@kaynooo/cli-kit 0.8.1 → 0.9.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,7 +33,7 @@ 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`).
@@ -45,7 +45,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.9.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

@@ -50,14 +50,48 @@ 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 = /\.$/
 
 // `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.
@@ -95,10 +129,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,7 +181,7 @@ 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))
@@ -153,7 +192,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 +214,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), '. ')

package/src/cli.ts

@@ -1,7 +1,7 @@
 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'
 
@@ -29,6 +29,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 = {
@@ -89,16 +91,22 @@ interface Level {
   // 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
   defaultCommand: string | undefined
   examples: Example[] | undefined
+  replaces: string | undefined
 }
 
 // The level's help; a default command's options follow the commands, as they apply with no command named.
-async function help({ path, header, commands, defaultCommand, examples }: Level, stream: { isTTY?: boolean }): Promise<string> {
+async function help({ path, header, summary, commands, defaultCommand, examples, replaces }: Level, stream: { isTTY?: boolean }): Promise<string> {
   const colors = paint(stream)
   const prefix = path.join(' ')
+
+  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.
@@ -108,6 +116,7 @@ async function help({ path, header, commands, defaultCommand, examples }: Level,
     header(colors),
     '',
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan('<command>') : `[${colors.cyan('<command>')}]`} [options]`, colors),
+    ...replacesRows(replaces, colors),
     '',
     ...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)],
@@ -130,9 +139,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 +173,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
 }
@@ -195,14 +230,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 => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, summary, commands: command.commands, aliases: 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))
   }
 }
 
@@ -266,7 +301,7 @@ export async function runCli(cli: Cli, argv = process.argv.slice(2)): Promise<nu
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)))
 
-  return dispatch({ path: [cli.name], header: colors => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand, examples: cli.examples }, argv, { version: cli.version, redact: cli.redact })
+  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 })
 }
 
 export interface Main {
@@ -291,6 +326,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 }
+}