@vinkius-core/mcp-fusion-testing 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,255 @@
+<p align="center">
+  <h1 align="center">@vinkius-core/mcp-fusion-testing</h1>
+  <p align="center">
+    <strong>In-Memory MVA Pipeline Tester</strong> — Run the full execution pipeline without MCP transport
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@vinkius-core/mcp-fusion-testing"><img src="https://img.shields.io/npm/v/@vinkius-core/mcp-fusion-testing?color=blue" alt="npm" /></a>
+  <a href="https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node" />
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Dependencies" />
+</p>
+
+---
+
+> The official test runner for MCP Fusion applications. In-memory MVA lifecycle emulator — runs the full execution pipeline without network transport. Zero runtime dependencies. Runner agnostic (Vitest, Jest, Mocha, `node:test`).
+
+## Why
+
+Every MCP server today is tested with HTTP mocks, raw `JSON.stringify` assertions, and string matching. That's like testing a REST API by reading TCP packets.
+
+**MCP Fusion** applications have **five auditable layers** (Zod Validation → Middleware Chain → Handler → Presenter Egress Firewall → System Rules). The `FusionTester` lets you assert each layer independently, in-memory, without starting a server.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    FusionTester                          │
+│                                                         │
+│  ┌──────────┐   ┌────────────┐   ┌─────────┐           │
+│  │   Zod    │──▶│ Middleware  │──▶│ Handler │           │
+│  │  Input   │   │   Chain    │   │         │           │
+│  └──────────┘   └────────────┘   └────┬────┘           │
+│                                       │                 │
+│                                  ┌────▼────┐            │
+│                                  │Presenter│            │
+│                                  │ (Egress │            │
+│                                  │Firewall)│            │
+│                                  └────┬────┘            │
+│                                       │                 │
+│  ┌────────────────────────────────────▼──────────────┐  │
+│  │              MvaTestResult                        │  │
+│  │  ┌──────┐ ┌───────────┐ ┌────────┐ ┌───────────┐ │  │
+│  │  │ data │ │systemRules│ │uiBlocks│ │rawResponse│ │  │
+│  │  └──────┘ └───────────┘ └────────┘ └───────────┘ │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## What You Can Audit
+
+| MVA Layer | What FusionTester asserts | SOC2 Relevance |
+|---|---|---|
+| **Egress Firewall** | Hidden fields (`passwordHash`, `tenantId`) are physically absent from `result.data` | Data leak prevention |
+| **OOM Guard** | Zod rejects `take: 10000` before it reaches the handler | Memory exhaustion protection |
+| **System Rules** | `result.systemRules` contains the expected domain rules | Deterministic LLM governance |
+| **UI Blocks** | SSR blocks (echarts, summaries) are correctly generated | Agent response quality |
+| **Middleware** | Auth guards block unauthorized calls, isError is true | Access control verification |
+| **Agent Limit** | Collections are truncated at cognitive guardrail bounds | Context window protection |
+| **HATEOAS** | `suggestActions` produces correct next-step affordances | Agent navigation safety |
+
+## Quick Start
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createFusionTester } from '@vinkius-core/mcp-fusion-testing';
+import { registry } from './server/registry.js';
+
+const tester = createFusionTester(registry, {
+    contextFactory: () => ({
+        prisma: mockPrisma,
+        tenantId: 't_enterprise_42',
+        role: 'ADMIN',
+    }),
+});
+
+describe('User MVA Audit', () => {
+    it('Egress Firewall strips sensitive fields', async () => {
+        const result = await tester.callAction('db_user', 'find_many', { take: 10 });
+
+        expect(result.data[0]).not.toHaveProperty('passwordHash');
+        expect(result.data[0]).not.toHaveProperty('tenantId');
+        expect(result.data[0].email).toBe('ceo@acme.com');
+    });
+
+    it('System rules are injected by Presenter', async () => {
+        const result = await tester.callAction('db_user', 'find_many', { take: 5 });
+
+        expect(result.systemRules).toContain(
+            'Data originates from the database via Prisma ORM.'
+        );
+    });
+
+    it('OOM Guard rejects unbounded queries', async () => {
+        const result = await tester.callAction('db_user', 'find_many', { take: 99999 });
+        expect(result.isError).toBe(true);
+    });
+});
+```
+
+## API Reference
+
+### `createFusionTester(registry, options)`
+
+Factory function — creates a `FusionTester` instance.
+
+```typescript
+function createFusionTester<TContext>(
+    registry: ToolRegistry<TContext>,
+    options: TesterOptions<TContext>,
+): FusionTester<TContext>;
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `registry` | `ToolRegistry<TContext>` | Your application's tool registry — the same one wired to the MCP server |
+| `options` | `TesterOptions<TContext>` | Configuration object |
+
+### `TesterOptions<TContext>`
+
+```typescript
+interface TesterOptions<TContext> {
+    contextFactory: () => TContext | Promise<TContext>;
+}
+```
+
+### `tester.callAction(toolName, actionName, args?, overrideContext?)`
+
+Executes a single tool action through the **full MVA pipeline** and returns a decomposed result.
+
+```typescript
+async callAction<TArgs>(
+    toolName: string,
+    actionName: string,
+    args?: TArgs,
+    overrideContext?: Partial<TContext>,
+): Promise<MvaTestResult>;
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `toolName` | `string` | ✅ | The registered tool name (e.g. `'db_user'`, `'analytics'`) |
+| `actionName` | `string` | ✅ | The action discriminator (e.g. `'find_many'`, `'create'`) |
+| `args` | `object` | ❌ | Arguments for the action — omit the `action` discriminator |
+| `overrideContext` | `Partial<TContext>` | ❌ | Per-test context overrides. Shallow-merged with `contextFactory()` output |
+
+### `MvaTestResult<TData>`
+
+Decomposed MVA response — each field maps to a specific pipeline layer.
+
+| Field | Type | Source | Description |
+|---|---|---|---|
+| `data` | `TData` | Presenter Zod schema | Validated data **after** the Egress Firewall. Hidden fields are physically absent. |
+| `systemRules` | `string[]` | Presenter `.systemRules()` | JIT domain rules injected by the Presenter. Empty array if no Presenter. |
+| `uiBlocks` | `unknown[]` | Presenter `.uiBlocks()` | SSR UI blocks (charts, summaries, markdown). Empty array if no Presenter. |
+| `isError` | `boolean` | Pipeline | `true` if Zod rejected, middleware blocked, or handler returned `error()`. |
+| `rawResponse` | `unknown` | Pipeline | The raw MCP `ToolResponse` for protocol-level inspection. |
+
+## Cookbook
+
+### Egress Firewall Audit
+
+```typescript
+it('strips PII from response', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 5 });
+
+    const users = result.data as Array<Record<string, unknown>>;
+    for (const user of users) {
+        expect(user).not.toHaveProperty('passwordHash');
+        expect(user).not.toHaveProperty('tenantId');
+    }
+});
+```
+
+### Middleware Guards (RBAC)
+
+```typescript
+it('blocks GUEST role', async () => {
+    const result = await tester.callAction(
+        'db_user', 'find_many', { take: 5 },
+        { role: 'GUEST' },
+    );
+    expect(result.isError).toBe(true);
+});
+
+it('allows ADMIN role', async () => {
+    const result = await tester.callAction(
+        'db_user', 'find_many', { take: 5 },
+        { role: 'ADMIN' },
+    );
+    expect(result.isError).toBe(false);
+});
+```
+
+### Agent Limit (Cognitive Guardrail)
+
+```typescript
+it('truncates at agentLimit', async () => {
+    const result = await tester.callAction('analytics', 'list', { limit: 100 });
+    expect((result.data as any[]).length).toBe(20);
+});
+```
+
+### Protocol-Level Inspection
+
+```typescript
+it('raw response follows MCP shape', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 1 });
+    const raw = result.rawResponse as { content: Array<{ type: string; text: string }> };
+
+    expect(raw.content).toBeInstanceOf(Array);
+    expect(raw.content[0].type).toBe('text');
+});
+```
+
+## How It Works
+
+The `FusionTester` runs the **real** execution pipeline — the exact same code path as your production MCP server:
+
+```
+ToolRegistry.routeCall()
+  → Concurrency Semaphore
+    → Discriminator Parsing
+      → Zod Input Validation
+        → Compiled Middleware Chain
+          → Handler Execution
+            → PostProcessor (Presenter auto-application)
+              → Egress Guard
+```
+
+The key insight: `ResponseBuilder.build()` attaches structured MVA metadata via a **global Symbol** (`MVA_META_SYMBOL`). Symbols are ignored by `JSON.stringify`, so the MCP transport never sees them — but the `FusionTester` reads them in RAM.
+
+**No XML regex. No string parsing. Zero coupling to response formatting.**
+
+## Installation
+
+```bash
+npm install @vinkius-core/mcp-fusion-testing
+```
+
+### Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `@vinkius-core/mcp-fusion` | `^2.0.0` |
+| `zod` | `^3.25.1 \|\| ^4.0.0` |
+
+## Requirements
+
+- **Node.js** ≥ 18.0.0
+- **TypeScript** 5.7+
+- **MCP Fusion** ≥ 2.0.0 (peer dependency)
+
+## License
+
+[Apache-2.0](https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE)

package/dist/FusionTester.d.ts

@@ -0,0 +1,98 @@
+/**
+ * FusionTester — In-Memory MVA Lifecycle Emulator
+ *
+ * Runs the **real** MCP Fusion execution pipeline in RAM:
+ * Zod Input Validation → Middleware Chain → Handler → PostProcessor → Egress Firewall
+ *
+ * Decomposes the `ToolResponse` into structured `MvaTestResult` objects
+ * using the Symbol Backdoor (`MVA_META_SYMBOL`) — zero XML parsing, zero regex.
+ *
+ * **Zero coupling to test runners.** Returns plain JS objects. Use with
+ * Vitest, Jest, Mocha, or Node's native `node:test`.
+ *
+ * @example
+ * ```typescript
+ * import { createFusionTester } from '@vinkius-core/mcp-fusion-testing';
+ * import { registry } from '../src/server/registry.js';
+ *
+ * const tester = createFusionTester(registry, {
+ *     contextFactory: () => ({
+ *         prisma: mockPrisma,
+ *         tenantId: 't_777',
+ *     }),
+ * });
+ *
+ * const result = await tester.callAction('db_user', 'find_many', { take: 10 });
+ *
+ * expect(result.data[0]).not.toHaveProperty('passwordHash');
+ * expect(result.systemRules).toContain('Data originates from the database via Prisma ORM.');
+ * ```
+ *
+ * @module
+ */
+import type { ToolRegistry } from '@vinkius-core/mcp-fusion';
+import type { TesterOptions, MvaTestResult } from './types.js';
+/**
+ * In-memory MVA lifecycle emulator.
+ *
+ * Delegates to `ToolRegistry.routeCall()` for full pipeline fidelity,
+ * then extracts structured MVA layers via the Symbol Backdoor.
+ *
+ * @typeParam TContext - Application context type (matches your ToolRegistry)
+ */
+export declare class FusionTester<TContext> {
+    private readonly registry;
+    private readonly options;
+    constructor(registry: ToolRegistry<TContext>, options: TesterOptions<TContext>);
+    /**
+     * Execute a tool action through the full MVA pipeline in-memory.
+     *
+     * @param toolName - The registered tool name (e.g. `'db_user'`)
+     * @param actionName - The action discriminator (e.g. `'find_many'`)
+     * @param args - Arguments for the action (excluding the discriminator)
+     * @param overrideContext - Partial context overrides for this specific test
+     *   (e.g. `{ role: 'GUEST' }` to simulate a different JWT)
+     * @returns Decomposed MVA result with `data`, `systemRules`, `uiBlocks`, `isError`
+     *
+     * @throws {Error} If Zod input validation rejects the args (the ZodError propagates)
+     *
+     * @example
+     * ```typescript
+     * // Egress Firewall test
+     * const result = await tester.callAction('db_user', 'find_many', { take: 10 });
+     * expect(result.data[0]).not.toHaveProperty('passwordHash');
+     *
+     * // OOM Guard test — Zod rejects take > 50
+     * await expect(
+     *     tester.callAction('db_user', 'find_many', { take: 10000 })
+     * ).rejects.toThrow();
+     *
+     * // Middleware test via overrideContext
+     * const result = await tester.callAction('db_user', 'create',
+     *     { email: 'test@co.com' },
+     *     { role: 'GUEST' }
+     * );
+     * expect(result.isError).toBe(true);
+     * ```
+     */
+    callAction<TArgs = Record<string, unknown>>(toolName: string, actionName: string, args?: TArgs, overrideContext?: Partial<TContext>): Promise<MvaTestResult>;
+}
+/**
+ * Create a FusionTester for the given registry.
+ *
+ * @param registry - The application's ToolRegistry instance
+ * @param options - Context factory and configuration
+ * @returns A new FusionTester instance
+ *
+ * @example
+ * ```typescript
+ * const tester = createFusionTester(registry, {
+ *     contextFactory: () => ({
+ *         prisma: mockPrisma,
+ *         tenantId: 't_enterprise_42',
+ *     }),
+ * });
+ * ```
+ */
+export declare function createFusionTester<TContext>(registry: ToolRegistry<TContext>, options: TesterOptions<TContext>): FusionTester<TContext>;
+//# sourceMappingURL=FusionTester.d.ts.map

package/dist/FusionTester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FusionTester.d.ts","sourceRoot":"","sources":["../src/FusionTester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI/D;;;;;;;GAOG;AACH,qBAAa,YAAY,CAAC,QAAQ;IAE1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,EAChC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC;IAGrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,KAAK,EACZ,eAAe,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GACpC,OAAO,CAAC,aAAa,CAAC;CAsD5B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EACvC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,EAChC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,GACjC,YAAY,CAAC,QAAQ,CAAC,CAExB"}

package/dist/FusionTester.js

@@ -0,0 +1,123 @@
+import { MVA_META_SYMBOL } from '@vinkius-core/mcp-fusion';
+// ── FusionTester Class ───────────────────────────────────
+/**
+ * In-memory MVA lifecycle emulator.
+ *
+ * Delegates to `ToolRegistry.routeCall()` for full pipeline fidelity,
+ * then extracts structured MVA layers via the Symbol Backdoor.
+ *
+ * @typeParam TContext - Application context type (matches your ToolRegistry)
+ */
+export class FusionTester {
+    registry;
+    options;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = options;
+    }
+    /**
+     * Execute a tool action through the full MVA pipeline in-memory.
+     *
+     * @param toolName - The registered tool name (e.g. `'db_user'`)
+     * @param actionName - The action discriminator (e.g. `'find_many'`)
+     * @param args - Arguments for the action (excluding the discriminator)
+     * @param overrideContext - Partial context overrides for this specific test
+     *   (e.g. `{ role: 'GUEST' }` to simulate a different JWT)
+     * @returns Decomposed MVA result with `data`, `systemRules`, `uiBlocks`, `isError`
+     *
+     * @throws {Error} If Zod input validation rejects the args (the ZodError propagates)
+     *
+     * @example
+     * ```typescript
+     * // Egress Firewall test
+     * const result = await tester.callAction('db_user', 'find_many', { take: 10 });
+     * expect(result.data[0]).not.toHaveProperty('passwordHash');
+     *
+     * // OOM Guard test — Zod rejects take > 50
+     * await expect(
+     *     tester.callAction('db_user', 'find_many', { take: 10000 })
+     * ).rejects.toThrow();
+     *
+     * // Middleware test via overrideContext
+     * const result = await tester.callAction('db_user', 'create',
+     *     { email: 'test@co.com' },
+     *     { role: 'GUEST' }
+     * );
+     * expect(result.isError).toBe(true);
+     * ```
+     */
+    async callAction(toolName, actionName, args, overrideContext) {
+        // 1. Context Hydration
+        const baseContext = await this.options.contextFactory();
+        const ctx = overrideContext
+            ? { ...baseContext, ...overrideContext }
+            : baseContext;
+        // 2. Build args with discriminator
+        const builtArgs = {
+            action: actionName,
+            ...(args || {}),
+        };
+        // 3. Run the REAL pipeline (validation → middleware → handler → presenter → egress)
+        const rawResponse = await this.registry.routeCall(ctx, toolName, builtArgs);
+        // 4. Error path — no MVA meta on error responses
+        if (rawResponse.isError) {
+            const errorText = rawResponse.content?.[0]?.text ?? 'Unknown error';
+            return {
+                data: errorText,
+                systemRules: [],
+                uiBlocks: [],
+                isError: true,
+                rawResponse,
+            };
+        }
+        // 5. Extract MVA Meta via Symbol Backdoor
+        const meta = rawResponse[MVA_META_SYMBOL];
+        if (meta) {
+            return {
+                data: meta.data,
+                systemRules: [...meta.systemRules],
+                uiBlocks: [...meta.uiBlocks],
+                isError: false,
+                rawResponse,
+            };
+        }
+        // 6. Fallback — tool without Presenter (raw data, no MVA layers)
+        const rawText = rawResponse.content?.[0]?.text ?? '';
+        let parsedData;
+        try {
+            parsedData = JSON.parse(rawText);
+        }
+        catch {
+            parsedData = rawText;
+        }
+        return {
+            data: parsedData,
+            systemRules: [],
+            uiBlocks: [],
+            isError: false,
+            rawResponse,
+        };
+    }
+}
+// ── Factory ──────────────────────────────────────────────
+/**
+ * Create a FusionTester for the given registry.
+ *
+ * @param registry - The application's ToolRegistry instance
+ * @param options - Context factory and configuration
+ * @returns A new FusionTester instance
+ *
+ * @example
+ * ```typescript
+ * const tester = createFusionTester(registry, {
+ *     contextFactory: () => ({
+ *         prisma: mockPrisma,
+ *         tenantId: 't_enterprise_42',
+ *     }),
+ * });
+ * ```
+ */
+export function createFusionTester(registry, options) {
+    return new FusionTester(registry, options);
+}
+//# sourceMappingURL=FusionTester.js.map

package/dist/FusionTester.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FusionTester.js","sourceRoot":"","sources":["../src/FusionTester.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAI3D,4DAA4D;AAE5D;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IAEA;IACA;IAFrB,YACqB,QAAgC,EAChC,OAAgC;QADhC,aAAQ,GAAR,QAAQ,CAAwB;QAChC,YAAO,GAAP,OAAO,CAAyB;IAClD,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,KAAK,CAAC,UAAU,CACZ,QAAgB,EAChB,UAAkB,EAClB,IAAY,EACZ,eAAmC;QAEnC,uBAAuB;QACvB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,eAAe;YACvB,CAAC,CAAC,EAAE,GAAG,WAAW,EAAE,GAAG,eAAe,EAAc;YACpD,CAAC,CAAC,WAAW,CAAC;QAElB,mCAAmC;QACnC,MAAM,SAAS,GAA4B;YACvC,MAAM,EAAE,UAAU;YAClB,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;SAClB,CAAC;QAEF,oFAAoF;QACpF,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QAE5E,iDAAiD;QACjD,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,eAAe,CAAC;YACpE,OAAO;gBACH,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,EAAE;gBACf,QAAQ,EAAE,EAAE;gBACZ,OAAO,EAAE,IAAI;gBACb,WAAW;aACd,CAAC;QACN,CAAC;QAED,0CAA0C;QAC1C,MAAM,IAAI,GAAI,WAAkD,CAAC,eAAe,CAAwB,CAAC;QAEzG,IAAI,IAAI,EAAE,CAAC;YACP,OAAO;gBACH,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;gBAClC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC5B,OAAO,EAAE,KAAK;gBACd,WAAW;aACd,CAAC;QACN,CAAC;QAED,iEAAiE;QACjE,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;QACrD,IAAI,UAAmB,CAAC;QACxB,IAAI,CAAC;YAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,UAAU,GAAG,OAAO,CAAC;QAAC,CAAC;QAEzE,OAAO;YACH,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,KAAK;YACd,WAAW;SACd,CAAC;IACN,CAAC;CACJ;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAC9B,QAAgC,EAChC,OAAgC;IAEhC,OAAO,IAAI,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 /**
- * @vinkius-core/mcp-fusion-testing
+ * @vinkius-core/mcp-fusion-testing — Barrel Export
  *
- * Testing utilities for MCP Fusion.
- * Provides mock servers, test clients, and assertion helpers
- * for developing and testing MCP tools.
+ * Public API for the in-memory MVA lifecycle emulator.
+ *
+ * @module
  */
-export {};
+export { FusionTester, createFusionTester } from './FusionTester.js';
+export type { TesterOptions, MvaTestResult } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,10 +1,9 @@
 /**
- * @vinkius-core/mcp-fusion-testing
+ * @vinkius-core/mcp-fusion-testing — Barrel Export
  *
- * Testing utilities for MCP Fusion.
- * Provides mock servers, test clients, and assertion helpers
- * for developing and testing MCP tools.
+ * Public API for the in-memory MVA lifecycle emulator.
+ *
+ * @module
  */
-// Testing utilities will be added here in future releases.
-export {};
+export { FusionTester, createFusionTester } from './FusionTester.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MVA Test Result Types — Structured Response Decomposition
+ *
+ * Zero coupling to any test runner. Returns plain JS/TS objects
+ * that any framework (Vitest, Jest, Mocha, node:test) can assert against.
+ *
+ * @module
+ */
+/**
+ * Configuration for the FusionTester.
+ *
+ * @typeParam TContext - Application context type (same as your ToolRegistry)
+ */
+export interface TesterOptions<TContext> {
+    /**
+     * Factory that produces the mock context for each test invocation.
+     * Inject fake Prisma, fake JWT, fake tenantId here.
+     *
+     * @example
+     * ```typescript
+     * contextFactory: () => ({
+     *     prisma: mockPrisma,
+     *     tenantId: 't_777',
+     *     auth: { role: 'ADMIN' },
+     * })
+     * ```
+     */
+    contextFactory: () => TContext | Promise<TContext>;
+}
+/**
+ * Decomposed MVA response from the FusionTester.
+ *
+ * Each field maps to a specific MVA layer, allowing QA to assert
+ * each pillar independently without parsing XML or JSON strings.
+ *
+ * @typeParam TData - The validated data type (post-Egress Firewall)
+ */
+export interface MvaTestResult<TData = unknown> {
+    /**
+     * Validated data AFTER the Egress Firewall (Presenter Zod schema).
+     * Hidden fields (`@fusion.hide`) are physically absent here.
+     */
+    data: TData;
+    /**
+     * JIT system rules from the Presenter's `.systemRules()`.
+     * The LLM reads these as domain-level directives.
+     */
+    systemRules: readonly string[];
+    /**
+     * SSR UI blocks from the Presenter's `.uiBlocks()` / `.collectionUiBlocks()`.
+     * Contains echarts configs, markdown blocks, summary strings, etc.
+     */
+    uiBlocks: readonly unknown[];
+    /**
+     * `true` if the pipeline returned an error response (`isError: true`).
+     * Useful for asserting OOM guard rejections, middleware blocks, and handler errors.
+     */
+    isError: boolean;
+    /**
+     * The raw MCP `ToolResponse` from the pipeline.
+     * For protocol-level inspection (content blocks, XML formatting, etc.)
+     */
+    rawResponse: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ;IACnC;;;;;;;;;;;;OAYG;IACH,cAAc,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO;IAC1C;;;OAGG;IACH,IAAI,EAAE,KAAK,CAAC;IAEZ;;;OAGG;IACH,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/B;;;OAGG;IACH,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAE7B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * MVA Test Result Types — Structured Response Decomposition
+ *
+ * Zero coupling to any test runner. Returns plain JS/TS objects
+ * that any framework (Vitest, Jest, Mocha, node:test) can assert against.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vinkius-core/mcp-fusion-testing",
-    "version": "1.0.0",
-    "description": "Testing utilities for MCP Fusion — mock servers, test clients, and assertion helpers for MCP tool development.",
+    "version": "1.0.1",
+    "description": "In-memory MVA lifecycle emulator for MCP Fusion. Runs the full pipeline (Zod Input → Middlewares → Handler → Egress Firewall) without network transport. Returns structured MvaTestResult objects — zero coupling to Jest/Vitest.",
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -13,8 +13,20 @@
     },
     "scripts": {
         "build": "tsc",
+        "test": "vitest run",
         "prepublishOnly": "npm run build"
     },
+    "keywords": [
+        "mcp",
+        "mcp-fusion",
+        "testing",
+        "mva",
+        "emulator",
+        "ai",
+        "llm",
+        "soc2",
+        "compliance"
+    ],
     "author": "Vinkius Labs",
     "repository": {
         "type": "git",
@@ -24,7 +36,7 @@
     "bugs": {
         "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
     },
-    "homepage": "https://vinkius-labs.github.io/mcp-fusion/",
+    "homepage": "https://mcp-fusion.vinkius.com/",
     "files": [
         "dist",
         "README.md"
@@ -36,7 +48,11 @@
         "access": "public"
     },
     "peerDependencies": {
-        "@vinkius-core/mcp-fusion": "^2.0.0"
+        "@vinkius-core/mcp-fusion": "^2.0.0",
+        "zod": "^3.25.1 || ^4.0.0"
     },
-    "license": "Apache-2.0"
-}
+    "license": "Apache-2.0",
+    "devDependencies": {
+        "@vinkius-core/mcp-fusion": ">=2.14.0"
+    }
+}