@specific.dev/spectest 0.76.1 → 0.77.0

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,
@@ -1252,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 {
@@ -1265,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(
@@ -1330,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);
@@ -1369,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.
@@ -1412,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
@@ -1442,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
@@ -1462,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) => {
@@ -3145,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) };
 }
 
@@ -3505,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);
   });
 });

package/src/harness/build-context.ts

@@ -47,10 +47,24 @@ export function isGeneratedDockerignore(text: string): boolean {
   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: string | null,
+  contextRoot: string | null,
+): string | null {
+  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:
@@ -113,44 +127,69 @@ export function unionDockerignore(
   return [GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
 }
 
+/**
+ * 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 function buildContentKey(
-  createHasher: () => Hasher,
-  image: { content: string; exclude?: readonly string[]; buildArgs?: Readonly<Record<string, string>> },
-): string {
+export function buildContentKey(createHasher: () => Hasher, build: ResolvedBuild): string {
   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: string | undefined): string[] {
+  return target ? ["--target", target] : [];
+}
+
 /** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
 export function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[] {
   return Object.entries(buildArgs ?? {})