@kaynooo/cli-kit 0.9.0 → 0.11.0

package/README.md

@@ -33,15 +33,20 @@ 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`.
 - `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`).
+- 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.
 - `<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.
@@ -52,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.9.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

@@ -3,8 +3,9 @@ import process from 'node:process'
 import { parseArgs } from 'node:util'
 import { upTo } from './format'
 import { paint } from './style'
+import { closest } from './text'
 
-export type Options = Record<string, ParseArgsOptionDescriptor & { description: string }>
+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) {
@@ -24,8 +25,8 @@ export function fail(message: string, code = 2, hint?: string): never {
 
 // 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)
+  constructor(message: string, hint?: string) {
+    super(message, 2, hint)
   }
 }
 
@@ -51,6 +52,7 @@ export const completion = { active: false }
 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 {
@@ -108,11 +110,11 @@ export function optionRows(options: Options, colors = paint(process.stdout)): st
     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 }
+    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)}`)
+  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.
@@ -184,7 +186,9 @@ export function parse<const T extends Options, const Names extends readonly stri
     parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
   }
   catch (error) {
-    badUsage(parseError(error))
+    const message = parseError(error)
+
+    throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true))
   }
 
   const values = parsed.values as { help?: boolean, color?: unknown, plain?: unknown }
@@ -248,14 +252,41 @@ function parseError(error: unknown): string {
   return `${message.charAt(0).toLowerCase()}${message.slice(1)}`
 }
 
+const UNKNOWN_OPTION = /^unknown option '(-[^']+)'/
+
+// `did you mean --no-check?` for an unknown option within reach of a known one (shorts and `--no-<flag>` included), nothing when none is, so runCli keeps its `--help` hint.
+function nearestOption(message: string, options: Options, allowNegative: boolean): string | undefined {
+  const typed = UNKNOWN_OPTION.exec(message)?.[1]
+
+  if (typed === undefined)
+    return undefined
+
+  const word = typed.replace(DASHES, '')
+
+  if (word.length < 2 && !typed.startsWith('--'))
+    return undefined
+
+  const known = Object.entries(options).flatMap(([name, option]) => [
+    ...option.short === undefined ? [] : [`-${option.short}`],
+    `--${name}`,
+    ...allowNegative && option.type === 'boolean' ? [`--no-${name}`] : [],
+  ])
+  const meant = closest(word, known.map(flag => flag.replace(DASHES, '')))
+
+  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/cli.ts

@@ -3,16 +3,24 @@ import type { Colors } from './style'
 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 { distance } from './text'
+import { closest } from './text'
+
+// 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>)
+
+export type Commands = Record<string, Command>
+
+// Commands known only once something is read, called with the words typed so far from the CLI's name on, and only when a word is not a command the level already has, or for a help or `__complete`.
+export type LazyCommands = (words: string[]) => Promise<Commands>
 
 export type Command = {
-  summary: string
+  summary: Summary
   // The heading the command is listed under in the help, after those with none.
   group?: 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>, examples?: Example[] }
+  // A group of subcommands dispatched the same way, with its own help; `commands` may be a function for a group made of lazy commands alone.
+  | { commands: Commands | LazyCommands, extraCommands?: LazyCommands, aliases?: Record<string, string>, examples?: Example[] }
 )
 
 export interface Cli {
@@ -20,7 +28,10 @@ export interface Cli {
   version: string
   // One line after `<name> <version>: ` in the help.
   about: string
-  commands: Record<string, Command>
+  // The commands, or a function giving them all lazily.
+  commands: Commands | LazyCommands
+  // Lazy commands added to `commands`, which win a name they share.
+  extraCommands?: LazyCommands
   // 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.
@@ -40,15 +51,16 @@ const LEVEL_OPTIONS = {
 const TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: 'boolean', short: 'v', description: 'print the version' } } as const satisfies Options
 
 // The rows under `Commands:`, then a heading per group in the order first met, names aligned across them all.
-function commandRows(commands: Record<string, Command>, colors: Colors): string[] {
+async function commandRows(commands: Commands, colors: Colors): Promise<string[]> {
   const width = Math.max(...Object.keys(commands).map(name => name.length))
   const groups = new Map<string, string[]>([['Commands:', []]])
+  const summaries = await Promise.all(Object.values(commands).map(async ({ summary }) => resolveSummary(summary)))
 
-  for (const [name, { summary, group }] of Object.entries(commands)) {
+  for (const [index, [name, { group }]] of Object.entries(commands).entries()) {
     const heading = group === undefined ? 'Commands:' : `${group}:`
     const rows = groups.get(heading) ?? []
 
-    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`)
+    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summaries[index]!)}`)
     groups.set(heading, rows)
   }
 
@@ -75,34 +87,51 @@ function takeOutputFlags(argv: string[]): string[] {
   return argv.slice(index)
 }
 
-// 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
+// What a level lists and dispatches: the commands it has, and the functions giving more once called.
+interface Scope {
+  commands: Commands
+  lazy: LazyCommands[]
+  aliases: Record<string, string> | undefined
 }
 
-interface Level {
+interface Level extends Scope {
   // The words typed to reach this level, `ft plan`.
   path: string[]
-  header: (colors: Colors) => string
-  summary: string
-  commands: Record<string, Command>
-  aliases: Record<string, string> | undefined
+  header: (colors: Colors, summary: string) => string
+  summary: Summary
   defaultCommand: string | undefined
   examples: Example[] | undefined
   replaces: string | undefined
 }
 
+async function resolveSummary(summary: Summary): Promise<string> {
+  return typeof summary === 'string' ? summary : summary()
+}
+
+function scopeOf(commands: Commands | LazyCommands, extra: LazyCommands | undefined, aliases: Record<string, string> | undefined): Scope {
+  return { commands: typeof commands === 'function' ? {} : commands, lazy: [...typeof commands === 'function' ? [commands] : [], ...extra === undefined ? [] : [extra]], aliases }
+}
+
+// The scope with its lazy commands called with the words typed so far and merged in, the ones it already has winning a shared name.
+async function expand<T extends Scope>(scope: T, words: string[]): Promise<T> {
+  if (scope.lazy.length === 0)
+    return scope
+
+  const commands = { ...scope.commands }
+
+  for (const added of await Promise.all(scope.lazy.map(async lazy => lazy(words)))) {
+    for (const [name, command] of Object.entries(added))
+      commands[name] ??= command
+  }
+
+  return { ...scope, commands, lazy: [] }
+}
+
 // The level's help; a default command's options follow the commands, as they apply with no command named.
-async function help({ path, header, summary, commands, defaultCommand, examples, replaces }: Level, stream: { isTTY?: boolean }): Promise<string> {
+async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }: Level, stream: { isTTY?: boolean }): Promise<string> {
   const colors = paint(stream)
   const prefix = path.join(' ')
+  const summary = await resolveSummary(lazySummary)
 
   if (wantsHelpJson())
     return JSON.stringify(description(`${prefix} <command> [options]: ${summary}`, { examples, replaces }))
@@ -113,12 +142,12 @@ async function help({ path, header, summary, commands, defaultCommand, examples,
   const own = Object.entries(options ?? {}).filter(([name]) => !(name in TOP_OPTIONS))
 
   return [
-    header(colors),
+    header(colors, summary),
     '',
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan('<command>') : `[${colors.cyan('<command>')}]`} [options]`, colors),
     ...replacesRows(replaces, colors),
     '',
