@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/node/events.ts

@@ -0,0 +1,176 @@
+/**
+ * Node's EventEmitter. Most of the Node API surface (streams, servers, child
+ * processes, `process` itself) is built on it, so it is written faithfully:
+ * listener order, `once` wrappers that `removeListener` can find, the throw on
+ * an unhandled `'error'`, and `newListener`/`removeListener` events.
+ */
+
+import { callable } from './callable.js';
+
+export type Listener = (...args: any[]) => unknown;
+interface OnceWrapper extends Listener {
+  listener: Listener;
+}
+
+/** The class itself, for subclassing inside the runtime; user code gets {@link EventEmitter}. */
+export class EventEmitterBase {
+  static defaultMaxListeners = 10;
+  static readonly errorMonitor = Symbol('events.errorMonitor');
+  // `declare`: no class-field initialiser, so a bare `EventEmitter.call(this)` and
+  // `new` set up the same state (see callable.ts).
+  declare _events: Map<string | symbol, Listener[]>;
+  declare _maxListeners?: number;
+
+  constructor() {
+    initEmitter(this);
+  }
+
+  /** Resolve with the arguments of the next `event` (rejects on `'error'`). */
+  static once(emitter: EventEmitterBase, event: string | symbol): Promise<unknown[]> {
+    return new Promise((resolve, reject) => {
+      const onError = (error: unknown) => {
+        emitter.removeListener(event, onEvent);
+        reject(error);
+      };
+      const onEvent = (...args: unknown[]) => {
+        if (event !== 'error') emitter.removeListener('error', onError);
+        resolve(args);
+      };
+      emitter.once(event, onEvent);
+      if (event !== 'error') emitter.once('error', onError);
+    });
+  }
+
+  static listenerCount(emitter: EventEmitterBase, event: string | symbol): number {
+    return emitter.listenerCount(event);
+  }
+
+  addListener(event: string | symbol, listener: Listener): this {
+    return this._add(event, listener, false);
+  }
+
+  on(event: string | symbol, listener: Listener): this {
+    return this._add(event, listener, false);
+  }
+
+  prependListener(event: string | symbol, listener: Listener): this {
+    return this._add(event, listener, true);
+  }
+
+  once(event: string | symbol, listener: Listener): this {
+    return this._add(event, this._onceWrap(event, listener), false);
+  }
+
+  prependOnceListener(event: string | symbol, listener: Listener): this {
+    return this._add(event, this._onceWrap(event, listener), true);
+  }
+
+  removeListener(event: string | symbol, listener: Listener): this {
+    const list = this._events?.get(event);
+    if (!list) return this;
+    for (let i = list.length - 1; i >= 0; i--) {
+      const entry = list[i]!;
+      if (entry === listener || (entry as OnceWrapper).listener === listener) {
+        list.splice(i, 1);
+        if (!list.length) this._events.delete(event);
+        if (this._events.has('removeListener')) this.emit('removeListener', event, listener);
+        break;
+      }
+    }
+    return this;
+  }
+
+  off(event: string | symbol, listener: Listener): this {
+    return this.removeListener(event, listener);
+  }
+
+  removeAllListeners(event?: string | symbol): this {
+    if (!this._events) return this;
+    if (event === undefined) this._events.clear();
+    else this._events.delete(event);
+    return this;
+  }
+
+  emit(event: string | symbol, ...args: unknown[]): boolean {
+    const list = this._events?.get(event);
+    if (event === 'error') {
+      this._events?.get(EventEmitterBase.errorMonitor)?.slice().forEach((l) => l.apply(this, args));
+      if (!list?.length) {
+        const error = args[0];
+        if (error instanceof Error) throw error;
+        const wrapped = new Error(`Unhandled error. (${String(error)})`) as Error & { context?: unknown };
+        wrapped.context = error;
+        throw wrapped;
+      }
+    }
+    if (!list?.length) return false;
+    for (const listener of list.slice()) listener.apply(this, args);
+    return true;
+  }
+
+  listeners(event: string | symbol): Listener[] {
+    return (this._events?.get(event) ?? []).map((l) => (l as OnceWrapper).listener ?? l);
+  }
+
+  rawListeners(event: string | symbol): Listener[] {
+    return [...(this._events?.get(event) ?? [])];
+  }
+
+  listenerCount(event: string | symbol): number {
+    return this._events?.get(event)?.length ?? 0;
+  }
+
+  eventNames(): Array<string | symbol> {
+    return [...(this._events?.keys() ?? [])];
+  }
+
+  setMaxListeners(n: number): this {
+    this._maxListeners = n;
+    return this;
+  }
+
+  getMaxListeners(): number {
+    return this._maxListeners ?? EventEmitterBase.defaultMaxListeners;
+  }
+
+  private _add(event: string | symbol, listener: Listener, prepend: boolean): this {
+    if (typeof listener !== 'function') throw new TypeError('The "listener" argument must be of type function');
+    // Subclasses created with util.inherits + EventEmitter.call(this) arrive here
+    // without the constructor's field initialisers having run on them.
+    if (!this._events) this._events = new Map();
+    if (this._events.has('newListener')) this.emit('newListener', event, (listener as OnceWrapper).listener ?? listener);
+    const list = this._events.get(event) ?? [];
+    if (prepend) list.unshift(listener);
+    else list.push(listener);
+    this._events.set(event, list);
+    return this;
+  }
+
+  private _onceWrap(event: string | symbol, listener: Listener): OnceWrapper {
+    let fired = false;
+    const wrapper = ((...args: unknown[]) => {
+      if (fired) return undefined;
+      fired = true;
+      this.removeListener(event, wrapper);
+      return listener.apply(this, args);
+    }) as OnceWrapper;
+    wrapper.listener = listener;
+    return wrapper;
+  }
+}
+
+function initEmitter(self: { _events?: Map<string | symbol, Listener[]> }): void {
+  if (!self._events || !(self._events instanceof Map)) self._events = new Map();
+}
+
+export const EventEmitter = callable(EventEmitterBase, initEmitter);
+export type EventEmitter = EventEmitterBase;
+
+/** The `events` module object: the class, with Node's statics hung on it. */
+export function createEventsModule(): Record<string, unknown> {
+  const mod = EventEmitter as unknown as Record<string, unknown>;
+  mod.EventEmitter = EventEmitter;
+  mod.once = EventEmitterBase.once;
+  mod.defaultMaxListeners = EventEmitterBase.defaultMaxListeners;
+  return mod;
+}

