@kaynooo/cli-kit 0.13.0 → 0.15.0

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 npmjs as a dependency (`bun add --exact @kaynooo/cli-kit`).
+It ships its TypeScript source and runs on Bun only (>= 1.4.3). The @kaynooo/cli-* packages 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'
@@ -44,13 +44,14 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `<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.
+- `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.
 - `runCommand(argv, { cwd, env, stdin, timeoutMs, signal, maxBytes, onChunk, onStart })` runs a command and returns `{ code, text, output, chunks, timedOut, truncated }`, the output of both streams (in arrival order, tagged by stream in `chunks`); it throws when the command cannot start. With `timeoutMs`, `signal`, `onChunk` or `onStart` the child leads its own process group, ended whole (SIGTERM, SIGKILL after 2 s) when the timeout passes, the signal aborts or `onChunk` throws, the pipes still read to the end: `timedOut` is then true, for the caller to exit 2. `maxBytes` caps what `chunks`, `output` and `text` keep (`truncated`), `onChunk` sees every chunk, and `onStart` hands over `{ kill }` for the whole group, to pass to `holdSignals().forward`. `exitCodeOf(code, signal)` is the exit code a shell reports.
 - `holdSignals(cleanup?)` takes SIGINT, SIGTERM and SIGHUP over until `release()`: a signal goes to the child given to `forward(child)`, so the CLI exits with the child's code; without one, `cleanup(signal)` runs and the signal is raised again, ending the process as it would have; without either, it is only kept in `signal`, for the caller to wind down (`base` holds them while its worktree exists).
-- `privateLogDirectory(name)` returns a folder for log files only this user reads (`$XDG_RUNTIME_DIR` or `~/.cache/agent-tools`, mode 0700, verified with `lstat` when it exists, else a fresh temp folder), `createLog(path)` opens a 0600 file that must not exist (returning its descriptor), and `sweepLogs(dir, maxAgeMs?)` removes what is older than a day, subfolders included.
+- `privateLogDirectory(name)` returns a folder for log files only this user reads (`$XDG_RUNTIME_DIR` or `~/.cache/kaynooo-cli`, mode 0700, verified with `lstat` when it exists, else a fresh temp folder), `createLog(path)` opens a 0600 file that must not exist (returning its descriptor), and `sweepLogs(dir, maxAgeMs?)` removes what is older than a day, subfolders included.
 - `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.
-- `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.
+- `replaces` on the CLI or in `parse`'s settings (`'sed -n N,Mp, grep -n chains'`) adds an `Instead of:` line under the usage. With `KIT_HELP=json` in the environment, `--help` prints `{synopsis, summary, replaces?, examples}` instead, the usage's first line split at its first `: `, which is how `cli list` reads every bin.
 - `runHint(command, effect?)` words the hint of a refusal that a command resolves, ``run `ft take 12 --take-stale` to take it over``, so every CLI writes it alike: `fail(message, 1, runHint('ft take 12 --take-stale', 'take it over'))`. `printHint(hint)` prints the `hint:` line under a refusal a command prints itself (one issue of several refused).
 - `limitOptions(fallback)` is the `--limit <n>` and `--full` flags of a listing, `limitOf(values, fallback)` the row count they ask for (Infinity with `--full`; with `json: true` in the values, Infinity unless `--limit` is given, so JSON is never cut on its own), and `capped(rows, limit)` the first rows plus the footer `N more, rerun with --full` when some are left out.
 - `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.
@@ -58,7 +59,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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.
 - `isSecretName(name)` is true for the name of a variable, column or JSON key that holds a secret (`API_TOKEN`, `DB_PASS`, `SMTP_PWD`, `clientSecret`, `session_id`, `ssn`), by whole words so `compass` and `author` stay plain; `ev`, `redact` and `db` share it.
-- `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.
+- `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.
@@ -69,7 +70,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `@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.
 - `task(label, run)` from `/progress` runs one step under a spinner, `run` given an `update({ done?, total?, unit? })` for a bar, and ends on `✓ <label> <time>`, or `✗ <label>` and the error thrown again.
 - `taskList(stream?, env?)` from `/progress` stacks a progress line per task running side by side: `add(label)` returns `{ update, done(text?), failed(text?) }`, and a task ending leaves its `✓` or `✗` line above those still running.
