@specific.dev/spectest 0.76.0 → 0.77.0

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.0",
+  "version": "0.77.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -31,7 +31,7 @@ import {
   lowerIngress,
   dnsName as makeDnsDecl,
   isWildcard,
-  resolveServiceImage,
+  validateServiceImage,
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
@@ -67,12 +67,13 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
 import {
-  DEFAULT_DOCKERIGNORE,
-  GENERATED_DOCKERIGNORE_HEADER,
+  type ResolvedBuild,
   buildArgFlags,
   buildContentKey as computeBuildContentKey,
+  buildTargetFlags,
   imageTag,
   isGeneratedDockerignore,
+  pickProjectIgnore,
   serviceDockerignore as composeServiceDockerignore,
   unionDockerignore,
 } from "./harness/build-context.js";
@@ -93,7 +94,7 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import type { WrapperDiagnostic } 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,
@@ -736,7 +737,17 @@ async function imageCachePaths(): Promise<ImageCachePaths | null> {
   return imageCachePathsSync(IMAGE_CACHE_MANIFEST);
 }
 
-let _localBuilder: boolean | undefined;
+/**
+ * The bring-up, once. A promise and not a flag: every build of a
+ * bootstrap calls this at the same time now that builds go in together,
+ * and a flag set to "not yet" while the first caller waits for buildkitd
+ * sent every other build to dockerd's own builder — which cannot build
+ * on the erofs store at all (`lease does not exist`), so Specific's
+ * first three cold builds on SDK 0.76.0 failed inside ten seconds
+ * (2026-09-07). Sharing the promise makes every caller wait for the one
+ * bring-up and read its one answer.
+ */
+let _localBuilder: Promise<boolean> | undefined;
 /**
  * Start buildkitd inside this VM with its state on the cache disk, and
  * register it as a buildx `remote` builder.
@@ -746,9 +757,12 @@ let _localBuilder: boolean | undefined;
  * best-effort: a daemon that will not start falls back to the shared host
  * one, which is a slower build and not a failed one.
  */
