@kaynooo/cli-kit 0.19.0 → 0.21.0

package/README.md

@@ -24,7 +24,30 @@ process.exitCode = await runCli({
 
 ## 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).
+Every bin answers by one table, stated in each command's `--help` under `Exits:` (the `exits` setting of `parse`, a list of `[code, meaning]`).
+
+| Code | Meaning |
+| --- | --- |
+| 0 | clean: it did what was asked, found nothing wrong; also `--help` and `--version` |
+| 1 | a finding (`audit`, `doctor`, `guard`), nothing found (`peek`, `hotspots`, `todo-scan`, `ports`, `pick`, `view`), or an operation that ran and failed (Forgejo, GitLab or the database refused, a step failed: `fail(message, 1)` and any other error a command throws) |
+| 2 | a usage error (an unknown command or option, a bad value, a missing argument: what `parse` and `fail` throw by default), or could not check (a timeout, an unreachable registry, no lockfile): never reported as clean |
+
+Exceptions, each stated in the command's own `Exits:`:
+
+- A bin running another command (`base`, `proof`, `out`, `slot`, `dc`, `dx`, `sf`, `gb`, `gc` on a signal) exits with that command's code: 126 when it cannot be run, 127 when it cannot be started, 128 plus the signal when interrupted.
+- `probe` exits 1 when the site could not be reached, that being its finding, and 0 when it answered, whatever it warns about.
+- `guard hook` never exits 2, which would block the tool call it vets.
+- `waitfor` and `ft watch`/`ft ci` exit 2 on a timeout, 1 on the failure they waited for.
+
+`tests/exits.test.ts` holds every bin to this: each command states its codes, only from the table, and answers `--help` with 0 and an unknown option with 2.
+
+## Flags that mean the same everywhere
+
+- `-n` is always a count: `--limit` (rows of a listing, with `--full` for all of them, from `limitOptions`), `--rows` (`db`, once `--limit`), `--lines` (`dlog`, `out` and `waitfor task`: lines of output kept), `--count` (`sub`, `dev uuid`) and `--slots` (`slot`). A listing cuts to its default and says `N more, rerun with --full`; `--json` is never cut on its own, only by an explicit `-n`.
+- `-t`/`--timeout` is how long to wait before giving up, a duration (`30s`, `5m`, `1h`). A bare number counts in the unit the help names: minutes for `ft ci`, `ft watch`, `ft release` and `gl ci`, seconds for `waitfor`, `slot` and `pkg bump`.
+- `-r`/`--repo` is the forge repository (`ft`, `gl`, `changelog`). Bins with no repository keep `-r` for their own noun: `--ref` (`base`, `proof`), `--regex` (`sub`), `--refs` (`peek`).
+- `--dry-run` shows what would change without changing it (`sub`, `ft release`, `pkg bump`, `changelog`; `changelog` keeps `--dry`).
+- A renamed flag keeps its old spelling through `aliases` on the option (`rows` answers `--limit`, `changelog` answers `--gitea` and `--dry`), left out of the help and of `__complete`.
 
 ## Look
 
@@ -32,6 +55,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 
 ## API
 
+- `version` is optional on `runCli`, `runMain` and `mainArgs`: it defaults to `packageVersion()`, the version of the nearest `package.json` above the entry file (links resolved, so `src/cli.ts` and the built `dist/cli.js` both find the package's own), which saves each bin its `import { version } from '../package.json'`.
 - `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`.
@@ -42,6 +66,8 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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"`, and an error there reads `error: db query: ...`), its options listed in `<cli> --help` under the commands, and `runBare: true` to have a bare `<cli>` run it instead of printing the help, and a command may be a group, `{ summary, commands, aliases? }`, dispatched with its own help and typo hints (`ft plan add`). A command taking `hidden: true` runs as usual but is left out of `--help`, `KIT_HELP=json`, `__complete` and the typo hints, for one only a script or a shell binding calls.
 - Commands known only once something is read (a project's config adding some) are lazy: `extraCommands: async (words) => ({ ... })` on the CLI or on a group adds them to its `commands` (which win a shared name), and `commands` itself may be such a function when every command is lazy. The function gets the words typed so far from the CLI's name on (`['team', 'hello', 'b']`) and is called only when the first word names no command the level already has, or for `--help`, `help` and `__complete`, never for a plain run of one it has, so existing `Cli` literals are unchanged. A `summary` may be an async function too, awaited only where a help, the `KIT_HELP=json` description or `__complete` lists it, never for a run. An error the function throws is not caught: handle it inside.
+- `runCli` and `runMain` record each run in `$XDG_STATE_HOME/kaynooo-cli/usage.jsonl` (`~/.local/state/...`, 0600): the bin, its command, the flag names it saw (never a value or an argument), the exit code and the unknown option of a usage error. `KAYNOOO_CLI_NO_USAGE=1` stops it, `NODE_ENV=test` too, and `usage: false` on the `Cli` or `Main` opts a bin out (`guard`, run on every tool call). `readUsage` and `summarizeUsage` read it, `cli stats` shows it.
+- Shell completion: `cli completions fish --install` writes one file per bin, `source <(cli completions bash)` in `~/.bashrc` loads one function for all of them, and zsh reads that same script through `bashcompinit`. Each bin answers `<bin> __complete <words>... <word>`, below.
 - `<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`'s `candidates: { '<project>': async () => ['alpha', ['beta', 'its description']] }` (by the positional's name as `positionals` writes it) gives the values of a positional, and `candidates: () => [...]` on a string option those of its value, besides `choices`; the function runs only while completing, and a command that gives none still answers `__files__`.
 - `parse` options also take `optional: { bare: '1', accepts: /^\d+$/ }` on a string option (`--out [n]`: bare it reads `bare`, a next word is its value unless it starts with a dash or fails `accepts`, and then stays a positional), `conflicts: ['pdf']` (both given is a usage error naming them) and, with `allowNegative`, `negative: 'keep the cached copy'` on a boolean option, which the help and `__complete` then list as `--no-<name>` with that description, the positive flag only when it has a `description` of its own.
 - `parse(args, usage, options, { positionals, trailing: true })` hands everything after the last declared positional back as `rest`, dashes included and without a `--` (`athome compose <project> exec -T php bash`); options typed before it parse as usual.
@@ -54,6 +80,9 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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.
+- `exits: [[0, 'clean'], [1, 'a finding'], [2, 'a usage error']]` in `parse`'s settings prints an `Exits:` block after the options (a code may be a word, `['its own', 'the code of the command']`), and `KIT_HELP=json` carries it as `exits: [{code, meaning}]`.
+- `aliases: ['limit']` on an option keeps an old long name working: it is read as the option, bare or with `=`, up to a `--`, and shown in neither the help nor `__complete`.
+- `compose(args, { flags, cwd, env })` runs `docker compose <flags> <args>` and returns `{ code, stdout, stderr }` whatever the exit code (it throws only when docker cannot start), `captureOutput(argv, { cwd, env })` is the same for any command, `composeError(output)` words a failure as the last line of stderr or `exit <code>`, and `jsonLines<T>(text)` reads `compose ps --format json`, one object per line or the older array.
 - `replaces` on the CLI or in `parse`'s settings (`'sed -n N,Mp, grep -n chains'`) adds an `Instead of:` line under the usage. With `KIT_HELP=json` in the environment, `--help` prints `{synopsis, summary, replaces?, examples}` instead, the usage's first line split at its first `: `, which is how `cli list` reads every bin.
 - `runHint(command, effect?)` words the hint of a refusal that a command resolves, ``run `ft take 12 --take-stale` to take it over``, so every CLI writes it alike: `fail(message, 1, runHint('ft take 12 --take-stale', 'take it over'))`. `printHint(hint)` prints the `hint:` line under a refusal a command prints itself (one issue of several refused).
 - `limitOptions(fallback)` is the `--limit <n>` (`-n`) and `--full` flags of a listing, `limitOf(values, fallback)` the row count they ask for (Infinity with `--full`; with `json: true` in the values, Infinity unless `--limit` is given, so JSON is never cut on its own), and `capped(rows, limit)` the first rows plus the footer `N more, rerun with --full` when some are left out.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.19.0",
+  "version": "0.21.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",
@@ -23,7 +23,8 @@
     "./progress": "./src/progress.ts",
     "./prompt": "./src/prompt.ts",
     "./shell": "./src/shell.ts",
-    "./test": "./src/test.ts"
+    "./test": "./src/test.ts",
+    "./fzf": "./src/fzf.ts"
   },
   "files": ["src"],
   "engines": {

package/src/advisory.ts

@@ -0,0 +1,22 @@
+export const SEVERITIES = ['low', 'moderate', 'high', 'critical'] as const
+
+export type Severity = (typeof SEVERITIES)[number]
+
+/** One advisory as `audit` and `pkg audit` both list it: `ghsa` is read from the url and `fixed` is the version its range ends below, both absent when none applies. */
+export interface AdvisoryRow {
+  id: number
+  ghsa?: string | undefined
+  url: string
+  title: string
+  severity: Severity
+  fixed?: string | undefined
+}
+
+export function severityRank(severity: Severity): number {
+  return SEVERITIES.indexOf(severity)
+}
+
+/** Whether `--ignore` skips an advisory, by its GHSA or numeric id. */
+export function isIgnored(advisory: Pick<AdvisoryRow, 'id' | 'ghsa'>, ignore: readonly string[]): boolean {
+  return ignore.includes(advisory.ghsa ?? '') || ignore.includes(String(advisory.id))
+}

package/src/args.ts

@@ -1,11 +1,13 @@
 import type { ParseArgsOptionDescriptor } from 'node:util'
-import { fstatSync } from 'node:fs'
+import type { ExitRow } from './help'
 import process from 'node:process'
 import { parseArgs } from 'node:util'
 import { upTo } from './format'
-import { paint } from './style'
+import { description, helpText, wantsHelpJson } from './help'
 import { closest } from './text'
 
+const DASHES = /^-+/
+
 interface OptionExtras {
   description?: string
   // A string option taking `choices` accepts only those values: another is a usage error naming them, the help shows them as the value and `__complete` offers them.
@@ -18,6 +20,8 @@ interface OptionExtras {
   conflicts?: readonly string[]
   // With `allowNegative`, a boolean option's `--no-<name>` as the help and `__complete` list it, with this description; the positive flag is then left out of both unless it has a `description` of its own, for a flag that defaults on.
   negative?: string
+  // Other long names the option answers to, kept for the spelling it had before a rename; the help and `__complete` list only its own name.
+  aliases?: readonly string[]
 }
 
 export type Options = Record<string, ParseArgsOptionDescriptor & OptionExtras>
@@ -69,77 +73,6 @@ export type Candidates = () => Candidate[] | Promise<Candidate[]>
 
 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
-const FULL_STOP = /\.$/
-const DASHES = /^-+/
-
-// `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), { examples = [], replaces }: Described = {}): string {
-  return [usageLine(usage, colors), ...replacesRows(replaces, colors), '', colors.bold('Options:'), ...optionRows(options, colors), ...exampleRows(examples, colors)].join('\n')
-}
-
-// An `Instead of:` line, after a blank line; nothing without one.
-export function replacesRows(replaces: string | undefined, colors = paint(process.stdout)): string[] {
-  return replaces === undefined ? [] : ['', `${colors.bold('Instead of:')} ${replaces}`]
-}
-
-// What a bin's --help prints under KIT_HELP=json, for `cli list` to read without parsing the text.
-export interface Description {
-  synopsis: string
-  summary: string
-  replaces?: string
-  examples: { line: string, note?: string }[]
-}
-
-export function wantsHelpJson(env: Record<string, string | undefined> = process.env): boolean {
-  return env.KIT_HELP === 'json'
-}
-
-// The synopsis and the summary a usage's first line splits into at its first `: `, else the first line after the synopses as the summary, with the examples spelled out.
-export function description(usage: string, { examples = [], replaces }: Described = {}): Description {
-  const lines = usage.replace(USAGE_PREFIX, '').split('\n')
-  const first = lines[0]!
-  const colon = first.indexOf(': ')
-  const prose = lines[lines.indexOf('') + 1] ?? ''
-  const fallback = lines.includes('') ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, '') : ''
-
-  return {
-    synopsis: colon === -1 ? first : first.slice(0, colon),
-    summary: colon === -1 ? fallback : first.slice(colon + 2),
-    ...replaces === undefined ? {} : { replaces },
-    examples: examples.map(example => typeof example === 'string' ? { line: example } : { line: example[0], note: example[1] }),
-  }
-}
-
-// An `Examples:` section, after a blank line, with a line per example; nothing without one.
-export function exampleRows(examples: Example[], colors = paint(process.stdout)): string[] {
-  if (examples.length === 0)
-    return []
-
-  return ['', colors.bold('Examples:'), ...examples.map(example => typeof example === 'string' ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)]
-}
-
-// 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 named = option.choices === undefined ? '<value>' : `<${option.choices.join('|')}>`
-    const placeholder = option.optional === undefined ? named : `[${named}]`
-    const value = option.type === 'string' ? ` ${colors.dim(placeholder)}` : ''
-
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === 'string' ? placeholder.length + 1 : 0), description: option.description ?? '' }
-  })
-  const width = Math.max(0, ...rows.map(row => row.width))
-
-  return rows.map(row => row.description === '' ? `  ${row.flag}` : `  ${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>]
@@ -169,12 +102,14 @@ export interface ParseSettings<Names extends readonly string[] = string[]> {
   examples?: Example[]
   // What the command is reached for instead of, shown as `Instead of:` in the help and listed by `cli list`: 'sed -n N,Mp, grep -n chains and whole-file reads'.
   replaces?: string
+  // What each exit code means, shown as an `Exits:` block in the help and listed by `cli list`: `[[0, 'clean'], [1, 'a finding'], [2, 'a usage error']]`.
+  exits?: ExitRow[]
 }
 
 export type Example = string | [line: string, note: string]
 
 // The parts of the settings the help and the description show.
-interface Described { examples?: Example[] | undefined, replaces?: string | undefined }
+export interface Described { examples?: Example[] | undefined, replaces?: string | undefined, exits?: ExitRow[] | undefined }
 
 // The output flags every command takes, before its own help.
 export const OUTPUT_OPTIONS = {
@@ -219,7 +154,7 @@ export function parse<const T extends Options, const Names extends readonly stri
   let parsed
 
   try {
-    parsed = parseArgs({ args: joinDashValues(withBare(own, all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+    parsed = parseArgs({ args: joinDashValues(withBare(withAliases(own, all), all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
   }
   catch (error) {
     const message = parseError(error)
@@ -232,7 +167,7 @@ export function parse<const T extends Options, const Names extends readonly stri
   applyOutput('color' in output ? values.color as string | undefined : undefined, 'plain' in output ? values.plain as boolean | undefined : undefined)
 
   if (values.help === true) {
-    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, listing, undefined, settings))
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings, listing)) : helpText(usage, listing, undefined, settings))
 
     throw new HelpShown()
   }
@@ -296,6 +231,24 @@ function listed(options: Options, allowNegative: boolean): Options {
   }))
 }
 
+// The arguments with an option typed under one of its `aliases` renamed to its own name, up to a `--`: `--limit 5` becomes `--rows 5`.
+function withAliases(args: string[], options: Options): string[] {
+  const named = new Map<string, string>(Object.entries(options).flatMap(([name, { aliases = [] }]) => aliases.map((alias): [string, string] => [`--${alias}`, `--${name}`])))
+
+  if (named.size === 0)
+    return args
+
+  const separator = args.indexOf('--')
+  const own = separator === -1 ? args : args.slice(0, separator)
+
+  return [...own.map((arg) => {
+    const at = arg.indexOf('=')
+    const current = named.get(at === -1 ? arg : arg.slice(0, at))
+
+    return current === undefined ? arg : `${current}${at === -1 ? '' : arg.slice(at)}`
+  }), ...separator === -1 ? [] : args.slice(separator)]
+}
+
 // The arguments with an optional-value option typed bare given its fallback, ahead of the next argument: `--out` becomes `--out 1` unless a value follows it.
 function withBare(args: string[], options: Options): string[] {
   const bare = new Map<string, NonNullable<Options[string]['optional']>>(Object.entries(options).flatMap(([name, { short, optional }]) => optional === undefined ? [] : [[`--${name}`, optional] as const, ...short === undefined ? [] : [[`-${short}`, optional] as const]]))
@@ -419,63 +372,5 @@ 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 (!WHOLE.test(value) || !Number.isSafeInteger(number) || number < min)
-    badUsage(`${name.startsWith('<') ? name : `--${name}`} takes a whole number from ${min}, not ${value}`)
-
-  return number
-}
-
-const DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/
-const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const
-
-// A duration such as `500ms`, `90s`, `5m`, `1h` or `7d` in milliseconds, a bare number counting in `unit`.
-export function duration(value: string | undefined, name: string, fallback: number, unit: 's' | 'm' | 'h' = '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, 1h or 7d, not ${value}`)
-
-  return ms
-}
-
-// Whether stdin is a pipe or a file to read, rather than a terminal or /dev/null that would leave a command waiting or reading nothing.
-export function isStdinPiped(): boolean {
-  const stat = fstatSync(0)
-
-  return stat.isFIFO() || stat.isFile()
-}
-
-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()
-}
+export * from './help'
+export * from './input'

