@specific.dev/spectest 0.39.0 → 0.43.0

package/src/harness/build-context.ts

@@ -0,0 +1,146 @@
+/**
+ * What goes into a docker build: the image tag, the ignore rules, and the
+ * key that lets two identical builds collapse into one.
+ *
+ * Ported out of `daemon.ts`. The functions here read no module state —
+ * the project's own `.dockerignore` is passed in rather than reached for —
+ * which is what makes the ordering rule below testable at all.
+ */
+
+/** Every service's built image is tagged in one namespace. */
+export function imageTag(name: string): string {
+  return `spectest/${name}:latest`;
+}
+
+/**
+ * Always excluded from a build context: version control, our own state,
+ * dependency and build output directories, and dotenv files.
+ */
+export const DEFAULT_DOCKERIGNORE: readonly string[] = [
+  ".git",
+  ".spectest",
+  "spectest",
+  "node_modules",
+  "target",
+  "__pycache__",
+  ".venv",
+  ".env",
+  ".env.local",
+  ".env.*",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  ".DS_Store",
+];
+
+/**
+ * First line of a `.dockerignore` we generated, so a later bootstrap can
+ * tell our file apart from one the project ships and never mistakes its
+ * own output for user intent.
+ */
+export const GENERATED_DOCKERIGNORE_HEADER =
+  "# spectest-generated — do not edit (your own .dockerignore is honoured verbatim)";
+
+/** Is this text a file we wrote ourselves on an earlier bootstrap? */
+export function isGeneratedDockerignore(text: string): boolean {
+  return text.startsWith(GENERATED_DOCKERIGNORE_HEADER);
+}
+
+/**
+ * Ignore rules for one dockerfile build, in precedence order: our
+ * defaults, then the project's own `.dockerignore` verbatim, 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:
+ *
+ * ```
+ * **                 ← the project's file: exclude everything
+ * !go.mod            ← …then re-include exactly what the build reads
+ * !cmd/api/**
+ * ```
+ *
+ * Our defaults must come *first* so that `**` subsumes them; if they came
+ * after, they would re-exclude nothing useful but would sit below the
+ * negations and confuse the intent. The service's `exclude` comes *last*
+ * so it still gets the final word over both.
+ *
+ * Written per service (`.spectest/services/<name>/Dockerfile.dockerignore`)
+ * because BuildKit gives a Dockerfile-adjacent ignore file precedence over
+ * the context root's — which is what stops one service's `exclude` from
+ * shrinking a sibling's build context.
+ */
+export function serviceDockerignore(
+  projectDockerignore: string | null,
+  exclude?: readonly string[],
+): string {
+  const parts = [DEFAULT_DOCKERIGNORE.join("\n")];
+  if (projectDockerignore !== null) {
+    parts.push(`# --- from the project's .dockerignore ---\n${projectDockerignore.trimEnd()}`);
+  }
+  if (exclude && exclude.length > 0) {
+    parts.push(`# --- from this service's exclude ---\n${exclude.join("\n")}`);
+  }
+  return parts.join("\n") + "\n";
+}
+
+/**
+ * The context-root `.dockerignore` we write **only when the project ships
+ * none**, as a fallback for the legacy non-BuildKit builder.
+ *
+ * Deliberately does not include the project's own rules: it exists only in
+ * the case where there are none. Overwriting a project's file was a real
+ * regression — a carefully minimised context silently became the whole
+ * repo, which is a 10x build-time hit on a monorepo, and any in-env
+ * tooling that read the file saw ours instead.
+ */
+export function unionDockerignore(
+  services: readonly { image: { type: string; exclude?: readonly string[] } }[],
+): string {
+  const seen = new Set<string>(DEFAULT_DOCKERIGNORE);
+  const extras: string[] = [];
+  for (const s of services) {
+    if (s.image.type === "dockerfile" && s.image.exclude) {
+      for (const e of s.image.exclude) {
+        if (!seen.has(e)) {
+          seen.add(e);
+          extras.push(e);
+        }
+      }
+    }
+  }
+  return [GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
+}
+
+/**
+ * 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.
+ */
+export interface Hasher {
+  update(s: string): Hasher;
+  digest(encoding: "hex"): string;
+}
+
+export function buildContentKey(
+  createHasher: () => Hasher,
+  image: { content: string; exclude?: readonly string[] },
+): 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
+      // 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 ?? []))
+      .digest("hex")
+  );
+}

