@kirrosh/zond 0.13.0 → 0.16.0

package/src/cli/index.ts

@@ -3,18 +3,15 @@
 import { runCommand } from "./commands/run.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { serveCommand } from "./commands/serve.ts";
-import { collectionsCommand } from "./commands/collections.ts";
-import { aiGenerateCommand } from "./commands/ai-generate.ts";
 import { mcpCommand } from "./commands/mcp.ts";
-import { initCommand } from "./commands/init.ts";
-import { updateCommand } from "./commands/update.ts";
-import { chatCommand } from "./commands/chat.ts";
-import { runsCommand } from "./commands/runs.ts";
 import { coverageCommand } from "./commands/coverage.ts";
-import { doctorCommand } from "./commands/doctor.ts";
-import { addApiCommand } from "./commands/add-api.ts";
 import { ciInitCommand } from "./commands/ci-init.ts";
-import { compareCommand } from "./commands/compare.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";
@@ -30,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);
@@ -45,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;
@@ -75,51 +92,20 @@ function printUsage(): void {
   console.log(`zond - API Testing Platform
 
 Usage:
-  zond add-api <name>   Register a new API (collection)
   zond run <path>       Run API tests
   zond validate <path>  Validate test files without running
-  zond ai-generate --from <spec> --prompt "..."  Generate tests with AI
-  zond runs [id]        View test run history
-  zond coverage --spec <path> --tests <dir>  Analyze API test coverage
-  zond collections      List test collections
+  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 init             Initialize a new zond project
-  zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
+  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 chat             Start interactive AI chat for API testing
-  zond compare <runA> <runB>  Compare two test runs (regressions/fixes)
-  zond doctor           Run diagnostic checks
-  zond update           Update to latest version
-
-Options for 'add-api':
-  --spec <path-or-url>   OpenAPI spec (extracts base_url from servers[0])
-  --dir <directory>      Base directory (default: ./apis/<name>/)
-  --env key=value        Set environment variables (repeatable)
-  --insecure             Skip TLS verification (self-signed certs)
-
-Options for 'chat':
-  --provider <name>    LLM provider: ollama, openai, anthropic, custom (default: ollama)
-  --model <name>       Model name (default: provider-specific)
-  --api-key <key>      API key (or set ZOND_AI_KEY env var)
-  --base-url <url>     Provider base URL override
-  --safe               Only allow running GET tests (read-only mode)
-
-Options for 'runs':
-  runs                 List recent test runs
-  runs <id>            Show run details with step results
-  --limit <n>          Number of runs to show (default: 20)
-
-Options for 'compare':
-  compare <runA> <runB>   Compare two run IDs
-  Exit code 1 if regressions found, 0 otherwise
-
-Options for 'coverage':
-  --api <name>         Use API collection (auto-resolves spec and tests dir)
-  --spec <path>        Path to OpenAPI spec (required unless --api used)
-  --tests <dir>        Path to test files directory (required unless --api used)
-  --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
+  zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
 
 Options for 'run':
   --dry-run            Show requests without sending them (exit code always 0)
@@ -135,21 +121,52 @@ 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 'ai-generate':
-  --api <name>         Use API collection (auto-resolves spec and output dir)
-  --from <spec>        Path to OpenAPI spec (required unless --api used)
-  --prompt <text>      Test scenario description (required)
-  --provider <name>    LLM provider: ollama, openai, anthropic, custom (default: ollama)
-  --model <name>       Model name (default: provider-specific)
-  --api-key <key>      API key (or set ZOND_AI_KEY env var)
-  --base-url <url>     Provider base URL override
-  --output <dir>       Output directory (default: ./generated/ai/)
-
-Options for 'serve':
+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)
+  --tests <dir>        Path to test files directory (required unless --api used)
+  --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' / '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':
@@ -159,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`);
 }
@@ -167,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) {
@@ -186,35 +205,6 @@ async function main(): Promise<number> {
   }
 
   switch (command) {
-    case "add-api": {
-      const name = positional[0];
-      if (!name) {
-        printError("Missing name argument. Usage: zond add-api <name> [--spec <path>] [--dir <dir>]");
-        return 2;
-      }
-
-      // Collect all --env flags (parseArgs only stores last one, so re-parse)
-      const envValues: string[] = [];
-      const rawArgs = process.argv.slice(2);
-      for (let i = 0; i < rawArgs.length; i++) {
-        if (rawArgs[i] === "--env" && rawArgs[i + 1] && rawArgs[i + 1]!.includes("=")) {
-          envValues.push(rawArgs[i + 1]!);
-          i++;
-        } else if (rawArgs[i]?.startsWith("--env=") && rawArgs[i]!.slice(6).includes("=")) {
-          envValues.push(rawArgs[i]!.slice(6));
-        }
-      }
-
-      return addApiCommand({
-        name,
-        spec: typeof flags["spec"] === "string" ? flags["spec"] : undefined,
-        dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
-        envPairs: envValues.length > 0 ? envValues : undefined,
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-        insecure: flags["insecure"] === true,
-      });
-    }
-
     case "run": {
       let path = positional[0];
       const apiFlag = typeof flags["api"] === "string" ? flags["api"] : undefined;
@@ -284,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,
       });
     }
 
