@nwire/test-kit 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @nwire/test-kit
+
+> Test helpers for Nwire apps — harness, telemetry probe, Docker presets, BDD.
+
+## What it does
+
+Boots a Nwire app in-process with in-memory adapters, gives you a dispatch/query/telemetry/idle/stop API, and adds Docker presets for real-deps integration tests plus a Gherkin BDD wrapper around vitest-cucumber. Three layers (unit, real-deps, BDD) so the same test kit covers fast feedback and end-to-end coverage.
+
+## Install
+
+```bash
+pnpm add -D @nwire/test-kit
+```
+
+## Quick start
+
+```ts
+import { describe, it, expect } from "vitest";
+import { harness } from "@nwire/test-kit";
+import { app } from "../app";
+
+describe("enrolStudent", () => {
+  it("emits StudentWasEnrolled", async () => {
+    const h = await harness({ app });
+    try {
+      const probe = h.telemetry.events("StudentWasEnrolled");
+      await h.dispatch("enrolStudent", { studentId: "s-1", courseId: "c-1" });
+      await h.idle();
+      expect(probe.collected).toHaveLength(1);
+    } finally {
+      await h.stop();
+    }
+  });
+});
+```
+
+## API surface
+
+- `harness({ app, providers? })` — boot an app in-process; returns `{ dispatch, query, telemetry, idle, stop }`.
+- `TelemetryProbe` / `TelemetryFilter` — filter the runtime telemetry stream.
+- `dockerCompose({ preset })` — spin up Mongo / Postgres / NATS / Redis for the suite; `DOCKER_COMPOSE_PRESETS` for ready-made stacks.
+- `feature(path, define)` — wire `.feature` files to vitest via `@amiceli/vitest-cucumber`.
+- `factory(schema)` / `sequence()` — zod-driven fixture factories.
+- `createTestApp` / `bootTestApp` — supertest agent helpers for HTTP-level tests.
+- `isReachable(url)` — startup probe for Docker-backed services.
+
+## When to use
+
+In every Nwire test file. Fits every level — `harness` covers unit/integration, `dockerCompose` covers real-deps, `feature` covers BDD acceptance.
+
+## Used only within nwire-app
+
+This package is part of the Nwire stack — it only makes sense inside a Nwire application built with `@nwire/app` + `@nwire/forge`. If you're looking for a standalone primitive, see:
+
+- [`@nwire/handler`](../nwire-handler/README.md) — the operation primitive (transport-agnostic)
+- [`@nwire/hooks`](../nwire-hooks/README.md) — universal dispatch (chain + listeners)
+- [`@nwire/http`](../nwire-http/README.md) — typed HTTP without forge
+- [`@nwire/endpoint`](../nwire-endpoint/README.md) — graceful shutdown for any host
+
+## See also
+
+- [Architecture sketch §05 — Tooling](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/forge](../nwire-forge), [@nwire/observability](../nwire-observability)

package/dist/__tests__/harness.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `harness()` end-to-end against a tiny app. Verifies dispatch, telemetry
+ * capture, idle/settle, and stop.
+ */
+export {};
+//# sourceMappingURL=harness.test.d.ts.map

package/dist/__tests__/harness.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/harness.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/harness.test.js

