@seanhogg/builderforce-webcontainers-core 2026.10.4 → 2026.10.6

package/src/shell/program.ts

@@ -1,5 +1,5 @@
 /**
- * The `jsh` program: `jsh -c "…"`, `jsh script.sh`, a script on stdin, or —
+ * The `bfsh` program: `bfsh -c "…"`, `bfsh script.sh`, a script on stdin, or —
  * attached to a terminal — the interactive shell. Interactively the shell owns
  * the keyboard (raw mode) while it edits a line, and hands it to the running
  * job otherwise: straight through to a terminal-attached child (which has its
@@ -22,7 +22,7 @@ function createShell(ctx: ProgramContext, positional: string[] = []): Shell {
   return new Shell({
     system: ctx.system,
     cwd: ctx.cwd,
-    env: { ...ctx.env, SHELL: '/bin/jsh' },
+    env: { ...ctx.env, SHELL: '/bin/bfsh' },
     positional,
     terminalSize: () => (ctx.io.terminal ? { cols: ctx.io.terminal.cols, rows: ctx.io.terminal.rows } : undefined),
     commands: SHELL_COMMANDS,
@@ -131,7 +131,7 @@ async function interactive(ctx: ProgramContext): Promise<number> {
     try {
       await shell.exec(line, io, current.input, controller.signal);
     } catch (error) {
-      ctx.io.stderr(`jsh: ${error instanceof Error ? error.message : String(error)}\n`);
+      ctx.io.stderr(`bfsh: ${error instanceof Error ? error.message : String(error)}\n`);
     }
     job = undefined;
     if (shell.exitRequested !== undefined) return finish(shell.exitRequested);
@@ -206,7 +206,7 @@ export const shellProgram: Program = async (ctx) => {
     const path = args[0].startsWith('/') ? args[0] : join(ctx.cwd, args[0]);
     const source = ctx.system.fs.readText(path);
     if (source === undefined) {
-      ctx.io.stderr(`jsh: ${args[0]}: No such file or directory\n`);
+      ctx.io.stderr(`bfsh: ${args[0]}: No such file or directory\n`);
       return 127;
     }
     return runOnce(ctx, createShell(ctx, args.slice(1)), source.replace(/^#!.*\n/, ''));

package/src/system/commands.ts

@@ -1,8 +1,8 @@
 /**
  * Command lookup, shared by the kernel, the browser host and the shell:
- * registered programs first (node, npm, jsh, coreutils), then a path or a
+ * registered programs first (node, npm, bfsh, coreutils), then a path or a
  * `PATH`/`node_modules/.bin` lookup. A found file runs under `node` (a `.bin`
- * shim runs its target directly) or, with a shell shebang, under `jsh`.
+ * shim runs its target directly) or, with a shell shebang, under `bfsh`.
  */
 import type { VirtualFileSystem } from '../vfs.js';
 import { dirname, extname, join, normalizePath } from '../paths.js';
