@kaynooo/cli-kit 0.7.3 → 0.8.0

package/README.md

@@ -43,6 +43,8 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
 - `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`).
@@ -57,4 +59,8 @@ On a terminal, help has bold `Usage:`, `Commands:` and `Options:` headers, comma
   - 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,7 +1,7 @@
 {
   "name": "@kaynooo/cli-kit",
   "type": "module",
-  "version": "0.7.3",
+  "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",

package/src/args.ts

@@ -56,8 +56,16 @@ 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)): string {
-  return [usageLine(usage, colors), '', colors.bold('Options:'), ...optionRows(options, colors)].join('\n')
+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.
@@ -85,11 +93,44 @@ export interface ParseSettings<Names extends readonly string[] = string[]> {
   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> = {}) {
-  const all = { ...options, help: { type: 'boolean', short: 'h', description: 'show this help' } } as const
+  // 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)
@@ -107,8 +148,12 @@ export function parse<const T extends Options, const Names extends readonly stri
     badUsage(parseError(error))
   }
 
-  if ((parsed.values as { help?: boolean }).help === true) {
-    console.log(helpText(usage, all))
+  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()
   }

package/src/chart.ts

@@ -59,3 +59,30 @@ export function barChart(rows: [label: string, value: number][], { width = 24, f
 
   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')
+}

package/src/cli.ts

@@ -1,14 +1,18 @@
-import type { Options } from './args'
+import type { Example, Options } from './args'
 import type { Colors } from './style'
 import process from 'node:process'
-import { Completing, completion, Exit, HelpShown, optionRows, UsageError, usageLine } from './args'
+import { applyOutput, Completing, completion, exampleRows, Exit, HelpShown, optionRows, OUTPUT_OPTIONS, UsageError, usageLine } from './args'
 import { paint, takesControlCodes } from './style'
 import { distance } from './text'
 
-export type Command = { summary: string } & (
+export type Command = {
+  summary: string
+  // The heading the command is listed under in the help, after those with none.
+  group?: string
+} & (
   | { run: (args: string[]) => Promise<number> }
   // A group of subcommands dispatched the same way, with its own help.
-  | { commands: Record<string, Command>, aliases?: Record<string, string> }
+  | { commands: Record<string, Command>, aliases?: Record<string, string>, examples?: Example[] }
 )
 
 export interface Cli {
@@ -23,6 +27,50 @@ export interface Cli {
   defaultCommand?: string
   // Rewrites an error's message and cause before they print, for a CLI whose errors may quote what a log must not keep.
   redact?: (text: string) => string
+  // Command lines shown under `Examples:` in `<cli> --help`; a command's own go to `parse`.
+  examples?: Example[]
+}
+
+const LEVEL_OPTIONS = {
+  ...OUTPUT_OPTIONS,
+  help: { type: 'boolean', short: 'h', description: 'show this help' },
+} as const satisfies Options
+const TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: 'boolean', short: 'v', description: 'print the version' } } as const satisfies Options
+
+// The rows under `Commands:`, then a heading per group in the order first met, names aligned across them all.
+function commandRows(commands: Record<string, Command>, colors: Colors): string[] {
+  const width = Math.max(...Object.keys(commands).map(name => name.length))
+  const groups = new Map<string, string[]>([['Commands:', []]])
+
+  for (const [name, { summary, group }] of Object.entries(commands)) {
+    const heading = group === undefined ? 'Commands:' : `${group}:`
+    const rows = groups.get(heading) ?? []
+
+    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`)
+    groups.set(heading, rows)
+  }
+
+  return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [''], colors.bold(heading), ...rows])
+}
+
+// The output flags typed before the command name, applied and dropped: `ft --plain runs`.
+function takeOutputFlags(argv: string[]): string[] {
+  let index = 0
+
+  for (; index < argv.length; index++) {
+    const word = argv[index]!
+
+    if (word === '--plain')
+      applyOutput(undefined, true)
+    else if (word.startsWith('--color='))
+      applyOutput(word.slice('--color='.length), undefined)
+    else if (word === '--color' && argv[index + 1] !== undefined)
+      applyOutput(argv[++index], undefined)
+    else
+      break
+  }
+
+  return argv.slice(index)
 }
 
 // A command the name starts, else one within two edits (one for a name under four letters).
@@ -44,24 +92,29 @@ interface Level {
   commands: Record<string, Command>
   aliases: Record<string, string> | undefined
   defaultCommand: string | undefined
+  examples: Example[] | undefined
 }
 
 // The level's help; a default command's options follow the commands, as they apply with no command named.
-async function help({ path, header, commands, defaultCommand }: Level, stream: { isTTY?: boolean }): Promise<string> {
+async function help({ path, header, commands, defaultCommand, examples }: Level, stream: { isTTY?: boolean }): Promise<string> {
   const colors = paint(stream)
-  const width = Math.max(...Object.keys(commands).map(name => name.length))
   const prefix = path.join(' ')
   const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
   const options = fallback !== undefined && 'run' in fallback ? await optionsOf(fallback.run) : undefined
+  // The default command's own run lists the output flags again, so they show once, under the level's.
+  const own = Object.entries(options ?? {}).filter(([name]) => !(name in TOP_OPTIONS))
 
   return [
     header(colors),
     '',
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan('<command>') : `[${colors.cyan('<command>')}]`} [options]`, colors),
     '',
-    colors.bold('Commands:'),
-    ...Object.entries(commands).map(([name, { summary }]) => `  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`),
-    ...options === undefined || Object.keys(options).length === 0 ? [] : ['', `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim('the command run when none is named')}`, ...optionRows(options, colors)],
+    ...commandRows(commands, colors),
+    ...own.length === 0 ? [] : ['', `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim('the command run when none is named')}`, ...optionRows(Object.fromEntries(own), colors)],
+    '',
+    colors.bold('Options:'),
+    ...optionRows(path.length === 1 ? TOP_OPTIONS : LEVEL_OPTIONS, colors),
+    ...exampleRows(examples ?? [], colors),
     '',
     `${colors.dim('Run')} ${prefix} ${colors.cyan('<command>')} --help ${colors.dim('for its options.')}`,
   ].join('\n')
@@ -92,9 +145,18 @@ function reportThrown(prefix: string, error: unknown, redact: (text: string) =>
   return error instanceof Exit ? error.code : 1
 }
 
-async function dispatch(level: Level, argv: string[], { version, redact }: { version: string, redact: Cli['redact'] | undefined }): Promise<number> {
-  const [name, ...args] = argv
+async function dispatch(level: Level, typed: string[], { version, redact }: { version: string, redact: Cli['redact'] | undefined }): Promise<number> {
   const prefix = level.path.join(' ')
+  let argv: string[]
+
+  try {
+    argv = takeOutputFlags(typed)
+  }
+  catch (error) {
+    return reportThrown(prefix, error)
+  }
+
+  const [name, ...args] = argv
 
   if (name === undefined && level.path.length > 1) {
     console.error(await help(level, process.stderr))
@@ -133,7 +195,7 @@ async function dispatch(level: Level, argv: string[], { version, redact }: { ver
   if ('commands' in command) {
     const { summary } = command
 
-    return dispatch({ path: [...level.path, name], header: colors => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined }, rest, { version, redact })
+    return dispatch({ path: [...level.path, name], header: colors => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined, examples: command.examples }, rest, { version, redact })
   }
 
   try {
@@ -204,7 +266,7 @@ export async function runCli(cli: Cli, argv = process.argv.slice(2)): Promise<nu
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)))
 
-  return dispatch({ path: [cli.name], header: colors => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand }, argv, { version: cli.version, redact: cli.redact })
+  return dispatch({ path: [cli.name], header: colors => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand, examples: cli.examples }, argv, { version: cli.version, redact: cli.redact })
 }
 
 export interface Main {

package/src/progress.ts

@@ -14,9 +14,31 @@ export interface Progress {
 interface ProgressStream {
   isTTY?: boolean
   columns?: number | undefined
+  rows?: number | undefined
   write: (text: string) => unknown
 }
 
+export interface LiveRegion {
+  // Draws the lines again now, rather than at the next frame.
+  redraw: () => void
+  // Prints `text` above the region, where it stays once the region goes.
+  print: (text: string) => void
+  // Clears the region and leaves nothing behind.
+  stop: () => void
+}
+
+export interface TaskHandle {
+  update: (progress: Omit<Progress, 'step'>) => void
+  // Leaves `✓ <text> <time since the task began>` above the tasks still running, the label when no text is given.
+  done: (text?: string) => void
+  // Leaves `✗ <text>`, the label when no text is given.
+  failed: (text?: string) => void
+}
+
+export interface TaskList {
+  add: (label: string) => TaskHandle
+}
+
 export interface ProgressLine {
   update: (progress: Progress) => void
   // Clears the line and leaves nothing behind.
@@ -34,54 +56,54 @@ const FRAME_MS = 80
 const BAR_WIDTH = 20
 // Back to the start of the line, then erases it.
 const CLEAR_LINE = '\r\x1B[2K'
+// Up a line, then erases it.
+const LINE_UP = '\x1B[1A\x1B[2K'
+const ESC = String.fromCharCode(27)
+// A colour or cursor code, or an OSC 8 link's opening or closing, read where `lastIndex` points.
+const ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x7E]|\\][^\\u0007${ESC}]*(?:\\u0007|${ESC}\\\\))`, 'y')
+const RESET_STYLE = `${ESC}[0m`
+const CLOSE_LINK = `${ESC}]8;;${ESC}\\`
 // What the console prints with, to the terminal the line is drawn on or the other.
 const CONSOLE_METHODS = ['log', 'info', 'warn', 'error', 'debug', 'dir', 'dirxml', 'table', 'trace', 'group', 'groupCollapsed', 'count', 'timeEnd', 'timeLog', 'assert'] as const
 
 // A piece of the line and how it is tinted, so the line can be cut to the terminal's width on its visible text.
 interface Part { text: string, tint: (colors: Colors) => (text: string) => string }
 
-// One line on `stream`, redrawn in place while a task runs: a spinner, the step, a bar where its total is known, and the time since the step began.
-// Drawn only on a terminal that takes control codes, so a log, CI or `NO_COLOR` gets `done` and `failed` lines alone; whatever else is printed meanwhile clears the line first, and the next frame draws it again under it.
-export function progressLine(stream: ProgressStream = process.stderr, env: Env = process.env): ProgressLine {
-  if (!takesControlCodes(stream, env)) {
-    const begun = performance.now()
-
-    return {
-      update: () => undefined,
-      stop: () => undefined,
-      done: text => stream.write(`${marked('ok', text, stream, formatDuration(performance.now() - begun), env)}\n`),
-      failed: text => stream.write(`${marked('problem', text, stream, undefined, env)}\n`),
-    }
-  }
+// Lines on `stream` redrawn in place every frame, `render` handed the spinner's next glyph, each line cut to the terminal's width and the block to its height.
+// Drawn only on a terminal that takes control codes, so elsewhere `render` never runs and the caller prints its own outcome; whatever else is printed meanwhile clears the block first, the next frame drawing it again under it, and an interrupt clears it before the process ends.
+export function liveRegion(render: (spinner: string) => string[], stream: ProgressStream = process.stderr, env: Env = process.env): LiveRegion {
+  if (!takesControlCodes(stream, env))
+    return { redraw: () => undefined, print: text => void stream.write(`${text}\n`), stop: () => undefined }
 
-  const colors = paint(stream, env)
-  // Its own write, taken before the line clears itself ahead of every other.
+  // Its own write, taken before the region clears itself ahead of every other.
   const write = stream.write.bind(stream)
-  const begun = performance.now()
-  let started = begun
-  let current: Progress | undefined
   let frame = 0
-  let drawn = false
+  let drawn = 0
   const clear = () => {
-    if (drawn)
-      write(CLEAR_LINE)
+    if (drawn > 0)
+      write(`${CLEAR_LINE}${LINE_UP.repeat(drawn - 1)}`)
 
-    drawn = false
+    drawn = 0
   }
   const draw = () => {
-    if (current === undefined)
-      return
-
-    // A terminal that does not say its width, as a pseudo-terminal may, answers 0.
+    // A terminal that does not say its size, as a pseudo-terminal may, answers 0.
     const width = (stream.columns === undefined || stream.columns === 0 ? 80 : stream.columns) - 1
+    const height = stream.rows === undefined || stream.rows === 0 ? 24 : stream.rows
+    const lines = render(FRAMES[frame++ % FRAMES.length]!).slice(0, Math.max(1, height - 1)).map(line => cutToWidth(line, width))
+
+    if (lines.length === 0) {
+      clear()
+
+      return
+    }
 
-    write(`${CLEAR_LINE}${fit(progressParts(current, FRAMES[frame++ % FRAMES.length]!, performance.now() - started), width, colors)}`)
-    drawn = true
+    write(`${drawn > 0 ? `${CLEAR_LINE}${LINE_UP.repeat(drawn - 1)}` : CLEAR_LINE}${lines.join('\n')}`)
+    drawn = lines.length
   }
   const timer = setInterval(draw, FRAME_MS)
   const restore = interceptOutput(clear)
   const onExit = () => clear()
-  // Interrupted, the line goes before the shell's prompt comes back.
+  // Interrupted, the block goes before the shell's prompt comes back.
   const signals = holdSignals(stop)
 
   function stop() {
@@ -95,6 +117,32 @@ export function progressLine(stream: ProgressStream = process.stderr, env: Env =
   timer.unref()
   process.on('exit', onExit)
 
+  return {
+    redraw: draw,
+    print: (text) => {
+      clear()
+      write(`${text}\n`)
+      draw()
+    },
+    stop,
+  }
+}
+
+// One line on `stream`, redrawn in place while a task runs: a spinner, the step, a bar where its total is known, and the time since the step began.
+// Off a terminal taking control codes, a log, CI or `NO_COLOR` gets the `done` and `failed` lines alone.
+export function progressLine(stream: ProgressStream = process.stderr, env: Env = process.env): ProgressLine {
+  const colors = paint(stream, env)
+  // Its own write, taken before the region clears itself ahead of every other.
+  const write = stream.write.bind(stream)
+  const begun = performance.now()
+  let started = begun
+  let current: Progress | undefined
+  const region = liveRegion(spinner => current === undefined ? [] : [tinted(progressParts(current, spinner, performance.now() - started), colors)], stream, env)
+  const end = (line: string) => {
+    region.stop()
+    write(`${line}\n`)
+  }
+
   return {
     // A new step is drawn at once, its clock started again; a count moving on waits for the next frame, so a burst of updates writes one.
     update: (progress) => {
@@ -104,17 +152,48 @@ export function progressLine(stream: ProgressStream = process.stderr, env: Env =
 
       if (progress.step !== step) {
         started = performance.now()
-        draw()
+        region.redraw()
       }
     },
-    stop,
-    done: (text) => {
-      stop()
-      write(`${marked('ok', text, stream, formatDuration(performance.now() - begun), env)}\n`)
-    },
-    failed: (text) => {
-      stop()
-      write(`${marked('problem', text, stream, undefined, env)}\n`)
+    stop: region.stop,
+    done: text => end(marked('ok', text, stream, formatDuration(performance.now() - begun), env)),
+    failed: text => end(marked('problem', text, stream, undefined, env)),
+  }
+}
+
+// Stacked lines for tasks running side by side, each drawn as a progress line is; a task ending leaves its ✓ or ✗ line above those still running, and the block goes once none is.
+export function taskList(stream: ProgressStream = process.stderr, env: Env = process.env): TaskList {
+  const colors = paint(stream, env)
+  const running = new Set<{ progress: Progress, started: number }>()
+  let region: LiveRegion | undefined
+  const render = (spinner: string) => [...running].map(({ progress, started }) => tinted(progressParts(progress, spinner, performance.now() - started), colors))
+
+  return {
+    add: (label) => {
+      const entry = { progress: { step: label } as Progress, started: performance.now() }
+      const end = (line: string) => {
+        if (!running.delete(entry))
+          return
+
+        region?.print(line)
+
+        if (running.size === 0) {
+          region?.stop()
+          region = undefined
+        }
+      }
+
+      running.add(entry)
+      region ??= liveRegion(render, stream, env)
+      region.redraw()
+
+      return {
+        update: (progress) => {
+          entry.progress = { ...progress, step: label }
+        },
+        done: text => end(marked('ok', text ?? label, stream, formatDuration(performance.now() - entry.started), env)),
+        failed: text => end(marked('problem', text ?? label, stream, undefined, env)),
+      }
     },
   }
 }
@@ -168,24 +247,48 @@ function plain(text: string): string {
   return text
 }
 
-// The parts cut to `width` visible characters, each tinted after the cut so no escape is split.
-function fit(parts: Part[], width: number, colors: Colors): string {
+function tinted(parts: Part[], colors: Colors): string {
+  return parts.map(({ text, tint }) => tint(colors)(text)).join('')
+}
+
+// The line cut to `width` columns of visible text, its escapes kept whole, and the styles and a link ended after a cut so none runs into the next line.
+function cutToWidth(line: string, width: number): string {
+  if (Bun.stringWidth(line) <= width)
+    return line
+
   let room = width
-  let line = ''
+  let kept = ''
+  let index = 0
+  let linked = false
+
+  while (index < line.length) {
+    ESCAPE_CODE.lastIndex = index
+
+    const escape = ESCAPE_CODE.exec(line)
+
+    if (escape !== null) {
+      kept += escape[0]
+      linked ||= escape[0].startsWith(`${ESC}]`)
+      index = ESCAPE_CODE.lastIndex
+
+      continue
+    }
 
-  for (const { text, tint } of parts) {
-    const kept = [...text].slice(0, Math.max(room, 0)).join('')
+    const char = String.fromCodePoint(line.codePointAt(index)!)
+    const columns = Bun.stringWidth(char)
 
-    room -= kept.length
+    if (columns > room)
+      break
 
-    if (kept !== '')
-      line += tint(colors)(kept)
+    kept += char
+    room -= columns
+    index += char.length
   }
 
-  return line
+  return `${kept}${RESET_STYLE}${linked ? CLOSE_LINK : ''}`
 }
 
-// Clears the line before anything the console or a stream writes, the caller's own code meanwhile included, and answers how to put them back.
+// Clears the region before anything the console or a stream writes, the caller's own code meanwhile included, and answers how to put them back.
 function interceptOutput(clear: () => void): () => void {
   const targets = [...CONSOLE_METHODS.map(name => [console, name] as const), [process.stdout, 'write'] as const, [process.stderr, 'write'] as const]
   const wrapped = targets.map(([target, name]) => {

package/src/style.ts

@@ -64,6 +64,36 @@ export function role(name: Role, stream: { isTTY?: boolean }, env: Record<string
   return ROLES[name](paint(stream, env))
 }
 
+export type Status = 'passed' | 'failed' | 'running' | 'queued' | 'skipped'
+
+// What each status draws, and the words CI services report it by.
+const STATUSES: Record<Status, { symbol: string, words: string[], paint: (colors: Colors) => (text: string) => string }> = {
+  passed: { symbol: '✓', words: ['passed', 'success', 'succeeded', 'ok'], paint: colors => colors.green },
+  failed: { symbol: '✗', words: ['failed', 'failure', 'error', 'errored'], paint: colors => colors.red },
+  running: { symbol: '●', words: ['running', 'in_progress', 'started'], paint: colors => colors.cyan },
+  queued: { symbol: '○', words: ['queued', 'waiting', 'pending', 'created', 'blocked', 'scheduled'], paint: colors => colors.yellow },
+  skipped: { symbol: '-', words: ['skipped', 'cancelled', 'canceled', 'manual'], paint: colors => colors.dim },
+}
+
+const STATUS_OF = new Map(Object.entries(STATUSES).flatMap(([status, { words }]) => words.map(word => [word, status as Status])))
+
+// The status a word such as `success` or `in_progress` stands for, undefined for one it does not know.
+export function statusOf(word: string): Status | undefined {
+  return STATUS_OF.get(word.toLowerCase())
+}
+
+// `✓ success` in green, `✗ failure` in red, `● running`, `○ waiting` or `- skipped` on a terminal; the word alone elsewhere, and a word of no known status as given.
+export function badge(word: string, stream: { isTTY?: boolean }, env: Record<string, string | undefined> = process.env): string {
+  const status = statusOf(word)
+
+  if (status === undefined || !takesControlCodes(stream, env))
+    return word
+
+  const { symbol, paint: tint } = STATUSES[status]
+
+  return tint(paint(stream, env))(`${symbol} ${word}`)
+}
+
 // A clickable OSC 8 link on a terminal; elsewhere `text (url)`, or the text alone when it is the url.
 export function link(text: string, url: string, stream: { isTTY?: boolean }, env: Record<string, string | undefined> = process.env): string {
   if (takesControlCodes(stream, env))