@specific.dev/spectest 0.86.0 → 0.86.1

package/dist/daemon.js

@@ -15,8 +15,9 @@
 // One sandbox = one daemon. Concurrency between tests is achieved by
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
+import { preparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -2947,23 +2948,31 @@ function logBootstrapTimings(t) {
     }
     console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
-async function bootstrap() {
+async function bootstrap(prepared) {
     // Tee everything this bootstrap logs — ours and every service `setup`
     // hook's — into the boot log, so GET /boot-log can explain a slow or
     // finished boot. Restored in the finally at the end.
     const restoreBootLog = captureConsole(BOOT_LOG_SINK);
     try {
-        return await bootstrapInner();
+        return await bootstrapInner(prepared);
     }
     finally {
         restoreBootLog();
     }
 }
-async function bootstrapInner() {
+async function imageInput(svc) {
+    const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+    return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+async function bootstrapInner(prepared, identity) {
     const bootStart = Date.now();
     const cfg = requireLoaded().project.environment;
     const services = namedServices(cfg);
     const timings = new Map();
+    if (prepared && (prepared.version !== 1 || !prepared.images ||
+        Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+        throw new Error("prepared image manifest does not match the environment's services");
+    }
     progressInit(services);
     // Build dedup is only valid within one workspace generation — a fresh
     // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3010,11 +3019,25 @@ async function bootstrapInner() {
     const tags = new Map();
     // Bootstrap is the only dedup scope: all its builds share one
     // /workspace generation (see prepareServiceImage).
-    const prepImage = (svc) => prepareServiceImage(svc, { dedup: true });
+    const prepImage = async (svc) => {
+        if (!prepared)
+            return prepareServiceImage(svc, { dedup: true });
+        const entry = prepared.images[svc.name];
+        if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+            throw new Error(`prepared image inputs changed for ${svc.name}`);
+        }
+        const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+        if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+            throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+        }
+        return { tag: entry.image, buildSteps: entry.buildSteps };
+    };
     const prep = new Map();
+    const prepOffsets = new Map();
     for (const svc of services) {
         const p = (async () => {
             const t0 = Date.now();
+            prepOffsets.set(svc.name, Date.now() - bootStart);
             const { tag, buildSteps } = await prepImage(svc);
             progressService(svc.name, { status: "prepared", detail: undefined });
             tags.set(svc.name, tag);
@@ -3032,6 +3055,21 @@ async function bootstrapInner() {
         p.catch(() => undefined);
         prep.set(svc.name, p);
     }
+    if (identity !== undefined) {
+        // No application services, setup hooks, ingress, or runtime state in the builder.
+        await Promise.all(prep.values());
+        const images = Object.create(null);
+        for (const svc of services) {
+            const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)], 30_000);
+            const image = out.stdout.trim();
+            if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+                throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+            }
+            const ti = timings.get(svc.name);
+            images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+        }
+        return { version: 1, identity, images };
+    }
     // Ingress (fakes + service-tls proxies) comes up BEFORE services so
     // that any service that calls a fake URL during its own startup
     // probe finds it answering. Service-tls proxies will return 502
@@ -3488,8 +3526,13 @@ async function writeCoverageInventory(svc) {
         },
         projectFiles: () => walkProjectFiles(WORKSPACE),
         async readProjectFile(p) {
+            // Not recorded as a read: an inventory fingerprinting every
+            // manifest is bookkeeping, not the suite depending on the files.
+            // Recording them made the setup set name every package.json as a
+            // whole file, so a version bump was "ran during environment
+            // setup" — a full run, the exact case the inventory exists for.
             try {
-                return await fs.readFile(resolveProjectPath(p), "utf8");
+                return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
             }
             catch {
                 return null;
@@ -3521,9 +3564,22 @@ async function writeCoverageInventory(svc) {
  * The project's reach (`harness/reach.ts`): every project file some
  * service's build context includes, some volume mounts, or a build
  * reads. Computed from the same resolution the builds use, once at the
- * bring-up capture.
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
  */
 async function computeProjectReach(all) {
+    const before = takeProjectReads();
+    try {
+        return await computeProjectReachInner(all);
+    }
+    finally {
+        // Discard what the resolution recorded, restore what was there.
+        takeProjectReads();
+        for (const p of before)
+            resolveProjectPath(p);
+    }
+}
+async function computeProjectReachInner(all) {
     const files = await walkProjectFiles(WORKSPACE, [".git"]);
     const sources = [];
     for (const svc of all) {
@@ -5398,7 +5454,7 @@ function loadedSummary(l) {
  */
 export function harnessMethods(state) {
     return {
-        health: async () => ({ ok: true }),
+        health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
         // 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.
@@ -5497,10 +5553,19 @@ export function harnessMethods(state) {
             }
             return { refs: [...refs] };
         },
-        bootstrap: async () => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-            ok: true,
-            timings: await bootstrap(),
-        })),
+        prepareImages: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const restore = captureConsole(BOOT_LOG_SINK);
+            try {
+                return await bootstrapInner(undefined, requireString(params, "identity"));
+            }
+            finally {
+                restore();
+            }
+        }),
+        bootstrap: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+            const prepared = params.prepared === undefined ? undefined : preparedImages(params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name));
+            return { ok: true, timings: await bootstrap(prepared) };
+        }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         eval: async (params) => {
             const code = requireString(params, "code");

package/dist/harness/prepared-images.d.ts

@@ -0,0 +1,14 @@
+import type { BuildStep } from "./buildkit-progress.js";
+export interface PreparedImages {
+    version: 1;
+    identity: string;
+    images: Record<string, {
+        input: string;
+        image: string;
+        prepMs: number;
+        startMs?: number;
+        buildSteps?: BuildStep[];
+    }>;
+}
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export declare function preparedImages(value: unknown, identity: unknown, names: string[]): PreparedImages;

package/dist/harness/prepared-images.js

@@ -0,0 +1,18 @@
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export function preparedImages(value, identity, names) {
+    const manifest = value;
+    if (!manifest || manifest.version !== 1 || typeof identity !== "string" || !identity || manifest.identity !== identity) {
+        throw new Error("prepared image source/SDK identity mismatch");
+    }
+    if (!manifest.images || typeof manifest.images !== "object" ||
+        Object.keys(manifest.images).sort().join("\n") !== [...names].sort().join("\n")) {
+        throw new Error("prepared image manifest does not match the environment's services");
+    }
+    for (const name of names) {
+        const entry = manifest.images[name];
+        if (!entry || !/^sha256:[a-f0-9]{64}$/.test(entry.image) || !/^[a-f0-9]{64}$/.test(entry.input)) {
+            throw new Error(`invalid prepared image for ${name}`);
+        }
+    }
+    return manifest;
+}

package/dist/project-files.d.ts

@@ -14,7 +14,9 @@ export declare function takeProjectReads(): string[];
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export declare function resolveProjectPath(p: string): string;
+export declare function resolveProjectPath(p: string, opts?: {
+    record?: boolean;
+}): string;
 /** {@link resolveProjectPath}, but a missing file is an error that names every
  *  place we looked. For inputs a user hands us by name — a fixture — where an
  *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */

package/dist/project-files.js

@@ -74,11 +74,16 @@ function relative(p) {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p) {
+export function resolveProjectPath(p, opts = {}) {
     if (path.isAbsolute(p))
         return p;
     const rel = relative(p);
-    PROJECT_READS.add(rel);
+    // A read is coverage of the file for the case that made it — unless
+    // the caller says otherwise: the harness's own bookkeeping reads (a
+    // coverage inventory fingerprinting every manifest) are not the
+    // suite's dependence on those files.
+    if (opts.record !== false)
+        PROJECT_READS.add(rel);
     if (rel.startsWith("spectest/")) {
         const app = path.join(APP_DIR, rel);
         if (existsSync(app))

package/package.json

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

package/src/daemon.ts

@@ -16,9 +16,10 @@
 // forking the sandbox; inside a single daemon we never run two tests at
 // once — that keeps stdout capture and timeouts simple.
 
+import { preparedImages, type PreparedImages } from "./harness/prepared-images.js";
 import { execFile, spawn } from "node:child_process";
 import type { ChildProcess } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -3512,23 +3513,34 @@ function logBootstrapTimings(t: BootstrapTimings): void {
   console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
 }
 
-async function bootstrap(): Promise<BootstrapTimings> {
+async function bootstrap(prepared?: PreparedImages): Promise<BootstrapTimings> {
   // Tee everything this bootstrap logs — ours and every service `setup`
   // hook's — into the boot log, so GET /boot-log can explain a slow or
   // finished boot. Restored in the finally at the end.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
   try {
-    return await bootstrapInner();
+    return await bootstrapInner(prepared);
   } finally {
     restoreBootLog();
   }
 }
 
-async function bootstrapInner(): Promise<BootstrapTimings> {
+async function imageInput(svc: NamedService): Promise<string> {
+  const input = svc.image.type === "registry" ? svc.image : await resolveDockerfileBuild(svc);
+  return createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+
+async function bootstrapInner(prepared?: PreparedImages): Promise<BootstrapTimings>;
+async function bootstrapInner(prepared: undefined, identity: string): Promise<PreparedImages>;
+async function bootstrapInner(prepared?: PreparedImages, identity?: string): Promise<BootstrapTimings | PreparedImages> {
   const bootStart = Date.now();
   const cfg: EnvironmentConfig = requireLoaded().project.environment;
   const services = namedServices(cfg);
   const timings = new Map<string, ServiceTiming>();
+  if (prepared && (prepared.version !== 1 || !prepared.images ||
+      Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+    throw new Error("prepared image manifest does not match the environment's services");
+  }
   progressInit(services);
   // Build dedup is only valid within one workspace generation — a fresh
   // bootstrap may follow a workspace re-upload with the same dockerfile
@@ -3579,12 +3591,24 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
   const tags = new Map<string, string>();
   // Bootstrap is the only dedup scope: all its builds share one
   // /workspace generation (see prepareServiceImage).
-  const prepImage = (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> =>
-    prepareServiceImage(svc, { dedup: true });
+  const prepImage = async (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> => {
+    if (!prepared) return prepareServiceImage(svc, { dedup: true });
+    const entry = prepared.images[svc.name];
+    if (!entry || entry.input !== await imageInput(svc) || !/^sha256:[a-f0-9]{64}$/.test(entry.image)) {
+      throw new Error(`prepared image inputs changed for ${svc.name}`);
+    }
+    const found = await docker(["image", "inspect", "--format", "{{.Id}}", entry.image], 30_000);
+    if (found.code !== 0 || found.stdout.trim() !== entry.image) {
+      throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
+    }
+    return { tag: entry.image, buildSteps: entry.buildSteps };
+  };
   const prep = new Map<string, Promise<void>>();
+  const prepOffsets = new Map<string, number>();
   for (const svc of services) {
     const p = (async () => {
       const t0 = Date.now();
+      prepOffsets.set(svc.name, Date.now() - bootStart);
       const { tag, buildSteps } = await prepImage(svc);
       progressService(svc.name, { status: "prepared", detail: undefined });
       tags.set(svc.name, tag);
@@ -3603,6 +3627,22 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
     prep.set(svc.name, p);
   }
 
+  if (identity !== undefined) {
+    // No application services, setup hooks, ingress, or runtime state in the builder.
+    await Promise.all(prep.values());
+    const images: PreparedImages["images"] = Object.create(null);
+    for (const svc of services) {
+      const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)!], 30_000);
+      const image = out.stdout.trim();
+      if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
+        throw new Error(`cannot resolve prepared image for ${svc.name}: ${out.stderr}`);
+      }
+      const ti = timings.get(svc.name)!;
+      images[svc.name] = { input: await imageInput(svc), image, prepMs: ti.prepMs, startMs: prepOffsets.get(svc.name), buildSteps: ti.buildSteps };
+    }
+    return { version: 1, identity, images };
+  }
+
   // Ingress (fakes + service-tls proxies) comes up BEFORE services so
   // that any service that calls a fake URL during its own startup
   // probe finds it answering. Service-tls proxies will return 502
@@ -4159,8 +4199,13 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
     },
     projectFiles: () => walkProjectFiles(WORKSPACE),
     async readProjectFile(p: string) {
+      // Not recorded as a read: an inventory fingerprinting every
+      // manifest is bookkeeping, not the suite depending on the files.
+      // Recording them made the setup set name every package.json as a
+      // whole file, so a version bump was "ran during environment
+      // setup" — a full run, the exact case the inventory exists for.
       try {
-        return await fs.readFile(resolveProjectPath(p), "utf8");
+        return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8");
       } catch {
         return null;
       }
@@ -4189,9 +4234,21 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
  * The project's reach (`harness/reach.ts`): every project file some
  * service's build context includes, some volume mounts, or a build
  * reads. Computed from the same resolution the builds use, once at the
- * bring-up capture.
+ * bring-up capture. The resolution's own path lookups are bookkeeping,
+ * not reads: they are taken out of the read set again afterwards.
  */
 async function computeProjectReach(all: NamedService[]): Promise<string[]> {
+  const before = takeProjectReads();
+  try {
+    return await computeProjectReachInner(all);
+  } finally {
+    // Discard what the resolution recorded, restore what was there.
+    takeProjectReads();
+    for (const p of before) resolveProjectPath(p);
+  }
+}
+
+async function computeProjectReachInner(all: NamedService[]): Promise<string[]> {
   const files = await walkProjectFiles(WORKSPACE, [".git"]);
   const sources: ReachSource[] = [];
   for (const svc of all) {
@@ -6484,7 +6541,7 @@ function loadedSummary(l: ReturnType<typeof requireLoaded>) {
  */
 export function harnessMethods(state: RouteState): MethodTable {
   return {
-    health: async () => ({ ok: true }),
+    health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
 
     // Live bootstrap progress, polled by the control plane during
     // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -6593,11 +6650,20 @@ export function harnessMethods(state: RouteState): MethodTable {
       return { refs: [...refs] };
     },
 
-    bootstrap: async () =>
-      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
-        ok: true,
-        timings: await bootstrap(),
-      })),
+    prepareImages: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const restore = captureConsole(BOOT_LOG_SINK);
+        try { return await bootstrapInner(undefined, requireString(params, "identity")); }
+        finally { restore(); }
+      }),
+
+    bootstrap: async (params) =>
+      exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
+        const prepared = params.prepared === undefined ? undefined : preparedImages(
+          params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name),
+        );
+        return { ok: true, timings: await bootstrap(prepared) };
+      }),
 
     projectSetup: async () =>
       exclusive(

package/src/harness/prepared-images.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { preparedImages } from "./prepared-images";
+
+const entry = { input: "a".repeat(64), image: `sha256:${"b".repeat(64)}`, prepMs: 12 };
+const manifest = () => ({ version: 1, identity: "source-and-sdk", images: { api: entry } });
+
+test("handoff pins immutable images and rejects a result from another source or SDK", () => {
+  expect(preparedImages(manifest(), "source-and-sdk", ["api"]).images.api.image).toBe(entry.image);
+  expect(() => preparedImages(manifest(), "different-source", ["api"])).toThrow(/identity/);
+});
+
+test("a missing or added service cannot silently fall back to an in-runtime build", () => {
+  expect(() => preparedImages(manifest(), "source-and-sdk", ["api", "worker"])).toThrow(/services/);
+  expect(() => preparedImages(manifest(), "source-and-sdk", [])).toThrow(/services/);
+});
+
+test("mutable image tags and malformed manifests are rejected", () => {
+  const m = manifest();
+  m.images.api = { ...entry, image: "spectest/api:latest" };
+  expect(() => preparedImages(m, "source-and-sdk", ["api"])).toThrow(/invalid/);
+  expect(() => preparedImages(null, "source-and-sdk", ["api"])).toThrow();
+});

package/src/harness/prepared-images.ts

@@ -0,0 +1,26 @@
+import type { BuildStep } from "./buildkit-progress.js";
+
+export interface PreparedImages {
+  version: 1;
+  identity: string;
+  images: Record<string, { input: string; image: string; prepMs: number; startMs?: number; buildSteps?: BuildStep[] }>;
+}
+
+/** Build outputs are required inputs, never a hint to rebuild or pull again. */
+export function preparedImages(value: unknown, identity: unknown, names: string[]): PreparedImages {
+  const manifest = value as PreparedImages | null;
+  if (!manifest || manifest.version !== 1 || typeof identity !== "string" || !identity || manifest.identity !== identity) {
+    throw new Error("prepared image source/SDK identity mismatch");
+  }
+  if (!manifest.images || typeof manifest.images !== "object" ||
+      Object.keys(manifest.images).sort().join("\n") !== [...names].sort().join("\n")) {
+    throw new Error("prepared image manifest does not match the environment's services");
+  }
+  for (const name of names) {
+    const entry = manifest.images[name];
+    if (!entry || !/^sha256:[a-f0-9]{64}$/.test(entry.image) || !/^[a-f0-9]{64}$/.test(entry.input)) {
+      throw new Error(`invalid prepared image for ${name}`);
+    }
+  }
+  return manifest;
+}

package/src/project-files.ts

@@ -80,10 +80,14 @@ function relative(p: string): string {
  * the caller's own `fs` error names a real path — `readProjectFile` keeps
  * reporting ENOENT the way it always has.
  */
-export function resolveProjectPath(p: string): string {
+export function resolveProjectPath(p: string, opts: { record?: boolean } = {}): string {
   if (path.isAbsolute(p)) return p;
   const rel = relative(p);
-  PROJECT_READS.add(rel);
+  // A read is coverage of the file for the case that made it — unless
+  // the caller says otherwise: the harness's own bookkeeping reads (a
+  // coverage inventory fingerprinting every manifest) are not the
+  // suite's dependence on those files.
+  if (opts.record !== false) PROJECT_READS.add(rel);
   if (rel.startsWith("spectest/")) {
     const app = path.join(APP_DIR, rel);
     if (existsSync(app)) return app;