@kaynooo/cli-kit 0.10.0 → 0.11.0

package/README.md

@@ -33,6 +33,9 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 ## API
 
 - `runCli({ name, version, about, commands, aliases })` dispatches `<cli> <command> [args]`: `--help` lists the commands, `--version` prints the version, a typo names the command it likely meant, and an `Exit` thrown by a command prints `error: <cli> <command>: <message>`, its hint under it, and exits with its code. Any other error exits 1, named by its class unless a plain `Error` (`error: tool sync: MigrationError: ...`), its cause's message on a `cause:` line under it when the cause is an `Error`; `redact(text)` rewrites both before they print, for errors that may quote what a log must not keep.
+- `runTool(label, argv, { timeoutMs, cwd, onStart })` runs a command through `runCommand` with the current environment and returns `{ code, stdout, stderr }`; it throws, naming `label`, when the command cannot start (noting a removed working directory) or outlives `timeoutMs`. `isPermanentFailure(error)` is true for what a retry cannot mend: a missing binary, or an answer of 401, 403 or 404. `cwdGone()` tells that the working directory was deleted.
+- `git(args, timeoutMs?)`, `gitOk`, `resolveCommit`, `fetchBranch`, `defaultBranch` and `leaveWorktree` are the git helpers the forge CLIs share, over `runTool`.
+- `waitForCi({ tool, short, giveUpMs, noneMs, stalledMs, covering, finished, key, announce, links, settle, stall, lines })` is the wait loop of `ft ci` and `gl ci`: it polls `covering` until what it returns is `finished`, retries a poll that failed for a network reason, fails at once on a refusal (`Exit`) or a permanent failure, and gives up on a timeout, on nothing covering the commit for `noneMs`, or on a `stall` that is certain or lasts `stalledMs`.
 - `parse(args, usage, options)` wraps `node:util` `parseArgs` with a generated `--help` (`usage` given with or without its `usage:`), which prints the help and ends the command with exit 0 (it throws `HelpShown`, which `runCli` and `runMain` take), so the command needs no check after it. A string option takes a next argument starting with a dash as its value (`--from "- item"`, `-n -3`) unless that argument names one of the command's options, which parseArgs alone refuses as ambiguous. `{ positionals: ['<key>', '[file]'] }` names the positionals the command takes: `<key>` or `KEY` required, `[file]` optional, a last one ending in `...` taking any more; one missing (`missing <key>`) or one too many (`unexpected argument x`) is a usage error, and `positionals` comes back typed as `[string, string?]`. `fail(message, code = 2, hint?)` ends a command, the hint printed under the error; `badUsage(message)` ends it with a `UsageError`, which `parse`, `wholeNumber` and `duration` throw too and which gets the hint `run <cli> <command> --help for its options`; `wholeNumber` reads a numeric option.
 - `table`, `truncate`, `formatSeconds`, `formatAge` and `upTo` format output.
 - `runMain({ name, version, run })` runs a CLI that is a single command: `--version` or `-v` alone prints the version, and an `Exit` or any error prints `error: <name>: <message>` and becomes the exit code. `await` it into `process.exitCode`.
@@ -41,8 +44,9 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `<bin> __complete <words>... <word>` is answered by `runCli` and `runMain` for shell completion: the subcommands with their summaries, a leaf command's options (read by running it until its `parse` call throws them, so every command parses its arguments first), or `__files__` where a path fits.
 - `parse(args, usage, options, { rest: true })` stops at the first `--` and returns what follows untouched as `rest` (`out -n 200 -- <cmd>`), `undefined` without a `--`; `{ allowNegative: true }` takes `--no-<flag>` as `false` for a boolean flag.
 - `readInput(path, { noStdin })` reads a file, or stdin when the path is `-`; a missing file or a stdin left on the terminal ends the command with a message.
-- `runCommand(argv, { cwd, env, stdin })` runs a command and returns `{ code, text, output, chunks }`, the output of both streams (in arrival order, tagged by stream in `chunks`); it throws when the command cannot start. `exitCodeOf(code, signal)` is the exit code a shell reports.
+- `runCommand(argv, { cwd, env, stdin, timeoutMs, signal, maxBytes, onChunk, onStart })` runs a command and returns `{ code, text, output, chunks, timedOut, truncated }`, the output of both streams (in arrival order, tagged by stream in `chunks`); it throws when the command cannot start. With `timeoutMs`, `signal`, `onChunk` or `onStart` the child leads its own process group, ended whole (SIGTERM, SIGKILL after 2 s) when the timeout passes, the signal aborts or `onChunk` throws, the pipes still read to the end: `timedOut` is then true, for the caller to exit 2. `maxBytes` caps what `chunks`, `output` and `text` keep (`truncated`), `onChunk` sees every chunk, and `onStart` hands over `{ kill }` for the whole group, to pass to `holdSignals().forward`. `exitCodeOf(code, signal)` is the exit code a shell reports.
 - `holdSignals(cleanup?)` takes SIGINT, SIGTERM and SIGHUP over until `release()`: a signal goes to the child given to `forward(child)`, so the CLI exits with the child's code; without one, `cleanup(signal)` runs and the signal is raised again, ending the process as it would have; without either, it is only kept in `signal`, for the caller to wind down (`base` holds them while its worktree exists).
+- `privateLogDirectory(name)` returns a folder for log files only this user reads (`$XDG_RUNTIME_DIR` or `~/.cache/agent-tools`, mode 0700, verified with `lstat` when it exists, else a fresh temp folder), `createLog(path)` opens a 0600 file that must not exist (returning its descriptor), and `sweepLogs(dir, maxAgeMs?)` removes what is older than a day, subfolders included.
 - `openUrl(target, env?)` opens a URL, or a file path made absolute, with the command `BROWSER` names or the platform's opener (`xdg-open`, `open`, `start`), without waiting; it returns `false` when that command cannot start.
 - Every command's `parse`, and `runCli` before the command name (`ft --plain runs`), takes `--color auto|always|never` and `--plain` (`--color never`), unless the command has its own option of that name. `always` sets `FORCE_COLOR=1` and `never` sets `NO_COLOR=1`, each dropping the other, so the kit's colours, marks and redrawn lines follow, and so do the processes the command starts; `always` colours a pipe but never redraws in one. `applyOutput(color, plain, env?)` is what they run.
 - `--help` lists the commands under `Commands:`, then a heading per `group` a command names (`{ summary, group: 'Admin', run }`), then the level's `Options:` and the `Examples:` the CLI or a group's `examples` give (`['ft ci', ['ft ci HEAD~1', 'the commit before']]`, a note shown dimmed after `#`); a command's own examples go to `parse(args, usage, options, { examples })`, shown under its options.
@@ -53,6 +57,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `stripAnsi(text)` removes colour and cursor codes, and `distance(a, b)` is the edit distance between two names.
 - `table(rows, { cellWidth, header })` also flattens each cell's line breaks and cuts it to `cellWidth`, and with `header` prints the first row bold on a terminal; and `formatDuration(ms)` formats milliseconds like `formatSeconds` but with one decimal under a minute (`0.3s`).
 - `ok(text, detail?)`, `note`, `warn` and `problem` print a status line marked with a green ✓, a dimmed ·, a yellow ! or a red ✗ (`ok` and `note` on stdout, the others on stderr), the detail dimmed after the text; plain, the marks read `ok:`, `note:`, `warning:` and `error:`. `marked(mark, text, stream, detail?)` returns such a line, `paint(stream)` the colours for a stream and `takesControlCodes(stream)` whether it draws in place.
