@xemahq/repo-build-tooling 0.10.2 → 0.12.0

package/README.md

@@ -29,11 +29,11 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-readiness` | Runs the ordered checks between a source change and a push |
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
-| `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
 | `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 `--tooling-version`, `--copy`, `--cache-id` and `--build-source`. 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 `--tooling-version`, `--copy`, `--cache-id` and `--build-source`. `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--tooling-version`, `--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. 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.10.2",
+  "version": "0.12.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -39,9 +39,9 @@
     "./service-bootstrap": "./src/service-bootstrap.mjs"
   },
   "scripts": {
-    "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/ghcr-manifest.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/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs"
+    "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/ghcr-manifest.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/registry-fetch.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-stage.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:6e85c2039576c5febe254e42d36eef92248dd33a88a8f86416ff654ff36a2765"
+    "sourceDigest": "sha256:65f155b64c9951c7c47a7d2a2b9cf65e08615471f0d5c49097a18460cbed260d"
   }
 }

package/src/composed-image-dockerfile.mjs

@@ -23,7 +23,7 @@ const VERSION = /^\d+\.\d+\.\d+$/;
 const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
 const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
 const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
-const NODE_BASE =
+export const NODE_BASE =
   'mirror.gcr.io/library/node:22-bookworm-slim@sha256:d649c27dae7ba0137b3cef5dd75baa422c08dc3d9e3fc0c23dfb172dc3cc6436';
 
 function validate({ toolingVersion, copy, cacheId, buildSource }) {
@@ -55,10 +55,10 @@ export function renderComposedDockerfile({ toolingVersion, copy, cacheId, buildS
     .map((d) => `COPY ${d} ./${d}`)
     .join('\n');
   const store = `--mount=type=cache,id=pnpm-store-${cacheId},target=/root/.pnpm-store`;
-  const mount = usesToken ? '  --mount=type=secret,id=npm_token,required=true \\\\\n' : '';
-  const tokenEnv = usesToken ? 'NPM_TOKEN="$(cat /run/secrets/npm_token)" GH_PACKAGES_TOKEN="$NPM_TOKEN" \\\\\n  ' : '';
+  const mount = usesToken ? '  --mount=type=secret,id=npm_token,required=true \\\n' : '';
+  const tokenEnv = usesToken ? 'NPM_TOKEN="$(cat /run/secrets/npm_token)" GH_PACKAGES_TOKEN="$NPM_TOKEN" \\\n  ' : '';
   const tokenExport = usesToken
-    ? 'export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\\\\n  '
+    ? 'export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\\n  '
     : '';
   const metadata = `--mount=type=cache,id=pnpm-metadata-${cacheId},target=/root/.cache/pnpm`;
   return `# @generated by \`xema-composed-image dockerfile --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.

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

@@ -84,3 +84,9 @@ test('the token use is derived from .npmrc, deterministically', () => {
   fs.writeFileSync(path.join(root, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
   assert.throws(() => syncComposedDockerfile({ mode: 'check', root, ...OPTIONS }), /is stale/);
 });
+
+test('a token-using repository gets single-backslash line continuations (a doubled one is a parse error)', () => {
+  const text = renderComposedDockerfile({ ...OPTIONS, usesToken: true });
+  assert.match(text, /--mount=type=secret,id=npm_token,required=true \\\n/);
+  for (const line of text.split('\n')) assert.doesNotMatch(line, /\\\\\s*$/, `line ends with a doubled backslash: ${line}`);
+});

package/src/composed-image-fixture.test.mjs

@@ -0,0 +1,55 @@
+// Shared fixture for the prebuilt-image tests: a tiny workspace with two members
+// (one with a Prisma schema) and one non-member dependency.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function write(root, rel, content) {
+  fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+  fs.writeFileSync(path.join(root, rel), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+}
+
+export const MEMBERS = Object.freeze({ 'alpha/alpha-api': 'biomes/alpha/api/alpha-api', 'alpha/alpha-db-api': 'biomes/alpha/api/alpha-db-api' });
+export const CLOSURE = Object.freeze(['biomes/alpha/api/alpha-api', 'biomes/alpha/api/alpha-db-api', 'packages/sdks/lib-a']);
+
+export function workspace({ built = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-prebuilt-'));
+  write(root, 'biomes/alpha/xema-biome.json', {
+    xema: {
+      id: 'alpha',
+      components: [
+        { key: 'alpha-api', kind: 'service', scheduler: 'platform', artifact: { path: 'api/alpha-api' } },
+        { key: 'alpha-db-api', kind: 'service', scheduler: 'platform', artifact: { path: 'api/alpha-db-api' } },
+      ],
+    },
+  });
+  write(root, 'infra/composed-process/image-build-inputs.json', { workspacePackages: Object.values(MEMBERS) });
+  write(root, 'pnpm-workspace.yaml', "packages:\n  - 'biomes/*/api/*'\n\nonlyBuiltDependencies:\n  - 'esbuild'\n  # a note\n  - prisma\n\n  - \"@prisma/engines\" # trailing\nother: 1\n");
+  write(root, '.npmrc', 'registry=https://registry.npmjs.org/\n');
+  write(root, 'biomes/alpha/api/alpha-api/package.json', { name: '@t/alpha-api' });
+  write(root, 'biomes/alpha/api/alpha-db-api/package.json', { name: '@t/alpha-db-api' });
+  write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', 'datasource db {}\n');
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist'] });
+  if (built) {
+    write(root, 'biomes/alpha/api/alpha-api/dist/main.js', '// main\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/dist/main.js', '// main\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/index.js', '// client\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma', 'datasource db {}\n');
+    write(root, 'packages/sdks/lib-a/dist/index.js', '// lib\n');
+  }
+  return root;
+}
+
+/** An `exec` standing in for `pnpm ls -r --depth -1 --json …`. */
+export function fakePnpm(root, closure = CLOSURE) {
+  const calls = [];
+  const exec = (file, args, options) => {
+    calls.push({ file, args, options });
+    return JSON.stringify(closure.map((dir) => ({ name: dir, path: path.join(root, dir) })));
+  };
+  exec.calls = calls;
+  return exec;
+}
+
+/** A `prisma format` stand-in that leaves the schema as it is (already formatted). */
+export const formatNoop = () => ({ status: 0, stdout: '', stderr: '' });

package/src/composed-image-members.mjs

@@ -0,0 +1,108 @@
+// The member set a repository's committed declaration names, and the workspace closure
+// those members select. Shared by the build-time tool, the stage command and the
+// prebuilt Dockerfile renderer, so all of them see one answer.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, posix, relative } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+
+export const IMAGE_BUILD_INPUTS_FILE = 'image-build-inputs.json';
+
+/** The `<biomeId>/<componentKey>` of the one service whose artifact is `directory`. */
+function memberKey(root, directory) {
+  for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
+    const manifestPath = join(root, dir, 'xema-biome.json');
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const matches = (manifest.xema?.components ?? []).filter(
+      (component) =>
+        component.kind === 'service' &&
+        typeof component.artifact?.path === 'string' &&
+        posix.normalize(posix.join(dir, component.artifact.path)) === directory,
+    );
+    if (matches.length !== 1) {
+      throw new Error(`${dir}/xema-biome.json declares ${matches.length} service(s) at ${directory}, not exactly one`);
+    }
+    return `${manifest.xema.id}/${matches[0].key}`;
+  }
+  throw new Error(`no biome manifest above ${directory}`);
+}
+
+/** `[key, directory]` for every member the committed declaration names. */
+export function readMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const inputs = join(root, imageDir, IMAGE_BUILD_INPUTS_FILE);
+  const directories = JSON.parse(readFileSync(inputs, 'utf8')).workspacePackages ?? [];
+  if (directories.length === 0) throw new Error(`${inputs} declares no workspacePackages`);
+  return directories.map((directory) => [memberKey(root, directory), directory]);
+}
+
+function packageName(root, directory) {
+  const manifest = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8'));
+  if (typeof manifest.name !== 'string') throw new Error(`${directory}/package.json has no name`);
+  return manifest.name;
+}
+
+/**
+ * The pnpm `--filter <package>...` arguments covering every member's closure, then
+ * each `also` package's (a workspace package name); a name a member already
+ * selected is listed once.
+ */
+export function memberFilters(options = {}) {
+  const root = options.root ?? process.cwd();
+  const names = readMembers(options).map(([, directory]) => packageName(root, directory));
+  return [...new Set([...names, ...(options.also ?? [])])].map((name) => `--filter ${name}...`);
+}
+
+
+/** The biome manifest (`xema-biome.json`) above every member, repository-relative and sorted: what `index` reads to name a member. */
+export function memberManifests({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const manifests = new Set();
+  for (const [, directory] of readMembers({ root, imageDir })) {
+    for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
+      if (existsSync(join(root, dir, 'xema-biome.json'))) {
+        manifests.add(posix.join(dir, 'xema-biome.json'));
+        break;
+      }
+    }
+  }
+  return [...manifests].sort();
+}
+
+const defaultExec = (file, args, { cwd }) => execFileSync(file, args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+
+function parseListing(listing) {
+  let packages;
+  try {
+    packages = JSON.parse(listing);
+  } catch (error) {
+    throw new Error(`pnpm ls did not print JSON: ${error.message}`);
+  }
+  if (!Array.isArray(packages)) throw new Error('pnpm ls did not print a JSON array');
+  return packages;
+}
+
+/**
+ * The workspace packages the members' filters select (the members and everything
+ * they depend on inside the workspace): repository-relative directories, sorted.
+ * `exec(file, args, { cwd })` returns stdout; injectable for tests.
+ */
+export function memberClosure({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec = defaultExec, also = [] } = {}) {
+  for (const name of also) {
+    const found = parseListing(exec('pnpm', ['ls', '-r', '--depth', '-1', '--json', '--filter', name], { cwd: root }));
+    if (!found.some((pkg) => pkg?.name === name)) throw new Error(`--also ${name}: no workspace package has that name`);
+  }
+  const words = memberFilters({ root, imageDir, also }).flatMap((filter) => filter.split(' '));
+  const packages = parseListing(exec('pnpm', ['ls', '-r', '--depth', '-1', '--json', ...words], { cwd: root }));
+  if (packages.length === 0) throw new Error('pnpm ls selected no workspace package');
+  const real = realpathSync(root);
+  const directories = new Set();
+  for (const pkg of packages) {
+    if (typeof pkg?.path !== 'string') throw new Error('pnpm ls listed a package with no path');
+    let rel = relative(root, pkg.path);
+    if (rel.startsWith('..')) rel = relative(real, pkg.path);
+    if (rel.startsWith('..')) throw new Error(`pnpm ls listed ${pkg.path}, outside ${root}`);
+    if (rel !== '') directories.add(rel.split('\\').join('/'));
+  }
+  return [...directories].sort();
+}

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

@@ -0,0 +1,220 @@
+// `xema-composed-image dockerfile --prebuilt --write|--check`: renders
+// `<image-dir>/Dockerfile` AND `<image-dir>/Dockerfile.dockerignore` for the image that
+// 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 { dirname, join, posix } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { NODE_BASE, npmrcUsesToken } from './composed-image-dockerfile.mjs';
+import { memberClosure, memberFilters, memberManifests } from './composed-image-members.mjs';
+
+export const DEFAULT_STAGE_DIR = '.xema-stage';
+const VERSION = /^\d+\.\d+\.\d+$/;
+const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
+const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
+const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+
+function validate({ toolingVersion, copy, cacheId, buildSource, stageDir }) {
+  if (!VERSION.test(toolingVersion ?? '')) throw new Error(`--tooling-version must be an exact x.y.z version, got "${toolingVersion}"`);
+  for (const directory of [...(copy ?? []), stageDir]) {
+    if (!DIRECTORY.test(directory) || directory.startsWith('/') || directory.split('/').includes('..')) {
+      throw new Error(`"${directory}" is not a repository-relative directory`);
+    }
+  }
+  if (!CACHE_ID.test(cacheId ?? '')) throw new Error(`--cache-id must be lowercase [a-z0-9-], got "${cacheId}"`);
+  if (!REPOSITORY.test(buildSource ?? '')) throw new Error(`--build-source must name a repository, got "${buildSource}"`);
+}
+
+/** The ignore file: the build context carries sources, never local build output, except the staged outputs. */
+export function renderPrebuiltDockerignore({ stageDir = DEFAULT_STAGE_DIR } = {}) {
+  return `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` — DO NOT EDIT.
+# Local build output stays out of the context; the staged outputs carry dist and node_modules/.prisma paths, so they are re-included LAST.
+.git
+**/node_modules
+**/dist
+**/.turbo
+**/coverage
+**/*.tsbuildinfo
+**/*.log
+!${stageDir}/**
+`;
+}
+
+/** The `onlyBuiltDependencies:` items of a `pnpm-workspace.yaml` text (block list; comments skipped; ends at the next top-level key). */
+export function onlyBuiltDependencies(workspaceYaml) {
+  const names = [];
+  let inList = false;
+  for (const line of workspaceYaml.split('\n')) {
+    if (!inList) {
+      inList = /^onlyBuiltDependencies:\s*(#.*)?$/.test(line);
+      continue;
+    }
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    if (/^\S/.test(line)) break;
+    const item = /^\s+-\s+(?:'([^']*)'|"([^"]*)"|([^\s#]+))\s*(?:#.*)?$/.exec(line);
+    if (item === null) throw new Error(`pnpm-workspace.yaml: cannot read onlyBuiltDependencies item "${line.trim()}"`);
+    names.push(item[1] ?? item[2] ?? item[3]);
+  }
+  for (const name of names) {
+    if (!/^[@A-Za-z0-9._/-]+$/.test(name)) throw new Error(`pnpm-workspace.yaml: onlyBuiltDependencies "${name}" is not a package name`);
+  }
+  return names;
+}
+
+const parts = (sources) => sources.map((source) => `    ${source} \\`).join('\n');
+
+/** The prebuilt Dockerfile text. The closure and the members' literal filters are derived from `root` (`memberClosure`); `exec` is injectable for tests. */
+export function renderPrebuiltDockerfile({
+  root = process.cwd(),
+  imageDir = COMPOSED_IMAGE_DIR,
+  toolingVersion,
+  copy = [],
+  cacheId,
+  buildSource,
+  usesToken,
+  stageDir = DEFAULT_STAGE_DIR,
+  exec,
+}) {
+  if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
+  validate({ toolingVersion, copy, cacheId, buildSource, stageDir });
+  const workspaceFile = join(root, 'pnpm-workspace.yaml');
+  const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
+  if (built.length === 0) {
+    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 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}/src/composed-image.mjs`;
+  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 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 manifestSources = closure.map((directory) => `${directory}/package.json`);
+  const assembleSources = [...closure, ...manifests];
+  const imageCopy = posix.normalize(`${imageDir}/`);
+  const text = `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
+# Re-render with the same options; \`--check\` refuses a stale file (and a stale Dockerfile.dockerignore).
+#
+# The COMPOSED-PROCESS image of this repository, ASSEMBLED from build outputs: ONE image
+# per build (repository at commit), every member of \`image-build-inputs.json\` in ONE module
+# graph behind the SDK's \`xema-composed-process\` host. Docker compiles nothing. The CI
+# runner ran \`turbo run build prisma:generate\` for the members' closures and
+# \`xema-composed-image stage ${stageDir}\` gathered the outputs into the build-step
+# directory \`${stageDir}/\` (\`out/\` = dist and generated Prisma clients, pure JS/wasm;
+# \`tool/\` = this tool, bind-mounted into the steps below and never copied into a layer).
+#
+# 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.
+#   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.
+#   (final)   \`/monorepo\` of assemble, shipped as THREE layers so a commit that changes only
+#             members' code re-pushes only the layers that changed (see the final stage).
+#             Nothing of the tool ships.
+#
+# The \`--filter <package>...\` words below are LITERAL: the content hash of this image reads
+# them to narrow the lockfile to the members' closures.
+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/* && \\
+    pnpm config set store-dir /root/.pnpm-store
+
+FROM base AS deps
+WORKDIR /monorepo
+ENV CI=true
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+${copies === '' ? '' : `${copies}\n`}COPY --parents \\
+${parts(manifestSources)}
+    ./
+RUN ${store} \\
+  ${metadata} \\
+${secret}  ${toolMount} \\
+  ${tokenExport}INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false" && \\
+  cp pnpm-lock.yaml /tmp/pnpm-lock.committed.yaml && \\
+  pnpm install --lockfile-only --prefer-offline \${INJECT} ${filters} && \\
+  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}
+
+FROM deps AS assemble
+COPY --parents \\
+${parts(assembleSources)}
+    ./
+COPY ${imageCopy} ./${imageCopy}
+COPY ${stageDir}/out/ ./
+ARG BUILD_SHA
+RUN ${toolMount} \\
+  T="node ${node}" && \\
+  $T sync-injected${dirFlag} && $T prisma-check${dirFlag} && \\
+  : "\${BUILD_SHA:?BUILD_SHA build-arg is required}" && $T index "\${BUILD_SHA}" --build-source ${buildSource}${dirFlag} && \\
+  cp ${toolDir}/src/composed-migrate.mjs /monorepo/xema-composed-migrate.mjs
+
+# Every member's module graph loads here, ALONE (one process each), through the host's own
+# entry reader, as the user and NODE_ENV the image runs with, or the image is never pushed.
+USER node
+RUN ${toolMount} \\
+  NODE_ENV=production node ${node} load --each${dirFlag}
+
+# The final stage is layered by how often each part changes, so a registry and a node
+# already holding the stable layers fetch only the rest. The three copies overlay to
+# exactly assemble's /monorepo (proven by a tree diff of both images).
+#   1 deps       root manifests, the external .pnpm store, and the injected stubs that hold
+#                only package.json. Stable while the lockfile and the closure's package.json
+#                files are unchanged.
+#   2 assemble   members, dist, Prisma clients, member index, migrate script: everything
+#                but the .pnpm store, whose packages layer 1 already carries.
+#   3 injected   the workspace copies \`node_modules/.pnpm/*@file+*\`: \`sync-injected\` fills
+#                them from the members' files, so they change with every commit. \`--parents\`
+#                keeps their paths under /.
+FROM base
+WORKDIR /monorepo
+COPY --from=deps /monorepo /monorepo
+COPY --from=assemble --exclude=node_modules/.pnpm /monorepo /monorepo
+COPY --from=assemble --parents /monorepo/node_modules/.pnpm/*@file+* /
+ENV NODE_ENV=production
+# Set by the IMAGE, never by a deployment (kernel \`COMPOSED_PROCESS_ENV.MemberIndex\`).
+ENV XEMA_COMPOSED_MEMBER_INDEX=/monorepo/xema-composed-member-index.json
+USER node
+CMD ["node", "/monorepo/xema-composed-process"]
+`;
+  return { dockerfile: text, dockerignore: renderPrebuiltDockerignore({ stageDir }), closure };
+}
+
+/** `--write` writes both files; `--check` throws when either differs. */
+export function syncPrebuiltDockerfile({ mode, root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec, ...options }) {
+  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 files = [
+    [posix.join(imageDir, 'Dockerfile'), dockerfile],
+    [posix.join(imageDir, 'Dockerfile.dockerignore'), dockerignore],
+  ];
+  const stale = [];
+  for (const [relativeTarget, rendered] of files) {
+    const target = join(root, relativeTarget);
+    if (mode === 'write') {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, rendered);
+    } else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) stale.push(relativeTarget);
+  }
+  if (stale.length > 0) {
+    throw new Error(`${stale.join(' and ')} ${stale.length > 1 ? 'are' : 'is'} stale. Run: xema-composed-image dockerfile --prebuilt --write (with the same options)`);
+  }
+  return files.map(([relativeTarget]) => relativeTarget);
+}

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

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+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 { parseArguments } from './composed-image.mjs';
+import { CLOSURE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
+
+function options(root, extra = {}) {
+  return { root, toolingVersion: '0.11.0', copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', usesToken: true, exec: fakePnpm(root), ...extra };
+}
+
+test('the closure comes from pnpm ls with the members filters, and the filters are literal per member', () => {
+  const root = workspace();
+  const exec = fakePnpm(root);
+  const { dockerfile, closure } = renderPrebuiltDockerfile(options(root, { exec }));
+  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']) {
+    assert.ok(dockerfile.includes(`${verb} ${filters}`), verb);
+  }
+  assert.doesNotMatch(renderPrebuiltDockerfile(options(root, { usesToken: false })).dockerfile, /\$\(cat/);
+});
+
+test('one COPY --parents per kind: manifests in deps, package dirs (and biome manifests) in assemble', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  assert.equal(dockerfile.match(/^COPY --parents/gm).length, 2);
+  const [deps, assemble] = dockerfile.split('FROM deps AS assemble');
+  assert.match(deps, /COPY tooling\/dev\/ \.\/tooling\/dev\/\nCOPY --parents \\\n {4}biomes\/alpha\/api\/alpha-api\/package\.json \\\n {4}biomes\/alpha\/api\/alpha-db-api\/package\.json \\\n {4}packages\/sdks\/lib-a\/package\.json \\\n {4}\.\/\n/);
+  assert.match(assemble, /COPY --parents \\\n {4}biomes\/alpha\/api\/alpha-api \\\n {4}biomes\/alpha\/api\/alpha-db-api \\\n {4}packages\/sdks\/lib-a \\\n {4}biomes\/alpha\/xema-biome\.json \\\n {4}\.\/\n/);
+  assert.match(assemble, /COPY infra\/composed-process\/ \.\/infra\/composed-process\/\nCOPY \.xema-stage\/out\/ \.\/\n/);
+});
+
+test('the tool is only bind-mounted, and the final stage carries nothing of it', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  assert.equal(dockerfile.match(/--mount=type=bind,source=\.xema-stage\/tool,target=\/opt\/xema-composed-image/g).length, 3);
+  assert.doesNotMatch(dockerfile, /\bnpm install|COPY \.xema-stage\/tool/);
+  const final = dockerfile.split('\nFROM base\n')[1];
+  assert.doesNotMatch(final, /xema-composed-image|repo-build-tooling|npm install|\/opt\//);
+  assert.doesNotMatch(final, /COPY --from=assemble \/monorepo \/monorepo/);
+  assert.match(dockerfile, /USER node\nRUN --mount=\S+ \\\n {2}NODE_ENV=production node \/opt\/xema-composed-image\/src\/composed-image\.mjs load --each\n/);
+  assert.match(dockerfile, /cp \/opt\/xema-composed-image\/src\/composed-migrate\.mjs \/monorepo\/xema-composed-migrate\.mjs/);
+});
+
+test('the secret is mounted only for a tokened .npmrc; a custom image dir and stage dir are threaded', () => {
+  const root = workspace();
+  assert.match(renderPrebuiltDockerfile(options(root)).dockerfile, /type=secret,id=npm_token,required=true \\\n {2}--mount=type=bind/);
+  const without = renderPrebuiltDockerfile(options(root, { usesToken: false })).dockerfile;
+  assert.doesNotMatch(without, /npm_token|NPM_TOKEN|type=secret/);
+  const custom = renderPrebuiltDockerfile(options(root, { stageDir: 'build/stage' })).dockerfile;
+  assert.match(custom, /source=build\/stage\/tool/);
+  assert.match(custom, /COPY build\/stage\/out\/ \.\/\n/);
+  assert.throws(() => renderPrebuiltDockerfile(options(root, { stageDir: '../x' })), /repository-relative/);
+  assert.throws(() => renderPrebuiltDockerfile(options(root, { usesToken: undefined })), /usesToken/);
+});
+
+test('the dockerignore re-includes the stage dir LAST', () => {
+  const lines = renderPrebuiltDockerignore({ stageDir: '.xema-stage' }).trim().split('\n');
+  assert.equal(lines.at(-1), '!.xema-stage/**');
+  for (const pattern of ['.git', '**/node_modules', '**/dist', '**/.turbo', '**/coverage', '**/*.tsbuildinfo', '**/*.log']) assert.ok(lines.includes(pattern), pattern);
+});
+
+test('--write writes both files; --check refuses either stale, and a closure change', () => {
+  const root = workspace();
+  const targets = syncPrebuiltDockerfile({ mode: 'write', ...options(root) });
+  assert.deepEqual(targets, ['infra/composed-process/Dockerfile', 'infra/composed-process/Dockerfile.dockerignore']);
+  syncPrebuiltDockerfile({ mode: 'check', ...options(root) });
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root, { exec: fakePnpm(root, [...CLOSURE, 'packages/sdks/lib-b']) }) }), /Dockerfile is stale/);
+  fs.appendFileSync(path.join(root, 'infra/composed-process/Dockerfile.dockerignore'), 'x\n');
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root) }), /Dockerfile\.dockerignore is stale/);
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'sideways', ...options(root) }), /write or check/);
+});
+
+test('the flags parse: --prebuilt and --each are booleans, --output repeats', () => {
+  const { options: parsed } = parseArguments(['dockerfile', '--prebuilt', '--write', '--stage-dir', 's']);
+  assert.equal(parsed.prebuilt, true);
+  assert.equal(parsed['stage-dir'], 's');
+  const stage = parseArguments(['stage', 'd', '--output', 'dist', '--output', 'build', '--each']);
+  assert.deepEqual(stage.options.output, ['dist', 'build']);
+  assert.equal(stage.options.each, true);
+  assert.equal(stage.argument, 'd');
+});
+
+test('the rebuild names come from onlyBuiltDependencies: comments skipped, empty refused, a change goes stale', () => {
+  assert.deepEqual(onlyBuiltDependencies("a: 1\nonlyBuiltDependencies:\n  # c\n  - '@x/y'\n  - z # t\n\n  # more\n  - \"w\"\nnext:\n  - nope\n"), ['@x/y', 'z', 'w']);
+  assert.deepEqual(onlyBuiltDependencies('packages: []\n'), []);
+  const root = workspace();
+  assert.throws(() => onlyBuiltDependencies('onlyBuiltDependencies:\n  - a b c d\n  - "bad name"\n'), /cannot read|not a package name/);
+  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/);
+  fs.writeFileSync(file, 'packages: []\n');
+  assert.throws(() => renderPrebuiltDockerfile(options(root)), /no onlyBuiltDependencies/);
+});
+
+test('a token-using repository gets single-backslash line continuations (a doubled one is a parse error)', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace(), { usesToken: true }));
+  assert.match(dockerfile, /--mount=type=secret,id=npm_token,required=true \\\n/);
+  for (const line of dockerfile.split('\n')) assert.doesNotMatch(line, /\\\\\s*$/, `line ends with a doubled backslash: ${line}`);
+});
+
+test('the final stage is layered: deps, then assemble without the .pnpm store, then the injected copies', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  const final = dockerfile.split('\nFROM base\n')[1];
+  const copies = final.split('\n').filter((line) => line.startsWith('COPY '));
+  assert.deepEqual(copies, [
+    'COPY --from=deps /monorepo /monorepo',
+    'COPY --from=assemble --exclude=node_modules/.pnpm /monorepo /monorepo',
+    'COPY --from=assemble --parents /monorepo/node_modules/.pnpm/*@file+* /',
+  ]);
+  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$/);
+});