Dockerfile

@@ -1,28 +1,36 @@
-# Two images from one recipe: the one modules are COMPILED in, and the one they RUN in.
+# Three stages, two published images: the one modules are COMPILED in, and the one they RUN in.
 #
 # **They were the same image, and that was a mistake.** A module's recipe starts from this and
 # invokes the compiler out of it, so the compiler had to be here — and because the same image was
 # also what every module ran in, every running container on every machine carried a TypeScript
-# compiler it would never invoke. 23 of the 28 MB of libraries were that compiler. It was defended
-# in a comment, which made a workaround look like a decision: the earlier attempt to prune the build
-# tools produced a smaller image that nothing could be built on, and the answer to that is two
-# images rather than one image that is bad at both jobs.
+# compiler it would never invoke. The answer is separate stages rather than one image bad at both
+# jobs. `build.artifacts` in module.json names the published stage each — `toolchain` and `runtime`.
 #
-# Kept in one recipe deliberately. They must agree about the operating system, the language version
-# and the library, and two files drift. `build.artifacts` in module.json names a stage each.
+# The `deps` stage is neither published nor named there: it is where the mesh's package registry is
+# reached, so it is where — and only where — the credential to reach it exists. The toolchain copies
+# resolved node_modules out of it, so the credential is in no image any machine ever holds
+# (novox/hq ADR 0076). This is the buildkit-secret's job done without buildkit, because a machine's
+# docker may carry no buildx.
 
-# ---- toolchain: what a module is compiled in -------------------------------------------------
-FROM node:22-bookworm-slim AS toolchain
-# git, because a dependency named by a git URL is fetched by git and this image does not carry it.
-# Only here: what it is needed for happens at build time, and an image that can clone is an image
-# that can be made to clone.
+# ---- deps: node_modules resolved from the mesh's registry, credential and all ----------------
+FROM node:22-bookworm-slim AS deps
 RUN apt-get update \
       && apt-get install -y --no-install-recommends git ca-certificates \
       && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
-COPY package.json package-lock.json ./
-# Development dependencies included: the compiler is one, and so is the toolkit's own.
-RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm install --no-audit --no-fund
+COPY package.json ./
+# The builder writes .npmrc into the build context; it authenticates to the mesh's package registry
+# for the @novox scope, which is where @novox/mesh-sdk resolves. This stage is not published, so the
+# credential travels no further than here. Development dependencies included: the compiler is one.
+COPY .npmrc ./.npmrc
+RUN npm install --no-audit --no-fund
+
+# ---- toolchain: what a module is compiled in, WITHOUT the credential --------------------------
+FROM node:22-bookworm-slim AS toolchain
+WORKDIR /app
+COPY package.json ./
+# The resolved libraries, but not the .npmrc that resolved them.
+COPY --from=deps /app/node_modules ./node_modules
 # The toolkit arrives compiled. It used to arrive as sources, and this compiled it by hand — the
 # hook that builds it on install was running all along, and the result was then packed out of the
 # package, because with no explicit file list npm falls back to .gitignore and that ignores the
@@ -32,9 +40,7 @@ COPY src ./src
 RUN npm run build
 
 # ---- what the running image needs, and nothing else -------------------------------------------
-# Its own stage so the toolchain image keeps its build tools while the runtime image does not. The
-# prune has to happen somewhere, and doing it in the toolchain stage would take the compiler out of
-# the image whose whole purpose is to have one.
+# Its own stage so the toolchain image keeps its build tools while the runtime image does not.
 FROM toolchain AS lean
 RUN npm prune --omit=dev