@kaynooo/cli-kit 0.0.0-stage → 0.8.0

package/src/cli.ts

@@ -0,0 +1,296 @@
+import type { Example, Options } from './args'
+import type { Colors } from './style'
+import process from 'node:process'
+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
+  // 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>, examples?: Example[] }
+)
+
+export interface Cli {
+  name: string
+  version: string
+  // One line after `<name> <version>: ` in the help.
+  about: string
+  commands: Record<string, Command>
+  // Names sessions reach for that mean an existing command.
+  aliases?: Record<string, string>
+  // The command that takes the arguments when the first one names no command, so `db "select 1"` runs `db query "select 1"`; `--help` lists its options under the commands.
+  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).
+export function closest(name: string, names: string[]): string | undefined {
+  const started = names.find(known => known.startsWith(name))
+
+  if (started !== undefined)
+    return started
+
+  const [best] = names.map(known => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far)
+
+  return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined
+}
+
+interface Level {
+  // The words typed to reach this level, `ft plan`.
+  path: string[]
+  header: (colors: Colors) => string
+  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, examples }: Level, stream: { isTTY?: boolean }): Promise<string> {
+  const colors = paint(stream)
+  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),
+    '',
+    ...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')
+}
+
+// `error <prefix>: <message>` on stderr, the cause and the hint each on a line of their own under it; plain words off a terminal.
+export function printError(prefix: string, message: string, hint?: string, cause?: string): void {
+  const colors = paint(process.stderr)
+  const styled = takesControlCodes(process.stderr)
+  const head = styled ? `${colors.red.bold('error')} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`
+  const under = (label: string, text: string | undefined, tint: (text: string) => string) => text === undefined ? '' : `\n  ${styled ? tint(label) : `${label}:`} ${text}`
+
+  console.error(`${head} ${message}${under('cause', cause, colors.dim)}${under('hint', hint, colors.yellow)}`)
+}
+
+// What a thrown error prints as and exits with: an Exit its own code and hint, a UsageError pointed at the help, HelpShown nothing at all and 0, anything else 1.
+// An error other than an Exit is named unless a plain `Error` (`MigrationError: ...`), and its cause's message printed under it, never the cause itself.
+function reportThrown(prefix: string, error: unknown, redact: (text: string) => string = text => text): number {
+  if (error instanceof HelpShown)
+    return 0
+
+  const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined
+  const named = error instanceof Error && !(error instanceof Exit) && error.name !== 'Error' ? `${error.name}: ${error.message}` : undefined
+  const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined
+
+  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause)
+
+  return error instanceof Exit ? error.code : 1
+}
+
+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))
+
+    return 2
+  }
+
+  if (name === undefined || name === 'help' || name === '--help' || name === '-h') {
+    console.log(await help(level, process.stdout))
+
+    return 0
+  }
+
+  if (level.path.length === 1 && (name === '--version' || name === '-v')) {
+    console.log(version)
+
+    return 0
+  }
+
+  let command = level.commands[level.aliases?.[name] ?? name]
+  let rest = args
+
+  if (command === undefined && level.defaultCommand !== undefined) {
+    command = level.commands[level.defaultCommand]
+    rest = argv
+  }
+
+  if (command === undefined) {
+    const meant = closest(name, Object.keys(level.commands))
+
+    printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`)
+
+    return 2
+  }
+
+  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, examples: command.examples }, rest, { version, redact })
+  }
+
+  try {
+    return await command.run(rest)
+  }
+  catch (error) {
+    return reportThrown(`${prefix} ${name}`, error, redact)
+  }
+}
+
+// The hidden first argument a shell completion calls a bin with: `<bin> __complete <words typed after it>... <word being typed>`.
+export const COMPLETE = '__complete'
+// Printed instead of candidates where a path fits, for the shell to complete files itself.
+export const FILES = '__files__'
+
+// A command's options, read by running it until its parse call throws them: every command parses its arguments before anything else.
+async function optionsOf(run: (args: string[]) => Promise<number>): Promise<Options> {
+  completion.active = true
+
+  try {
+    await run([])
+  }
+  catch (error) {
+    if (error instanceof Completing)
+      return error.options
+  }
+  finally {
+    completion.active = false
+  }
+
+  return {}
+}
+
+// A leaf command's candidates: its long options for a word starting with a dash, else paths.
+async function leafCandidates(run: (args: string[]) => Promise<number>, words: string[]): Promise<string[]> {
+  if (!(words.at(-1) ?? '').startsWith('-'))
+    return [FILES]
+
+  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}\t${option.description}`)
+}
+
+// The candidates for the last word, `value\tdescription` per line, after walking the subcommands the earlier words name.
+async function candidates(commands: Record<string, Command>, aliases: Record<string, string> | undefined, defaultCommand: string | undefined, words: string[]): Promise<string[]> {
+  const [word = '', ...rest] = words
+  const command = commands[aliases?.[word] ?? word]
+
+  if (rest.length === 0 && !word.startsWith('-'))
+    return Object.entries(commands).map(([name, { summary }]) => `${name}\t${summary}`)
+
+  if (command === undefined) {
+    const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand]
+
+    return fallback !== undefined && 'run' in fallback ? leafCandidates(fallback.run, words) : []
+  }
+
+  return 'commands' in command ? candidates(command.commands, command.aliases, undefined, rest) : leafCandidates(command.run, rest)
+}
+
+async function printCandidates(found: Promise<string[]>): Promise<number> {
+  for (const line of await found)
+    console.log(line)
+
+  return 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> {
+  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, examples: cli.examples }, argv, { version: cli.version, redact: cli.redact })
+}
+
+export interface Main {
+  name: string
+  version: string
+  run: (args: string[]) => Promise<number>
+  redact?: (text: string) => string
+}
+
+// Runs a CLI that is a single command: `--version` or `-v` alone prints the version, an `Exit` or any error prints as `error: <name>: <message>`. Returns the exit code.
+export async function runMain({ name, version, run, redact }: Main, argv = process.argv.slice(2)): Promise<number> {
+  if (argv[0] === COMPLETE)
+    return printCandidates(leafCandidates(run, argv.slice(1)))
+
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
+    console.log(version)
+
+    return 0
+  }
+
+  try {
+    return await run(argv)
+  }
+  catch (error) {
+    return reportThrown(name, error, redact)
+  }
+}