package/src/ci.ts

@@ -21,6 +21,8 @@ export interface CiWait<T> {
   // How long queued work may sit while nothing moves.
   stalledMs: number
   pollMs?: number
+  // Leaves the live region and the retry warnings out, so only what the caller prints around the wait shows.
+  quiet?: boolean
   // 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.
@@ -43,13 +45,17 @@ 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 { tool, short, giveUpMs, noneMs, stalledMs, pollMs = POLL, quiet = false } = 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 region = wait.lines === undefined || quiet ? undefined : liveRegion(spinner => wait.lines?.(spinner, found, started) ?? [])
+  const retrying = (error: unknown) => {
+    if (!quiet)
+      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+  }
   const suffix = () => found === undefined ? '' : `: ${wait.links(found)}`
 
   // A failure to read the stall is retried on the next poll, and leaves the stall unknown.
@@ -61,7 +67,7 @@ export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
       if (error instanceof Exit || isPermanentFailure(error))
         throw error
 
-      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+      retrying(error)
 
       return 'unknown'
     }
@@ -86,7 +92,7 @@ export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
         if (isPermanentFailure(error))
           fail(error instanceof Error ? error.message : String(error))
 
-        console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+        retrying(error)
 
         const latest = found === undefined ? undefined : await wait.settle(found)
 

