@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/shell/builtins.ts

@@ -0,0 +1,141 @@
+/**
+ * Builtins that change or inspect the shell itself (cd, export, exit…), plus
+ * the command tables the executor dispatches on.
+ */
+
+import { findExecutable } from '../system/commands.js';
+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';
+
+/** The slice of the shell a builtin may change. */
+export interface ShellState {
+  cwd: string;
+  env: Record<string, string>;
+  history: string[];
+  lastStatus: number;
+  /** Set by `exit`: the shell stops after the current command. */
+  exitRequested?: number;
+  /** Run a script in this shell (for `source`). */
+  run(source: string): Promise<number>;
+}
+
+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,
+  true: trueCommand,
+  false: falseCommand,
+};
+
+/** Programs the runtime provides besides coreutils (reported by `which`/`type`). */
+export const SYSTEM_PROGRAMS = ['node', 'npm', 'npx', 'jsh', 'sh', 'bash'];
+
+const HELP = `jsh — 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
+  Text:      echo, printf, head, tail, grep, wc, env, clear, sleep, basename, dirname
+  Node:      node <file>, npm install|ci|run|start|test, npx <bin>
+  Syntax:    'quotes' "\$VARS" a && b || c; a | b > out.txt >> log 2>&1 2> err; FOO=bar cmd; $(cmd); *.js
+
+`;
+
+export const BUILTINS: Record<string, Builtin> = {
+  async cd(ctx, shell) {
+    const home = shell.env.HOME && ctx.fs.isDirectory(shell.env.HOME) ? shell.env.HOME : '/';
+    const target = ctx.args[0] === '-' ? shell.env.OLDPWD ?? shell.cwd : ctx.args[0] ?? home;
+    const path = resolvePath(ctx, target);
+    if (!ctx.fs.isDirectory(path)) {
+      ctx.io.stderr(`cd: ${ctx.fs.isFile(path) ? 'not a directory' : 'no such file or directory'}: ${target}\n`);
+      return 1;
+    }
+    shell.env.OLDPWD = shell.cwd;
+    shell.cwd = path;
+    shell.env.PWD = path;
+    if (ctx.args[0] === '-') ctx.io.stdout(path + '\n');
+    return 0;
+  },
+  async export(ctx, shell) {
+    if (!ctx.args.length) {
+      ctx.io.stdout(Object.entries(shell.env).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\n');
+      return 0;
+    }
+    for (const arg of ctx.args) {
+      const eq = arg.indexOf('=');
+      if (eq > 0) shell.env[arg.slice(0, eq)] = arg.slice(eq + 1);
+      else if (!(arg in shell.env)) shell.env[arg] = '';
+    }
+    return 0;
+  },
+  async unset(ctx, shell) {
+    for (const name of ctx.args) delete shell.env[name];
+    return 0;
+  },
+  async exit(ctx, shell) {
+    const code = ctx.args[0] === undefined ? shell.lastStatus : Number(ctx.args[0]);
+    shell.exitRequested = Number.isFinite(code) ? code & 255 : 2;
+    return shell.exitRequested;
+  },
+  async source(ctx, shell) {
+    const file = ctx.args[0];
+    if (!file) {
+      ctx.io.stderr('source: filename argument required\n');
+      return 2;
+    }
+    const text = ctx.fs.readText(resolvePath(ctx, file));
+    if (text === undefined) {
+      ctx.io.stderr(`source: ${file}: No such file or directory\n`);
+      return 1;
+    }
+    return shell.run(text);
+  },
+  async history(ctx, shell) {
+    ctx.io.stdout(shell.history.map((line, i) => `${String(i + 1).padStart(5)}  ${line}`).join('\n') + (shell.history.length ? '\n' : ''));
+    return 0;
+  },
+  async help(ctx) {
+    ctx.io.stdout(HELP);
+    return 0;
+  },
+  async which(ctx) {
+    let status = 0;
+    for (const name of ctx.args.filter((a) => !a.startsWith('-'))) {
+      if (name in COREUTILS || SYSTEM_PROGRAMS.includes(name)) ctx.io.stdout(`/usr/local/bin/${name}\n`);
+      else if (name in BUILTINS) ctx.io.stdout(`${name}: shell built-in command\n`);
+      else {
+        const file = findExecutable(ctx.fs, name, ctx.cwd, ctx.env);
+        if (file) ctx.io.stdout(file + '\n');
+        else {
+          ctx.io.stderr(`${name} not found\n`);
+          status = 1;
+        }
+      }
+    }
+    return status;
+  },
+  async type(ctx) {
+    let status = 0;
+    for (const name of ctx.args) {
+      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);
+        if (file) ctx.io.stdout(`${name} is ${file}\n`);
+        else {
+          ctx.io.stderr(`type: ${name}: not found\n`);
+          status = 1;
+        }
+      }
+    }
+    return status;
+  },
+  async set() {
+    return 0; // options (-e, -x) are accepted and ignored
+  },
+};
+BUILTINS['.'] = BUILTINS.source!;
+BUILTINS[':'] = async () => 0;
+

