@seanhogg/builderforce-webcontainers-core 2026.10.7 → 2026.10.8

package/src/node/http/serverResponse.ts

@@ -0,0 +1,98 @@
+/**
+ * ServerResponse, streamed: the head goes out on `writeHead`/`flushHeaders` or
+ * the first write, each `write` is a body chunk, `end` ends the body. So
+ * Server-Sent Events and chunked progress reach the client as they happen. A
+ * client that hangs up mid-response is seen the way Node reports it.
+ */
+import type { HttpResponseHead } from '../../system/types.js';
+import { STATUS_CODES } from './status.js';
+import { FakeSocket, IncomingMessage, OutgoingHeaders } from './messages.js';
+
+/** Where a response goes as it is written. */
+export interface ResponseSink {
+  head(head: HttpResponseHead): void;
+  chunk(data: Uint8Array): void;
+  end(): void;
+}
+
+/** Statuses that never carry a body. */
+const NO_BODY = new Set([101, 204, 304]);
+
+export class ServerResponse extends OutgoingHeaders {
+  statusCode = 200;
+  statusMessage = '';
+  req: IncomingMessage;
+  socket: FakeSocket;
+  connection: FakeSocket;
+  chunkedEncoding = false;
+  shouldKeepAlive = false;
+  private headWritten = false;
+  private hungUp = false;
+
+  constructor(req: IncomingMessage, private readonly sink: ResponseSink) {
+    super({ decodeStrings: true });
+    this.req = req;
+    this.socket = req.socket;
+    this.connection = req.socket;
+  }
+
+  get finished(): boolean {
+    return this.writableEnded;
+  }
+
+  writeHead(status: number, message?: string | Record<string, unknown> | unknown[], headers?: Record<string, unknown> | unknown[]): this {
+    if (typeof message !== 'string') [headers, message] = [message, undefined];
+    this.statusCode = status;
+    if (message) this.statusMessage = message;
+    if (Array.isArray(headers)) {
+      for (let i = 0; i + 1 < headers.length; i += 2) this.setHeader(String(headers[i]), headers[i + 1] as string);
+    } else if (headers) {
+      for (const [k, v] of Object.entries(headers)) if (v !== undefined) this.setHeader(k, v as string);
+    }
+    this.sendHead();
+    return this;
+  }
+  override flushHeaders(): void {
+    this.sendHead();
+  }
+  writeContinue(): void {}
+  writeProcessing(): void {}
+  writeEarlyHints(): void {}
+  addTrailers(): void {}
+  assignSocket(): void {}
+  detachSocket(): void {}
+
+  override _write(chunk: Uint8Array, _encoding: string, callback: () => void): void {
+    this.sendHead();
+    if (!this.hungUp && this.req.method !== 'HEAD' && !NO_BODY.has(this.statusCode)) this.sink.chunk(new Uint8Array(chunk));
+    callback();
+  }
+
+  override _final(callback: () => void): void {
+    this.sendHead();
+    if (!this.hungUp) this.sink.end();
+    callback();
+  }
+
+  /** The client went away (closed its EventSource, navigated off): `aborted`/`close` on the request, `close` here; later writes are dropped. */
+  _hangUp(): void {
+    if (this.hungUp || this.writableFinished) return;
+    this.hungUp = true;
+    this._writableState.emitClose = false;
+    this.req.aborted = true;
+    this.req.emit('aborted');
+    this.req.emit('close');
+    this.socket.destroyed = true;
+    this.socket.emit('close', false);
+    this.emit('close');
+  }
+
+  private sendHead(): void {
+    this.headersSent = true;
+    if (this.headWritten) return;
+    this.headWritten = true;
+    const headers: Record<string, string | string[]> = {};
+    for (const { name, value } of this._headers.values()) headers[name] = value;
+    this.sink.head({ status: this.statusCode, statusText: this.statusMessage || STATUS_CODES[this.statusCode] || '', headers });
+  }
+}

package/src/node/http/upgradeSocket.ts

