@kirrosh/zond 0.7.0

package/src/db/schema.ts

@@ -0,0 +1,159 @@
+import { Database } from "bun:sqlite";
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+let _db: Database | null = null;
+let _dbPath: string | null = null;
+
+export function getDb(dbPath?: string): Database {
+  const path = dbPath ? resolve(dbPath) : (_dbPath ?? resolve(process.cwd(), "zond.db"));
+
+  // If cached connection exists, verify the file still exists
+  if (_db && _dbPath === path && existsSync(path)) return _db;
+
+  // Close stale connection if any
+  if (_db) {
+    try { _db.close(); } catch {}
+    _db = null;
+    _dbPath = null;
+  }
+  const db = new Database(path, { create: true });
+
+  // Performance and integrity settings
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+
+  runMigrations(db);
+
+  _db = db;
+  _dbPath = path;
+  return db;
+}
+
+export function closeDb(): void {
+  if (_db) {
+    try { _db.close(); } catch {}
+    _db = null;
+    _dbPath = null;
+  }
+}
+
+export function resetDb(): void {
+  if (_db) { try { _db.close(); } catch {} }
+  _db = null;
+  _dbPath = null;
+}
+
+// ──────────────────────────────────────────────
+// Schema
+// ──────────────────────────────────────────────
+
+const SCHEMA_VERSION = 1;
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS runs (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    started_at    TEXT NOT NULL,
+    finished_at   TEXT,
+    total         INTEGER NOT NULL DEFAULT 0,
+    passed        INTEGER NOT NULL DEFAULT 0,
+    failed        INTEGER NOT NULL DEFAULT 0,
+    skipped       INTEGER NOT NULL DEFAULT 0,
+    trigger       TEXT DEFAULT 'manual',
+    commit_sha    TEXT,
+    branch        TEXT,
+    environment   TEXT,
+    duration_ms   INTEGER,
+    collection_id INTEGER REFERENCES collections(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS results (
+    id               INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id           INTEGER NOT NULL REFERENCES runs(id),
+    suite_name       TEXT NOT NULL,
+    test_name        TEXT NOT NULL,
+    status           TEXT NOT NULL,
+    duration_ms      INTEGER NOT NULL,
+    request_method   TEXT,
+    request_url      TEXT,
+    request_body     TEXT,
+    response_status  INTEGER,
+    response_body    TEXT,
+    error_message    TEXT,
+    assertions       TEXT,
+    captures         TEXT,
+    response_headers TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS collections (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    name         TEXT NOT NULL,
+    test_path    TEXT NOT NULL,
+    openapi_spec TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    base_dir     TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS ai_generations (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    collection_id     INTEGER REFERENCES collections(id),
+    prompt            TEXT NOT NULL,
+    model             TEXT NOT NULL,
+    provider          TEXT NOT NULL,
+    generated_yaml    TEXT,
+    output_path       TEXT,
+    status            TEXT NOT NULL DEFAULT 'pending',
+    error_message     TEXT,
+    prompt_tokens     INTEGER,
+    completion_tokens INTEGER,
+    duration_ms       INTEGER,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS chat_sessions (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    title       TEXT,
+    provider    TEXT NOT NULL,
+    model       TEXT NOT NULL,
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    last_active TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS chat_messages (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id    INTEGER NOT NULL REFERENCES chat_sessions(id),
+    role          TEXT NOT NULL,
+    content       TEXT NOT NULL,
+    tool_name     TEXT,
+    tool_args     TEXT,
+    tool_result   TEXT,
+    input_tokens  INTEGER,
+    output_tokens INTEGER,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS settings (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_runs_started      ON runs(started_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_runs_collection    ON runs(collection_id);
+  CREATE INDEX IF NOT EXISTS idx_results_run        ON results(run_id);
+  CREATE INDEX IF NOT EXISTS idx_results_status     ON results(status);
+  CREATE INDEX IF NOT EXISTS idx_results_name       ON results(suite_name, test_name);
+  CREATE INDEX IF NOT EXISTS idx_collections_name   ON collections(name);
+  CREATE INDEX IF NOT EXISTS idx_ai_gen_collection  ON ai_generations(collection_id);
+  CREATE INDEX IF NOT EXISTS idx_chat_messages_session ON chat_messages(session_id);
+  CREATE INDEX IF NOT EXISTS idx_chat_sessions_active  ON chat_sessions(last_active DESC);
+`;
+
+function runMigrations(db: Database): void {
+  const ver = (db.query("PRAGMA user_version").get() as { user_version: number }).user_version;
+  if (ver >= SCHEMA_VERSION) return;
+
+  db.transaction(() => {
+    db.exec(SCHEMA);
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+  })();
+}

package/src/mcp/descriptions.ts

@@ -0,0 +1,88 @@
+/**
+ * Single source of truth for all MCP tool descriptions.
+ * Update descriptions here — they are imported by each tool file.
+ */
+export const TOOL_DESCRIPTIONS = {
+  set_work_dir:
+    "Set the working directory for this MCP session. " +
+    "Call this FIRST before any other tool when using a shared MCP server (npx). " +
+    "Determines where zond.db and relative test paths resolve to. " +
+    "Pass the absolute path to your project root (same as workspace root in your editor).",
+
+  setup_api:
+    "Register a new API for testing. Creates directory structure, reads OpenAPI spec, " +
+    "sets up environment variables, and creates a collection in the database. " +
+    "Use this before generating tests for a new API.",
+
+  explore_api:
+    "Explore an OpenAPI spec — list endpoints, servers, and security schemes. " +
+    "Use with includeSchemas=true when generating tests to get full request/response body schemas.",
+
+  describe_endpoint:
+    "Full details for one endpoint: params grouped by type, request body schema, " +
+    "all response schemas + response headers, security, deprecated flag. " +
+    "Use when a test fails and you need complete endpoint spec without reading the whole file.",
+
+  generate_tests_guide:
+    "Get a comprehensive guide for generating API test suites. " +
+    "Returns the full API specification (with request/response schemas) and a step-by-step algorithm " +
+    "for creating YAML test files. Use this BEFORE generating tests — it gives you " +
+    "everything you need to write high-quality test suites. " +
+    "After generating, use save_test_suite to save, run_tests to execute, " +
+    "manage_server(action: 'start') to view results in the Web UI, " +
+    "and query_db(action: 'diagnose_failure') to debug failures.",
+
+  generate_missing_tests:
+    "Analyze test coverage and generate a test guide for only the uncovered endpoints. " +
+    "Combines coverage_analysis + generate_tests_guide — returns a focused guide for missing tests. " +
+    "Use this for incremental test generation to avoid duplicating existing tests. " +
+    "After saving and running new tests, use manage_server(action: 'start') to view results in the Web UI.",
+
+  save_test_suite:
+    "Save a YAML test suite file with validation. Parses and validates the YAML content " +
+    "before writing. Returns structured errors if validation fails so you can fix and retry. " +
+    "Use after generating test content with generate_tests_guide.",
+
+  save_test_suites:
+    "Save multiple YAML test suite files in a single call. Each file is validated before writing. " +
+    "Returns per-file results. Use when you have generated multiple suites at once.",
+
+  validate_tests:
+    "Validate YAML test files without running them. Returns parsed suite info or validation errors.",
+
+  run_tests:
+    "Execute API tests from a YAML file or directory and return results summary with failures. " +
+    "Use after saving test suites with save_test_suite. Check query_db(action: 'diagnose_failure') for detailed failure analysis.",
+
+  query_db:
+    "Query the zond database. Actions: list_collections (all APIs with run stats), " +
+    "list_runs (recent test runs), get_run_results (full detail for a run), " +
+    "diagnose_failure (only failed/errored steps for a run — each failure includes failure_type: api_error/assertion_failed/network_error, " +
+    "and summary includes api_errors/assertion_failures/network_errors counts), " +
+    "compare_runs (regressions and fixes between two runs).",
+
+  coverage_analysis:
+    "Compare an OpenAPI spec against existing test files to find untested endpoints. " +
+    "Use to identify gaps and prioritize which endpoints to generate tests for next. " +
+    "Pass runId to get enriched pass/fail/5xx breakdown per endpoint. " +
+    "Always includes static spec warnings (deprecated, missing response schemas, required params without examples).",
+
+  send_request:
+    "Send an ad-hoc HTTP request. Supports variable interpolation from environments (e.g. {{base_url}}).",
+
+  manage_server:
+    "Start, stop, restart, or check status of the zond WebUI server. " +
+    "Useful for viewing test results in a browser without leaving the MCP session.",
+
+  generate_and_save:
+    "Read an OpenAPI spec, auto-chunk by tags if large (>30 endpoints), " +
+    "and return a focused test generation guide. For large APIs returns a chunking plan — " +
+    "call again with tag parameter for each chunk. Use testsDir param to only generate for uncovered endpoints. " +
+    "After generating YAML, use save_test_suites to save files, then run_tests to verify.",
+
+  ci_init:
+    "Generate a CI/CD workflow file for running API tests automatically on push, PR, and schedule. " +
+    "Supports GitHub Actions and GitLab CI. Auto-detects platform from project structure " +
+    "(.github/ → GitHub, .gitlab-ci.yml → GitLab). " +
+    "Use after tests are generated and passing. After generating the workflow, help the user commit and push to activate CI.",
+} as const;

package/src/mcp/server.ts

@@ -0,0 +1,52 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerRunTestsTool } from "./tools/run-tests.ts";
+import { registerValidateTestsTool } from "./tools/validate-tests.ts";
+import { registerQueryDbTool } from "./tools/query-db.ts";
+import { registerSendRequestTool } from "./tools/send-request.ts";
+import { registerExploreApiTool } from "./tools/explore-api.ts";
+import { registerCoverageAnalysisTool } from "./tools/coverage-analysis.ts";
+import { registerSaveTestSuiteTool, registerSaveTestSuitesTool } from "./tools/save-test-suite.ts";
+import { registerGenerateTestsGuideTool } from "./tools/generate-tests-guide.ts";
+import { registerSetupApiTool } from "./tools/setup-api.ts";
+import { registerGenerateMissingTestsTool } from "./tools/generate-missing-tests.ts";
+import { registerManageServerTool } from "./tools/manage-server.ts";
+import { registerCiInitTool } from "./tools/ci-init.ts";
+import { registerSetWorkDirTool } from "./tools/set-work-dir.ts";
+import { registerDescribeEndpointTool } from "./tools/describe-endpoint.ts";
+import { registerGenerateAndSaveTool } from "./tools/generate-and-save.ts";
+
+export interface McpServerOptions {
+  dbPath?: string;
+}
+
+export async function startMcpServer(options: McpServerOptions = {}): Promise<void> {
+  const { dbPath } = options;
+
+  const server = new McpServer({
+    name: "zond",
+    version: "0.4.0",
+  });
+
+  // Register all tools
+  registerRunTestsTool(server, dbPath);
+  registerValidateTestsTool(server);
+  registerQueryDbTool(server, dbPath);
+  registerSendRequestTool(server, dbPath);
+  registerExploreApiTool(server);
+  registerCoverageAnalysisTool(server, dbPath);
+  registerSaveTestSuiteTool(server, dbPath);
+  registerSaveTestSuitesTool(server, dbPath);
+  registerGenerateTestsGuideTool(server);
+  registerSetupApiTool(server, dbPath);
+  registerGenerateMissingTestsTool(server);
+  registerManageServerTool(server, dbPath);
+  registerCiInitTool(server);
+  registerSetWorkDirTool(server);
+  registerDescribeEndpointTool(server);
+  registerGenerateAndSaveTool(server);
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools/ci-init.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ciInitCommand } from "../../cli/commands/ci-init.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+export function registerCiInitTool(server: McpServer) {
+  server.registerTool("ci_init", {
+    description: TOOL_DESCRIPTIONS.ci_init,
+    inputSchema: {
+      platform: z.optional(z.enum(["github", "gitlab"]))
+        .describe("CI platform. If omitted, auto-detects from project structure (defaults to GitHub)"),
+      force: z.optional(z.boolean())
+        .describe("Overwrite existing CI config (default: false)"),
+      dir: z.optional(z.string())
+        .describe("Project root directory where CI config will be created (default: current working directory)"),
+    },
+  }, async ({ platform, force, dir }) => {
+    // Capture stdout to return as result
+    const logs: string[] = [];
+    const origWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      logs.push(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      const code = await ciInitCommand({
+        platform,
+        force: force ?? false,
+        dir,
+      });
+
+      process.stdout.write = origWrite;
+
+      const output = logs.join("").trim();
+      if (code !== 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: output || "ci init failed", exitCode: code }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ message: output, exitCode: 0 }, null, 2) }],
+      };
+    } catch (err) {
+      process.stdout.write = origWrite;
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/coverage-analysis.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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 { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+function extractPathFromUrl(url: string): string | null {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    // If not a full URL, treat as path directly
+    return url.startsWith("/") ? url : null;
+  }
+}
+
+export function registerCoverageAnalysisTool(server: McpServer, dbPath?: string) {
+  server.registerTool("coverage_analysis", {
+    description: TOOL_DESCRIPTIONS.coverage_analysis,
+    inputSchema: {
+      specPath: z.string().describe("Path to OpenAPI spec file (JSON or YAML)"),
+      testsDir: z.string().describe("Path to directory with test YAML files"),
+      failThreshold: z.optional(z.number().min(0).max(100)).describe("Return isError when coverage % is below this threshold (0–100)"),
+      runId: z.optional(z.number().int()).describe("Run ID to cross-reference test results for pass/fail/5xx breakdown"),
+    },
+  }, async ({ specPath, testsDir, failThreshold, runId }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      const allEndpoints = extractEndpoints(doc);
+
+      if (allEndpoints.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "No endpoints found in the spec" }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      const covered = await scanCoveredEndpoints(testsDir);
+      const uncovered = filterUncoveredEndpoints(allEndpoints, covered);
+      const coveredCount = allEndpoints.length - uncovered.length;
+      const percentage = Math.round((coveredCount / allEndpoints.length) * 100);
+
+      // Static warnings
+      const warnings = analyzeEndpoints(allEndpoints);
+
+      const result: Record<string, unknown> = {
+        totalEndpoints: allEndpoints.length,
+        covered: coveredCount,
+        uncovered: uncovered.length,
+        percentage,
+        uncoveredEndpoints: uncovered.map(ep => ({
+          method: ep.method,
+          path: ep.path,
+          summary: ep.summary,
+          tags: ep.tags,
+        })),
+        coveredEndpoints: covered.map(ep => ({
+          method: ep.method,
+          path: ep.path,
+          file: ep.file,
+        })),
+      };
+
+      if (warnings.length > 0) {
+        result.warnings = warnings;
+      }
+
+      // Enriched breakdown when runId is provided
+      if (runId != null) {
+        getDb(dbPath);
+        const run = getRunById(runId);
+        if (!run) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ error: `Run ${runId} not found` }, null, 2) }],
+            isError: true,
+          };
+        }
+
+        const results = getResultsByRunId(runId);
+
+        // Build a map: spec endpoint → status classification
+        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);
+
+          // Find matching spec endpoint
+          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);
+
+              // Worst status wins: api_error > test_failed > passing
+              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++;
+        }
+
+        result.enriched = {
+          passing,
+          api_error: apiError,
+          test_failed: testFailed,
+          not_covered: uncovered.length,
+        };
+      }
+
+      const belowThreshold = failThreshold !== undefined && percentage < failThreshold;
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        ...(belowThreshold ? { isError: true } : {}),
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}