@kirrosh/zond 0.12.4 → 0.12.7

package/README.md

@@ -1,128 +1,83 @@
 # zond
 
-Point your AI agent at an OpenAPI spec. Get working tests in minutes. No config, no cloud, no Postman.
+AI-powered API testing for Claude Code, Cursor, and CI/CD.
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
+Say "test my API" — get working tests, coverage dashboard, and CI config in minutes.
+
+<!-- TODO: add demo GIF (15 sec: plugin install → "cover openapi.json with tests" → 42/47 endpoints covered → dashboard) -->
 
-## Claude Code Plugin
+Zond reads your OpenAPI spec and gives your AI agent everything it needs to test your API: structured tools, safety guardrails, coverage tracking, and run history. You don't need to learn anything new — just describe what you want and the agent handles the rest.
 
-Install in Claude Code:
+## Quick Start
 
 ```
 /plugin marketplace add kirrosh/zond
 /plugin install zond@zond-marketplace
 ```
 
-This gives you:
-- **17 MCP tools** for API testing (test generation, execution, diagnostics, coverage)
-- **Skills** for test generation, debugging failures, and CI setup
-- **Slash commands**: `/zond:api-test`, `/zond:api-coverage`
-
-After installation, just say: _"Safely cover the API from openapi.json with tests"_ — the agent handles everything.
-
-## Install
-
-```bash
-# Option 1: via npx (recommended — works everywhere with Node.js)
-npx -y @kirrosh/zond --version
-
-# Option 2: Binary (no Node.js required)
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-
-# Windows
-iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex
-```
+Then say: _"Safely cover the API from openapi.json with tests"_
 