+- `isSecretName(name)` is true for the name of a variable, column or JSON key that holds a secret (`API_TOKEN`, `DB_PASS`, `SMTP_PWD`, `clientSecret`, `session_id`, `ssn`), by whole words so `compass` and `author` stay plain; `ev`, `redact` and `db` share it.
 - `capture(fn)` from `@kaynooo/cli-kit/test` runs a command in-process and returns `{ result, out, err }`, what it printed through `console` and `process.stdout`/`stderr`, so a test needs no spy.
 - `findUp(names, from?)` is the nearest of `names` in the current folder (or `from`) or one above it; `loadConfig(names, { from?, path? })` imports the nearest config (`.ts`, `.js` or `.json`), or the file `path` names, and returns `{ path, dir, config }` with its default export for the caller to check, `undefined` when there is none. A named file missing, one failing to import or one without a default export ends the command with exit 1.
 - `@kaynooo/cli-kit/prompt` asks on the terminal, on stderr:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "What every @kaynooo CLI shares: argument parsing with --help, a command dispatcher with typo hints and shell completion, and output formatting.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",

package/src/args.ts

@@ -276,14 +276,17 @@ function nearestOption(message: string, options: Options, allowNegative: boolean
   return meant === undefined ? undefined : `did you mean ${known.find(flag => flag.replace(DASHES, '') === meant)}?`
 }
 
+const WHOLE = /^\d+$/
+
+// A name written `<run id>` is a positional and is printed as is, any other is an option printed `--name`.
 export function wholeNumber(value: string | undefined, name: string, fallback: number, min = 1): number {
   if (value === undefined)
     return fallback
 
   const number = Number(value)
 
-  if (!Number.isInteger(number) || number < min)
-    badUsage(`--${name} takes a whole number from ${min}, not ${value}`)
+  if (!WHOLE.test(value) || !Number.isSafeInteger(number) || number < min)
+    badUsage(`${name.startsWith('<') ? name : `--${name}`} takes a whole number from ${min}, not ${value}`)
 
   return number
 }

package/src/ci.ts

@@ -0,0 +1,132 @@
+import { Exit, fail } from './args'
+import { formatDuration } from './format'
+import { liveRegion } from './progress'
+import { cwdGone, isPermanentFailure } from './tool'
+
+export interface CiStall {
+  // The message the wait fails with.
+  message: string
+  // Fails at once instead of after `stalledMs`.
+  certain?: boolean
+}
+
+export interface CiWait<T> {
+  // The command's name, as its warnings print it (`ft ci`).
+  tool: string
+  // The abbreviated sha the wait is for.
+  short: string
+  giveUpMs: number
+  // How long the wait goes on with nothing covering the commit.
+  noneMs: number
+  // How long queued work may sit while nothing moves.
+  stalledMs: number
+  pollMs?: number
+  // The message the wait fails with once nothing covered the commit for `noneMs`.
+  noneMessage: string
+  // What covers the commit now, or undefined; a refusal such as a commit not on the branch is thrown as an Exit.
+  covering: () => Promise<T | undefined>
+  finished: (found: T) => boolean
+  // Identifies what is followed, so `announce` runs again when it changes.
+  key: (found: T) => string
+  announce: (found: T) => void
+  // The links to what is followed, for the messages of a wait that ends unfinished.
+  links: (found: T) => string
+  // What a covering that failed leaves of the followed value once it can be read as over, or undefined to go on polling.
+  settle: (found: T) => Promise<T | undefined>
+  // Why the unfinished work is not moving, or undefined while it moves.
+  stall?: (found: T) => Promise<CiStall | undefined>
+  // The lines of a live region under the wait, on a terminal.
+  lines?: (spinner: string, found: T | undefined, startedAt: number) => string[]
+}
+
+const POLL = 15_000
+
+// Waits until what covers a commit has finished, polling `covering`: a poll failing for a network reason is retried, one failing for good (a missing binary, a 401, 403 or 404) or a refusal ends the wait.
+export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
+  const { tool, short, giveUpMs, noneMs, stalledMs, pollMs = POLL } = wait
+  const started = Date.now()
+  let seen = started
+  let moving = started
+  let followed = ''
+  let found: T | undefined
+  const region = wait.lines === undefined ? undefined : liveRegion(spinner => wait.lines?.(spinner, found, started) ?? [])
+  const suffix = () => found === undefined ? '' : `: ${wait.links(found)}`
+
+  // A failure to read the stall is retried on the next poll, and leaves the stall unknown.
+  async function stallOf(current: T): Promise<CiStall | undefined | 'unknown'> {
+    try {
+      return await wait.stall?.(current)
+    }
+    catch (error) {
+      if (error instanceof Exit || isPermanentFailure(error))
+        throw error
+
+      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+
+      return 'unknown'
+    }
+  }
+
+  try {
+    for (;;) {
+      if (Date.now() - started > giveUpMs)
+        fail(`CI has not finished on ${short} in ${formatDuration(giveUpMs)}${suffix()}`)
+
+      // The forge or origin missing one poll leaves the wait to the next, unless what is followed is over by then.
+      try {
+        found = await wait.covering()
+      }
+      catch (error) {
+        if (error instanceof Exit)
+          throw error
+
+        if (cwdGone())
+          fail(`the working directory was removed while waiting for CI on ${short}${suffix()}`)
+
+        if (isPermanentFailure(error))
+          fail(error instanceof Error ? error.message : String(error))
+
+        console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+
+        const latest = found === undefined ? undefined : await wait.settle(found)
+
+        if (latest !== undefined)
+          return latest
+
+        await Bun.sleep(pollMs)
+
+        continue
+      }
+
+      if (found !== undefined) {
+        seen = Date.now()
+
+        const key = wait.key(found)
+
+        if (key !== followed) {
+          followed = key
+          moving = Date.now()
+          wait.announce(found)
+        }
+
+        if (wait.finished(found))
+          return found
+
+        const stall = await stallOf(found)
+
+        if (stall === undefined)
+          moving = Date.now()
+        else if (stall !== 'unknown' && (stall.certain === true || Date.now() - moving > stalledMs))
+          fail(stall.message)
+      }
+      else if (Date.now() - seen > noneMs) {
+        fail(wait.noneMessage)
+      }
+
+      await Bun.sleep(pollMs)
+    }
+  }
+  finally {
+    region?.stop()
+  }
+}

package/src/config.ts

@@ -1,10 +1,11 @@
 import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import process from 'node:process'
 import { fail } from './args'
 