-async function ensureLocalBuildkitd(): Promise<boolean> {
-  if (_localBuilder !== undefined) return _localBuilder;
-  _localBuilder = false;
+function ensureLocalBuildkitd(): Promise<boolean> {
+  _localBuilder ??= bringUpLocalBuildkitd();
+  return _localBuilder;
+}
+
+async function bringUpLocalBuildkitd(): Promise<boolean> {
   const paths = await imageCachePaths();
   if (!paths) return false;
   const state = paths.root;
@@ -795,7 +809,6 @@ async function ensureLocalBuildkitd(): Promise<boolean> {
   // hit is a snapshot that already exists — no tar blob to unpack
   // before the first uncached step, no export pass after a miss.
   await ensureBuildkitCacheUnion(paths);
-  _localBuilder = true;
   return true;
 }
 
@@ -1240,12 +1253,12 @@ async function ensureCertificates(svc: NamedService, tag: string): Promise<strin
  * 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: string | null = null;
-
-async function readProjectDockerignore(): Promise<string | null> {
+/** 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: string): Promise<string | null> {
   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;
   } catch {
@@ -1253,33 +1266,84 @@ async function readProjectDockerignore(): Promise<string | 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?: readonly string[]): string {
-  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<
   string,
   { name: string; promise: Promise<{ tag: string; buildSteps?: BuildStep[] }> }
 >();
 
-type DockerfileBuild = {
-  content: string;
-  exclude?: readonly string[];
-  buildArgs?: Readonly<Record<string, string>>;
+/** A dockerfile build resolved against the repo, plus where the context is. */
+type DockerfileBuild = ResolvedBuild & {
+  /** Absolute context directory in the VM. */
+  contextDir: string;
+  /** Where the project's ignore rules came from, for the boot log. */
+  ignoreSource: string | null;
+  /** How many `exclude` patterns the service added, for the boot log. */
+  excludeCount: number;
 };
 
-function buildContentKey(image: DockerfileBuild): string {
-  return computeBuildContentKey(() => new Bun.CryptoHasher("sha256") as any, image);
+function buildContentKey(build: ResolvedBuild): string {
+  return computeBuildContentKey(() => new Bun.CryptoHasher("sha256") as any, 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: NamedService): Promise<DockerfileBuild> {
+  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: string;
+  let adjacent: string | null = null;
+  let adjacentPath: string | null = 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(
@@ -1318,11 +1382,10 @@ async function prepareServiceImage(
   }
   // 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);
@@ -1357,17 +1420,6 @@ async function prepareServiceImage(
   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: NamedService): DockerfileBuild {
-  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.
@@ -1400,22 +1452,35 @@ async function runServiceBuild(
 ): Promise<{ ok: boolean; log: string; buildSteps?: BuildStep[] }> {
   let buildSteps: BuildStep[] | undefined;
   {
-    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
@@ -1430,7 +1495,8 @@ async function runServiceBuild(
     let buildArgs: string[];
     // 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
@@ -1450,13 +1516,13 @@ async function runServiceBuild(
         "--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) => {
@@ -3133,9 +3199,9 @@ const RUNTIME_SERVICES = new Map<string, NamedService>();
 function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   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 as ServiceConfig), 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 as ServiceConfig), image: validateServiceImage(name, rest.image) };
   return { name, ...applyCoverageAdapters(name, svc) };
 }
 
@@ -3493,20 +3559,13 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
     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.
-        return;
-      }
+      // 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/src/dockerfile-path.test.ts

@@ -1,24 +1,31 @@
-// `image: { type: "dockerfile", path }` — a Dockerfile in the repo is read
-// into `content` when the environment loads, so the harness only ever sees
-// bytes. The project root is `SPECTEST_WORKSPACE` (the VM's /workspace).
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+// `image: { type: "dockerfile", path, context, target }` — checked when the
+// environment loads, carried as written. The harness reads the Dockerfile
+// and its ignore file off the repo at build time. The project root is
+// `SPECTEST_WORKSPACE` (the VM's /workspace).
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
 // Set before the SDK reads it (module-load time), so no top-level import.
+// One root for the whole file: the SDK reads SPECTEST_WORKSPACE once, when
+// `./index` is first imported, so a per-test root would leave every later
+// test pointing at the first one's deleted directory.
 let root = "";
-beforeEach(() => {
+beforeAll(() => {
   root = mkdtempSync(path.join(tmpdir(), "spectest-dockerfile-"));
   process.env.SPECTEST_WORKSPACE = root;
   process.env.SPECTEST_APP_DIR = path.join(root, "app-copy");
 });
-afterEach(() => rmSync(root, { recursive: true, force: true }));
+afterEach(() => {
+  for (const entry of readdirSync(root)) rmSync(path.join(root, entry), { recursive: true, force: true });
+});
+afterAll(() => rmSync(root, { recursive: true, force: true }));
 
 const load = async () => await import("./index");
 
 describe("dockerfile path", () => {
-  test("a repo-relative path is read into content, exclude kept", async () => {
+  test("a repo-relative path is kept as written, with its context and target", async () => {
     mkdirSync(path.join(root, "apps/api"), { recursive: true });
     writeFileSync(path.join(root, "apps/api/Dockerfile"), "FROM node:20\nCOPY . /app\n");
     const { defineEnvironment } = await load();
@@ -29,6 +36,8 @@ describe("dockerfile path", () => {
           image: {
             type: "dockerfile",
             path: "apps/api/Dockerfile",
+            context: "apps/api",
+            target: "runtime",
             exclude: ["docs/**"],
             buildArgs: { NODE_ENV: "test" },
           },
@@ -37,7 +46,9 @@ describe("dockerfile path", () => {
     });
     expect(env.config.services.api.image).toEqual({
       type: "dockerfile",
-      content: "FROM node:20\nCOPY . /app\n",
+      path: "apps/api/Dockerfile",
+      context: "apps/api",
+      target: "runtime",
       exclude: ["docs/**"],
       buildArgs: { NODE_ENV: "test" },
     });
@@ -53,23 +64,55 @@ describe("dockerfile path", () => {
     ).toThrow(/service "api" Dockerfile "nope\/Dockerfile" is not in the VM/);
   });
 
+  test("a path that is a directory is refused, pointing at `context`", async () => {
+    mkdirSync(path.join(root, "apps/api"), { recursive: true });
+    const { validateServiceImage } = await load();
+    expect(() => validateServiceImage("api", { type: "dockerfile", path: "apps/api" })).toThrow(
+      /is not a file/,
+    );
+  });
+
+  test("a missing or non-directory context fails the load", async () => {
+    writeFileSync(path.join(root, "Dockerfile"), "FROM x\n");
+    const { validateServiceImage } = await load();
+    expect(() =>
+      validateServiceImage("api", { type: "dockerfile", path: "Dockerfile", context: "packages" }),
+    ).toThrow(/service "api" build context "packages" is not in the VM/);
+    expect(() =>
+      validateServiceImage("api", { type: "dockerfile", path: "Dockerfile", context: "Dockerfile" }),
+    ).toThrow(/is not a directory/);
+    expect(() =>
+      validateServiceImage("api", { type: "dockerfile", content: "FROM x", context: "" }),
+    ).toThrow(/context must be a directory path/);
+  });
+
+  test("a target must look like a stage name", async () => {
+    const { validateServiceImage } = await load();
+    expect(() =>
+      validateServiceImage("api", { type: "dockerfile", content: "FROM x", target: "run time" }),
+    ).toThrow(/target must be a Dockerfile stage name/);
+    expect(() =>
+      validateServiceImage("api", { type: "dockerfile", content: "FROM x", target: "" }),
+    ).toThrow(/target must be a Dockerfile stage name/);
+  });
+
   test("path and content together, or neither, is an error", async () => {
-    const { resolveServiceImage } = await load();
+    const { validateServiceImage } = await load();
     expect(() =>
-      resolveServiceImage("api", { type: "dockerfile", path: "Dockerfile", content: "FROM x" } as never),
+      validateServiceImage("api", { type: "dockerfile", path: "Dockerfile", content: "FROM x" } as never),
     ).toThrow(/both `path` and `content`/);
-    expect(() => resolveServiceImage("api", { type: "dockerfile" } as never)).toThrow(
+    expect(() => validateServiceImage("api", { type: "dockerfile" } as never)).toThrow(
       /needs `path`/,
     );
   });
 
   test("buildArgs keys must be ARG names and values strings", async () => {
-    const { resolveServiceImage } = await load();
+    const { validateServiceImage } = await load();
     expect(() =>
-      resolveServiceImage("api", { type: "dockerfile", content: "FROM x", buildArgs: { "NO-DASH": "1" } }),
+      validateServiceImage("api", { type: "dockerfile", content: "FROM x", buildArgs: { "NO-DASH": "1" } }),
     ).toThrow(/not a valid ARG name/);
     expect(() =>
-      resolveServiceImage("api", {
+      validateServiceImage("api", {
         type: "dockerfile",
         content: "FROM x",
         buildArgs: { PORT: 3000 } as never,
@@ -78,10 +121,10 @@ describe("dockerfile path", () => {
   });
 
   test("content and registry images pass through untouched", async () => {
-    const { resolveServiceImage } = await load();
+    const { validateServiceImage } = await load();
     const inline = { type: "dockerfile", content: "FROM x\n" } as const;
-    expect(resolveServiceImage("a", inline)).toBe(inline);
+    expect(validateServiceImage("a", inline)).toBe(inline);
     const reg = { type: "registry", reference: "nginx" } as const;
-    expect(resolveServiceImage("a", reg)).toBe(reg);
+    expect(validateServiceImage("a", reg)).toBe(reg);
   });
 });