@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/tui/startup.ts

@@ -0,0 +1,231 @@
+// Startup progress — the bring-up, reported IN the companion column.
+//
+// The column is empty at that moment and already the right shape (its width
+// comes from config), so it costs no new surface: memory forward, OpenViking
+// namespaces, container bring-up, day rollover and the first poll each report
+// there, and when the companion is up the mirror takes the space back. Lines
+// printed on the NORMAL screen would be erased by the alt screen's clear.
+//
+// A step that never completes must be distinguishable from one still working:
+// past STALL_AFTER_MS a running step stops looking like a spinner and says so,
+// with the elapsed time, in warning colour. Nothing here has a timeout of its
+// own — the bring-up steps own their deadlines; this only tells the truth about
+// how long one has been going.
+import { ACCENT, BAD, MUTED, OK, RESET, WARN } from "./design.js";
+
+export type StepState = "pending" | "running" | "done" | "failed" | "skipped";
+
+export interface StartupStep {
+  key: string;
+  label: string;
+  state: StepState;
+  /** One short clause: what happened, or what it is doing. */
+  detail?: string;
+  startedAt?: number;
+  endedAt?: number;
+}
+
+/** After this long a running step is flagged as overdue rather than working. */
+export const STALL_AFTER_MS = 20_000;
+
+/** The bring-up, in the order it runs. Declared here so the column shows every
+ * step from the first frame — a step nobody has reached yet is `pending`, which
+ * is a different thing from one that failed. */
+export const STARTUP_STEPS = [
+  { key: "ssh", label: "vm ssh" },
+  { key: "poll", label: "daemon status" },
+  { key: "memory-forward", label: "memory forward" },
+  { key: "memory-namespaces", label: "memory namespaces" },
+  { key: "container", label: "companion container" },
+  { key: "rollover", label: "day rollover" },
+  { key: "companion-pi", label: "companion pi" },
+] as const satisfies ReadonlyArray<{ key: string; label: string }>;
+
+/** Every step key the bring-up may address — derived from `STARTUP_STEPS`, so
+ * a key cannot exist without the step it names. A union rather than bare
+ * strings: `set()` has to ignore an unknown key (a progress reporter must
+ * never break the startup it reports on), which makes a typo INVISIBLE at
+ * runtime — so it is caught at compile time instead. */
+export type StartupStepKey = (typeof STARTUP_STEPS)[number]["key"];
+
+/** What a reporter is allowed to read — structural, so `StartupOpts` does not
+ * have to be generic over the step keys. */
+export interface ProgressView {
+  lines(): string[];
+  steps(): StartupStep[];
+  settled(): boolean;
+}
+
+export interface StartupOpts {
+  now?: () => number;
+  /** Called after every transition AND on every tick — the TUI repaints here. */
+  onUpdate?: (progress: ProgressView) => void;
+  /** Re-render cadence while a step is running (0 disables the ticker).
+   *
+   * Without this the overdue warning can never appear. A step that hangs emits
+   * no transition, so nothing calls `onUpdate`, so the column keeps painting
+   * the elapsed time it had at the last transition — `⟳ companion container ·
+   * 0ms`, frozen, forever. A docker daemon which is down must look different
+   * from one that is slow, and it is exactly this tick that makes the
+   * difference visible. */
+  tickMs?: number;
+}
+
+/** Re-render cadence while the bring-up is unsettled. Deliberately slower than
+ * a second is not worth it (the elapsed counter would visibly stutter) and
+ * faster is pointless; it is independent of the 3s poll and never triggers
+ * one — it only repaints what is already known. */
+export const DEFAULT_TICK_MS = 1_000;
+
+/**
+ * The bring-up's state. Total by construction: an unknown key is ignored rather
+ * than throwing — a progress reporter must never be able to break the startup
+ * it is reporting on.
+ */
+export class StartupProgress<K extends string = StartupStepKey> {
+  private readonly order: StartupStep[];
+  private readonly byKey = new Map<string, StartupStep>();
+
+  constructor(
+    steps: ReadonlyArray<{ key: K; label: string }> = STARTUP_STEPS as unknown as ReadonlyArray<{
+      key: K;
+      label: string;
+    }>,
+    private readonly opts: StartupOpts = {},
+  ) {
+    this.order = steps.map((s) => ({ key: s.key, label: s.label, state: "pending" }));
+    for (const s of this.order) this.byKey.set(s.key, s);
+  }
+
+  private now(): number {
+    return this.opts.now?.() ?? Date.now();
+  }
+
+  private set(key: K, patch: Partial<StartupStep>): void {
+    const step = this.byKey.get(key);
+    if (!step) return;
+    Object.assign(step, patch);
+    if (this.settled()) this.stop();
+    else this.ensureTicker();
+    this.opts.onUpdate?.(this);
+  }
+
+  /** The re-render tick. Unref'd, so it can never hold the process open at
+   * quit, and self-stopping the moment nothing is running any more. */
+  private ticker: ReturnType<typeof setInterval> | undefined;
+
+  private ensureTicker(): void {
+    const ms = this.opts.tickMs ?? DEFAULT_TICK_MS;
+    if (this.ticker !== undefined || ms <= 0) return;
+    const t = setInterval(() => {
+      if (this.settled()) {
+        this.stop();
+        return;
+      }
+      this.opts.onUpdate?.(this);
+    }, ms);
+    t.unref?.();
+    this.ticker = t;
+  }
+
+  /** Stop ticking. Called on settle and from the TUI's teardown. */
+  stop(): void {
+    if (this.ticker !== undefined) clearInterval(this.ticker);
+    this.ticker = undefined;
+  }
+
+  /** Start (or restart) a step: what a previous attempt said — a failure's
+   * detail, its end time — is cleared, never carried into this one. */
+  begin(key: K, detail?: string): void {
+    const step = this.byKey.get(key);
+    if (step) {
+      delete step.detail;
+      delete step.endedAt;
+    }
+    this.set(key, {
+      state: "running",
+      startedAt: this.now(),
+      ...(detail !== undefined ? { detail } : {}),
+    });
+  }
+
+  /** Update a running step's detail WITHOUT restarting its clock — "what it is
+   * doing right now". Restarting it would hide a stall behind chatter. */
+  note(key: K, detail: string): void {
+    if (this.byKey.get(key)?.state !== "running") return;
+    this.set(key, { detail });
+  }
+
+  done(key: K, detail?: string): void {
+    this.set(key, {
+      state: "done",
+      endedAt: this.now(),
+      ...(detail !== undefined ? { detail } : {}),
+    });
+  }
+
+  fail(key: K, detail: string): void {
+    this.set(key, { state: "failed", endedAt: this.now(), detail });
+  }
+
+  skip(key: K, detail?: string): void {
+    this.set(key, {
+      state: "skipped",
+      endedAt: this.now(),
+      ...(detail !== undefined ? { detail } : {}),
+    });
+  }
+
+  steps(): StartupStep[] {
+    return this.order.map((s) => ({ ...s }));
+  }
+
+  /** Every step has reached a terminal state — nothing left to re-render for,
+   * which is what stops the ticker. */
+  settled(): boolean {
+    return this.order.every((s) => s.state !== "pending" && s.state !== "running");
+  }
+
+  lines(): string[] {
+    return startupLines(this.order, this.now());
+  }
+}
+
+/** ` · 400ms` for a step that actually ran; "" for one that never began. */
+function took(s: StartupStep): string {
+  return s.startedAt !== undefined && s.endedAt !== undefined
+    ? ` · ${secs(s.endedAt - s.startedAt)}`
+    : "";
+}
+
+function secs(ms: number): string {
+  return ms < 1_000 ? `${Math.max(0, Math.round(ms))}ms` : `${Math.round(ms / 1000)}s`;
+}
+
+/** Pure render: one line per step, in declaration order. */
+export function startupLines(steps: readonly StartupStep[], nowMs: number): string[] {
+  return steps.map((s) => {
+    const detail = s.detail && s.detail.trim() !== "" ? ` · ${s.detail.trim()}` : "";
+    switch (s.state) {
+      case "pending":
+        return `${MUTED}○ ${s.label} · waiting${RESET}`;
+      case "running": {
+        const elapsed = s.startedAt === undefined ? 0 : Math.max(0, nowMs - s.startedAt);
+        if (elapsed >= STALL_AFTER_MS) {
+          return `${WARN}⚠ ${s.label} · ${secs(elapsed)} — still running, no result yet${RESET}${MUTED}${detail}${RESET}`;
+        }
+        return `${ACCENT}⟳ ${s.label} · ${secs(elapsed)}${RESET}${MUTED}${detail}${RESET}`;
+      }
+      case "done": {
+        return `${OK}✓ ${s.label}${RESET}${MUTED}${took(s)}${detail}${RESET}`;
+      }
+      case "failed":
+        // The duration matters on a failure too: 12s says the probe timed out,
+        // 40ms says it was refused outright. Its ABSENCE is also information —
+        // a step that failed without ever starting never ran at all.
+        return `${BAD}✗ ${s.label}${RESET}${MUTED}${took(s)}${RESET}${BAD}${detail}${RESET}`;
+      case "skipped":
+        return `${MUTED}– ${s.label}${detail}${RESET}`;
+    }
+  });
+}