-// The nearest of `names` in `from` or a folder above it, the first name winning within one folder.
-export function findUp(names: string | string[], from = process.cwd()): string | undefined {
+// The nearest of `names` in `from` or a folder above it, the first name winning within one folder; the walk ends after a folder `stop` accepts.
+export function findUp(names: string | string[], from = process.cwd(), stop: (dir: string) => boolean = () => false): string | undefined {
   const wanted = typeof names === 'string' ? [names] : names
 
   for (let dir = resolve(from); ; dir = dirname(dir)) {
@@ -13,11 +14,16 @@ export function findUp(names: string | string[], from = process.cwd()): string |
     if (found !== undefined)
       return found
 
-    if (dirname(dir) === dir)
+    if (stop(dir) || dirname(dir) === dir)
       return undefined
   }
 }
 
+// A config is looked for up to the repository root or the home folder, never in a folder above them where a stranger's file could sit.
+function endsWalk(dir: string): boolean {
+  return dir === resolve(homedir()) || existsSync(join(dir, '.git'))
+}
+
 export interface ConfigSettings {
   // Where the search starts, the current folder by default.
   from?: string
@@ -33,9 +39,9 @@ export interface LoadedConfig {
   config: unknown
 }
 
-// Imports the nearest config named `names` (`.ts`, `.js` or `.json`), or the one `path` names; undefined when none is found. A named file missing, one failing to import or one without a default export ends the command.
+// Imports the nearest config named `names` (`.ts`, `.js` or `.json`) up to the git root or the home folder, or the one `path` names; undefined when none is found. A named file missing, one failing to import or one without a default export ends the command.
 export async function loadConfig(names: string | string[], { from = process.cwd(), path }: ConfigSettings = {}): Promise<LoadedConfig | undefined> {
-  const file = path === undefined ? findUp(names, from) : resolve(from, path)
+  const file = path === undefined ? findUp(names, from, endsWalk) : resolve(from, path)
 
   if (file === undefined)
     return undefined

package/src/git.ts

@@ -0,0 +1,55 @@
+import { basename, dirname } from 'node:path'
+import process from 'node:process'
+import { fail } from './args'
+import { cwdGone, runTool } from './tool'
+
+const ORIGIN_PREFIX = /^origin\//
+
+// How long a git call that reaches the network waits for origin.
+export const GIT_NETWORK_MS = 60_000
+
+// Runs git and returns its trimmed output; throws with git's own message on a failure, or when git cannot start or outlives `timeoutMs`.
+export async function git(args: string[], timeoutMs?: number): Promise<string> {
+  const result = await runTool(`git ${args.join(' ')}`, ['git', ...args], { timeoutMs })
+
+  if (result.code !== 0)
+    throw new Error(`git ${args.join(' ')}: ${result.stderr.trim() || `exit ${result.code}`}${cwdGone() ? ' (the working directory was removed)' : ''}`)
+
+  return result.stdout.trim()
+}
+
+export async function gitOk(args: string[]): Promise<boolean> {
+  return (await runTool(`git ${args.join(' ')}`, ['git', ...args])).code === 0
+}
+
+export async function resolveCommit(ref: string): Promise<string> {
+  const sha = (await runTool('git rev-parse', ['git', 'rev-parse', '--verify', '-q', '--end-of-options', `${ref}^{commit}`])).stdout.trim()
+
+  if (sha === '')
+    fail(`no commit ${ref}`)
+
+  return sha
+}
+
+// Fetches one branch of origin; a name that is no branch, such as `--upload-pack=<command>`, is refused before git reads it, and the refspec is spelled out so it can never be an option.
+export async function fetchBranch(branch: string): Promise<void> {
+  if (branch.startsWith('-') || !await gitOk(['check-ref-format', '--branch', branch]))
+    fail(`${branch} is not a branch name`)
+
+  await git(['fetch', '-q', 'origin', `refs/heads/${branch}`], GIT_NETWORK_MS)
+}
+
+// The branch origin's HEAD names, which is the repository's default branch once cloned or `git remote set-head origin -a` ran.
+export async function defaultBranch(): Promise<string> {
+  const head = (await runTool('git symbolic-ref', ['git', 'symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD'])).stdout.trim()
+
+  return head === '' ? 'main' : head.replace(ORIGIN_PREFIX, '')
+}
+
+// A linked worktree can be deleted while a wait runs in it, so the wait moves to the main checkout, which outlives it.
+export async function leaveWorktree(): Promise<void> {
+  const common = await git(['rev-parse', '--path-format=absolute', '--git-common-dir'])
+
+  if (basename(common) === '.git')
+    process.chdir(dirname(common))
+}

package/src/index.ts

@@ -1,9 +1,14 @@
 export * from './args'
 export * from './chart'
+export * from './ci'
 export * from './cli'
 export * from './config'
 export * from './format'
+export * from './git'
 export * from './limit'
+export * from './logs'
 export * from './process'
+export * from './secrets'
 export * from './style'
 export * from './text'
+export * from './tool'

package/src/logs.ts

@@ -0,0 +1,72 @@
+import { lstatSync, openSync } from 'node:fs'
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+// Whether the folder is a real directory (not a link) that only this user can use.
+function isPrivateDirectory(path: string): boolean {
+  try {
+    const info = lstatSync(path, { throwIfNoEntry: false })
+
+    return info !== undefined && info.isDirectory() && info.uid === (process.getuid?.() ?? info.uid) && (info.mode & 0o077) === 0
+  }
+  catch {
+    return false
+  }
+}
+
+// A folder for log files that only this user can read: `<name>` under $XDG_RUNTIME_DIR, else ~/.cache/agent-tools. When one already exists it must be a private directory of this user, otherwise a fresh private folder in the temp directory is used instead of trusting it.
+export async function privateLogDirectory(name: string, env: Record<string, string | undefined> = process.env): Promise<string> {
+  const runtime = env.XDG_RUNTIME_DIR
+  const base = runtime === undefined || runtime === '' ? join(homedir(), '.cache', 'agent-tools') : join(runtime, 'agent-tools')
+  const path = join(base, name)
+
+  try {
+    await mkdir(path, { recursive: true, mode: 0o700 })
+
+    if (isPrivateDirectory(path))
+      return path
+  }
+  catch {
+    // Falls through to the temp folder below.
+  }
+
+  return mkdtemp(join(tmpdir(), `${name.replaceAll('/', '-')}-`))
+}
+
+// Removes what is older than `maxAgeMs` in the folder, and the empty subfolders it leaves, best effort since another run may be doing the same.
+export async function sweepLogs(dir: string, maxAgeMs = DAY_MS, now = Date.now()): Promise<void> {
+  let names: string[]
+
+  try {
+    names = await readdir(dir)
+  }
+  catch {
+    return
+  }
+
+  for (const name of names) {
+    const path = join(dir, name)
+
+    try {
+      const info = await stat(path)
+
+      if (info.isDirectory())
+        await sweepLogs(path, maxAgeMs, now)
+
+      if (now - info.mtimeMs > maxAgeMs)
+        await rm(path, { force: true, recursive: info.isDirectory() })
+    }
+    catch {
+      continue
+    }
+  }
+}
+
+// Creates a log file nobody else can read and that must not exist yet, so a planted link is never followed; returns its descriptor, for writeSync.
+export function createLog(path: string): number {
+  return openSync(path, 'wx', 0o600)
+}

package/src/process.ts

@@ -14,12 +14,26 @@ export interface Ran {
   // The bytes of every chunk joined.
   output: Buffer
   text: string
+  // The command was ended because `timeoutMs` passed, its code then being the signal's.
+  timedOut: boolean
+  // More than `maxBytes` came, and the rest was left out of chunks, output and text.
+  truncated: boolean
 }
 
 export interface RunSettings {
   cwd?: string
   env?: Record<string, string | undefined>
   stdin?: 'inherit' | 'ignore'
+  // Ends the command and its children after this long.
+  timeoutMs?: number
+  // Ends the command and its children when aborted.
+  signal?: AbortSignal
+  // Bytes kept in the result; the pipes are still read to the end.
+  maxBytes?: number
+  // Called with each chunk as it arrives; throwing ends the command and rethrows once the pipes are drained.
+  onChunk?: (chunk: Chunk) => void
+  // Called once the command runs, with a handle that sends a signal to its whole process group, for `holdSignals().forward`.
+  onStart?: (child: { kill: (signal: NodeJS.Signals) => void }) => void
 }
 
 export interface HeldSignals {
@@ -31,16 +45,12 @@ export interface HeldSignals {
   release: () => void
 }
 
+const KILL_GRACE_MS = 2000
 const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
 // A scheme of two letters or more, so a Windows drive is read as a path.
 const SCHEME = /^[a-z][\w+.-]+:/i
 const OPENERS: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ['open'], win32: ['cmd', '/c', 'start', ''] }
 
-async function collect(stream: ReadableStream<Uint8Array>, name: Chunk['stream'], chunks: Chunk[]): Promise<void> {
-  for await (const data of stream)
-    chunks.push({ stream: name, data })
-}
-
 // The exit code a shell would report: the code, or 128 plus the signal.
 export function exitCodeOf(code: number | null, signal: NodeJS.Signals | number | null): number {
   if (code !== null)
@@ -106,15 +116,106 @@ export function openUrl(target: string, env: Record<string, string | undefined>
   }
 }
 
-// Runs a command with stdout and stderr captured; throws when it cannot be started.
-export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore' }: RunSettings = {}): Promise<Ran> {
+// Runs a command with stdout and stderr captured; throws when it cannot be started. With `timeoutMs`, `signal`, `onStart` or `onChunk` the child leads its own process group, and the whole group is ended (SIGTERM, then SIGKILL after a short grace) on the timeout, an abort or a throwing `onChunk`; the pipes are drained to their end either way.
+export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore', timeoutMs, signal, maxBytes = Infinity, onChunk, onStart }: RunSettings = {}): Promise<Ran> {
   const chunks: Chunk[] = []
-  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe' })
+  const grouped = timeoutMs !== undefined || signal !== undefined || onStart !== undefined || onChunk !== undefined
+  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe', ...(grouped ? { detached: true } : {}) })
+  const state = { kept: 0, truncated: false, timedOut: false, failure: undefined as unknown, done: false }
+  const timers: ReturnType<typeof setTimeout>[] = []
+
+  const killGroup = (killing: NodeJS.Signals) => {
+    if (state.done)
+      return
+
+    try {
+      if (grouped)
+        process.kill(-proc.pid, killing)
+      else
+        proc.kill(killing)
+    }
+    catch {
+      // The group is already gone.
+    }
+  }
+
+  const stop = () => {
+    killGroup('SIGTERM')
+    timers.push(setTimeout(killGroup, KILL_GRACE_MS, 'SIGKILL'))
+  }
+
+  const onAbort = () => stop()
+
+  if (timeoutMs !== undefined) {
+    timers.push(setTimeout(() => {
+      state.timedOut = true
+      stop()
+    }, timeoutMs))
+  }
+
+  if (signal?.aborted === true)
+    onAbort()
+  else
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+  onStart?.({ kill: killing => killGroup(killing) })
+
+  const drain = async (stream: ReadableStream<Uint8Array>, name: Chunk['stream']) => {
+    for await (const data of stream) {
+      if (state.failure !== undefined)
+        continue
 
-  await Promise.all([collect(proc.stdout, 'stdout', chunks), collect(proc.stderr, 'stderr', chunks)])
-  await proc.exited
+      try {
+        onChunk?.({ stream: name, data })
+      }
+      catch (error) {
+        state.failure = error
+        stop()
 
-  const output = Buffer.concat(chunks.map(({ data }) => data))
+        continue
+      }
 
-  return { code: exitCodeOf(proc.exitCode, proc.signalCode), chunks, output, text: output.toString() }
+      if (state.kept + data.length > maxBytes) {
+        state.truncated = true
+
+        continue
+      }
+
+      state.kept += data.length
+      chunks.push({ stream: name, data })
+    }
+  }
+
+  try {
+    await Promise.all([drain(proc.stdout, 'stdout'), drain(proc.stderr, 'stderr')])
+    await proc.exited
+  }
+  finally {
+    state.done = true
+
+    for (const timer of timers)
+      clearTimeout(timer)
+
+    signal?.removeEventListener('abort', onAbort)
+  }
+
+  if (state.failure !== undefined)
+    throw state.failure
+
+  const joined = () => Buffer.concat(chunks.map(({ data }) => data))
+  let output: Buffer | undefined
+  let text: string | undefined
+
+  return {
+    code: exitCodeOf(proc.exitCode, proc.signalCode),
+    chunks,
+    timedOut: state.timedOut,
+    truncated: state.truncated,
+    get output() {
+      return output ??= joined()
+    },
+    get text() {
+      return text ??= (output ??= joined()).toString()
+    },
+  }
 }

package/src/secrets.ts

@@ -0,0 +1,10 @@
+// Parts of a name that make it secret wherever they sit in it (`DB_PASSWORD`, `PGPASSWORD`, `clientSecret`).
+const SECRET_PART = /token|secret|passw|credential|private|dsn|apikey|accesskey|key$/i
+// Whole words of a name that make it secret (`DB_PASS`, `SMTP_PWD`, `encryptionKey`, `session_id`), so `compass`, `author` or `keyword` stay plain.
+const SECRET_WORDS = new Set(['key', 'pass', 'pwd', 'auth', 'salt', 'cookie', 'session', 'jwt', 'ssn', 'iban', 'card', 'cvv', 'otp'])
+const WORD_BREAKS = /[^a-zA-Z\d]+|(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+
+// True for the name of a variable, a column or a JSON key that holds a secret, by one definition shared by ev, redact and db.
+export function isSecretName(name: string): boolean {
+  return SECRET_PART.test(name) || name.split(WORD_BREAKS).some(word => SECRET_WORDS.has(word.toLowerCase()))
+}

package/src/shell.ts

@@ -1,20 +1,78 @@
-// `text` is the piece as written, `command` the same less its heredoc bodies, which are data and never commands; `separator` is what ends it (`|`, `&&`, `;`, a newline...), empty for the last; `expanded` holds the bodies of its unquoted heredocs, where the shell still runs `$(...)`.
-export interface Piece { text: string, start: number, end: number, command: string, separator: string, expanded: string }
+// `text` is the piece as written, `command` the same less its heredoc bodies and comments, which are data and never commands; `separator` is what ends it (`|`, `&&`, `;`, a newline...), empty for the last; `expanded` holds the bodies of its unquoted heredocs, where the shell still runs `$(...)`, and `heredocs` those of all its heredocs.
+export interface Piece { text: string, start: number, end: number, command: string, separator: string, expanded: string, heredocs: string[] }
 export interface Invocation { program: string, args: string[], assignments: string[], isWrapped: boolean }
 
 const SEPARATORS = new Set(['\n', ';', '|'])
 const PLAIN_BREAKERS = new Set(['<', '>', '(', ')', '&', '|'])
+const GLOB_CHARS = new Set(['*', '?', '['])
+const COMMENT_PREFIXES = new Set([';', '&', '|', '(', ')'])
 const WHITESPACE = /\s/
 const ASSIGNMENT = /^\w+=/
 const TRAILING_SLASHES = /\/+$/
+const TRAILING_CR = /\r$/
 const LEADING_TILDE = /^~(?=\/|$)/
 const LEADING_TABS = /^\t+/
 const OPENERS = /^[({]+/
 const CLOSERS = /[)}]+$/
+const CASE_LABEL = /^\(?[^\s()]*\)$/
+const REDIRECT_ONLY = /^\d*(?:<|>|>>|<&|>&|&>|>\||<>)$/
+const REDIRECT_START = /^\d*[<>]|^&>/
+const SAFE_WORD = /^[\w@%+=:,./-]+$/
+const LEADING_HEX = /^[\da-f]*/i
 const DOUBLE_QUOTED_ESCAPES = new Set(['$', '`', '"', '\\'])
 const HEREDOC = /^<<(-?)[ \t]*(?:'([^']*)'|"([^"]*)"|([^\s;&|<>()-][^\s;&|<>()]*))/
-// Programs that run the command following them, which is the one that counts.
-const WRAPPERS = new Set(['command', 'env', 'sudo', 'exec', 'nohup', 'time'])
+// The quote opened by `$'`, inside which a backslash escapes and decodes.
+const ANSI_QUOTE = '$\''
+const ANSI_ESCAPES: Record<string, string> = { 'n': '\n', 't': '\t', 'r': '\r', 'a': '\x07', 'b': '\b', 'f': '\f', 'v': '\v', 'e': '\x1B', 'E': '\x1B', '\\': '\\', '\'': '\'', '"': '"', '?': '?' }
+const ANSI_DIGITS: Record<string, number> = { x: 2, u: 4, U: 8 }
+const OCTAL = /^[0-7]{1,3}/
+// Keywords opening a command of a compound statement, which the command following them is the one that counts.
+const KEYWORDS = new Set(['then', 'do', 'else', 'if', 'elif', 'while', 'until', '!', '{', '}'])
+const MAX_DEPTH = 8
+const MAX_BRACES = 256
+// Programs reading a command string with `-c`.
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ash', 'ksh'])
+const COMMAND_STRING_PROGRAMS = new Set([...SHELLS, 'su', 'runuser'])
+const SHELL_VALUE_OPTIONS = new Set(['-o', '-O', '--rcfile', '--init-file'])
+const PRINTERS = new Set(['echo', 'printf'])
+const FIND_EXEC = new Set(['-exec', '-execdir', '-ok', '-okdir'])
+
+// Programs that run the command following them, which is the one that counts, with the options taking a value and the operands before that command.
+interface WrapperSpec { short: string, long: readonly string[], operands: number }
+
+function wrapper(short = '', long: readonly string[] = [], operands = 0): WrapperSpec {
+  return { short, long, operands }
+}
+
+const WRAPPERS = new Map<string, WrapperSpec>([
+  ['command', wrapper()],
+  ['builtin', wrapper()],
+  ['nohup', wrapper()],
+  ['setsid', wrapper()],
+  ['busybox', wrapper()],
+  ['exec', wrapper('a')],
+  ['time', wrapper('fo', ['--format', '--output'])],
+  ['env', wrapper('uCS', ['--unset', '--chdir', '--split-string', '--argv0'])],
+  ['sudo', wrapper('ughpCTrtUDR', ['--user', '--group', '--host', '--prompt', '--close-from', '--command-timeout', '--role', '--type', '--other-user', '--chdir', '--chroot'])],
+  ['doas', wrapper('uC')],
+  ['timeout', wrapper('sk', ['--signal', '--kill-after'], 1)],
+  ['nice', wrapper('n', ['--adjustment'])],
+  ['ionice', wrapper('cnpPu', ['--class', '--classdata', '--pid', '--pgid', '--uid'])],
+  ['stdbuf', wrapper('ioe', ['--input', '--output', '--error'])],
+  ['chroot', wrapper('', ['--userspec', '--groups'], 1)],
+  ['xargs', wrapper('IndsEaPL', ['--max-args', '--max-procs', '--max-chars', '--delimiter', '--arg-file', '--eof', '--max-lines', '--process-slot-var'])],
+])
+
+function closerOf(quote: string): string {
+  return quote === ANSI_QUOTE ? '\'' : quote
+}
+
+// A `#` starts a comment at the start of a word, never inside one such as `$#` or `a#b`.
+function startsComment(command: string, i: number): boolean {
+  const before = command[i - 1] ?? ''
+
+  return i === 0 || WHITESPACE.test(before) || COMMENT_PREFIXES.has(before)
+}
 
 // A lone `&` sends the command before it to the background, unless it belongs to a redirection such as `2>&1` or `&>`.
 function separatorWidth(command: string, i: number): number {
@@ -31,7 +89,7 @@ function separatorWidth(command: string, i: number): number {
   return SEPARATORS.has(char) ? 1 : 0
 }
 
-// Where the heredocs opened on a line end: from the newline closing that line to the end of the last delimiter line.
+// Where the heredocs opened on a line end: from the newline closing that line to the end of the last delimiter line, a CRLF one included.
 function heredocEnd(command: string, newline: number, words: readonly { word: string, stripsTabs: boolean }[]): number {
   let lineStart = newline + 1
 
@@ -39,7 +97,7 @@ function heredocEnd(command: string, newline: number, words: readonly { word: st
     while (lineStart <= command.length) {
       const next = command.indexOf('\n', lineStart)
       const lineEnd = next === -1 ? command.length : next
-      const line = command.slice(lineStart, lineEnd)
+      const line = command.slice(lineStart, lineEnd).replace(TRAILING_CR, '')
 
       lineStart = lineEnd + 1
 
@@ -66,10 +124,11 @@ function withoutRanges(command: string, start: number, end: number, ranges: read
   return text + command.slice(at, end)
 }
 
-// Splits on the shell separators outside quotes and heredocs, so the `;` and `|` of an inline script stay in its piece, each piece keeping where it sits in the command.
+// Splits on the shell separators outside quotes, comments and heredocs, so the `;` and `|` of an inline script stay in its piece, each piece keeping where it sits in the command.
 export function splitCommand(command: string): Piece[] {
   const bounds: [number, number, string][] = []
   const bodies: [number, number, boolean][] = []
+  const comments: [number, number][] = []
   let heredocs: { word: string, stripsTabs: boolean, isQuoted: boolean }[] = []
   let start = 0
   let quote: string | null = null
@@ -84,18 +143,35 @@ export function splitCommand(command: string): Piece[] {
     }
 
     if (quote !== null) {
-      if (char === quote)
+      if (char === closerOf(quote))
         quote = null
 
       continue
     }
 
+    if (char === '$' && command[i + 1] === '\'') {
+      quote = ANSI_QUOTE
+      i++
+
+      continue
+    }
+
     if (char === '\'' || char === '"') {
       quote = char
 
       continue
     }
 
+    if (char === '#' && startsComment(command, i)) {
+      const newline = command.indexOf('\n', i)
+      const end = newline === -1 ? command.length : newline
+
+      comments.push([i, end])
+      i = end - 1
+
+      continue
+    }
+
     const heredoc = char === '<' && command[i + 1] === '<' && command[i + 2] !== '<' ? HEREDOC.exec(command.slice(i)) : null
 
     if (heredoc) {
@@ -126,16 +202,21 @@ export function splitCommand(command: string): Piece[] {
   }
   bounds.push([start, command.length, ''])
 
-  const ranges = bodies.map(([from, to]): [number, number] => [from, to])
+  const ranges = [...bodies, ...comments].map(([from, to]): [number, number] => [from, to]).sort(([a], [b]) => a - b)
+
+  return bounds.map(([from, to, separator]) => {
+    const inside = bodies.filter(([body]) => body >= from && body < to)
 
-  return bounds.map(([from, to, separator]) => ({
-    text: command.slice(from, to),
-    start: from,
-    end: to,
-    command: withoutRanges(command, from, to, ranges),
-    separator,
-    expanded: bodies.filter(([body, , expands]) => expands && body >= from && body < to).map(([body, bodyEnd]) => command.slice(body, bodyEnd)).join(''),
-  }))
+    return {
+      text: command.slice(from, to),
+      start: from,
+      end: to,
+      command: withoutRanges(command, from, to, ranges),
+      separator,
+      expanded: inside.filter(([, , expands]) => expands).map(([body, bodyEnd]) => command.slice(body, bodyEnd)).join(''),
+      heredocs: inside.map(([body, bodyEnd]) => command.slice(body, bodyEnd)),
+    }
+  })
 }
 
 // True when the text holds no redirect, substitution, subshell or group outside single quotes, and closes every quote it opens.
@@ -146,19 +227,74 @@ export function isPlain(text: string): boolean {
     const char = text[i] ?? ''
     const isSubstitution = char === '`' || (char === '$' && text[i + 1] === '(')
 
+    if (quote === null && char === '$' && text[i + 1] === '\'') {
+      quote = ANSI_QUOTE
+      i++
+
+      continue
+    }
+
     if (char === '\\' && quote !== '\'')
       i++
-    else if (quote !== null && char === quote)
+    else if (quote !== null && char === closerOf(quote))
       quote = null
     else if (quote === null && (char === '"' || char === '\''))
       quote = char
-    else if (quote !== '\'' && (isSubstitution || (quote === null && PLAIN_BREAKERS.has(char))))
+    else if (quote !== '\'' && quote !== ANSI_QUOTE && (isSubstitution || (quote === null && PLAIN_BREAKERS.has(char))))
       return false
   }
 
   return quote === null
 }
 
+// How many `)` the text closes without opening, as the end of a subshell does.
+function unmatchedClosers(text: string): number {
+  let depth = 0
+  let unmatched = 0
+  let quote: string | null = null
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] ?? ''
+
+    if (quote === null && char === '$' && text[i + 1] === '\'') {
+      quote = ANSI_QUOTE
+      i++
+
+      continue
+    }
+
+    if (char === '\\' && quote !== '\'')
+      i++
+    else if (quote !== null && char === closerOf(quote))
+      quote = null
+    else if (quote === null && (char === '"' || char === '\''))
+      quote = char
+    else if (quote === null && char === '(')
+      depth++
+    else if (quote === null && char === ')' && depth > 0)
+      depth--
+    else if (quote === null && char === ')')
+      unmatched++
+  }
+
+  return unmatched
+}
+
+// A piece less the `(` opening its subshell and the `)` closing it, so the last word of `(cat .env)` is the file.
+function withoutSubshell(text: string): string {
+  let result = text.trim()
+  let closers = unmatchedClosers(result)
+
+  while (result.startsWith('(')) result = result.slice(1).trimStart()
+
+  while (closers > 0 && result.endsWith(')')) {
+    result = result.slice(0, -1).trimEnd()
+    closers--
+  }
+
+  return result
+}
+
 // The index of the `)` closing the `(` at `open`, past nested parentheses and quotes; the text's end when it never closes.
 function closingParen(text: string, open: number): number {
   let depth = 0
@@ -171,9 +307,13 @@ function closingParen(text: string, open: number): number {
       i++
     }
     else if (quote !== null) {
-      if (char === quote)
+      if (char === closerOf(quote))
         quote = null
     }
+    else if (char === '$' && text[i + 1] === '\'') {
+      quote = ANSI_QUOTE
+      i++
+    }
     else if (char === '\'' || char === '"') {
       quote = char
     }
@@ -200,22 +340,29 @@ function closingBackquote(text: string, open: number): number {
   return text.length
 }
 
-// The bodies of the outermost `$(...)` and backquotes; quotes only count where `isQuoting`, as a heredoc body holds them as plain text.
+// The bodies of the outermost `$(...)`, `<(...)`, `>(...)` and backquotes; quotes only count where `isQuoting`, as a heredoc body holds them as plain text.
 function bodies(text: string, isQuoting: boolean): string[] {
   const found: string[] = []
   let quote: string | null = null
 
   for (let i = 0; i < text.length; i++) {
     const char = text[i] ?? ''
+    const next = text[i + 1]
 
     if (quote === '\'') {
       if (char === '\'')
         quote = null
     }
+    else if (quote === ANSI_QUOTE) {
+      if (char === '\\')
+        i++
+      else if (char === '\'')
+        quote = null
+    }
     else if (char === '\\') {
       i++
     }
-    else if (char === '$' && text[i + 1] === '(') {
+    else if ((char === '$' && next === '(') || (isQuoting && quote === null && (char === '<' || char === '>') && next === '(')) {
       const end = closingParen(text, i + 1)
 
       found.push(text.slice(i + 2, end))
@@ -230,6 +377,10 @@ function bodies(text: string, isQuoting: boolean): string[] {
     else if (isQuoting && char === '"') {
       quote = quote === null ? char : null
     }
+    else if (isQuoting && char === '$' && next === '\'' && quote === null) {
+      quote = ANSI_QUOTE
+      i++
+    }
     else if (isQuoting && char === '\'' && quote === null) {
       quote = char
     }
@@ -238,13 +389,34 @@ function bodies(text: string, isQuoting: boolean): string[] {
   return found
 }
 
-// The commands each piece runs through `$(...)` or backquotes, inside double quotes and unquoted heredoc bodies too; a nested one is found by reading each result in turn.
+// The commands each piece runs through `$(...)`, `<(...)` or backquotes, inside double quotes and unquoted heredoc bodies too; a nested one is found by reading each result in turn.
 export function substitutions(command: string): string[] {
   return splitCommand(command).flatMap(piece => [...bodies(piece.command, true), ...bodies(piece.expanded, false)])
 }
 
-// A word as the shell would pass it; `isProse` when a quoted part of it holds whitespace, a message or a pattern rather than a path.
-export interface Word { text: string, isProse: boolean }
+// A word as the shell would pass it; `isProse` when a quoted part of it holds whitespace, a message or a pattern rather than a path, `hasGlob` and `hasBrace` when it holds an unquoted `*?[` or `{` the shell would expand.
+export interface Word { text: string, isProse: boolean, hasGlob: boolean, hasBrace: boolean }
+
+// What the backslash escape at `at` inside `$'...'` stands for, and the index of its last character.
+function ansiEscape(text: string, at: number): [string, number] {
+  const letter = text[at + 1] ?? ''
+  const simple = ANSI_ESCAPES[letter]
+
+  if (simple !== undefined)
+    return [simple, at + 1]
+
+  const hex = LEADING_HEX.exec(text.slice(at + 2, at + 2 + (ANSI_DIGITS[letter] ?? 0)))?.[0] ?? ''
+
+  if (hex !== '')
+    return [String.fromCodePoint(Number.parseInt(hex, 16)), at + 1 + hex.length]
+
+  const octal = OCTAL.exec(text.slice(at + 1))?.[0]
+
+  if (octal !== undefined)
+    return [String.fromCodePoint(Number.parseInt(octal, 8)), at + octal.length]
+
+  return [`\\${letter}`, at + 1]
+}
 
 // The words of a piece, quotes and line continuations removed.
 export function words(text: string): Word[] {
@@ -252,6 +424,8 @@ export function words(text: string): Word[] {
   let current = ''
   let isStarted = false
   let isProse = false
+  let hasGlob = false
+  let hasBrace = false
   let quote: string | null = null
 
   for (let i = 0; i < text.length; i++) {
@@ -263,11 +437,13 @@ export function words(text: string): Word[] {
 
     if (quote === null && (isContinuation || WHITESPACE.test(char))) {
       if (isStarted)
-        found.push({ text: current, isProse })
+        found.push({ text: current, isProse, hasGlob, hasBrace })
 
       current = ''
       isStarted = false
       isProse = false
+      hasGlob = false
+      hasBrace = false
 
       continue
     }
@@ -278,22 +454,39 @@ export function words(text: string): Word[] {
     isStarted = true
 
     // within double quotes a backslash escapes only `$`, a backtick, `"` and itself, and stays before anything else (`"v\d"`)
-    if (char === '\\' && quote === '"' && !DOUBLE_QUOTED_ESCAPES.has(text[i + 1] ?? ''))
+    if (char === '\\' && quote === ANSI_QUOTE) {
+      const [decoded, last] = ansiEscape(text, i)
+
+      current += decoded
+      i = last
+    }
+    else if (char === '\\' && quote === '"' && !DOUBLE_QUOTED_ESCAPES.has(text[i + 1] ?? '')) {
       current += char
-    else if (char === '\\' && quote !== '\'')
+    }
+    else if (char === '\\' && quote !== '\'') {
       current += text[++i] ?? ''
-    else if (quote !== null && char === quote)
+    }
+    else if (quote !== null && char === closerOf(quote)) {
       quote = null
-    else if (quote === null && (char === '"' || char === '\''))
+    }
+    else if (quote === null && char === '$' && text[i + 1] === '\'') {
+      quote = ANSI_QUOTE
+      i++
+    }
+    else if (quote === null && (char === '"' || char === '\'')) {
       quote = char
-    else
+    }
+    else {
       current += char
+      hasGlob ||= quote === null && GLOB_CHARS.has(char)
+      hasBrace ||= quote === null && char === '{'
+    }
 
     isProse ||= quote !== null && WHITESPACE.test(char)
   }
 
   if (isStarted)
-    found.push({ text: current, isProse })
+    found.push({ text: current, isProse, hasGlob, hasBrace })
 
   return found
 }
@@ -303,7 +496,45 @@ export function tokenize(text: string): string[] {
   return words(text).map(word => word.text)
 }
 
-// The program a piece runs, by its base name, past any subshell opener, variable assignment or wrapper such as `env` or `sudo`.
+// Drops the options of a wrapper and the values they take, then its leading operands; `env -S` splits its value into the command it runs.
+function skipOptions(tokens: string[], spec: WrapperSpec): void {
+  const take = (name: string, attached: string) => {
+    const value = attached === '' ? (tokens.shift() ?? '') : attached
+
+    if (name === 'S' || name === '--split-string')
+      tokens.unshift(...tokenize(value))
+  }
+
+  while (tokens[0] !== undefined && tokens[0].startsWith('-') && tokens[0] !== '-') {
+    const option = tokens.shift() ?? ''
+
+    if (option === '--')
+      break
+
+    if (option.startsWith('--')) {
+      const [name = '', ...value] = option.split('=')
+
+      if (spec.long.includes(name))
+        take(name, value.join('='))
+
+      continue
+    }
+
+    for (const [index, letter] of [...option.slice(1)].entries()) {
+      if (!spec.short.includes(letter))
+        continue
+
+      // the value is what follows the letter, else the next word
+      take(letter, option.slice(index + 2))
+
+      break
+    }
+  }
+
+  for (let operand = 0; operand < spec.operands; operand++) tokens.shift()
+}
+
+// The program a piece runs, by its base name, past any subshell opener, keyword, variable assignment or wrapper such as `env` or `sudo`.
 export function parseCommand(text: string): Invocation {
   const tokens = tokenize(text)
   const assignments: string[] = []
@@ -311,6 +542,7 @@ export function parseCommand(text: string): Invocation {
 
   for (;;) {
     const first = tokens[0] ?? ''
+    const spec = WRAPPERS.get(first.split('/').pop() ?? '')
 
     if (OPENERS.test(first)) {
       isWrapped = true
@@ -323,11 +555,24 @@ export function parseCommand(text: string): Invocation {
     else if (ASSIGNMENT.test(first)) {
       assignments.push(tokens.shift() ?? '')
     }
-    else if (WRAPPERS.has(first)) {
+    else if (KEYWORDS.has(first)) {
       isWrapped = true
       tokens.shift()
+    }
+    else if (first === 'case') {
+      isWrapped = true
+      const at = tokens.indexOf('in')
 
-      while (tokens[0]?.startsWith('-')) tokens.shift()
+      tokens.splice(0, at === -1 ? tokens.length : at + 1)
+    }
+    else if (tokens.length > 1 && CASE_LABEL.test(first)) {
+      isWrapped = true
+      tokens.shift()
+    }
+    else if (spec !== undefined) {
+      isWrapped = true
+      tokens.shift()
+      skipOptions(tokens, spec)
     }
     else {
       break
@@ -347,6 +592,193 @@ export function parseCommand(text: string): Invocation {
   return { program: program.split('/').pop() ?? '', args, assignments, isWrapped }
 }
 
+function quoted(word: string): string {
+  return SAFE_WORD.test(word) || word === '{}' ? word : `'${word.replaceAll('\'', '\'\\\'\'')}'`
+}
+
+// The command strings a piece hands to a shell with `-c`, wherever the shell sits in it (`docker exec db sh -c '...'`, `su -c '...'`).
+function commandStrings(tokens: readonly string[]): string[] {
+  const found: string[] = []
+
+  for (const [i, token] of tokens.entries()) {
+    const name = token.split('/').pop() ?? ''
+
+    if (!COMMAND_STRING_PROGRAMS.has(name))
+      continue
+
+    const isUser = name === 'su' || name === 'runuser'
+    let isValue = false
+
+    for (let j = i + 1; j < tokens.length; j++) {
+      const option = tokens[j] ?? ''
+
+      if (isValue) {
+        isValue = false
+
+        continue
+      }
+
+      if (SHELL_VALUE_OPTIONS.has(option)) {
+        isValue = true
+
+        continue
+      }
+
+      if (option.startsWith('--command=')) {
+        found.push(option.slice('--command='.length))
+
+        break
+      }
+
+      if (option === '--command' || (!option.startsWith('--') && option.startsWith('-') && option.slice(1).includes('c'))) {
+        found.push(tokens[j + 1] ?? '')
+
+        break
+      }
+
+      if (!option.startsWith('-') && !isUser)
+        break
+    }
+  }
+
+  return found
+}
+
+// A piece's arguments less its redirections, and the words fed to it as here-strings.
+function redirections(args: readonly string[]): { operands: string[], hereStrings: string[] } {
+  const operands: string[] = []
+  const hereStrings: string[] = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? ''
+
+    if (arg.startsWith('<<<'))
+      hereStrings.push(arg.length > 3 ? arg.slice(3) : (args[++i] ?? ''))
+    else if (REDIRECT_ONLY.test(arg))
+      i++
+    else if (!REDIRECT_START.test(arg))
+      operands.push(arg)
+  }
+
+  return { operands, hereStrings }
+}
+
+// The argv `find` hands to each `-exec`, up to its `;` or `+`.
+function findExecs(args: readonly string[]): string[] {
+  const found: string[] = []
+
+  for (const [i, arg] of args.entries()) {
+    if (!FIND_EXEC.has(arg))
+      continue
+
+    const rest = args.slice(i + 1)
+    const end = rest.findIndex(word => word === ';' || word === '+')
+
+    found.push((end === -1 ? rest : rest.slice(0, end)).map(quoted).join(' '))
+  }
+
+  return found
+}
+
+// The commands a piece makes a shell run besides its own: `sh -c` strings, `eval`, `find -exec`, and what is fed to a shell reading its input, heredocs, here-strings and an `echo` piped in.
+function nestedCommands(piece: Piece, previous: Piece | undefined): string[] {
+  const tokens = tokenize(piece.command)
+  const { program, args } = parseCommand(piece.command)
+  const found = commandStrings(tokens)
+
+  if (program === 'eval')
+    found.push(args.join(' '))
+
+  if (program === 'find')
+    found.push(...findExecs(args))
+
+  if (!SHELLS.has(program))
+    return found
+
+  const { operands, hereStrings } = redirections(args)
+
+  if (operands.length > 0)
+    return found
+
+  found.push(...piece.heredocs, ...hereStrings)
+
+  if (previous?.separator === '|') {
+    const before = parseCommand(previous.command)
+
+    if (PRINTERS.has(before.program))
+      found.push(...before.args, before.args.join(' '))
+  }
+
+  return found
+}
+
+// The command and every command it makes the shell run: substitutions, subshells, `sh -c` and `eval` strings, `find -exec`, and what is fed to a shell; each is one to check.
+export function commandsRun(command: string, depth = 0): string[] {
+  const found = [command]
+
+  if (depth >= MAX_DEPTH)
+    return found
+
+  const pieces = splitCommand(command)
+
+  for (const [index, piece] of pieces.entries()) {
+    const inner = withoutSubshell(piece.command)
+    const nested = [...bodies(piece.command, true), ...bodies(piece.expanded, false), ...nestedCommands(piece, pieces[index - 1])]
+
+    if (inner !== piece.command.trim())
+      nested.push(inner)
+
+    for (const each of nested)
+      found.push(...commandsRun(each, depth + 1))
+  }
+
+  return found
+}
+
+function expandBraces(word: string): string[] {
+  const open = word.indexOf('{')
+
+  if (open === -1)
+    return [word]
+
+  const alternatives: string[] = []
+  let depth = 0
+  let cut = open
+
+  for (let i = open; i < word.length; i++) {
+    const char = word[i]
+
+    if (char === '{') {
+      depth++
+    }
+    else if (char === ',' && depth === 1) {
+      alternatives.push(word.slice(cut + 1, i))
+      cut = i
+    }
+    else if (char === '}' && --depth === 0) {
+      if (alternatives.length === 0)
+        break
+
+      alternatives.push(word.slice(cut + 1, i))
+
+      const prefix = word.slice(0, open)
+      const suffix = word.slice(i + 1)
+
+      return alternatives.flatMap(alternative => expandBraces(prefix + alternative + suffix)).slice(0, MAX_BRACES + 1)
+    }
+  }
+
+  // no list at this brace: keep it and expand what follows
+  return expandBraces(word.slice(open + 1)).map(rest => `${word.slice(0, open + 1)}${rest}`)
+}
+
+// The words a word with `{a,b}` lists stands for, `.{e,}nv` being `.env` and `.nv`; a word with no list, or one growing past a sane size, is returned as it is.
+export function braceExpand(word: string): string[] {
+  const found = expandBraces(word)
+
+  return found.length > MAX_BRACES ? [word] : found
+}
+
 // Swaps each piece's text for its replacement, keeping the separators between them.
 export function replacePieces(command: string, replacements: ReadonlyMap<Piece, string>): string {
   let result = command

package/src/tool.ts

@@ -0,0 +1,71 @@
+import type { RunSettings } from './process'
+import process from 'node:process'
+import { formatDuration } from './format'
+import { runCommand } from './process'
+
+export interface ToolRun {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+// What an answer says when retrying it can only give the same answer: an expired token, a missing permission, a route or repository that does not exist.
+const PERMANENT = /\bHTTP (?:401|403|404)\b|unauthorized|forbidden|not found|couldn't be found|token is required/i
+
+// True once the directory the process runs in was deleted, as a worktree is after its work lands.
+export function cwdGone(): boolean {
+  try {
+    process.cwd()
+
+    return false
+  }
+  catch {
+    return true
+  }
+}
+
+class SpawnError extends Error {
+  constructor(message: string, readonly missing: boolean) {
+    super(message)
+  }
+}
+
+// A spawn failing before the command runs says only "No such file or directory", which names the working directory once it was deleted.
+export function spawnFailure(command: string, error: unknown): Error {
+  const gone = cwdGone()
+  const missing = !gone && (error as { code?: unknown } | undefined)?.code === 'ENOENT'
+
+  return new SpawnError(`${command}: ${error instanceof Error ? error.message : String(error)}${gone ? ' (the working directory was removed)' : ''}`, missing)
+}
+
+// True for a failure a poll cannot recover from: a binary that is not installed, or an answer of 401, 403 or 404.
+export function isPermanentFailure(error: unknown): boolean {
+  if (!(error instanceof Error))
+    return false
+
+  return (error instanceof SpawnError && error.missing) || PERMANENT.test(error.message)
+}
+
+// Runs a command and returns its code and both streams; throws, naming `label`, when it cannot start or outlives `timeoutMs`.
+export async function runTool(label: string, argv: string[], { timeoutMs, cwd, onStart }: { [K in 'timeoutMs' | 'cwd' | 'onStart']?: RunSettings[K] | undefined } = {}): Promise<ToolRun> {
+  let ran
+
+  try {
+    // The environment is passed whole so the program is looked up on the PATH as it is now, not as the process started with.
+    ran = await runCommand(argv, { env: process.env, ...(timeoutMs === undefined ? {} : { timeoutMs }), ...(cwd === undefined ? {} : { cwd }), ...(onStart === undefined ? {} : { onStart }) })
+  }
+  catch (error) {
+    throw spawnFailure(label, error)
+  }
+
+  if (ran.timedOut)
+    throw new Error(`${label}: no answer in ${formatDuration(timeoutMs ?? 0)}`)
+
+  const decoder = new TextDecoder()
+  const streams = { stdout: '', stderr: '' }
+
+  for (const { stream, data } of ran.chunks)
+    streams[stream] += decoder.decode(data, { stream: true })
+
+  return { code: ran.code, ...streams }
+}