@kaynooo/cli-kit 0.0.0-stage → 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaynooo <kaynooo@kevyn.fr>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @kaynooo/cli-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What every @kaynooo CLI shares, so each one parses, helps and fails the same way.
+
+```sh
+bun add @kaynooo/cli-kit
+```
+
+It ships its TypeScript source and runs on Bun only (>= 1.4.3). The agent-tools CLIs take it as a `workspace:*` dev dependency and bundle it at build; a CLI elsewhere takes it from the registry as a dependency.
+
+```ts
+import { parse, runCli } from '@kaynooo/cli-kit'
+
+process.exitCode = await runCli({
+  name: 'tool',
+  version: '1.0.0',
+  about: 'does things',
+  commands: {
+    // A command imports its module when it runs, so `tool --help` loads none of them.
+    build: { summary: 'build the project', run: async args => (await import('./commands/build')).run(args) },
+  },
+})
+```
+
+## Exit codes
+
+0 for success, help and version; 2 for a usage error (an unknown command, a bad option, a missing argument, what `parse` and `fail` throw by default); 1 for a command that ran and failed (`fail(message, 1)`, or any other error a command throws).
+
+## Look
+
+On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, command and flag names in cyan and descriptions dimmed; an error reads as a red `error`, the dimmed `<cli> <command>:` and the message, with a yellow `hint` under it. Piped, in CI or under `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb`, the same text prints with plain words (`error: demo greet: give a name`, `  hint: run demo greet --help for its options`), so logs and what agents read stay greppable. `FORCE_COLOR` forces colours as `@kaynooo/utils` reads it.
+
+## 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.
+- `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. `{ 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`.
+- `runCli` also takes `defaultCommand`, the command that gets the arguments when the first one names no command (`db "select 1"` runs `db query "select 1"`), its options listed in `<cli> --help` under the commands, and a command may be a group, `{ summary, commands, aliases? }`, dispatched with its own help and typo hints (`ft plan add`).
+- `<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.
+- `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).
+- `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.
+- `jsonOption(holds?)` is the `--json` flag, worded `print JSON` or `print JSON: <holds>` alike in every CLI, and `printJson(value)` prints the value indented on stdout.
+- `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.
+- `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:
+  - `select(question, choices, { initial })` picks one `{ value, label, hint }`: typing filters the choices (every word typed in the label or hint, case ignored, Backspace editing), the arrows move and Enter picks.
+  - `checklist(question, choices, { initial, toggle })` checks several the same way, Space toggling the choice under the cursor; `toggle(checked, value)` returns what is checked after it, for choices that pull others along, and flips the one choice by default.
+  - `confirm(question, { default })` answers y or n, Enter taking the default; `input(question, { default, mask, validate })` takes a line, `mask` drawing it as `*`, `validate(value)` returning a message shown under it until the answer passes.
+  - Each answers `undefined` once Escape or Ctrl+C cancels and leaves `✓ <question> <answer>` or `✗ <question> cancelled`; a list longer than the terminal (10 rows at most) scrolls with the cursor, a dimmed `… n more` above and below.
+  - Off a terminal, a prompt fails at once with exit 2, `cannot ask "<question>" off a terminal`, with `hint` under it when given (`{ hint: 'pass --yes' }`); none reads a piped line. Each takes a `terminal: { stdin, stderr }`, the process's by default, for a test to drive.
+- `@kaynooo/cli-kit/progress` draws `progressLine(stream?, env?)` on stderr, one line redrawn in place while a task runs (`⠹ prerendering ████████░░░░░░░░░░░░ 8/20 routes 4.2s`, the bar cyan on a dimmed track), fed `update({ step, done?, total?, unit? })` and ended with `stop()`, `done(text)` leaving `✓ <text> <time>` or `failed(text)` leaving `✗ <text>`. It draws only where `takesControlCodes`; elsewhere `update` and `stop` do nothing and `done` and `failed` print their plain line. Anything printed meanwhile clears it first, and an interrupt clears it before the process ends.
+- `task(label, run)` from `/progress` runs one step under a spinner, `run` given an `update({ done?, total?, unit? })` for a bar, and ends on `✓ <label> <time>`, or `✗ <label>` and the error thrown again.
+- `@kaynooo/cli-kit/shell` reads shell command lines the way a hook vetting them needs: `splitCommand` cuts one into pieces at the separators outside quotes and heredocs, `parseCommand` names a piece's program past `sudo`/`env` wrappers and assignments, `tokenize`, `words`, `substitutions` and `replacePieces` take it apart and put it back.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@kaynooo/cli-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.7.3",
+  "description": "What every @kaynooo CLI shares: argument parsing with --help, a command dispatcher with typo hints and shell completion, and output formatting.",
+  "author": "Kaynooo <kaynooo@kevyn.fr>",
+  "license": "MIT",
+  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "directory": "packages/kit"
+  },
+  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "keywords": [
+    "args",
+    "bun",
+    "cli",
+    "completion"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./progress": "./src/progress.ts",
+    "./prompt": "./src/prompt.ts",
+    "./shell": "./src/shell.ts",
+    "./test": "./src/test.ts"
+  },
+  "files": ["src"],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+  },
+  "dependencies": {
+    "@kaynooo/utils": "^2.31.0"
+  }
+}