package/src/tui/tabs.ts

@@ -0,0 +1,45 @@
+// The TUI's eight surfaces, in the order their digit keys reach them. One
+// vocabulary, applied everywhere: the identifier here IS the label on the nav
+// bar, the word in the help overlay, the tab name the companion's `switch_tab`
+// verb accepts, and the heading in docs/tui.md.
+//
+//   board     what the reviewer is doing right now, PR by PR
+//   memory    the reviewer's durable store — the timeline, day by day
+//   digest    what the EOD sweep wrote — a document, read top to bottom
+//   tickets   the tracker tickets adjudication filed
+//   deploy    what the VM runs versus this checkout, and the button that ships
+//   metrics   whether the reviewer is working well over time
+//   feedback  the loop: signal → adjudication → proposal → change → revert
+//   scan      the whole-repo scan's report — findings by unit, triage, the
+//             stage 2 plan, the run and its stop
+//
+// This module imports nothing, so keys.ts, cmdbar.ts and actions.ts can all
+// read the order without a cycle through app.ts.
+
+export const TABS = [
+  "board",
+  "memory",
+  "digest",
+  "tickets",
+  "deploy",
+  "metrics",
+  "feedback",
+  "scan",
+] as const;
+
+export type Tab = (typeof TABS)[number];
+
+export function isTab(value: unknown): value is Tab {
+  return typeof value === "string" && (TABS as readonly string[]).includes(value);
+}
+
+/** The digit key that opens each tab: `1`…`8` in TABS order. */
+export function tabDigit(tab: Tab): string {
+  return String(TABS.indexOf(tab) + 1);
+}
+
+/** The tab a digit key opens, or undefined for a digit no tab owns. */
+export function tabForDigit(ch: string): Tab | undefined {
+  if (!/^[1-9]$/.test(ch)) return undefined;
+  return TABS[Number(ch) - 1];
+}

