@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/db.ts

@@ -1,8 +1,9 @@
 import { getCollections, getRuns, getRunDetail, diagnoseRun, compareRuns } from "../../core/diagnostics/db-analysis.ts";
-import { getFilteredResults } from "../../db/queries.ts";
+import { getFilteredResults, getLatestFailingRunId, getLatestRunId } 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";
 
 export interface DbOptions {
   subcommand: string;
@@ -12,7 +13,16 @@ 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;
 }
 
 export async function dbCommand(options: DbOptions): Promise<number> {
@@ -46,7 +56,8 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           } else {
             for (const r of runs) {
               const run = r as any;
-              const status = run.failed > 0 ? "FAIL" : "PASS";
+              const isFail = run.failed > 0 || (run.total > 0 && run.passed === 0);
+              const status = isFail ? "FAIL" : "PASS";
               console.log(`#${run.id} ${status} ${run.passed}/${run.total} passed (${run.started_at})`);
             }
           }
@@ -65,7 +76,21 @@ 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 {
@@ -83,17 +108,72 @@ export async function dbCommand(options: DbOptions): Promise<number> {
       }
 
       case "diagnose": {
-        const id = parseInt(positional[0] ?? "", 10);
-        if (isNaN(id)) {
-          const msg = "Missing run ID. Usage: zond db diagnose <id>";
+        // 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".
+        getDb(options.dbPath);
+        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`);
+              console.log(JSON.stringify(result, null, 2));
+            }
+            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 {
+          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`);
+          }
           console.log(JSON.stringify(result, null, 2));
         }
         return 0;
@@ -134,3 +214,95 @@ 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("--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,
+        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("--limit <N>", "Examples per failure group", parsePositiveInt("--limit"))
+    .option("--verbose", "Show all examples (not grouped)")
+    .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,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+
+  db
+    .command("compare <idA> <idB>")
+    .description("Compare two runs")
+    .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],
+        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),
+      });
+    });
+}