package/src/config.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import process from 'node:process'
+import { fail } from './args'
+
+// The nearest of `names` in `from` or a folder above it, the first name winning within one folder.
+export function findUp(names: string | string[], from = process.cwd()): string | undefined {
+  const wanted = typeof names === 'string' ? [names] : names
+
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    const found = wanted.map(name => join(dir, name)).find(path => existsSync(path))
+
+    if (found !== undefined)
+      return found
+
+    if (dirname(dir) === dir)
+      return undefined
+  }
+}
+
+export interface ConfigSettings {
+  // Where the search starts, the current folder by default.
+  from?: string
+  // A file named on the command line, read instead of searching; resolved against `from`.
+  path?: string | undefined
+}
+
+export interface LoadedConfig {
+  path: string
+  // The folder holding the config, which paths written in it are relative to.
+  dir: string
+  // Its default export, for the caller to check.
+  config: unknown
+}
+
+// Imports the nearest config named `names` (`.ts`, `.js` or `.json`), or the one `path` names; undefined when none is found. A named file missing, one failing to import or one without a default export ends the command.
+export async function loadConfig(names: string | string[], { from = process.cwd(), path }: ConfigSettings = {}): Promise<LoadedConfig | undefined> {
+  const file = path === undefined ? findUp(names, from) : resolve(from, path)
+
+  if (file === undefined)
+    return undefined
+
+  if (!existsSync(file))
+    fail(`no file ${file}`, 1)
+
+  let module: { default?: unknown }
+
+  try {
+    module = await import(file) as { default?: unknown }
+  }
+  catch (error) {
+    fail(`${file} does not load: ${error instanceof Error ? error.message : String(error)}`, 1)
+  }
+
+  if (module.default === undefined)
+    fail(`${file} has no default export`, 1)
+
+  return { path: file, dir: dirname(file), config: module.default }
+}

package/src/format.ts

