File System Operations

/**
 * Create a temporary directory
 * @param prefix - Directory name prefix (default: zx-{randomId})
 * @param mode - Directory permissions
 * @returns Absolute path to created directory
 */
function tempdir(prefix?: string, mode?: Mode): string;

/**
 * Create a temporary file
 * @param name - File name (optional, uses random if not provided)
 * @param data - Initial file content
 * @param mode - File permissions
 * @returns Absolute path to created file
 */
function tempfile(
  name?: string,
  data?: string | Buffer,
  mode?: Mode
): string;

// Aliases
declare const tmpdir: typeof tempdir;
declare const tmpfile: typeof tempfile;

import { tempdir, tempfile, $ } from "zx";

// Create temporary directory
const tmpDir = tempdir('my-script-');
console.log(tmpDir); // /tmp/my-script-abc123

// Create temporary file with content
const configFile = tempfile('config.json', JSON.stringify({
  environment: 'test',
  debug: true
}));

// Use in commands
await $`cat ${configFile}`;

// Create temporary file without content
const emptyFile = tempfile();
await $`echo "data" > ${emptyFile}`;

// Temporary directory with specific permissions
const secureDir = tempdir('secure-', 0o700);

/**
 * Change current working directory
 * @param dir - Directory path or ProcessOutput containing path
 */
function cd(dir: string | ProcessOutput): void;

/**
 * Control directory synchronization behavior
 * @param flag - Whether to sync process.cwd() with internal state
 */
function syncProcessCwd(flag?: boolean): void;

import { $, cd } from "zx";

// Change to specific directory
cd('/tmp');
await $`pwd`; // Shows /tmp

// Use ProcessOutput
const homeDir = await $`echo $HOME`;
cd(homeDir);

// Get current directory
const currentDir = await $`pwd`;
console.log('Working in:', currentDir.stdout.trim());

// Temporary directory change
const originalDir = process.cwd();
cd('/var/log');
await $`ls *.log`;
cd(originalDir);

/**
 * Node.js path module with cross-platform path utilities
 */
export { default as path } from "node:path";

import { path, $ } from "zx";

// Path manipulation
const fullPath = path.join('/tmp', 'my-script', 'data.txt');
const fileName = path.basename(fullPath); // 'data.txt'
const dirName = path.dirname(fullPath);   // '/tmp/my-script'
const extension = path.extname(fullPath); // '.txt'

// Cross-platform paths
const scriptPath = path.resolve('./scripts/deploy.js');
await $`node ${scriptPath}`;

// Path parsing
const parsed = path.parse('/home/user/documents/file.txt');
// {
//   root: '/',
//   dir: '/home/user/documents',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }

/**
 * Node.js os module with operating system utilities
 */
export * as os from "node:os";

import { os, $ } from "zx";

// System information
console.log('Platform:', os.platform());     // 'linux', 'darwin', 'win32'
console.log('Architecture:', os.arch());     // 'x64', 'arm64'
console.log('CPU cores:', os.cpus().length);
console.log('Total memory:', os.totalmem());
console.log('Free memory:', os.freemem());

// Temporary directory
const tmpDir = os.tmpdir();
console.log('System temp dir:', tmpDir);

// User information
console.log('Home directory:', os.homedir());
console.log('Username:', os.userInfo().username);

// Network interfaces
const interfaces = os.networkInterfaces();
console.log('Network interfaces:', Object.keys(interfaces));

// Platform-specific operations
if (os.platform() === 'win32') {
  await $`dir`;
} else {
  await $`ls -la`;
}

/**
 * Enhanced file system operations (fs-extra)
 * Includes all Node.js fs methods plus additional utilities
 */
export { fs } from "./vendor";

interface FileSystem {
  // Standard fs methods
  readFile(path: string, encoding?: BufferEncoding): Promise<string | Buffer>;
  writeFile(path: string, data: string | Buffer): Promise<void>;
  readdir(path: string): Promise<string[]>;
  stat(path: string): Promise<Stats>;
  
  // Additional fs-extra methods
  ensureDir(path: string): Promise<void>;
  ensureFile(path: string): Promise<void>;
  copy(src: string, dest: string): Promise<void>;
  move(src: string, dest: string): Promise<void>;
  remove(path: string): Promise<void>;
  pathExists(path: string): Promise<boolean>;
  readJson(path: string): Promise<any>;
  writeJson(path: string, object: any): Promise<void>;
  emptyDir(path: string): Promise<void>;
}

import { fs, $ } from "zx";

// Ensure directory exists
await fs.ensureDir('./build/assets');

// Copy files
await fs.copy('./src', './dist');

// Check if path exists
if (await fs.pathExists('./config.json')) {
  const config = await fs.readJson('./config.json');
  console.log('Config:', config);
}

// Write JSON file
await fs.writeJson('./output.json', {
  timestamp: new Date().toISOString(),
  results: ['success', 'completed']
});

// Clean directory
await fs.emptyDir('./temp');

// Move files
await fs.move('./old-location/file.txt', './new-location/file.txt');

// Remove files/directories
await fs.remove('./temporary-files');

import { $, fs, tempfile, path } from "zx";

// Save command output to file
const logOutput = await $`dmesg`;
const logFile = tempfile('system.log', logOutput.stdout);

// Process file listing
const fileList = await $`find . -name "*.js"`;
const files = fileList.lines();

for (const file of files) {
  const stats = await fs.stat(file);
  console.log(`${file}: ${stats.size} bytes`);
}

// Backup files
const timestamp = new Date().toISOString().replace(/:/g, '-');
const backupDir = `./backup-${timestamp}`;
await fs.ensureDir(backupDir);

for (const file of files) {
  const destPath = path.join(backupDir, path.basename(file));
  await fs.copy(file, destPath);
}

/**
 * File mode permissions (octal number or string)
 */
type Mode = number | string;

/**
 * File system stats object
 */
interface Stats {
  isFile(): boolean;
  isDirectory(): boolean;
  isSymbolicLink(): boolean;
  size: number;
  mtime: Date;
  ctime: Date;
  atime: Date;
  mode: number;
  uid: number;
  gid: number;
}