@specific.dev/spectest 0.31.0 → 0.32.1

package/dist/daemon.js

@@ -2553,7 +2553,11 @@ async function bootstrapInner() {
         if (svc.setup) {
             progressService(svc.name, { status: "probing", detail: "running setup" });
             const helpers = await ensureHelpers(svc.name, svc);
-            await svc.setup({ name: svc.name, helpers, ...componentContext() });
+            await svc.setup({
+                name: svc.name,
+                helpers,
+                ...(await spectestContext({ service: svc.name, includeSelf: true })),
+            });
         }
         progressService(svc.name, { status: "ready", detail: undefined });
         const ti = timings.get(svc.name);
@@ -2622,25 +2626,15 @@ async function runProjectSetupInner() {
     if (!proj.setup)
         return { ran: false, durationMs: 0 };
     const start = Date.now();
-    // Build the same `svc` handles tests see, so setup and tests share
-    // helper instances (e.g. a Bun.SQL pool created here is reused later).
-    const svc = (await buildServiceHandles(proj.environment));
-    const fakes = await buildFakeHandles();
     // Install the fetch wrapper for the duration of setup so `ctx.fetch` (and any
     // client routed through `globalThis.fetch`) returns a wrapped Response, same
     // as in a test. No recorder is active here, so it wraps without provenance —
     // but the wrapped type stays honest at runtime (`.unwrap()` works).
     const restoreFetch = installFetchWrapper();
-    const ctx = {
-        fetch: globalThis.fetch,
-        exec: execInServiceWrapped,
-        svc,
-        fakes,
-        dnsName: registerDnsName,
-        certificate: mintCertificate,
-        startService: startRuntimeService,
-        stopService: stopRuntimeService,
-    };
+    // 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 proj.setup(ctx);
     }
@@ -3013,63 +3007,131 @@ const TEST_DATA = new Map();
 // so components don't hand-roll child_process docker execs or hard-code
 // control-plane paths like /workspace.
 // ────────────────────────────────────────────────────────────────────────
+/** Default `ctx.exec` timeout inside a service-level `setup`/`helpers`
+ *  hook. Those run during boot where nothing else bounds them, so a wedged
+ *  command would hang the whole env start. A test's exec inherits the
+ *  test timeout instead, and a project `setup` — which routinely waits on
+ *  rollouts — stays unbounded, so neither gets a default. */
 const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
 /** Raw `docker exec` with optional piped stdin. Array command = exact
  * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
- * `exitCode`, never thrown. Unlike `execInService` this records nothing —
- * setup/helpers-factory time has no test timeline. */
-function componentExec(service, command, opts) {
+ * `exitCode`, never thrown. Unlike the test-context `exec` this records
+ * nothing — setup/helpers-factory time has no test timeline. */
+function componentExec(service, command, opts, defaultTimeoutMs) {
     assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
-    const argv = ["exec", "-i"];
-    if (opts?.cwd)
-        argv.push("-w", opts.cwd);
-    argv.push(service);
-    if (typeof command === "string")
-        argv.push("sh", "-lc", command);
-    else
-        argv.push(...command);
-    const timeoutMs = opts?.timeoutMs ?? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS;
-    return new Promise((resolve, reject) => {
-        const child = spawn("docker", argv, {
-            stdio: [opts?.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
-        });
-        const out = [];
-        const err = [];
-        child.stdout.on("data", (c) => out.push(c));
-        child.stderr.on("data", (c) => err.push(c));
-        let timedOut = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGKILL");
-        }, timeoutMs);
-        child.on("error", (e) => {
-            clearTimeout(timer);
-            reject(e);
-        });
-        child.on("close", (code) => {
-            clearTimeout(timer);
-            // A SIGKILL'd child reports 137, which reads like an OOM kill.
-            // Report the `timeout(1)` convention plus a note instead, so a
-            // wedged command is diagnosable from the result alone.
-            const stderrText = Buffer.concat(err).toString("utf8");
-            resolve({
-                stdout: Buffer.concat(out).toString("utf8"),
-                stderr: timedOut
-                    ? `${stderrText}\ntimeout after ${timeoutMs}ms`
-                    : stderrText,
-                exitCode: timedOut ? EXEC_TIMEOUT_EXIT_CODE : (code ?? -1),
-            });
-        });
-        feedStdin(child, opts?.stdin);
+    const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
+    return execInService(service, command, {
+        ...opts,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+}
+/** Transitive `dependsOn` closure of a service, by name. */
+function transitiveDeps(service) {
+    const services = loaded?.project.environment.services ?? {};
+    const seen = new Set();
+    const walk = (name) => {
+        for (const dep of services[name]?.dependsOn ?? []) {
+            if (seen.has(dep) || !services[dep])
+                continue;
+            seen.add(dep);
+            walk(dep);
+        }
+    };
+    walk(service);
+    return seen;
+}
+/** Property reads that are language plumbing, not a service lookup —
+ *  `then` above all: a context object holding this map gets awaited, and a
+ *  throwing `then` read would turn `await ctx` into a hard failure. */
+const SVC_PLUMBING_PROPS = ["then", "toJSON", "constructor"];
+/**
+ * `svc` for a service-level hook: the handles of everything the DAG says
+ * is up, behind a Proxy that turns a read of anything else into an error
+ * naming the fix rather than a `undefined is not an object` further down.
+ */
+function scopedServiceHandles(built, scope) {
+    const allowed = transitiveDeps(scope.service);
+    if (scope.includeSelf)
+        allowed.add(scope.service);
+    return new Proxy(built.handles, {
+        get(target, prop, receiver) {
+            if (typeof prop === "string" &&
+                !SVC_PLUMBING_PROPS.includes(prop) &&
+                !(prop in target)) {
+                // A dependency whose own `helpers` factory blew up: surface THAT
+                // error, and only if someone actually reads the handle — a hook
+                // that never touches `ctx.svc` shouldn't fail over a sibling's
+                // broken factory.
+                const failure = built.failures.get(prop);
+                if (failure)
+                    throw failure;
+                if (!allowed.has(prop)) {
+                    const known = loaded?.project.environment.services ?? {};
+                    throw new Error(known[prop]
+                        ? `ctx.svc.${prop} is not available in ${scope.service}'s ${scope.includeSelf ? "setup" : "helpers"} hook: "${prop}" is not a dependency of "${scope.service}", so it may not be running yet. Add it to ${scope.service}'s \`dependsOn\`.`
+                        : `ctx.svc.${prop}: no service named "${prop}" in this environment.`);
+                }
+            }
+            return Reflect.get(target, prop, receiver);
+        },
     });
 }
-function componentContext() {
+/**
+ * Build the context every hook receives. `scope` decides which services'
+ * handles are reachable and whether `exec` gets the boot-time default
+ * timeout; everything else is identical in every context.
+ */
+async function spectestContext(scope = {}) {
+    const handles = scope.service
+        ? scopedServiceHandles(await buildScopedHandles(scope.service, scope.includeSelf === true), { ...scope, service: scope.service })
+        : loaded
+            ? await buildServiceHandles(loaded.project.environment)
+            : {};
+    const fakes = loaded ? await buildFakeHandles() : {};
+    const execTimeoutMs = scope.service ? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS : undefined;
     return {
         projectRoot: WORKSPACE,
         readProjectFile: (p) => fs.readFile(path.isAbsolute(p) ? p : path.join(WORKSPACE, p), "utf8"),
-        exec: componentExec,
+        exec: (service, command, opts) => componentExec(service, command, opts, execTimeoutMs),
+        // Read `globalThis.fetch` at call time: the wrapper is installed for
+        // the duration of a test / eval / project setup, so a context built
+        // before it lands still gets the wrapped one.
+        fetch: ((input, init) => globalThis.fetch(input, init)),
+        svc: handles,
+        fakes: fakes,
+        poll: pollCall,
+        dnsName: registerDnsName,
+        certificate: mintCertificate,
+        startService: startRuntimeService,
+        stopService: stopRuntimeService,
     };
 }
+/** Handles for a service hook: its dependencies (always up by the time the
+ *  hook runs) plus, for a `setup` hook, the service itself. Built eagerly —
+ *  the factories are cached, so a later test reuses these instances, and
+ *  building them here puts them in the warm-template snapshot. A factory
+ *  that throws is recorded rather than propagated: only a hook that
+ *  actually reads that handle should fail (see `scopedServiceHandles`). */
+async function buildScopedHandles(service, includeSelf) {
+    const services = loaded?.project.environment.services ?? {};
+    const names = transitiveDeps(service);
+    if (includeSelf)
+        names.add(service);
+    const handles = {};
+    const failures = new Map();
+    for (const name of names) {
+        const def = services[name];
+        if (!def?.helpers)
+            continue;
+        try {
+            handles[name] = await ensureHelpers(name, def);
+        }
+        catch (err) {
+            failures.set(name, err);
+        }
+    }
+    return { handles, failures };
+}
 // Cached helper namespaces produced by `ServiceDefinition.helpers`
 // factories. Built lazily on first access and reused for the daemon's
 // lifetime — Bun.SQL pools and similar resources are happy to live a
@@ -3086,10 +3148,30 @@ async function ensureHelpers(name, def) {
     if (!def.helpers)
         return {};
     if (!HELPERS_CACHE.has(name)) {
-        HELPERS_CACHE.set(name, await def.helpers({ name, ...componentContext() }));
+        // A factory can now read `ctx.svc` (its dependencies'), so it can
+        // re-enter this function. Deps are a DAG, but a factory reaching a
+        // NON-dependency it happens to be reachable from would spin forever —
+        // report the cycle instead of hanging the boot.
+        if (HELPERS_BUILDING.has(name)) {
+            throw new Error(`helpers factory cycle: building ctx.svc.${name} re-entered itself ` +
+                `(via ${[...HELPERS_BUILDING].join(" → ")}). A helpers factory can read its ` +
+                `dependencies' handles, but they must not read back.`);
+        }
+        HELPERS_BUILDING.add(name);
+        try {
+            HELPERS_CACHE.set(name, await def.helpers({
+                name,
+                ...(await spectestContext({ service: name, includeSelf: false })),
+            }));
+        }
+        finally {
+            HELPERS_BUILDING.delete(name);
+        }
     }
     return HELPERS_CACHE.get(name);
 }
+/** Names whose `helpers` factory is mid-flight — see the cycle check above. */
+const HELPERS_BUILDING = new Set();
 /**
  * Build the `svc` map for one test/eval. The value at `svc[name]` is
  * exactly the record the service's `helpers` factory returned (e.g.
@@ -3209,21 +3291,32 @@ function installFetchWrapper() {
         globalThis.fetch = original;
     };
 }
-/** Build the `docker exec` argv for a service command. An optional `cwd`
- *  becomes `-w <cwd>` (the working-directory option of `ctx.exec`), so the
- *  command runs from that directory without it being baked into the command
- *  string. `-i` is passed whenever stdin will be piped — without it docker
- *  attaches no stdin and the payload is silently discarded. Used by both the
- *  buffered and streaming variants so they stay in lockstep. */
+/** Build the `docker exec` argv for a service command. A string command runs
+ *  through `sh -lc`; an array is exact argv with no shell (the
+ *  `["psql", "-f", "-"]` shape). An optional `cwd` becomes `-w <cwd>` (the
+ *  working-directory option of `ctx.exec`), so the command runs from that
+ *  directory without it being baked into the command string. `-i` is passed
+ *  whenever stdin will be piped — without it docker attaches no stdin and the
+ *  payload is silently discarded. Used by both the buffered and streaming
+ *  variants so they stay in lockstep. */
 function dockerExecArgs(service, command, opts) {
     const args = ["exec"];
     if (opts?.stdin !== undefined)
         args.push("-i");
     if (opts?.cwd)
         args.push("-w", opts.cwd);
-    args.push(service, "sh", "-lc", command);
+    args.push(service);
+    if (typeof command === "string")
+        args.push("sh", "-lc", command);
+    else
+        args.push(...command);
     return args;
 }
+/** How an argv-array command is shown in the timeline / asciicast prompt.
+ *  Display only — the real invocation never goes through a shell. */
+function displayCommand(command) {
+    return typeof command === "string" ? command : command.join(" ");
+}
 /** Exit code reported when an exec is killed by its own `timeoutMs`
  *  (the `timeout(1)` convention, matching `shx`). */
 const EXEC_TIMEOUT_EXIT_CODE = 124;
@@ -3515,14 +3608,17 @@ async function runOne(testCase) {
         const t = Date.now();
         const cwd = opts?.cwd;
         const resv = reserveEvent();
-        const session = newTerminalSession(start, service, command, EXEC_CAST_COLS, EXEC_CAST_ROWS, testCase.id);
+        // An argv array has no shell form to show; render it space-joined for
+        // the prompt line and the timeline row (display only).
+        const shown = displayCommand(command);
+        const session = newTerminalSession(start, service, shown, EXEC_CAST_COLS, EXEC_CAST_ROWS, testCase.id);
         terminalSessions.push(session.record);
         // Synthetic prompt frame so the replay is self-describing — the
         // program's own output starts on the next line, like a real shell. A
         // working directory rides in the prompt sigil (`svc:/dir $`) the way a
         // real shell prompt shows it, so the recording stays self-describing.
         const sigil = cwd ? `${service}:${cwd}` : service;
-        session.pushFrame(0, `\x1b[32m${sigil} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
+        session.pushFrame(0, `\x1b[32m${sigil} $\x1b[0m \x1b[1m${shown}\x1b[0m\r\n`);
         let frameBytes = 0;
         let frameCapped = false;
         const res = await execInServiceStreaming(service, command, (_stream, data) => {
@@ -3551,7 +3647,7 @@ async function runOne(testCase) {
         const stdin = opts?.stdin !== undefined ? truncateUtf8(opts.stdin) : undefined;
         const seq = recordExec({
             service,
-            command,
+            command: shown,
             cwd,
             ...(stdin
                 ? { stdin: stdin.value, stdinTruncated: stdin.truncated }
@@ -3713,20 +3809,16 @@ async function runOne(testCase) {
         sharedMobiles.set(app.url, mobile);
         return mobile;
     };
-    // Build convenience handles (e.g. ctx.svc.db.client) from the loaded
-    // project. Done before installing the timeout so a slow client factory
-    // surfaces as a real error rather than getting attributed to the test.
-    const svc = await buildServiceHandles(requireLoaded().project.environment);
-    const fakes = await buildFakeHandles();
+    // The shared context (svc/fakes handles, poll, project files, dnsName,
+    // certificate, runtime services) — identical to what a `setup` hook gets.
+    // Built before installing the timeout so a slow client factory surfaces as
+    // a real error rather than getting attributed to the test.
+    const base = await spectestContext();
     const ctx = {
-        // installFetchWrapper just swapped globalThis.fetch for the wrapped
-        // version, so capturing it here gets us instrumentation on ctx.fetch
-        // for free. The recorder is active for the test, so responses come
-        // back wrapped — hence the SpectestFetch type.
-        fetch: globalThis.fetch,
+        ...base,
         // exec/terminal/poll wrap their results at runtime (the recorder is
-        // active), so the ctx interface types them wrapped — same bridge as
-        // `fetch` above. The impls' own return types stay raw.
+        // active), so the ctx interface types them wrapped. The impls' own
+        // return types stay raw — hence the bridging casts.
         exec: recordedExec,
         terminal: recordedTerminal,
         openTerminal: recordedOpenTerminal,
@@ -3734,13 +3826,6 @@ async function runOne(testCase) {
         mobile: trackedOpenMobile,
         testName: testCase.name,
         parent,
-        svc,
-        fakes,
-        poll: pollCall,
-        dnsName: registerDnsName,
-        certificate: mintCertificate,
-        startService: startRuntimeService,
-        stopService: stopRuntimeService,
     };
     const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
     let timer;
@@ -4072,19 +4157,14 @@ async function evalCode(code, secrets) {
     const evalOpenTerminal = async (service, opts) => {
         return openInstrumentedTerminal(service, opts, start, terminalSessions, false, "eval");
     };
-    // Convenience handles are best-effort for eval — if the project isn't
-    // loaded yet, fall back to an empty map so quick `await fetch(...)`
+    // The shared context. Handles are best-effort for eval — with no project
+    // loaded `spectestContext()` yields empty maps, so quick `await fetch(...)`
     // snippets don't require a /load round-trip first.
-    const svc = loaded
-        ? await buildServiceHandles(loaded.project.environment)
-        : {};
-    const fakes = loaded ? await buildFakeHandles() : {};
+    const base = await spectestContext();
     const ctx = {
-        // installFetchWrapper swapped globalThis.fetch above, so this captures the
-        // wrapped version — eval results are wrapped just like in a test.
-        fetch: globalThis.fetch,
-        // Wraps its result the same way (no recorder under eval, so no provenance —
-        // but the wrapped type is honest at runtime, so `.unwrap()` works).
+        ...base,
+        // Wraps its result (no recorder under eval, so no provenance — but the
+        // wrapped type is honest at runtime, so `.unwrap()` works).
         exec: execInServiceWrapped,
         terminal: evalTerminal,
         openTerminal: evalOpenTerminal,
@@ -4092,13 +4172,6 @@ async function evalCode(code, secrets) {
         mobile: trackedOpenMobile,
         testName: "eval",
         parent: undefined,
-        svc,
-        fakes,
-        poll: pollCall,
-        dnsName: registerDnsName,
-        certificate: mintCertificate,
-        startService: startRuntimeService,
-        stopService: stopRuntimeService,
     };
     // Expose the test context, matchers, and persistent state as globals
     // so the snippet can use them without an explicit import. The user code