@cyanheads/mcp-ts-core 0.1.28 → 0.2.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.28
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.0
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
 > **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
@@ -38,6 +38,7 @@
 | `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
 | `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
 | `/testing` | `createMockContext` | Test helpers |
+| `/testing/fuzz` | `fuzzTool`, `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, `adversarialArbitrary`, `ADVERSARIAL_STRINGS` | Fuzz testing |
 
 All subpaths prefixed with `@cyanheads/mcp-ts-core`. **†Tier 3 modules** require optional peer dependencies — see `package.json` `peerDependencies`. Tier 3 methods that lazy-load deps are **async**.
 
@@ -383,6 +384,21 @@ describe('myTool', () => {
 
 **`createMockContext` options:** `createMockContext()` (minimal), `{ tenantId: 'test-tenant' }` (enables state), `{ sample: vi.fn() }`, `{ elicit: vi.fn() }`, `{ progress: true }` (task progress).
 
+**Fuzz testing:** `fuzzTool`/`fuzzResource`/`fuzzPrompt` from `/testing/fuzz` generate valid and adversarial inputs from Zod schemas via `fast-check`, then assert handler invariants (no crashes, no prototype pollution, no stack trace leaks). Returns a `FuzzReport` for custom assertions.
+
+```ts
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+it('survives fuzz testing', async () => {
+  const report = await fuzzTool(myTool, { numRuns: 100 });
+  expect(report.crashes).toHaveLength(0);
+  expect(report.leaks).toHaveLength(0);
+  expect(report.prototypePollution).toBe(false);
+});
+```
+
+Options: `numRuns` (valid inputs, default 50), `numAdversarial` (adversarial inputs, default 30), `seed` (reproducibility), `timeout` (per-call ms, default 5000), `ctx` (`MockContextOptions` for stateful handlers). Also exports `zodToArbitrary(schema)` for custom property-based tests and `ADVERSARIAL_STRINGS` for targeted injection testing.
+
 **Vitest config:** Extend core config, add `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`. Construct deps in `beforeEach`. Re-init services per suite.
 
 ---
@@ -413,6 +429,8 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `setup` | `skills/setup/SKILL.md` | Initialize a new consumer server from the template |
 | `devcheck` | `skills/devcheck/SKILL.md` | Run lint, format, typecheck, security checks |
 | `polish-docs-meta` | `skills/polish-docs-meta/SKILL.md` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `report-issue-framework` | `skills/report-issue-framework/SKILL.md` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | `skills/report-issue-local/SKILL.md` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `release` | `skills/release/SKILL.md` | Version bump, changelog, publish workflow |
 | `maintenance` | `skills/maintenance/SKILL.md` | Dependency updates, housekeeping tasks |
 | `migrate-mcp-ts-template` | `skills/migrate-mcp-ts-template/SKILL.md` | Migrate legacy template fork to package dependency |

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.28-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -191,6 +191,7 @@ import { markdown, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
 import { OpenRouterProvider, GraphService } from '@cyanheads/mcp-ts-core/services';
 import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { fuzzTool, fuzzResource, fuzzPrompt } from '@cyanheads/mcp-ts-core/testing/fuzz';
 ```
 
 See [CLAUDE.md](CLAUDE.md) for the complete exports reference.
@@ -222,6 +223,21 @@ const result = await myTool.handler(input, ctx);
 
 `createMockContext()` provides stubbed `log`, `state`, and `signal`. Pass `{ tenantId }` for state operations, `{ sample }` for LLM mocking, `{ elicit }` for elicitation mocking, `{ progress: true }` for task tools.
 
+### Fuzz testing
+
+Schema-aware fuzz testing via `fast-check`. Generates valid inputs from Zod schemas and adversarial payloads (prototype pollution, injection strings, type confusion) to verify handler invariants.
+
+```ts
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+const report = await fuzzTool(myTool, { numRuns: 100 });
+expect(report.crashes).toHaveLength(0);
+expect(report.leaks).toHaveLength(0);
+expect(report.prototypePollution).toBe(false);
+```
+
+Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_STRINGS` for custom property-based tests.
+
 ## Documentation
 
 - **[CLAUDE.md](CLAUDE.md)** — Complete API reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
@@ -232,6 +248,7 @@ const result = await myTool.handler(input, ctx);
 ```bash
 bun run build          # tsc && tsc-alias
 bun run devcheck       # lint, format, typecheck, security
+bun run lint:mcp       # validate MCP definitions against spec
 bun run test           # vitest
 bun run dev:stdio      # dev mode (stdio)
 bun run dev:http       # dev mode (HTTP)

package/biome.json

@@ -81,6 +81,16 @@
         }
       }
     },
+    {
+      "includes": ["src/testing/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noExplicitAny": "off"
+          }
+        }
+      }
+    },
     {
       "includes": ["scripts/**"],
       "linter": {

package/dist/linter/rules/tool-rules.js

@@ -123,28 +123,16 @@ function lintToolAnnotations(annotations, toolName) {
             });
         }
     }
