@kirrosh/zond 0.14.0 → 0.17.0

package/src/cli/index.ts

@@ -3,9 +3,16 @@
 import { runCommand } from "./commands/run.ts";
 import { validateCommand } from "./commands/validate.ts";
 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 { exportCommand } from "./commands/export.ts";
+import { syncCommand } from "./commands/sync.ts";
 import { printError } from "./output.ts";
 import { getRuntimeInfo } from "./runtime.ts";
 import { getDb } from "../db/schema.ts";
@@ -21,6 +28,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 +60,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,10 +96,17 @@ 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 mcp              Start MCP server (stdio transport for AI agents)
-                           --dir <path>  Set working directory (relative paths resolve here)
+  zond ui               Alias for 'serve --open' (start dashboard & open browser)
   zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
+  zond export postman <path>  Export YAML tests as Postman Collection v2.1
+  zond sync <spec>      Detect new/removed endpoints and generate tests for new ones
 
 Options for 'run':
   --dry-run            Show requests without sending them (exit code always 0)
@@ -88,6 +122,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 +163,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':
@@ -108,7 +176,18 @@ Options for 'ci init':
   --dir <path>         Project root directory (default: current directory)
   --force              Overwrite existing CI config
 
+Options for 'export postman':
+  --output <file>      Output file path (default: collection.postman.json)
+  --env <file>         Also export .env.yaml as Postman environment
+  --collection-name <name>  Collection name (default: derived from path)
+
+Options for 'sync':
+  --tests <dir>        Path to test files directory (required)
+  --dry-run            Show what would be generated without writing files
+  --tag <tag>          Limit sync to endpoints with this tag
+
 General:
+  --json               Output in JSON envelope format (available for all commands)
   --help, -h           Show this help
   --version, -v        Show version`);
 }
@@ -117,6 +196,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 +285,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 +296,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,16 +313,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 "mcp": {
-      return mcpCommand({
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-        dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
+        open: command === "ui" || flags["open"] === true,
       });
     }
 
@@ -257,6 +332,7 @@ async function main(): Promise<number> {
         platform,
         force: flags["force"] === true,
         dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
+        json: jsonFlag,
       });
     }
 
@@ -304,7 +380,172 @@ 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,
+      });
+    }
+
+    case "export": {
+      const subcommand = positional[0];
+      if (subcommand !== "postman") {
+        printError(`Unknown export subcommand: ${subcommand ?? "(none)"}. Usage: zond export postman <path>`);
+        return 2;
+      }
+      const testsPath = positional[1];
+      if (!testsPath) {
+        printError("Missing tests path. Usage: zond export postman <path> [--output <file>]");
+        return 2;
+      }
+      return exportCommand({
+        testsPath,
+        output: typeof flags["output"] === "string" ? flags["output"] : "collection.postman.json",
+        env: typeof flags["env"] === "string" ? flags["env"] : undefined,
+        collectionName: typeof flags["collection-name"] === "string" ? flags["collection-name"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "sync": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond sync <spec> --tests <dir> [--dry-run] [--tag <tag>]");
+        return 2;
+      }
+      const testsDir = typeof flags["tests"] === "string" ? flags["tests"] : undefined;
+      if (!testsDir) {
+        printError("Missing --tests <dir>. Usage: zond sync <spec> --tests <dir>");
+        return 2;
+      }
+      return syncCommand({
+        specPath,
+        testsDir,
+        dryRun: flags["dry-run"] === true,
+        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");
+}