@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/shell/fileCommands.ts

@@ -0,0 +1,206 @@
+/**
+ * File coreutils over the VFS: ls, cat, mkdir, rm, cp, mv, touch, pwd. Errors
+ * read like GNU coreutils (`rm: cannot remove 'x': No such file or directory`)
+ * because people (and agents) pattern-match on them.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+import { basename, dirname, join } from '../paths.js';
+import { parseFlags, resolvePath, type Command } from './context.js';
+
+const encoder = new TextEncoder();
+const sizeOf = (fs: VirtualFileSystem, path: string) => {
+  const c = fs.readFile(path);
+  return c === undefined ? 4096 : typeof c === 'string' ? encoder.encode(c).length : c.length;
+};
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function lsDate(ms: number): string {
+  const d = new Date(ms);
+  return `${MONTHS[d.getMonth()]} ${String(d.getDate()).padStart(2)} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+
+export const ls: Command = async (ctx) => {
+  const { flags, operands } = parseFlags(ctx.args);
+  const all = flags.has('a') || flags.has('A');
+  const long = flags.has('l');
+  const one = flags.has('1') || !ctx.io.isTerminal;
+  const targets = operands.length ? operands : ['.'];
+  let status = 0;
+  const colour = (name: string, dir: boolean) => (ctx.io.isTerminal && dir ? `\x1b[1;34m${name}\x1b[0m` : name);
+  const render = (dir: string, names: string[]) => {
+    if (long) {
+      const lines = names.map((name) => {
+        const path = name === '.' ? dir : name === '..' ? dirname(dir) : join(dir, name);
+        const isDir = ctx.fs.isDirectory(path);
+        const size = isDir ? 4096 : sizeOf(ctx.fs, path);
+        return `${isDir ? 'drwxr-xr-x' : '-rw-r--r--'} 1 user user ${String(size).padStart(8)} ${lsDate(ctx.fs.mtime(path) ?? Date.now())} ${colour(name, isDir)}`;
+      });
+      return lines.length ? `total ${names.length}\n${lines.join('\n')}\n` : 'total 0\n';
+    }
+    const shown = names.map((n) => colour(n, ctx.fs.isDirectory(join(dir, n))));
+    return shown.length ? shown.join(one ? '\n' : '  ') + '\n' : '';
+  };
+  for (const [index, target] of targets.entries()) {
+    const path = resolvePath(ctx, target);
+    if (ctx.fs.isFile(path)) {
+      ctx.io.stdout(render(dirname(path), [basename(path)]).replace(basename(path), target));
+      continue;
+    }
+    if (!ctx.fs.isDirectory(path)) {
+      ctx.io.stderr(`ls: cannot access '${target}': No such file or directory\n`);
+      status = 2;
+      continue;
+    }
+    let names = ctx.fs.readdir(path).filter((n) => all || !n.startsWith('.'));
+    if (flags.has('a')) names = ['.', '..', ...names];
+    if (targets.length > 1) ctx.io.stdout(`${index ? '\n' : ''}${target}:\n`);
+    ctx.io.stdout(render(path, names));
+  }
+  return status;
+};
+
+export const cat: Command = async (ctx) => {
+  const { operands } = parseFlags(ctx.args);
+  if (!operands.length || (operands.length === 1 && operands[0] === '-')) {
+    ctx.io.stdout(await ctx.io.stdin.readAll());
+    return 0;
+  }
+  let status = 0;
+  for (const file of operands) {
+    const path = resolvePath(ctx, file);
+    if (ctx.fs.isDirectory(path)) {
+      ctx.io.stderr(`cat: ${file}: Is a directory\n`);
+      status = 1;
+    } else if (!ctx.fs.isFile(path)) {
+      ctx.io.stderr(`cat: ${file}: No such file or directory\n`);
+      status = 1;
+    } else ctx.io.stdout(ctx.fs.readText(path) ?? '');
+  }
+  return status;
+};
+
+export const mkdir: Command = async (ctx) => {
+  const { flags, operands } = parseFlags(ctx.args, ['m']);
+  if (!operands.length) {
+    ctx.io.stderr('mkdir: missing operand\n');
+    return 1;
+  }
+  let status = 0;
+  for (const dir of operands) {
+    const path = resolvePath(ctx, dir);
+    if (ctx.fs.exists(path)) {
+      if (flags.has('p') && ctx.fs.isDirectory(path)) continue;
+      ctx.io.stderr(`mkdir: cannot create directory '${dir}': File exists\n`);
+      status = 1;
+    } else if (!flags.has('p') && !ctx.fs.isDirectory(dirname(path))) {
+      ctx.io.stderr(`mkdir: cannot create directory '${dir}': No such file or directory\n`);
+      status = 1;
+    } else ctx.fs.mkdir(path);
+  }
+  return status;
+};
+
+export const rm: Command = async (ctx) => {
+  const { flags, operands } = parseFlags(ctx.args);
+  const recursive = flags.has('r') || flags.has('R') || flags.has('recursive');
+  const force = flags.has('f') || flags.has('force');
+  if (!operands.length && !force) {
+    ctx.io.stderr('rm: missing operand\n');
+    return 1;
+  }
+  let status = 0;
+  for (const target of operands) {
+    const path = resolvePath(ctx, target);
+    if (path === '/') {
+      ctx.io.stderr(`rm: it is dangerous to operate recursively on '/'\n`);
+      status = 1;
+    } else if (!ctx.fs.exists(path)) {
+      if (!force) {
+        ctx.io.stderr(`rm: cannot remove '${target}': No such file or directory\n`);
+        status = 1;
+      }
+    } else if (ctx.fs.isDirectory(path) && !recursive) {
+      ctx.io.stderr(`rm: cannot remove '${target}': Is a directory\n`);
+      status = 1;
+    } else ctx.fs.rm(path);
+  }
+  return status;
+};
+
+function copyTree(fs: VirtualFileSystem, from: string, to: string): void {
+  if (fs.isFile(from)) {
+    const c = fs.readFile(from)!;
+    fs.writeFile(to, typeof c === 'string' ? c : c.slice());
+    return;
+  }
+  fs.mkdir(to);
+  for (const name of fs.readdir(from)) copyTree(fs, join(from, name), join(to, name));
+}
+
+/** cp and mv share argument handling: `SRC… DEST` where DEST may be a directory. */
+function transfer(verb: 'cp' | 'mv'): Command {
+  return async (ctx) => {
+    const { flags, operands } = parseFlags(ctx.args);
+    if (operands.length < 2) {
+      ctx.io.stderr(`${verb}: missing destination file operand\n`);
+      return 1;
+    }
+    const dest = resolvePath(ctx, operands[operands.length - 1]!);
+    const sources = operands.slice(0, -1);
+    const destIsDir = ctx.fs.isDirectory(dest);
+    if (sources.length > 1 && !destIsDir) {
+      ctx.io.stderr(`${verb}: target '${operands[operands.length - 1]}' is not a directory\n`);
+      return 1;
+    }
+    let status = 0;
+    for (const source of sources) {
+      const from = resolvePath(ctx, source);
+      const to = destIsDir ? join(dest, basename(from)) : dest;
+      if (!ctx.fs.exists(from)) {
+        ctx.io.stderr(`${verb}: cannot stat '${source}': No such file or directory\n`);
+        status = 1;
+        continue;
+      }
+      if (verb === 'cp' && ctx.fs.isDirectory(from) && !(flags.has('r') || flags.has('R') || flags.has('a'))) {
+        ctx.io.stderr(`cp: -r not specified; omitting directory '${source}'\n`);
+        status = 1;
+        continue;
+      }
+      if (to === from || to.startsWith(from + '/')) {
+        ctx.io.stderr(`${verb}: cannot ${verb === 'cp' ? 'copy' : 'move'} '${source}' into itself\n`);
+        status = 1;
+        continue;
+      }
+      if (ctx.fs.isFile(to) && ctx.fs.isDirectory(from)) {
+        ctx.io.stderr(`${verb}: cannot overwrite non-directory '${to}' with directory '${source}'\n`);
+        status = 1;
+        continue;
+      }
+      if (ctx.fs.isFile(to)) ctx.fs.rm(to);
+      copyTree(ctx.fs, from, to);
+      if (verb === 'mv') ctx.fs.rm(from);
+    }
+    return status;
+  };
+}
+
+export const cp = transfer('cp');
+export const mv = transfer('mv');
+
+export const touch: Command = async (ctx) => {
+  const { operands } = parseFlags(ctx.args);
+  let status = 0;
+  for (const file of operands) {
+    const path = resolvePath(ctx, file);
+    if (!ctx.fs.isDirectory(dirname(path))) {
+      ctx.io.stderr(`touch: cannot touch '${file}': No such file or directory\n`);
+      status = 1;
+    } else if (!ctx.fs.isDirectory(path)) ctx.fs.writeFile(path, ctx.fs.readFile(path) ?? '');
+  }
+  return status;
+};
+
+export const pwd: Command = async (ctx) => {
+  ctx.io.stdout(ctx.cwd + '\n');
+  return 0;
+};

