@kirrosh/zond 0.20.0 → 0.22.0

package/src/cli/commands/probe-methods.ts

@@ -0,0 +1,108 @@
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  serializeSuite,
+} from "../../core/generator/index.ts";
+import { filterByTag } from "../../core/generator/chunker.ts";
+import { generateMethodProbes } from "../../core/probe/method-probe.ts";
+import { printError, printSuccess } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface ProbeMethodsOptions {
+  specPath: string;
+  output: string;
+  tag?: string;
+  json?: boolean;
+}
+
+export async function probeMethodsCommand(
+  options: ProbeMethodsOptions,
+): Promise<number> {
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    let endpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+
+    if (options.tag) endpoints = filterByTag(endpoints, options.tag);
+
+    if (endpoints.length === 0) {
+      const message = "No endpoints to probe.";
+      if (options.json) {
+        printJson(jsonOk("probe-methods", { files: [], message }));
+      } else {
+        console.log(message);
+      }
+      return 0;
+    }
+
+    const result = generateMethodProbes({
+      endpoints,
+      securitySchemes,
+    });
+
+    if (result.suites.length === 0) {
+      const message =
+        "Every path declares all of GET/POST/PUT/PATCH/DELETE — nothing to probe.";
+      if (options.json) {
+        printJson(
+          jsonOk("probe-methods", {
+            files: [],
+            probedPaths: 0,
+            skippedPaths: result.skippedPaths,
+            totalProbes: 0,
+            message,
+          }),
+        );
+      } else {
+        console.log(message);
+      }
+      return 0;
+    }
+
+    await mkdir(options.output, { recursive: true });
+
+    const created: Array<{ file: string; suite: string; tests: number }> = [];
+    for (const suite of result.suites) {
+      const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+      const filePath = join(options.output, fileName);
+      await Bun.write(filePath, serializeSuite(suite));
+      created.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+    }
+
+    if (options.json) {
+      printJson(
+        jsonOk("probe-methods", {
+          files: created,
+          probedPaths: result.probedPaths,
+          skippedPaths: result.skippedPaths,
+          totalProbes: result.totalProbes,
+          outputDir: options.output,
+        }),
+      );
+    } else {
+      printSuccess(
+        `Generated ${result.suites.length} method-probe suite(s) with ${result.totalProbes} probe(s) in ${options.output}`,
+      );
+      console.log(
+        `  ${result.probedPaths} path(s) probed, ${result.skippedPaths} skipped (full method coverage)`,
+      );
+      console.log("");
+      console.log("Next steps:");
+      console.log(`  zond run ${options.output} --report json   # any 5xx or 2xx → bug candidate`);
+      console.log(`  zond db diagnose <run-id>                  # inspect failures`);
+    }
+
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("probe-methods", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/probe-validation.ts

@@ -0,0 +1,124 @@
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  serializeSuite,
+} from "../../core/generator/index.ts";
+import { filterByTag, collectTags } from "../../core/generator/chunker.ts";
+import { generateNegativeProbes } from "../../core/probe/negative-probe.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface ProbeValidationOptions {
+  specPath: string;
+  output: string;
+  tag?: string;
+  maxPerEndpoint?: number;
+  noCleanup?: boolean;
+  json?: boolean;
+  listTags?: boolean;
+}
+
+export async function probeValidationCommand(
+  options: ProbeValidationOptions,
+): Promise<number> {
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    const allEndpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+
+    if (options.listTags) {
+      const tags = collectTags(allEndpoints);
+      if (options.json) {
+        printJson(jsonOk("probe-validation", { tags }));
+      } else {
+        if (tags.length === 0) {
+          console.log("No tags found in spec.");
+        } else {
+          console.log("Available tags:");
+          for (const t of tags) console.log(`  - ${t}`);
+        }
+      }
+      return 0;
+    }
+
+    let endpoints = allEndpoints;
+    if (options.tag) {
+      endpoints = filterByTag(allEndpoints, options.tag);
+      if (endpoints.length === 0) {
+        const available = collectTags(allEndpoints);
+        const msg = `No endpoints tagged "${options.tag}". Available tags: ${available.length ? available.join(", ") : "(none)"}`;
+        if (options.json) {
+          printJson(jsonError("probe-validation", [msg]));
+        } else {
+          printWarning(msg);
+        }
+        return 2;
+      }
+    }
+
+    if (endpoints.length === 0) {
+      const message = "No endpoints to probe.";
+      if (options.json) {
+        printJson(jsonOk("probe-validation", { files: [], message }));
+      } else {
+        console.log(message);
+      }
+      return 0;
+    }
+
+    const result = generateNegativeProbes({
+      endpoints,
+      securitySchemes,
+      maxProbesPerEndpoint: options.maxPerEndpoint,
+      noCleanup: options.noCleanup,
+    });
+
+    await mkdir(options.output, { recursive: true });
+
+    const created: Array<{ file: string; suite: string; tests: number }> = [];
+    for (const suite of result.suites) {
+      const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+      const filePath = join(options.output, fileName);
+      await Bun.write(filePath, serializeSuite(suite));
+      created.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+    }
+
+    if (options.json) {
+      printJson(
+        jsonOk("probe-validation", {
+          files: created,
+          probedEndpoints: result.probedEndpoints,
+          skippedEndpoints: result.skippedEndpoints,
+          totalProbes: result.totalProbes,
+          outputDir: options.output,
+          warnings: result.warnings,
+        }),
+      );
+    } else {
+      printSuccess(
+        `Generated ${result.suites.length} probe suite(s) with ${result.totalProbes} probe(s) in ${options.output}`,
+      );
+      console.log(
+        `  ${result.probedEndpoints} endpoint(s) probed, ${result.skippedEndpoints} skipped (no probable surface)`,
+      );
+      for (const w of result.warnings) printWarning(w);
+      console.log("");
+      console.log("Next steps:");
+      console.log(`  zond run ${options.output} --report json   # any 5xx → bug candidate`);
+      console.log(`  zond db diagnose <run-id>                  # inspect failures`);
+    }
+
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("probe-validation", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/run.ts

@@ -1,11 +1,14 @@
 import { dirname } from "path";
 import { stat } from "node:fs/promises";
 import { parse } from "../../core/parser/yaml-parser.ts";
-import { loadEnvironment } from "../../core/parser/variables.ts";
+import { loadEnvironment, loadEnvMeta, loadEnvFile } from "../../core/parser/variables.ts";
 import { filterSuitesByTags, excludeSuitesByTags, filterSuitesByMethod } from "../../core/parser/filter.ts";
 import { runSuite } from "../../core/runner/executor.ts";
-import { getReporter } from "../../core/reporter/index.ts";
+import { createRateLimiter, createAdaptiveRateLimiter } from "../../core/runner/rate-limiter.ts";
+import { getReporter, generateJsonReport, generateJunitXml } from "../../core/reporter/index.ts";
 import type { ReporterName } from "../../core/reporter/types.ts";
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname as pathDirname, isAbsolute, resolve as pathResolve } from "node:path";
 import type { TestSuite } from "../../core/parser/types.ts";
 import type { TestRunResult } from "../../core/runner/types.ts";
 import { printError, printWarning } from "../output.ts";
@@ -19,7 +22,10 @@ export interface RunOptions {
   env?: string;
   report: ReporterName;
   timeout?: number;
+  rateLimit?: number | "auto";
   bail: boolean;
+  /** Run regular suites sequentially (one after another) instead of in parallel. */
+  sequential?: boolean;
   noDb?: boolean;
   dbPath?: string;
   authToken?: string;
@@ -30,6 +36,8 @@ export interface RunOptions {
   envVars?: string[];
   dryRun?: boolean;
   json?: boolean;
+  /** Write the report to a file instead of stdout. */
+  reportOut?: string;
 }
 
 export async function runCommand(options: RunOptions): Promise<number> {
@@ -110,6 +118,30 @@ export async function runCommand(options: RunOptions): Promise<number> {
     return 2;
   }
 
+  // Auto-load ./.env.yaml from cwd when --env not given and the searchDir env
+  // file produced nothing. Useful when running with absolute test paths from
+  // a collection cwd (e.g. APPLY agents in the auto-loop).
+  if (!options.env && Object.keys(env).length === 0) {
+    const cwd = process.cwd();
+    const cwdEnvPath = `${cwd}/.env.yaml`;
+    // Avoid double-load if cwd is already covered by searchDir or its parent
+    const alreadyCovered = cwd === searchDir || cwd === dirname(searchDir);
+    if (!alreadyCovered) {
+      try {
+        const cwdVars = await loadEnvFile(cwdEnvPath);
+        if (cwdVars && Object.keys(cwdVars).length > 0) {
+          env = { ...cwdVars };
+          if (!options.json) {
+            process.stderr.write(`zond: using ./.env.yaml (cwd fallback)\n`);
+          }
+        }
+      } catch (err) {
+        printError(`Failed to load environment: ${(err as Error).message}`);
+        return 2;
+      }
+    }
+  }
+
   // Inject CLI auth token — overrides env file value
   if (options.authToken) {
     env.auth_token = options.authToken;
@@ -137,6 +169,19 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
+  // 3b. Resolve rate limit: CLI flag > .env.yaml `rateLimit:` field
+  let rateLimit: number | "auto" | undefined = options.rateLimit;
+  if (rateLimit === undefined) {
+    try {
+      const envMeta = await loadEnvMeta(options.env, searchDir);
+      rateLimit = envMeta.rateLimit;
+    } catch { /* meta load failure is non-fatal */ }
+  }
+  const rateLimiter = rateLimit === "auto"
+    ? createAdaptiveRateLimiter()
+    : createRateLimiter(rateLimit);
+  const runOpts = { rateLimiter };
+
   // 4. Run suites — setup suites run first (sequentially), their captures flow into regular suites
   const results: TestRunResult[] = [];
   const dryRun = options.dryRun === true;
@@ -146,7 +191,7 @@ export async function runCommand(options: RunOptions): Promise<number> {
   const setupCaptures: Record<string, string> = {};
 
   for (const suite of setupSuites) {
-    const result = await runSuite(suite, env, dryRun);
+    const result = await runSuite(suite, env, dryRun, runOpts);
     results.push(result);
     for (const step of result.steps) {
       for (const [k, v] of Object.entries(step.captures)) {
@@ -160,15 +205,21 @@ export async function runCommand(options: RunOptions): Promise<number> {
   if (options.bail) {
     // Sequential with bail at suite level
     for (const suite of regularSuites) {
-      const result = await runSuite(suite, enrichedEnv, dryRun);
+      const result = await runSuite(suite, enrichedEnv, dryRun, runOpts);
       results.push(result);
       if (!dryRun && (result.failed > 0 || result.steps.some((s) => s.status === "error"))) {
         break;
       }
     }
+  } else if (options.sequential) {
+    // Sequential without bail — run suites one by one
+    for (const suite of regularSuites) {
+      const result = await runSuite(suite, enrichedEnv, dryRun, runOpts);
+      results.push(result);
+    }
   } else {
     // Parallel
-    const all = await Promise.all(regularSuites.map((suite) => runSuite(suite, enrichedEnv, dryRun)));
+    const all = await Promise.all(regularSuites.map((suite) => runSuite(suite, enrichedEnv, dryRun, runOpts)));
     results.push(...all);
   }
 
@@ -182,10 +233,45 @@ export async function runCommand(options: RunOptions): Promise<number> {
 
   // 5b. Report
   if (!options.json) {
-    const reporter = getReporter(options.report);
-    reporter.report(results);
-    for (const w of warnings) {
-      printWarning(w);
+    if (options.reportOut) {
+      // Write report to a file via fs (bypass stdout). Console reporter falls
+      // back to a single-line summary on stdout; json/junit produce no stdout.
+      const outPath = isAbsolute(options.reportOut)
+        ? options.reportOut
+        : pathResolve(process.cwd(), options.reportOut);
+      let content: string;
+      let label: string;
+      switch (options.report) {
+        case "json":
+          content = generateJsonReport(results);
+          label = "JSON";
+          break;
+        case "junit":
+          content = generateJunitXml(results);
+          label = "JUnit XML";
+          break;
+        default: // "console" — fall back to JSON in the file (most useful)
+          content = generateJsonReport(results);
+          label = "JSON";
+          break;
+      }
+      try {
+        await mkdir(pathDirname(outPath), { recursive: true });
+        await writeFile(outPath, content, "utf-8");
+        process.stderr.write(`zond: ${label} report written to ${outPath}\n`);
+      } catch (err) {
+        printError(`Failed to write --report-out file ${outPath}: ${(err as Error).message}`);
+        return 2;
+      }
+      for (const w of warnings) {
+        printWarning(w);
+      }
+    } else {
+      const reporter = getReporter(options.report);
+      reporter.report(results);
+      for (const w of warnings) {
+        printWarning(w);
+      }
     }
   }
 
@@ -226,10 +312,13 @@ export async function runCommand(options: RunOptions): Promise<number> {
         test: s.name,
         ...(r.suite_file ? { file: r.suite_file } : {}),
         status: s.status,
+        ...(typeof s.response?.status === "number" ? { http_status: s.response.status } : {}),
+        ...(typeof s.response?.status === "number" && s.response.status >= 500 && s.response.status < 600 ? { is_5xx: true } : {}),
         error: s.error,
       }))
     );
-    printJson(jsonOk("run", { summary: { total, passed, failed }, failures, warnings, runId: savedRunId }));
+    const fiveXx = failures.filter(f => f.is_5xx).length;
+    printJson(jsonOk("run", { summary: { total, passed, failed, fiveXx }, failures, warnings, runId: savedRunId }));
   }
 
   return hasFailures ? 1 : 0;

package/src/cli/commands/serve.ts

@@ -1,4 +1,5 @@
 import { startServer } from "../../web/server.ts";
+import { printError } from "../output.ts";
 
 export interface ServeOptions {
   port?: number;
@@ -6,14 +7,18 @@ export interface ServeOptions {
   dbPath?: string;
   watch?: boolean;
   open?: boolean;
+  /** When true, kill any existing process holding `port` before binding (DANGEROUS). */
+  killExisting?: boolean;
 }
 
-/** Kill any existing process listening on the given port (Windows + Unix) */
+/** Range scanned when auto-picking a free port (only when --port is not set). */
+const PORT_SCAN_LENGTH = 11; // 8080..8090 inclusive
+
+/** Kill any existing process listening on the given port (Windows + Unix). */
 async function killPortHolder(port: number): Promise<void> {
   const isWin = process.platform === "win32";
   try {
     if (isWin) {
-      // PowerShell: find PID on port, then kill it
       const find = Bun.spawn(["powershell", "-NoProfile", "-Command",
         `(Get-NetTCPConnection -LocalPort ${port} -ErrorAction SilentlyContinue).OwningProcess`], {
         stdout: "pipe", stderr: "ignore",
@@ -26,12 +31,8 @@ async function killPortHolder(port: number): Promise<void> {
           stdout: "ignore", stderr: "ignore",
         });
       }
-      if (pids.length > 0) {
-        // Give OS time to release the port
-        await Bun.sleep(500);
-      }
+      if (pids.length > 0) await Bun.sleep(500);
     } else {
-      // Unix: lsof + kill
       const find = Bun.spawn(["lsof", "-ti", `:${port}`], {
         stdout: "pipe", stderr: "ignore",
       });
@@ -40,20 +41,54 @@ async function killPortHolder(port: number): Promise<void> {
       for (const pid of pids) {
         Bun.spawn(["kill", "-9", pid], { stdout: "ignore", stderr: "ignore" });
       }
-      if (pids.length > 0) {
-        await Bun.sleep(300);
-      }
+      if (pids.length > 0) await Bun.sleep(300);
     }
   } catch {
-    // Best effort — if we can't kill, startServer will fail with port-in-use
+    // Best effort — if we can't kill, the bind below will fail with port-in-use
+  }
+}
+
+/** Returns true if `port` is free on `host` (best-effort: tries to bind & immediately stops). */
+async function isPortFree(port: number, host: string): Promise<boolean> {
+  try {
+    const srv = Bun.serve({ port, hostname: host, fetch: () => new Response() });
+    srv.stop(true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Scans `[start, start+count)` and returns the first free port, or null. */
+async function pickAvailablePort(start: number, count: number, host: string): Promise<number | null> {
+  for (let p = start; p < start + count; p++) {
+    if (await isPortFree(p, host)) return p;
   }
+  return null;
 }
 
 export async function serveCommand(options: ServeOptions): Promise<number> {
-  const port = options.port ?? 8080;
+  const requested = options.port ?? 8080;
+  const host = options.host ?? "0.0.0.0";
 
-  // Kill previous instance on the same port
-  await killPortHolder(port);
+  let port: number;
+  if (options.killExisting) {
+    await killPortHolder(requested);
+    port = requested;
+  } else {
+    const picked = await pickAvailablePort(requested, PORT_SCAN_LENGTH, host);
+    if (picked === null) {
+      printError(
+        `All ports ${requested}..${requested + PORT_SCAN_LENGTH - 1} are in use. ` +
+        `Use --port <n> to pick another, or --kill-existing to free :${requested}.`,
+      );
+      return 1;
+    }
+    if (picked !== requested) {
+      process.stderr.write(`[zond] port ${requested} busy, using ${picked}\n`);
+    }
+    port = picked;
+  }
 
   await startServer({
     port,
@@ -62,20 +97,18 @@ export async function serveCommand(options: ServeOptions): Promise<number> {
     dev: options.watch,
   });
 
-  // Open browser if requested
   if (options.open) {
-    const host = options.host === "0.0.0.0" || !options.host ? "localhost" : options.host;
-    const url = `http://${host}:${port}`;
+    const openHost = host === "0.0.0.0" ? "localhost" : host;
+    const url = `http://${openHost}:${port}`;
     try {
       const cmd = process.platform === "win32" ? ["cmd", "/c", "start", url]
         : process.platform === "darwin" ? ["open", url]
         : ["xdg-open", url];
       Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
     } catch {
-      // Best effort — if browser can't open, server still runs
+      // Best effort
     }
   }
 
-  // Keep running — Bun.serve keeps the process alive
   return 0;
 }

package/src/cli/commands/sync.ts

@@ -5,6 +5,8 @@ import {
   extractEndpoints,
   extractSecuritySchemes,
   serializeSuite,
+  buildCatalog,
+  serializeCatalog,
 } from "../../core/generator/index.ts";
 import { generateSuites } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
@@ -78,6 +80,19 @@ export async function syncCommand(options: SyncOptions): Promise<number> {
     }
 
     if (newEndpoints.length === 0) {
+      // Update catalog even when no new endpoints — spec schema may have changed
+      const allEndpoints = extractEndpoints(doc);
+      const catalog = buildCatalog({
+        endpoints: allEndpoints,
+        securitySchemes,
+        specSource: options.specPath,
+        specHash: currentHash,
+        apiName: (doc as any).info?.title,
+        apiVersion: (doc as any).info?.version,
+        baseUrl: (doc as any).servers?.[0]?.url,
+      });
+      await Bun.write(join(options.testsDir, ".api-catalog.yaml"), serializeCatalog(catalog));
+
       const msg = "Spec changed (hash differs) but no new endpoints detected. Existing tests may need manual review.";
       warnings.push(msg);
       if (options.json) {
@@ -163,11 +178,23 @@ export async function syncCommand(options: SyncOptions): Promise<number> {
     await writeMeta(options.testsDir, {
       zondVersion: ZOND_VERSION,
       lastSyncedAt: new Date().toISOString(),
-      specUrl: options.specPath,
       specHash: currentHash,
       files: { ...meta.files, ...updatedMetaFiles },
     });
 
+    // Update .api-catalog.yaml with current spec state
+    const allEndpoints = extractEndpoints(doc);
+    const catalog = buildCatalog({
+      endpoints: allEndpoints,
+      securitySchemes,
+      specSource: options.specPath,
+      specHash: currentHash,
+      apiName: (doc as any).info?.title,
+      apiVersion: (doc as any).info?.version,
+      baseUrl: (doc as any).servers?.[0]?.url,
+    });
+    await Bun.write(join(options.testsDir, ".api-catalog.yaml"), serializeCatalog(catalog));
+
     // Sync DB collection if one is registered for this tests directory
     try {
       getDb();

package/src/cli/commands/update.ts

@@ -1,4 +1,4 @@
-import { VERSION } from "../index.ts";
+import { VERSION } from "../version.ts";
 import { isCompiledBinary } from "../runtime.ts";
 import { printError, printSuccess, printWarning } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";

package/src/cli/commands/use.ts

@@ -0,0 +1,57 @@
+import {
+  clearCurrentApi,
+  currentApiPath,
+  readCurrentApi,
+  writeCurrentApi,
+} from "../../core/context/current.ts";
+import { jsonError, jsonOk, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface UseOptions {
+  api?: string;
+  clear?: boolean;
+  json?: boolean;
+}
+
+export async function useCommand(opts: UseOptions): Promise<number> {
+  const path = currentApiPath();
+
+  if (opts.clear) {
+    const removed = clearCurrentApi();
+    if (opts.json) {
+      printJson(jsonOk("use", { action: "cleared", path, removed }));
+    } else if (removed) {
+      printSuccess(`Cleared ${path}`);
+    } else {
+      process.stdout.write(`No .zond-current file in ${process.cwd()}\n`);
+    }
+    return 0;
+  }
+
+  if (opts.api) {
+    try {
+      writeCurrentApi(opts.api);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (opts.json) printJson(jsonError("use", [message]));
+      else printError(message);
+      return 1;
+    }
+    if (opts.json) {
+      printJson(jsonOk("use", { action: "set", api: opts.api, path }));
+    } else {
+      printSuccess(`Set current API to '${opts.api}' (${path})`);
+    }
+    return 0;
+  }
+
+  const current = readCurrentApi();
+  if (opts.json) {
+    printJson(jsonOk("use", { action: "show", api: current, path }));
+  } else if (current) {
+    process.stdout.write(`${current}\n`);
+  } else {
+    process.stdout.write(`No current API set. Run 'zond use <api>'.\n`);
+  }
+  return 0;
+}