@kirrosh/zond 0.12.5 → 0.12.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.12.5",
+  "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}")`,