@kirrosh/zond 0.7.0

package/src/cli/commands/ci-init.ts

@@ -0,0 +1,163 @@
+import { resolve, dirname } from "path";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { printSuccess, printError } from "../output.ts";
+
+export interface CiInitOptions {
+  platform?: "github" | "gitlab";
+  force: boolean;
+  dir?: string;
+}
+
+const GH_ACTIONS_TEMPLATE = `name: API Tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 */6 * * *"
+  workflow_dispatch:
+  repository_dispatch:
+    types: [api-updated]
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install zond
+        run: curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+
+      - name: Check coverage
+        run: zond coverage --api myapi --fail-on-coverage 60
+        # Fails if coverage drops below 60% — adjust threshold as needed
+
+      - name: Run smoke tests (read-only, safe for production)
+        run: |
+          mkdir -p test-results
+          zond run apis/ --tag smoke --safe --report junit --no-db > test-results/smoke.xml
+          # Use --env-var "API_KEY=\${{ secrets.API_KEY }}" to inject secrets without writing to disk
+        continue-on-error: true
+
+      - name: Run CRUD tests (staging only)
+        run: |
+          zond run apis/ --tag crud --env staging --report junit --no-db > test-results/crud.xml
+          # Add --env-var "BASE_URL=\${{ secrets.STAGING_URL }}" for staging URL
+        continue-on-error: true
+
+      - name: Publish test results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-results/*.xml
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results
+          path: test-results/
+`;
+
+const GITLAB_CI_TEMPLATE = `# Trigger via API: curl -X POST --form ref=main --form token=TRIGGER_TOKEN $CI_API_V4_URL/projects/$CI_PROJECT_ID/trigger/pipeline
+
+variables:
+  # Set API_KEY in GitLab CI/CD → Settings → Variables
+  API_KEY: ""
+
+api-coverage:
+  image: ubuntu:latest
+  before_script:
+    - apt-get update -qq && apt-get install -y -qq curl
+    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+  script:
+    - zond coverage --api myapi --fail-on-coverage 60
+
+api-smoke:
+  image: ubuntu:latest
+  before_script:
+    - apt-get update -qq && apt-get install -y -qq curl
+    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+  script:
+    - mkdir -p test-results
+    # Use --env-var to inject secrets without writing to disk
+    - zond run apis/ --tag smoke --safe --report junit --no-db --env-var "API_KEY=$API_KEY" > test-results/smoke.xml
+  allow_failure:
+    exit_codes: 1
+  artifacts:
+    when: always
+    reports:
+      junit: test-results/smoke.xml
+
+api-crud:
+  image: ubuntu:latest
+  before_script:
+    - apt-get update -qq && apt-get install -y -qq curl
+    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+  script:
+    - mkdir -p test-results
+    - zond run apis/ --tag crud --env staging --report junit --no-db > test-results/crud.xml
+  allow_failure:
+    exit_codes: 1
+  artifacts:
+    when: always
+    reports:
+      junit: test-results/crud.xml
+`;
+
+function writeIfMissing(filePath: string, content: string, force: boolean): boolean {
+  if (!force && existsSync(filePath)) {
+    console.log(`  Skipped ${filePath} (already exists, use --force to overwrite)`);
+    return false;
+  }
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, content, "utf-8");
+  console.log(`  Created ${filePath}`);
+  return true;
+}
+
+function detectPlatform(cwd: string): "github" | "gitlab" | undefined {
+  if (existsSync(resolve(cwd, ".github"))) return "github";
+  if (existsSync(resolve(cwd, ".gitlab-ci.yml"))) return "gitlab";
+  return undefined;
+}
+
+export async function ciInitCommand(options: CiInitOptions): Promise<number> {
+  const cwd = options.dir ? resolve(options.dir) : process.cwd();
+  let platform = options.platform;
+
+  if (!platform) {
+    platform = detectPlatform(cwd);
+    if (!platform) {
+      platform = "github";
+      console.log("No CI platform detected, defaulting to GitHub Actions.\n");
+    } else {
+      console.log(`Detected ${platform === "github" ? "GitHub Actions" : "GitLab CI"}.\n`);
+    }
+  }
+
+  console.log(`Generating ${platform === "github" ? "GitHub Actions" : "GitLab CI"} workflow...\n`);
+
+  let created = false;
+
+  if (platform === "github") {
+    const targetPath = resolve(cwd, ".github/workflows/api-tests.yml");
+    created = writeIfMissing(targetPath, GH_ACTIONS_TEMPLATE, options.force);
+  } else {
+    const targetPath = resolve(cwd, ".gitlab-ci.yml");
+    created = writeIfMissing(targetPath, GITLAB_CI_TEMPLATE, options.force);
+  }
+
+  if (created) {
+    printSuccess("CI workflow created. Commit and push to activate.");
+  }
+
+  return 0;
+}

