@vinkius-core/testing 1.0.0

package/README.md

@@ -0,0 +1,494 @@
+# @vinkius-core/testing
+
+<div align="center">
+  <strong>The official test runner for MCP Fusion applications.</strong>
+  <br />
+  In-memory MVA lifecycle emulator — runs the full execution pipeline without network transport.
+  <br /><br />
+
+  [![npm version](https://img.shields.io/npm/v/@vinkius-core/testing.svg?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@vinkius-core/testing)
+  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](package.json)
+  [![Runner Agnostic](https://img.shields.io/badge/runner-agnostic-purple.svg?style=flat-square)](package.json)
+</div>
+
+---
+
+## 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 |
+
+---
+
+## Install
+
+```bash
+npm install @vinkius-core/testing
+```
+
+### Peer Dependencies
+
+| Package | Version |
+|---|---|
+| `@vinkius-core/mcp-fusion` | `^2.0.0` |
+| `zod` | `^3.25.1 \|\| ^4.0.0` |
+
+> **Zero runtime dependencies.** The package ships only TypeScript types and one class. Your test runner (Vitest, Jest, Mocha, `node:test`) is your choice.
+
+---
+
+## Quick Start
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createFusionTester } from '@vinkius-core/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>;
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `contextFactory` | `() => TContext \| Promise<TContext>` | Factory that produces the mock context for each call. Inject fake Prisma, auth tokens, tenant IDs here. Supports async (e.g., DB lookup). |
+
+### `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, FusionTester injects it |
+| `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.
+
+```typescript
+interface MvaTestResult<TData = unknown> {
+    data: TData;
+    systemRules: readonly string[];
+    uiBlocks: readonly unknown[];
+    isError: boolean;
+    rawResponse: unknown;
+}
+```
+
+| 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()` / `.collectionUiBlocks()` | SSR UI blocks (charts, summaries, markdown). Empty array if no Presenter. |
+| `isError` | `boolean` | Pipeline | `true` if Zod rejected the input, middleware blocked, or handler returned `error()`. |
+| `rawResponse` | `unknown` | Pipeline | The raw MCP `ToolResponse` for protocol-level inspection. |
+
+---
+
+## Cookbook
+
+### Egress Firewall Audit
+
+Verify that the Presenter's Zod schema physically strips sensitive fields:
+
+```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');
+        expect(user).not.toHaveProperty('internalFlags');
+    }
+});
+```
+
+### OOM Guard (Input Validation)
+
+Verify that Zod boundaries reject out-of-range values:
+
+```typescript
+it('rejects take > 50 (OOM Guard)', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 10000 });
+    expect(result.isError).toBe(true);
+});
+
+it('rejects non-integer take', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 3.14 });
+    expect(result.isError).toBe(true);
+});
+
+it('rejects invalid email format', async () => {
+    const result = await tester.callAction('db_user', 'create', {
+        email: 'not-an-email', name: 'Test',
+    });
+    expect(result.isError).toBe(true);
+});
+```
+
+### Agent Limit (Cognitive Guardrail)
+
+Verify that collections are truncated to prevent context window exhaustion:
+
+```typescript
+it('truncates at agentLimit', async () => {
+    // Handler returns 100 items, Presenter has agentLimit(20)
+    const result = await tester.callAction('analytics', 'list', { limit: 100 });
+    expect((result.data as any[]).length).toBe(20);
+});
+
+it('shows truncation warning in UI blocks', async () => {
+    const result = await tester.callAction('analytics', 'list', { limit: 100 });
+    const warning = result.uiBlocks.find((b: any) => b.content?.includes('Truncated'));
+    expect(warning).toBeDefined();
+});
+```
+
+### Middleware Guards (RBAC)
+
+Test authentication and authorization middleware using `overrideContext`:
+
+```typescript
+it('blocks GUEST role', async () => {
+    const result = await tester.callAction(
+        'db_user', 'find_many', { take: 5 },
+        { role: 'GUEST' },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.data).toContain('Unauthorized');
+});
+
+it('allows ADMIN role', async () => {
+    const result = await tester.callAction(
+        'db_user', 'find_many', { take: 5 },
+        { role: 'ADMIN' },
+    );
+    expect(result.isError).toBe(false);
+});
+
+it('blocks across all actions (not just find_many)', async () => {
+    const result = await tester.callAction(
+        'db_user', 'create', { email: 'test@co.com', name: 'Test' },
+        { role: 'VIEWER' },
+    );
+    expect(result.isError).toBe(true);
+});
+```
+
+### System Rules Verification
+
+Assert that the LLM receives correct domain directives:
+
+```typescript
+it('injects domain rules from Presenter', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 1 });
+
+    expect(result.systemRules).toContain(
+        'Data originates from the database via Prisma ORM.'
+    );
+    expect(result.systemRules).toContain(
+        'Email addresses are PII. Mask when possible.'
+    );
+});
+
+it('injects contextual rules based on role', async () => {
+    const result = await tester.callAction(
+        'analytics', 'list', { limit: 1 },
+        { role: 'ADMIN' },
+    );
+    expect(result.systemRules).toContain('User is ADMIN. Show full details.');
+});
+```
+
+### UI Block Inspection
+
+Verify SSR blocks are generated for client rendering:
+
+```typescript
+it('generates collection summary', async () => {
+    const result = await tester.callAction('analytics', 'list', { limit: 5 });
+
+    const summary = result.uiBlocks.find((b: any) => b.type === 'summary') as any;
+    expect(summary).toBeDefined();
+    expect(summary.content).toContain('Total:');
+});
+```
+
+### Manual `response()` Builder
+
+Test actions that use the `response()` builder directly (without a Presenter):
+
+```typescript
+it('extracts rules from manual builder', async () => {
+    const result = await tester.callAction('system', 'health');
+
+    expect(result.systemRules).toContain('System is operational.');
+    expect(result.data).toEqual({ status: 'healthy', uptime: 42 });
+});
+```
+
+### Context Override Isolation
+
+Verify that overrides don't leak between test calls:
+
+```typescript
+it('isolates context between sequential calls', async () => {
+    // Call 1 — GUEST (blocked)
+    const r1 = await tester.callAction('db_user', 'find_many', { take: 1 }, { role: 'GUEST' });
+
+    // Call 2 — default ADMIN (succeeds)
+    const r2 = await tester.callAction('db_user', 'find_many', { take: 1 });
+
+    expect(r1.isError).toBe(true);
+    expect(r2.isError).toBe(false);
+});
+```
+
+### Async Context Factory
+
+Simulate async DI resolution (e.g., reading JWT from a database):
+
+```typescript
+const tester = createFusionTester(registry, {
+    contextFactory: async () => {
+        const token = await fetchTestToken();
+        return {
+            prisma: mockPrisma,
+            tenantId: token.tenantId,
+            role: token.role,
+        };
+    },
+});
+```
+
+### Protocol-Level Inspection
+
+Inspect the raw MCP `ToolResponse` for transport-level assertions:
+
+```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');
+});
+
+it('Symbol metadata is invisible to JSON.stringify', async () => {
+    const result = await tester.callAction('db_user', 'find_many', { take: 1 });
+    const json = JSON.stringify(result.rawResponse);
+
+    // Transport layer never sees MVA metadata
+    expect(json).not.toContain('systemRules');
+    expect(json).not.toContain('mva-meta');
+});
+```
+
+---
+
+## Architecture
+
+### The Symbol Backdoor
+
+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.
+
+```typescript
+// What the MCP transport sees (JSON.stringify):
+{ "content": [{ "type": "text", "text": "{...}" }] }
+
+// What FusionTester reads (Symbol key):
+response[Symbol.for('mcp-fusion.mva-meta')] = {
+    data: { id: '1', name: 'Alice', email: 'alice@acme.com' },
+    systemRules: ['Data from Prisma ORM...'],
+    uiBlocks: [{ type: 'summary', content: 'User: Alice' }],
+};
+```
+
+**No XML regex. No string parsing. Zero coupling to response formatting.**
+
+### Why not reimplement the pipeline?
+
+The tester calls `ToolRegistry.routeCall()` — the same function your production server uses. If we reimplemented the pipeline, tests would pass in the tester but fail in production. Full fidelity means:
+
+- ✅ Concurrency semaphore limits
+- ✅ Mutation serialization
+- ✅ Abort signal propagation
+- ✅ Egress payload guards
+- ✅ Zod error formatting
+- ✅ Generator result draining
+
+---
+
+## MVA Convention: `tests/` Layer
+
+The testing package introduces a fourth layer to the MVA convention:
+
+```text
+src/
+├── models/         ← M — Zod schemas
+├── views/          ← V — Presenters
+├── agents/         ← A — MCP tool definitions
+├── index.ts        ← Registry barrel
+└── server.ts       ← Server bootstrap
+tests/
+├── firewall/       ← Egress Firewall assertions
+├── guards/         ← Middleware & OOM Guard tests
+├── rules/          ← System Rules verification
+└── setup.ts        ← Shared tester instance
+```
+
+### Recommended `setup.ts`
+
+```typescript
+// tests/setup.ts
+import { createFusionTester } from '@vinkius-core/testing';
+import { registry } from '../src/index.js';
+
+export const tester = createFusionTester(registry, {
+    contextFactory: () => ({
+        prisma: mockPrisma,
+        tenantId: 't_test',
+        role: 'ADMIN',
+    }),
+});
+```
+
+### File Naming
+
+| Directory | Suffix | What it tests |
+|---|---|---|
+| `tests/firewall/` | `.firewall.test.ts` | Presenter Zod filtering (PII, hidden fields) |
+| `tests/guards/` | `.guard.test.ts` | Middleware RBAC, OOM limits, input validation |
+| `tests/rules/` | `.rules.test.ts` | System rules injection, contextual rules |
+| `tests/blocks/` | `.blocks.test.ts` | UI blocks, collection summaries, truncation warnings |
+
+---
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.7+
+- `@vinkius-core/mcp-fusion ^2.0.0`
+- `zod ^3.25.1 || ^4.0.0`
+
+## Documentation
+
+Full docs: **[vinkius-labs.github.io/mcp-fusion](https://vinkius-labs.github.io/mcp-fusion/)**.

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/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

@@ -0,0 +1,10 @@
+/**
+ * @vinkius-core/testing — Barrel Export
+ *
+ * Public API for the in-memory MVA lifecycle emulator.
+ *
+ * @module
+ */
+export { FusionTester, createFusionTester } from './FusionTester.js';
+export type { TesterOptions, MvaTestResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,9 @@
+/**
+ * @vinkius-core/testing — Barrel Export
+ *
+ * Public API for the in-memory MVA lifecycle emulator.
+ *
+ * @module
+ */
+export { FusionTester, createFusionTester } from './FusionTester.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,55 @@
+{
+    "name": "@vinkius-core/testing",
+    "version": "1.0.0",
+    "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",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "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",
+        "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
+        "directory": "packages/testing"
+    },
+    "bugs": {
+        "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
+    },
+    "homepage": "https://vinkius-labs.github.io/mcp-fusion/",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "@vinkius-core/mcp-fusion": "^2.0.0",
+        "zod": "^3.25.1 || ^4.0.0"
+    },
+    "license": "Apache-2.0"
+}