sandbox-fs 1.0.0 → 1.1.0

package/src/PathModule.ts

@@ -1,142 +0,0 @@
-import * as path from 'path';
-
-/**
- * Creates a path module that operates in virtual path space
- * All paths use Unix-style forward slashes
- * Fixed virtual CWD of '/'
- */
-export function createPathModule() {
-  const virtualCwd = '/';
-
-  const pathModule = {
-    /**
-     * Normalize a path, reducing '..' and '.' parts
-     */
-    normalize(p: string): string {
-      const normalized = path.posix.normalize(p);
-      // Ensure it starts with / if it's absolute-like
-      return normalized.startsWith('/') ? normalized : normalized;
-    },
-
-    /**
-     * Join all path segments together and normalize the result
-     */
-    join(...paths: string[]): string {
-      return path.posix.join(...paths);
-    },
-
-    /**
-     * Resolve a sequence of paths to an absolute path
-     */
-    resolve(...paths: string[]): string {
-      if (paths.length === 0) {
-        return virtualCwd;
-      }
-
-      let resolved = virtualCwd;
-      
-      for (const p of paths) {
-        if (path.posix.isAbsolute(p)) {
-          resolved = p;
-        } else {
-          resolved = path.posix.join(resolved, p);
-        }
-      }
-
-      return path.posix.normalize(resolved);
-    },
-
-    /**
-     * Return the relative path from 'from' to 'to'
-     */
-    relative(from: string, to: string): string {
-      return path.posix.relative(from, to);
-    },
-
-    /**
-     * Return the directory name of a path
-     */
-    dirname(p: string): string {
-      return path.posix.dirname(p);
-    },
-
-    /**
-     * Return the last portion of a path
-     */
-    basename(p: string, ext?: string): string {
-      return path.posix.basename(p, ext);
-    },
-
-    /**
-     * Return the extension of the path
-     */
-    extname(p: string): string {
-      return path.posix.extname(p);
-    },
-
-    /**
-     * Parse a path into an object
-     */
-    parse(p: string): path.ParsedPath {
-      const parsed = path.posix.parse(p);
-      // Ensure root is always '/' for virtual paths
-      if (parsed.root) {
-        parsed.root = '/';
-      }
-      return parsed;
-    },
-
-    /**
-     * Format a path object into a string
-     */
-    format(pathObject: path.FormatInputPathObject): string {
-      // Ensure root is '/' for virtual paths
-      const virtualPathObject = { ...pathObject };
-      if (virtualPathObject.root) {
-        virtualPathObject.root = '/';
-      }
-      return path.posix.format(virtualPathObject);
-    },
-
-    /**
-     * Check if a path is absolute
-     */
-    isAbsolute(p: string): boolean {
-      return p.startsWith('/');
-    },
-
-    /**
-     * Convert path to namespaced path (Windows-only, no-op in virtual space)
-     */
-    toNamespacedPath(p: string): string {
-      // In virtual space, just return the path as-is
-      return p;
-    },
-
-    /**
-     * Path segment separator (always / in virtual space)
-     */
-    sep: '/',
-
-    /**
-     * Path delimiter (always : in virtual space)
-     */
-    delimiter: ':',
-
-    /**
-     * POSIX-specific methods (same as main module in virtual space)
-     */
-    posix: null as any,
-
-    /**
-     * Windows-specific methods (same as main module in virtual space)
-     */
-    win32: null as any,
-  };
-
-  // Both posix and win32 reference the same virtual implementation
-  pathModule.posix = pathModule;
-  pathModule.win32 = pathModule;
-
-  return pathModule;
-}

package/src/ResourceTracker.ts

