@kaynooo/cli-kit 0.15.2 → 0.17.0

package/README.md

@@ -36,12 +36,15 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `runTool(label, argv, { timeoutMs, cwd, onStart })` runs a command through `runCommand` with the current environment and returns `{ code, stdout, stderr }`; it throws, naming `label`, when the command cannot start (noting a removed working directory) or outlives `timeoutMs`. `isPermanentFailure(error)` is true for what a retry cannot mend: a missing binary, or an answer of 401, 403 or 404. `cwdGone()` tells that the working directory was deleted.
 - `git(args, timeoutMs?)`, `gitOk`, `resolveCommit`, `fetchBranch`, `defaultBranch` and `leaveWorktree` are the git helpers the forge CLIs share, over `runTool`.
 - `waitForCi({ tool, short, giveUpMs, noneMs, stalledMs, covering, finished, key, announce, links, settle, stall, lines })` is the wait loop of `ft ci` and `gl ci`: it polls `covering` until what it returns is `finished`, retries a poll that failed for a network reason, fails at once on a refusal (`Exit`) or a permanent failure, and gives up on a timeout, on nothing covering the commit for `noneMs`, or on a `stall` that is certain or lasts `stalledMs`.
-- `parse(args, usage, options)` wraps `node:util` `parseArgs` with a generated `--help` (`usage` given with or without its `usage:`), which prints the help and ends the command with exit 0 (it throws `HelpShown`, which `runCli` and `runMain` take), so the command needs no check after it. A string option takes a next argument starting with a dash as its value (`--from "- item"`, `-n -3`) unless that argument names one of the command's options, which parseArgs alone refuses as ambiguous. `{ positionals: ['<key>', '[file]'] }` names the positionals the command takes: `<key>` or `KEY` required, `[file]` optional, a last one ending in `...` taking any more; one missing (`missing <key>`) or one too many (`unexpected argument x`) is a usage error, and `positionals` comes back typed as `[string, string?]`. `fail(message, code = 2, hint?)` ends a command, the hint printed under the error; `badUsage(message)` ends it with a `UsageError`, which `parse`, `wholeNumber` and `duration` throw too and which gets the hint `run <cli> <command> --help for its options`; `wholeNumber` reads a numeric option.
+- `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. A string option may take `choices: ['patch', 'minor', 'major']`: a value outside them is a usage error naming the allowed ones, `--help` shows them as the option's value (`--bump <patch|minor|major>`) and `__complete` offers them after the flag; `oneOf(value, '<bump>', choices)` checks a positional against a set the same way and returns it typed as their union, as `parse` types the option's value (`'patch' | 'minor' | 'major' | undefined`, an array of them with `multiple`).
 - `table`, `truncate`, `formatSeconds`, `formatAge` and `upTo` format output.
+- `mainArgs({ name, version }, argv => parse(argv, USAGE, OPTIONS))` is `runMain` for a module running at its top level: the parsed values come back, and the process ends itself on `--help`, `--version`, `__complete` or a usage error with the exit code `runMain` gives.
 - `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`).
+- `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.
-- `<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.
+- `<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.
 - `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.
 - `isStdinPiped()` is true when stdin is a pipe or a file, false on a terminal or `/dev/null`, so a command can read what is piped in without waiting on a terminal.
@@ -62,9 +65,10 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `capture(fn)` from `@kaynooo/cli-kit/test` runs a command in-process and returns `{ result, out, err }`, what it printed through `console` and `process.stdout`/`stderr`, so a test needs no spy. `tempDirs()`, called at the top of a test file, answers a `temp(prefix?)` making fresh folders under the system temp folder, all removed once the file's tests are done.
 - `findUp(names, from?)` is the nearest of `names` in the current folder (or `from`) or one above it; `loadConfig(names, { from?, path? })` imports the nearest config (`.ts`, `.js` or `.json`), or the file `path` names, and returns `{ path, dir, config }` with its default export for the caller to check, `undefined` when there is none. A named file missing, one failing to import or one without a default export ends the command with exit 1.
 - `@kaynooo/cli-kit/prompt` asks on the terminal, on stderr:
-  - `select(question, choices, { initial })` picks one `{ value, label, hint }`: typing filters the choices (every word typed in the label or hint, case ignored, Backspace editing), the arrows move and Enter picks.
-  - `checklist(question, choices, { initial, toggle })` checks several the same way, Space toggling the choice under the cursor; `toggle(checked, value)` returns what is checked after it, for choices that pull others along, and flips the one choice by default.
+  - `select(question, choices, { initial, default })` picks one `{ value, label, hint }`, the cursor starting on the index `initial` or on the choice holding the value `default`: typing filters the choices (every word typed in the label or hint, case ignored, Backspace editing), the arrows move and Enter picks.
+  - `checklist(question, choices, { initial, min, toggle })` checks several the same way (Enter on fewer than `min` shows `pick at least N` under the list instead of answering), Space toggling the choice under the cursor; `toggle(checked, value)` returns what is checked after it, for choices that pull others along, and flips the one choice by default.
   - `confirm(question, { default })` answers y or n, Enter taking the default; `input(question, { default, mask, validate })` takes a line, `mask` drawing it as `*`, `validate(value)` returning a message shown under it until the answer passes.
+  - `editor(question, { default, extension })` hands a temp file to `VISUAL` or `EDITOR` (`vi` without either), run through the shell so `code --wait` works, and answers the text it was left with; an editor exiting nonzero (`:cq`) cancels.
   - Each answers `undefined` once Escape or Ctrl+C cancels and leaves `✓ <question> <answer>` or `✗ <question> cancelled`; a list longer than the terminal (10 rows at most) scrolls with the cursor, a dimmed `… n more` above and below.
   - Off a terminal, a prompt fails at once with exit 2, `cannot ask "<question>" off a terminal`, with `hint` under it when given (`{ hint: 'pass --yes' }`); none reads a piped line. Each takes a `terminal: { stdin, stderr }`, the process's by default, for a test to drive.
 - `@kaynooo/cli-kit/progress` draws `progressLine(stream?, env?)` on stderr, one line redrawn in place while a task runs (`⠹ prerendering ████████░░░░░░░░░░░░ 8/20 routes 4.2s`, the bar cyan on a dimmed track), fed `update({ step, done?, total?, unit? })` and ended with `stop()`, `done(text)` leaving `✓ <text> <time>` or `failed(text)` leaving `✗ <text>`. It draws only where `takesControlCodes`; elsewhere `update` and `stop` do nothing and `done` and `failed` print their plain line. Anything printed meanwhile clears it first, and an interrupt clears it before the process ends.

package/package.json

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

@@ -6,7 +6,21 @@ import { upTo } from './format'
 import { paint } from './style'
 import { closest } from './text'
 
-export type Options = Record<string, ParseArgsOptionDescriptor & { description?: string }>
+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.
+  choices?: readonly string[]
+  // The values a string option can take, from a function, offered by `__complete` when `choices` does not give them.
+  candidates?: Candidates
+  // A string option whose value may be left out (`--out [n]`): bare, it reads `bare`. A next word is its value unless it starts with a dash or, given `accepts`, does not match it, and then stays a positional.
+  optional?: { bare: string, accepts?: RegExp }
+  // Options it cannot be given with, a usage error naming both when they are.
+  conflicts?: readonly string[]
+  // With `allowNegative`, a boolean option's `--no-<name>` as the help and `__complete` list it, with this description; the positive flag is then left out of both unless it has a `description` of its own, for a flag that defaults on.
+  negative?: string
+}
+
+export type Options = Record<string, ParseArgsOptionDescriptor & OptionExtras>
 
 // The `--json` flag every CLI words alike: `print JSON`, then what it holds when given.
 export function jsonOption(holds?: string) {
@@ -44,9 +58,15 @@ export class HelpShown extends Exit {
 
 // Thrown by parse while a bin answers `__complete`, so the command reached hands over its options before doing anything else.
 export class Completing {
-  constructor(readonly options: Options) {}
+  constructor(readonly options: Options, readonly positionals: readonly string[] = [], readonly candidates: Record<string, Candidates | undefined> = {}) {}
 }
 
+// A value `__complete` offers, with an optional description shown beside it.
+export type Candidate = string | [value: string, description: string]
+
+// The values a positional or an option can take, read only while a shell completes it.
+export type Candidates = () => Candidate[] | Promise<Candidate[]>
+
 export const completion = { active: false }
 
 // Optional parts of a usage line, `[options]` or `[tag]`, dimmed in the help.
@@ -109,9 +129,11 @@ export function exampleRows(examples: Example[], colors = paint(process.stdout))
 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 value = option.type === 'string' ? ` ${colors.dim('<value>')}` : ''
+    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' ? ' <value>'.length : 0), description: option.description ?? '' }
+    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))
 
@@ -123,13 +145,26 @@ type Slots<Names extends readonly string[]> = Names extends readonly [infer Firs
   ? First extends `${string}...` | `${string}...]` ? string[] : First extends `[${string}` ? [string?, ...Slots<Others>] : [string, ...Slots<Others>]
   : Names extends readonly [] ? [] : string[]
 
+// The parsed values with an option that has `choices` typed as their union, `undefined` kept when the option may be absent.
+type Chosen<T extends Options, Values> = {
+  [Name in keyof Values]: Name extends keyof T
+    ? T[Name] extends { choices: infer Choices extends readonly string[] }
+      ? Extract<Values[Name], undefined> | (NonNullable<Values[Name]> extends unknown[] ? Choices[number][] : Choices[number])
+      : Values[Name]
+    : Values[Name]
+}
+
 export interface ParseSettings<Names extends readonly string[] = string[]> {
   // Stops at the first `--` and hands what follows back untouched as `rest`, for a command that runs another (`out -n 200 -- <cmd>`).
   rest?: boolean
+  // With `positionals`, passes everything after the last declared one back untouched as `rest`, dashes included and without a `--`: `athome compose <project> exec -T php bash`. Options typed before it parse as usual, and it replaces `rest`.
+  trailing?: boolean
   // Takes `--no-<flag>` as `false` for a boolean flag, as parseArgs' own `allowNegative` does.
   allowNegative?: boolean
   // The positionals the command takes, by name as its usage writes them: `<key>` or `KEY` required, `[file]` optional, a last one ending in `...` taking any more. One missing or one too many is a usage error, and the positionals come back typed by these names.
   positionals?: Names
+  // The values `__complete` offers for a positional, by its name as `positionals` writes it: `{ '<project>': async () => names }`. A positional without one completes as a path.
+  candidates?: Partial<Record<Names[number], Candidates>>
   // 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 `cli list`: 'sed -n N,Mp, grep -n chains and whole-file reads'.
@@ -174,17 +209,17 @@ export function parse<const T extends Options, const Names extends readonly stri
   const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options))) as Omit<typeof OUTPUT_OPTIONS, keyof T>
   const all = { ...options, ...output, help: { type: 'boolean', short: 'h', description: 'show this help' } } as const
 
+  const listing = listed(all, settings.allowNegative === true)
+
   if (completion.active)
-    throw new Completing(all)
+    throw new Completing(listing, settings.positionals, settings.candidates)
 
-  const separator = settings.rest === true ? args.indexOf('--') : -1
-  const own = separator === -1 ? args : args.slice(0, separator)
-  const rest = separator === -1 ? undefined : args.slice(separator + 1)
+  const { own, rest } = settings.trailing === true ? splitTrailing(args, all, settings.positionals?.length ?? 0) : splitRest(args, settings.rest === true)
 
   let parsed
 
   try {
-    parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+    parsed = parseArgs({ args: joinDashValues(withBare(own, all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
   }
   catch (error) {
     const message = parseError(error)
@@ -197,15 +232,122 @@ 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(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, all, undefined, settings))
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, listing, undefined, settings))
 
     throw new HelpShown()
   }
 
+  checkChoices(parsed.values, all)
+  checkConflicts(parsed.values, all)
+
   if (settings.positionals !== undefined)
     checkPositionals(parsed.positionals, settings.positionals)
 
-  return { ...parsed, positionals: parsed.positionals as Slots<Names>, rest }
+  return { ...parsed, values: parsed.values as Chosen<T, typeof parsed.values>, positionals: parsed.positionals as Slots<Names>, rest }
+}
+
+// The arguments before a `--` and what follows it, when the command passes that through.
+function splitRest(args: string[], passes: boolean): { own: string[], rest: string[] | undefined } {
+  const separator = passes ? args.indexOf('--') : -1
+
+  return { own: separator === -1 ? args : args.slice(0, separator), rest: separator === -1 ? undefined : args.slice(separator + 1) }
+}
+
+// The arguments up to the last of `count` positionals, options and their values apart, and everything after it.
+function splitTrailing(args: string[], options: Options, count: number): { own: string[], rest: string[] | undefined } {
+  const takesValue = (word: string) => !word.includes('=') && Object.entries(options).some(([name, { short, type }]) => type === 'string' && (word === `--${name}` || word === `-${short}`))
+  let seen = 0
+
+  if (count === 0)
+    return { own: args, rest: undefined }
+
+  for (let at = 0; at < args.length; at++) {
+    const word = args[at]!
+
+    if (word === '--')
+      break
+
+    if (word.startsWith('-')) {
+      if (takesValue(word))
+        at++
+
+      continue
+    }
+
+    seen++
+
+    if (seen === count)
+      return { own: args.slice(0, at + 1), rest: args.slice(at + 1) }
+  }
+
+  return { own: args, rest: undefined }
+}
+
+// The options as the help and `__complete` list them: with `allowNegative`, `--no-<name>` for an option with a `negative` description, in place of the positive flag when that has none of its own.
+function listed(options: Options, allowNegative: boolean): Options {
+  if (!allowNegative)
+    return options
+
+  return Object.fromEntries(Object.entries(options).flatMap(([name, option]): [string, Options[string]][] => {
+    if (option.type !== 'boolean' || option.negative === undefined)
+      return [[name, option]]
+
+    return [...option.description === undefined ? [] : [[name, option] as [string, Options[string]]], [`no-${name}`, { type: 'boolean', description: option.negative }]]
+  }))
+}
+
+// The arguments with an optional-value option typed bare given its fallback, ahead of the next argument: `--out` becomes `--out 1` unless a value follows it.
+function withBare(args: string[], options: Options): string[] {
+  const bare = new Map<string, NonNullable<Options[string]['optional']>>(Object.entries(options).flatMap(([name, { short, optional }]) => optional === undefined ? [] : [[`--${name}`, optional] as const, ...short === undefined ? [] : [[`-${short}`, optional] as const]]))
+
+  if (bare.size === 0)
+    return args
+
+  const separator = args.indexOf('--')
+  const own = separator === -1 ? args : args.slice(0, separator)
+
+  return [...own.flatMap((arg, index) => {
+    const optional = bare.get(arg)
+    const next = own[index + 1]
+    const value = next !== undefined && (optional?.accepts === undefined ? !next.startsWith('-') : optional.accepts.test(next))
+
+    return optional === undefined || value ? [arg] : [arg, optional.bare]
+  }), ...separator === -1 ? [] : args.slice(separator)]
+}
+
+// A usage error for two options given together that one of them declares in conflict with the other.
+function checkConflicts(values: Record<string, unknown>, options: Options): void {
+  const given = (name: string) => values[name] !== undefined && values[name] !== false
+
+  for (const [name, { conflicts = [] }] of Object.entries(options)) {
+    const other = given(name) ? conflicts.find(given) : undefined
+
+    if (other !== undefined)
+      badUsage(`--${name} cannot be used with --${other}`)
+  }
+}
+
+// A usage error for an option given a value outside its `choices`, in parseArgs' own order.
+function checkChoices(values: Record<string, unknown>, options: Options): void {
+  for (const [name, option] of Object.entries(options)) {
+    if (option.choices === undefined)
+      continue
+
+    const given = values[name]
+
+    for (const value of Array.isArray(given) ? given : [given]) {
+      if (typeof value === 'string')
+        oneOf(value, name, option.choices)
+    }
+  }
+}
+
+// The value when it is one of `choices`, else a usage error naming them: `--bump takes one of patch, minor, major, not big`. A name written `<bump>` is a positional and is printed as is, any other is an option printed `--name`.
+export function oneOf<const Choices extends readonly string[]>(value: string, name: string, choices: Choices): Choices[number] {
+  if (!choices.includes(value))
+    badUsage(`${name.startsWith('<') ? name : `--${name}`} takes one of ${choices.join(', ')}, not ${value}`)
+
+  return value
 }
 
 function checkPositionals(given: string[], names: readonly string[]): void {

package/src/cli.ts

@@ -1,4 +1,4 @@
-import type { Example, Options } from './args'
+import type { Candidate, Example, Options } from './args'
 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'
@@ -17,6 +17,8 @@ export type Command = {
   summary: Summary
   // The heading the command is listed under in the help, after those with none.
   group?: string
+  // Runs as usual but is left out of the help, the typo hints and `__complete`, for a command only a script or a shell binding calls.
+  hidden?: boolean
 } & (
   | { run: (args: string[]) => Promise<number> }
   // 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.
@@ -36,6 +38,8 @@ export interface Cli {
   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.
   defaultCommand?: string
+  // With `defaultCommand`, a bare `<cli>` runs it instead of printing the help (`account` lists, `mux` attaches).
+  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
   // Command lines shown under `Examples:` in `<cli> --help`; a command's own go to `parse`.
@@ -51,8 +55,9 @@ 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.
-async function commandRows(commands: Commands, colors: Colors): Promise<string[]> {
-  const width = Math.max(...Object.keys(commands).map(name => name.length))
+async function commandRows(all: Commands, colors: Colors): Promise<string[]> {
+  const commands = shown(all)
+  const width = Math.max(0, ...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)))
 
@@ -67,6 +72,11 @@ async function commandRows(commands: Commands, colors: Colors): Promise<string[]
   return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [''], colors.bold(heading), ...rows])
 }
 
+// The commands that are not hidden.
+function shown(commands: Commands): Commands {
+  return Object.fromEntries(Object.entries(commands).filter(([, { hidden }]) => hidden !== true))
+}
+
 // The output flags typed before the command name, applied and dropped: `ft --plain runs`.
 function takeOutputFlags(argv: string[]): string[] {
   let index = 0
@@ -100,6 +110,8 @@ interface Level extends Scope {
   header: (colors: Colors, summary: string) => string
   summary: Summary
   defaultCommand: string | undefined
+  // Whether a bare run of the level runs its default command instead of printing the help.
+  runBare: boolean
   examples: Example[] | undefined
   replaces: string | undefined
 }
@@ -221,6 +233,16 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   }
 
   const [name, ...args] = argv
+  const fallback = level.defaultCommand === undefined ? undefined : level.commands[level.defaultCommand]
+
+  if (name === undefined && level.runBare && fallback !== undefined && 'run' in fallback) {
+    try {
+      return await fallback.run([])
+    }
+    catch (error) {
+      return reportThrown(`${prefix} ${level.defaultCommand}`, error, redact, false)
+    }
+  }
 
   if (name === undefined && level.path.length > 1) {
     console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process.stderr))
@@ -242,6 +264,7 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
 
   let command = level.commands[level.aliases?.[name] ?? name]
   let rest = args
+  let ran = name
 
   if (command === undefined && level.lazy.length > 0) {
     level = await expand(level, [...level.path.slice(1), ...argv])
@@ -251,10 +274,11 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand]
     rest = argv
+    ran = level.defaultCommand
   }
 
   if (command === undefined) {
-    const meant = closest(name, Object.keys(level.commands))
+    const meant = closest(name, Object.keys(shown(level.commands)))
 
     printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`)
 
