@uknows/setup 0.0.0-stage → 0.2.0

package/lib/toml.mjs

@@ -0,0 +1,64 @@
+// A small TOML reader for the files this tool reads: pyproject.toml, uv.lock and poetry.lock. It reads tables,
+// strings, string arrays, keys and 1-line inline tables. It never writes TOML.
+
+/** The lines of 1 table, without its header. Array tables ([[x]]) end a table. */
+export function tomlTable(body, header) {
+  const out = []
+  let on = false
+  for (const line of (body ?? '').split(/\r?\n/)) {
+    const h = /^\s*\[([^\][]+)\]\s*(?:#.*)?$/.exec(line)
+    if (h) { on = h[1].trim() === header; continue }
+    if (/^\s*\[\[/.test(line)) { on = false; continue }
+    if (on) out.push(line)
+  }
+  return out.join('\n')
+}
+
+export const tomlString = (table, key) => new RegExp(`^\\s*${key}\\s*=\\s*(["'])([^"'\\n]*)\\1`, 'm').exec(table ?? '')?.[2] ?? null
+export const tomlKeys = (table) => (table ?? '').split('\n').map((l) => /^\s*"?([A-Za-z0-9_.-]+)"?\s*=/.exec(l)?.[1]).filter(Boolean)
+
+/** The strings of a string array, which can span lines. */
+export function tomlArray(table, key) {
+  const m = new RegExp(`^\\s*${key}\\s*=\\s*\\[`, 'm').exec(table ?? '')
+  if (!m) return []
+  const out = []
+  let quote = '', value = ''
+  for (const c of table.slice(m.index + m[0].length)) {
+    if (quote) { if (c === quote) { out.push(value); quote = ''; value = '' } else value += c }
+    else if (c === '"' || c === "'") quote = c
+    else if (c === ']') break
+  }
+  return out
+}
+
+/**
+ * A 1-line inline table, { path = "../shared", editable = true }, as an object of strings and booleans.
+ * null when the text is not an inline table.
+ */
+export function tomlInline(text) {
+  const m = /^\s*\{(.*)\}\s*(?:#.*)?$/.exec(text ?? '')
+  if (!m) return null
+  const out = {}
+  for (const pair of m[1].matchAll(/([A-Za-z0-9_-]+)\s*=\s*("(?:[^"\\]|\\.)*"|'[^']*'|true|false|[^,}\s]+)/g)) {
+    const raw = pair[2]
+    out[pair[1]] = raw === 'true' ? true : raw === 'false' ? false : /^["']/.test(raw) ? raw.slice(1, -1) : raw
+  }
+  return out
+}
+
+/** The key = value lines of 1 table, with 1-based line numbers in the whole file. */
+export function tomlEntries(body, header) {
+  const out = []
+  let on = false
+  ;(body ?? '').split(/\r?\n/).forEach((line, i) => {
+    const h = /^\s*\[([^\][]+)\]\s*(?:#.*)?$/.exec(line)
+    if (h) { on = h[1].trim() === header; return }
+    if (/^\s*\[\[/.test(line)) { on = false; return }
+    const kv = on && /^\s*["']?([A-Za-z0-9_.-]+)["']?\s*=\s*(.*?)\s*$/.exec(line)
+    if (kv) out.push({ key: kv[1], value: kv[2].replace(/\s+#.*$/, ''), line: i + 1 })
+  })
+  return out
+}
+
+/** PEP 503 name: lower case, runs of - _ . become -. */
+export const pyName = (name) => String(name).toLowerCase().replace(/[-_.]+/g, '-')

package/lib/types.mjs

@@ -0,0 +1,208 @@
+/*
+ * Shared types for @uknows/setup. JSDoc only: this module has no runtime code.
+ * Import types with: @typedef {import('./types.mjs').Service} Service
+ *
+ * Path rule: every path in these types, in the manifest and in the --json
+ * report is relative to the repo root (the --path folder, default the current
+ * folder) and uses '/' on every OS. The root folder itself is '.'.
+ */
+
+/** @typedef {'node'|'python'|'dotnet'|'java'|'go'|'php'|'ruby'} Lang */
+/** @typedef {Lang|'otel'} StackId  Same ids as contract STACKS. 'otel' = the app already uses OpenTelemetry: settings only. */
+/**
+ * @typedef {'standard'|'otel'|'azure-monitor'|'stop'} Mode  How the tool sets up 1 service.
+ *   standard: no OpenTelemetry yet, the 5 settings. otel: OpenTelemetry already, 3 settings. azure-monitor: keep
+ *   Azure Monitor and add 1 exporter beside it, 3 settings. stop: another APM agent or an unknown wrapper, change nothing (exit 1).
+ */
+/** @typedef {'azure-container-apps'|'kubernetes'|'alibaba-sae'|'vm-docker'|'github-actions'} HostId  Same ids as contract HOSTS. */
+
+/**
+ * @typedef {{file: string, line?: number, what: string}} Evidence  `what` is plain English, e.g. 'express in dependencies'.
+ *   Host evidence can name a file above the --path folder in the same git repo, as '../../k8s/api.yaml'. It is shown, never written.
+ */
+/** @typedef {{code: string, message: string}} Problem  `message` is 1 plain-English sentence. */
+
+/**
+ * @typedef {Object} Start  How the service starts, as the repo declares it.
+ * @property {'dockerfile'|'package.json'|'procfile'|'answer'} kind  'answer' = the user typed it at the prompt (file '', line 0).
+ * @property {string} file
+ * @property {number} line          1-based line of the ENTRYPOINT/CMD (ENTRYPOINT when both), the "start" key, or the web: line.
+ * @property {'exec'|'shell'} form  exec = Dockerfile JSON array. Everything else is shell.
+ * @property {string} raw           The command text. Dockerfile: ENTRYPOINT then CMD args, as written.
+ * @property {string[]|null} argv   Literal argv when the text has no shell syntax, else null.
+ */
+
+/**
+ * @typedef {Object} K8sTarget  A container in a plain Kubernetes manifest that runs this service.
+ * @property {string} file          e.g. 'k8s/api.yaml'
+ * @property {number} doc           0-based index of the YAML document in the file ('---' separated)
+ * @property {string} container     the container name
+ * @property {Record<string, string|null>} env  Its env list: name -> value, null for valueFrom. It replaces the image ENV.
+ * @property {boolean} command      It sets command:, which replaces the image ENTRYPOINT and CMD.
+ * @property {boolean} args         It sets args:, which replaces the image CMD.
+ */
+
+/**
+ * @typedef {Object} Service  One deployable app folder.
+ * @property {string} dir                 '.' or 'services/api'
+ * @property {Lang|null} lang             null = nothing recognized. The CLI then shows the language menu.
+ * @property {string[]} frameworks        Canonical ids, sorted:
+ *   node: express fastify nestjs koa hapi nitro nuxt next | python: fastapi django flask starlette falcon tornado
+ *   dotnet: aspnetcore | java: spring-boot quarkus micronaut keycloak (a Keycloak image with no manifest) | go: echo gin chi | php: laravel symfony slim | ruby: rails sinatra
+ * @property {string[]} manifests         Manifest paths in this folder, sorted.
+ * @property {string} name                Proposed OTEL_SERVICE_NAME: [a-z0-9-], 1 to 63 chars, no leading or trailing '-'.
+ * @property {string} nameFrom            'existing' (an OTEL_SERVICE_NAME already in the repo), a manifest basename, or 'folder'.
+ * @property {string|null} dockerfile     The Dockerfile that builds this service.
+ * @property {Start|null} start           The single start declaration. null when there is none or it is ambiguous (see problems).
+ * @property {string|null} runtimeVersion Version from the final FROM image tag ('3.12', '8.0', '22'), else from an exact declaration
+ *                                        (.python-version, TargetFramework 'net8.0' -> '8.0', go directive). Ranges such as
+ *                                        requires-python do not count. null when unknown.
+ * @property {K8sTarget[]} k8s            Plain k8s containers that run this service. Files with '{{' (Helm) are never listed.
+ * @property {Problem[]} problems         codes: start-ambiguous, start-hooks, start-unknown, dockerfile-ambiguous, frontend
+ * @property {Evidence[]} evidence        Why this folder is a service.
+ * @property {Mode} [mode]                Set by detection when it knows. Without it, the engine classifies the service (existing.mjs classify).
+ */
+
+/**
+ * @typedef {Object} Host
+ * @property {HostId} id
+ * @property {Evidence[]} evidence        Empty for the vm-docker fallback.
+ */
+
+/**
+ * @typedef {Object} Detection  What detect() returns. Static reading only: no commands, no network.
+ * @property {string} root                Absolute native path of the repo root.
+ * @property {Service[]} services         Sorted by dir. When nothing is recognized: 1 service {dir: '.', lang: null}.
+ * @property {Host[]} hosts               Runtime hosts in HOSTS order, then 'github-actions'. Never empty ('vm-docker' fallback).
+ * @property {Problem[]} problems         Repo-level notes, such as skipped large files.
+ */
+
+/** @typedef {{vendor: string, evidence: Evidence[]}} Apm  vendor: Datadog, New Relic, Elastic APM, Azure Monitor, Dynatrace, Instana or Sentry. */
+
+/**
+ * @typedef {Evidence & {kind: string, value?: string}} Anchor  A line in source code or a deploy file that matters.
+ *   kind: azure-call, appinsights-call, phoenix, provider, otlp-signal, sampling, service-name, connection-string,
+ *   auto-attach, sampler-env. value: what the line sets, when the rule reads it.
+ */
+
+/**
+ * @typedef {Object} Existing  What findExisting() returns for 1 service. It reads the service and its first-party members.
+ * @property {Evidence[]} otel            OpenTelemetry SDK-level packages or agents already in use.
+ * @property {Apm[]} apm                  Other APM agents. Any entry stops the run (exit 1).
+ * @property {(Evidence & {version?: string|null})[]} [azure]    Azure Monitor OpenTelemetry packages, and App Insights 3.x: azure-monitor mode.
+ * @property {(Evidence & {version?: string|null})[]} [classic]  App Insights that UKNOWS cannot join (.NET 2.x, Node 2.x, OpenCensus, Java): stop.
+ * @property {Evidence[]} [browser]       The browser App Insights SDK: a note only.
+ * @property {Evidence[]} [tracers]       Phoenix, openinference, langfuse, traceloop, logfire: allowed, with advice about the key.
+ * @property {Anchor[]} [anchors]
+ * @property {import('./members.mjs').LocalPackage[]} [local]   Wheels, sdists, .tgz, .nupkg files and local NuGet sources.
+ * @property {import('./members.mjs').Member[]} [members]       uv workspace members, path sources, file: packages, project references.
+ * @property {import('./locks.mjs').InstalledSet} [installed]   The lock closure.
+ */
+
+/**
+ * @typedef {Object} Classification  What classify() returns.
+ * @property {Mode} mode
+ * @property {'apm'|'classic'|'wrapper'|'local'|null} reason   Why it stops.
+ * @property {Evidence[]} [classic]
+ * @property {{package: import('./locks.mjs').Installed, sdk: import('./locks.mjs').Installed, limit: {name: string, spec: string|null, line?: number}|null, need: string|null}} [wrapper]
+ * @property {import('./members.mjs').LocalPackage} [local]
+ */
+
+/**
+ * @typedef {Object} Edit  One change to one text file.
+ * @property {string} file                Repo-relative path.
+ * @property {string|null} before         Exactly ctx.ws.read(file) when the producer read it (BOM removed). null = new file.
+ * @property {string} after               The full new text, without BOM. The engine puts the original BOM back.
+ * @property {string} why                 1 plain-English sentence, e.g. 'Load OpenTelemetry when node starts.'
+ */
+
+/**
+ * @typedef {Object} Command  A package manager run. The engine runs it after it writes the edits, only on apply.
+ * @property {string} cwd                 Repo-relative folder to run in.
+ * @property {string} cmd                 'npm' | 'pnpm' | 'yarn', or for kind 'lock' 'uv' | 'poetry' | 'dotnet'
+ * @property {'lock'} [kind]              A lock refresh (uv lock, poetry lock, dotnet restore --force-evaluate). The manifest records
+ *                                        the files in touches as text changes, not as packages, so remove restores them byte for
+ *                                        byte. undo is null. When it fails, the engine prints the resolver text and puts every file back.
+ * @property {{file: string, pattern: string}[]} [keep]  kind 'lock': a line (regex, m flag) that must not change, such as
+ *                                        '^version = \\d+$' in uv.lock. When it changes, the run is rolled back.
+ * @property {{assets: string, library: string, range: string[], package: string, version: string}} [verify]  dotnet restore: after
+ *                                        it, obj/project.assets.json must not show `library` in `range` (the build check would then
+ *                                        need `package`). When it does, the run is rolled back (dotnet.mjs verifyRestore).
+ * @property {string[]} args              Exact argv, e.g. ['install', '--save', '@opentelemetry/api', '@opentelemetry/auto-instrumentations-node'].
+ * @property {string[]} touches           Repo-relative files it changes. The engine restores them when any step fails.
+ * @property {string[]} added             Packages it adds that were not there before. The manifest records them.
+ * @property {boolean} [lockOnly]         It writes only the files in touches (no node_modules).
+ * @property {{cmd: string, args: string[]}} undo   Removes `added`. The remove command runs it.
+ * @property {string} why                 Plan sentence, e.g. 'Add @opentelemetry/api and @opentelemetry/auto-instrumentations-node with npm.'
+ */
+
+/** @typedef {{caption: string, language: string, code: string}} Snippet  Same shape as contract snippets. */
+
+/**
+ * @typedef {Object} Block  A printable section: a manual step, a key step or a stop reason.
+ * @property {string} title               Sentence case, no final period, e.g. 'Set your key once on Kubernetes'.
+ * @property {string[]} lines             Plain-English sentences. The CLI prints them as a numbered list.
+ * @property {Snippet[]} [snippets]
+ * @property {boolean} [required]         Manual steps only. false = advice (sampling, role name, Phoenix, Alpine): printed under
+ *                                        "Advice", never counts toward exit 3. Missing or true = a step traces need. The engine
+ *                                        sets it on every manual block of the --json report.
+ */
+
+/** @typedef {{name: string, value: string}} Setting */
+
+/**
+ * @typedef {Object} Ctx  What appliers and settingsPlan() get.
+ * @property {import('./workspace.mjs').Workspace} ws   Reads include the edits staged earlier in this run.
+ * @property {string} name                The final OTEL_SERVICE_NAME of this service.
+ * @property {Detection} detection
+ * @property {import('./workspace.mjs').RepoView} [repo]  Reads files above the root too ('../x'), for --path runs. Never written.
+ * @property {string} [endpoint]          The ingest address for OTEL_EXPORTER_OTLP_ENDPOINT. Default: INGEST_ENDPOINT.
+ * @property {Mode} [mode]                The mode of this service. settingsPlan() and the azure applier read it. Default: standard.
+ * @property {Existing} [existing]        What findExisting() found for this service.
+ * @property {import('./locks.mjs').InstalledSet} [installed]  The lock closure (existing.installed).
+ * @property {Record<string, string|null>} [tools]  Local tools probed before planning: name -> version, null when missing.
+ *                                        uv and poetry: their version. dotnet: the newest SDK of dotnet --list-sdks.
+ *                                        Missing key: not probed (unit tests), so the applier assumes the tool is there.
+ */
+
+/**
+ * @typedef {Object} StackPlan  What Applier.plan() returns.
+ * @property {string[]} summary           Plan sentences, e.g. 'Load OpenTelemetry when node starts (NODE_OPTIONS in Dockerfile).'
+ * @property {Edit[]} edits
+ * @property {Command[]} commands
+ * @property {Setting[]} extraSettings    Settings to place with the 5, e.g. DJANGO_SETTINGS_MODULE or OTEL_PHP_AUTOLOAD_ENABLED.
+ * @property {Block[]} manual             Steps for the user. Any entry without required: false makes the run exit 3.
+ * @property {string[]} notes             Warnings and tips, 1 sentence each.
+ * @property {boolean} [stop]             Change nothing for this service, settings included: the user must run this tool elsewhere.
+ */
+
+/**
+ * @typedef {Object} Applier
+ * @property {StackId} id
+ * @property {(service: Service, ctx: Ctx) => StackPlan} plan
+ *   Pure: reads ctx.ws only. Never writes, runs, prompts or reads process.env.
+ *   Idempotent: planning its own output returns no edits and no commands.
+ */
+
+/**
+ * @typedef {Object} SettingsPlan  What settingsPlan() returns.
+ * @property {{kind: 'dockerfile'|'k8s'|'env-file', file: string}} target
+ * @property {Edit[]} edits               Empty when every setting is already there with the right value.
+ * @property {string[]} summary
+ * @property {Block[]} manual             e.g. a key committed in the repo, or an endpoint that points at another collector. Required ones: exit 3.
+ * @property {string[]} notes
+ */
+
+/**
+ * @typedef {Object} CheckResult  What runCheck() returns.
+ * @property {boolean} ok
+ * @property {number|null} status         HTTP status. null on a network error.
+ * @property {string|null} workspace
+ * @property {string|null} environment
+ * @property {string|null} [keyState]     From the site: active, retiring, or revoked. null when the site was not asked.
+ * @property {string[]} lines             What to print. Never contains the key.
+ * @property {boolean} [notReady]         A new key that UKNOWS did not get ready within 2 minutes (check.mjs NEW_KEY).
+ * @property {0|1|2} exit                 0 reached, 1 rejected or network error, 2 OTEL_EXPORTER_OTLP_HEADERS is not set.
+ */
+
+export {}

package/lib/ui.mjs

@@ -0,0 +1,225 @@
+/*
+ * Terminal input and output. Normal text goes to stdout and errors to stderr. With --json, normal text is left out,
+ * so stdout holds only the JSON report, and nothing ever prompts. Color, the spinner and single key presses are only
+ * for a real terminal: in a pipe, a log or a test, the text is plain and every line ends.
+ */
+import { createInterface } from 'node:readline'
+import { HOSTS, STACKS } from './contract.mjs'
+
+/** A usage error: exit 2 with the message and a hint to run --help. */
+export class UsageError extends Error {}
+
+const FRAMEWORKS = { express: 'Express', fastify: 'Fastify', nestjs: 'NestJS', koa: 'Koa', hapi: 'Hapi', nitro: 'Nitro',
+  nuxt: 'Nuxt', next: 'Next.js', fastapi: 'FastAPI', django: 'Django', flask: 'Flask', starlette: 'Starlette',
+  falcon: 'Falcon', tornado: 'Tornado', aspnetcore: 'ASP.NET Core', 'spring-boot': 'Spring Boot', quarkus: 'Quarkus',
+  micronaut: 'Micronaut', keycloak: 'Keycloak', echo: 'Echo', gin: 'Gin', chi: 'chi', laravel: 'Laravel', symfony: 'Symfony', slim: 'Slim',
+  rails: 'Rails', sinatra: 'Sinatra', 'azure-functions': 'Azure Functions' }
+
+export const stackLabel = (id) => STACKS.find((s) => s.id === id)?.label ?? 'an unknown stack'
+/** Azure Functions is a host of the setup tool before it is one of the docs page (FUNCTIONS in the contract). */
+export const hostLabel = (id) => HOSTS.find((h) => h.id === id)?.label ?? (id === 'azure-functions' ? 'Azure Functions' : id)
+export const frameworkLabel = (id) => FRAMEWORKS[id] ?? id
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+export const unique = (list) => [...new Set(list)]
+/** 'a', 'a and b', 'a, b and c'. */
+export const list = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names.join(''))
+
+/** Color only on a terminal that shows it: not with NO_COLOR, not on TERM=dumb. FORCE_COLOR turns it on. */
+export function colorOn(stream, env = process.env) {
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== '0') return true
+  if ('NO_COLOR' in env && env.NO_COLOR !== '') return false
+  return Boolean(stream?.isTTY) && env.TERM !== 'dumb'
+}
+
+/** The old Windows console shows no braille or check marks. Windows Terminal (WT_SESSION) does. */
+const unicode = (env = process.env, platform = process.platform) => platform !== 'win32' || Boolean(env.WT_SESSION || env.TERM_PROGRAM)
+
+/**
+ * Wrap text to width, by words. Each line after the first starts with indent. A word longer than the line (a link)
+ * stays whole. Color codes do not count toward the width.
+ */
+export function wrap(text, width = 80, indent = '') {
+  const visible = (s) => s.replace(/\u001b\[[0-9;]*m/g, '').length
+  // Spaces at the start of the text stay, and the lines after the first keep them too.
+  const lead = /^ */.exec(String(text))[0]
+  indent += lead
+  const lines = []
+  let line = lead
+  for (const word of String(text).slice(lead.length).split(/ +/)) {
+    if (line === lead) { line += word; continue }
+    if (visible(line) + 1 + visible(word) > width) { lines.push(line); line = `${indent}${word}` } else line += ` ${word}`
+  }
+  lines.push(line)
+  return lines
+}
+
+/**
+ * @param {{stdin?: any, stdout?: any, stderr?: any, json?: boolean, interactive?: boolean, terminal?: boolean,
+ *   env?: Record<string, string|undefined>}} [io]
+ *   interactive defaults to: stdin and stdout are terminals and json is off.
+ *   terminal defaults to: stdout is a terminal and json is off. Then --yes still checks a key set in this terminal.
+ */
+export function createUI({ stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, json = false, interactive, terminal, env = process.env } = {}) {
+  let rl = null, closed = false, detaching = false
+  const queue = [], waiting = []
+  const nextLine = () => {
+    if (!rl) {
+      rl = createInterface({ input: stdin, terminal: false })
+      rl.on('line', (line) => (waiting.length ? waiting.shift()(line) : queue.push(line)))
+      rl.on('close', () => { if (detaching) return; closed = true; while (waiting.length) waiting.shift()(null) })
+    }
+    if (queue.length) return Promise.resolve(queue.shift())
+    return closed ? Promise.resolve(null) : new Promise((resolve) => waiting.push(resolve))
+  }
+  /** Stop reading lines for a while, so single key presses do not end up as answers. The next question reads again. */
+  const detach = () => {
+    if (!rl || waiting.length) return
+    detaching = true
+    rl.close()
+    rl = null
+    detaching = false
+  }
+  // A line that the spinner owns: it is cleared before any other text, so text never runs into it.
+  let live = null
+  const clearLive = () => { if (live) { stdout.write('\r\u001b[2K'); live.drawn = false } }
+  const print = (text = '') => { if (!json) { clearLive(); stdout.write(`${text}\n`) } }
+  /** null when input ended. */
+  const prompt = (question) => { clearLive(); stdout.write(`${question} `); return nextLine() }
+  const color = !json && colorOn(stdout, env)
+  const paint = (code) => (text) => (color ? `\u001b[${code}m${text}\u001b[0m` : String(text))
+  const cyan = paint('36')
+  const fancy = unicode(env)
+  const tty = Boolean(stdout.isTTY) && !json
+  // Only a terminal gets text wrapped to its width. A pipe or a log keeps each line whole.
+  const columns = () => (tty ? Math.max(40, Math.min(Number(stdout.columns) || 80, 100)) : 1000)
+  const FRAMES = fancy ? ['\u280b', '\u2819', '\u2839', '\u2838', '\u283c', '\u2834', '\u2826', '\u2827', '\u2807', '\u280f'] : ['-', '\\', '|', '/']
+  const marks = { done: fancy ? '\u2713' : '+', failed: fancy ? '\u2717' : 'x' }
+
+  return {
+    interactive: interactive ?? Boolean(stdin.isTTY && stdout.isTTY && !json),
+    terminal: terminal ?? Boolean(stdout.isTTY && !json),
+    /** True when the screen is a real terminal: the spinner and the redrawn line work there. */
+    tty,
+    color,
+    columns,
+    marks,
+    bold: paint('1'),
+    dim: paint('2'),
+    cyan,
+    red: paint('31'),
+    print,
+    error: (text) => { clearLive(); stderr.write(`${text}\n`) },
+    /** Print text wrapped to the terminal, with indent before every line and hang after the first. */
+    say(text = '', indent = '', hang = '') {
+      for (const line of wrap(text, columns() - indent.length, hang)) print(`${indent}${line}`)
+    },
+    /** @param {import('./types.mjs').Block} block */
+    block(block) {
+      print(block.title)
+      block.lines.forEach((line, i) => print(`  ${i + 1}. ${line}`))
+      for (const s of block.snippets ?? []) {
+        print(`  ${s.caption}:`)
+        for (const line of s.code.split('\n')) print(`      ${line}`)
+      }
+      print()
+    },
+    /**
+     * A line that shows work in progress: a spinner and text() on a terminal, redrawn 10 times a second, else nothing.
+     * end(line) puts the last line in its place. Only 1 at a time.
+     */
+    progress(text, indent = '') {
+      if (!tty) return { end: (line) => { if (line !== null) print(line) }, stop() {} }
+      let frame = 0
+      const self = { drawn: false }
+      const draw = () => {
+        const body = typeof text === 'function' ? text() : text
+        const line = `${indent}${cyan(FRAMES[frame++ % FRAMES.length])} ${body}`
+        stdout.write(`\r\u001b[2K${line.length > columns() + 10 ? line.slice(0, columns() + 10) : line}`)
+        self.drawn = true
+      }
+      live = self
+      draw()
+      const timer = setInterval(() => { if (live === self) draw() }, 100)
+      const stop = () => { clearInterval(timer); if (live === self) { clearLive(); live = null } }
+      return { end: (line) => { stop(); if (line !== null) print(line) }, stop }
+    },
+    /**
+     * Single key presses on a terminal: next() gives 'enter', 'ctrl-c' or the key, as a person presses it. null when
+     * this is no terminal (a pipe or a test): then nothing reads keys. close() gives the input back to the questions.
+     */
+    keys() {
+      if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
+      detach()
+      const pending = [], readers = []
+      const onData = (chunk) => {
+        for (const ch of chunk.toString('utf8')) {
+          const key = ch === '\r' || ch === '\n' ? 'enter' : ch === '\u0003' ? 'ctrl-c' : ch === '\u0004' ? 'ctrl-d' : ch.toLowerCase()
+          if (readers.length) readers.shift()(key); else pending.push(key)
+        }
+      }
+      stdin.setRawMode(true)
+      stdin.on('data', onData)
+      stdin.resume()
+      let open = true
+      return {
+        next: () => (pending.length ? Promise.resolve(pending.shift()) : new Promise((resolve) => readers.push(resolve))),
+        close() {
+          if (!open) return
+          open = false
+          stdin.off('data', onData)
+          stdin.setRawMode(false)
+          stdin.pause()
+          while (readers.length) readers.shift()(null)
+        },
+      }
+    },
+    async ask(question) { return ((await prompt(question)) ?? '').trim() },
+    /** Like ask, but null when input ended, so an empty answer and no answer differ. */
+    async line(question) { const answer = await prompt(question); return answer === null ? null : answer.trim() },
+    /**
+     * Read 1 line without showing it, for a key. In a terminal, raw mode stops the echo. Backspace works,
+     * Ctrl-C and Ctrl-D skip. Without a terminal (tests, pipes) it reads a plain line. Never stores the answer.
+     */
+    async secret(question) {
+      const raw = stdin.isTTY && typeof stdin.setRawMode === 'function'
+      if (raw) stdin.setRawMode(true)
+      let line
+      try { line = await prompt(question) } finally { if (raw) { stdin.setRawMode(false); stdout.write('\n') } }
+      let out = ''
+      for (const ch of line ?? '') {
+        if (ch === '\u0003' || ch === '\u0004') return ''
+        if (ch === '\u007f' || ch === '\b') out = out.slice(0, -1)
+        else if (ch === '\u0015') out = ''
+        else if (ch >= ' ') out += ch
+      }
+      return out
+    },
+    /** Y/n. Empty means yes, or no when yes is false (a y/N question). Ended input means no. */
+    async confirm(question, yes = true) {
+      for (let tries = 0; tries < 3; tries++) {
+        const answer = await prompt(question)
+        if (answer === null) return false
+        const a = answer.trim().toLowerCase()
+        if (a === '') return yes
+        if (a === 'y' || a === 'yes') return true
+        if (a === 'n' || a === 'no') return false
+        print('Type y or n.')
+      }
+      return false
+    },
+    /** A numbered menu. Returns the 0-based index. 3 bad answers: usage error. */
+    async choose(title, options) {
+      print(title)
+      options.forEach((option, i) => print(`  ${i + 1}. ${option}`))
+      for (let tries = 0; tries < 3; tries++) {
+        const answer = await prompt(`Type a number from 1 to ${options.length}:`)
+        if (answer === null) break
+        const n = Number(answer.trim())
+        if (Number.isInteger(n) && n >= 1 && n <= options.length) return n - 1
+        print(`Type a number from 1 to ${options.length}.`)
+      }
+      throw new UsageError('No choice was made.')
+    },
+    close() { if (live) { clearLive(); live = null } rl?.close() },
+  }
+}