@kaynooo/cli-kit 0.18.0 → 0.20.0

package/README.md

@@ -42,6 +42,7 @@ 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.
 - `<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.
@@ -56,7 +57,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `--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.
 - `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>` 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.
+- `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.
 - `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`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.18.0",
+  "version": "0.20.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

@@ -1,11 +1,12 @@
 import type { ParseArgsOptionDescriptor } from 'node:util'
-import { fstatSync } from 'node:fs'
 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.
@@ -69,77 +70,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>]
@@ -174,7 +104,7 @@ export interface ParseSettings<Names extends readonly string[] = 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 }
+export interface Described { examples?: Example[] | undefined, replaces?: string | undefined }
 
 // The output flags every command takes, before its own help.
 export const OUTPUT_OPTIONS = {
@@ -419,63 +349,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/cli.ts

@@ -4,6 +4,7 @@ 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>)
@@ -42,6 +43,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 +217,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)
@@ -427,7 +433,39 @@ export async function runCli(cli: Cli, argv = process.argv.slice(2)): Promise<nu
   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(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 })
+
+  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 {
@@ -435,6 +473,7 @@ export interface Main {
   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,7 +493,7 @@ 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)))
 
@@ -464,10 +503,17 @@ export async function runMain({ name, version, run, redact }: Main, argv = proce
     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)
+    recordUsage(usageEntry(name, undefined, argv, code))
+
+  return code
 }

package/src/help.ts

@@ -0,0 +1,73 @@
+import type { Described, Example, Options } from './args'
+import process from 'node:process'
+import { paint } from './style'
+
+// 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 = /\.$/
+
+// `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)}`)
+}

package/src/index.ts

@@ -13,3 +13,4 @@ export * from './sessions'
 export * from './style'
 export * from './text'
 export * from './tool'
+export * from './usage'

package/src/input.ts

@@ -0,0 +1,64 @@
+import { fstatSync } from 'node:fs'
+import process from 'node:process'
+import { badUsage, fail } from './args'
+
+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()
+}

package/src/limit.ts

@@ -3,7 +3,7 @@ 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})` },
+    limit: { type: 'string', short: 'n', description: `show at most this many rows, the rest counted (${fallback})` },
     full: { type: 'boolean', description: 'show every row' },
   } as const
 }

package/src/shell.ts

@@ -162,6 +162,13 @@ export function splitCommand(command: string): Piece[] {
       continue
     }
 
+    // A backquoted body is read whole, as its own separators split nothing of the command around it.
+    if (char === '`') {
+      i = closingBackquote(command, i)
+
+      continue
+    }
+
     if (char === '#' && startsComment(command, i)) {
       const newline = command.indexOf('\n', i)
       const end = newline === -1 ? command.length : newline

package/src/usage.ts

@@ -0,0 +1,129 @@
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+import process from 'node:process'
+import { CLI_FOLDER } from './logs'
+
+// One run of a bin: which command it ran, the names of the flags it saw (never a value or an argument), how it exited and, on a usage error, the option it did not know.
+export interface UsageEntry {
+  at: string
+  bin: string
+  command?: string
+  flags: string[]
+  code: number
+  unknown?: string
+}
+
+const UNKNOWN_OPTION = /unknown option '(--[a-z][a-z0-9-]*)[=']/
+// A long name, or a single letter: anything else is an argument that happens to start with a dash, such as `-secret`.
+const FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/
+const LONGEST_NAME = 40
+
+// Set when a run reported a usage error, so the entry of that run can name the option.
+let usageError: string | undefined
+
+export function noteUsageError(message: string): void {
+  usageError = message
+}
+
+// XDG_STATE_HOME when it is an absolute path, else ~/.local/state, as the spec says an empty or relative value is ignored.
+export function stateHome(env: Record<string, string | undefined> = process.env): string {
+  const dir = env.XDG_STATE_HOME
+
+  return dir !== undefined && isAbsolute(dir) ? dir : join(homedir(), '.local', 'state')
+}
+
+export function usagePath(env: Record<string, string | undefined> = process.env): string {
+  return join(stateHome(env), CLI_FOLDER, 'usage.jsonl')
+}
+
+// Whether runs are recorded: never under `bun test`, and not once KAYNOOO_CLI_NO_USAGE is set to anything but 0 or an empty value.
+export function usageRecorded(env: Record<string, string | undefined> = process.env): boolean {
+  const off = env.KAYNOOO_CLI_NO_USAGE
+
+  return env.NODE_ENV !== 'test' && (off === undefined || off === '' || off === '0')
+}
+
+// The flags among the arguments by name, `--limit=5` as `--limit`, stopping at `--`.
+export function flagNames(argv: readonly string[]): string[] {
+  const end = argv.indexOf('--')
+  const names = (end === -1 ? argv : argv.slice(0, end)).filter(word => word.startsWith('-') && word !== '-').map(word => word.includes('=') ? word.slice(0, word.indexOf('=')) : word)
+
+  return [...new Set(names)].filter(name => name.length <= LONGEST_NAME && FLAG_NAME.test(name))
+}
+
+// The entry for a run that exited with `code`, with the unknown option a usage error named.
+export function usageEntry(bin: string, command: string | undefined, argv: readonly string[], code: number, now = new Date()): UsageEntry {
+  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION.exec(usageError)?.[1] : undefined
+
+  usageError = undefined
+
+  return { at: now.toISOString(), bin, ...(command === undefined ? {} : { command }), flags: flagNames(argv), code, ...(unknown === undefined ? {} : { unknown }) }
+}
+
+// Appends the run to the usage log, best effort: a log that cannot be written never changes what a bin prints or exits with.
+export function recordUsage(entry: UsageEntry, env: Record<string, string | undefined> = process.env): void {
+  if (!usageRecorded(env))
+    return
+
+  try {
+    const path = usagePath(env)
+
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 })
+  }
+  catch {}
+}
+
+export async function readUsage(path = usagePath(), since = 0): Promise<UsageEntry[]> {
+  const file = Bun.file(path)
+
+  if (!await file.exists())
+    return []
+
+  return (await file.text()).split('\n').flatMap((line) => {
+    try {
+      const entry = JSON.parse(line) as UsageEntry
+
+      return Date.parse(entry.at) >= since ? [entry] : []
+    }
+    catch {
+      return []
+    }
+  })
+}
+
+export interface UsageSummary {
+  runs: number
+  bins: { bin: string, runs: number, failed: number, usageErrors: number }[]
+  usageErrors: { bin: string, command?: string, unknown: string, count: number }[]
+}
+
+// Runs per bin, and the usage errors by the option that was not known, most common first.
+export function summarizeUsage(entries: readonly UsageEntry[]): UsageSummary {
+  const bins = new Map<string, { runs: number, failed: number, usageErrors: number }>()
+  const errors = new Map<string, { bin: string, command?: string, unknown: string, count: number }>()
+
+  for (const entry of entries) {
+    const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 }
+
+    bin.runs++
+    bin.failed += entry.code === 0 ? 0 : 1
+    bin.usageErrors += entry.code === 2 ? 1 : 0
+    bins.set(entry.bin, bin)
+
+    if (entry.code === 2 && entry.unknown !== undefined) {
+      const key = `${entry.bin} ${entry.command ?? ''} ${entry.unknown}`
+      const error = errors.get(key) ?? { bin: entry.bin, ...(entry.command === undefined ? {} : { command: entry.command }), unknown: entry.unknown, count: 0 }
+
+      error.count++
+      errors.set(key, error)
+    }
+  }
+
+  return {
+    runs: entries.length,
+    bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count),
+  }
+}