@seanhogg/builderforce-webcontainers-core 2026.10.7 → 2026.10.8

package/src/shell/compound.ts

@@ -0,0 +1,89 @@
+/**
+ * Running compound commands (`if`, `while`/`until`, `for`, `case`, `{ }`,
+ * `( )`) against a narrow {@link ScriptRunner}, so the executor stays a
+ * dispatcher. Loop control (`break`, `continue`) and `return` travel as a
+ * {@link Flow} the runner holds: lists stop running while one is set, and the
+ * construct it targets clears it.
+ */
+import type { CompoundCommand, Script, Word } from './ast.js';
+import type { JobInput, ShellIO } from './exec.js';
+import { patternToRegExp } from './expand.js';
+
+export type Flow = { kind: 'break' | 'continue'; levels: number } | { kind: 'return'; status: number };
+
+export interface ScriptRunner {
+  flow?: Flow;
+  readonly positional: readonly string[];
+  runScript(script: Script, io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number>;
+  /** Words with splitting and globbing, as command arguments. */
+  expandWords(words: Word[], io: ShellIO, signal: AbortSignal): Promise<string[]>;
+  /** One word as a single string: no splitting, no globbing. */
+  expandText(word: Word, io: ShellIO, signal: AbortSignal): Promise<string>;
+  setVar(name: string, value: string): void;
+  /** A copy of this shell for `( … )`: changes inside do not leak out. */
+  subshell(): ScriptRunner;
+}
+
+/** After one pass of a loop body: whether the loop goes on. Consumes the flow aimed at this loop. */
+function continueLoop(runner: ScriptRunner): boolean {
+  const flow = runner.flow;
+  if (!flow) return true;
+  if (flow.kind === 'return') return false;
+  if (flow.levels > 1) {
+    runner.flow = { kind: flow.kind, levels: flow.levels - 1 };
+    return false;
+  }
+  runner.flow = undefined;
+  return flow.kind === 'continue';
+}
+
+export async function runCompound(node: CompoundCommand, runner: ScriptRunner, io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number> {
+  switch (node.type) {
+    case 'group':
+      return runner.runScript(node.body, io, input, signal);
+    case 'subshell':
+      return runner.subshell().runScript(node.body, io, input, signal);
+    case 'if': {
+      for (const clause of node.clauses) {
+        const condition = await runner.runScript(clause.condition, io, input, signal);
+        if (runner.flow) return condition;
+        if (condition === 0) return runner.runScript(clause.body, io, input, signal);
+      }
+      return node.otherwise ? runner.runScript(node.otherwise, io, input, signal) : 0;
+    }
+    case 'while':
+    case 'until': {
+      let status = 0;
+      while (!signal.aborted) {
+        const condition = await runner.runScript(node.condition, io, input, signal);
+        if (runner.flow && !continueLoop(runner)) break;
+        if ((condition === 0) !== (node.type === 'while')) break;
+        status = await runner.runScript(node.body, io, input, signal);
+        if (!continueLoop(runner)) break;
+      }
+      return status;
+    }
+    case 'for': {
+      const items = node.items ? await runner.expandWords(node.items, io, signal) : [...runner.positional];
+      let status = 0;
+      for (const item of items) {
+        if (signal.aborted) break;
+        runner.setVar(node.name, item);
+        status = await runner.runScript(node.body, io, input, signal);
+        if (!continueLoop(runner)) break;
+      }
+      return status;
+    }
+    case 'case': {
+      const subject = await runner.expandText(node.subject, io, signal);
+      for (const arm of node.arms) {
+        for (const pattern of arm.patterns) {
+          if (patternToRegExp(await runner.expandText(pattern, io, signal), { slash: true }).test(subject)) {
+            return runner.runScript(arm.body, io, input, signal);
+          }
+        }
+      }
+      return 0;
+    }
+  }
+}

package/src/shell/exec.ts

@@ -1,18 +1,21 @@
 /**
  * The executor: runs a parsed script. Lists honour `&&`/`||`/`;`/`&`; pipeline
- * stages run concurrently, joined by in-memory pipes; redirects swap a stage's
- * stdin/stdout/stderr for files. Dispatch order per command: shell builtins,
+ * stages run concurrently, joined by in-memory pipes; redirects (here-documents
+ * included) swap a stage's stdin/stdout/stderr. Compound commands run through
+ * compound.ts. Dispatch order per simple command: shell functions, builtins,
  * extra in-process commands (npm, npx), the dev-server handoff, coreutils, and
  * finally `system.spawn` (node, scripts on PATH, `.bin` entries) — which in the
  * browser is a separate Web Worker.
  */
 import type { System } from '../system/types.js';
 import { InputQueue } from '../system/terminal.js';
-import { parse, ShellSyntaxError, type Command as CommandNode, type Pipeline, type Script } from './parse.js';
+import type { Command as CommandNode, FunctionDefinition, Pipeline, Redirect, Script, SimpleCommand, Word } from './ast.js';
+import { parse, ShellSyntaxError } from './parse.js';
 import { expandWord, expandWords, type ExpandContext } from './expand.js';
-import { BUILTINS, COREUTILS, type ShellState } from './builtins.js';
+import { BUILTINS, COREUTILS, type BackgroundJob, type ShellState } from './builtins.js';
 import { resolvePath, type CommandContext } from './context.js';
 import { matchDevServer, runDevServerHandoff } from './devHandoff.js';
+import { runCompound, type Flow, type ScriptRunner } from './compound.js';
 
 export interface ShellIO {
   stdout(text: string): void;
@@ -39,31 +42,44 @@ export interface ShellOptions {
   /** The terminal size, when attached to one. */
   terminalSize?: () => { cols: number; rows: number } | undefined;
   commands?: Record<string, ShellCommand>;
+  /** Functions inherited from a parent shell (subshells and `$(…)`). */
+  functions?: Map<string, FunctionDefinition>;
 }
 
 let nextShellPid = 500;
 
-export class Shell implements ShellState {
+export class Shell implements ShellState, ScriptRunner {
   cwd: string;
   env: Record<string, string>;
   lastStatus = 0;
   history: string[] = [];
   exitRequested?: number;
+  flow?: Flow;
+  positional: string[];
+  readonly functions: Map<string, FunctionDefinition>;
+  readonly jobs = new Map<number, BackgroundJob>();
+  /** One frame per running function: names declared `local`, with the value to restore. */
+  readonly localFrames: Array<Map<string, string | undefined>> = [];
   readonly pid = nextShellPid++;
   readonly system: System;
-  private readonly positional: string[];
+  private nextJob = 1;
   private current?: { io: ShellIO; input: JobInput; signal: AbortSignal };
 
   constructor(readonly options: ShellOptions) {
     this.system = options.system;
     this.cwd = options.cwd;
     this.env = { ...options.env, PWD: options.cwd };
-    this.positional = options.positional ?? [];
+    this.positional = [...(options.positional ?? [])];
+    this.functions = new Map(options.functions);
   }
 
-  /** A child shell for `npm run` / subshells: same IO, its own cwd and environment. */
+  /** A child shell for `npm run` / subshells: same IO, its own cwd, environment and functions. */
   fork(overrides: { cwd?: string; env?: Record<string, string>; positional?: string[] }): Shell {
-    return new Shell({ ...this.options, cwd: overrides.cwd ?? this.cwd, env: { ...this.env, ...overrides.env }, positional: overrides.positional });
+    return new Shell({ ...this.options, cwd: overrides.cwd ?? this.cwd, env: { ...this.env, ...overrides.env }, positional: overrides.positional ?? this.positional, functions: this.functions });
+  }
+
+  subshell(): Shell {
+    return this.fork({});
   }
 
   /** Parse and run `source`. Syntax errors print and return 2. */
@@ -80,23 +96,11 @@ export class Shell implements ShellState {
     const previous = this.current;
     this.current = { io, input, signal };
     try {
-      for (const list of script) {
-        if (this.exitRequested !== undefined || signal.aborted) break;
-        const run = async () => {
-          let status = await this.runPipeline(list.first, io, input, signal);
-          for (const { op, pipeline } of list.rest) {
-            if (this.exitRequested !== undefined || signal.aborted) break;
-            if ((op === '&&') === (status === 0)) status = await this.runPipeline(pipeline, io, input, signal);
-          }
-          return status;
-        };
-        if (list.background) {
-          void run();
-          this.lastStatus = 0;
-        } else this.lastStatus = await run();
-      }
+      await this.runScript(script, io, input, signal);
     } finally {
       this.current = previous;
+      // A `break`/`continue` outside any loop (or `return` outside a function) must not stop later lines.
+      if (!this.localFrames.length) this.flow = undefined;
     }
     if (signal.aborted && this.lastStatus === 0) this.lastStatus = 130;
     return this.exitRequested ?? this.lastStatus;
@@ -109,6 +113,40 @@ export class Shell implements ShellState {
     return this.exec(source, job.io, job.input, job.signal);
   }
 
+  async runScript(script: Script, io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number> {
+    for (const list of script) {
+      if (this.exitRequested !== undefined || signal.aborted || this.flow) break;
+      const run = async () => {
+        let status = await this.runPipeline(list.first, io, input, signal);
+        for (const { op, pipeline } of list.rest) {
+          if (this.exitRequested !== undefined || signal.aborted || this.flow) break;
+          if ((op === '&&') === (status === 0)) status = await this.runPipeline(pipeline, io, input, signal);
+        }
+        return status;
+      };
+      if (list.background) {
+        const id = this.nextJob++;
+        const done = run();
+        this.jobs.set(id, { id, done });
+        void done.finally(() => this.jobs.delete(id));
+        this.lastStatus = 0;
+      } else this.lastStatus = await run();
+    }
+    return this.lastStatus;
+  }
+
+  expandWords(words: Word[], io: ShellIO, signal: AbortSignal): Promise<string[]> {
+    return expandWords(words, this.expandContext(io, signal));
+  }
+
+  async expandText(word: Word, io: ShellIO, signal: AbortSignal): Promise<string> {
+    return (await expandWord(word, this.expandContext(io, signal), { split: false, glob: false })).join('');
+  }
+
+  setVar(name: string, value: string): void {
+    this.env[name] = value;
+  }
+
   private expandContext(io: ShellIO, signal: AbortSignal): ExpandContext {
     return {
       fs: this.system.fs,
@@ -147,6 +185,21 @@ export class Shell implements ShellState {
   }
 
   private async runCommand(node: CommandNode, io: ShellIO, input: JobInput, signal: AbortSignal, alone: boolean): Promise<number> {
+    if (node.type === 'function') {
+      this.functions.set(node.name, node);
+      return 0;
+    }
+    if (node.type === 'simple') return this.runSimple(node, io, input, signal, alone);
+    const redirected = await this.applyRedirects(node.redirects, io, input, signal);
+    if (typeof redirected === 'number') return redirected;
+    try {
+      return await runCompound(node, this, redirected.io, redirected.input, signal);
+    } finally {
+      redirected.flush();
+    }
+  }
+
+  private async runSimple(node: SimpleCommand, io: ShellIO, input: JobInput, signal: AbortSignal, alone: boolean): Promise<number> {
     const ectx = this.expandContext(io, signal);
     const argv = await expandWords(node.words, ectx);
     const assigned: Record<string, string> = {};
@@ -155,14 +208,27 @@ export class Shell implements ShellState {
       Object.assign(this.env, assigned);
       return 0;
     }
+    const redirected = await this.applyRedirects(node.redirects, io, input, signal);
+    if (typeof redirected === 'number') return redirected;
+    try {
+      return await this.dispatch(argv, assigned, redirected.io, redirected.input, signal, alone && redirected.io.isTerminal);
+    } finally {
+      redirected.flush();
+    }
+  }
 
-    // Redirects.
-    let stdout = io.stdout;
-    let stderr = io.stderr;
+  /** Apply redirects; returns the new IO, or an exit status when a redirect fails. */
+  private async applyRedirects(redirects: Redirect[], io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number | { io: ShellIO; input: JobInput; flush(): void }> {
+    let { stdout, stderr, isTerminal } = io;
     let stdin = input;
-    let isTerminal = io.isTerminal;
     const flushes: Array<() => void> = [];
-    for (const redirect of node.redirects) {
+    const fromText = (text: string): JobInput => {
+      const queue = new InputQueue();
+      queue.push(text);
+      queue.push(null);
+      return { queue };
+    };
+    for (const redirect of redirects) {
       if (redirect.op === '2>&1') {
         stderr = stdout;
         continue;
@@ -171,7 +237,12 @@ export class Shell implements ShellState {
         stdout = stderr;
         continue;
       }
-      const target = (await expandWord(redirect.target!, ectx)).join(' ');
+      if (redirect.heredoc) {
+        const text = await this.expandText(redirect.heredoc.body, io, signal);
+        stdin = fromText(text);
+        continue;
+      }
+      const target = (await expandWord(redirect.target!, this.expandContext(io, signal))).join(' ');
       const path = resolvePath(this, target);
       if (redirect.op === '<') {
         const text = this.system.fs.readText(path);
@@ -179,10 +250,7 @@ export class Shell implements ShellState {
           io.stderr(`bfsh: ${target}: No such file or directory\n`);
           return 1;
         }
-        const queue = new InputQueue();
-        queue.push(text);
-        queue.push(null);
-        stdin = { queue };
+        stdin = fromText(text);
         continue;
       }
       if (this.system.fs.isDirectory(path)) {
@@ -201,16 +269,13 @@ export class Shell implements ShellState {
         isTerminal = false;
       }
     }
-
-    try {
-      return await this.dispatch(argv, assigned, { stdout, stderr, isTerminal }, stdin, signal, alone && isTerminal);
-    } finally {
-      for (const flush of flushes) flush();
-    }
+    return { io: { stdout, stderr, isTerminal }, input: stdin, flush: () => flushes.forEach((flush) => flush()) };
   }
 
   private async dispatch(argv: string[], assigned: Record<string, string>, io: ShellIO, input: JobInput, signal: AbortSignal, attachTerminal: boolean): Promise<number> {
     const [name, ...args] = argv as [string, ...string[]];
+    const fn = this.functions.get(name);
+    if (fn) return this.callFunction(fn, args, io, input, signal);
     const env = { ...this.env, ...assigned };
     const ctx: CommandContext = {
       args,
@@ -233,6 +298,29 @@ export class Shell implements ShellState {
     return this.spawnExternal(name, args, env, io, input, signal, attachTerminal);
   }
 
+  /** A shell function: its own positional parameters and `local` frame; `return` ends it. */
+  private async callFunction(fn: FunctionDefinition, args: string[], io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number> {
+    const savedPositional = this.positional;
+    this.positional = args;
+    const frame = new Map<string, string | undefined>();
+    this.localFrames.push(frame);
+    try {
+      let status = await runCompound(fn.body, this, io, input, signal);
+      if (this.flow?.kind === 'return') {
+        status = this.flow.status;
+        this.flow = undefined;
+      }
+      return status;
+    } finally {
+      this.localFrames.pop();
+      for (const [name, value] of frame) {
+        if (value === undefined) delete this.env[name];
+        else this.env[name] = value;
+      }
+      this.positional = savedPositional;
+    }
+  }
+
   private async spawnExternal(name: string, args: string[], env: Record<string, string>, io: ShellIO, input: JobInput, signal: AbortSignal, attachTerminal: boolean): Promise<number> {
     const size = attachTerminal ? this.options.terminalSize?.() : undefined;
     let child;

package/src/shell/expand.ts

@@ -6,7 +6,7 @@
  */
 import type { VirtualFileSystem } from '../vfs.js';
 import { join, normalizePath } from '../paths.js';
-import type { Segment, Word } from './parse.js';
+import type { Segment, Word } from './ast.js';
 
 export interface ExpandContext {
   fs: VirtualFileSystem;
@@ -49,12 +49,14 @@ async function paramValue(seg: Extract<Segment, { kind: 'var' }>, ctx: ExpandCon
 
 const GLOB_CHARS = /[*?[]/;
 
-function globToRegExp(pattern: string): RegExp {
+/** A glob as a regular expression. `slash: true` lets `*`/`?` cross `/` (a `case` pattern, not a path). */
+export function patternToRegExp(pattern: string, options: { slash?: boolean } = {}): RegExp {
+  const any = options.slash ? '.' : '[^/]';
   let source = '';
   for (let i = 0; i < pattern.length; i++) {
     const c = pattern[i]!;
-    if (c === '*') source += '[^/]*';
-    else if (c === '?') source += '[^/]';
+    if (c === '*') source += `${any}*`;
+    else if (c === '?') source += any;
     else if (c === '[') {
       const end = pattern.indexOf(']', i + 1);
       if (end < 0) source += '\\[';
@@ -64,7 +66,7 @@ function globToRegExp(pattern: string): RegExp {
       }
     } else source += c.replace(/[.+^${}()|\\]/g, '\\$&');
   }
-  return new RegExp(`^${source}$`);
+  return new RegExp(`^${source}$`, 's');
 }
 
 export function glob(fs: VirtualFileSystem, cwd: string, pattern: string): string[] {
@@ -80,7 +82,7 @@ export function glob(fs: VirtualFileSystem, cwd: string, pattern: string): strin
         if (fs.exists(candidate.startsWith('/') ? candidate : join(cwd, candidate))) next.push(candidate);
         continue;
       }
-      const re = globToRegExp(part);
+      const re = patternToRegExp(part);
       for (const name of fs.readdir(normalizePath(dir))) {
         if (name.startsWith('.') && !part.startsWith('.')) continue;
         if (re.test(name)) next.push(base ? (base.endsWith('/') ? base + name : `${base}/${name}`) : name);

package/src/shell/lineReader.ts

@@ -0,0 +1,46 @@
+/**
+ * Reading stdin one line at a time (`read`, `while read line`). A chunk can
+ * hold several lines, so what follows the first newline is kept per queue and
+ * served to the next read before any new chunk.
+ */
+import type { InputQueue } from '../system/terminal.js';
+
+const leftovers = new WeakMap<InputQueue, string>();
+const finished = new WeakSet<InputQueue>();
+
+/** The next line without its newline, or `null` at end of input. */
+export function readLine(queue: InputQueue, signal?: AbortSignal): Promise<string | null> {
+  let buffer = leftovers.get(queue) ?? '';
+  const take = (): string | null => {
+    const newline = buffer.indexOf('\n');
+    if (newline < 0) return null;
+    leftovers.set(queue, buffer.slice(newline + 1));
+    return buffer.slice(0, newline);
+  };
+  const ready = take();
+  if (ready !== null) return Promise.resolve(ready);
+  if (finished.has(queue)) {
+    leftovers.delete(queue);
+    return Promise.resolve(buffer ? buffer : null);
+  }
+  return new Promise((resolve) => {
+    const settle = (line: string | null) => {
+      stop();
+      signal?.removeEventListener('abort', onAbort);
+      resolve(line);
+    };
+    const onAbort = () => settle(null);
+    signal?.addEventListener('abort', onAbort);
+    const stop = queue.subscribe((chunk) => {
+      if (chunk === null) {
+        finished.add(queue);
+        leftovers.delete(queue);
+        settle(buffer ? buffer : null);
+        return;
+      }
+      buffer += chunk;
+      const line = take();
+      if (line !== null) settle(line);
+    });
+  });
+}

package/src/shell/packageManagers.ts

@@ -0,0 +1,75 @@
+/**
+ * `pnpm` and `yarn`, as front ends to the same installer and script runner
+ * `npm` uses: their commands are translated to npm's, so `pnpm add -D x`,
+ * `yarn dev` or `pnpm dlx create-vite` behave as a project's README expects.
+ * The tree is npm-style (hoisted `node_modules`, `package-lock.json`);
+ * `pnpm-lock.yaml` and `yarn.lock` are not read.
+ */
+import { join } from '../paths.js';
+import { findPackageScope } from '../node/resolve.js';
+import { findExecutable } from '../system/commands.js';
+import type { CommandContext } from './context.js';
+import type { JobInput, Shell } from './exec.js';
+import { npmCommand, npxCommand } from './npm.js';
+
+const VERSIONS = { pnpm: '9.12.0', yarn: '1.22.22' } as const;
+
+type Manager = keyof typeof VERSIONS;
+
+const INSTALL = new Set(['install', 'i']);
+const REMOVE = new Set(['remove', 'rm', 'uninstall', 'un']);
+const NPM_PASSTHROUGH = new Set(['test', 't', 'start', 'init', 'ls', 'list', 'run', 'run-script']);
+
+function hasScript(ctx: CommandContext, name: string): boolean {
+  const dir = findPackageScope(ctx.fs, ctx.cwd)?.dir ?? ctx.cwd;
+  try {
+    const pkg = JSON.parse(ctx.fs.readText(join(dir, 'package.json')) ?? '{}') as { scripts?: Record<string, string> };
+    return !!pkg.scripts?.[name];
+  } catch {
+    return false;
+  }
+}
+
+/** Map `--dev` / `-D` to npm's flag; drop flags npm has no use for here. */
+function addFlags(args: string[]): string[] {
+  return args.flatMap((a) => (a === '--dev' || a === '-D' || a === '--save-dev' ? ['--save-dev'] : a === '--frozen-lockfile' || a === '--immutable' || a === '--prefer-offline' ? [] : [a]));
+}
+
+/** The npm (or npx) command line a pnpm/yarn command stands for, or a message when there is none. */
+export function translate(manager: Manager, args: string[], ctx: CommandContext): { tool: 'npm' | 'npx'; args: string[] } | { version: string } | { error: string } {
+  const [sub, ...rest] = args;
+  if (sub === undefined) return { tool: 'npm', args: ['install'] };
+  if (sub === '-v' || sub === '--version') return { version: VERSIONS[manager] };
+  if (INSTALL.has(sub)) {
+    // `yarn install x` is an error in yarn; treat any operands as `add` for both.
+    const flags = addFlags(rest);
+    return { tool: 'npm', args: ['install', ...flags] };
+  }
+  if (sub === 'add') return { tool: 'npm', args: ['install', ...addFlags(rest)] };
+  if (REMOVE.has(sub)) return { tool: 'npm', args: ['uninstall', ...rest] };
+  if (sub === 'dlx' || sub === 'exec' || (manager === 'pnpm' && sub === 'x')) return { tool: 'npx', args: rest };
+  if (NPM_PASSTHROUGH.has(sub)) return { tool: 'npm', args: [sub, ...rest] };
+  // `pnpm dev` / `yarn build`: a script of that name, else an installed bin.
+  if (hasScript(ctx, sub)) return { tool: 'npm', args: ['run', sub, ...(rest.length ? ['--', ...rest] : [])] };
+  if (findExecutable(ctx.fs, sub, ctx.cwd, { PATH: '' })) return { tool: 'npx', args: [sub, ...rest] };
+  return { error: `${manager}: no script or command named "${sub}"` };
+}
+
+function frontEnd(manager: Manager) {
+  return async (ctx: CommandContext, shell: Shell, input: JobInput): Promise<number> => {
+    const plan = translate(manager, ctx.args, ctx);
+    if ('version' in plan) {
+      ctx.io.stdout(`${plan.version}\n`);
+      return 0;
+    }
+    if ('error' in plan) {
+      ctx.io.stderr(`${plan.error}\n`);
+      return 1;
+    }
+    const next = { ...ctx, args: plan.args, name: plan.tool };
+    return plan.tool === 'npm' ? npmCommand(next, shell, input) : npxCommand(next, shell, input);
+  };
+}
+
+export const pnpmCommand = frontEnd('pnpm');
+export const yarnCommand = frontEnd('yarn');