package/src/tui/termmirror.ts

@@ -0,0 +1,224 @@
+// The embedded-terminal protocol shared by both tmux mirrors (the board's PR
+// pane in `pipane.ts`, the companion column in `sidebar.ts`): the capture
+// argv, capture text -> painted lines, scrollback bounds, and raw stdin ->
+// `tmux send-keys`. Pure functions and constants only — no transport, no
+// state. The mirrors differ in how they run the argv, not in what it says.
+import { closeSgr } from "./paint.js";
+import type { CaptureRange } from "./remote.js";
+
+/**
+ * The tmux arguments of one embedded-terminal capture, after `tmux` and
+ * before any transport: an optional `resize-window` to the painted rectangle,
+ * then `capture-pane -e -p -J` over `range`. Both embedded terminals build
+ * their capture from this — the board's PR pane through `captureArgv`, the
+ * companion column through its local docker runner — so the capture protocol
+ * is spelled once.
+ */
+export function tmuxCaptureArgs(
+  session: string,
+  range?: CaptureRange,
+  size?: { cols: number; rows: number },
+): string[] {
+  const window: string[] = [];
+  if (range && range.startBack > 0) {
+    window.push("-S", `-${range.startBack}`);
+    if (range.endBack !== undefined && range.endBack > 0) window.push("-E", `-${range.endBack}`);
+  }
+  const resize: string[] = size
+    ? ["resize-window", "-t", session, "-x", String(size.cols), "-y", String(size.rows), ";"]
+    : [];
+  return [...resize, "capture-pane", "-e", "-p", "-J", ...window, "-t", session];
+}
+
+/**
+ * Keep SGR (color/style) escapes, drop everything else.
+ *
+ * `capture-pane -e` re-emits the pane's colors, but a pane can also carry
+ * cursor-movement, erase, scroll-region and OSC sequences. Painting those into
+ * our frame would rehome the cursor and shred the board border, so they go.
+ * `paint.sanitizeText` is the wrong tool here — it strips *all* escapes, which
+ * would throw away the colors that make the mirror readable.
+ */
+export function keepSgrOnly(line: string): string {
+  const SEQ =
+    /\x1b\[[0-9;:?<>!$"' ]*[A-Za-z@`{|}~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[ #%()*+][0-9A-Za-z]|\x1b[@-Z\\-_]/g;
+  const kept = line
+    .replace(SEQ, (m) => (/^\x1b\[[0-9;:]*m$/.test(m) ? m : ""))
+    .replace(/\t/g, "  ")
+    .replace(/[\x00-\x08\x0b-\x1a\x1c-\x1f\x7f-\x9f]/g, ""); // C0/C1 minus ESC (0x1b)
+  // Close the row. A tmux pane row often ends with a background or foreground
+  // still set, and an open attribute does not stop at the mirror's edge: it
+  // paints the pane's padding, the board's right border and the companion
+  // column beside it. `truncate` already closes the lines it cuts; this
+  // covers every line that fits, which is most of them.
+  return closeSgr(kept);
+}
+
+/** Keep the mirror bounded — the board only ever paints the tail. */
+const MAX_LINES = 400;
+
+/** Wheel notch = three lines, the usual terminal step. */
+export const SCROLL_STEP = 3;
+
+// ---- keyboard: raw stdin → tmux send-keys ----------------------------------
+
+/** Escape sequences we can name for tmux. Longest-first matching. */
+const SEQUENCES: Array<[string, string]> = [
+  ["\x1b[1;5A", "C-Up"],
+  ["\x1b[1;5B", "C-Down"],
+  ["\x1b[1;5C", "C-Right"],
+  ["\x1b[1;5D", "C-Left"],
+  ["\x1b[5~", "PPage"],
+  ["\x1b[6~", "NPage"],
+  ["\x1b[3~", "DC"],
+  ["\x1b[2~", "IC"],
+  ["\x1b[1~", "Home"],
+  ["\x1b[4~", "End"],
+  ["\x1b[7~", "Home"],
+  ["\x1b[8~", "End"],
+  ["\x1b[A", "Up"],
+  ["\x1b[B", "Down"],
+  ["\x1b[C", "Right"],
+  ["\x1b[D", "Left"],
+  ["\x1b[H", "Home"],
+  ["\x1b[F", "End"],
+  ["\x1b[Z", "BTab"],
+  ["\x1bOA", "Up"],
+  ["\x1bOB", "Down"],
+  ["\x1bOC", "Right"],
+  ["\x1bOD", "Left"],
+  ["\x1bOH", "Home"],
+  ["\x1bOF", "End"],
+  ["\x1b\r", "M-Enter"],
+  ["\x1b\n", "M-Enter"],
+  ["\x1b\x7f", "M-BSpace"],
+];
+
+/** ESC [ with at least one parameter byte, optional intermediates and a final
+ * byte: a whole keyboard report, as opposed to a typed Alt-[. */
+const CSI_WITH_PARAMS = /^\x1b\[[0-9;:<=>?]+[ -/]*[@-~]/;
+
+/** Is `input` exactly one encoding of the End key (the pane's "back to
+ * live")? Read off the same table the keys are translated by. */
+export function isEndKey(input: string): boolean {
+  return SEQUENCES.some(([seq, name]) => name === "End" && seq === input);
+}
+
+/**
+ * The board's Ctrl-q — the byte that hands focus back to the list. It is the
+ * one byte that never reaches the session, so the operator can always get out.
+ */
+export const PANE_ESCAPE = 0x11;
+
+// The rule both embedded surfaces share (docs/tui.md): while focused, a pi
+// pane forwards every byte except this one. `/` commands, completion, history
+// and Ctrl-C are pi's — never put a TUI-side input box in front of them. Same
+// byte in `sidebar.ts`, so there is one way out of every embedded surface.
+
+/**
+ * One raw stdin chunk → the `tmux send-keys` argument groups that reproduce it
+ * inside the session.
+ *
+ * Why groups and not one flat argv: `send-keys -l` is a flag of the *command*,
+ * not of an argument, so literal text and named keys cannot share one
+ * invocation. Runs of printable characters coalesce into a single
+ * `["-l", "--", "<text>"]` group (so typing a word — or pasting a paragraph — is one
+ * round trip), runs of specials coalesce into a single group of key names, and
+ * a chunk that is purely one or the other (the overwhelmingly common case) is
+ * exactly one invocation.
+ *
+ * Ctrl-q is dropped, never translated: the focus chord belongs to the board.
+ */
+export function keysToTmux(buf: Buffer): string[][] {
+  const s = buf.toString("utf8");
+  const groups: string[][] = [];
+  let literal = "";
+  let names: string[] = [];
+  const flushLiteral = (): void => {
+    if (literal.length === 0) return;
+    // `--` ends tmux's options: a literal that begins with `-` (a pasted
+    // markdown list item, a `--flag`) is text for pi, never flags for tmux.
+    groups.push(["-l", "--", literal]);
+    literal = "";
+  };
+  const flushNames = (): void => {
+    if (names.length === 0) return;
+    groups.push(names);
+    names = [];
+  };
+  const pushName = (name: string): void => {
+    flushLiteral();
+    names.push(name);
+  };
+
+  let csi: RegExpExecArray | null;
+  let i = 0;
+  outer: while (i < s.length) {
+    for (const [seq, name] of SEQUENCES) {
+      if (s.startsWith(seq, i)) {
+        pushName(name);
+        i += seq.length;
+        continue outer;
+      }
+    }
+    const ch = s[i]!;
+    const code = ch.codePointAt(0)!;
+    if (code === PANE_ESCAPE) {
+      i += 1; // the board's own chord — it never travels
+      continue;
+    }
+    if (ch === "\r" || ch === "\n") {
+      pushName("Enter");
+    } else if (ch === "\t") {
+      pushName("Tab");
+    } else if (ch === "\x7f" || ch === "\b") {
+      pushName("BSpace");
+    } else if (ch === "\x1b" && (csi = CSI_WITH_PARAMS.exec(s.slice(i))) !== null) {
+      // A complete CSI sequence the table does not name (Alt-Left ESC[1;3D,
+      // CSI-u keys): the application decodes it, so it travels whole.
+      flushNames();
+      literal += csi[0];
+      i += csi[0].length;
+      continue;
+    } else if (ch === "\x1b") {
+      // Alt-<printable> arrives as ESC + the character; a lone ESC is Escape.
+      const next = s[i + 1];
+      if (next !== undefined && next >= " " && next !== "\x7f") {
+        pushName(`M-${next}`);
+        i += 2;
+        continue;
+      }
+      pushName("Escape");
+    } else if (code === 0) {
+      pushName("C-Space");
+    } else if (code < 0x20) {
+      pushName(`C-${String.fromCharCode(code + 96)}`); // 0x01 → C-a …
+    } else {
+      flushNames();
+      literal += ch;
+    }
+    i += 1;
+  }
+  flushLiteral();
+  flushNames();
+  return groups;
+}
+
+/** Capture text → sanitized lines, trailing blanks trimmed, bounded. The
+ * bound is MAX_LINES above the parked window: a capture scrolled `offset`
+ * lines back keeps those `offset` lines too, or the window the renderer cuts
+ * at `length - offset` would fall off the front and paint blank. */
+export function splitCapture(stdout: string, offset = 0): string[] {
+  const lines = stdout.split("\n").map(keepSgrOnly);
+  while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop();
+  return lines.slice(-(MAX_LINES + Math.max(0, offset)));
+}
+
+/** A scrolled capture that came back with less history than the window needs
+ * has reached the top of tmux's scrollback: park the window there instead of
+ * past it (which paints blank under a "↑N" that points at nothing). `rows` is
+ * the painted window height (1 when not yet known). 0 stays 0. */
+export function clampScrollback(offset: number, lineCount: number, rows = 1): number {
+  if (offset <= 0) return 0;
+  return Math.min(offset, Math.max(0, lineCount - Math.max(1, rows)));
+}

package/src/tui/theme.ts

@@ -0,0 +1,95 @@
+// Semantic truecolor theme: every lifecycle
+// state owns a hue used consistently across the list, detail, events, and
+// legend — a glance at the color tells the state without reading. Verdicts
+// and anomalies get their own fixed colors.
+import { ACCENT, MUTED } from "./design.js";
+import { STATE_GLYPHS } from "./model.js";
+import { ESC, rgb } from "./paint.js";
+
+export const FG = {
+  reviewing: rgb(97, 175, 239), // blue — the daemon is on it
+  queued: rgb(140, 148, 160), // grey — waiting its turn
+  awaiting_author: rgb(229, 192, 123), // yellow — ball with the author
+  // Magenta belongs to the legacy NEEDS_HUMAN *verdict* spelling that older
+  // rounds still carry. It is not a lifecycle state, so `stateColor` can
+  // never reach this key.
+  needs_human: rgb(198, 120, 221),
+  tracked: rgb(92, 99, 112), // dim grey — known, no live trigger
+  closed: rgb(92, 99, 112),
+  approve: rgb(152, 195, 121), // green
+  request_changes: rgb(209, 154, 102), // orange
+  anomaly: rgb(224, 108, 117), // red
+  accent: ACCENT, // the one accent (design.ts) — titles, links, focus
+  text: rgb(171, 178, 191),
+  dim: MUTED,
+  author: rgb(152, 195, 121),
+} as const;
+
+export const RESET = `${ESC}0m`;
+
+export function stateColor(state: string): string {
+  return (FG as Record<string, string>)[state] ?? FG.text;
+}
+
+export function verdictColor(verdict: string | null | undefined): string {
+  if (verdict === "APPROVE") return FG.approve;
+  if (verdict === "REQUEST_CHANGES") return FG.request_changes;
+  // "ESCALATE" is the legacy spelling older recorded rounds still carry.
+  if (verdict === "NEEDS_HUMAN" || verdict === "ESCALATE") return FG.needs_human;
+  return FG.dim;
+}
+
+/** The verdict chip's text, unstyled: APPROVE → ✓A, REQUEST_CHANGES → ✗RC,
+ * NEEDS_HUMAN (and its legacy ESCALATE spelling) → ⚑H, any other verdict as
+ * itself, none → "". What the board measures is what it paints. */
+export function verdictLabel(verdict: string | null | undefined): string {
+  if (!verdict) return "";
+  return verdict === "APPROVE"
+    ? "✓A"
+    : verdict === "REQUEST_CHANGES"
+      ? "✗RC"
+      : verdict === "NEEDS_HUMAN" || verdict === "ESCALATE"
+        ? "⚑H"
+        : verdict;
+}
+
+/** Compact verdict chip: `verdictLabel` in the verdict's color. */
+export function verdictChip(verdict: string | null | undefined): string {
+  if (!verdict) return "";
+  return `${verdictColor(verdict)}${verdictLabel(verdict)}${RESET}`;
+}
+
+/** 45s / 12m / 3h / 2d — age at a glance. */
+export function fmtAge(iso: string | null | undefined, now: Date): string {
+  if (!iso) return "—";
+  const s = Math.max(0, Math.floor((now.getTime() - new Date(iso).getTime()) / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+/** Colored one-line glyph legend rendered under the PR list. */
+export function legendLine(): string {
+  // The lifecycle glyphs are the board's own (`STATE_GLYPHS`); `↻` is the
+  // stale-recheck prefix `glyphFor` adds.
+  const parts: Array<[string, string, string]> = [
+    [STATE_GLYPHS.reviewing, "reviewing", FG.reviewing],
+    [STATE_GLYPHS.queued, "queued", FG.queued],
+    [STATE_GLYPHS.awaiting_author, "author", FG.awaiting_author],
+    [STATE_GLYPHS.tracked, "tracked", FG.tracked],
+    ["↻", "stale", FG.accent],
+  ];
+  return parts
+    .map(([g, label, color]) => `${color}${g}${RESET} ${FG.dim}${label}${RESET}`)
+    .join("  ");
+}
+
+/** OSC-8 terminal hyperlink — Ctrl+click works natively in modern terminals. */
+export function osc8(url: string, text: string): string {
+  return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
+
+export function prUrl(repo: string, pr: number): string {
+  return `https://github.com/${repo}/pull/${pr}`;
+}