@c9up/helix 0.1.3 → 0.1.5

package/dist/cli/watch/loop.js

@@ -0,0 +1,133 @@
+/**
+ * Watch-mode run loop: runs `runOnce` once on startup, installs the
+ * watcher, and re-invokes `runOnce` whenever a coalesced change burst
+ * fires. Re-runs are serialised — at most one queued follow-up while a
+ * run is in flight; further bursts during that window are dropped (the
+ * queued run will pick up the latest disk state).
+ *
+ * On SIGINT (or an aborted external `AbortSignal`), the loop closes
+ * the watcher, waits for any in-flight run, and resolves with the
+ * LAST `RunOutcome` (with `exitCode: 0`, since a failing run during
+ * interactive watch should not poison the exit status — failures
+ * already surface as test output).
+ */
+import { createWatcher } from "./watcher.js";
+const BANNER_WAITING = "[helix] watching for changes… (Ctrl-C to exit)";
+const BANNER_RERUN = "[helix] change detected, re-running…";
+function fallbackOutcome() {
+    return {
+        summary: {
+            totals: { pass: 0, fail: 0, skip: 0, todo: 0, fileErrors: 0 },
+            files: [],
+            fileErrors: [],
+            durationMs: 0,
+        },
+        exitCode: 0,
+    };
+}
+export async function runWatch(opts, runOnce) {
+    // Initialise upfront so the final return never reads `undefined`,
+    // even if `runOnce` throws and the catch path's fallback construction
+    // itself throws (defence-in-depth against a brittle cast).
+    let lastOutcome = fallbackOutcome();
+    let inFlight;
+    let queued = false;
+    let closing = false;
+    let watcher;
+    let resolveSettled;
+    const settled = new Promise((resolve) => {
+        resolveSettled = resolve;
+    });
+    function beginShutdown() {
+        if (closing)
+            return;
+        closing = true;
+        void (async () => {
+            if (watcher)
+                await watcher.close();
+            if (inFlight)
+                await inFlight;
+            resolveSettled();
+        })();
+    }
+    const onSigint = () => beginShutdown();
+    const onAbort = () => beginShutdown();
+    process.on("SIGINT", onSigint);
+    if (opts.signal) {
+        if (opts.signal.aborted) {
+            closing = true;
+        }
+        else {
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+    }
+    function trigger() {
+        if (closing)
+            return;
+        if (inFlight) {
+            queued = true;
+            return;
+        }
+        process.stdout.write(`${BANNER_RERUN}\n`);
+        inFlight = (async () => {
+            try {
+                lastOutcome = await runOnce();
+            }
+            catch (err) {
+                process.stderr.write(`helix-watch: run failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            finally {
+                inFlight = undefined;
+                if (!closing) {
+                    process.stdout.write(`${BANNER_WAITING}\n`);
+                }
+                if (queued && !closing) {
+                    queued = false;
+                    trigger();
+                }
+            }
+        })();
+    }
+    // Initial run — drive it through the same in-flight machinery so a
+    // SIGINT/abort arriving during the first run is handled exactly like
+    // one arriving during a re-run (handler awaits `inFlight`, then
+    // resolves).
+    inFlight = (async () => {
+        try {
+            lastOutcome = await runOnce();
+        }
+        catch (err) {
+            process.stderr.write(`helix-watch: run failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        finally {
+            inFlight = undefined;
+        }
+    })();
+    await inFlight;
+    if (closing) {
+        process.off("SIGINT", onSigint);
+        opts.signal?.removeEventListener("abort", onAbort);
+        return { ...lastOutcome, exitCode: 0 };
+    }
+    process.stdout.write(`${BANNER_WAITING}\n`);
+    let watcherFatalError;
+    watcher = createWatcher({
+        root: opts.root,
+        include: opts.include,
+        exclude: opts.exclude,
+        debounceMs: opts.debounceMs,
+        onChange: () => trigger(),
+        onError: (err) => {
+            watcherFatalError = err;
+            beginShutdown();
+        },
+    });
+    await settled;
+    process.off("SIGINT", onSigint);
+    opts.signal?.removeEventListener("abort", onAbort);
+    if (watcherFatalError) {
+        process.stderr.write(`helix-watch: watcher error — ${watcherFatalError.message}\n`);
+    }
+    return { ...lastOutcome, exitCode: 0 };
+}
+//# sourceMappingURL=loop.js.map

package/dist/cli/watch/loop.js.map

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

package/dist/cli/watch/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Watch-mode public types. Kept in their own file so `bin/helix.js` and
+ * `run.ts` can import without pulling in the watcher implementation.
+ */
+export interface WatchOptions {
+    enabled: boolean;
+    /** Debounce window in ms — events within the window collapse to one
+     *  re-run. Default 200, range [1, 5_000]. */
+    debounceMs?: number;
+    /** Override the watcher's include globs. Defaults to `coverage.include`
+     *  when set, otherwise the watch defaults (`src/**`, `tests/**`,
+     *  `test/**`). */
+    include?: string[];
+    /** Override the watcher's exclude globs. Defaults to `coverage.exclude`
+     *  when set, otherwise the watch defaults (`node_modules/**`,
+     *  `.helix-coverage/**`, etc.). */
+    exclude?: string[];
+    /** Optional `AbortSignal` to drive shutdown without a real SIGINT —
+     *  primarily a test seam. */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/watch/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;iDAC6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;sBAEkB;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;uCAEmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;iCAC6B;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/dist/cli/watch/types.js

@@ -0,0 +1,6 @@
+/**
+ * Watch-mode public types. Kept in their own file so `bin/helix.js` and
+ * `run.ts` can import without pulling in the watcher implementation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/watch/types.js.map

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

package/dist/cli/watch/watcher.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Recursive file watcher for `helix test --watch`. Wraps Node's
+ * `fs.watch(root, { recursive: true })` with a glob filter (reusing the
+ * coverage glob translator) and a single-timer debounce that coalesces
+ * burst events into one `onChange` call.
+ *
+ * The shape (`createWatcher` returning a `{ close }` handle) is the
+ * abstraction a future Rust `notify`-NAPI implementation slots into
+ * without touching the loop.
+ */
+export interface CreateWatcherOptions {
+    root: string;
+    include: string[];
+    exclude: string[];
+    debounceMs: number;
+    onChange: (paths: Set<string>) => void;
+    /** Surfaces `FSWatcher` errors (recursive unsupported, EMFILE, etc.)
+     *  so the loop can stop instead of waiting forever on a dead handle. */
+    onError?: (err: Error) => void;
+}
+export interface WatcherHandle {
+    close(): Promise<void>;
+}
+export declare function createWatcher(opts: CreateWatcherOptions): WatcherHandle;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/cli/watch/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACvC;4EACwE;IACxE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAaD,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAuGvE"}

package/dist/cli/watch/watcher.js

@@ -0,0 +1,122 @@
+/**
+ * Recursive file watcher for `helix test --watch`. Wraps Node's
+ * `fs.watch(root, { recursive: true })` with a glob filter (reusing the
+ * coverage glob translator) and a single-timer debounce that coalesces
+ * burst events into one `onChange` call.
+ *
+ * The shape (`createWatcher` returning a `{ close }` handle) is the
+ * abstraction a future Rust `notify`-NAPI implementation slots into
+ * without touching the loop.
+ */
+import { watch as fsWatch, realpathSync } from "node:fs";
+import path from "node:path";
+import { compileGlobs, matchesAnyGlob } from "../coverage/glob.js";
+const DEBOUNCE_MIN = 1;
+const DEBOUNCE_MAX = 5_000;
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function createWatcher(opts) {
+    if (opts.debounceMs < DEBOUNCE_MIN ||
+        opts.debounceMs > DEBOUNCE_MAX ||
+        !Number.isFinite(opts.debounceMs)) {
+        throw new Error(`createWatcher: debounceMs must be in [${DEBOUNCE_MIN}, ${DEBOUNCE_MAX}], got ${opts.debounceMs}`);
+    }
+    if (opts.include.length === 0) {
+        throw new Error("createWatcher: include must be non-empty (an empty include matches nothing — silent watcher).");
+    }
+    const include = compileGlobs(opts.include);
+    const exclude = compileGlobs(opts.exclude);
+    // Realpath the root so events delivered with the canonical path
+    // (macOS `/tmp` → `/private/tmp`, Docker bind-mounts, pnpm worktree
+    // symlinks) don't get filtered out as "outside root". Mirrors what
+    // `coverage/filter.ts` does for the same reason.
+    const root = tryRealpath(path.resolve(opts.root));
+    const pending = new Set();
+    let timer;
+    let closed = false;
+    function flush() {
+        timer = undefined;
+        if (closed)
+            return;
+        if (pending.size === 0)
+            return;
+        const batch = new Set(pending);
+        pending.clear();
+        opts.onChange(batch);
+    }
+    function arm() {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(flush, opts.debounceMs);
+    }
+    function shouldNotify(filename) {
+        if (!filename)
+            return undefined;
+        const abs = path.resolve(root, filename);
+        const rel = path.relative(root, abs).split(path.sep).join("/");
+        if (rel.length === 0 || rel.startsWith("..") || path.isAbsolute(rel)) {
+            return undefined;
+        }
+        if (matchesAnyGlob(exclude, rel))
+            return undefined;
+        if (!matchesAnyGlob(include, rel))
+            return undefined;
+        return abs;
+    }
+    let watcher;
+    try {
+        watcher = fsWatch(root, { recursive: true }, (_event, filename) => {
+            if (closed)
+                return;
+            const abs = shouldNotify(typeof filename === "string" ? filename : null);
+            if (!abs)
+                return;
+            pending.add(abs);
+            arm();
+        });
+    }
+    catch (err) {
+        throw new Error(`createWatcher: fs.watch failed on ${root}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // On `'error'`, surface the failure to the caller and shut down so
+    // the loop doesn't sit on a dead handle. Without this, recursive
+    // watch failures on Linux<20 leave the user staring at a "watching…"
+    // banner that will never tick.
+    watcher.on("error", (err) => {
+        if (closed)
+            return;
+        closed = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        try {
+            watcher.close();
+        }
+        catch {
+            /* already torn down */
+        }
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return {
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            pending.clear();
+            watcher.close();
+            await new Promise((resolve) => setImmediate(resolve));
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/cli/watch/watcher.js.map

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

package/dist/container/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@c9up/helix/container` — barrel for the test-container facade.
+ */
+export type { ContainerLike, ContainerToken, } from "../runtime/vi/index.js";
+export { clearActiveContainer, type HelixContainer, override, overrideOn, useContainer, } from "./override.js";
+export { spy } from "./spy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/container/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/container/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACX,aAAa,EACb,cAAc,GACd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,oBAAoB,EACpB,KAAK,cAAc,EACnB,QAAQ,EACR,UAAU,EACV,YAAY,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/container/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@c9up/helix/container` — barrel for the test-container facade.
+ */
+export { clearActiveContainer, override, overrideOn, useContainer, } from "./override.js";
+export { spy } from "./spy.js";
+//# sourceMappingURL=index.js.map

package/dist/container/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/container/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EACN,oBAAoB,EAEpB,QAAQ,EACR,UAAU,EACV,YAAY,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/{src/container/override.ts → dist/container/override.d.ts}

@@ -12,17 +12,11 @@
  * by the host app's test bootstrap). For bare unit tests with no host
  * app, callers can pass the container explicitly to `overrideOn`.
  */
-
-import { inTestContext, registerTestCleanup } from "../runtime/test-context.js";
 import type { ContainerLike, ContainerToken } from "../runtime/vi/index.js";
-
 /** Container surface helix needs: a value-based override + a restore. */
 export interface HelixContainer extends ContainerLike {
-	override(token: ContainerToken, value: unknown): void;
+    override(token: ContainerToken, value: unknown): void;
 }
-
-let activeContainer: HelixContainer | undefined;
-
 /**
  * Bind a container instance as active for `helix.override(...)` calls.
  *
@@ -32,22 +26,12 @@ let activeContainer: HelixContainer | undefined;
  * frame the assignment is permanent until the next `useContainer` /
  * `clearActiveContainer` call.
  */
-export function useContainer(container: HelixContainer): void {
-	const previous = activeContainer;
-	activeContainer = container;
-	registerTestCleanup(() => {
-		activeContainer = previous;
-	});
-}
-
+export declare function useContainer(container: HelixContainer): void;
 /** Reset the active container binding. Typically not needed in user
  *  code — `useContainer` already auto-restores when called inside a
  *  test. Exposed so `afterEach` blocks (and unit tests) can clear the
  *  module-scoped slot explicitly. */
-export function clearActiveContainer(): void {
-	activeContainer = undefined;
-}
-
+export declare function clearActiveContainer(): void;
 /**
  * Override a binding on the active container with a value, and queue
  * the restore for end-of-test. Use `overrideOn` when you need to
@@ -56,31 +40,7 @@ export function clearActiveContainer(): void {
  * Throws if called outside a test frame: a queued cleanup would never
  * fire there, so the override would leak across tests silently.
  */
-export function override(token: ContainerToken, value: unknown): void {
-	if (!inTestContext()) {
-		throw new Error(
-			"helix.override: must be called inside a test (no active test frame). Calls from top-level setup leak across tests — use container.override() directly with manual restore() if that is what you want.",
-		);
-	}
-	if (!activeContainer) {
-		throw new Error(
-			"helix.override: no active container. Call helix.useContainer(container) before invoking override(), or use overrideOn(container, token, value).",
-		);
-	}
-	overrideOn(activeContainer, token, value);
-}
-
+export declare function override(token: ContainerToken, value: unknown): void;
 /** Override on a specific container instance. */
-export function overrideOn(
-	container: HelixContainer,
-	token: ContainerToken,
-	value: unknown,
-): void {
-	container.override(token, value);
-	// `registerTestCleanup` returns false when called outside a test
-	// frame (e.g. raw vitest tests, REPL, top-level setup). In that
-	// case the caller is responsible for `container.restore(token)` —
-	// we don't queue a fallback that might fire in an unexpected
-	// frame.
-	registerTestCleanup(() => container.restore(token));
-}
+export declare function overrideOn(container: HelixContainer, token: ContainerToken, value: unknown): void;
+//# sourceMappingURL=override.d.ts.map

package/dist/container/override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.d.ts","sourceRoot":"","sources":["../../src/container/override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE5E,yEAAyE;AACzE,MAAM,WAAW,cAAe,SAAQ,aAAa;IACpD,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACtD;AAID;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAM5D;AAED;;;qCAGqC;AACrC,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAYpE;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CACzB,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,OAAO,GACZ,IAAI,CAQN"}

package/dist/container/override.js

@@ -0,0 +1,67 @@
+/**
+ * Helix facade over `@c9up/ream`'s `Container.override(token, value)`.
+ *
+ * Adds two things to the raw container call:
+ *   1. The override is registered against the active test context's
+ *      auto-restore queue, so it's undone after the test even if the
+ *      test body never calls `restore()` itself.
+ *   2. A clear error when called outside a test (no AsyncLocalStorage
+ *      frame) — the queued cleanup would never fire there.
+ *
+ * The active container is passed via `useContainer(container)` (called
+ * by the host app's test bootstrap). For bare unit tests with no host
+ * app, callers can pass the container explicitly to `overrideOn`.
+ */
+import { inTestContext, registerTestCleanup } from "../runtime/test-context.js";
+let activeContainer;
+/**
+ * Bind a container instance as active for `helix.override(...)` calls.
+ *
+ * If called inside a test frame, the previous active container is
+ * captured and restored when the frame ends — so swapping the active
+ * container mid-test does not leak into the next test. Outside a test
+ * frame the assignment is permanent until the next `useContainer` /
+ * `clearActiveContainer` call.
+ */
+export function useContainer(container) {
+    const previous = activeContainer;
+    activeContainer = container;
+    registerTestCleanup(() => {
+        activeContainer = previous;
+    });
+}
+/** Reset the active container binding. Typically not needed in user
+ *  code — `useContainer` already auto-restores when called inside a
+ *  test. Exposed so `afterEach` blocks (and unit tests) can clear the
+ *  module-scoped slot explicitly. */
+export function clearActiveContainer() {
+    activeContainer = undefined;
+}
+/**
+ * Override a binding on the active container with a value, and queue
+ * the restore for end-of-test. Use `overrideOn` when you need to
+ * target a specific container instance.
+ *
+ * Throws if called outside a test frame: a queued cleanup would never
+ * fire there, so the override would leak across tests silently.
+ */
+export function override(token, value) {
+    if (!inTestContext()) {
+        throw new Error("helix.override: must be called inside a test (no active test frame). Calls from top-level setup leak across tests — use container.override() directly with manual restore() if that is what you want.");
+    }
+    if (!activeContainer) {
+        throw new Error("helix.override: no active container. Call helix.useContainer(container) before invoking override(), or use overrideOn(container, token, value).");
+    }
+    overrideOn(activeContainer, token, value);
+}
+/** Override on a specific container instance. */
+export function overrideOn(container, token, value) {
+    container.override(token, value);
+    // `registerTestCleanup` returns false when called outside a test
+    // frame (e.g. raw vitest tests, REPL, top-level setup). In that
+    // case the caller is responsible for `container.restore(token)` —
+    // we don't queue a fallback that might fire in an unexpected
+    // frame.
+    registerTestCleanup(() => container.restore(token));
+}
+//# sourceMappingURL=override.js.map

package/dist/container/override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.js","sourceRoot":"","sources":["../../src/container/override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAQhF,IAAI,eAA2C,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,SAAyB;IACrD,MAAM,QAAQ,GAAG,eAAe,CAAC;IACjC,eAAe,GAAG,SAAS,CAAC;IAC5B,mBAAmB,CAAC,GAAG,EAAE;QACxB,eAAe,GAAG,QAAQ,CAAC;IAC5B,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;qCAGqC;AACrC,MAAM,UAAU,oBAAoB;IACnC,eAAe,GAAG,SAAS,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAqB,EAAE,KAAc;IAC7D,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACd,uMAAuM,CACvM,CAAC;IACH,CAAC;IACD,IAAI,CAAC,eAAe,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACd,iJAAiJ,CACjJ,CAAC;IACH,CAAC;IACD,UAAU,CAAC,eAAe,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,UAAU,CACzB,SAAyB,EACzB,KAAqB,EACrB,KAAc;IAEd,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjC,iEAAiE;IACjE,gEAAgE;IAChE,kEAAkE;IAClE,6DAA6D;IAC7D,SAAS;IACT,mBAAmB,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/{src/container/spy.ts → dist/container/spy.d.ts}

@@ -9,10 +9,7 @@
  *   // ...
  *   expect(fakeMail.send).toHaveBeenCalledOnce();
  */
-
-import { vi } from "../runtime/vi/index.js";
 import type { AnyFn, Spy } from "../runtime/vi/spy.js";
-
 /**
  * Wrap (don't bind) `vi.fn` so `spy` always reaches through to the
  * current `vi.fn` even if it gets replaced at runtime — and so the
@@ -20,6 +17,5 @@ import type { AnyFn, Spy } from "../runtime/vi/spy.js";
  * object. The cost over `export const spy = vi.fn` is one extra
  * function call per spawn.
  */
-export function spy<Fn extends AnyFn>(implementation?: Fn): Spy<Fn> {
-	return vi.fn(implementation);
-}
+export declare function spy<Fn extends AnyFn>(implementation?: Fn): Spy<Fn>;
+//# sourceMappingURL=spy.d.ts.map

package/dist/container/spy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spy.d.ts","sourceRoot":"","sources":["../../src/container/spy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,EAAE,SAAS,KAAK,EAAE,cAAc,CAAC,EAAE,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,CAElE"}

package/dist/container/spy.js

@@ -0,0 +1,23 @@
+/**
+ * `helix.spy()` — Jest-like spy factory.
+ *
+ * Thin alias over `vi.fn()` so the documented one-liner from FR69 /
+ * Story 42.3 reads:
+ *
+ *   const fakeMail = { send: spy() };
+ *   override('mail', fakeMail);
+ *   // ...
+ *   expect(fakeMail.send).toHaveBeenCalledOnce();
+ */
+import { vi } from "../runtime/vi/index.js";
+/**
+ * Wrap (don't bind) `vi.fn` so `spy` always reaches through to the
+ * current `vi.fn` even if it gets replaced at runtime — and so the
+ * captured reference can never go stale relative to the live `vi`
+ * object. The cost over `export const spy = vi.fn` is one extra
+ * function call per spawn.
+ */
+export function spy(implementation) {
+    return vi.fn(implementation);
+}
+//# sourceMappingURL=spy.js.map

package/dist/container/spy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spy.js","sourceRoot":"","sources":["../../src/container/spy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,wBAAwB,CAAC;AAG5C;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,CAAmB,cAAmB;IACxD,OAAO,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC;AAC9B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@c9up/helix` — the framework-agnostic test runtime for the Ream ecosystem.
+ *
+ * This barrel exposes the Vitest-compatible runtime (describe/test/expect/vi/
+ * spies/lifecycle), the container facade, and time-travel — none of which import
+ * an ecosystem package. It is fully agnostic: usable in any project.
+ *
+ * Per-package test fakes/helpers live in EACH package's own `/testing` subpath
+ * (a package owns its test surface, not helix): `@c9up/ream/testing`
+ * (TestClient, FakeBus, assertEmitted), `@c9up/atlas/testing` (factory,
+ * useTransaction), `@c9up/rover/testing` (FakeMail), `@c9up/bay/testing`
+ * (FakeQueue), `@c9up/spectrum/testing` (FakeLogger), `@c9up/nova/testing`
+ * (FakeNova), `@c9up/relay/testing` (FakeRelay), `@c9up/archive/testing`
+ * (FakeStorage). Install a package → you get its testing surface.
+ */
+export * from "./container/index.js";
+export type { Assertion, FileResult, Hook, HookType, MatcherName, MatcherResult, Spy, SuiteResult, TestResult, Vi, } from "./runtime/index.js";
+export { AssertionError, afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test, vi, } from "./runtime/index.js";
+export * as time from "./time/index.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;;;;;;;;;;;;;;GAcG;AAEH,cAAc,sBAAsB,CAAC;AACrC,YAAY,EACX,SAAS,EACT,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,aAAa,EACb,GAAG,EACH,WAAW,EACX,UAAU,EACV,EAAE,GACF,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,cAAc,EACd,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,MAAM,EACN,EAAE,EACF,IAAI,EACJ,EAAE,GACF,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC"}

package/{src/index.ts → dist/index.js}

@@ -13,30 +13,7 @@
  * (FakeNova), `@c9up/relay/testing` (FakeRelay), `@c9up/archive/testing`
  * (FakeStorage). Install a package → you get its testing surface.
  */
-
 export * from "./container/index.js";
-export type {
-	Assertion,
-	FileResult,
-	Hook,
-	HookType,
-	MatcherName,
-	MatcherResult,
-	Spy,
-	SuiteResult,
-	TestResult,
-	Vi,
-} from "./runtime/index.js";
-export {
-	AssertionError,
-	afterAll,
-	afterEach,
-	beforeAll,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	test,
-	vi,
-} from "./runtime/index.js";
+export { AssertionError, afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test, vi, } from "./runtime/index.js";
 export * as time from "./time/index.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;;;;;;;;;;;;;;GAcG;AAEH,cAAc,sBAAsB,CAAC;AAarC,OAAO,EACN,cAAc,EACd,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,MAAM,EACN,EAAE,EACF,IAAI,EACJ,EAAE,GACF,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC"}

package/dist/runtime/assertion-error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Assertion error thrown by `expect` — carries structured fields so runners
+ * (Vitest-compatible reporters, IDE integrations) can render diffs.
+ */
+export interface AssertionErrorInit {
+    message: string;
+    actual?: unknown;
+    expected?: unknown;
+    operator?: string;
+    showDiff?: boolean;
+}
+export declare class AssertionError extends Error {
+    readonly actual: unknown;
+    readonly expected: unknown;
+    readonly operator: string | undefined;
+    readonly showDiff: boolean;
+    constructor(init: AssertionErrorInit);
+}
+export declare function isAssertionError(value: unknown): value is AssertionError;
+//# sourceMappingURL=assertion-error.d.ts.map