@kaynooo/cli-kit 0.15.2 → 0.16.0

package/README.md

@@ -36,10 +36,10 @@ 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.
 - `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"`), 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`). 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.
 - `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.
@@ -65,6 +65,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
   - `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.
   - `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.16.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,8 @@ import { upTo } from './format'
 import { paint } from './style'
 import { closest } from './text'
 
-export type Options = Record<string, ParseArgsOptionDescriptor & { 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.
+export type Options = Record<string, ParseArgsOptionDescriptor & { description?: string, choices?: readonly string[] }>
 
 // The `--json` flag every CLI words alike: `print JSON`, then what it holds when given.
 export function jsonOption(holds?: string) {
@@ -109,9 +110,10 @@ 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 placeholder = option.choices === undefined ? '<value>' : `<${option.choices.join('|')}>`
+    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,6 +125,15 @@ 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
@@ -202,10 +213,35 @@ export function parse<const T extends Options, const Names extends readonly stri
     throw new HelpShown()
   }
 
+  checkChoices(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 }
+}
+
+// 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

@@ -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.
@@ -51,8 +53,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 +70,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
@@ -254,7 +262,7 @@ async function dispatch(level: Level, typed: string[], { version, redact }: { ve
   }
 
   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}?`)
 
@@ -298,10 +306,14 @@ async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Opti
   return {}
 }
 
-// A leaf command's candidates: its long options for a word starting with a dash, else paths.
+// A leaf command's candidates: the choices of the string option just typed, its long options for a word starting with a dash, else paths.
 async function leafCandidates(run: (args: string[]) => Promise<number>, words: string[]): Promise<string[]> {
-  if (!(words.at(-1) ?? '').startsWith('-'))
-    return [FILES]
+  if (!(words.at(-1) ?? '').startsWith('-')) {
+    const flag = words.at(-2)
+    const option = flag?.startsWith('-') === true ? Object.entries(await optionsOf(run)).find(([name, { short }]) => flag === `--${name}` || flag === `-${short}`)?.[1] : undefined
+
+    return option?.type === 'string' && option.choices !== undefined ? [...option.choices] : [FILES]
+  }
 
   return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}\t${option.description}`)
 }
@@ -319,7 +331,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]

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'
@@ -329,3 +332,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 })
+  }
+}