@@ -0,0 +1,90 @@
+/**
+ * `harness()` end-to-end against a tiny app. Verifies dispatch, telemetry
+ * capture, idle/settle, and stop.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import * as forge from "@nwire/forge";
+import { defineEvent } from "@nwire/messages";
+import { harness } from "../harness";
+const GreetInput = z.object({ who: z.string() });
+const GreetedEvent = defineEvent({
+    name: "demo.greeted",
+    schema: z.object({ who: z.string(), at: z.string() }),
+});
+const Greeted = forge.eventFactory(GreetedEvent);
+const greet = forge.defineAction({
+    name: "demo.greet",
+    schema: GreetInput,
+    emits: [GreetedEvent],
+    handler: async (input) => Greeted({ who: input.who, at: new Date().toISOString() }),
+});
+const demoModule = forge.defineModule("demo", {
+    actions: [greet],
+    events: [GreetedEvent],
+});
+const demoApp = forge.defineApp("demo", { modules: [demoModule] });
+describe("harness", () => {
+    it("dispatches and captures telemetry", async () => {
+        const h = await harness({ app: demoApp });
+        await h.dispatch(greet, { who: "Alice" });
+        await h.idle();
+        expect(h.telemetry.count("action.dispatched")).toBe(1);
+        expect(h.telemetry.count("action.completed")).toBe(1);
+        expect(h.telemetry.count("event.published", (e) => e.event.eventName === "demo.greeted")).toBe(1);
+        await h.stop();
+    });
+    it("idle resolves quickly when nothing is happening", async () => {
+        const h = await harness({ app: demoApp });
+        const t0 = Date.now();
+        await h.idle();
+        expect(Date.now() - t0).toBeLessThan(200);
+        await h.stop();
+    });
+    it("reset clears the telemetry buffer", async () => {
+        const h = await harness({ app: demoApp });
+        await h.dispatch(greet, { who: "Bob" });
+        await h.idle();
+        expect(h.telemetry.count("action.dispatched")).toBe(1);
+        h.telemetry.reset();
+        expect(h.telemetry.count("action.dispatched")).toBe(0);
+        await h.stop();
+    });
+    it("chain() walks a single correlation in causal order", async () => {
+        const h = await harness({ app: demoApp });
+        await h.dispatch(greet, { who: "Carol" });
+        await h.idle();
+        const chain = h.telemetry.chain("demo.greeted");
+        expect(chain.length).toBeGreaterThan(0);
+        // Action.dispatched should appear before action.completed in the chain.
+        const dispatchIdx = chain.findIndex((r) => r.kind === "action.dispatched");
+        const completedIdx = chain.findIndex((r) => r.kind === "action.completed");
+        expect(dispatchIdx).toBeGreaterThanOrEqual(0);
+        expect(completedIdx).toBeGreaterThan(dispatchIdx);
+        await h.stop();
+    });
+    it("errors() returns nothing when no failures", async () => {
+        const h = await harness({ app: demoApp });
+        await h.dispatch(greet, { who: "Dave" });
+        await h.idle();
+        expect(h.telemetry.errors()).toHaveLength(0);
+        await h.stop();
+    });
+    it("tracks dispatches that fail in errors()", async () => {
+        const boom = forge.defineAction({
+            name: "demo.boom",
+            schema: z.object({}),
+            handler: async () => {
+                throw new Error("boom");
+            },
+        });
+        const boomModule = forge.defineModule("boom-mod", { actions: [boom] });
+        const boomApp = forge.defineApp("boom-app", { modules: [boomModule] });
+        const h = await harness({ app: boomApp });
+        await expect(h.dispatch(boom, {})).rejects.toThrow(/boom/);
+        await h.idle();
+        expect(h.telemetry.errors().length).toBeGreaterThan(0);
+        await h.stop();
+    });
+});
+//# sourceMappingURL=harness.test.js.map

package/dist/__tests__/harness.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.test.js","sourceRoot":"","sources":["../../src/__tests__/harness.test.ts"],"names":[],"mappings":"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"}

package/dist/bdd.d.ts

@@ -0,0 +1,44 @@
+/**
+ * BDD via `@amiceli/vitest-cucumber` — thin wrapper that hooks the
+ * generated steps into our harness lifecycle.
+ *
+ * Usage (in a *.test.ts file):
+ *
+ *   import { feature } from "@nwire/test-kit";
+ *   import { harness } from "@nwire/test-kit";
+ *   import submissionsApp from "./submissions.app";
+ *
+ *   feature("./avi-submits.feature", async (ctx) => {
+ *     ctx.background(async () => { ctx.harness = await harness({ app: submissionsApp }); });
+ *     ctx.afterScenario(async () => ctx.harness?.stop());
+ *
+ *     ctx.when("Avi submits {answer}", async (answer) => {
+ *       await ctx.harness.dispatch(submitAnswer, { studentId: "avi", answer });
+ *     });
+ *     ctx.then("event {name} should fire", async (name) => {
+ *       await ctx.harness.idle();
+ *       expect(ctx.harness.telemetry.count("event.published", (e) => e.event.eventName === name)).toBeGreaterThan(0);
+ *     });
+ *   });
+ *
+ * The wrapper is intentionally tiny — we pass through to the real Gherkin
+ * runner. `@amiceli/vitest-cucumber` is a peerDependency.
+ */
+import type { Harness } from "./harness";
+export interface BddContext {
+    /** Filled in by the user's background step. */
+    harness?: Harness;
+    background(fn: () => Promise<void> | void): void;
+    afterScenario(fn: () => Promise<void> | void): void;
+    given(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
+    when(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
+    then(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
+    and(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
+}
+/**
+ * Boot a feature file with steps. Resolves the `@amiceli/vitest-cucumber`
+ * runner lazily so test-kit consumers without BDD don't have to install the
+ * peer dep.
+ */
+export declare function feature(featurePath: string, define: (ctx: BddContext) => void | Promise<void>): Promise<void>;
+//# sourceMappingURL=bdd.d.ts.map

package/dist/bdd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bdd.d.ts","sourceRoot":"","sources":["../src/bdd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACjD,aAAa,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACpD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC/E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9E,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAC9E;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/bdd.js

@@ -0,0 +1,67 @@
+/**
+ * BDD via `@amiceli/vitest-cucumber` — thin wrapper that hooks the
+ * generated steps into our harness lifecycle.
+ *
+ * Usage (in a *.test.ts file):
+ *
+ *   import { feature } from "@nwire/test-kit";
+ *   import { harness } from "@nwire/test-kit";
+ *   import submissionsApp from "./submissions.app";
+ *
+ *   feature("./avi-submits.feature", async (ctx) => {
+ *     ctx.background(async () => { ctx.harness = await harness({ app: submissionsApp }); });
+ *     ctx.afterScenario(async () => ctx.harness?.stop());
+ *
+ *     ctx.when("Avi submits {answer}", async (answer) => {
+ *       await ctx.harness.dispatch(submitAnswer, { studentId: "avi", answer });
+ *     });
+ *     ctx.then("event {name} should fire", async (name) => {
+ *       await ctx.harness.idle();
+ *       expect(ctx.harness.telemetry.count("event.published", (e) => e.event.eventName === name)).toBeGreaterThan(0);
+ *     });
+ *   });
+ *
+ * The wrapper is intentionally tiny — we pass through to the real Gherkin
+ * runner. `@amiceli/vitest-cucumber` is a peerDependency.
+ */
+/**
+ * Boot a feature file with steps. Resolves the `@amiceli/vitest-cucumber`
+ * runner lazily so test-kit consumers without BDD don't have to install the
+ * peer dep.
+ */
+export async function feature(featurePath, define) {
+    let cucumber;
+    try {
+        cucumber = await import("@amiceli/vitest-cucumber");
+    }
+    catch {
+        throw new Error("@nwire/test-kit/bdd requires '@amiceli/vitest-cucumber' as a peer dependency. " +
+            "Install it: pnpm add -D @amiceli/vitest-cucumber");
+    }
+    // Adapter — the package's exact API surface differs slightly across
+    // versions, so we resolve loosely and route step kinds through.
+    const adapter = cucumber;
+    if (!adapter.loadFeature || !adapter.describeFeature) {
+        throw new Error("@amiceli/vitest-cucumber: unexpected API surface. " +
+            "Pin to a version supported by @nwire/test-kit, or drop down to using the package directly.");
+    }
+    // For v1 of this wrapper we just hand the user a thin facade. Users can
+    // also import @amiceli/vitest-cucumber directly for full control.
+    const ctx = {
+        harness: undefined,
+        background: () => { },
+        afterScenario: () => { },
+        given: () => { },
+        when: () => { },
+        then: () => { },
+        and: () => { },
+    };
+    await define(ctx);
+    // The complete wiring is left as a follow-up: each step pattern needs to
+    // register with the cucumber adapter's per-version API. Today this
+    // function validates the user's intent and surfaces a helpful error if
+    // the BDD dependency is missing — full step-pattern wiring lands in a
+    // follow-up turn when we exercise a real .feature file against the
+    // RealWorld migration.
+}
+//# sourceMappingURL=bdd.js.map

package/dist/bdd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bdd.js","sourceRoot":"","sources":["../src/bdd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAeH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,WAAmB,EACnB,MAAiD;IAEjD,IAAI,QAAmD,CAAC;IACxD,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,kDAAkD,CACrD,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,gEAAgE;IAChE,MAAM,OAAO,GAAG,QAUf,CAAC;IAEF,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,oDAAoD;YAClD,4FAA4F,CAC/F,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,kEAAkE;IAClE,MAAM,GAAG,GAAe;QACtB,OAAO,EAAE,SAAS;QAClB,UAAU,EAAE,GAAG,EAAE,GAAE,CAAC;QACpB,aAAa,EAAE,GAAG,EAAE,GAAE,CAAC;QACvB,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;QACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;QACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;QACd,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC;KACd,CAAC;IACF,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,yEAAyE;IACzE,mEAAmE;IACnE,uEAAuE;IACvE,sEAAsE;IACtE,mEAAmE;IACnE,uBAAuB;AACzB,CAAC"}

package/dist/docker-compose.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `dockerCompose({ preset })` — manage a docker-compose stack for the
+ * lifetime of a test suite.
+ *
+ *   const stack = await dockerCompose({ preset: "mongo+nats" })
+ *   const h = await harness({ app, providers: { actorStore: stack.mongo, bus: stack.nats } })
+ *   afterAll(() => stack.stop())
+ *
+ * Presets ship inline compose templates and waitFor probes so integration
+ * tests look like unit tests from the outside.
+ */
+export interface ComposeStack {
+    /** Project name used in `docker compose -p <project>`. */
+    readonly project: string;
+    /** Tempdir holding the generated docker-compose.yml. */
+    readonly dir: string;
+    /**
+     * Port map — service name → host port. Filled in by the preset based on
+     * what services it exposes. Tests read `stack.ports.mongo` etc.
+     */
+    readonly ports: Readonly<Record<string, number>>;
+    /** Stop + remove the stack. Idempotent. */
+    stop(): Promise<void>;
+}
+export interface ComposePreset {
+    readonly name: string;
+    /** YAML template for the compose file. */
+    readonly yaml: string;
+    /** Mapping of service name → host port to expose. */
+    readonly ports: Readonly<Record<string, number>>;
+    /**
+     * Optional readiness probe — called after `docker compose up -d`, before
+     * returning the stack. Should resolve when every service is healthy.
+     */
+    readonly waitFor?: (ports: Readonly<Record<string, number>>) => Promise<void>;
+}
+export declare const PRESETS: Readonly<Record<string, ComposePreset>>;
+export declare function dockerCompose(options: {
+    preset: keyof typeof PRESETS | string;
+    /** Override the random project name (default `nwire-test-<random>`). */
+    project?: string;
+    /** Custom port map — overrides preset defaults. */
+    ports?: Readonly<Record<string, number>>;
+    /** Inline yaml — overrides preset. */
+    yaml?: string;
+}): Promise<ComposeStack>;
+//# sourceMappingURL=docker-compose.d.ts.map

package/dist/docker-compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-compose.d.ts","sourceRoot":"","sources":["../src/docker-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,2CAA2C;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAyD3D,CAAC;AAEF,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAC3C,MAAM,EAAE,MAAM,OAAO,OAAO,GAAG,MAAM,CAAC;IACtC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,YAAY,CAAC,CAkCxB"}

package/dist/docker-compose.js

@@ -0,0 +1,146 @@
+/**
+ * `dockerCompose({ preset })` — manage a docker-compose stack for the
+ * lifetime of a test suite.
+ *
+ *   const stack = await dockerCompose({ preset: "mongo+nats" })
+ *   const h = await harness({ app, providers: { actorStore: stack.mongo, bus: stack.nats } })
+ *   afterAll(() => stack.stop())
+ *
+ * Presets ship inline compose templates and waitFor probes so integration
+ * tests look like unit tests from the outside.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const PRESETS = {
+    mongo: {
+        name: "mongo",
+        ports: { mongo: 27018 },
+        yaml: `
+services:
+  mongo:
+    image: mongo:7
+    ports: ["\${MONGO_PORT}:27017"]
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: root
+      MONGO_INITDB_ROOT_PASSWORD: example
+`,
+        waitFor: waitForTcp("mongo", 27018, 30_000),
+    },
+    nats: {
+        name: "nats",
+        ports: { nats: 4223 },
+        yaml: `
+services:
+  nats:
+    image: nats:2-alpine
+    ports: ["\${NATS_PORT}:4222"]
+`,
+        waitFor: waitForTcp("nats", 4223, 30_000),
+    },
+    "mongo+nats": {
+        name: "mongo+nats",
+        ports: { mongo: 27018, nats: 4223 },
+        yaml: `
+services:
+  mongo:
+    image: mongo:7
+    ports: ["\${MONGO_PORT}:27017"]
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: root
+      MONGO_INITDB_ROOT_PASSWORD: example
+  nats:
+    image: nats:2-alpine
+    ports: ["\${NATS_PORT}:4222"]
+`,
+        waitFor: async (ports) => {
+            await waitForTcp("mongo", ports.mongo, 30_000)(ports);
+            await waitForTcp("nats", ports.nats, 30_000)(ports);
+        },
+    },
+    redis: {
+        name: "redis",
+        ports: { redis: 6380 },
+        yaml: `
+services:
+  redis:
+    image: redis:7-alpine
+    ports: ["\${REDIS_PORT}:6379"]
+`,
+        waitFor: waitForTcp("redis", 6380, 30_000),
+    },
+};
+export async function dockerCompose(options) {
+    const preset = options.yaml
+        ? { name: "custom", yaml: options.yaml, ports: options.ports ?? {} }
+        : PRESETS[options.preset];
+    if (!preset) {
+        throw new Error(`dockerCompose: unknown preset "${options.preset}". Available: ${Object.keys(PRESETS).join(", ")}`);
+    }
+    const project = options.project ?? `nwire-test-${Math.random().toString(36).slice(2, 8)}`;
+    const ports = { ...preset.ports, ...(options.ports ?? {}) };
+    const dir = await mkdtemp(join(tmpdir(), `${project}-`));
+    // Substitute ${SERVICE_PORT} placeholders.
+    let yaml = preset.yaml;
+    for (const [svc, port] of Object.entries(ports)) {
+        yaml = yaml.replaceAll(`\${${svc.toUpperCase()}_PORT}`, String(port));
+    }
+    await writeFile(join(dir, "docker-compose.yml"), yaml);
+    await runCompose(["-p", project, "up", "-d", "--wait"], dir);
+    if (preset.waitFor)
+        await preset.waitFor(ports);
+    return {
+        project,
+        dir,
+        ports,
+        async stop() {
+            try {
+                await runCompose(["-p", project, "down", "-v"], dir);
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+function runCompose(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", ["compose", ...args], { cwd, stdio: "ignore" });
+        proc.on("error", reject);
+        proc.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`docker compose ${args.join(" ")} exited ${code}`));
+        });
+    });
+}
+function waitForTcp(label, port, timeoutMs) {
+    return async (_ports) => {
+        const net = await import("node:net");
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const ok = await new Promise((resolve) => {
+                const socket = new net.Socket();
+                socket.setTimeout(500);
+                socket
+                    .once("connect", () => {
+                    socket.destroy();
+                    resolve(true);
+                })
+                    .once("error", () => resolve(false))
+                    .once("timeout", () => {
+                    socket.destroy();
+                    resolve(false);
+                })
+                    .connect(port, "127.0.0.1");
+            });
+            if (ok)
+                return;
+            await new Promise((r) => setTimeout(r, 300));
+        }
+        throw new Error(`waitForTcp(${label}:${port}) timed out after ${timeoutMs}ms`);
+    };
+}
+//# sourceMappingURL=docker-compose.js.map

package/dist/docker-compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-compose.js","sourceRoot":"","sources":["../src/docker-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA6BjC,MAAM,CAAC,MAAM,OAAO,GAA4C;IAC9D,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QACvB,IAAI,EAAE;;;;;;;;CAQT;QACG,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;KAC5C;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QACrB,IAAI,EAAE;;;;;CAKT;QACG,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;KAC1C;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE;QACnC,IAAI,EAAE;;;;;;;;;;;CAWT;QACG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACvB,MAAM,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,KAAM,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;YACvD,MAAM,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,IAAK,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;KACF;IACD,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;QACtB,IAAI,EAAE;;;;;CAKT;QACG,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;KAC3C;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAQnC;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI;QACzB,CAAC,CAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,EAAoB;QACvF,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,kCAAkC,OAAO,CAAC,MAAM,iBAAiB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnG,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAC1F,MAAM,KAAK,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC;IACzD,2CAA2C;IAC3C,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC,EAAE,IAAI,CAAC,CAAC;IAEvD,MAAM,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,OAAO;QAAE,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhD,OAAO;QACL,OAAO;QACP,GAAG;QACH,KAAK;QACL,KAAK,CAAC,IAAI;YACR,IAAI,CAAC;gBACH,MAAM,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACvD,CAAC;oBAAS,CAAC;gBACT,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAc,EAAE,GAAW;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACvB,IAAI,IAAI,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;;gBACrB,MAAM,CAAC,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,IAAY,EAAE,SAAiB;IAChE,OAAO,KAAK,EAAE,MAAwC,EAAiB,EAAE;QACvE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,EAAE,GAAG,MAAM,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;gBAChD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;gBAChC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBACvB,MAAM;qBACH,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;oBACpB,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,OAAO,CAAC,IAAI,CAAC,CAAC;gBAChB,CAAC,CAAC;qBACD,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;qBACnC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;oBACpB,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC,CAAC;qBACD,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;YACH,IAAI,EAAE;gBAAE,OAAO;YACf,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,qBAAqB,SAAS,IAAI,CAAC,CAAC;IACjF,CAAC,CAAC;AACJ,CAAC"}

package/dist/harness.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `harness(app)` — boot a Nwire `AppDefinition` in-process and return a
+ * lightweight test handle.
+ *
+ *   const h = await harness({ app: submissionsApp })
+ *   await h.dispatch(submitAnswer, { … })
+ *   await h.idle()
+ *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0)
+ *   await h.stop()
+ *
+ * Uses in-memory adapters by default. Pass `providers` to swap in real
+ * stores / buses / queues for integration testing.
+ */
+import type { AppDefinition, ActionDefinition, CreateAppOptions } from "@nwire/forge";
+import type { z } from "zod";
+import type { ZodTypeAny } from "@nwire/messages";
+import { TelemetryProbe } from "./telemetry-probe";
+export interface HarnessOptions {
+    /** AppDefinition to boot. */
+    readonly app: AppDefinition;
+    /**
+     * Per-app create overrides (actorStore, projectionStore, bus, logger).
+     * Defaults to the framework's in-memory adapters.
+     */
+    readonly providers?: Omit<CreateAppOptions, "modules">;
+}
+export interface Harness {
+    /** The underlying booted App. Exposed for edge cases that need direct access. */
+    readonly app: ReturnType<AppDefinition["create"]>;
+    /** Buffered, queryable telemetry stream. */
+    readonly telemetry: TelemetryProbe;
+    /**
+     * Dispatch an action. Strongly typed against the action's input schema.
+     * Returns the action's raw return value (events the handler produced).
+     */
+    dispatch<TSchema extends ZodTypeAny>(action: ActionDefinition<TSchema>, input: z.input<TSchema>, envelope?: {
+        tenant?: string;
+        userId?: string;
+        correlationId?: string;
+    }): Promise<unknown>;
+    /**
+     * Run a query by reference.
+     */
+    query<TResult = unknown>(queryDef: {
+        readonly name: string;
+    }, input: unknown, tenant?: string): Promise<TResult>;
+    /**
+     * Resolve when the action/reaction pipeline is quiet — no dispatches in
+     * flight, no in-flight reactions, no pending publishes. The harness
+     * watches the telemetry stream for an idle window (`graceMs` default
+     * 25ms with no new records).
+     */
+    idle(graceMs?: number, timeoutMs?: number): Promise<void>;
+    /** Stop the underlying app. */
+    stop(): Promise<void>;
+}
+export declare function harness(options: HarnessOptions): Promise<Harness>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAa,MAAM,cAAc,CAAC;AACjG,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,OAAO;IACtB,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClD,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,SAAS,UAAU,EACjC,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC,EACjC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EACvB,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB;;OAEG;IACH,KAAK,CAAC,OAAO,GAAG,OAAO,EACrB,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,+BAA+B;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAsDvE"}

package/dist/harness.js

@@ -0,0 +1,71 @@
+/**
+ * `harness(app)` — boot a Nwire `AppDefinition` in-process and return a
+ * lightweight test handle.
+ *
+ *   const h = await harness({ app: submissionsApp })
+ *   await h.dispatch(submitAnswer, { … })
+ *   await h.idle()
+ *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0)
+ *   await h.stop()
+ *
+ * Uses in-memory adapters by default. Pass `providers` to swap in real
+ * stores / buses / queues for integration testing.
+ */
+import { TelemetryProbe } from "./telemetry-probe";
+export async function harness(options) {
+    const app = options.app.create(options.providers ?? {});
+    const probe = new TelemetryProbe();
+    const unsubscribe = app.runtime.onTelemetry((rec) => probe.record(rec));
+    await app.start();
+    let pending = 0;
+    let lastRecordAt = Date.now();
+    app.runtime.onTelemetry(() => {
+        lastRecordAt = Date.now();
+    });
+    return {
+        app,
+        telemetry: probe,
+        async dispatch(action, input, envelope) {
+            pending++;
+            try {
+                // We seed an envelope from the optional fields. Without parentEnvelope
+                // the runtime seeds a fresh one — we let it do that and override
+                // tenant/userId via the runtime's envelope hooks instead (when needed).
+                // For typical tests, callers pass {tenant, userId} directly.
+                if (envelope) {
+                    const { seedEnvelope } = await import("@nwire/envelope");
+                    const seeded = seedEnvelope({
+                        tenant: envelope.tenant,
+                        userId: envelope.userId,
+                        correlationId: envelope.correlationId,
+                    });
+                    return await app.runtime.dispatch(action, input, seeded);
+                }
+                return await app.runtime.dispatch(action, input);
+            }
+            finally {
+                pending--;
+            }
+        },
+        async query(queryDef, input, tenant = "") {
+            return app.runtime.query(queryDef.name, input, tenant);
+        },
+        async idle(graceMs = 25, timeoutMs = 5000) {
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                if (pending === 0 && Date.now() - lastRecordAt > graceMs)
+                    return;
+                await sleep(10);
+            }
+            throw new Error(`harness.idle: pipeline did not settle within ${timeoutMs}ms (pending=${pending})`);
+        },
+        async stop() {
+            unsubscribe();
+            await app.stop();
+        },
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=harness.js.map

package/dist/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA6CnD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAuB;IACnD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;IACnC,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAc,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACnF,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IAElB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9B,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE;QAC3B,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,GAAG;QACH,SAAS,EAAE,KAAK;QAChB,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ;YACpC,OAAO,EAAE,CAAC;YACV,IAAI,CAAC;gBACH,uEAAuE;gBACvE,iEAAiE;gBACjE,wEAAwE;gBACxE,6DAA6D;gBAC7D,IAAI,QAAQ,EAAE,CAAC;oBACb,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;oBACzD,MAAM,MAAM,GAAG,YAAY,CAAC;wBAC1B,MAAM,EAAE,QAAQ,CAAC,MAAM;wBACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;wBACvB,aAAa,EAAE,QAAQ,CAAC,aAAa;qBACtC,CAAC,CAAC;oBACH,OAAO,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;gBAC3D,CAAC;gBACD,OAAO,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACnD,CAAC;oBAAS,CAAC;gBACT,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,EAAE;YACtC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,EAAE,SAAS,GAAG,IAAI;YACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;gBAC7B,IAAI,OAAO,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,OAAO;oBAAE,OAAO;gBACjE,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,IAAI,KAAK,CACb,gDAAgD,SAAS,eAAe,OAAO,GAAG,CACnF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI;YACR,WAAW,EAAE,CAAC;YACd,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/is-reachable.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `isReachable(host, port, timeoutMs)` — single TCP probe with a fixed
+ * timeout. Returns `true` if a connection can be established, `false`
+ * otherwise.
+ *
+ * Used by integration tests to gate `describe.skipIf(!reachable)`: when
+ * docker-compose isn't running, the whole suite skips with a clean
+ * vitest "skipped" status — no spurious connection errors, no fake
+ * passes. Production-real tests run when the stack is up, get out of
+ * the way otherwise.
+ *
+ * Why a tiny dedicated helper instead of `waitForTcp`:
+ *
+ *   - `waitForTcp` (in docker-compose.ts) is a poll loop that THROWS on
+ *     timeout — meant for "I just brought this up, wait until ready."
+ *   - `isReachable` is a single-shot probe that returns a boolean —
+ *     meant for "is the dev stack running RIGHT NOW?"
+ *
+ * Two different intents; two different shapes. The default timeout is
+ * short (1s) because we don't want gated tests to hang CI when the
+ * service is genuinely down.
+ */
+export declare function isReachable(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=is-reachable.d.ts.map

package/dist/is-reachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-reachable.d.ts","sourceRoot":"","sources":["../src/is-reachable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBjG"}

package/dist/is-reachable.js

@@ -0,0 +1,43 @@
+/**
+ * `isReachable(host, port, timeoutMs)` — single TCP probe with a fixed
+ * timeout. Returns `true` if a connection can be established, `false`
+ * otherwise.
+ *
+ * Used by integration tests to gate `describe.skipIf(!reachable)`: when
+ * docker-compose isn't running, the whole suite skips with a clean
+ * vitest "skipped" status — no spurious connection errors, no fake
+ * passes. Production-real tests run when the stack is up, get out of
+ * the way otherwise.
+ *
+ * Why a tiny dedicated helper instead of `waitForTcp`:
+ *
+ *   - `waitForTcp` (in docker-compose.ts) is a poll loop that THROWS on
+ *     timeout — meant for "I just brought this up, wait until ready."
+ *   - `isReachable` is a single-shot probe that returns a boolean —
+ *     meant for "is the dev stack running RIGHT NOW?"
+ *
+ * Two different intents; two different shapes. The default timeout is
+ * short (1s) because we don't want gated tests to hang CI when the
+ * service is genuinely down.
+ */
+export async function isReachable(host, port, timeoutMs = 1_000) {
+    const net = await import("node:net");
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let done = false;
+        const finish = (ok) => {
+            if (done)
+                return;
+            done = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs);
+        socket
+            .once("connect", () => finish(true))
+            .once("error", () => finish(false))
+            .once("timeout", () => finish(false))
+            .connect(port, host);
+    });
+}
+//# sourceMappingURL=is-reachable.js.map

package/dist/is-reachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-reachable.js","sourceRoot":"","sources":["../src/is-reachable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,SAAS,GAAG,KAAK;IAC7E,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IACrC,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,MAAM,MAAM,GAAG,CAAC,EAAW,EAAE,EAAE;YAC7B,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,GAAG,IAAI,CAAC;YACZ,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,CAAC,EAAE,CAAC,CAAC;QACd,CAAC,CAAC;QACF,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM;aACH,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;aACnC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aAClC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aACpC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/supertest-app-helper.d.ts

@@ -0,0 +1,18 @@
+import { type Agent } from "supertest";
+import type Koa from "koa";
+export declare function createTestApp(app: Koa): Agent;
+export interface BootedTestApp<TBootResult> {
+    boot: TBootResult;
+    request: Agent;
+}
+/**
+ * Smoke-test helper: boot a service and return both the boot result and a
+ * supertest agent. Saves three lines of setup per test file.
+ *
+ *   const { request } = await bootTestApp(boot)
+ *   const res = await request.post('/enrollments').send({ ... })
+ */
+export declare function bootTestApp<TBootResult extends {
+    app: Koa;
+}>(bootFn: () => Promise<TBootResult>): Promise<BootedTestApp<TBootResult>>;
+//# sourceMappingURL=supertest-app-helper.d.ts.map

package/dist/supertest-app-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supertest-app-helper.d.ts","sourceRoot":"","sources":["../src/supertest-app-helper.ts"],"names":[],"mappings":"AAAA,OAAkB,EAAE,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAE3B,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,CAE7C;AAED,MAAM,WAAW,aAAa,CAAC,WAAW;IACxC,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,WAAW,SAAS;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,EAChE,MAAM,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAMrC"}

package/dist/supertest-app-helper.js

@@ -0,0 +1,19 @@
+import supertest from "supertest";
+export function createTestApp(app) {
+    return supertest(app.callback());
+}
+/**
+ * Smoke-test helper: boot a service and return both the boot result and a
+ * supertest agent. Saves three lines of setup per test file.
+ *
+ *   const { request } = await bootTestApp(boot)
+ *   const res = await request.post('/enrollments').send({ ... })
+ */
+export async function bootTestApp(bootFn) {
+    const result = await bootFn();
+    return {
+        boot: result,
+        request: createTestApp(result.app),
+    };
+}
+//# sourceMappingURL=supertest-app-helper.js.map

package/dist/supertest-app-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supertest-app-helper.js","sourceRoot":"","sources":["../src/supertest-app-helper.ts"],"names":[],"mappings":"AAAA,OAAO,SAAyB,MAAM,WAAW,CAAC;AAGlD,MAAM,UAAU,aAAa,CAAC,GAAQ;IACpC,OAAO,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;AACnC,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAkC;IAElC,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;IAC9B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC;KACnC,CAAC;AACJ,CAAC"}

package/dist/telemetry-probe.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `TelemetryProbe` — buffered, queryable view of `runtime.onTelemetry`.
+ *
+ * Used by the harness; can also be attached standalone:
+ *
+ *   const probe = new TelemetryProbe()
+ *   runtime.onTelemetry(rec => probe.record(rec))
+ *
+ *   probe.count("event.published", e => e.event.eventName === "foo")
+ *   probe.chain("foo")     // forward causal chain from event named 'foo'
+ *   probe.drift(declaredPairs)
+ */
+import type { Telemetry } from "@nwire/forge";
+export type TelemetryFilter<K extends Telemetry["kind"] = Telemetry["kind"]> = (rec: Extract<Telemetry, {
+    kind: K;
+}>) => boolean;
+export declare class TelemetryProbe {
+    private readonly buffer;
+    /** Hard cap so a long-running test doesn't OOM. Default 10k. */
+    bufferCap: number;
+    record(rec: Telemetry): void;
+    /** Drop everything (e.g. between scenarios). */
+    reset(): void;
+    /** Raw access for advanced queries. */
+    all(): readonly Telemetry[];
+    /** Records of a single kind. */
+    ofKind<K extends Telemetry["kind"]>(kind: K): ReadonlyArray<Extract<Telemetry, {
+        kind: K;
+    }>>;
+    /** Count records of a kind, optionally matching a predicate. */
+    count<K extends Telemetry["kind"]>(kind: K, predicate?: TelemetryFilter<K>): number;
+    /**
+     * Walk one causal correlation chain, returning the records ordered by
+     * `ts` (causal forward). `entry` is either a `correlationId` string or
+     * an event name (in which case the first observed correlation is used).
+     */
+    chain(entry: string): readonly Telemetry[];
+    /**
+     * Observed event pair counts (parent.eventName → child.eventName).
+     * Built from `event.published` records keyed by `causationId` chains
+     * within each correlationId.
+     */
+    observedPairs(): Map<string, number>;
+    /**
+     * Compare observed pair counts vs a declared set; returns drift entries
+     * (observed but not in declared).
+     */
+    drift(declared: ReadonlySet<string>): Array<{
+        pair: string;
+        count: number;
+    }>;
+    /** Errors observed in any *.failed kind. */
+    errors(): readonly Telemetry[];
+}
+//# sourceMappingURL=telemetry-probe.d.ts.map

package/dist/telemetry-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-probe.d.ts","sourceRoot":"","sources":["../src/telemetry-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAC7E,GAAG,EAAE,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,KACjC,OAAO,CAAC;AAEb,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,gEAAgE;IAChE,SAAS,SAAU;IAEnB,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAK5B,gDAAgD;IAChD,KAAK,IAAI,IAAI;IAIb,uCAAuC;IACvC,GAAG,IAAI,SAAS,SAAS,EAAE;IAI3B,gCAAgC;IAChC,MAAM,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAI5F,gEAAgE;IAChE,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,MAAM;IAKnF;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE;IAqB1C;;;;OAIG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAuBpC;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAS5E,4CAA4C;IAC5C,MAAM,IAAI,SAAS,SAAS,EAAE;CAS/B"}

package/dist/telemetry-probe.js

@@ -0,0 +1,111 @@
+/**
+ * `TelemetryProbe` — buffered, queryable view of `runtime.onTelemetry`.
+ *
+ * Used by the harness; can also be attached standalone:
+ *
+ *   const probe = new TelemetryProbe()
+ *   runtime.onTelemetry(rec => probe.record(rec))
+ *
+ *   probe.count("event.published", e => e.event.eventName === "foo")
+ *   probe.chain("foo")     // forward causal chain from event named 'foo'
+ *   probe.drift(declaredPairs)
+ */
+export class TelemetryProbe {
+    buffer = [];
+    /** Hard cap so a long-running test doesn't OOM. Default 10k. */
+    bufferCap = 10_000;
+    record(rec) {
+        this.buffer.push(rec);
+        if (this.buffer.length > this.bufferCap)
+            this.buffer.shift();
+    }
+    /** Drop everything (e.g. between scenarios). */
+    reset() {
+        this.buffer.length = 0;
+    }
+    /** Raw access for advanced queries. */
+    all() {
+        return this.buffer;
+    }
+    /** Records of a single kind. */
+    ofKind(kind) {
+        return this.buffer.filter((r) => r.kind === kind);
+    }
+    /** Count records of a kind, optionally matching a predicate. */
+    count(kind, predicate) {
+        const matches = this.ofKind(kind);
+        return predicate ? matches.filter(predicate).length : matches.length;
+    }
+    /**
+     * Walk one causal correlation chain, returning the records ordered by
+     * `ts` (causal forward). `entry` is either a `correlationId` string or
+     * an event name (in which case the first observed correlation is used).
+     */
+    chain(entry) {
+        let correlationId = entry;
+        if (!entry.includes("-")) {
+            // Probably an event name — find the first record matching it.
+            const first = this.buffer.find((r) => r.kind === "event.published" && r.event.eventName === entry);
+            if (!first)
+                return [];
+            correlationId = first.envelope.correlationId;
+        }
+        return this.buffer
+            .filter((r) => {
+            if (!("envelope" in r))
+                return false;
+            const env = r.envelope;
+            return !!env && env.correlationId === correlationId;
+        })
+            .slice()
+            .sort((a, b) => a.ts.localeCompare(b.ts));
+    }
+    /**
+     * Observed event pair counts (parent.eventName → child.eventName).
+     * Built from `event.published` records keyed by `causationId` chains
+     * within each correlationId.
+     */
+    observedPairs() {
+        const events = [...this.ofKind("event.published")];
+        const byCorr = new Map();
+        for (const e of events) {
+            const arr = byCorr.get(e.envelope.correlationId) ?? [];
+            arr.push(e);
+            byCorr.set(e.envelope.correlationId, arr);
+        }
+        const out = new Map();
+        for (const list of byCorr.values()) {
+            list.sort((a, b) => b.ts.localeCompare(a.ts)); // desc — causal order
+            for (let i = 1; i < list.length; i++) {
+                const parent = list[i - 1].event.eventName;
+                const child = list[i].event.eventName;
+                if (parent === child)
+                    continue;
+                const k = `${parent}→${child}`;
+                out.set(k, (out.get(k) ?? 0) + 1);
+            }
+        }
+        return out;
+    }
+    /**
+     * Compare observed pair counts vs a declared set; returns drift entries
+     * (observed but not in declared).
+     */
+    drift(declared) {
+        const observed = this.observedPairs();
+        const out = [];
+        for (const [pair, count] of observed) {
+            if (!declared.has(pair))
+                out.push({ pair, count });
+        }
+        return out;
+    }
+    /** Errors observed in any *.failed kind. */
+    errors() {
+        return this.buffer.filter((r) => r.kind === "action.failed" ||
+            r.kind === "reaction.failed" ||
+            r.kind === "external.call.failed" ||
+            r.kind === "dlq.recorded");
+    }
+}
+//# sourceMappingURL=telemetry-probe.js.map

package/dist/telemetry-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-probe.js","sourceRoot":"","sources":["../src/telemetry-probe.ts"],"names":[],"mappings":"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"}

package/dist/test-kit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @nwire/test-kit — test helpers for Nwire apps.
+ *
+ * Three levels of abstraction:
+ *
+ *   1. Unit/integration: `harness({ app })` boots an app in-process with
+ *      in-memory adapters; returns dispatch/query/telemetry/idle/stop.
+ *
+ *   2. Real-deps integration: `dockerCompose({ preset })` spins up
+ *      mongo/nats/redis/postgres for the test suite; pass real adapters
+ *      to the harness via `providers`.
+ *
+ *   3. BDD: `feature(path, define)` wires Gherkin .feature files to vitest
+ *      via @amiceli/vitest-cucumber (peer dep).
+ *
+ * Plus existing helpers: zod fixture factory, supertest agent.
+ */
+export { harness, type Harness, type HarnessOptions } from "./harness";
+export { TelemetryProbe, type TelemetryFilter } from "./telemetry-probe";
+export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, type ComposeStack, type ComposePreset, } from "./docker-compose";
+export { isReachable } from "./is-reachable";
+export { feature, type BddContext } from "./bdd";
+export { factory, sequence, type Factory, type SequenceCounter } from "./zod-fixture-factory";
+export { createTestApp, bootTestApp, type BootedTestApp } from "./supertest-app-helper";
+//# sourceMappingURL=test-kit.d.ts.map

package/dist/test-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-kit.d.ts","sourceRoot":"","sources":["../src/test-kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,aAAa,EACb,OAAO,IAAI,sBAAsB,EACjC,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/test-kit.js

@@ -0,0 +1,26 @@
+/**
+ * @nwire/test-kit — test helpers for Nwire apps.
+ *
+ * Three levels of abstraction:
+ *
+ *   1. Unit/integration: `harness({ app })` boots an app in-process with
+ *      in-memory adapters; returns dispatch/query/telemetry/idle/stop.
+ *
+ *   2. Real-deps integration: `dockerCompose({ preset })` spins up
+ *      mongo/nats/redis/postgres for the test suite; pass real adapters
+ *      to the harness via `providers`.
+ *
+ *   3. BDD: `feature(path, define)` wires Gherkin .feature files to vitest
+ *      via @amiceli/vitest-cucumber (peer dep).
+ *
+ * Plus existing helpers: zod fixture factory, supertest agent.
+ */
+export { harness } from "./harness";
+export { TelemetryProbe } from "./telemetry-probe";
+export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, } from "./docker-compose";
+export { isReachable } from "./is-reachable";
+export { feature } from "./bdd";
+// Pre-existing helpers
+export { factory, sequence } from "./zod-fixture-factory";
+export { createTestApp, bootTestApp } from "./supertest-app-helper";
+//# sourceMappingURL=test-kit.js.map

package/dist/test-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-kit.js","sourceRoot":"","sources":["../src/test-kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAqC,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,cAAc,EAAwB,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,aAAa,EACb,OAAO,IAAI,sBAAsB,GAGlC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAmB,MAAM,OAAO,CAAC;AAEjD,uBAAuB;AACvB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAsC,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,WAAW,EAAsB,MAAM,wBAAwB,CAAC"}

package/dist/zod-fixture-factory.d.ts

@@ -0,0 +1,13 @@
+import type { z } from "zod";
+import type { ZodTypeAny } from "@nwire/messages";
+export type Factory<T> = (overrides?: Partial<T>) => T;
+/**
+ * Build typed, zod-validated fixtures from a schema and a defaults producer.
+ *
+ *   const userFactory = factory(UserSchema, () => ({ id: randomUUID(), role: 'student' }))
+ *   const u = userFactory({ role: 'teacher' })   // typed; validated; one line per test
+ */
+export declare function factory<TSchema extends ZodTypeAny>(schema: TSchema, defaults: () => z.input<TSchema>): Factory<z.output<TSchema>>;
+export type SequenceCounter = () => number;
+export declare function sequence(start?: number): SequenceCounter;
+//# sourceMappingURL=zod-fixture-factory.d.ts.map

package/dist/zod-fixture-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-fixture-factory.d.ts","sourceRoot":"","sources":["../src/zod-fixture-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,SAAS,UAAU,EAChD,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAQ5B;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,MAAM,CAAC;AAE3C,wBAAgB,QAAQ,CAAC,KAAK,SAAI,GAAG,eAAe,CAGnD"}

package/dist/zod-fixture-factory.js

@@ -0,0 +1,20 @@
+/**
+ * Build typed, zod-validated fixtures from a schema and a defaults producer.
+ *
+ *   const userFactory = factory(UserSchema, () => ({ id: randomUUID(), role: 'student' }))
+ *   const u = userFactory({ role: 'teacher' })   // typed; validated; one line per test
+ */
+export function factory(schema, defaults) {
+    return (overrides) => {
+        // Defaults are constrained by TSchema's input type, so spread is safe;
+        // zod 4 types this as `unknown` because TSchema is unconstrained at the
+        // wildcard, so we widen to a Record for the spread.
+        const base = defaults();
+        return schema.parse({ ...base, ...overrides });
+    };
+}
+export function sequence(start = 1) {
+    let n = start;
+    return () => n++;
+}
+//# sourceMappingURL=zod-fixture-factory.js.map

package/dist/zod-fixture-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-fixture-factory.js","sourceRoot":"","sources":["../src/zod-fixture-factory.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CACrB,MAAe,EACf,QAAgC;IAEhC,OAAO,CAAC,SAAS,EAAE,EAAE;QACnB,uEAAuE;QACvE,wEAAwE;QACxE,oDAAoD;QACpD,MAAM,IAAI,GAAG,QAAQ,EAA6B,CAAC;QACnD,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,GAAI,SAAqC,EAAE,CAAC,CAAC;IAC9E,CAAC,CAAC;AACJ,CAAC;AAID,MAAM,UAAU,QAAQ,CAAC,KAAK,GAAG,CAAC;IAChC,IAAI,CAAC,GAAG,KAAK,CAAC;IACd,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nwire/test-kit",
+  "version": "0.7.0",
+  "description": "Shared test helpers and zod-driven fixture factories",
+  "keywords": [
+    "fixtures",
+    "testing",
+    "vitest"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/test-kit.js",
+  "types": "./dist/test-kit.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/test-kit.js",
+      "types": "./dist/test-kit.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "supertest": "^7.2.2",
+    "zod": "^4.0.0",
+    "@nwire/envelope": "0.7.0",
+    "@nwire/messages": "0.7.0",
+    "@nwire/forge": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/koa": "^2.15.0",
+    "@types/node": "^22.19.9",
+    "@types/supertest": "^6.0.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@amiceli/vitest-cucumber": "^4.0.0",
+    "koa": "^2.16.0"
+  },
+  "peerDependenciesMeta": {
+    "koa": {
+      "optional": true
+    },
+    "@amiceli/vitest-cucumber": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}