@@ -294,54 +285,10 @@ async function main(): Promise<number> {
         return 2;
       }
 
-      return validateCommand({ path });
-    }
-
-    case "ai-generate": {
-      let from = flags["from"] as string | undefined;
-      let output = typeof flags["output"] === "string" ? flags["output"] : undefined;
-      const aiGenApiFlag = typeof flags["api"] === "string" ? flags["api"] : undefined;
-
-      // Resolve --api to spec and output dir from collection
-      if (aiGenApiFlag) {
-        try {
-          getDb(typeof flags["db"] === "string" ? flags["db"] : undefined);
-          const col = findCollectionByNameOrId(aiGenApiFlag);
-          if (!col) { printError(`API '${aiGenApiFlag}' not found`); return 1; }
-          if (!from && col.openapi_spec) from = col.openapi_spec;
-          if (!output && col.test_path) output = col.test_path;
-        } catch (err) {
-          printError(`Failed to resolve --api: ${(err as Error).message}`);
-          return 2;
-        }
-      }
-
-      if (typeof from !== "string") {
-        printError("Missing --from <spec>. Usage: zond ai-generate --from <spec> --prompt \"...\"");
-        return 2;
-      }
-      const prompt = flags["prompt"];
-      if (typeof prompt !== "string") {
-        printError("Missing --prompt <text>. Usage: zond ai-generate --from <spec> --prompt \"...\"");
-        return 2;
-      }
-      return aiGenerateCommand({
-        from,
-        prompt,
-        provider: typeof flags["provider"] === "string" ? flags["provider"] : "ollama",
-        model: typeof flags["model"] === "string" ? flags["model"] : undefined,
-        apiKey: typeof flags["api-key"] === "string" ? flags["api-key"] : undefined,
-        baseUrl: typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
-        output,
-      });
-    }
-
-    case "collections": {
-      return collectionsCommand(
-        typeof flags["db"] === "string" ? flags["db"] : undefined,
-      );
+      return validateCommand({ path, json: jsonFlag });
     }
 
+    case "ui":
     case "serve": {
       const portRaw = flags["port"];
       let port: number | undefined;
@@ -355,15 +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,
-      });
-    }
-
-    case "init": {
-      return initCommand({
-        force: flags["force"] === true,
+        open: command === "ui" || flags["open"] === true,
       });
     }
 
@@ -374,49 +315,6 @@ async function main(): Promise<number> {
       });
     }
 
-    case "chat": {
-      return chatCommand({
-        provider: typeof flags["provider"] === "string" ? flags["provider"] : undefined,
-        model: typeof flags["model"] === "string" ? flags["model"] : undefined,
-        apiKey: typeof flags["api-key"] === "string" ? flags["api-key"] : undefined,
-        baseUrl: typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
-        safe: flags["safe"] === true,
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-      });
-    }
-
-    case "update": {
-      return updateCommand({ force: flags["force"] === true });
-    }
-
-    case "runs": {
-      const idRaw = positional[0];
-      let runId: number | undefined;
-      if (idRaw) {
-        runId = parseInt(idRaw, 10);
-        if (isNaN(runId)) {
-          printError(`Invalid run ID: ${idRaw}`);
-          return 2;
-        }
-      }
-
-      const limitRaw = flags["limit"];
-      let limit: number | undefined;
-      if (typeof limitRaw === "string") {
-        limit = parseInt(limitRaw, 10);
-        if (isNaN(limit) || limit <= 0) {
-          printError(`Invalid limit value: ${limitRaw}`);
-          return 2;
-        }
-      }
-
-      return runsCommand({
-        runId,
-        limit,
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-      });
-    }
-
     case "ci": {
       const ciSub = positional[0];
       if (ciSub !== "init") {
@@ -430,32 +328,7 @@ async function main(): Promise<number> {
         platform,
         force: flags["force"] === true,
         dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
-      });
-    }
-
-    case "compare": {
-      const rawA = positional[0];
-      const rawB = positional[1];
-      if (!rawA || !rawB) {
-        printError("Usage: zond compare <runA> <runB>");
-        return 2;
-      }
-      const runA = parseInt(rawA, 10);
-      const runB = parseInt(rawB, 10);
-      if (isNaN(runA) || isNaN(runB)) {
-        printError("Run IDs must be integers");
-        return 2;
-      }
-      return compareCommand({
-        runA,
-        runB,
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-      });
-    }
-
-    case "doctor": {
-      return doctorCommand({
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
+        json: jsonFlag,
       });
     }
 
@@ -503,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");
+}