@kaynooo/cli-kit 0.0.0-stage → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaynooo <kaynooo@kevyn.fr>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @kaynooo/cli-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What every @kaynooo CLI shares, so each one parses, helps and fails the same way.
+
+```sh
+bun add @kaynooo/cli-kit
+```
+
+It ships its TypeScript source and runs on Bun only (>= 1.4.3). The agent-tools CLIs take it as a `workspace:*` dev dependency and bundle it at build; a CLI elsewhere takes it from the registry as a dependency.
+
+```ts
+import { parse, runCli } from '@kaynooo/cli-kit'
+
+process.exitCode = await runCli({
+  name: 'tool',
+  version: '1.0.0',
+  about: 'does things',
+  commands: {
+    // A command imports its module when it runs, so `tool --help` loads none of them.
+    build: { summary: 'build the project', run: async args => (await import('./commands/build')).run(args) },
+  },
+})
+```
+
+## 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).
+
+## Look
+
+On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, command and flag names in cyan and descriptions dimmed; an error reads as a red `error`, the dimmed `<cli> <command>:` and the message, with a yellow `hint` under it. Piped, in CI or under `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb`, the same text prints with plain words (`error: demo greet: give a name`, `  hint: run demo greet --help for its options`), so logs and what agents read stay greppable. `FORCE_COLOR` forces colours as `@kaynooo/utils` reads it.
+
+## 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.
+- `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. `{ 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`.
+- `runCli` also takes `defaultCommand`, the command that gets the arguments when the first one names no command (`db "select 1"` runs `db query "select 1"`), its options listed in `<cli> --help` under the commands, and a command may be a group, `{ summary, commands, aliases? }`, dispatched with its own help and typo hints (`ft plan add`).
+- `<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.
+- `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).
+- `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.
+- `jsonOption(holds?)` is the `--json` flag, worded `print JSON` or `print JSON: <holds>` alike in every CLI, and `printJson(value)` prints the value indented on stdout.
+- `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.
+- `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:
+  - `select(question, choices, { initial })` picks one `{ value, label, hint }`: typing filters the choices (every word typed in the label or hint, case ignored, Backspace editing), the arrows move and Enter picks.
+  - `checklist(question, choices, { initial, toggle })` checks several the same way, Space toggling the choice under the cursor; `toggle(checked, value)` returns what is checked after it, for choices that pull others along, and flips the one choice by default.
+  - `confirm(question, { default })` answers y or n, Enter taking the default; `input(question, { default, mask, validate })` takes a line, `mask` drawing it as `*`, `validate(value)` returning a message shown under it until the answer passes.
+  - Each answers `undefined` once Escape or Ctrl+C cancels and leaves `✓ <question> <answer>` or `✗ <question> cancelled`; a list longer than the terminal (10 rows at most) scrolls with the cursor, a dimmed `… n more` above and below.
+  - Off a terminal, a prompt fails at once with exit 2, `cannot ask "<question>" off a terminal`, with `hint` under it when given (`{ hint: 'pass --yes' }`); none reads a piped line. Each takes a `terminal: { stdin, stderr }`, the process's by default, for a test to drive.
+- `@kaynooo/cli-kit/progress` draws `progressLine(stream?, env?)` on stderr, one line redrawn in place while a task runs (`⠹ prerendering ████████░░░░░░░░░░░░ 8/20 routes 4.2s`, the bar cyan on a dimmed track), fed `update({ step, done?, total?, unit? })` and ended with `stop()`, `done(text)` leaving `✓ <text> <time>` or `failed(text)` leaving `✗ <text>`. It draws only where `takesControlCodes`; elsewhere `update` and `stop` do nothing and `done` and `failed` print their plain line. Anything printed meanwhile clears it first, and an interrupt clears it before the process ends.
+- `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.
+- `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,6 +1,38 @@
 {
   "name": "@kaynooo/cli-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.8.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 <kaynooo@kevyn.fr>",
+  "license": "MIT",
+  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "directory": "packages/kit"
+  },
+  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "keywords": [
+    "args",
+    "bun",
+    "cli",
+    "completion"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./progress": "./src/progress.ts",
+    "./prompt": "./src/prompt.ts",
+    "./shell": "./src/shell.ts",
+    "./test": "./src/test.ts"
+  },
+  "files": ["src"],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+  },
+  "dependencies": {
+    "@kaynooo/utils": "^2.31.0"
+  }
+}