-- `liveRegion(render, stream?, env?)` from `/progress` is the block both draw with: the lines `render(spinner)` returns, redrawn every frame (`redraw()` draws at once), each cut to the terminal's width and the block to its height, `print(text)` printing above it and `stop()` clearing it. Like the progress line it draws only where `takesControlCodes`, and `ft ci` and `waitfor` show what they wait on with it.
+- `liveRegion(render, stream?, env?)` from `/progress` is the block both draw with: the lines `render(spinner)` returns, redrawn every frame (`redraw()` draws at once), each cut to the terminal's width and the block to its height, `print(text)` printing above it and `stop()` clearing it. Like the progress line it draws only where `takesControlCodes`; keys typed on the terminal meanwhile are swallowed, Ctrl+C aside, so an Enter cannot push it down and leave a line behind. `ft ci` and `ft ci` and `waitfor` show what they wait on with it.
 - `badge(word, stream)` marks a status word on a terminal, the same five ways everywhere: `✓ success` green, `✗ failure` red, `● running` cyan, `○ waiting` yellow, `- skipped` dimmed; the word alone elsewhere. `statusOf(word)` reads the words Forgejo and GitLab report (`success`, `failed`, `pending`, `canceled`...) as `passed`, `failed`, `running`, `queued` or `skipped`.
 - `keyValue(pairs)` aligns `label  value` lines, `sparkline(values)` draws `▁▃▇`, `bar(ratio)` and `barChart(rows)` draw cyan bars on a dimmed track, and `tree(roots)` hangs `{ label, children? }` nodes on dimmed `├─`, `└─` branches.
 - `@kaynooo/cli-kit/shell` reads shell command lines the way a hook vetting them needs: `splitCommand` cuts one into pieces at the separators outside quotes and heredocs, `parseCommand` names a piece's program past `sudo`/`env` wrappers and assignments, `tokenize`, `words`, `substitutions` and `replacePieces` take it apart and put it back.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.15.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",
-  "homepage": "https://git.kaynooo.fr/kaynooo/agent-tools/src/branch/main/packages/kit#readme",
+  "homepage": "https://git.kaynooo.fr/kaynooo/cli/src/branch/main/packages/kit#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://git.kaynooo.fr/kaynooo/agent-tools.git",
+    "url": "git+https://git.kaynooo.fr/kaynooo/cli.git",
     "directory": "packages/kit"
   },