package/src/shell/lineEditor.ts

@@ -0,0 +1,233 @@
+/**
+ * Readline-style line editing for an xterm.js terminal in raw mode: insert and
+ * delete at the cursor, ←/→, Home/End (and Ctrl-A/E), ↑/↓ history, Ctrl-U/K/W,
+ * Ctrl-L, Tab completion, Ctrl-C (cancel the line) and Ctrl-D (end of input).
+ *
+ * `feed` consumes input up to the first completed line and hands back the rest,
+ * so a pasted block of several commands runs them one at a time.
+ */
+
+export type EditorEvent = { type: 'line'; line: string } | { type: 'interrupt' } | { type: 'eof' };
+
+export interface LineEditorOptions {
+  write(text: string): void;
+  history: string[];
+  /** Candidates for the word ending at the cursor (`word` is that word). */
+  complete?(line: string, word: string): string[];
+}
+
+const KEYS: Array<[RegExp, string]> = [
+  [/^\x1b\[(?:1;\d)?A/, 'up'],
+  [/^\x1b\[(?:1;\d)?B/, 'down'],
+  [/^\x1b\[1;[35]C|^\x1bf/, 'wordRight'],
+  [/^\x1b\[1;[35]D|^\x1bb/, 'wordLeft'],
+  [/^\x1b\[C|^\x1bOC/, 'right'],
+  [/^\x1b\[D|^\x1bOD/, 'left'],
+  [/^\x1b\[(?:H|1~|7~)|^\x1bOH/, 'home'],
+  [/^\x1b\[(?:F|4~|8~)|^\x1bOF/, 'end'],
+  [/^\x1b\[3~/, 'delete'],
+  [/^\x1b\[[0-9;]*[~A-Za-z]|^\x1bO[A-Za-z]|^\x1b./, 'ignore'],
+];
+
+function commonPrefix(words: string[]): string {
+  if (!words.length) return '';
+  let prefix = words[0]!;
+  for (const w of words) while (!w.startsWith(prefix)) prefix = prefix.slice(0, -1);
+  return prefix;
+}
+
+export class LineEditor {
+  line = '';
+  cursor = 0;
+  prompt = '';
+  private historyIndex = -1;
+  private draft = '';
+
+  constructor(private readonly options: LineEditorOptions) {}
+
+  /** Show `prompt` and start a fresh line. */
+  begin(prompt: string): void {
+    this.prompt = prompt;
+    this.line = '';
+    this.cursor = 0;
+    this.historyIndex = -1;
+    this.options.write(prompt);
+  }
+
+  feed(data: string): { event?: EditorEvent; rest: string } {
+    let i = 0;
+    while (i < data.length) {
+      const ch = data[i]!;
+      if (ch === '\x1b') {
+        const slice = data.slice(i);
+        const key = KEYS.find(([re]) => re.test(slice));
+        const match = key ? key[0].exec(slice)![0] : '\x1b';
+        i += match.length;
+        this.key(key?.[1] ?? 'ignore');
+        continue;
+      }
+      i++;
+      switch (ch) {
+        case '\r':
+        case '\n': {
+          if (ch === '\r' && data[i] === '\n') i++;
+          const line = this.line;
+          this.options.write('\r\n');
+          if (line.trim() && this.options.history[this.options.history.length - 1] !== line) this.options.history.push(line);
+          this.line = '';
+          this.cursor = 0;
+          return { event: { type: 'line', line }, rest: data.slice(i) };
+        }
+        case '\x03':
+          this.options.write('^C\r\n');
+          this.line = '';
+          this.cursor = 0;
+          return { event: { type: 'interrupt' }, rest: data.slice(i) };
+        case '\x04':
+          if (!this.line) return { event: { type: 'eof' }, rest: data.slice(i) };
+          this.key('delete');
+          break;
+        case '\x7f':
+        case '\b':
+          if (this.cursor > 0) {
+            this.line = this.line.slice(0, this.cursor - 1) + this.line.slice(this.cursor);
+            this.cursor--;
+            this.redraw();
+          }
+          break;
+        case '\x01':
+          this.key('home');
+          break;
+        case '\x05':
+          this.key('end');
+          break;
+        case '\x02':
+          this.key('left');
+          break;
+        case '\x06':
+          this.key('right');
+          break;
+        case '\x10':
+          this.key('up');
+          break;
+        case '\x0e':
+          this.key('down');
+          break;
+        case '\x15':
+          this.line = this.line.slice(this.cursor);
+          this.cursor = 0;
+          this.redraw();
+          break;
+        case '\x0b':
+          this.line = this.line.slice(0, this.cursor);
+          this.redraw();
+          break;
+        case '\x17': {
+          const before = this.line.slice(0, this.cursor).replace(/\S+\s*$/, '');
+          this.line = before + this.line.slice(this.cursor);
+          this.cursor = before.length;
+          this.redraw();
+          break;
+        }
+        case '\x0c':
+          this.options.write('\x1b[2J\x1b[H');
+          this.redraw();
+          break;
+        case '\t':
+          this.complete();
+          break;
+        default:
+          if (ch >= ' ') this.insert(ch);
+      }
+    }
+    return { rest: '' };
+  }
+
+  private insert(text: string): void {
+    this.line = this.line.slice(0, this.cursor) + text + this.line.slice(this.cursor);
+    this.cursor += text.length;
+    if (this.cursor === this.line.length) this.options.write(text);
+    else this.redraw();
+  }
+
+  private key(name: string): void {
+    const history = this.options.history;
+    switch (name) {
+      case 'left':
+        if (this.cursor > 0) {
+          this.cursor--;
+          this.options.write('\x1b[D');
+        }
+        return;
+      case 'right':
+        if (this.cursor < this.line.length) {
+          this.cursor++;
+          this.options.write('\x1b[C');
+        }
+        return;
+      case 'wordLeft':
+        this.cursor = this.line.slice(0, this.cursor).replace(/\S+\s*$/, '').length;
+        return this.redraw();
+      case 'wordRight': {
+        const m = /^\s*\S+/.exec(this.line.slice(this.cursor));
+        this.cursor += m ? m[0].length : 0;
+        return this.redraw();
+      }
+      case 'home':
+        this.cursor = 0;
+        return this.redraw();
+      case 'end':
+        this.cursor = this.line.length;
+        return this.redraw();
+      case 'delete':
+        if (this.cursor < this.line.length) {
+          this.line = this.line.slice(0, this.cursor) + this.line.slice(this.cursor + 1);
+          this.redraw();
+        }
+        return;
+      case 'up':
+        if (!history.length) return;
+        if (this.historyIndex === -1) {
+          this.draft = this.line;
+          this.historyIndex = history.length - 1;
+        } else if (this.historyIndex > 0) this.historyIndex--;
+        this.line = history[this.historyIndex]!;
+        this.cursor = this.line.length;
+        return this.redraw();
+      case 'down':
+        if (this.historyIndex === -1) return;
+        this.historyIndex++;
+        if (this.historyIndex >= history.length) {
+          this.historyIndex = -1;
+          this.line = this.draft;
+        } else this.line = history[this.historyIndex]!;
+        this.cursor = this.line.length;
+        return this.redraw();
+    }
+  }
+
+  private complete(): void {
+    const before = this.line.slice(0, this.cursor);
+    const word = /\S*$/.exec(before)![0];
+    const candidates = this.options.complete?.(before, word) ?? [];
+    if (!candidates.length) return;
+    if (candidates.length === 1) {
+      const only = candidates[0]!;
+      this.insert(only.slice(word.length) + (only.endsWith('/') ? '' : ' '));
+      return;
+    }
+    const prefix = commonPrefix(candidates);
+    if (prefix.length > word.length) {
+      this.insert(prefix.slice(word.length));
+      return;
+    }
+    this.options.write('\r\n' + candidates.map((c) => c.slice(c.lastIndexOf('/', c.length - 2) + 1)).join('  ') + '\r\n');
+    this.redraw();
+  }
+
+  /** Repaint the prompt and line, then put the terminal cursor back where ours is. */
+  redraw(): void {
+    const back = this.line.length - this.cursor;
+    this.options.write(`\r\x1b[K${this.prompt}${this.line}${back ? `\x1b[${back}D` : ''}`);
+  }
+}

package/src/shell/npm.ts

@@ -0,0 +1,229 @@
+/**
+ * `npm` and `npx`, in-process in the shell. Installs go through the core
+ * installer (installer/); scripts run through a child shell with npm's
+ * environment (`node_modules/.bin` on PATH, `npm_lifecycle_event`, …) and
+ * pre/post hooks. `npx` runs an installed bin, or installs the package into a
+ * scratch directory first, as npx does.
+ */
+import { join } from '../paths.js';
+import { installPackages, type InstallOptions } from '../installer/install.js';
+import type { PackageJson } from '../installer/spec.js';
+import { binDirectories, findExecutable } from '../system/commands.js';
+import { findPackageScope } from '../node/resolve.js';
+import { parseFlags, type CommandContext } from './context.js';
+import type { JobInput, Shell } from './exec.js';
+import { matchDevServer } from './devHandoff.js';
+
+export const NPM_VERSION = '10.8.2';
+
+const quote = (arg: string) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`);
+
+function projectDir(ctx: CommandContext): string {
+  return findPackageScope(ctx.fs, ctx.cwd)?.dir ?? ctx.cwd;
+}
+
+function readPackage(ctx: CommandContext, dir: string): PackageJson | undefined {
+  try {
+    return JSON.parse(ctx.fs.readText(join(dir, 'package.json')) ?? 'null') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function install(ctx: CommandContext, options: Partial<InstallOptions>, dir = projectDir(ctx)): Promise<number> {
+  const started = performance.now();
+  const progress = ctx.io.isTerminal;
+  try {
+    const result = await installPackages({
+      fs: ctx.fs,
+      fetch: (url, init) => ctx.system.fetch(url, init as RequestInit),
+      registry: ctx.env.npm_config_registry ?? ctx.system.registry,
+      cache: ctx.system.packageCache,
+      cwd: dir,
+      signal: ctx.signal,
+      onProgress: progress ? (p) => p.phase === 'fetch' && ctx.io.stdout(`\r\x1b[Kfetching ${p.done}/${p.total} ${p.package ?? ''}`) : undefined,
+      ...options,
+    });
+    if (progress) ctx.io.stdout('\r\x1b[K');
+    for (const warning of result.warnings) ctx.io.stderr(`npm warn ${warning}\n`);
+    const seconds = ((performance.now() - started) / 1000).toFixed(1);
+    const parts = [result.added && `added ${result.added} package${result.added === 1 ? '' : 's'}`, result.removed && `removed ${result.removed} package${result.removed === 1 ? '' : 's'}`].filter(Boolean);
+    ctx.io.stdout(`\n${parts.length ? parts.join(', ') : 'up to date'}, audited ${result.total + 1} packages in ${seconds}s\n`);
+    return 0;
+  } catch (error) {
+    if (progress) ctx.io.stdout('\r\x1b[K');
+    if (ctx.signal.aborted) return 130;
+    ctx.io.stderr(`npm error ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+async function runScript(ctx: CommandContext, shell: Shell, input: JobInput, name: string, extra: string[]): Promise<number> {
+  const dir = projectDir(ctx);
+  const pkg = readPackage(ctx, dir);
+  if (!pkg) {
+    ctx.io.stderr(`npm error Could not read package.json in ${dir}\n`);
+    return 1;
+  }
+  const scripts = { ...pkg.scripts };
+  if (name === 'start' && !scripts.start && ctx.fs.isFile(join(dir, 'server.js'))) scripts.start = 'node server.js';
+  if (!scripts[name]) {
+    if (name === 'test') {
+      ctx.io.stderr('npm error Missing script: "test"\n');
+      return 1;
+    }
+    ctx.io.stderr(`npm error Missing script: "${name}"\n\nTo see a list of scripts, run:\n  npm run\n`);
+    return 1;
+  }
+  const PATH = [...binDirectories(dir), ctx.env.PATH ?? ''].filter(Boolean).join(':');
+  for (const stage of [`pre${name}`, name, `post${name}`]) {
+    const script = scripts[stage];
+    if (!script) continue;
+    const command = stage === name && extra.length ? `${script} ${extra.map(quote).join(' ')}` : script;
+    ctx.io.stdout(`\n> ${pkg.name ?? ''}${pkg.version ? '@' + pkg.version : ''} ${stage}\n> ${command}\n\n`);
+    const child = shell.fork({
+      cwd: dir,
+      env: {
+        PATH,
+        npm_lifecycle_event: stage,
+        npm_lifecycle_script: script,
+        npm_command: 'run-script',
+        npm_package_name: pkg.name ?? '',
+        npm_package_version: pkg.version ?? '',
+        npm_package_json: join(dir, 'package.json'),
+        INIT_CWD: ctx.cwd,
+        NODE: '/usr/local/bin/node',
+      },
+    });
+    const status = await child.exec(command, { stdout: ctx.io.stdout, stderr: ctx.io.stderr, isTerminal: ctx.io.isTerminal }, input, ctx.signal);
+    if (status !== 0) {
+      if (!ctx.signal.aborted) ctx.io.stderr(`npm error Lifecycle script \`${stage}\` failed with error:\nnpm error code ${status}\n`);
+      return status;
+    }
+  }
+  return 0;
+}
+
+function listScripts(ctx: CommandContext): number {
+  const pkg = readPackage(ctx, projectDir(ctx));
+  const scripts = Object.entries(pkg?.scripts ?? {});
+  if (!scripts.length) return 0;
+  ctx.io.stdout(`Scripts available in ${pkg?.name ?? 'this package'} via \`npm run-script\`:\n${scripts.map(([k, v]) => `  ${k}\n    ${v}`).join('\n')}\n`);
+  return 0;
+}
+
+export async function npmCommand(ctx: CommandContext, shell: Shell, input: JobInput): Promise<number> {
+  const [sub = 'help', ...rest] = ctx.args;
+  const { flags, operands } = parseFlags(rest, ['registry']);
+  const dev = flags.has('D') || flags.has('save-dev');
+  const production = flags.has('production') || rest.includes('--omit=dev');
+  switch (sub) {
+    case '-v':
+    case '--version':
+    case 'version':
+      ctx.io.stdout(`${NPM_VERSION}\n`);
+      return 0;
+    case 'install':
+    case 'i':
+    case 'add':
+    case 'isntall':
+      return install(ctx, { add: operands, saveDev: dev, production });
+    case 'ci':
+    case 'clean-install':
+      return install(ctx, { ci: true, production });
+    case 'uninstall':
+    case 'remove':
+    case 'rm':
+    case 'un': {
+      const dir = projectDir(ctx);
+      const pkg = readPackage(ctx, dir);
+      if (!pkg) {
+        ctx.io.stderr('npm error No package.json found\n');
+        return 1;
+      }
+      for (const field of ['dependencies', 'devDependencies', 'optionalDependencies'] as const) {
+        for (const name of operands) if (pkg[field]) delete pkg[field]![name];
+      }
+      ctx.fs.writeFile(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+      return install(ctx, {}, dir);
+    }
+    case 'run':
+    case 'run-script': {
+      const dash = rest.indexOf('--');
+      const [name, ...args] = dash >= 0 ? [...rest.slice(0, dash), ...rest.slice(dash + 1)] : rest;
+      return name ? runScript(ctx, shell, input, name, args) : listScripts(ctx);
+    }
+    case 'start':
+    case 'test':
+    case 't':
+    case 'stop':
+    case 'restart':
+      return runScript(ctx, shell, input, sub === 't' ? 'test' : sub, rest.filter((a) => a !== '--'));
+    case 'init': {
+      const path = join(ctx.cwd, 'package.json');
+      if (ctx.fs.isFile(path)) {
+        ctx.io.stderr('npm error package.json already exists\n');
+        return 1;
+      }
+      const name = ctx.cwd.split('/').filter(Boolean).pop() ?? 'project';
+      const pkg = { name, version: '1.0.0', description: '', main: 'index.js', scripts: { test: 'echo "Error: no test specified" && exit 1' }, keywords: [], author: '', license: 'ISC' };
+      ctx.fs.writeFile(path, JSON.stringify(pkg, null, 2) + '\n');
+      ctx.io.stdout(`Wrote to ${path}:\n\n${JSON.stringify(pkg, null, 2)}\n`);
+      return 0;
+    }
+    case 'ls':
+    case 'list': {
+      const dir = projectDir(ctx);
+      const pkg = readPackage(ctx, dir);
+      const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+      ctx.io.stdout(`${pkg?.name ?? ''}@${pkg?.version ?? ''} ${dir}\n`);
+      const names = Object.keys(deps).sort();
+      names.forEach((name, i) => {
+        const installed = readPackage(ctx, join(dir, 'node_modules', name))?.version;
+        ctx.io.stdout(`${i === names.length - 1 ? '└──' : '├──'} ${name}@${installed ?? `(missing ${deps[name]})`}\n`);
+      });
+      return 0;
+    }
+    case 'exec':
+    case 'x':
+      return npxCommand({ ...ctx, args: rest.filter((a) => a !== '--') }, shell, input);
+    case 'help':
+    case '-h':
+    case '--help':
+      ctx.io.stdout(`npm ${NPM_VERSION} (BuilderForce WebContainers)\n\nUsage: npm <install|ci|uninstall|run|start|test|init|ls|exec> …\n`);
+      return 0;
+    default:
+      ctx.io.stderr(`npm error Unknown command: "${sub}"\n`);
+      return 1;
+  }
+}
+
+export async function npxCommand(ctx: CommandContext, shell: Shell, input: JobInput): Promise<number> {
+  const args = ctx.args.filter((a) => a !== '-y' && a !== '--yes');
+  const packageFlag = args.findIndex((a) => a === '-p' || a === '--package');
+  const explicitPackage = packageFlag >= 0 ? args.splice(packageFlag, 2)[1] : undefined;
+  const [bin, ...rest] = args;
+  if (!bin) {
+    ctx.io.stderr('npx: missing command\n');
+    return 1;
+  }
+  const binName = bin.replace(/^@[^/]+\//, '').replace(/@[^@]*$/, '');
+  const io = { stdout: ctx.io.stdout, stderr: ctx.io.stderr, isTerminal: ctx.io.isTerminal };
+  if (matchDevServer([binName, ...rest])) return shell.fork({}).exec([binName, ...rest].map(quote).join(' '), io, input, ctx.signal);
+  let found = findExecutable(ctx.fs, binName, ctx.cwd, { PATH: '' });
+  if (!found) {
+    // Not installed locally: install into a scratch project, as npx does.
+    const spec = explicitPackage ?? bin;
+    const scratch = `/tmp/.npx/${spec.replace(/[^\w.-]+/g, '_')}`;
+    if (!ctx.fs.isFile(join(scratch, 'package.json'))) ctx.fs.writeFile(join(scratch, 'package.json'), '{"private": true}\n');
+    ctx.io.stderr(`npx: installing ${spec}\n`);
+    const status = await install({ ...ctx, io: { ...ctx.io, stdout: () => undefined } }, { add: [spec] }, scratch);
+    if (status !== 0) return status;
+    found = findExecutable(ctx.fs, binName, scratch, { PATH: '' }) ?? findExecutable(ctx.fs, ctx.fs.readdir(join(scratch, 'node_modules/.bin'))[0] ?? binName, scratch, { PATH: '' });
+    if (!found) {
+      ctx.io.stderr(`npx: ${spec} has no executable named ${binName}\n`);
+      return 1;
+    }
+  }
+  return shell.fork({}).exec([found, ...rest].map(quote).join(' '), io, input, ctx.signal);
+}