@kaynooo/cli-kit 0.12.0 → 0.14.0

package/README.md

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

@@ -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'
@@ -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/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/shell.ts

@@ -592,8 +592,13 @@ export function parseCommand(text: string): Invocation {
   return { program: program.split('/').pop() ?? '', args, assignments, isWrapped }
 }
 
+// A word as a POSIX shell or zsh reads it back unchanged: left bare when it holds nothing the shell would act on (zsh expands a leading `=`), else single-quoted.
+export function shellQuote(word: string): string {
+  return SAFE_WORD.test(word) && !word.startsWith('=') ? word : `'${word.replaceAll('\'', '\'\\\'\'')}'`
+}
+
 function quoted(word: string): string {
-  return SAFE_WORD.test(word) || word === '{}' ? word : `'${word.replaceAll('\'', '\'\\\'\'')}'`
+  return word === '{}' ? word : shellQuote(word)
 }
 
 // The command strings a piece hands to a shell with `-c`, wherever the shell sits in it (`docker exec db sh -c '...'`, `su -c '...'`).

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: '' }