@kirrosh/zond 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.9.1",
+  "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,6 +59,66 @@ export function compressEndpointsWithSchemas(
   return lines.join("\n");
 }
 
+const YAML_FORMAT_CHEATSHEET = `
+## YAML Test Format Reference
+
+### Suite structure
+\`\`\`yaml
+name: Suite Name          # required
+base_url: "{{base_url}}"  # or hardcoded URL
+tags: [smoke]             # optional: smoke | crud | destructive | auth
+tests:
+  - GET /endpoint:        # method + path as YAML key
+      query: { limit: 10 }
+      expect:
+        status: 200
+        _body: { type: array }
+\`\`\`
+
+### 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
+  - POST /resource:
+      json: { name: "test", email: "a@b.com" }
+      expect:
+        status: 201
+\`\`\`
+
+### Built-in generators
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
+
+### Variable capture & interpolation
+\`\`\`yaml
+  - POST /items:
+      json: { name: "test-{{$uuid}}" }
+      capture:
+        created_id: id    # saves response.id
+      expect:
+        status: 201
+  - GET /items/{{created_id}}:
+      expect:
+        status: 200
+\`\`\`
+`;
+
 export interface GuideOptions {
   title: string;
   baseUrl?: string;
@@ -67,6 +127,7 @@ export interface GuideOptions {
   securitySchemes: SecuritySchemeInfo[];
   endpointCount: number;
   coverageHeader?: string;
+  includeFormat?: boolean;
 }
 
 export function buildGenerationGuide(opts: GuideOptions): string {
@@ -76,11 +137,13 @@ export function buildGenerationGuide(opts: GuideOptions): string {
     ? `Security: ${opts.securitySchemes.map(s => `${s.name} (${s.type}${s.scheme ? `/${s.scheme}` : ""})`).join(", ")}`
     : "Security: none";
 
+  const formatSection = opts.includeFormat !== false ? YAML_FORMAT_CHEATSHEET : "";
+
   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}`;
+${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,6 +108,7 @@ export function registerGenerateAndSaveTool(server: McpServer) {
         securitySchemes,
         endpointCount: endpoints.length,
         coverageHeader,
+        includeFormat: includeFormat ?? true,
       });
 
       const saveInstructions = `