@kirrosh/zond 0.26.1 → 0.27.1

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

@@ -1,227 +0,0 @@
-/**
- * `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, printWarning } from "../output.ts";
-import { readFileSync as readFileSyncNode } from "node:fs";
-import {
-  loadSchemaOverlay,
-  mergePatch,
-  saveSchemaOverlay,
-  applySchemaOverlay,
-  type ResponseSchemaPatch,
-} from "../../core/spec/schema-overlay.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;
-  /** ARV-176: path to a patch.schema.json (from `schema-from-runs`) to fold
-   *  into the response-schema overlay before rebuilding spec.json. */
-  mergeSchema?: string;
-  /** ARV-176: overwrite response schemas already declared upstream. */
-  force?: boolean;
-}
-
-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) ?? "";
-
-  // ARV-176: response-schema overlay. Fold a --merge-schema patch into the
-  // persistent overlay first, then apply the (possibly-updated) overlay onto
-  // the freshly-pulled doc *before* it's serialised to spec.json. Applying on
-  // every refresh (not only when --merge-schema is passed) is what makes the
-  // overlay survive an upstream re-pull (AC#2).
-  let schemaReport: {
-    merged_from?: string;
-    applied: string[];
-    preserved: string[];
-    conflicts: string[];
-  } | undefined;
-  if (opts.mergeSchema) {
-    let incoming: ResponseSchemaPatch;
-    try {
-      incoming = JSON.parse(readFileSyncNode(opts.mergeSchema, "utf-8")) as ResponseSchemaPatch;
-    } catch (err) {
-      const m = `Failed to read --merge-schema "${opts.mergeSchema}": ${(err as Error).message}`;
-      if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
-      return 2;
-    }
-    const merged = mergePatch(loadSchemaOverlay(baseDir), incoming);
-    saveSchemaOverlay(baseDir, merged);
-  }
-  const overlay = loadSchemaOverlay(baseDir);
-  if (overlay) {
-    const r = applySchemaOverlay(doc, overlay, { force: opts.force === true });
-    schemaReport = {
-      ...(opts.mergeSchema ? { merged_from: opts.mergeSchema } : {}),
-      applied: r.applied,
-      preserved: r.preserved,
-      conflicts: r.conflicts,
-    };
-  }
-
-  // 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"],
-    ...(schemaReport ? { schema_overlay: schemaReport } : {}),
-  };
-
-  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`);
-    if (schemaReport) {
-      process.stdout.write(`  schema overlay: ${schemaReport.applied.length} applied, ${schemaReport.preserved.length} preserved, ${schemaReport.conflicts.length} conflict(s)\n`);
-      for (const c of schemaReport.conflicts) {
-        printWarning(`schema overlay conflict (endpoint not in upstream, skipped): ${c}`);
-      }
-    }
-    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("--merge-schema <path>", "ARV-176: fold a patch.schema.json (from `zond schema-from-runs`) into the persistent response-schema overlay (.api-schema.local.yaml) and apply it to spec.json. The overlay survives future refreshes.")
-    .option("--force", "ARV-176: overwrite response schemas already declared upstream (default: only fill gaps).")
-    .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,
-        mergeSchema: typeof opts.mergeSchema === "string" ? opts.mergeSchema : undefined,
-        force: opts.force === true,
-        dbPath: typeof opts.db === "string" ? opts.db : undefined,
-        json: globalJson(cmd),
-      });
-    });
-}

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

@@ -1,150 +0,0 @@
-/**
- * `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

@@ -1,310 +0,0 @@
-/**
- * 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;
-}
-
-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;
-    }
-
-    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,
-        })),
-        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 |");
-  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(" · ") || "—"} |`,
-    );
-  }
-
-  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("/");
-}