package/src/cli/commands/collections.ts

@@ -0,0 +1,41 @@
+import { getDb } from "../../db/schema.ts";
+import { listCollections } from "../../db/queries.ts";
+import { formatDuration } from "../../core/reporter/console.ts";
+
+export function collectionsCommand(dbPath?: string): number {
+  getDb(dbPath);
+  const collections = listCollections();
+
+  if (collections.length === 0) {
+    console.log("No collections found.");
+    console.log("Hint: use `zond generate --from <spec>` to create a collection automatically.");
+    return 0;
+  }
+
+  // Print table header
+  const header = [
+    "ID".padEnd(5),
+    "Name".padEnd(30),
+    "Runs".padEnd(6),
+    "Pass Rate".padEnd(11),
+    "Last Run".padEnd(20),
+  ].join(" ");
+
+  console.log(header);
+  console.log("-".repeat(header.length));
+
+  for (const c of collections) {
+    const passRate = c.total_runs > 0 ? `${c.pass_rate}%` : "-";
+    const lastRun = c.last_run_at ?? "-";
+    const row = [
+      String(c.id).padEnd(5),
+      c.name.slice(0, 30).padEnd(30),
+      String(c.total_runs).padEnd(6),
+      passRate.padEnd(11),
+      lastRun.slice(0, 20).padEnd(20),
+    ].join(" ");
+    console.log(row);
+  }
+
+  return 0;
+}

package/src/cli/commands/compare.ts

@@ -0,0 +1,129 @@
+import { getDb } from "../../db/schema.ts";
+import { getRunById, getResultsByRunId } from "../../db/queries.ts";
+import { printError } from "../output.ts";
+
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const BOLD = "\x1b[1m";
+
+function useColor(): boolean {
+  return process.stdout.isTTY ?? false;
+}
+
+export interface CompareOptions {
+  runA: number;
+  runB: number;
+  dbPath?: string;
+}
+
+export async function compareCommand(options: CompareOptions): Promise<number> {
+  const { runA, runB, dbPath } = options;
+
+  try {
+    getDb(dbPath);
+
+    const runARecord = getRunById(runA);
+    const runBRecord = getRunById(runB);
+
+    if (!runARecord) {
+      printError(`Run #${runA} not found`);
+      return 2;
+    }
+    if (!runBRecord) {
+      printError(`Run #${runB} not found`);
+      return 2;
+    }
+
+    const resultsA = getResultsByRunId(runA);
+    const resultsB = getResultsByRunId(runB);
+
+    // Build lookup maps: "suite_name::test_name" → status
+    const mapA = new Map<string, string>();
+    const mapB = new Map<string, string>();
+
+    for (const r of resultsA) {
+      mapA.set(`${r.suite_name}::${r.test_name}`, r.status);
+    }
+    for (const r of resultsB) {
+      mapB.set(`${r.suite_name}::${r.test_name}`, r.status);
+    }
+
+    const regressions: Array<{ suite: string; test: string; before: string; after: string }> = [];
+    const fixes: Array<{ suite: string; test: string; before: string; after: string }> = [];
+    const unchanged: number[] = [];
+    let newTests = 0;
+    let removedTests = 0;
+
+    // Check all keys from B (current run)
+    for (const [key, statusB] of mapB) {
+      const statusA = mapA.get(key);
+      if (statusA === undefined) {
+        newTests++;
+        continue;
+      }
+      const wasPass = statusA === "pass";
+      const isPass = statusB === "pass";
+      const wasFail = statusA === "fail" || statusA === "error";
+      const isFail = statusB === "fail" || statusB === "error";
+
+      const [suite, test] = key.split("::") as [string, string];
+
+      if (wasPass && isFail) {
+        regressions.push({ suite, test, before: statusA, after: statusB });
+      } else if (wasFail && isPass) {
+        fixes.push({ suite, test, before: statusA, after: statusB });
+      } else {
+        unchanged.push(1);
+      }
+    }
+
+    // Count removed tests
+    for (const key of mapA.keys()) {
+      if (!mapB.has(key)) removedTests++;
+    }
+
+    const color = useColor();
+
+    // Header
+    console.log(`\nComparing run #${runA} (${runARecord.started_at.slice(0, 19)}) → run #${runB} (${runBRecord.started_at.slice(0, 19)})\n`);
+
+    // Summary line
+    const parts = [
+      `${color ? BOLD : ""}${regressions.length} regressions${color ? RESET : ""}`,
+      `${fixes.length} fixes`,
+      `${unchanged.length} unchanged`,
+    ];
+    if (newTests > 0) parts.push(`${newTests} new`);
+    if (removedTests > 0) parts.push(`${removedTests} removed`);
+    console.log(parts.join("  |  ") + "\n");
+
+    // Regressions
+    if (regressions.length > 0) {
+      console.log(`${color ? RED + BOLD : ""}Regressions (pass → fail):${color ? RESET : ""}`);
+      for (const r of regressions) {
+        console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} [${r.suite}] ${r.test}  (${r.before} → ${r.after})`);
+      }
+      console.log("");
+    }
+
+    // Fixes
+    if (fixes.length > 0) {
+      console.log(`${color ? GREEN : ""}Fixes (fail → pass):${color ? RESET : ""}`);
+      for (const f of fixes) {
+        console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} [${f.suite}] ${f.test}  (${f.before} → ${f.after})`);
+      }
+      console.log("");
+    }
+
+    if (regressions.length === 0 && fixes.length === 0) {
+      console.log(`${color ? GREEN : ""}No regressions detected.${color ? RESET : ""}`);
+    }
+
+    return regressions.length > 0 ? 1 : 0;
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+}

