@seanhogg/builderforce-webcontainers-core 2026.10.6 → 2026.10.8

package/src/system/ports.ts

@@ -4,7 +4,8 @@
  * in one process is reachable from another (`fetch('http://localhost:3000')`)
  * and from the preview service worker (`/__bfwc/<id>/__port/3000/`).
  */
-import type { HttpHandler, HttpRequestData, HttpResponseData } from './types.js';
+import type { ByteChannel, HttpHandler, HttpRequestData, HttpResponseData, HttpStreamResponse, UpgradeHandler } from './types.js';
+import { bufferResponse, createChannelPair } from './httpStream.js';
 
 export interface PortEvent {
   type: 'open' | 'close';
@@ -15,10 +16,11 @@ const EPHEMERAL_START = 49152;
 
 export class PortRegistry {
   private readonly handlers = new Map<number, HttpHandler>();
+  private readonly upgrades = new Map<number, UpgradeHandler>();
   private readonly listeners = new Set<(event: PortEvent) => void>();
   private nextEphemeral = EPHEMERAL_START;
 
-  listen(port: number, handler: HttpHandler): { port: number; close(): void } {
+  listen(port: number, handler: HttpHandler, upgrade?: UpgradeHandler): { port: number; close(): void } {
     let actual = port;
     if (!actual) {
       while (this.handlers.has(this.nextEphemeral)) this.nextEphemeral++;
@@ -28,6 +30,7 @@ export class PortRegistry {
       throw Object.assign(new Error(`listen EADDRINUSE: address already in use :::${actual}`), { code: 'EADDRINUSE', errno: -98, syscall: 'listen', address: '::', port: actual });
     }
     this.handlers.set(actual, handler);
+    if (upgrade) this.upgrades.set(actual, upgrade);
     this.emit({ type: 'open', port: actual });
     let open = true;
     return {
@@ -36,6 +39,7 @@ export class PortRegistry {
         if (!open || this.handlers.get(actual) !== handler) return;
         open = false;
         this.handlers.delete(actual);
+        this.upgrades.delete(actual);
         this.emit({ type: 'close', port: actual });
       },
     };
@@ -49,12 +53,27 @@ export class PortRegistry {
     return [...this.handlers.keys()].sort((a, b) => a - b);
   }
 
-  /** Dispatch to the server on `port`; undefined when nothing listens there. */
-  async request(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
+  /** Dispatch to the server on `port`; resolves with the head as soon as it is written, the body streaming. Undefined when nothing listens there. */
+  async request(port: number, request: HttpRequestData): Promise<HttpStreamResponse | undefined> {
     const handler = this.handlers.get(port);
     return handler ? handler(request) : undefined;
   }
 
+  /** {@link request}, waiting for the whole body. */
+  async requestBuffered(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
+    const response = await this.request(port, request);
+    return response && bufferResponse(response);
+  }
+
+  /** Open an upgraded connection to the server on `port`; returns the client end, or undefined when nothing there takes upgrades. */
+  upgrade(port: number, request: HttpRequestData): ByteChannel | undefined {
+    const upgrade = this.upgrades.get(port);
+    if (!upgrade) return undefined;
+    const [client, server] = createChannelPair();
+    upgrade(request, server);
+    return client;
+  }
+
   watch(listener: (event: PortEvent) => void): () => void {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);

package/src/system/programs.ts

@@ -2,7 +2,7 @@
  * The command table: every program a process can be. Hosts start from
  * `defaultPrograms()` and may add or replace entries (a custom `git`, say).
  *
- * `npm`/`npx` live in the shell (they run scripts through it), so spawning them
+ * `npm`/`npx`/`pnpm`/`yarn` live in the shell (they run scripts through it), so spawning them
  * directly runs them through a one-shot shell; coreutils run standalone.
  */
 import type { Program } from './types.js';
@@ -25,6 +25,8 @@ export function defaultPrograms(): Record<string, Program> {
     bash: shellProgram,
     npm: viaShell('npm'),
     npx: viaShell('npx'),
+    pnpm: viaShell('pnpm'),
+    yarn: viaShell('yarn'),
   };
   for (const [name, command] of Object.entries(COREUTILS)) programs[name] = asProgram(command, name);
   return programs;

package/src/system/types.ts

@@ -51,24 +51,58 @@ export interface HttpRequestData {
   body: Uint8Array | null;
 }
 
-export interface HttpResponseData {
+export interface HttpResponseHead {
   status: number;
   statusText?: string;
   headers: Record<string, string | string[]>;
+}
+
+/** A whole response, body buffered (`Kernel.request`, tests). */
+export interface HttpResponseData extends HttpResponseHead {
   body: Uint8Array;
 }
 
-export type HttpHandler = (request: HttpRequestData) => Promise<HttpResponseData>;
+/**
+ * A response as the server produces it: the head as soon as it is written, then
+ * the body chunk by chunk (Server-Sent Events, chunked progress). Cancelling the
+ * body hangs up, which the server sees as the client closing the connection.
+ */
+export interface HttpStreamResponse extends HttpResponseHead {
+  body: ReadableStream<Uint8Array>;
+}
+
+export type HttpHandler = (request: HttpRequestData) => Promise<HttpStreamResponse>;
+
+/**
+ * One end of a raw byte pipe — an upgraded connection. The server end carries
+ * whatever the server writes (a WebSocket server writes its `101` reply and then
+ * frames), so packages like `ws` run their own framing over it unchanged.
+ */
+export interface ByteChannel {
+  send(data: Uint8Array): void;
+  /** Hang up; the other end hears `onClose`. */
+  close(): void;
+  onData(listener: (data: Uint8Array) => void): () => void;
+  /** The other end hung up. */
+  onClose(listener: () => void): () => void;
+  readonly closed: boolean;
+}
+
+/** Take over a connection a client asked to upgrade (`Upgrade: websocket`); `socket` is the server end. */
+export type UpgradeHandler = (request: HttpRequestData, socket: ByteChannel) => void;
 
 export interface System {
   fs: VirtualFileSystem;
   /** Outbound network (registry, `http.request`, `fetch`). */
   fetch(input: string, init?: RequestInit): Promise<Response>;
   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>;
+  /**
+   * Register a virtual server; throws `EADDRINUSE`. Port 0 picks a free one.
+   * `upgrade` takes over connections that ask to upgrade (WebSockets). Returns the port and an unlisten.
+   */
+  listen(port: number, handler: HttpHandler, upgrade?: UpgradeHandler): { port: number; close(): void };
+  /** Send a request to a virtual server in this runtime (`http.get('http://localhost:3000')`); undefined when nothing listens. The body streams. */
+  loopback(port: number, request: HttpRequestData): Promise<HttpStreamResponse | 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 reachable without opening a port; used by the dev-server handoff. */

package/src/system/webSocketClient.ts

@@ -0,0 +1,177 @@
+/**
+ * The client end of a WebSocket to a virtual server, over an upgraded
+ * {@link ByteChannel}: sends the opening handshake as an HTTP request, checks
+ * the server's `101` reply (whatever wrote it — `ws`, socket.io's engine, a
+ * hand-written `upgrade` handler), then speaks RFC 6455 frames. The host page
+ * uses it to carry a preview's `new WebSocket('ws://localhost:3000')`.
+ */
+import type { ByteChannel, HttpRequestData } from './types.js';
+import { FrameDecoder, Opcode, decodeClosePayload, encodeClosePayload, encodeFrame, webSocketAccept, webSocketKey } from './webSocketFrames.js';
+
+export interface WebSocketCloseInfo {
+  code: number;
+  reason: string;
+  wasClean: boolean;
+}
+
+export interface WebSocketConnection {
+  /** 0 connecting, 1 open, 2 closing, 3 closed — `WebSocket.readyState`'s values. */
+  readonly readyState: number;
+  onOpen(listener: (info: { protocol: string }) => void): () => void;
+  onMessage(listener: (data: string | Uint8Array) => void): () => void;
+  /** Fires once; `wasClean` false and code 1006 when the connection dropped or the handshake failed. */
+  onClose(listener: (info: WebSocketCloseInfo) => void): () => void;
+  send(data: string | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+}
+
+export interface WebSocketConnectOptions {
+  /** Path and query on the server (`/socket?room=1`). */
+  path: string;
+  protocols?: string[];
+  /** Extra request headers (`origin`, `cookie`). */
+  headers?: Record<string, string>;
+  /** Give up on a close handshake the server never answers. Default 5000ms. */
+  closeTimeoutMs?: number;
+}
+
+const HEAD_END = [13, 10, 13, 10];
+
+function indexOfHeadEnd(bytes: Uint8Array): number {
+  outer: for (let i = 0; i + 3 < bytes.length; i++) {
+    for (let j = 0; j < 4; j++) if (bytes[i + j] !== HEAD_END[j]) continue outer;
+    return i;
+  }
+  return -1;
+}
+
+function parseHead(text: string): { status: number; headers: Record<string, string> } {
+  const [statusLine = '', ...lines] = text.split('\r\n');
+  const headers: Record<string, string> = {};
+  for (const line of lines) {
+    const colon = line.indexOf(':');
+    if (colon > 0) headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+  }
+  return { status: Number(/^HTTP\/\d(?:\.\d)?\s+(\d{3})/.exec(statusLine)?.[1] ?? 0), headers };
+}
+
+/** Open a WebSocket through `upgrade` (`kernel.upgrade` / `processHost.upgrade` bound to a port). */
+export function connectWebSocket(upgrade: (request: HttpRequestData) => ByteChannel | undefined, options: WebSocketConnectOptions): WebSocketConnection {
+  const opens = new Set<(info: { protocol: string }) => void>();
+  const messages = new Set<(data: string | Uint8Array) => void>();
+  const closes = new Set<(info: WebSocketCloseInfo) => void>();
+  const key = webSocketKey();
+  const decoder = new FrameDecoder();
+  let state = 0;
+  let head: Uint8Array = new Uint8Array(0);
+  let fragments: Uint8Array[] = [];
+  let fragmentOpcode = 0;
+  let closeSent = false;
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const headers: Record<string, string> = {
+    ...options.headers,
+    connection: 'Upgrade',
+    upgrade: 'websocket',
+    'sec-websocket-version': '13',
+    'sec-websocket-key': key,
+  };
+  if (options.protocols?.length) headers['sec-websocket-protocol'] = options.protocols.join(', ');
+  const channel = upgrade({ method: 'GET', url: options.path, headers, body: null });
+
+  const finish = (info: WebSocketCloseInfo) => {
+    if (state === 3) return;
+    state = 3;
+    clearTimeout(closeTimer);
+    channel?.close();
+    for (const listener of closes) listener(info);
+  };
+  const fail = () => finish({ code: 1006, reason: '', wasClean: false });
+  const sendFrame = (opcode: number, payload: Uint8Array) => channel?.send(encodeFrame(opcode, payload, { mask: true }));
+
+  const onFrame = (opcode: number, fin: boolean, payload: Uint8Array) => {
+    if (opcode === Opcode.ping) return sendFrame(Opcode.pong, payload);
+    if (opcode === Opcode.pong) return;
+    if (opcode === Opcode.close) {
+      const { code, reason } = decodeClosePayload(payload);
+      if (!closeSent) {
+        closeSent = true;
+        sendFrame(Opcode.close, code === 1005 ? new Uint8Array() : encodeClosePayload(code));
+      }
+      return finish({ code, reason, wasClean: true });
+    }
+    if (opcode !== Opcode.continuation) {
+      fragmentOpcode = opcode;
+      fragments = [];
+    }
+    fragments.push(payload);
+    if (!fin) return;
+    const whole = fragments.length === 1 ? fragments[0]! : joinChunks(fragments);
+    fragments = [];
+    const data = fragmentOpcode === Opcode.text ? new TextDecoder().decode(whole) : whole;
+    for (const listener of messages) listener(data);
+  };
+
+  const onBytes = (bytes: Uint8Array) => {
+    if (state === 3) return;
+    let rest = bytes;
+    if (state === 0) {
+      head = joinChunks([head, bytes]);
+      const end = indexOfHeadEnd(head);
+      if (end < 0) return;
+      const reply = parseHead(new TextDecoder().decode(head.subarray(0, end)));
+      rest = head.subarray(end + 4);
+      if (reply.status !== 101 || reply.headers['sec-websocket-accept'] !== webSocketAccept(key)) return fail();
+      state = 1;
+      const protocol = reply.headers['sec-websocket-protocol'] ?? '';
+      for (const listener of opens) listener({ protocol });
+    }
+    for (const frame of decoder.push(rest)) {
+      onFrame(frame.opcode, frame.fin, frame.payload);
+      if (state === 3) return;
+    }
+  };
+
+  if (!channel) queueMicrotask(fail);
+  else {
+    channel.onData(onBytes);
+    channel.onClose(fail);
+  }
+
+  return {
+    get readyState() {
+      return state;
+    },
+    onOpen: (listener) => subscribe(opens, listener),
+    onMessage: (listener) => subscribe(messages, listener),
+    onClose: (listener) => subscribe(closes, listener),
+    send(data) {
+      if (state !== 1) return;
+      if (typeof data === 'string') sendFrame(Opcode.text, new TextEncoder().encode(data));
+      else sendFrame(Opcode.binary, data);
+    },
+    close(code, reason) {
+      if (state === 0) return fail();
+      if (state !== 1) return;
+      state = 2;
+      closeSent = true;
+      sendFrame(Opcode.close, encodeClosePayload(code ?? 1000, reason));
+      closeTimer = setTimeout(fail, options.closeTimeoutMs ?? 5000);
+    },
+  };
+}
+
+function subscribe<T>(set: Set<T>, listener: T): () => void {
+  set.add(listener);
+  return () => set.delete(listener);
+}
+
+function joinChunks(chunks: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0));
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}

package/src/system/webSocketFrames.ts

@@ -0,0 +1,118 @@
+/**
+ * The WebSocket wire format (RFC 6455): the opening handshake's accept key and
+ * frame encoding/decoding. Runtime-agnostic, so the same codec drives the
+ * client end in the host page (bridging a preview's `WebSocket`) and tests that
+ * speak to a server's `upgrade` handler byte for byte.
+ */
+import { hashAlgorithm } from '../node/hashes.js';
+
+export const WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+export const Opcode = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa } as const;
+
+export interface WebSocketFrame {
+  fin: boolean;
+  opcode: number;
+  /** Unmasked. */
+  payload: Uint8Array;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
+  return btoa(binary);
+}
+
+/** `Sec-WebSocket-Accept` for a client's `Sec-WebSocket-Key`. */
+export function webSocketAccept(key: string): string {
+  return bytesToBase64(hashAlgorithm('sha1').digest(new TextEncoder().encode(key + WEBSOCKET_GUID)));
+}
+
+/** A fresh `Sec-WebSocket-Key` (16 random bytes, base64). */
+export function webSocketKey(): string {
+  return bytesToBase64(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+}
+
+/** One frame. Clients must mask (`mask: true` picks a random key); servers must not. */
+export function encodeFrame(opcode: number, payload: Uint8Array, options: { mask?: boolean | Uint8Array; fin?: boolean } = {}): Uint8Array {
+  const length = payload.byteLength;
+  const maskKey = options.mask === true ? globalThis.crypto.getRandomValues(new Uint8Array(4)) : options.mask || undefined;
+  const extended = length < 126 ? 0 : length <= 0xffff ? 2 : 8;
+  const headerLength = 2 + extended + (maskKey ? 4 : 0);
+  const frame = new Uint8Array(headerLength + length);
+  const view = new DataView(frame.buffer);
+  frame[0] = (options.fin === false ? 0 : 0x80) | (opcode & 0x0f);
+  frame[1] = (maskKey ? 0x80 : 0) | (extended === 0 ? length : extended === 2 ? 126 : 127);
+  if (extended === 2) view.setUint16(2, length);
+  else if (extended === 8) {
+    view.setUint32(2, Math.floor(length / 2 ** 32));
+    view.setUint32(6, length >>> 0);
+  }
+  if (maskKey) {
+    frame.set(maskKey, 2 + extended);
+    for (let i = 0; i < length; i++) frame[headerLength + i] = payload[i]! ^ maskKey[i & 3]!;
+  } else frame.set(payload, headerLength);
+  return frame;
+}
+
+/** A close frame's payload: the status code and a UTF-8 reason. */
+export function encodeClosePayload(code?: number, reason = ''): Uint8Array {
+  if (code === undefined) return new Uint8Array();
+  const text = new TextEncoder().encode(reason);
+  const out = new Uint8Array(2 + text.byteLength);
+  new DataView(out.buffer).setUint16(0, code);
+  out.set(text, 2);
+  return out;
+}
+
+/** Status 1005 ("no status received") when the payload is empty. */
+export function decodeClosePayload(payload: Uint8Array): { code: number; reason: string } {
+  if (payload.byteLength < 2) return { code: 1005, reason: '' };
+  return { code: new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint16(0), reason: new TextDecoder().decode(payload.subarray(2)) };
+}
+
+/** Splits a byte stream into frames, whatever the chunking. */
+export class FrameDecoder {
+  private buffer = new Uint8Array(0);
+
+  push(bytes: Uint8Array): WebSocketFrame[] {
+    if (bytes.byteLength) {
+      const joined = new Uint8Array(this.buffer.byteLength + bytes.byteLength);
+      joined.set(this.buffer);
+      joined.set(bytes, this.buffer.byteLength);
+      this.buffer = joined;
+    }
+    const frames: WebSocketFrame[] = [];
+    for (;;) {
+      const frame = this.next();
+      if (!frame) return frames;
+      frames.push(frame);
+    }
+  }
+
+  private next(): WebSocketFrame | undefined {
+    const b = this.buffer;
+    if (b.byteLength < 2) return undefined;
+    const masked = (b[1]! & 0x80) !== 0;
+    let length = b[1]! & 0x7f;
+    let offset = 2;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    if (length === 126) {
+      if (b.byteLength < 4) return undefined;
+      length = view.getUint16(2);
+      offset = 4;
+    } else if (length === 127) {
+      if (b.byteLength < 10) return undefined;
+      length = view.getUint32(2) * 2 ** 32 + view.getUint32(6);
+      offset = 10;
+    }
+    const maskKey = masked ? b.subarray(offset, offset + 4) : undefined;
+    if (masked) offset += 4;
+    if (b.byteLength < offset + length) return undefined;
+    const payload = b.slice(offset, offset + length);
+    if (maskKey) for (let i = 0; i < payload.length; i++) payload[i] = payload[i]! ^ maskKey[i & 3]!;
+    const frame = { fin: (b[0]! & 0x80) !== 0, opcode: b[0]! & 0x0f, payload };
+    this.buffer = b.slice(offset + length);
+    return frame;
+  }
+}

package/src/vfs.ts

@@ -14,6 +14,11 @@ export interface FileTree {
   [name: string]: FileContent | FileTree;
 }
 
+export interface DirectoryEntry {
+  name: string;
+  kind: 'file' | 'directory';
+}
+
 export interface FsChange {
   /** `mkdir` is an explicitly created (possibly empty) directory. */
   type: 'write' | 'remove' | 'mkdir';
@@ -98,6 +103,39 @@ export class VirtualFileSystem {
     return [...(this.children.get(normalizePath(path)) ?? [])].sort();
   }
 
+  /** Direct children with their kind, sorted by name — `readdir` for callers that render a tree. */
+  entries(path: string): DirectoryEntry[] {
+    const dir = normalizePath(path);
+    return this.readdir(dir).map((name) => ({ name, kind: this.children.has(join(dir, name)) ? 'directory' : 'file' }));
+  }
+
+  /**
+   * Move a file or a directory (with everything under it). Throws when `from` is
+   * missing or `to` already exists. Watchers see the old paths removed and the
+   * new ones written, which is what every consumer (dev server, process sync) needs.
+   */
+  rename(from: string, to: string): void {
+    const source = normalizePath(from);
+    const target = normalizePath(to);
+    if (source === target) return;
+    if (!this.exists(source)) throw new Error(`ENOENT: no such file or directory, rename '${source}' -> '${target}'`);
+    if (this.exists(target)) throw new Error(`EEXIST: file already exists, rename '${source}' -> '${target}'`);
+    if (target.startsWith(source + '/')) throw new Error(`EINVAL: cannot move '${source}' into itself`);
+    if (this.files.has(source)) {
+      const contents = this.files.get(source)!;
+      this.removeFile(source);
+      this.writeFile(target, contents);
+      return;
+    }
+    const prefix = source + '/';
+    const moved = [...this.files].filter(([path]) => path.startsWith(prefix));
+    const dirs = [...this.explicit].filter((dir) => dir === source || dir.startsWith(prefix));
+    this.rm(source);
+    this.mkdir(target);
+    for (const dir of dirs) this.mkdir(target + dir.slice(source.length));
+    for (const [path, contents] of moved) this.writeFile(target + path.slice(source.length), contents);
+  }
+
   /** Every file path, sorted. */
   list(): string[] {
     return [...this.files.keys()].sort();
@@ -152,9 +190,14 @@ export class VirtualFileSystem {
     return out;
   }
 
-  watch(listener: (change: FsChange) => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+  /** Every change, or with `under` only changes at or below that path. */
+  watch(listener: (change: FsChange) => void, options: { under?: string } = {}): () => void {
+    const root = options.under === undefined ? undefined : normalizePath(options.under);
+    const filtered = root === undefined || root === '/'
+      ? listener
+      : (change: FsChange) => (change.path === root || change.path.startsWith(root + '/')) && listener(change);
+    this.listeners.add(filtered);
+    return () => this.listeners.delete(filtered);
   }
 
   private removeFile(key: string): void {