@seanhogg/builderforce-webcontainers-core 2026.10.1 → 2026.10.3

package/src/system/types.ts

@@ -0,0 +1,103 @@
+/**
+ * The contract between programs (node, the shell, npm, coreutils) and whatever
+ * hosts them. Programs only ever see these ports, so the same program code runs
+ * in-process under the core `Kernel` (Node tests) and one-per-Web-Worker in the
+ * browser runtime, where `spawn` and `listen` are relayed to the page.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import type { PackageCache } from '../installer/registry.js';
+
+export interface TerminalPort {
+  cols: number;
+  rows: number;
+  onResize(listener: (cols: number, rows: number) => void): () => void;
+  /** Raw mode: the program handles keystrokes itself (no line editing, no echo). */
+  setRawMode(raw: boolean): void;
+}
+
+export interface ProgramIO {
+  stdout(chunk: string | Uint8Array): void;
+  stderr(chunk: string | Uint8Array): void;
+  /** Stdin chunks as they arrive; `null` is end-of-file. Buffered until the first subscriber. */
+  onStdin(listener: (chunk: string | null) => void): () => void;
+  /** Present when attached to a terminal (xterm.js). */
+  terminal?: TerminalPort;
+}
+
+export interface SpawnOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Attach to a terminal of this size (`isTTY`, line discipline, `\r\n` output). */
+  terminal?: { cols: number; rows: number };
+}
+
+/** A child as its parent sees it (separate stdout/stderr, unlike the public API). */
+export interface ChildHandle {
+  readonly pid: number;
+  onStdout(listener: (chunk: string) => void): () => void;
+  onStderr(listener: (chunk: string) => void): () => void;
+  write(data: string): void;
+  closeStdin(): void;
+  kill(signal?: string): void;
+  resize?(cols: number, rows: number): void;
+  readonly exit: Promise<number>;
+}
+
+export interface HttpRequestData {
+  method: string;
+  /** Path and query, as the server sees it (`/api?x=1`). */
+  url: string;
+  headers: Record<string, string>;
+  body: Uint8Array | null;
+}
+
+export interface HttpResponseData {
+  status: number;
+  statusText?: string;
+  headers: Record<string, string | string[]>;
+  body: Uint8Array;
+}
+
+export type HttpHandler = (request: HttpRequestData) => Promise<HttpResponseData>;
+
+export interface System {
+  fs: VirtualFileSystem;
+  /** Outbound network (registry, `http.request`, `fetch`). */
+  fetch(input: string, init?: RequestInit): Promise<Response>;
+  spawn(command: string, args: string[], options?: SpawnOptions): ChildHandle;
+  /** Register a virtual server; throws `EADDRINUSE`. Port 0 picks a free one. Returns the port and an unlisten. */
+  listen(port: number, handler: HttpHandler): { port: number; close(): void };
+  /** Send a request to a virtual server in this runtime (`http.get('http://localhost:3000')`); undefined when nothing listens. */
+  loopback(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined>;
+  /** Where a browser reaches a server on `port` (the preview URL), if known. */
+  serverUrl(port: number): string | undefined;
+  /** Tell the host a server is ready (`server-ready`); used by the dev-server handoff. */
+  announceServer(port: number, url: string): void;
+  /** The in-browser dev server's preview URL, for `vite`/`react-scripts start` handoff. */
+  previewUrl?: string;
+  /**
+   * This program has the JS realm to itself (one process per Web Worker): node
+   * may install `process`, `Buffer`, timers on `globalThis`, and the host routes
+   * the realm's uncaught errors to it through `trapUncaught`.
+   */
+  ownsRealm?: boolean;
+  /** Register for the realm's uncaught errors and unhandled rejections. */
+  trapUncaught?(handler: (error: unknown) => void): () => void;
+  /** npm registry and cache for `npm install`. */
+  registry?: string;
+  packageCache?: PackageCache;
+}
+
+export interface ProgramContext {
+  /** Arguments after the program name. */
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  io: ProgramIO;
+  system: System;
+  /** Aborted by kill(): in-process programs stop at their next await. */
+  signal: AbortSignal;
+}
+
+/** A program resolves with its exit code. */
+export type Program = (ctx: ProgramContext) => Promise<number>;

package/src/vfs.ts

@@ -1,4 +1,4 @@
-import { normalizePath, join } from './paths.js';
+import { normalizePath, join, dirname } from './paths.js';
 
 export type FileContent = string | Uint8Array;
 
@@ -11,7 +11,8 @@ export interface FileSystemTree {
 export type FlatFiles = Record<string, FileContent>;
 
 export interface FsChange {
-  type: 'write' | 'remove';
+  /** `mkdir` is an explicitly created (possibly empty) directory. */
+  type: 'write' | 'remove' | 'mkdir';
   path: string;
   /** For a write: the file did not exist before. A new file can change how imports resolve. */
   created?: boolean;
@@ -20,9 +21,14 @@ export interface FsChange {
 const decoder = new TextDecoder();
 
 /**
- * An in-memory file system. Files only — a directory exists while it contains a
- * file, which keeps the store a single map and makes "is this a directory?" a
- * prefix check rather than a second structure to keep consistent.
+ * An in-memory file system. Files are the store; a directory exists while it
+ * contains something, or because it was created explicitly with `mkdir` (shells
+ * and Node programs create empty directories, a preview never needs to).
+ *
+ * A directory index (dir → child names) is maintained alongside the files, so
+ * `isDirectory`/`readdir` stay O(1)/O(children) even with a populated
+ * `node_modules` of tens of thousands of files — module resolution probes those
+ * constantly.
  *
  * Every write bumps a per-file version, so a transform cache can key on
  * (path, version) instead of hashing contents.
@@ -30,14 +36,22 @@ const decoder = new TextDecoder();
 export class VirtualFileSystem {
   private readonly files = new Map<string, FileContent>();
   private readonly versions = new Map<string, number>();
+  private readonly mtimes = new Map<string, number>();
+  /** dir → names of its direct children (files and directories). */
+  private readonly children = new Map<string, Set<string>>([['/', new Set()]]);
+  /** Directories created with `mkdir`: they outlive their last file. */
+  private readonly explicit = new Set<string>();
   private readonly listeners = new Set<(change: FsChange) => void>();
   private clock = 0;
 
   writeFile(path: string, contents: FileContent): void {
     const key = normalizePath(path);
+    if (key === '/' || this.children.has(key)) throw new Error(`EISDIR: illegal operation on a directory, open '${key}'`);
     const created = !this.files.has(key);
+    if (created) this.link(key);
     this.files.set(key, contents);
     this.versions.set(key, ++this.clock);
+    this.mtimes.set(key, Date.now());
     this.emit({ type: 'write', path: key, created });
   }
 
@@ -56,29 +70,28 @@ export class VirtualFileSystem {
   }
 
   isDirectory(path: string): boolean {
-    const key = normalizePath(path);
-    if (key === '/') return true;
-    const prefix = key + '/';
-    for (const file of this.files.keys()) if (file.startsWith(prefix)) return true;
-    return false;
+    return this.children.has(normalizePath(path));
   }
 
   exists(path: string): boolean {
     return this.isFile(path) || this.isDirectory(path);
   }
 
+  /** Create a directory (and its parents). A no-op when it already exists. */
+  mkdir(path: string): void {
+    const key = normalizePath(path);
+    if (this.files.has(key)) throw new Error(`EEXIST: file already exists, mkdir '${key}'`);
+    if (key === '/') return;
+    const existed = this.children.has(key);
+    this.explicit.add(key);
+    if (existed) return;
+    this.ensureDir(key);
+    this.emit({ type: 'mkdir', path: key });
+  }
+
   /** Direct children of a directory (files and sub-directories), sorted. */
   readdir(path: string): string[] {
-    const key = normalizePath(path);
-    const prefix = key === '/' ? '/' : key + '/';
-    const names = new Set<string>();
-    for (const file of this.files.keys()) {
-      if (!file.startsWith(prefix)) continue;
-      const rest = file.slice(prefix.length);
-      const name = rest.split('/')[0];
-      if (name) names.add(name);
-    }
-    return [...names].sort();
+    return [...(this.children.get(normalizePath(path)) ?? [])].sort();
   }
 
   /** Every file path, sorted. */
@@ -86,17 +99,24 @@ export class VirtualFileSystem {
     return [...this.files.keys()].sort();
   }
 
+  /** Directories created explicitly with `mkdir` — what `list()` cannot reproduce. */
+  explicitDirectories(): string[] {
+    return [...this.explicit].sort();
+  }
+
   /** Remove a file, or a directory and everything under it. */
   rm(path: string): void {
     const key = normalizePath(path);
-    const prefix = key === '/' ? '/' : key + '/';
-    for (const file of [...this.files.keys()]) {
-      if (file === key || file.startsWith(prefix)) {
-        this.files.delete(file);
-        this.versions.delete(file);
-        this.emit({ type: 'remove', path: file });
-      }
+    if (this.files.has(key)) {
+      this.removeFile(key);
+      return;
     }
+    if (!this.children.has(key)) return;
+    for (const name of [...(this.children.get(key) ?? [])]) this.rm(key === '/' ? '/' + name : `${key}/${name}`);
+    if (key === '/') return;
+    const wasExplicit = this.explicit.delete(key);
+    if (this.children.has(key)) this.unlinkDir(key);
+    if (wasExplicit) this.emit({ type: 'remove', path: key });
   }
 
   /** The file's version (bumped on every write), or undefined when absent. */
@@ -104,6 +124,11 @@ export class VirtualFileSystem {
     return this.versions.get(normalizePath(path));
   }
 
+  /** When the file was last written (epoch ms), or undefined when absent. */
+  mtime(path: string): number | undefined {
+    return this.mtimes.get(normalizePath(path));
+  }
+
   /**
    * Write many files at once. Takes either the nested WebContainer tree or a flat
    * path→contents map — or a mix, since each entry is judged on its own.
@@ -113,7 +138,10 @@ export class VirtualFileSystem {
       const path = join(at, name);
       if (typeof entry === 'string' || entry instanceof Uint8Array) this.writeFile(path, entry);
       else if ('file' in entry) this.writeFile(path, entry.file.contents);
-      else this.mount(entry.directory, path);
+      else {
+        this.mkdir(path);
+        this.mount(entry.directory, path);
+      }
     }
   }
 
@@ -129,6 +157,42 @@ export class VirtualFileSystem {
     return () => this.listeners.delete(listener);
   }
 
+  private removeFile(key: string): void {
+    this.files.delete(key);
+    this.versions.delete(key);
+    this.mtimes.delete(key);
+    this.unlink(key);
+    this.emit({ type: 'remove', path: key });
+  }
+
+  /** Register `key` under its parent, creating implicit ancestors as needed. */
+  private link(key: string): void {
+    const parent = dirname(key);
+    this.ensureDir(parent);
+    this.children.get(parent)!.add(key.slice(key.lastIndexOf('/') + 1));
+  }
+
+  private ensureDir(dir: string): void {
+    if (this.children.has(dir)) return;
+    if (this.files.has(dir)) throw new Error(`ENOTDIR: not a directory, '${dir}'`);
+    this.children.set(dir, new Set());
+    this.link(dir);
+  }
+
+  /** Detach `key` from its parent, pruning implicit ancestors left empty. */
+  private unlink(key: string): void {
+    const parent = dirname(key);
+    const siblings = this.children.get(parent);
+    if (!siblings) return;
+    siblings.delete(key.slice(key.lastIndexOf('/') + 1));
+    if (siblings.size === 0 && parent !== '/' && !this.explicit.has(parent)) this.unlinkDir(parent);
+  }
+
+  private unlinkDir(dir: string): void {
+    this.children.delete(dir);
+    this.unlink(dir);
+  }
+
   private emit(change: FsChange): void {
     for (const listener of this.listeners) listener(change);
   }

package/src/vueCompiler.ts

@@ -0,0 +1,121 @@
+import type { ComponentCompiler } from './components.js';
+import type { Loader } from './transformer.js';
+import { contentHash } from './hash.js';
+
+/**
+ * Vue single-file components through `@vue/compiler-sfc` — the same steps
+ * `@vitejs/plugin-vue` takes, minus HMR: script (with `<script setup>` and its
+ * template inlined), a separate render function for options-API components, and
+ * each `<style>` compiled with the component's scope id.
+ */
+
+interface VueBlock {
+  content: string;
+  lang?: string;
+}
+
+interface VueStyleBlock extends VueBlock {
+  scoped?: boolean;
+}
+
+export interface VueDescriptor {
+  script: VueBlock | null;
+  scriptSetup: VueBlock | null;
+  template: VueBlock | null;
+  styles: VueStyleBlock[];
+}
+
+type Problem = string | { message: string };
+/**
+ * The script's binding analysis, passed from compileScript to compileTemplate
+ * untouched. Opaque here (`any`) so the real compiler's precise type fits.
+ */
+type BindingMetadata = any;
+
+/** The subset of `@vue/compiler-sfc` used (its browser build has the same API). */
+export interface VueCompilerSfcLike {
+  parse(source: string, options: { filename: string; sourceMap: boolean }): { descriptor: VueDescriptor; errors: Problem[] };
+  compileScript(
+    descriptor: VueDescriptor,
+    options: { id: string; inlineTemplate: boolean; genDefaultAs: string; isProd: boolean; sourceMap: boolean },
+  ): { content: string; bindings?: BindingMetadata };
+  compileTemplate(options: {
+    source: string;
+    filename: string;
+    id: string;
+    scoped: boolean;
+    isProd: boolean;
+    compilerOptions: { bindingMetadata?: BindingMetadata; isTS?: boolean };
+  }): { code: string; errors: Problem[] };
+  compileStyle(options: { source: string; filename: string; id: string; scoped: boolean; isProd: boolean }): {
+    code: string;
+    errors: Problem[];
+  };
+}
+
+const SCRIPT_LOADERS: Record<string, Loader> = { js: 'js', jsx: 'jsx', ts: 'ts', tsx: 'tsx' };
+
+function fail(path: string, problems: Problem[]): never {
+  const first = problems[0];
+  throw new Error(`${path}: ${typeof first === 'string' ? first : first?.message ?? 'Vue compile error'}`);
+}
+
+export function createVueCompiler(sfc: VueCompilerSfcLike): ComponentCompiler {
+  return {
+    compile(source, { path, dev }) {
+      const { descriptor, errors } = sfc.parse(source, { filename: path, sourceMap: false });
+      if (errors.length) fail(path, errors);
+
+      for (const style of descriptor.styles) {
+        if (style.lang && style.lang !== 'css') {
+          throw new Error(`${path}: <style lang="${style.lang}"> needs a CSS preprocessor this runtime does not have yet.`);
+        }
+      }
+
+      // Stable per file, so the scope attribute does not change between reloads.
+      const id = contentHash(path);
+      const scoped = descriptor.styles.some((style) => style.scoped);
+      const lang = descriptor.scriptSetup?.lang ?? descriptor.script?.lang ?? 'js';
+      const loader = SCRIPT_LOADERS[lang];
+      if (!loader) throw new Error(`${path}: <script lang="${lang}"> is not supported.`);
+
+      const parts: string[] = [];
+      let bindings: BindingMetadata;
+      if (descriptor.script || descriptor.scriptSetup) {
+        const script = sfc.compileScript(descriptor, { id, inlineTemplate: true, genDefaultAs: '_sfc_main', isProd: !dev, sourceMap: false });
+        parts.push(script.content);
+        bindings = script.bindings;
+      } else {
+        parts.push('const _sfc_main = {};');
+      }
+
+      // `<script setup>` inlines its template; anything else needs a render function.
+      if (descriptor.template && !descriptor.scriptSetup) {
+        const template = sfc.compileTemplate({
+          source: descriptor.template.content,
+          filename: path,
+          id,
+          scoped,
+          isProd: !dev,
+          compilerOptions: { bindingMetadata: bindings, isTS: loader === 'ts' || loader === 'tsx' },
+        });
+        if (template.errors.length) fail(path, template.errors);
+        parts.push(template.code.replace(/\bexport (function|const) render\b/, '$1 _sfc_render'));
+        parts.push('_sfc_main.render = _sfc_render;');
+      }
+      if (scoped) parts.push(`_sfc_main.__scopeId = ${JSON.stringify(`data-v-${id}`)};`);
+      if (dev) parts.push(`_sfc_main.__file = ${JSON.stringify(path)};`);
+      parts.push('export default _sfc_main;');
+
+      const css = descriptor.styles
+        .map((style) => {
+          const out = sfc.compileStyle({ source: style.content, filename: path, id: `data-v-${id}`, scoped: !!style.scoped, isProd: !dev });
+          if (out.errors.length) fail(path, out.errors);
+          return out.code;
+        })
+        .join('\n');
+
+      return { code: parts.join('\n'), loader, css };
+    },
+  };
+}