-    ...commandRows(commands, colors),
+    ...await commandRows(commands, colors),
     ...own.length === 0 ? [] : ['', `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim('the command run when none is named')}`, ...optionRows(Object.fromEntries(own), colors)],
     '',
     colors.bold('Options:'),
@@ -194,13 +223,13 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   const [name, ...args] = argv
 
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(level, process.stderr))
+    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process.stderr))
 
     return 2
   }
 
   if (name === undefined || name === 'help' || name === '--help' || name === '-h') {
-    console.log(await help(level, process.stdout))
+    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process.stdout))
 
     return 0
   }
@@ -214,6 +243,11 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   let command = level.commands[level.aliases?.[name] ?? name]
   let rest = args
 
+  if (command === undefined && level.lazy.length > 0) {
+    level = await expand(level, [...level.path.slice(1), ...argv])
+    command = level.commands[level.aliases?.[name] ?? name]
+  }
+
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand]
     rest = argv
@@ -230,7 +264,7 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   if ('commands' in command) {
     const { summary } = command
 
-    return dispatch({ path: [...level.path, name], header: colors => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, summary, commands: command.commands, aliases: command.aliases, defaultCommand: undefined, examples: command.examples, replaces: undefined }, rest, { version, redact })
+    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, examples: command.examples, replaces: undefined }, rest, { version, redact })
   }
 
   try {
@@ -269,16 +303,23 @@ async function leafCandidates(run: (args: string[]) => Promise<number>, words: s
   if (!(words.at(-1) ?? '').startsWith('-'))
     return [FILES]
 
-  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}\t${option.description}`)
+  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${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[]> {
+async function candidates(scope: Scope, defaultCommand: string | undefined, words: string[], before: string[] = []): Promise<string[]> {
   const [word = '', ...rest] = words
-  const command = commands[aliases?.[word] ?? word]
+  const listing = rest.length === 0 && !word.startsWith('-')
+  let { commands, aliases } = scope
+  let command = commands[aliases?.[word] ?? word]
+
+  if (listing || command === undefined) {
+    ({ commands, aliases } = await expand(scope, [...before, ...words]))
+    command = commands[aliases?.[word] ?? word]
+  }
 
-  if (rest.length === 0 && !word.startsWith('-'))
-    return Object.entries(commands).map(([name, { summary }]) => `${name}\t${summary}`)
+  if (listing)
+    return Promise.all(Object.entries(commands).map(async ([name, { summary }]) => `${name}\t${await resolveSummary(summary)}`))
 
   if (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
@@ -286,7 +327,7 @@ async function candidates(commands: Record<string, Command>, aliases: Record<str
     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)
+  return 'commands' in command ? candidates(scopeOf(command.commands, command.extraCommands, command.aliases), undefined, rest, [...before, word]) : leafCandidates(command.run, rest)
 }
 
 async function printCandidates(found: Promise<string[]>): Promise<number> {
@@ -299,9 +340,9 @@ async function printCandidates(found: Promise<string[]>): Promise<number> {
 // 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 printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)))
 
-  return dispatch({ path: [cli.name], header: colors => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, summary: cli.about, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact })
+  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, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact })
 }
 
 export interface Main {

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'