-    // Semantic coherence: destructiveHint and idempotentHint are meaningless when readOnlyHint is true
-    if (annotations.readOnlyHint === true) {
-        if ('destructiveHint' in annotations) {
-            diagnostics.push({
-                rule: 'annotation-coherence',
-                severity: 'warning',
-                message: `Tool '${toolName}' sets destructiveHint while readOnlyHint is true. ` +
-                    'destructiveHint is meaningless for read-only tools.',
-                definitionType: 'tool',
-                definitionName: toolName,
-            });
-        }
-        if ('idempotentHint' in annotations) {
-            diagnostics.push({
-                rule: 'annotation-coherence',
-                severity: 'warning',
-                message: `Tool '${toolName}' sets idempotentHint while readOnlyHint is true. ` +
-                    'Read-only tools are inherently idempotent — this hint is redundant.',
-                definitionType: 'tool',
-                definitionName: toolName,
-            });
-        }
+    // Semantic coherence: destructiveHint is meaningless when readOnlyHint is true
+    if (annotations.readOnlyHint === true && 'destructiveHint' in annotations) {
+        diagnostics.push({
+            rule: 'annotation-coherence',
+            severity: 'warning',
+            message: `Tool '${toolName}' sets destructiveHint while readOnlyHint is true. ` +
+                'destructiveHint is meaningless for read-only tools.',
+            definitionType: 'tool',
+            definitionName: toolName,
+        });
     }
     return diagnostics;
 }

package/dist/linter/rules/tool-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,IAAI,WAAW,CAAC;IAExC,kBAAkB;IAClB,MAAM,OAAO,GAAG,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,OAAO;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvC,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,OAAO;YAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,cAAc;IACd,IAAI,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrE,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,sBAAsB;YAC5B,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,SAAS,WAAW,8EAA8E;YAC3G,cAAc,EAAE,MAAM;YACtB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,UAAU;IACV,IAAI,OAAO,CAAC,EAAE,OAAO,KAAK,UAAU,EAAE,CAAC;QACrC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,SAAS,WAAW,kCAAkC;YAC/D,cAAc,EAAE,MAAM;YACtB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,+DAA+D;IAC/D,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5E,IAAI,UAAU,EAAE,CAAC;QACf,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;QACpF,MAAM,WAAW,GAAG,uBAAuB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACpF,IAAI,WAAW;YAAE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,gEAAgE;IAChE,MAAM,WAAW,GAAG,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/E,IAAI,WAAW,EAAE,CAAC;QAChB,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;QACtF,MAAM,YAAY,GAAG,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACvF,IAAI,YAAY;YAAE,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED,yBAAyB;IACzB,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1B,WAAW,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,yBAAyB;IACzB,IAAI,CAAC,EAAE,WAAW,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACxD,WAAW,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,WAAsC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAC5B,IAAa,EACb,cAAgD,EAChD,cAAsB;IAEtB,MAAM,WAAW,GAAqB,EAAE,CAAC;IAEzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,GAAG,cAAc,KAAK,cAAc,2CAA2C;YACxF,cAAc;YACd,cAAc;SACf,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,mBAAmB;gBACzB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EACL,GAAG,cAAc,KAAK,cAAc,UAAU,CAAC,gCAAgC;oBAC/E,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG;gBACrE,cAAc;gBACd,cAAc;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,yEAAyE;AACzE,SAAS,mBAAmB,CAC1B,WAAoC,EACpC,QAAgB;IAEhB,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,YAAY,GAAG;QACnB,cAAc;QACd,iBAAiB;QACjB,gBAAgB;QAChB,eAAe;KACP,CAAC;IAEX,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,IAAI,IAAI,WAAW,IAAI,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAClE,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,SAAS;gBACnB,OAAO,EAAE,SAAS,QAAQ,iBAAiB,IAAI,8BAA8B,OAAO,WAAW,CAAC,IAAI,CAAC,GAAG;gBACxG,cAAc,EAAE,MAAM;gBACtB,cAAc,EAAE,QAAQ;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,mGAAmG;IACnG,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACtC,IAAI,iBAAiB,IAAI,WAAW,EAAE,CAAC;YACrC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,sBAAsB;gBAC5B,QAAQ,EAAE,SAAS;gBACnB,OAAO,EACL,SAAS,QAAQ,qDAAqD;oBACtE,qDAAqD;gBACvD,cAAc,EAAE,MAAM;gBACtB,cAAc,EAAE,QAAQ;aACzB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,gBAAgB,IAAI,WAAW,EAAE,CAAC;YACpC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,sBAAsB;gBAC5B,QAAQ,EAAE,SAAS;gBACnB,OAAO,EACL,SAAS,QAAQ,oDAAoD;oBACrE,qEAAqE;gBACvE,cAAc,EAAE,MAAM;gBACtB,cAAc,EAAE,QAAQ;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"tool-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"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"}

