@rigkit/cli 0.0.0-canary-20260518T014918-c5bc0c2

package/src/run-logger.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import { appendFileSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRunLogger } from "./run-logger.ts";
+
+describe("createRunLogger", () => {
+  test("writes a run.start envelope, every appended event, and a run.end envelope", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-run-logger-"));
+    try {
+      const logger = createRunLogger({ projectDir, operation: "plan" });
+      expect(logger).toBeDefined();
+      logger!.append({ type: "node.started", nodePath: "build" });
+      logger!.append({ type: "node.completed", nodePath: "build" });
+      logger!.finish({ status: "completed", result: { ok: true } });
+      logger!.close();
+
+      const lines = readFileSync(logger!.path, "utf8").trim().split("\n");
+      expect(lines.length).toBe(4);
+      const entries = lines.map((line) => JSON.parse(line));
+      expect(entries[0]).toMatchObject({ type: "run.start", operation: "plan" });
+      expect(entries[1]).toMatchObject({ type: "node.started", nodePath: "build" });
+      expect(entries[2]).toMatchObject({ type: "node.completed", nodePath: "build" });
+      expect(entries[3]).toMatchObject({ type: "run.end", status: "completed", result: { ok: true } });
+
+      const logFiles = readdirSync(join(projectDir, ".rigkit", "logs"));
+      expect(logFiles.length).toBe(1);
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test("captures failure details on the run.end envelope", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-run-logger-"));
+    try {
+      const logger = createRunLogger({ projectDir, operation: "apply" });
+      logger!.append({ type: "run.failed", error: { message: "boom" } });
+      logger!.finish({ status: "failed", error: new Error("boom") });
+      logger!.close();
+
+      const entries = readFileSync(logger!.path, "utf8").trim().split("\n").map((line) => JSON.parse(line));
+      expect(entries.at(-1)).toMatchObject({
+        type: "run.end",
+        status: "failed",
+        error: { message: "boom" },
+      });
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test("splices daemon stderr written during the run into the failure log", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-run-logger-"));
+    const daemonStderrPath = join(projectDir, "daemon.log");
+    // Pre-existing daemon output that predates the run — we must NOT splice it.
+    writeFileSync(daemonStderrPath, "earlier daemon noise we should ignore\n");
+
+    try {
+      const logger = createRunLogger({ projectDir, operation: "apply", daemonStderrPath });
+      // Daemon writes a real stack trace mid-run.
+      appendFileSync(daemonStderrPath, "Error: connect ECONNREFUSED 127.0.0.1:443\n    at fetch (engine.ts:42)\n");
+      logger!.finish({ status: "failed", error: new Error("INTERNAL_ERROR: Internal server error") });
+      logger!.close();
+
+      const entries = readFileSync(logger!.path, "utf8").trim().split("\n").map((line) => JSON.parse(line));
+      const stderr = entries.filter((entry) => entry.type === "daemon.stderr").map((entry) => entry.data);
+      expect(stderr).toEqual([
+        "Error: connect ECONNREFUSED 127.0.0.1:443",
+        "    at fetch (engine.ts:42)",
+      ]);
+      expect(stderr.some((line) => line.includes("earlier daemon noise"))).toBe(false);
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test("does not splice daemon stderr on success", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-run-logger-"));
+    const daemonStderrPath = join(projectDir, "daemon.log");
+    try {
+      const logger = createRunLogger({ projectDir, operation: "apply", daemonStderrPath });
+      appendFileSync(daemonStderrPath, "noise during a successful run\n");
+      logger!.finish({ status: "completed" });
+      logger!.close();
+
+      const entries = readFileSync(logger!.path, "utf8").trim().split("\n").map((line) => JSON.parse(line));
+      expect(entries.find((entry) => entry.type === "daemon.stderr")).toBeUndefined();
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/run-logger.ts

@@ -0,0 +1,203 @@
+// Persists every runtime event for a single run to `.rigkit/logs/`. The
+// presenter on stderr stays terse; this file is the unfiltered transcript you
+// grep when something goes wrong. NDJSON, one event per line, plus a couple of
+// envelope records (run.start / run.end) so logs stand on their own.
+//
+// On failure we also splice in the daemon's stderr emitted during this run's
+// time window. The daemon's "INTERNAL_ERROR: Internal server error" event
+// carries no stack — the real trace is in its stderr. We capture that to
+// `runtimeLogPath` (in runtime-client) and tail it here so the run log is
+// self-contained.
+
+import {
+  appendFileSync,
+  closeSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+
+const LOG_DIR_NAME = "logs";
+const MAX_LOG_FILES = 50;
+
+export type RunLogger = {
+  append(event: unknown): void;
+  finish(outcome: { status: "completed" | "failed"; error?: unknown; result?: unknown }): void;
+  close(): void;
+  path: string;
+};
+
+export function createRunLogger(input: {
+  projectDir: string;
+  operation: string;
+  runtimeStateDir?: string;
+  // Daemon stderr file. When the run fails we splice everything written here
+  // during this run's time window into the run log.
+  daemonStderrPath?: string;
+}): RunLogger | undefined {
+  const logDir = resolveLogDir(input);
+  if (!logDir) return undefined;
+
+  try {
+    mkdirSync(logDir, { recursive: true });
+  } catch {
+    return undefined;
+  }
+
+  const path = join(logDir, `${fileTimestamp()}-${slugify(input.operation)}.log`);
+
+  let fd: number;
+  try {
+    fd = openSync(path, "a");
+  } catch {
+    return undefined;
+  }
+
+  rotate(logDir);
+
+  const startedAt = new Date().toISOString();
+  // Snapshot the daemon log's current size so we can read only what this run
+  // appended later. We don't want to dump the daemon's entire history.
+  const daemonOffset = input.daemonStderrPath ? safeFileSize(input.daemonStderrPath) : 0;
+  let closed = false;
+
+  const writeLine = (value: unknown): void => {
+    if (closed) return;
+    try {
+      appendFileSync(fd, `${JSON.stringify(value)}\n`);
+    } catch {
+      // best-effort: a logging failure should never break the run
+    }
+  };
+
+  writeLine({
+    ts: startedAt,
+    type: "run.start",
+    operation: input.operation,
+    cwd: process.cwd(),
+  });
+
+  return {
+    path,
+    append(event) {
+      writeLine({ ts: new Date().toISOString(), ...(toRecord(event) ?? { value: event }) });
+    },
+    finish(outcome) {
+      if (outcome.status === "failed" && input.daemonStderrPath) {
+        spliceDaemonStderr(input.daemonStderrPath, daemonOffset, writeLine);
+      }
+      writeLine({
+        ts: new Date().toISOString(),
+        type: "run.end",
+        status: outcome.status,
+        durationMs: Date.now() - Date.parse(startedAt),
+        ...(outcome.error !== undefined ? { error: toErrorRecord(outcome.error) } : {}),
+        ...(outcome.result !== undefined ? { result: outcome.result } : {}),
+      });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        closeSync(fd);
+      } catch {
+        // best-effort
+      }
+    },
+  };
+}
+
+function spliceDaemonStderr(
+  path: string,
+  offset: number,
+  write: (value: unknown) => void,
+): void {
+  let fd: number | undefined;
+  try {
+    const size = safeFileSize(path);
+    if (size <= offset) return;
+    fd = openSync(path, "r");
+    const length = size - offset;
+    const buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, offset);
+    const text = buffer.toString("utf8");
+    for (const line of text.split("\n")) {
+      if (!line) continue;
+      write({ ts: new Date().toISOString(), type: "daemon.stderr", data: line });
+    }
+  } catch {
+    // best-effort: failure to splice should never break the run log
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // best-effort
+      }
+    }
+  }
+}
+
+function safeFileSize(path: string): number {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+function resolveLogDir(input: { projectDir: string; runtimeStateDir?: string }): string | undefined {
+  if (input.runtimeStateDir) return join(input.runtimeStateDir, LOG_DIR_NAME);
+  if (input.projectDir) return join(input.projectDir, ".rigkit", LOG_DIR_NAME);
+  return undefined;
+}
+
+function rotate(logDir: string): void {
+  try {
+    const entries = readdirSync(logDir)
+      .filter((name) => name.endsWith(".log"))
+      .map((name) => {
+        const filePath = join(logDir, name);
+        return { path: filePath, mtime: statSync(filePath).mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+
+    for (const stale of entries.slice(MAX_LOG_FILES)) {
+      try {
+        unlinkSync(stale.path);
+      } catch {
+        // best-effort
+      }
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+function fileTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function slugify(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  const slug = cleaned.slice(0, 40);
+  return slug || "run";
+}
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function toErrorRecord(value: unknown): Record<string, unknown> {
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+  const record = toRecord(value);
+  return record ?? { message: String(value) };
+}

package/src/run-presenter.ts

@@ -0,0 +1,250 @@
+// Append-only run presenter. Each runtime event prints zero or one line to
+// stderr. No spinners, no re-renders. Looks the same in a TTY, a CI log, and an
+// LLM transcript — and it pipes cleanly.
+
+import { accent, bold, clip, dim, err, ok, sym, termWidth, warn } from "./ui.ts";
+
+export type RunPresenter = {
+  render(event: { type: string; [key: string]: unknown }): void;
+  pause(): void;
+  resume(): void;
+  close(): void;
+};
+
+export function createRunPresenter(operation: string): RunPresenter | undefined {
+  if (process.env.RIGKIT_RENDER === "0") return undefined;
+
+  let workflow = "";
+  let totalNodes = 0;
+  let cachedNodes = 0;
+  const seenNodes = new Set<string>();
+  const completedNodes = new Set<string>();
+  let lastNodePath: string | undefined;
+  let closed = false;
+
+  const write = (line: string): void => {
+    process.stderr.write(`${line}\n`);
+  };
+
+  const indent = (line: string): string => `  ${line}`;
+
+  const trim = (value: string): string => clip(value, Math.max(40, termWidth() - 4));
+
+  const headerLine = (): string => {
+    const left = workflow ? `${bold(operation)} ${dim(workflow)}` : bold(operation);
+    return `${accent(sym.active)} ${left}`;
+  };
+
+  return {
+    render(event) {
+      if (closed) return;
+      switch (event.type) {
+        case "definition.loaded": {
+          workflow = stringField(event.workflow) ?? workflow;
+          break;
+        }
+        case "plan.created": {
+          workflow = stringField(event.workflow) ?? workflow;
+          totalNodes = numberField(event.nodeCount) ?? totalNodes;
+          cachedNodes = numberField(event.cachedNodeCount) ?? cachedNodes;
+          write(headerLine());
+          write(indent(dim(planSummary(totalNodes, cachedNodes))));
+          break;
+        }
+        case "workflow.apply.started": {
+          workflow = stringField(event.workflow) ?? workflow;
+          write(`${accent(sym.active)} workflow ${bold(workflow || operation)}`);
+          break;
+        }
+        case "workflow.apply.completed": {
+          const name = stringField(event.workflow) ?? workflow;
+          totalNodes = numberField(event.nodeCount) ?? totalNodes;
+          cachedNodes = numberField(event.cachedNodeCount) ?? cachedNodes;
+          const summary = totalNodes > 0 ? `  ${dim(planSummary(totalNodes, cachedNodes))}` : "";
+          write(`${ok(sym.ok)} ${bold(name || "workflow")} ${dim("prepared")}${summary}`);
+          break;
+        }
+        case "node.cached": {
+          const path = stringField(event.nodePath);
+          if (!path || completedNodes.has(path)) break;
+          completedNodes.add(path);
+          seenNodes.add(path);
+          write(indent(`${dim(sym.ok)} ${dim(path)}  ${dim("cached")}`));
+          break;
+        }
+        case "node.started": {
+          const path = stringField(event.nodePath);
+          if (!path || seenNodes.has(path)) break;
+          seenNodes.add(path);
+          lastNodePath = path;
+          write(indent(`${accent(sym.active)} ${bold(path)}`));
+          break;
+        }
+        case "node.completed": {
+          const path = stringField(event.nodePath);
+          if (!path || completedNodes.has(path)) break;
+          completedNodes.add(path);
+          if (lastNodePath === path) lastNodePath = undefined;
+          const detail = compactId(event.runId);
+          const tail = detail ? `  ${dim(detail)}` : "";
+          write(indent(`${ok(sym.ok)} ${path}${tail}`));
+          break;
+        }
+        case "vm.created": {
+          const vmId = stringField(event.vmId);
+          const from = stringField(event.fromSnapshotId);
+          const label = from ? `vm ${vmId ?? ""} from ${from}` : `vm ${vmId ?? "ready"}`;
+          write(indent(`  ${dim(label)}`));
+          break;
+        }
+        case "command.started": {
+          const command = stringField(event.command) ?? stringField(event.commandName);
+          if (command) write(indent(`  ${dim(`$ ${trim(command)}`)}`));
+          break;
+        }
+        case "command.output": {
+          const data = stringField(event.data);
+          if (!data) break;
+          for (const line of data.replace(/\r/g, "").split("\n")) {
+            if (!line) continue;
+            write(indent(`  ${dim(trim(line))}`));
+          }
+          break;
+        }
+        case "command.completed": {
+          const exitCode = numberField(event.exitCode) ?? 0;
+          if (exitCode !== 0) {
+            const name = stringField(event.commandName) ?? "command";
+            write(indent(`  ${err(`${name} exited ${exitCode}`)}`));
+          }
+          break;
+        }
+        case "log.output": {
+          const data = stringField(event.data);
+          if (!data) break;
+          const stream = stringField(event.stream);
+          // console.debug is intentionally silent at the terminal — it lives
+          // in the run log file only. Surface it live with RIGKIT_DEBUG=1.
+          if (stream === "debug" && process.env.RIGKIT_DEBUG !== "1") break;
+          const label = stringField(event.label);
+          const { icon, style } = logStreamPresentation(stream);
+          for (const line of data.replace(/\r/g, "").split("\n")) {
+            if (!line) continue;
+            const prefix = label ? `${dim(`[${label}]`)} ` : "";
+            write(indent(`  ${icon} ${prefix}${style(trim(line))}`));
+          }
+          break;
+        }
+        case "interaction.awaiting_user": {
+          const label = stringField(event.title) ?? stringField(event.label) ?? "user interaction";
+          const url = stringField(event.url);
+          write(indent(`${accent(sym.arrow)} waiting on ${bold(label)}`));
+          if (url) write(indent(`  ${dim(url)}`));
+          break;
+        }
+        case "interaction.completed": {
+          const label = stringField(event.title) ?? stringField(event.label) ?? "interaction";
+          write(indent(`${ok(sym.ok)} ${dim(`${label} completed`)}`));
+          break;
+        }
+        case "artifact.created": {
+          const kind = stringField(event.kind) ?? "artifact";
+          const provider = stringField(event.providerId);
+          const label = provider ? `${provider}:${kind}` : kind;
+          write(indent(`  ${dim(`+ ${label}`)}`));
+          break;
+        }
+        case "workspace.create.started": {
+          const name = stringField(event.workspaceName) ?? "workspace";
+          write(`${accent(sym.active)} creating workspace ${bold(name)}`);
+          break;
+        }
+        case "workspace.ready": {
+          const id = stringField(event.workspaceId) ?? "workspace";
+          write(`${ok(sym.ok)} ${bold(id)} ${dim("ready")}`);
+          break;
+        }
+        case "workspace.remove.started": {
+          const name = stringField(event.workspaceName) ?? "workspace";
+          write(`${accent(sym.active)} removing workspace ${bold(name)}`);
+          break;
+        }
+        case "workspace.remove.completed": {
+          const name = stringField(event.workspaceName) ?? "workspace";
+          write(`${ok(sym.ok)} removed ${bold(name)}`);
+          break;
+        }
+        case "workspace.operation.started": {
+          const name = stringField(event.workspaceName) ?? "workspace";
+          const op = stringField(event.operationId) ?? "operation";
+          write(`${accent(sym.active)} running ${bold(op)} on ${bold(name)}`);
+          break;
+        }
+        case "workspace.operation.completed": {
+          const name = stringField(event.workspaceName) ?? "workspace";
+          const op = stringField(event.operationId) ?? "operation";
+          write(`${ok(sym.ok)} ran ${bold(op)} on ${bold(name)}`);
+          break;
+        }
+        case "run.completed":
+        case "run.failed": {
+          // Run terminal events are owned by the CLI's failure renderer so the
+          // structured failure block stays in one place.
+          break;
+        }
+      }
+    },
+    pause() {
+      // No-op — output is already append-only.
+    },
+    resume() {
+      // No-op — output is already append-only.
+    },
+    close() {
+      closed = true;
+    },
+  };
+}
+
+function planSummary(total: number, cached: number): string {
+  if (total === 0) return "no nodes";
+  if (cached === 0) return `${total} ${noun("node", total)}`;
+  return `${cached}/${total} cached`;
+}
+
+function noun(singular: string, count: number): string {
+  return count === 1 ? singular : `${singular}s`;
+}
+
+function compactId(value: unknown): string {
+  return typeof value === "string" && value.length > 0 ? value.slice(0, 8) : "";
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberField(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function logStreamPresentation(stream: string | undefined): {
+  icon: string;
+  style: (text: string) => string;
+} {
+  switch (stream) {
+    case "warn":
+      return { icon: warn("!"), style: warn };
+    case "stderr":
+    case "error":
+      return { icon: err(sym.err), style: err };
+    case "debug":
+      return { icon: dim("·"), style: (text: string) => dim(`${dim("debug")} ${text}`) };
+    case "stdout":
+    case "info":
+    case "log":
+    default:
+      return { icon: dim(sym.dot), style: dim };
+  }
+}
+

package/src/ui.ts

@@ -0,0 +1,159 @@
+// Minimal design system for the rig CLI.
+// Mirrors apps/website/src/components/CliShowcase.tsx: bold black for the thing
+// that matters, dim for muted, blue for prompts and active items, green for ok,
+// red for fail. No spinners, no log-update, no boxes. Append-only output that
+// looks the same in a TTY, a CI log, or an LLM transcript.
+
+import chalk from "chalk";
+
+const HEX_ACCENT = "#2d4df5";
+const HEX_OK = "#1f8b4c";
+const HEX_WARN = "#a36b00";
+const HEX_ERR = "#b91c1c";
+
+export const accent = (text: string) => chalk.hex(HEX_ACCENT)(text);
+export const ok = (text: string) => chalk.hex(HEX_OK)(text);
+export const warn = (text: string) => chalk.hex(HEX_WARN)(text);
+export const err = (text: string) => chalk.hex(HEX_ERR)(text);
+export const dim = (text: string) => chalk.dim(text);
+export const bold = (text: string) => chalk.bold(text);
+
+export const sym = {
+  prompt: "$",
+  arrow: "›",
+  active: "▸",
+  ok: "✓",
+  err: "✗",
+  dot: "·",
+  ellipsis: "…",
+} as const;
+
+export function title(text: string): string {
+  return bold(text);
+}
+
+export function heading(text: string): string {
+  return bold(text);
+}
+
+export function muted(text: string): string {
+  return dim(text);
+}
+
+export function prompt(command: string): string {
+  return `${accent(sym.prompt)} ${command}`;
+}
+
+export function hint(text: string): string {
+  return `${dim(sym.arrow)} ${text}`;
+}
+
+export type FileStatus = "created" | "updated" | "kept" | "failed" | "pinned";
+
+const STATUS_WORD_WIDTH = "created".length;
+
+export function fileStatus(kind: FileStatus, label: string): string {
+  switch (kind) {
+    case "created":
+      return `${ok("+")} ${bold(pad("created", STATUS_WORD_WIDTH))}  ${label}`;
+    case "updated":
+      return `${warn("~")} ${bold(pad("updated", STATUS_WORD_WIDTH))}  ${label}`;
+    case "kept":
+      return `${dim(sym.dot)} ${dim(pad("kept", STATUS_WORD_WIDTH))}  ${dim(label)}`;
+    case "pinned":
+      return `${accent("·")} ${bold(pad("pinned", STATUS_WORD_WIDTH))}  ${label}`;
+    case "failed":
+      return `${err(sym.err)} ${err(pad("failed", STATUS_WORD_WIDTH))}  ${label}`;
+  }
+}
+
+export type StepKind = "active" | "ok" | "cached" | "err";
+
+export function stepLine(kind: StepKind, label: string, detail?: string): string {
+  const tail = detail ? `  ${dim(detail)}` : "";
+  switch (kind) {
+    case "active":
+      return `${accent(sym.active)} ${bold(label)}${tail}`;
+    case "ok":
+      return `${ok(sym.ok)} ${label}${tail}`;
+    case "cached":
+      return `${dim(sym.ok)} ${dim(label)}${tail ? `  ${dim("cached")}` : `  ${dim("cached")}`}`;
+    case "err":
+      return `${err(sym.err)} ${bold(label)}${tail}`;
+  }
+}
+
+type Cell = { text: string; style?: (text: string) => string };
+type Row = Array<string | Cell>;
+
+function toCell(value: string | Cell): Cell {
+  return typeof value === "string" ? { text: value } : value;
+}
+
+export type ColumnsOptions = {
+  // Bold + underline the header row. Default true.
+  emphasizeHeader?: boolean;
+  // Two-space indent in front of each row. Default true.
+  indent?: boolean;
+};
+
+// Replacement for the old ASCII table. Aligned columns, bold-underlined header,
+// no dashed separator. Cells may carry their own style.
+export function columns(headers: string[], rows: Row[], options: ColumnsOptions = {}): string {
+  const indent = options.indent === false ? "" : "  ";
+  const emphasizeHeader = options.emphasizeHeader !== false;
+  const widths = headers.map((header, index) =>
+    Math.max(
+      header.length,
+      ...rows.map((row) => toCell(row[index] ?? "").text.length),
+    ),
+  );
+
+  const renderRow = (cells: Cell[], styleFallback?: (text: string) => string): string => {
+    const last = cells.length - 1;
+    return indent + cells
+      .map((cell, index) => {
+        const width = widths[index] ?? cell.text.length;
+        const style = cell.style ?? styleFallback;
+        const styled = style ? style(cell.text) : cell.text;
+        if (index === last) return styled;
+        const padding = " ".repeat(Math.max(0, width - cell.text.length));
+        return `${styled}${padding}  `;
+      })
+      .join("")
+      .replace(/\s+$/u, "");
+  };
+
+  const headerCells = headers.map((text) => ({ text }));
+  const lines: string[] = [];
+  lines.push(renderRow(headerCells, emphasizeHeader ? (s) => chalk.bold.underline(s) : undefined));
+  for (const row of rows) {
+    lines.push(renderRow(row.map(toCell)));
+  }
+  return lines.join("\n");
+}
+
+// "key  value" pairs aligned by the longest key. Keys are bold.
+export function kvList(pairs: Array<[string, string]>, options: { indent?: boolean } = {}): string {
+  const indent = options.indent === false ? "" : "  ";
+  const width = pairs.reduce((max, [key]) => Math.max(max, key.length), 0);
+  return pairs
+    .map(([key, value]) => `${indent}${bold(pad(key, width))}  ${value}`)
+    .join("\n");
+}
+
+export function section(headingText: string, body: string): string {
+  return `${heading(headingText)}\n${body}`;
+}
+
+export function pad(text: string, width: number): string {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+
+export function termWidth(stream: NodeJS.WriteStream = process.stderr): number {
+  return stream.columns || 80;
+}
+
+export function clip(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, Math.max(0, max - 1))}${sym.ellipsis}` : value;
+}