@seanhogg/builderforce-webcontainers-core 2026.10.1 → 2026.10.3

package/src/shell/parse.ts

@@ -0,0 +1,295 @@
+/**
+ * The shell grammar, a practical subset of POSIX sh:
+ *
+ *   script   := list (('\n' | ';' | '&') list)*
+ *   list     := pipeline (('&&' | '||') pipeline)*
+ *   pipeline := ['!'] command ('|' command)*
+ *   command  := (NAME=word)* word* redirect*
+ *   redirect := ('>' | '>>' | '<' | '2>' | '2>>' | '&>') word | '2>&1' | '>&2'
+ *
+ * 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;
+}
+export interface Command {
+  assignments: Array<{ name: string; value: Word }>;
+  words: Word[];
+  redirects: Redirect[];
+}
+export interface Pipeline {
+  negate: boolean;
+  commands: Command[];
+}
+export interface AndOrList {
+  first: Pipeline;
+  rest: Array<{ op: '&&' | '||'; pipeline: Pipeline }>;
+  background: boolean;
+}
+export type Script = AndOrList[];
+
+type Token = { type: 'word'; word: Word; raw: string } | { type: 'op'; op: string };
+
+export class ShellSyntaxError extends Error {
+  /** The input ended inside a quote or after `|`/`&&`: an interactive shell asks for more. */
+  constructor(message: string, readonly incomplete = false) {
+    super(message);
+  }
+}
+
+const OPERATORS = ['2>&1', '>&2', '2>>', '&&', '||', '>>', '2>', '&>', '|', '&', ';', '>', '<', '\n'];
+const SPECIAL_VARS = /^[?$#@*!0-9]/;
+
+/** Find the `)` closing a `$(` at `start` (just after the paren), honouring quotes and nesting. */
+function matchParen(input: string, start: number): number {
+  let depth = 1;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === '\\') i++;
+    else if (ch === "'") i = input.indexOf("'", i + 1) < 0 ? input.length : input.indexOf("'", i + 1);
+    else if (ch === '"') {
+      for (i++; i < input.length && input[i] !== '"'; i++) if (input[i] === '\\') i++;
+    } else if (ch === '(') depth++;
+    else if (ch === ')' && --depth === 0) return i;
+  }
+  throw new ShellSyntaxError('unexpected end of input: missing )', true);
+}
+
+/** Parse `$…` at `i` (pointing at `$`); returns the segment and the index after it. */
+function readDollar(input: string, i: number, quoted: boolean): [Segment, number] {
+  const next = input[i + 1];
+  if (next === '(') {
+    const end = matchParen(input, i + 2);
+    return [{ kind: 'cmd', source: input.slice(i + 2, end), quoted }, end + 1];
+  }
+  if (next === '{') {
+    const end = input.indexOf('}', i + 2);
+    if (end < 0) throw new ShellSyntaxError('unexpected end of input: missing }', true);
+    const body = input.slice(i + 2, end);
+    const m = /^([A-Za-z_][\w]*|[?$#@*!0-9])(?:(:-|-|:=|:\+)(.*))?$/s.exec(body);
+    if (!m) throw new ShellSyntaxError(`bad substitution: \${${body}}`);
+    const seg: Segment = { kind: 'var', name: m[1]!, quoted };
+    if (m[2]) {
+      seg.op = m[2] as ':-';
+      seg.arg = tokenizeWord(m[3] ?? '', quoted);
+    }
+    return [seg, end + 1];
+  }
+  if (next && SPECIAL_VARS.test(next)) return [{ kind: 'var', name: next, quoted }, i + 2];
+  const m = /^[A-Za-z_]\w*/.exec(input.slice(i + 1));
+  if (!m) return [{ kind: 'text', value: '$', quoted }, i + 1];
+  return [{ kind: 'var', name: m[0], quoted }, i + 1 + m[0].length];
+}
+
+/** Segments of a word body (used for `${x:-default}` arguments). */
+function tokenizeWord(text: string, quoted: boolean): Word {
+  const tokens = tokenize(text, true);
+  const word: Word = [];
+  for (const t of tokens) if (t.type === 'word') word.push(...t.word.map((s) => (s.kind === 'tilde' ? s : { ...s, quoted: quoted || ('quoted' in s && s.quoted) } as Segment)));
+  return word;
+}
+
+export function tokenize(input: string, wordOnly = false): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i]!;
+    if (ch === ' ' || ch === '\t' || ch === '\r') {
+      i++;
+      continue;
+    }
+    if (ch === '\\' && input[i + 1] === '\n') {
+      i += 2;
+      continue;
+    }
+    if (ch === '#') {
+      while (i < input.length && input[i] !== '\n') i++;
+      continue;
+    }
+    if (!wordOnly) {
+      const op = OPERATORS.find((o) => input.startsWith(o, i));
+      if (op) {
+        tokens.push({ type: 'op', op });
+        i += op.length;
+        continue;
+      }
+    }
+    // A word: runs until unquoted whitespace or an operator character.
+    const word: Word = [];
+    const start = i;
+    let text = '';
+    const flush = () => {
+      if (text) word.push({ kind: 'text', value: text, quoted: false });
+      text = '';
+    };
+    if (input[i] === '~' && (i + 1 >= input.length || /[\s/;|&<>]/.test(input[i + 1]!))) {
+      word.push({ kind: 'tilde' });
+      i++;
+    }
+    while (i < input.length) {
+      const c = input[i]!;
+      if (/[\s]/.test(c) && !wordOnly) break;
+      if (!wordOnly && /[;|&<>]/.test(c)) break;
+      if (c === '\\') {
+        text += input[i + 1] ?? '';
+        i += 2;
+      } else if (c === "'") {
+        const end = input.indexOf("'", i + 1);
+        if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated quote', true);
+        flush();
+        word.push({ kind: 'text', value: input.slice(i + 1, end), quoted: true });
+        i = end + 1;
+      } else if (c === '"') {
+        flush();
+        i++;
+        let inner = '';
+        const pushInner = () => {
+          if (inner) word.push({ kind: 'text', value: inner, quoted: true });
+          inner = '';
+        };
+        let closed = false;
+        while (i < input.length) {
+          const d = input[i]!;
+          if (d === '"') {
+            closed = true;
+            i++;
+            break;
+          }
+          if (d === '\\' && /["\\$`\n]/.test(input[i + 1] ?? '')) {
+            inner += input[i + 1];
+            i += 2;
+          } else if (d === '$') {
+            pushInner();
+            const [seg, next] = readDollar(input, i, true);
+            word.push(seg);
+            i = next;
+          } else if (d === '`') {
+            pushInner();
+            const end = input.indexOf('`', i + 1);
+            if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated `', true);
+            word.push({ kind: 'cmd', source: input.slice(i + 1, end), quoted: true });
+            i = end + 1;
+          } else {
+            inner += d;
+            i++;
+          }
+        }
+        if (!closed) throw new ShellSyntaxError('unexpected end of input: unterminated quote', true);
+        pushInner();
+        if (!word.length || word[word.length - 1]!.kind !== 'text') word.push({ kind: 'text', value: '', quoted: true });
+      } else if (c === '$') {
+        flush();
+        const [seg, next] = readDollar(input, i, false);
+        word.push(seg);
+        i = next;
+      } else if (c === '`') {
+        flush();
+        const end = input.indexOf('`', i + 1);
+        if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated `', true);
+        word.push({ kind: 'cmd', source: input.slice(i + 1, end), quoted: false });
+        i = end + 1;
+      } else {
+        text += c;
+        i++;
+      }
+    }
+    flush();
+    tokens.push({ type: 'word', word, raw: input.slice(start, i) });
+  }
+  return tokens;
+}
+
+const ASSIGNMENT = /^([A-Za-z_]\w*)=/;
+const REDIRECTS = new Set(['>', '>>', '<', '2>', '2>>', '&>', '2>&1', '>&2']);
+
+export function parse(input: string): Script {
+  const tokens = tokenize(input);
+  let pos = 0;
+  const peek = () => tokens[pos];
+  const isOp = (op: string) => {
+    const t = tokens[pos];
+    return t?.type === 'op' && t.op === op;
+  };
+
+  const command = (): Command => {
+    const cmd: Command = { assignments: [], words: [], redirects: [] };
+    for (;;) {
+      const t = peek();
+      if (!t) break;
+      if (t.type === 'op') {
+        if (!REDIRECTS.has(t.op)) break;
+        pos++;
+        if (t.op === '2>&1' || t.op === '>&2') {
+          cmd.redirects.push({ op: t.op });
+          continue;
+        }
+        const target = peek();
+        if (target?.type !== 'word') throw new ShellSyntaxError(`syntax error near unexpected token \`${target?.type === 'op' ? target.op.replace('\n', 'newline') : 'newline'}'`);
+        pos++;
+        cmd.redirects.push({ op: t.op as RedirectOp, target: target.word });
+        continue;
+      }
+      pos++;
+      const first = t.word[0];
+      const m = !cmd.words.length && first?.kind === 'text' && !first.quoted ? ASSIGNMENT.exec(first.value) : null;
+      if (m) {
+        const rest = first!.kind === 'text' ? first!.value.slice(m[0].length) : '';
+        cmd.assignments.push({ name: m[1]!, value: [...(rest ? [{ kind: 'text', value: rest, quoted: false } as Segment] : []), ...t.word.slice(1)] });
+      } else cmd.words.push(t.word);
+    }
+    return cmd;
+  };
+
+  const pipeline = (): Pipeline => {
+    let negate = false;
+    const t = peek();
+    if (t?.type === 'word' && t.raw === '!') {
+      negate = true;
+      pos++;
+    }
+    const commands = [command()];
+    while (isOp('|')) {
+      pos++;
+      while (isOp('\n')) pos++;
+      if (!peek()) throw new ShellSyntaxError('unexpected end of input after |', true);
+      commands.push(command());
+    }
+    for (const c of commands) if (!c.words.length && !c.assignments.length && !c.redirects.length) throw new ShellSyntaxError('syntax error near unexpected token `|\'');
+    return { negate, commands };
+  };
+
+  const script: Script = [];
+  while (pos < tokens.length) {
+    if (isOp(';') || isOp('\n')) {
+      pos++;
+      continue;
+    }
+    const t = peek()!;
+    if (t.type === 'op' && !REDIRECTS.has(t.op)) throw new ShellSyntaxError(`syntax error near unexpected token \`${t.op}'`);
+    const list: AndOrList = { first: pipeline(), rest: [], background: false };
+    while (isOp('&&') || isOp('||')) {
+      const op = (tokens[pos] as { op: '&&' | '||' }).op;
+      pos++;
+      while (isOp('\n')) pos++;
+      if (!peek()) throw new ShellSyntaxError(`unexpected end of input after ${op}`, true);
+      list.rest.push({ op, pipeline: pipeline() });
+    }
+    if (isOp('&')) {
+      list.background = true;
+      pos++;
+    }
+    script.push(list);
+  }
+  return script;
+}

package/src/shell/program.ts

@@ -0,0 +1,223 @@
+/**
+ * The `jsh` program: `jsh -c "…"`, `jsh script.sh`, a script on stdin, or —
+ * attached to a terminal — the interactive shell. Interactively the shell owns
+ * the keyboard (raw mode) while it edits a line, and hands it to the running
+ * job otherwise: straight through to a terminal-attached child (which has its
+ * own line discipline), or cooked by the shell for everything else.
+ */
+import type { Program, ProgramContext } from '../system/types.js';
+import { InputQueue, LineDiscipline } from '../system/terminal.js';
+import { join } from '../paths.js';
+import { binDirectories } from '../system/commands.js';
+import { parse, ShellSyntaxError } from './parse.js';
+import { Shell, type JobInput, type ShellCommand, type ShellIO } from './exec.js';
+import { LineEditor } from './lineEditor.js';
+import { BUILTINS, COREUTILS, SYSTEM_PROGRAMS } from './builtins.js';
+import { npmCommand, npxCommand } from './npm.js';
+import { glob } from './expand.js';
+
+export const SHELL_COMMANDS: Record<string, ShellCommand> = { npm: npmCommand, npx: npxCommand };
+
+function createShell(ctx: ProgramContext, positional: string[] = []): Shell {
+  return new Shell({
+    system: ctx.system,
+    cwd: ctx.cwd,
+    env: { ...ctx.env, SHELL: '/bin/jsh' },
+    positional,
+    terminalSize: () => (ctx.io.terminal ? { cols: ctx.io.terminal.cols, rows: ctx.io.terminal.rows } : undefined),
+    commands: SHELL_COMMANDS,
+  });
+}
+
+/**
+ * The stdin a non-interactive run hands its commands. On a terminal the shell
+ * takes raw input so a terminal-attached child (node, a REPL) gets keystrokes
+ * once — its own line discipline cooks them — while everything else gets lines
+ * cooked here, exactly once.
+ */
+function stdinJob(ctx: ProgramContext, controller?: AbortController): { input: JobInput; stop(): void } {
+  const queue = new InputQueue();
+  const terminal = ctx.io.terminal;
+  if (!terminal) {
+    const stop = ctx.io.onStdin((chunk) => queue.push(chunk));
+    return { input: { queue }, stop };
+  }
+  terminal.setRawMode(true);
+  let rawSink: ((data: string) => void) | undefined;
+  const discipline = new LineDiscipline({
+    echo: (t) => ctx.io.stdout(t),
+    deliver: (chunk) => queue.push(chunk),
+    signal: (name) => controller?.abort(name),
+  });
+  const stop = ctx.io.onStdin((chunk) => {
+    if (chunk === null) queue.push(null);
+    else if (rawSink) rawSink(chunk);
+    else discipline.input(chunk);
+  });
+  return {
+    input: { queue, setRawSink: (sink) => void (rawSink = sink) },
+    stop() {
+      stop();
+      terminal.setRawMode(false);
+    },
+  };
+}
+
+/** Run with a signal that both the program's kill and a cooked Ctrl-C abort. */
+async function runOnce(ctx: ProgramContext, shell: Shell, source: string): Promise<number> {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(ctx.signal.reason);
+  ctx.signal.addEventListener('abort', onAbort);
+  const { input, stop } = stdinJob(ctx, controller);
+  try {
+    return await shell.exec(source, text(ctx), input, controller.signal);
+  } finally {
+    stop();
+    ctx.signal.removeEventListener('abort', onAbort);
+  }
+}
+
+const text = (ctx: ProgramContext): ShellIO => ({
+  stdout: (t) => ctx.io.stdout(t),
+  stderr: (t) => ctx.io.stderr(t),
+  isTerminal: !!ctx.io.terminal,
+});
+
+function displayCwd(cwd: string, home: string | undefined): string {
+  if (home && (cwd === home || cwd.startsWith(home + '/'))) return '~' + cwd.slice(home.length);
+  return cwd;
+}
+
+function completer(shell: Shell) {
+  return (before: string, word: string): string[] => {
+    const isCommand = !/\S\s/.test(before.trimStart()) && !word.includes('/');
+    const fs = shell.system.fs;
+    const dirPart = word.includes('/') ? word.slice(0, word.lastIndexOf('/') + 1) : '';
+    const files = glob(fs, shell.cwd, `${dirPart}*`).filter((f) => f.slice(dirPart.length).startsWith(word.slice(dirPart.length)) || !dirPart)
+      .filter((f) => f.startsWith(word))
+      .map((f) => (fs.isDirectory(f.startsWith('/') ? f : join(shell.cwd, f)) ? f + '/' : f));
+    if (!isCommand) return files.sort();
+    const commands = new Set([...Object.keys(BUILTINS), ...Object.keys(COREUTILS), ...SYSTEM_PROGRAMS]);
+    for (const dir of binDirectories(shell.cwd)) for (const name of fs.readdir(dir)) commands.add(name);
+    return [...[...commands].filter((c) => c.startsWith(word)).sort(), ...files.filter((f) => f.endsWith('/'))];
+  };
+}
+
+async function interactive(ctx: ProgramContext): Promise<number> {
+  const terminal = ctx.io.terminal!;
+  const shell = createShell(ctx);
+  const io = text(ctx);
+  terminal.setRawMode(true);
+  const editor = new LineEditor({ write: (t) => ctx.io.stdout(t), history: shell.history, complete: completer(shell) });
+  const prompt = () => `\x1b[1;36m${displayCwd(shell.cwd, shell.env.HOME)}\x1b[0m \x1b[1;32m$\x1b[0m `;
+
+  let job: { controller: AbortController; input: JobInput; discipline: LineDiscipline; rawSink?: (data: string) => void } | undefined;
+  let pending = '';
+  let typeahead = '';
+  let finish!: (code: number) => void;
+  const done = new Promise<number>((resolve) => (finish = resolve));
+
+  const runLine = async (line: string) => {
+    const queue = new InputQueue();
+    const controller = new AbortController();
+    const discipline = new LineDiscipline({
+      echo: (t) => ctx.io.stdout(t),
+      deliver: (chunk) => queue.push(chunk),
+      signal: (name) => controller.abort(name),
+    });
+    const current: NonNullable<typeof job> = { controller, input: { queue }, discipline };
+    current.input.setRawSink = (sink) => void (current.rawSink = sink);
+    job = current;
+    try {
+      await shell.exec(line, io, current.input, controller.signal);
+    } catch (error) {
+      ctx.io.stderr(`jsh: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    job = undefined;
+    if (shell.exitRequested !== undefined) return finish(shell.exitRequested);
+    editor.begin(prompt());
+    if (typeahead) {
+      const rest = typeahead;
+      typeahead = '';
+      onInput(rest);
+    }
+  };
+
+  const onInput = (data: string) => {
+    if (job) {
+      if (job.rawSink) job.rawSink(data);
+      else job.discipline.input(data);
+      return;
+    }
+    let rest = data;
+    while (rest && !job) {
+      const { event, rest: remaining } = editor.feed(rest);
+      rest = remaining;
+      if (!event) break;
+      if (event.type === 'eof') {
+        ctx.io.stdout('exit\r\n');
+        return finish(shell.lastStatus);
+      }
+      if (event.type === 'interrupt') {
+        pending = '';
+        shell.lastStatus = 130;
+        editor.begin(prompt());
+        continue;
+      }
+      const source = pending ? `${pending}\n${event.line}` : event.line;
+      try {
+        parse(source);
+      } catch (error) {
+        if (error instanceof ShellSyntaxError && error.incomplete) {
+          pending = source;
+          editor.begin('> ');
+          continue;
+        }
+      }
+      pending = '';
+      if (!source.trim()) {
+        editor.begin(prompt());
+        continue;
+      }
+      typeahead = rest;
+      rest = '';
+      void runLine(source);
+    }
+  };
+
+  const stopInput = ctx.io.onStdin((chunk) => (chunk === null ? finish(shell.lastStatus) : onInput(chunk)));
+  const onAbort = () => {
+    job?.controller.abort('SIGHUP');
+    finish(129);
+  };
+  ctx.signal.addEventListener('abort', onAbort);
+  editor.begin(prompt());
+  const code = await done;
+  stopInput();
+  ctx.signal.removeEventListener('abort', onAbort);
+  terminal.setRawMode(false);
+  return code;
+}
+
+export const shellProgram: Program = async (ctx) => {
+  const args = ctx.args.filter((a) => a !== '-l' && a !== '--login' && a !== '-i');
+  if (args[0] === '-c') return runOnce(ctx, createShell(ctx, args.slice(2)), args[1] ?? '');
+  if (args[0]) {
+    const path = args[0].startsWith('/') ? args[0] : join(ctx.cwd, args[0]);
+    const source = ctx.system.fs.readText(path);
+    if (source === undefined) {
+      ctx.io.stderr(`jsh: ${args[0]}: No such file or directory\n`);
+      return 127;
+    }
+    return runOnce(ctx, createShell(ctx, args.slice(1)), source.replace(/^#!.*\n/, ''));
+  }
+  if (ctx.io.terminal) return interactive(ctx);
+  // No terminal, no script: read commands from stdin.
+  const { input, stop } = stdinJob(ctx);
+  const source = await input.queue.readAll();
+  stop();
+  const shell = createShell(ctx);
+  const empty = new InputQueue();
+  empty.push(null);
+  return shell.exec(source, text(ctx), { queue: empty }, ctx.signal);
+};

package/src/shell/textCommands.ts

@@ -0,0 +1,177 @@
+/**
+ * Text coreutils: echo, printf, head, tail, grep, wc, env, clear, sleep,
+ * basename, dirname, true, false. Each reads named files or, without any,
+ * stdin — so they work at either end of a pipe.
+ */
+import { basename as baseOf, dirname as dirOf, join } from '../paths.js';
+import { parseFlags, resolvePath, type Command, type CommandContext } from './context.js';
+
+/** Contents of each operand file, or stdin when there are none. */
+async function inputs(ctx: CommandContext, operands: string[], name: string): Promise<Array<{ label: string; text: string }> | number> {
+  if (!operands.length || (operands.length === 1 && operands[0] === '-')) return [{ label: '(standard input)', text: await ctx.io.stdin.readAll() }];
+  const out: Array<{ label: string; text: string }> = [];
+  for (const file of operands) {
+    const path = resolvePath(ctx, file);
+    if (!ctx.fs.isFile(path)) {
+      ctx.io.stderr(`${name}: ${file}: ${ctx.fs.isDirectory(path) ? 'Is a directory' : 'No such file or directory'}\n`);
+      return 1;
+    }
+    out.push({ label: file, text: ctx.fs.readText(path) ?? '' });
+  }
+  return out;
+}
+
+const lines = (text: string) => {
+  const list = text.split('\n');
+  if (list[list.length - 1] === '') list.pop();
+  return list;
+};
+
+function unescape(text: string): string {
+  return text.replace(/\\(n|t|r|\\|e|a|0)/g, (_m, c: string) => ({ n: '\n', t: '\t', r: '\r', '\\': '\\', e: '\x1b', a: '\x07', 0: '\0' })[c] ?? c);
+}
+
+export const echo: Command = async (ctx) => {
+  let args = ctx.args;
+  let newline = true;
+  let escapes = false;
+  while (args[0] && /^-[neE]+$/.test(args[0])) {
+    if (args[0].includes('n')) newline = false;
+    if (args[0].includes('e')) escapes = true;
+    args = args.slice(1);
+  }
+  const text = args.join(' ');
+  ctx.io.stdout((escapes ? unescape(text) : text) + (newline ? '\n' : ''));
+  return 0;
+};
+
+export const printf: Command = async (ctx) => {
+  const [format = '', ...rest] = ctx.args;
+  let i = 0;
+  const out = unescape(format).replace(/%([sdif%])/g, (_m, spec: string) => {
+    if (spec === '%') return '%';
+    const arg = rest[i++] ?? '';
+    return spec === 's' ? arg : String(spec === 'f' ? parseFloat(arg) || 0 : parseInt(arg, 10) || 0);
+  });
+  ctx.io.stdout(out);
+  return 0;
+};
+
+function headTail(which: 'head' | 'tail'): Command {
+  return async (ctx) => {
+    const numeric = ctx.args.find((a) => /^-\d+$/.test(a));
+    const { values, operands } = parseFlags(ctx.args.filter((a) => a !== numeric), ['n']);
+    const count = numeric ? Number(numeric.slice(1)) : values.n !== undefined ? Number(values.n) : 10;
+    const files = await inputs(ctx, operands, which);
+    if (typeof files === 'number') return files;
+    files.forEach((file, index) => {
+      if (files.length > 1) ctx.io.stdout(`${index ? '\n' : ''}==> ${file.label} <==\n`);
+      const all = lines(file.text);
+      const picked = which === 'head' ? all.slice(0, count) : count ? all.slice(-count) : [];
+      if (picked.length) ctx.io.stdout(picked.join('\n') + '\n');
+    });
+    return 0;
+  };
+}
+export const head = headTail('head');
+export const tail = headTail('tail');
+
+export const grep: Command = async (ctx) => {
+  const { flags, operands } = parseFlags(ctx.args);
+  const [pattern, ...files] = operands;
+  if (pattern === undefined) {
+    ctx.io.stderr('Usage: grep [-ivnrclEF] PATTERN [FILE]...\n');
+    return 2;
+  }
+  let re: RegExp;
+  try {
+    const source = flags.has('F') ? pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : flags.has('E') ? pattern : pattern.replace(/\\([|(){}+?])/g, '$1');
+    re = new RegExp(flags.has('w') ? `\\b(?:${source})\\b` : source, flags.has('i') ? 'i' : '');
+  } catch {
+    ctx.io.stderr(`grep: invalid pattern: ${pattern}\n`);
+    return 2;
+  }
+  let targets = files;
+  if (flags.has('r') || flags.has('R')) {
+    targets = [];
+    const walk = (path: string, label: string) => {
+      if (ctx.fs.isFile(path)) targets.push(label);
+      else for (const name of ctx.fs.readdir(path)) if (name !== 'node_modules' && !name.startsWith('.')) walk(join(path, name), label === '.' ? name : `${label}/${name}`);
+    };
+    for (const f of files.length ? files : ['.']) walk(resolvePath(ctx, f), f);
+  }
+  const sources = await inputs(ctx, targets, 'grep');
+  if (typeof sources === 'number') return 2;
+  const prefix = sources.length > 1;
+  let matched = 0;
+  for (const { label, text } of sources) {
+    let count = 0;
+    lines(text).forEach((line, index) => {
+      if (re.test(line) === flags.has('v')) return;
+      count++;
+      matched++;
+      if (flags.has('c') || flags.has('l') || flags.has('q')) return;
+      ctx.io.stdout(`${prefix ? label + ':' : ''}${flags.has('n') ? index + 1 + ':' : ''}${line}\n`);
+    });
+    if (flags.has('c')) ctx.io.stdout(`${prefix ? label + ':' : ''}${count}\n`);
+    if (flags.has('l') && count) ctx.io.stdout(label + '\n');
+  }
+  return matched ? 0 : 1;
+};
+
+export const wc: Command = async (ctx) => {
+  const { flags, operands } = parseFlags(ctx.args);
+  const files = await inputs(ctx, operands, 'wc');
+  if (typeof files === 'number') return files;
+  const only = ['l', 'w', 'c'].filter((f) => flags.has(f));
+  for (const { label, text } of files) {
+    const counts: Record<string, number> = { l: (text.match(/\n/g) ?? []).length, w: text.split(/\s+/).filter(Boolean).length, c: new TextEncoder().encode(text).length };
+    const shown = (only.length ? only : ['l', 'w', 'c']).map((f) => String(counts[f]).padStart(7)).join(' ');
+    ctx.io.stdout(`${shown}${operands.length ? ' ' + label : ''}\n`);
+  }
+  return 0;
+};
+
+export const env: Command = async (ctx) => {
+  ctx.io.stdout(Object.entries(ctx.env).map(([k, v]) => `${k}=${v}`).join('\n') + '\n');
+  return 0;
+};
+
+export const clear: Command = async (ctx) => {
+  ctx.io.stdout('\x1b[2J\x1b[3J\x1b[H');
+  return 0;
+};
+
+export const sleep: Command = async (ctx) => {
+  const seconds = Number(ctx.args[0] ?? 0);
+  if (!Number.isFinite(seconds)) {
+    ctx.io.stderr(`sleep: invalid time interval '${ctx.args[0]}'\n`);
+    return 1;
+  }
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, seconds * 1000);
+    ctx.signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+  return ctx.signal.aborted ? 130 : 0;
+};
+
+export const basename: Command = async (ctx) => {
+  const [path = '', suffix] = ctx.args;
+  let base = baseOf(path);
+  if (suffix && base.endsWith(suffix) && base !== suffix) base = base.slice(0, -suffix.length);
+  ctx.io.stdout(base + '\n');
+  return 0;
+};
+
+export const dirname: Command = async (ctx) => {
+  const path = (ctx.args[0] ?? '.').replace(/(.)\/+$/, '$1');
+  const cut = path.lastIndexOf('/');
+  ctx.io.stdout((cut < 0 ? '.' : cut === 0 ? '/' : path.startsWith('/') ? dirOf(path) : path.slice(0, cut)) + '\n');
+  return 0;
+};
+
+export const trueCommand: Command = async () => 0;
+export const falseCommand: Command = async () => 1;