package/src/shell/context.ts

@@ -0,0 +1,89 @@
+/**
+ * What a shell command runs with. Builtins get the shell's own state (to `cd`
+ * and `export`); coreutils only need IO, cwd and the file system, which is why
+ * they can also be spawned as standalone programs (`spawn('ls', ['-la'])`).
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import type { Program, System } from '../system/types.js';
+import { InputQueue } from '../system/terminal.js';
+import { join, normalizePath } from '../paths.js';
+
+export interface CommandIO {
+  stdout(text: string): void;
+  stderr(text: string): void;
+  stdin: InputQueue;
+  /** stdout is a terminal (colours, `clear`). */
+  isTerminal: boolean;
+}
+
+export interface CommandContext {
+  /** Arguments after the command name. */
+  args: string[];
+  /** The command name as typed (for messages). */
+  name: string;
+  cwd: string;
+  env: Record<string, string>;
+  fs: VirtualFileSystem;
+  system: System;
+  io: CommandIO;
+  signal: AbortSignal;
+}
+
+export type Command = (ctx: CommandContext) => Promise<number>;
+
+export function resolvePath(ctx: { cwd: string; env: Record<string, string> }, path: string): string {
+  if (path === '~' || path.startsWith('~/')) return join(ctx.env.HOME ?? '/home/user', path.slice(1));
+  return path.startsWith('/') ? normalizePath(path) : join(ctx.cwd, path);
+}
+
+/** Split `-abc` style flags from operands (`--` ends flags). */
+export function parseFlags(args: string[], withValue: string[] = []): { flags: Set<string>; values: Record<string, string>; operands: string[] } {
+  const flags = new Set<string>();
+  const values: Record<string, string> = {};
+  const operands: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--') {
+      operands.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--') && arg.length > 2) {
+      const [k, v] = arg.slice(2).split('=', 2) as [string, string | undefined];
+      if (v !== undefined) values[k] = v;
+      else if (withValue.includes(k)) values[k] = args[++i] ?? '';
+      else flags.add(k);
+    } else if (arg.startsWith('-') && arg.length > 1 && !/^-\d/.test(arg)) {
+      for (let j = 1; j < arg.length; j++) {
+        const f = arg[j]!;
+        if (withValue.includes(f)) {
+          values[f] = arg.slice(j + 1) || args[++i] || '';
+          break;
+        }
+        flags.add(f);
+      }
+    } else operands.push(arg);
+  }
+  return { flags, values, operands };
+}
+
+/** Run a coreutil as a standalone program (spawned directly rather than from the shell). */
+export function asProgram(command: Command, name: string): Program {
+  return async (ctx) => {
+    const stdin = new InputQueue();
+    const stop = ctx.io.onStdin((chunk) => stdin.push(chunk));
+    try {
+      return await command({
+        args: ctx.args,
+        name,
+        cwd: ctx.cwd,
+        env: ctx.env,
+        fs: ctx.system.fs,
+        system: ctx.system,
+        io: { stdout: ctx.io.stdout, stderr: ctx.io.stderr, stdin, isTerminal: !!ctx.io.terminal },
+        signal: ctx.signal,
+      });
+    } finally {
+      stop();
+    }
+  };
+}