package/src/harness/buildkit-progress.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+
+import { summarizeBuildKit } from "./buildkit-progress";
+
+/** A realistic slice of `docker build --progress=plain` output. */
+const SAMPLE = `
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 512B done
+#1 DONE 0.1s
+
+#5 [builder 2/6] COPY go.mod go.sum ./
+#5 CACHED
+
+#7 [builder 3/6] RUN go build -o /out/api ./cmd/api
+#7 sha256:deadbeef
+#7 12.113 building...
+#7 DONE 12.4s
+
+#9 [stage-1 2/2] COPY --from=builder /out/api /usr/local/bin/api
+#9 DONE 0.3s
+`;
+
+describe("summarizeBuildKit", () => {
+  test("names each step from its bracketed line", () => {
+    const steps = summarizeBuildKit(SAMPLE);
+    const names = steps.map((s) => s.name);
+    expect(names).toContain("RUN go build -o /out/api ./cmd/api");
+    expect(names).toContain("COPY go.mod go.sum ./");
+  });
+
+  test("slowest first, so the answer to 'why is this slow' leads", () => {
+    const steps = summarizeBuildKit(SAMPLE);
+    expect(steps[0].name).toBe("RUN go build -o /out/api ./cmd/api");
+    expect(steps[0].secs).toBeCloseTo(12.4, 5);
+  });
+
+  /** "This was cached" is the answer to "why was this build fast" —
+   *  dropping cached steps makes a fully-cached build look like it did
+   *  nothing at all. */
+  test("cached steps are kept, at zero seconds", () => {
+    const cached = summarizeBuildKit(SAMPLE).find((s) => s.name.startsWith("COPY go.mod"))!;
+    expect(cached.cached).toBe(true);
+    expect(cached.secs).toBe(0);
+  });
+
+  test("uncached steps are not marked cached", () => {
+    const step = summarizeBuildKit(SAMPLE).find((s) => s.name.startsWith("RUN go build"))!;
+    expect(step.cached).toBe(false);
+  });
+
+  /** BuildKit repeats a step id on digest and progress lines; only the
+   *  first naming line is the command. */
+  test("a step's name is not overwritten by later lines for the same id", () => {
+    const out = summarizeBuildKit(`
+#7 [builder 3/6] RUN make
+#7 [builder 3/6] 1.234 some log output that looks like a name
+#7 DONE 1.0s
+`);
+    expect(out).toHaveLength(1);
+    expect(out[0].name).toBe("RUN make");
+  });
+
+  test("digest and transfer noise never becomes a step", () => {
+    const steps = summarizeBuildKit(SAMPLE);
+    expect(steps.some((s) => s.name.includes("sha256"))).toBe(false);
+    expect(steps.some((s) => s.name.includes("transferring"))).toBe(false);
+  });
+
+  test("a step with no DONE line reports zero rather than NaN", () => {
+    const out = summarizeBuildKit("#3 [x 1/2] RUN something\n");
+    expect(out).toHaveLength(1);
+    expect(out[0].secs).toBe(0);
+    expect(Number.isNaN(out[0].secs)).toBe(false);
+  });
+
+  test("a long step name is truncated", () => {
+    const long = "RUN " + "x".repeat(500);
+    const out = summarizeBuildKit(`#1 [a 1/1] ${long}\n#1 DONE 1.0s\n`);
+    expect(out[0].name.length).toBeLessThanOrEqual(80);
+  });
+
+  test("empty output yields no steps", () => {
+    expect(summarizeBuildKit("")).toEqual([]);
+  });
+
+  test("sub-second durations parse", () => {
+    const out = summarizeBuildKit("#1 [a 1/1] COPY . .\n#1 DONE 0.05s\n");
+    expect(out[0].secs).toBeCloseTo(0.05, 5);
+  });
+
+  /** A step can report CACHED after a DONE when only part of its work was
+   *  reused; the measured duration is the more useful number. */
+  test("CACHED after DONE does not clobber the measured duration", () => {
+    const out = summarizeBuildKit("#1 [a 1/1] RUN x\n#1 DONE 3.0s\n#1 CACHED\n");
+    expect(out[0].secs).toBeCloseTo(3.0, 5);
+    expect(out[0].cached).toBe(true);
+  });
+});