package/src/args.ts

@@ -0,0 +1,234 @@
+import type { ParseArgsOptionDescriptor } from 'node:util'
+import process from 'node:process'
+import { parseArgs } from 'node:util'
+import { upTo } from './format'
+import { paint } from './style'
+
+export type Options = Record<string, ParseArgsOptionDescriptor & { description: string }>
+
+// The `--json` flag every CLI words alike: `print JSON`, then what it holds when given.
+export function jsonOption(holds?: string) {
+  return { type: 'boolean', description: holds === undefined ? 'print JSON' : `print JSON: ${holds}` } as const
+}
+
+// Thrown to end a command with this exit code and message, which runCli prints as `error: <cli> <command>: <message>`, the hint on a line of its own.
+export class Exit extends Error {
+  constructor(message: string, readonly code: number, readonly hint?: string) {
+    super(message)
+  }
+}
+
+export function fail(message: string, code = 2, hint?: string): never {
+  throw new Exit(message, code, hint)
+}
+
+// An Exit for arguments the command cannot take, which runCli points at the command's --help.
+export class UsageError extends Exit {
+  constructor(message: string) {
+    super(message, 2)
+  }
+}
+
+export function badUsage(message: string): never {
+  throw new UsageError(message)
+}
+
+// Thrown by parse once it has printed --help, so the command stops there; runCli and runMain end on it with exit 0, printing nothing more.
+export class HelpShown extends Exit {
+  constructor() {
+    super('help shown', 0)
+  }
+}
+
+// Thrown by parse while a bin answers `__complete`, so the command reached hands over its options before doing anything else.
+export class Completing {
+  constructor(readonly options: Options) {}
+}
+
+export const completion = { active: false }
+
+// Optional parts of a usage line, `[options]` or `[tag]`, dimmed in the help.
+const OPTIONAL = /\[[^\]]+\]/g
+const USAGE_PREFIX = /^usage:\s*/i
+
+// `Usage: <usage>`, the usage given with or without its own `usage:`, optional parts dimmed.
+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: Example[] = []): string {
+  return [usageLine(usage, colors), '', colors.bold('Options:'), ...optionRows(options, colors), ...exampleRows(examples, colors)].join('\n')
+}
+
+// An `Examples:` section, after a blank line, with a line per example; nothing without one.
+export function exampleRows(examples: Example[], colors = paint(process.stdout)): string[] {
+  if (examples.length === 0)
+    return []
+
+  return ['', colors.bold('Examples:'), ...examples.map(example => typeof example === 'string' ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)]
+}
+
+// A line per option, `-n, --times <value>  how many`, aligned on the visible text.
+export function optionRows(options: Options, colors = paint(process.stdout)): string[] {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? '    ' : `${colors.cyan(`-${option.short}`)}, `
+    const value = option.type === 'string' ? ` ${colors.dim('<value>')}` : ''
+
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === 'string' ? ' <value>'.length : 0), description: option.description }
+  })
+  const width = Math.max(0, ...rows.map(row => row.width))
+
+  return rows.map(row => `  ${row.flag}${' '.repeat(width - row.width)}  ${colors.dim(row.description)}`)
+}
+
+// The positionals typed by their names: `<key>` or `KEY` a string, `[file]` an optional one, a name ending in `...` the rest.
+type Slots<Names extends readonly string[]> = Names extends readonly [infer First extends string, ...infer Others extends readonly string[]]
+  ? First extends `${string}...` | `${string}...]` ? string[] : First extends `[${string}` ? [string?, ...Slots<Others>] : [string, ...Slots<Others>]
+  : Names extends readonly [] ? [] : string[]
+
+export interface ParseSettings<Names extends readonly string[] = string[]> {
+  // Stops at the first `--` and hands what follows back untouched as `rest`, for a command that runs another (`out -n 200 -- <cmd>`).
+  rest?: boolean
+  // Takes `--no-<flag>` as `false` for a boolean flag, as parseArgs' own `allowNegative` does.
+  allowNegative?: boolean
+  // The positionals the command takes, by name as its usage writes them: `<key>` or `KEY` required, `[file]` optional, a last one ending in `...` taking any more. One missing or one too many is a usage error, and the positionals come back typed by these names.
+  positionals?: Names
+  // Command lines shown under `Examples:` in the help, each with an optional dimmed note: `['ft ci HEAD~1', 'wait for the commit before the last']`.
+  examples?: Example[]
+}
+
+export type Example = string | [line: string, note: string]
+
+// The output flags every command takes, before its own help.
+export const OUTPUT_OPTIONS = {
+  color: { type: 'string', description: 'auto (on a terminal alone), always or never' },
+  plain: { type: 'boolean', description: 'plain text, no colour or spinner: --color never' },
+} as const satisfies Options
+
+// Applies --color or --plain to the environment, where the kit's colours and redrawn lines read it and so do the processes a command starts; `auto` leaves it as it is.
+export function applyOutput(color: string | undefined, plain: boolean | undefined, env: Record<string, string | undefined> = process.env): void {
+  const when = plain === true ? 'never' : color ?? 'auto'
+
+  if (when === 'auto')
+    return
+
+  if (when !== 'always' && when !== 'never')
+    badUsage(`--color takes auto, always or never, not ${when}`)
+
+  // FORCE_COLOR wins over NO_COLOR for the colours, so each choice drops the other.
+  if (when === 'always') {
+    env.FORCE_COLOR = '1'
+    delete env.NO_COLOR
+  }
+  else {
+    env.NO_COLOR = '1'
+    delete env.FORCE_COLOR
+  }
+}
+
+// Parses a command's arguments; on --help, prints its help and throws HelpShown, which ends the command with exit 0.
+export function parse<const T extends Options, const Names extends readonly string[] = string[]>(args: string[], usage: string, options: T, settings: ParseSettings<Names> = {}) {
+  // A command's own --color or --plain is its own to read.
+  const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options))) as Omit<typeof OUTPUT_OPTIONS, keyof T>
+  const all = { ...options, ...output, help: { type: 'boolean', short: 'h', description: 'show this help' } } as const
+
+  if (completion.active)
+    throw new Completing(all)
+
+  const separator = settings.rest === true ? args.indexOf('--') : -1
+  const own = separator === -1 ? args : args.slice(0, separator)
+  const rest = separator === -1 ? undefined : args.slice(separator + 1)
+
+  let parsed
+
+  try {
+    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true })
+  }
+  catch (error) {
+    badUsage(parseError(error))
+  }
+
+  const values = parsed.values as { help?: boolean, color?: unknown, plain?: unknown }
+
+  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(helpText(usage, all, undefined, settings.examples))
+
+    throw new HelpShown()
+  }
+
+  if (settings.positionals !== undefined)
+    checkPositionals(parsed.positionals, settings.positionals)
+
+  return { ...parsed, positionals: parsed.positionals as Slots<Names>, rest }
+}
+
+function checkPositionals(given: string[], names: readonly string[]): void {
+  const variadic = names.at(-1)?.replace(']', '').endsWith('...') === true
+  const required = names.filter(name => !name.startsWith('[')).length
+
+  if (given.length < required)
+    badUsage(`missing ${names[given.length]}`)
+
+  if (!variadic && given.length > names.length)
+    badUsage(`unexpected argument ${given[names.length]}`)
+}
+
+// parseArgs' message, its first sentence alone and lowercased as the kit's own: `unknown option '--nope'`.
+function parseError(error: unknown): string {
+  const message = upTo(error instanceof Error ? error.message : String(error), '. ')
+
+  return `${message.charAt(0).toLowerCase()}${message.slice(1)}`
+}
+
+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}`)
+
+  return number
+}
+
+const DURATION = /^(\d+(?:\.\d+)?)(ms|[smh])?$/
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_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 {
+  if (value === undefined)
+    return fallback
+
+  const match = DURATION.exec(value.trim())
+  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}`)
+
+  return ms
+}
+
+export interface InputSettings {
+  // What to say when stdin is a terminal, as nothing is piped.
+  noStdin?: string
+}
+
+// Text from a file, or from stdin when the path is `-`. A missing file or a stdin left on the terminal ends the command.
+export async function readInput(path: string, { noStdin = 'nothing is piped on stdin' }: InputSettings = {}): Promise<string> {
+  if (path === '-') {
+    if (process.stdin.isTTY)
+      fail(noStdin)
+
+    return Bun.stdin.text()
+  }
+
+  const file = Bun.file(path)
+
+  if (!await file.exists())
+    fail(`no file ${path}`)
+
+  return file.text()
+}