package/src/shell/devHandoff.ts

@@ -0,0 +1,49 @@
+/**
+ * Dev-server handoff. `vite`, `vite dev`, `react-scripts start` (what `npm run
+ * 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,
+ * which is exactly what a host waiting on `npm run dev` expects.
+ */
+import type { CommandContext } from './context.js';
+
+interface Handoff {
+  tool: string;
+  defaultPort: number;
+}
+
+/** Does this command line start a dev server we hand off? */
+export function matchDevServer(argv: string[]): Handoff | undefined {
+  const [command, ...rest] = argv;
+  const sub = rest[0] !== undefined && !rest[0].startsWith('-') ? rest[0] : undefined;
+  if (command === 'vite' && (sub === undefined || sub === 'dev' || sub === 'serve')) return { tool: 'vite', defaultPort: 5173 };
+  if ((command === 'react-scripts' || command === 'craco') && sub === 'start') return { tool: 'react-scripts', defaultPort: 3000 };
+  return undefined;
+}
+
+function portOf(argv: string[], fallback: number, env: Record<string, string>): number {
+  const at = argv.findIndex((a) => a === '--port' || a.startsWith('--port='));
+  const value = at < 0 ? env.PORT : argv[at]!.includes('=') ? argv[at]!.split('=')[1] : argv[at + 1];
+  const port = Number(value);
+  return Number.isInteger(port) && port > 0 ? port : fallback;
+}
+
+export async function runDevServerHandoff(ctx: CommandContext, argv: string[], handoff: Handoff): Promise<number> {
+  const url = ctx.system.previewUrl;
+  if (!url) {
+    ctx.io.stderr(`${handoff.tool}: no in-browser preview is attached to this runtime, so there is nothing to serve.\n`);
+    return 1;
+  }
+  const port = portOf(argv, handoff.defaultPort, ctx.env);
+  const banner = handoff.tool === 'vite'
+    ? `\n  VITE (BuilderForce in-browser dev server)  ready\n\n  ➜  Local:   ${url}\n\n`
+    : `\nCompiled successfully!\n\nYou can now view the app in the browser.\n\n  Local:  ${url}\n\n`;
+  ctx.io.stdout(banner);
+  ctx.system.announceServer(port, url);
+  await new Promise<void>((resolve) => {
+    if (ctx.signal.aborted) resolve();
+    ctx.signal.addEventListener('abort', () => resolve());
+  });
+  return 130;
+}

package/src/shell/exec.ts

