@kaynooo/cli-kit 0.8.1 → 0.10.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kaynooo <kaynooo@kevyn.fr>
+Copyright (c) 2026 Kaynooo <contact@kaynooo.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

package/README.md

@@ -6,7 +6,7 @@ What every @kaynooo CLI shares, so each one parses, helps and fails the same way
 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.
+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 npmjs as a dependency (`bun add --exact @kaynooo/cli-kit`).
 
 ```ts
 import { parse, runCli } from '@kaynooo/cli-kit'
@@ -33,10 +33,11 @@ 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.
-- `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.
+- `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.
@@ -45,7 +46,10 @@ 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.
-- `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.
+- `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 `agent-tools 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>` 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.
+- `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, bare, with no envelope. Under `--json` runMain and runCli print a thrown error as `{"error", "hint"?, "cause"?}` on stderr instead of the `error:` line, its exit code unchanged; `printJsonError(message, hint?, cause?)` prints one for a command reporting a failure itself.
 - `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.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.8.1",
+  "version": "0.10.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 <kaynooo@kevyn.fr>",
+  "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
-  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/kit#readme",
+  "homepage": "https://git.kaynooo.fr/kaynooo/agent-tools/src/branch/main/packages/kit#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "url": "git+https://git.kaynooo.fr/kaynooo/agent-tools.git",
     "directory": "packages/kit"
   },
-  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "bugs": "https://git.kaynooo.fr/kaynooo/agent-tools/issues",
   "keywords": [
     "args",
     "bun",
@@ -30,7 +30,7 @@
     "bun": ">=1.4.3"
   },
   "publishConfig": {
-    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+    "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
   },
   "dependencies": {
     "@kaynooo/utils": "^2.31.0"

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)
   }
 }
 
@@ -50,14 +51,49 @@ 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: Example[] = []): string {
-  return [usageLine(usage, colors), '', colors.bold('Options:'), ...optionRows(options, colors), ...exampleRows(examples, colors)].join('\n')
+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 `agent-tools 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.
@@ -74,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.
@@ -95,10 +131,15 @@ export interface ParseSettings<Names extends readonly string[] = string[]> {
   positionals?: Names
   // Command lines shown under `Examples:` in the help, each with an optional dimmed note: `['ft ci HEAD~1', 'wait for the commit before the last']`.
   examples?: Example[]
+  // What the command is reached for instead of, shown as `Instead of:` in the help and listed by `agent-tools list`: 'sed -n N,Mp, grep -n chains and whole-file reads'.
+  replaces?: string
 }
 
 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 }
+
 // The output flags every command takes, before its own help.
 export const OUTPUT_OPTIONS = {
   color: { type: 'string', description: 'auto (on a terminal alone), always or never' },
@@ -142,10 +183,12 @@ export function parse<const T extends Options, const Names extends readonly stri
   let parsed
 
   try {
-    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+    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 }
@@ -153,7 +196,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(helpText(usage, all, undefined, settings.examples))
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, all, undefined, settings))
 
     throw new HelpShown()
   }
@@ -175,6 +218,33 @@ function checkPositionals(given: string[], names: readonly string[]): void {
     badUsage(`unexpected argument ${given[names.length]}`)
 }
 
+// The arguments with a string option's value joined to it as `--name=value` when that value starts with a dash and names no option, which parseArgs would refuse as ambiguous: `sub --from "- item"`.
+function joinDashValues(args: readonly string[], options: Options): string[] {
+  const longOf = new Map<string, string>(Object.entries(options).flatMap(([name, option]): [string, string][] => option.short === undefined ? [[`--${name}`, name]] : [[`--${name}`, name], [`-${option.short}`, name]]))
+  const isOption = (arg: string) => arg === '--' || longOf.has(arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg)
+  const joined: string[] = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? ''
+
+    if (arg === '--')
+      return [...joined, ...args.slice(i)]
+
+    const name = longOf.get(arg)
+    const next = args[i + 1]
+
+    if (name !== undefined && options[name]?.type === 'string' && next !== undefined && next.startsWith('-') && next !== '-' && !isOption(next)) {
+      joined.push(`--${name}=${next}`)
+      i++
+    }
+    else {
+      joined.push(arg)
+    }
+  }
+
+  return joined
+}
+
 // 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), '. ')
@@ -182,6 +252,30 @@ 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)}?`
+}
+
 export function wholeNumber(value: string | undefined, name: string, fallback: number, min = 1): number {
   if (value === undefined)
     return fallback

package/src/cli.ts

@@ -1,18 +1,26 @@
 import type { Example, Options } from './args'
 import type { Colors } from './style'
 import process from 'node:process'
-import { applyOutput, Completing, completion, exampleRows, Exit, HelpShown, optionRows, OUTPUT_OPTIONS, UsageError, usageLine } from './args'
+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.
@@ -29,6 +40,8 @@ export interface Cli {
   redact?: (text: string) => string
   // 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`.
