@kirrosh/zond 0.9.0 → 0.9.2

package/package.json

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

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

@@ -59,301 +59,91 @@ export function compressEndpointsWithSchemas(
   return lines.join("\n");
 }
 
-export interface GuideOptions {
-  title: string;
-  baseUrl?: string;
-  apiContext: string;
-  outputDir: string;
-  securitySchemes: SecuritySchemeInfo[];
-  endpointCount: number;
-  coverageHeader?: string;
-  compact?: boolean;
-}
-
-export function buildGenerationGuide(opts: GuideOptions): string {
-  const hasAuth = opts.securitySchemes.length > 0;
-
-  if (opts.compact) {
-    const securitySummary = hasAuth
-      ? `Security: ${opts.securitySchemes.map(s => `${s.name} (${s.type}${s.scheme ? `/${s.scheme}` : ""})`).join(", ")}`
-      : "Security: none";
-
-    return `# Test Generation Guide for ${opts.title}
-${opts.coverageHeader ? `\n${opts.coverageHeader}\n` : ""}
-## API Specification (${opts.endpointCount} endpoints)
-${opts.baseUrl ? `Base URL: ${opts.baseUrl}` : "Base URL: use {{base_url}} environment variable"}
-${securitySummary}
-
-${opts.apiContext}
-
----
-
-> **Note:** Refer to the full YAML format reference, generation algorithm, tag conventions, and practical tips from the initial \`generate_and_save\` call (without \`tag\`). Only the API endpoints above are unique to this chunk.`;
-  }
-
-  return `# Test Generation Guide for ${opts.title}
-${opts.coverageHeader ? `\n${opts.coverageHeader}\n` : ""}
-## API Specification (${opts.endpointCount} endpoints)
-${opts.baseUrl ? `Base URL: ${opts.baseUrl}` : "Base URL: use {{base_url}} environment variable"}
-
-${opts.apiContext}
-
-${hasAuth ? `---
-
-## Environment Setup (Required for Authentication)
-
-This API uses authentication. Before running tests, set up your credentials:
-
-### Edit the env file
-After \`setup_api\`, the collection directory contains \`.env.yaml\`. Edit it to add your credentials:
-\`\`\`yaml
-base_url: "https://api.example.com"
-api_key: "your-actual-api-key-here"
-auth_token: "your-token-here"
-\`\`\`
-
-### How it works
-- Tests **automatically** load the \`"default"\` environment — no need to pass \`envName\` to \`run_tests\`
-- If the env file is in the collection root and tests are in a \`tests/\` subdirectory, the file is still found automatically
-- Use \`{{api_key}}\`, \`{{auth_token}}\`, \`{{base_url}}\` etc. in test headers/bodies
-- **Never hardcode credentials** in YAML files — always use \`{{variable}}\` references
-
-` : ""}---
-
-## YAML Test Suite Format Reference
+const YAML_FORMAT_CHEATSHEET = `
+## YAML Test Format Reference
 
+### Suite structure
 \`\`\`yaml
-name: "Suite Name"
-description: "What this suite tests"  # optional
-tags: [smoke, crud]                   # optional — used for filtering with --tag
-base_url: "{{base_url}}"
-headers:                          # optional suite-level headers
-  Authorization: "Bearer {{auth_token}}"
-  Content-Type: "application/json"
-config:                           # optional
-  timeout: 30000
-  retries: 0
-  follow_redirects: true
+name: Suite Name          # required
+base_url: "{{base_url}}"  # or hardcoded URL
+tags: [smoke]             # optional: smoke | crud | destructive | auth
 tests:
-  - name: "Test step name"
-    POST: "/path/{{variable}}"    # exactly ONE method key: GET, POST, PUT, PATCH, DELETE
-    json:                         # request body (object)
-      field: "value"
-    query:                        # query parameters
-      limit: "10"
-    headers:                      # step-level headers (override suite)
-      X-Custom: "value"
-    expect:
-      status: 200                 # expected HTTP status: integer OR array [200, 204]
-      body:                       # field-level assertions
-        id: { type: "integer", capture: "item_id" }
-        name: { equals: "expected" }
-        email: { contains: "@", type: "string" }
-        count: { gt: 0, lt: 100 }
-        items: { exists: true }       # exists must be boolean, NEVER string
-        pattern: { matches: "^[A-Z]+" }
-      headers:
-        Content-Type: "application/json"
-      duration: 5000              # max response time in ms
-\`\`\`
-
-### Assertion Rules
-- \`capture: "var_name"\` — SAVES the value into a variable (use in later steps as {{var_name}})
-- \`equals: value\` — exact match COMPARISON (NEVER use equals to save a value!)
-- \`type: "string"|"number"|"integer"|"boolean"|"array"|"object"\`
-- \`contains: "substring"\` — string substring match
-- \`matches: "regex"\` — regex pattern match
-- \`gt: N\` / \`lt: N\` — numeric comparison
-- \`exists: true|false\` — field presence check (MUST be boolean, not string)
-
-### Nested Body Assertions
-Both forms are equivalent and supported:
-
-**Dot-notation (flat):**
-\`\`\`yaml
-body:
-  "category.name": { equals: "Dogs" }
-  "address.city": { type: "string" }
-\`\`\`
-
-**Nested YAML (auto-flattened):**
-\`\`\`yaml
-body:
-  category:
-    name: { equals: "Dogs" }
-  address:
-    city: { type: "string" }
+  - GET /endpoint:        # method + path as YAML key
+      query: { limit: 10 }
+      expect:
+        status: 200
+        _body: { type: array }
 \`\`\`
 
-### Root Body Assertions (\`_body\`)
-Use \`_body\` to assert on the response body itself (not a field inside it):
-
+### Assertion operators
+| Operator | Example |
+|----------|---------|
+| equals (default) | \`status: 200\` |
+| not_equals | \`status: { not_equals: 500 }\` |
+| contains | \`name: { contains: "john" }\` |
+| not_contains | \`body: { not_contains: "error" }\` |
+| exists / not_exists | \`id: { exists: true }\` |
+| gt / gte / lt / lte | \`count: { gte: 1 }\` |
+| matches (regex) | \`email: { matches: "^.+@.+$" }\` |
+| type | \`items: { type: array }\` |
+| length | \`items: { length: 5 }\` |
+| length_gt/gte/lt/lte | \`items: { length_gt: 0 }\` |
+
+### Body assertions
+- \`_body\` — assert on entire response body: \`_body: { type: array }\`
+- Dot-notation for nested: \`data.user.id: { exists: true }\`
+- Array item access: \`items.0.name: { exists: true }\`
+
+### Request body (JSON)
 \`\`\`yaml
-body:
-  _body: { type: "array" }           # check that response body IS an array
-  _body: { type: "object" }          # check that response body IS an object
-  _body: { exists: true }            # check that body is not null/undefined
+  - POST /resource:
+      json: { name: "test", email: "a@b.com" }
+      expect:
+        status: 201
 \`\`\`
 
-### Built-in Generators
-Use in string values: \`{{$randomInt}}\`, \`{{$uuid}}\`, \`{{$timestamp}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`, \`{{$randomName}}\`
-These are the ONLY generators — do NOT invent others.
-
-### Variable Interpolation
-- \`{{variable}}\` in paths, bodies, headers, query params
-- Captured values from previous steps are available in subsequent steps
-- Environment variables from .env.yaml files: \`{{base_url}}\`, \`{{auth_username}}\`, etc.
-
----
-
-## Step-by-Step Generation Algorithm
-
-### Step 0: Register the API (REQUIRED FIRST)
-**Always call \`setup_api\` before generating any tests.** This registers the collection in the database so WebUI, coverage tracking, and env loading all work.
-\`\`\`
-setup_api(name: "myapi", specPath: "/path/to/openapi.json", dir: "/path/to/project/apis/myapi")
-\`\`\`
-If you skip this step, WebUI will show "No API collections registered yet" and env variables won't auto-load.
+### Built-in generators
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
 
-${hasAuth ? `**Then set credentials immediately after setup_api** — edit the \`.env.yaml\` file in the API directory to add your credentials:
+### Variable capture & interpolation
 \`\`\`yaml
-api_key: "<actual-key>"
-base_url: "https://..."
-\`\`\`
-Never put actual key values directly in YAML test files.
-
-` : ""}\
-### Step 1: Analyze the API
-- Identify authentication method (${hasAuth ? opts.securitySchemes.map(s => `${s.name}: ${s.type}${s.scheme ? `/${s.scheme}` : ""}`).join(", ") : "none detected"})
-- Group endpoints by resource (e.g., /users/*, /pets/*, /orders/*)
-- Identify CRUD patterns: POST (create) → GET (read) → PUT/PATCH (update) → DELETE
-- Note required fields in request bodies
-
-### Step 2: Plan Test Suites
-Before generating, check coverage with \`coverage_analysis\` to avoid duplicating existing tests. Use \`generate_and_save(testsDir=...)\` for incremental generation of uncovered endpoints only.
-
-> **Coverage note**: coverage is a static scan of YAML files — an endpoint is "covered" if a test file contains a matching METHOD + path line, regardless of whether tests pass or actually run.
-
-Create separate files for each concern:
-${hasAuth ? `- \`${opts.outputDir}auth.yaml\` — Authentication flow\n` : ""}\
-- \`${opts.outputDir}{resource}-crud.yaml\` — CRUD lifecycle per resource
-- \`${opts.outputDir}{resource}-validation.yaml\` — Error cases per resource
-
-### Step 3: Generate Each Suite
-
-${hasAuth ? `**Auth suite** (\`auth.yaml\`):
-1. Login with valid credentials → capture token
-2. Access protected endpoint with token → 200
-3. Login with invalid credentials → 401/403
-4. Access protected endpoint without token → 401
-
-` : ""}\
-**CRUD lifecycle** (\`{resource}-crud.yaml\`):
-1. Create resource (POST) → 201, **always verify key fields in response body** (at minimum: id, name/title)
-2. Read created resource (GET /resource/{{id}}) → 200, verify fields match what was sent
-3. List resources (GET /resource) → 200, verify \`_body: { type: "array" }\` AND \`_body.length: { gt: 0 }\`
-4. Update resource (PUT/PATCH /resource/{{id}}) → 200
-5. Read updated resource → verify changes applied
-6. Delete resource (DELETE /resource/{{id}}) → 200/204
-7. Verify deleted (GET /resource/{{id}}) → 404
-8. For bulk create endpoints (createWithArray/List): create → then GET each to verify they exist
-
-**Validation suite** (\`{resource}-validation.yaml\`):
-1. Create with missing required fields → 400/422, verify \`message: { exists: true }\` in error body
-2. Create with invalid field types → 400/422
-3. Get non-existent resource (e.g. id=999999) → 404
-4. Delete non-existent resource → 404
-5. For error responses: always assert error body has meaningful content, not just status code
-
-### Step 4: Save, Run, Debug
-1. Use \`save_test_suite\` to save each file — it validates YAML before writing
-2. Use \`run_tests\` to execute — review pass/fail summary
-3. If failures: use \`query_db\` with \`action: "diagnose_failure"\` and the runId to see full request/response details
-4. Fix issues and re-save with \`overwrite: true\`
-
----
-
-## Tag Conventions
-
-Use standard tags to enable safe filtering:
-
-| Tag | HTTP Methods | Safe for |
-|-----|-------------|---------|
-| \`smoke\` | GET only | Production (read-only, zero risk) |
-| \`crud\` | POST/PUT/PATCH | Staging only (state-changing) |
-| \`destructive\` | DELETE | Explicit opt-in, run last |
-| \`auth\` | Any (auth flows) | Run first to capture tokens |
-
-Example: \`zond run --tag smoke --safe\` → reads-only, safe against production.
-
----
-
-## Practical Tips
-
-- **int64 IDs**: For APIs returning large auto-generated IDs (int64), prefer setting fixed IDs in request bodies rather than capturing auto-generated ones, as JSON number precision may cause mismatches.
-- **Nested assertions**: Use dot-notation or nested YAML — both work identically.
-- **Root body type**: Use \`_body: { type: "array" }\` to verify the response body type itself.
-- **List endpoints**: Always check both type AND non-emptiness: \`_body: { type: "array" }\` + \`_body.length: { gt: 0 }\`
-- **Create responses**: Always verify at least the key identifying fields (id, name) in the response body — don't just check status.
-- **Error responses**: Assert that error bodies contain useful info (\`message: { exists: true }\`), not just status codes.
-- **Bulk operations**: After bulk create (createWithArray, createWithList), add GET steps to verify resources were actually created.
-- **204 No Content**: When an endpoint returns 204, omit \`body:\` assertions entirely — an empty response IS the correct behavior. Adding body assertions on 204 will always fail.
-- **Cleanup pattern**: Always delete test data in the same suite. Use a create → read → delete lifecycle so tests are idempotent:
-  \`\`\`yaml
-  tests:
-    - name: Create test resource
-      POST: /users
-      json: { name: "zond-test-{{$randomString}}" }
+  - POST /items:
+      json: { name: "test-{{$uuid}}" }
+      capture:
+        created_id: id    # saves response.id
       expect:
         status: 201
-        body:
-          id: { capture: user_id }
-    - name: Read created resource
-      GET: /users/{{user_id}}
+  - GET /items/{{created_id}}:
       expect:
         status: 200
-    - name: Cleanup - delete test resource
-      DELETE: /users/{{user_id}}
-      expect:
-        status: 204
-  \`\`\`
-- **Identifiable test data**: Prefix test data with \`zond-test-\` or use \`{{$uuid}}\` / \`zond-test-{{$randomString}}\` so you can identify and clean up leftover test data if needed.
-
----
-
-## Common Mistakes to Avoid
+\`\`\`
+`;
 
-1. **equals vs capture**: \`capture\` SAVES a value, \`equals\` COMPARES. To extract a token: \`{ capture: "token" }\` NOT \`{ equals: "{{token}}" }\`
-2. **exists must be boolean**: \`exists: true\` NOT \`exists: "true"\`
-3. **Status must be integer or array**: \`status: 200\` or \`status: [200, 204]\` NOT \`status: "200"\`
-4. **One method per step**: Each test step has exactly ONE of GET/POST/PUT/PATCH/DELETE
-5. **Don't hardcode base URL**: Use \`{{base_url}}\` — set it in environment or suite base_url
-6. **Auth credentials**: Use environment variables \`{{auth_username}}\`, \`{{auth_password}}\` — NOT generators
-7. **String query params**: Query parameter values must be strings: \`limit: "10"\` not \`limit: 10\`
-8. **Hardcoded credentials**: NEVER put actual API keys/tokens in YAML — use \`{{api_key}}\` from env instead
-9. **Body assertions on 204**: Don't add \`body:\` checks for DELETE or other endpoints that return 204 No Content — the body is empty by design.
+export interface GuideOptions {
+  title: string;
+  baseUrl?: string;
+  apiContext: string;
+  outputDir: string;
+  securitySchemes: SecuritySchemeInfo[];
+  endpointCount: number;
+  coverageHeader?: string;
+  includeFormat?: boolean;
+}
 
----
+export function buildGenerationGuide(opts: GuideOptions): string {
+  const hasAuth = opts.securitySchemes.length > 0;
 
-## Tools to Use
+  const securitySummary = hasAuth
+    ? `Security: ${opts.securitySchemes.map(s => `${s.name} (${s.type}${s.scheme ? `/${s.scheme}` : ""})`).join(", ")}`
+    : "Security: none";
 
-| Tool | When |
-|------|------|
-| \`setup_api\` | Register a new API (creates dirs, reads spec, sets up env) |
-| \`generate_and_save\` | Get test generation guide (with auto-chunking for large APIs) |
-| \`save_test_suite\` | Save generated YAML (validates before writing) |
-| \`save_test_suites\` | Save multiple YAML files in one call |
-| \`run_tests\` | Execute saved test suites |
-| \`query_db\` | Query runs, collections, results, diagnose failures |
-| \`coverage_analysis\` | Find untested endpoints for incremental generation |
-| \`describe_endpoint\` | Get full details for one endpoint when debugging |
-| \`ci_init\` | Generate CI/CD workflow (GitHub Actions / GitLab CI) to run tests on push |
+  const formatSection = opts.includeFormat !== false ? YAML_FORMAT_CHEATSHEET : "";
 
-## Workflow After Tests Pass
+  return `# Test Generation Guide for ${opts.title}
+${opts.coverageHeader ? `\n${opts.coverageHeader}\n` : ""}
+## API Specification (${opts.endpointCount} endpoints)
+${opts.baseUrl ? `Base URL: ${opts.baseUrl}` : "Base URL: use {{base_url}} environment variable"}
+${securitySummary}
 
-After tests are saved and running successfully, ask the user if they want to set up CI/CD:
-1. Use \`ci_init\` to generate a CI workflow (auto-detects platform or use platform param)
-2. Help them commit and push to their repository
-3. Tests will run automatically on push, PR, and on schedule
-`;
+${opts.apiContext}${formatSection}`;
 }

package/src/mcp/descriptions.ts

@@ -56,7 +56,8 @@ export const TOOL_DESCRIPTIONS = {
     "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.",
+    "After generating YAML, use save_test_suites to save files, then run_tests to verify. " +
+    "Includes YAML format cheatsheet by default; pass includeFormat: false for subsequent tag chunks to save tokens.",
 
   ci_init:
     "Generate a CI/CD workflow file for running API tests automatically on push, PR, and schedule. " +

package/src/mcp/tools/generate-and-save.ts

@@ -21,8 +21,9 @@ export function registerGenerateAndSaveTool(server: McpServer) {
       methodFilter: z.optional(z.array(z.string())).describe("Only include endpoints with these HTTP methods (e.g. [\"GET\"] for smoke tests)"),
       testsDir: z.optional(z.string()).describe("Path to existing tests directory — filters to uncovered endpoints only"),
       overwrite: z.optional(z.boolean()).describe("Hint for save_test_suites overwrite behavior (default: false)"),
+      includeFormat: z.optional(z.boolean()).describe("Include YAML format reference (default: true, set false for subsequent tag chunks)"),
     },
-  }, async ({ specPath, outputDir, tag, methodFilter, testsDir, overwrite }) => {
+  }, async ({ specPath, outputDir, tag, methodFilter, testsDir, overwrite, includeFormat }) => {
     try {
       const doc = await readOpenApiSpec(specPath);
       let endpoints = extractEndpoints(doc);
@@ -82,6 +83,7 @@ export function registerGenerateAndSaveTool(server: McpServer) {
           instruction:
             `This API has ${plan.totalEndpoints} endpoints across ${plan.chunks.length} tags. ` +
             `Call generate_and_save with tag parameter for each chunk sequentially. ` +
+            `Pass includeFormat: false for subsequent chunks to save tokens. ` +
             `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0].tag}')`,
         };
         if (coverageInfo) {
@@ -106,7 +108,7 @@ export function registerGenerateAndSaveTool(server: McpServer) {
         securitySchemes,
         endpointCount: endpoints.length,
         coverageHeader,
-        compact: !!tag,
+        includeFormat: includeFormat ?? true,
       });
 
       const saveInstructions = `