@@ -10,7 +10,7 @@ import { readBinLink } from '../installer/bins.js';
 import type { Program } from './types.js';
 
 export interface ResolvedCommand {
-  /** The registered program that will run (`node`, `jsh`, `ls`…). */
+  /** The registered program that will run (`node`, `bfsh`, `ls`…). */
   name: string;
   program: Program;
   args: string[];
@@ -40,12 +40,12 @@ export function findExecutable(fs: VirtualFileSystem, command: string, cwd: stri
 }
 
 /** How to run a script file: its interpreter and arguments. */
-export function interpreterFor(fs: VirtualFileSystem, path: string): { name: 'node' | 'jsh'; args: string[] } {
+export function interpreterFor(fs: VirtualFileSystem, path: string): { name: 'node' | 'bfsh'; args: string[] } {
   const target = readBinLink(fs, path);
   if (target) return { name: 'node', args: [target] };
   const firstLine = (fs.readText(path) ?? '').split('\n', 1)[0] ?? '';
-  if (/^#!.*\b(?:sh|bash|jsh|zsh|dash)\b/.test(firstLine)) return { name: 'jsh', args: [path] };
-  if (['.sh', '.bash'].includes(extname(path))) return { name: 'jsh', args: [path] };
+  if (/^#!.*\b(?:sh|bash|bfsh|zsh|dash)\b/.test(firstLine)) return { name: 'bfsh', args: [path] };
+  if (['.sh', '.bash'].includes(extname(path))) return { name: 'bfsh', args: [path] };
   return { name: 'node', args: [path] };
 }
 

package/src/system/index.ts

@@ -1,10 +1,12 @@
 export { Kernel, DEFAULT_ENV } from './kernel.js';
-export type { KernelOptions, KernelSpawnOptions } from './kernel.js';
-export type { System, Program, ProgramContext, ProgramIO, TerminalPort, SpawnOptions, ChildHandle, HttpRequestData, HttpResponseData, HttpHandler } from './types.js';
+export type { KernelOptions } from './kernel.js';
+export type { System, Program, ProgramContext, ProgramIO, TerminalPort, ProcessOptions, ChildHandle, HttpRequestData, HttpResponseData, HttpHandler } from './types.js';
 export { PortRegistry, parsePortPath } from './ports.js';
 export type { PortEvent } from './ports.js';
-export { runProgram, toWebContainerProcess, allocatePid } from './process.js';
-export type { WebContainerProcess, RunProgramOptions } from './process.js';
+export { runProgram, runArguments, toRuntimeProcess, allocatePid } from './process.js';
+export type { RuntimeProcess, RunProgramOptions } from './process.js';
+export { ServerEvents } from './serverEvents.js';
+export type { ServerAddress, PortChange } from './serverEvents.js';
 export { resolveCommand, findExecutable, binDirectories, interpreterFor, commandNotFound } from './commands.js';
 export type { ResolvedCommand } from './commands.js';
 export { InputQueue, LineDiscipline, toTerminal } from './terminal.js';

package/src/system/kernel.ts

@@ -7,10 +7,11 @@
  */
 import { VirtualFileSystem } from '../vfs.js';
 import type { PackageCache } from '../installer/registry.js';
-import type { ChildHandle, HttpRequestData, HttpResponseData, Program, SpawnOptions, System } from './types.js';
+import type { ChildHandle, HttpRequestData, HttpResponseData, Program, ProcessOptions, System } from './types.js';
 import { PortRegistry } from './ports.js';
+import { ServerEvents } from './serverEvents.js';
 import { commandNotFound, resolveCommand } from './commands.js';
-import { runProgram, toWebContainerProcess, type WebContainerProcess } from './process.js';
+import { runArguments, runProgram, toRuntimeProcess, type RuntimeProcess } from './process.js';
 
 export interface KernelOptions {
   fs?: VirtualFileSystem;
@@ -26,19 +27,11 @@ export interface KernelOptions {
   packageCache?: PackageCache;
 }
 
-export interface KernelSpawnOptions extends SpawnOptions {
-  /** Kept for `@webcontainer/api` parity; output is always delivered. */
-  output?: boolean;
-}
-
-type ServerReadyListener = (port: number, url: string) => void;
-type PortListener = (port: number, type: 'open' | 'close', url: string) => void;
-
 export const DEFAULT_ENV: Record<string, string> = {
   PATH: '/usr/local/bin:/usr/bin:/bin',
   HOME: '/home/user',
   USER: 'user',
-  SHELL: '/bin/jsh',
+  SHELL: '/bin/bfsh',
   TERM: 'xterm-256color',
   COLORTERM: 'truecolor',
   LANG: 'en_US.UTF-8',
@@ -48,20 +41,16 @@ export const DEFAULT_ENV: Record<string, string> = {
 export class Kernel {
   readonly fs: VirtualFileSystem;
   readonly ports = new PortRegistry();
+  /** Servers listening, ports opening and closing. */
+  readonly servers = new ServerEvents();
   readonly env: Record<string, string>;
-  private readonly serverReady = new Set<ServerReadyListener>();
-  private readonly portListeners = new Set<PortListener>();
   private readonly system: System;
 
   constructor(private readonly options: KernelOptions) {
     this.fs = options.fs ?? new VirtualFileSystem();
     this.env = { ...DEFAULT_ENV, ...options.env };
     const serverUrl = (port: number) => options.serverUrl?.(port) ?? `http://localhost:${port}/`;
-    this.ports.watch(({ type, port }) => {
-      const url = serverUrl(port);
-      for (const l of this.portListeners) l(port, type, url);
-      if (type === 'open') for (const l of this.serverReady) l(port, url);
-    });
+    this.ports.watch(({ type, port }) => this.servers.portChanged({ type, port, url: serverUrl(port) }));
     this.system = {
       fs: this.fs,
       fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
@@ -69,21 +58,23 @@ export class Kernel {
       listen: (port, handler) => this.ports.listen(port, handler),
       loopback: (port, request) => this.ports.request(port, request),
       serverUrl,
-      announceServer: (port, url) => this.serverReady.forEach((l) => l(port, url)),
+      announceServer: (port, url) => this.servers.announce({ port, url }),
       previewUrl: options.previewUrl,
       registry: options.registry,
       packageCache: options.packageCache,
     };
   }
 
-  /** Same shape as `WebContainer#spawn`. */
-  spawn(command: string, args: string[] | KernelSpawnOptions = [], options: KernelSpawnOptions = {}): WebContainerProcess {
-    if (!Array.isArray(args)) [options, args] = [args, []];
-    return toWebContainerProcess(this.spawnChild(command, args, options), !!options.terminal);
+  /** Start a command — `run('npm', ['install'])`, `run('bfsh', { terminal })` — as a stream-based {@link RuntimeProcess}. */
+  run(command: string, args?: string[], options?: ProcessOptions): RuntimeProcess;
+  run(command: string, options?: ProcessOptions): RuntimeProcess;
+  run(command: string, argsOrOptions?: string[] | ProcessOptions, maybeOptions?: ProcessOptions): RuntimeProcess {
+    const [args, options] = runArguments(argsOrOptions, maybeOptions);
+    return toRuntimeProcess(this.spawnChild(command, args, options), !!options.terminal);
   }
 
   /** A child as a program's parent sees it — what `System.spawn` returns. */
-  spawnChild(command: string, args: string[] = [], options: SpawnOptions = {}): ChildHandle {
+  spawnChild(command: string, args: string[] = [], options: ProcessOptions = {}): ChildHandle {
     const cwd = options.cwd ?? '/';
     const env = { ...this.env, ...options.env };
     const resolved = resolveCommand(this.fs, this.options.programs, command, args, cwd, env);
@@ -95,12 +86,4 @@ export class Kernel {
   request(port: number, request: Partial<HttpRequestData> & { url: string }): Promise<HttpResponseData | undefined> {
     return this.ports.request(port, { method: 'GET', headers: {}, body: null, ...request });
   }
-
-  on(event: 'server-ready', listener: ServerReadyListener): () => void;
-  on(event: 'port', listener: PortListener): () => void;
-  on(event: 'server-ready' | 'port', listener: ServerReadyListener | PortListener): () => void {
-    const set = (event === 'server-ready' ? this.serverReady : this.portListeners) as Set<typeof listener>;
-    set.add(listener);
-    return () => set.delete(listener);
-  }
 }

package/src/system/process.ts

@@ -2,10 +2,10 @@
  * Running one program in-process: its stdin queue, TTY line discipline,
  * output listeners and kill signal, packaged as a {@link ChildHandle}. The core
  * kernel uses it for every process; the browser worker uses it for the one
- * program it hosts. Also the WebContainer-shaped wrapper (`output`/`input`
- * streams) that public `spawn` returns.
+ * program it hosts. Also {@link RuntimeProcess}, the stream-based handle the
+ * public `run()` returns.
  */
-import type { ChildHandle, Program, ProgramIO, SpawnOptions, System } from './types.js';
+import type { ChildHandle, Program, ProgramIO, ProcessOptions, System } from './types.js';
 import { InputQueue, LineDiscipline, toTerminal } from './terminal.js';
 
 let nextPid = 1000;
@@ -14,7 +14,7 @@ export function allocatePid(): number {
   return nextPid++;
 }
 
-export interface RunProgramOptions extends SpawnOptions {
+export interface RunProgramOptions extends ProcessOptions {
   program: Program;
   args: string[];
   system: System;
@@ -122,18 +122,28 @@ export function runProgram(options: RunProgramOptions): ChildHandle {
   };
 }
 
-/** The public process shape, deliberately the same as `@webcontainer/api`'s `WebContainerProcess`. */
-export interface WebContainerProcess {
+/** A running process as a host page sees it: streams for xterm.js or a log, and its exit code. */
+export interface RuntimeProcess {
+  readonly pid: number;
   /** stdout and stderr, interleaved as written (`\r\n` line endings when attached to a terminal). */
-  readonly output: ReadableStream<string>;
-  readonly input: WritableStream<string>;
-  readonly exit: Promise<number>;
+  readonly combinedOutput: ReadableStream<string>;
+  /** Keystrokes or piped input; closing it is end-of-file. */
+  readonly stdin: WritableStream<string>;
+  /** Resolves with the exit code (128 + signal number when killed). */
+  wait(): Promise<number>;
+  /** Default `SIGTERM`; `SIGKILL` cannot be caught. */
   kill(signal?: string): void;
-  resize(dimensions: { cols: number; rows: number } | number, rows?: number): void;
+  /** Resize the attached terminal. A no-op for a process started without one. */
+  resizeTerminal(cols: number, rows: number): void;
 }
 
-export function toWebContainerProcess(child: ChildHandle, terminal: boolean): WebContainerProcess {
-  const output = new ReadableStream<string>({
+/** `run(command, args?, options?)` and `run(command, options)` — the same call either way. */
+export function runArguments(args: string[] | ProcessOptions = [], options: ProcessOptions = {}): [string[], ProcessOptions] {
+  return Array.isArray(args) ? [args, options] : [[], args];
+}
+
+export function toRuntimeProcess(child: ChildHandle, terminal: boolean): RuntimeProcess {
+  const combinedOutput = new ReadableStream<string>({
     start(controller) {
       const push = (chunk: string) => controller.enqueue(terminal ? toTerminal(chunk) : chunk);
       child.onStdout(push);
@@ -141,18 +151,16 @@ export function toWebContainerProcess(child: ChildHandle, terminal: boolean): We
       void child.exit.then(() => controller.close());
     },
   });
-  const input = new WritableStream<string>({
+  const stdin = new WritableStream<string>({
     write: (chunk) => child.write(chunk),
     close: () => child.closeStdin(),
   });
   return {
-    output,
-    input,
-    exit: child.exit,
+    pid: child.pid,
+    combinedOutput,
+    stdin,
+    wait: () => child.exit,
     kill: (signal) => child.kill(signal),
-    resize(dimensions, rows) {
-      const size = typeof dimensions === 'number' ? { cols: dimensions, rows: rows ?? 24 } : dimensions;
-      child.resize?.(size.cols, size.rows);
-    },
+    resizeTerminal: (cols, rows) => child.resize?.(cols, rows),
   };
 }

package/src/system/programs.ts

@@ -20,7 +20,7 @@ function viaShell(command: string): Program {
 export function defaultPrograms(): Record<string, Program> {
   const programs: Record<string, Program> = {
     node: nodeProgram,
-    jsh: shellProgram,
+    bfsh: shellProgram,
     sh: shellProgram,
     bash: shellProgram,
     npm: viaShell('npm'),

package/src/system/serverEvents.ts

@@ -0,0 +1,44 @@
+/**
+ * Who hears about servers in a runtime: a port opening or closing, and a
+ * server becoming reachable (which a dev-server handoff announces without
+ * opening a port). One instance per runtime — the core `Kernel` and the
+ * browser's process host both own one, so the listener contract is the same.
+ */
+
+export interface ServerAddress {
+  port: number;
+  /** Where a browser reaches it (the preview URL for that port). */
+  url: string;
+}
+
+export interface PortChange extends ServerAddress {
+  type: 'open' | 'close';
+}
+
+export class ServerEvents {
+  private readonly listening = new Set<(server: ServerAddress) => void>();
+  private readonly changes = new Set<(change: PortChange) => void>();
+
+  /** A server started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+  onListening(listener: (server: ServerAddress) => void): () => void {
+    this.listening.add(listener);
+    return () => this.listening.delete(listener);
+  }
+
+  /** A virtual server opened or closed its port. */
+  onPortChange(listener: (change: PortChange) => void): () => void {
+    this.changes.add(listener);
+    return () => this.changes.delete(listener);
+  }
+
+  /** Report a port table change; an opened port is also a server listening. */
+  portChanged(change: PortChange): void {
+    for (const listener of this.changes) listener(change);
+    if (change.type === 'open') this.announce({ port: change.port, url: change.url });
+  }
+
+  /** Report a reachable server that did not open a port of its own. */
+  announce(server: ServerAddress): void {
+    for (const listener of this.listening) listener(server);
+  }
+}

package/src/system/types.ts

@@ -24,14 +24,14 @@ export interface ProgramIO {
   terminal?: TerminalPort;
 }
 
-export interface SpawnOptions {
+export interface ProcessOptions {
   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). */
+/** A child as its parent sees it (separate stdout/stderr listeners, unlike the streams of the public `RuntimeProcess`). */
 export interface ChildHandle {
   readonly pid: number;
   onStdout(listener: (chunk: string) => void): () => void;
@@ -64,14 +64,14 @@ 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;
+  spawn(command: string, args: string[], options?: ProcessOptions): 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. */
+  /** Tell the host a server is reachable without opening a port; 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;

package/src/vfs.ts

@@ -2,14 +2,18 @@ import { normalizePath, join, dirname } from './paths.js';
 
 export type FileContent = string | Uint8Array;
 
-/** The nested tree shape `@webcontainer/api`'s `mount()` takes — accepted as-is. */
-export interface FileSystemTree {
-  [name: string]: { file: { contents: FileContent } } | { directory: FileSystemTree };
-}
-
-/** A flat `{ 'src/main.tsx': '...' }` map, the other shape callers commonly hold. */
+/** A flat `{ 'src/main.tsx': '...' }` map: path → contents. */
 export type FlatFiles = Record<string, FileContent>;
 
+/**
+ * Files to write: a name maps to contents (a file) or to another tree (a
+ * directory). Names may hold slashes, so a {@link FlatFiles} map is a tree too,
+ * and the two styles mix freely: `{ src: { 'main.tsx': '…' }, 'public/a.svg': '…' }`.
+ */
+export interface FileTree {
+  [name: string]: FileContent | FileTree;
+}
+
 export interface FsChange {
   /** `mkdir` is an explicitly created (possibly empty) directory. */
   type: 'write' | 'remove' | 'mkdir';
@@ -129,18 +133,14 @@ export class VirtualFileSystem {
     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.
-   */
-  mount(files: FileSystemTree | FlatFiles, at = '/'): void {
+  /** Write many files at once, under `at` (default `/`). A nested object is a directory, created even when empty. */
+  writeTree(files: FileTree, at = '/'): void {
     for (const [name, entry] of Object.entries(files)) {
       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.mkdir(path);
-        this.mount(entry.directory, path);
+        this.writeTree(entry, path);
       }
     }
   }