groundwork-method 0.0.1 → 0.11.0

package/src/generators/workspace-dev-cli/cli-src/src/theme/render.ts

@@ -0,0 +1,158 @@
+/**
+ * The render layer — the typographic and structural vocabulary of the CLI.
+ *
+ * This is the Node port of the bash `_ui.sh` helpers, rebuilt on the brand-token
+ * painter so output is themed from the design system rather than hard-coded. It is
+ * the shared surface both `./dev` and the `cli-app` starter render through.
+ *
+ * All human chrome is written to stderr so stdout stays clean for `--json` and pipes.
+ */
+
+import { Painter, detectCaps } from './color';
+import { BrandTokens, mergeTokens, SymbolName } from './tokens';
+
+const PAD = '  ';
+
+export class Renderer {
+  readonly painter: Painter;
+  private readonly tokens: BrandTokens;
+  private spinnerTimer: NodeJS.Timeout | null = null;
+  private spinnerText = '';
+
+  constructor(tokens: BrandTokens, stream: NodeJS.WriteStream = process.stderr) {
+    this.tokens = tokens;
+    this.out = stream;
+    this.painter = new Painter(tokens, detectCaps(stream));
+  }
+
+  private out: NodeJS.WriteStream;
+
+  /** A twin renderer bound to a different stream (e.g. stdout for command *results*,
+   *  while progress and spinners stay on stderr). */
+  asStream(stream: NodeJS.WriteStream): Renderer {
+    return new Renderer(this.tokens, stream);
+  }
+
+  private sym(name: SymbolName): string {
+    const t = this.tokens.terminal?.symbols?.[name];
+    if (!t) return '';
+    return this.painter.caps.unicode ? t.unicode : t.ascii;
+  }
+
+  private write(line: string): void {
+    this.out.write(line + '\n');
+  }
+
+  logo(subtitle?: string): void {
+    const { wordmark, appName } = this.tokens.identity;
+    const mark = this.painter.primary(`${wordmark} ${appName}`.trim());
+    this.write('');
+    this.write(subtitle ? `${PAD}${this.painter.bold(mark)} ${this.painter.dim('— ' + subtitle)}` : `${PAD}${this.painter.bold(mark)}`);
+    this.write('');
+  }
+
+  step(text: string): void {
+    this.write(`\n${PAD}${this.painter.primary(this.sym('step'))} ${this.painter.bold(text)}`);
+  }
+
+  substep(text: string): void {
+    this.write(`${PAD}${PAD}${this.painter.dim(`${this.sym('substep')} ${text}`)}`);
+  }
+
+  info(text: string): void {
+    this.write(`${PAD}${this.painter.dim(this.sym('info'))} ${text}`);
+  }
+
+  success(text: string): void {
+    this.write(`${PAD}${this.painter.paint('success', this.sym('success'))} ${text}`);
+  }
+
+  error(text: string): void {
+    this.write(`${PAD}${this.painter.paint('error', this.sym('error'))} ${text}`);
+  }
+
+  warn(text: string): void {
+    this.write(`${PAD}${this.painter.paint('warning', this.sym('warning'))} ${text}`);
+  }
+
+  category(text: string): void {
+    this.write(`\n${PAD}${this.painter.dim('■')} ${this.painter.paint('header', text)}`);
+  }
+
+  cmd(name: string, desc: string): void {
+    this.write(`    ${this.painter.paint('accent', name.padEnd(15))} ${desc}`);
+  }
+
+  /** A boxed error card with an optional action line. */
+  errorCard(msg: string, action?: string): void {
+    const bar = this.painter.paint('error', '│');
+    this.write('');
+    this.write(`${PAD}${this.painter.paint('error', '╭' + '─'.repeat(58) + '╮')}`);
+    this.write(`${PAD}${bar}  ${this.painter.paint('error', this.sym('error'))} ${this.painter.bold('ERROR:')} ${msg}`);
+    if (action) {
+      this.write(`${PAD}${bar}`);
+      this.write(`${PAD}${bar}  ${this.painter.dim('Action required:')}`);
+      this.write(`${PAD}${bar}  ${this.painter.paint('accent', this.sym('active'))} ${action}`);
+    }
+    this.write(`${PAD}${this.painter.paint('error', '╰' + '─'.repeat(58) + '╯')}`);
+    this.write('');
+  }
+
+  /** A simple three-column table for status output. */
+  table(title: string, rows: Array<[string, string, string]>): void {
+    this.write(`${PAD}${this.painter.dim('╭─')} ${this.painter.bold(title)}`);
+    if (rows.length === 0) {
+      this.write(`${PAD}${this.painter.dim('│')}  ${this.painter.dim('(none)')}`);
+    }
+    for (const [a, b, c] of rows) {
+      this.write(`${PAD}${this.painter.dim('│')}  ${a.padEnd(28)} ${b.padEnd(16)} ${this.painter.dim(c)}`);
+    }
+    this.write(`${PAD}${this.painter.dim('╰' + '─'.repeat(40))}`);
+  }
+
+  // --- Spinner (TTY only; degrades to a static line) -------------------------
+
+  startSpinner(text: string): void {
+    this.spinnerText = text;
+    if (!this.painter.caps.isTTY) {
+      this.write(`${PAD}${this.painter.dim(this.sym('info'))} ${text}...`);
+      return;
+    }
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const asciiFrames = ['|', '/', '-', '\\'];
+    const set = this.painter.caps.unicode ? frames : asciiFrames;
+    let i = 0;
+    this.out.write('\x1b[?25l'); // hide cursor
+    this.spinnerTimer = setInterval(() => {
+      const frame = this.painter.primary(set[i % set.length]);
+      this.out.write(`\r${PAD}${frame} ${this.spinnerText}`);
+      i += 1;
+    }, 90);
+  }
+
+  stopSpinner(successMsg: string, elapsed?: string): void {
+    if (this.spinnerTimer) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+      this.out.write('\r\x1b[K'); // clear line
+      this.out.write('\x1b[?25h'); // restore cursor
+    }
+    const time = elapsed ? ` ${this.painter.dim(`(${elapsed})`)}` : '';
+    this.success(`${successMsg}${time}`);
+  }
+
+  failSpinner(failMsg: string): void {
+    if (this.spinnerTimer) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+      this.out.write('\r\x1b[K');
+      this.out.write('\x1b[?25h');
+    }
+    this.error(failMsg);
+  }
+}
+
+/** Build a renderer from a (possibly partial) tokens object loaded from disk. */
+export function makeRenderer(partialTokens: unknown, stream?: NodeJS.WriteStream): Renderer {
+  return new Renderer(mergeTokens(partialTokens), stream);
+}

