@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/db.ts

@@ -1,8 +1,13 @@
+import { stringify as stringifyYaml } from "yaml";
 import { getCollections, getRuns, getRunDetail, diagnoseRun, compareRuns } from "../../core/diagnostics/db-analysis.ts";
-import { getFilteredResults } from "../../db/queries.ts";
+import { getFilteredResults, getLatestFailingRunId, getLatestRunId, runKindStats, deleteRunsOlderThan, listRunsBySession, listRunsByCollectionFiltered, findCollectionByNameOrId } from "../../db/queries.ts";
 import { getDb } from "../../db/schema.ts";
 import { printError } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { parseStatusFilter, compileStatusFilterToSql, type StatusMatcher } from "../status-filter.ts";
+import { parseUnion, type UnionSpec } from "./coverage.ts";
+import { readCurrentSession } from "../../core/context/session.ts";
+import { readCurrentApi } from "../../core/context/current.ts";
 
 export interface DbOptions {
   subcommand: string;
@@ -12,12 +17,143 @@ export interface DbOptions {
   dbPath?: string;
   json?: boolean;
   method?: string;
-  status?: number;
+  /** Raw `--status` argument (TASK-140). Parsed lazily so help text can show
+   *  the literal user input in error messages. */
+  status?: string;
+  /** TASK-266: `db diagnose --latest` — pick the most recent run regardless
+   *  of failure status (default is most recent failing run). */
+  latest?: boolean;
+  /** TASK-266: explicit run id override (`--run-id N`). Same effect as
+   *  passing the id positionally; kept as a flag because the `zond-triage`
+   *  skill and other agents prefer self-documenting flags. */
+  runId?: number;
+  /** ARV-266: `db prune --older-than <spec>` — cutoff for retention.
+   *  Accepts `30d`, `12h`, or a bare integer (days). Omitted ⇒ per-kind
+   *  documented defaults are applied. */
+  olderThan?: string;
+  /** ARV-266: restrict prune to one run_kind. */
+  kind?: string;
+  /** ARV-266: show what would be deleted without deleting. */
+  dryRun?: boolean;
+  /** ARV-338: `--report yaml` — emit the same payload as YAML instead of
+   *  JSON, so agents can drop it next to suite YAMLs and diff runs as text. */
+  report?: string;
+  /** ARV-380: `db diagnose --union <spec>` — aggregate `by_recommended_action`
+   *  across a run set using coverage's `--union` vocabulary
+   *  (session | since:<dur> | tag:<name> | runs:<id1,id2,…>). */
+  union?: string;
+  /** ARV-380: API name for scoping since:/tag: unions to a collection. */
+  api?: string;
+}
+
+/** ARV-338: shared stdout emitter for run/diagnose/compare payloads. */
+function emitPayload(payload: unknown, format?: string): void {
+  console.log(format === "yaml" ? stringifyYaml(payload).trimEnd() : JSON.stringify(payload, null, 2));
+}
+
+/** ARV-266: per-run_kind default retention. Noise kinds (check/probe/
+ *  request/fixture runs) are cheap to regenerate and dominate DB growth —
+ *  drop after a week. `regular` runs are the signal a user compares against
+ *  over time — kept forever unless an explicit --older-than says otherwise. */
+const RETENTION_DEFAULT_DAYS: Record<string, number | null> = {
+  regular: null,
+  check: 7,
+  probe: 7,
+  request: 7,
+  fixture: 7,
+};
+
+/** ARV-266: parse `30d` / `12h` / `30` into whole days. Returns null on a
+ *  malformed spec so the caller can surface a clear error. */
+export function parseRetentionDays(spec: string): number | null {
+  const m = spec.trim().match(/^(\d+)\s*([dh]?)$/i);
+  if (!m) return null;
+  const n = Number.parseInt(m[1]!, 10);
+  if (!Number.isFinite(n)) return null;
+  if (m[2]?.toLowerCase() === "h") return n / 24;
+  return n; // bare number or `d` ⇒ days
+}
+
+/** ARV-266: cutoff ISO timestamp `days` before now. */
+function cutoffIso(days: number, now: Date): string {
+  return new Date(now.getTime() - days * 86_400_000).toISOString();
+}
+
+/** ARV-380: resolve a coverage-style `--union` spec to the concrete run-ids
+ *  it selects. session/since/tag need context (active session / collection);
+ *  `runs:` is self-contained. */
+function resolveUnionRunIds(spec: UnionSpec, apiName?: string): { ids: number[] } | { error: string } {
+  switch (spec.kind) {
+    case "runIds":
+      return { ids: spec.ids };
+    case "session": {
+      const cur = readCurrentSession();
+      if (!cur) return { error: "--union session: no active session (start one with `zond session start`, or use --union runs:<ids>)." };
+      return { ids: listRunsBySession(cur.id).map((r) => (r as { id: number }).id) };
+    }
+    case "since":
+    case "tag": {
+      // Mirror the standard --api chain: explicit flag > ZOND_API(_GLOBAL) > `zond use`.
+      const resolvedApi = apiName ?? readCurrentApi();
+      if (!resolvedApi) return { error: `--union ${spec.kind}:<...> needs --api <name> (or ZOND_API / \`zond use\`) to scope runs to a collection.` };
+      const col = findCollectionByNameOrId(resolvedApi);
+      if (!col) return { error: `API '${apiName}' not found. Register it with \`zond add api\` or check the name.` };
+      const filter = spec.kind === "since"
+        ? { since: new Date(Date.now() - spec.durationMs).toISOString() }
+        : { tag: spec.name };
+      return { ids: listRunsByCollectionFiltered((col as { id: number }).id, filter).map((r) => r.id) };
+    }
+  }
+}
+
+/** ARV-380: fold `by_recommended_action` (+ summary counts) across a run set.
+ *  Examples are deduped by method+path+status and capped at 5 per action,
+ *  mirroring the single-run cap in `diagnoseRun`. */
+function aggregateDiagnose(ids: number[], options: DbOptions) {
+  type Example = NonNullable<ReturnType<typeof diagnoseRun>["by_recommended_action"]>[string]["examples"][number];
+  const byAction: Record<string, { count: number; examples: Example[]; seen: Set<string> }> = {};
+  const summary = { total: 0, passed: 0, failed: 0, api_errors: 0, assertion_failures: 0, network_errors: 0 };
+  for (const id of ids) {
+    const r = diagnoseRun(id, options.verbose, options.dbPath, options.limit);
+    summary.total += r.summary.total;
+    summary.passed += r.summary.passed;
+    summary.failed += r.summary.failed;
+    summary.api_errors += r.summary.api_errors;
+    summary.assertion_failures += r.summary.assertion_failures;
+    summary.network_errors += r.summary.network_errors;
+    for (const [action, bucket] of Object.entries(r.by_recommended_action ?? {})) {
+      const agg = byAction[action] ??= { count: 0, examples: [], seen: new Set<string>() };
+      agg.count += bucket.count;
+      for (const ex of bucket.examples) {
+        const key = `${ex.method} ${ex.path} ${ex.status}`;
+        if (agg.seen.has(key) || agg.examples.length >= 5) continue;
+        agg.seen.add(key);
+        agg.examples.push(ex);
+      }
+    }
+  }
+  const by_recommended_action: Record<string, { count: number; examples: Example[] }> = {};
+  for (const [action, agg] of Object.entries(byAction)) {
+    by_recommended_action[action] = { count: agg.count, examples: agg.examples };
+  }
+  return { runs_diagnosed: ids.length, run_ids: ids, summary, by_recommended_action };
 }
 
 export async function dbCommand(options: DbOptions): Promise<number> {
   const { subcommand, positional, json } = options;
 
+  if (options.report !== undefined && options.report !== "yaml" && options.report !== "json") {
+    const msg = `Invalid --report format: ${options.report}. Supported: json, yaml`;
+    if (json) printJson(jsonError(`db ${subcommand}`, [msg]));
+    else printError(msg);
+    return 2;
+  }
+  if (options.report === "yaml" && json) {
+    const msg = "--report yaml and --json are mutually exclusive — pick one output format";
+    printJson(jsonError(`db ${subcommand}`, [msg]));
+    return 2;
+  }
+
   try {
     switch (subcommand) {
       case "collections": {
@@ -66,36 +202,140 @@ export async function dbCommand(options: DbOptions): Promise<number> {
         // If filtering by method/status, show filtered results instead of full detail
         if (options.method || options.status !== undefined) {
           getDb(options.dbPath);
-          const results = getFilteredResults(id, { method: options.method, status: options.status });
+          let statusSql: { sql: string; params: number[] } | undefined;
+          if (options.status !== undefined) {
+            let matcher: StatusMatcher;
+            try {
+              matcher = parseStatusFilter(options.status);
+            } catch (err) {
+              const msg = `Invalid --status: ${(err as Error).message}`;
+              if (json) printJson(jsonError("db run", [msg]));
+              else printError(msg);
+              return 2;
+            }
+            const compiled = compileStatusFilterToSql(matcher, "response_status");
+            if (compiled) statusSql = compiled;
+          }
+          const results = getFilteredResults(id, { method: options.method, statusSql });
           if (json) {
             printJson(jsonOk("db run", { run_id: id, count: results.length, results }));
           } else {
-            console.log(JSON.stringify({ run_id: id, count: results.length, results }, null, 2));
+            emitPayload({ run_id: id, count: results.length, results }, options.report);
           }
         } else {
           const detail = getRunDetail(id, options.verbose, options.dbPath);
           if (json) {
             printJson(jsonOk("db run", detail));
           } else {
-            console.log(JSON.stringify(detail, null, 2));
+            emitPayload(detail, options.report);
           }
         }
         return 0;
       }
 
       case "diagnose": {
-        const id = parseInt(positional[0] ?? "", 10);
-        if (isNaN(id)) {
-          const msg = "Missing run ID. Usage: zond db diagnose <id>";
+        getDb(options.dbPath);
+
+        // ARV-380: `--union <spec>` aggregates by_recommended_action across a
+        // run set (same vocabulary as `zond coverage --union`) instead of the
+        // single-run default, so an agent stops looping `db diagnose $id` per
+        // run and merging client-side.
+        if (options.union !== undefined) {
+          let spec: UnionSpec;
+          try {
+            spec = parseUnion(options.union);
+          } catch (err) {
+            const msg = (err as Error).message;
+            if (json) printJson(jsonError("db diagnose", [msg])); else printError(msg);
+            return 2;
+          }
+          const resolved = resolveUnionRunIds(spec, options.api);
+          if ("error" in resolved) {
+            if (json) printJson(jsonError("db diagnose", [resolved.error])); else printError(resolved.error);
+            return 2;
+          }
+          if (resolved.ids.length === 0) {
+            const msg = `No runs match --union ${options.union}.`;
+            if (json) printJson(jsonError("db diagnose", [msg])); else printError(msg);
+            return 1;
+          }
+          const agg = aggregateDiagnose(resolved.ids, options);
+          const payload = { ...agg, union: options.union };
+          if (json) printJson(jsonOk("db diagnose", payload));
+          else emitPayload(payload, options.report);
+          return 0;
+        }
+
+        // TASK-266: resolve run id with the priority
+        //   explicit positional > --run-id > --latest > last failing run.
+        // The bare `zond db diagnose` is the agent-friendly default the
+        // `zond-triage` skill relies on; `--latest` exists for "show me the
+        // last run, even if it passed".
+        let id: number | null = null;
+        let resolution: "explicit" | "run-id-flag" | "latest" | "latest-failing" = "explicit";
+        const positionalRaw = positional[0];
+        if (positionalRaw !== undefined && positionalRaw !== "") {
+          const n = parseInt(positionalRaw, 10);
+          if (isNaN(n)) {
+            const msg = `Invalid run id: ${positionalRaw}. Expected a positive integer.`;
+            if (json) printJson(jsonError("db diagnose", [msg]));
+            else printError(msg);
+            return 2;
+          }
+          id = n;
+        } else if (options.runId !== undefined) {
+          id = options.runId;
+          resolution = "run-id-flag";
+        } else if (options.latest) {
+          id = getLatestRunId();
+          resolution = "latest";
+        } else {
+          id = getLatestFailingRunId();
+          resolution = "latest-failing";
+          if (id == null) {
+            // No failures — fall back to the latest run so the user still
+            // gets a useful payload, with a "no failures" hint.
+            const fallback = getLatestRunId();
+            if (fallback == null) {
+              const msg = "No runs in the database yet. Try `zond run <suite>` first.";
+              if (json) printJson(jsonError("db diagnose", [msg]));
+              else printError(msg);
+              return 1;
+            }
+            const result = diagnoseRun(fallback, options.verbose, options.dbPath, options.limit);
+            const warning = `No failing runs — diagnosing latest run #${fallback} (all passed).`;
+            if (json) {
+              printJson(jsonOk("db diagnose", { ...result, resolution: "latest-no-failures", run_id: fallback }, [warning]));
+            } else {
+              process.stderr.write(`zond: ${warning}\n`);
+              emitPayload({ ...result, resolution: "latest-no-failures", run_id: fallback }, options.report);
+            }
+            return 0;
+          }
+        }
+        if (id == null) {
+          const msg = "Missing run ID. Usage: zond db diagnose [id] (default: last failing run)";
           if (json) printJson(jsonError("db diagnose", [msg]));
           else printError(msg);
           return 2;
         }
         const result = diagnoseRun(id, options.verbose, options.dbPath, options.limit);
         if (json) {
-          printJson(jsonOk("db diagnose", result));
+          printJson(jsonOk("db diagnose", { ...result, resolution, run_id: id }));
         } else {
-          console.log(JSON.stringify(result, null, 2));
+          // ARV-208: in human mode, embed resolution + run_id in the stdout
+          // JSON so users (and the zond-triage skill) don't need --json just
+          // to discover which run was auto-selected by `zond db diagnose --api`.
+          // The stderr hint stays as a quick visual cue when running interactively.
+          if (resolution !== "explicit") {
+            const label = resolution === "latest-failing"
+              ? `last failing run #${id}`
+              : resolution === "latest"
+                ? `latest run #${id}`
+                : `run #${id}`;
+            process.stderr.write(`zond: diagnosing ${label}\n`);
+          }
+          emitPayload({ ...result, resolution, run_id: id }, options.report);
         }
         return 0;
       }
@@ -109,17 +349,117 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           else printError(msg);
           return 2;
         }
+        // ARV-360: a run compared against itself is always a degenerate green
+        // (0 regressions / 0 body_changes) and signals nothing. This bit an
+        // audit pipeline that resolved "latest run id" to the same stale run
+        // for both A and B — the meaningless diff read as "contract stable".
+        // Fail loud instead of emitting a fake-passing comparison.
+        if (idA === idB) {
+          const msg = `Cannot compare run #${idA} against itself — pass two distinct run ids (a self-compare always reports 0 changes and hides that the ids were resolved wrong).`;
+          if (json) printJson(jsonError("db compare", [msg]));
+          else printError(msg);
+          return 2;
+        }
         const result = compareRuns(idA, idB, options.dbPath);
         if (json) {
           printJson(jsonOk("db compare", result));
         } else {
-          console.log(JSON.stringify(result, null, 2));
+          emitPayload(result, options.report);
+        }
+        return 0;
+      }
+
+      case "stats": {
+        // ARV-266: per-kind row counts so users see DB growth before it bites.
+        getDb(options.dbPath);
+        const stats = runKindStats();
+        const totalRuns = stats.reduce((a, s) => a + s.runs, 0);
+        const totalResults = stats.reduce((a, s) => a + s.results, 0);
+        if (json) {
+          printJson(jsonOk("db stats", { by_kind: stats, totals: { runs: totalRuns, results: totalResults } }));
+        } else if (stats.length === 0) {
+          console.log("No runs in the database yet.");
+        } else {
+          console.log(`Row counts by run_kind (${totalRuns} runs, ${totalResults} result rows):`);
+          for (const s of stats) {
+            const retention = RETENTION_DEFAULT_DAYS[s.run_kind];
+            const ret = retention == null ? "kept forever" : `default prune ${retention}d`;
+            console.log(`  ${s.run_kind.padEnd(9)} ${String(s.runs).padStart(6)} runs  ${String(s.results).padStart(8)} results  (${ret})`);
+          }
+          console.log("\nPrune noise kinds with `zond db prune` (per-kind defaults) or `zond db prune --older-than 30d`.");
+        }
+        return 0;
+      }
+
+      case "prune": {
+        // ARV-266: explicit, opt-in retention — never runs unless the user
+        // asks. Default (no --older-than) applies the documented per-kind
+        // cutoffs; `regular` runs are never dropped by the defaults.
+        getDb(options.dbPath);
+        const now = new Date();
+        // Build the (kind, cutoffIso) work-list.
+        let jobs: Array<{ kind?: string; cutoff: string; label: string }> = [];
+        if (options.olderThan) {
+          const days = parseRetentionDays(options.olderThan);
+          if (days == null) {
+            const msg = `Invalid --older-than "${options.olderThan}" (expected e.g. 30d, 12h, or a day count).`;
+            if (json) printJson(jsonError("db prune", [msg])); else printError(msg);
+            return 2;
+          }
+          jobs = [{ kind: options.kind, cutoff: cutoffIso(days, now), label: `${options.kind ?? "all"} < ${options.olderThan}` }];
+        } else {
+          // Per-kind defaults. A --kind filter narrows to that one kind.
+          for (const [kind, retDays] of Object.entries(RETENTION_DEFAULT_DAYS)) {
+            if (retDays == null) continue; // regular ⇒ forever
+            if (options.kind && options.kind !== kind) continue;
+            jobs.push({ kind, cutoff: cutoffIso(retDays, now), label: `${kind} < ${retDays}d` });
+          }
+          if (options.kind && RETENTION_DEFAULT_DAYS[options.kind] == null) {
+            const msg = `run_kind "${options.kind}" is retained forever by default. Pass --older-than to prune it explicitly.`;
+            if (json) printJson(jsonOk("db prune", { deleted: [], dry_run: options.dryRun === true, note: msg }, [msg]));
+            else console.log(msg);
+            return 0;
+          }
+        }
+
+        const deleted: Array<{ scope: string; runs: number; results: number }> = [];
+        for (const jobItem of jobs) {
+          if (options.dryRun) {
+            // Count-only: reuse the delete query's SELECT by inspecting stats
+            // is imprecise, so do a lightweight targeted count.
+            const { getDb: gd } = await import("../../db/schema.ts");
+            const dbh = gd();
+            const kindClause = jobItem.kind ? "AND run_kind = ?" : "";
+            const params = jobItem.kind ? [jobItem.cutoff, jobItem.kind] : [jobItem.cutoff];
+            const row = dbh.query(`SELECT COUNT(*) AS runs FROM runs WHERE started_at < ? ${kindClause}`).get(...params) as { runs: number };
+            deleted.push({ scope: jobItem.label, runs: row.runs, results: 0 });
+          } else {
+            const r = deleteRunsOlderThan(jobItem.cutoff, jobItem.kind);
+            deleted.push({ scope: jobItem.label, runs: r.runs, results: r.results });
+          }
+        }
+        const totalRuns = deleted.reduce((a, d) => a + d.runs, 0);
+        if (!options.dryRun && totalRuns > 0) {
+          // Reclaim freed pages after a large delete.
+          const { getDb: gd } = await import("../../db/schema.ts");
+          gd().exec("VACUUM");
+        }
+        if (json) {
+          printJson(jsonOk("db prune", { deleted, total_runs: totalRuns, dry_run: options.dryRun === true }));
+        } else if (totalRuns === 0) {
+          console.log(options.dryRun ? "Nothing would be pruned." : "Nothing to prune.");
+        } else {
+          console.log(`${options.dryRun ? "Would prune" : "Pruned"} ${totalRuns} run(s):`);
+          for (const d of deleted) {
+            if (d.runs > 0) console.log(`  ${d.scope.padEnd(20)} ${d.runs} run(s)${options.dryRun ? "" : `, ${d.results} result row(s)`}`);
+          }
+          if (!options.dryRun) console.log("VACUUM reclaimed freed pages.");
         }
         return 0;
       }
 
       default: {
-        const msg = `Unknown db subcommand: ${subcommand}. Available: collections, runs, run, diagnose, compare`;
+        const msg = `Unknown db subcommand: ${subcommand}. Available: collections, runs, run, diagnose, compare, stats, prune`;
         if (json) printJson(jsonError("db", [msg]));
         else printError(msg);
         return 2;
@@ -135,3 +475,137 @@ export async function dbCommand(options: DbOptions): Promise<number> {
     return 2;
   }
 }
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+import { parsePositiveInt } from "../argv.ts";
+
+export function registerDb(program: Command): void {
+  const db = program.command("db").description("Query the test database");
+
+  db
+    .command("collections")
+    .description("List all API collections")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "collections",
+        positional: [],
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("runs")
+    .description("List recent test runs")
+    .option("--limit <N>", "Maximum number of runs to display", parsePositiveInt("--limit"))
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "runs",
+        positional: [],
+        limit: opts.limit,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("run <id>")
+    .description("Show run details")
+    .option("--verbose", "Show all results")
+    .option("--method <method>", "Filter by HTTP method")
+    .option(
+      "--status <expr>",
+      "Filter by HTTP status. Accepts: exact code (502), class (5xx), range (500-599), comparison (>=500, <400), or comma-separated mix (5xx,429).",
+    )
+    .option("--report <format>", "Output format: json (default) or yaml (ARV-338: agent-friendly run snapshot)")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (id: string, opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "run",
+        positional: [id],
+        verbose: opts.verbose === true,
+        method: opts.method,
+        status: opts.status,
+        report: opts.report,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("diagnose [id]")
+    .description("Diagnose run failures. Without [id]: defaults to the most recent failing run (TASK-266); falls back to latest run with a 'no failures' note when nothing has failed.")
+    .option("--latest", "Diagnose the most recent run regardless of status (TASK-266)")
+    .option("--run-id <N>", "Explicit run id override (same as positional [id]; preferred form for agents)", parsePositiveInt("--run-id"))
+    .option("--union <spec>", "ARV-380: aggregate by_recommended_action across a run set instead of one run. Vocabulary matches `zond coverage --union`: session | since:<dur> | tag:<name> | runs:<id1,id2,…>. since:/tag: need --api to scope the collection.")
+    .option("--api <name>", "API/collection to scope --union since:/tag: against. Falls back to ZOND_API / .zond/current-api.")
+    .option("--limit <N>", "Examples per failure group", parsePositiveInt("--limit"))
+    .option("--verbose", "Show all examples (not grouped)")
+    .option("--report <format>", "Output format: json (default) or yaml (ARV-338: agent-friendly summary)")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (id: string | undefined, opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "diagnose",
+        positional: id !== undefined ? [id] : [],
+        limit: opts.limit,
+        verbose: opts.verbose === true,
+        latest: opts.latest === true,
+        runId: opts.runId,
+        union: opts.union,
+        api: opts.api,
+        report: opts.report,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("compare <idA> <idB>")
+    .description("Compare two runs")
+    .option("--report <format>", "Output format: json (default) or yaml (ARV-338: agent-friendly diff)")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (idA: string, idB: string, opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "compare",
+        positional: [idA, idB],
+        report: opts.report,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("stats")
+    .description("ARV-266: row counts per run_kind + default retention, so DB growth is visible before it bites")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "stats",
+        positional: [],
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("prune")
+    .description("ARV-266: delete old runs to bound DB growth. Default (no --older-than) applies per-kind retention: check/probe/request/fixture runs older than 7d are dropped; 'regular' runs are kept forever. VACUUMs after a delete. Opt-in — never runs unless invoked.")
+    .option("--older-than <spec>", "Uniform cutoff for all kinds (e.g. 30d, 12h, or a day count). Overrides per-kind defaults; prunes 'regular' too.")
+    .option("--kind <run_kind>", "Restrict to one run_kind: regular | check | probe | request | fixture")
+    .option("--dry-run", "Report what would be deleted without deleting")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await dbCommand({
+        subcommand: "prune",
+        positional: [],
+        olderThan: opts.olderThan,
+        kind: opts.kind,
+        dryRun: opts.dryRun === true,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+}

package/src/cli/commands/describe.ts

@@ -37,7 +37,13 @@ export async function describeCommand(options: DescribeOptions): Promise<number>
       return 0;
     }
 
-    if (options.compact) {
+    // No flags = compact listing. Erroring out (exit 2) on `zond describe`
+    // breaks scripts that pipe the listing; the listing IS the only useful
+    // default since the spec is the only required arg. Single-endpoint detail
+    // remains opt-in via --method/--path.
+    const useCompact = options.compact || (!options.method && !options.path);
+
+    if (useCompact) {
       const endpoints = await describeCompact(options.specPath);
 
       if (options.json) {
@@ -55,8 +61,10 @@ export async function describeCommand(options: DescribeOptions): Promise<number>
       return 0;
     }
 
+    // We get here only when one of --method/--path is set but not both —
+    // single-endpoint detail needs both halves of the address.
     if (!options.method || !options.path) {
-      const msg = "Missing --method and --path. Use --compact for all endpoints, or specify --method and --path for one.";
+      const msg = "--method and --path must be used together for single-endpoint detail. Drop both for the compact listing.";
       if (options.json) {
         printJson(jsonError("describe", [msg]));
       } else {
@@ -83,3 +91,30 @@ export async function describeCommand(options: DescribeOptions): Promise<number>
     return 2;
   }
 }
+
+import type { Command } from "commander";
+import { globalJson, resolveSpecArg } from "../resolve.ts";
+
+export function registerDescribe(program: Command): void {
+  program
+    .command("describe [spec]")
+    .description("Describe endpoints from OpenAPI spec")
+    .option("--api <name>", "Use the registered API's spec (apis/<name>/spec.json)")
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--compact", "List all endpoints briefly")
+    .option("--list-params", "List all unique parameters across all endpoints")
+    .option("--method <method>", "HTTP method for single endpoint detail")
+    .option("--path <path>", "Endpoint path for single endpoint detail")
+    .action(async (specPos: string | undefined, opts, cmd: Command) => {
+      const resolved = resolveSpecArg(specPos, opts.api, opts.db);
+      if ("error" in resolved) { printError(resolved.error); process.exitCode = 2; return; }
+      process.exitCode = await describeCommand({
+        specPath: resolved.spec,
+        compact: opts.compact === true,
+        listParams: opts.listParams === true,
+        method: opts.method,
+        path: opts.path,
+        json: globalJson(cmd),
+      });
+    });
+}