@volter/tabnode 0.2.14-volter.88

package/src/virtual-fs.ts

@@ -0,0 +1,1048 @@
+/**
+ * Virtual File System - In-memory file tree with POSIX-like operations
+ */
+
+import type { VFSSnapshot, VFSFileEntry } from './runtime-interface';
+import { uint8ToBase64, base64ToUint8 } from './utils/binary-encoding';
+import { Readable } from './node-lib/stream-module';
+
+/**
+ * A read stream is a real `Readable`, so a guest can pipe it, iterate it, or
+ * listen for `open` and `ready`; the hand-rolled object it used to answer had
+ * only `on` and `pipe`, so anything that treated it as a stream got nothing.
+ * `start`, `end` and `encoding` are honoured as Node honours them.
+ *
+ * What `createReadStream` accepts: the subset of Node's options bag used here.
+ */
+export interface ReadStreamOptions {
+  encoding?: string;
+  start?: number;
+  end?: number;
+}
+
+/** A `Readable` carrying the two properties Node's fs read stream carries. */
+export interface FsReadStream extends Readable {
+  path: string;
+  bytesRead: number;
+}
+
+
+
+export interface FSNode {
+  type: 'file' | 'directory' | 'symlink';
+  content?: Uint8Array;
+  /** Where a symlink points, exactly as it was written. */
+  target?: string;
+  children?: Map<string, FSNode>;
+  mtime: number;
+  /**
+   * When the file was last read. Node reports it apart from the write time
+   * and `utimes` sets the two separately; this filesystem reported the write
+   * time in its place, so a program that set an access time and read it back
+   * got the other one (Node's own test/wasi `stat` fixture asserts them
+   * apart). Absent until something sets it, which is the write time.
+   */
+  atime?: number;
+}
+
+// Simple EventEmitter for VFS change notifications
+type VFSChangeListener = (path: string, content: string) => void;
+type VFSDeleteListener = (path: string) => void;
+type VFSEventListener = VFSChangeListener | VFSDeleteListener;
+
+export interface Stats {
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+  isBlockDevice(): boolean;
+  isCharacterDevice(): boolean;
+  isFIFO(): boolean;
+  isSocket(): boolean;
+  size: number;
+  mode: number;
+  mtime: Date;
+  atime: Date;
+  ctime: Date;
+  birthtime: Date;
+  mtimeMs: number;
+  atimeMs: number;
+  ctimeMs: number;
+  birthtimeMs: number;
+  nlink: number;
+  uid: number;
+  gid: number;
+  dev: number;
+  ino: number;
+  rdev: number;
+  blksize: number;
+  blocks: number;
+}
+
+export type WatchEventType = 'change' | 'rename';
+export type WatchListener = (eventType: WatchEventType, filename: string | null) => void;
+
+export interface FSWatcher {
+  close(): void;
+  ref(): this;
+  unref(): this;
+}
+
+interface WatcherEntry {
+  listener: WatchListener;
+  recursive: boolean;
+  closed: boolean;
+}
+
+/**
+ * Create a Node.js-style error with code property
+ */
+export interface NodeError extends Error {
+  code: string;
+  errno: number;
+  syscall: string;
+  path?: string;
+}
+
+export function createNodeError(
+  code: 'ENOENT' | 'ENOTDIR' | 'EISDIR' | 'EEXIST' | 'ENOTEMPTY' | 'ELOOP' | 'EINVAL',
+  syscall: string,
+  path: string,
+  message?: string
+): NodeError {
+  const errno: Record<string, number> = {
+    ENOENT: -2,
+    ENOTDIR: -20,
+    EISDIR: -21,
+    EEXIST: -17,
+    ENOTEMPTY: -39,
+  };
+
+  const messages: Record<string, string> = {
+    ENOENT: 'no such file or directory',
+    ENOTDIR: 'not a directory',
+    EISDIR: 'is a directory',
+    EEXIST: 'file already exists',
+    ENOTEMPTY: 'directory not empty',
+  };
+
+  const err = new Error(
+    message || `${code}: ${messages[code]}, ${syscall} '${path}'`
+  ) as NodeError;
+  err.code = code;
+  err.errno = errno[code];
+  err.syscall = syscall;
+  err.path = path;
+  return err;
+}
+
+export class VirtualFS {
+  private root: FSNode;
+  private encoder = new TextEncoder();
+  private decoder = new TextDecoder();
+  private watchers = new Map<string, Set<WatcherEntry>>();
+  private eventListeners = new Map<string, Set<VFSEventListener>>();
+
+  constructor() {
+    this.root = {
+      type: 'directory',
+      children: new Map(),
+      mtime: Date.now(),
+    };
+  }
+
+  /**
+   * Add event listener (for change notifications to workers)
+   */
+  on(event: 'change', listener: VFSChangeListener): this;
+  on(event: 'delete', listener: VFSDeleteListener): this;
+  on(event: string, listener: VFSEventListener): this {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    this.eventListeners.get(event)!.add(listener);
+    return this;
+  }
+
+  /**
+   * Remove event listener
+   */
+  off(event: 'change', listener: VFSChangeListener): this;
+  off(event: 'delete', listener: VFSDeleteListener): this;
+  off(event: string, listener: VFSEventListener): this {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+    return this;
+  }
+
+  /**
+   * Emit event to listeners
+   */
+  private emit(event: 'change', path: string, content: string): void;
+  private emit(event: 'delete', path: string): void;
+  private emit(event: string, ...args: unknown[]): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          (listener as (...args: unknown[]) => void)(...args);
+        } catch (err) {
+          console.error('Error in VFS event listener:', err);
+        }
+      }
+    }
+  }
+
+  /**
+   * Serialize the entire file tree to a snapshot (for worker transfer)
+   */
+  toSnapshot(): VFSSnapshot {
+    const files: VFSFileEntry[] = [];
+    this.serializeNode('/', this.root, files);
+    return { files };
+  }
+
+  private serializeNode(path: string, node: FSNode, files: VFSFileEntry[]): void {
+    if (node.type === 'file') {
+      // Encode binary content as base64
+      let content = '';
+      if (node.content && node.content.length > 0) {
+        content = uint8ToBase64(node.content);
+      }
+      files.push({ path, type: 'file', content });
+    } else if (node.type === 'symlink') {
+      files.push({ path, type: 'symlink', target: node.target } as unknown as VFSFileEntry);
+    } else if (node.type === 'directory') {
+      files.push({ path, type: 'directory' });
+      if (node.children) {
+        for (const [name, child] of node.children) {
+          const childPath = path === '/' ? `/${name}` : `${path}/${name}`;
+          this.serializeNode(childPath, child, files);
+        }
+      }
+    }
+  }
+
+  /**
+   * Create a VirtualFS from a snapshot
+   */
+  static fromSnapshot(snapshot: VFSSnapshot): VirtualFS {
+    const vfs = new VirtualFS();
+
+    // Sort entries to ensure directories are created before their contents
+    const sortedFiles = snapshot.files
+      .map((entry, i) => ({ entry, depth: entry.path.split('/').length, i }))
+      .sort((a, b) => a.depth - b.depth || a.i - b.i)
+      .map(x => x.entry);
+
+    for (const entry of sortedFiles) {
+      if (entry.path === '/') continue; // Skip root
+
+      if (entry.type === 'directory') {
+        vfs.mkdirSync(entry.path, { recursive: true });
+      } else if ((entry as { type: string }).type === 'symlink') {
+        const parentPath = entry.path.substring(0, entry.path.lastIndexOf('/')) || '/';
+        if (parentPath !== '/' && !vfs.existsSync(parentPath)) {
+          vfs.mkdirSync(parentPath, { recursive: true });
+        }
+        vfs.symlinkSync((entry as unknown as { target: string }).target, entry.path);
+      } else if (entry.type === 'file') {
+        // Decode base64 content
+        let content: Uint8Array;
+        if (entry.content) {
+          content = base64ToUint8(entry.content);
+        } else {
+          content = new Uint8Array(0);
+        }
+        // Ensure parent directory exists
+        const parentPath = entry.path.substring(0, entry.path.lastIndexOf('/')) || '/';
+        if (parentPath !== '/' && !vfs.existsSync(parentPath)) {
+          vfs.mkdirSync(parentPath, { recursive: true });
+        }
+        vfs.writeFileSyncInternal(entry.path, content, false); // Don't emit events during restore
+      }
+    }
+
+    return vfs;
+  }
+
+  /**
+   * Internal write that optionally emits events
+   */
+  private writeFileSyncInternal(path: string, data: string | Uint8Array, emitEvent: boolean): void {
+    const normalized = this.normalizePath(path);
+    const parentPath = this.getParentPath(normalized);
+    const basename = this.getBasename(normalized);
+
+    if (!basename) {
+      throw new Error(`EISDIR: illegal operation on a directory, '${path}'`);
+    }
+
+    const parent = this.ensureDirectory(parentPath);
+    const existing = parent.children!.get(basename);
+    const existed = existing !== void 0;
+
+    const content = typeof data === 'string' ? this.encoder.encode(data) : data;
+
+    // A write changes a file's bytes; it does not make a new file. Replacing
+    // the node on every write moved the file's identity, and an inode or an
+    // open descriptor that held it was left pointing at a file nobody had.
+    if (existed && existing!.type === 'file') {
+      existing!.content = content;
+      existing!.mtime = Date.now();
+    } else {
+      parent.children!.set(basename, {
+        type: 'file',
+        content,
+        mtime: Date.now(),
+      });
+    }
+
+    if (emitEvent) {
+      // Notify watchers
+      this.notifyWatchers(normalized, existed ? 'change' : 'rename');
+      // Emit change event for worker sync
+      this.emit('change', normalized, typeof data === 'string' ? data : this.decoder.decode(data));
+    }
+  }
+
+  /**
+   * Normalize path - resolve . and .. segments, ensure leading /
+   */
+  private normalizePath(path: string): string {
+    if (!path.startsWith('/')) {
+      path = '/' + path;
+    }
+
+    const parts = path.split('/').filter(Boolean);
+    const resolved: string[] = [];
+
+    for (const part of parts) {
+      if (part === '..') {
+        resolved.pop();
+      } else if (part !== '.') {
+        resolved.push(part);
+      }
+    }
+
+    return '/' + resolved.join('/');
+  }
+
+  /**
+   * Get path segments from normalized path
+   */
+  private getPathSegments(path: string): string[] {
+    return this.normalizePath(path).split('/').filter(Boolean);
+  }
+
+  /**
+   * Get parent directory path
+   */
+  private getParentPath(path: string): string {
+    const normalized = this.normalizePath(path);
+    const lastSlash = normalized.lastIndexOf('/');
+    return lastSlash <= 0 ? '/' : normalized.slice(0, lastSlash);
+  }
+
+  /**
+   * Get basename from path
+   */
+  private getBasename(path: string): string {
+    const normalized = this.normalizePath(path);
+    const lastSlash = normalized.lastIndexOf('/');
+    return normalized.slice(lastSlash + 1);
+  }
+
+  /**
+   * Get node at path, returns undefined if not found
+   */
+  getNode(path: string): FSNode | undefined {
+    return this.__substrateNode(path, true, 0);
+  }
+  /** The node at a path, following every link on the way and, when `follow`, the last one too. */
+  __substrateNode(path: string, follow: boolean, depth: number): FSNode | undefined {
+    if (depth > 40) throw createNodeError('ELOOP', 'stat', path);
+    const segments = this.getPathSegments(path);
+    let current = this.root;
+    for (let index = 0; index < segments.length; index += 1) {
+      if (current.type !== 'directory' || !current.children) {
+        return undefined;
+      }
+      const child = current.children.get(segments[index]);
+      if (!child) {
+        return undefined;
+      }
+      if (child.type === 'symlink' && (follow || index < segments.length - 1)) {
+        const linkPath = '/' + segments.slice(0, index + 1).join('/');
+        const rest = segments.slice(index + 1).join('/');
+        const target = this.__substrateLinkTarget(linkPath, child.target!);
+        return this.__substrateNode(rest ? target + '/' + rest : target, follow, depth + 1);
+      }
+      current = child;
+    }
+    return current;
+  }
+  /** A link's target as an absolute path: absolute as written, or relative to the link's directory. */
+  __substrateLinkTarget(linkPath: string, target: string): string {
+    return this.normalizePath(target.startsWith('/') ? target : this.getParentPath(linkPath) + '/' + target);
+  }
+  symlinkSync(target: string, path: string): void {
+    const normalized = this.normalizePath(path);
+    const parentPath = this.getParentPath(normalized);
+    const basename = this.getBasename(normalized);
+    const parent = this.getNode(parentPath);
+    if (!parent || parent.type !== 'directory') {
+      throw createNodeError('ENOENT', 'symlink', path);
+    }
+    if (parent.children!.has(basename)) {
+      throw createNodeError('EEXIST', 'symlink', path);
+    }
+    parent.children!.set(basename, { type: 'symlink', target: String(target), mtime: Date.now() });
+    this.notifyWatchers(normalized, 'rename');
+  }
+  readlinkSync(path: string): string {
+    const node = this.__substrateNode(path, false, 0);
+    if (!node) {
+      throw createNodeError('ENOENT', 'readlink', path);
+    }
+    if (node.type !== 'symlink') {
+      throw createNodeError('EINVAL', 'readlink', path);
+    }
+    return node.target!;
+  }
+
+  /**
+   * Get or create directory at path (for mkdir -p behavior)
+   */
+  private ensureDirectory(path: string): FSNode {
+    const segments = this.getPathSegments(path);
+    let current = this.root;
+
+    for (let index = 0; index < segments.length; index += 1) {
+      const segment = segments[index];
+      if (!current.children) {
+        current.children = new Map();
+      }
+
+      let child = current.children.get(segment);
+      if (!child) {
+        child = { type: 'directory', children: new Map(), mtime: Date.now() };
+        current.children.set(segment, child);
+        // A directory that appears is a `rename` in its parent, as Node
+        // reports one, and it is the only event a watcher of a tree has to
+        // start watching the new directory from.
+        this.notifyWatchers('/' + segments.slice(0, index + 1).join('/'), 'rename');
+      } else if (child.type === 'symlink') {
+        // A directory reached through a link is the link's target.
+        const linkPath = '/' + segments.slice(0, index + 1).join('/');
+        const rest = segments.slice(index + 1).join('/');
+        const target = this.__substrateLinkTarget(linkPath, child.target!);
+        return this.ensureDirectory(rest ? target + '/' + rest : target);
+      } else if (child.type !== 'directory') {
+        throw new Error(`ENOTDIR: not a directory, '${path}'`);
+      }
+
+      current = child;
+    }
+
+    return current;
+  }
+
+  /**
+   * Check if path exists
+   */
+  existsSync(path: string): boolean {
+    return this.getNode(path) !== undefined;
+  }
+
+  /**
+   * Get stats for path
+   */
+  statSync(path: string): Stats {
+    const node = this.getNode(path);
+    if (!node) {
+      throw createNodeError('ENOENT', 'stat', path);
+    }
+
+    const size = node.type === 'file' ? (node.content?.length || 0) : 0;
+    const mtime = node.mtime;
+    const atime = node.atime ?? mtime;
+
+    return {
+      isFile: () => node.type === 'file',
+      isDirectory: () => node.type === 'directory',
+      isSymbolicLink: () => false,
+      isBlockDevice: () => false,
+      isCharacterDevice: () => false,
+      isFIFO: () => false,
+      isSocket: () => false,
+      size,
+      mode: node.type === 'directory' ? 0o755 : 0o644,
+      mtime: new Date(mtime),
+      atime: new Date(atime),
+      ctime: new Date(mtime),
+      birthtime: new Date(mtime),
+      mtimeMs: mtime,
+      atimeMs: atime,
+      ctimeMs: mtime,
+      birthtimeMs: mtime,
+      nlink: 1,
+      uid: 1000,
+      gid: 1000,
+      dev: 0,
+      ino: 0,
+      rdev: 0,
+      blksize: 4096,
+      blocks: Math.ceil(size / 512),
+    };
+  }
+
+  /**
+   * lstatSync - same as statSync for our virtual FS (no symlinks)
+   */
+  lstatSync(path: string): Stats {
+    const node = this.__substrateNode(path, false, 0);
+    if (!node) {
+      throw createNodeError('ENOENT', 'lstat', path);
+    }
+    if (node.type !== 'symlink') return this.statSync(path);
+    const mtime = node.mtime;
+    const atime = node.atime ?? mtime;
+    return {
+      isFile: () => false,
+      isDirectory: () => false,
+      isSymbolicLink: () => true,
+      isBlockDevice: () => false,
+      isCharacterDevice: () => false,
+      isFIFO: () => false,
+      isSocket: () => false,
+      size: node.target!.length,
+      mode: 41471,
+      mtime: new Date(mtime),
+      atime: new Date(atime),
+      ctime: new Date(mtime),
+      birthtime: new Date(mtime),
+      mtimeMs: mtime,
+      atimeMs: atime,
+      ctimeMs: mtime,
+      birthtimeMs: mtime,
+      nlink: 1,
+      uid: 1000,
+      gid: 1000,
+      dev: 0,
+      ino: 0,
+      rdev: 0,
+      blksize: 4096,
+      blocks: 0
+    } as unknown as Stats;
+  }
+
+  /**
+   * Read file contents as Uint8Array
+   */
+  readFileSync(path: string): Uint8Array;
+  readFileSync(path: string, encoding: 'utf8' | 'utf-8'): string;
+  readFileSync(path: string, encoding?: 'utf8' | 'utf-8'): Uint8Array | string {
+    const node = this.getNode(path);
+
+    if (!node) {
+      throw createNodeError('ENOENT', 'open', path);
+    }
+
+    if (node.type !== 'file') {
+      throw createNodeError('EISDIR', 'read', path);
+    }
+
+    const content = node.content || new Uint8Array(0);
+
+    if (encoding === 'utf8' || encoding === 'utf-8') {
+      return this.decoder.decode(content);
+    }
+
+    return content;
+  }
+
+  /**
+   * Write data to file, creating parent directories as needed
+   */
+  writeFileSync(path: string, data: string | Uint8Array): void {
+    this.writeFileSyncInternal(path, data, true);
+  }
+
+  /**
+   * Create directory, optionally with recursive parent creation
+   */
+  mkdirSync(path: string, options?: { recursive?: boolean }): void {
+    const normalized = this.normalizePath(path);
+
+    if (options?.recursive) {
+      this.ensureDirectory(normalized);
+      return;
+    }
+
+    const parentPath = this.getParentPath(normalized);
+    const basename = this.getBasename(normalized);
+
+    if (!basename) {
+      return; // Root directory already exists
+    }
+
+    const parent = this.getNode(parentPath);
+
+    if (!parent) {
+      throw createNodeError('ENOENT', 'mkdir', parentPath);
+    }
+
+    if (parent.type !== 'directory') {
+      throw createNodeError('ENOTDIR', 'mkdir', parentPath);
+    }
+
+    if (parent.children!.has(basename)) {
+      throw createNodeError('EEXIST', 'mkdir', path);
+    }
+
+    parent.children!.set(basename, {
+      type: 'directory',
+      children: new Map(),
+      mtime: Date.now(),
+    });
+    this.notifyWatchers(normalized, 'rename');
+  }
+
+  /**
+   * Read directory contents
+   */
+  readdirSync(path: string): string[] {
+    const node = this.getNode(path);
+
+    if (!node) {
+      throw createNodeError('ENOENT', 'scandir', path);
+    }
+
+    if (node.type !== 'directory') {
+      throw createNodeError('ENOTDIR', 'scandir', path);
+    }
+
+    return Array.from(node.children!.keys());
+  }
+
+  /**
+   * Remove file
+   */
+  unlinkSync(path: string): void {
+    const normalized = this.normalizePath(path);
+    const parentPath = this.getParentPath(normalized);
+    const basename = this.getBasename(normalized);
+
+    const parent = this.getNode(parentPath);
+
+    if (!parent || parent.type !== 'directory') {
+      throw createNodeError('ENOENT', 'unlink', path);
+    }
+
+    const node = parent.children!.get(basename);
+
+    if (!node) {
+      throw createNodeError('ENOENT', 'unlink', path);
+    }
+
+    if (node.type !== 'file' && node.type !== 'symlink') {
+      throw createNodeError('EISDIR', 'unlink', path);
+    }
+
+    parent.children!.delete(basename);
+
+    // Notify watchers
+    this.notifyWatchers(normalized, 'rename');
+    // Emit delete event for worker sync
+    this.emit('delete', normalized);
+  }
+
+  /**
+   * Remove directory (must be empty)
+   */
+  rmdirSync(path: string): void {
+    const normalized = this.normalizePath(path);
+    const parentPath = this.getParentPath(normalized);
+    const basename = this.getBasename(normalized);
+
+    if (!basename) {
+      throw new Error(`EPERM: operation not permitted, '${path}'`);
+    }
+
+    const parent = this.getNode(parentPath);
+
+    if (!parent || parent.type !== 'directory') {
+      throw createNodeError('ENOENT', 'rmdir', path);
+    }
+
+    const node = parent.children!.get(basename);
+
+    if (!node) {
+      throw createNodeError('ENOENT', 'rmdir', path);
+    }
+
+    if (node.type !== 'directory') {
+      throw createNodeError('ENOTDIR', 'rmdir', path);
+    }
+
+    if (node.children!.size > 0) {
+      throw createNodeError('ENOTEMPTY', 'rmdir', path);
+    }
+
+    parent.children!.delete(basename);
+    // A directory that goes is a `rename` in its parent too, as its removal is.
+    this.notifyWatchers(normalized, 'rename');
+  }
+
+  /**
+   * Rename/move file or directory
+   */
+  renameSync(oldPath: string, newPath: string): void {
+    const normalizedOld = this.normalizePath(oldPath);
+    const normalizedNew = this.normalizePath(newPath);
+
+    const oldParentPath = this.getParentPath(normalizedOld);
+    const oldBasename = this.getBasename(normalizedOld);
+    const newParentPath = this.getParentPath(normalizedNew);
+    const newBasename = this.getBasename(normalizedNew);
+
+    const oldParent = this.getNode(oldParentPath);
+
+    if (!oldParent || oldParent.type !== 'directory') {
+      throw createNodeError('ENOENT', 'rename', oldPath);
+    }
+
+    const node = oldParent.children!.get(oldBasename);
+
+    if (!node) {
+      throw createNodeError('ENOENT', 'rename', oldPath);
+    }
+
+    const newParent = this.ensureDirectory(newParentPath);
+
+    oldParent.children!.delete(oldBasename);
+    newParent.children!.set(newBasename, node);
+
+    // Notify watchers
+    this.notifyWatchers(normalizedOld, 'rename');
+    this.notifyWatchers(normalizedNew, 'rename');
+  }
+
+  /**
+   * Read file with optional options parameter
+   */
+  readFile(
+    path: string,
+    optionsOrCallback?: string | { encoding?: string } | ((err: Error | null, data?: Uint8Array | string) => void),
+    callback?: (err: Error | null, data?: Uint8Array | string) => void
+  ): void | Promise<Uint8Array | string> {
+    const actualCallback = typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
+    const encoding = typeof optionsOrCallback === 'string' ? optionsOrCallback
+      : optionsOrCallback && typeof optionsOrCallback === 'object' ? optionsOrCallback.encoding : void 0;
+    const read = () => encoding ? this.readFileSync(path, encoding as 'utf8') : this.readFileSync(path);
+    if (!actualCallback) {
+      return new Promise((resolve, reject) => {
+        try { resolve(read()); } catch (err) { reject(err); }
+      });
+    }
+    try {
+      const data = read();
+      queueMicrotask(() => actualCallback(null, data));
+    } catch (err) {
+      queueMicrotask(() => actualCallback(err as Error));
+    }
+  }
+
+  /**
+   * Async stat
+   */
+  stat(path: string, callback: (err: Error | null, stats?: Stats) => void): void {
+    try {
+      const stats = this.statSync(path);
+      queueMicrotask(() => callback(null, stats));
+    } catch (err) {
+      queueMicrotask(() => callback(err as Error));
+    }
+  }
+
+  /**
+   * Async lstat
+   */
+  lstat(path: string, callback: (err: Error | null, stats?: Stats) => void): void {
+    try {
+      const stats = this.lstatSync(path);
+      queueMicrotask(() => callback(null, stats));
+    } catch (err) {
+      queueMicrotask(() => callback(err as Error));
+    }
+  }
+
+  /**
+   * Async readdir
+   */
+  readdir(
+    path: string,
+    optionsOrCallback?: { withFileTypes?: boolean } | ((err: Error | null, files?: string[]) => void),
+    callback?: (err: Error | null, files?: string[]) => void
+  ): void {
+    const actualCallback = typeof optionsOrCallback === 'function' ? optionsOrCallback : callback;
+
+    try {
+      const files = this.readdirSync(path);
+      if (actualCallback) {
+        queueMicrotask(() => actualCallback(null, files));
+      }
+    } catch (err) {
+      if (actualCallback) {
+        queueMicrotask(() => actualCallback(err as Error));
+      }
+    }
+  }
+
+  /**
+   * Async realpath
+   */
+  realpath(path: string, callback: (err: Error | null, resolvedPath?: string) => void): void {
+    try {
+      const resolved = this.realpathSync(path);
+      queueMicrotask(() => callback(null, resolved));
+    } catch (err) {
+      queueMicrotask(() => callback(err as Error));
+    }
+  }
+
+  /**
+   * Sync realpath - in our VFS, just normalize the path
+   */
+  realpathSync(path: string): string {
+    let resolved = this.normalizePath(path);
+    for (let hops = 0; hops <= 40; hops += 1) {
+      const segments = resolved.split('/').filter(Boolean);
+      let current: FSNode | undefined = this.root;
+      let linked = false;
+      for (let index = 0; index < segments.length; index += 1) {
+        const child: FSNode | undefined = current && current.children ? current.children.get(segments[index]) : void 0;
+        if (!child) throw createNodeError('ENOENT', 'realpath', path);
+        if (child.type === 'symlink') {
+          const linkPath = '/' + segments.slice(0, index + 1).join('/');
+          const rest = segments.slice(index + 1).join('/');
+          const target = this.__substrateLinkTarget(linkPath, child.target!);
+          resolved = this.normalizePath(rest ? target + '/' + rest : target);
+          linked = true;
+          break;
+        }
+        current = child;
+      }
+      if (!linked) return resolved;
+    }
+    throw createNodeError('ELOOP', 'realpath', path);
+  }
+
+  /**
+   * Watch for file changes
+   */
+  watch(
+    filename: string,
+    optionsOrListener?: { persistent?: boolean; recursive?: boolean; encoding?: string } | WatchListener,
+    listener?: WatchListener
+  ): FSWatcher {
+    const normalized = this.normalizePath(filename);
+
+    // Parse arguments
+    let options: { persistent?: boolean; recursive?: boolean } = {};
+    let actualListener: WatchListener | undefined;
+
+    if (typeof optionsOrListener === 'function') {
+      actualListener = optionsOrListener;
+    } else if (optionsOrListener) {
+      options = optionsOrListener;
+      actualListener = listener;
+    } else {
+      actualListener = listener;
+    }
+
+    // Create watcher entry
+    const entry: WatcherEntry = {
+      listener: actualListener || (() => {}),
+      recursive: options.recursive || false,
+      closed: false,
+    };
+
+    // Add to watchers map
+    if (!this.watchers.has(normalized)) {
+      this.watchers.set(normalized, new Set());
+    }
+    this.watchers.get(normalized)!.add(entry);
+
+    // Return FSWatcher interface
+    const watcher: FSWatcher = {
+      close: () => {
+        entry.closed = true;
+        const watcherSet = this.watchers.get(normalized);
+        if (watcherSet) {
+          watcherSet.delete(entry);
+          if (watcherSet.size === 0) {
+            this.watchers.delete(normalized);
+          }
+        }
+      },
+      ref: () => watcher,
+      unref: () => watcher,
+    };
+
+    return watcher;
+  }
+
+  /**
+   * Notify watchers of file changes
+   */
+  private notifyWatchers(path: string, eventType: WatchEventType): void {
+    const normalized = this.normalizePath(path);
+    const basename = this.getBasename(normalized);
+
+    // Check direct watchers on this file
+    const directWatchers = this.watchers.get(normalized);
+    if (directWatchers) {
+      for (const entry of directWatchers) {
+        if (!entry.closed) {
+          try {
+            entry.listener(eventType, basename);
+          } catch (err) {
+            console.error('Error in file watcher:', err);
+          }
+        }
+      }
+    }
+
+    // Check parent directory watchers (recursive and non-recursive)
+    let currentPath = this.getParentPath(normalized);
+    let relativePath = basename;
+
+    while (currentPath) {
+      const parentWatchers = this.watchers.get(currentPath);
+      if (parentWatchers) {
+        for (const entry of parentWatchers) {
+          if (!entry.closed) {
+            // Non-recursive watchers only get notified for direct children
+            const isDirectChild = this.getParentPath(normalized) === currentPath;
+            if (entry.recursive || isDirectChild) {
+              try {
+                entry.listener(eventType, relativePath);
+              } catch (err) {
+                console.error('Error in file watcher:', err);
+              }
+            }
+          }
+        }
+      }
+
+      if (currentPath === '/') break;
+      relativePath = this.getBasename(currentPath) + '/' + relativePath;
+      currentPath = this.getParentPath(currentPath);
+    }
+  }
+
+  /**
+   * Access check - in our VFS, always succeeds if file exists
+   */
+  accessSync(path: string, mode?: number): void {
+    if (!this.existsSync(path)) {
+      throw createNodeError('ENOENT', 'access', path);
+    }
+  }
+
+  /**
+   * Async access
+   */
+  access(path: string, modeOrCallback?: number | ((err: Error | null) => void), callback?: (err: Error | null) => void): void {
+    const actualCallback = typeof modeOrCallback === 'function' ? modeOrCallback : callback;
+    try {
+      this.accessSync(path);
+      if (actualCallback) queueMicrotask(() => actualCallback(null));
+    } catch (err) {
+      if (actualCallback) queueMicrotask(() => actualCallback(err as Error));
+    }
+  }
+
+  /**
+   * Copy file
+   */
+  copyFileSync(src: string, dest: string): void {
+    const content = this.readFileSync(src);
+    this.writeFileSync(dest, content);
+  }
+
+  /**
+   * Create read stream - simplified implementation
+   */
+  createReadStream(path: string, options?: ReadStreamOptions | string): FsReadStream {
+    const self = this;
+    const opts = typeof options === 'string' ? { encoding: options } : options || {};
+    const stream = new Readable() as FsReadStream;
+    stream.path = path;
+    stream.bytesRead = 0;
+    if (opts.encoding) stream.setEncoding(opts.encoding);
+    setTimeout(() => {
+      try {
+        let data = self.readFileSync(path);
+        const start = typeof opts.start === 'number' ? opts.start : 0;
+        const end = typeof opts.end === 'number' ? opts.end + 1 : data.length;
+        if (start > 0 || end < data.length) data = data.subarray(start, Math.max(start, end));
+        stream.bytesRead = data.length;
+        stream.emit('open');
+        stream.emit('ready');
+        if (data.length > 0) stream.push(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+        stream.push(null);
+      } catch (err) {
+        stream.emit('error', err);
+      }
+    }, 0);
+    return stream;
+  }
+
+  /**
+   * Create write stream - simplified implementation
+   */
+  createWriteStream(path: string): {
+    write: (data: string | Uint8Array) => boolean;
+    end: (data?: string | Uint8Array) => void;
+    on: (event: string, cb: (...args: unknown[]) => void) => void;
+  } {
+    const self = this;
+    const chunks: Uint8Array[] = [];
+    const listeners: Record<string, ((...args: unknown[]) => void)[]> = {};
+    const encoder = new TextEncoder();
+
+    return {
+      write(data: string | Uint8Array): boolean {
+        const chunk = typeof data === 'string' ? encoder.encode(data) : data;
+        chunks.push(chunk);
+        return true;
+      },
+      end(data?: string | Uint8Array): void {
+        if (data) {
+          const chunk = typeof data === 'string' ? encoder.encode(data) : data;
+          chunks.push(chunk);
+        }
+        // Combine chunks
+        const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+        const combined = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.length;
+        }
+        self.writeFileSync(path, combined);
+        listeners['finish']?.forEach((cb) => cb());
+        listeners['close']?.forEach((cb) => cb());
+      },
+      on(event: string, cb: (...args: unknown[]) => void) {
+        if (!listeners[event]) listeners[event] = [];
+        listeners[event].push(cb);
+        return this;
+      },
+    };
+  }
+}