@xemahq/repo-build-tooling 0.15.0 → 0.16.0

package/README.md

@@ -33,7 +33,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 
-`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, `cache/`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. Run `xema-composed-image` with no arguments for the full usage.
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -44,6 +44,6 @@
     "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:d3f54741da7e081ed21ee59ca2b27600880be97f359fde67028b756528c66153"
+    "sourceDigest": "sha256:679fdd3bb57a17ae5498cff954e255f49308d3babaed4c89fbb37a0ecc126db2"
   }
 }

package/src/composed-image-pnpm-context.mjs

@@ -3,26 +3,36 @@
 // offline prebuilt image build consumes as the named BuildKit context `xema-pnpm`. The runner's
 // own pnpm store is the second context (`xema-pnpm-store`); it is never copied.
 //
-//   <dir>/staged.json         { tool, pnpm, storeDir, subjects[], imageDir? } — the sentinel the image checks
+//   <dir>/staged.json         { tool, pnpm, storeDir, subjects[], cache, imageDir? } — the sentinel the image checks
 //   <dir>/corepack/pnpm.tgz   `corepack pack pnpm@<root packageManager>`
-//   <dir>/cache/              pnpm `cache-dir` (registry metadata), seeded from the runner's and warmed
+//   <dir>/cache/              --image-dir only: pnpm `cache-dir` (registry metadata), seeded from the runner's and warmed
+//                             (--subject writes no cache/: the member deploy is lockfile-driven and offline)
 //
 // stdout is exactly two lines for `$GITHUB_ENV`: `XEMA_PNPM_CONTEXT=<dir>` and
 // `XEMA_PNPM_STORE=<store root>`. Everything else goes to stderr. pnpm's own request-level
 // fetch retries apply; nothing here retries a command.
 import { execFileSync } from 'node:child_process';
 import { cpSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 
 import { memberClosure, memberFilters } from './composed-image-members.mjs';
-import { lockfileOnlyCommand } from './composed-image-prebuilt-dockerfile.mjs';
+import { depsCopyDirs, lockfileOnlyCommand } from './composed-image-prebuilt-dockerfile.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 
 /** Runs a command, returns stdout; stderr is the caller's. Injectable for tests. */
 const defaultExec = (file, args, { cwd } = {}) =>
   execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], maxBuffer: 64 * 1024 * 1024 });
 
+/** `pnpm config get cache-dir` prints `undefined` when unset; then pnpm's own default applies. */
+export function resolveCacheDir(printed, { platform = process.platform, env = process.env, home = homedir() } = {}) {
+  const value = printed.trim();
+  if (value !== '' && value !== 'undefined') return value;
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'pnpm');
+  if (platform === 'win32') return join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'pnpm-cache');
+  return join(env.XDG_CACHE_HOME ?? join(home, '.cache'), 'pnpm');
+}
+
 /** `pnpm@10.33.0+sha512.…` → `10.33.0`. */
 function pnpmVersion(root) {
   const manager = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager;
@@ -49,7 +59,11 @@ function seedCache(exec, source, target, log) {
 }
 
 /** A scratch tree holding exactly the deps stage's inputs, so `--lockfile-only` never touches the repository. */
-function scratchLockfileInputs({ root, imageDir, exec, copy }) {
+function scratchLockfileInputs({ root, imageDir, exec }) {
+  // The directories the deps stage COPYs are read back from the committed Dockerfile (`depsCopyDirs`), so there is one definition.
+  const dockerfile = join(root, imageDir, 'Dockerfile');
+  if (!existsSync(dockerfile)) throw new Error(`${imageDir}/Dockerfile is absent — render it first: xema-composed-image dockerfile --prebuilt --write`);
+  const copy = depsCopyDirs(readFileSync(dockerfile, 'utf8'));
   const scratch = mkdtempSync(join(tmpdir(), 'xema-pnpm-lock-'));
   const put = (rel) => {
     if (!existsSync(join(root, rel))) return;
@@ -67,7 +81,6 @@ export function buildPnpmContext({
   dir,
   subjects = [],
   imageDir,
-  copy = [],
   exec = defaultExec,
   log = () => {},
 }) {
@@ -83,37 +96,27 @@ export function buildPnpmContext({
   if (storePath === '' || !existsSync(storePath)) {
     throw new Error(`the runner's pnpm store ${storePath || '(unknown)'} does not exist — run pnpm install --frozen-lockfile before pnpm-context`);
   }
-  const cacheSource = exec('pnpm', ['config', 'get', 'cache-dir'], { cwd: root }).trim();
-
   mkdirSync(join(target, 'corepack'), { recursive: true });
   exec('corepack', ['pack', `pnpm@${pnpm}`, '-o', join(target, 'corepack', 'pnpm.tgz')], { cwd: root });
-  const cache = join(target, 'cache');
-  log(`pnpm-context: cache ${seedCache(exec, cacheSource, cache, log)} from ${cacheSource}`);
 