@@ -1,162 +0,0 @@
-import * as fs from 'fs';
-import { Readable, Writable } from 'stream';
-
-/**
- * Information about a tracked file descriptor
- */
-export interface FDInfo {
-  fd: number;
-  virtualPath: string;
-  realPath: string;
-  flags: string | number;
-  mode?: number;
-  isStream: boolean;
-}
-
-/**
- * Manages lifecycle of file descriptors and streams to prevent resource leaks
- * and ensure proper cleanup when VFS is closed
- */
-export class ResourceTracker {
-  private fdMap: Map<number, FDInfo> = new Map();
-  private streams: Set<Readable | Writable> = new Set();
-  private abortControllers: Set<AbortController> = new Set();
-  private _closed: boolean = false;
-
-  /**
-   * Check if the VFS has been closed
-   */
-  get closed(): boolean {
-    return this._closed;
-  }
-
-  /**
-   * Assert that the VFS is not closed, throwing EBADF if it is
-   */
-  assertNotClosed(): void {
-    if (this._closed) {
-      const error = new Error('bad file descriptor') as NodeJS.ErrnoException;
-      error.code = 'EBADF';
-      error.errno = -9;
-      error.syscall = 'read';
-      throw error;
-    }
-  }
-
-  /**
-   * Track a file descriptor
-   */
-  trackFD(fd: number, info: Omit<FDInfo, 'fd'>): void {
-    this.fdMap.set(fd, { fd, ...info });
-  }
-
-  /**
-   * Get information about a tracked file descriptor
-   */
-  getFD(fd: number): FDInfo | undefined {
-    return this.fdMap.get(fd);
-  }
-
-  /**
-   * Check if a file descriptor is tracked
-   */
-  isTracked(fd: number): boolean {
-    return this.fdMap.has(fd);
-  }
-
-  /**
-   * Untrack a file descriptor (when closed)
-   */
-  untrackFD(fd: number): FDInfo | undefined {
-    const info = this.fdMap.get(fd);
-    this.fdMap.delete(fd);
-    return info;
-  }
-
-  /**
-   * Track a stream
-   */
-  trackStream(stream: Readable | Writable): void {
-    this.streams.add(stream);
-  }
-
-  /**
-   * Untrack a stream (when closed)
-   */
-  untrackStream(stream: Readable | Writable): void {
-    this.streams.delete(stream);
-  }
-
-  /**
-   * Register an AbortSignal listener for cleanup
-   */
-  registerAbortListener(signal: AbortSignal | undefined, cleanup: () => void): void {
-    if (!signal) return;
-
-    const controller = new AbortController();
-    this.abortControllers.add(controller);
-
-    signal.addEventListener('abort', () => {
-      cleanup();
-      this.abortControllers.delete(controller);
-    }, { once: true });
-  }
-
-  /**
-   * Dispose all tracked resources and mark as closed
-   */
-  dispose(): void {
-    if (this._closed) return;
-
-    // Close all tracked file descriptors
-    for (const [fd, info] of this.fdMap) {
-      try {
-        if (!info.isStream) {
-          fs.closeSync(fd);
-        }
-      } catch (err) {
-        // Ignore errors during cleanup
-      }
-    }
-    this.fdMap.clear();
-
-    // Destroy all tracked streams
-    for (const stream of this.streams) {
-      try {
-        stream.destroy();
-      } catch (err) {
-        // Ignore errors during cleanup
-      }
-    }
-    this.streams.clear();
-
-    // Abort all pending operations
-    for (const controller of this.abortControllers) {
-      try {
-        controller.abort();
-      } catch (err) {
-        // Ignore errors during cleanup
-      }
-    }
-    this.abortControllers.clear();
-
-    this._closed = true;
-  }
-
-  /**
-   * Get all tracked file descriptors (for debugging)
-   */
-  getAllFDs(): FDInfo[] {
-    return Array.from(this.fdMap.values());
-  }
-
-  /**
-   * Get count of tracked resources
-   */
-  getResourceCount(): { fds: number; streams: number } {
-    return {
-      fds: this.fdMap.size,
-      streams: this.streams.size,
-    };
-  }
-}

package/src/VirtualFileSystem.ts