@@ -0,0 +1,79 @@
+/**
+ * The socket an `http.Server` hands its `upgrade` listeners: a real Duplex
+ * over the upgraded connection's byte pipe, with the slice of net.Socket that
+ * WebSocket servers touch (`ws` writes its `101` reply and frames with
+ * `write(data, cb)`, corks, pauses, reads `_readableState`, and calls
+ * `setNoDelay`/`setTimeout`). Raw bytes only — framing is the package's job.
+ */
+import { Buffer } from '../buffer.js';
+import { Duplex } from '../stream/index.js';
+import type { ByteChannel } from '../../system/types.js';
+
+type Callback = (error?: Error | null) => void;
+
+export class UpgradeSocket extends Duplex {
+  remoteAddress = '127.0.0.1';
+  remotePort = 50000 + Math.floor(Math.random() * 10000);
+  remoteFamily = 'IPv4';
+  localAddress = '127.0.0.1';
+  localPort: number;
+  encrypted = false;
+  connecting = false;
+  bytesRead = 0;
+  bytesWritten = 0;
+  private release?: () => void;
+
+  /** `hold` keeps the process alive while the connection is open, as a TCP socket would. */
+  constructor(private readonly channel: ByteChannel, port: number, hold?: () => () => void) {
+    super({ allowHalfOpen: false });
+    this.localPort = port;
+    this.release = hold?.();
+    channel.onData((data) => {
+      this.bytesRead += data.byteLength;
+      this.push(Buffer.from(data.buffer as ArrayBuffer, data.byteOffset, data.byteLength));
+    });
+    channel.onClose(() => {
+      this.push(null);
+      this.end();
+    });
+    this.once('close', () => {
+      this.release?.();
+      this.release = undefined;
+    });
+  }
+
+  override _read(): void {
+    // bytes are pushed as they arrive
+  }
+
+  _write(chunk: Uint8Array, _encoding: string, callback: Callback): void {
+    this.bytesWritten += chunk.byteLength;
+    this.channel.send(chunk);
+    callback();
+  }
+
+  _final(callback: Callback): void {
+    this.channel.close();
+    this.push(null);
+    callback();
+  }
+
+  override _destroy(error: Error | null, callback: Callback): void {
+    this.channel.close();
+    callback(error);
+  }
+
+  setTimeout(_ms: number, cb?: () => void): this {
+    if (cb) this.once('timeout', cb);
+    return this;
+  }
+  setNoDelay(): this { return this; }
+  setKeepAlive(): this { return this; }
+  address() { return { address: this.localAddress, family: 'IPv4', port: this.localPort }; }
+  ref(): this { return this; }
+  unref(): this {
+    this.release?.();
+    this.release = undefined;
+    return this;
+  }
+}

package/src/node/runtime.ts

