initial

ts/providers/smartfs.provider.memory.ts

@@ -0,0 +1,642 @@
+/**
+ * In-memory filesystem provider for SmartFS
+ * Perfect for testing and temporary storage
+ */
+
+import type {
+  ISmartFsProvider,
+  IProviderCapabilities,
+  TWatchCallback,
+  IWatcherHandle,
+} from '../interfaces/mod.provider.js';
+
+import type {
+  IFileStats,
+  IDirectoryEntry,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+  IListOptions,
+  IWatchOptions,
+  ITransactionOperation,
+  IWatchEvent,
+  TWatchEventType,
+} from '../interfaces/mod.types.js';
+
+/**
+ * In-memory file entry
+ */
+interface IMemoryEntry {
+  type: 'file' | 'directory';
+  content?: Buffer;
+  created: Date;
+  modified: Date;
+  accessed: Date;
+  mode: number;
+}
+
+/**
+ * Watcher registration
+ */
+interface IWatcherRegistration {
+  path: string;
+  callback: TWatchCallback;
+  options?: IWatchOptions;
+}
+
+/**
+ * In-memory filesystem provider
+ */
+export class SmartFsProviderMemory implements ISmartFsProvider {
+  public readonly name = 'memory';
+
+  public readonly capabilities: IProviderCapabilities = {
+    supportsWatch: true,
+    supportsAtomic: true,
+    supportsTransactions: true,
+    supportsStreaming: true,
+    supportsSymlinks: false, // Not implemented yet
+    supportsPermissions: true,
+  };
+
+  private storage: Map<string, IMemoryEntry> = new Map();
+  private watchers: Map<string, IWatcherRegistration> = new Map();
+  private nextWatcherId = 1;
+
+  constructor() {
+    // Create root directory
+    this.storage.set('/', {
+      type: 'directory',
+      created: new Date(),
+      modified: new Date(),
+      accessed: new Date(),
+      mode: 0o755,
+    });
+  }
+
+  // --- File Operations ---
+
+  public async readFile(path: string, options?: IReadOptions): Promise<Buffer | string> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+
+    if (entry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+    }
+
+    entry.accessed = new Date();
+
+    if (!entry.content) {
+      return options?.encoding ? '' : Buffer.alloc(0);
+    }
+
+    if (options?.encoding && options.encoding !== 'buffer') {
+      return entry.content.toString(options.encoding as BufferEncoding);
+    }
+
+    return entry.content;
+  }
+
+  public async writeFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, options?.encoding as BufferEncoding);
+
+    // Ensure parent directory exists
+    await this.ensureParentDirectory(path);
+
+    const now = new Date();
+    const entry = this.storage.get(path);
+
+    if (entry && entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, open '${path}'`);
+    }
+
+    this.storage.set(path, {
+      type: 'file',
+      content: buffer,
+      created: entry?.created || now,
+      modified: now,
+      accessed: now,
+      mode: options?.mode || 0o644,
+    });
+
+    await this.emitWatchEvent(path, entry ? 'change' : 'add');
+  }
+
+  public async appendFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, options?.encoding as BufferEncoding);
+
+    const entry = this.storage.get(path);
+
+    if (entry && entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, open '${path}'`);
+    }
+
+    const existingContent = entry?.content || Buffer.alloc(0);
+    const newContent = Buffer.concat([existingContent, buffer]);
+
+    await this.writeFile(path, newContent, options);
+  }
+
+  public async deleteFile(path: string): Promise<void> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, unlink '${path}'`);
+    }
+
+    if (entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, unlink '${path}'`);
+    }
+
+    this.storage.delete(path);
+    await this.emitWatchEvent(path, 'delete');
+  }
+
+  public async copyFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    const fromEntry = this.storage.get(from);
+
+    if (!fromEntry) {
+      throw new Error(`ENOENT: no such file or directory, copyfile '${from}'`);
+    }
+
+    if (fromEntry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, copyfile '${from}'`);
+    }
+
+    const toEntry = this.storage.get(to);
+    if (toEntry && !options?.overwrite) {
+      throw new Error(`EEXIST: file already exists, copyfile '${from}' -> '${to}'`);
+    }
+
+    const now = new Date();
+    this.storage.set(to, {
+      type: 'file',
+      content: fromEntry.content ? Buffer.from(fromEntry.content) : undefined,
+      created: now,
+      modified: options?.preserveTimestamps ? fromEntry.modified : now,
+      accessed: now,
+      mode: fromEntry.mode,
+    });
+
+    await this.emitWatchEvent(to, toEntry ? 'change' : 'add');
+  }
+
+  public async moveFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    await this.copyFile(from, to, options);
+    await this.deleteFile(from);
+  }
+
+  public async fileExists(path: string): Promise<boolean> {
+    const entry = this.storage.get(path);
+    return entry !== undefined && entry.type === 'file';
+  }
+
+  public async fileStat(path: string): Promise<IFileStats> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    }
+
+    if (entry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, stat '${path}'`);
+    }
+
+    return {
+      size: entry.content?.length || 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: true,
+      isDirectory: false,
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  public async createReadStream(path: string, options?: IStreamOptions): Promise<ReadableStream<Uint8Array>> {
+    const content = await this.readFile(path);
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const chunkSize = options?.chunkSize || 64 * 1024;
+
+    let offset = 0;
+
+    return new ReadableStream({
+      pull(controller) {
+        if (offset >= buffer.length) {
+          controller.close();
+          return;
+        }
+
+        const end = Math.min(offset + chunkSize, buffer.length);
+        const chunk = buffer.subarray(offset, end);
+        controller.enqueue(new Uint8Array(chunk));
+        offset = end;
+      },
+    });
+  }
+
+  public async createWriteStream(path: string, options?: IStreamOptions): Promise<WritableStream<Uint8Array>> {
+    const chunks: Buffer[] = [];
+
+    return new WritableStream({
+      write: async (chunk) => {
+        chunks.push(Buffer.from(chunk));
+      },
+      close: async () => {
+        const content = Buffer.concat(chunks);
+        await this.writeFile(path, content);
+      },
+    });
+  }
+
+  // --- Directory Operations ---
+
+  public async listDirectory(path: string, options?: IListOptions): Promise<IDirectoryEntry[]> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+    }
+
+    const entries: IDirectoryEntry[] = [];
+    const normalizedPath = this.normalizePath(path);
+    const prefix = normalizedPath === '/' ? '/' : `${normalizedPath}/`;
+
+    for (const [entryPath, entryData] of this.storage.entries()) {
+      if (entryPath === normalizedPath) continue;
+
+      if (options?.recursive) {
+        // Recursive: include all descendants
+        if (entryPath.startsWith(prefix)) {
+          const relativePath = entryPath.slice(prefix.length);
+          const name = relativePath.split('/').pop()!;
+
+          const directoryEntry: IDirectoryEntry = {
+            name,
+            path: entryPath,
+            isFile: entryData.type === 'file',
+            isDirectory: entryData.type === 'directory',
+            isSymbolicLink: false,
+          };
+
+          if (this.matchesFilter(directoryEntry, options.filter)) {
+            if (options.includeStats) {
+              directoryEntry.stats = await this.getEntryStats(entryPath, entryData);
+            }
+            entries.push(directoryEntry);
+          }
+        }
+      } else {
+        // Non-recursive: only direct children
+        if (entryPath.startsWith(prefix) && !entryPath.slice(prefix.length).includes('/')) {
+          const name = entryPath.slice(prefix.length);
+
+          const directoryEntry: IDirectoryEntry = {
+            name,
+            path: entryPath,
+            isFile: entryData.type === 'file',
+            isDirectory: entryData.type === 'directory',
+            isSymbolicLink: false,
+          };
+
+          if (this.matchesFilter(directoryEntry, options?.filter)) {
+            if (options?.includeStats) {
+              directoryEntry.stats = await this.getEntryStats(entryPath, entryData);
+            }
+            entries.push(directoryEntry);
+          }
+        }
+      }
+    }
+
+    return entries;
+  }
+
+  public async createDirectory(path: string, options?: { recursive?: boolean; mode?: number }): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+
+    if (options?.recursive) {
+      // Create parent directories
+      const parts = normalizedPath.split('/').filter(Boolean);
+      let currentPath = '/';
+
+      for (const part of parts) {
+        currentPath = currentPath === '/' ? `/${part}` : `${currentPath}/${part}`;
+
+        if (!this.storage.has(currentPath)) {
+          const now = new Date();
+          this.storage.set(currentPath, {
+            type: 'directory',
+            created: now,
+            modified: now,
+            accessed: now,
+            mode: options?.mode || 0o755,
+          });
+          await this.emitWatchEvent(currentPath, 'add');
+        }
+      }
+    } else {
+      const entry = this.storage.get(normalizedPath);
+
+      if (entry) {
+        throw new Error(`EEXIST: file already exists, mkdir '${normalizedPath}'`);
+      }
+
+      const now = new Date();
+      this.storage.set(normalizedPath, {
+        type: 'directory',
+        created: now,
+        modified: now,
+        accessed: now,
+        mode: options?.mode || 0o755,
+      });
+
+      await this.emitWatchEvent(normalizedPath, 'add');
+    }
+  }
+
+  public async deleteDirectory(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, rmdir '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, rmdir '${path}'`);
+    }
+
+    if (options?.recursive) {
+      // Delete all descendants
+      const normalizedPath = this.normalizePath(path);
+      const prefix = normalizedPath === '/' ? '/' : `${normalizedPath}/`;
+
+      const toDelete: string[] = [];
+      for (const entryPath of this.storage.keys()) {
+        if (entryPath.startsWith(prefix) || entryPath === normalizedPath) {
+          toDelete.push(entryPath);
+        }
+      }
+
+      for (const entryPath of toDelete) {
+        this.storage.delete(entryPath);
+        await this.emitWatchEvent(entryPath, 'delete');
+      }
+    } else {
+      // Check if directory is empty
+      const children = await this.listDirectory(path);
+      if (children.length > 0) {
+        throw new Error(`ENOTEMPTY: directory not empty, rmdir '${path}'`);
+      }
+
+      this.storage.delete(path);
+      await this.emitWatchEvent(path, 'delete');
+    }
+  }
+
+  public async directoryExists(path: string): Promise<boolean> {
+    const entry = this.storage.get(path);
+    return entry !== undefined && entry.type === 'directory';
+  }
+
+  public async directoryStat(path: string): Promise<IFileStats> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, stat '${path}'`);
+    }
+
+    return {
+      size: 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: false,
+      isDirectory: true,
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  // --- Watch Operations ---
+
+  public async watch(path: string, callback: TWatchCallback, options?: IWatchOptions): Promise<IWatcherHandle> {
+    const watcherId = `watcher-${this.nextWatcherId++}`;
+
+    this.watchers.set(watcherId, {
+      path: this.normalizePath(path),
+      callback,
+      options,
+    });
+
+    return {
+      stop: async () => {
+        this.watchers.delete(watcherId);
+      },
+    };
+  }
+
+  // --- Transaction Operations ---
+
+  public async prepareTransaction(operations: ITransactionOperation[]): Promise<ITransactionOperation[]> {
+    const prepared: ITransactionOperation[] = [];
+
+    for (const op of operations) {
+      const preparedOp = { ...op };
+      const entry = this.storage.get(op.path);
+
+      if (entry && entry.type === 'file') {
+        preparedOp.backup = {
+          existed: true,
+          content: entry.content ? Buffer.from(entry.content) : undefined,
+          stats: await this.getEntryStats(op.path, entry),
+        };
+      } else {
+        preparedOp.backup = {
+          existed: false,
+        };
+      }
+
+      prepared.push(preparedOp);
+    }
+
+    return prepared;
+  }
+
+  public async executeTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (const op of operations) {
+      try {
+        switch (op.type) {
+          case 'write':
+            await this.writeFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'append':
+            await this.appendFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'delete':
+            await this.deleteFile(op.path);
+            break;
+          case 'copy':
+            await this.copyFile(op.path, op.targetPath!);
+            break;
+          case 'move':
+            await this.moveFile(op.path, op.targetPath!);
+            break;
+        }
+      } catch (error) {
+        // On error, rollback
+        await this.rollbackTransaction(operations);
+        throw error;
+      }
+    }
+  }
+
+  public async rollbackTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (let i = operations.length - 1; i >= 0; i--) {
+      const op = operations[i];
+      if (!op.backup) continue;
+
+      try {
+        if (op.backup.existed && op.backup.content) {
+          await this.writeFile(op.path, op.backup.content);
+        } else if (!op.backup.existed) {
+          try {
+            await this.deleteFile(op.path);
+          } catch {
+            // Ignore errors
+          }
+        }
+      } catch {
+        // Ignore rollback errors
+      }
+    }
+  }
+
+  // --- Path Operations ---
+
+  public normalizePath(path: string): string {
+    // Simple normalization
+    let normalized = path.replace(/\\/g, '/');
+    normalized = normalized.replace(/\/+/g, '/');
+    if (normalized !== '/' && normalized.endsWith('/')) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (!normalized.startsWith('/')) {
+      normalized = `/${normalized}`;
+    }
+    return normalized;
+  }
+
+  public joinPath(...segments: string[]): string {
+    return this.normalizePath(segments.join('/'));
+  }
+
+  // --- Helper Methods ---
+
+  private async ensureParentDirectory(path: string): Promise<void> {
+    const parentPath = path.split('/').slice(0, -1).join('/') || '/';
+    if (!this.storage.has(parentPath)) {
+      await this.createDirectory(parentPath, { recursive: true });
+    }
+  }
+
+  private async emitWatchEvent(path: string, type: TWatchEventType): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+
+    for (const { path: watchPath, callback, options } of this.watchers.values()) {
+      const shouldTrigger = options?.recursive
+        ? normalizedPath.startsWith(watchPath)
+        : normalizedPath.split('/').slice(0, -1).join('/') === watchPath;
+
+      if (!shouldTrigger) continue;
+
+      // Apply filter
+      if (options?.filter && !this.matchesPathFilter(normalizedPath, options.filter)) {
+        continue;
+      }
+
+      const entry = this.storage.get(normalizedPath);
+      const event: IWatchEvent = {
+        type,
+        path: normalizedPath,
+        timestamp: new Date(),
+        stats: entry ? await this.getEntryStats(normalizedPath, entry) : undefined,
+      };
+
+      await callback(event);
+    }
+  }
+
+  private async getEntryStats(path: string, entry: IMemoryEntry): Promise<IFileStats> {
+    return {
+      size: entry.content?.length || 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: entry.type === 'file',
+      isDirectory: entry.type === 'directory',
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  private matchesFilter(
+    entry: IDirectoryEntry,
+    filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean),
+  ): boolean {
+    if (!filter) return true;
+
+    if (typeof filter === 'function') {
+      return filter(entry);
+    } else if (filter instanceof RegExp) {
+      return filter.test(entry.name);
+    } else {
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(entry.name);
+    }
+  }
+
+  private matchesPathFilter(
+    path: string,
+    filter: string | RegExp | ((path: string) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(path);
+    } else if (filter instanceof RegExp) {
+      return filter.test(path);
+    } else {
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(path);
+    }
+  }
+
+  /**
+   * Clear all data (useful for testing)
+   */
+  public clear(): void {
+    this.storage.clear();
+    // Recreate root
+    this.storage.set('/', {
+      type: 'directory',
+      created: new Date(),
+      modified: new Date(),
+      accessed: new Date(),
+      mode: 0o755,
+    });
+  }
+}

ts/providers/smartfs.provider.node.ts

@@ -0,0 +1,514 @@
+/**
+ * Node.js filesystem provider for SmartFS
+ * Uses Node.js fs/promises and fs.watch APIs
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as pathModule from 'path';
+import { Readable, Writable } from 'stream';
+
+import type {
+  ISmartFsProvider,
+  IProviderCapabilities,
+  TWatchCallback,
+  IWatcherHandle,
+} from '../interfaces/mod.provider.js';
+
+import type {
+  IFileStats,
+  IDirectoryEntry,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+  IListOptions,
+  IWatchOptions,
+  ITransactionOperation,
+  IWatchEvent,
+  TWatchEventType,
+} from '../interfaces/mod.types.js';
+
+/**
+ * Node.js filesystem provider
+ */
+export class SmartFsProviderNode implements ISmartFsProvider {
+  public readonly name = 'node';
+
+  public readonly capabilities: IProviderCapabilities = {
+    supportsWatch: true,
+    supportsAtomic: true,
+    supportsTransactions: true,
+    supportsStreaming: true,
+    supportsSymlinks: true,
+    supportsPermissions: true,
+  };
+
+  // --- File Operations ---
+
+  public async readFile(path: string, options?: IReadOptions): Promise<Buffer | string> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    if (encoding) {
+      return fs.readFile(path, { encoding });
+    }
+    return fs.readFile(path);
+  }
+
+  public async writeFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    const mode = options?.mode;
+
+    if (options?.atomic) {
+      // Atomic write: write to temp file, then rename
+      const tempPath = `${path}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+      try {
+        await fs.writeFile(tempPath, content, { encoding, mode });
+        await fs.rename(tempPath, path);
+      } catch (error) {
+        // Clean up temp file on error
+        try {
+          await fs.unlink(tempPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+        throw error;
+      }
+    } else {
+      await fs.writeFile(path, content, { encoding, mode });
+    }
+  }
+
+  public async appendFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    const mode = options?.mode;
+    await fs.appendFile(path, content, { encoding, mode });
+  }
+
+  public async deleteFile(path: string): Promise<void> {
+    await fs.unlink(path);
+  }
+
+  public async copyFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    // Copy the file
+    await fs.copyFile(from, to);
+
+    // Preserve timestamps if requested
+    if (options?.preserveTimestamps) {
+      const stats = await fs.stat(from);
+      await fs.utimes(to, stats.atime, stats.mtime);
+    }
+  }
+
+  public async moveFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    try {
+      // Try rename first (fastest if on same filesystem)
+      await fs.rename(from, to);
+
+      // Preserve timestamps if requested
+      if (options?.preserveTimestamps) {
+        const stats = await fs.stat(to);
+        await fs.utimes(to, stats.atime, stats.mtime);
+      }
+    } catch (error: any) {
+      if (error.code === 'EXDEV') {
+        // Cross-device move: copy then delete
+        await this.copyFile(from, to, options);
+        await this.deleteFile(from);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  public async fileExists(path: string): Promise<boolean> {
+    try {
+      await fs.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async fileStat(path: string): Promise<IFileStats> {
+    const stats = await fs.stat(path);
+    return this.convertStats(stats);
+  }
+
+  public async createReadStream(path: string, options?: IStreamOptions): Promise<ReadableStream<Uint8Array>> {
+    const nodeStream = fsSync.createReadStream(path, {
+      highWaterMark: options?.chunkSize || options?.highWaterMark,
+    });
+
+    return this.nodeReadableToWeb(nodeStream);
+  }
+
+  public async createWriteStream(path: string, options?: IStreamOptions): Promise<WritableStream<Uint8Array>> {
+    const nodeStream = fsSync.createWriteStream(path, {
+      highWaterMark: options?.chunkSize || options?.highWaterMark,
+    });
+
+    return this.nodeWritableToWeb(nodeStream);
+  }
+
+  // --- Directory Operations ---
+
+  public async listDirectory(path: string, options?: IListOptions): Promise<IDirectoryEntry[]> {
+    const entries: IDirectoryEntry[] = [];
+
+    if (options?.recursive) {
+      await this.listDirectoryRecursive(path, entries, options);
+    } else {
+      const dirents = await fs.readdir(path, { withFileTypes: true });
+
+      for (const dirent of dirents) {
+        const entryPath = pathModule.join(path, dirent.name);
+        const entry: IDirectoryEntry = {
+          name: dirent.name,
+          path: entryPath,
+          isFile: dirent.isFile(),
+          isDirectory: dirent.isDirectory(),
+          isSymbolicLink: dirent.isSymbolicLink(),
+        };
+
+        // Apply filter
+        if (options?.filter && !this.matchesFilter(entry, options.filter)) {
+          continue;
+        }
+
+        // Add stats if requested
+        if (options?.includeStats) {
+          try {
+            entry.stats = await this.fileStat(entryPath);
+          } catch {
+            // Ignore stat errors
+          }
+        }
+
+        entries.push(entry);
+      }
+    }
+
+    return entries;
+  }
+
+  private async listDirectoryRecursive(
+    path: string,
+    entries: IDirectoryEntry[],
+    options?: IListOptions,
+  ): Promise<void> {
+    const dirents = await fs.readdir(path, { withFileTypes: true });
+
+    for (const dirent of dirents) {
+      const entryPath = pathModule.join(path, dirent.name);
+      const entry: IDirectoryEntry = {
+        name: dirent.name,
+        path: entryPath,
+        isFile: dirent.isFile(),
+        isDirectory: dirent.isDirectory(),
+        isSymbolicLink: dirent.isSymbolicLink(),
+      };
+
+      // Apply filter
+      if (options?.filter && !this.matchesFilter(entry, options.filter)) {
+        // Skip this entry but continue recursion for directories
+        if (dirent.isDirectory()) {
+          await this.listDirectoryRecursive(entryPath, entries, options);
+        }
+        continue;
+      }
+
+      // Add stats if requested
+      if (options?.includeStats) {
+        try {
+          entry.stats = await this.fileStat(entryPath);
+        } catch {
+          // Ignore stat errors
+        }
+      }
+
+      entries.push(entry);
+
+      // Recurse into subdirectories
+      if (dirent.isDirectory()) {
+        await this.listDirectoryRecursive(entryPath, entries, options);
+      }
+    }
+  }
+
+  public async createDirectory(path: string, options?: { recursive?: boolean; mode?: number }): Promise<void> {
+    await fs.mkdir(path, {
+      recursive: options?.recursive,
+      mode: options?.mode,
+    });
+  }
+
+  public async deleteDirectory(path: string, options?: { recursive?: boolean }): Promise<void> {
+    await fs.rm(path, {
+      recursive: options?.recursive,
+      force: true,
+    });
+  }
+
+  public async directoryExists(path: string): Promise<boolean> {
+    try {
+      const stats = await fs.stat(path);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  public async directoryStat(path: string): Promise<IFileStats> {
+    const stats = await fs.stat(path);
+    return this.convertStats(stats);
+  }
+
+  // --- Watch Operations ---
+
+  public async watch(path: string, callback: TWatchCallback, options?: IWatchOptions): Promise<IWatcherHandle> {
+    const watcher = fsSync.watch(
+      path,
+      {
+        recursive: options?.recursive,
+      },
+      async (eventType, filename) => {
+        if (!filename) return;
+
+        const fullPath = pathModule.join(path, filename);
+
+        // Apply filter
+        if (options?.filter && !this.matchesPathFilter(fullPath, options.filter)) {
+          return;
+        }
+
+        // Determine event type
+        let type: TWatchEventType = 'change';
+        try {
+          await fs.access(fullPath);
+          type = eventType === 'rename' ? 'add' : 'change';
+        } catch {
+          type = 'delete';
+        }
+
+        // Get stats if available
+        let stats: IFileStats | undefined;
+        if (type !== 'delete') {
+          try {
+            stats = await this.fileStat(fullPath);
+          } catch {
+            // Ignore stat errors
+          }
+        }
+
+        const event: IWatchEvent = {
+          type,
+          path: fullPath,
+          timestamp: new Date(),
+          stats,
+        };
+
+        await callback(event);
+      },
+    );
+
+    return {
+      stop: async () => {
+        watcher.close();
+      },
+    };
+  }
+
+  // --- Transaction Operations ---
+
+  public async prepareTransaction(operations: ITransactionOperation[]): Promise<ITransactionOperation[]> {
+    const prepared: ITransactionOperation[] = [];
+
+    for (const op of operations) {
+      const preparedOp = { ...op };
+
+      // Create backup for rollback
+      try {
+        const exists = await this.fileExists(op.path);
+        if (exists) {
+          const content = await this.readFile(op.path);
+          const stats = await this.fileStat(op.path);
+          preparedOp.backup = {
+            existed: true,
+            content: Buffer.isBuffer(content) ? content : Buffer.from(content),
+            stats,
+          };
+        } else {
+          preparedOp.backup = {
+            existed: false,
+          };
+        }
+      } catch {
+        preparedOp.backup = {
+          existed: false,
+        };
+      }
+
+      prepared.push(preparedOp);
+    }
+
+    return prepared;
+  }
+
+  public async executeTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (const op of operations) {
+      try {
+        switch (op.type) {
+          case 'write':
+            await this.writeFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'append':
+            await this.appendFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'delete':
+            await this.deleteFile(op.path);
+            break;
+          case 'copy':
+            await this.copyFile(op.path, op.targetPath!);
+            break;
+          case 'move':
+            await this.moveFile(op.path, op.targetPath!);
+            break;
+        }
+      } catch (error) {
+        // On error, rollback the transaction
+        await this.rollbackTransaction(operations);
+        throw error;
+      }
+    }
+  }
+
+  public async rollbackTransaction(operations: ITransactionOperation[]): Promise<void> {
+    // Rollback in reverse order
+    for (let i = operations.length - 1; i >= 0; i--) {
+      const op = operations[i];
+      if (!op.backup) continue;
+
+      try {
+        if (op.backup.existed && op.backup.content) {
+          // Restore original content
+          await this.writeFile(op.path, op.backup.content);
+        } else if (!op.backup.existed) {
+          // Delete file that was created
+          try {
+            await this.deleteFile(op.path);
+          } catch {
+            // Ignore errors
+          }
+        }
+      } catch {
+        // Ignore rollback errors
+      }
+    }
+  }
+
+  // --- Path Operations ---
+
+  public normalizePath(path: string): string {
+    return pathModule.normalize(path);
+  }
+
+  public joinPath(...segments: string[]): string {
+    return pathModule.join(...segments);
+  }
+
+  // --- Helper Methods ---
+
+  private convertStats(stats: fsSync.Stats): IFileStats {
+    return {
+      size: stats.size,
+      birthtime: stats.birthtime,
+      mtime: stats.mtime,
+      atime: stats.atime,
+      isFile: stats.isFile(),
+      isDirectory: stats.isDirectory(),
+      isSymbolicLink: stats.isSymbolicLink(),
+      mode: stats.mode,
+    };
+  }
+
+  private matchesFilter(
+    entry: IDirectoryEntry,
+    filter: string | RegExp | ((entry: IDirectoryEntry) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(entry);
+    } else if (filter instanceof RegExp) {
+      return filter.test(entry.name);
+    } else {
+      // Simple glob-like pattern matching
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(entry.name);
+    }
+  }
+
+  private matchesPathFilter(
+    path: string,
+    filter: string | RegExp | ((path: string) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(path);
+    } else if (filter instanceof RegExp) {
+      return filter.test(path);
+    } else {
+      // Simple glob-like pattern matching
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(path);
+    }
+  }
+
+  // --- Stream Conversion Helpers ---
+
+  private nodeReadableToWeb(nodeStream: Readable): ReadableStream<Uint8Array> {
+    return new ReadableStream({
+      start(controller) {
+        nodeStream.on('data', (chunk: Buffer) => {
+          controller.enqueue(new Uint8Array(chunk));
+        });
+
+        nodeStream.on('end', () => {
+          controller.close();
+        });
+
+        nodeStream.on('error', (error) => {
+          controller.error(error);
+        });
+      },
+      cancel() {
+        nodeStream.destroy();
+      },
+    });
+  }
+
+  private nodeWritableToWeb(nodeStream: Writable): WritableStream<Uint8Array> {
+    return new WritableStream({
+      write(chunk) {
+        return new Promise((resolve, reject) => {
+          const canContinue = nodeStream.write(Buffer.from(chunk));
+          if (canContinue) {
+            resolve();
+          } else {
+            nodeStream.once('drain', resolve);
+            nodeStream.once('error', reject);
+          }
+        });
+      },
+      close() {
+        return new Promise((resolve, reject) => {
+          nodeStream.end();
+          nodeStream.once('finish', resolve);
+          nodeStream.once('error', reject);
+        });
+      },
+      abort(reason) {
+        nodeStream.destroy(new Error(reason));
+      },
+    });
+  }
+}