-[All releases](https://github.com/kirrosh/zond/releases) (Linux x64, macOS ARM, Windows x64)
-
-## MCP Setup (Cursor / Claude Code / Windsurf)
-
-Click the badge above, or add manually:
-
-```json
-{
-  "mcpServers": {
-    "zond": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@kirrosh/zond@latest",
-        "mcp",
-        "--dir",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
+You get skills, slash commands, and 12 MCP tools in one package.
 
-> `@latest` ensures npx always pulls the newest version on each restart — no manual update needed.
+<details>
+<summary>Other installation methods (MCP, CLI, binary)</summary>
 
-**Where to put this:**
+### MCP Server (Cursor, Windsurf, other editors)
 
-| Editor      | Config file                                           |
-| ----------- | ----------------------------------------------------- |
-| Cursor      | Settings > MCP, or `.cursor/mcp.json` in project root |
-| Claude Code | `.mcp.json` in project root                           |
-| Windsurf    | `.windsurfrules/mcp.json` or settings                 |
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
 
-## Main Flow (5 steps)
+Or add manually — see [MCP setup guide](docs/mcp-guide.md) for Cursor, Claude Code, and Windsurf config.
 
-Once MCP is connected, ask your AI agent to cover your API with tests:
+### CLI / Binary
 
-**1. Register your API**
+```bash
+npx -y @kirrosh/zond --version
 
-```
-setup_api(name: "myapi", specPath: "openapi.json")
+# Standalone binary (no Node.js required)
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # macOS/Linux
+iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
 ```
 
-**2. Generate a test guide** (agent reads OpenAPI + gets instructions)
-
-```
-generate_and_save(specPath: "openapi.json")
-```
+See [ZOND.md](ZOND.md) for full CLI reference.
 
-For large APIs (>30 endpoints), auto-chunks by tags and returns a plan. Call with `tag` for each chunk.
+</details>
 
-**3. Save test suites** (agent writes YAML based on the guide)
+## What Happens
 
-```
-save_test_suite(filePath: "apis/myapi/tests/smoke.yaml", content: "...")
-```
+1. **Point** — you give the agent an OpenAPI spec
+2. **Generate** — zond reads the spec, produces YAML test suites (smoke + CRUD)
+3. **Run** — tests execute, failures are diagnosed, coverage is tracked
 
-**4. Run tests**
+The agent does all three steps autonomously. It asks you only when it needs an auth token or permission to run write operations.
 
-```
-run_tests(testPath: "apis/myapi/tests/", safe: true)
-```
+## Why Not Just Ask Claude to Write pytest?
 
-**5. Diagnose failures**
+Claude Code can write pytest from scratch — but it takes 30-60 minutes per flow, has no safety guardrails, no coverage tracking, and no run history. Zond gives the agent structured tools to do it in 5 minutes with full visibility.
 
-```
-query_db(action: "diagnose_failure", runId: 42)
-```
+## Key Capabilities
 
-Or just say: _"Safely cover the API from openapi.json with tests"_ — the agent will do all 5 steps.
+| | |
+|---|---|
+| **Safe by Default** | `--safe` runs only GET requests. `--dry-run` previews without sending. The agent never touches production data without your explicit approval. |
+| **Spec-Grounded** | Tests are derived from your OpenAPI schema, not invented from scratch. The spec is the source of truth. |
+| **Full Visibility** | Every run is stored in SQLite. Compare runs, track regressions, see exactly what the server returned. |
+| **Coverage Tracking** | See which endpoints are tested, which aren't, and what broke since last run. |
+| **CI-Ready** | One command generates GitHub Actions or GitLab CI workflow. Tests in YAML, in git, with code review. |
 
-## CLI
+## Try It
 
 ```
-zond run <path>           Run tests (--env, --safe, --tag, --dry-run, --env-var, --report)
-zond add-api <name>       Register API (--spec <openapi>)
-zond coverage             API test coverage (--spec, --tests, --fail-on-coverage)
-zond compare <runA> <runB> Compare two test runs
-zond serve                Web dashboard with health strip + endpoints/suites/runs tabs (--port 8080)
-zond mcp                  Start MCP server
-zond chat                 AI chat agent (--provider ollama|openai|anthropic)
-zond doctor               Diagnostics
+"Cover openapi.json with tests"
+"Run only smoke tests against staging"
+"What broke since last run?"
+"Set up CI for API tests"
 ```
 
 ## Documentation
 
-- [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart guide (RU)
 - [ZOND.md](ZOND.md) — full CLI and MCP tools reference
 - [docs/mcp-guide.md](docs/mcp-guide.md) — MCP agent workflow guide
+- [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart (RU)
 - [docs/ci.md](docs/ci.md) — CI/CD integration
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.12.4",
+  "version": "0.12.7",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",

package/src/cli/commands/add-api.ts

@@ -7,10 +7,11 @@ export interface AddApiOptions {
   dir?: string;
   envPairs?: string[];
   dbPath?: string;
+  insecure?: boolean;
 }
 
 export async function addApiCommand(options: AddApiOptions): Promise<number> {
-  const { name, spec, envPairs, dbPath, dir } = options;
+  const { name, spec, envPairs, dbPath, dir, insecure } = options;
 
   // Parse --env key=value pairs into a record
   const envVars: Record<string, string> = {};
@@ -31,6 +32,7 @@ export async function addApiCommand(options: AddApiOptions): Promise<number> {
       dir,
       envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
       dbPath,
+      insecure,
     });
 
     printSuccess(`API '${name}' created (id=${result.collectionId})`);

package/src/cli/index.ts

@@ -96,6 +96,7 @@ 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)
@@ -210,6 +211,7 @@ async function main(): Promise<number> {
         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,
       });
     }
 

package/src/core/generator/guide-builder.ts

