@specific.dev/spectest 0.76.1 → 0.77.0

package/dist/daemon.js

@@ -21,7 +21,7 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, resolveServiceImage, proxy as makeProxyDecl, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
@@ -32,7 +32,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
-import { buildArgFlags, buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
+import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
@@ -41,7 +41,7 @@ import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./ha
 import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
-import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
+import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
@@ -924,11 +924,12 @@ async function ensureCertificates(svc, tag) {
  * context silently became the whole repo, and the checked-out file was
  * clobbered for any in-env tooling that read it too.
  */
-let PROJECT_DOCKERIGNORE = null;
-async function readProjectDockerignore() {
+/** A project ignore file, or null when it is missing — or when it is one
+ *  we wrote ourselves on an earlier bootstrap of this workspace, which is
+ *  not the project's intent. */
+async function readIgnoreFile(file) {
     try {
-        const text = await fs.readFile(path.join(WORKSPACE, ".dockerignore"), "utf8");
-        // Ours, from a previous bootstrap of this workspace — not the project's.
+        const text = await fs.readFile(file, "utf8");
         if (isGeneratedDockerignore(text))
             return null;
         return text;
@@ -937,22 +938,70 @@ async function readProjectDockerignore() {
         return null;
     }
 }
-/** Ignore rules for one dockerfile build. Composition (and the reason the
- *  order matters) lives in `harness/build-context.ts`; this supplies the
- *  project's own file, read once per bootstrap. */
-function serviceDockerignore(exclude) {
-    return composeServiceDockerignore(PROJECT_DOCKERIGNORE, exclude);
-}
 /// In-flight/finished dockerfile builds of this bootstrap, keyed by
-/// sha256(dockerfile content + exclude list). Services that share an
-/// identical image definition (e.g. an API server and a worker running the
-/// same codebase with different entrypoints) build ONCE; the others wait
-/// and `docker tag` the result. Cleared at every bootstrap() — the build
-/// CONTEXT (/workspace) is an input too, so dedup is only valid within one
-/// workspace generation (runtime services started mid-test share it).
+/// sha256(Dockerfile bytes + context dir + ignore rules + target + args).
+/// Services that share an identical image definition (e.g. an API server
+/// and a worker running the same codebase with different entrypoints)
+/// build ONCE; the others wait and `docker tag` the result. Cleared at
+/// every bootstrap() — the CONTENTS of the build context are an input too,
+/// so dedup is only valid within one workspace generation (runtime
+/// services started mid-test share it).
 const BUILD_DEDUP = new Map();
-function buildContentKey(image) {
-    return computeBuildContentKey(() => new Bun.CryptoHasher("sha256"), image);
+function buildContentKey(build) {
+    return computeBuildContentKey(() => new Bun.CryptoHasher("sha256"), build);
+}
+/**
+ * Read everything a dockerfile build needs off the mounted project: the
+ * Dockerfile (`content` as given, or `path` read from the repo now, at
+ * build time — never copied through the config), the context directory,
+ * and the project's own ignore rules chosen the way `docker build`
+ * chooses them (`<Dockerfile>.dockerignore` beside a `path` Dockerfile,
+ * else `<context>/.dockerignore`; see `pickProjectIgnore`). Our defaults
+ * and the service's `exclude` are composed around those into the
+ * per-service ignore file the build is pointed at.
+ *
+ * `validateServiceImage` already refused a missing file or directory at
+ * load time, so a failure here is a read error, not a typo.
+ */
+async function resolveDockerfileBuild(svc) {
+    const image = svc.image;
+    if (image.type !== "dockerfile") {
+        throw new Error(`service "${svc.name}" image is not a Dockerfile build`);
+    }
+    const contextRel = image.context ?? ".";
+    const contextDir = resolveExistingProjectPath(contextRel, `service "${svc.name}" build context`);
+    let content;
+    let adjacent = null;
+    let adjacentPath = null;
+    if (typeof image.path === "string") {
+        const file = resolveExistingProjectPath(image.path, `service "${svc.name}" Dockerfile`);
+        content = await fs.readFile(file, "utf8");
+        adjacentPath = `${image.path}.dockerignore`;
+        adjacent = await readIgnoreFile(`${file}.dockerignore`);
+    }
+    else if (typeof image.content === "string") {
+        content = image.content;
+    }
+    else {
+        throw new Error(`service "${svc.name}" image { type: "dockerfile" } has neither \`path\` nor \`content\``);
+    }
+    const contextRoot = await readIgnoreFile(path.join(contextDir, ".dockerignore"));
+    const projectIgnore = pickProjectIgnore(adjacent, contextRoot);
+    const ignoreSource = adjacent !== null
+        ? adjacentPath
+        : contextRoot !== null
+            ? path.posix.join(contextRel, ".dockerignore")
+            : null;
+    return {
+        content,
+        context: contextRel,
+        contextDir,
+        ignore: composeServiceDockerignore(projectIgnore, image.exclude),
+        ignoreSource,
+        excludeCount: image.exclude?.length ?? 0,
+        target: image.target,
+        buildArgs: image.buildArgs,
+    };
 }
 async function prepareServiceImage(svc, opts) {
     const tag = imageTag(svc.name);
@@ -987,11 +1036,10 @@ async function prepareServiceImage(svc, opts) {
     }
     // Dockerfile build. Within one bootstrap, identical definitions (shared
     // codebase images) dedup to a single build. Only bootstrap opts in: the
-    // dedup key is dockerfile content + exclude, but the build CONTEXT
-    // (/workspace) is an input too — a runtime service started mid-test
-    // after setup/test code mutated /workspace must rebuild, not share a
-    // pre-mutation image.
-    const image = dockerfileContent(svc);
+    // dedup key names the context directory but not its contents — a
+    // runtime service started mid-test after setup/test code mutated
+    // /workspace must rebuild, not share a pre-mutation image.
+    const image = await resolveDockerfileBuild(svc);
     if (opts?.dedup) {
         const key = buildContentKey(image);
         const inflight = BUILD_DEDUP.get(key);
@@ -1027,16 +1075,6 @@ async function prepareServiceImage(svc, opts) {
     }
     return buildServiceImage(svc.name, image, tag);
 }
-/** The built form of a dockerfile image. `resolveServiceImage` read a
- *  `path` into `content` at config time, so a service that still carries
- *  `path` here skipped that step — a programming error, not user input. */
-function dockerfileContent(svc) {
-    const image = svc.image;
-    if (image.type !== "dockerfile" || typeof image.content !== "string") {
-        throw new Error(`service "${svc.name}" image was not resolved to Dockerfile contents`);
-    }
-    return image;
-}
 /**
  * Build a dockerfile service's image — the project's Dockerfile as
  * written, nothing appended.
@@ -1060,22 +1098,33 @@ async function buildServiceImage(name, image, tag) {
 async function runServiceBuild(name, image, tag) {
     let buildSteps;
     {
-        const content = image.content;
+        // The build runs straight against the mounted project: the context is
+        // the repo directory the service named (the root by default), and a
+        // `path` Dockerfile's bytes were read from the repo just now. The one
+        // thing written is a per-service pair under `.spectest/services/`:
+        // the Dockerfile's text and, beside it, the ignore rules. That pair
+        // exists because BuildKit takes extra ignore rules from exactly one
+        // place — a `<Dockerfile>.dockerignore` next to the Dockerfile it was
+        // pointed at — and the rules here are per service (our defaults, the
+        // project's own file, ITS OWN `exclude`): two services building one
+        // repo Dockerfile with different excludes need two of them, and
+        // nothing may be written next to the user's file. So `-f` names our
+        // copy and the context stays the user's directory; a Dockerfile
+        // outside its context is ordinary `docker build -f`. Verified on both
+        // the buildx and DOCKER_BUILDKIT paths (client-side context
+        // filtering). The root `.dockerignore` written at bootstrap stays as
+        // the fallback for the legacy non-BuildKit builder, which predates
+        // per-Dockerfile ignores — and is written ONLY when the project ships
+        // none of its own.
         const dfDir = path.join(WORKSPACE, ".spectest", "services", name);
         await fs.mkdir(dfDir, { recursive: true });
         const dfPath = path.join(dfDir, "Dockerfile");
-        await fs.writeFile(dfPath, content);
-        // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
-        // (next to the Dockerfile) in preference to the context root's
-        // `.dockerignore`, so this build sees the defaults, the project's own
-        // `.dockerignore`, and ITS OWN `exclude` — one service excluding
-        // `handhelds/**` no longer empties a sibling's build context. Verified
-        // on both the remote-buildx and DOCKER_BUILDKIT paths (client-side
-        // context filtering). The root `.dockerignore` written at bootstrap
-        // stays as the fallback for the legacy non-BuildKit builder, which
-        // predates per-Dockerfile ignores — and is written ONLY when the
-        // project ships none of its own (see readProjectDockerignore).
-        await fs.writeFile(`${dfPath}.dockerignore`, serviceDockerignore(image.exclude));
+        await fs.writeFile(dfPath, image.content);
+        await fs.writeFile(`${dfPath}.dockerignore`, image.ignore);
+        console.log(`[build] ${name}: context ${image.context}` +
+            (image.target ? `, target ${image.target}` : "") +
+            (image.ignoreSource ? `, ignore rules from ${image.ignoreSource}` : ", no project ignore file") +
+            (image.excludeCount > 0 ? ` + ${image.excludeCount} exclude pattern(s)` : ""));
         // The in-VM buildkitd on the container store first: the build runs
         // inside the guest's own isolation boundary, against this project's
         // own layer cache, and the finished image is already in the store
@@ -1090,7 +1139,8 @@ async function runServiceBuild(name, image, tag) {
         let buildArgs;
         // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
         // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
-        const argFlags = buildArgFlags(image.buildArgs);
+        const argFlags = [...buildTargetFlags(image.target), ...buildArgFlags(image.buildArgs)];
+        const contextDir = image.contextDir;
         if (useLocal) {
             // The in-VM builder is BuildKit's containerd worker on this VM's
             // own image store (CONTAINER_STORE.md): the output is an image
@@ -1110,15 +1160,15 @@ async function runServiceBuild(name, image, tag) {
                 "--progress=plain",
                 "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
                 ...argFlags,
-                "-f", dfPath, WORKSPACE,
+                "-f", dfPath, contextDir,
             ];
         }
         else if (useBuildKit) {
-            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
+            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", contextDir];
             buildEnv.DOCKER_BUILDKIT = "1";
         }
         else {
-            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, WORKSPACE];
+            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, contextDir];
         }
         progressService(name, { status: "building", detail: "starting build" });
         const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
@@ -2624,9 +2674,9 @@ const RUNTIME_SERVICES = new Map();
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
     // A runtime spec skipped `defineEnvironment`, so its config-time passes
-    // run here: a `path` Dockerfile is read into `content`, and coverage
-    // adapters get their configure step.
-    const svc = { ...rest, image: resolveServiceImage(name, rest.image) };
+    // run here: the image is checked (a `path` Dockerfile and a `context`
+    // must exist), and coverage adapters get their configure step.
+    const svc = { ...rest, image: validateServiceImage(name, rest.image) };
     return { name, ...applyCoverageAdapters(name, svc) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
@@ -2945,18 +2995,14 @@ async function bootstrapInner() {
         ensureNetwork(),
         (async () => {
             await fs.mkdir(WORKSPACE, { recursive: true });
-            // Read the project's own .dockerignore BEFORE we consider writing
-            // one — every per-service ignore composes on top of it.
-            PROJECT_DOCKERIGNORE = await readProjectDockerignore();
-            if (PROJECT_DOCKERIGNORE !== null) {
-                console.log("[bootstrap] using the project's .dockerignore for every build context");
-                // Never overwrite it. BuildKit reads the per-service
-                // `<Dockerfile>.dockerignore` (which already folds this file in),
-                // and the legacy builder reads the project's file directly —
-                // which is what the project asked for. Clobbering it also broke
-                // any in-env tooling that reads it.
+            // Never overwrite the project's own root `.dockerignore`. BuildKit
+            // reads the per-service `<Dockerfile>.dockerignore` (which folds the
+            // project's file in, see resolveDockerfileBuild), and the legacy
+            // builder reads the project's file directly — which is what the
+            // project asked for. Clobbering it also broke any in-env tooling
+            // that reads it.
+            if ((await readIgnoreFile(path.join(WORKSPACE, ".dockerignore"))) !== null)
                 return;
-            }
             await fs.writeFile(path.join(WORKSPACE, ".dockerignore"), unionDockerignore(services));
         })(),
     ]);

package/dist/harness/build-context.d.ts

@@ -21,10 +21,18 @@ export declare const DEFAULT_DOCKERIGNORE: readonly string[];
 export declare const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated \u2014 do not edit (your own .dockerignore is honoured verbatim)";
 /** Is this text a file we wrote ourselves on an earlier bootstrap? */
 export declare function isGeneratedDockerignore(text: string): boolean;
+/**
+ * The project's own ignore rules for one build, chosen the way BuildKit
+ * chooses them: a `<Dockerfile>.dockerignore` next to the Dockerfile wins
+ * outright, else the context root's `.dockerignore`, else nothing. The two
+ * are never merged — a Dockerfile-adjacent file is the whole rule set for
+ * that build, exactly as `docker build` reads it.
+ */
+export declare function pickProjectIgnore(adjacent: string | null, contextRoot: string | null): string | null;
 /**
  * Ignore rules for one dockerfile build, in precedence order: our
- * defaults, then the project's own `.dockerignore` verbatim, then that
- * service's `exclude`.
+ * defaults, then the project's own ignore file verbatim (see
+ * {@link pickProjectIgnore}), then that service's `exclude`.
  *
  * **The order is load-bearing**, because of the `**`-plus-negations idiom
  * that monorepos use to keep a build context small:
@@ -62,24 +70,40 @@ export declare function unionDockerignore(services: readonly {
         exclude?: readonly string[];
     };
 }[]): string;
+/**
+ * Everything one dockerfile build reads, resolved from the project: the
+ * Dockerfile's bytes (from `path` or `content`), the context directory
+ * (project-root-relative, `.` by default), the composed ignore rules, the
+ * stage to stop at, and the build args. The harness resolves this once per
+ * service and both the dedup key and the build itself work from it.
+ */
+export interface ResolvedBuild {
+    /** The Dockerfile text. */
+    content: string;
+    /** Project-root-relative build context directory (`.` for the root). */
+    context: string;
+    /** The generated `<Dockerfile>.dockerignore` text. */
+    ignore: string;
+    /** `--target` stage, if any. */
+    target?: string;
+    buildArgs?: Readonly<Record<string, string>>;
+}
 /**
  * Identity of a dockerfile build within one bootstrap, so services sharing
  * an image definition (an api and a worker on the same codebase with
  * different entrypoints) build once and the rest just re-tag.
  *
- * The build **context** is an input too, but it isn't hashed: the context
- * is `/workspace`, which is fixed within a bootstrap and mutable between
- * them, so this key is only ever valid inside one workspace generation.
- * The dedup map is cleared per bootstrap for exactly that reason.
+ * The context *directory* is part of the key, but its *contents* are not:
+ * `/workspace` is fixed within a bootstrap and mutable between them, so
+ * this key is only ever valid inside one workspace generation. The dedup
+ * map is cleared per bootstrap for exactly that reason.
  */
 export interface Hasher {
     update(s: string): Hasher;
     digest(encoding: "hex"): string;
 }
-export declare function buildContentKey(createHasher: () => Hasher, image: {
-    content: string;
-    exclude?: readonly string[];
-    buildArgs?: Readonly<Record<string, string>>;
-}): string;
+export declare function buildContentKey(createHasher: () => Hasher, build: ResolvedBuild): string;
+/** `--target <stage>`, or nothing. A plain client flag every builder takes. */
+export declare function buildTargetFlags(target: string | undefined): string[];
 /** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
 export declare function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[];

package/dist/harness/build-context.js

@@ -41,10 +41,20 @@ export const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated — do not ed
 export function isGeneratedDockerignore(text) {
     return text.startsWith(GENERATED_DOCKERIGNORE_HEADER);
 }
+/**
+ * The project's own ignore rules for one build, chosen the way BuildKit
+ * chooses them: a `<Dockerfile>.dockerignore` next to the Dockerfile wins
+ * outright, else the context root's `.dockerignore`, else nothing. The two
+ * are never merged — a Dockerfile-adjacent file is the whole rule set for
+ * that build, exactly as `docker build` reads it.
+ */
+export function pickProjectIgnore(adjacent, contextRoot) {
+    return adjacent ?? contextRoot;
+}
 /**
  * Ignore rules for one dockerfile build, in precedence order: our
- * defaults, then the project's own `.dockerignore` verbatim, then that
- * service's `exclude`.
+ * defaults, then the project's own ignore file verbatim (see
+ * {@link pickProjectIgnore}), then that service's `exclude`.
  *
  * **The order is load-bearing**, because of the `**`-plus-negations idiom
  * that monorepos use to keep a build context small:
@@ -100,23 +110,31 @@ export function unionDockerignore(services) {
     }
     return [GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
 }
-export function buildContentKey(createHasher, image) {
+export function buildContentKey(createHasher, build) {
     return (createHasher()
-        .update(image.content)
-        // A separator that cannot occur in either field. Without it a
-        // Dockerfile whose text ends with an exclude list would hash the
+        .update(build.content)
+        // A separator that cannot occur in any field. Without it a
+        // Dockerfile whose text ends with an ignore list would hash the
         // same as that Dockerfile with the list actually set, and two
         // genuinely different builds would collapse into one.
         .update("\0")
-        .update(JSON.stringify(image.exclude ?? []))
+        .update(build.context)
+        .update("\0")
+        .update(build.ignore)
+        .update("\0")
+        .update(build.target ?? "")
         // Build args are an input to the image (an ARG picks the base image,
         // the NODE_ENV of an install step…), so two services on one
         // Dockerfile with different args must not share a build. Sorted, so
         // key order in the user's object doesn't split identical builds.
         .update("\0")
-        .update(JSON.stringify(buildArgFlags(image.buildArgs)))
+        .update(JSON.stringify(buildArgFlags(build.buildArgs)))
         .digest("hex"));
 }
+/** `--target <stage>`, or nothing. A plain client flag every builder takes. */
+export function buildTargetFlags(target) {
+    return target ? ["--target", target] : [];
+}
 /** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
 export function buildArgFlags(buildArgs) {
     return Object.entries(buildArgs ?? {})

package/dist/index.d.ts

@@ -734,17 +734,33 @@ export type ServiceImage = {
      * Path of a Dockerfile in your repo, relative to the project root
      * (where `spectest/` lives) — `"Dockerfile"`, `"apps/api/Dockerfile"`.
      * This is the preferred form: the test environment builds the same
-     * Dockerfile production does, so the two cannot drift. The build
-     * context is always the project root, as with
-     * `docker build -f apps/api/Dockerfile .`, so `COPY` / `ADD` resolve
-     * against the repo root wherever the file sits. The file is read when
-     * the environment loads; a missing file fails the load and names the
-     * path. Mutually exclusive with `content`.
+     * Dockerfile production does, so the two cannot drift. The file is
+     * read from the repo at build time; a missing file fails the
+     * environment load and names the path. Mutually exclusive with
+     * `content`.
+     *
+     * Ignore rules come from the repo the way `docker build` reads them:
+     * a `<Dockerfile>.dockerignore` beside this file, else the context
+     * directory's `.dockerignore`. `exclude` adds to whichever applied.
      */
     path: string;
     content?: never;
+    /**
+     * Build context directory, relative to the project root. Defaults to
+     * the project root, as with `docker build -f apps/api/Dockerfile .`.
+     * `"apps/api"` is `docker build apps/api`: `COPY` / `ADD` resolve
+     * against that directory, and so do the ignore rules.
+     */
+    context?: string;
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
+    /**
+     * Stage to build, as `docker build --target <stage>`. Lets a
+     * production Dockerfile keep a final stage the tests never need (an
+     * ops layer, a slow install) while the environment stops at the
+     * stage before it.
+     */
+    target?: string;
     /**
      * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
      * Build-time only: they are not in the container's environment (use
@@ -756,16 +772,24 @@ export type ServiceImage = {
 } | {
     type: "dockerfile";
     /**
-     * Dockerfile contents, written verbatim into the build context. The
-     * build context is the project root (where `spectest/` lives), so any
-     * `COPY` / `ADD` references resolve relative to that directory.
-     * Prefer `path`, which points at the Dockerfile your repo already has.
-     * Mutually exclusive with `path`.
+     * Dockerfile contents, built as if the file sat outside the build
+     * context (it is never written into your repo). The context is the
+     * project root (where `spectest/` lives) unless `context` says
+     * otherwise, and `COPY` / `ADD` resolve against it. Prefer `path`,
+     * which points at the Dockerfile your repo already has. Mutually
+     * exclusive with `path`.
      */
     content: string;
     path?: never;
+    /**
+     * Build context directory, relative to the project root. Defaults to
+     * the project root. The context's own `.dockerignore` applies.
+     */
+    context?: string;
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
+    /** Stage to build, as `docker build --target <stage>`. */
+    target?: string;
     /**
      * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
      * Build-time only: they are not in the container's environment (use
@@ -776,19 +800,23 @@ export type ServiceImage = {
     buildArgs?: Readonly<Record<string, string>>;
 };
 /**
- * Resolve a service's `image` to the form the harness builds: a `path`
- * Dockerfile is read from the repo and becomes `content`. The wire config
- * therefore never carries `path` — the control plane and the daemon's build
- * code only ever see Dockerfile bytes, and the warm-template hash covers
- * them because the file is part of the project tree.
+ * Check a service's `image` at config time, so a mistake fails the
+ * environment load with a message that names it, instead of a build
+ * minutes later. Nothing is rewritten: a `path` Dockerfile stays a path,
+ * and the harness reads it — and the ignore file beside it — from the
+ * repo when it builds (`daemon.ts::resolveDockerfileBuild`). The wire
+ * config therefore carries `path`, `context` and `target` as written; the
+ * control plane only tells a Dockerfile build from a registry pull, and
+ * the warm-template hash covers the files because they are part of the
+ * project tree.
  *
- * Runs at config time (`defineEnvironment`, and the daemon's runtime
- * `startService` twin), inside the VM, where the repo sits at the project
- * root. The read goes through the project-file resolver, so the same rules
- * as `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * Runs in `defineEnvironment`, and in the daemon's runtime `startService`
+ * twin, inside the VM, where the repo sits at the project root. Existence
+ * checks go through the project-file resolver, so the same rules as
+ * `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
  * instead of read stale).
  */
-export declare function resolveServiceImage(serviceName: string, image: ServiceImage): ServiceImage;
+export declare function validateServiceImage(serviceName: string, image: ServiceImage): ServiceImage;
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one

package/dist/index.js

@@ -4,7 +4,7 @@
 // The daemon loads this file on boot and the control plane talks to it
 // over HTTP.
 import { strict as nodeAssert } from "node:assert";
-import { readFileSync } from "node:fs";
+import { statSync } from "node:fs";
 import { recordAssertion, safeSerialize } from "./recorder.js";
 import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
@@ -236,20 +236,26 @@ function validateBuildArgs(serviceName, buildArgs) {
         }
     }
 }
+/** A Dockerfile stage name, as `--target` accepts it: no whitespace. */
+const BUILD_TARGET_RE = /^[^\s]+$/;
 /**
- * Resolve a service's `image` to the form the harness builds: a `path`
- * Dockerfile is read from the repo and becomes `content`. The wire config
- * therefore never carries `path` — the control plane and the daemon's build
- * code only ever see Dockerfile bytes, and the warm-template hash covers
- * them because the file is part of the project tree.
+ * Check a service's `image` at config time, so a mistake fails the
+ * environment load with a message that names it, instead of a build
+ * minutes later. Nothing is rewritten: a `path` Dockerfile stays a path,
+ * and the harness reads it — and the ignore file beside it — from the
+ * repo when it builds (`daemon.ts::resolveDockerfileBuild`). The wire
+ * config therefore carries `path`, `context` and `target` as written; the
+ * control plane only tells a Dockerfile build from a registry pull, and
+ * the warm-template hash covers the files because they are part of the
+ * project tree.
  *
- * Runs at config time (`defineEnvironment`, and the daemon's runtime
- * `startService` twin), inside the VM, where the repo sits at the project
- * root. The read goes through the project-file resolver, so the same rules
- * as `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * Runs in `defineEnvironment`, and in the daemon's runtime `startService`
+ * twin, inside the VM, where the repo sits at the project root. Existence
+ * checks go through the project-file resolver, so the same rules as
+ * `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
  * instead of read stale).
  */
-export function resolveServiceImage(serviceName, image) {
+export function validateServiceImage(serviceName, image) {
     if (image.type !== "dockerfile")
         return image;
     validateBuildArgs(serviceName, image.buildArgs);
@@ -261,22 +267,27 @@ export function resolveServiceImage(serviceName, image) {
     if (!hasPath && !hasContent) {
         throw new Error(`service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
     }
-    if (!hasPath)
-        return image;
-    const file = resolveExistingProjectPath(image.path, `service "${serviceName}" Dockerfile`);
-    let content;
-    try {
-        content = readFileSync(file, "utf8");
+    if (hasPath) {
+        const file = resolveExistingProjectPath(image.path, `service "${serviceName}" Dockerfile`);
+        if (!statSync(file).isFile()) {
+            throw new Error(`service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} is not a file — \`path\` names the Dockerfile itself, \`context\` names the directory to build from`);
+        }
     }
-    catch (e) {
-        throw new Error(`service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} could not be read: ${e.message}`);
+    if (image.context !== undefined) {
+        if (typeof image.context !== "string" || image.context === "") {
+            throw new Error(`service "${serviceName}" image context must be a directory path relative to the project root (\`"."\` for the root)`);
+        }
+        const dir = resolveExistingProjectPath(image.context, `service "${serviceName}" build context`);
+        if (!statSync(dir).isDirectory()) {
+            throw new Error(`service "${serviceName}" build context ${JSON.stringify(image.context)} is not a directory`);
+        }
+    }
+    if (image.target !== undefined) {
+        if (typeof image.target !== "string" || !BUILD_TARGET_RE.test(image.target)) {
+            throw new Error(`service "${serviceName}" image target must be a Dockerfile stage name (\`FROM … AS <name>\`); got ${JSON.stringify(image.target)}`);
+        }
     }
-    const lowered = { type: "dockerfile", content };
-    if (image.exclude !== undefined)
-        lowered.exclude = image.exclude;
-    if (image.buildArgs !== undefined)
-        lowered.buildArgs = image.buildArgs;
-    return lowered;
+    return image;
 }
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);
@@ -389,7 +400,7 @@ export function defineEnvironment(input) {
     for (const [key, svc] of Object.entries(expanded)) {
         expanded[key] = applyCoverageAdapters(key, {
             ...svc,
-            image: resolveServiceImage(key, svc.image),
+            image: validateServiceImage(key, svc.image),
         });
     }
     const config = {

package/package.json

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