@kaynooo/cli-kit 0.0.0-stage → 0.7.3

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() }
+}

package/src/progress.ts

@@ -0,0 +1,211 @@
+import type { Colors } from './style'
+import process from 'node:process'
+import { formatDuration } from './format'
+import { holdSignals } from './process'
+import { marked, paint, takesControlCodes } from './style'
+
+export interface Progress {
+  step: string
+  done?: number | undefined
+  total?: number | undefined
+  unit?: string | undefined
+}
+
+interface ProgressStream {
+  isTTY?: boolean
+  columns?: number | undefined
+  write: (text: string) => unknown
+}
+
+export interface ProgressLine {
+  update: (progress: Progress) => void
+  // Clears the line and leaves nothing behind.
+  stop: () => void
+  // Clears the line and leaves `✓ <text> <time since the line began>` in its place.
+  done: (text: string) => void
+  // Clears the line and leaves `✗ <text>` in its place.
+  failed: (text: string) => void
+}
+
+type Env = Record<string, string | undefined>
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+const FRAME_MS = 80
+const BAR_WIDTH = 20
+// Back to the start of the line, then erases it.
+const CLEAR_LINE = '\r\x1B[2K'
+// 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`),
+    }
+  }
+
+  const colors = paint(stream, env)
+  // Its own write, taken before the line 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
+  const clear = () => {
+    if (drawn)
+      write(CLEAR_LINE)
+
+    drawn = false
+  }
+  const draw = () => {
+    if (current === undefined)
+      return
+
+    // A terminal that does not say its width, as a pseudo-terminal may, answers 0.
+    const width = (stream.columns === undefined || stream.columns === 0 ? 80 : stream.columns) - 1
+
+    write(`${CLEAR_LINE}${fit(progressParts(current, FRAMES[frame++ % FRAMES.length]!, performance.now() - started), width, colors)}`)
+    drawn = true
+  }
+  const timer = setInterval(draw, FRAME_MS)
+  const restore = interceptOutput(clear)
+  const onExit = () => clear()
+  // Interrupted, the line goes before the shell's prompt comes back.
+  const signals = holdSignals(stop)
+
+  function stop() {
+    clearInterval(timer)
+    clear()
+    restore()
+    process.off('exit', onExit)
+    signals.release()
+  }
+
+  timer.unref()
+  process.on('exit', onExit)
+
+  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) => {
+      const step = current?.step
+
+      current = progress
+
+      if (progress.step !== step) {
+        started = performance.now()
+        draw()
+      }
+    },
+    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`)
+    },
+  }
+}
+
+// Runs one step under a spinner on a terminal, then leaves `✓ <label> <time>`, or `✗ <label>` and throws again; off a terminal those lines alone print, as `ok:` and `error:`.
+export async function task<T>(label: string, run: (update: (progress: Omit<Progress, 'step'>) => void) => Promise<T>, stream: ProgressStream = process.stderr, env: Env = process.env): Promise<T> {
+  const line = progressLine(stream, env)
+
+  line.update({ step: label })
+
+  try {
+    const result = await run(progress => line.update({ ...progress, step: label }))
+
+    line.done(label)
+
+    return result
+  }
+  catch (error) {
+    line.failed(label)
+
+    throw error
+  }
+}
+
+// `⠹ prerendering ████████░░░░░░░░░░░░ 8/20 routes 4.2s`; a step with no total has no bar.
+export function progressText(progress: Progress, spinner: string, ms: number): string {
+  return progressParts(progress, spinner, ms).map(part => part.text).join('')
+}
+
+function progressParts({ step, done, total, unit }: Progress, spinner: string, ms: number): Part[] {
+  const parts: Part[] = [{ text: spinner, tint: colors => colors.cyan }, { text: ` ${step}`, tint: () => plain }]
+
+  if (total !== undefined && total > 0) {
+    const counted = Math.min(done ?? 0, total)
+    const filled = Math.round(counted / total * BAR_WIDTH)
+
+    parts.push(
+      { text: ' ', tint: () => plain },
+      { text: '█'.repeat(filled), tint: colors => colors.cyan },
+      { text: '░'.repeat(BAR_WIDTH - filled), tint: colors => colors.dim },
+      { text: ` ${counted}/${total}${unit === undefined ? '' : ` ${unit}`}`, tint: colors => colors.dim },
+    )
+  }
+
+  parts.push({ text: ` ${(ms / 1000).toFixed(1)}s`, tint: colors => colors.dim })
+
+  return parts
+}
+
+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 {
+  let room = width
+  let line = ''
+
+  for (const { text, tint } of parts) {
+    const kept = [...text].slice(0, Math.max(room, 0)).join('')
+
+    room -= kept.length
+
+    if (kept !== '')
+      line += tint(colors)(kept)
+  }
+
+  return line
+}
+
+// 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.
+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]) => {
+    const original = Reflect.get(target, name) as (...args: unknown[]) => unknown
+    const wrapper = (...args: unknown[]) => {
+      clear()
+
+      return original.apply(target, args)
+    }
+
+    Reflect.set(target, name, wrapper)
+
+    return { target, name, original, wrapper }
+  })
+
+  // What the caller replaced meanwhile is its own, and stays.
+  return () => {
+    for (const { target, name, original, wrapper } of wrapped) {
+      if (Reflect.get(target, name) === wrapper)
+        Reflect.set(target, name, original)
+    }
+  }
+}