@@ -0,0 +1,268 @@
+/**
+ * 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,
+ * 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 { expandWord, expandWords, type ExpandContext } from './expand.js';
+import { BUILTINS, COREUTILS, type ShellState } from './builtins.js';
+import { resolvePath, type CommandContext } from './context.js';
+import { matchDevServer, runDevServerHandoff } from './devHandoff.js';
+
+export interface ShellIO {
+  stdout(text: string): void;
+  stderr(text: string): void;
+  /** stdout is a terminal. */
+  isTerminal: boolean;
+}
+
+/** A job's stdin: a queue, and (interactive) a raw keystroke tap for a terminal-attached child. */
+export interface JobInput {
+  queue: InputQueue;
+  /** Route raw terminal input straight to `sink` (a child with its own line discipline), or back to the queue. */
+  setRawSink?(sink: ((data: string) => void) | undefined): void;
+}
+
+/** In-process commands with access to the shell (npm runs scripts through it). */
+export type ShellCommand = (ctx: CommandContext, shell: Shell, input: JobInput) => Promise<number>;
+
+export interface ShellOptions {
+  system: System;
+  cwd: string;
+  env: Record<string, string>;
+  positional?: string[];
+  /** The terminal size, when attached to one. */
+  terminalSize?: () => { cols: number; rows: number } | undefined;
+  commands?: Record<string, ShellCommand>;
+}
+
+let nextShellPid = 500;
+
+export class Shell implements ShellState {
+  cwd: string;
+  env: Record<string, string>;
+  lastStatus = 0;
+  history: string[] = [];
+  exitRequested?: number;
+  readonly pid = nextShellPid++;
+  readonly system: System;
+  private readonly positional: string[];
+  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 ?? [];
+  }
+
+  /** A child shell for `npm run` / subshells: same IO, its own cwd and environment. */
+  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 });
+  }
+
+  /** Parse and run `source`. Syntax errors print and return 2. */
+  async exec(source: string, io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number> {
+    let script: Script;
+    try {
+      script = parse(source);
+    } catch (error) {
+      if (!(error instanceof ShellSyntaxError)) throw error;
+      io.stderr(`jsh: ${error.message}\n`);
+      this.lastStatus = 2;
+      return 2;
+    }
+    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();
+      }
+    } finally {
+      this.current = previous;
+    }
+    if (signal.aborted && this.lastStatus === 0) this.lastStatus = 130;
+    return this.exitRequested ?? this.lastStatus;
+  }
+
+  /** `source` and friends: run in this shell with the current job's IO. */
+  run(source: string): Promise<number> {
+    const job = this.current;
+    if (!job) throw new Error('Shell.run outside a job');
+    return this.exec(source, job.io, job.input, job.signal);
+  }
+
+  private expandContext(io: ShellIO, signal: AbortSignal): ExpandContext {
+    return {
+      fs: this.system.fs,
+      cwd: this.cwd,
+      get: (name) => this.env[name],
+      set: (name, value) => void (this.env[name] = value),
+      positional: this.positional,
+      lastStatus: this.lastStatus,
+      pid: this.pid,
+      substitute: async (source) => {
+        let out = '';
+        const sub = this.fork({});
+        await sub.exec(source, { stdout: (t) => (out += t), stderr: io.stderr, isTerminal: false }, { queue: emptyInput() }, signal);
+        return out;
+      },
+    };
+  }
+
+  private async runPipeline(pipeline: Pipeline, io: ShellIO, input: JobInput, signal: AbortSignal): Promise<number> {
+    const count = pipeline.commands.length;
+    const pipes = Array.from({ length: count - 1 }, () => new InputQueue());
+    const statuses = await Promise.all(
+      pipeline.commands.map(async (command, i) => {
+        const stdin: JobInput = i === 0 ? input : { queue: pipes[i - 1]! };
+        const stdout = i === count - 1 ? io.stdout : (text: string) => pipes[i]!.push(text);
+        const stageIO: ShellIO = { stdout, stderr: io.stderr, isTerminal: io.isTerminal && i === count - 1 };
+        try {
+          return await this.runCommand(command, stageIO, stdin, signal, count === 1);
+        } finally {
+          if (i < count - 1) pipes[i]!.push(null);
+        }
+      }),
+    );
+    const status = statuses[statuses.length - 1]!;
+    return pipeline.negate ? (status === 0 ? 1 : 0) : status;
+  }
+
+  private async runCommand(node: CommandNode, 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> = {};
+    for (const { name, value } of node.assignments) assigned[name] = (await expandWord(value, ectx, { split: false, glob: false })).join('');
+    if (!argv.length) {
+      Object.assign(this.env, assigned);
+      return 0;
+    }
+
+    // Redirects.
+    let stdout = io.stdout;
+    let stderr = io.stderr;
+    let stdin = input;
+    let isTerminal = io.isTerminal;
+    const flushes: Array<() => void> = [];
+    for (const redirect of node.redirects) {
+      if (redirect.op === '2>&1') {
+        stderr = stdout;
+        continue;
+      }
+      if (redirect.op === '>&2') {
+        stdout = stderr;
+        continue;
+      }
+      const target = (await expandWord(redirect.target!, ectx)).join(' ');
+      const path = resolvePath(this, target);
+      if (redirect.op === '<') {
+        const text = this.system.fs.readText(path);
+        if (text === undefined) {
+          io.stderr(`jsh: ${target}: No such file or directory\n`);
+          return 1;
+        }
+        const queue = new InputQueue();
+        queue.push(text);
+        queue.push(null);
+        stdin = { queue };
+        continue;
+      }
+      if (this.system.fs.isDirectory(path)) {
+        io.stderr(`jsh: ${target}: Is a directory\n`);
+        return 1;
+      }
+      const append = redirect.op === '>>' || redirect.op === '2>>';
+      let content = append ? this.system.fs.readText(path) ?? '' : '';
+      this.system.fs.writeFile(path, content);
+      const sink = (text: string) => void (content += text);
+      flushes.push(() => this.system.fs.writeFile(path, content));
+      if (redirect.op === '2>' || redirect.op === '2>>') stderr = sink;
+      else if (redirect.op === '&>') stdout = stderr = sink;
+      else {
+        stdout = sink;
+        isTerminal = false;
+      }
+    }
+
+    try {
+      return await this.dispatch(argv, assigned, { stdout, stderr, isTerminal }, stdin, signal, alone && isTerminal);
+    } finally {
+      for (const flush of flushes) 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 env = { ...this.env, ...assigned };
+    const ctx: CommandContext = {
+      args,
+      name,
+      cwd: this.cwd,
+      env,
+      fs: this.system.fs,
+      system: this.system,
+      io: { stdout: io.stdout, stderr: io.stderr, stdin: input.queue, isTerminal: io.isTerminal },
+      signal,
+    };
+    const builtin = BUILTINS[name];
+    if (builtin) return builtin(ctx, this);
+    const command = this.options.commands?.[name];
+    if (command) return command(ctx, this, input);
+    const handoff = matchDevServer(argv);
+    if (handoff) return runDevServerHandoff(ctx, argv, handoff);
+    const coreutil = COREUTILS[name];
+    if (coreutil) return coreutil(ctx);
+    return this.spawnExternal(name, args, env, io, input, signal, attachTerminal);
+  }
+
+  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;
+    try {
+      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`);
+      return 127;
+    }
+    child.onStdout(io.stdout);
+    child.onStderr(io.stderr);
+    let stop: (() => void) | undefined;
+    if (size && input.setRawSink) input.setRawSink((data) => child.write(data));
+    else stop = input.queue.subscribe((chunk) => (chunk === null ? child.closeStdin() : child.write(chunk)));
+    const onAbort = () => child.kill(typeof signal.reason === 'string' ? signal.reason : 'SIGINT');
+    if (signal.aborted) onAbort();
+    signal.addEventListener('abort', onAbort);
+    try {
+      return await child.exit;
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+      if (size && input.setRawSink) input.setRawSink(undefined);
+      stop?.();
+    }
+  }
+}
+
+function emptyInput(): InputQueue {
+  const queue = new InputQueue();
+  queue.push(null);
+  return queue;
+}

package/src/shell/expand.ts

@@ -0,0 +1,145 @@
+/**
+ * Word expansion, in sh order: tilde, parameters (`$X`, `${X:-d}`, `$?`, `$1`),
+ * command substitution, field splitting of UNQUOTED results, then pathname
+ * globbing (`*`, `?`, `[…]`) of unquoted patterns. A glob with no match stays
+ * literal, as in bash without `nullglob`.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import { join, normalizePath } from '../paths.js';
+import type { Segment, Word } from './parse.js';
+
+export interface ExpandContext {
+  fs: VirtualFileSystem;
+  cwd: string;
+  get(name: string): string | undefined;
+  set(name: string, value: string): void;
+  positional: string[];
+  lastStatus: number;
+  pid: number;
+  /** Run `$(…)` and return its stdout. */
+  substitute(source: string): Promise<string>;
+}
+
+async function paramValue(seg: Extract<Segment, { kind: 'var' }>, ctx: ExpandContext): Promise<string> {
+  let value: string | undefined;
+  switch (seg.name) {
+    case '?': value = String(ctx.lastStatus); break;
+    case '$': value = String(ctx.pid); break;
+    case '#': value = String(ctx.positional.length); break;
+    case '@':
+    case '*': value = ctx.positional.join(' '); break;
+    case '!': value = ''; break;
+    case '0': value = 'jsh'; break;
+    default: value = /^\d$/.test(seg.name) ? ctx.positional[Number(seg.name) - 1] : ctx.get(seg.name);
+  }
+  if (!seg.op) return value ?? '';
+  const arg = async () => (await expandWord(seg.arg ?? [], ctx, { split: false, glob: false })).join(' ');
+  switch (seg.op) {
+    case ':-': return value ? value : arg();
+    case '-': return value !== undefined ? value : arg();
+    case ':+': return value ? arg() : '';
+    case ':=': {
+      if (value) return value;
+      const fallback = await arg();
+      ctx.set(seg.name, fallback);
+      return fallback;
+    }
+  }
+}
+
+const GLOB_CHARS = /[*?[]/;
+
+function globToRegExp(pattern: string): RegExp {
+  let source = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]!;
+    if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else if (c === '[') {
+      const end = pattern.indexOf(']', i + 1);
+      if (end < 0) source += '\\[';
+      else {
+        source += '[' + pattern.slice(i + 1, end).replace(/^!/, '^').replace(/\\/g, '\\\\') + ']';
+        i = end;
+      }
+    } else source += c.replace(/[.+^${}()|\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+export function glob(fs: VirtualFileSystem, cwd: string, pattern: string): string[] {
+  const absolute = pattern.startsWith('/');
+  const parts = pattern.split('/').filter((p, i) => p || i === 0);
+  let matches: string[] = [absolute ? '/' : ''];
+  for (const part of absolute ? parts.slice(1) : parts) {
+    const next: string[] = [];
+    for (const base of matches) {
+      const dir = base ? (base.startsWith('/') ? base : join(cwd, base)) : cwd;
+      if (!GLOB_CHARS.test(part)) {
+        const candidate = base ? (base.endsWith('/') ? base + part : `${base}/${part}`) : part;
+        if (fs.exists(candidate.startsWith('/') ? candidate : join(cwd, candidate))) next.push(candidate);
+        continue;
+      }
+      const re = globToRegExp(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);
+      }
+    }
+    matches = next;
+  }
+  return matches.sort();
+}
+
+/** Expand one word into zero or more fields. */
+export async function expandWord(word: Word, ctx: ExpandContext, options: { split?: boolean; glob?: boolean } = {}): Promise<string[]> {
+  const split = options.split ?? true;
+  const fields: string[] = [''];
+  let started = false; // a quoted part (even empty) makes the word a field
+  let globbable = false;
+  const append = (text: string) => {
+    fields[fields.length - 1] += text;
+  };
+  for (const seg of word) {
+    if (seg.kind === 'tilde') {
+      append(ctx.get('HOME') ?? '/home/user');
+      started = true;
+      continue;
+    }
+    if (seg.kind === 'text') {
+      append(seg.value);
+      if (seg.quoted || seg.value) started = true;
+      if (!seg.quoted && GLOB_CHARS.test(seg.value)) globbable = true;
+      continue;
+    }
+    const value = seg.kind === 'var' ? await paramValue(seg, ctx) : (await ctx.substitute(seg.source)).replace(/\n+$/, '');
+    if (seg.quoted || !split) {
+      append(value);
+      started = true;
+      continue;
+    }
+    const pieces = value.split(/[ \t\n]+/);
+    pieces.forEach((piece, index) => {
+      if (index > 0 && (fields[fields.length - 1] || started)) fields.push('');
+      if (piece) {
+        append(piece);
+        started = true;
+      }
+    });
+  }
+  const result = fields.filter((f, i) => f !== '' || (started && i === fields.length - 1 && fields.length === 1));
+  if (!started && result.every((f) => !f)) return [];
+  if (options.glob === false || !globbable) return result;
+  return result.flatMap((field) => {
+    if (!GLOB_CHARS.test(field)) return [field];
+    const hits = glob(ctx.fs, ctx.cwd, field);
+    return hits.length ? hits : [field];
+  });
+}
+
+/** Expand every word of a command line. */
+export async function expandWords(words: Word[], ctx: ExpandContext): Promise<string[]> {
+  const out: string[] = [];
+  for (const word of words) out.push(...(await expandWord(word, ctx)));
+  return out;
+}