@kaynooo/cli-kit 0.20.0 → 0.21.0

package/README.md

@@ -24,7 +24,30 @@ process.exitCode = await runCli({
 
 ## Exit codes
 
-0 for success, help and version; 2 for a usage error (an unknown command, a bad option, a missing argument, what `parse` and `fail` throw by default); 1 for a command that ran and failed (`fail(message, 1)`, or any other error a command throws).
+Every bin answers by one table, stated in each command's `--help` under `Exits:` (the `exits` setting of `parse`, a list of `[code, meaning]`).
+
+| Code | Meaning |
+| --- | --- |
+| 0 | clean: it did what was asked, found nothing wrong; also `--help` and `--version` |
+| 1 | a finding (`audit`, `doctor`, `guard`), nothing found (`peek`, `hotspots`, `todo-scan`, `ports`, `pick`, `view`), or an operation that ran and failed (Forgejo, GitLab or the database refused, a step failed: `fail(message, 1)` and any other error a command throws) |
+| 2 | a usage error (an unknown command or option, a bad value, a missing argument: what `parse` and `fail` throw by default), or could not check (a timeout, an unreachable registry, no lockfile): never reported as clean |
+
+Exceptions, each stated in the command's own `Exits:`:
+
+- A bin running another command (`base`, `proof`, `out`, `slot`, `dc`, `dx`, `sf`, `gb`, `gc` on a signal) exits with that command's code: 126 when it cannot be run, 127 when it cannot be started, 128 plus the signal when interrupted.
+- `probe` exits 1 when the site could not be reached, that being its finding, and 0 when it answered, whatever it warns about.
+- `guard hook` never exits 2, which would block the tool call it vets.
+- `waitfor` and `ft watch`/`ft ci` exit 2 on a timeout, 1 on the failure they waited for.
+
+`tests/exits.test.ts` holds every bin to this: each command states its codes, only from the table, and answers `--help` with 0 and an unknown option with 2.
+
+## Flags that mean the same everywhere
+
+- `-n` is always a count: `--limit` (rows of a listing, with `--full` for all of them, from `limitOptions`), `--rows` (`db`, once `--limit`), `--lines` (`dlog`, `out` and `waitfor task`: lines of output kept), `--count` (`sub`, `dev uuid`) and `--slots` (`slot`). A listing cuts to its default and says `N more, rerun with --full`; `--json` is never cut on its own, only by an explicit `-n`.
+- `-t`/`--timeout` is how long to wait before giving up, a duration (`30s`, `5m`, `1h`). A bare number counts in the unit the help names: minutes for `ft ci`, `ft watch`, `ft release` and `gl ci`, seconds for `waitfor`, `slot` and `pkg bump`.
+- `-r`/`--repo` is the forge repository (`ft`, `gl`, `changelog`). Bins with no repository keep `-r` for their own noun: `--ref` (`base`, `proof`), `--regex` (`sub`), `--refs` (`peek`).
+- `--dry-run` shows what would change without changing it (`sub`, `ft release`, `pkg bump`, `changelog`; `changelog` keeps `--dry`).
+- A renamed flag keeps its old spelling through `aliases` on the option (`rows` answers `--limit`, `changelog` answers `--gitea` and `--dry`), left out of the help and of `__complete`.
 
 ## Look
 
@@ -32,6 +55,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 
 ## API
 
+- `version` is optional on `runCli`, `runMain` and `mainArgs`: it defaults to `packageVersion()`, the version of the nearest `package.json` above the entry file (links resolved, so `src/cli.ts` and the built `dist/cli.js` both find the package's own), which saves each bin its `import { version } from '../package.json'`.
 - `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`.
@@ -43,6 +67,7 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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.
 - `runCli` and `runMain` record each run in `$XDG_STATE_HOME/kaynooo-cli/usage.jsonl` (`~/.local/state/...`, 0600): the bin, its command, the flag names it saw (never a value or an argument), the exit code and the unknown option of a usage error. `KAYNOOO_CLI_NO_USAGE=1` stops it, `NODE_ENV=test` too, and `usage: false` on the `Cli` or `Main` opts a bin out (`guard`, run on every tool call). `readUsage` and `summarizeUsage` read it, `cli stats` shows it.
+- Shell completion: `cli completions fish --install` writes one file per bin, `source <(cli completions bash)` in `~/.bashrc` loads one function for all of them, and zsh reads that same script through `bashcompinit`. Each bin answers `<bin> __complete <words>... <word>`, below.
 - `<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.
@@ -55,6 +80,9 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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.
+- `exits: [[0, 'clean'], [1, 'a finding'], [2, 'a usage error']]` in `parse`'s settings prints an `Exits:` block after the options (a code may be a word, `['its own', 'the code of the command']`), and `KIT_HELP=json` carries it as `exits: [{code, meaning}]`.
+- `aliases: ['limit']` on an option keeps an old long name working: it is read as the option, bare or with `=`, up to a `--`, and shown in neither the help nor `__complete`.
+- `compose(args, { flags, cwd, env })` runs `docker compose <flags> <args>` and returns `{ code, stdout, stderr }` whatever the exit code (it throws only when docker cannot start), `captureOutput(argv, { cwd, env })` is the same for any command, `composeError(output)` words a failure as the last line of stderr or `exit <code>`, and `jsonLines<T>(text)` reads `compose ps --format json`, one object per line or the older array.
 - `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>` (`-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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.20.0",
+  "version": "0.21.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",
@@ -23,7 +23,8 @@
     "./progress": "./src/progress.ts",
     "./prompt": "./src/prompt.ts",
     "./shell": "./src/shell.ts",
-    "./test": "./src/test.ts"
+    "./test": "./src/test.ts",
+    "./fzf": "./src/fzf.ts"
   },
   "files": ["src"],
   "engines": {

package/src/advisory.ts

@@ -0,0 +1,22 @@
+export const SEVERITIES = ['low', 'moderate', 'high', 'critical'] as const
+
+export type Severity = (typeof SEVERITIES)[number]
+
+/** One advisory as `audit` and `pkg audit` both list it: `ghsa` is read from the url and `fixed` is the version its range ends below, both absent when none applies. */
+export interface AdvisoryRow {
+  id: number
+  ghsa?: string | undefined
+  url: string
+  title: string
+  severity: Severity
+  fixed?: string | undefined
+}
+
+export function severityRank(severity: Severity): number {
+  return SEVERITIES.indexOf(severity)
+}
+
+/** Whether `--ignore` skips an advisory, by its GHSA or numeric id. */
+export function isIgnored(advisory: Pick<AdvisoryRow, 'id' | 'ghsa'>, ignore: readonly string[]): boolean {
+  return ignore.includes(advisory.ghsa ?? '') || ignore.includes(String(advisory.id))
+}

package/src/args.ts

@@ -1,4 +1,5 @@
 import type { ParseArgsOptionDescriptor } from 'node:util'
+import type { ExitRow } from './help'
 import process from 'node:process'
 import { parseArgs } from 'node:util'
 import { upTo } from './format'
@@ -19,6 +20,8 @@ interface OptionExtras {
   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
+  // Other long names the option answers to, kept for the spelling it had before a rename; the help and `__complete` list only its own name.
+  aliases?: readonly string[]
 }
 
 export type Options = Record<string, ParseArgsOptionDescriptor & OptionExtras>
@@ -99,12 +102,14 @@ export interface ParseSettings<Names extends readonly string[] = string[]> {
   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'.
   replaces?: string
+  // What each exit code means, shown as an `Exits:` block in the help and listed by `cli list`: `[[0, 'clean'], [1, 'a finding'], [2, 'a usage error']]`.
+  exits?: ExitRow[]
 }
 
 export type Example = string | [line: string, note: string]
 
 // The parts of the settings the help and the description show.
-export interface Described { examples?: Example[] | undefined, replaces?: string | undefined }
+export interface Described { examples?: Example[] | undefined, replaces?: string | undefined, exits?: ExitRow[] | undefined }
 
 // The output flags every command takes, before its own help.
 export const OUTPUT_OPTIONS = {
@@ -149,7 +154,7 @@ export function parse<const T extends Options, const Names extends readonly stri
   let parsed
 
   try {
-    parsed = parseArgs({ args: joinDashValues(withBare(own, all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+    parsed = parseArgs({ args: joinDashValues(withBare(withAliases(own, all), all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
   }
   catch (error) {
     const message = parseError(error)
@@ -162,7 +167,7 @@ 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, listing, undefined, settings))
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings, listing)) : helpText(usage, listing, undefined, settings))
 
     throw new HelpShown()
   }
@@ -226,6 +231,24 @@ function listed(options: Options, allowNegative: boolean): Options {
   }))
 }
 
+// The arguments with an option typed under one of its `aliases` renamed to its own name, up to a `--`: `--limit 5` becomes `--rows 5`.
+function withAliases(args: string[], options: Options): string[] {
+  const named = new Map<string, string>(Object.entries(options).flatMap(([name, { aliases = [] }]) => aliases.map((alias): [string, string] => [`--${alias}`, `--${name}`])))
+
+  if (named.size === 0)
+    return args
+
+  const separator = args.indexOf('--')
+  const own = separator === -1 ? args : args.slice(0, separator)
+
+  return [...own.map((arg) => {
+    const at = arg.indexOf('=')
+    const current = named.get(at === -1 ? arg : arg.slice(0, at))
+
+    return current === undefined ? arg : `${current}${at === -1 ? '' : arg.slice(at)}`
+  }), ...separator === -1 ? [] : args.slice(separator)]
+}
+
 // 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]]))

package/src/ci.ts

@@ -21,6 +21,8 @@ export interface CiWait<T> {
   // How long queued work may sit while nothing moves.
   stalledMs: number
   pollMs?: number
+  // Leaves the live region and the retry warnings out, so only what the caller prints around the wait shows.
+  quiet?: boolean
   // 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.
@@ -43,13 +45,17 @@ 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 { tool, short, giveUpMs, noneMs, stalledMs, pollMs = POLL, quiet = false } = 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 region = wait.lines === undefined || quiet ? undefined : liveRegion(spinner => wait.lines?.(spinner, found, started) ?? [])
+  const retrying = (error: unknown) => {
+    if (!quiet)
+      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+  }
   const suffix = () => found === undefined ? '' : `: ${wait.links(found)}`
 
   // A failure to read the stall is retried on the next poll, and leaves the stall unknown.
@@ -61,7 +67,7 @@ export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
       if (error instanceof Exit || isPermanentFailure(error))
         throw error
 
-      console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+      retrying(error)
 
       return 'unknown'
     }
@@ -86,7 +92,7 @@ export async function waitForCi<T>(wait: CiWait<T>): Promise<T> {
         if (isPermanentFailure(error))
           fail(error instanceof Error ? error.message : String(error))
 
-        console.warn(`${tool}: ${error instanceof Error ? error.message : String(error)}, polling again`)
+        retrying(error)
 
         const latest = found === undefined ? undefined : await wait.settle(found)
 

package/src/cli.ts

@@ -1,5 +1,7 @@
 import type { Candidate, Example, Options } from './args'
 import type { Colors } from './style'
+import { readFileSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
 import { applyOutput, Completing, completion, description, exampleRows, Exit, HelpShown, optionRows, OUTPUT_OPTIONS, replacesRows, UsageError, usageLine, wantsHelpJson } from './args'
 import { paint, takesControlCodes } from './style'
@@ -28,7 +30,8 @@ export type Command = {
 
 export interface Cli {
   name: string
-  version: string
+  // The package's own by default, read from the nearest package.json above the entry file.
+  version?: string
   // One line after `<name> <version>: ` in the help.
   about: string
   // The commands, or a function giving them all lazily.
@@ -428,12 +431,30 @@ async function printCandidates(found: Promise<string[]>): Promise<number> {
   return 0
 }
 
+// The version of the nearest package.json above the entry file (symlinks resolved) that holds one, `0.0.0` when none does.
+export function packageVersion(entry = Bun.main): string {
+  for (let dir = dirname(realpathSync(entry)); ; dir = dirname(dir)) {
+    try {
+      const { version } = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: unknown }
+
+      if (typeof version === 'string')
+        return version
+    }
+    catch {}
+
+    if (dirname(dir) === dir)
+      return '0.0.0'
+  }
+}
+
 // Runs the command argv names and returns the exit code: 0 for help and version, 2 for an unknown command.
 export async function runCli(cli: Cli, argv = process.argv.slice(2)): Promise<number> {
+  const version = cli.version ?? packageVersion()
+
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)))
 
-  const code = await 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 })
+  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(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, redact: cli.redact })
 
   if (cli.usage !== false) {
     try {
@@ -470,7 +491,8 @@ function commandPath(scope: Pick<Level, 'commands' | 'aliases'>, argv: readonly
 
 export interface Main {
   name: string
-  version: string
+  // The package's own by default, read from the nearest package.json above the entry file.
+  version?: string
   run: (args: string[]) => Promise<number>
   redact?: (text: string) => string
   usage?: false
@@ -498,7 +520,7 @@ export async function runMain({ name, version, run, redact, usage }: Main, argv
     return printCandidates(leafCandidates(run, argv.slice(1)))
 
   if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
-    console.log(version)
+    console.log(version ?? packageVersion())
 
     return 0
   }
@@ -512,8 +534,12 @@ export async function runMain({ name, version, run, redact, usage }: Main, argv
     code = reportThrown(name, error, redact, wantsJson(argv))
   }
 
-  if (usage !== false)
-    recordUsage(usageEntry(name, undefined, argv, code))
+  if (usage !== false) {
+    try {
+      recordUsage(usageEntry(name, undefined, argv, code))
+    }
+    catch {}
+  }
 
   return code
 }

package/src/compose.ts

@@ -0,0 +1,43 @@
+export interface ComposeOptions {
+  // Compose's own options, given before the subcommand: `['-f', 'compose.yaml']`, `['-p', project]`, `['--project-directory', dir]`.
+  flags?: string[]
+  cwd?: string
+  // Variables set over the process's environment for compose.
+  env?: Record<string, string | undefined>
+}
+
+export interface CommandOutput {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+// Runs a command to its end with no stdin and returns both streams apart, whatever its exit code; it throws when the command cannot start.
+export async function captureOutput(argv: string[], { cwd, env }: Pick<ComposeOptions, 'cwd' | 'env'> = {}): Promise<CommandOutput> {
+  const run = Bun.spawn(argv, { ...cwd === undefined ? {} : { cwd }, env: { ...process.env, ...env }, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+  const [stdout, stderr, code] = await Promise.all([run.stdout.text(), run.stderr.text(), run.exited])
+
+  return { code, stdout, stderr }
+}
+
+// Runs `docker compose <flags> <args>` to its end: `captureOutput` with compose in front.
+export async function compose(args: string[], { flags = [], ...options }: ComposeOptions = {}): Promise<CommandOutput> {
+  return captureOutput(['docker', 'compose', ...flags, ...args], options)
+}
+
+// Why a command failed, in its own words: the last line it wrote to stderr, else `exit <code>`.
+export function composeError({ code, stderr }: CommandOutput): string {
+  const last = stderr.trim().split('\n').at(-1) ?? ''
+
+  return last === '' ? `exit ${code}` : last
+}
+
+// The objects of `docker compose ps --format json`, which prints one per line since Compose 2.21 and an array before.
+export function jsonLines<T>(text: string): T[] {
+  const trimmed = text.trim()
+
+  if (trimmed === '')
+    return []
+
+  return trimmed.startsWith('[') ? JSON.parse(trimmed) as T[] : trimmed.split('\n').map(line => JSON.parse(line) as T)
+}

package/src/fzf.ts

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+export interface Row {
+  hidden: string[]
+  cells: string[]
+}
+
+export interface FzfOptions {
+  prompt: string
+  header?: string
+  // Keys that pick the highlighted row too, telling which one was pressed.
+  expect?: string[]
+  // Called with the hidden fields as `{1}`, `{2}`...
+  preview?: string
+  // How many leading cells are searched, so a word of a description does not outrank the name it was typed for.
+  searched: number
+  // Whole height by default, for a list of a few candidates asked about under the command.
+  height?: string
+  bind?: string[]
+  // How many leading fields are hidden, taken from the first row by default, which a list that starts empty and reloads has none of.
+  hidden?: number
+  // The query comes back too, and an expected key pressed with no row matching still picks, with no hidden fields.
+  query?: boolean
+}
+
+export interface Picked {
+  key: string
+  hidden: string[]
+  query: string
+}
+
+// A row as term lists it with `--list` in place of the fzf window, in the pane's folder: what tmux_pick types back for Enter and for the picker's other keys.
+export interface Listed {
+  label: string
+  hint: string
+  // The words typed after the picker's name to find the same choice again; for a row asking for a text, the ones before it.
+  typed: string
+  // Set for a row asking for a text first, typed after its words: ctrl-n's new branch.
+  asks?: string
+  // The picker's arguments printing the row's preview, its `--show` as fzf calls it.
+  preview?: string[]
+  // ctrl-e leaves the picker's name and these words on the prompt rather than the command they run.
+  editsTyped?: boolean
+  actions?: ListedAction[]
+}
+
+export interface ListedAction {
+  label: string
+  // fzf's name for the key doing it there.
+  key: string
+  typed?: string
+  // The picker run with these arguments, then listed again: ctrl-r's fetch.
+  reload?: string[]
+}
+
+export interface Run {
+  id: string
+  args: string[]
+}
+
+// A word of the command: fixed, an argument given by the user, or the name of one to prompt for; the last two are what a run is remembered with.
+export type Arg = string | { given: string } | { ask: string }
+
+const REMEMBERED = 20
+
+// Every cell but the last padded to its column, one space short of the two between columns since a tab renders as one, see `--tabstop`.
+// Widths are measured without the color codes.
+export function table(rows: Row[]): string[] {
+  const widths = rows[0]?.cells.map((_, index) => Math.max(...rows.map(row => Bun.stringWidth(row.cells[index]!)))) ?? []
+
+  return rows.map(row => [
+    ...row.hidden,
+    ...row.cells.map((cell, index) => (index === row.cells.length - 1 ? cell.trimEnd() : `${cell}${' '.repeat(widths[index]! + 1 - Bun.stringWidth(cell))}`)),
+  ].join('\t'))
+}
+
+export function fzf(rows: Row[], options: FzfOptions): Picked | undefined {
+  const hidden = options.hidden ?? rows[0]?.hidden.length ?? 0
+  const proc = Bun.spawnSync([
+    'fzf',
+    '--prompt',
+    options.prompt,
+    ...options.header === undefined ? [] : ['--header', options.header],
+    ...(options.expect ?? []).length > 0 ? ['--expect', (options.expect ?? []).join(',')] : [],
+    '--ansi',
+    '--reverse',
+    '--height',
+    options.height ?? '100%',
+    '--delimiter',
+    '\t',
+    '--with-nth',
+    `${hidden + 1}..`,
+    '--nth',
+    `1..${options.searched}`,
+    '--tabstop',
+    '1',
+    // The shortest word holding the match wins a tie, `install` before `install-hooks`, where the default length would count the description too.
+    '--tiebreak',
+    'chunk,index',
+    ...options.preview === undefined ? [] : ['--preview', options.preview, '--preview-window', 'down,40%'],
+    ...(options.bind ?? []).flatMap(bind => ['--bind', bind]),
+    ...options.query === true ? ['--print-query'] : [],
+  ], {
+    stdin: new TextEncoder().encode(table(rows).join('\n')),
+    stdout: 'pipe',
+    stderr: 'inherit',
+  })
+
+  return picked(proc.stdout.toString(), hidden, options)
+}
+
+// What fzf printed: the query when asked for, the key when keys are expected, then the line picked.
+export function picked(output: string, hidden: number, options: Pick<FzfOptions, 'expect' | 'query'>): Picked | undefined {
+  const lines = output.split('\n')
+  const query = options.query === true ? lines.shift()! : ''
+  const [key, line] = (options.expect ?? []).length > 0 ? [lines[0]!, lines[1]] : ['', lines[0]]
+
+  if (line !== undefined && line !== '')
+    return { key, hidden: line.split('\t').slice(0, hidden), query }
+
+  return options.query === true && key !== '' ? { key, hidden: [], query } : undefined
+}
+
+// A few candidates, as tall as they need under the command with the preview below them.
+export function heightFor(count: number): string {
+  return String(Math.max(15, Math.ceil((count + 4) / 0.6)))
+}
+
+function historyFile(name: string): string {
+  return join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), name, 'history.json')
+}
+
+// Keyed by folder, a broken or missing file reading as nothing run yet.
+function history(name: string): Record<string, Run[]> {
+  try {
+    const file = historyFile(name)
+
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf-8')) as Record<string, Run[]> : {}
+  }
+  catch {
+    return {}
+  }
+}
+
+export function runs(name: string): Run[] {
+  return history(name)[process.cwd()] ?? []
+}
+
+export function record(name: string, run: Run): void {
+  const all = history(name)
+  const file = historyFile(name)
+
+  all[process.cwd()] = [run, ...(all[process.cwd()] ?? []).filter(earlier => earlier.id !== run.id)].slice(0, REMEMBERED)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(all))
+}
+
+// The ones run last come first, most recent at the top, the rest keeping their order.
+export function byRecency<T>(items: T[], previous: Run[], idOf: (item: T) => string): T[] {
+  const rank = new Map(previous.map((run, index) => [run.id, index]))
+  const recent = items.filter(item => rank.has(idOf(item))).sort((a, b) => rank.get(idOf(a))! - rank.get(idOf(b))!)
+
+  return [...recent, ...items.filter(item => !rank.has(idOf(item)))]
+}
+
+function word(arg: Arg): string {
+  if (typeof arg === 'string')
+    return `=${arg}`
+
+  return 'given' in arg ? `+${arg.given}` : `?${arg.ask}`
+}
+
+// The lines `__pick_run` and tmux_pick read: `run`, or `edit` to leave the command on the prompt; the words typed after the picker's name to find the same choice again; the id the run is called back with once the prompts are answered, or nothing; then one line per word of the command, `=fixed`, `+given` or `?name` to prompt for.
+export function emit(mode: 'run' | 'edit', typed: string, recorded: string, command: Arg[]): void {
+  const words = command.map(word)
+
+  console.log([mode, typed, recorded, ...words].join('\n'))
+}
+
+// What `--list` prints, term reading it back.
+export function list(rows: Listed[]): void {
+  console.log(JSON.stringify(rows))
+}

package/src/help.ts

@@ -12,8 +12,21 @@ export function usageLine(usage: string, colors = paint(process.stdout)): string
   return `${colors.bold('Usage:')} ${usage.replace(USAGE_PREFIX, '').replaceAll(OPTIONAL, part => colors.dim(part))}`
 }
 
-export function helpText(usage: string, options: Options, colors = paint(process.stdout), { examples = [], replaces }: Described = {}): string {
-  return [usageLine(usage, colors), ...replacesRows(replaces, colors), '', colors.bold('Options:'), ...optionRows(options, colors), ...exampleRows(examples, colors)].join('\n')
+export function helpText(usage: string, options: Options, colors = paint(process.stdout), { examples = [], replaces, exits = [] }: Described = {}): string {
+  return [usageLine(usage, colors), ...replacesRows(replaces, colors), '', colors.bold('Options:'), ...optionRows(options, colors), ...exitRows(exits, colors), ...exampleRows(examples, colors)].join('\n')
+}
+
+// An exit code and what it means.
+export type ExitRow = [code: number | string, meaning: string]
+
+// An `Exits:` block, after a blank line, a line per code with the codes aligned; nothing without one.
+export function exitRows(exits: ExitRow[], colors = paint(process.stdout)): string[] {
+  if (exits.length === 0)
+    return []
+
+  const width = Math.max(...exits.map(([code]) => String(code).length))
+
+  return ['', colors.bold('Exits:'), ...exits.map(([code, meaning]) => `  ${colors.cyan(String(code).padEnd(width))}  ${meaning}`)]
 }
 
 // An `Instead of:` line, after a blank line; nothing without one.
@@ -27,6 +40,9 @@ export interface Description {
   summary: string
   replaces?: string
   examples: { line: string, note?: string }[]
+  exits?: { code: number | string, meaning: string }[]
+  // The flags of a command with no subcommands, for a test comparing them with what a README documents.
+  options?: { name: string, short?: string, description?: string }[]
 }
 
 export function wantsHelpJson(env: Record<string, string | undefined> = process.env): boolean {
@@ -34,7 +50,7 @@ export function wantsHelpJson(env: Record<string, string | undefined> = process.
 }
 
 // The synopsis and the summary a usage's first line splits into at its first `: `, else the first line after the synopses as the summary, with the examples spelled out.
-export function description(usage: string, { examples = [], replaces }: Described = {}): Description {
+export function description(usage: string, { examples = [], replaces, exits }: Described = {}, options?: Options): Description {
   const lines = usage.replace(USAGE_PREFIX, '').split('\n')
   const first = lines[0]!
   const colon = first.indexOf(': ')
@@ -46,6 +62,8 @@ export function description(usage: string, { examples = [], replaces }: Describe
     summary: colon === -1 ? fallback : first.slice(colon + 2),
     ...replaces === undefined ? {} : { replaces },
     examples: examples.map(example => typeof example === 'string' ? { line: example } : { line: example[0], note: example[1] }),
+    ...exits === undefined ? {} : { exits: exits.map(([code, meaning]) => ({ code, meaning })) },
+    ...options === undefined ? {} : { options: Object.entries(options).map(([name, { short, description }]) => ({ name, ...short === undefined ? {} : { short }, ...description === undefined ? {} : { description } })) },
   }
 }
 

package/src/index.ts

@@ -1,7 +1,9 @@
+export * from './advisory'
 export * from './args'
 export * from './chart'
 export * from './ci'
 export * from './cli'
+export * from './compose'
 export * from './config'
 export * from './format'
 export * from './git'
@@ -10,7 +12,9 @@ export * from './logs'
 export * from './process'
 export * from './secrets'
 export * from './sessions'
+export * from './size'
 export * from './style'
 export * from './text'
 export * from './tool'
 export * from './usage'
+export * from './user-config'

package/src/shell.ts

@@ -1,6 +1,6 @@
 // `text` is the piece as written, `command` the same less its heredoc bodies and comments, which are data and never commands; `separator` is what ends it (`|`, `&&`, `;`, a newline...), empty for the last; `expanded` holds the bodies of its unquoted heredocs, where the shell still runs `$(...)`, and `heredocs` those of all its heredocs.
 export interface Piece { text: string, start: number, end: number, command: string, separator: string, expanded: string, heredocs: string[] }
-export interface Invocation { program: string, args: string[], assignments: string[], isWrapped: boolean }
+export interface Invocation { program: string, args: string[], assignments: string[], isWrapped: boolean, strings: string[] }
 
 const SEPARATORS = new Set(['\n', ';', '|'])
 const PLAIN_BREAKERS = new Set(['<', '>', '(', ')', '&', '|'])
@@ -30,18 +30,30 @@ const OCTAL = /^[0-7]{1,3}/
 const KEYWORDS = new Set(['then', 'do', 'else', 'if', 'elif', 'while', 'until', '!', '{', '}'])
 const MAX_DEPTH = 8
 const MAX_BRACES = 256
+
 // Programs reading a command string with `-c`.
-const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ash', 'ksh'])
-const COMMAND_STRING_PROGRAMS = new Set([...SHELLS, 'su', 'runuser'])
+export const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ash', 'ksh', 'fish', 'csh', 'tcsh', 'nu', 'xonsh', 'elvish', 'pwsh', 'powershell'])
+// Programs that take their command string past other operands, so every word is scanned for the option.
+const SCANNED_PROGRAMS = new Set(['su', 'runuser', 'flock'])
+const COMMAND_STRING_PROGRAMS = new Set([...SHELLS, ...SCANNED_PROGRAMS])
+// PowerShell's `-Command`, which it accepts abbreviated to any prefix.
+const POWERSHELL_COMMAND = /^-c(?:o(?:m(?:m(?:a(?:nd?)?)?)?)?)?$/i
+const POWERSHELL = new Set(['pwsh', 'powershell'])
+const FUNCTION_DEFINITION = /^[\w.:-]+\(\)\{?$/
+const FUNCTION_NAME = /^[\w.:-]+$/
 const SHELL_VALUE_OPTIONS = new Set(['-o', '-O', '--rcfile', '--init-file'])
+const FISH_VALUE_OPTIONS = new Set(['-C', '--init-command'])
+// A `let` builtin, whose `<<` is a shift.
+const LET_PIECE = /^\s*let\s/
 const PRINTERS = new Set(['echo', 'printf'])
 const FIND_EXEC = new Set(['-exec', '-execdir', '-ok', '-okdir'])
 
 // Programs that run the command following them, which is the one that counts, with the options taking a value and the operands before that command.
-interface WrapperSpec { short: string, long: readonly string[], operands: number }
+interface WrapperSpec { short: string, long: readonly string[], operands: number, runsString: boolean }
 
-function wrapper(short = '', long: readonly string[] = [], operands = 0): WrapperSpec {
-  return { short, long, operands }
+// `runsString` for a wrapper that hands its command to a shell, so a quoted `'git stash'` is a command line.
+function wrapper(short = '', long: readonly string[] = [], operands = 0, runsString = false): WrapperSpec {
+  return { short, long, operands, runsString }
 }
 
 const WRAPPERS = new Map<string, WrapperSpec>([
@@ -60,6 +72,11 @@ const WRAPPERS = new Map<string, WrapperSpec>([
   ['ionice', wrapper('cnpPu', ['--class', '--classdata', '--pid', '--pgid', '--uid'])],
   ['stdbuf', wrapper('ioe', ['--input', '--output', '--error'])],
   ['chroot', wrapper('', ['--userspec', '--groups'], 1)],
+  ['watch', wrapper('n', ['--interval'], 0, true)],
+  ['flock', wrapper('wE', ['--timeout', '--conflict-exit-code'], 1)],
+  ['parallel', wrapper('jnNSaIPlLdTsC', ['--jobs', '--max-args', '--max-replace-args', '--sshlogin', '--arg-file', '--delimiter', '--colsep'], 0, true)],
+  ['unbuffer', wrapper()],
+  ['systemd-run', wrapper('puEMH', ['--property', '--unit', '--description', '--slice', '--setenv', '--machine', '--host', '--uid', '--gid', '--working-directory', '--nice', '--service-type'])],
   ['xargs', wrapper('IndsEaPL', ['--max-args', '--max-procs', '--max-chars', '--delimiter', '--arg-file', '--eof', '--max-lines', '--process-slot-var'])],
 ])
 
@@ -162,6 +179,15 @@ export function splitCommand(command: string): Piece[] {
       continue
     }
 
+    // The legacy arithmetic `$[...]` is read whole, like `$((...))`.
+    if (char === '$' && command[i + 1] === '[') {
+      const close = command.indexOf(']', i)
+
+      i = close === -1 ? command.length : close
+
+      continue
+    }
+
     // A backquoted body is read whole, as its own separators split nothing of the command around it.
     if (char === '`') {
       i = closingBackquote(command, i)
@@ -169,6 +195,13 @@ export function splitCommand(command: string): Piece[] {
       continue
     }
 
+    // Arithmetic is read whole: its `<<` shifts, it opens no heredoc.
+    if (command.startsWith('((', char === '$' ? i + 1 : i) && (char === '$' || startsComment(command, i))) {
+      i = closingParen(command, char === '$' ? i + 1 : i)
+
+      continue
+    }
+
     if (char === '#' && startsComment(command, i)) {
       const newline = command.indexOf('\n', i)
       const end = newline === -1 ? command.length : newline
@@ -179,7 +212,7 @@ export function splitCommand(command: string): Piece[] {
       continue
     }
 
-    const heredoc = char === '<' && command[i + 1] === '<' && command[i + 2] !== '<' ? HEREDOC.exec(command.slice(i)) : null
+    const heredoc = char === '<' && command[i + 1] === '<' && command[i + 2] !== '<' && !LET_PIECE.test(command.slice(start, i)) ? HEREDOC.exec(command.slice(i)) : null
 
     if (heredoc) {
       heredocs.push({ word: heredoc[2] ?? heredoc[3] ?? heredoc[4] ?? '', stripsTabs: heredoc[1] === '-', isQuoted: heredoc[4] === undefined })
@@ -545,13 +578,29 @@ function skipOptions(tokens: string[], spec: WrapperSpec): void {
 export function parseCommand(text: string): Invocation {
   const tokens = tokenize(text)
   const assignments: string[] = []
+  const strings: string[] = []
   let isWrapped = false
 
   for (;;) {
     const first = tokens[0] ?? ''
     const spec = WRAPPERS.get(first.split('/').pop() ?? '')
 
-    if (OPENERS.test(first)) {
+    if (first === 'function' && tokens.length > 1) {
+      isWrapped = true
+      tokens.splice(0, 2)
+
+      if (tokens[0] === '()')
+        tokens.shift()
+    }
+    else if (FUNCTION_DEFINITION.test(first)) {
+      isWrapped = true
+      tokens.shift()
+    }
+    else if (tokens[1] === '()' && FUNCTION_NAME.test(first)) {
+      isWrapped = true
+      tokens.splice(0, 2)
+    }
+    else if (OPENERS.test(first)) {
       isWrapped = true
       const rest = first.replace(OPENERS, '')
 
@@ -580,6 +629,9 @@ export function parseCommand(text: string): Invocation {
       isWrapped = true
       tokens.shift()
       skipOptions(tokens, spec)
+
+      if (spec.runsString && WHITESPACE.test(tokens[0] ?? ''))
+        strings.push(tokens[0] ?? '')
     }
     else {
       break
@@ -596,7 +648,7 @@ export function parseCommand(text: string): Invocation {
 
   const [program = '', ...args] = tokens
 
-  return { program: program.split('/').pop() ?? '', args, assignments, isWrapped }
+  return { program: program.split('/').pop() ?? '', args, assignments, isWrapped, strings }
 }
 
 // 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.
@@ -618,7 +670,8 @@ function commandStrings(tokens: readonly string[]): string[] {
     if (!COMMAND_STRING_PROGRAMS.has(name))
       continue
 
-    const isUser = name === 'su' || name === 'runuser'
+    const isScanned = SCANNED_PROGRAMS.has(name)
+    const isPowershell = POWERSHELL.has(name)
     let isValue = false
 
     for (let j = i + 1; j < tokens.length; j++) {
@@ -630,25 +683,27 @@ function commandStrings(tokens: readonly string[]): string[] {
         continue
       }
 
-      if (SHELL_VALUE_OPTIONS.has(option)) {
+      if (SHELL_VALUE_OPTIONS.has(option) || (name === 'fish' && FISH_VALUE_OPTIONS.has(option))) {
         isValue = true
 
         continue
       }
 
-      if (option.startsWith('--command=')) {
-        found.push(option.slice('--command='.length))
+      if (option.startsWith('--command=') || option.startsWith('--commands=')) {
+        found.push(option.slice(option.indexOf('=') + 1))
 
         break
       }
 
-      if (option === '--command' || (!option.startsWith('--') && option.startsWith('-') && option.slice(1).includes('c'))) {
-        found.push(tokens[j + 1] ?? '')
+      const isCommandOption = isPowershell ? POWERSHELL_COMMAND.test(option) : !option.startsWith('--') && option.startsWith('-') && option.slice(1).includes('c')
+
+      if (option === '--command' || option === '--commands' || isCommandOption) {
+        found.push(isPowershell ? tokens.slice(j + 1).join(' ') : (tokens[j + 1] ?? ''))
 
         break
       }
 
-      if (!option.startsWith('-') && !isUser)
+      if (!option.startsWith('-') && !isScanned)
         break
     }
   }
@@ -695,8 +750,8 @@ function findExecs(args: readonly string[]): string[] {
 // The commands a piece makes a shell run besides its own: `sh -c` strings, `eval`, `find -exec`, and what is fed to a shell reading its input, heredocs, here-strings and an `echo` piped in.
 function nestedCommands(piece: Piece, previous: Piece | undefined): string[] {
   const tokens = tokenize(piece.command)
-  const { program, args } = parseCommand(piece.command)
-  const found = commandStrings(tokens)
+  const { program, args, strings } = parseCommand(piece.command)
+  const found = [...commandStrings(tokens), ...strings]
 
   if (program === 'eval')
     found.push(args.join(' '))

package/src/size.ts

@@ -0,0 +1,14 @@
+const SIZE = /^(\d+(?:\.\d+)?)\s*([kmgt]?)i?b?$/i
+const POWERS: Record<string, number> = { '': 0, 'k': 1, 'm': 2, 'g': 3, 't': 4 }
+
+// A size such as `500M`, `1.5G` or `800kb` in bytes, counting in powers of 1024; a bare number counts `bareUnit` bytes (1 for bytes, 1024 ** 2 for megabytes). Undefined when it is none.
+export function parseSize(text: string, bareUnit = 1): number | undefined {
+  const match = SIZE.exec(text.trim())
+
+  if (match === null)
+    return undefined
+
+  const suffix = match[2]!.toLowerCase()
+
+  return Math.round(Number(match[1]) * (suffix === '' ? bareUnit : 1024 ** POWERS[suffix]!))
+}

package/src/tool.ts

@@ -61,11 +61,14 @@ export async function runTool(label: string, argv: string[], { timeoutMs, cwd, o
   if (ran.timedOut)
     throw new Error(`${label}: no answer in ${formatDuration(timeoutMs ?? 0)}`)
 
-  const decoder = new TextDecoder()
+  const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() }
   const streams = { stdout: '', stderr: '' }
 
   for (const { stream, data } of ran.chunks)
-    streams[stream] += decoder.decode(data, { stream: true })
+    streams[stream] += decoders[stream].decode(data, { stream: true })
+
+  streams.stdout += decoders.stdout.decode()
+  streams.stderr += decoders.stderr.decode()
 
   return { code: ran.code, ...streams }
 }

package/src/user-config.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+export interface UserConfigLocation {
+  // The home folder; `$XDG_CONFIG_HOME` is then ignored unless `xdg` is given too.
+  home?: string | undefined
+  // The config base folder, `$XDG_CONFIG_HOME` or `<home>/.config` by default.
+  xdg?: string | undefined
+}
+
+export function configBase(where: UserConfigLocation = {}): string {
+  const xdg = where.xdg ?? (where.home === undefined ? process.env.XDG_CONFIG_HOME : undefined)
+
+  return xdg !== undefined && xdg !== '' ? xdg : join(where.home ?? homedir(), '.config')
+}
+
+// The one config file of a bin, `~/.config/kaynooo-cli/<bin>.json`: where it is written.
+export function userConfigPath(bin: string, where: UserConfigLocation = {}): string {
+  return join(configBase(where), 'kaynooo-cli', `${bin}.json`)
+}
+
+// Where to read a bin's config: the new file, else the first of `legacy` (paths under the config base, such as `['ft', 'config.json']`) that exists, else the new path. A legacy file is never moved or deleted.
+export function userConfigReadPath(bin: string, legacy: string[][] = [], where: UserConfigLocation = {}): string {
+  const current = userConfigPath(bin, where)
+
+  if (existsSync(current))
+    return current
+
+  const base = configBase(where)
+
+  return legacy.map(parts => join(base, ...parts)).find(path => existsSync(path)) ?? current
+}