@@ -264,14 +288,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, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, 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, runBare: false, examples: command.examples, replaces: undefined }, rest, { version, redact })
   }
 
   try {
     return await command.run(rest)
   }
   catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest))
+    return reportThrown(`${prefix} ${ran}`, error, redact, wantsJson(rest))
   }
 }
 
@@ -280,8 +304,8 @@ export const COMPLETE = '__complete'
 // Printed instead of candidates where a path fits, for the shell to complete files itself.
 export const FILES = '__files__'
 
-// A command's options, read by running it until its parse call throws them: every command parses its arguments before anything else.
-async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Options> {
+// What a command declares to its completion, read by running it until its parse call throws it: every command parses its arguments before anything else.
+async function completingOf(run: (args: string[]) => Promise<number>): Promise<Completing> {
   completion.active = true
 
   try {
@@ -289,21 +313,74 @@ async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Opti
   }
   catch (error) {
     if (error instanceof Completing)
-      return error.options
+      return error
   }
   finally {
     completion.active = false
   }
 
-  return {}
+  return new Completing({})
+}
+
+async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Options> {
+  return (await completingOf(run)).options
+}
+
+function candidateLine(candidate: Candidate): string {
+  return typeof candidate === 'string' ? candidate : candidate.join('\t')
+}
+
+// The name of the positional the last word is, counting the words before it that are neither options, nor the values of string ones; the last name repeats when it ends in `...`.
+function positionalBeingTyped(before: string[], { options, positionals }: Completing): string | undefined {
+  const takesValue = (word: string) => !word.includes('=') && Object.entries(options).some(([name, { short, type }]) => type === 'string' && (word === `--${name}` || word === `-${short}`))
+  let index = 0
+  let at = 0
+
+  while (at < before.length) {
+    const word = before[at]!
+
+    if (word === '--') {
+      index += before.length - at - 1
+
+      break
+    }
+
+    if (!word.startsWith('-'))
+      index++
+    else if (takesValue(word))
+      at++
+
+    at++
+  }
+
+  const last = positionals.at(-1)
+
+  if (index < positionals.length)
+    return positionals[index]
+
+  return last?.replace(']', '').endsWith('...') === true ? last : undefined
 }
 
-// A leaf command's candidates: its long options for a word starting with a dash, else paths.
+// A leaf command's candidates: the values of the string option just typed or of the positional being typed, else paths for a word not starting with a dash; its long options for one that does.
 async function leafCandidates(run: (args: string[]) => Promise<number>, words: string[]): Promise<string[]> {
-  if (!(words.at(-1) ?? '').startsWith('-'))
-    return [FILES]
+  const completing = await completingOf(run)
 
-  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}\t${option.description}`)
+  if ((words.at(-1) ?? '').startsWith('-'))
+    return Object.entries(completing.options).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}\t${option.description}`)
+
+  const flag = words.at(-2)
+  const option = flag?.startsWith('-') === true ? Object.entries(completing.options).find(([name, { short }]) => flag === `--${name}` || flag === `-${short}`)?.[1] : undefined
+
+  if (option?.type === 'string') {
+    const values = option.choices === undefined ? await option.candidates?.() : option.choices
+
+    return values === undefined ? [FILES] : values.map(candidateLine)
+  }
+
+  const name = positionalBeingTyped(words.slice(0, -1), completing)
+  const values = name === undefined ? undefined : await completing.candidates[name]?.()
+
+  return values === undefined ? [FILES] : values.map(candidateLine)
 }
 
 // The candidates for the last word, `value\tdescription` per line, after walking the subcommands the earlier words name.
