/**
 * File system utilities for common async operations.
 *
 * Provides Promise-based wrappers for file system operations.
 *
 * **Note:** These functions are Node.js only and will throw an error
 * if called in a browser environment.
 */
/**
 * Lazily resolve `child_process.spawn` for callers that need to spawn a
 * detached worker (CLI task runners, dev-server supervisors, etc.). Throws
 * via `assertNode` on non-Node runtimes.
 *
 * **Node.js only.** Exposed because consumers (e.g. `CliTaskRunner` in the
 * SDK) need a single place to reach `spawn` without a top-level
 * `import 'node:child_process'` that V8 isolates would choke on.
 */
export declare function getSpawnFn(): typeof import('child_process').spawn;
/**
 * Read a file's contents as a string.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to file
 * @param encoding - Encoding (default 'utf8')
 * @returns File contents as string
 *
 * @example
 * const content = await readFile('/path/to/file.txt');
 */
export declare function readFile(p: string, encoding?: BufferEncoding): Promise<string>;
/**
 * Read a file's contents as a string synchronously.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * Use this only when async operations are not possible (e.g., module initialization).
 * Prefer the async `readFile` function in most cases.
 *
 * @param p - Path to file
 * @param encoding - Encoding (default 'utf8')
 * @returns File contents as string
 *
 * @example
 * const content = readFileSync('/path/to/file.txt');
 */
export declare function readFileSync(p: string, encoding?: BufferEncoding): string;
/**
 * Read a file's contents as a Buffer.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to file
 * @returns File contents as Buffer
 *
 * @example
 * const buffer = await readFileBuffer('/path/to/file.bin');
 */
export declare function readFileBuffer(p: string): Promise<Buffer>;
/**
 * Write content to a file.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to write to
 * @param content - Content to write
 * @param options - Optional mode (permissions)
 *
 * @example
 * await writeFile('/path/to/file.txt', 'hello', { mode: 0o600 });
 */
export declare function writeFile(p: string, content: string, options?: {
    mode?: number;
}): Promise<void>;
/**
 * Create a directory with optional mode (permissions).
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to directory
 * @param options - Optional recursive and mode settings
 *
 * @example
 * await mkdir('/path/to/dir', { recursive: true, mode: 0o700 });
 */
export declare function mkdir(p: string, options?: {
    recursive?: boolean;
    mode?: number;
}): Promise<void>;
/**
 * Ensure a directory exists, creating it recursively if needed (synchronous).
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * Use this only when async operations are not possible (e.g., a synchronous
 * constructor that must open a file path before the first I/O). Prefer the
 * async `ensureDir` in most cases.
 *
 * @param p - Path to directory
 *
 * @example
 * ensureDirSync('/path/to/new/directory');
 */
export declare function ensureDirSync(p: string): void;
/**
 * Rename/move a file or directory.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param oldPath - Current path
 * @param newPath - New path
 *
 * @example
 * await rename('/path/to/old.txt', '/path/to/new.txt');
 */
export declare function rename(oldPath: string, newPath: string): Promise<void>;
/**
 * Delete a file.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to file to delete
 *
 * @example
 * await unlink('/path/to/file.txt');
 */
export declare function unlink(p: string): Promise<void>;
/**
 * Check if a file exists asynchronously.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to check
 * @returns true if file exists, false otherwise
 *
 * @example
 * await fileExists('/path/to/file.txt') // true or false
 */
export declare function fileExists(p: string): Promise<boolean>;
/**
 * Read and parse a JSON file.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param jsonPath - Path to JSON file
 * @returns Parsed JSON content, or null if file doesn't exist or is invalid
 *
 * @example
 * const config = await readJSON<Config>('/path/to/config.json');
 */
export declare function readJSON<T = unknown>(jsonPath: string): Promise<T | null>;
/**
 * Write an object to a JSON file with pretty formatting.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to write to
 * @param obj - Object to serialize
 *
 * @example
 * await writeJSON('/path/to/output.json', { key: 'value' });
 */
export declare function writeJSON(p: string, obj: unknown): Promise<void>;
/**
 * Ensure a directory exists, creating it recursively if needed.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to directory
 *
 * @example
 * await ensureDir('/path/to/new/directory');
 */
export declare function ensureDir(p: string): Promise<void>;
/**
 * Get file/directory stats.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to file or directory
 * @returns Stats object with isDirectory(), isFile(), etc.
 *
 * @example
 * const stats = await stat('/path/to/file');
 * if (stats.isDirectory()) { ... }
 */
export declare function stat(p: string): Promise<import('fs').Stats>;
/**
 * Create a symbolic link at `linkPath` pointing to `target`.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param target - Path the symlink should point to
 * @param linkPath - Where to create the symlink
 *
 * @example
 * await symlink('/etc/hosts', '/tmp/hosts-link');
 */
