@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/refresh-api.ts

@@ -0,0 +1,169 @@
+/**
+ * `zond refresh-api <name>` — re-fetch the OpenAPI spec and regenerate
+ * the four artifacts (spec.json, .api-catalog.yaml, .api-resources.yaml,
+ * .api-fixtures.yaml).
+ *
+ * Without --spec, refresh re-reads from the source recorded at register
+ * time (treating workspace-relative paths as the local snapshot — which
+ * is a no-op refresh useful only for re-emitting derived artifacts after
+ * a builder change). With --spec, the new source is fetched, dereferenced,
+ * and replaces the local snapshot.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getDb } from "../../db/schema.ts";
+import { findCollectionByNameOrId, updateCollection } from "../../db/queries.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { readOpenApiSpec } from "../../core/generator/openapi-reader.ts";
+import {
+  resolveCollectionSpec,
+  writeArtifactsFromDoc,
+  SPEC_SNAPSHOT_FILENAME,
+} from "../../core/setup-api.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface RefreshApiOptions {
+  api: string;
+  /** When provided, fetch this source and replace spec.json. Otherwise
+   *  re-read the existing local snapshot and just rebuild artifacts. */
+  spec?: string;
+  insecure?: boolean;
+  json?: boolean;
+  dbPath?: string;
+}
+
+export async function refreshApiCommand(opts: RefreshApiOptions): Promise<number> {
+  try {
+    getDb(opts.dbPath);
+  } catch (err) {
+    const m = `DB unavailable: ${(err as Error).message}`;
+    if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const collection = findCollectionByNameOrId(opts.api);
+  if (!collection) {
+    const m = `API '${opts.api}' not found.`;
+    if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+    return 2;
+  }
+
+  if (!collection.base_dir) {
+    const m = `API '${opts.api}' has no base_dir recorded — cannot refresh artifacts.`;
+    if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const workspaceRoot = findWorkspaceRoot().root;
+  const baseDir = collection.base_dir;
+
+  // 1. Pick spec source
+  let specSource: string;
+  let usedExternal: boolean;
+  if (opts.spec) {
+    specSource = opts.spec;
+    usedExternal = true;
+  } else if (collection.openapi_spec) {
+    specSource = resolveCollectionSpec(collection.openapi_spec);
+    usedExternal = false;
+    if (!existsSync(specSource) && !/^https?:\/\//i.test(specSource)) {
+      const m = `Local spec snapshot missing at ${specSource}. Pass --spec <path|url> to re-pull from upstream.`;
+      if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+      return 2;
+    }
+  } else {
+    const m = `API '${opts.api}' has no spec recorded. Pass --spec <path|url>.`;
+    if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+    return 2;
+  }
+
+  // 2. Dereference (fetch if URL)
+  let doc: unknown;
+  try {
+    doc = await readOpenApiSpec(specSource, { insecure: opts.insecure });
+  } catch (err) {
+    const m = `Failed to read spec ${specSource}: ${(err as Error).message}`;
+    if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+    return 2;
+  }
+
+  // 3. Determine baseUrl from the doc
+  const baseUrl = ((doc as any).servers?.[0]?.url as string | undefined) ?? "";
+
+  // 4. Write spec.json + 3 artifacts
+  writeArtifactsFromDoc({
+    doc,
+    baseDir,
+    apiName: collection.name,
+    baseUrl,
+    workspaceRoot,
+  });
+
+  // 5. If we pulled fresh from external, ensure the DB points to the local snapshot
+  const expectedDbSpec = `apis/${collection.name}/${SPEC_SNAPSHOT_FILENAME}`;
+  if (collection.openapi_spec !== expectedDbSpec) {
+    updateCollection(collection.id, { openapi_spec: expectedDbSpec });
+  }
+
+  // 6. Surface result
+  const localSpec = join(baseDir, SPEC_SNAPSHOT_FILENAME);
+  const endpointCount = readEndpointCount(localSpec);
+  const result = {
+    api: collection.name,
+    baseDir,
+    spec: localSpec,
+    pulledFrom: usedExternal ? specSource : null,
+    endpointCount,
+    artifacts: [".api-catalog.yaml", ".api-resources.yaml", ".api-fixtures.yaml"],
+  };
+
+  if (opts.json) {
+    printJson(jsonOk("refresh-api", result));
+  } else {
+    printSuccess(`Refreshed '${collection.name}' (${endpointCount} endpoints)${usedExternal ? ` from ${specSource}` : ""}`);
+    process.stdout.write(`  spec: ${localSpec}\n`);
+    process.stdout.write(`  artifacts: ${result.artifacts.join(", ")}\n`);
+    process.stdout.write(`  Run \`zond doctor --api ${collection.name}\` to verify fixtures.\n`);
+  }
+  return 0;
+}
+
+function readEndpointCount(specPath: string): number {
+  try {
+    const doc = JSON.parse(readFileSync(specPath, "utf-8")) as any;
+    let count = 0;
+    for (const item of Object.values(doc.paths ?? {})) {
+      if (item && typeof item === "object") {
+        for (const k of Object.keys(item as object)) {
+          if (["get", "post", "put", "patch", "delete", "head", "options"].includes(k.toLowerCase())) count++;
+        }
+      }
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerRefreshApi(program: Command): void {
+  program
+    .command("refresh-api <name>")
+    .description("Re-snapshot the OpenAPI spec into apis/<name>/spec.json and regenerate the 3 artifacts (catalog/resources/fixtures)")
+    .option("--spec <path>", "Pull fresh from this path or URL (overrides registered source)")
+    .option("--insecure", "Allow self-signed TLS when --spec is an https URL")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (name: string, opts, cmd: Command) => {
+      process.exitCode = await refreshApiCommand({
+        api: name,
+        spec: opts.spec,
+        insecure: opts.insecure === true,
+        dbPath: typeof opts.db === "string" ? opts.db : undefined,
+        json: globalJson(cmd),
+      });
+    });
+}

package/src/cli/commands/remove-api.ts

@@ -0,0 +1,150 @@
+/**
+ * `zond remove api <name>` — unregister an API from the workspace.
+ *
+ * Mirrors `zond add api`. Removes the `collections` row, optionally the
+ * associated `runs`/`results`, and (by default) the `apis/<name>/`
+ * directory on disk. If the removed API was the active one
+ * (`.zond/current-api`), the marker is cleared.
+ *
+ * Without `--purge`, runs that referenced the collection are detached
+ * (`collection_id = NULL`) so historical run data survives the removal.
+ * `--purge` deletes them outright. `--keep-files` leaves the directory
+ * on disk and only drops the DB row, useful when the user wants to
+ * snapshot the artifacts elsewhere first.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { getDb } from "../../db/schema.ts";
+import {
+  deleteCollection,
+  findCollectionByNameOrId,
+} from "../../db/queries.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { clearCurrentApi, readCurrentApi } from "../../core/context/current.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface RemoveApiOptions {
+  api: string;
+  purge?: boolean;
+  keepFiles?: boolean;
+  yes?: boolean;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export interface RemoveApiResult {
+  api: string;
+  collectionId: number;
+  removedDir: string | null;
+  detachedRuns: number;
+  deletedRuns: number;
+  clearedCurrent: boolean;
+}
+
+export async function removeApiCommand(opts: RemoveApiOptions): Promise<number> {
+  try {
+    getDb(opts.dbPath);
+  } catch (err) {
+    const m = `DB unavailable: ${(err as Error).message}`;
+    if (opts.json) printJson(jsonError("remove-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const collection = findCollectionByNameOrId(opts.api);
+  if (!collection) {
+    const m = `API '${opts.api}' not found.`;
+    if (opts.json) printJson(jsonError("remove-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const db = getDb();
+  const runsCount = (db
+    .query("SELECT COUNT(*) AS c FROM runs WHERE collection_id = ?")
+    .get(collection.id) as { c: number }).c;
+
+  const workspaceRoot = findWorkspaceRoot().root;
+  const dirAbs = collection.base_dir
+    ? resolve(workspaceRoot, collection.base_dir)
+    : null;
+  const willRemoveDir = !opts.keepFiles && dirAbs !== null && existsSync(dirAbs);
+  const dirRel = dirAbs ? relative(workspaceRoot, dirAbs).replace(/\\/g, "/") : null;
+
+  if (!opts.yes && !opts.json) {
+    const parts = [
+      `Removing API '${collection.name}' (id=${collection.id})`,
+      willRemoveDir ? `  • directory: ${dirRel}` : `  • directory: kept`,
+      opts.purge
+        ? `  • runs: ${runsCount} runs + their results will be DELETED`
+        : `  • runs: ${runsCount} runs will be detached (collection_id=NULL)`,
+    ];
+    process.stderr.write(parts.join("\n") + "\nPass --yes to confirm.\n");
+    return 1;
+  }
+
+  const detachedRuns = opts.purge ? 0 : runsCount;
+  const deletedRuns = opts.purge ? runsCount : 0;
+  deleteCollection(collection.id, opts.purge === true);
+
+  let removedDir: string | null = null;
+  if (willRemoveDir && dirAbs) {
+    rmSync(dirAbs, { recursive: true, force: true });
+    removedDir = relative(workspaceRoot, dirAbs).replace(/\\/g, "/");
+  }
+
+  let clearedCurrent = false;
+  const current = readCurrentApi(workspaceRoot);
+  if (current === collection.name) {
+    clearedCurrent = clearCurrentApi(workspaceRoot);
+  }
+
+  const result: RemoveApiResult = {
+    api: collection.name,
+    collectionId: collection.id,
+    removedDir,
+    detachedRuns,
+    deletedRuns,
+    clearedCurrent,
+  };
+
+  if (opts.json) {
+    printJson(jsonOk("remove-api", result));
+  } else {
+    printSuccess(`Removed API '${collection.name}' (id=${collection.id})`);
+    if (removedDir) process.stdout.write(`  Directory: ${removedDir} (deleted)\n`);
+    else if (opts.keepFiles) process.stdout.write(`  Directory: ${dirRel ?? "<unknown>"} (kept by --keep-files)\n`);
+    if (opts.purge) process.stdout.write(`  Runs: ${deletedRuns} deleted (--purge)\n`);
+    else if (detachedRuns > 0) process.stdout.write(`  Runs: ${detachedRuns} detached (collection_id=NULL)\n`);
+    if (clearedCurrent) process.stdout.write(`  Cleared .zond/current-api marker (was '${collection.name}')\n`);
+  }
+  return 0;
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerRemove(program: Command): void {
+  const remove = program
+    .command("remove")
+    .alias("rm")
+    .description("Unregister objects from the workspace");
+  remove
+    .command("api <name>")
+    .description("Unregister an API: drops collections row, removes apis/<name>/, optionally purges run history")
+    .option("--purge", "Also delete the runs+results that referenced this API (default: detach to NULL)")
+    .option("--keep-files", "Leave apis/<name>/ on disk; only remove the DB record")
+    .option("--yes", "Skip the interactive confirmation prompt")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (name: string, opts, cmd: Command) => {
+      const json = globalJson(cmd);
+      process.exitCode = await removeApiCommand({
+        api: name,
+        purge: opts.purge === true,
+        keepFiles: opts.keepFiles === true,
+        yes: opts.yes === true || json,
+        dbPath: typeof opts.db === "string" ? opts.db : undefined,
+        json,
+      });
+    });
+}

package/src/cli/commands/report-bundle.ts

@@ -0,0 +1,318 @@
+/**
+ * TASK-143: `zond report bundle <range> [--output <dir>] [--include ...]`.
+ *
+ * Batch triage exporter — collects case-study + HTML report + diagnose JSON
+ * for a range of run-ids in one command, plus a top-level index.md with a
+ * table of run-id, totals, and links.
+ *
+ * Range forms:
+ *   A..B               inclusive numeric range, e.g. "135..142"
+ *   A,B,C              comma-separated list
+ *   --session <id>     all runs for a CLI session (DB column `session_id`)
+ */
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import { getDb } from "../../db/schema.ts";
+import { getRunById, getResultsByRunId, getCollectionById } from "../../db/queries.ts";
+import type { RunRecord, StoredStepResult } from "../../db/queries/types.ts";
+import { renderHtmlReport } from "../../core/exporter/html-report/index.ts";
+import { renderCaseStudy } from "../../core/exporter/case-study/index.ts";
+import { diagnoseRun } from "../../core/diagnostics/db-analysis.ts";
+import { applySanitizer } from "../../core/exporter/exporter.ts";
+import { resolveCollectionSpec } from "../../core/setup-api.ts";
+import { readOpenApiSpec } from "../../core/generator/openapi-reader.ts";
+import { printError, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { VERSION } from "../version.ts";
+
+export type BundleArtifact = "case-study" | "export" | "diagnose";
+
+export interface ReportBundleOptions {
+  /** "A..B" range, "A,B,C" list, or unused when sessionId is set. */
+  range?: string;
+  /** Resolve runs by session_id instead of explicit ids. */
+  sessionId?: string;
+  output?: string;
+  include?: BundleArtifact[];
+  bodyCapBytes?: number;
+  dbPath?: string;
+  json?: boolean;
+}
+
+const DEFAULT_BODY_CAP_BYTES = 8192;
+const ALL_ARTIFACTS: BundleArtifact[] = ["case-study", "export", "diagnose"];
+
+interface BundleEntry {
+  runId: number;
+  spec: string | null;
+  totals: { total: number; passed: number; failed: number; skipped: number };
+  caseStudy?: string;
+  htmlReport?: string;
+  diagnose?: string;
+  agentDirective?: string | null;
+}
+
+export function parseBundleRange(input: string): number[] | { error: string } {
+  const trimmed = input.trim();
+  if (!trimmed) return { error: "empty range" };
+
+  const rangeMatch = trimmed.match(/^(\d+)\.\.(\d+)$/);
+  if (rangeMatch) {
+    const a = parseInt(rangeMatch[1]!, 10);
+    const b = parseInt(rangeMatch[2]!, 10);
+    if (a > b) return { error: `range start ${a} is greater than end ${b}` };
+    const out: number[] = [];
+    for (let i = a; i <= b; i++) out.push(i);
+    return out;
+  }
+
+  if (trimmed.includes(",")) {
+    const parts = trimmed.split(",").map(s => s.trim()).filter(Boolean);
+    const ids: number[] = [];
+    for (const p of parts) {
+      const n = parseInt(p, 10);
+      if (!Number.isFinite(n) || n <= 0) return { error: `not a positive integer: ${p}` };
+      ids.push(n);
+    }
+    return Array.from(new Set(ids)).sort((a, b) => a - b);
+  }
+
+  const n = parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n <= 0) return { error: `not a recognised range: ${trimmed}` };
+  return [n];
+}
+
+export async function reportBundleCommand(options: ReportBundleOptions): Promise<number> {
+  try {
+    getDb(options.dbPath);
+  } catch (err) {
+    const msg = `Failed to open database: ${(err as Error).message}`;
+    if (options.json) printJson(jsonError("report bundle", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  let runIds: number[];
+  if (options.sessionId) {
+    runIds = listRunIdsBySession(options.sessionId);
+    if (runIds.length === 0) {
+      const msg = `No runs found for --session ${options.sessionId}`;
+      if (options.json) printJson(jsonError("report bundle", [msg]));
+      else printError(msg);
+      return 1;
+    }
+  } else {
+    if (!options.range) {
+      const msg = "report bundle requires <range> (A..B / A,B,C) or --session <id>";
+      if (options.json) printJson(jsonError("report bundle", [msg]));
+      else printError(msg);
+      return 2;
+    }
+    const parsed = parseBundleRange(options.range);
+    if (!Array.isArray(parsed)) {
+      const msg = `Invalid range: ${parsed.error}. Examples: 135..142, 135,137,141`;
+      if (options.json) printJson(jsonError("report bundle", [msg]));
+      else printError(msg);
+      return 2;
+    }
+    runIds = parsed;
+  }
+
+  const include = options.include && options.include.length > 0 ? options.include : ALL_ARTIFACTS;
+  const outDir = options.output ?? join("triage", "bundle", new Date().toISOString().replace(/[:.]/g, "-"));
+  await mkdir(outDir, { recursive: true });
+
+  const entries: BundleEntry[] = [];
+  const skipped: Array<{ runId: number; reason: string }> = [];
+  const bodyCap = options.bodyCapBytes ?? DEFAULT_BODY_CAP_BYTES;
+
+  for (const runId of runIds) {
+    const run = getRunById(runId);
+    if (!run) {
+      skipped.push({ runId, reason: "not found" });
+      continue;
+    }
+    const results = getResultsByRunId(runId);
+    const runDir = join(outDir, String(runId));
+    await mkdir(runDir, { recursive: true });
+
+    const entry: BundleEntry = {
+      runId,
+      spec: await loadSpecTitle(run),
+      totals: {
+        total: run.total ?? 0,
+        passed: run.passed ?? 0,
+        failed: run.failed ?? 0,
+        skipped: run.skipped ?? 0,
+      },
+    };
+
+    if (include.includes("export")) {
+      const html = renderHtmlReport({
+        run,
+        results,
+        zondVersion: VERSION,
+        generatedAt: new Date(),
+        collectionName: run.collection_id != null ? getCollectionById(run.collection_id)?.name ?? null : null,
+        bodyCapBytes: bodyCap,
+      });
+      const file = join(runDir, "report.html");
+      await Bun.write(file, html);
+      entry.htmlReport = file;
+    }
+
+    if (include.includes("case-study")) {
+      const failure = pickPrimaryFailure(results);
+      if (failure) {
+        const specDoc = await loadSpecDoc(run);
+        const md = applySanitizer(renderCaseStudy({
+          result: failure,
+          run,
+          specTitle: entry.spec,
+          specVersion: null,
+          zondVersion: VERSION,
+          bodyCapBytes: bodyCap,
+          apiName: collectionApiName(run),
+          specDoc: specDoc as Parameters<typeof renderCaseStudy>[0]["specDoc"],
+        }));
+        const file = join(runDir, "case-study.md");
+        await Bun.write(file, md);
+        entry.caseStudy = file;
+      }
+    }
+
+    if (include.includes("diagnose")) {
+      const diag = diagnoseRun(runId, false, options.dbPath, 5);
+      const file = join(runDir, "diagnose.json");
+      await Bun.write(file, JSON.stringify(diag, null, 2));
+      entry.diagnose = file;
+      entry.agentDirective = (diag as unknown as { agent_directive?: string }).agent_directive ?? null;
+    }
+
+    entries.push(entry);
+  }
+
+  if (entries.length === 0) {
+    const msg = `No runs in [${runIds.join(", ")}] resolved to existing rows`;
+    if (options.json) printJson(jsonError("report bundle", [msg]));
+    else printError(msg);
+    return 1;
+  }
+
+  const indexPath = join(outDir, "index.md");
+  await Bun.write(indexPath, renderIndex(entries, skipped));
+
+  if (options.json) {
+    printJson(
+      jsonOk("report bundle", {
+        outputDir: outDir,
+        index: indexPath,
+        entries: entries.map(e => ({
+          runId: e.runId,
+          spec: e.spec,
+          totals: e.totals,
+          caseStudy: e.caseStudy ?? null,
+          htmlReport: e.htmlReport ?? null,
+          diagnose: e.diagnose ?? null,
+          agentDirective: e.agentDirective ?? null,
+        })),
+        skipped,
+      }),
+    );
+  } else {
+    if (skipped.length > 0) {
+      for (const s of skipped) printWarning(`Run #${s.runId} skipped: ${s.reason}`);
+    }
+    // TASK-241: status → stderr; stdout carries only the bundle dir path.
+    process.stderr.write(`zond: bundle written (${entries.length} run(s), index: ${indexPath})\n`,);
+    process.stdout.write(`${outDir}\n`);
+  }
+  return 0;
+}
+
+function listRunIdsBySession(sessionId: string): number[] {
+  const db = getDb();
+  const rows = db.query("SELECT id FROM runs WHERE session_id = ? ORDER BY started_at ASC")
+    .all(sessionId) as Array<{ id: number }>;
+  return rows.map(r => r.id);
+}
+
+async function loadSpecTitle(run: RunRecord): Promise<string | null> {
+  if (run.collection_id == null) return null;
+  const collection = getCollectionById(run.collection_id);
+  if (!collection?.openapi_spec) return collection?.name ?? null;
+  try {
+    const doc = await readOpenApiSpec(resolveCollectionSpec(collection.openapi_spec));
+    return doc.info?.title ?? collection.name ?? null;
+  } catch {
+    return collection.name ?? null;
+  }
+}
+
+/** ARV-107: load the parsed spec document for the run's collection so the
+ *  case-study renderer can auto-extract the operation slice. */
+async function loadSpecDoc(run: RunRecord): Promise<unknown | null> {
+  if (run.collection_id == null) return null;
+  const collection = getCollectionById(run.collection_id);
+  if (!collection?.openapi_spec) return null;
+  try {
+    return await readOpenApiSpec(resolveCollectionSpec(collection.openapi_spec));
+  } catch {
+    return null;
+  }
+}
+
+/** ARV-106/107: short registry slug (`--api <name>` form) for the run's
+ *  collection, used to fill the case-study `apiName` option. */
+function collectionApiName(run: RunRecord): string | null {
+  if (run.collection_id == null) return null;
+  return getCollectionById(run.collection_id)?.name ?? null;
+}
+
+function pickPrimaryFailure(results: StoredStepResult[]): StoredStepResult | null {
+  // Prefer a result classified as a real bug.
+  const bugFirst = results.find(
+    r => r.status !== "pass" && (r.failure_class === "definitely_bug" || r.failure_class === "likely_bug"),
+  );
+  if (bugFirst) return bugFirst;
+  return results.find(r => r.status === "fail" || r.status === "5xx") ?? null;
+}
+
+function renderIndex(entries: BundleEntry[], skipped: Array<{ runId: number; reason: string }>): string {
+  const lines: string[] = [];
+  lines.push("# Bundle index", "");
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push(`Runs: ${entries.length}` + (skipped.length > 0 ? ` (skipped: ${skipped.length})` : ""));
+  lines.push("");
+  lines.push("| Run | Spec | Total | Pass | Fail | Skip | Artefacts | Directive |");
+  lines.push("|----:|------|------:|-----:|-----:|-----:|-----------|-----------|");
+
+  for (const e of entries) {
+    const links: string[] = [];
+    if (e.caseStudy) links.push(`[case-study](${rel(e.caseStudy)})`);
+    if (e.htmlReport) links.push(`[html](${rel(e.htmlReport)})`);
+    if (e.diagnose) links.push(`[diagnose](${rel(e.diagnose)})`);
+    lines.push(
+      `| ${e.runId} | ${e.spec ?? "—"} | ${e.totals.total} | ${e.totals.passed} | ${e.totals.failed} | ${e.totals.skipped} | ${links.join(" · ") || "—"} | ${truncate(e.agentDirective ?? "", 80)} |`,
+    );
+  }
+
+  if (skipped.length > 0) {
+    lines.push("", "## Skipped", "");
+    for (const s of skipped) lines.push(`- run #${s.runId} — ${s.reason}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function rel(p: string): string {
+  // Index lives at <dir>/index.md, run files at <dir>/<id>/<file> — strip the
+  // shared parent so relative links still work after the dir is moved.
+  const seg = p.split(/[/\\]/);
+  const tail = seg.slice(-2);
+  return tail.join("/");
+}
+
+function truncate(s: string, n: number): string {
+  if (s.length <= n) return s.replace(/\n/g, " ");
+  return s.slice(0, n - 1).replace(/\n/g, " ") + "…";
+}