@@ -57,8 +57,8 @@ export async function startNode(options: NodeOptions): Promise<NodeInstance> {
   // Servers die with the process: wrap listen so exit can close what is left open.
   const processSystem: System = {
     ...system,
-    listen(port, handler) {
-      const registration = system.listen(port, handler);
+    listen(port, handler, upgrade) {
+      const registration = system.listen(port, handler, upgrade);
       const tracked = {
         port: registration.port,
         close() {

package/src/previewBridge.ts

@@ -0,0 +1,194 @@
+/**
+ * Scripts injected into preview pages that let them reach virtual servers the
+ * way a page reaches a real one, where a service worker cannot help:
+ *
+ *   • WebSockets. A service worker never sees a WebSocket, so the page's
+ *     `WebSocket` is replaced by one that, for URLs naming a virtual server
+ *     (`ws://localhost:3000/…`, `/__bfwc/<id>/__port/3000/…`, or a path on the
+ *     page's own host from a page that server served), opens a MessageChannel
+ *     to the runtime's host page (`parent`, else `opener`). The host connects
+ *     to the server and relays frames both ways. Every other URL gets the real
+ *     `WebSocket`, untouched.
+ *   • `document.cookie` on pages a virtual server served. The host keeps those
+ *     cookies (a service worker cannot set `Set-Cookie`); this mirrors the
+ *     non-HttpOnly ones into `document.cookie` and sends assignments back.
+ *
+ * Messages on a socket's channel — page → host: `{ kind: 'send', data }`,
+ * `{ kind: 'close', code, reason }`; host → page: `{ kind: 'open', protocol }`,
+ * `{ kind: 'message', data }` (string or ArrayBuffer), `{ kind: 'close', code, reason, wasClean }`.
+ * On the cookie channel — page → host `{ kind: 'set-cookie', value }`, host → page `{ kind: 'cookies', value }`.
+ */
+
+/** page → host, with a MessagePort: "connect a WebSocket to `port` at `path`". */
+export const SOCKET_MESSAGE_TYPE = 'bfwc:socket';
+/** page → host, with a MessagePort: "keep my `document.cookie` in sync" (pages served by a virtual server). */
+export const COOKIE_MESSAGE_TYPE = 'bfwc:cookies';
+/** How long a page waits for the host to answer a socket before failing it (code 1006). */
+export const SOCKET_CONNECT_TIMEOUT_MS = 15_000;
+
+/** The `WebSocket` replacement; runs in every preview page (dev-server documents and virtual-server HTML). */
+export function previewSocketScript(): string {
+  return `<script>(function(){
+  var Native = window.WebSocket;
+  if (!Native || Native.__bfwc) return;
+  var runtime = window.parent !== window ? window.parent : window.opener;
+  var m = /^(.*\\/__bfwc\\/[A-Za-z0-9_-]+\\/)(?:__port\\/(\\d{1,5})(?:\\/|$))?/.exec(location.pathname);
+  if (!runtime || !m || typeof MessageChannel === 'undefined') return;
+  var base = m[1], ownPort = m[2] ? Number(m[2]) : 0;
+  var LOCAL = /^(localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\])$/i;
+  function target(url) {
+    var u;
+    try { u = new URL(String(url), location.href); } catch (_) { return null; }
+    if (!/^(wss?|https?):$/.test(u.protocol)) return null;
+    if (u.host === location.host) {
+      if (u.pathname.indexOf(base) === 0) {
+        var p = /^__port\\/(\\d{1,5})(\\/.*)?$/.exec(u.pathname.slice(base.length));
+        return p ? { port: Number(p[1]), path: (p[2] || '/') + u.search } : null;
+      }
+      return ownPort ? { port: ownPort, path: u.pathname + u.search } : null;
+    }
+    if (LOCAL.test(u.hostname)) return { port: Number(u.port || (/^(wss|https):$/.test(u.protocol) ? 443 : 80)), path: u.pathname + u.search };
+    return null;
+  }
+  var CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3;
+  class VirtualWebSocket extends EventTarget {
+    constructor(url, protocols) {
+      var t = target(url);
+      if (!t) return protocols === undefined ? new Native(url) : new Native(url, protocols);
+      super();
+      var self = this, channel = new MessageChannel();
+      this._url = new URL(String(url), location.href).href.replace(/^http/, 'ws');
+      this._state = CONNECTING;
+      this._protocol = '';
+      this._binaryType = 'blob';
+      this._queue = Promise.resolve();
+      this._port = channel.port1;
+      this._port.onmessage = function (e) { self._receive(e.data); };
+      this._timer = setTimeout(function () { self._receive({ kind: 'close', code: 1006, reason: '', wasClean: false }); }, ${SOCKET_CONNECT_TIMEOUT_MS});
+      var list = protocols === undefined ? [] : typeof protocols === 'string' ? [protocols] : Array.from(protocols, String);
+      runtime.postMessage({ type: ${JSON.stringify(SOCKET_MESSAGE_TYPE)}, href: location.href, port: t.port, path: t.path, protocols: list }, '*', [channel.port2]);
+    }
+    get url() { return this._url; }
+    get readyState() { return this._state; }
+    get protocol() { return this._protocol; }
+    get extensions() { return ''; }
+    get bufferedAmount() { return 0; }
+    get binaryType() { return this._binaryType; }
+    set binaryType(v) { if (v === 'blob' || v === 'arraybuffer') this._binaryType = v; }
+    send(data) {
+      if (this._state === CONNECTING) throw new DOMException("Failed to execute 'send' on 'WebSocket': Still in CONNECTING state.", 'InvalidStateError');
+      if (this._state !== OPEN) return;
+      var port = this._port;
+      var value = typeof data === 'string' ? data
+        : data instanceof Blob ? data.arrayBuffer()
+        : ArrayBuffer.isView(data) ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+        : data instanceof ArrayBuffer ? data.slice(0) : String(data);
+      this._queue = this._queue.then(function () { return value; }).then(function (v) { port.postMessage({ kind: 'send', data: v }); });
+    }
+    close(code, reason) {
+      if (code !== undefined && code !== 1000 && (code < 3000 || code > 4999)) throw new DOMException("Failed to execute 'close' on 'WebSocket': The code must be either 1000, or between 3000 and 4999.", 'InvalidAccessError');
+      if (this._state === CLOSING || this._state === CLOSED) return;
+      this._state = CLOSING;
+      var port = this._port;
+      this._queue.then(function () { port.postMessage({ kind: 'close', code: code, reason: reason === undefined ? '' : String(reason) }); });
+    }
+    _receive(m) {
+      if (!m || this._state === CLOSED) return;
+      if (m.kind === 'open' && this._state === CONNECTING) {
+        clearTimeout(this._timer);
+        this._state = OPEN;
+        this._protocol = m.protocol || '';
+        this._emit(new Event('open'));
+      } else if (m.kind === 'message' && this._state !== CONNECTING) {
+        var d = m.data;
+        if (typeof d !== 'string' && this._binaryType === 'blob') d = new Blob([d]);
+        this._emit(new MessageEvent('message', { data: d, origin: new URL(this._url).origin }));
+      } else if (m.kind === 'close') {
+        clearTimeout(this._timer);
+        this._state = CLOSED;
+        this._port.close();
+        if (!m.wasClean) this._emit(new Event('error'));
+        this._emit(new CloseEvent('close', { code: m.code, reason: m.reason || '', wasClean: !!m.wasClean }));
+      }
+    }
+    _emit(event) {
+      var handler = this['on' + event.type];
+      if (typeof handler === 'function') handler.call(this, event);
+      this.dispatchEvent(event);
+    }
+  }
+  [['CONNECTING', CONNECTING], ['OPEN', OPEN], ['CLOSING', CLOSING], ['CLOSED', CLOSED]].forEach(function (c) {
+    Object.defineProperty(VirtualWebSocket, c[0], { value: c[1] });
+    Object.defineProperty(VirtualWebSocket.prototype, c[0], { value: c[1] });
+  });
+  Object.defineProperty(VirtualWebSocket, Symbol.hasInstance, { value: function (o) { return o instanceof Native || Function.prototype[Symbol.hasInstance].call(VirtualWebSocket, o); } });
+  VirtualWebSocket.__bfwc = true;
+  window.WebSocket = VirtualWebSocket;
+})();</script>`;
+}
+
+/** `JSON.stringify`, safe inside an inline script. */
+const scriptLiteral = (value: unknown) => JSON.stringify(value).replace(/</g, '\\u003c');
+
+/**
+ * `document.cookie` for a page a virtual server served: starts from the host's
+ * jar (`initial`: the non-HttpOnly cookies for this page's path), stays in sync
+ * over a channel, and sends assignments to the host's jar.
+ */
+export function previewCookieScript(initial: string): string {
+  return `<script>(function(){
+  var runtime = window.parent !== window ? window.parent : window.opener;
+  var cookies = ${scriptLiteral(initial)};
+  var port = null;
+  if (runtime && typeof MessageChannel !== 'undefined') {
+    var channel = new MessageChannel();
+    port = channel.port1;
+    port.onmessage = function (e) { if (e.data && e.data.kind === 'cookies') cookies = String(e.data.value); };
+    runtime.postMessage({ type: ${JSON.stringify(COOKIE_MESSAGE_TYPE)}, href: location.href }, '*', [channel.port2]);
+  }
+  function apply(value) {
+    var parts = value.split(';'), pair = parts[0], eq = pair.indexOf('=');
+    if (eq < 0) return;
+    var name = pair.slice(0, eq).trim(), remove = false;
+    if (!name) return;
+    for (var i = 1; i < parts.length; i++) {
+      var a = parts[i].trim(), k = a.split('=')[0].trim().toLowerCase(), v = a.slice(a.indexOf('=') + 1).trim();
+      if (k === 'httponly') return;
+      if (k === 'max-age' && /^-?\\d+$/.test(v) && Number(v) <= 0) remove = true;
+      if (k === 'expires' && Date.parse(v) <= Date.now()) remove = true;
+    }
+    var list = cookies ? cookies.split('; ').filter(function (c) { return c.slice(0, c.indexOf('=')) !== name; }) : [];
+    if (!remove) list.push(name + '=' + pair.slice(eq + 1).trim());
+    cookies = list.join('; ');
+  }
+  try {
+    Object.defineProperty(document, 'cookie', {
+      configurable: true,
+      get: function () { return cookies; },
+      set: function (value) { value = String(value); apply(value); if (port) port.postMessage({ kind: 'set-cookie', value: value }); },
+    });
+  } catch (_) {}
+})();</script>`;
+}
+
+const HEAD_OPEN = /<head(?:\s[^>]*)?>/i;
+const HTML_OPEN = /<html(?:\s[^>]*)?>/i;
+const DOCTYPE = /<!doctype[^>]*>/i;
+/** Content past which `<head>` can no longer appear. */
+const BODY_STARTED = /<(?:body|script|link|meta|style|title|div|p)[\s>/]/i;
+
+/**
+ * Where to inject the bridge into a streamed document, from its first bytes:
+ * just after `<head …>`, else after `<html …>` or the doctype (never before the
+ * doctype, which would switch the page to quirks mode), else the start.
+ * Undefined while the prefix is too short to tell; pass `complete` at the end of the body.
+ */
+export function bridgeInsertionPoint(prefix: string, complete = false): number | undefined {
+  const head = HEAD_OPEN.exec(prefix);
+  if (head) return head.index + head[0].length;
+  if (!complete && !BODY_STARTED.test(prefix) && prefix.length < 4096) return undefined;
+  const html = HTML_OPEN.exec(prefix);
+  if (html) return html.index + html[0].length;
+  const doctype = DOCTYPE.exec(prefix);
+  return doctype ? doctype.index + doctype[0].length : 0;
+}

package/src/shell/ast.ts

@@ -0,0 +1,85 @@
+/**
+ * The shell's syntax tree. Words keep their quoting as segments, because
+ * expansion (variables, `$(…)`, `~`, globs, field splitting) happens at run
+ * time and depends on it.
+ */
+
+export type Segment =
+  | { kind: 'text'; value: string; quoted: boolean }
+  | { kind: 'var'; name: string; quoted: boolean; op?: ':-' | '-' | ':=' | ':+'; arg?: Word }
+  | { kind: 'cmd'; source: string; quoted: boolean }
+  | { kind: 'tilde' };
+export type Word = Segment[];
+
+export type RedirectOp = '>' | '>>' | '<' | '2>' | '2>>' | '&>' | '2>&1' | '>&2' | '<<' | '<<-';
+export interface Redirect {
+  op: RedirectOp;
+  target?: Word;
+  /** A here-document's body; expanded like a double-quoted string unless the delimiter was quoted. */
+  heredoc?: { body: Word };
+}
+
+export interface SimpleCommand {
+  type: 'simple';
+  assignments: Array<{ name: string; value: Word }>;
+  words: Word[];
+  redirects: Redirect[];
+}
+
+export interface IfCommand {
+  type: 'if';
+  clauses: Array<{ condition: Script; body: Script }>;
+  otherwise?: Script;
+  redirects: Redirect[];
+}
+
+export interface LoopCommand {
+  type: 'while' | 'until';
+  condition: Script;
+  body: Script;
+  redirects: Redirect[];
+}
+
+export interface ForCommand {
+  type: 'for';
+  name: string;
+  /** Absent: iterate the positional parameters (`for x; do …`). */
+  items?: Word[];
+  body: Script;
+  redirects: Redirect[];
+}
+
+export interface CaseCommand {
+  type: 'case';
+  subject: Word;
+  arms: Array<{ patterns: Word[]; body: Script }>;
+  redirects: Redirect[];
+}
+
+/** `{ list; }` runs in this shell; `( list )` in a copy of it. */
+export interface GroupCommand {
+  type: 'group' | 'subshell';
+  body: Script;
+  redirects: Redirect[];
+}
+
+export interface FunctionDefinition {
+  type: 'function';
+  name: string;
+  body: CompoundCommand;
+  redirects: Redirect[];
+}
+
+export type CompoundCommand = IfCommand | LoopCommand | ForCommand | CaseCommand | GroupCommand;
+export type Command = SimpleCommand | CompoundCommand | FunctionDefinition;
+
+export interface Pipeline {
+  negate: boolean;
+  commands: Command[];
+}
+export interface AndOrList {
+  first: Pipeline;
+  rest: Array<{ op: '&&' | '||'; pipeline: Pipeline }>;
+  background: boolean;
+}
+export type Script = AndOrList[];

package/src/shell/builtins.ts

@@ -8,6 +8,15 @@ import type { CommandContext, Command } from './context.js';
 import { resolvePath } from './context.js';
 import { cat, cp, ls, mkdir, mv, pwd, rm, touch } from './fileCommands.js';
 import { basename, clear, dirname, echo, env, falseCommand, grep, head, printf, sleep, tail, trueCommand, wc } from './textCommands.js';
+import { bracket, test } from './testCommand.js';
+import { readLine } from './lineReader.js';
+import type { Flow } from './compound.js';
+
+/** A command started with `&`. */
+export interface BackgroundJob {
+  id: number;
+  done: Promise<number>;
+}
 
 /** The slice of the shell a builtin may change. */
 export interface ShellState {
@@ -17,6 +26,14 @@ export interface ShellState {
   lastStatus: number;
   /** Set by `exit`: the shell stops after the current command. */
   exitRequested?: number;
+  /** Set by `break`, `continue` and `return`; the loop or function it targets clears it. */
+  flow?: Flow;
+  /** `$1…`, `$@`; a function call swaps them for its arguments. */
+  positional: string[];
+  readonly functions: ReadonlyMap<string, unknown>;
+  readonly jobs: ReadonlyMap<number, BackgroundJob>;
+  /** One frame per running function (for `local`). */
+  readonly localFrames: Array<Map<string, string | undefined>>;
   /** Run a script in this shell (for `source`). */
   run(source: string): Promise<number>;
 }
@@ -25,21 +42,25 @@ export type Builtin = (ctx: CommandContext, shell: ShellState) => Promise<number
 
 /** Coreutils: plain commands, also spawnable as standalone programs. */
 export const COREUTILS: Record<string, Command> = {
-  ls, cat, mkdir, rm, cp, mv, touch, pwd, echo, printf, head, tail, grep, wc, env, clear, sleep, basename, dirname,
+  ls, cat, mkdir, rm, cp, mv, touch, pwd, echo, printf, head, tail, grep, wc, env, clear, sleep, basename, dirname, test,
+  '[': bracket,
   true: trueCommand,
   false: falseCommand,
 };
 
 /** Programs the runtime provides besides coreutils (reported by `which`/`type`). */
-export const SYSTEM_PROGRAMS = ['node', 'npm', 'npx', 'bfsh', 'sh', 'bash'];
+export const SYSTEM_PROGRAMS = ['node', 'npm', 'npx', 'pnpm', 'yarn', 'bfsh', 'sh', 'bash'];
 
 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
+  Builtins:  cd, pwd, export, unset, exit, source, history, type, which, help,
+             read, local, shift, return, break, continue, jobs, wait
+  Files:     ls [-la], cat, mkdir [-p], rm [-rf], cp [-r], mv, touch, test / [ … ]
   Text:      echo, printf, head, tail, grep, wc, env, clear, sleep, basename, dirname
-  Node:      node <file>, npm install|ci|run|start|test, npx <bin>
+  Node:      node <file>, npm install|ci|run|start|test, npx <bin>, pnpm, yarn
   Syntax:    'quotes' "\$VARS" a && b || c; a | b > out.txt >> log 2>&1 2> err; FOO=bar cmd; $(cmd); *.js
+             if …; then …; elif …; else …; fi   while|until …; do …; done   for x in …; do …; done
+             case $x in a|b) …;; *) …;; esac   name() { …; }   { …; }   ( … )   cat <<EOF … EOF
 
 `;
 
@@ -116,10 +137,11 @@ export const BUILTINS: Record<string, Builtin> = {
     }
     return status;
   },
-  async type(ctx) {
+  async type(ctx, shell) {
     let status = 0;
     for (const name of ctx.args) {
-      if (name in BUILTINS) ctx.io.stdout(`${name} is a shell builtin\n`);
+      if (shell.functions.has(name)) ctx.io.stdout(`${name} is a function\n`);
+      else if (name in BUILTINS) ctx.io.stdout(`${name} is a shell builtin\n`);
       else if (name in COREUTILS || SYSTEM_PROGRAMS.includes(name)) ctx.io.stdout(`${name} is /usr/local/bin/${name}\n`);
       else {
         const file = findExecutable(ctx.fs, name, ctx.cwd, ctx.env);
@@ -135,7 +157,75 @@ export const BUILTINS: Record<string, Builtin> = {
   async set() {
     return 0; // options (-e, -x) are accepted and ignored
   },
+  async break(ctx, shell) {
+    return loopControl(ctx, shell, 'break');
+  },
+  async continue(ctx, shell) {
+    return loopControl(ctx, shell, 'continue');
+  },
+  async return(ctx, shell) {
+    if (!shell.localFrames.length) {
+      ctx.io.stderr('return: can only `return\' from a function or sourced script\n');
+      return 1;
+    }
+    const status = ctx.args[0] === undefined ? shell.lastStatus : Number(ctx.args[0]) & 255;
+    shell.flow = { kind: 'return', status };
+    return status;
+  },
+  async local(ctx, shell) {
+    const frame = shell.localFrames[shell.localFrames.length - 1];
+    if (!frame) {
+      ctx.io.stderr('local: can only be used in a function\n');
+      return 1;
+    }
+    for (const arg of ctx.args) {
+      const eq = arg.indexOf('=');
+      const name = eq > 0 ? arg.slice(0, eq) : arg;
+      if (!frame.has(name)) frame.set(name, shell.env[name]);
+      shell.env[name] = eq > 0 ? arg.slice(eq + 1) : '';
+    }
+    return 0;
+  },
+  async shift(ctx, shell) {
+    const count = ctx.args[0] === undefined ? 1 : Number(ctx.args[0]);
+    if (!Number.isInteger(count) || count < 0 || count > shell.positional.length) return 1;
+    shell.positional = shell.positional.slice(count);
+    return 0;
+  },
+  async read(ctx, shell) {
+    const raw = ctx.args.includes('-r');
+    const names = ctx.args.filter((a) => !a.startsWith('-'));
+    let line = await readLine(ctx.io.stdin, ctx.signal);
+    if (line === null) return 1;
+    if (!raw) line = line.replace(/\\(.)/g, '$1');
+    const targets = names.length ? names : ['REPLY'];
+    const fields = names.length ? line.trim().split(/\s+/) : [line];
+    targets.forEach((name, i) => {
+      shell.env[name] = i === targets.length - 1 ? fields.slice(i).join(' ') : fields[i] ?? '';
+    });
+    return 0;
+  },
+  async jobs(ctx, shell) {
+    for (const job of shell.jobs.values()) ctx.io.stdout(`[${job.id}]  Running\n`);
+    return 0;
+  },
+  async wait(ctx, shell) {
+    const ids = ctx.args.map((a) => Number(a.replace(/^%/, '')));
+    const jobs = ids.length ? ids.map((id) => shell.jobs.get(id)).filter((j): j is BackgroundJob => !!j) : [...shell.jobs.values()];
+    const statuses = await Promise.all(jobs.map((job) => job.done));
+    return statuses.length ? statuses[statuses.length - 1]! : 0;
+  },
 };
+
+function loopControl(ctx: CommandContext, shell: ShellState, kind: 'break' | 'continue'): number {
+  const levels = ctx.args[0] === undefined ? 1 : Number(ctx.args[0]);
+  if (!Number.isInteger(levels) || levels < 1) {
+    ctx.io.stderr(`${kind}: ${ctx.args[0]}: loop count out of range\n`);
+    return 1;
+  }
+  shell.flow = { kind, levels };
+  return 0;
+}
 BUILTINS['.'] = BUILTINS.source!;
 BUILTINS[':'] = async () => 0;