package/src/args.ts

@@ -0,0 +1,189 @@
+import type { ParseArgsOptionDescriptor } from 'node:util'
+import process from 'node:process'
+import { parseArgs } from 'node:util'
+import { upTo } from './format'
+import { paint } from './style'
+
+export type Options = Record<string, ParseArgsOptionDescriptor & { description: string }>
+
+// The `--json` flag every CLI words alike: `print JSON`, then what it holds when given.
+export function jsonOption(holds?: string) {
+  return { type: 'boolean', description: holds === undefined ? 'print JSON' : `print JSON: ${holds}` } as const
+}
+
+// Thrown to end a command with this exit code and message, which runCli prints as `error: <cli> <command>: <message>`, the hint on a line of its own.
+export class Exit extends Error {
+  constructor(message: string, readonly code: number, readonly hint?: string) {
+    super(message)
+  }
+}
+
+export function fail(message: string, code = 2, hint?: string): never {
+  throw new Exit(message, code, hint)
+}
+
+// An Exit for arguments the command cannot take, which runCli points at the command's --help.
+export class UsageError extends Exit {
+  constructor(message: string) {
+    super(message, 2)
+  }
+}
+
+export function badUsage(message: string): never {
+  throw new UsageError(message)
+}
+
+// Thrown by parse once it has printed --help, so the command stops there; runCli and runMain end on it with exit 0, printing nothing more.
+export class HelpShown extends Exit {
+  constructor() {
+    super('help shown', 0)
+  }
+}
+
+// Thrown by parse while a bin answers `__complete`, so the command reached hands over its options before doing anything else.
+export class Completing {
+  constructor(readonly options: Options) {}
+}
+
+export const completion = { active: false }
+
+// Optional parts of a usage line, `[options]` or `[tag]`, dimmed in the help.
+const OPTIONAL = /\[[^\]]+\]/g
+const USAGE_PREFIX = /^usage:\s*/i
+
+// `Usage: <usage>`, the usage given with or without its own `usage:`, optional parts dimmed.
+export function usageLine(usage: string, colors = paint(process.stdout)): string {
+  return `${colors.bold('Usage:')} ${usage.replace(USAGE_PREFIX, '').replaceAll(OPTIONAL, part => colors.dim(part))}`
+}
+
+export function helpText(usage: string, options: Options, colors = paint(process.stdout)): string {
+  return [usageLine(usage, colors), '', colors.bold('Options:'), ...optionRows(options, colors)].join('\n')
+}
+
+// A line per option, `-n, --times <value>  how many`, aligned on the visible text.
+export function optionRows(options: Options, colors = paint(process.stdout)): string[] {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? '    ' : `${colors.cyan(`-${option.short}`)}, `
+    const value = option.type === 'string' ? ` ${colors.dim('<value>')}` : ''
+
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === 'string' ? ' <value>'.length : 0), description: option.description }
+  })
+  const width = Math.max(0, ...rows.map(row => row.width))
+
+  return rows.map(row => `  ${row.flag}${' '.repeat(width - row.width)}  ${colors.dim(row.description)}`)
+}
+
+// The positionals typed by their names: `<key>` or `KEY` a string, `[file]` an optional one, a name ending in `...` the rest.
+type Slots<Names extends readonly string[]> = Names extends readonly [infer First extends string, ...infer Others extends readonly string[]]
+  ? First extends `${string}...` | `${string}...]` ? string[] : First extends `[${string}` ? [string?, ...Slots<Others>] : [string, ...Slots<Others>]
+  : Names extends readonly [] ? [] : string[]
+
+export interface ParseSettings<Names extends readonly string[] = string[]> {
+  // Stops at the first `--` and hands what follows back untouched as `rest`, for a command that runs another (`out -n 200 -- <cmd>`).
+  rest?: boolean
+  // Takes `--no-<flag>` as `false` for a boolean flag, as parseArgs' own `allowNegative` does.
+  allowNegative?: boolean
+  // The positionals the command takes, by name as its usage writes them: `<key>` or `KEY` required, `[file]` optional, a last one ending in `...` taking any more. One missing or one too many is a usage error, and the positionals come back typed by these names.
+  positionals?: Names
+}
+
+// Parses a command's arguments; on --help, prints its help and throws HelpShown, which ends the command with exit 0.
+export function parse<const T extends Options, const Names extends readonly string[] = string[]>(args: string[], usage: string, options: T, settings: ParseSettings<Names> = {}) {
+  const all = { ...options, help: { type: 'boolean', short: 'h', description: 'show this help' } } as const
+
+  if (completion.active)
+    throw new Completing(all)
+
+  const separator = settings.rest === true ? args.indexOf('--') : -1
+  const own = separator === -1 ? args : args.slice(0, separator)
+  const rest = separator === -1 ? undefined : args.slice(separator + 1)
+
+  let parsed
+
+  try {
+    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+  }
+  catch (error) {
+    badUsage(parseError(error))
+  }
+
+  if ((parsed.values as { help?: boolean }).help === true) {
+    console.log(helpText(usage, all))
+
+    throw new HelpShown()
+  }
+
+  if (settings.positionals !== undefined)
+    checkPositionals(parsed.positionals, settings.positionals)
+
+  return { ...parsed, positionals: parsed.positionals as Slots<Names>, rest }
+}
+
+function checkPositionals(given: string[], names: readonly string[]): void {
+  const variadic = names.at(-1)?.replace(']', '').endsWith('...') === true
+  const required = names.filter(name => !name.startsWith('[')).length
+
+  if (given.length < required)
+    badUsage(`missing ${names[given.length]}`)
+
+  if (!variadic && given.length > names.length)
+    badUsage(`unexpected argument ${given[names.length]}`)
+}
+
+// parseArgs' message, its first sentence alone and lowercased as the kit's own: `unknown option '--nope'`.
+function parseError(error: unknown): string {
+  const message = upTo(error instanceof Error ? error.message : String(error), '. ')
+
+  return `${message.charAt(0).toLowerCase()}${message.slice(1)}`
+}
+
+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}`)
+
+  return number
+}
+
+const DURATION = /^(\d+(?:\.\d+)?)(ms|[smh])?$/
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 } as const
+
+// A duration such as `500ms`, `90s`, `5m` or `1h` in milliseconds, a bare number counting in `unit`.
+export function duration(value: string | undefined, name: string, fallback: number, unit: 's' | 'm' = 's'): number {
+  if (value === undefined)
+    return fallback
+
+  const match = DURATION.exec(value.trim())
+  const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[(match[2] ?? unit) as keyof typeof UNIT_MS]
+
+  if (ms < 1)
+    badUsage(`--${name} takes a duration such as 30s, 5m or 1h, not ${value}`)
+
+  return ms
+}
+
+export interface InputSettings {
+  // What to say when stdin is a terminal, as nothing is piped.
+  noStdin?: string
+}
+
+// Text from a file, or from stdin when the path is `-`. A missing file or a stdin left on the terminal ends the command.
+export async function readInput(path: string, { noStdin = 'nothing is piped on stdin' }: InputSettings = {}): Promise<string> {
+  if (path === '-') {
+    if (process.stdin.isTTY)
+      fail(noStdin)
+
+    return Bun.stdin.text()
+  }
+
+  const file = Bun.file(path)
+
+  if (!await file.exists())
+    fail(`no file ${path}`)
+
+  return file.text()
+}

package/src/chart.ts

@@ -0,0 +1,61 @@
+import process from 'node:process'
+import { textWidth } from './format'
+import { paint } from './style'
+
+type Env = Record<string, string | undefined>
+
+const LEVELS = '▁▂▃▄▅▆▇█'
+
+// One block per value, tall in proportion to where it sits between the smallest and the largest; a flat series draws mid-height.
+export function sparkline(values: number[]): string {
+  if (values.length === 0)
+    return ''
+
+  const low = Math.min(...values)
+  const span = Math.max(...values) - low
+
+  return values.map(value => LEVELS[span === 0 ? 3 : Math.round((value - low) / span * (LEVELS.length - 1))]).join('')
+}
+
+export interface BarSettings {
+  width?: number
+  stream?: { isTTY?: boolean }
+  env?: Env
+}
+
+// `████████░░░░░░░░░░░░` for a ratio between 0 and 1, filled in cyan and the rest dim on a terminal.
+export function bar(ratio: number, { width = 20, stream = process.stdout, env = process.env }: BarSettings = {}): string {
+  const colors = paint(stream, env)
+  const filled = Math.round(Math.min(1, Math.max(0, ratio)) * width)
+
+  return `${colors.cyan('█'.repeat(filled))}${colors.dim('░'.repeat(width - filled))}`
+}
+
+export interface KeyValueSettings {
+  stream?: { isTTY?: boolean }
+  env?: Env
+}
+
+// Labels dimmed and padded to the longest, one pair per line: `state   open`.
+export function keyValue(pairs: [label: string, value: string][], { stream = process.stdout, env = process.env }: KeyValueSettings = {}): string {
+  const colors = paint(stream, env)
+  const width = Math.max(0, ...pairs.map(([label]) => textWidth(label)))
+
+  return pairs.map(([label, value]) => `${colors.dim(label)}${' '.repeat(width - textWidth(label))}  ${value}`).join('\n')
+}
+
+export interface BarChartSettings extends KeyValueSettings {
+  // Columns the bars take, 24 by default.
+  width?: number
+  // Formats the number at the end of each row.
+  format?: (value: number) => string
+}
+
+// A bar per labelled value, scaled to the largest: `label  ██████░░░░░░  42`.
+export function barChart(rows: [label: string, value: number][], { width = 24, format = String, stream = process.stdout, env = process.env }: BarChartSettings = {}): string {
+  const largest = Math.max(0, ...rows.map(([, value]) => value))
+  const labels = Math.max(0, ...rows.map(([label]) => textWidth(label)))
+  const values = Math.max(0, ...rows.map(([, value]) => textWidth(format(value))))
+
+  return rows.map(([label, value]) => `${label}${' '.repeat(labels - textWidth(label))}  ${bar(largest === 0 ? 0 : value / largest, { width, stream, env })}  ${' '.repeat(values - textWidth(format(value)))}${format(value)}`).join('\n')
+}

package/src/cli.ts

@@ -0,0 +1,234 @@
+import type { Options } from './args'
+import type { Colors } from './style'
+import process from 'node:process'
+import { Completing, completion, Exit, HelpShown, optionRows, UsageError, usageLine } from './args'
+import { paint, takesControlCodes } from './style'
+import { distance } from './text'
+
+export type Command = { summary: string } & (
+  | { run: (args: string[]) => Promise<number> }
+  // A group of subcommands dispatched the same way, with its own help.
+  | { commands: Record<string, Command>, aliases?: Record<string, string> }
+)
+
+export interface Cli {
+  name: string
+  version: string
+  // One line after `<name> <version>: ` in the help.
+  about: string
+  commands: Record<string, Command>
+  // Names sessions reach for that mean an existing command.
+  aliases?: Record<string, string>
+  // The command that takes the arguments when the first one names no command, so `db "select 1"` runs `db query "select 1"`; `--help` lists its options under the commands.
+  defaultCommand?: string
+  // Rewrites an error's message and cause before they print, for a CLI whose errors may quote what a log must not keep.
+  redact?: (text: string) => string
+}
+
+// A command the name starts, else one within two edits (one for a name under four letters).
+export function closest(name: string, names: string[]): string | undefined {
+  const started = names.find(known => known.startsWith(name))
+
+  if (started !== undefined)
+    return started
+
+  const [best] = names.map(known => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far)
+
+  return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined
+}
+
+interface Level {
+  // The words typed to reach this level, `ft plan`.
+  path: string[]
+  header: (colors: Colors) => string
+  commands: Record<string, Command>
+  aliases: Record<string, string> | undefined
+  defaultCommand: string | undefined
+}
+
+// The level's help; a default command's options follow the commands, as they apply with no command named.
+async function help({ path, header, commands, defaultCommand }: Level, stream: { isTTY?: boolean }): Promise<string> {
+  const colors = paint(stream)
+  const width = Math.max(...Object.keys(commands).map(name => name.length))
+  const prefix = path.join(' ')
+  const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
+  const options = fallback !== undefined && 'run' in fallback ? await optionsOf(fallback.run) : undefined
+
+  return [
+    header(colors),
+    '',
+    usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan('<command>') : `[${colors.cyan('<command>')}]`} [options]`, colors),
+    '',
+    colors.bold('Commands:'),
+    ...Object.entries(commands).map(([name, { summary }]) => `  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`),
+    ...options === undefined || Object.keys(options).length === 0 ? [] : ['', `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim('the command run when none is named')}`, ...optionRows(options, colors)],
+    '',
+    `${colors.dim('Run')} ${prefix} ${colors.cyan('<command>')} --help ${colors.dim('for its options.')}`,
+  ].join('\n')
+}
+
+// `error <prefix>: <message>` on stderr, the cause and the hint each on a line of their own under it; plain words off a terminal.
+export function printError(prefix: string, message: string, hint?: string, cause?: string): void {
+  const colors = paint(process.stderr)
+  const styled = takesControlCodes(process.stderr)
+  const head = styled ? `${colors.red.bold('error')} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`
+  const under = (label: string, text: string | undefined, tint: (text: string) => string) => text === undefined ? '' : `\n  ${styled ? tint(label) : `${label}:`} ${text}`
+
+  console.error(`${head} ${message}${under('cause', cause, colors.dim)}${under('hint', hint, colors.yellow)}`)
+}
+
+// What a thrown error prints as and exits with: an Exit its own code and hint, a UsageError pointed at the help, HelpShown nothing at all and 0, anything else 1.
+// An error other than an Exit is named unless a plain `Error` (`MigrationError: ...`), and its cause's message printed under it, never the cause itself.
+function reportThrown(prefix: string, error: unknown, redact: (text: string) => string = text => text): number {
+  if (error instanceof HelpShown)
+    return 0
+
+  const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined
+  const named = error instanceof Error && !(error instanceof Exit) && error.name !== 'Error' ? `${error.name}: ${error.message}` : undefined
+  const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined
+
+  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause)
+
+  return error instanceof Exit ? error.code : 1
+}
+
+async function dispatch(level: Level, argv: string[], { version, redact }: { version: string, redact: Cli['redact'] | undefined }): Promise<number> {
+  const [name, ...args] = argv
+  const prefix = level.path.join(' ')
+
+  if (name === undefined && level.path.length > 1) {
+    console.error(await help(level, process.stderr))
+
+    return 2
+  }
+
+  if (name === undefined || name === 'help' || name === '--help' || name === '-h') {
+    console.log(await help(level, process.stdout))
+
+    return 0
+  }
+
+  if (level.path.length === 1 && (name === '--version' || name === '-v')) {
+    console.log(version)
+
+    return 0
+  }
+
+  let command = level.commands[level.aliases?.[name] ?? name]
+  let rest = args
+
+  if (command === undefined && level.defaultCommand !== undefined) {
+    command = level.commands[level.defaultCommand]
+    rest = argv
+  }
+
+  if (command === undefined) {
+    const meant = closest(name, Object.keys(level.commands))
+
+    printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`)
+
+    return 2
+  }
+
+  if ('commands' in command) {
+    const { summary } = command
+
+    return dispatch({ path: [...level.path, name], header: colors => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined }, rest, { version, redact })
+  }
+
+  try {
+    return await command.run(rest)
+  }
+  catch (error) {
+    return reportThrown(`${prefix} ${name}`, error, redact)
+  }
+}
+
+// The hidden first argument a shell completion calls a bin with: `<bin> __complete <words typed after it>... <word being typed>`.
+export const COMPLETE = '__complete'
+// Printed instead of candidates where a path fits, for the shell to complete files itself.
+export const FILES = '__files__'
+
+// A command's options, read by running it until its parse call throws them: every command parses its arguments before anything else.
+async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Options> {
+  completion.active = true
+
+  try {
+    await run([])
+  }
+  catch (error) {
+    if (error instanceof Completing)
+      return error.options
+  }
+  finally {
+    completion.active = false
+  }
+
+  return {}
+}
+
+// A leaf command's candidates: its long options for a word starting with a dash, else paths.
+async function leafCandidates(run: (args: string[]) => Promise<number>, words: string[]): Promise<string[]> {
+  if (!(words.at(-1) ?? '').startsWith('-'))
+    return [FILES]
+
+  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}\t${option.description}`)
+}
+
+// The candidates for the last word, `value\tdescription` per line, after walking the subcommands the earlier words name.
+async function candidates(commands: Record<string, Command>, aliases: Record<string, string> | undefined, defaultCommand: string | undefined, words: string[]): Promise<string[]> {
+  const [word = '', ...rest] = words
+  const command = commands[aliases?.[word] ?? word]
+
+  if (rest.length === 0 && !word.startsWith('-'))
+    return Object.entries(commands).map(([name, { summary }]) => `${name}\t${summary}`)
+
+  if (command === undefined) {
+    const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
+
+    return fallback !== undefined && 'run' in fallback ? leafCandidates(fallback.run, words) : []
+  }
+
+  return 'commands' in command ? candidates(command.commands, command.aliases, undefined, rest) : leafCandidates(command.run, rest)
+}
+
+async function printCandidates(found: Promise<string[]>): Promise<number> {
+  for (const line of await found)
+    console.log(line)
+
+  return 0
+}
+
+// Runs the command argv names and returns the exit code: 0 for help and version, 2 for an unknown command.
+export async function runCli(cli: Cli, argv = process.argv.slice(2)): Promise<number> {
+  if (argv[0] === COMPLETE)
+    return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)))
+
+  return dispatch({ path: [cli.name], header: colors => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand }, argv, { version: cli.version, redact: cli.redact })
+}
+
+export interface Main {
+  name: string
+  version: string
+  run: (args: string[]) => Promise<number>
+  redact?: (text: string) => string
+}
+
+// Runs a CLI that is a single command: `--version` or `-v` alone prints the version, an `Exit` or any error prints as `error: <name>: <message>`. Returns the exit code.
+export async function runMain({ name, version, run, redact }: Main, argv = process.argv.slice(2)): Promise<number> {
+  if (argv[0] === COMPLETE)
+    return printCandidates(leafCandidates(run, argv.slice(1)))
+
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
+    console.log(version)
+
+    return 0
+  }
+
+  try {
+    return await run(argv)
+  }
+  catch (error) {
+    return reportThrown(name, error, redact)
+  }
+}