package/dist/testing/fuzz.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Schema-aware fuzz testing utilities for MCP definitions.
+ * Generates valid, near-miss, and adversarial inputs from Zod schemas,
+ * then asserts handler invariants (no crashes, well-formed errors, etc.).
+ *
+ * Uses `fast-check` for property-based generation. Consumers use
+ * `fuzzTool()`, `fuzzResource()`, and `fuzzPrompt()` in their Vitest suites.
+ *
+ * @module src/testing/fuzz
+ */
+import fc from 'fast-check';
+import type { ZodObject, ZodRawShape } from 'zod';
+import type { AnyPromptDefinition } from '../mcp-server/prompts/utils/promptDefinition.js';
+import type { AnyResourceDefinition } from '../mcp-server/resources/utils/resourceDefinition.js';
+import type { AnyToolDefinition } from '../mcp-server/tools/utils/toolDefinition.js';
+import { type MockContextOptions } from './index.js';
+/** Options for fuzz test runners. */
+export interface FuzzOptions {
+    /** Mock context options passed to `createMockContext()`. */
+    ctx?: MockContextOptions;
+    /** Number of adversarial-input runs. @default 30 */
+    numAdversarial?: number;
+    /** Number of valid-input runs. @default 50 */
+    numRuns?: number;
+    /** fast-check seed for reproducibility. */
+    seed?: number;
+    /** Timeout per individual handler call in ms. @default 5000 */
+    timeout?: number;
+}
+/**
+ * Converts a Zod schema to a fast-check `Arbitrary` that produces valid values.
+ * Supports the JSON-Schema-serializable subset used by MCP tool/resource schemas.
+ */
+export declare function zodToArbitrary(schema: unknown): fc.Arbitrary<unknown>;
+/** Strings designed to trigger injection, encoding, or parsing vulnerabilities. */
+export declare const ADVERSARIAL_STRINGS: readonly string[];
+/** Generates adversarial values for object fields based on expected type. */
+export declare function adversarialArbitrary(): fc.Arbitrary<unknown>;
+/**
+ * Generates an adversarial variant of a Zod object schema's input.
+ * Produces objects that match the key structure but have wrong-type values.
+ */
+export declare function adversarialObjectArbitrary(schema: ZodObject<ZodRawShape>): fc.Arbitrary<Record<string, unknown>>;
+/** Result of a fuzz run, useful for custom assertions. */
+export interface FuzzReport {
+    /** Inputs that caused the handler to crash (unhandled throw past framework). */
+    crashes: Array<{
+        input: unknown;
+        error: unknown;
+    }>;
+    /** Responses that leaked stack traces or internal paths. */
+    leaks: Array<{
+        input: unknown;
+        errorText: string;
+    }>;
+    /** Prototype pollution detected on global objects. */
+    prototypePollution: boolean;
+    /** Total inputs tested. */
+    totalRuns: number;
+}
+/**
+ * Fuzz-tests a tool definition's handler with valid and adversarial inputs.
+ * Designed to be called inside a `describe()` / `it()` block.
+ *
+ * Checks:
+ * 1. Valid inputs -> handler runs without crash, output matches schema
+ * 2. Adversarial inputs -> Zod rejects or handler errors gracefully
+ * 3. No prototype pollution on Object.prototype
+ * 4. No stack trace / path leaks in error messages
+ * 5. Aborted signals -> handler doesn't hang
+ *
+ * @returns FuzzReport for additional custom assertions.
+ *
+ * @example
+ * ```ts
+ * import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+ *
+ * describe('myTool fuzz', () => {
+ *   it('survives fuzz testing', async () => {
+ *     const report = await fuzzTool(myTool, { numRuns: 100 });
+ *     expect(report.crashes).toHaveLength(0);
+ *     expect(report.leaks).toHaveLength(0);
+ *     expect(report.prototypePollution).toBe(false);
+ *   });
+ * });
+ * ```
+ */
+export declare function fuzzTool(def: AnyToolDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+/**
+ * Fuzz-tests a resource definition's handler with valid and adversarial params.
+ *
+ * @example
+ * ```ts
+ * const report = await fuzzResource(myResource, { numRuns: 50 });
+ * expect(report.crashes).toHaveLength(0);
+ * ```
+ */
+export declare function fuzzResource(def: AnyResourceDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+/**
+ * Fuzz-tests a prompt definition's `generate()` with valid and adversarial args.
+ *
+ * @example
+ * ```ts
+ * const report = await fuzzPrompt(myPrompt, { numRuns: 50 });
+ * expect(report.crashes).toHaveLength(0);
+ * ```
+ */
+export declare function fuzzPrompt(def: AnyPromptDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+//# sourceMappingURL=fuzz.d.ts.map

package/dist/testing/fuzz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzz.d.ts","sourceRoot":"","sources":["../../src/testing/fuzz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAalD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMxE,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,GAAG,CAAC,EAAE,kBAAkB,CAAC;IACzB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAErE;AAmHD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAwDvC,CAAC;AAEX,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CA4B5D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAC7B,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CASvC;AA2DD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnD,4DAA4D;IAC5D,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,sDAAsD;IACtD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA8FrB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,qBAAqB,EAC1B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA4ErB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,mBAAmB,EACxB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAmErB"}