export declare function symlink(target: string, linkPath: string): Promise<void>;
/**
 * Resolve a path, following symbolic links to their final target.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * Unlike `pathResolve`, this returns the canonical path with symlinks
 * resolved, which is what callers need when validating that a path stays
 * inside a trusted root (`startsWith` checks on `pathResolve` are
 * symlink-bypassable).
 *
 * @param p - Path to resolve
 * @returns Canonical absolute path with symlinks resolved
 *
 * @example
 * const real = await realpath('/var/log/app.log');
 */
export declare function realpath(p: string): Promise<string>;
/**
 * Copy a file.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param src - Source path
 * @param dest - Destination path
 *
 * @example
 * await copyFile('/path/to/src', '/path/to/dest');
 */
export declare function copyFile(src: string, dest: string): Promise<void>;
/**
 * Copy a file or directory recursively.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param src - Source path
 * @param dest - Destination path
 * @param options - Copy options
 *
 * @example
 * await cp('/path/to/src', '/path/to/dest', { recursive: true });
 */
export declare function cp(src: string, dest: string, options?: {
    recursive?: boolean;
}): Promise<void>;
/**
 * List directory contents.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to directory
 * @returns Array of file/directory names
 *
 * @example
 * const files = await readdir('/path/to/dir');
 */
export declare function readdir(p: string): Promise<string[]>;
/**
 * List directory contents synchronously.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * Use this only when async operations are not possible (e.g., per-scrape
 * synchronous metrics collectors). Prefer the async `readdir` in most cases.
 *
 * @param p - Path to directory
 * @returns Array of file/directory names
 *
 * @example
 * const files = readdirSync('/proc/self/fd');
 */
export declare function readdirSync(p: string): string[];
/**
 * Remove a file or directory recursively.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to remove
 * @param options - Optional recursive flag
 *
 * @example
 * await rm('/path/to/dir', { recursive: true });
 */
export declare function rm(p: string, options?: {
    recursive?: boolean;
    force?: boolean;
}): Promise<void>;
/**
 * Check if a directory is empty.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param dir - Path to directory
 * @returns true if directory is empty or doesn't exist
 *
 * @example
 * await isDirEmpty('/path/to/directory') // true or false
 */
export declare function isDirEmpty(dir: string): Promise<boolean>;
/**
 * Create a temporary directory with a unique name.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param prefix - Directory prefix
 * @returns Path to the created directory
 *
 * @example
 * const tmpDir = await mkdtemp('/tmp/myapp-');
 */
export declare function mkdtemp(prefix: string): Promise<string>;
/**
 * Check if a file or directory is accessible.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param p - Path to check
 * @param mode - Access mode (default F_OK for existence check)
 * @throws Error if path is not accessible
 *
 * @example
 * await access('/path/to/file'); // throws if not accessible
 */
export declare function access(p: string, mode?: number): Promise<void>;
/**
 * Run a command as a child process.
 *
 * **Node.js only** - throws an error if called in browser.
 *
 * @param cmd - Command to run
 * @param args - Command arguments
 * @param opts - Options including cwd
 * @returns Promise that resolves when command completes successfully
 * @throws Error if command exits with non-zero code
 *
 * @example
 * await runCmd('npm', ['install'], { cwd: '/project' });
 */
export declare function runCmd(cmd: string, args: string[], opts?: {
    cwd?: string;
    env?: NodeJS.ProcessEnv;
}): Promise<void>;
/**
 * Handle returned by {@link watchFile}. `close()` stops the watch and is safe
 * to call multiple times. `onError` registers an error handler — useful for
 * platforms (Linux watch-count limits, network filesystems) that surface
 * mid-stream failures.
 */
export interface FileWatcherHandle {
    close(): void;
    onError(handler: (err: Error) => void): void;
}
/** Options for {@link watchFile}. Mirrors a subset of Node `fs.watch`. */
export interface WatchFileOptions {
    /** Watch a directory recursively. Node-specific; default false. */
    recursive?: boolean;
}
/** Callback fired on each filesystem change event. */
export type WatchFileListener = (eventType: 'rename' | 'change', filename: string | null) => void;
/**
 * Watch a file or directory for changes. Returns a handle the caller closes
 * to stop watching.
 *
 * Accepts either a no-arg listener (the simple case) or one that receives
 * the Node-shaped `(eventType, filename)` pair — both are tolerated so
 * shallow callers stay terse while filesystem-walking callers get the full
 * signal.
 *
 * **Node.js only** — calls `assertNode` at invocation time. Build-time env
 * selection (`frontmcp build --target <env>`) keeps this off non-Node
 * targets; runtime callers in V8 isolates will hit the assertion.
 */
export declare function watchFile(p: string, onChange: WatchFileListener | (() => void), options?: WatchFileOptions): FileWatcherHandle;