-  // Warm: the exact metadata requests the offline image build will make, answered from the registry once, here.
-  const base = [`--config.cache-dir=${cache}`];
-  if (subjects.length > 0) {
-    const tmp = mkdtempSync(join(tmpdir(), 'xema-pnpm-deploy-'));
-    try {
-      for (const subject of subjects) {
-        exec('pnpm', ['deploy', '--prod', '--ignore-scripts', '--prefer-offline', ...base, '--filter', subject, join(tmp, subject.replace(/[^A-Za-z0-9._-]/g, '_'))], { cwd: root });
-        log(`pnpm-context: warmed ${subject}`);
-      }
-    } finally {
-      rmSync(tmp, { recursive: true, force: true });
-    }
-  } else {
-    const scratch = scratchLockfileInputs({ root, imageDir, exec, copy });
+  // --subject: the member image runs the lockfile-driven `pnpm deploy --offline` from the store alone, so no
+  // metadata cache is seeded or warmed. --image-dir: its `--lockfile-only` resolve needs registry metadata, warmed here.
+  const withCache = subjects.length === 0;
+  if (withCache) {
+    const cacheSource = resolveCacheDir(exec('pnpm', ['config', 'get', 'cache-dir'], { cwd: root }));
+    const cache = join(target, 'cache');
+    log(`pnpm-context: cache ${seedCache(exec, cacheSource, cache, log)} from ${cacheSource}`);
+    const scratch = scratchLockfileInputs({ root, imageDir, exec });
     try {
-      const [file, ...args] = lockfileOnlyCommand(memberFilters({ root, imageDir }).flatMap((f) => f.split(' ')));
-      exec(file, [...args, ...base], { cwd: scratch });
+      const [file, ...args] = lockfileOnlyCommand(memberFilters({ root, imageDir }).flatMap((f) => f.split(' ')), { offline: false });
+      exec(file, [...args, `--config.cache-dir=${cache}`], { cwd: scratch });
       log(`pnpm-context: warmed the ${imageDir} lockfile-only resolve`);
     } finally {
       rmSync(scratch, { recursive: true, force: true });
     }
   }
 
-  const sentinel = { tool: toolVersion(), pnpm, storeDir: storeRoot, subjects: [...subjects], ...(imageDir === undefined ? {} : { imageDir }) };
+  const sentinel = { tool: toolVersion(), pnpm, storeDir: storeRoot, subjects: [...subjects], cache: withCache, ...(imageDir === undefined ? {} : { imageDir }) };
   writeFileSync(join(target, 'staged.json'), `${JSON.stringify(sentinel, null, 2)}\n`);
   return { context: target, store: storeRoot };
 }

