@pipefy/pipefy-process-coder 0.1.0

package/src/report/run.ts

@@ -0,0 +1,475 @@
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { mkdirp, writeFile, writeJson, exists } from '../util/fsx.ts';
+import { paths } from '../workspace/layout.ts';
+import type { PayloadEnvelope } from '../model/payload.ts';
+import type { Plan } from '../apply/types.ts';
+import { integrationsFrom, renderIntegrations, type IntegrationsView } from './integrations.ts';
+
+/**
+ * A run record: what one invocation of the tool did to a pipe, kept in the
+ * workspace next to the state it produced.
+ *
+ * The reason this is a first-class artifact rather than terminal scrollback is
+ * that the write path is non-atomic (PLAN.md §5). When an apply half-succeeds,
+ * the question a week later is not "what did the plan say" — the plan file
+ * already answers that — but "which of those calls actually landed, in what
+ * order, and what did the pipe look like on either side of it". The plan file
+ * holds the requests; the run folder holds the *outcome*, plus the state.
+ *
+ * Each run gets a directory:
+ *
+ *   runs/2026-08-30T00-12-04Z--apply--a1b2c3/
+ *     report.md            what happened, readable, credentials redacted
+ *     run.json             the same thing structured
+ *     pipe.json            the payload envelope as of the end of the run
+ *     integrations.json    the outward-facing surface, raw
+ *     pipe.before.json     the payload the run started from (writes only)
+ *     integrations.before.json
+ *
+ * `report.md` is written to be shareable — it names hosts and ids but never a
+ * credential. The two `.json` payloads are not: they are a full copy of the
+ * pipe, HTTP-request auth values included.
+ */
+
+export type RunKind = 'pull' | 'plan' | 'apply' | 'dry-run' | 'verify' | 'scaffold';
+
+export type RunOutcome = 'ok' | 'partial' | 'failed' | 'refused' | 'no-op';
+
+export type RunStepRecord = {
+  index: number;
+  id: string;
+  description: string;
+  entity: string;
+  op: string;
+  kind: string;
+  status: string;
+  /** Destructive / unverified / internal-api, as the plan tagged it. */
+  tags: string[];
+  error?: string;
+  /** The id the step created, when it created one. */
+  produced?: string | number;
+  durationMs?: number;
+};
+
+export type RunRecord = {
+  id: string;
+  kind: RunKind;
+  /** The command as invoked, for reproduction. Flag values are kept; tokens are not. */
+  command: string;
+  tool: { name: string; version: string };
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  workspace: string;
+  repo: { id: number; uuid: string | null; name: string; kind: 'pipe' | 'table' };
+  outcome: RunOutcome;
+  /** One line, the way the terminal summarised it. */
+  summary: string;
+  planId?: string;
+  preApplyVersionId?: string | null;
+  counts: { steps: number; done: number; failed: number; skipped: number; pending: number; blocked: number };
+  steps: RunStepRecord[];
+  blocked: Array<{ label: string; entity: string; op: string; reason?: string; ask?: number }>;
+  warnings: string[];
+  notes: string[];
+  verification?: { ran: boolean; ok: boolean; detail?: string };
+  /** Read coverage of the state this run ended with. */
+  coverage?: Record<string, string>;
+  integrations?: { before?: IntegrationsView['counts']; after?: IntegrationsView['counts'] };
+  artifacts: string[];
+};
+
+export type RunContext = {
+  workspace: string;
+  repo: { id: number; uuid: string | null; name: string; kind: 'pipe' | 'table' };
+  command: string;
+  /** When the command began, for commands that learn their workspace late. */
+  startedAt?: Date;
+};
+
+const stamp = (d = new Date()) => d.toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z');
+
+/**
+ * The command as typed, for reproduction — with any token elided. `--token` is
+ * the one flag whose value must never reach a file, and `pipe login --token` is
+ * a real invocation someone might run inside a workspace.
+ */
+export const invocation = (argv = process.argv.slice(2)): string => {
+  const parts: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] as string;
+    if (/^--token(=|$)/.test(a)) {
+      parts.push('--token <elided>');
+      if (!a.includes('=') && argv[i + 1] && !argv[i + 1]!.startsWith('-')) i++;
+      continue;
+    }
+    parts.push(a);
+  }
+  return `pipe ${parts.join(' ')}`.trim();
+};
+
+/** `runs/` lives at the workspace root, not under `.ppc/` — these are for reading. */
+export const runsDir = (root: string) => join(paths(root).root, 'runs');
+
+export const runDir = (root: string, id: string) => join(runsDir(root), id);
+
+/**
+ * Collects what happened while a command runs.
+ *
+ * Deliberately tolerant: a recorder that throws would turn a successful apply
+ * into a failed command, and the record is worth less than the work it
+ * describes. Everything here is additive and total.
+ */
+export class RunRecorder {
+  readonly id: string;
+  readonly startedAt: Date;
+  private notes: string[] = [];
+  private warnings: string[] = [];
+  private plan: Plan | null = null;
+  private verification: RunRecord['verification'] | undefined;
+  private beforeEnv: PayloadEnvelope | null = null;
+  private afterEnv: PayloadEnvelope | null = null;
+
+  readonly kind: RunKind;
+  readonly ctx: RunContext;
+
+  constructor(kind: RunKind, ctx: RunContext) {
+    this.kind = kind;
+    this.ctx = ctx;
+    /**
+     * `startedAt` is passed in by commands that only learn where the workspace
+     * is at the end — a pull cannot name its own output directory until
+     * discovery has run, and a run that reports 0.0s for a 60-second snapshot is
+     * worse than no timing at all.
+     */
+    this.startedAt = ctx.startedAt ?? new Date();
+    this.id = `${stamp(this.startedAt)}--${kind}`;
+  }
+
+  note(text: string) {
+    this.notes.push(text);
+  }
+
+  warn(text: string) {
+    this.warnings.push(text);
+  }
+
+  /** The plan is the step list; recording it is how the report gets its detail. */
+  fromPlan(plan: Plan) {
+    this.plan = plan;
+  }
+
+  verified(ok: boolean, detail?: string) {
+    this.verification = { ran: true, ok, ...(detail ? { detail } : {}) };
+  }
+
+  /** The payload the run started from, when the command knows it. */
+  before(env: PayloadEnvelope | null) {
+    this.beforeEnv = env;
+  }
+
+  after(env: PayloadEnvelope | null) {
+    this.afterEnv = env;
+  }
+
+  build(outcome: RunOutcome, summary: string): RunRecord {
+    const finished = new Date();
+    const steps = (this.plan?.steps ?? []).map((s): RunStepRecord => {
+      const started = s.startedAt ? Date.parse(s.startedAt) : NaN;
+      const ended = s.finishedAt ? Date.parse(s.finishedAt) : NaN;
+      return {
+        index: s.index,
+        id: s.id,
+        description: s.description,
+        entity: String(s.entity),
+        op: s.op,
+        kind: s.kind,
+        status: s.status,
+        tags: [
+          ...(s.destructive ? ['destructive'] : []),
+          ...(s.unverified ? ['unverified'] : []),
+          ...(s.kind.startsWith('internal') ? ['internal-api'] : []),
+        ],
+        ...(s.error ? { error: s.error } : {}),
+        ...(producedId(s.result) !== undefined ? { produced: producedId(s.result) } : {}),
+        ...(Number.isFinite(started) && Number.isFinite(ended) ? { durationMs: ended - started } : {}),
+      };
+    });
+
+    const count = (status: string) => steps.filter((s) => s.status === status).length;
+
+    const env = this.afterEnv;
+    return {
+      id: this.id,
+      kind: this.kind,
+      command: this.ctx.command,
+      tool: { name: 'pipefy-process-coder', version: '0.1.0' },
+      startedAt: this.startedAt.toISOString(),
+      finishedAt: finished.toISOString(),
+      durationMs: finished.getTime() - this.startedAt.getTime(),
+      workspace: this.ctx.workspace,
+      repo: this.ctx.repo,
+      outcome,
+      summary,
+      ...(this.plan ? { planId: this.plan.id, preApplyVersionId: this.plan.preApplyVersionId ?? null } : {}),
+      counts: {
+        steps: steps.length,
+        done: count('done'),
+        failed: count('failed'),
+        skipped: count('skipped'),
+        pending: count('pending'),
+        blocked: this.plan?.blocked.length ?? 0,
+      },
+      steps,
+      blocked: (this.plan?.blocked ?? []).map((b) => ({
+        label: b.label,
+        entity: String(b.entity),
+        op: b.op,
+        ...(b.reason ? { reason: b.reason } : {}),
+        ...(b.ask ? { ask: b.ask } : {}),
+      })),
+      // Deduplicated: a multi-repo pull collects the same coverage note from
+      // every tree, and three copies of it read as three problems.
+      warnings: [...new Set([...(this.plan?.warnings ?? []), ...this.warnings])],
+      notes: [...new Set(this.notes)],
+      ...(this.verification ? { verification: this.verification } : {}),
+      ...(env ? { coverage: env.coverage as unknown as Record<string, string> } : {}),
+      integrations: {
+        ...(this.beforeEnv ? { before: integrationsFrom(this.beforeEnv).counts } : {}),
+        ...(this.afterEnv ? { after: integrationsFrom(this.afterEnv).counts } : {}),
+      },
+      artifacts: [],
+    };
+  }
+
+  /**
+   * Write the run folder. Never throws: a failure to record is reported as a
+   * note and nothing more, because the alternative is a command that did its
+   * work and then reported failure.
+   */
+  async write(outcome: RunOutcome, summary: string): Promise<{ dir: string; error?: string } | null> {
+    try {
+      const record = this.build(outcome, summary);
+      const dir = runDir(this.ctx.workspace, record.id);
+      await mkdirp(dir);
+
+      const written: string[] = [];
+      const put = async (name: string, value: unknown) => {
+        await writeJson(join(dir, name), value);
+        written.push(name);
+      };
+
+      if (this.afterEnv) {
+        await put('pipe.json', this.afterEnv);
+        await put('integrations.json', integrationsFrom(this.afterEnv));
+      }
+      if (this.beforeEnv && this.kind !== 'pull') {
+        await put('pipe.before.json', this.beforeEnv);
+        await put('integrations.before.json', integrationsFrom(this.beforeEnv));
+      }
+
+      record.artifacts = [...written, 'report.md', 'run.json'];
+      await writeJson(join(dir, 'run.json'), record);
+      await writeFile(join(dir, 'report.md'), renderRunReport(record, this.afterEnv, this.beforeEnv));
+      await appendIndex(this.ctx.workspace, record);
+      return { dir };
+    } catch (e) {
+      return { dir: runDir(this.ctx.workspace, this.id), error: (e as Error).message };
+    }
+  }
+}
+
+/** The created id, from whatever shape the mutation answered with. */
+const producedId = (result: unknown): string | number | undefined => {
+  if (!result || typeof result !== 'object') return undefined;
+  const seen = new Set<unknown>();
+  const walk = (v: unknown, depth: number): string | number | undefined => {
+    if (depth > 4 || !v || typeof v !== 'object' || seen.has(v)) return undefined;
+    seen.add(v);
+    const o = v as Record<string, unknown>;
+    if (typeof o['id'] === 'string' || typeof o['id'] === 'number') return o['id'] as string | number;
+    for (const val of Object.values(o)) {
+      const hit = walk(val, depth + 1);
+      if (hit !== undefined) return hit;
+    }
+    return undefined;
+  };
+  return walk(result, 0);
+};
+
+const OUTCOME_WORD: Record<RunOutcome, string> = {
+  ok: 'succeeded',
+  partial: 'partially applied',
+  failed: 'failed',
+  refused: 'refused before sending anything',
+  'no-op': 'had nothing to do',
+};
+
+export const renderRunReport = (
+  r: RunRecord,
+  after: PayloadEnvelope | null,
+  before: PayloadEnvelope | null,
+): string => {
+  const L: string[] = [];
+  const secs = (r.durationMs / 1000).toFixed(1);
+
+  L.push(`# ${r.kind} — ${r.repo.name} (${r.repo.id})`, '');
+  L.push(`**${OUTCOME_WORD[r.outcome]}** · ${r.summary}`, '');
+  L.push('| | |', '| --- | --- |');
+  L.push(`| Run | \`${r.id}\` |`);
+  L.push(`| Command | \`${r.command}\` |`);
+  L.push(`| Started | ${r.startedAt} |`);
+  L.push(`| Duration | ${secs}s |`);
+  L.push(`| Workspace | \`${r.workspace}\` |`);
+  if (r.planId) L.push(`| Plan | \`${r.planId}\` |`);
+  if (r.preApplyVersionId) L.push(`| Pre-apply snapshot | \`${r.preApplyVersionId}\` |`);
+  if (after) L.push(`| Read path | ${after.source}${after.versionId ? ` \`${after.versionId.slice(0, 8)}\`` : ''} |`);
+  if (r.counts.steps) {
+    L.push(
+      `| Steps | ${r.counts.steps} — ${r.counts.done} done, ${r.counts.failed} failed, ` +
+        `${r.counts.skipped} skipped${r.counts.pending ? `, ${r.counts.pending} never attempted` : ''} |`,
+    );
+  }
+  if (r.verification) L.push(`| Verification | ${r.verification.ok ? 'clean' : 'found differences'} |`);
+  L.push('');
+
+  if (r.steps.length) {
+    L.push('## Steps', '');
+    L.push('| # | Step | Entity | Op | Status | Result |', '| --- | --- | --- | --- | --- | --- |');
+    for (const s of r.steps) {
+      const result = s.error
+        ? `\`${s.error.replace(/\|/g, '\\|').slice(0, 160)}\``
+        : s.produced !== undefined
+          ? `id ${s.produced}`
+          : s.status === 'done'
+            ? 'applied'
+            : '—';
+      const tags = s.tags.length ? ` <sub>${s.tags.join(' ')}</sub>` : '';
+      L.push(
+        `| ${s.index} | ${s.description.replace(/\|/g, '\\|')}${tags} | ${s.entity} | ${s.op} | ` +
+          `${statusMark(s.status)} | ${result} |`,
+      );
+    }
+    L.push('');
+
+    const failures = r.steps.filter((s) => s.status === 'failed' || s.status === 'skipped');
+    if (failures.length) {
+      L.push('### What did not land', '');
+      for (const s of failures) {
+        L.push(`- **${s.description}** (${s.status}) — ${s.error ?? 'no reason recorded'}`);
+      }
+      L.push('');
+    }
+  }
+
+  if (r.blocked.length) {
+    L.push('## Refused before sending', '');
+    L.push('These changes are in the workspace and have no write path. Nothing was attempted.', '');
+    for (const b of r.blocked) {
+      L.push(`- **${b.label}** — ${b.reason ?? 'no write path'}${b.ask ? ` (ask ${b.ask})` : ''}`);
+    }
+    L.push('');
+  }
+
+  if (r.warnings.length) {
+    L.push('## Warnings', '');
+    for (const w of r.warnings) L.push(`- ${w}`);
+    L.push('');
+  }
+
+  if (after) {
+    const t = after.payload.relations;
+    L.push('## The pipe, as of the end of this run', '');
+    L.push('| Group | Count | Coverage |', '| --- | --- | --- |');
+    for (const [name, rows] of Object.entries(t)) {
+      const cov = (r.coverage ?? {})[name] ?? 'unknown';
+      if (!rows.length && cov === 'complete') continue;
+      L.push(`| ${name} | ${rows.length} | ${cov}${cov === 'complete' ? '' : ' ⚠'} |`);
+    }
+    L.push('');
+    const gaps = Object.entries(r.coverage ?? {}).filter(([, c]) => c !== 'complete');
+    if (gaps.length) {
+      L.push(
+        `⚠ ${gaps.length} group${gaps.length === 1 ? '' : 's'} not fully read. ` +
+          'A count of 0 there means "not read", not "empty".',
+        '',
+      );
+    }
+
+    L.push('## Integrations', '');
+    if (before) {
+      const b = integrationsFrom(before).counts;
+      const a = integrationsFrom(after).counts;
+      const moved = (Object.keys(a) as Array<keyof typeof a>).filter((k) => a[k] !== b[k]);
+      if (moved.length) {
+        L.push(`Changed by this run: ${moved.map((k) => `${k} ${b[k]} → ${a[k]}`).join(', ')}.`, '');
+      }
+    }
+    L.push(...renderIntegrations(integrationsFrom(after)));
+    L.push('');
+  }
+
+  if (r.notes.length) {
+    L.push('## Notes', '');
+    for (const n of r.notes) L.push(`- ${n}`);
+    L.push('');
+  }
+
+  L.push('---', '', `Artifacts in this folder: ${r.artifacts.map((a) => `\`${a}\``).join(', ')}.`);
+  L.push(
+    '',
+    '`pipe.json` and `integrations.json` are full copies of the pipe and include ' +
+      'webhook URLs and HTTP-request credentials. This report does not.',
+  );
+  return L.join('\n') + '\n';
+};
+
+const statusMark = (status: string) =>
+  status === 'done' ? 'done' : status === 'failed' ? '**failed**' : status === 'skipped' ? 'skipped' : status;
+
+/**
+ * One line per run in `runs/index.md`, newest last.
+ *
+ * Appended rather than regenerated so that a run folder someone has deleted or
+ * moved does not silently vanish from the history.
+ */
+const appendIndex = async (root: string, r: RunRecord) => {
+  const path = join(runsDir(root), 'index.md');
+  const header = [
+    '# Runs',
+    '',
+    'Every invocation that read or wrote this pipe, oldest first. Each row links to',
+    'the run folder, which holds the report, the payload, and the integration surface',
+    'as of the end of that run.',
+    '',
+    '| When | Run | Kind | Outcome | Steps | Summary |',
+    '| --- | --- | --- | --- | --- | --- |',
+  ].join('\n');
+
+  if (!(await exists(path))) await writeFile(path, header + '\n');
+
+  const row =
+    `| ${r.startedAt.replace('T', ' ').slice(0, 19)} | [${r.id}](${r.id}/report.md) | ${r.kind} | ` +
+    `${r.outcome} | ${r.counts.steps ? `${r.counts.done}/${r.counts.steps}` : '—'} | ` +
+    `${r.summary.replace(/\|/g, '\\|')} |\n`;
+  await fs.appendFile(path, row, 'utf8');
+};
+
+/** Read every run record in a workspace, oldest first. */
+export const listRuns = async (root: string): Promise<RunRecord[]> => {
+  const dir = runsDir(root);
+  if (!(await exists(dir))) return [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const out: RunRecord[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    try {
+      out.push(JSON.parse(await fs.readFile(join(dir, e.name, 'run.json'), 'utf8')) as RunRecord);
+    } catch {
+      // A run folder without a readable run.json is skipped, not fatal: the
+      // report beside it may still be the thing someone wants to read.
+    }
+  }
+  return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+};

package/src/util/fsx.ts

@@ -0,0 +1,45 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pretty } from './json.ts';
+
+export const mkdirp = (p: string) => fs.mkdir(p, { recursive: true });
+
+export const writeFile = async (p: string, content: string) => {
+  await mkdirp(dirname(p));
+  await fs.writeFile(p, content, 'utf8');
+};
+
+export const writeJson = (p: string, v: unknown) => writeFile(p, pretty(v));
+
+export const readJson = async <T>(p: string): Promise<T> => {
+  const raw = await fs.readFile(p, 'utf8');
+  try {
+    return JSON.parse(raw) as T;
+  } catch (e) {
+    throw new Error(`${p}: invalid JSON - ${(e as Error).message}`);
+  }
+};
+
+export const exists = async (p: string) => {
+  try { await fs.stat(p); return true; } catch { return false; }
+};
+
+/** Every .json file under a directory, recursively, sorted. */
+export const listJson = async (dir: string): Promise<string[]> => {
+  const acc: string[] = [];
+  const walk = async (d: string) => {
+    let entries: Array<{ name: string; isDirectory(): boolean }>;
+    try {
+      entries = (await fs.readdir(d, { withFileTypes: true })) as unknown as Array<{ name: string; isDirectory(): boolean }>;
+    } catch { return; }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) await walk(full);
+      else if (e.name.endsWith('.json')) acc.push(full);
+    }
+  };
+  await walk(dir);
+  return acc.sort();
+};
+
+export const rmrf = (p: string) => fs.rm(p, { recursive: true, force: true });

package/src/util/git.ts

@@ -0,0 +1,32 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export type GitStatus = {
+  /** `git` resolves at all — on PATH, runnable. */
+  installed: boolean;
+  /** `root` sits inside a working tree git already tracks. */
+  tracked: boolean;
+};
+
+/**
+ * Best-effort, and never throws: a workspace with no local version control is
+ * an advisory, not a blocker. `pipe rollback` only restores the *latest*
+ * snapshot (commands/misc.ts), so it stops covering a rollback the moment
+ * anything re-snapshots the repo — which a normal `pipe apply` does on its own
+ * read-back. A local git history is what covers the gap.
+ */
+export const checkGit = async (root: string): Promise<GitStatus> => {
+  try {
+    await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root });
+    return { installed: true, tracked: true };
+  } catch {
+    try {
+      await execFileAsync('git', ['--version']);
+      return { installed: true, tracked: false };
+    } catch {
+      return { installed: false, tracked: false };
+    }
+  }
+};

package/src/util/json.ts

@@ -0,0 +1,55 @@
+/**
+ * Canonical JSON. PLAN.md §3: the round-trip exit criterion is *semantic*
+ * equality under a canonical form, never byte equality — `JSON.parse` turns
+ * `index: 6.0` into `6`, and fractional indices invite float noise.
+ */
+
+export type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+/** Normalise a number to a stable representation. -0 -> 0, 6.0 -> 6. */
+const num = (n: number): number => {
+  if (!Number.isFinite(n)) return n;
+  if (Object.is(n, -0)) return 0;
+  // Collapse float noise past 10 significant decimals; index and lateness are
+  // the only fractional numbers in the payload and never need more.
+  const r = Number(n.toFixed(10));
+  return Object.is(r, -0) ? 0 : r;
+};
+
+export const canonical = (v: unknown): Json => {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'number') return num(v);
+  if (typeof v === 'boolean' || typeof v === 'string') return v;
+  if (Array.isArray(v)) return v.map(canonical);
+  if (typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    const res: { [k: string]: Json } = {};
+    for (const k of Object.keys(o).sort()) {
+      if (o[k] === undefined) continue;
+      res[k] = canonical(o[k]);
+    }
+    return res;
+  }
+  return String(v);
+};
+
+export const canonicalString = (v: unknown): string => JSON.stringify(canonical(v));
+
+export const deepEqual = (a: unknown, b: unknown): boolean => canonicalString(a) === canonicalString(b);
+
+/** Stable pretty JSON for files a human and Claude will read and edit. */
+export const pretty = (v: unknown): string => JSON.stringify(v, null, 2) + '\n';
+
+export const clone = <T>(v: T): T => (v === undefined ? v : (JSON.parse(JSON.stringify(v)) as T));
+
+/** Walk every string in a structure, replacing it. Used by the %{id} rewriter. */
+export const mapStrings = <T>(v: T, fn: (s: string) => string): T => {
+  if (typeof v === 'string') return fn(v) as unknown as T;
+  if (Array.isArray(v)) return v.map((x) => mapStrings(x, fn)) as unknown as T;
+  if (v && typeof v === 'object') {
+    const res: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) res[k] = mapStrings(val, fn);
+    return res as unknown as T;
+  }
+  return v;
+};

package/src/util/log.ts

@@ -0,0 +1,76 @@
+const ESC = '\x1b[';
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code: string) => (s: string) => (useColor ? `${ESC}${code}m${s}${ESC}0m` : s);
+
+export const dim = c('2');
+export const bold = c('1');
+export const red = c('31');
+export const green = c('32');
+export const yellow = c('33');
+export const blue = c('36');
+export const magenta = c('35');
+
+let verbose = false;
+export const setVerbose = (v: boolean) => { verbose = v; };
+export const isVerbose = () => verbose;
+
+/**
+ * While a live progress display owns the screen, ordinary log lines cannot go
+ * straight to stderr: the display repaints a block of lines in place, and an
+ * interleaved write lands inside that block and garbles the frame. A claimed
+ * sink receives them instead — see src/util/tui.ts.
+ *
+ * `step` is dropped rather than forwarded, being the progress chatter the
+ * display is already showing. Anything the user must not miss — warn, error,
+ * ok — is forwarded.
+ */
+export type LogSink = { note: (text: string) => void };
+
+let sink: LogSink | null = null;
+export const claimLogSink = (s: LogSink | null) => {
+  sink = s;
+};
+export const hasLogSink = () => sink !== null;
+
+/** Colour is for a terminal. A report is a file, so it gets none. */
+export const stripAnsi = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, '');
+export const out = (s = '') => process.stdout.write(s + '\n');
+export const info = (s: string) => {
+  if (sink) sink.note(s);
+  else process.stderr.write(s + '\n');
+};
+export const debug = (s: string) => { if (verbose) process.stderr.write(dim('· ' + s) + '\n'); };
+export const warn = (s: string) => {
+  if (sink) sink.note(yellow('! ') + s);
+  else process.stderr.write(yellow('! ') + s + '\n');
+};
+export const error = (s: string) => {
+  if (sink) sink.note(red('x ') + s);
+  else process.stderr.write(red('x ') + s + '\n');
+};
+export const ok = (s: string) => {
+  if (sink) sink.note(green('+ ') + s);
+  else process.stderr.write(green('+ ') + s + '\n');
+};
+export const step = (s: string) => {
+  if (sink) return;
+  process.stderr.write(blue('> ') + s + '\n');
+};
+
+const CLEAR_LINE = `\r${ESC}2K`;
+
+/** Single-line progress that collapses to nothing on a non-tty. */
+export const progress = (s: string) => {
+  if (!process.stderr.isTTY) return;
+  process.stderr.write(CLEAR_LINE + dim('  ' + s));
+};
+export const progressDone = () => { if (process.stderr.isTTY) process.stderr.write(CLEAR_LINE); };
+
+export class UserError extends Error {
+  hint: string | undefined;
+  constructor(message: string, hint?: string) {
+    super(message);
+    this.name = 'UserError';
+    this.hint = hint;
+  }
+}