@kirrosh/zond 0.14.0 → 0.16.0

package/src/cli/commands/run.ts

@@ -9,6 +9,7 @@ import type { ReporterName } from "../../core/reporter/types.ts";
 import type { TestSuite } from "../../core/parser/types.ts";
 import type { TestRunResult } from "../../core/runner/types.ts";
 import { printError, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { getDb } from "../../db/schema.ts";
 import { createRun, finalizeRun, saveResults, findCollectionByTestPath } from "../../db/queries.ts";
 
@@ -25,6 +26,7 @@ export interface RunOptions {
   tag?: string[];
   envVars?: string[];
   dryRun?: boolean;
+  json?: boolean;
 }
 
 export async function runCommand(options: RunOptions): Promise<number> {
@@ -51,14 +53,19 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
-  // 1c. Safe mode: filter to GET-only tests
+  // 1c. Safe mode: keep GET, set-only steps, and auth-related requests
   if (options.safe) {
+    const AUTH_PATH_RE = /\/(auth|login|signin|token|oauth)\b/i;
     for (const suite of suites) {
-      suite.tests = suite.tests.filter(t => t.method === "GET");
+      suite.tests = suite.tests.filter(t => {
+        if (t.method === "GET" || !t.method) return true;
+        if (AUTH_PATH_RE.test(t.path)) return true;
+        return false;
+      });
     }
     suites = suites.filter(s => s.tests.length > 0);
     if (suites.length === 0) {
-      printWarning("No GET tests found. Nothing to run in safe mode.");
+      printWarning("No safe tests found. Nothing to run in safe mode.");
       return 0;
     }
   }
@@ -128,29 +135,65 @@ export async function runCommand(options: RunOptions): Promise<number> {
     results.push(...all);
   }
 
-  // 5. Report
-  const reporter = getReporter(options.report);
-  reporter.report(results);
+  // 5. Collect warnings
+  const warnings: string[] = [];
+  const rateLimited = results.flatMap(r => r.steps)
+    .filter(s => s.response?.status === 429);
+  if (rateLimited.length > 0) {
+    warnings.push(`${rateLimited.length} request(s) hit rate limit (429). Consider: consolidating login steps, adding --bail, or using retry_until with delay.`);
+  }
+
+  // 5b. Report
+  if (!options.json) {
+    const reporter = getReporter(options.report);
+    reporter.report(results);
+    for (const w of warnings) {
+      printWarning(w);
+    }
+  }
 
   // 6. Save to DB
+  let savedRunId: number | undefined;
   if (!options.noDb) {
     try {
       getDb(options.dbPath);
       const collection = findCollectionByTestPath(options.path);
-      const runId = createRun({
+      savedRunId = createRun({
         started_at: results[0]?.started_at ?? new Date().toISOString(),
         environment: options.env,
         collection_id: collection?.id,
       });
-      finalizeRun(runId, results);
-      saveResults(runId, results);
+      finalizeRun(savedRunId, results);
+      saveResults(savedRunId, results);
     } catch (err) {
       printWarning(`Failed to save results to DB: ${(err as Error).message}`);
     }
   }
 
   // 7. Exit code (always 0 in dry-run mode)
-  if (dryRun) return 0;
+  if (dryRun) {
+    if (options.json) {
+      printJson(jsonOk("run", { summary: { total: results.length, passed: 0, failed: 0 }, dryRun: true }));
+    }
+    return 0;
+  }
   const hasFailures = results.some((r) => r.failed > 0 || r.steps.some((s) => s.status === "error"));
+
+  if (options.json) {
+    const total = results.reduce((s, r) => s + r.total, 0);
+    const passed = results.reduce((s, r) => s + r.passed, 0);
+    const failed = results.reduce((s, r) => s + r.failed, 0);
+    const failures = results.flatMap(r =>
+      r.steps.filter(s => s.status === "fail" || s.status === "error").map(s => ({
+        suite: r.suite_name,
+        test: s.name,
+        ...(r.suite_file ? { file: r.suite_file } : {}),
+        status: s.status,
+        error: s.error,
+      }))
+    );
+    printJson(jsonOk("run", { summary: { total, passed, failed }, failures, warnings, runId: savedRunId }));
+  }
+
   return hasFailures ? 1 : 0;
 }

package/src/cli/commands/serve.ts

@@ -3,20 +3,79 @@ import { startServer } from "../../web/server.ts";
 export interface ServeOptions {
   port?: number;
   host?: string;
-  openapiSpec?: string;
-  testsDir?: string;
   dbPath?: string;
   watch?: boolean;
+  open?: boolean;
+}
+
+/** 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",
+      });
+      const out = await new Response(find.stdout).text();
+      const pids = [...new Set(out.trim().split(/\s+/).filter(s => /^\d+$/.test(s) && s !== "0"))];
+      for (const pid of pids) {
+        Bun.spawn(["powershell", "-NoProfile", "-Command",
+          `Stop-Process -Id ${pid} -Force -ErrorAction SilentlyContinue`], {
+          stdout: "ignore", stderr: "ignore",
+        });
+      }
+      if (pids.length > 0) {
+        // Give OS time to release the port
+        await Bun.sleep(500);
+      }
+    } else {
+      // Unix: lsof + kill
+      const find = Bun.spawn(["lsof", "-ti", `:${port}`], {
+        stdout: "pipe", stderr: "ignore",
+      });
+      const out = await new Response(find.stdout).text();
+      const pids = out.trim().split(/\s+/).filter(s => /^\d+$/.test(s));
+      for (const pid of pids) {
+        Bun.spawn(["kill", "-9", pid], { stdout: "ignore", stderr: "ignore" });
+      }
+      if (pids.length > 0) {
+        await Bun.sleep(300);
+      }
+    }
+  } catch {
+    // Best effort — if we can't kill, startServer will fail with port-in-use
+  }
 }
 
 export async function serveCommand(options: ServeOptions): Promise<number> {
+  const port = options.port ?? 8080;
+
+  // Kill previous instance on the same port
+  await killPortHolder(port);
+
   await startServer({
-    port: options.port,
+    port,
     host: options.host,
     dbPath: options.dbPath,
     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}`;
+    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
+    }
+  }
+
   // Keep running — Bun.serve keeps the process alive
   return 0;
 }

package/src/cli/commands/validate.ts

@@ -1,18 +1,34 @@
 import { parse } from "../../core/parser/yaml-parser.ts";
 import { printError, printSuccess } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
 export interface ValidateOptions {
   path: string;
+  json?: boolean;
 }
 
 export async function validateCommand(options: ValidateOptions): Promise<number> {
   try {
     const suites = await parse(options.path);
     const totalSteps = suites.reduce((sum, s) => sum + s.tests.length, 0);
-    printSuccess(`OK: ${suites.length} suite(s), ${totalSteps} test(s) validated successfully`);
+    if (options.json) {
+      printJson(jsonOk("validate", {
+        files: suites.length,
+        suites: suites.length,
+        tests: totalSteps,
+        valid: true,
+      }));
+    } else {
+      printSuccess(`OK: ${suites.length} suite(s), ${totalSteps} test(s) validated successfully`);
+    }
     return 0;
   } catch (err) {
-    printError(err instanceof Error ? err.message : String(err));
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("validate", [message]));
+    } else {
+      printError(message);
+    }
     return 2;
   }
 }

package/src/cli/index.ts

@@ -6,6 +6,12 @@ import { serveCommand } from "./commands/serve.ts";
 import { mcpCommand } from "./commands/mcp.ts";
 import { coverageCommand } from "./commands/coverage.ts";
 import { ciInitCommand } from "./commands/ci-init.ts";
+import { initCommand } from "./commands/init.ts";
+import { describeCommand } from "./commands/describe.ts";
+import { dbCommand } from "./commands/db.ts";
+import { requestCommand } from "./commands/request.ts";
+import { guideCommand } from "./commands/guide.ts";
+import { generateCommand } from "./commands/generate.ts";
 import { printError } from "./output.ts";
 import { getRuntimeInfo } from "./runtime.ts";
 import { getDb } from "../db/schema.ts";
@@ -21,6 +27,23 @@ export interface ParsedArgs {
   flags: Record<string, string | boolean>;
 }
 
+/**
+ * Strip MSYS/Git Bash automatic path conversion.
+ * Git Bash on Windows converts "/foo" → "C:/Program Files/Git/foo".
+ * Detect and reverse this for flags that expect API paths (e.g. --path /users).
+ */
+const MSYS_PREFIX_RE = /^[A-Z]:[\\/](?:Program Files[\\/]Git|msys64|usr)[\\/]/i;
+
+function stripMsysPath(value: string): string {
+  if (!MSYS_PREFIX_RE.test(value)) return value;
+  // Extract the original path: "C:/Program Files/Git/products" → "/products"
+  const stripped = value.replace(MSYS_PREFIX_RE, "/");
+  return stripped;
+}
+
+/** Flags whose values are API paths, not filesystem paths — subject to MSYS fix */
+const API_PATH_FLAGS = new Set(["path", "json-path"]);
+
 export function parseArgs(argv: string[]): ParsedArgs {
   // argv: [bunPath, scriptPath, ...userArgs]
   const args = argv.slice(2);
@@ -36,12 +59,15 @@ export function parseArgs(argv: string[]): ParsedArgs {
       const eqIndex = arg.indexOf("=");
       if (eqIndex !== -1) {
         // --flag=value
-        flags[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+        const key = arg.slice(2, eqIndex);
+        let val = arg.slice(eqIndex + 1);
+        if (API_PATH_FLAGS.has(key)) val = stripMsysPath(val);
+        flags[key] = val;
       } else {
         const key = arg.slice(2);
         const next = args[i + 1];
         if (next !== undefined && !next.startsWith("-")) {
-          flags[key] = next;
+          flags[key] = API_PATH_FLAGS.has(key) ? stripMsysPath(next) : next;
           i++;
         } else {
           flags[key] = true;
@@ -69,7 +95,14 @@ Usage:
   zond run <path>       Run API tests
   zond validate <path>  Validate test files without running
   zond coverage         Analyze API test coverage
+  zond init             Register a new API for testing
+  zond describe <spec>  Describe endpoints from OpenAPI spec
+  zond db <subcommand>  Query the test database
+  zond request <method> <url>  Send an ad-hoc HTTP request
+  zond generate <spec>  Generate test suites from OpenAPI spec
+  zond guide <spec>     Generate test generation guide from OpenAPI spec
   zond serve            Start web dashboard
+  zond ui               Alias for 'serve --open' (start dashboard & open browser)
   zond mcp              Start MCP server (stdio transport for AI agents)
                            --dir <path>  Set working directory (relative paths resolve here)
   zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
@@ -88,6 +121,40 @@ Options for 'run':
   --safe               Run only GET tests (read-only, safe mode)
   --tag <tag>          Filter suites by tag (repeatable, comma-separated, OR logic)
 
+Options for 'init':
+  --name <name>        API name (auto-detected from spec title if omitted)
+  --spec <path>        Path to OpenAPI spec file
+  --base-url <url>     Override base URL
+  --force              Overwrite existing API collection
+
+Options for 'describe':
+  --compact            List all endpoints briefly
+  --method <method>    HTTP method for single endpoint detail
+  --path <path>        Endpoint path for single endpoint detail
+
+Options for 'db':
+  zond db collections           List all API collections
+  zond db runs [--limit N]      List recent test runs
+  zond db run <id> [--verbose]  Show run details
+  zond db diagnose <id>         Diagnose run failures
+  zond db compare <idA> <idB>   Compare two runs
+
+Options for 'request':
+  --header <H>         Request header "Name: Value" (repeatable)
+  --body <json>        Request body (JSON string)
+  --env <name>         Environment for variable interpolation
+  --api <name>         Collection name (loads env from its directory)
+  --json-path <path>   Extract value from response (dot notation)
+
+Options for 'generate':
+  --output <dir>       Output directory for generated test files (required)
+  --tag <tag>          Generate only for endpoints with this tag
+  --uncovered-only     Skip endpoints already covered by existing tests
+
+Options for 'guide':
+  --tests-dir <dir>    Filter to uncovered endpoints only
+  --tag <tag>          Generate only for endpoints with this tag
+
 Options for 'coverage':
   --api <name>         Use API collection (auto-resolves spec and tests dir)
   --spec <path>        Path to OpenAPI spec (required unless --api used)
@@ -95,11 +162,11 @@ Options for 'coverage':
   --fail-on-coverage N Exit 1 when coverage percentage is below N (0–100)
   --run-id <number>    Cross-reference with a test run for pass/fail/5xx breakdown
 
-Options for 'serve':
+Options for 'serve' / 'ui':
   --port <port>        Server port (default: 8080)
   --host <host>        Server host (default: 0.0.0.0)
-  --openapi <spec>     Path to OpenAPI spec for Explorer
   --db <path>          Path to SQLite database file (default: zond.db)
+  --open               Open dashboard in browser after starting
   --watch              Enable dev mode with hot reload (auto-refresh browser on file changes)
 
 Options for 'ci init':
@@ -109,6 +176,7 @@ Options for 'ci init':
   --force              Overwrite existing CI config
 
 General:
+  --json               Output in JSON envelope format (available for all commands)
   --help, -h           Show this help
   --version, -v        Show version`);
 }
@@ -117,6 +185,7 @@ const VALID_REPORTERS = new Set<string>(["console", "json", "junit"]);
 
 async function main(): Promise<number> {
   const { command, positional, flags } = parseArgs(process.argv);
+  const jsonFlag = flags["json"] === true;
 
   // Help
   if (command === "help" || command === "--help" || flags["help"] === true || flags["h"] === true) {
@@ -205,6 +274,7 @@ async function main(): Promise<number> {
         tag: tags.length > 0 ? tags : undefined,
         envVars: envVarValues.length > 0 ? envVarValues : undefined,
         dryRun: flags["dry-run"] === true,
+        json: jsonFlag,
       });
     }
 
@@ -215,9 +285,10 @@ async function main(): Promise<number> {
         return 2;
       }
 
-      return validateCommand({ path });
+      return validateCommand({ path, json: jsonFlag });
     }
 
+    case "ui":
     case "serve": {
       const portRaw = flags["port"];
       let port: number | undefined;
@@ -231,9 +302,9 @@ async function main(): Promise<number> {
       return serveCommand({
         port,
         host: typeof flags["host"] === "string" ? flags["host"] : undefined,
-        openapiSpec: typeof flags["openapi"] === "string" ? flags["openapi"] : undefined,
         dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
         watch: flags["watch"] === true,
+        open: command === "ui" || flags["open"] === true,
       });
     }
 
@@ -257,6 +328,7 @@ async function main(): Promise<number> {
         platform,
         force: flags["force"] === true,
         dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
+        json: jsonFlag,
       });
     }
 
@@ -304,7 +376,132 @@ async function main(): Promise<number> {
           return 2;
         }
       }
-      return coverageCommand({ spec, tests, failOnCoverage, runId });
+      return coverageCommand({ spec, tests, failOnCoverage, runId, json: jsonFlag });
+    }
+
+    case "init": {
+      return initCommand({
+        name: typeof flags["name"] === "string" ? flags["name"] : undefined,
+        spec: typeof flags["spec"] === "string" ? flags["spec"] : positional[0],
+        baseUrl: typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
+        dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
+        force: flags["force"] === true,
+        insecure: flags["insecure"] === true,
+        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "describe": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond describe <spec> [--compact | --method <M> --path <P>]");
+        return 2;
+      }
+      return describeCommand({
+        specPath,
+        compact: flags["compact"] === true,
+        method: typeof flags["method"] === "string" ? flags["method"] : undefined,
+        path: typeof flags["path"] === "string" ? flags["path"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "db": {
+      const dbSub = positional[0];
+      if (!dbSub) {
+        printError("Missing subcommand. Usage: zond db <collections|runs|run|diagnose|compare> [args]");
+        return 2;
+      }
+      const limitRaw = flags["limit"];
+      let limit: number | undefined;
+      if (typeof limitRaw === "string") {
+        limit = parseInt(limitRaw, 10);
+        if (isNaN(limit) || limit <= 0) limit = undefined;
+      }
+      return dbCommand({
+        subcommand: dbSub,
+        positional: positional.slice(1),
+        limit,
+        verbose: flags["verbose"] === true,
+        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "request": {
+      const method = positional[0];
+      const url = positional[1];
+      if (!method || !url) {
+        printError("Missing arguments. Usage: zond request <METHOD> <URL> [--header H] [--body JSON]");
+        return 2;
+      }
+      // Collect all --header flags
+      const headerValues: string[] = [];
+      const rawArgs = process.argv.slice(2);
+      for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i]!;
+        if (arg === "--header" && rawArgs[i + 1]) {
+          headerValues.push(rawArgs[i + 1]!);
+          i++;
+        } else if (arg.startsWith("--header=")) {
+          headerValues.push(arg.slice("--header=".length));
+        }
+      }
+
+      const timeoutRaw = flags["timeout"];
+      let timeout: number | undefined;
+      if (typeof timeoutRaw === "string") {
+        timeout = parseInt(timeoutRaw, 10);
+        if (isNaN(timeout) || timeout <= 0) timeout = undefined;
+      }
+
+      return requestCommand({
+        method,
+        url,
+        headers: headerValues.length > 0 ? headerValues : undefined,
+        body: typeof flags["body"] === "string" ? flags["body"] : undefined,
+        timeout,
+        env: typeof flags["env"] === "string" ? flags["env"] : undefined,
+        api: typeof flags["api"] === "string" ? flags["api"] : undefined,
+        jsonPath: typeof flags["json-path"] === "string" ? flags["json-path"] : undefined,
+        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "generate": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond generate <spec> --output <dir> [--tag <tag>] [--uncovered-only] [--json]");
+        return 2;
+      }
+      const output = typeof flags["output"] === "string" ? flags["output"] : undefined;
+      if (!output) {
+        printError("Missing --output <dir>. Usage: zond generate <spec> --output <dir>");
+        return 2;
+      }
+      return generateCommand({
+        specPath,
+        output,
+        tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
+        uncoveredOnly: flags["uncovered-only"] === true,
+        json: jsonFlag,
+      });
+    }
+
+    case "guide": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond guide <spec> [--tests-dir <dir>] [--tag <tag>]");
+        return 2;
+      }
+      return guideCommand({
+        specPath,
+        testsDir: typeof flags["tests-dir"] === "string" ? flags["tests-dir"] : undefined,
+        tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
+        json: jsonFlag,
+      });
     }
 
     default: {

package/src/cli/json-envelope.ts

@@ -0,0 +1,19 @@
+export interface JsonEnvelope<T = unknown> {
+  ok: boolean;
+  command: string;
+  data: T;
+  warnings: string[];
+  errors: string[];
+}
+
+export function jsonOk<T>(command: string, data: T, warnings?: string[]): JsonEnvelope<T> {
+  return { ok: true, command, data, warnings: warnings ?? [], errors: [] };
+}
+
+export function jsonError(command: string, errors: string[], warnings?: string[]): JsonEnvelope<null> {
+  return { ok: false, command, data: null, warnings: warnings ?? [], errors };
+}
+
+export function printJson(envelope: JsonEnvelope): void {
+  process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+}