package/src/composed-image-pnpm-context.test.mjs

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { buildPnpmContext } from './composed-image-pnpm-context.mjs';
+import { buildPnpmContext, resolveCacheDir } from './composed-image-pnpm-context.mjs';
 import { lockfileOnlyCommand, renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { CLOSURE, fakePnpm, workspace, write } from './composed-image-fixture.test.mjs';
 
@@ -12,6 +12,8 @@ function setup({ store = true, cache = true } = {}) {
   const root = workspace();
   write(root, 'package.json', { name: 'r', packageManager: 'pnpm@10.33.0+sha512.abc' });
   write(root, 'pnpm-lock.yaml', 'lockfileVersion: 9\n');
+  write(root, 'tooling/dev/x.txt', 'x');
+  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', usesToken: false, exec: fakePnpm(root) }).dockerfile);
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-home-'));
   const storePath = path.join(home, '.pnpm-store', 'v10');
   const cacheDir = path.join(home, 'cache');
@@ -38,23 +40,20 @@ function setup({ store = true, cache = true } = {}) {
   return { root, out, exec, calls, storePath, home };
 }
 
-test('--subject: writes corepack tgz, a seeded and warmed cache dir, and the sentinel; returns the two env values', () => {
+test('--subject: writes the corepack tgz and the sentinel, no cache dir and no deploy warm-up; returns the two env values', () => {
   const { root, out, exec, calls, home } = setup();
   const result = buildPnpmContext({ root, dir: out, subjects: ['svc-a', 'svc-b'], exec });
   assert.deepEqual(result, { context: out, store: path.join(home, '.pnpm-store') });
   assert.equal(fs.readFileSync(path.join(out, 'corepack/pnpm.tgz'), 'utf8'), 'tgz');
-  assert.ok(fs.existsSync(path.join(out, 'cache/metadata-v1.3/registry.npmjs.org/x.json')));
+  assert.equal(fs.existsSync(path.join(out, 'cache')), false);
   const staged = JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8'));
-  assert.deepEqual(Object.keys(staged), ['tool', 'pnpm', 'storeDir', 'subjects']);
+  assert.deepEqual(Object.keys(staged), ['tool', 'pnpm', 'storeDir', 'subjects', 'cache']);
   assert.equal(staged.pnpm, '10.33.0');
+  assert.equal(staged.cache, false);
   assert.deepEqual(staged.subjects, ['svc-a', 'svc-b']);
   assert.deepEqual(calls.find((c) => c.file === 'corepack').args.slice(0, 2), ['pack', 'pnpm@10.33.0']);
-  const deploys = calls.filter((c) => c.args[0] === 'deploy');
-  assert.equal(deploys.length, 2);
-  for (const d of deploys) {
-    for (const flag of ['--prod', '--ignore-scripts', '--prefer-offline', `--config.cache-dir=${path.join(out, 'cache')}`]) assert.ok(d.args.includes(flag), flag);
-    assert.ok(!fs.existsSync(d.args.at(-1)), 'the deploy target is deleted');
-  }
+  assert.equal(calls.filter((c) => c.args[0] === 'deploy' || c.args.includes('--lockfile-only')).length, 0, 'no warm-up');
+  assert.ok(!calls.some((c) => c.args[0] === 'config'));
 });
 
 test('refuses a non-empty directory, a missing store, and a bad invocation, writing nothing', () => {
@@ -74,19 +73,24 @@ test('--image-dir: runs the generator\'s lockfile-only command on a scratch copy
   const resolve = calls.find((c) => c.args.includes('--lockfile-only'));
   assert.notEqual(resolve.cwd, root);
   assert.ok(resolve.scratch.includes('pnpm-lock.yaml') && resolve.scratch.includes('package.json'));
+  assert.ok(resolve.scratch.includes('tooling'), 'the deps stage COPY directories come from the committed Dockerfile');
+  assert.ok(resolve.args.includes('--prefer-offline') && !resolve.args.includes('--offline'), 'the warm-up fetches; the image resolves --offline');
   assert.ok(resolve.args.includes(`--config.cache-dir=${path.join(out, 'cache')}`));
   assert.equal(fs.existsSync(resolve.cwd), false, 'the scratch tree is deleted');
   assert.equal(fs.readFileSync(path.join(root, 'pnpm-lock.yaml'), 'utf8'), 'lockfileVersion: 9\n');
-  assert.equal(JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8')).imageDir, 'infra/composed-process');
+  const staged = JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8'));
+  assert.equal(staged.imageDir, 'infra/composed-process');
+  assert.equal(staged.cache, true);
 });
 
 test('the lockfile-only command is the one the generated Dockerfile runs (no drift)', () => {
   const root = workspace();
   const words = lockfileOnlyCommand(['--filter', '@t/alpha-api...']);
-  assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--prefer-offline']);
+  assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--offline']);
+  assert.equal(lockfileOnlyCommand(['--filter', 'x'], { offline: false })[3], '--prefer-offline');
   assert.ok(words.includes('--config.inject-workspace-packages=true') && words.includes('--config.dedupe-injected-deps=false'));
   const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', usesToken: false, exec: fakePnpm(root) });
-  assert.ok(text.includes('pnpm install --lockfile-only --prefer-offline ${INJECT} --filter @t/alpha-api... --filter @t/alpha-db-api... &&'));
+  assert.ok(text.includes('pnpm install --lockfile-only --offline ${INJECT} --filter @t/alpha-api... --filter @t/alpha-db-api... &&'));
   assert.ok(text.includes('INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false"'));
 });
 
@@ -97,8 +101,15 @@ test('a failed cp -al falls back to a copy and logs why', () => {
     if (file === 'cp') throw new Error('cross-device link');
     return exec(file, args, options);
   };
-  buildPnpmContext({ root, dir: out, subjects: ['s'], exec: failing, log: (m) => logs.push(m) });
+  buildPnpmContext({ root, dir: out, imageDir: 'infra/composed-process', exec: failing, log: (m) => logs.push(m) });
   assert.ok(logs.some((m) => /cp -al failed \(cross-device link\)/.test(m)));
   assert.ok(fs.existsSync(path.join(out, 'cache/metadata-v1.3/registry.npmjs.org/x.json')));
   assert.ok(home);
 });
+
+test('an unset cache-dir ("undefined") resolves to the pnpm default per platform', () => {
+  assert.equal(resolveCacheDir('/x/c\n'), '/x/c');
+  assert.equal(resolveCacheDir('undefined\n', { platform: 'darwin', home: '/h' }), '/h/Library/Caches/pnpm');
+  assert.equal(resolveCacheDir('undefined', { platform: 'linux', env: {}, home: '/h' }), '/h/.cache/pnpm');
+  assert.equal(resolveCacheDir('', { platform: 'linux', env: { XDG_CACHE_HOME: '/xdg' }, home: '/h' }), '/xdg/pnpm');
+});

package/src/composed-image-prebuilt-dockerfile.mjs

@@ -3,7 +3,8 @@
 // is ASSEMBLED from build outputs made on the CI runner (`xema-composed-image stage`).
 // Docker compiles nothing. The full-build template (`composed-image-dockerfile.mjs`)
 // stays available for repositories that still build inside Docker.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
 
 import { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY } from './composed-image-paths.mjs';
@@ -68,12 +69,75 @@ export const injectFlags = () => ['--config.inject-workspace-packages=true', '--
 
 /**
  * The deps stage's `--lockfile-only` resolve, as words (`INJECT_TOKEN` stands for `injectFlags()`).
- * The Dockerfile renderer and `xema-composed-image pnpm-context` both read THIS function, so the
- * metadata the context warms is exactly what the image resolves.
+ * The image runs it `--offline` against the metadata cache `pnpm-context --image-dir` warmed; the warm-up
+ * runs the SAME words with `--prefer-offline` (`offline: false`). Both read THIS function, so the metadata
+ * the context holds is exactly what the image resolves.
  */
-export const lockfileOnlyWords = (filters) => ['pnpm', 'install', '--lockfile-only', '--prefer-offline', INJECT_TOKEN, ...filters];
-/** The same command with the inject words expanded: `[file, ...args]`. */
-export const lockfileOnlyCommand = (filters) => lockfileOnlyWords(filters).flatMap((w) => (w === INJECT_TOKEN ? injectFlags() : [w]));
+export const lockfileOnlyWords = (filters, { offline = true } = {}) =>
+  ['pnpm', 'install', '--lockfile-only', offline ? '--offline' : '--prefer-offline', INJECT_TOKEN, ...filters];
+/** The same command with the inject words expanded: `[file, ...args]`. `offline: false` is the cache warm-up form. */
+export const lockfileOnlyCommand = (filters, options) => lockfileOnlyWords(filters, options).flatMap((w) => (w === INJECT_TOKEN ? injectFlags() : [w]));
+
+/** The line that brings one `--copy` directory into the deps stage; `depsCopyDirs` is its inverse (pnpm-context reads the directories back from the committed Dockerfile). */
+const copyLine = (directory) => `COPY ${directory} ./${directory}`;
+export function depsCopyDirs(dockerfileText) {
+  const deps = /^FROM base AS deps\n([\s\S]*?)^COPY --parents/m.exec(dockerfileText);
+  if (deps === null) throw new Error('the Dockerfile has no deps stage with COPY --parents — render it: xema-composed-image dockerfile --prebuilt --write');
+  return [...deps[1].matchAll(/^COPY (\S+\/) \.\/\1$/gm)].map((m) => m[1]);
+}
+
+/** Build-script dependencies the image never runs: Prisma 7 with the pg adapter ships no engine (migrations run in-app), the rest are JS or fetch nothing the image needs. */
+export const REBUILD_EXCLUDED = Object.freeze(['prisma', '@prisma/client', '@prisma/engines', '@nestjs/core', 'esbuild', '@swc/core']);
+
+/**
+ * The `onlyBuiltDependencies` the image must still `pnpm rebuild`: those in the members' PROD closure
+ * (`prodPackages`: `[{ name, dir }]`) less `REBUILD_EXCLUDED`. A module that needs `node-gyp` (a `binding.gyp`
+ * and no optional prebuilt packages) cannot be built here (the install is offline, `--ignore-scripts`, and the base
+ * has no toolchain), so it is refused: build it on a runner of the target arch and stage the `.node` files.
+ */
+export function rebuildList({ built, prodPackages }) {
+  const present = new Map(prodPackages.map((p) => [p.name, p.dir]));
+  const names = built.filter((name) => !REBUILD_EXCLUDED.includes(name) && present.has(name));
+  for (const name of names) {
+    const dir = present.get(name);
+    let optional = 0;
+    try {
+      optional = Object.keys(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).optionalDependencies ?? {}).length;
+    } catch {
+      /* unreadable manifest: judged by binding.gyp alone */
+    }
+    if (existsSync(join(dir, 'binding.gyp')) && optional === 0) {
+      throw new Error(
+        `${name} needs node-gyp (binding.gyp, no optional prebuilt packages) and no native artifact is staged for it: ` +
+          'the prebuilt composed image installs offline with --ignore-scripts and has no toolchain. ' +
+          'Build it on a runner of each target arch (the arm runner for arm64) and stage the .node files; see the arm64 native-artifact note in composed-image-prebuilt-dockerfile.mjs. Refusing to render.',
+      );
+    }
+  }
+  return names;
+}
+
+const defaultExec = (file, args, { cwd }) => execFileSync(file, args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+
+/** `[{ name, dir }]` for every installed package in the members' prod closure (`pnpm ls --prod --parseable`); needs `pnpm install` to have run. */
+export function memberProdPackages({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec = defaultExec } = {}) {
+  const words = memberFilters({ root, imageDir }).flatMap((f) => f.split(' '));
+  const listing = exec('pnpm', ['ls', '-r', '--prod', '--depth', 'Infinity', '--parseable', ...words], { cwd: root });
+  const seen = new Map();
+  for (const line of listing.split('\n').map((l) => l.trim()).filter(Boolean)) {
+    if (!line.includes('node_modules')) continue; // workspace packages themselves
+    let dir;
+    try {
+      dir = realpathSync(line);
+      const name = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name;
+      if (typeof name === 'string') seen.set(name, dir);
+    } catch {
+      /* not an installed package directory */
+    }
+  }
+  if (seen.size === 0) throw new Error('pnpm ls --prod listed no installed package: run pnpm install --frozen-lockfile before rendering the prebuilt Dockerfile');
+  return [...seen].map(([name, dir]) => ({ name, dir }));
+}
 
 const parts = (sources) => sources.map((source) => `    ${source} \\`).join('\n');
 
@@ -87,6 +151,7 @@ export function renderPrebuiltDockerfile({
   usesToken,
   stageDir = DEFAULT_STAGE_DIR,
   exec,
+  prodPackages = [],
 }) {
   if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
   validate({ copy, cacheId, buildSource, stageDir });
@@ -97,19 +162,20 @@ export function renderPrebuiltDockerfile({
     throw new Error('pnpm-workspace.yaml has no onlyBuiltDependencies: — `pnpm rebuild` would have nothing to build; refusing to render');
   }
   const closure = memberClosure({ root, imageDir, exec });
+  const rebuild = rebuildList({ built, prodPackages });
   const filters = memberFilters({ root, imageDir }).join(' ');
   const manifests = memberManifests({ root, imageDir });
   const dirFlag = imageDir === COMPOSED_IMAGE_DIR ? '' : ` --image-dir ${imageDir}`;
   const toolDir = '/opt/xema-composed-image';
   const toolMount = `--mount=type=bind,source=${stageDir}/tool,target=${toolDir}`;
   const node = `${toolDir}/${IN_IMAGE_ENTRY}`;
-  const store = `--mount=type=cache,id=pnpm-store-${cacheId},target=/root/.pnpm-store`;
-  const metadata = `--mount=type=cache,id=pnpm-metadata-${cacheId},target=/root/.cache/pnpm`;
+  const store = '--mount=type=bind,from=xema-pnpm-store,target=/root/.pnpm-store,rw';
+  const metadata = '--mount=type=bind,from=xema-pnpm,source=cache,target=/root/.cache/pnpm,rw';
   const secret = usesToken ? '  --mount=type=secret,id=npm_token,required=true \\\n' : '';
   const tokenExport = usesToken
     ? 'export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\\n  '
     : '';
-  const copies = [...new Set(copy.map((d) => posix.normalize(`${d}/`)))].map((d) => `COPY ${d} ./${d}`).join('\n');
+  const copies = [...new Set(copy.map((d) => posix.normalize(`${d}/`)))].map(copyLine).join('\n');
   const manifestSources = closure.map((directory) => `${directory}/package.json`);
   const assembleSources = [...closure, ...manifests];
   const imageCopy = posix.normalize(`${imageDir}/`);
@@ -126,12 +192,16 @@ export function renderPrebuiltDockerfile({
 #
 # Stages:
 #   deps      arch-native. Inputs are the lockfile and the closure's manifests ONLY, so the
-#             layer is cached until one of them changes. Production install with the
-#             workspace packages INJECTED, then \`pnpm rebuild <names>\` runs the build scripts
-#             of the root \`onlyBuiltDependencies\` (Prisma engines, native addons) natively.
-#             The names are listed because a bare filtered \`pnpm rebuild\` would also run
-#             the members' own postinstall (no schema here); a name absent from the graph
-#             is tolerated. The list is rendered, so a change to it makes \`--check\` stale.
+#             layer is cached until one of them changes. OFFLINE: every install RUN is
+#             \`--network=none\` and reads only the CI runner's pnpm store (\`xema-pnpm-store\`
+#             context), the packed pnpm and the warmed registry-metadata cache (\`xema-pnpm\`
+#             context, built by \`xema-composed-image pnpm-context --image-dir\`). corepack
+#             installs pnpm from that tarball, never from the network. Production install with
+#             the workspace packages INJECTED and \`--ignore-scripts\`. \`pnpm rebuild <names>\`
+#             runs only for \`onlyBuiltDependencies\` present in the members' PROD closure, less
+#             prisma, @prisma/client, @prisma/engines (Prisma 7 + pg adapter ships no engine and
+#             migrations run in-app), @nestjs/core, esbuild and @swc/core; when none is left the
+#             step is not rendered. The list is rendered, so a change makes \`--check\` stale.
 #   assemble  source of the closure + the staged outputs, the injected copies synced to
 #             their \`files\`, then the proofs on the target arch: Prisma clients run, the
 #             member index is written, every member loads ALONE as \`node\`, production.
@@ -139,8 +209,18 @@ export function renderPrebuiltDockerfile({
 #             members' code re-pushes only the layers that changed (see the final stage).
 #             Nothing of the tool ships.
 #
+# NATIVE MODULES. No prod-closure module needs node-gyp today. The renderer REFUSES to render when
+# one appears (a \`binding.gyp\` and no optional prebuilt packages) because this image installs with
+# --ignore-scripts and carries no compiler. The path then: build the module on a runner of EACH target
+# arch natively (the \`arm\` runner for arm64; no QEMU), in the digest-pinned bookworm node image with
+# --network=none and the image's node headers, stage \`native/<arch>/<pkg>/*.node\`, and COPY them from
+# \`native/\${TARGETARCH}/\` in the deps stage.
+#
 # The \`--filter <package>...\` words below are LITERAL: the content hash of this image reads
 # them to narrow the lockfile to the members' closures.
+FROM scratch AS xema-pnpm
+FROM scratch AS xema-pnpm-store
+
 FROM ${NODE_BASE} AS base
 RUN corepack enable && \\
     apt-get update && apt-get install -y --no-install-recommends openssl wget && rm -rf /var/lib/apt/lists/* && \\
@@ -149,19 +229,29 @@ RUN corepack enable && \\
 FROM base AS deps
 WORKDIR /monorepo
 ENV CI=true
+# corepack must not download pnpm: the packed tarball comes from the runner.
+ENV COREPACK_ENABLE_NETWORK=0
+# The runner's store is bind-mounted here. Set it for pnpm explicitly: the base layer's \`pnpm config set\` was
+# written by whatever pnpm corepack fetched then, and an offline resolve falls back to the store index.
+ENV npm_config_store_dir=/root/.pnpm-store
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
 ${copies === '' ? '' : `${copies}\n`}COPY --parents \\
 ${parts(manifestSources)}
     ./
-RUN ${store} \\
+RUN --network=none --mount=type=bind,from=xema-pnpm,target=/xema-pnpm \\
+  test -f /xema-pnpm/staged.json || { \\
+    echo "the prebuilt composed image needs --build-context xema-pnpm and xema-pnpm-store (CI only); render the full image (no --prebuilt) to build elsewhere" >&2; \\
+    exit 1; \\
+  } && corepack install -g /xema-pnpm/corepack/pnpm.tgz
+RUN --network=none ${store} \\
   ${metadata} \\
 ${secret}  ${toolMount} \\
   ${tokenExport}INJECT="${injectFlags().join(' ')}" && \\
   cp pnpm-lock.yaml /tmp/pnpm-lock.committed.yaml && \\
   ${lockfileOnlyWords(filters.split(' ')).join(' ')} && \\
   node ${node} pins${dirFlag} /tmp/pnpm-lock.committed.yaml && \\
-  pnpm install --prod --prefer-offline --ignore-scripts \${INJECT} ${filters} --frozen-lockfile && \\
-  pnpm rebuild ${built.join(' ')} ${filters}
+  pnpm install --prod --offline --ignore-scripts \${INJECT} ${filters} --frozen-lockfile${rebuild.length === 0 ? '' : ` && \\
+  pnpm rebuild ${rebuild.join(' ')} ${filters}`}
 
 FROM deps AS assemble
 COPY --parents \\
@@ -212,7 +302,8 @@ export function syncPrebuiltDockerfile({ mode, root = process.cwd(), imageDir =
   if (mode !== 'write' && mode !== 'check') throw new Error(`mode must be write or check, got "${mode}"`);
   const npmrc = join(root, '.npmrc');
   if (!existsSync(npmrc)) throw new Error(`${npmrc} is absent — the Dockerfile copies it and its token use decides the build secret`);
-  const { dockerfile, dockerignore } = renderPrebuiltDockerfile({ ...options, root, imageDir, exec, usesToken: npmrcUsesToken(readFileSync(npmrc, 'utf8')) });
+  const prodPackages = options.prodPackages ?? memberProdPackages({ root, imageDir, exec });
+  const { dockerfile, dockerignore } = renderPrebuiltDockerfile({ ...options, root, imageDir, exec, prodPackages, usesToken: npmrcUsesToken(readFileSync(npmrc, 'utf8')) });
   const files = [
     [posix.join(imageDir, 'Dockerfile'), dockerfile],
     [posix.join(imageDir, 'Dockerfile.dockerignore'), dockerignore],

package/src/composed-image-prebuilt-dockerfile.test.mjs

@@ -3,12 +3,21 @@ import fs from 'node:fs';
 import path from 'node:path';
 import test from 'node:test';
 
-import { onlyBuiltDependencies, renderPrebuiltDockerfile, renderPrebuiltDockerignore, syncPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
+import { depsCopyDirs, memberProdPackages, onlyBuiltDependencies, renderPrebuiltDockerfile, renderPrebuiltDockerignore, syncPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { parseArguments } from './composed-image.mjs';
 import { CLOSURE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
 
+/** An installed package directory for the prod-closure listing: `{ name, dir }`. */
+function installed(root, name, { gyp = false, optional = {} } = {}) {
+  const dir = path.join(root, 'node_modules/.pnpm', name.replace('/', '+'), 'node_modules', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name, optionalDependencies: optional }));
+  if (gyp) fs.writeFileSync(path.join(dir, 'binding.gyp'), '{}');
+  return { name, dir };
+}
+
 function options(root, extra = {}) {
-  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', usesToken: true, exec: fakePnpm(root), ...extra };
+  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', usesToken: true, exec: fakePnpm(root), prodPackages: [], ...extra };
 }
 
 test('the closure comes from pnpm ls with the members filters, and the filters are literal per member', () => {
@@ -18,9 +27,10 @@ test('the closure comes from pnpm ls with the members filters, and the filters a
   assert.deepEqual(closure, CLOSURE);
   assert.deepEqual(exec.calls[0].args, ['ls', '-r', '--depth', '-1', '--json', '--filter', '@t/alpha-api...', '--filter', '@t/alpha-db-api...']);
   const filters = '--filter @t/alpha-api... --filter @t/alpha-db-api...';
-  for (const verb of ['pnpm install --lockfile-only --prefer-offline ${INJECT}', 'pnpm install --prod --prefer-offline --ignore-scripts ${INJECT}', 'pnpm rebuild esbuild prisma @prisma/engines']) {
+  for (const verb of ['pnpm install --lockfile-only --offline ${INJECT}', 'pnpm install --prod --offline --ignore-scripts ${INJECT}']) {
     assert.ok(dockerfile.includes(`${verb} ${filters}`), verb);
   }
+  assert.doesNotMatch(dockerfile, /^ {2}pnpm rebuild/m, 'every built dependency is excluded or absent from the prod closure');
   assert.doesNotMatch(renderPrebuiltDockerfile(options(root, { usesToken: false })).dockerfile, /\$\(cat/);
 });
 
@@ -91,7 +101,7 @@ test('the rebuild names come from onlyBuiltDependencies: comments skipped, empty
   syncPrebuiltDockerfile({ mode: 'write', ...options(root) });
   const file = path.join(root, 'pnpm-workspace.yaml');
   fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace("  - 'esbuild'\n", "  - 'esbuild'\n  - sharp\n"));
-  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root) }), /Dockerfile is stale/);
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root, { prodPackages: [installed(root, 'sharp')] }) }), /Dockerfile is stale/);
   fs.writeFileSync(file, 'packages: []\n');
   assert.throws(() => renderPrebuiltDockerfile(options(root)), /no onlyBuiltDependencies/);
 });
@@ -114,3 +124,54 @@ test('the final stage is layered: deps, then assemble without the .pnpm store, t
   assert.ok(final.indexOf('ENV NODE_ENV=production') > final.lastIndexOf('COPY --from=assemble'));
   assert.match(final, /USER node\nCMD \["node", "\/monorepo\/xema-composed-process"\]\n$/);
 });
+
+test('rebuild lists only built dependencies present in the prod closure, less the excluded; none left means no step', () => {
+  const root = workspace();
+  fs.appendFileSync(path.join(root, 'pnpm-workspace.yaml'), '');
+  const yaml = fs.readFileSync(path.join(root, 'pnpm-workspace.yaml'), 'utf8').replace("  - 'esbuild'\n", "  - 'esbuild'\n  - msgpackr-extract\n  - not-in-closure\n  - '@swc/core'\n");
+  fs.writeFileSync(path.join(root, 'pnpm-workspace.yaml'), yaml);
+  const prodPackages = ['prisma', '@prisma/engines', 'esbuild', '@swc/core', 'msgpackr-extract'].map((n) => installed(root, n, n === 'msgpackr-extract' ? { gyp: true, optional: { '@msgpackr-extract/linux-x64': '1' } } : {}));
+  const { dockerfile } = renderPrebuiltDockerfile(options(root, { prodPackages }));
+  assert.match(dockerfile, /--frozen-lockfile && \\\n {2}pnpm rebuild msgpackr-extract --filter @t\/alpha-api\.\.\. --filter @t\/alpha-db-api\.\.\.\n/);
+  assert.doesNotMatch(dockerfile, /^ {2}pnpm rebuild[^\n]*(prisma|esbuild|swc|engines|not-in-closure)/);
+  assert.doesNotMatch(renderPrebuiltDockerfile(options(root, { prodPackages: prodPackages.slice(0, 4) })).dockerfile, /^ {2}pnpm rebuild/m);
+});
+
+test('the renderer refuses a node-gyp module with no optional prebuilt packages, naming it and the arm-runner path', () => {
+  const root = workspace();
+  fs.writeFileSync(path.join(root, 'pnpm-workspace.yaml'), "onlyBuiltDependencies:\n  - node-pty\n  - better-sqlite3\n");
+  const bare = [installed(root, 'node-pty', { gyp: true })];
+  assert.throws(() => renderPrebuiltDockerfile(options(root, { prodPackages: bare })), (e) => /node-pty needs node-gyp/.test(e.message) && /arm runner/.test(e.message) && /Refusing to render/.test(e.message));
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'write', ...options(root, { prodPackages: bare }) }), /node-pty needs node-gyp/);
+  assert.equal(fs.existsSync(path.join(root, 'infra/composed-process/Dockerfile')), false);
+  // The same package outside the prod closure, or with optional prebuilt packages, is fine.
+  assert.doesNotThrow(() => renderPrebuiltDockerfile(options(root, { prodPackages: [] })));
+  assert.doesNotThrow(() => renderPrebuiltDockerfile(options(root, { prodPackages: [installed(root, 'better-sqlite3', { gyp: true, optional: { prebuilt: '1' } })] })));
+});
+
+test('the deps stage is offline: --network=none on every pnpm and corepack RUN, no cache mounts, packed pnpm, scratch contexts', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  assert.match(dockerfile, /^FROM scratch AS xema-pnpm\nFROM scratch AS xema-pnpm-store\n/m);
+  const deps = dockerfile.split('FROM base AS deps')[1].split('FROM deps AS assemble')[0];
+  const runs = deps.split(/^RUN /m).slice(1);
+  assert.equal(runs.length, 2);
+  for (const run of runs) assert.match(run, /^--network=none /);
+  assert.doesNotMatch(dockerfile, /type=cache|--prefer-offline|npx /);
+  assert.match(deps, /ENV COREPACK_ENABLE_NETWORK=0/);
+  assert.match(deps, /^ENV npm_config_store_dir=\/root\/\.pnpm-store$/m);
+  assert.match(deps, /corepack install -g \/xema-pnpm\/corepack\/pnpm\.tgz/);
+  assert.match(deps, /from=xema-pnpm-store,target=\/root\/\.pnpm-store,rw/);
+  assert.match(deps, /from=xema-pnpm,source=cache,target=\/root\/\.cache\/pnpm,rw/);
+  assert.match(deps, /needs --build-context xema-pnpm and xema-pnpm-store \(CI only\)/);
+});
+
+test('memberProdPackages reads the installed prod closure and refuses an empty one; depsCopyDirs inverts the rendered COPY lines', () => {
+  const root = workspace();
+  const a = installed(root, '@s/a');
+  const exec = () => `${root}/biomes/x\n${a.dir}\n${a.dir}\n/not/installed/node_modules/zzz\n`;
+  assert.deepEqual(memberProdPackages({ root, exec }), [{ name: '@s/a', dir: fs.realpathSync(a.dir) }]);
+  assert.throws(() => memberProdPackages({ root, exec: () => '' }), /run pnpm install/);
+  const { dockerfile } = renderPrebuiltDockerfile(options(root, { copy: ['tooling/dev', 'tooling/ci/'] }));
+  assert.deepEqual(depsCopyDirs(dockerfile), ['tooling/dev/', 'tooling/ci/']);
+  assert.deepEqual(depsCopyDirs(renderPrebuiltDockerfile(options(root, { copy: [] })).dockerfile), []);
+});