@@ -0,0 +1,163 @@
+import process from 'node:process'
+import { paint } from './style'
+
+export { formatFileSize, formatUnit } from '@kaynooo/utils/format'
+
+const UNITS = [['d', 86_400], ['h', 3600], ['m', 60], ['s', 1]] as const
+
+// Renders as "13m 28s": the largest unit and the next one, dropped when zero.
+export function formatSeconds(total: number): string {
+  let rest = Math.max(0, Math.round(total))
+  const amounts = UNITS.map(([unit, size]) => {
+    const amount = Math.floor(rest / size)
+
+    rest -= amount * size
+
+    return `${amount}${unit}`
+  })
+  const first = amounts.findIndex(amount => !amount.startsWith('0'))
+
+  if (first === -1)
+    return '0s'
+
+  const next = amounts[first + 1]
+
+  return next === undefined || next.startsWith('0') ? amounts[first] ?? '0s' : `${amounts[first]} ${next}`
+}
+
+// Like formatSeconds from a duration in milliseconds, but under a minute with one decimal so a fast step reads `0.3s`, not `0s`.
+export function formatDuration(ms: number): string {
+  return ms < 60_000 ? `${(Math.max(0, ms) / 1000).toFixed(1)}s` : formatSeconds(ms / 1000)
+}
+
+// The text up to the first separator, or all of it.
+export function upTo(text: string, separator: string): string {
+  const end = text.indexOf(separator)
+
+  return end === -1 ? text : text.slice(0, end)
+}
+
+export function formatAge(date: string | number, now = Date.now()): string {
+  const at = typeof date === 'number' ? date : Date.parse(date)
+
+  if (Number.isNaN(at))
+    return '-'
+
+  const seconds = (now - at) / 1000
+
+  return seconds < 60 ? 'just now' : `${upTo(formatSeconds(seconds), ' ')} ago`
+}
+
+export function truncate(text: string, width: number): string {
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`
+}
+
+const LINE_BREAKS = /\s*\n\s*/g
+const ESCAPE = String.fromCharCode(27)
+
+export type Align = 'left' | 'right'
+
+export interface TableSettings {
+  // Flattens each cell's line breaks to a space and cuts it to this many characters.
+  cellWidth?: number
+  // Takes the first row for column names, bold on a terminal.
+  header?: boolean
+  // Per column, `right` for numbers; a column not named is left-aligned.
+  align?: Align[]
+  // Narrows the widest column until a row fits this many characters, `process.stdout.columns` for the terminal's own width. Cells holding colours are never cut.
+  fit?: number
+}
+
+// Columns in the visible width of a cell, escapes and wide characters accounted for.
+export function textWidth(text: string): number {
+  return Bun.stringWidth(text)
+}
+
+export function table(rows: string[][], { cellWidth, header = false, align = [], fit }: TableSettings = {}): string {
+  const cells = cellWidth === undefined ? rows : rows.map(row => row.map(cell => truncate(cell.replaceAll(LINE_BREAKS, ' '), cellWidth)))
+  const widths: number[] = []
+
+  for (const row of cells) {
+    for (const [index, cell] of row.entries())
+      widths[index] = Math.max(widths[index] ?? 0, textWidth(cell))
+  }
+
+  const shown = fit === undefined ? cells : narrow(cells, widths, fit)
+  const colors = paint(process.stdout)
+  const lines = shown.map(row => row.map((cell, index) => {
+    const width = widths[index] ?? 0
+    const gap = ' '.repeat(Math.max(0, width - textWidth(cell)))
+
+    if (align[index] === 'right')
+      return `${gap}${cell}`
+
+    return index === row.length - 1 ? cell : `${cell}${gap}`
+  }).join('  ').trimEnd())
+
+  return lines.map((line, index) => header && index === 0 ? colors.bold(line) : line).join('\n')
+}
+
+// The rows with the widest cuttable column cut so every line fits `limit`, `widths` shrinking with it.
+function narrow(rows: string[][], widths: number[], limit: number): string[][] {
+  const used = () => widths.reduce((sum, width) => sum + width, 0) + 2 * Math.max(0, widths.length - 1)
+  const cuttable = (index: number) => rows.every(row => !(row[index] ?? '').includes(ESCAPE))
+  const floor = 8
+
+  while (used() > limit) {
+    let widest = -1
+
+    for (const [index, width] of widths.entries()) {
+      if (cuttable(index) && width > floor && width > (widths[widest] ?? 0))
+        widest = index
+    }
+
+    if (widest === -1)
+      break
+
+    widths[widest] = Math.max(floor, (widths[widest] ?? 0) - (used() - limit))
+  }
+
+  return rows.map(row => row.map((cell, index) => textWidth(cell) > (widths[index] ?? 0) ? truncate(cell, widths[index] ?? 0) : cell))
+}
+
+// What a `--json` flag prints: the value indented by two spaces, on stdout.
+export function printJson(value: unknown): void {
+  console.log(JSON.stringify(value, undefined, 2))
+}
+
+// `0.62` as `62%`.
+export function formatPercent(ratio: number, digits = 0): string {
+  return `${(ratio * 100).toFixed(digits)}%`
+}
+
+// A change with its sign: `+3`, `-3`, `0`.
+export function formatDelta(value: number, digits = 0): string {
+  const text = value.toFixed(digits)
+
+  if (Number(text) === 0)
+    return text.replace('-', '')
+
+  return value > 0 ? `+${text}` : text
+}
+
+export interface ChangeSettings {
+  // Which way is an improvement; the other way is painted red.
+  better?: 'lower' | 'higher'
+  stream?: { isTTY?: boolean }
+  env?: Record<string, string | undefined>
+}
+
+// How `after` moved from `before` as a signed percentage (`-36%`), green when it improved and red when it did not; `-` when `before` is zero.
+export function formatChange(before: number, after: number, { better = 'lower', stream = process.stdout, env = process.env }: ChangeSettings = {}): string {
+  if (before === 0)
+    return '-'
+
+  const change = (after - before) / before
+  const text = `${formatDelta(change * 100)}%`
+  const colors = paint(stream, env)
+
+  if (change === 0)
+    return colors.dim(text)
+
+  return (change < 0) === (better === 'lower') ? colors.green(text) : colors.red(text)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './args'
+export * from './chart'
+export * from './cli'
+export * from './config'
+export * from './format'
+export * from './process'
+export * from './style'
+export * from './text'

package/src/process.ts

@@ -0,0 +1,120 @@
+import { constants } from 'node:os'
+import { resolve } from 'node:path'
+import process from 'node:process'
+
+export interface Chunk {
+  stream: 'stdout' | 'stderr'
+  data: Uint8Array
+}
+
+export interface Ran {
+  code: number
+  // Both streams in the order they arrived.
+  chunks: Chunk[]
+  // The bytes of every chunk joined.
+  output: Buffer
+  text: string
+}
+
+export interface RunSettings {
+  cwd?: string
+  env?: Record<string, string | undefined>
+  stdin?: 'inherit' | 'ignore'
+}
+
+export interface HeldSignals {
+  // The last signal received, undefined while none has come.
+  readonly signal: NodeJS.Signals | undefined
+  // Passes each signal received from now on to `child`, so it ends and its code is the one to exit with.
+  forward: (child: { kill: (signal: NodeJS.Signals) => unknown }) => void
+  // Takes the handlers off again, and may be called more than once.
+  release: () => void
+}
+
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+// A scheme of two letters or more, so a Windows drive is read as a path.
+const SCHEME = /^[a-z][\w+.-]+:/i
+const OPENERS: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ['open'], win32: ['cmd', '/c', 'start', ''] }
+
+async function collect(stream: ReadableStream<Uint8Array>, name: Chunk['stream'], chunks: Chunk[]): Promise<void> {
+  for await (const data of stream)
+    chunks.push({ stream: name, data })
+}
+
+// The exit code a shell would report: the code, or 128 plus the signal.
+export function exitCodeOf(code: number | null, signal: NodeJS.Signals | number | null): number {
+  if (code !== null)
+    return code
+
+  if (typeof signal === 'number')
+    return 128 + signal
+
+  return signal === null ? 129 : 128 + constants.signals[signal]
+}
+
+// Takes SIGINT, SIGTERM and SIGHUP over until released. A signal goes to the child given to `forward`; without one, `cleanup` runs and the signal is raised again so the process ends as it would have; without either, it is only kept in `signal` for the caller to wind down on.
+export function holdSignals(cleanup?: (signal: NodeJS.Signals) => void): HeldSignals {
+  let received: NodeJS.Signals | undefined
+  let child: Parameters<HeldSignals['forward']>[0] | undefined
+  const held: HeldSignals = {
+    get signal() {
+      return received
+    },
+    forward: (to) => {
+      child = to
+    },
+    release: () => {
+      for (const signal of SIGNALS)
+        process.off(signal, onSignal)
+    },
+  }
+
+  function onSignal(signal: NodeJS.Signals) {
+    received = signal
+
+    if (child !== undefined) {
+      child.kill(signal)
+
+      return
+    }
+
+    if (cleanup === undefined)
+      return
+
+    held.release()
+    cleanup(signal)
+    process.kill(process.pid, signal)
+  }
+
+  for (const signal of SIGNALS)
+    process.on(signal, onSignal)
+
+  return held
+}
+
+// Opens a URL, or a file path, with the command BROWSER names or the platform's opener, run in `env` without waiting for it; false when that command cannot start.
+export function openUrl(target: string, env: Record<string, string | undefined> = process.env, platform: NodeJS.Platform = process.platform): boolean {
+  const opener = env.BROWSER === undefined || env.BROWSER === '' ? OPENERS[platform] ?? ['xdg-open'] : [env.BROWSER]
+
+  try {
+    Bun.spawn([...opener, SCHEME.test(target) ? target : resolve(target)], { env, stdio: ['ignore', 'ignore', 'ignore'] }).unref()
+
+    return true
+  }
+  catch {
+    return false
+  }
+}
+
+// Runs a command with stdout and stderr captured; throws when it cannot be started.
+export async function runCommand(argv: string[], { cwd, env, stdin = 'ignore' }: RunSettings = {}): Promise<Ran> {
+  const chunks: Chunk[] = []
+  const proc = Bun.spawn(argv, { ...(cwd === undefined ? {} : { cwd }), ...(env === undefined ? {} : { env }), stdin, stdout: 'pipe', stderr: 'pipe' })
+
+  await Promise.all([collect(proc.stdout, 'stdout', chunks), collect(proc.stderr, 'stderr', chunks)])
+  await proc.exited
+
+  const output = Buffer.concat(chunks.map(({ data }) => data))
+
+  return { code: exitCodeOf(proc.exitCode, proc.signalCode), chunks, output, text: output.toString() }
+}