@@ -1,172 +0,0 @@
-import { PathMapper } from './PathMapper';
-import { ResourceTracker } from './ResourceTracker';
-import { createFSModule } from './FSModule';
-import { createPathModule } from './PathModule';
-
-/**
- * Options for creating a VirtualFileSystem
- */
-export interface VFSOptions {
-  /**
-   * The real filesystem path to use as the VFS root.
-   * Can be a Windows path (C:\data) or Unix path (/opt/data).
-   * All virtual paths will be mapped relative to this root.
-   */
-  root: string;
-}
-
-/**
- * A read-only virtual file system that maps Unix-style virtual paths
- * to a real directory root.
- * 
- * @example
- * ```typescript
- * const vfs = new VirtualFileSystem({ root: '/opt/data' });
- * const fs = vfs.createNodeFSModule();
- * const path = vfs.createNodePathModule();
- * 
- * // Read a file (real path: /opt/data/file.txt)
- * const content = fs.readFileSync('/file.txt', 'utf8');
- * 
- * // Write operations are denied
- * fs.writeFileSync('/file.txt', 'data'); // throws EACCES
- * 
- * // Clean up when done
- * vfs.close();
- * ```
- */
-export class VirtualFileSystem {
-  private pathMapper: PathMapper;
-  private resourceTracker: ResourceTracker;
-
-  /**
-   * Create a new VirtualFileSystem instance
-   * 
-   * @param options - Configuration options
-   * @throws Error if root path doesn't exist or is not a directory
-   */
-  constructor(options: VFSOptions) {
-    this.pathMapper = new PathMapper(options.root);
-    this.resourceTracker = new ResourceTracker();
-  }
-
-  /**
-   * Convert a virtual path to a real filesystem path
-   * 
-   * @param virtualPath - Virtual path (Unix-style, starts with /)
-   * @returns Real filesystem path (platform-native)
-   * @throws Error if path traversal is detected
-   * 
-   * @example
-   * ```typescript
-   * const vfs = new VirtualFileSystem({ root: 'C:\\data' });
-   * vfs.toRealPath('/foo/bar.txt'); // Returns: C:\data\foo\bar.txt
-   * ```
-   */
-  toRealPath(virtualPath: string): string {
-    return this.pathMapper.toRealPath(virtualPath);
-  }
-
-  /**
-   * Convert a real filesystem path to a virtual path
-   * 
-   * @param realPath - Real filesystem path (platform-native)
-   * @returns Virtual path (Unix-style, starts with /)
-   * @throws Error if real path is outside VFS root
-   * 
-   * @example
-   * ```typescript
-   * const vfs = new VirtualFileSystem({ root: 'C:\\data' });
-   * vfs.toVirtualPath('C:\\data\\foo\\bar.txt'); // Returns: /foo/bar.txt
-   * ```
-   */
-  toVirtualPath(realPath: string): string {
-    return this.pathMapper.toVirtualPath(realPath);
-  }
-
-  /**
-   * Create a Node.js fs-compatible module
-   * 
-   * Returns an object that matches the Node.js fs module API.
-   * All read operations work normally, write operations return EACCES,
-   * and symlink operations return EACCES. Error messages have real paths
-   * filtered out and replaced with virtual paths.
-   * 
-   * @returns An fs-compatible object with both callback and promise APIs
-   * 
-   * @example
-   * ```typescript
-   * const vfs = new VirtualFileSystem({ root: '/opt/data' });
-   * const fs = vfs.createNodeFSModule();
-   * 
-   * // Callback API
-   * fs.readFile('/file.txt', 'utf8', (err, data) => {
-   *   if (err) throw err;
-   *   console.log(data);
-   * });
-   * 
-   * // Promise API
-   * const data = await fs.promises.readFile('/file.txt', 'utf8');
-   * 
-   * // Sync API
-   * const data = fs.readFileSync('/file.txt', 'utf8');
-   * ```
-   */
-  createNodeFSModule(): any {
-    return createFSModule(this.pathMapper, this.resourceTracker);
-  }
-
-  /**
-   * Create a Node.js path-compatible module
-   * 
-   * Returns an object that matches the Node.js path module API.
-   * All operations use Unix-style paths with forward slashes.
-   * The virtual current working directory is always '/'.
-   * 
-   * @returns A path-compatible object
-   * 
-   * @example
-   * ```typescript
-   * const vfs = new VirtualFileSystem({ root: '/opt/data' });
-   * const path = vfs.createNodePathModule();
-   * 
-   * path.resolve('.');           // Returns: /
-   * path.resolve('foo/bar.txt'); // Returns: /foo/bar.txt
-   * path.join('/foo', 'bar');    // Returns: /foo/bar
-   * path.sep;                     // Returns: /
-   * ```
-   */
-  createNodePathModule(): any {
-    return createPathModule();
-  }
-
-  /**
-   * Close the VFS and release all resources
-   * 
-   * Closes all tracked file descriptors, destroys all streams,
-   * and marks the VFS as closed. After calling close(), all
-   * subsequent fs operations will throw EBADF errors.
-   * 
-   * @example
-   * ```typescript
-   * const vfs = new VirtualFileSystem({ root: '/opt/data' });
-   * const fs = vfs.createNodeFSModule();
-   * 
-   * const fd = fs.openSync('/file.txt', 'r');
-   * 
-   * vfs.close(); // Closes fd and all other resources
-   * 
-   * fs.readFileSync('/file.txt'); // Throws EBADF
-   * ```
-   */
-  close(): void {
-    this.resourceTracker.dispose();
-  }
-
-  /**
-   * Check if the VFS has been closed
-   */
-  get closed(): boolean {
-    return this.resourceTracker.closed;
-  }
-}