package/src/generators/workspace-dev-cli/cli-src/src/theme/tokens.ts

@@ -0,0 +1,122 @@
+/**
+ * Brand tokens — the machine-readable projection of the design system's branding.
+ *
+ * This module is the shared theme contract. The `./dev` CLI is its first consumer;
+ * the `cli-app` product starter is the second. Both read a `dev.config.json` (itself
+ * projected from `.groundwork/config/brand-tokens.json`) and render from it.
+ *
+ * Keep this module free of `./dev`-specific logic so it can be extracted to a shared
+ * package when the second consumer lands. See the contract at
+ * groundwork-design-system/templates/brand-tokens.md.
+ */
+
+export type NoColorTreatment =
+  | 'bold'
+  | 'dim'
+  | 'underline'
+  | 'bold+upper'
+  | 'plain';
+
+export interface ColorRole {
+  truecolor: string | null; // "#rrggbb" or null
+  ansi256: number | null; // 0-255 or null
+  noColor: NoColorTreatment;
+}
+
+export type RoleName =
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'info'
+  | 'muted'
+  | 'accent'
+  | 'header'
+  | 'key'
+  | 'value';
+
+export interface SymbolToken {
+  unicode: string;
+  ascii: string;
+}
+
+export type SymbolName =
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'info'
+  | 'step'
+  | 'substep'
+  | 'active';
+
+export interface BrandTokens {
+  identity: {
+    appName: string;
+    wordmark: string;
+    primary: string; // "#rrggbb"
+    accent: string; // "#rrggbb"
+    voice: string;
+  };
+  terminal?: {
+    colorRoles: Record<RoleName, ColorRole>;
+    symbols: Record<SymbolName, SymbolToken>;
+    splash: { style: 'wordmark-line' | 'banner' | 'none'; tagline: string };
+    typography: Record<'header' | 'title' | 'body' | 'muted', string>;
+  };
+}
+
+/** The fallback theme used when no brand tokens are present. Mirrors the values in
+ *  the design-system colour exemplar so a themed and an un-themed CLI look like kin. */
+export const DEFAULT_TOKENS: BrandTokens = {
+  identity: {
+    appName: 'Workspace',
+    wordmark: '◢◤',
+    primary: '#5fafff',
+    accent: '#d7afff',
+    voice: 'clear, modern',
+  },
+  terminal: {
+    colorRoles: {
+      success: { truecolor: '#5faf87', ansi256: 72, noColor: 'bold' },
+      error: { truecolor: '#d75f5f', ansi256: 167, noColor: 'bold' },
+      warning: { truecolor: '#d7af5f', ansi256: 179, noColor: 'bold' },
+      info: { truecolor: '#5fafff', ansi256: 75, noColor: 'dim' },
+      muted: { truecolor: '#8a8a8a', ansi256: 245, noColor: 'dim' },
+      accent: { truecolor: '#d7afff', ansi256: 183, noColor: 'underline' },
+      header: { truecolor: null, ansi256: null, noColor: 'bold+upper' },
+      key: { truecolor: '#5fafff', ansi256: 75, noColor: 'plain' },
+      value: { truecolor: '#d0d0d0', ansi256: 252, noColor: 'plain' },
+    },
+    symbols: {
+      success: { unicode: '✔', ascii: 'OK' },
+      error: { unicode: '✖', ascii: 'x' },
+      warning: { unicode: '⚠', ascii: '!' },
+      info: { unicode: '●', ascii: '*' },
+      step: { unicode: '▶', ascii: '>' },
+      substep: { unicode: '↳', ascii: '-' },
+      active: { unicode: '❯', ascii: '>' },
+    },
+    splash: { style: 'wordmark-line', tagline: '' },
+    typography: {
+      header: 'bold + UPPERCASE',
+      title: 'bold + primary',
+      body: 'plain',
+      muted: 'dim',
+    },
+  },
+};
+
+/** Deep-merge a partial tokens object from dev.config.json over the defaults so a
+ *  Tier-1 file (identity only) still yields a complete, renderable theme. */
+export function mergeTokens(partial: unknown): BrandTokens {
+  const p = (partial ?? {}) as Partial<BrandTokens>;
+  const identity = { ...DEFAULT_TOKENS.identity, ...(p.identity ?? {}) };
+  const terminal = p.terminal
+    ? {
+        colorRoles: { ...DEFAULT_TOKENS.terminal!.colorRoles, ...p.terminal.colorRoles },
+        symbols: { ...DEFAULT_TOKENS.terminal!.symbols, ...p.terminal.symbols },
+        splash: { ...DEFAULT_TOKENS.terminal!.splash, ...p.terminal.splash },
+        typography: { ...DEFAULT_TOKENS.terminal!.typography, ...p.terminal.typography },
+      }
+    : DEFAULT_TOKENS.terminal;
+  return { identity, terminal };
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/context.ts

@@ -0,0 +1,43 @@
+import { Renderer } from '../theme/render';
+import { Runner } from './runners';
+import type { CommandDef } from '../registry';
+
+/** Raised by a command to abort with an error card and exit code 1, mirroring the
+ *  bash `fail()` helper. */
+export class CliError extends Error {
+  constructor(
+    message: string,
+    public readonly action?: string,
+  ) {
+    super(message);
+    this.name = 'CliError';
+  }
+}
+
+/** Raised for usage errors (bad/missing args, unknown flags) → exit code 2. */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+export interface Ctx {
+  /** Human-facing renderer (writes to stderr). */
+  r: Renderer;
+  /** Global --json mode: machine output to stdout, no spinners/chrome. */
+  json: boolean;
+  /** Positional args after the command verb. */
+  args: string[];
+  /** Project prefix (for container names etc.), from dev.config.json. */
+  projectPrefix: string;
+  /** Declared native runners (surfaces, sidecars) from dev.config.json. */
+  runners: Runner[];
+  /** The merged command registry (built-ins + project commands) — the single source
+   *  of truth shared by dispatch, `--help`, and completion. */
+  commands: CommandDef[];
+}
+
+export function elapsedSince(startMs: number): string {
+  return `${Math.round((Date.now() - startMs) / 1000)}s`;
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/extensions.ts

@@ -0,0 +1,99 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { CONFIG_PATH, DEV_DIR } from './paths';
+
+/** A project-owned command — a verb the project adds to `./dev` without touching the
+ *  framework bundle. This is the composability seam: the shipped commands are a
+ *  starting point, and a project grows the toolkit with every convenience it needs.
+ *
+ *  Declared in either place (both carry the same shape):
+ *    - inline in `.dev/dev.config.json` under a `commands` array, or
+ *    - one-per-file under `.dev/commands/*.json` (easier to manage and diff).
+ *
+ *  The CLI runs `run` as a subprocess (`bash -c`) with any extra args appended, so a
+ *  project command is a shell one-liner or a call into a project script — no rebuild,
+ *  no dependency added to the zero-dependency bundle. A project command whose `name`
+ *  matches a built-in **shadows** it, so a project can redefine `start` for a stack the
+ *  default lifecycle does not fit. These declarations are project-owned: `groundwork
+ *  update` never overwrites them. */
+export interface ProjectCommand {
+  name: string;
+  summary: string;
+  /** Display group in `--help`. Defaults to `PROJECT`. */
+  group?: string;
+  /** Shell command, run via `bash -c` from `cwd`; extra args are appended. */
+  run: string;
+  /** Working directory, relative to the repo root. */
+  cwd?: string;
+  /** Extra environment merged over the parent process env. */
+  env?: Record<string, string>;
+}
+
+/** Command names are lowercase verbs (optionally namespaced with `:` or `-`), matching
+ *  the built-in vocabulary so completion and help stay legible. */
+const NAME_RX = /^[a-z][a-z0-9:-]*$/;
+
+/** Coerce one untrusted entry into a validated ProjectCommand, or null if malformed.
+ *  Dropping bad entries (rather than throwing) means one broken command never breaks
+ *  the whole CLI. */
+function coerce(item: unknown): ProjectCommand | null {
+  if (!item || typeof item !== 'object') return null;
+  const c = item as Record<string, unknown>;
+  if (typeof c.name !== 'string' || !NAME_RX.test(c.name)) return null;
+  if (typeof c.run !== 'string' || !c.run.trim()) return null;
+  return {
+    name: c.name,
+    summary: typeof c.summary === 'string' && c.summary.trim() ? c.summary : '(project command)',
+    group:
+      typeof c.group === 'string' && c.group.trim() ? c.group.trim().toUpperCase() : 'PROJECT',
+    run: c.run,
+    cwd: typeof c.cwd === 'string' ? c.cwd : undefined,
+    env:
+      c.env && typeof c.env === 'object' && !Array.isArray(c.env)
+        ? (c.env as Record<string, string>)
+        : undefined,
+  };
+}
+
+/** Discover project commands from both sources. A `.dev/commands/*.json` file wins over
+ *  an inline `commands` entry of the same name, so a project can promote an inline
+ *  command to its own file without a duplicate. Any read/parse failure degrades to
+ *  fewer commands rather than breaking the CLI. */
+export function loadProjectCommands(): ProjectCommand[] {
+  const byName = new Map<string, ProjectCommand>();
+
+  // Inline: .dev/dev.config.json → commands: [ ... ]
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as { commands?: unknown };
+      if (Array.isArray(raw.commands)) {
+        for (const item of raw.commands) {
+          const c = coerce(item);
+          if (c) byName.set(c.name, c);
+        }
+      }
+    }
+  } catch {
+    /* no inline commands */
+  }
+
+  // Per-file: .dev/commands/*.json
+  try {
+    const dir = path.join(DEV_DIR, 'commands');
+    if (fs.existsSync(dir)) {
+      for (const f of fs.readdirSync(dir).sort()) {
+        if (!f.endsWith('.json')) continue;
+        try {
+          const c = coerce(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')));
+          if (c) byName.set(c.name, c);
+        } catch {
+          /* skip a malformed file */
+        }
+      }
+    }
+  } catch {
+    /* no commands dir */
+  }
+
+  return [...byName.values()];
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/paths.ts

@@ -0,0 +1,46 @@
+import * as path from 'path';
+import * as fs from 'fs';
+
+/** The project root. The `dev` launcher sets DEV_ROOT to its own directory; we fall
+ *  back to walking up from cwd to find a project marker so the CLI also works when
+ *  invoked directly. */
+export const ROOT: string = (() => {
+  if (process.env.DEV_ROOT) return process.env.DEV_ROOT;
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i += 1) {
+    if (
+      fs.existsSync(path.join(dir, 'dev')) ||
+      fs.existsSync(path.join(dir, 'docker-compose.yml')) ||
+      fs.existsSync(path.join(dir, '.groundwork'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+})();
+
+export const DEV_DIR = path.join(ROOT, '.dev');
+export const PID_DIR = path.join(DEV_DIR, 'pids');
+export const LOG_DIR = path.join(DEV_DIR, 'logs');
+export const SERVICES_DIR = path.join(ROOT, 'services');
+export const TESTS_DIR = path.join(ROOT, 'tests');
+export const DOCS_DIR = path.join(ROOT, 'docs');
+export const CONFIG_PATH = path.join(DEV_DIR, 'dev.config.json');
+/** Machine-readable twin of docs/surfaces.md (surface registry + capability ledger). */
+export const GROUNDWORK_SURFACES_FILE = path.join(ROOT, '.groundwork', 'surfaces.json');
+
+export function ensureDirs(): void {
+  fs.mkdirSync(PID_DIR, { recursive: true });
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+export function pidFile(svc: string): string {
+  return path.join(PID_DIR, `${svc}.pid`);
+}
+
+export function logFile(svc: string): string {
+  return path.join(LOG_DIR, `${svc}.log`);
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/proc.ts

@@ -0,0 +1,106 @@
+import { spawn, spawnSync, SpawnSyncOptions } from 'child_process';
+import * as http from 'http';
+
+export interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Run a command synchronously, inheriting stdio (for user-visible subprocesses
+ *  like `docker compose up`). Returns the exit status. */
+export function run(cmd: string, args: string[], opts: SpawnSyncOptions = {}): number {
+  const r = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  return r.status ?? 1;
+}
+
+/** Run a command synchronously and capture its output (for parsing, e.g.
+ *  `docker compose ps`). */
+export function capture(cmd: string, args: string[], opts: SpawnSyncOptions = {}): RunResult {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    status: r.status ?? (r.error ? 127 : 1),
+    stdout: (r.stdout as string) ?? '',
+    stderr: (r.stderr as string) ?? '',
+  };
+}
+
+/** Run a shell command string (for piped/compound commands ported from bash). */
+export function sh(command: string, opts: SpawnSyncOptions = {}): RunResult {
+  const r = spawnSync(command, { shell: true, encoding: 'utf8', ...opts });
+  return {
+    status: r.status ?? (r.error ? 127 : 1),
+    stdout: (r.stdout as string) ?? '',
+    stderr: (r.stderr as string) ?? '',
+  };
+}
+
+/** True if a command is resolvable on PATH. Passes a single command string (never
+ *  args with shell:true) to avoid Node's DEP0190 shell-injection warning. */
+export function commandExists(cmd: string): boolean {
+  const safe = cmd.replace(/[^a-zA-Z0-9._-]/g, '');
+  const probe = process.platform === 'win32' ? `where ${safe}` : `command -v ${safe}`;
+  const r = spawnSync(probe, { shell: true, stdio: 'ignore' });
+  return (r.status ?? 1) === 0;
+}
+
+/** `docker compose` (v2) is the only supported form. */
+export const COMPOSE = ['compose'];
+
+export function dockerComposeCapture(args: string[]): RunResult {
+  return capture('docker', [...COMPOSE, ...args]);
+}
+
+export function dockerComposeRun(args: string[]): number {
+  return run('docker', [...COMPOSE, ...args]);
+}
+
+/** Spawn a detached background process writing to a log file; returns its PID.
+ *  Optional cwd/env let a declared runner launch from its own directory with a
+ *  merged environment (native runners, sidecars). */
+export function spawnBackground(
+  command: string,
+  logStream: number,
+  opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {},
+): number {
+  const child = spawn('bash', ['-c', command], {
+    stdio: ['ignore', logStream, logStream],
+    detached: true,
+    cwd: opts.cwd,
+    env: opts.env,
+  });
+  child.unref();
+  return child.pid ?? -1;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Probe an HTTP endpoint and resolve with its status code, or 0 on a connection
+ *  error/timeout. Never throws — used by health/doctor connectivity checks so a
+ *  hung or absent port renders as a row, not a crash. Localhost-only (http). */
+export function httpProbe(url: string, timeoutMs = 3000): Promise<number> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (code: number): void => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    };
+    try {
+      const req = http.get(url, (res) => {
+        const code = res.statusCode ?? 0;
+        res.resume(); // drain so the socket can close
+        done(code);
+      });
+      req.setTimeout(timeoutMs, () => {
+        req.destroy();
+        done(0);
+      });
+      req.on('error', () => done(0));
+    } catch {
+      done(0);
+    }
+  });
+}

package/src/generators/workspace-dev-cli/cli-src/src/util/prompt.ts

@@ -0,0 +1,108 @@
+/**
+ * Interactive prompts — arrow-key selection and validated text input — built on Node's
+ * raw-mode stdin and ANSI, so they add no dependencies and bundle to nothing.
+ *
+ * Every prompt is TTY-gated by `isInteractive()`. Callers must check it first and fall
+ * back to a non-interactive path (the agent contract: the CLI never blocks off a TTY).
+ */
+
+import * as readline from 'readline';
+import { Painter } from '../theme/color';
+
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+interface Key {
+  name?: string;
+  ctrl?: boolean;
+  sequence?: string;
+}
+
+/** Arrow-key single-select. Renders to stderr; returns the chosen value. */
+export function selectPrompt<T>(
+  painter: Painter,
+  message: string,
+  choices: Array<{ label: string; value: T; hint?: string }>,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    let index = 0;
+    const out = process.stderr;
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    out.write('\x1b[?25l'); // hide cursor
+
+    const render = (first: boolean) => {
+      if (!first) out.write(`\x1b[${choices.length + 1}A`); // move up to redraw
+      out.write(`\x1b[2K  ${painter.bold(message)}\n`);
+      choices.forEach((c, i) => {
+        const active = i === index;
+        const marker = active ? painter.primary('❯') : ' ';
+        const label = active ? painter.primary(c.label) : c.label;
+        const hint = c.hint ? painter.dim(`  ${c.hint}`) : '';
+        out.write(`\x1b[2K  ${marker} ${label}${hint}\n`);
+      });
+    };
+
+    const cleanup = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener('keypress', onKey);
+      out.write('\x1b[?25h'); // restore cursor
+    };
+
+    const onKey = (_str: string, key: Key) => {
+      if (key.ctrl && key.name === 'c') {
+        cleanup();
+        process.exit(130);
+      } else if (key.name === 'up' || key.name === 'k') {
+        index = (index - 1 + choices.length) % choices.length;
+        render(false);
+      } else if (key.name === 'down' || key.name === 'j') {
+        index = (index + 1) % choices.length;
+        render(false);
+      } else if (key.name === 'return' || key.name === 'enter') {
+        cleanup();
+        resolve(choices[index].value);
+      }
+    };
+
+    render(true);
+    process.stdin.on('keypress', onKey);
+    process.stdin.on('error', (e) => {
+      cleanup();
+      reject(e);
+    });
+  });
+}
+
+/** Validated single-line text input. Re-prompts until `validate` returns null. */
+export function textPrompt(
+  painter: Painter,
+  message: string,
+  validate?: (value: string) => string | null,
+): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const ask = (): Promise<string> =>
+    new Promise((resolve) => {
+      rl.question(`  ${painter.bold(message)} `, (answer) => resolve(answer.trim()));
+    });
+
+  return (async () => {
+    try {
+      for (;;) {
+        const value = await ask();
+        const err = validate ? validate(value) : null;
+        if (!err) {
+          rl.close();
+          return value;
+        }
+        process.stderr.write(`  ${painter.paint('error', '✖')} ${err}\n`);
+      }
+    } catch (e) {
+      rl.close();
+      throw e;
+    }
+  })();
+}