@specific.dev/spectest 0.107.2 → 0.109.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { Android, AndroidApp } from "./android.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
-import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
+import type { Provenanced, SpectestFetch, Wrapped, Unwrap } from "./inspect.js";
 export { field } from "./inspect.js";
 export { annotate } from "./annotate.js";
 export type { Annotated, AnnotationKind, AnnotationOptions, ChatAnnotation, ChatMessageAnnotation, ChatReactionAnnotation, EmailAnnotation, } from "./annotate.js";
@@ -563,6 +563,11 @@ export interface ServiceDefinition<H extends Record<string, any> = Record<string
      * user chose in the services map and matches the in-VM DNS name; the
      * rest of the {@link ServiceHelpersContext} (exec, projectRoot) lets a
      * component reach into its containers without daemon internals.
+     *
+     * Direct helper functions may return `annotate(value, "email" | "chat")`.
+     * That call becomes one named service step, its internal events are hidden,
+     * and the caller receives `Wrapped<T>` linked to the helper. Ordinary returns
+     * retain their existing value/type and underlying operation events.
      */
     helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
     /**
@@ -600,13 +605,20 @@ type HelpersOf<D> = "helpers" extends keyof D ? [NonNullable<D["helpers"]>] exte
 /**
  * Per-service handles derived from a concrete services map. Only
  * services that ship a `helpers` factory appear here; `ctx.svc.<name>`
- * is exactly the record the factory returned (e.g. `{ client: SqlClient }`
- * for `postgres(...)`). Services without helpers don't show up at all,
+ * preserves the factory's live handles and ordinary function results. A
+ * function returning `annotate(value, kind)` instead returns a wrapped value
+ * linked to one named service-helper step. Services without helpers don't show up,
  * so plain `services: { api: { image: ... } }` adds no noise.
  */
 export type ServiceHandlesFor<S extends ServicesMap> = {
-    [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: HelpersOf<S[K]>;
+    [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: ServiceHelpers<HelpersOf<S[K]>>;
+};
+/** Only annotated returns change type. Keeping other function types verbatim
+ * preserves generics, overloads, and callable clients with attached methods. */
+type ServiceHelpers<H> = {
+    [K in keyof H]: H[K] extends (...args: infer A) => infer R ? Extract<Awaited<R>, Annotated<unknown>> extends never ? H[K] : (...args: A) => R extends Promise<infer V> ? Promise<ServiceHelperResult<V>> : ServiceHelperResult<R> : H[K];
 };
+type ServiceHelperResult<R> = R extends Annotated<infer V> ? Wrapped<Unwrap<V>> : R;
 /** Loose, runtime-friendly shape of `ctx.svc` for code that doesn't
  * know the concrete services map (the daemon, generic helpers). The
  * typed `ctx.svc` in test bodies is `ServiceHandlesFor<S>`. */
@@ -1543,14 +1555,14 @@ export declare function defineFake<S = any, H extends Record<string, unknown> =
  * at use sites. */
 export type FakesMap = Record<string, FakeDefinition<any, any>>;
 /** Rewrite a helpers record so each function's result is inspect-wrapped
- * ({@link Wrapped}) — mirroring the runtime, where `trackFakeHelpers` wraps
+ * ({@link Wrapped}) — mirroring the runtime, where `trackHelpers` wraps
  * every helper return value for assertion provenance. Without this the raw
  * return type (e.g. `Charge[]`) reaches `expect`, which the `Provenanced`
  * gate rejects. Handles sync and async helpers; non-function members (and
  * `void` side-effect helpers) pass through untouched. Mirrors `Tagged<T>` in
  * `components/k3s.ts`, extended to cover synchronous returns. */
 type WrappedHelpers<H> = {
-    [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<Unannotated<R>>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<Unannotated<R>> : H[K];
+    [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<Unwrap<Unannotated<R>>>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<Unwrap<Unannotated<R>>> : H[K];
 };
 /** A helper's return type as the *test* sees it. {@link annotate} boxes the
  * value in an {@link Annotated} to pick how the step renders; the daemon
@@ -1612,17 +1624,25 @@ export interface Project<S extends ServicesMap = ServicesMap, F extends FakesMap
      * appear in the timeline.
      */
     setup?: ProjectSetupFn<S, F>;
+    /**
+     * Prepare a new interactive environment, after normal setup and the shared
+     * warm-template snapshot. Runs on both cold starts and warm restores from
+     * the dashboard or `spectest env start`, before the environment is ready.
+     * Never runs for tests, snapshot forks, or resuming a stopped environment.
+     * Uses the same context as `setup`; throw to fail the start.
+     */
+    setupInteractive?: ProjectSetupFn<S, F>;
     tests?: TestSuite<S, F>;
 }
 /**
- * Context handed to the project-level `setup` hook: the full
+ * Context handed to the project-level `setup` and `setupInteractive` hooks: the full
  * {@link SpectestContext}, minus only what a timeline gives a test
  * (testName, parent, browser/mobile/terminal). Everything a test can do
  * to the environment — exec, fetch, `svc`/`fakes` helpers, `poll`,
  * `dnsName`, `certificate`, `startService`, and project-file access via
- * `projectRoot`/`readProjectFile` — is available here too, and whatever it
- * produces is captured into the warm-template snapshot, so every test
- * inherits it without re-running.
+ * `projectRoot`/`readProjectFile` — is available here too. Normal `setup`
+ * state is captured into the shared warm template; `setupInteractive`
+ * state belongs only to the new interactive environment.
  */
 export interface ProjectSetupContext<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> extends SpectestContext<S, F> {
 }
@@ -1661,6 +1681,8 @@ export type ProjectSetupFn<S extends ServicesMap = ServicesMap, F extends FakesM
 export interface ProjectOpts<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     /** Optional project-level setup. See `Project.setup`. */
     setup?: ProjectSetupFn<S, F>;
+    /** Optional interactive-only setup. See `Project.setupInteractive`. */
+    setupInteractive?: ProjectSetupFn<S, F>;
     /** Test cases for this project's suite. */
     tests?: TestCase<unknown, S, F>[];
 }
@@ -1714,7 +1736,7 @@ export interface DefinedEnvironment<S extends ServicesMap, F extends FakesMap =
     group<P = undefined>(name: string, opts?: GroupOpts<P, S, F>): TestGroup<P, S, F>;
     /** Bundle this environment with a test suite into the project default
      * export. Pass tests as a plain array for the common case, or an
-     * options bag to attach project-level `setup`. (Fakes are declared on
+     * options bag to attach `setup` or `setupInteractive`. (Fakes are declared on
      * `defineEnvironment`, not here.) */
     project(tests?: TestCase<unknown, S, F>[]): Project<S, F>;
     project(opts: ProjectOpts<S, F>): Project<S, F>;

package/dist/index.js

@@ -17,13 +17,9 @@ import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // always wrapped (in every context), so the method is always there; there is no
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
-// Render annotations for fake helpers: a helper returns
-// `annotate(value, "email", { … })` or `annotate(value, "chat", { … })`
-// when its value is one of those, and the fake step it records gains a
-// nested event drawing it — an email mail-client style, a conversation as
-// bubbles — which the step's panel leads with, tabbing to the raw JSON
-// value. The kind picks the options' type, and the test still gets the raw
-// value, with the raw value's type — see `annotate.ts`.
+// Fake and service helpers return annotate(value, kind) to render their own
+// result as email/chat. Their boundary opens the box and links assertions to
+// the helper step. Annotated service returns suppress internal operation events.
 export { annotate } from "./annotate.js";
 // Instrumented client primitives — drop-in replacements for Bun's native
 // clients that record each operation on the test event log and return their
@@ -488,6 +484,8 @@ export function defineEnvironment(input) {
         const proj = { environment: config };
         if (opts.setup)
             proj.setup = opts.setup;
+        if (opts.setupInteractive)
+            proj.setupInteractive = opts.setupInteractive;
         if (fakes)
             proj.fakes = fakes;
         if (opts.tests && opts.tests.length > 0) {

package/dist/recorder.d.ts

@@ -1,5 +1,5 @@
 import type { AndroidStepDetails } from "./android-step.js";
-export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | EnvEvent | EmailEvent | StepEvent;
+export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | ServiceHelperEvent | EnvEvent | EmailEvent | StepEvent;
 interface BaseEvent {
     /** Order of *start* within the test. Reserved when an op begins (see
      *  `reserveEvent`), so an op whose nested children finish — and record —
@@ -294,6 +294,13 @@ export interface FakeEvent extends BaseEvent {
     /** Set if the helper threw. */
     error?: string;
 }
+/** An annotated service helper has the same call/return shape as a fake.
+ * Only helpers returning an annotation emit this event. */
+export interface ServiceHelperEvent extends Omit<FakeEvent, "kind" | "fake"> {
+    kind: "service";
+    /** Service name — the key in `ctx.svc`. */
+    service: string;
+}
 /**
  * One captured email, as embedded on an {@link EmailEvent}. The HTML and
  * text bodies ride along (truncated to the output cap) so the dashboard
@@ -563,6 +570,15 @@ export interface EventReservation {
     seq: number;
     tOffsetMs: number;
 }
+/** Buffer a helper's async descendants until its return chooses between the
+ * implementation's events and one annotated helper call. Seqs still come from
+ * the test recorder, so concurrent calls and linked assertions stay unique.
+ * Poll truncation/grouping inside the helper applies only to its own buffer. */
+export declare function captureRecording(): {
+    run<T>(fn: () => T): T;
+    finish(keep: boolean): void;
+    isCurrent(): boolean;
+};
 export declare function pauseRecording(): void;
 export declare function resumeRecording(): void;
 export declare function startRecording(startedAt?: number): void;
@@ -592,6 +608,7 @@ export declare function recordS3(ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">
 export declare function recordTerminal(ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordTerminalStep(ev: Omit<TerminalStepEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordFake(ev: Omit<FakeEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordServiceHelper(ev: Omit<ServiceHelperEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordEnv(ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 /**
  * One block of step detail, in the dashboard's presentation vocabulary

package/dist/recorder.js

@@ -7,12 +7,18 @@
 // When no test is running (production code paths, eval, etc.) the
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
     start;
-    events = [];
+    rootEvents = [];
+    pendingHelpers = new Set();
+    get events() {
+        const branch = recordingBranches.getStore();
+        return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
+    }
     seq = 0;
     constructor(start = Date.now()) {
         this.start = start;
@@ -106,6 +112,48 @@ class Recorder {
     }
 }
 let current = null;
+const recordingBranches = new AsyncLocalStorage();
+function branchEvents(branch) {
+    return branch.state === "kept"
+        ? branch.parent ? branchEvents(branch.parent) : branch.destination
+        : branch.events;
+}
+function branchAllowsRecording(branch) {
+    return !branch || (branch.owner === current && branch.state !== "discarded" &&
+        branchAllowsRecording(branch.parent));
+}
+/** Buffer a helper's async descendants until its return chooses between the
+ * implementation's events and one annotated helper call. Seqs still come from
+ * the test recorder, so concurrent calls and linked assertions stay unique.
+ * Poll truncation/grouping inside the helper applies only to its own buffer. */
+export function captureRecording() {
+    if (!active())
+        return { run: (fn) => fn(), finish: () => { }, isCurrent: () => false };
+    const branch = {
+        owner: current, events: [], parent: recordingBranches.getStore(),
+        destination: current.drain(), state: "open",
+    };
+    current.pendingHelpers.add(branch);
+    return {
+        run: (fn) => recordingBranches.run(branch, fn),
+        isCurrent: () => branch.owner === current && active(),
+        finish(keep) {
+            if (branch.state !== "open")
+                return;
+            branch.owner.pendingHelpers.delete(branch);
+            if (keep && branchAllowsRecording(branch)) {
+                const destination = branch.parent ? branchEvents(branch.parent) : branch.destination;
+                for (const event of branch.events)
+                    destination.push(event);
+                branch.state = "kept";
+            }
+            else {
+                branch.state = "discarded";
+            }
+            branch.events.length = 0;
+        },
+    };
+}
 // Counter-based pause: `pauseRecording`/`resumeRecording` nest safely
 // (a nested `ctx.poll` inside another `ctx.poll`'s predicate stays
 // suppressed until its own resume balances out). Active record* sites
@@ -121,7 +169,7 @@ export function resumeRecording() {
     paused = Math.max(0, paused - 1);
 }
 function active() {
-    return current !== null && paused === 0 && scopeAllowsRecording();
+    return current !== null && paused === 0 && scopeAllowsRecording() && branchAllowsRecording(recordingBranches.getStore());
 }
 export function startRecording(startedAt = Date.now()) {
     current = new Recorder(startedAt);
@@ -131,6 +179,19 @@ export function stopRecording() {
     if (!current)
         return [];
     const evs = current.drain();
+    // A timeout can stop the test before a helper returns. Keep its available
+    // diagnostics, then fence detached work out of any subsequent recording.
+    for (const branch of current.pendingHelpers) {
+        if (branchAllowsRecording(branch)) {
+            for (const event of branch.events)
+                evs.push(event);
+        }
+    }
+    for (const branch of current.pendingHelpers) {
+        branch.events.length = 0;
+        branch.state = "discarded";
+    }
+    current.pendingHelpers.clear();
     current = null;
     paused = 0;
     return evs;
@@ -189,6 +250,9 @@ export function recordTerminalStep(ev, reservation) {
 export function recordFake(ev, reservation) {
     return active() ? current.push({ kind: "fake", ...ev }, reservation) : undefined;
 }
+export function recordServiceHelper(ev, reservation) {
+    return active() ? current.push({ kind: "service", ...ev }, reservation) : undefined;
+}
 export function recordEnv(ev, reservation) {
     return active() ? current.push({ kind: "env", ...ev }, reservation) : undefined;
 }
@@ -199,11 +263,7 @@ export function recordEmail(ev, reservation) {
     return active() ? current.push({ kind: "email", ...ev }, reservation) : undefined;
 }
 export function recordWait(ev, reservation) {
-    // Use `current` directly (not `active()`) so a `recordWait` at the
-    // end of a `ctx.poll` block lands even though the surrounding code
-    // just resumed from `paused`. Pushing this event is the whole point
-    // of the poll primitive.
-    return current?.push({ kind: "wait", ...ev }, reservation);
+    return active() ? current.push({ kind: "wait", ...ev }, reservation) : undefined;
 }
 /** Number of events the active recorder has accumulated. Returns 0
  *  when no recorder is active. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.107.2",
+  "version": "0.109.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/annotate.ts

@@ -1,34 +1,10 @@
-// Render annotations — how a fake tells the dashboard to draw a helper's
-// return value as something richer than JSON.
-//
-// A fake helper call is recorded as a `fake` step and its return value is
-// rendered as pretty JSON, which is the right default for arbitrary data.
-// When the value *is* a domain object the timeline already draws well — an
-// email, today — the fake says so: `return annotate(msg, "email", {…})`.
-// The call is still recorded as the `fake` step it is; the annotation rides
-// *under* it as a child event (`parentSeq`, marked `annotation`) of the kind
-// that already knows how to draw this — for `"email"`, the very event the
-// built-in `email()` component's mailbox helpers record — so the dashboard
-// renders it mail-client style (header block + sandboxed HTML body) with no
-// new rendering code. It leads the step's detail panel; the raw JSON value
-// is a tab away.
-//
-// One function, keyed by kind: the kind is a key of `AnnotationOptions`, so
-// the options argument is typed against the kind that was named, and a new
-// kind is an entry in that interface (+ a case in `lower`, + an arm in
-// `daemon.ts::recordAnnotatedCall`) rather than a new export.
-//
-// The test is unaffected. `annotate` returns a box that the daemon opens at
-// the helper boundary (`daemon.ts::invokeFakeHelper`), so the caller gets
-// the raw value back, inspect-wrapped as always, and the *type* it sees is
-// still the raw value's (`WrappedHelpers` in index.ts unwraps `Annotated`).
-// Assertions keep linking to the fake step, exactly as for an unannotated
-// helper. The annotation is a rendering hint and nothing else.
-//
-// This is a fake-helper mechanism: those calls go through a tracking proxy
-// that can open the box. A *service* helper (`ctx.svc.<name>.…`) is the raw
-// record its factory returned, so an annotation there would reach the test
-// as an opaque value — don't.
+// A helper returns an annotation box to choose a richer view of its result.
+// Both fake and service helper boundaries open it, record one named helper
+// operation with an annotation child, and wrap the value for linked assertions.
+// annotate() itself does not record or attach anything to an existing operation.
+// Fake helpers always hide their implementation; service helpers opt into that
+// behavior by returning this box. Ordinary service returns keep their internal
+// recorded operations and their existing types.
 
 import { deepUnwrap } from "./inspect.js";
 import {
@@ -50,15 +26,14 @@ import {
 const ANNOTATION = Symbol.for("spectest.render-annotation");
 
 /** Phantom brand — `Annotated<T>` is nominally distinct from `T`, so the
- *  box can't be read as the value by accident inside the fake, and the
+ *  box can't be read as the value by accident inside the helper, and the
  *  helper types can recognise it and hand the *test* back a plain `T`. */
 declare const ANNOTATED: unique symbol;
 
 /**
  * A value plus a rendering hint, as returned by {@link annotate}. Return it
- * straight from a fake helper: the daemon unwraps it, so the test receives
- * the value itself and `ctx.fakes.<name>.<fn>()` is typed as if the
- * annotation weren't there.
+ * straight from a fake or service helper: the boundary opens it and the test
+ * receives the value wrapped for assertions. The box never reaches the test.
  */
 export interface Annotated<T> {
   readonly [ANNOTATED]: T;
@@ -71,7 +46,7 @@ export interface Annotated<T> {
  * another kind is a compile error at the call site.
  *
  * A new kind is an entry here, a case in `lower`, and an arm in
- * `daemon.ts::recordAnnotationChild`.
+ * `helper-tracking.ts::recordAnnotationChild`.
  */
 export interface AnnotationOptions {
   /** Draw the value as an email — one message, or a list of them for a
@@ -87,7 +62,7 @@ export type AnnotationKind = keyof AnnotationOptions;
 
 /**
  * What an annotation lowers to: the fields of the child event the daemon
- * records under the call's own `fake` one. Tagged by that event's `kind` —
+ * records under the helper call's own event. Tagged by that event's `kind` —
  * which needn't be the annotation kind's name, since an annotation names
  * what the value *is* and the event names how it's drawn.
  */
@@ -113,13 +88,13 @@ type ChatRenderAnnotation = {
 };
 
 /**
- * The email fields to render. Every one is optional — pass what the fake
- * has. Addresses take a single string or a list.
+ * The email fields to render. Every one is optional — pass what the helper
+ * observed. Addresses take a single string or a list.
  *
  * The event can also carry a date, per-row previews and attachment
- * metadata, which the built-in `email()` component fills from a really
- * captured message; a fake's mail was never sent, so those are deliberately
- * not offered here. A listing row's preview is derived from the body.
+ * metadata, which the built-in `email()` component fills from a captured
+ * message. Annotations currently cover the header/body fields below. A
+ * listing row's preview is derived from the body.
  */
 export interface EmailAnnotation {
   from?: string;
@@ -248,10 +223,12 @@ const NO_FIELDS =
   "html: value.body }).";
 
 /**
- * Say what a fake helper's return value *is*, so the timeline can draw it
+ * Say what a helper's return value *is*, so the timeline can draw it
  * as that on top of the JSON it always shows. The call stays an ordinary
- * fake step; the rendered view nests inside it. The value is returned to
- * the test unchanged (and unchanged in type).
+ * helper step; the rendered view nests inside it. Return this box from the
+ * helper: the caller receives the value wrapped for assertions. An annotated
+ * service return suppresses the helper's internal events; an ordinary service
+ * return keeps them. Calling annotate without returning the box has no effect.
  *
  * ```ts
  * helpers: ({ state }) => ({