package/src/cli.ts

@@ -1,9 +1,12 @@
 import type { Candidate, Example, Options } from './args'
 import type { Colors } from './style'
+import { readFileSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
 import { applyOutput, Completing, completion, description, exampleRows, Exit, HelpShown, optionRows, OUTPUT_OPTIONS, replacesRows, UsageError, usageLine, wantsHelpJson } from './args'
 import { paint, takesControlCodes } from './style'
 import { closest } from './text'
+import { noteUsageError, recordUsage, usageEntry } from './usage'
 
 // A command's one-line summary, or a function reading it (a lazily loaded module) that only a listing of the command awaits, never a run.
 export type Summary = string | (() => Promise<string>)
@@ -27,7 +30,8 @@ export type Command = {
 
 export interface Cli {
   name: string
-  version: string
+  // The package's own by default, read from the nearest package.json above the entry file.
+  version?: string
   // One line after `<name> <version>: ` in the help.
   about: string
   // The commands, or a function giving them all lazily.
@@ -42,6 +46,8 @@ export interface Cli {
   runBare?: boolean
   // 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
+  // Set to false for a bin run on every tool call, which would fill the usage log (`guard hook`).
+  usage?: false
   // Command lines shown under `Examples:` in `<cli> --help`; a command's own go to `parse`.
   examples?: Example[]
   // What the CLI is reached for instead of, shown as `Instead of:` in `<cli> --help`.
@@ -214,6 +220,9 @@ function reportThrown(prefix: string, error: unknown, redact: (text: string) =>
   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
 
+  if (error instanceof UsageError)
+    noteUsageError(error.message)
+
   const report = json ? printJsonError : (message: string, hint?: string, causeText?: string) => printError(prefix, message, hint, causeText)
 
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause)
@@ -422,19 +431,71 @@ async function printCandidates(found: Promise<string[]>): Promise<number> {
   return 0
 }
 
+// The version of the nearest package.json above the entry file (symlinks resolved) that holds one, `0.0.0` when none does.
+export function packageVersion(entry = Bun.main): string {
+  for (let dir = dirname(realpathSync(entry)); ; dir = dirname(dir)) {
+    try {
+      const { version } = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: unknown }
+
+      if (typeof version === 'string')
+        return version
+    }
+    catch {}
+
+    if (dirname(dir) === dir)
+      return '0.0.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> {
+  const version = cli.version ?? packageVersion()
+
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)))
 
-  return dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact })
+  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version, redact: cli.redact })
+
+  if (cli.usage !== false) {
+    try {
+      recordUsage(usageEntry(cli.name, commandPath(scopeOf(cli.commands, cli.extraCommands, cli.aliases), argv), argv, code))
+    }
+    catch {}
+  }
+
+  return code
+}
+
+// The command words the arguments start with, a group's subcommand included; lazy commands are not loaded for it.
+function commandPath(scope: Pick<Level, 'commands' | 'aliases'>, argv: readonly string[]): string | undefined {
+  const path: string[] = []
+  let level = scope
+
+  for (const word of argv.filter(each => !each.startsWith('-'))) {
+    const name = level.aliases !== undefined && Object.hasOwn(level.aliases, word) ? (level.aliases[word] ?? word) : word
+    const command: Level['commands'][string] | undefined = Object.hasOwn(level.commands, name) ? level.commands[name] : undefined
+
+    if (command === undefined)
+      break
+
+    path.push(word)
+
+    if (!('commands' in command))
+      break
+
+    level = scopeOf(command.commands, command.extraCommands, command.aliases)
+  }
+
+  return path.length === 0 ? undefined : path.join(' ')
 }
 
 export interface Main {
   name: string
-  version: string
+  // The package's own by default, read from the nearest package.json above the entry file.
+  version?: string
   run: (args: string[]) => Promise<number>
   redact?: (text: string) => string
+  usage?: false
 }
 
 // Parses a module's own arguments through runMain's handling, for a script running at its top level: the parsed values come back, and the process ends itself on --help, --version, `__complete` or an error, with the exit code runMain gives.