@@ -106,15 +106,18 @@ Inline the value directly — there is NO \`params\` field:
 - Array element: \`items.0.name: { exists: true }\`
 - YAML keys must be unique — do NOT repeat \`_body\` twice
 
-### Request body (JSON)
+### Request body — IMPORTANT
+Use \`json:\` for JSON request bodies. Do NOT use \`body:\` — it is not a valid key.
 \`\`\`yaml
   - name: Create resource
     POST: /resources
-    json: { name: "test", email: "a@b.com" }
+    json: { name: "test", email: "a@b.com" }   # correct — use json:
+    # body: { ... }                              # WRONG — body: is not supported
     expect:
       status: 201
       id: { exists: true }
 \`\`\`
+For form-encoded: use \`form:\` instead of \`json:\`.
 
 ### Built-in generators
 \`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
@@ -140,6 +143,12 @@ Inline the value directly — there is NO \`params\` field:
 Use spec paths with \`{param}\` placeholders in the path for coverage to match:
 - Spec says \`GET /products/{id}\` → write \`GET: /products/1\` (hardcode the value)
 - Coverage scanner matches test paths against spec paths automatically
+
+### CRITICAL: Never mask server errors
+- If an endpoint returns 500 — do NOT change expect to \`status: 500\`. Keep \`status: 200\` and let the test fail.
+- A failing test = signal about an API bug. The goal is NOT "all tests green" but "tests reflect expected behavior".
+- Fixing tests means fixing test logic (wrong path, missing auth, bad body), NOT accepting error responses as expected.
+- Legitimate error expectations: 404 for missing resources, 400/422 for invalid input, 401 for no auth — these are negative tests by design.
 `;
 
 export interface GuideOptions {

package/src/core/generator/openapi-reader.ts

@@ -4,10 +4,12 @@ import type { EndpointInfo, ResponseInfo, SecuritySchemeInfo } from "./types.ts"
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
 
-export async function readOpenApiSpec(specPath: string): Promise<OpenAPIV3.Document> {
+export async function readOpenApiSpec(specPath: string, options?: { insecure?: boolean }): Promise<OpenAPIV3.Document> {
   // For HTTP URLs, fetch the spec first then dereference the parsed object
   if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
-    const resp = await fetch(specPath);
+    const resp = await fetch(specPath, {
+      ...(options?.insecure ? { tls: { rejectUnauthorized: false } } : {}),
+    });
     if (!resp.ok) throw new Error(`Failed to fetch spec: ${resp.status} ${resp.statusText}`);
     const spec = await resp.json();
     const api = await dereference(spec as string);

package/src/core/generator/suite-generator.ts

@@ -62,10 +62,19 @@ function getAuthHeaders(
     const scheme = schemes.find(s => s.name === secName);
     if (!scheme) continue;
 
-    if (scheme.type === "http" && scheme.scheme === "bearer") {
-      return { Authorization: "Bearer {{auth_token}}" };
+    if (scheme.type === "http") {
+      if (scheme.scheme === "bearer" || !scheme.scheme) {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
+      if (scheme.scheme === "basic") {
+        return { Authorization: "Basic {{auth_token}}" };
+      }
     }
     if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
+      // When apiKey scheme uses Authorization header, it's typically a Bearer token
+      if (scheme.apiKeyName === "Authorization") {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
       return { [scheme.apiKeyName]: "{{api_key}}" };
     }
   }

package/src/core/runner/http-client.ts

@@ -53,6 +53,16 @@ export async function executeRequest(
           // Body is not valid JSON despite content-type
         }
       }
+      // Fallback: for non-JSON responses, store trimmed body as string
+      // so that captures like `_body` work for text/plain, text/html, etc.
+      if (body_parsed === undefined && bodyText.length > 0) {
+        // Try JSON parse as fallback (some APIs omit content-type)
+        try {
+          body_parsed = JSON.parse(bodyText);
+        } catch {
+          body_parsed = bodyText.trim();
+        }
+      }
 
       const headers: Record<string, string> = {};
       response.headers.forEach((v, k) => {

package/src/core/setup-api.ts

@@ -20,6 +20,7 @@ export interface SetupApiOptions {
   envVars?: Record<string, string>;
   dbPath?: string;
   force?: boolean;
+  insecure?: boolean;
 }
 
 export interface SetupApiResult {
@@ -30,6 +31,7 @@ export interface SetupApiResult {
   baseUrl: string;
   specEndpoints: number;
   pathParams?: Record<string, string>;
+  warnings?: string[];
 }
 
 export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult> {
@@ -42,13 +44,17 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   let baseUrl = "";
   let endpointCount = 0;
   const pathParams = new Map<string, string>();
+  const warnings: string[] = [];
   let specTitle: string | undefined;
   if (spec) {
-    const doc = await readOpenApiSpec(spec);
+    const doc = await readOpenApiSpec(spec, { insecure: options.insecure });
     openapiSpec = spec;
     if ((doc as any).servers?.[0]?.url) {
       baseUrl = (doc as any).servers[0].url;
     }
+    if (baseUrl && !baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
+      warnings.push(`Spec server URL "${baseUrl}" is relative — requests will fail without a host. Override with envVars: {"base_url": "https://your-host${baseUrl}"}`);
+    }
     specTitle = (doc as any).info?.title;
     const endpoints = extractEndpoints(doc);
     endpointCount = endpoints.length;
@@ -139,5 +145,6 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     baseUrl,
     specEndpoints: endpointCount,
     ...(pathParamsObj ? { pathParams: pathParamsObj } : {}),
+    ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

package/src/mcp/descriptions.ts

@@ -12,7 +12,8 @@ export const TOOL_DESCRIPTIONS = {
   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.",
+    "Use this before generating tests for a new API. " +
+    "Warns if spec has relative server URL. Use insecure: true for self-signed HTTPS certs.",
 
   describe_endpoint:
     "Full details for one endpoint: params grouped by type, request body schema, " +
@@ -36,7 +37,7 @@ export const TOOL_DESCRIPTIONS = {
     "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), " +
+    "and summary includes api_errors/assertion_failures/network_errors counts; stack traces are truncated by default, use verbose: true for full traces), " +
     "compare_runs (regressions and fixes between two runs).",
 
   coverage_analysis:
@@ -46,7 +47,8 @@ export const TOOL_DESCRIPTIONS = {
     "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}}).",
+    "Send an ad-hoc HTTP request. Supports variable interpolation from environments (e.g. {{base_url}}). " +
+    "Use jsonPath to extract a subset of the response (e.g. '[0].code'), maxResponseChars to truncate large responses.",
 
   manage_server:
     "Start, stop, restart, or check status of the zond WebUI server. " +

package/src/mcp/tools/query-db.ts

@@ -6,6 +6,28 @@ import { join } from "node:path";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 import { statusHint, classifyFailure, envHint, envCategory, schemaHint } from "../../core/diagnostics/failure-hints.ts";
 
+function truncateErrorMessage(raw: string | null | undefined, verbose?: boolean): string | undefined {
+  if (!raw) return undefined;
+  if (verbose || raw.length < 500) return raw;
+  const lines = raw.split(/\r?\n/);
+  // First line is the error message itself
+  const msgLines = [lines[0]!];
+  // Grab up to 3 stack-trace lines (indented or starting with "at ")
+  let traceCount = 0;
+  for (let i = 1; i < lines.length && traceCount < 3; i++) {
+    const line = lines[i]!;
+    if (/^\s+/.test(line) || /^\s*at\s/.test(line)) {
+      msgLines.push(line);
+      traceCount++;
+    }
+  }
+  const remaining = lines.length - msgLines.length;
+  if (remaining > 0) {
+    msgLines.push(`...[truncated ${remaining} lines]`);
+  }
+  return msgLines.join("\n");
+}
+
 function parseBodySafe(raw: string | null | undefined): unknown {
   if (!raw) return undefined;
   const truncated = raw.length > 2000 ? raw.slice(0, 2000) + "…[truncated]" : raw;
@@ -49,8 +71,10 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
         .describe("Second run ID (required for compare_runs — this is the newer run)"),
       limit: z.optional(z.number().int().min(1).max(100))
         .describe("Max number of runs to return (default: 20, only for list_runs)"),
+      verbose: z.optional(z.boolean())
+        .describe("Show full error messages and stack traces (default: false, truncates long traces)"),
     },
-  }, async ({ action, runId, runIdB, limit }) => {
+  }, async ({ action, runId, runIdB, limit, verbose }) => {
     try {
       getDb(dbPath);
 
@@ -105,7 +129,7 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
               request_method: r.request_method,
               request_url: r.request_url,
               response_status: r.response_status,
-              error_message: r.error_message,
+              error_message: truncateErrorMessage(r.error_message, verbose),
               assertions: r.assertions,
             })),
           };
@@ -151,7 +175,7 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
                 test_name: r.test_name,
                 status: r.status,
                 failure_type,
-                error_message: r.error_message,
+                error_message: truncateErrorMessage(r.error_message, verbose),
                 request_method: r.request_method,
                 request_url: r.request_url,
                 response_status: r.response_status,

package/src/mcp/tools/send-request.ts

@@ -6,6 +6,24 @@ import { getDb } from "../../db/schema.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 
+function extractByPath(obj: unknown, path: string): unknown {
+  const segments = path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (Array.isArray(current)) {
+      const idx = parseInt(seg, 10);
+      if (isNaN(idx)) return undefined;
+      current = current[idx];
+    } else if (typeof current === 'object') {
+      current = (current as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
 export function registerSendRequestTool(server: McpServer, dbPath?: string) {
   server.registerTool("send_request", {
     description: TOOL_DESCRIPTIONS.send_request,
@@ -17,8 +35,10 @@ export function registerSendRequestTool(server: McpServer, dbPath?: string) {
       timeout: z.optional(z.number().int().positive()).describe("Request timeout in ms"),
       envName: z.optional(z.string()).describe("Environment name for variable interpolation"),
       collectionName: z.optional(z.string()).describe("Collection name to load env from its base_dir (e.g. 'petstore'). Required for {{variable}} interpolation."),
+      jsonPath: z.optional(z.string()).describe("Simple dot-notation path to extract from response body (e.g. '[0].code', 'data.items', 'id'). Supports array indices."),
+      maxResponseChars: z.optional(z.number().int().positive()).describe("Truncate response body to this many characters"),
     },
-  }, async ({ method, url, headers, body, timeout, envName, collectionName }) => {
+  }, async ({ method, url, headers, body, timeout, envName, collectionName, jsonPath, maxResponseChars }) => {
     try {
       let searchDir = process.cwd();
       if (collectionName) {
@@ -43,15 +63,29 @@ export function registerSendRequestTool(server: McpServer, dbPath?: string) {
         timeout ? { timeout } : undefined,
       );
 
+      let responseBody: unknown = response.body_parsed ?? response.body;
+
+      // Apply jsonPath filter
+      if (jsonPath && responseBody !== undefined) {
+        responseBody = extractByPath(responseBody, jsonPath);
+      }
+
       const result = {
         status: response.status,
         headers: response.headers,
-        body: response.body_parsed ?? response.body,
+        body: responseBody,
         duration_ms: response.duration_ms,
       };
 
+      let text = JSON.stringify(result, null, 2);
+
+      // Apply maxResponseChars truncation
+      if (maxResponseChars && text.length > maxResponseChars) {
+        text = text.slice(0, maxResponseChars) + '\n…[truncated]';
+      }
+
       return {
-        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        content: [{ type: "text" as const, text }],
       };
     } catch (err) {
       return {

package/src/mcp/tools/setup-api.ts

@@ -27,8 +27,9 @@ export function registerSetupApiTool(server: McpServer, dbPath?: string) {
       dir: z.optional(z.string()).describe("Base directory (default: ./apis/<name>/)"),
       envVars: z.optional(z.string()).describe("Environment variables as JSON string (e.g. '{\"base_url\": \"...\", \"token\": \"...\"}')"),
       force: z.optional(z.boolean()).describe("If true, delete existing API with same name and recreate from scratch"),
+      insecure: z.optional(z.boolean()).describe("Skip TLS certificate verification when fetching spec over HTTPS (for self-signed certs)"),
     },
-  }, async ({ name, specPath, dir, envVars, force }) => {
+  }, async ({ name, specPath, dir, envVars, force, insecure }) => {
     try {
       let parsedEnvVars: Record<string, string> | undefined;
       if (envVars) {
@@ -59,12 +60,15 @@ export function registerSetupApiTool(server: McpServer, dbPath?: string) {
         envVars: parsedEnvVars,
         dbPath,
         force,
+        insecure,
       });
 
       const envFilePath = join(result.baseDir, ".env.yaml");
+      const warningSteps = result.warnings?.map(w => `WARNING: ${w}`) ?? [];
       const response = {
         ...result,
         nextSteps: [
+          ...warningSteps,
           `Edit ${envFilePath} to add credentials (auth_token, api_key, base_url, etc.)`,
           `File is already git-ignored via .gitignore`,
           `Then run: run_tests(testPath: "${result.testPath}")`,