@@ -319,7 +396,7 @@ async function candidates(scope: Scope, defaultCommand: string | undefined, word
   }
 
   if (listing)
-    return Promise.all(Object.entries(commands).map(async ([name, { summary }]) => `${name}\t${await resolveSummary(summary)}`))
+    return Promise.all(Object.entries(shown(commands)).map(async ([name, { summary }]) => `${name}\t${await resolveSummary(summary)}`))
 
   if (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
@@ -342,7 +419,7 @@ 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, 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, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact })
 }
 
 export interface Main {
@@ -352,6 +429,22 @@ export interface Main {
   redact?: (text: string) => string
 }
 
+// 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.
+export async function mainArgs<T>(main: Omit<Main, 'run'>, parseArgv: (args: string[]) => T, argv = process.argv.slice(2)): Promise<T> {
+  let parsed: { value: T } | undefined
+  // eslint-disable-next-line ts/require-await -- commands are async by contract
+  const code = await runMain({ ...main, run: async (args) => {
+    parsed = { value: parseArgv(args) }
+
+    return 0
+  } }, argv)
+
+  if (parsed === undefined)
+    process.exit(code)
+
+  return parsed.value
+}
+
 // 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> {
   if (argv[0] === COMPLETE)

package/src/prompt.ts

@@ -1,4 +1,7 @@
 import type { Colors } from './style'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import process from 'node:process'
 import { fail } from './args'
 import { truncate } from './format'
@@ -42,14 +45,17 @@ function readKeys(input: string): Key[] {
   return (input.match(KEY_SEQUENCES) ?? []).flatMap(sequence => KEYS[sequence] ?? (CONTROL.test(sequence) ? [] : [{ text: sequence }]))
 }
 
-export interface SelectSettings extends PromptSettings {
+export interface SelectSettings<T> extends PromptSettings {
   // The index of the choice the cursor starts on.
   initial?: number
+  // The value of the choice the cursor starts on, winning over `initial` when a choice holds it.
+  default?: T
 }
 
 // One choice among several, typing filtering them, the arrows moving and Enter picking; undefined once Escape or Ctrl+C cancels.
-export async function select<T>(question: string, choices: Choice<T>[], { initial = 0, ...settings }: SelectSettings = {}): Promise<T | undefined> {
-  const list = new List(choices, initial)
+export async function select<T>(question: string, choices: Choice<T>[], { initial = 0, default: fallback, ...settings }: SelectSettings<T> = {}): Promise<T | undefined> {
+  const named = choices.findIndex(choice => choice.value === fallback)
+  const list = new List(choices, fallback === undefined || named === -1 ? initial : named)
   const picked = await ask(question, settings, (colors, state, rows) => state === 'asking'
     ? [asking(colors, question, list.query, 'type to filter, enter picks'), ...list.rows(colors, rows, () => '')]
     : [answer(colors, question, state, list.current()?.label ?? '')], (key) => {
@@ -69,6 +75,8 @@ export async function select<T>(question: string, choices: Choice<T>[], { initia
 
 export interface ChecklistSettings<T> extends PromptSettings {
   initial?: ReadonlySet<T>
+  // How many choices Enter needs checked: on fewer, `pick at least N` shows under the list until the next key instead of answering.
+  min?: number
   // What checking or unchecking `value` leaves checked, which may change other choices along; flips `value` alone by default.
   toggle?: (checked: ReadonlySet<T>, value: T) => ReadonlySet<T>
 }
@@ -83,15 +91,24 @@ function flip<T>(checked: ReadonlySet<T>, value: T): ReadonlySet<T> {
 }
 
 // Several choices, typing filtering them, Space checking or unchecking the one under the cursor and Enter accepting what is checked; undefined once cancelled.
-export async function checklist<T>(question: string, choices: Choice<T>[], { initial = new Set(), toggle = flip, ...settings }: ChecklistSettings<T> = {}): Promise<ReadonlySet<T> | undefined> {
+export async function checklist<T>(question: string, choices: Choice<T>[], { initial = new Set(), min = 0, toggle = flip, ...settings }: ChecklistSettings<T> = {}): Promise<ReadonlySet<T> | undefined> {
   const list = new List(choices, 0)
   let checked = initial
+  let invalid: string | undefined
   const accepted = await ask(question, settings, (colors, state, rows) => state === 'asking'
-    ? [asking(colors, question, list.query, 'type to filter, space toggles, enter accepts'), ...list.rows(colors, rows, choice => checked.has(choice.value) ? `${colors.cyan('◉')} ` : `${colors.dim('◯')} `)]
+    ? [asking(colors, question, list.query, 'type to filter, space toggles, enter accepts'), ...list.rows(colors, rows, choice => checked.has(choice.value) ? `${colors.cyan('◉')} ` : `${colors.dim('◯')} `), ...invalid === undefined ? [] : [`  ${colors.red(invalid)}`]]
     : [answer(colors, question, state, choices.filter(choice => checked.has(choice.value)).map(choice => choice.label).join(', ') || 'none')], (key) => {
-    if (key === 'enter' || key === 'cancel')
+    if (key === 'cancel')
       return key
 
+    invalid = undefined
+
+    if (key === 'enter') {
+      invalid = checked.size < min ? `pick at least ${min}` : undefined
+
+      return invalid === undefined ? 'enter' : undefined
+    }
+
     const current = list.current()
 
     if (typeof key === 'object' && key.text === ' ') {
@@ -329,3 +346,41 @@ async function ask(question: string, { hint, terminal = process }: PromptSetting
     stdin.pause()
   }
 }
+
+export interface EditorSettings extends PromptSettings {
+  // The text the file starts with.
+  default?: string
+  // The file's extension, such as `.md`, so the editor picks its highlighting.
+  extension?: string
+  // Where VISUAL and EDITOR are read, the process's environment by default.
+  env?: Record<string, string | undefined>
+}
+
+// A text edited in VISUAL or EDITOR (vi without either) on a temp file, the editor taking the terminal until it exits; undefined when it exits nonzero, as `:cq` does.
+export async function editor(question: string, { default: text = '', extension = '.txt', env = process.env, hint, terminal = process }: EditorSettings = {}): Promise<string | undefined> {
+  const { stdin, stderr } = terminal
+
+  if (stdin.isTTY !== true || stderr.isTTY !== true)
+    fail(`cannot ask "${question}" off a terminal`, 2, hint)
+
+  const colors = paint(stderr)
+  const command = [env.VISUAL, env.EDITOR].find(value => value !== undefined && value !== '') ?? 'vi'
+  const dir = await mkdtemp(join(tmpdir(), 'kit-editor-'))
+  const file = join(dir, `edit${extension}`)
+
+  try {
+    await writeFile(file, text)
+    stderr.write(`${colors.cyan('?')} ${question} ${colors.dim(`(${command})`)}\n`)
+
+    // Through the shell, so an EDITOR with arguments (`code --wait`) runs as typed.
+    const edited = Bun.spawn(['sh', '-c', `${command} "$1"`, 'sh', file], { stdio: ['inherit', 'inherit', 'inherit'], env })
+    const done = await edited.exited === 0
+
+    stderr.write(`${answer(colors, question, done ? 'enter' : 'cancel', 'edited')}\n`)
+
+    return done ? await readFile(file, 'utf8') : undefined
+  }
+  finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}