@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/vm/builtins.ts

@@ -0,0 +1,1590 @@
+/**
+ * Shell builtins. Each receives a {@link BuiltinContext}: `proc` has the
+ * command's redirections applied; `base` is the shell process itself (same
+ * state, original fds) for builtins that change fds permanently (`exec`).
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type * as A from '../parser/ast.ts'
+import { parse, ParseError } from '../parser/parser.ts'
+import { known } from '../analysis/value.ts'
+import { shellQuote, varElements } from './expand.ts'
+import type { Interpreter } from './interp.ts'
+import { resolveCommand } from './interp.ts'
+import { AbortRun, CommandError, DiscardError, ExitSignal, LoopSignal, ReturnSignal, type Proc } from './proc.ts'
+import { KNOWN_SHOPTS, newVar, SET_FLAGS, SET_O_NAMES, type ShellState, type Variable } from './state.ts'
+import { evalTest } from './test.ts'
+
+export interface BuiltinContext {
+  interp: Interpreter
+  proc: Proc
+  base: Proc
+  argv: string[]
+  node: A.SimpleCommand
+  /** If `arg` is a placeholder for an `Assign` node (declaration builtins), the node. */
+  assignArg(arg: string): A.Assign | null
+  out(text: string): Promise<void>
+  err(text: string): Promise<void>
+  error(message: string): void
+}
+
+export type Builtin = (ctx: BuiltinContext) => Promise<number>
+
+export const BUILTINS = new Map<string, Builtin>()
+
+const def = (names: string[], fn: Builtin): void => {
+  for (const n of names) BUILTINS.set(n, fn)
+}
+
+// ---------------------------------------------------------------------------
+// Escapes
+// ---------------------------------------------------------------------------
+
+/** Interpret backslash escapes (echo -e, printf %b). Returns [text, stop] where stop means \c was seen. */
+export function interpretEscapes(s: string, printfStyle = false): [string, boolean] {
+  let out = ''
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i]
+    if (c !== '\\' || i + 1 >= s.length) {
+      out += c
+      continue
+    }
+    const e = s[++i]
+    switch (e) {
+      case 'a': out += '\x07'; break
+      case 'b': out += '\b'; break
+      case 'c': return [out, true]
+      case 'e': case 'E': out += '\x1b'; break
+      case 'f': out += '\f'; break
+      case 'n': out += '\n'; break
+      case 'r': out += '\r'; break
+      case 't': out += '\t'; break
+      case 'v': out += '\v'; break
+      case '\\': out += '\\'; break
+      case '"': out += printfStyle ? '"' : '\\"'; break
+      case "'": out += printfStyle ? "'" : "\\'"; break
+      case 'x': {
+        const m = /^[0-9a-fA-F]{1,2}/.exec(s.slice(i + 1))
+        if (!m) {
+          out += '\\x'
+          break
+        }
+        out += String.fromCharCode(parseInt(m[0], 16))
+        i += m[0].length
+        break
+      }
+      case 'u': case 'U': {
+        const m = new RegExp(`^[0-9a-fA-F]{1,${e === 'u' ? 4 : 8}}`).exec(s.slice(i + 1))
+        if (!m) {
+          out += '\\' + e
+          break
+        }
+        out += String.fromCodePoint(parseInt(m[0], 16))
+        i += m[0].length
+        break
+      }
+      case '0': {
+        const m = /^[0-7]{0,3}/.exec(s.slice(i + 1))!
+        out += String.fromCharCode(parseInt(m[0] || '0', 8) & 0xff)
+        i += m[0].length
+        break
+      }
+      default:
+        if (printfStyle && /[1-7]/.test(e)) {
+          const m = /^[0-7]{0,2}/.exec(s.slice(i + 1))!
+          out += String.fromCharCode(parseInt(e + m[0], 8) & 0xff)
+          i += m[0].length
+        } else out += '\\' + e
+    }
+  }
+  return [out, false]
+}
+
+// ---------------------------------------------------------------------------
+// Trivial
+// ---------------------------------------------------------------------------
+
+def([':', 'true'], async () => 0)
+def(['false'], async () => 1)
+
+def(['echo'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let newline = true
+  let escapes = ctx.proc.state.shopts.has('xpg_echo')
+  while (args.length > 0 && /^-[neE]+$/.test(args[0])) {
+    for (const f of args[0].slice(1)) {
+      if (f === 'n') newline = false
+      else if (f === 'e') escapes = true
+      else escapes = false
+    }
+    args.shift()
+  }
+  let text = args.join(' ')
+  if (escapes) {
+    const [t, stop] = interpretEscapes(text)
+    if (stop) {
+      await ctx.out(t)
+      return 0
+    }
+    text = t
+  }
+  await ctx.out(newline ? text + '\n' : text)
+  return 0
+})
+
+// ---------------------------------------------------------------------------
+// printf
+// ---------------------------------------------------------------------------
+
+function parseNumArg(arg: string | undefined, ctx: BuiltinContext, onError: () => void): bigint {
+  if (arg === undefined) return 0n
+  if (arg === '') {
+    // bash 5: an empty numeric argument is an invalid number (value 0, status 1); 3.2 accepted it
+    ctx.error(': invalid number')
+    onError()
+    return 0n
+  }
+  if (/^['"]/.test(arg)) return BigInt(arg.length > 1 ? arg.codePointAt(1)! : 0)
+  const t = arg.trim()
+  try {
+    if (/^[+-]?0[xX][0-9a-fA-F]+$/.test(t)) return BigInt(t.replace(/^([+-]?)0[xX]/, '$10x').replace(/^-0x(.*)$/, '-0x$1').startsWith('-') ? -BigInt(t.replace(/^-/, '')) : BigInt(t.replace(/^\+/, '')))
+    if (/^[+-]?0[0-7]+$/.test(t)) return (t.startsWith('-') ? -1n : 1n) * BigInt('0o' + t.replace(/^[+-]?0/, ''))
+    if (/^[+-]?\d+$/.test(t)) return BigInt(t)
+  } catch {
+    // fall through
+  }
+  const m = /^([+-]?\d+)/.exec(t)
+  ctx.error(`${arg}: invalid number`)
+  onError()
+  return m ? BigInt(m[1]) : 0n
+}
+
+export function formatPrintf(fmt: string, args: string[], ctx: BuiltinContext): { text: string; failed: boolean } {
+  let out = ''
+  let failed = false
+  let ai = 0
+  const next = (): string | undefined => args[ai++]
+  const fail = (): void => {
+    failed = true
+  }
+  let first = true
+  while (first || ai < args.length) {
+    first = false
+    const startAi = ai
+    for (let i = 0; i < fmt.length; i++) {
+      const c = fmt[i]
+      if (c === '\\') {
+        // escapes in the format
+        let j = i + 1
+        const e = fmt[j]
+        if (e === undefined) {
+          out += '\\'
+          continue
+        }
+        let seq = '\\' + e
+        if (/[0-7]/.test(e)) {
+          const m = /^[0-7]{1,3}/.exec(fmt.slice(j))!
+          seq = '\\0' + m[0]
+          j += m[0].length - 1
+        } else if (e === 'x' || e === 'u' || e === 'U') {
+          const m = new RegExp(`^[0-9a-fA-F]{1,${e === 'x' ? 2 : e === 'u' ? 4 : 8}}`).exec(fmt.slice(j + 1))
+          if (m) {
+            seq += m[0]
+            j += m[0].length
+          }
+        }
+        if (seq === '\\c') {
+          out += '\\c'
+          i = j
+          continue
+        }
+        const [t] = interpretEscapes(seq, true)
+        out += t
+        i = j
+        continue
+      }
+      if (c !== '%') {
+        out += c
+        continue
+      }
+      if (fmt[i + 1] === '%') {
+        out += '%'
+        i++
+        continue
+      }
+      const m = /^%([-+ #0']*)(\*|\d+)?(?:\.(\*|\d*))?(?:hh|h|ll|l|L|q|j|z|t)?([diouxXfFeEgGcsbqaA])/.exec(fmt.slice(i))
+      if (!m) {
+        out += c
+        continue
+      }
+      i += m[0].length - 1
+      const flags = m[1]
+      let width = m[2] === '*' ? Number(parseNumArg(next(), ctx, fail)) : m[2] ? Number(m[2]) : undefined
+      let leftAlign = flags.includes('-')
+      if (width !== undefined && width < 0) {
+        leftAlign = true
+        width = -width
+      }
+      const precision = m[3] === undefined ? undefined : m[3] === '*' ? Number(parseNumArg(next(), ctx, fail)) : Number(m[3] || '0')
+      const conv = m[4]
+      const isFloat = 'fFeEgGaA'.includes(conv)
+      const pad = (s: string, numeric: boolean): string => {
+        if (width === undefined || s.length >= width) return s
+        if (leftAlign) return s.padEnd(width)
+        if (numeric && flags.includes('0') && (precision === undefined || isFloat)) {
+          const sign = /^[+ -]/.test(s) ? s[0] : ''
+          return sign + s.slice(sign.length).padStart(width - sign.length, '0')
+        }
+        return s.padStart(width)
+      }
+      switch (conv) {
+        case 's': {
+          let s = next() ?? ''
+          if (precision !== undefined) s = s.slice(0, precision)
+          out += pad(s, false)
+          break
+        }
+        case 'b': {
+          const [t, stop] = interpretEscapes(next() ?? '', true)
+          let s = t
+          if (precision !== undefined) s = s.slice(0, precision)
+          out += pad(s, false)
+          if (stop) return { text: out, failed }
+          break
+        }
+        case 'q':
+          out += pad(printfQuote(next() ?? ''), false)
+          break
+        case 'c': {
+          // bash 5 prints the first byte, so an empty argument gives a NUL (3.2: nothing)
+          const a = next()
+          out += pad(a === '' ? '\0' : (a ?? '').slice(0, 1), false)
+          break
+        }
+        case 'd': case 'i': {
+          const n = parseNumArg(next(), ctx, fail)
+          let s = (n < 0n ? -n : n).toString()
+          if (precision !== undefined) s = s.padStart(precision, '0')
+          s = (n < 0n ? '-' : flags.includes('+') ? '+' : flags.includes(' ') ? ' ' : '') + s
+          out += pad(s, true)
+          break
+        }
+        case 'u': case 'o': case 'x': case 'X': {
+          let n = parseNumArg(next(), ctx, fail)
+          if (n < 0n) n = BigInt.asUintN(64, n)
+          let s = conv === 'o' ? n.toString(8) : conv === 'u' ? n.toString() : n.toString(16)
+          if (conv === 'X') s = s.toUpperCase()
+          if (precision !== undefined) s = s.padStart(precision, '0')
+          if (flags.includes('#') && n !== 0n) s = (conv === 'o' ? '0' : conv === 'x' ? '0x' : conv === 'X' ? '0X' : '') + s
+          out += pad(s, true)
+          break
+        }
+        default: {
+          // floating point
+          const raw = next()
+          let x = raw === undefined || raw === '' ? 0 : Number(raw)
+          if (Number.isNaN(x)) {
+            ctx.error(`${raw}: invalid number`)
+            fail()
+            x = 0
+          }
+          const p = precision ?? 6
+          let s: string
+          switch (conv) {
+            case 'f': case 'F': s = toFixedHalfEven(x, p); break
+            case 'e': case 'E': s = x.toExponential(p).replace(/e([+-])(\d)$/, 'e$10$2'); break
+            case 'g': case 'G': {
+              const pp = p === 0 ? 1 : p
+              const exp = x === 0 ? 0 : Math.floor(Math.log10(Math.abs(x)))
+              if (exp < -4 || exp >= pp) s = x.toExponential(pp - 1).replace(/\.?0+e/, 'e').replace(/e([+-])(\d)$/, 'e$10$2')
+              else s = String(Number(x.toPrecision(pp)))
+              break
+            }
+            default: s = x.toString(16)
+          }
+          if (conv === 'E' || conv === 'G' || conv === 'F') s = s.toUpperCase()
+          if (x >= 0 && flags.includes('+')) s = '+' + s
+          else if (x >= 0 && flags.includes(' ')) s = ' ' + s
+          out += pad(s, true)
+        }
+      }
+    }
+    if (ai === startAi) break // format consumed no arguments
+  }
+  return { text: out, failed }
+}
+
+/** `printf %q`: backslash-escape shell metacharacters (bash style). */
+function printfQuote(s: string): string {
+  if (s === '') return "''"
+  if (/[\x00-\x1f\x7f]/.test(s)) return shellQuote(s)
+  return s.replace(/[^A-Za-z0-9_@%+=:,./-]/g, (c) => '\\' + c)
+}
+
+/** C printf `%.Nf`: round the exact binary value, ties to even. */
+export function toFixedHalfEven(x: number, digits: number): string {
+  if (!Number.isFinite(x)) return String(x)
+  const neg = x < 0 || Object.is(x, -0)
+  // exact decimal expansion of the double
+  const [mant, exp] = (() => {
+    const buf = new DataView(new ArrayBuffer(8))
+    buf.setFloat64(0, Math.abs(x))
+    const bits = buf.getBigUint64(0)
+    const e = Number((bits >> 52n) & 0x7ffn)
+    const f = bits & ((1n << 52n) - 1n)
+    return e === 0 ? [f, -1074] : [f | (1n << 52n), e - 1075]
+  })()
+  // value = mant * 2^exp; scaled = value * 10^digits as a rational num/den
+  let num = mant * 10n ** BigInt(digits)
+  let den = 1n
+  if (exp >= 0) num <<= BigInt(exp)
+  else den <<= BigInt(-exp)
+  let q = num / den
+  const r = num % den
+  if (r * 2n > den || (r * 2n === den && (q & 1n) === 1n)) q += 1n
+  let s = q.toString().padStart(digits + 1, '0')
+  if (digits > 0) s = s.slice(0, -digits) + '.' + s.slice(-digits)
+  return (neg && q !== 0n ? '-' : neg && x !== 0 ? '-' : '') + s
+}
+
+def(['printf'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let varName: string | null = null
+  if (args[0] === '-v') {
+    varName = args[1] ?? null
+    args.splice(0, 2)
+  }
+  if (args[0] === '--') args.shift()
+  if (args.length === 0) {
+    ctx.error('usage: printf [-v var] format [arguments]')
+    return 2
+  }
+  const { text, failed } = formatPrintf(args[0], args.slice(1), ctx)
+  const element = varName === null ? null : /^([A-Za-z_]\w*)\[(.+)\]$/.exec(varName)
+  if (element) await ctx.interp.assignElement(ctx.proc, element[1], element[2], text)
+  else if (varName !== null) ctx.interp.assignScalar(ctx.proc, varName, text)
+  else await ctx.out(text)
+  return failed ? 1 : 0
+})
+
+// ---------------------------------------------------------------------------
+// Directories
+// ---------------------------------------------------------------------------
+
+function changeDir(ctx: BuiltinContext, target: string, physical: boolean): number {
+  const st = ctx.proc.state
+  let abs = path.resolve(st.cwd, target)
+  let stat: fs.Stats
+  try {
+    stat = fs.statSync(abs)
+  } catch {
+    ctx.error(`${target}: No such file or directory`)
+    return 1
+  }
+  if (!stat.isDirectory()) {
+    ctx.error(`${target}: Not a directory`)
+    return 1
+  }
+  try {
+    fs.accessSync(abs, fs.constants.X_OK)
+  } catch {
+    ctx.error(`${target}: Permission denied`)
+    return 1
+  }
+  if (physical) abs = fs.realpathSync(abs)
+  const old = st.cwd
+  st.cwd = abs
+  ctx.interp.assignScalar(ctx.proc, 'OLDPWD', old)
+  ctx.interp.assignScalar(ctx.proc, 'PWD', abs)
+  return 0
+}
+
+def(['cd'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let physical = false
+  while (args[0] === '-P' || args[0] === '-L' || args[0] === '--') {
+    if (args[0] === '-P') physical = true
+    if (args.shift() === '--') break
+  }
+  const st = ctx.proc.state
+  let target = args[0]
+  if (target === undefined) {
+    target = st.getString('HOME') ?? os.homedir()
+  } else if (target === '-') {
+    const old = st.getString('OLDPWD')
+    if (!old) {
+      ctx.error('OLDPWD not set')
+      return 1
+    }
+    target = old
+    const r = changeDir(ctx, target, physical)
+    if (r === 0) await ctx.out(st.cwd + '\n')
+    return r
+  }
+  return changeDir(ctx, target, physical)
+})
+
+def(['pwd'], async (ctx) => {
+  const physical = ctx.argv.includes('-P')
+  await ctx.out((physical ? fs.realpathSync(ctx.proc.state.cwd) : ctx.proc.state.cwd) + '\n')
+  return 0
+})
+
+def(['pushd'], async (ctx) => {
+  const st = ctx.proc.state
+  const dir = ctx.argv[1]
+  if (dir === undefined) {
+    const top = st.dirStack.shift()
+    if (!top) {
+      ctx.error('no other directory')
+      return 1
+    }
+    const cur = st.cwd
+    const r = changeDir(ctx, top, false)
+    if (r === 0) st.dirStack.unshift(cur)
+    else st.dirStack.unshift(top)
+  } else {
+    const cur = st.cwd
+    const r = changeDir(ctx, dir, false)
+    if (r !== 0) return r
+    st.dirStack.unshift(cur)
+  }
+  await ctx.out([st.cwd, ...st.dirStack].join(' ') + '\n')
+  return 0
+})
+
+def(['popd'], async (ctx) => {
+  const st = ctx.proc.state
+  const top = st.dirStack.shift()
+  if (top === undefined) {
+    ctx.error('directory stack empty')
+    return 1
+  }
+  const r = changeDir(ctx, top, false)
+  if (r !== 0) return r
+  await ctx.out([st.cwd, ...st.dirStack].join(' ') + '\n')
+  return 0
+})
+
+def(['dirs'], async (ctx) => {
+  const st = ctx.proc.state
+  if (ctx.argv.includes('-c')) {
+    st.dirStack = []
+    return 0
+  }
+  await ctx.out([st.cwd, ...st.dirStack].join(' ') + '\n')
+  return 0
+})
+
+// ---------------------------------------------------------------------------
+// Variables
+// ---------------------------------------------------------------------------
+
+function declLine(name: string, v: Variable): string {
+  let flags = ''
+  if (v.value?.kind === 'indexed' || v.declaredKind === 'indexed') flags += 'a'
+  if (v.value?.kind === 'assoc' || v.declaredKind === 'assoc') flags += 'A'
+  if (v.integer) flags += 'i'
+  if (v.lower) flags += 'l'
+  if (v.readonly) flags += 'r'
+  if (v.upper) flags += 'u'
+  if (v.exported) flags += 'x'
+  const f = flags === '' ? '--' : '-' + flags
+  if (v.value === null) return `declare ${f} ${name}`
+  if (v.value.kind === 'string') return `declare ${f} ${name}=${dq(v.value.value)}`
+  if (v.value.kind === 'indexed') {
+    const items = [...v.value.values.entries()].sort((a, b) => a[0] - b[0]).map(([k, x]) => `[${k}]=${dq(x)}`)
+    return `declare ${f} ${name}=(${items.join(' ')})`
+  }
+  const items = [...v.value.values.entries()].map(([k, x]) => `[${shellQuote(k)}]=${dq(x)}`)
+  return `declare ${f} ${name}=(${items.join(' ')} )`
+}
+
+function dq(s: string): string {
+  return '"' + s.replace(/(["\\$`])/g, '\\$1') + '"'
+}
+
+function isName(s: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(s)
+}
+
+async function declare(ctx: BuiltinContext, variant: 'declare' | 'local' | 'export' | 'readonly'): Promise<number> {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  const on = new Set<string>()
+  const off = new Set<string>()
+  let i = 0
+  for (; i < args.length; i++) {
+    const a = args[i]
+    if (ctx.assignArg(a)) break
+    if (a === '--') {
+      i++
+      break
+    }
+    if (/^[-+][a-zA-Z]+$/.test(a)) {
+      for (const f of a.slice(1)) (a[0] === '-' ? on : off).add(f)
+    } else break
+  }
+  const names = args.slice(i)
+  // expand every assignment value before assigning any (bash semantics)
+  const frozen = new Map<string, A.Assign>()
+  for (const arg of names) {
+    const a = ctx.assignArg(arg)
+    if (a) frozen.set(arg, await ctx.interp.freezeAssign(a, ctx.proc))
+  }
+  if (variant === 'local' && st.locals.length === 0) {
+    ctx.error('can only be used in a function')
+    return 1
+  }
+  const inFunction = st.locals.length > 0
+  const local = variant === 'local' || ((variant === 'declare') && inFunction && !on.has('g'))
+  if (variant === 'export') on.add('x')
+  if (variant === 'readonly') on.add('r')
+
+  if ((on.has('f') || off.has('f')) && (variant === 'export' || on.has('x') || off.has('x'))) {
+    let status = 0
+    for (const n of names) {
+      const f = st.functions.get(n)
+      if (!f) {
+        ctx.error(`${n}: not a function`)
+        status = 1
+        continue
+      }
+      st.functions.set(n, { ...f, exported: !off.has('f') && !off.has('x') })
+    }
+    return status
+  }
+  if (on.has('f') || on.has('F')) {
+    for (const n of names.length > 0 ? names : [...st.functions.keys()].sort()) {
+      const f = st.functions.get(n)
+      if (!f) return 1
+      await ctx.out(on.has('F') ? (names.length > 0 ? `${n}\n` : `declare -f ${n}\n`) : `${n} () ${ctx.interp.rt.text(f.def.body)}\n`)
+    }
+    return 0
+  }
+  if (names.length === 0 || (on.has('p') && names.length === 0)) {
+    for (const n of st.visibleNames()) {
+      const v = st.lookup(n)!
+      if (variant === 'export' && !v.exported) continue
+      if (variant === 'readonly' && !v.readonly) continue
+      await ctx.out(variant === 'export' ? `declare -x ${n}${v.value?.kind === 'string' ? '=' + dq(v.value.value) : ''}\n` : declLine(n, v) + '\n')
+    }
+    return 0
+  }
+  if (on.has('p')) {
+    let status = 0
+    for (const n of names) {
+      const v = st.lookup(n)
+      if (!v) {
+        ctx.error(`${n}: not found`)
+        status = 1
+        continue
+      }
+      await ctx.out(declLine(n, v) + '\n')
+    }
+    return status
+  }
+  const kind = on.has('A') ? 'assoc' : on.has('a') ? 'indexed' : undefined
+  let status = 0
+  const applyAttrs = (v: Variable): void => {
+    if (on.has('x')) v.exported = true
+    if (off.has('x')) v.exported = false
+    if (on.has('i')) v.integer = true
+    if (off.has('i')) v.integer = false
+    if (on.has('l')) {
+      v.lower = true
+      v.upper = false
+    }
+    if (on.has('u')) {
+      v.upper = true
+      v.lower = false
+    }
+  }
+  for (const arg of names) {
+    const assign = frozen.get(arg) ?? null
+    if (assign) {
+      const v = local ? st.declareLocal(assign.name) : st.ensure(assign.name)
+      if (v.readonly) {
+        ctx.error(`${assign.name}: readonly variable`)
+        status = 1
+        continue
+      }
+      applyAttrs(v)
+      if (kind && v.value === null) v.declaredKind = kind
+      await ctx.interp.performAssign(assign, ctx.proc, { local, declareKind: kind })
+      if (on.has('r')) v.readonly = true
+      continue
+    }
+    const eq = arg.indexOf('=')
+    const name = eq === -1 ? arg : arg.slice(0, eq).replace(/\+$/, '')
+    if (!isName(name.replace(/\[.*\]$/, ''))) {
+      ctx.error(`\`${arg}': not a valid identifier`)
+      status = 1
+      continue
+    }
+    const v = local ? st.declareLocal(name) : (variant === 'declare' && on.has('g') ? globalVar(st, name) : st.ensure(name))
+    if (eq !== -1 && v.readonly) {
+      ctx.error(`${name}: readonly variable`)
+      status = 1
+      continue
+    }
+    applyAttrs(v)
+    if (kind) {
+      if (v.value === null) v.declaredKind = kind
+      else if (kind === 'indexed' && v.value.kind === 'string') v.value = { kind: 'indexed', values: new Map([[0, v.value.value]]) }
+      else if (kind === 'assoc' && v.value.kind !== 'assoc') v.value = { kind: 'assoc', values: new Map() }
+    }
+    if (eq !== -1) {
+      const append = arg[eq - 1] === '+'
+      const value = arg.slice(eq + 1)
+      const old = append ? st.getString(name) ?? '' : ''
+      ctx.interp.assignScalar(ctx.proc, name, old + value, { local })
+    }
+    if (on.has('r')) v.readonly = true
+    if (off.has('r') && v.readonly) {
+      ctx.error(`${name}: readonly variable`)
+      status = 1
+    }
+  }
+  return status
+}
+
+function globalVar(st: ShellState, name: string): Variable {
+  let v = st.globals.get(name)
+  if (!v) {
+    v = newVar(null)
+    st.globals.set(name, v)
+  }
+  return v
+}
+
+def(['declare', 'typeset'], (ctx) => declare(ctx, 'declare'))
+def(['local'], (ctx) => declare(ctx, 'local'))
+def(['export'], async (ctx) => {
+  if (ctx.argv[1] === '-n') {
+    for (const n of ctx.argv.slice(2)) {
+      const v = ctx.proc.state.lookup(n)
+      if (v) v.exported = false
+    }
+    return 0
+  }
+  return declare(ctx, 'export')
+})
+def(['readonly'], (ctx) => declare(ctx, 'readonly'))
+
+def(['unset'], async (ctx) => {
+  const st = ctx.proc.state
+  let mode: 'v' | 'f' | 'auto' = 'auto'
+  let status = 0
+  for (const a of ctx.argv.slice(1)) {
+    if (a === '-v') {
+      mode = 'v'
+      continue
+    }
+    if (a === '-f') {
+      mode = 'f'
+      continue
+    }
+    if (a === '-n') continue
+    if (mode === 'f') {
+      st.functions.delete(a)
+      continue
+    }
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)\[(.*)\]$/.exec(a)
+    if (m && (m[2] === '@' || m[2] === '*')) {
+      st.unset(m[1])
+      continue
+    }
+    if (m) {
+      const v = st.lookup(m[1])
+      if (v?.value?.kind === 'indexed') {
+        const idx = Number(await ctx.interp.arithText(m[2], ctx.proc))
+        v.value.values.delete(idx)
+      } else if (v?.value?.kind === 'assoc') v.value.values.delete(m[2])
+      continue
+    }
+    if (!isName(a)) {
+      ctx.error(`\`${a}': not a valid identifier`)
+      status = 1
+      continue
+    }
+    if (st.lookup(a)) {
+      if (!st.unset(a)) {
+        ctx.error(`${a}: cannot unset: readonly variable`)
+        status = 1
+      }
+    } else if (mode === 'auto') st.functions.delete(a)
+  }
+  return status
+})
+
+def(['set'], async (ctx) => {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  if (args.length === 0) {
+    for (const n of st.visibleNames()) {
+      const v = st.lookup(n)!
+      if (v.value?.kind === 'string') await ctx.out(`${n}=${shellQuote(v.value.value)}\n`)
+      else if (v.value) await ctx.out(`${n}=(${varElements(v).map(shellQuote).join(' ')})\n`)
+    }
+    return 0
+  }
+  let i = 0
+  for (; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--') {
+      st.positional = args.slice(i + 1)
+      return 0
+    }
+    if (a === '-' ) {
+      st.options.xtrace = false
+      st.options.verbose = false
+      st.positional = args.slice(i + 1)
+      return 0
+    }
+    if (!/^[-+]/.test(a)) break
+    const enable = a[0] === '-'
+    for (let j = 1; j < a.length; j++) {
+      const f = a[j]
+      if (f === 'o') {
+        const name = args[i + 1]
+        if (name === undefined || /^[-+]/.test(name)) {
+          for (const [n, opt] of Object.entries(SET_O_NAMES)) await ctx.out(`${n.padEnd(15)}\t${st.options[opt] ? 'on' : 'off'}\n`)
+          continue
+        }
+        i++
+        const opt = SET_O_NAMES[name]
+        if (!opt) {
+          if (['posix', 'emacs', 'vi', 'monitor', 'notify', 'hashall', 'braceexpand', 'histexpand', 'history', 'ignoreeof', 'interactive-comments', 'keyword', 'onecmd', 'physical', 'privileged', 'errtrace', 'functrace'].includes(name)) continue
+          ctx.error(`${name}: invalid option name`)
+          return 2
+        }
+        st.options[opt] = enable
+        continue
+      }
+      const opt = SET_FLAGS[f]
+      if (opt) st.options[opt] = enable
+      else if (!'hBmbHPTkt'.includes(f)) {
+        ctx.error(`${a[0]}${f}: invalid option`)
+        return 2
+      }
+    }
+  }
+  if (i < args.length) st.positional = args.slice(i)
+  return 0
+})
+
+def(['shopt'], async (ctx) => {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  let mode: 's' | 'u' | 'print' = 'print'
+  let quiet = false
+  let printMode = false
+  const names: string[] = []
+  for (const a of args) {
+    if (a === '-s') mode = 's'
+    else if (a === '-u') mode = 'u'
+    else if (a === '-q') quiet = true
+    else if (a === '-p') printMode = true
+    else if (a === '-o') continue
+    else names.push(a)
+  }
+  let status = 0
+  for (const n of names) {
+    if (!(KNOWN_SHOPTS as readonly string[]).includes(n)) {
+      ctx.error(`${n}: invalid shell option name`)
+      status = 1
+    }
+  }
+  if (status !== 0) return status
+  if (mode === 's') for (const n of names) st.shopts.add(n)
+  else if (mode === 'u') for (const n of names) st.shopts.delete(n)
+  else {
+    const list = names.length > 0 ? names : [...KNOWN_SHOPTS]
+    for (const n of list) {
+      const on = st.shopts.has(n)
+      if (!on) status = 1
+      if (!quiet) await ctx.out(printMode ? `shopt ${on ? '-s' : '-u'} ${n}\n` : `${n.padEnd(20)}\t${on ? 'on' : 'off'}\n`) // bash 5 width (3.2: 15)
+    }
+  }
+  return status
+})
+
+def(['shift'], async (ctx) => {
+  const n = ctx.argv[1] === undefined ? 1 : Number(ctx.argv[1])
+  const st = ctx.proc.state
+  if (!Number.isInteger(n) || n < 0) {
+    ctx.error(`${ctx.argv[1]}: numeric argument required`)
+    return 1
+  }
+  if (n > st.positional.length) return 1
+  st.positional = st.positional.slice(n)
+  return 0
+})
+
+def(['let'], async (ctx) => {
+  if (ctx.argv.length < 2) {
+    ctx.error('expression expected')
+    return 1
+  }
+  let last = 0n
+  for (const e of ctx.argv.slice(1)) last = await ctx.interp.arithText(e, ctx.proc)
+  return last !== 0n ? 0 : 1
+})
+
+// ---------------------------------------------------------------------------
+// read / mapfile
+// ---------------------------------------------------------------------------
+
+def(['read'], async (ctx) => {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  let raw = false
+  let arrayName: string | null = null
+  let delim: number | null = 10
+  let nchars: number | null = null
+  let exactChars = false
+  let fd = 0
+  let timeout: number | null = null
+  let prompt: string | null = null
+  let i = 0
+  for (; i < args.length; i++) {
+    const a = args[i]
+    if (!a.startsWith('-') || a === '-') break
+    if (a === '--') {
+      i++
+      break
+    }
+    for (let j = 1; j < a.length; j++) {
+      const f = a[j]
+      const takeArg = (): string => {
+        const rest = a.slice(j + 1)
+        j = a.length
+        if (rest !== '') return rest
+        return args[++i] ?? ''
+      }
+      switch (f) {
+        case 'r': raw = true; break
+        case 's': case 'e': break
+        case 'a': arrayName = takeArg(); break
+        case 'd': {
+          const d = takeArg()
+          delim = d === '' ? 0 : d.charCodeAt(0)
+          break
+        }
+        case 'n': nchars = Number(takeArg()); break
+        case 'N': nchars = Number(takeArg()); exactChars = true; break
+        case 'u': fd = Number(takeArg()); break
+        case 't': timeout = Number(takeArg()); break
+        case 'p': prompt = takeArg(); break
+        case 'i': takeArg(); break
+        default:
+          ctx.error(`-${f}: invalid option`)
+          return 2
+      }
+    }
+  }
+  const names = args.slice(i)
+  const input = ctx.proc.fds.get(fd)
+  if (!input || !input.readable) {
+    ctx.error(`${fd}: invalid file descriptor: Bad file descriptor`)
+    return 1
+  }
+  if (prompt !== null) await ctx.err(prompt)
+  // read bytes
+  let bytes: Uint8Array | null
+  const doRead = async (signal?: AbortSignal): Promise<Uint8Array | null> => {
+    if (nchars !== null) {
+      // read up to n chars (bytes; good enough for ASCII), stopping at delim unless -N
+      let acc = new Uint8Array(0)
+      while (acc.length < nchars) {
+        const chunk = await input.read(signal)
+        if (chunk === null) break
+        let take = Math.min(chunk.length, nchars - acc.length)
+        if (!exactChars && delim !== null) {
+          const idx = chunk.subarray(0, take).indexOf(delim)
+          if (idx >= 0) take = idx + 1
+        }
+        const merged = new Uint8Array(acc.length + take)
+        merged.set(acc)
+        merged.set(chunk.subarray(0, take), acc.length)
+        acc = merged
+        input.unread(chunk.subarray(take))
+        if (!exactChars && delim !== null && acc[acc.length - 1] === delim) break
+      }
+      return acc.length === 0 ? null : acc
+    }
+    let acc = new Uint8Array(0)
+    for (;;) {
+      const part = await input.readUntil(delim)
+      if (part === null) return acc.length === 0 ? null : acc
+      const merged = new Uint8Array(acc.length + part.length)
+      merged.set(acc)
+      merged.set(part, acc.length)
+      acc = merged
+      // backslash-newline continuation without -r
+      if (!raw && delim === 10 && acc.length >= 2 && acc[acc.length - 1] === 10 && acc[acc.length - 2] === 92) continue
+      return acc
+    }
+  }
+  if (timeout !== null) {
+    const ac = new AbortController()
+    const timer = setTimeout(() => ac.abort(), timeout * 1000)
+    bytes = await doRead(ac.signal)
+    clearTimeout(timer)
+    if (ac.signal.aborted && bytes === null) return 142
+  } else {
+    bytes = await doRead()
+  }
+  if (bytes === null) {
+    for (const n of names.length > 0 ? names : arrayName ? [] : ['REPLY']) ctx.interp.assignScalar(ctx.proc, n, '')
+    if (arrayName) st.ensure(arrayName).value = { kind: 'indexed', values: new Map() }
+    return 1
+  }
+  let text = new TextDecoder().decode(bytes)
+  let hitDelim = false
+  if (delim !== null && nchars === null && text.length > 0 && text.charCodeAt(text.length - 1) === delim) {
+    text = text.slice(0, -1)
+    hitDelim = true
+  } else if (delim !== null && nchars !== null && !exactChars && text.length > 0 && text.charCodeAt(text.length - 1) === delim) {
+    text = text.slice(0, -1)
+    hitDelim = true
+  }
+  // process backslashes (without -r): \x -> x, \<newline> removed; mark escaped chars so IFS does not split them
+  const chars: { c: string; esc: boolean }[] = []
+  for (let k = 0; k < text.length; k++) {
+    const c = text[k]
+    if (!raw && c === '\\' && k + 1 < text.length) {
+      k++
+      if (text[k] === '\n') continue
+      chars.push({ c: text[k], esc: true })
+      continue
+    }
+    if (!raw && c === '\\') continue
+    chars.push({ c, esc: false })
+  }
+  const ifs = st.getString('IFS') ?? ' \t\n'
+  const isWs = (c: string): boolean => ifs.includes(c) && (c === ' ' || c === '\t' || c === '\n')
+  const isIfs = (c: { c: string; esc: boolean }): boolean => !c.esc && ifs.includes(c.c)
+  if (names.length === 0 && !arrayName) {
+    ctx.interp.assignScalar(ctx.proc, 'REPLY', chars.map((c) => c.c).join(''))
+    return hitDelim || nchars !== null ? 0 : 1
+  }
+  // split into fields
+  const fields: string[] = []
+  let pos = 0
+  const skipWs = (): void => {
+    while (pos < chars.length && !chars[pos].esc && isWs(chars[pos].c)) pos++
+  }
+  skipWs()
+  const targetCount = arrayName ? Infinity : names.length
+  while (pos < chars.length && fields.length < targetCount - 1) {
+    let f = ''
+    while (pos < chars.length && !isIfs(chars[pos])) f += chars[pos++].c
+    fields.push(f)
+    // consume one delimiter (with surrounding whitespace)
+    skipWs()
+    if (pos < chars.length && isIfs(chars[pos]) && !isWs(chars[pos].c)) {
+      pos++
+      skipWs()
+    }
+  }
+  if (pos < chars.length) {
+    // remainder goes to the last name; trim trailing IFS whitespace
+    let end = chars.length
+    while (end > pos && !chars[end - 1].esc && isWs(chars[end - 1].c)) end--
+    // a single trailing non-whitespace IFS delimiter is dropped from the last field
+    if (end - 1 > pos && isIfs(chars[end - 1]) && !isWs(chars[end - 1].c) && !chars.slice(pos, end - 1).some(isIfs)) {
+      end--
+      while (end > pos && !chars[end - 1].esc && isWs(chars[end - 1].c)) end--
+    }
+    let rest = chars.slice(pos, end).map((c) => c.c).join('')
+    if (arrayName) {
+      // arrays: split remainder fully
+      rest = rest
+    }
+    fields.push(rest)
+  }
+  if (arrayName) {
+    const values = new Map<number, string>()
+    fields.forEach((f, k) => values.set(k, f))
+    const v = st.ensure(arrayName)
+    v.value = { kind: 'indexed', values }
+  } else {
+    names.forEach((n, k) => ctx.interp.assignScalar(ctx.proc, n, fields[k] ?? ''))
+  }
+  return hitDelim || nchars !== null ? 0 : 1
+})
+
+def(['mapfile', 'readarray'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let strip = false
+  let count = Infinity
+  let skip = 0
+  let delim = 10
+  let fd = 0
+  let name = 'MAPFILE'
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '-t') strip = true
+    else if (a === '-n') count = Number(args[++i]) || Infinity
+    else if (a === '-s') skip = Number(args[++i])
+    else if (a === '-d') {
+      const d = args[++i] ?? ''
+      delim = d === '' ? 0 : d.charCodeAt(0)
+    } else if (a === '-u') fd = Number(args[++i])
+    else if (a === '-C' || a === '-c' || a === '-O') i++
+    else name = a
+  }
+  const input = ctx.proc.fds.get(fd)
+  const values = new Map<number, string>()
+  if (input?.readable) {
+    let n = 0
+    for (;;) {
+      if (values.size >= count) break
+      const line = await input.readUntil(delim)
+      if (line === null) break
+      let s = new TextDecoder().decode(line)
+      if (strip && s.length > 0 && s.charCodeAt(s.length - 1) === delim) s = s.slice(0, -1)
+      if (n++ < skip) continue
+      values.set(values.size, s)
+    }
+  }
+  const v = ctx.proc.state.ensure(name)
+  v.value = { kind: 'indexed', values }
+  return 0
+})
+
+// ---------------------------------------------------------------------------
+// test
+// ---------------------------------------------------------------------------
+
+def(['test'], async (ctx) => evalTest(ctx.argv.slice(1), ctx.proc))
+def(['['], async (ctx) => {
+  if (ctx.argv[ctx.argv.length - 1] !== ']') {
+    ctx.error("missing `]'")
+    return 2
+  }
+  return evalTest(ctx.argv.slice(1, -1), ctx.proc)
+})
+
+// ---------------------------------------------------------------------------
+// Control flow
+// ---------------------------------------------------------------------------
+
+function numArg(ctx: BuiltinContext, s: string | undefined, dflt: number): number {
+  if (s === undefined) return dflt
+  if (!/^-?\d+$/.test(s.trim())) {
+    ctx.error(`${s}: numeric argument required`)
+    return 2
+  }
+  return Number(s) & 0xff
+}
+
+def(['exit'], async (ctx) => {
+  throw new ExitSignal(numArg(ctx, ctx.argv[1], ctx.proc.state.lastStatus))
+})
+
+def(['return'], async (ctx) => {
+  const st = ctx.proc.state
+  if (st.funcStack.length === 0 && !ctx.proc.sourcing) {
+    ctx.error("can only `return' from a function or sourced script")
+    return 2 // bash 5 (3.2: 1)
+  }
+  throw new ReturnSignal(numArg(ctx, ctx.argv[1], st.lastStatus))
+})
+
+def(['break', 'continue'], async (ctx) => {
+  const n = ctx.argv[1] === undefined ? 1 : Number(ctx.argv[1])
+  if (!Number.isInteger(n) || n < 1) {
+    ctx.error(`${ctx.argv[1]}: loop count out of range`)
+    return 1
+  }
+  if (ctx.proc.loopDepth === 0) return 0
+  throw new LoopSignal(ctx.argv[0] as 'break' | 'continue', Math.min(n, ctx.proc.loopDepth))
+})
+
+def(['eval'], async (ctx) => {
+  const src = ctx.argv.slice(1).join(' ')
+  if (src.trim() === '') return 0
+  let script: A.Script
+  try {
+    script = ctx.interp.rt.parse(src, 'eval')
+  } catch (e) {
+    if (e instanceof ParseError) {
+      ctx.error(e.message)
+      return 2
+    }
+    throw e
+  }
+  try {
+    return await ctx.interp.execList(script.body, ctx.proc)
+  } catch (e) {
+    if (e instanceof DiscardError) {
+      ctx.error(e.message)
+      return e.status
+    }
+    throw e
+  }
+})
+
+def(['source', '.'], async (ctx) => {
+  const file = ctx.argv[1]
+  if (file === undefined) {
+    ctx.error('filename argument required')
+    return 2
+  }
+  const st = ctx.proc.state
+  let resolved = path.resolve(st.cwd, file)
+  if (!file.includes('/') && !fs.existsSync(resolved)) {
+    for (const dir of (st.getString('PATH') ?? '').split(':')) {
+      const p = path.resolve(st.cwd, dir || '.', file)
+      if (fs.existsSync(p)) {
+        resolved = p
+        break
+      }
+    }
+  }
+  const a = await ctx.interp.rt.assessRedirects([{ kind: 'read', path: known(resolved), source: 'source' }], ctx.node, ctx.proc)
+  if (a.action === 'abort') throw new AbortRun(a.reason, a.status)
+  if (a.action === 'deny') {
+    ctx.error(a.reason)
+    return a.status
+  }
+  let text: string
+  try {
+    text = fs.readFileSync(resolved, 'utf8')
+  } catch {
+    ctx.error(`${file}: No such file or directory`)
+    return 1
+  }
+  let script: A.Script
+  try {
+    script = ctx.interp.rt.parse(text, resolved)
+  } catch (e) {
+    if (e instanceof ParseError) {
+      ctx.error(`${file}: ${e.message}`)
+      return 2
+    }
+    throw e
+  }
+  const saved = st.positional
+  if (ctx.argv.length > 2) st.positional = ctx.argv.slice(2)
+  const wasSourcing = ctx.proc.sourcing
+  ctx.proc.sourcing = true
+  const savedSource = st.globals.get('BASH_SOURCE')
+  st.globals.set('BASH_SOURCE', newVar({ kind: 'indexed', values: new Map([[0, file], ...[...(savedSource?.value?.kind === 'indexed' ? savedSource.value.values.values() : [])].map((v, i) => [i + 1, v] as [number, string])]) }))
+  try {
+    return await ctx.interp.execList(script.body, ctx.proc)
+  } catch (e) {
+    if (e instanceof ReturnSignal) return e.status
+    throw e
+  } finally {
+    if (savedSource) st.globals.set('BASH_SOURCE', savedSource)
+    else st.globals.delete('BASH_SOURCE')
+    ctx.proc.sourcing = wasSourcing
+    if (ctx.argv.length > 2) st.positional = saved
+  }
+})
+
+def(['exec'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  while (args[0] === '-c' || args[0] === '-l' || args[0] === '--') args.shift()
+  if (args[0] === '-a') args.splice(0, 2)
+  if (args.length === 0) {
+    // make this command's redirections permanent
+    const base = ctx.base.fds
+    const mine = new Map(ctx.proc.fds.entries())
+    for (const [fd] of base.entries()) if (!mine.has(fd)) base.close(fd)
+    for (const [fd, file] of mine) if (base.get(fd) !== file) base.set(fd, file.retain())
+    return 0
+  }
+  const status = await ctx.interp.runArgv(args, ctx.proc, ctx.node, { externalOnly: true })
+  // the shell process was replaced: its EXIT trap never runs
+  ctx.proc.state.traps.delete('EXIT')
+  throw new ExitSignal(status)
+})
+
+def(['command'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let describe: 'v' | 'V' | null = null
+  while (args[0]?.startsWith('-') && args[0] !== '-') {
+    const a = args.shift()!
+    if (a === '--') break
+    if (a.includes('v')) describe = 'v'
+    if (a.includes('V')) describe = 'V'
+  }
+  if (args.length === 0) return 0
+  if (describe) {
+    let status = 0
+    for (const n of args) {
+      const d = describeCommand(n, ctx.proc.state)
+      if (!d) {
+        if (describe === 'V') ctx.error(`${n}: not found`)
+        status = 1
+        continue
+      }
+      await ctx.out(describe === 'v' ? (d.kind === 'file' ? d.path! : n) + '\n' : d.text + '\n')
+    }
+    return status
+  }
+  return ctx.interp.runArgv(args, ctx.proc, ctx.node, { skipFunctions: true })
+})
+
+def(['builtin'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  if (args.length === 0) return 0
+  if (!BUILTINS.has(args[0])) {
+    ctx.error(`${args[0]}: not a shell builtin`)
+    return 1
+  }
+  return ctx.interp.runArgv(args, ctx.proc, ctx.node, { builtinOnly: true })
+})
+
+interface CommandDescription {
+  kind: 'keyword' | 'function' | 'builtin' | 'file' | 'alias'
+  path?: string
+  text: string
+}
+
+const KEYWORDS = new Set(['if', 'then', 'else', 'elif', 'fi', 'case', 'esac', 'for', 'select', 'while', 'until', 'do', 'done', 'in', 'function', 'time', '{', '}', '!', '[[', ']]'])
+
+function describeCommand(name: string, st: ShellState): CommandDescription | null {
+  if (st.aliases.has(name)) return { kind: 'alias', text: `${name} is aliased to \`${st.aliases.get(name)}'` }
+  if (KEYWORDS.has(name)) return { kind: 'keyword', text: `${name} is a shell keyword` }
+  if (st.functions.has(name)) return { kind: 'function', text: `${name} is a function` }
+  if (BUILTINS.has(name)) return { kind: 'builtin', text: `${name} is a shell builtin` }
+  const p = resolveCommand(name, st)
+  if (p) return { kind: 'file', path: p, text: `${name} is ${p}` }
+  return null
+}
+
+def(['type'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let mode: 'normal' | 't' | 'p' | 'P' = 'normal'
+  let all = false
+  const names: string[] = []
+  for (const a of args) {
+    if (a === '-t') mode = 't'
+    else if (a === '-p') mode = 'p'
+    else if (a === '-P') mode = 'P'
+    else if (a === '-a') all = true
+    else if (a === '-f') continue
+    else names.push(a)
+  }
+  let status = 0
+  for (const n of names) {
+    if (all && mode === 'normal') {
+      const lines: string[] = []
+      const d0 = describeCommand(n, ctx.proc.state)
+      if (d0 && d0.kind !== 'file') lines.push(d0.text)
+      for (const dir of (ctx.proc.state.getString('PATH') ?? '').split(':')) {
+        const p = path.join(dir || '.', n)
+        try {
+          if (fs.statSync(p).isFile()) {
+            fs.accessSync(p, fs.constants.X_OK)
+            lines.push(`${n} is ${p}`)
+          }
+        } catch {
+          // not here
+        }
+      }
+      if (lines.length === 0) {
+        ctx.error(`${n}: not found`)
+        status = 1
+      }
+      for (const l of [...new Set(lines)]) await ctx.out(l + '\n')
+      continue
+    }
+    const d = mode === 'P' ? (() => {
+      const p = resolveCommand(n, ctx.proc.state)
+      return p ? { kind: 'file' as const, path: p, text: '' } : null
+    })() : describeCommand(n, ctx.proc.state)
+    if (!d) {
+      if (mode === 'normal') ctx.error(`${n}: not found`)
+      status = 1
+      continue
+    }
+    if (mode === 't') await ctx.out(d.kind + '\n')
+    else if (mode === 'p' || mode === 'P') {
+      if (d.kind === 'file') await ctx.out(d.path + '\n')
+    } else await ctx.out(d.text + '\n')
+  }
+  return status
+})
+
+def(['hash'], async (ctx) => {
+  if (ctx.argv.includes('-r')) ctx.proc.state.hash.clear()
+  if (ctx.argv[1] === '-t') {
+    let status = 0
+    for (const n of ctx.argv.slice(2)) {
+      const p = ctx.proc.state.hash.get(n)
+      if (p) await ctx.out(p + '\n')
+      else {
+        ctx.error(`${n}: not found`)
+        status = 1
+      }
+    }
+    return status
+  }
+  for (const n of ctx.argv.slice(1).filter((a) => !a.startsWith('-'))) {
+    if (!resolveCommand(n, ctx.proc.state)) {
+      ctx.error(`${n}: not found`)
+      return 1
+    }
+  }
+  return 0
+})
+
+def(['alias'], async (ctx) => {
+  const st = ctx.proc.state
+  for (const a of ctx.argv.slice(1)) {
+    const eq = a.indexOf('=')
+    if (eq === -1) {
+      const v = st.aliases.get(a)
+      if (v === undefined) return 1
+      await ctx.out(`alias ${a}=${shellQuote(v)}\n`)
+    } else st.aliases.set(a.slice(0, eq), a.slice(eq + 1))
+  }
+  return 0
+})
+
+def(['unalias'], async (ctx) => {
+  for (const a of ctx.argv.slice(1)) {
+    if (a === '-a') ctx.proc.state.aliases.clear()
+    else ctx.proc.state.aliases.delete(a)
+  }
+  return 0
+})
+
+// ---------------------------------------------------------------------------
+// Jobs, traps
+// ---------------------------------------------------------------------------
+
+def(['wait'], async (ctx) => {
+  const proc = ctx.proc
+  const args = ctx.argv.slice(1).filter((a) => a !== '-f')
+  if (args[0] === '-n') {
+    const pending = [...proc.jobs.values()].filter((j) => j.status === null)
+    if (pending.length === 0) return 127
+    const s = await Promise.race(pending.map((j) => j.done))
+    return s
+  }
+  if (args.length === 0) {
+    for (const j of proc.jobs.values()) await j.done
+    proc.jobs.clear()
+    return 0
+  }
+  let status = 0
+  for (const a of args) {
+    const pid = Number(a.replace(/^%/, ''))
+    const job = proc.jobs.get(pid) ?? [...proc.jobs.values()][pid - 1]
+    if (!job) {
+      ctx.error(`pid ${a} is not a child of this shell`)
+      status = 127
+      continue
+    }
+    status = await job.done
+    proc.jobs.delete(job.pid)
+  }
+  return status
+})
+
+def(['jobs'], async (ctx) => {
+  let i = 1
+  for (const j of ctx.proc.jobs.values()) {
+    await ctx.out(ctx.argv.includes('-p') ? `${j.pid}\n` : `[${i++}]  ${j.status === null ? 'Running' : 'Done'}\t${j.pid}\n`)
+  }
+  return 0
+})
+
+def(['kill'], async (ctx) => {
+  const args = ctx.argv.slice(1)
+  let sig: NodeJS.Signals = 'SIGTERM'
+  if (args[0] === '-l') {
+    await ctx.out(Object.keys(os.constants.signals).map((s) => s.replace(/^SIG/, '')).join(' ') + '\n')
+    return 0
+  }
+  if (args[0] === '-s' || args[0] === '-n') {
+    args.shift()
+    const s = args.shift() ?? 'TERM'
+    sig = (/^\d+$/.test(s) ? Object.entries(os.constants.signals).find(([, n]) => n === Number(s))?.[0] : 'SIG' + s.replace(/^SIG/, '')) as NodeJS.Signals
+  } else if (args[0]?.startsWith('-') && args[0] !== '--') {
+    const s = args.shift()!.slice(1)
+    if (s === '0') sig = 'SIG0' as NodeJS.Signals
+    else sig = (/^\d+$/.test(s) ? Object.entries(os.constants.signals).find(([, n]) => n === Number(s))?.[0] ?? 'SIGTERM' : 'SIG' + s.replace(/^SIG/, '')) as NodeJS.Signals
+  }
+  if (args[0] === '--') args.shift()
+  let status = 0
+  for (const a of args) {
+    const n = Number(a.replace(/^%/, ''))
+    const job = ctx.proc.jobs.get(n) ?? (a.startsWith('%') ? [...ctx.proc.jobs.values()][n - 1] : undefined) ?? ctx.interp.rt.findJob(n)
+    const signalZero = sig === undefined || (sig as string) === 'SIG0' || (sig as string) === 'SIGEXIT'
+    if (job) {
+      if (signalZero) {
+        if (job.status !== null) status = 1
+        continue
+      }
+      job.kill(sig)
+      continue
+    }
+    if (n === ctx.interp.rt.shellPid || n === ctx.proc.pid) {
+      // the VM's own (virtual) shell: never signal the host process
+      if (signalZero) continue
+      const name = String(sig).replace(/^SIG/, '')
+      const trap = ctx.proc.state.traps.get(name)
+      if (trap !== undefined) {
+        if (trap !== '') await ctx.interp.execList(ctx.interp.rt.parse(trap, `trap ${name}`).body, ctx.proc)
+        continue
+      }
+      throw new ExitSignal(128 + ((os.constants.signals as Record<string, number>)[sig] ?? 15))
+    }
+    try {
+      process.kill(n, sig)
+    } catch (e) {
+      ctx.error(`(${a}) - ${(e as NodeJS.ErrnoException).code === 'ESRCH' ? 'No such process' : String(e)}`)
+      status = 1
+    }
+  }
+  return status
+})
+
+def(['trap'], async (ctx) => {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  if (args.length === 0 || args[0] === '-p') {
+    for (const [sig, action] of st.parentTraps ?? st.traps) {
+      if (args[0] === '-p' && args.length > 1 && !args.slice(1).some((a) => a.toUpperCase().replace(/^SIG/, '') === sig)) continue
+      const name = ['EXIT', 'ERR', 'DEBUG', 'RETURN'].includes(sig) ? sig : `SIG${sig}`
+      await ctx.out(`trap -- ${shellQuote(action)} ${name}\n`)
+    }
+    return 0
+  }
+  if (args[0] === '-l') {
+    await ctx.out(Object.keys(os.constants.signals).join(' ') + '\n')
+    return 0
+  }
+  let action: string | null = args[0]
+  let sigs = args.slice(1)
+  if (/^\d+$/.test(action) && sigs.length === 0) {
+    sigs = [action]
+    action = null
+  }
+  if (action === '-') action = null
+  st.parentTraps = undefined
+  for (let s of sigs) {
+    s = s.toUpperCase().replace(/^SIG/, '')
+    if (s === '0') s = 'EXIT'
+    if (action === null) st.traps.delete(s)
+    else st.traps.set(s, action)
+  }
+  return 0
+})
+
+def(['getopts'], async (ctx) => {
+  const st = ctx.proc.state
+  const [optstring, name, ...rest] = ctx.argv.slice(1)
+  if (optstring === undefined || name === undefined) {
+    ctx.error('usage: getopts optstring name [arg ...]')
+    return 2
+  }
+  const args = rest.length > 0 ? rest : st.positional
+  let optind = Number(st.getString('OPTIND') ?? '1') || 1
+  const silent = optstring.startsWith(':')
+  const spec = silent ? optstring.slice(1) : optstring
+  const sub = Number(st.getString('__MASH_OPTPOS') ?? '1') || 1
+  const arg = args[optind - 1]
+  const set = (n: string, v: string): void => ctx.interp.assignScalar(ctx.proc, n, v)
+  if (arg === undefined || !arg.startsWith('-') || arg === '-') {
+    set(name, '?')
+    return 1
+  }
+  if (arg === '--') {
+    set('OPTIND', String(optind + 1))
+    set(name, '?')
+    return 1
+  }
+  const ch = arg[sub]
+  let nextSub = sub + 1
+  const advance = (): void => {
+    if (nextSub >= arg.length) {
+      optind++
+      nextSub = 1
+    }
+  }
+  const idx = spec.indexOf(ch)
+  if (idx === -1 || ch === ':') {
+    if (silent) {
+      set('OPTARG', ch)
+    } else {
+      ctx.error(`illegal option -- ${ch}`)
+      st.unset('OPTARG')
+    }
+    set(name, '?')
+    advance()
+    set('OPTIND', String(optind))
+    set('__MASH_OPTPOS', String(nextSub))
+    return 0
+  }
+  if (spec[idx + 1] === ':') {
+    let optarg: string | undefined
+    if (nextSub < arg.length) {
+      optarg = arg.slice(nextSub)
+      optind++
+    } else {
+      optarg = args[optind]
+      optind += 2
+    }
+    nextSub = 1
+    if (optarg === undefined) {
+      if (silent) {
+        set(name, ':')
+        set('OPTARG', ch)
+      } else {
+        ctx.error(`option requires an argument -- ${ch}`)
+        set(name, '?')
+      }
+      set('OPTIND', String(optind))
+      set('__MASH_OPTPOS', '1')
+      return 0
+    }
+    set('OPTARG', optarg)
+  } else {
+    st.unset('OPTARG')
+    advance()
+  }
+  set(name, ch)
+  set('OPTIND', String(optind))
+  set('__MASH_OPTPOS', String(nextSub))
+  return 0
+})
+
+def(['umask'], async (ctx) => {
+  const st = ctx.proc.state
+  const args = ctx.argv.slice(1)
+  const symbolic = args[0] === '-S'
+  if (symbolic) args.shift()
+  if (args[0] === '-p') args.shift()
+  if (args.length === 0) {
+    if (symbolic) {
+      const perm = (shift: number): string => ['r', 'w', 'x'].filter((_, i) => !(st.umask & (4 >> i) << shift)).join('')
+      await ctx.out(`u=${perm(6)},g=${perm(3)},o=${perm(0)}\n`)
+    } else await ctx.out(st.umask.toString(8).padStart(4, '0') + '\n')
+    return 0
+  }
+  if (!/^[0-7]{1,4}$/.test(args[0])) {
+    ctx.error(`${args[0]}: octal number out of range (symbolic modes are not supported)`)
+    return 1
+  }
+  st.umask = parseInt(args[0], 8)
+  return 0
+})
+
+def(['times'], async (ctx) => {
+  await ctx.out('0m0.000s 0m0.000s\n0m0.000s 0m0.000s\n')
+  return 0
+})
+
+def(['caller'], async () => 1)