@specific.dev/spectest 0.108.0 → 0.109.1

package/dist/daemon.js

@@ -2925,31 +2925,34 @@ async function bootstrapInner(prepared, identity) {
     logBootstrapTimings(result);
     return result;
 }
+// Captured as false in the shared template, true in a seeded interactive
+// snapshot. Repeated requests must not apply a successful seed twice.
+let interactiveSetupCompleted = false;
 /**
- * Run the loaded project's `setup` hook, if any. Called by the control
- * plane once between /bootstrap and the warm-template snapshot, so the
- * effects (seeded DB rows, initial pods, fixture files) are captured
- * exactly once and inherited by every later snapshot/fork.
+ * Run a project setup hook. Normal `setup` runs before the shared warm
+ * snapshot; `setupInteractive` runs only after it, in a fresh user start.
+ * Both use the same context and boot-log capture.
  *
  * Unlike test runs, this is NOT instrumented — no recorder, no event
  * timeline, no timeout from the test runner. Setup failures abort the
  * env bring-up; the control plane surfaces them as a start failure.
  */
-async function runProjectSetup() {
+async function runProjectSetup(hook = "setup") {
     // Same tee as bootstrap: a project `setup` hook's console output is
     // part of explaining the boot, not something to lose on success.
     const restoreBootLog = captureConsole(BOOT_LOG_SINK);
     try {
-        return await runProjectSetupInner();
+        return await runProjectSetupInner(hook);
     }
     finally {
         restoreBootLog();
     }
 }
-async function runProjectSetupInner() {
-    const proj = requireLoaded().project;
-    if (!proj.setup)
+async function runProjectSetupInner(hook) {
+    const setup = requireLoaded().project[hook];
+    if (!setup || (hook === "setupInteractive" && interactiveSetupCompleted)) {
         return { ran: false, durationMs: 0 };
+    }
     const start = Date.now();
     // Install the fetch wrapper for the duration of setup so `ctx.fetch` (and any
     // client routed through `globalThis.fetch`) returns a wrapped Response, same
@@ -2960,9 +2963,11 @@ async function runProjectSetupInner() {
     // The full context, unscoped: every service is up by project-setup time,
     // so `ctx.svc` is the same map tests see (and shares helper instances with
     // them — a Bun.SQL pool created here is reused later).
-    const ctx = await spectestContext();
     try {
-        await runInstrumented(fetchScope, () => proj.setup(ctx));
+        const ctx = await spectestContext();
+        await runInstrumented(fetchScope, () => setup(ctx));
+        if (hook === "setupInteractive")
+            interactiveSetupCompleted = true;
     }
     finally {
         fetchScope.active = false;
@@ -5131,7 +5136,13 @@ export function harnessMethods(state) {
         setRecordSecrets(secrets);
     };
     return {
-        health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
+        health: async () => ({
+            ok: true,
+            capabilities: ["prepared-images-v1"],
+            // Optional discovery: old SDKs omit this field and are never sent the
+            // new method. Check the loaded project, including after warm restore.
+            setupInteractive: typeof loaded?.project.setupInteractive === "function",
+        }),
         // Live bootstrap progress, polled by the control plane during
         // `bootstrap` and streamed into the test-run row. `{}` before the
         // first bootstrap of this harness process.
@@ -5248,6 +5259,7 @@ export function harnessMethods(state) {
             return { ok: true, timings: await bootstrap(prepared) };
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
+        interactiveSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup("setupInteractive")),
         eval: async (params) => {
             const code = requireString(params, "code");
             return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/dist/harness/protocol.d.ts

@@ -23,7 +23,7 @@
 /** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
 export declare const PROTOCOL_VERSION = 1;
 /** Methods either side can send. */
-export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
+export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
 /** Methods this build knows how to dispatch. A method outside this set still
  *  *parses* — it is answered with an error, never dropped. */
 export declare const KNOWN_METHODS: ReadonlySet<string>;

package/dist/harness/protocol.js

@@ -30,6 +30,7 @@ export const KNOWN_METHODS = new Set([
     "loadTests",
     "fingerprint",
     "bootstrap",
+    "interactiveSetup",
     "run",
     "eval",
     "setRecordSecrets",

package/dist/helper-tracking.js

@@ -83,9 +83,11 @@ function invokeHelper(kind, name, member, fn, receiver, callArgs) {
     };
     let result;
     try {
+        // Reading a callable proxy's `.apply` can bind directly to its raw client
+        // and bypass instrumentation (SQL does this). Invoke the proxy itself.
         result = recording.run(() => kind === "fake"
-            ? runUninstrumented(() => fn.apply(receiver, args))
-            : fn.apply(receiver, args));
+            ? runUninstrumented(() => Reflect.apply(fn, receiver, args))
+            : Reflect.apply(fn, receiver, args));
     }
     catch (error) {
         return fail(error);

package/dist/index.d.ts

@@ -1624,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> {
 }
@@ -1673,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>[];
 }
@@ -1726,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

@@ -484,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/package.json

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

package/src/daemon.ts

@@ -3473,30 +3473,35 @@ interface ProjectSetupResult {
   durationMs: number;
 }
 
+// Captured as false in the shared template, true in a seeded interactive
+// snapshot. Repeated requests must not apply a successful seed twice.
+let interactiveSetupCompleted = false;
+
 /**
- * Run the loaded project's `setup` hook, if any. Called by the control
- * plane once between /bootstrap and the warm-template snapshot, so the
- * effects (seeded DB rows, initial pods, fixture files) are captured
- * exactly once and inherited by every later snapshot/fork.
+ * Run a project setup hook. Normal `setup` runs before the shared warm
+ * snapshot; `setupInteractive` runs only after it, in a fresh user start.
+ * Both use the same context and boot-log capture.
  *
  * Unlike test runs, this is NOT instrumented — no recorder, no event
  * timeline, no timeout from the test runner. Setup failures abort the
  * env bring-up; the control plane surfaces them as a start failure.
  */
-async function runProjectSetup(): Promise<ProjectSetupResult> {
+async function runProjectSetup(hook: "setup" | "setupInteractive" = "setup"): Promise<ProjectSetupResult> {
   // Same tee as bootstrap: a project `setup` hook's console output is
   // part of explaining the boot, not something to lose on success.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
   try {
-    return await runProjectSetupInner();
+    return await runProjectSetupInner(hook);
   } finally {
     restoreBootLog();
   }
 }
 
-async function runProjectSetupInner(): Promise<ProjectSetupResult> {
-  const proj = requireLoaded().project;
-  if (!proj.setup) return { ran: false, durationMs: 0 };
+async function runProjectSetupInner(hook: "setup" | "setupInteractive"): Promise<ProjectSetupResult> {
+  const setup = requireLoaded().project[hook];
+  if (!setup || (hook === "setupInteractive" && interactiveSetupCompleted)) {
+    return { ran: false, durationMs: 0 };
+  }
   const start = Date.now();
   // Install the fetch wrapper for the duration of setup so `ctx.fetch` (and any
   // client routed through `globalThis.fetch`) returns a wrapped Response, same
@@ -3507,9 +3512,10 @@ async function runProjectSetupInner(): Promise<ProjectSetupResult> {
   // The full context, unscoped: every service is up by project-setup time,
   // so `ctx.svc` is the same map tests see (and shares helper instances with
   // them — a Bun.SQL pool created here is reused later).
-  const ctx: ProjectSetupContext = await spectestContext();
   try {
-    await runInstrumented(fetchScope, () => proj.setup!(ctx));
+    const ctx: ProjectSetupContext = await spectestContext();
+    await runInstrumented(fetchScope, () => setup(ctx));
+    if (hook === "setupInteractive") interactiveSetupCompleted = true;
   } finally {
     fetchScope.active = false;
     restoreFetch();
@@ -6148,7 +6154,13 @@ export function harnessMethods(state: RouteState): MethodTable {
     setRecordSecrets(secrets as Record<string, string>);
   };
   return {
-    health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
+    health: async () => ({
+      ok: true,
+      capabilities: ["prepared-images-v1"],
+      // Optional discovery: old SDKs omit this field and are never sent the
+      // new method. Check the loaded project, including after warm restore.
+      setupInteractive: typeof loaded?.project.setupInteractive === "function",
+    }),
 
     // Live bootstrap progress, polled by the control plane during
     // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -6285,6 +6297,14 @@ export function harnessMethods(state: RouteState): MethodTable {
         () => runProjectSetup(),
       ),
 
+    interactiveSetup: async () =>
+      exclusive(
+        state,
+        "inFlightProjectSetup",
+        "project-setup already in progress",
+        () => runProjectSetup("setupInteractive"),
+      ),
+
     eval: async (params) => {
       const code = requireString(params, "code");
       return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/src/harness/protocol.ts

@@ -32,6 +32,7 @@ export type Method =
   | "loadTests"
   | "fingerprint"
   | "bootstrap"
+  | "interactiveSetup"
   | "run"
   | "eval"
   | "setRecordSecrets"
@@ -51,6 +52,7 @@ export const KNOWN_METHODS: ReadonlySet<string> = new Set<Method>([
   "loadTests",
   "fingerprint",
   "bootstrap",
+  "interactiveSetup",
   "run",
   "eval",
   "setRecordSecrets",

package/src/helper-tracking.test.ts

@@ -3,6 +3,7 @@ import { annotate } from "./annotate.js";
 import { expect as assertValue, type ServiceHandlesFor, type Wrapped } from "./index.js";
 import { readRaw, readTag, wrap } from "./inspect.js";
 import { trackHelpers } from "./helper-tracking.js";
+import { SQL } from "./sql.js";
 import {
   recordHttp, recordWait, recorderEventCount, recorderMarkChildren, recorderTruncate,
   startRecording, stopRecording,
@@ -175,6 +176,41 @@ test("live objects, callable clients, function properties and receivers survive"
   expect<unknown>(readRaw(helper.latest.call({...raw, subject: "Other"}))).toEqual({subject: "Other"});
 });
 
+test("a tracked SQL client keeps tagged queries and attached methods instrumented", async () => {
+  const client = new SQL("sqlite://:memory:", { label: "db" });
+  const helper = trackHelpers("service", "db", { client });
+  startRecording();
+  try {
+    const rows = await helper.client<{ id: number }>`SELECT ${7} AS id`;
+    assertValue(rows.transform("ids", (rows) => Array.from(rows, (row) => row.id))).toEqual([7]);
+    const other = await helper.client.unsafe<{ id: number }>("SELECT ? AS id", [8]);
+    assertValue(other[0]!.id).toBe(8);
+    const events = stopRecording();
+    expect(events.map((event) => event.kind)).toEqual(["db", "assertion", "db", "assertion"]);
+    expect(events[0]).toMatchObject({ service: "db", query: "SELECT $1 AS id", params: [7], rows: [{ id: 7 }] });
+    expect(events[1]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["<ids>"] });
+    expect(events[2]).toMatchObject({ service: "db", query: "SELECT ? AS id", params: [8], rows: [{ id: 8 }] });
+    expect(events[3]).toMatchObject({ sourceSeq: events[2]!.seq, path: ["0", "id"] });
+  } finally {
+    await helper.client.close!();
+  }
+});
+
+test("a tracked SQL client preserves query failure diagnostics", async () => {
+  const client = new SQL("sqlite://:memory:", { label: "db" });
+  const helper = trackHelpers("service", "db", { client });
+  startRecording();
+  try {
+    await expect(helper.client`SELECT * FROM missing_table`).rejects.toThrow("no such table");
+    const events = stopRecording();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ kind: "db", service: "db", query: "SELECT * FROM missing_table",
+      error: expect.stringContaining("no such table") });
+  } finally {
+    await helper.client.close!();
+  }
+});
+
 test("setup/eval unwrap annotated returns without recording", async () => {
   const scope = createInstrumentationScope(false);
   const helper = trackHelpers("service", "mail", { latest: () => annotate({subject: "Invoice"}, "email") });

package/src/helper-tracking.ts

@@ -93,9 +93,11 @@ function invokeHelper(
   };
   let result: unknown;
   try {
+    // Reading a callable proxy's `.apply` can bind directly to its raw client
+    // and bypass instrumentation (SQL does this). Invoke the proxy itself.
     result = recording.run(() => kind === "fake"
-      ? runUninstrumented(() => fn.apply(receiver, args))
-      : fn.apply(receiver, args));
+      ? runUninstrumented(() => Reflect.apply(fn, receiver, args))
+      : Reflect.apply(fn, receiver, args));
   } catch (error) {
     return fail(error);
   }

package/src/index.ts

@@ -2377,18 +2377,26 @@ export interface Project<
    * 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,
@@ -2437,6 +2445,8 @@ export interface ProjectOpts<
 > {
   /** 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>[];
 }
@@ -2501,7 +2511,7 @@ export interface DefinedEnvironment<
   ): 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>;
@@ -2653,6 +2663,7 @@ export function defineEnvironment<
       : (arg ?? {});
     const proj: Project<S, F> = { 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) {
       // Explicit suite (single-file / legacy layout): the tests are listed

package/src/interactive-setup.test.ts

@@ -0,0 +1,89 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// The daemon owns globals and snapshot-resident state. Use a fresh process,
+// just as each freshly built environment has its own harness.
+for (const withHook of [false, true]) {
+  test(`interactive setup: ${withHook ? "context, failure, exclusion and one-shot state" : "optional hook"}`, async () => {
+    const root = await mkdtemp(join(tmpdir(), "spectest-interactive-setup-"));
+    try {
+      await mkdir(join(root, "spectest"));
+      await mkdir(join(root, "bin"));
+      await writeFile(join(root, "bin/docker"), '#!/bin/sh\nprintf "%s\\n" "$*"\n', { mode: 0o755 });
+      const entry = join(root, "spectest/index.ts");
+      await writeFile(entry, `
+        import { defineEnvironment } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+        export const calls = [];
+        const env = defineEnvironment({ name: "seed", services: {
+          app: { image: { type: "registry", reference: "busybox" },
+            helpers: () => ({ label: "typed helper" }) },
+        }});
+        export default env.project({
+          setup: () => { calls.push("baseline"); },
+          ${withHook ? `setupInteractive: async (ctx) => {
+            calls.push("interactive");
+            console.log("seeding demo data");
+            await globalThis.seedGate;
+            if (globalThis.failSeed) throw new Error("seed rejected");
+            const response = await ctx.fetch("data:application/json,%7B%22ok%22%3Atrue%7D");
+            if (response.status.unwrap() !== 200) throw new Error("fetch not wrapped");
+            if (ctx.svc.app.label !== "typed helper") throw new Error("missing helpers");
+            if ("browser" in ctx || "testName" in ctx) throw new Error("test context leaked");
+            const result = await ctx.exec("app", ["seed", "demo"]);
+            if (typeof result.exitCode !== "number" || !result.stdout.includes("seed demo")) {
+              throw new Error("exec result not plain: " + JSON.stringify(result));
+            }
+          },` : ""}
+        });
+      `);
+      const script = `
+        import { strict as assert } from "node:assert";
+        import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
+        import { calls } from ${JSON.stringify(entry)};
+        const nativeFetch = globalThis.fetch;
+        await METHODS.load({});
+        assert.equal((await METHODS.health({})).setupInteractive, ${withHook});
+        await METHODS.projectSetup({});
+        assert.deepEqual(calls, ["baseline"]);
+        ${withHook ? `
+          let release;
+          globalThis.seedGate = new Promise(r => { release = r; });
+          globalThis.failSeed = true;
+          const failed = METHODS.interactiveSetup({});
+          await assert.rejects(METHODS.interactiveSetup({}), /already in progress/);
+          await assert.rejects(METHODS.projectSetup({}), /already in progress/);
+          release();
+          await assert.rejects(failed, /seed rejected/);
+          assert.equal(globalThis.fetch, nativeFetch);
+          globalThis.failSeed = false;
+          assert.equal((await METHODS.interactiveSetup({})).ran, true);
+          assert.deepEqual(calls, ["baseline", "interactive", "interactive"]);
+          // A repeated request (or a resumed seeded snapshot) cannot reseed.
+          assert.equal((await METHODS.interactiveSetup({})).ran, false);
+          assert.deepEqual(calls, ["baseline", "interactive", "interactive"]);
+          const logs = await METHODS.envLogs({});
+          assert.ok(logs.bootLog.includes("seeding demo data"));
+        ` : `
+          assert.equal((await METHODS.interactiveSetup({})).ran, false);
+          assert.deepEqual(calls, ["baseline"]);
+        `}
+        assert.equal(globalThis.fetch, nativeFetch);
+        // envLogs' subprocess timeout keeps a timer alive after it returns;
+        // this fixture tests hook behavior, not daemon process lifetime.
+        process.exit(0);
+      `;
+      const child = Bun.spawn([process.execPath, "--eval", script], {
+        env: { ...process.env, SPECTEST_APP_DIR: root, PATH: `${root}/bin:${process.env.PATH}` },
+        stdout: "pipe", stderr: "pipe",
+      });
+      const [code, stdout, stderr] = await Promise.all([
+        child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+      ]);
+      expect(code, stdout + stderr).toBe(0);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 20_000);
+}