-  "bugs": "https://git.kaynooo.fr/kaynooo/agent-tools/issues",
+  "bugs": "https://git.kaynooo.fr/kaynooo/cli/issues",
   "keywords": [
     "args",
     "bun",

package/src/args.ts

@@ -1,4 +1,5 @@
 import type { ParseArgsOptionDescriptor } from 'node:util'
+import { fstatSync } from 'node:fs'
 import process from 'node:process'
 import { parseArgs } from 'node:util'
 import { upTo } from './format'
@@ -68,7 +69,7 @@ export function replacesRows(replaces: string | undefined, colors = paint(proces
   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.
+// What a bin's --help prints under KIT_HELP=json, for `cli list` to read without parsing the text.
 export interface Description {
   synopsis: string
   summary: string
@@ -131,7 +132,7 @@ 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'.
+  // 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'.
   replaces?: string
 }
 
@@ -291,11 +292,11 @@ export function wholeNumber(value: string | undefined, name: string, fallback: n
   return number
 }
 
-const DURATION = /^(\d+(?:\.\d+)?)(ms|[smh])?$/
-const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 } as const
+const DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const
 
-// A duration such as `500ms`, `90s`, `5m` or `1h` in milliseconds, a bare number counting in `unit`.
-export function duration(value: string | undefined, name: string, fallback: number, unit: 's' | 'm' = 's'): number {
+// A duration such as `500ms`, `90s`, `5m`, `1h` or `7d` in milliseconds, a bare number counting in `unit`.
+export function duration(value: string | undefined, name: string, fallback: number, unit: 's' | 'm' | 'h' = 's'): number {
   if (value === undefined)
     return fallback
 
@@ -303,11 +304,18 @@ export function duration(value: string | undefined, name: string, fallback: numb
   const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[(match[2] ?? unit) as keyof typeof UNIT_MS]
 
   if (ms < 1)
-    badUsage(`--${name} takes a duration such as 30s, 5m or 1h, not ${value}`)
+    badUsage(`--${name} takes a duration such as 30s, 5m, 1h or 7d, not ${value}`)
 
   return ms
 }
 
+// Whether stdin is a pipe or a file to read, rather than a terminal or /dev/null that would leave a command waiting or reading nothing.
+export function isStdinPiped(): boolean {
+  const stat = fstatSync(0)
+
+  return stat.isFIFO() || stat.isFile()
+}
+
 export interface InputSettings {
   // What to say when stdin is a terminal, as nothing is piped.
   noStdin?: string

package/src/logs.ts

@@ -6,6 +6,9 @@ import process from 'node:process'
 
 const DAY_MS = 24 * 60 * 60 * 1000
 
+// The folder the @kaynooo/cli-* bins keep their logs and state in, under the runtime, cache or state directory.
+export const CLI_FOLDER = 'kaynooo-cli'
+
 // Whether the folder is a real directory (not a link) that only this user can use.
 function isPrivateDirectory(path: string): boolean {
   try {
@@ -18,10 +21,10 @@ function isPrivateDirectory(path: string): boolean {
   }
 }
 
-// A folder for log files that only this user can read: `<name>` under $XDG_RUNTIME_DIR, else ~/.cache/agent-tools. When one already exists it must be a private directory of this user, otherwise a fresh private folder in the temp directory is used instead of trusting it.
+// A folder for log files that only this user can read: `<name>` under $XDG_RUNTIME_DIR, else ~/.cache/kaynooo-cli. When one already exists it must be a private directory of this user, otherwise a fresh private folder in the temp directory is used instead of trusting it.
 export async function privateLogDirectory(name: string, env: Record<string, string | undefined> = process.env): Promise<string> {
   const runtime = env.XDG_RUNTIME_DIR
-  const base = runtime === undefined || runtime === '' ? join(homedir(), '.cache', 'agent-tools') : join(runtime, 'agent-tools')
+  const base = runtime === undefined || runtime === '' ? join(homedir(), '.cache', CLI_FOLDER) : join(runtime, CLI_FOLDER)
   const path = join(base, name)
 
   try {

package/src/progress.ts

@@ -62,6 +62,8 @@ const ESC = String.fromCharCode(27)
 // A colour or cursor code, or an OSC 8 link's opening or closing, read where `lastIndex` points.
 const ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x7E]|\\][^\\u0007${ESC}]*(?:\\u0007|${ESC}\\\\))`, 'y')
 const RESET_STYLE = `${ESC}[0m`
+// What Ctrl+C sends once raw mode stops the terminal turning it into SIGINT.
+const CTRL_C = 3
 const CLOSE_LINK = `${ESC}]8;;${ESC}\\`
 // What the console prints with, to the terminal the line is drawn on or the other.
 const CONSOLE_METHODS = ['log', 'info', 'warn', 'error', 'debug', 'dir', 'dirxml', 'table', 'trace', 'group', 'groupCollapsed', 'count', 'timeEnd', 'timeLog', 'assert'] as const
@@ -102,7 +104,11 @@ export function liveRegion(render: (spinner: string) => string[], stream: Progre
   }
   const timer = setInterval(draw, FRAME_MS)
   const restore = interceptOutput(clear)
-  const onExit = () => clear()
+  const release = swallowInput()
+  const onExit = () => {
+    clear()
+    release()
+  }
   // Interrupted, the block goes before the shell's prompt comes back.
   const signals = holdSignals(stop)
 
@@ -110,6 +116,7 @@ export function liveRegion(render: (spinner: string) => string[], stream: Progre
     clearInterval(timer)
     clear()
     restore()
+    release()
     process.off('exit', onExit)
     signals.release()
   }
@@ -288,6 +295,35 @@ function cutToWidth(line: string, width: number): string {
   return `${kept}${RESET_STYLE}${linked ? CLOSE_LINK : ''}`
 }
 
+// Keeps keys typed on the terminal from being echoed while the region is drawn: an Enter would push it down a line and leave its first line behind on every redraw. Ctrl+C still interrupts.
+function swallowInput(): () => void {
+  const input = process.stdin
+
+  if (!input.isTTY)
+    return () => undefined
+
+  const onData = (data: Buffer) => {
+    if (data.includes(CTRL_C))
+      process.kill(process.pid, 'SIGINT')
+  }
+
+  input.setRawMode(true)
+  input.on('data', onData)
+  input.resume()
+
+  let released = false
+
+  return () => {
+    if (released)
+      return
+
+    released = true
+    input.off('data', onData)
+    input.pause()
+    input.setRawMode(false)
+  }
+}
+
 // Clears the region before anything the console or a stream writes, the caller's own code meanwhile included, and answers how to put them back.
 function interceptOutput(clear: () => void): () => void {
   const targets = [...CONSOLE_METHODS.map(name => [console, name] as const), [process.stdout, 'write'] as const, [process.stderr, 'write'] as const]

package/src/test.ts

@@ -1,5 +1,9 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import process from 'node:process'
 import { format } from 'node:util'
+import { afterAll } from 'bun:test'
 
 export interface Captured<T> {
   result: T
@@ -9,6 +13,24 @@ export interface Captured<T> {
   err: string
 }
 
+// Called at the top of a test file, answers a maker of fresh folders under the system temp folder, each removed with its content once the file's tests are done.
+export function tempDirs(): (prefix?: string) => string {
+  const made: string[] = []
+
+  afterAll(() => {
+    for (const dir of made.splice(0))
+      rmSync(dir, { recursive: true, force: true })
+  })
+
+  return (prefix = 'test-') => {
+    const dir = mkdtempSync(join(tmpdir(), prefix))
+
+    made.push(dir)
+
+    return dir
+  }
+}
+
 // Runs a command in-process and returns what it printed, so a test needs no spy on console. Output is restored even when the command throws.
 export async function capture<T>(run: () => Promise<T> | T): Promise<Captured<T>> {
   const written = { out: '', err: '' }