@seanhogg/builderforce-webcontainers-core 2026.10.5 → 2026.10.7

package/src/installer/npmrc.ts

@@ -0,0 +1,69 @@
+/**
+ * `.npmrc`: the default registry, per-scope registries (`@acme:registry=…`) and
+ * auth tokens keyed by registry path (`//npm.acme.dev/:_authToken=${NPM_TOKEN}`).
+ * Project and user files are read like npm does — the project's wins — and
+ * `${VAR}` is filled from the process environment.
+ *
+ * A private registry is reached with the browser's `fetch`, so it must answer
+ * CORS requests that carry an `Authorization` header.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+
+export interface NpmConfig {
+  registry?: string;
+  /** `@scope` → registry URL. */
+  scopes: Record<string, string>;
+  /** `//host/path/` → bearer token. */
+  tokens: Record<string, string>;
+}
+
+export function emptyNpmConfig(): NpmConfig {
+  return { scopes: {}, tokens: {} };
+}
+
+const trimSlash = (url: string) => url.replace(/\/+$/, '');
+
+export function parseNpmrc(text: string, env: Record<string, string | undefined> = {}, into: NpmConfig = emptyNpmConfig()): NpmConfig {
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim().replace(/^(["'])(.*)\1$/, '$2').replace(/\$\{([^}]+)\}/g, (_m, name: string) => env[name] ?? '');
+    if (key === 'registry') into.registry = trimSlash(value);
+    else if (/^@[^:]+:registry$/.test(key)) into.scopes[key.slice(0, key.indexOf(':'))] = trimSlash(value);
+    else if (key.startsWith('//') && key.endsWith(':_authToken')) into.tokens[key.slice(0, -':_authToken'.length).replace(/\/?$/, '/')] = value;
+  }
+  return into;
+}
+
+/** Read `.npmrc` files, lowest precedence first (user, then project). Missing files are skipped. */
+export function readNpmConfig(fs: VirtualFileSystem, paths: string[], env: Record<string, string | undefined> = {}): NpmConfig {
+  const config = emptyNpmConfig();
+  for (const path of paths) {
+    const text = fs.readText(path);
+    if (text !== undefined) parseNpmrc(text, env, config);
+  }
+  return config;
+}
+
+/** The registry a package is fetched from: its scope's, else the default. */
+export function registryFor(config: NpmConfig | undefined, name: string, fallback: string): string {
+  if (name.startsWith('@')) {
+    const scoped = config?.scopes[name.slice(0, name.indexOf('/'))];
+    if (scoped) return scoped;
+  }
+  return fallback;
+}
+
+/** `Authorization` for a URL: the token whose registry path is the longest prefix of it. */
+export function authHeaders(config: NpmConfig | undefined, url: string): Record<string, string> {
+  if (!config) return {};
+  const target = url.replace(/^https?:/, '');
+  let best = '';
+  for (const prefix of Object.keys(config.tokens)) {
+    if ((target.startsWith(prefix) || target + '/' === prefix) && prefix.length > best.length) best = prefix;
+  }
+  return best ? { authorization: `Bearer ${config.tokens[best]}` } : {};
+}

package/src/installer/registry.ts

@@ -5,6 +5,8 @@
  * caller injects one, which is what keeps this testable against a fake registry.
  */
 
+import { authHeaders, registryFor, type NpmConfig } from './npmrc.js';
+
 export type FetchLike = (url: string, init?: { headers?: Record<string, string>; signal?: AbortSignal }) => Promise<{
   ok: boolean;
   status: number;
@@ -60,6 +62,8 @@ export interface RegistryOptions {
   fetch: FetchLike;
   registry?: string;
   cache?: PackageCache;
+  /** `.npmrc` settings: scoped registries and auth tokens. */
+  npmrc?: NpmConfig;
   /** How long a cached packument is trusted. Default 10 minutes. */
   packumentMaxAgeMs?: number;
   signal?: AbortSignal;
@@ -136,7 +140,8 @@ export class RegistryClient {
   }
 
   private async loadPackument(name: string): Promise<Packument> {
-    const key = `packument:${this.registry}/${name}`;
+    const registry = registryFor(this.options.npmrc, name, this.registry);
+    const key = `packument:${registry}/${name}`;
     const maxAge = this.options.packumentMaxAgeMs ?? 10 * 60_000;
     const cached = await this.options.cache?.get(key);
     if (cached) {
@@ -147,15 +152,16 @@ export class RegistryClient {
         // a corrupt entry is just a miss
       }
     }
-    const url = `${this.registry}/${name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name)}`;
-    const bytes = await this.get(url, { accept: ABBREVIATED }, name);
+    const url = `${registry}/${name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name)}`;
+    const bytes = await this.get(url, { accept: ABBREVIATED }, name, registry);
     const packument = JSON.parse(decoder.decode(bytes)) as Packument;
     if (!packument.versions) throw new Error(`The registry returned no versions for "${name}".`);
     await this.options.cache?.put(key, encoder.encode(JSON.stringify({ t: Date.now(), p: packument })));
     return packument;
   }
 
-  private async get(url: string, headers: Record<string, string>, packageName?: string): Promise<Uint8Array> {
+  private async get(url: string, headers: Record<string, string>, packageName?: string, registry = this.registry): Promise<Uint8Array> {
+    headers = { ...headers, ...authHeaders(this.options.npmrc, url) };
     let lastError: unknown;
     for (let attempt = 0; attempt < 2; attempt++) {
       let response: Awaited<ReturnType<FetchLike>>;
@@ -166,7 +172,8 @@ export class RegistryClient {
         lastError = error; // network blip: retry once
         continue;
       }
-      if (response.status === 404 && packageName) throw new Error(`Package "${packageName}" was not found in ${this.registry}.`);
+      if (response.status === 404 && packageName) throw new Error(`Package "${packageName}" was not found in ${registry}.`);
+      if ((response.status === 401 || response.status === 403) && packageName) throw new Error(`${registry} refused "${packageName}" (HTTP ${response.status}). Add an auth token to .npmrc.`);
       if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}.`);
       return new Uint8Array(await response.arrayBuffer());
     }

package/src/node/childProcess.ts

@@ -68,7 +68,7 @@ class ChildProcess extends EventEmitterBase {
 
     const env: Record<string, string> = {};
     for (const [k, v] of Object.entries(options.env ?? deps.env())) if (v !== undefined) env[k] = String(v);
-    const [file, argv] = options.shell ? ['jsh', ['-c', [command, ...args].join(' ')]] : [command, args];
+    const [file, argv] = options.shell ? ['bfsh', ['-c', [command, ...args].join(' ')]] : [command, args];
     const release = deps.loop.hold();
     try {
       this.handle = deps.system.spawn(file, argv, { cwd: options.cwd ?? deps.cwd(), env });

package/src/node/misc.ts

@@ -27,7 +27,7 @@ export function createOsModule(env: () => Record<string, string | undefined>): R
     hostname: () => 'localhost',
     homedir: () => env().HOME ?? '/home/user',
     tmpdir: () => env().TMPDIR ?? '/tmp',
-    userInfo: () => ({ uid: 1000, gid: 1000, username: env().USER ?? 'user', homedir: env().HOME ?? '/home/user', shell: '/bin/jsh' }),
+    userInfo: () => ({ uid: 1000, gid: 1000, username: env().USER ?? 'user', homedir: env().HOME ?? '/home/user', shell: '/bin/bfsh' }),
     cpus: () => cpus,
     availableParallelism: () => cpus.length,
     totalmem: () => 4 * 1024 ** 3,

package/src/shell/builtins.ts

@@ -31,9 +31,9 @@ export const COREUTILS: Record<string, Command> = {
 };
 
 /** Programs the runtime provides besides coreutils (reported by `which`/`type`). */
-export const SYSTEM_PROGRAMS = ['node', 'npm', 'npx', 'jsh', 'sh', 'bash'];
+export const SYSTEM_PROGRAMS = ['node', 'npm', 'npx', 'bfsh', 'sh', 'bash'];
 
-const HELP = `jsh — BuilderForce WebContainers shell
+const HELP = `bfsh — BuilderForce WebContainers shell
 
   Builtins:  cd, pwd, export, unset, exit, source, history, type, which, help
   Files:     ls [-la], cat, mkdir [-p], rm [-rf], cp [-r], mv, touch

package/src/shell/devHandoff.ts

@@ -3,7 +3,7 @@
  * dev` / `npm start` usually run) cannot run here as-is — Vite itself needs
  * esbuild's native binary — but the runtime already IS a Vite-style dev server:
  * the in-browser DevServer serving the preview. So these commands announce that
- * preview as their server (`server-ready`) and stay "running" until Ctrl-C,
+ * preview as their server (a listening announcement) and stay "running" until Ctrl-C,
  * which is exactly what a host waiting on `npm run dev` expects.
  */
 import type { CommandContext } from './context.js';

package/src/shell/exec.ts

@@ -73,7 +73,7 @@ export class Shell implements ShellState {
       script = parse(source);
     } catch (error) {
       if (!(error instanceof ShellSyntaxError)) throw error;
-      io.stderr(`jsh: ${error.message}\n`);
+      io.stderr(`bfsh: ${error.message}\n`);
       this.lastStatus = 2;
       return 2;
     }
@@ -176,7 +176,7 @@ export class Shell implements ShellState {
       if (redirect.op === '<') {
         const text = this.system.fs.readText(path);
         if (text === undefined) {
-          io.stderr(`jsh: ${target}: No such file or directory\n`);
+          io.stderr(`bfsh: ${target}: No such file or directory\n`);
           return 1;
         }
         const queue = new InputQueue();
@@ -186,7 +186,7 @@ export class Shell implements ShellState {
         continue;
       }
       if (this.system.fs.isDirectory(path)) {
-        io.stderr(`jsh: ${target}: Is a directory\n`);
+        io.stderr(`bfsh: ${target}: Is a directory\n`);
         return 1;
       }
       const append = redirect.op === '>>' || redirect.op === '2>>';
@@ -240,7 +240,7 @@ export class Shell implements ShellState {
       child = this.system.spawn(name, args, { cwd: this.cwd, env, terminal: size });
     } catch (error) {
       if ((error as { code?: string }).code !== 'ENOENT') throw error;
-      io.stderr(`jsh: command not found: ${name}\n`);
+      io.stderr(`bfsh: command not found: ${name}\n`);
       return 127;
     }
     child.onStdout(io.stdout);

package/src/shell/expand.ts

@@ -29,7 +29,7 @@ async function paramValue(seg: Extract<Segment, { kind: 'var' }>, ctx: ExpandCon
     case '@':
     case '*': value = ctx.positional.join(' '); break;
     case '!': value = ''; break;
-    case '0': value = 'jsh'; break;
+    case '0': value = 'bfsh'; break;
     default: value = /^\d$/.test(seg.name) ? ctx.positional[Number(seg.name) - 1] : ctx.get(seg.name);
   }
   if (!seg.op) return value ?? '';

package/src/shell/npm.ts

@@ -7,6 +7,7 @@
  */
 import { join } from '../paths.js';
 import { installPackages, type InstallOptions } from '../installer/install.js';
+import { readNpmConfig } from '../installer/npmrc.js';
 import type { PackageJson } from '../installer/spec.js';
 import { binDirectories, findExecutable } from '../system/commands.js';
 import { findPackageScope } from '../node/resolve.js';
@@ -34,10 +35,13 @@ async function install(ctx: CommandContext, options: Partial<InstallOptions>, di
   const started = performance.now();
   const progress = ctx.io.isTerminal;
   try {
+    // User file first, then the project's: later files win, as with npm.
+    const npmrc = readNpmConfig(ctx.fs, [join(ctx.env.HOME ?? '/home/user', '.npmrc'), join(dir, '.npmrc')], ctx.env);
     const result = await installPackages({
       fs: ctx.fs,
       fetch: (url, init) => ctx.system.fetch(url, init as RequestInit),
-      registry: ctx.env.npm_config_registry ?? ctx.system.registry,
+      registry: ctx.env.npm_config_registry ?? npmrc.registry ?? ctx.system.registry,
+      npmrc,
       cache: ctx.system.packageCache,
       cwd: dir,
       signal: ctx.signal,

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;