/**
 * File system utilities for real-time file watching and browsing
 *
 * Uses @parcel/watcher for efficient, scalable file watching.
 * This is the same library used by VS Code, Parcel, Nx, and Nuxt.
 *
 * Benefits over chokidar:
 * - Native C++ implementation with throttling/coalescing in C++
 * - Automatic Watchman integration for large repos
 * - Uses FSEvents on macOS, inotify on Linux efficiently
 * - Handles tens of thousands of files without exhausting inotify limits
 */
export interface FileItem {
    name: string;
    path: string;
    type: "file" | "dir";
    size?: number;
    mtime?: number;
}
export interface FileContent {
    path: string;
    content: string;
    size: number;
    truncated: boolean;
    binary: boolean;
    mimeType?: string;
}
/**
 * File change event from @parcel/watcher
 * Event types:
 * - "create": file or directory was created
 * - "update": file was modified
 * - "delete": file or directory was deleted
 */
export interface FileChange {
    event: "create" | "update" | "delete";
    path: string;
}
/**
 * Validate and resolve a path, preventing path traversal attacks
 * Returns null if the path is outside the root directory
 */
export declare function safePath(root: string, userPath: string): string | null;
/**
 * List contents of a directory (lazy loading - one level only)
 */
export declare function listDir(root: string, dirPath: string): FileItem[] | null;
/**
 * Read file content with size limits and type detection
 */
export declare function readFile(root: string, filePath: string): FileContent | null;
export type FileChangeHandler = (changes: FileChange[]) => void;
/**
 * Start watching a directory for file changes using @parcel/watcher.
 *
 * This uses native OS APIs for efficient watching:
 * - macOS: FSEvents (kernel-level, very efficient)
 * - Linux: inotify (with smart batching to avoid exhausting limits)
 * - Windows: ReadDirectoryChangesW
 * - Watchman: automatically used if installed (best for huge repos)
 *
 * Events are throttled and coalesced in C++ for performance during
 * large filesystem changes (e.g., git checkout, npm install).
 *
 * Uses reference counting - multiple clients can subscribe to the same root.
 * Returns an unsubscribe function to remove this specific handler.
 */
export declare function startWatcher(root: string, handler: FileChangeHandler): Promise<() => void>;
/**
 * Stop watching a directory (removes all handlers)
 */
export declare function stopWatcher(root: string): Promise<void>;
/**
 * Stop all watchers
 */
export declare function stopAllWatchers(): Promise<void>;
//# sourceMappingURL=files.d.ts.map