package/src/composed-image.mjs

@@ -44,7 +44,7 @@
 //            generated Prisma clients into a build-step directory, with this tool,
 //            for the `--prebuilt` Dockerfile (`composed-image-stage.mjs`). Each `--also`
 //            workspace package adds its closure's built outputs (no Prisma checks).
-//   pnpm-context <dir> (--subject <svc>… | --image-dir <composed>) [--copy <dir>]…
+//   pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)
 //            CI-runner only, after `pnpm install --frozen-lockfile`: build the offline `xema-pnpm`
 //            build context (corepack pnpm.tgz, warmed metadata cache, staged.json) for the
 //            prebuilt Dockerfiles (`composed-image-pnpm-context.mjs`). stdout is
@@ -319,7 +319,7 @@ const USAGE =
   'usage: xema-composed-image <command> [--root <dir>] [--image-dir <dir>]\n' +
   '  members --write|--check [--manifests <glob>]… [--canonical-dockerfile <path>] [--cross-repo-manifest <path>]\n' +
   '  filters [--also <pkg>]… | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each]\n' +
-  '  pnpm-context <dir> (--subject <svc>… | --image-dir <composed>) [--copy <dir>]…\n' +
+  '  pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)\n' +
   '  stage <dir> [--output <rel>]… [--also <pkg>]…   | sync-injected | prisma-check | migrate <member> [--root <dir>]\n' +
   '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG [TAG_ARGS_FILE])\n' +
   '  load-image <image>\n' +
@@ -416,7 +416,6 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
         dir: argument,
         subjects: options.subject,
         imageDir: options.subject === undefined ? options['image-dir'] : undefined,
-        copy: options.copy,
         log: (message) => process.stderr.write(`${message}\n`),
       });
       write(`XEMA_PNPM_CONTEXT=${result.context}\nXEMA_PNPM_STORE=${result.store}\n`);