package/src/node/fs/index.ts

@@ -0,0 +1,277 @@
+/**
+ * The `fs` module: the sync API (sync.ts) plus callback, promise and stream
+ * forms derived from it, and `watch` over the VFS's change events.
+ *
+ * Async forms complete on a microtask. That is enough to keep ordering
+ * Node-like (callbacks never run synchronously) and, because microtasks always
+ * drain before the runtime's exit check, a chain of fs callbacks can never be
+ * cut short by the process exiting.
+ */
+import { EventEmitterBase } from '../events.js';
+import { Buffer } from '../buffer.js';
+import { Readable } from '../stream/readable.js';
+import { Writable } from '../stream/writable.js';
+import { createSyncFs, type FsContext, type SyncFs } from './sync.js';
+import { Dirent, Stats, constants } from './stats.js';
+import { normalizePath } from '../../paths.js';
+
+export interface FsModuleContext extends FsContext {
+  /** Keep the process alive (a watcher is open); call the result to let go. */
+  hold(): () => void;
+}
+
+type Fn = (...args: any[]) => any;
+
+const CHUNK = 64 * 1024;
+
+function lastCallback(args: unknown[]): Fn | undefined {
+  return typeof args[args.length - 1] === 'function' ? (args.pop() as Fn) : undefined;
+}
+
+export function createFsModule(ctx: FsModuleContext): Record<string, any> {
+  const sync = createSyncFs(ctx);
+
+  const toCallback = (fn: Fn, shape: (result: any, args: any[]) => any[] = (r) => [r]) =>
+    (...args: any[]) => {
+      const cb = lastCallback(args);
+      queueMicrotask(() => {
+        let result: unknown;
+        try {
+          result = fn(...args);
+        } catch (error) {
+          cb?.(error);
+          return;
+        }
+        cb?.(null, ...shape(result, args));
+      });
+    };
+
+  const toPromise = (fn: Fn) => async (...args: any[]) => fn(...args);
+
+  class ReadStream extends Readable {
+    bytesRead = 0;
+    readonly path: string;
+    fd: number | null = null;
+    pending = true;
+    private data?: Uint8Array;
+    private offset: number;
+    private readonly endAt: number;
+
+    constructor(path: string | URL, options: { start?: number; end?: number; encoding?: string; highWaterMark?: number; fd?: number } | string = {}) {
+      const opts = typeof options === 'string' ? { encoding: options } : options;
+      super({ highWaterMark: opts.highWaterMark ?? CHUNK, encoding: opts.encoding });
+      this.path = typeof options === 'object' && opts.fd !== undefined ? '' : sync._resolve(path);
+      this.offset = opts.start ?? 0;
+      this.endAt = opts.end ?? Infinity;
+      queueMicrotask(() => {
+        try {
+          const contents = sync.readFileSync(this.path) as Buffer;
+          this.data = contents;
+          this.fd = -1;
+          this.pending = false;
+          this.emit('open', this.fd);
+          this.emit('ready');
+          this._pull();
+        } catch (error) {
+          this.destroy(error as Error);
+        }
+      });
+    }
+
+    override _read(): void {
+      if (!this.data) {
+        this._readableState.reading = false; // retried once the file is loaded
+        return;
+      }
+      const end = Math.min(this.data.length, this.endAt + 1);
+      if (this.offset >= end) {
+        this.push(null);
+        return;
+      }
+      const chunk = this.data.subarray(this.offset, Math.min(end, this.offset + this._readableState.highWaterMark));
+      this.offset += chunk.length;
+      this.bytesRead += chunk.length;
+      this.push(Buffer.from(chunk));
+    }
+
+    close(callback?: Fn): void {
+      this.destroy();
+      if (callback) this.once('close', callback);
+    }
+  }
+
+  class WriteStream extends Writable {
+    bytesWritten = 0;
+    readonly path: string;
+    pending = false;
+    private started = false;
+
+    constructor(path: string | URL, private readonly options: { flags?: string; encoding?: string } | string = {}) {
+      super({ decodeStrings: true });
+      this.path = sync._resolve(path);
+      queueMicrotask(() => {
+        try {
+          this.open();
+          this.emit('open', -1);
+          this.emit('ready');
+        } catch (error) {
+          this.destroy(error as Error);
+        }
+      });
+    }
+
+    private open(): void {
+      if (this.started) return;
+      this.started = true;
+      const flags = typeof this.options === 'object' ? this.options.flags ?? 'w' : 'w';
+      if (!flags.startsWith('a') || !ctx.vfs.isFile(this.path)) sync.writeFileSync(this.path, '', { flag: flags.includes('x') ? 'wx' : 'w' });
+    }
+
+    override _write(chunk: Buffer, _encoding: string, callback: (error?: Error | null) => void): void {
+      try {
+        this.open();
+        sync.appendFileSync(this.path, chunk);
+        this.bytesWritten += chunk.length;
+        callback();
+      } catch (error) {
+        callback(error as Error);
+      }
+    }
+
+    close(callback?: Fn): void {
+      this.end();
+      if (callback) this.once('close', callback);
+    }
+  }
+
+  class FSWatcher extends EventEmitterBase {
+    private readonly release: () => void;
+    private readonly unwatch: () => void;
+
+    constructor(path: string, recursive: boolean, listener?: Fn) {
+      super();
+      const root = normalizePath(path);
+      if (listener) this.on('change', listener);
+      this.release = ctx.hold();
+      this.unwatch = ctx.vfs.watch((change) => {
+        const p = change.path;
+        const inside = p === root || p.startsWith(root === '/' ? '/' : root + '/');
+        if (!inside) return;
+        const rel = p === root ? p.slice(p.lastIndexOf('/') + 1) : p.slice(root.length + (root === '/' ? 0 : 1));
+        if (!recursive && rel.includes('/')) return;
+        this.emit('change', change.type === 'write' && !change.created ? 'change' : 'rename', rel);
+      });
+    }
+
+    close(): void {
+      this.unwatch();
+      this.release();
+      this.emit('close');
+    }
+
+    ref(): this { return this; }
+    unref(): this { return this; }
+  }
+
+  const watch = (path: string | URL, options?: Fn | string | { recursive?: boolean }, listener?: Fn) => {
+    if (typeof options === 'function') [listener, options] = [options, undefined];
+    const resolved = sync._resolve(path);
+    if (!ctx.vfs.exists(resolved)) throw sync.statSync(resolved); // throws ENOENT
+    return new FSWatcher(resolved, typeof options === 'object' && !!options?.recursive, listener);
+  };
+
+  const fileWatchers = new Map<string, { watcher: FSWatcher; listeners: Fn[] }>();
+  const watchFile = (path: string, options: Fn | object, listener?: Fn) => {
+    const fn = (typeof options === 'function' ? options : listener)!;
+    const resolved = sync._resolve(path);
+    let entry = fileWatchers.get(resolved);
+    if (!entry) {
+      const watcher = new FSWatcher(resolved, false);
+      const current = { watcher, listeners: [] as Fn[] };
+      let previous = sync.statSync(resolved, { throwIfNoEntry: false }) ?? new Stats(resolved, 'file', 0, 0);
+      watcher.on('change', () => {
+        const next = sync.statSync(resolved, { throwIfNoEntry: false }) ?? new Stats(resolved, 'file', 0, 0);
+        for (const l of current.listeners) l(next, previous);
+        previous = next;
+      });
+      fileWatchers.set(resolved, (entry = current));
+    }
+    entry.listeners.push(fn as Fn);
+    return entry.watcher;
+  };
+  const unwatchFile = (path: string, listener?: Fn) => {
+    const resolved = sync._resolve(path);
+    const entry = fileWatchers.get(resolved);
+    if (!entry) return;
+    entry.listeners = listener ? entry.listeners.filter((l) => l !== listener) : [];
+    if (!entry.listeners.length) {
+      entry.watcher.close();
+      fileWatchers.delete(resolved);
+    }
+  };
+
+  const fs: Record<string, any> = { ...sync, constants, Stats, Dirent, ReadStream, WriteStream, FSWatcher, F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1 };
+  delete fs._resolve;
+
+  for (const name of Object.keys(sync)) {
+    if (!name.endsWith('Sync')) continue;
+    const base = name.slice(0, -4);
+    const fn = (sync as unknown as Record<string, Fn>)[name]!;
+    if (base === 'exists') fs.exists = (p: string, cb: Fn) => queueMicrotask(() => cb(sync.existsSync(p)));
+    else if (base === 'read') fs.read = toCallback(fn, (n, args) => [n, args[1]]);
+    else if (base === 'write') fs.write = toCallback(fn, (n, args) => [n, args[1]]);
+    else fs[base] = toCallback(fn);
+  }
+  fs.realpath.native = fs.realpath;
+  fs.createReadStream = (path: string, options?: object | string) => new ReadStream(path, options as object);
+  fs.createWriteStream = (path: string, options?: object | string) => new WriteStream(path, options as object);
+  fs.watch = watch;
+  fs.watchFile = watchFile;
+  fs.unwatchFile = unwatchFile;
+
+  const promises: Record<string, any> = { constants };
+  for (const name of Object.keys(sync)) {
+    if (!name.endsWith('Sync') || name === 'existsSync') continue;
+    promises[name.slice(0, -4)] = toPromise((sync as unknown as Record<string, Fn>)[name]!);
+  }
+  promises.open = async (path: string, flags?: string) => fileHandle(sync, sync.openSync(path, flags), sync._resolve(path));
+  promises.watch = (path: string, options?: { recursive?: boolean; signal?: AbortSignal }) => watchIterator(watch(path, options), options?.signal);
+  fs.promises = promises;
+  return fs;
+}
+
+function fileHandle(sync: SyncFs, fd: number, path: string) {
+  return {
+    fd,
+    readFile: async (options?: string | { encoding?: string }) => sync.readFileSync(fd, options),
+    writeFile: async (data: string | Uint8Array) => void sync.writeFileSync(path, data),
+    appendFile: async (data: string | Uint8Array) => void sync.appendFileSync(path, data),
+    read: async (buffer: Uint8Array, offset?: number, length?: number, position?: number | null) => ({ bytesRead: sync.readSync(fd, buffer, offset, length, position), buffer }),
+    write: async (data: string | Uint8Array, ...rest: any[]) => ({ bytesWritten: sync.writeSync(fd, data, ...rest), buffer: data }),
+    stat: async () => sync.fstatSync(fd),
+    truncate: async (length?: number) => sync.ftruncateSync(fd, length),
+    sync: async () => undefined,
+    datasync: async () => undefined,
+    chmod: async () => undefined,
+    close: async () => sync.closeSync(fd),
+  };
+}
+
+async function* watchIterator(watcher: { on(e: string, l: Fn): unknown; close(): void }, signal?: AbortSignal) {
+  const queue: Array<{ eventType: string; filename: string }> = [];
+  let wake: (() => void) | undefined;
+  watcher.on('change', (eventType: string, filename: string) => {
+    queue.push({ eventType, filename });
+    wake?.();
+  });
+  signal?.addEventListener('abort', () => wake?.());
+  try {
+    while (!signal?.aborted) {
+      if (queue.length) yield queue.shift()!;
+      else await new Promise<void>((resolve) => (wake = resolve));
+    }
+  } finally {
+    watcher.close();
+  }
+}
+

