@kaynooo/cli-kit 0.10.0 → 0.12.0

package/README.md

@@ -33,6 +33,9 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 ## API
 
 - `runCli({ name, version, about, commands, aliases })` dispatches `<cli> <command> [args]`: `--help` lists the commands, `--version` prints the version, a typo names the command it likely meant, and an `Exit` thrown by a command prints `error: <cli> <command>: <message>`, its hint under it, and exits with its code. Any other error exits 1, named by its class unless a plain `Error` (`error: tool sync: MigrationError: ...`), its cause's message on a `cause:` line under it when the cause is an `Error`; `redact(text)` rewrites both before they print, for errors that may quote what a log must not keep.
+- `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.
 - `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`.
@@ -41,8 +44,9 @@ 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.
-- `runCommand(argv, { cwd, env, stdin })` runs a command and returns `{ code, text, output, chunks }`, the output of both streams (in arrival order, tagged by stream in `chunks`); it throws when the command cannot start. `exitCodeOf(code, signal)` is the exit code a shell reports.
+- `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.
 - `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.
@@ -53,6 +57,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `stripAnsi(text)` removes colour and cursor codes, and `distance(a, b)` is the edit distance between two names.
 - `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.
 - `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:

package/package.json

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

@@ -276,14 +276,17 @@ function nearestOption(message: string, options: Options, allowNegative: boolean
   return meant === undefined ? undefined : `did you mean ${known.find(flag => flag.replace(DASHES, '') === meant)}?`
 }
 
+const WHOLE = /^\d+$/
+
+// A name written `<run id>` is a positional and is printed as is, any other is an option printed `--name`.
 export function wholeNumber(value: string | undefined, name: string, fallback: number, min = 1): number {
   if (value === undefined)
     return fallback
 
   const number = Number(value)
 
-  if (!Number.isInteger(number) || number < min)
-    badUsage(`--${name} takes a whole number from ${min}, not ${value}`)
+  if (!WHOLE.test(value) || !Number.isSafeInteger(number) || number < min)
+    badUsage(`${name.startsWith('<') ? name : `--${name}`} takes a whole number from ${min}, not ${value}`)
 
   return number
 }

package/src/ci.ts

@@ -0,0 +1,132 @@
+import { Exit, fail } from './args'
+import { formatDuration } from './format'
+import { liveRegion } from './progress'
+import { cwdGone, isPermanentFailure } from './tool'
+
+export interface CiStall {
+  // The message the wait fails with.
+  message: string
+  // Fails at once instead of after `stalledMs`.
+  certain?: boolean
+}
+
+export interface CiWait<T> {
+  // The command's name, as its warnings print it (`ft ci`).
+  tool: string
+  // The abbreviated sha the wait is for.
+  short: string
+  giveUpMs: number
+  // How long the wait goes on with nothing covering the commit.
+  noneMs: number
+  // How long queued work may sit while nothing moves.
+  stalledMs: number
+  pollMs?: number
+  // The message the wait fails with once nothing covered the commit for `noneMs`.
+  noneMessage: string
+  // What covers the commit now, or undefined; a refusal such as a commit not on the branch is thrown as an Exit.
+  covering: () => Promise<T | undefined>
+  finished: (found: T) => boolean
+  // Identifies what is followed, so `announce` runs again when it changes.
+  key: (found: T) => string
+  announce: (found: T) => void
+  // The links to what is followed, for the messages of a wait that ends unfinished.
+  links: (found: T) => string
+  // What a covering that failed leaves of the followed value once it can be read as over, or undefined to go on polling.
+  settle: (found: T) => Promise<T | undefined>
+  // Why the unfinished work is not moving, or undefined while it moves.
+  stall?: (found: T) => Promise<CiStall | undefined>
+  // The lines of a live region under the wait, on a terminal.
+  lines?: (spinner: string, found: T | undefined, startedAt: number) => string[]
+}
+
+const POLL = 15_000
+
+// Waits until what covers a commit has finished, polling `covering`: a poll failing for a network reason is retried, one failing for good (a missing binary, a 401, 403 or 404) or a refusal ends the wait.
+export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
+  const { tool, short, giveUpMs, noneMs, stalledMs, pollMs = POLL } = wait
+  const started = Date.now()
+  let seen = started
+  let moving = started
+  let followed = ''
+  let found: T | undefined
+  const region = wait.lines === undefined ? undefined : liveRegion(spinner => wait.lines?.(spinner, found, started) ?? [])
+  const suffix = () => found === undefined ? '' : `: ${wait.links(found)}`
+
+  // A failure to read the stall is retried on the next poll, and leaves the stall unknown.
+  async function stallOf(current: T): Promise<CiStall | undefined | 'unknown'> {
+    try {
+      return await wait.stall?.(current)
+    }
+    catch (error) {
+      if (error instanceof Exit || isPermanentFailure(error))
+        throw error
+
+      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+
+      return 'unknown'
+    }
+  }
+
+  try {
+    for (;;) {
+      if (Date.now() - started > giveUpMs)
+        fail(`CI has not finished on ${short} in ${formatDuration(giveUpMs)}${suffix()}`)
+
+      // The forge or origin missing one poll leaves the wait to the next, unless what is followed is over by then.
+      try {
+        found = await wait.covering()
+      }
+      catch (error) {
+        if (error instanceof Exit)
+          throw error
+
+        if (cwdGone())
+          fail(`the working directory was removed while waiting for CI on ${short}${suffix()}`)
+
+        if (isPermanentFailure(error))
+          fail(error instanceof Error ? error.message : String(error))
+
+        console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+
+        const latest = found === undefined ? undefined : await wait.settle(found)
+
+        if (latest !== undefined)
+          return latest
+
+        await Bun.sleep(pollMs)
+
+        continue
+      }
+
+      if (found !== undefined) {
+        seen = Date.now()
+
+        const key = wait.key(found)
+
+        if (key !== followed) {
+          followed = key
+          moving = Date.now()
+          wait.announce(found)
+        }
+
+        if (wait.finished(found))
+          return found
+
+        const stall = await stallOf(found)
+
+        if (stall === undefined)
+          moving = Date.now()
+        else if (stall !== 'unknown' && (stall.certain === true || Date.now() - moving > stalledMs))
+          fail(stall.message)
+      }
+      else if (Date.now() - seen > noneMs) {
+        fail(wait.noneMessage)
+      }
+
+      await Bun.sleep(pollMs)
+    }
+  }
+  finally {
+    region?.stop()
+  }
+}

package/src/config.ts

@@ -1,10 +1,11 @@
 import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import process from 'node:process'
 import { fail } from './args'
 
-// The nearest of `names` in `from` or a folder above it, the first name winning within one folder.
-export function findUp(names: string | string[], from = process.cwd()): string | undefined {
+// The nearest of `names` in `from` or a folder above it, the first name winning within one folder; the walk ends after a folder `stop` accepts.
+export function findUp(names: string | string[], from = process.cwd(), stop: (dir: string) => boolean = () => false): string | undefined {
   const wanted = typeof names === 'string' ? [names] : names
 
   for (let dir = resolve(from); ; dir = dirname(dir)) {
@@ -13,11 +14,16 @@ export function findUp(names: string | string[], from = process.cwd()): string |
     if (found !== undefined)
       return found
 
-    if (dirname(dir) === dir)
+    if (stop(dir) || dirname(dir) === dir)
       return undefined
   }
 }
 
+// A config is looked for up to the repository root or the home folder, never in a folder above them where a stranger's file could sit.
+function endsWalk(dir: string): boolean {
+  return dir === resolve(homedir()) || existsSync(join(dir, '.git'))
+}
+
 export interface ConfigSettings {
   // Where the search starts, the current folder by default.
   from?: string
@@ -33,9 +39,9 @@ export interface LoadedConfig {
   config: unknown
 }
 
-// Imports the nearest config named `names` (`.ts`, `.js` or `.json`), or the one `path` names; undefined when none is found. A named file missing, one failing to import or one without a default export ends the command.
+// Imports the nearest config named `names` (`.ts`, `.js` or `.json`) up to the git root or the home folder, or the one `path` names; undefined when none is found. A named file missing, one failing to import or one without a default export ends the command.
 export async function loadConfig(names: string | string[], { from = process.cwd(), path }: ConfigSettings = {}): Promise<LoadedConfig | undefined> {
-  const file = path === undefined ? findUp(names, from) : resolve(from, path)
+  const file = path === undefined ? findUp(names, from, endsWalk) : resolve(from, path)
 
   if (file === undefined)
     return undefined

package/src/git.ts

@@ -0,0 +1,55 @@
+import { basename, dirname } from 'node:path'
+import process from 'node:process'
+import { fail } from './args'
+import { cwdGone, runTool } from './tool'
+
+const ORIGIN_PREFIX = /^origin\//
+
+// How long a git call that reaches the network waits for origin.
+export const GIT_NETWORK_MS = 60_000
+
+// Runs git and returns its trimmed output; throws with git's own message on a failure, or when git cannot start or outlives `timeoutMs`.
+export async function git(args: string[], timeoutMs?: number): Promise<string> {
+  const result = await runTool(`git ${args.join(' ')}`, ['git', ...args], { timeoutMs })
+
+  if (result.code !== 0)
+    throw new Error(`git ${args.join(' ')}: ${result.stderr.trim() || `exit ${result.code}`}${cwdGone() ? ' (the working directory was removed)' : ''}`)
+
+  return result.stdout.trim()
+}
+
+export async function gitOk(args: string[]): Promise<boolean> {
+  return (await runTool(`git ${args.join(' ')}`, ['git', ...args])).code === 0
+}
+
+export async function resolveCommit(ref: string): Promise<string> {
+  const sha = (await runTool('git rev-parse', ['git', 'rev-parse', '--verify', '-q', '--end-of-options', `${ref}^{commit}`])).stdout.trim()
+
+  if (sha === '')
+    fail(`no commit ${ref}`)
+
+  return sha
+}
+
+// Fetches one branch of origin; a name that is no branch, such as `--upload-pack=<command>`, is refused before git reads it, and the refspec is spelled out so it can never be an option.
+export async function fetchBranch(branch: string): Promise<void> {
+  if (branch.startsWith('-') || !await gitOk(['check-ref-format', '--branch', branch]))
+    fail(`${branch} is not a branch name`)
+
+  await git(['fetch', '-q', 'origin', `refs/heads/${branch}`], GIT_NETWORK_MS)
+}
+
+// The branch origin's HEAD names, which is the repository's default branch once cloned or `git remote set-head origin -a` ran.
+export async function defaultBranch(): Promise<string> {
+  const head = (await runTool('git symbolic-ref', ['git', 'symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD'])).stdout.trim()
+
+  return head === '' ? 'main' : head.replace(ORIGIN_PREFIX, '')
+}
+
+// A linked worktree can be deleted while a wait runs in it, so the wait moves to the main checkout, which outlives it.
+export async function leaveWorktree(): Promise<void> {
+  const common = await git(['rev-parse', '--path-format=absolute', '--git-common-dir'])
+
+  if (basename(common) === '.git')
+    process.chdir(dirname(common))
+}

package/src/index.ts

@@ -1,9 +1,15 @@
 export * from './args'
 export * from './chart'
+export * from './ci'
 export * from './cli'
 export * from './config'
 export * from './format'
+export * from './git'
 export * from './limit'
+export * from './logs'
 export * from './process'
+export * from './secrets'
+export * from './sessions'
 export * from './style'
 export * from './text'
+export * from './tool'

package/src/logs.ts

@@ -0,0 +1,72 @@
+import { lstatSync, openSync } from 'node:fs'
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+// Whether the folder is a real directory (not a link) that only this user can use.
+function isPrivateDirectory(path: string): boolean {
+  try {
+    const info = lstatSync(path, { throwIfNoEntry: false })
+
+    return info !== undefined && info.isDirectory() && info.uid === (process.getuid?.() ?? info.uid) && (info.mode & 0o077) === 0
+  }
+  catch {
+    return false
+  }
+}
+
+// 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.
+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 path = join(base, name)
+
+  try {
+    await mkdir(path, { recursive: true, mode: 0o700 })
+
+    if (isPrivateDirectory(path))
+      return path
+  }
+  catch {
+    // Falls through to the temp folder below.
+  }
+
+  return mkdtemp(join(tmpdir(), `${name.replaceAll('/', '-')}-`))
+}
+
+// Removes what is older than `maxAgeMs` in the folder, and the empty subfolders it leaves, best effort since another run may be doing the same.
+export async function sweepLogs(dir: string, maxAgeMs = DAY_MS, now = Date.now()): Promise<void> {
+  let names: string[]
+
+  try {
+    names = await readdir(dir)
+  }
+  catch {
+    return
+  }
+
+  for (const name of names) {
+    const path = join(dir, name)
+
+    try {
+      const info = await stat(path)
+
+      if (info.isDirectory())
+        await sweepLogs(path, maxAgeMs, now)
+
+      if (now - info.mtimeMs > maxAgeMs)
+        await rm(path, { force: true, recursive: info.isDirectory() })
+    }
+    catch {
+      continue
+    }
+  }
+}
+
+// Creates a log file nobody else can read and that must not exist yet, so a planted link is never followed; returns its descriptor, for writeSync.
+export function createLog(path: string): number {
+  return openSync(path, 'wx', 0o600)
+}

package/src/process.ts

@@ -14,12 +14,26 @@ export interface Ran {
   // The bytes of every chunk joined.
   output: Buffer
   text: string
+  // The command was ended because `timeoutMs` passed, its code then being the signal's.
+  timedOut: boolean
+  // More than `maxBytes` came, and the rest was left out of chunks, output and text.
+  truncated: boolean
 }
 
 export interface RunSettings {
   cwd?: string
   env?: Record<string, string | undefined>
   stdin?: 'inherit' | 'ignore'
+  // Ends the command and its children after this long.
+  timeoutMs?: number
+  // Ends the command and its children when aborted.
+  signal?: AbortSignal
+  // Bytes kept in the result; the pipes are still read to the end.
+  maxBytes?: number
+  // Called with each chunk as it arrives; throwing ends the command and rethrows once the pipes are drained.
+  onChunk?: (chunk: Chunk) => void
+  // Called once the command runs, with a handle that sends a signal to its whole process group, for `holdSignals().forward`.
+  onStart?: (child: { kill: (signal: NodeJS.Signals) => void }) => void
 }
 
 export interface HeldSignals {
@@ -31,16 +45,12 @@ export interface HeldSignals {
   release: () => void
 }
 
+const KILL_GRACE_MS = 2000
 const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
 // A scheme of two letters or more, so a Windows drive is read as a path.
 const SCHEME = /^[a-z][\w+.-]+:/i
 const OPENERS: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ['open'], win32: ['cmd', '/c', 'start', ''] }
 
-async function collect(stream: ReadableStream<Uint8Array>, name: Chunk['stream'], chunks: Chunk[]): Promise<void> {
-  for await (const data of stream)
-    chunks.push({ stream: name, data })
-}
-
 // The exit code a shell would report: the code, or 128 plus the signal.
 export function exitCodeOf(code: number | null, signal: NodeJS.Signals | number | null): number {
   if (code !== null)
@@ -106,15 +116,106 @@ export function openUrl(target: string, env: Record<string, string | undefined>
   }
 }
 
-// Runs a command with stdout and stderr captured; throws when it cannot be started.
-export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore' }: RunSettings = {}): Promise<Ran> {
+// Runs a command with stdout and stderr captured; throws when it cannot be started. With `timeoutMs`, `signal`, `onStart` or `onChunk` the child leads its own process group, and the whole group is ended (SIGTERM, then SIGKILL after a short grace) on the timeout, an abort or a throwing `onChunk`; the pipes are drained to their end either way.
+export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore', timeoutMs, signal, maxBytes = Infinity, onChunk, onStart }: RunSettings = {}): Promise<Ran> {
   const chunks: Chunk[] = []
-  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe' })
+  const grouped = timeoutMs !== undefined || signal !== undefined || onStart !== undefined || onChunk !== undefined
+  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe', ...(grouped ? { detached: true } : {}) })
+  const state = { kept: 0, truncated: false, timedOut: false, failure: undefined as unknown, done: false }
+  const timers: ReturnType<typeof setTimeout>[] = []
+
+  const killGroup = (killing: NodeJS.Signals) => {
+    if (state.done)
+      return
+
+    try {
+      if (grouped)
+        process.kill(-proc.pid, killing)
+      else
+        proc.kill(killing)
+    }
+    catch {
+      // The group is already gone.
+    }
+  }
+
+  const stop = () => {
+    killGroup('SIGTERM')
+    timers.push(setTimeout(killGroup, KILL_GRACE_MS, 'SIGKILL'))
+  }
+
+  const onAbort = () => stop()
+
+  if (timeoutMs !== undefined) {
+    timers.push(setTimeout(() => {
+      state.timedOut = true
+      stop()
+    }, timeoutMs))
+  }
+
+  if (signal?.aborted === true)
+    onAbort()
+  else
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+  onStart?.({ kill: killing => killGroup(killing) })
+
+  const drain = async (stream: ReadableStream<Uint8Array>, name: Chunk['stream']) => {
+    for await (const data of stream) {
+      if (state.failure !== undefined)
+        continue
 
-  await Promise.all([collect(proc.stdout, 'stdout', chunks), collect(proc.stderr, 'stderr', chunks)])
-  await proc.exited
+      try {
+        onChunk?.({ stream: name, data })
+      }
+      catch (error) {
+        state.failure = error
+        stop()
 
-  const output = Buffer.concat(chunks.map(({ data }) => data))
+        continue
+      }
 
-  return { code: exitCodeOf(proc.exitCode, proc.signalCode), chunks, output, text: output.toString() }
+      if (state.kept + data.length > maxBytes) {
+        state.truncated = true
+
+        continue
+      }
+
+      state.kept += data.length
+      chunks.push({ stream: name, data })
+    }
+  }
+
+  try {
+    await Promise.all([drain(proc.stdout, 'stdout'), drain(proc.stderr, 'stderr')])
+    await proc.exited
+  }
+  finally {
+    state.done = true
+
+    for (const timer of timers)
+      clearTimeout(timer)
+
+    signal?.removeEventListener('abort', onAbort)
+  }
+
+  if (state.failure !== undefined)
+    throw state.failure
+
+  const joined = () => Buffer.concat(chunks.map(({ data }) => data))
+  let output: Buffer | undefined
+  let text: string | undefined
+
+  return {
+    code: exitCodeOf(proc.exitCode, proc.signalCode),
+    chunks,
+    timedOut: state.timedOut,
+    truncated: state.truncated,
+    get output() {
+      return output ??= joined()
+    },
+    get text() {
+      return text ??= (output ??= joined()).toString()
+    },
+  }
 }

package/src/secrets.ts

@@ -0,0 +1,10 @@
+// Parts of a name that make it secret wherever they sit in it (`DB_PASSWORD`, `PGPASSWORD`, `clientSecret`).
+const SECRET_PART = /token|secret|passw|credential|private|dsn|apikey|accesskey|key$/i
+// Whole words of a name that make it secret (`DB_PASS`, `SMTP_PWD`, `encryptionKey`, `session_id`), so `compass`, `author` or `keyword` stay plain.
+const SECRET_WORDS = new Set(['key', 'pass', 'pwd', 'auth', 'salt', 'cookie', 'session', 'jwt', 'ssn', 'iban', 'card', 'cvv', 'otp'])
+const WORD_BREAKS = /[^a-zA-Z\d]+|(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+
+// True for the name of a variable, a column or a JSON key that holds a secret, by one definition shared by ev, redact and db.
+export function isSecretName(name: string): boolean {
+  return SECRET_PART.test(name) || name.split(WORD_BREAKS).some(word => SECRET_WORDS.has(word.toLowerCase()))
+}

package/src/sessions.ts

@@ -0,0 +1,107 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { Glob } from 'bun'
+
+// A running Claude Code session, as it registers itself in <config dir>/sessions/<pid>.json.
+export interface Session { name: string, pid: number, status: string, cwd: string }
+
+interface Entry { name?: string, pid?: number, procStart?: string, status?: string, cwd?: string }
+
+const SESSION_FILES = new Glob('*.json')
+const ACCOUNT_DIRS = new Glob('*/sessions')
+
+async function sessionDirs(): Promise<string[]> {
+  const home = homedir()
+  const dirs = new Set([join(home, '.claude', 'sessions')])
+
+  if (process.env.CLAUDE_CONFIG_DIR !== undefined)
+    dirs.add(join(process.env.CLAUDE_CONFIG_DIR, 'sessions'))
+
+  try {
+    for await (const dir of ACCOUNT_DIRS.scan({ cwd: join(home, '.claude-accounts'), onlyFiles: false, absolute: true }))
+      dirs.add(dir)
+  }
+  catch {
+    // No ~/.claude-accounts: the default config dir is the only one.
+  }
+
+  return [...dirs]
+}
+
+// The fields of /proc/<pid>/stat after the command name, which may itself hold spaces and parentheses.
+async function procStat(pid: number): Promise<string[] | undefined> {
+  try {
+    const stat = await Bun.file(`/proc/${pid}/stat`).text()
+
+    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')
+  }
+  catch {
+    return undefined
+  }
+}
+
+// Alive and the same process the session registered, not a later one given its pid; starttime is field 22, the 20th after the name.
+async function isAlive(pid: number, procStart: string | undefined): Promise<boolean> {
+  const stat = await procStat(pid)
+
+  if (stat === undefined)
+    return false
+
+  return procStart === undefined || stat[19] === procStart
+}
+
+export async function liveSessions(): Promise<Session[]> {
+  const sessions = new Map<number, Session>()
+
+  for (const dir of await sessionDirs()) {
+    let files: string[]
+
+    try {
+      files = await Array.fromAsync(SESSION_FILES.scan({ cwd: dir, absolute: true }))
+    }
+    catch {
+      continue
+    }
+
+    for (const file of files) {
+      let entry: Entry
+
+      try {
+        entry = await Bun.file(file).json() as Entry
+      }
+      catch {
+        continue
+      }
+
+      if (entry.name === undefined || entry.pid === undefined || sessions.has(entry.pid) || !await isAlive(entry.pid, entry.procStart))
+        continue
+
+      sessions.set(entry.pid, { name: entry.name, pid: entry.pid, status: entry.status ?? 'unknown', cwd: entry.cwd ?? '' })
+    }
+  }
+
+  return [...sessions.values()]
+}
+
+// The session this process runs under, found by walking up its parent pids.
+export async function currentSession(sessions: Session[]): Promise<Session | undefined> {
+  const byPid = new Map(sessions.map(session => [session.pid, session]))
+  let pid = process.ppid
+
+  for (let depth = 0; depth < 32 && pid > 1; depth++) {
+    const session = byPid.get(pid)
+
+    if (session !== undefined)
+      return session
+
+    const parent = Number((await procStat(pid))?.[1])
+
+    if (!Number.isInteger(parent))
+      return undefined
+
+    pid = parent
+  }
+
+  return undefined
+}