package/src/harness/buildkit-progress.ts

@@ -0,0 +1,74 @@
+/**
+ * Reading `docker build --progress=plain` output.
+ *
+ * BuildKit's plain progress is the only machine-readable account of what a
+ * build actually did, and it is what the dashboard shows when a bootstrap
+ * is slow — which step took the time, and which were cache hits. Parsing
+ * it is pure string work, so it belongs out here where it can be tested
+ * against real output shapes rather than inferred from the regexes.
+ *
+ * Ported out of `daemon.ts`.
+ *
+ * The format, for the parts we read:
+ *
+ * ```
+ * #7 [builder 3/6] RUN go build ./...
+ * #7 sha256:abc…                       ← noise; ignored
+ * #7 DONE 12.4s
+ * #9 CACHED
+ * ```
+ */
+
+export interface BuildStep {
+  name: string;
+  secs: number;
+  cached: boolean;
+}
+
+/** Longest step name we keep — these are Dockerfile lines and can be huge. */
+const MAX_NAME = 80;
+
+/**
+ * Summarise a build's steps, slowest first.
+ *
+ * Only the **first** line seen for a step id names it: BuildKit repeats
+ * the id for progress and digest lines, and a later one would overwrite
+ * the actual command with noise.
+ *
+ * A `CACHED` step is recorded at zero seconds rather than dropped —
+ * "this was cached" is the answer to "why was this build fast", and
+ * omitting it makes a fully-cached build look like it did nothing.
+ */
+export function summarizeBuildKit(out: string): BuildStep[] {
+  const names = new Map<string, string>();
+  const secs = new Map<string, number>();
+  const cached = new Set<string>();
+
+  for (const line of out.split("\n")) {
+    let m = line.match(/^#(\d+)\s+\[[^\]]*\]\s+(.+)$/);
+    if (m) {
+      const id = `#${m[1]}`;
+      if (!names.has(id)) names.set(id, m[2].trim().slice(0, MAX_NAME));
+      continue;
+    }
+    m = line.match(/^#(\d+)\s+DONE\s+([\d.]+)s/);
+    if (m) {
+      secs.set(`#${m[1]}`, parseFloat(m[2]));
+      continue;
+    }
+    m = line.match(/^#(\d+)\s+CACHED/);
+    if (m) {
+      const id = `#${m[1]}`;
+      cached.add(id);
+      // Don't clobber a real duration: a step can report CACHED after a
+      // DONE when part of its work was reused.
+      if (!secs.has(id)) secs.set(id, 0);
+    }
+  }
+
+  const steps: BuildStep[] = [];
+  for (const [id, name] of names) {
+    steps.push({ name, secs: secs.get(id) ?? 0, cached: cached.has(id) });
+  }
+  return steps.sort((a, b) => b.secs - a.secs);
+}

package/src/harness/container-run.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, test } from "bun:test";
+
+import { TCP_RETRIES2, runContainerArgs, type ContainerRunInput } from "./container-run";
+
+const base = (over: Partial<ContainerRunInput> = {}): ContainerRunInput => ({
+  svc: { name: "web" },
+  tag: "spectest/web:latest",
+  network: "spectest-net",
+  hostCacheName: "spectest-host",
+  caPath: "/etc/spectest/ca.crt",
+  ...over,
+});
+
+/** The value after a `-e` / `--sysctl` style flag. */
+function valueAfter(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  return i === -1 ? undefined : args[i + 1];
+}
+const envOf = (args: string[], name: string): string | undefined =>
+  args.filter((a, i) => args[i - 1] === "-e").find((a) => a.startsWith(`${name}=`))
+    ?.slice(name.length + 1);
+
+describe("identity and network", () => {
+  test("the image is the last thing before any command override", () => {
+    const args = runContainerArgs(base());
+    expect(args[args.length - 1]).toBe("spectest/web:latest");
+  });
+
+  test("names the container and its host after the service", () => {
+    const args = runContainerArgs(base());
+    expect(args).toContain("--name=web");
+    expect(args).toContain("--hostname=web");
+    expect(args).toContain("--network=spectest-net");
+  });
+
+  /** A single-label host breaks headless Chromium, which attempts TLS
+   *  against it; every service therefore also answers to a FQDN. */
+  test("always adds the .internal alias", () => {
+    expect(runContainerArgs(base())).toContain("--network-alias=web.internal");
+  });
+
+  test("extra aliases are added alongside, not instead of, .internal", () => {
+    const args = runContainerArgs(base({ aliases: ["api.test", "www.test"] }));
+    expect(args).toContain("--network-alias=web.internal");
+    expect(args).toContain("--network-alias=api.test");
+    expect(args).toContain("--network-alias=www.test");
+  });
+
+  test("bounds TCP give-up time inside the container's netns", () => {
+    const args = runContainerArgs(base());
+    expect(valueAfter(args, "--sysctl")).toBe(`net.ipv4.tcp_retries2=${TCP_RETRIES2}`);
+  });
+});
+
+describe("host resolution", () => {
+  test("pins every ingress hostname at the gateway", () => {
+    const args = runContainerArgs(
+      base({ gatewayIp: "10.42.0.1", ingressHosts: ["api.stripe.com", "app.test"] }),
+    );
+    expect(args).toContain("--add-host=api.stripe.com:10.42.0.1");
+    expect(args).toContain("--add-host=app.test:10.42.0.1");
+  });
+
+  /** The gateway is discovered from dockerd and may not be known yet.
+   *  Emitting `--add-host=h:` would be a docker error, not a no-op. */
+  test("emits no ingress host entries when the gateway is unknown", () => {
+    const args = runContainerArgs(base({ gatewayIp: null, ingressHosts: ["api.stripe.com"] }));
+    expect(args.some((a) => a.startsWith("--add-host=api.stripe.com"))).toBe(false);
+  });
+
+  test("names the host cache so apps can address it without an IP", () => {
+    const args = runContainerArgs(base({ hostCacheGateway: "10.42.0.1" }));
+    expect(args).toContain("--add-host=spectest-host:10.42.0.1");
+  });
+
+  test("omits the host cache where there isn't one", () => {
+    const args = runContainerArgs(base({ hostCacheGateway: null }));
+    expect(args.some((a) => a.startsWith("--add-host=spectest-host"))).toBe(false);
+  });
+});
+
+describe("certificate trust", () => {
+  test("mounts the CA and appends it to Node's roots", () => {
+    const args = runContainerArgs(base());
+    expect(args).toContain("--volume=/etc/spectest/ca.crt:/etc/spectest/ca.crt:ro");
+    expect(envOf(args, "NODE_EXTRA_CA_CERTS")).toBe("/etc/spectest/ca.crt");
+  });
+
+  /** The load-bearing one. These three variables REPLACE the trust store,
+   *  so handing them the bare CA leaves the container trusting spectest and
+   *  no public root — Python requests and every AWS SDK then fail to verify
+   *  real HTTPS, in any image. They must get the combined bundle. */
+  test("the replacing variables get the bundle, never the bare CA", () => {
+    const args = runContainerArgs(base({ caBundle: "/etc/spectest/ca-bundle.crt" }));
+    for (const name of ["SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "AWS_CA_BUNDLE"]) {
+      expect(envOf(args, name)).toBe("/etc/spectest/ca-bundle.crt");
+      expect(envOf(args, name)).not.toBe("/etc/spectest/ca.crt");
+    }
+    expect(args).toContain(
+      "--volume=/etc/spectest/ca-bundle.crt:/etc/spectest/ca-bundle.crt:ro",
+    );
+  });
+
+  test("with no bundle, the replacing variables are left unset", () => {
+    const args = runContainerArgs(base({ caBundle: null }));
+    expect(envOf(args, "SSL_CERT_FILE")).toBeUndefined();
+    expect(envOf(args, "AWS_CA_BUNDLE")).toBeUndefined();
+    // The appending one is still safe to set on its own.
+    expect(envOf(args, "NODE_EXTRA_CA_CERTS")).toBe("/etc/spectest/ca.crt");
+  });
+
+  test("a bundle equal to the CA path is not mounted twice", () => {
+    const args = runContainerArgs(base({ caBundle: "/etc/spectest/ca.crt" }));
+    const mounts = args.filter((a) => a === "--volume=/etc/spectest/ca.crt:/etc/spectest/ca.crt:ro");
+    expect(mounts).toHaveLength(1);
+  });
+});
+
+describe("service configuration", () => {
+  test("passes the service's own environment through", () => {
+    const args = runContainerArgs(base({ svc: { name: "web", env: { PORT: "3000" } } }));
+    expect(envOf(args, "PORT")).toBe("3000");
+  });
+
+  /** A project must be able to override what we set — an env var it
+   *  declares is an explicit statement, ours is a default. */
+  test("the service's environment comes after ours, so it wins", () => {
+    const args = runContainerArgs(
+      base({
+        svc: { name: "web", env: { NODE_EXTRA_CA_CERTS: "/custom.pem" } },
+        caBundle: "/etc/spectest/ca-bundle.crt",
+      }),
+    );
+    const ours = args.indexOf("NODE_EXTRA_CA_CERTS=/etc/spectest/ca.crt");
+    const theirs = args.indexOf("NODE_EXTRA_CA_CERTS=/custom.pem");
+    expect(ours).toBeGreaterThanOrEqual(0);
+    expect(theirs).toBeGreaterThan(ours);
+  });
+
+  test("passes volume flags through untouched", () => {
+    const args = runContainerArgs(base({ volumeFlags: ["--volume=/a:/b", "--mount=type=tmpfs"] }));
+    expect(args).toContain("--volume=/a:/b");
+    expect(args).toContain("--mount=type=tmpfs");
+  });
+
+  test("carries privileged, tmpfs, cgroupns and workdir", () => {
+    const args = runContainerArgs(
+      base({
+        svc: {
+          name: "web",
+          privileged: true,
+          tmpfs: ["/run", "/tmp"],
+          cgroupns: "host",
+          workdir: "/srv",
+        },
+      }),
+    );
+    expect(args).toContain("--privileged");
+    expect(args).toContain("--tmpfs=/run");
+    expect(args).toContain("--tmpfs=/tmp");
+    expect(args).toContain("--cgroupns=host");
+    expect(args).toContain("--workdir=/srv");
+  });
+
+  test("omits every optional flag when nothing asks for it", () => {
+    const args = runContainerArgs(base());
+    expect(args).not.toContain("--privileged");
+    expect(args.some((a) => a.startsWith("--tmpfs="))).toBe(false);
+    expect(args.some((a) => a.startsWith("--cgroupns="))).toBe(false);
+    expect(args.some((a) => a.startsWith("--workdir="))).toBe(false);
+    expect(args).not.toContain("--entrypoint=/bin/sh");
+  });
+});
+
+describe("command vs args", () => {
+  test("command replaces the entrypoint and runs through sh -c", () => {
+    const args = runContainerArgs(base({ svc: { name: "web", command: "node server.js" } }));
+    expect(args).toContain("--entrypoint=/bin/sh");
+    expect(args.slice(-3)).toEqual(["spectest/web:latest", "-c", "node server.js"]);
+  });
+
+  /** The init-wrapped-image case: postgres needs extra flags without
+   *  losing the entrypoint that sets the cluster up. */
+  test("args override CMD and keep the entrypoint", () => {
+    const args = runContainerArgs(
+      base({ svc: { name: "db", args: ["postgres", "-c", "wal_level=logical"] } }),
+    );
+    expect(args).not.toContain("--entrypoint=/bin/sh");
+    expect(args.slice(-4)).toEqual([
+      "spectest/web:latest",
+      "postgres",
+      "-c",
+      "wal_level=logical",
+    ]);
+  });
+
+  /** Accepting both would silently drop one, and which one is dropped is
+   *  not something a reader could predict from the config. */
+  test("declaring both is rejected, naming the service", () => {
+    expect(() =>
+      runContainerArgs(base({ svc: { name: "web", command: "x", args: ["y"] } })),
+    ).toThrow(/service web:.*mutually exclusive/s);
+  });
+
+  test("an empty args array is not treated as an override", () => {
+    const args = runContainerArgs(base({ svc: { name: "web", args: [] } }));
+    expect(args[args.length - 1]).toBe("spectest/web:latest");
+  });
+});

package/src/harness/container-run.ts

@@ -0,0 +1,158 @@
+/**
+ * Assembling the `docker run` command line for a service container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This is the most
+ * consequential command the harness builds — it decides a container's
+ * network identity, what it trusts, what it can see of the host, and what
+ * it actually executes — and it had no tests, because the only way to
+ * reach it was to start a real container.
+ *
+ * Splitting the argv construction from running it makes every rule below
+ * assertable in milliseconds. The caller keeps the side effects: removing
+ * a leftover container, invoking docker, and reading the result.
+ *
+ * ## Rules encoded here
+ *
+ * **Two names, always.** Every service answers to its bare name and to
+ * `<name>.internal`. The multi-label form exists because a single-label
+ * host breaks things that assume a FQDN — notably headless Chromium, which
+ * tries TLS against a bare name and fails with a protocol error even
+ * though `fetch` to the same URL is fine.
+ *
+ * **Certificate trust is two different mechanisms, and mixing them up
+ * breaks images silently.** `NODE_EXTRA_CA_CERTS` *appends* to the trust
+ * store, so it takes the bare spectest CA. `SSL_CERT_FILE`,
+ * `REQUESTS_CA_BUNDLE` and `AWS_CA_BUNDLE` *replace* it, so they must get
+ * the combined bundle — public roots plus ours. Pointing those three at
+ * the bare CA leaves the container trusting spectest and nothing else, and
+ * every outbound HTTPS call to a real service fails to verify. Node never
+ * showed the problem, which is why it went unnoticed: only the appending
+ * variable was in play.
+ *
+ * **`command` and `args` are different overrides.** `command` replaces the
+ * entrypoint and runs through `sh -c`; `args` keeps the entrypoint and
+ * overrides CMD, which is what init-wrapped images like postgres need to
+ * take extra flags. Accepting both would silently drop one.
+ */
+
+/** The subset of a service's config that shapes its container. */
+export interface ContainerService {
+  name: string;
+  env?: Record<string, string>;
+  workdir?: string;
+  privileged?: boolean;
+  tmpfs?: readonly string[];
+  cgroupns?: string;
+  command?: string;
+  args?: readonly string[];
+}
+
+export interface ContainerRunInput {
+  svc: ContainerService;
+  /** The image tag to run. */
+  tag: string;
+  /** Docker network to attach to. */
+  network: string;
+  /** Extra `--network-alias` names beyond `<name>` and `<name>.internal`. */
+  aliases?: readonly string[];
+  /** Volume/file/certificate mount flags, already assembled. */
+  volumeFlags?: readonly string[];
+  /** Ingress hostnames to pin to {@link ContainerRunInput.gatewayIp}. */
+  ingressHosts?: readonly string[];
+  /** The bridge gateway, where the ingress listeners are. Null when it
+   *  isn't known yet, in which case no `--add-host` is emitted. */
+  gatewayIp?: string | null;
+  /** The host image-cache gateway, reachable as `spectest-host`. */
+  hostCacheGateway?: string | null;
+  hostCacheName: string;
+  /** The in-VM root CA, bind-mounted and appended to Node's roots. */
+  caPath: string;
+  /** Public roots ⧺ our CA, for the variables that *replace* the store. */
+  caBundle?: string | null;
+}
+
+/**
+ * Bound TCP give-up time inside the container's own network namespace.
+ *
+ * `net.ipv4.tcp_retries2` is per-netns and a fresh netns resets to the
+ * kernel default (15, roughly 15 minutes of RTO backoff), so lowering it on
+ * the guest's init netns does not reach containers — and the flows that
+ * actually wedge live here: buildkit pulling base images and exporting
+ * cache, and k3s's containerd pulling images, all over the VM↔host path to
+ * the host registry. On a lost retransmit under concurrent forks such a
+ * flow otherwise stalls a build for minutes; six retries resets a genuinely
+ * stuck connection in tens of seconds and the client reconnects. Live
+ * connections keep getting ACKs and are unaffected.
+ *
+ * Safe because every service runs on the bridge network with its own netns,
+ * never `--network=host`, where writing `net.*` is denied.
+ */
+export const TCP_RETRIES2 = 6;
+
+/** Build the full `docker run` argv. Pure: no I/O, no module state. */
+export function runContainerArgs(input: ContainerRunInput): string[] {
+  const { svc, tag, network } = input;
+
+  if (svc.command && svc.args?.length) {
+    throw new Error(
+      `service ${svc.name}: \`command\` and \`args\` are mutually exclusive ` +
+        `(command replaces the entrypoint with /bin/sh -c; args keeps it)`,
+    );
+  }
+
+  const args = [
+    "run",
+    "-d",
+    "--restart=no",
+    `--name=${svc.name}`,
+    `--hostname=${svc.name}`,
+    `--network=${network}`,
+    `--network-alias=${svc.name}.internal`,
+  ];
+
+  for (const alias of input.aliases ?? []) args.push(`--network-alias=${alias}`);
+
+  args.push("--sysctl", `net.ipv4.tcp_retries2=${TCP_RETRIES2}`);
+
+  // Ingress hostnames via /etc/hosts, which beats Docker's embedded DNS —
+  // so app code reaching a fake or a TLS-terminated proxy lands on the
+  // harness listener without touching the container's resolver config.
+  if (input.gatewayIp) {
+    for (const h of input.ingressHosts ?? []) {
+      args.push(`--add-host=${h}:${input.gatewayIp}`);
+    }
+  }
+  if (input.hostCacheGateway) {
+    args.push(`--add-host=${input.hostCacheName}:${input.hostCacheGateway}`);
+  }
+
+  if (svc.workdir) args.push(`--workdir=${svc.workdir}`);
+
+  // See the module header: the appending variable takes the bare CA, the
+  // replacing ones take the combined bundle.
+  args.push(`--volume=${input.caPath}:${input.caPath}:ro`);
+  args.push("-e", `NODE_EXTRA_CA_CERTS=${input.caPath}`);
+  const bundle = input.caBundle;
+  if (bundle) {
+    if (bundle !== input.caPath) args.push(`--volume=${bundle}:${bundle}:ro`);
+    args.push("-e", `SSL_CERT_FILE=${bundle}`);
+    args.push("-e", `REQUESTS_CA_BUNDLE=${bundle}`);
+    args.push("-e", `AWS_CA_BUNDLE=${bundle}`);
+  }
+
+  // The service's own env comes after ours, so a project can override the
+  // defaults we set rather than being silently overridden by them.
+  for (const [k, v] of Object.entries(svc.env ?? {})) args.push("-e", `${k}=${v}`);
+
+  for (const flag of input.volumeFlags ?? []) args.push(flag);
+  if (svc.privileged) args.push("--privileged");
+  for (const p of svc.tmpfs ?? []) args.push(`--tmpfs=${p}`);
+  if (svc.cgroupns) args.push(`--cgroupns=${svc.cgroupns}`);
+
+  if (svc.command) args.push("--entrypoint=/bin/sh");
+  args.push(tag);
+  if (svc.command) args.push("-c", svc.command);
+  else if (svc.args?.length) args.push(...svc.args);
+
+  return args;
+}