@kaynooo/cli-kit 0.9.0 → 0.10.0

package/README.md

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.9.0",
+  "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 <contact@kaynooo.fr>",
   "license": "MIT",

package/src/args.ts

@@ -3,8 +3,9 @@ import process from 'node:process'
 import { parseArgs } from 'node:util'
 import { upTo } from './format'
 import { paint } from './style'
+import { closest } from './text'
 
-export type Options = Record<string, ParseArgsOptionDescriptor & { description: string }>
+export type Options = Record<string, ParseArgsOptionDescriptor & { description?: string }>
 
 // The `--json` flag every CLI words alike: `print JSON`, then what it holds when given.
 export function jsonOption(holds?: string) {
@@ -24,8 +25,8 @@ export function fail(message: string, code = 2, hint?: string): never {
 
 // An Exit for arguments the command cannot take, which runCli points at the command's --help.
 export class UsageError extends Exit {
-  constructor(message: string) {
-    super(message, 2)
+  constructor(message: string, hint?: string) {
+    super(message, 2, hint)
   }
 }
 
@@ -51,6 +52,7 @@ export const completion = { active: false }
 const OPTIONAL = /\[[^\]]+\]/g
 const USAGE_PREFIX = /^usage:\s*/i
 const FULL_STOP = /\.$/
+const DASHES = /^-+/
 
 // `Usage: <usage>`, the usage given with or without its own `usage:`, optional parts dimmed.
 export function usageLine(usage: string, colors = paint(process.stdout)): string {
@@ -108,11 +110,11 @@ export function optionRows(options: Options, colors = paint(process.stdout)): st
     const short = option.short === undefined ? '    ' : `${colors.cyan(`-${option.short}`)}, `
     const value = option.type === 'string' ? ` ${colors.dim('<value>')}` : ''
 
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === 'string' ? ' <value>'.length : 0), description: option.description }
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === 'string' ? ' <value>'.length : 0), description: option.description ?? '' }
   })
   const width = Math.max(0, ...rows.map(row => row.width))
 
-  return rows.map(row => `  ${row.flag}${' '.repeat(width - row.width)}  ${colors.dim(row.description)}`)
+  return rows.map(row => row.description === '' ? `  ${row.flag}` : `  ${row.flag}${' '.repeat(width - row.width)}  ${colors.dim(row.description)}`)
 }
 
 // The positionals typed by their names: `<key>` or `KEY` a string, `[file]` an optional one, a name ending in `...` the rest.
@@ -184,7 +186,9 @@ export function parse<const T extends Options, const Names extends readonly stri
     parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
   }
   catch (error) {
-    badUsage(parseError(error))
+    const message = parseError(error)
+
+    throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true))
   }
 
   const values = parsed.values as { help?: boolean, color?: unknown, plain?: unknown }
@@ -248,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

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

package/src/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
+}