package/src/cli/commands/coverage.ts

@@ -0,0 +1,156 @@
+import { readOpenApiSpec, extractEndpoints, scanCoveredEndpoints, filterUncoveredEndpoints, normalizePath, specPathToRegex, analyzeEndpoints } from "../../core/generator/index.ts";
+import { getDb } from "../../db/schema.ts";
+import { getResultsByRunId, getRunById } from "../../db/queries.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface CoverageOptions {
+  spec: string;
+  tests: string;
+  failOnCoverage?: number;
+  runId?: number;
+}
+
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+
+function useColor(): boolean {
+  return process.stdout.isTTY ?? false;
+}
+
+function extractPathFromUrl(url: string): string | null {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.startsWith("/") ? url : null;
+  }
+}
+
+export async function coverageCommand(options: CoverageOptions): Promise<number> {
+  const { spec, tests } = options;
+
+  try {
+    const doc = await readOpenApiSpec(spec);
+    const allEndpoints = extractEndpoints(doc);
+
+    if (allEndpoints.length === 0) {
+      printError("No endpoints found in the OpenAPI spec");
+      return 1;
+    }
+
+    const covered = await scanCoveredEndpoints(tests);
+    const uncovered = filterUncoveredEndpoints(allEndpoints, covered);
+    const coveredCount = allEndpoints.length - uncovered.length;
+    const percentage = Math.round((coveredCount / allEndpoints.length) * 100);
+
+    const color = useColor();
+
+    // Enriched mode with run results
+    if (options.runId != null) {
+      getDb();
+      const run = getRunById(options.runId);
+      if (!run) {
+        printError(`Run #${options.runId} not found`);
+        return 2;
+      }
+
+      const results = getResultsByRunId(options.runId);
+
+      // Build endpoint → status map
+      const endpointStatus = new Map<string, "passing" | "api_error" | "test_failed">();
+      for (const r of results) {
+        if (!r.request_url || !r.request_method) continue;
+        const urlPath = extractPathFromUrl(r.request_url);
+        if (!urlPath) continue;
+        const normalizedUrl = normalizePath(urlPath);
+
+        for (const ep of allEndpoints) {
+          const regex = specPathToRegex(ep.path);
+          if (r.request_method === ep.method && regex.test(normalizedUrl)) {
+            const key = `${ep.method} ${ep.path}`;
+            const existing = endpointStatus.get(key);
+
+            if (r.response_status !== null && r.response_status >= 500) {
+              endpointStatus.set(key, "api_error");
+            } else if (r.status === "fail" || r.status === "error") {
+              if (existing !== "api_error") {
+                endpointStatus.set(key, "test_failed");
+              }
+            } else if (!existing) {
+              endpointStatus.set(key, "passing");
+            }
+            break;
+          }
+        }
+      }
+
+      let passing = 0;
+      let apiError = 0;
+      let testFailed = 0;
+      for (const status of endpointStatus.values()) {
+        if (status === "passing") passing++;
+        else if (status === "api_error") apiError++;
+        else if (status === "test_failed") testFailed++;
+      }
+
+      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%) — Run #${options.runId}`);
+      console.log("");
+
+      if (passing > 0) {
+        console.log(`  ${color ? GREEN : ""}✅ ${passing} covered and passing${color ? RESET : ""}`);
+      }
+      if (apiError > 0) {
+        console.log(`  ${color ? YELLOW : ""}⚠️  ${apiError} covered but returning 5xx (possibly broken API)${color ? RESET : ""}`);
+      }
+      if (testFailed > 0) {
+        console.log(`  ${color ? RED : ""}❌ ${testFailed} covered, test assertions failed${color ? RESET : ""}`);
+      }
+      if (uncovered.length > 0) {
+        console.log(`  ${color ? DIM : ""}⬜ ${uncovered.length} not covered${color ? RESET : ""}`);
+      }
+    } else {
+      // Standard mode
+      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%)`);
+      console.log("");
+
+      // Covered endpoints
+      if (coveredCount > 0) {
+        console.log(`${color ? GREEN : ""}Covered:${color ? RESET : ""}`);
+        for (const ep of allEndpoints) {
+          if (!uncovered.includes(ep)) {
+            console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+          }
+        }
+        console.log("");
+      }
+
+      // Uncovered endpoints
+      if (uncovered.length > 0) {
+        console.log(`${color ? RED : ""}Uncovered:${color ? RESET : ""}`);
+        for (const ep of uncovered) {
+          console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+        }
+      }
+    }
+
+    // Static warnings (always shown)
+    const warnings = analyzeEndpoints(allEndpoints);
+    if (warnings.length > 0) {
+      console.log("");
+      console.log(`${color ? YELLOW : ""}Spec warnings:${color ? RESET : ""}`);
+      for (const w of warnings) {
+        console.log(`  ${color ? YELLOW : ""}⚠${color ? RESET : ""} ${w.method.padEnd(7)} ${w.path}: ${w.warnings.join(", ")}`);
+      }
+    }
+
+    if (options.failOnCoverage !== undefined) {
+      return percentage < options.failOnCoverage ? 1 : 0;
+    }
+    return uncovered.length > 0 ? 1 : 0;
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+}

package/src/cli/commands/doctor.ts

@@ -0,0 +1,127 @@
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { getDb, closeDb } from "../../db/schema.ts";
+
+export interface DoctorOptions {
+  dbPath?: string;
+}
+
+interface Check {
+  label: string;
+  ok: boolean;
+  detail: string;
+}
+
+export async function doctorCommand(options: DoctorOptions): Promise<number> {
+  const checks: Check[] = [];
+
+  // 1. Database
+  checks.push(checkDatabase(options.dbPath));
+
+  // 2. Test files
+  checks.push(checkTestFiles());
+
+  // 3. OpenAPI spec
+  checks.push(checkOpenApiSpec());
+
+  // 4. Environment files
+  checks.push(checkEnvFiles());
+
+  // 5. Ollama
+  checks.push(await checkOllama());
+
+  // Print results
+  console.log("\nzond doctor\n");
+
+  let hasFailure = false;
+  for (const check of checks) {
+    const icon = check.ok ? "\u2713" : "\u2717";
+    console.log(`  ${icon} ${check.label}: ${check.detail}`);
+    if (!check.ok) hasFailure = true;
+  }
+
+  console.log("");
+  if (hasFailure) {
+    console.log("Some checks failed. See details above.");
+  } else {
+    console.log("All checks passed.");
+  }
+
+  return hasFailure ? 1 : 0;
+}
+
+function checkDatabase(dbPath?: string): Check {
+  const path = dbPath ? resolve(dbPath) : resolve(process.cwd(), "zond.db");
+  try {
+    const db = getDb(path);
+    const runs = (db.query("SELECT COUNT(*) as cnt FROM runs").get() as { cnt: number }).cnt;
+    const envs = (db.query("SELECT COUNT(*) as cnt FROM environments").get() as { cnt: number }).cnt;
+    closeDb();
+    return { label: "Database", ok: true, detail: `${path} (${runs} runs, ${envs} environments)` };
+  } catch (err) {
+    return { label: "Database", ok: false, detail: `Cannot open ${path}: ${(err as Error).message}` };
+  }
+}
+
+function checkTestFiles(): Check {
+  const dirs = [".", "tests", "test"];
+  const found: string[] = [];
+
+  for (const dir of dirs) {
+    const full = resolve(process.cwd(), dir);
+    if (!existsSync(full)) continue;
+    try {
+      const glob = new Bun.Glob("**/*.yaml");
+      for (const file of glob.scanSync({ cwd: full, absolute: false })) {
+        if (!file.startsWith(".env.")) {
+          found.push(`${dir}/${file}`);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (found.length > 0) {
+    return { label: "Test files", ok: true, detail: `${found.length} YAML file(s) found` };
+  }
+  return { label: "Test files", ok: false, detail: "No YAML test files found in cwd or tests/" };
+}
+
+function checkOpenApiSpec(): Check {
+  const candidates = ["openapi.yaml", "openapi.json", "openapi.yml", "swagger.yaml", "swagger.json"];
+  for (const name of candidates) {
+    const full = resolve(process.cwd(), name);
+    if (existsSync(full)) {
+      return { label: "OpenAPI spec", ok: true, detail: name };
+    }
+  }
+  return { label: "OpenAPI spec", ok: false, detail: "No openapi.yaml/json found (optional)" };
+}
+
+function checkEnvFiles(): Check {
+  const found: string[] = [];
+  try {
+    const glob = new Bun.Glob(".env.*.yaml");
+    for (const file of glob.scanSync({ cwd: process.cwd(), absolute: false })) {
+      found.push(file);
+    }
+  } catch { /* ignore */ }
+
+  if (found.length > 0) {
+    return { label: "Environment files", ok: true, detail: found.join(", ") };
+  }
+  return { label: "Environment files", ok: false, detail: "No .env.*.yaml files found (optional)" };
+}
+
+async function checkOllama(): Promise<Check> {
+  try {
+    const res = await fetch("http://localhost:11434/api/tags", { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const data = await res.json() as { models?: { name: string }[] };
+      const count = data.models?.length ?? 0;
+      return { label: "Ollama", ok: true, detail: `Running (${count} model(s) available)` };
+    }
+    return { label: "Ollama", ok: false, detail: `Responded with status ${res.status}` };
+  } catch {
+    return { label: "Ollama", ok: false, detail: "Not reachable at localhost:11434 (optional, needed for chat)" };
+  }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,84 @@
+import { resolve, dirname } from "path";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { printSuccess } from "../output.ts";
+
+export interface InitCommandOptions {
+  force: boolean;
+}
+
+const EXAMPLE_TEST = `name: Example Smoke Test
+base_url: "{{base_url}}"
+
+tests:
+  - name: "List posts"
+    GET: /posts
+    expect:
+      status: 200
+      body:
+        id: { type: integer }
+
+  - name: "Get single post"
+    GET: /posts/1
+    expect:
+      status: 200
+      body:
+        id: { equals: 1 }
+        title: { type: string }
+`;
+
+const ENV_DEV = `base_url: https://jsonplaceholder.typicode.com
+`;
+
+const MCP_CONFIG = `{
+  "mcpServers": {
+    "zond": {
+      "command": "zond",
+      "args": ["mcp"]
+    }
+  }
+}
+`;
+
+function writeIfMissing(filePath: string, content: string, force: boolean): boolean {
+  if (!force && existsSync(filePath)) {
+    console.log(`  Skipped ${filePath} (already exists)`);
+    return false;
+  }
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, content, "utf-8");
+  console.log(`  Created ${filePath}`);
+  return true;
+}
+
+function isClaudeCodeAvailable(): boolean {
+  try {
+    const result = Bun.spawnSync(["claude", "--version"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function initCommand(options: InitCommandOptions): Promise<number> {
+  const cwd = process.cwd();
+
+  console.log("Initializing zond project...\n");
+
+  writeIfMissing(resolve(cwd, "tests/example.yaml"), EXAMPLE_TEST, options.force);
+  writeIfMissing(resolve(cwd, ".env.dev.yaml"), ENV_DEV, options.force);
+
+  // Create .mcp.json if Claude Code is detected
+  if (isClaudeCodeAvailable()) {
+    writeIfMissing(resolve(cwd, ".mcp.json"), MCP_CONFIG, options.force);
+    printSuccess("Claude Code detected — .mcp.json created");
+  }
+
+  console.log("\nReady! Run: zond run tests/");
+  return 0;
+}