package/src/chart.ts

@@ -0,0 +1,88 @@
+import process from 'node:process'
+import { textWidth } from './format'
+import { paint } from './style'
+
+type Env = Record<string, string | undefined>
+
+const LEVELS = '▁▂▃▄▅▆▇█'
+
+// One block per value, tall in proportion to where it sits between the smallest and the largest; a flat series draws mid-height.
+export function sparkline(values: number[]): string {
+  if (values.length === 0)
+    return ''
+
+  const low = Math.min(...values)
+  const span = Math.max(...values) - low
+
+  return values.map(value => LEVELS[span === 0 ? 3 : Math.round((value - low) / span * (LEVELS.length - 1))]).join('')
+}
+
+export interface BarSettings {
+  width?: number
+  stream?: { isTTY?: boolean }
+  env?: Env
+}
+
+// `████████░░░░░░░░░░░░` for a ratio between 0 and 1, filled in cyan and the rest dim on a terminal.
+export function bar(ratio: number, { width = 20, stream = process.stdout, env = process.env }: BarSettings = {}): string {
+  const colors = paint(stream, env)
+  const filled = Math.round(Math.min(1, Math.max(0, ratio)) * width)
+
+  return `${colors.cyan('█'.repeat(filled))}${colors.dim('░'.repeat(width - filled))}`
+}
+
+export interface KeyValueSettings {
+  stream?: { isTTY?: boolean }
+  env?: Env
+}
+
+// Labels dimmed and padded to the longest, one pair per line: `state   open`.
+export function keyValue(pairs: [label: string, value: string][], { stream = process.stdout, env = process.env }: KeyValueSettings = {}): string {
+  const colors = paint(stream, env)
+  const width = Math.max(0, ...pairs.map(([label]) => textWidth(label)))
+
+  return pairs.map(([label, value]) => `${colors.dim(label)}${' '.repeat(width - textWidth(label))}  ${value}`).join('\n')
+}
+
+export interface BarChartSettings extends KeyValueSettings {
+  // Columns the bars take, 24 by default.
+  width?: number
+  // Formats the number at the end of each row.
+  format?: (value: number) => string
+}
+
+// A bar per labelled value, scaled to the largest: `label  ██████░░░░░░  42`.
+export function barChart(rows: [label: string, value: number][], { width = 24, format = String, stream = process.stdout, env = process.env }: BarChartSettings = {}): string {
+  const largest = Math.max(0, ...rows.map(([, value]) => value))
+  const labels = Math.max(0, ...rows.map(([label]) => textWidth(label)))
+  const values = Math.max(0, ...rows.map(([, value]) => textWidth(format(value))))
+
+  return rows.map(([label, value]) => `${label}${' '.repeat(labels - textWidth(label))}  ${bar(largest === 0 ? 0 : value / largest, { width, stream, env })}  ${' '.repeat(values - textWidth(format(value)))}${format(value)}`).join('\n')
+}
+
+export interface TreeNode {
+  label: string
+  children?: TreeNode[]
+}
+
+// Each root on a line of its own and its children under it, hung on dimmed `├─`, `└─` and `│` branches.
+export function tree(roots: TreeNode[], { stream = process.stdout, env = process.env }: KeyValueSettings = {}): string {
+  const colors = paint(stream, env)
+  const lines: string[] = []
+
+  function branch(nodes: TreeNode[], indent: string) {
+    for (const [index, { label, children = [] }] of nodes.entries()) {
+      const last = index === nodes.length - 1
+
+      lines.push(`${colors.dim(`${indent}${last ? '└─' : '├─'}`)} ${label}`)
+      branch(children, `${indent}${last ? '   ' : '│  '}`)
+    }
+  }
+
+  for (const { label, children = [] } of roots) {
+    lines.push(label)
+    branch(children, '')
+  }
+
+  return lines.join('\n')
+}