package/src/index.ts

@@ -1,9 +0,0 @@
-/**
- * sandbox-fs - A read-only virtual file system for Node.js
- * 
- * Maps Unix-style virtual paths to a real directory root while preventing
- * write operations and filtering real paths from error messages.
- */
-
-export { VirtualFileSystem, VirtualFileSystem as default } from './VirtualFileSystem';
-export type { VFSOptions } from './VirtualFileSystem';

package/src/operations/newer.ts

@@ -1,223 +0,0 @@
-import * as fs from 'fs';
-import type { PathMapper } from '../PathMapper';
-import type { ResourceTracker } from '../ResourceTracker';
-import { filterError } from '../utils/ErrorFilter';
-
-/**
- * Wrap an async operation with error filtering and closed check
- */
-async function wrapOperation<T>(
-  operation: () => Promise<T>,
-  pathMapper: PathMapper,
-  resourceTracker: ResourceTracker
-): Promise<T> {
-  resourceTracker.assertNotClosed();
-  try {
-    return await operation();
-  } catch (error) {
-    throw filterError(error as Error, pathMapper);
-  }
-}
-
-/**
- * Create access denied error for write operations
- */
-function createEACCESError(syscall: string, path: string): NodeJS.ErrnoException {
-  const error = new Error(`${syscall}: operation not permitted, ${syscall} '${path}'`) as NodeJS.ErrnoException;
-  error.code = 'EACCES';
-  error.errno = -13;
-  error.syscall = syscall;
-  error.path = path;
-  return error;
-}
-
-/**
- * glob - Pattern matching (Node.js 22+)
- */
-export function createGlobOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return async function* (pattern: string, options?: any): AsyncIterableIterator<string> {
-    resourceTracker.assertNotClosed();
-    
-    try {
-      // Check if glob is available (Node.js 22+)
-      if (typeof (fs.promises as any).glob !== 'function') {
-        throw new Error('glob is not supported in this Node.js version');
-      }
-      
-      // Convert pattern to real path context
-      const realRoot = pathMapper.getRoot();
-      
-      if (options?.signal) {
-        resourceTracker.registerAbortListener(options.signal, () => {});
-      }
-      
-      // Execute glob in real path context
-      const realOptions = { ...options, cwd: realRoot };
-      const globIterator = (fs.promises as any).glob(pattern, realOptions);
-      
-      for await (const realPath of globIterator) {
-        try {
-          // Convert real path back to virtual path
-          const virtualPath = pathMapper.toVirtualPath(realPath);
-          yield virtualPath;
-        } catch (error) {
-          // Skip paths that can't be converted (outside VFS root)
-          continue;
-        }
-      }
-    } catch (error) {
-      throw filterError(error as Error, pathMapper);
-    }
-  };
-}
-
-/**
- * statfs - File system statistics (Node.js 19+)
- */
-export function createStatfsOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return async (virtualPath: string, options?: any): Promise<fs.StatsFsBase<any>> => {
-    return wrapOperation(async () => {
-      // Check if statfs is available (Node.js 19+)
-      if (typeof (fs.promises as any).statfs !== 'function') {
-        throw new Error('statfs is not supported in this Node.js version');
-      }
-      
-      const realPath = pathMapper.toRealPath(virtualPath);
-      
-      if (options?.signal) {
-        resourceTracker.registerAbortListener(options.signal, () => {});
-      }
-      
-      return (fs.promises as any).statfs(realPath, options);
-    }, pathMapper, resourceTracker);
-  };
-}
-
-/**
- * cp - Copy files/directories (read source only, write dest is denied)
- */
-export function createCpOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return async (source: string, destination: string, options?: any): Promise<void> => {
-    // Always deny - this is a write operation
-    throw createEACCESError('cp', destination);
-  };
-}
-
-/**
- * openAsBlob - Open file as Blob (Node.js 19+)
- */
-export function createOpenAsBlobOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return async (virtualPath: string, options?: any): Promise<Blob> => {
-    return wrapOperation(async () => {
-      // Check if openAsBlob is available (Node.js 19+)
-      if (typeof (fs as any).openAsBlob !== 'function') {
-        throw new Error('openAsBlob is not supported in this Node.js version');
-      }
-      
-      const realPath = pathMapper.toRealPath(virtualPath);
-      
-      if (options?.signal) {
-        resourceTracker.registerAbortListener(options.signal, () => {});
-      }
-      
-      return (fs as any).openAsBlob(realPath, options);
-    }, pathMapper, resourceTracker);
-  };
-}
-
-/**
- * readv - Vector read (Node.js 13+)
- */
-export function createReadvOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return async (fd: number, buffers: NodeJS.ArrayBufferView[], position?: number): Promise<number> => {
-    return wrapOperation(async () => {
-      if (!resourceTracker.isTracked(fd)) {
-        const error = new Error('bad file descriptor') as NodeJS.ErrnoException;
-        error.code = 'EBADF';
-        error.errno = -9;
-        error.syscall = 'readv';
-        throw error;
-      }
-      
-      // Check if readv is available
-      if (typeof (fs.promises as any).readv !== 'function') {
-        throw new Error('readv is not supported in this Node.js version');
-      }
-      
-      return (fs.promises as any).readv(fd, buffers, position);
-    }, pathMapper, resourceTracker);
-  };
-}
-
-/**
- * watch - Watch for file changes
- */
-export function createWatchOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return (virtualPath: string, options?: any): fs.FSWatcher => {
-    resourceTracker.assertNotClosed();
-    
-    try {
-      const realPath = pathMapper.toRealPath(virtualPath);
-      const watcher = fs.watch(realPath, options);
-      
-      // Wrap error events to filter paths
-      const originalOn = watcher.on.bind(watcher);
-      watcher.on = function(event: string, listener: any) {
-        if (event === 'error') {
-          const wrappedListener = (error: Error) => {
-            listener(filterError(error, pathMapper));
-          };
-          return originalOn(event, wrappedListener);
-        }
-        return originalOn(event, listener);
-      };
-      
-      return watcher;
-    } catch (error) {
-      throw filterError(error as Error, pathMapper);
-    }
-  };
-}
-
-/**
- * watchFile - Watch a file for changes
- */
-export function createWatchFileOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return (virtualPath: string, options: any, listener?: any): void => {
-    resourceTracker.assertNotClosed();
-    
-    try {
-      const realPath = pathMapper.toRealPath(virtualPath);
-      
-      // Handle both signatures: (path, listener) and (path, options, listener)
-      if (typeof options === 'function') {
-        fs.watchFile(realPath, options);
-      } else {
-        fs.watchFile(realPath, options, listener);
-      }
-    } catch (error) {
-      throw filterError(error as Error, pathMapper);
-    }
-  };
-}
-
-/**
- * unwatchFile - Stop watching a file
- */
-export function createUnwatchFileOperation(pathMapper: PathMapper, resourceTracker: ResourceTracker) {
-  return (virtualPath: string, listener?: any): void => {
-    resourceTracker.assertNotClosed();
-    
-    try {
-      const realPath = pathMapper.toRealPath(virtualPath);
-      
-      if (listener) {
-        fs.unwatchFile(realPath, listener);
-      } else {
-        fs.unwatchFile(realPath);
-      }
-    } catch (error) {
-      throw filterError(error as Error, pathMapper);
-    }
-  };
-}