@@ -454,20 +515,31 @@ export async function mainArgs<T>(main: Omit<Main, 'run'>, parseArgv: (args: str
 }
 
 // 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> {
+export async function runMain({ name, version, run, redact, usage }: 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)
+    console.log(version ?? packageVersion())
 
     return 0
   }
 
+  let code: number
+
   try {
-    return await run(argv)
+    code = await run(argv)
   }
   catch (error) {
-    return reportThrown(name, error, redact, wantsJson(argv))
+    code = reportThrown(name, error, redact, wantsJson(argv))
+  }
+
+  if (usage !== false) {
+    try {
+      recordUsage(usageEntry(name, undefined, argv, code))
+    }
+    catch {}
   }
+
+  return code
 }

package/src/compose.ts

@@ -0,0 +1,43 @@
+export interface ComposeOptions {
+  // Compose's own options, given before the subcommand: `['-f', 'compose.yaml']`, `['-p', project]`, `['--project-directory', dir]`.
+  flags?: string[]
+  cwd?: string
+  // Variables set over the process's environment for compose.
+  env?: Record<string, string | undefined>
+}
+
+export interface CommandOutput {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+// Runs a command to its end with no stdin and returns both streams apart, whatever its exit code; it throws when the command cannot start.
+export async function captureOutput(argv: string[], { cwd, env }: Pick<ComposeOptions, 'cwd' | 'env'> = {}): Promise<CommandOutput> {
+  const run = Bun.spawn(argv, { ...cwd === undefined ? {} : { cwd }, env: { ...process.env, ...env }, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+  const [stdout, stderr, code] = await Promise.all([run.stdout.text(), run.stderr.text(), run.exited])
+
+  return { code, stdout, stderr }
+}
+
+// Runs `docker compose <flags> <args>` to its end: `captureOutput` with compose in front.
+export async function compose(args: string[], { flags = [], ...options }: ComposeOptions = {}): Promise<CommandOutput> {
+  return captureOutput(['docker', 'compose', ...flags, ...args], options)
+}
+
+// Why a command failed, in its own words: the last line it wrote to stderr, else `exit <code>`.
+export function composeError({ code, stderr }: CommandOutput): string {
+  const last = stderr.trim().split('\n').at(-1) ?? ''
+
+  return last === '' ? `exit ${code}` : last
+}
+
+// The objects of `docker compose ps --format json`, which prints one per line since Compose 2.21 and an array before.
+export function jsonLines<T>(text: string): T[] {
+  const trimmed = text.trim()
+
+  if (trimmed === '')
+    return []
+
+  return trimmed.startsWith('[') ? JSON.parse(trimmed) as T[] : trimmed.split('\n').map(line => JSON.parse(line) as T)
+}