package/src/node/fs/stats.ts

@@ -0,0 +1,110 @@
+/**
+ * The value types of the fs module: Node-shaped errors (`code`, `errno`,
+ * `syscall`, `path` — callers branch on `code === 'ENOENT'`), `Stats`,
+ * `Dirent` and `fs.constants`.
+ */
+
+const ERRNO: Record<string, [number, string]> = {
+  ENOENT: [-2, 'no such file or directory'],
+  EEXIST: [-17, 'file already exists'],
+  EISDIR: [-21, 'illegal operation on a directory'],
+  ENOTDIR: [-20, 'not a directory'],
+  ENOTEMPTY: [-39, 'directory not empty'],
+  EBADF: [-9, 'bad file descriptor'],
+  EINVAL: [-22, 'invalid argument'],
+  EPERM: [-1, 'operation not permitted'],
+  EACCES: [-13, 'permission denied'],
+  ENOSYS: [-38, 'function not implemented'],
+};
+
+export interface FsError extends Error {
+  code: string;
+  errno: number;
+  syscall: string;
+  path?: string;
+  dest?: string;
+}
+
+export function fsError(code: keyof typeof ERRNO | string, syscall: string, path?: string, dest?: string): FsError {
+  const [errno, text] = ERRNO[code] ?? [-1, code.toLowerCase()];
+  const where = path === undefined ? '' : dest === undefined ? ` '${path}'` : ` '${path}' -> '${dest}'`;
+  const error = new Error(`${code}: ${text}, ${syscall}${where}`) as FsError;
+  error.code = code;
+  error.errno = errno;
+  error.syscall = syscall;
+  if (path !== undefined) error.path = path;
+  if (dest !== undefined) error.dest = dest;
+  return error;
+}
+
+function inode(path: string): number {
+  let hash = 5381;
+  for (let i = 0; i < path.length; i++) hash = ((hash * 33) ^ path.charCodeAt(i)) >>> 0;
+  return hash;
+}
+
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+
+export class Stats {
+  dev = 2049;
+  ino: number;
+  mode: number;
+  nlink = 1;
+  uid = 1000;
+  gid = 1000;
+  rdev = 0;
+  size: number;
+  blksize = 4096;
+  blocks: number;
+  atimeMs: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  birthtimeMs: number;
+  atime: Date;
+  mtime: Date;
+  ctime: Date;
+  birthtime: Date;
+
+  constructor(path: string, kind: 'file' | 'directory', size: number, mtimeMs: number) {
+    this.ino = inode(path);
+    this.mode = kind === 'file' ? S_IFREG | 0o644 : S_IFDIR | 0o755;
+    this.size = size;
+    this.blocks = Math.ceil(size / 512);
+    this.atimeMs = this.mtimeMs = this.ctimeMs = this.birthtimeMs = mtimeMs;
+    this.atime = new Date(mtimeMs);
+    this.mtime = new Date(mtimeMs);
+    this.ctime = new Date(mtimeMs);
+    this.birthtime = new Date(mtimeMs);
+  }
+
+  isFile(): boolean { return (this.mode & 0o170000) === S_IFREG; }
+  isDirectory(): boolean { return (this.mode & 0o170000) === S_IFDIR; }
+  isSymbolicLink(): boolean { return false; }
+  isBlockDevice(): boolean { return false; }
+  isCharacterDevice(): boolean { return false; }
+  isFIFO(): boolean { return false; }
+  isSocket(): boolean { return false; }
+}
+
+export class Dirent {
+  constructor(readonly name: string, readonly parentPath: string, private readonly kind: 'file' | 'directory') {}
+  get path(): string { return this.parentPath; }
+  isFile(): boolean { return this.kind === 'file'; }
+  isDirectory(): boolean { return this.kind === 'directory'; }
+  isSymbolicLink(): boolean { return false; }
+  isBlockDevice(): boolean { return false; }
+  isCharacterDevice(): boolean { return false; }
+  isFIFO(): boolean { return false; }
+  isSocket(): boolean { return false; }
+}
+
+export const constants = {
+  F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1,
+  O_RDONLY: 0, O_WRONLY: 1, O_RDWR: 2, O_CREAT: 64, O_EXCL: 128, O_NOCTTY: 256, O_TRUNC: 512, O_APPEND: 1024,
+  O_DIRECTORY: 65536, O_NOFOLLOW: 131072, O_SYNC: 1052672, O_DSYNC: 4096, O_NONBLOCK: 2048,
+  S_IFMT: 0o170000, S_IFREG, S_IFDIR, S_IFCHR: 0o020000, S_IFBLK: 0o060000, S_IFIFO: 0o010000, S_IFLNK: 0o120000, S_IFSOCK: 0o140000,
+  S_IRWXU: 0o700, S_IRUSR: 0o400, S_IWUSR: 0o200, S_IXUSR: 0o100,
+  COPYFILE_EXCL: 1, COPYFILE_FICLONE: 2, COPYFILE_FICLONE_FORCE: 4,
+  UV_FS_COPYFILE_EXCL: 1,
+};