+  replaces?: string
 }
 
 const LEVEL_OPTIONS = {
@@ -38,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)
   }
 
@@ -73,43 +87,67 @@ 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
-  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, commands, defaultCommand, examples }: 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 }))
+
   const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
   const options = fallback !== undefined && 'run' in fallback ? await optionsOf(fallback.run) : undefined
   // The default command's own run lists the output flags again, so they show once, under the level's.
   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:'),
@@ -130,9 +168,33 @@ export function printError(prefix: string, message: string, hint?: string, cause
   console.error(`${head} ${message}${under('cause', cause, colors.dim)}${under('hint', hint, colors.yellow)}`)
 }
 
+// The hint of a refusal a command resolves with another command, worded alike everywhere: ``run `ft take 12 --take-stale` ``, then what it does when that is not obvious.
+export function runHint(command: string, effect?: string): string {
+  return `run \`${command}\`${effect === undefined ? '' : ` to ${effect}`}`
+}
+
+// A hint under a refusal a command prints itself, laid out as printError lays it.
+export function printHint(hint: string): void {
+  const colors = paint(process.stderr)
+
+  console.error(`  ${takesControlCodes(process.stderr) ? colors.yellow('hint') : 'hint:'} ${hint}`)
+}
+
+// An error as `{"error", "hint"?, "cause"?}` on stderr, for a command run with `--json`, so a caller parses its failures as it parses its output.
+export function printJsonError(message: string, hint?: string, cause?: string): void {
+  console.error(JSON.stringify({ error: message, ...(hint === undefined ? {} : { hint }), ...(cause === undefined ? {} : { cause }) }))
+}
+
+// Whether the arguments ask for JSON, read before parsing so even a parse error prints as JSON.
+function wantsJson(argv: readonly string[]): boolean {
+  const end = argv.indexOf('--')
+
+  return (end === -1 ? argv : argv.slice(0, end)).includes('--json')
+}
+
 // 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 {
+function reportThrown(prefix: string, error: unknown, redact: (text: string) => string = text => text, json = false): number {
   if (error instanceof HelpShown)
     return 0
 
@@ -140,7 +202,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
 
-  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause)
+  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)
 
   return error instanceof Exit ? error.code : 1
 }
@@ -159,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
   }
@@ -179,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
@@ -195,14 +264,14 @@ 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}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined, examples: command.examples }, 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 {
     return await command.run(rest)
   }
   catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact)
+    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest))
   }
 }
 
@@ -234,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]
@@ -251,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> {
@@ -264,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}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand, examples: cli.examples }, 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 {
@@ -291,6 +367,6 @@ export async function runMain({ name, version, run, redact }: Main, argv = proce
     return await run(argv)
   }
   catch (error) {
-    return reportThrown(name, error, redact)
+    return reportThrown(name, error, redact, wantsJson(argv))
   }
 }

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './chart'
 export * from './cli'
 export * from './config'
 export * from './format'
+export * from './limit'
 export * from './process'
 export * from './style'
 export * from './text'

package/src/limit.ts

@@ -0,0 +1,31 @@
+import { badUsage, wholeNumber } from './args'
+
+// The `--limit` and `--full` flags every listing words alike, `fallback` being the rows shown without either.
+export function limitOptions(fallback: number) {
+  return {
+    limit: { type: 'string', description: `show at most this many rows, the rest counted (${fallback})` },
+    full: { type: 'boolean', description: 'show every row' },
+  } as const
+}
+
+// How many rows to print: --limit, the fallback without one, and every row (Infinity) with --full or, when `json` is set, whenever --limit is not given, so JSON is never cut on its own.
+export function limitOf(values: { limit?: string | undefined, full?: boolean | undefined, json?: boolean | undefined }, fallback: number): number {
+  if (values.full === true && values.limit !== undefined)
+    badUsage('--limit and --full exclude each other')
+
+  if (values.full === true || (values.json === true && values.limit === undefined))
+    return Number.POSITIVE_INFINITY
+
+  return wholeNumber(values.limit, 'limit', fallback)
+}
+
+export function moreFooter(more: number): string {
+  return `${more} more, rerun with --full`
+}
+
+// The first `limit` rows and, when some are left out, the footer counting them: `12 more, rerun with --full`.
+export function capped<T>(rows: readonly T[], limit: number): { shown: T[], footer: string | undefined } {
+  const more = rows.length - limit
+
+  return more > 0 ? { shown: rows.slice(0, limit), footer: moreFooter(more) } : { shown: [...rows], footer: undefined }
+}

package/src/text.ts

@@ -19,3 +19,15 @@ export function distance(a: string, b: string): number {
 
   return previous[b.length] ?? 0
 }
+
+// A name the typed one 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
+}