@xemahq/repo-build-tooling 0.8.2 → 0.9.0

package/README.md

@@ -64,6 +64,49 @@ shape and no clean literal, and that a residual leak fails the run. This step's
 failure mode is silence, so "0 leaks" and "0 files read" must never be
 indistinguishable.
 
+### `xema-composed-image <command>`
+
+The build-time half of a repository's composed-process image (the runtime half,
+the `xema-composed-process` host, is `@xemahq/xema-service-nest`'s). One image per
+build carries every composable platform service of the repository at one commit.
+
+- `members --write|--check` derives that set from the tracked biome manifests and
+  writes or verifies `infra/composed-process/image-build-inputs.json`. A member is a
+  `kind: service` with `scheduler: platform`; workers, jobs and runtime-scheduled
+  services never are. A service is left out, with its reason printed, when its
+  `src/main.ts` is not one top-level `void bootstrapXemaService(…)`, it has its own
+  `Dockerfile`, it bakes cross-repository inputs, or the canonical Dockerfile
+  installs a toolchain for it. Options say where the repository keeps those facts:
+  `--manifests <glob>` (repeatable, default `**/xema-biome.json`),
+  `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>` (both optional).
+- Inside the image build: `filters` and `dirs` name the members' closures,
+  `pins <committed-lockfile>` refuses a re-resolution that moves a registry pin,
+  `index <commit> --build-source <repo>` writes the member index the host reads
+  (graded by `@xemahq/contracts/process-topology`, resolved from the members) and
+  links the host bin, and `load` evaluates every member's entry through the host's
+  `readServiceEntry`. `--build-source` is the `repo` the repository's subjects carry
+  in an edition's image lock.
+
+- `coordinate --image-name <name>` is the image's release coordinate: the content tag
+  and whether GHCR already serves it (only 200 and 404 are answers). The tag is computed
+  ONLY by the repository's own `@xemahq/distribution-source-hash` (`xema-compute-image-tag`,
+  resolved from the repository root); the command refuses when it is not installed, and never
+  hashes anything itself. Environment: `SHA`, `REGISTRY`, `REGISTRY_ORG`, `REGISTRY_USER`,
+  `REGISTRY_TOKEN`, optional `TAG_ARGS_FILE`, `GITHUB_OUTPUT`. Outputs `image`, `content_tag`,
+  `exists`, `entry`. The registry check is also exported as `./ghcr-manifest`
+  (`ghcrManifestExists`, `acquireGhcrPullToken`).
+- `smoke-refusal <image> [--member <biomeId>/<componentKey>]x2` boots the pushed image
+  with two members on one port and fails unless the host refuses at the declaration, names
+  the collision, and constructs no member. Needs only `docker`.
+- `dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>`
+  renders `infra/composed-process/Dockerfile` from one template. The builder stage installs
+  this tool at the EXACT version (so the hashed image directory moves when the tool does),
+  runs every step above, and runs `load` last as `node` with `NODE_ENV=production`. Nothing here
+  ships in an image: the final stage copies `/monorepo` only.
+
+Every step refuses rather than skips. The tool has no dependencies: the host and
+the kernel schema are resolved from the members being built.
+
 ## Scope boundary
 
 Dev-time tooling that **more than one repository** runs. Two rules keep it from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.8.2",
+  "version": "0.9.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)",
@@ -23,17 +23,23 @@
   "bin": {
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
+    "xema-composed-image": "src/composed-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
   },
   "exports": {
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
+    "./composed-image": "./src/composed-image.mjs",
+    "./ghcr-manifest": "./src/ghcr-manifest.mjs",
     "./package.json": "./package.json",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.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"
+    "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/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs"
+  },
+  "xemaRelease": {
+    "sourceDigest": "sha256:89bea8bf6a2415cef4ea2dd5f199135d3ee71cba50d1c9eb93cc92f1b9eb1984"
   }
-}
+}

package/src/composed-image-coordinate.mjs

@@ -0,0 +1,112 @@
+// `xema-composed-image coordinate --image-name <name>`: the release coordinate of a
+// repository's composed-process image, and whether the registry already serves it.
+//
+// The tag is the ORDINARY build-input key, `xema-compute-image-tag` over the
+// image directory, exactly as for any other image subject, so the distribution
+// resolver (which hashes the `composed-process` subject at the image directory with
+// the same package) computes the same value. The hash is NEVER computed here: the
+// bin is resolved from the CONSUMER's own `@xemahq/distribution-source-hash`
+// install, and the coordinate refuses when the repository does not carry it.
+//
+// Presence is the same question a service matrix asks (a HEAD on the content tag),
+// with the same posture: only 200 and 404 are answers.
+//
+// Environment: SHA (40-hex commit), REGISTRY, REGISTRY_ORG, REGISTRY_USER,
+// REGISTRY_TOKEN, optional TAG_ARGS_FILE (one tag argument per line, e.g. the
+// repository's vendored cross-repository inputs; when set it must exist),
+// optional GITHUB_OUTPUT.
+
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+import { ghcrManifestExists } from './ghcr-manifest.mjs';
+
+export const HASH_PACKAGE = '@xemahq/distribution-source-hash';
+export const HASH_BIN = 'xema-compute-image-tag';
+
+function required(env, name) {
+  const value = env[name];
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`${name} is required`);
+  return value;
+}
+
+/** The consumer's own `xema-compute-image-tag` bin path; refuses when it is not installed there. */
+export function resolveHashBin(root) {
+  let manifestPath;
+  try {
+    manifestPath = createRequire(join(root, 'package.json')).resolve(`${HASH_PACKAGE}/package.json`);
+  } catch (error) {
+    if (error?.code === 'MODULE_NOT_FOUND' || error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      throw new Error(
+        `${HASH_PACKAGE} is not installed at ${root} — the content tag is computed only by its ${HASH_BIN} bin; ` +
+          'add it as a devDependency of this repository and install',
+      );
+    }
+    throw error;
+  }
+  const bin = JSON.parse(readFileSync(manifestPath, 'utf8')).bin?.[HASH_BIN];
+  if (typeof bin !== 'string') throw new Error(`${HASH_PACKAGE} at ${manifestPath} ships no "${HASH_BIN}" bin`);
+  return join(dirname(manifestPath), bin);
+}
+
+/** `{ image, content_tag, exists, entry }` for the composed image of the repository at `root`. */
+export async function composedCoordinate({ root, imageName, imageDir, env = process.env, fetchImpl = fetch, hash }) {
+  if (typeof imageName !== 'string' || imageName.length === 0) throw new Error('coordinate needs --image-name');
+  const sha = required(env, 'SHA');
+  if (!/^[a-f0-9]{40}$/.test(sha)) throw new Error(`SHA '${sha}' is not an exact 40-hex commit`);
+  const registry = required(env, 'REGISTRY');
+  const org = required(env, 'REGISTRY_ORG');
+  const tagArgsFile = env.TAG_ARGS_FILE;
+  let tagArgs = [];
+  if (tagArgsFile !== undefined && tagArgsFile.length > 0) {
+    if (!existsSync(tagArgsFile)) throw new Error(`TAG_ARGS_FILE ${tagArgsFile} is absent`);
+    tagArgs = readFileSync(tagArgsFile, 'utf8').split('\n').filter(Boolean);
+  }
+
+  const hashArguments = ['--service', imageName, '--path', imageDir, '--commit', sha, '--repo-dir', root, ...tagArgs];
+  const contentHash = (
+    hash ??
+    ((args) =>
+      execFileSync(process.execPath, [resolveHashBin(root), ...args], {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+      }))
+  )(hashArguments).trim();
+  if (!/^[a-f0-9]{64}$/.test(contentHash)) {
+    throw new Error(`${HASH_BIN} emitted '${contentHash}', not a sha256 hex digest`);
+  }
+
+  const repository = `${org}/${imageName}`;
+  const exists = await ghcrManifestExists({
+    registry,
+    repository,
+    contentHash,
+    user: required(env, 'REGISTRY_USER'),
+    token: required(env, 'REGISTRY_TOKEN'),
+    fetchImpl,
+  });
+  const image = `${registry}/${repository}`;
+  // The same entry shape a service matrix entry has, so the arm64 supplement
+  // lane reads this image's receipt exactly as it reads a service's.
+  const entry = {
+    service: imageName,
+    path: imageDir,
+    workspace: false,
+    runtimeImage: false,
+    imageRepository: image,
+    contentHash,
+  };
+  return { image, content_tag: contentHash, exists: String(exists), entry: JSON.stringify(entry) };
+}
+
+/** Print the outputs, append them to GITHUB_OUTPUT when set. */
+export function emitCoordinate(outputs, { env = process.env, log = console.log } = {}) {
+  for (const [key, value] of Object.entries(outputs)) {
+    if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `${key}=${value}\n`);
+    log(`${key}=${value}`);
+  }
+  log(`${outputs.image}:${outputs.content_tag} ${outputs.exists === 'true' ? 'exists — skip' : 'is missing — build'}`);
+}

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

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { composedCoordinate, emitCoordinate, resolveHashBin } from './composed-image-coordinate.mjs';
+
+const SHA = 'c'.repeat(40);
+const HASH = 'd'.repeat(64);
+const ENV = { SHA, REGISTRY: 'ghcr.io', REGISTRY_ORG: 'xema-dev', REGISTRY_USER: 'runner', REGISTRY_TOKEN: 'secret' };
+
+function response(status, body) {
+  return { status, async json() { return body; } };
+}
+
+function registry(manifestStatus) {
+  const urls = [];
+  return {
+    urls,
+    fetchImpl: async (url) => {
+      urls.push(String(url));
+      return String(url).includes('/token') ? response(200, { token: 't' }) : response(manifestStatus, {});
+    },
+  };
+}
+
+/** A consumer root whose own install carries a stand-in `xema-compute-image-tag` that echoes its arguments into a file. */
+function consumer({ withHash = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-coordinate-'));
+  fs.writeFileSync(path.join(root, 'package.json'), '{"name":"consumer"}');
+  if (withHash) {
+    const pkg = path.join(root, 'node_modules/@xemahq/distribution-source-hash');
+    fs.mkdirSync(path.join(pkg, 'dist/bin'), { recursive: true });
+    fs.writeFileSync(
+      path.join(pkg, 'package.json'),
+      JSON.stringify({ name: '@xemahq/distribution-source-hash', version: '1.0.0', bin: { 'xema-compute-image-tag': 'dist/bin/compute-image-tag.js' } }),
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'dist/bin/compute-image-tag.js'),
+      `require('node:fs').writeFileSync(${JSON.stringify(path.join(root, 'args.json'))}, JSON.stringify(process.argv.slice(2)));\nconsole.log(${JSON.stringify(HASH)});\n`,
+    );
+  }
+  return root;
+}
+
+test('the hash comes from the consumer\'s own bin, called with the service, directory, commit and tag args', async () => {
+  const root = consumer();
+  const tagArgs = path.join(root, 'tag-args.txt');
+  fs.writeFileSync(tagArgs, '--vendored\nx=y@z:w\n');
+  const { fetchImpl, urls } = registry(404);
+  const out = await composedCoordinate({
+    root,
+    imageName: 'alpha-composed-process',
+    imageDir: 'infra/composed-process',
+    env: { ...ENV, TAG_ARGS_FILE: tagArgs },
+    fetchImpl,
+  });
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(root, 'args.json'), 'utf8')), [
+    '--service', 'alpha-composed-process', '--path', 'infra/composed-process', '--commit', SHA, '--repo-dir', root, '--vendored', 'x=y@z:w',
+  ]);
+  assert.equal(out.image, 'ghcr.io/xema-dev/alpha-composed-process');
+  assert.equal(out.content_tag, HASH);
+  assert.equal(out.exists, 'false');
+  assert.ok(urls[1].endsWith(`/v2/xema-dev/alpha-composed-process/manifests/${HASH}`));
+  assert.deepEqual(JSON.parse(out.entry), {
+    service: 'alpha-composed-process', path: 'infra/composed-process', workspace: false, runtimeImage: false,
+    imageRepository: 'ghcr.io/xema-dev/alpha-composed-process', contentHash: HASH,
+  });
+});
+
+test('a present manifest reports exists', async () => {
+  const out = await composedCoordinate({ root: consumer(), imageName: 'a', imageDir: 'd', env: ENV, fetchImpl: registry(200).fetchImpl });
+  assert.equal(out.exists, 'true');
+});
+
+test('a repository without the hash package is refused, never hashed another way', async () => {
+  await assert.rejects(
+    composedCoordinate({ root: consumer({ withHash: false }), imageName: 'a', imageDir: 'd', env: ENV, fetchImpl: registry(404).fetchImpl }),
+    /distribution-source-hash is not installed/,
+  );
+  assert.throws(() => resolveHashBin(consumer({ withHash: false })), /not installed/);
+});
+
+test('the inputs are checked: commit, registry settings, tag args file, digest shape', async () => {
+  const root = consumer();
+  const base = { root, imageName: 'a', imageDir: 'd', fetchImpl: registry(404).fetchImpl };
+  await assert.rejects(composedCoordinate({ ...base, env: { ...ENV, SHA: 'abc' } }), /40-hex/);
+  await assert.rejects(composedCoordinate({ ...base, env: { ...ENV, REGISTRY_ORG: '' } }), /REGISTRY_ORG is required/);
+  await assert.rejects(composedCoordinate({ ...base, env: { ...ENV, TAG_ARGS_FILE: path.join(root, 'nope') } }), /TAG_ARGS_FILE .* absent/);
+  await assert.rejects(composedCoordinate({ ...base, imageName: '', env: ENV }), /--image-name/);
+  await assert.rejects(composedCoordinate({ ...base, env: ENV, hash: () => 'not-a-digest' }), /not a sha256/);
+});
+
+test('an unusable registry answer fails the coordinate rather than reading as missing', async () => {
+  await assert.rejects(
+    composedCoordinate({ root: consumer(), imageName: 'a', imageDir: 'd', env: ENV, fetchImpl: registry(500).fetchImpl }),
+    /HTTP 500/,
+  );
+});
+
+test('emitCoordinate prints every output and appends them to GITHUB_OUTPUT', () => {
+  const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'xema-out-')), 'out');
+  const lines = [];
+  emitCoordinate({ image: 'i', content_tag: HASH, exists: 'false', entry: '{}' }, { env: { GITHUB_OUTPUT: file }, log: (l) => lines.push(l) });
+  assert.equal(fs.readFileSync(file, 'utf8'), `image=i\ncontent_tag=${HASH}\nexists=false\nentry={}\n`);
+  assert.match(lines.at(-1), /is missing — build/);
+});

package/src/composed-image-dockerfile.mjs

@@ -0,0 +1,181 @@
+// `xema-composed-image dockerfile --write|--check`: renders `<image-dir>/Dockerfile`,
+// the composed-process image of ANY producing repository, from one template.
+//
+// What differs per repository is a parameter, never a branch: the directories its
+// build context carries (`--copy`, repeatable), its pnpm cache id (`--cache-id`),
+// the repository its member subjects name in an edition's image lock
+// (`--build-source`) and the EXACT version of this tool the builder installs
+// (`--tooling-version`). The tool is pinned exactly so the image directory, which
+// the content tag hashes, changes whenever the tool does.
+//
+// NOTHING OF THE TOOL SHIPS: it is installed globally in the builder stage only,
+// and the final stage copies `/monorepo` alone. `load` runs at the end of the
+// builder as the `node` user with NODE_ENV=production, after the production
+// install, which is the user and environment the image runs with.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+
+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 =
+  'mirror.gcr.io/library/node:22-bookworm-slim@sha256:d649c27dae7ba0137b3cef5dd75baa422c08dc3d9e3fc0c23dfb172dc3cc6436';
+
+function validate({ toolingVersion, copy, cacheId, buildSource }) {
+  if (!VERSION.test(toolingVersion ?? '')) {
+    throw new Error(`--tooling-version must be an exact x.y.z version, got "${toolingVersion}"`);
+  }
+  if (!Array.isArray(copy) || copy.length === 0) throw new Error('--copy needs at least one directory');
+  for (const directory of copy) {
+    if (!DIRECTORY.test(directory) || directory.startsWith('/') || directory.split('/').includes('..')) {
+      throw new Error(`--copy "${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 Dockerfile text. `imageDir` is where the repository keeps the image (and so where this is written). */
+export function renderComposedDockerfile({ toolingVersion, copy, cacheId, buildSource, imageDir = COMPOSED_IMAGE_DIR }) {
+  validate({ toolingVersion, copy, cacheId, buildSource });
+  const dirFlag = imageDir === COMPOSED_IMAGE_DIR ? '' : ` --image-dir ${imageDir}`;
+  const tool = (command) => `xema-composed-image ${command}${dirFlag}`;
+  const copies = [...new Set([...copy.map((d) => posix.normalize(`${d}/`)), posix.normalize(`${imageDir}/`)])]
+    .map((d) => `COPY ${d} ./${d}`)
+    .join('\n');
+  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`;
+  return `# @generated by \`xema-composed-image dockerfile --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
+# Re-render with the same options; \`--check\` refuses a stale file.
+#
+# The COMPOSED-PROCESS image of this repository: ONE image per build (repository at
+# commit), carrying every member listed in \`image-build-inputs.json\` in ONE
+# module graph, behind the SDK's \`xema-composed-process\` host.
+#
+# It is never per grouping. Which members share a process is the DEPLOYMENT's
+# declaration (\`XEMA_PROCESS_*\`), read at boot; the image owns only what it
+# contains — the baked member index — so regrouping never builds an image.
+#
+# Built at the ordinary build-input key \`xema-compute-image-tag\` computes for this
+# directory, so the tool pinned below is part of the key.
+#
+# Layout: the workspace stays a workspace. Every member keeps its own
+# directory, its own \`node_modules\` and its own Prisma client, all resolving
+# through ONE \`.pnpm\` store, so an identity package (\`@nestjs/core\`, …) has one
+# physical copy — the host refuses at boot, and \`xema-composed-image index\`
+# refuses at build, any member that resolves a second one.
+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 builder
+WORKDIR /monorepo
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ && rm -rf /var/lib/apt/lists/*
+ENV CI=true
+ARG BUILD_SHA
+
+# The build tool, at an EXACT version, in the builder only: the final stage
+# copies /monorepo, so nothing of it ships.
+RUN npm install --global --ignore-scripts @xemahq/repo-build-tooling@${toolingVersion}
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc tsconfig.base.json ./
+${copies}
+
+RUN ${tool('filters')} > /tmp/member-filters && \\
+    test -s /tmp/member-filters
+
+RUN ${store} \\
+  --mount=type=secret,id=npm_token,required=true \\
+  NPM_TOKEN="$(cat /run/secrets/npm_token)" GH_PACKAGES_TOKEN="$NPM_TOKEN" \\
+  pnpm fetch $(cat /tmp/member-filters) --frozen-lockfile
+RUN ${store} \\
+  --mount=type=secret,id=npm_token,required=true \\
+  NPM_TOKEN="$(cat /run/secrets/npm_token)" GH_PACKAGES_TOKEN="$NPM_TOKEN" \\
+  pnpm install --prefer-offline $(cat /tmp/member-filters) --frozen-lockfile
+
+# Every member that owns a Prisma schema generates its OWN client into its own
+# \`node_modules/.prisma/<service>\` (the schema's \`output\`), before it builds.
+RUN for schema in $(${tool('dirs')}); do \\
+      if [ -f "\${schema}/prisma/schema.prisma" ]; then \\
+        echo "prisma generate: \${schema}" && pnpm --dir "\${schema}" exec prisma generate || exit 1; \\
+      fi; \\
+    done
+
+RUN --mount=type=secret,id=npm_token,required=true \\
+  NPM_TOKEN="$(cat /run/secrets/npm_token)" GH_PACKAGES_TOKEN="$NPM_TOKEN" \\
+  pnpm $(cat /tmp/member-filters) run build
+
+# Production install, with the members' WORKSPACE packages INJECTED — the same
+# resolution the per-service image gets from \`pnpm deploy\` (legacy deploy
+# injects every workspace dependency). A workspace SDK that lists a package
+# only as a PEER (\`@nestjs/common\`, \`ioredis\`, …) has it in the linked
+# workspace solely as its own devDependency, which \`--prod\` removes: the members
+# that import it then fail \`Cannot find module\`. Injected, each workspace
+# package is a copy (its built \`files\`) inside the store whose peers are the
+# DEPENDENT member's own copies — one module graph, peers resolved.
+#
+# The committed lockfile links workspace packages, so the injected one is
+# re-resolved here from it (\`--lockfile-only\`; \`dedupe-injected-deps=false\`, or
+# pnpm folds an injected package back to the link that loses its peers). The
+# re-resolution may only add the injected workspace entries: \`pins\` refuses it
+# if any registry package's version moved off the committed lockfile. Then the
+# frozen install of exactly that lockfile, and the Prisma clients the prune may
+# have removed (\`prisma\` is a production dependency of every member with a schema).
+#
+# \`--ignore-scripts\`: an injected workspace package runs its own lifecycle
+# (\`prepublishOnly: build\` on the clients), which cannot run in a production
+# install and has nothing to do — its \`dist\` was built above and is what is
+# injected. Every registry package keeps the virtual-store directory the first
+# install built, and the members' \`postinstall\` is the Prisma loop below.
+RUN ${store} \\
+  ${metadata} \\
+  --mount=type=secret,id=npm_token,required=true \\
+  export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\
+  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} $(cat /tmp/member-filters) && \\
+  ${tool('pins')} /tmp/pnpm-lock.committed.yaml && \\
+  pnpm install --prod --prefer-offline --ignore-scripts \${INJECT} $(cat /tmp/member-filters) --frozen-lockfile
+RUN for schema in $(${tool('dirs')}); do \\
+      if [ -f "\${schema}/prisma/schema.prisma" ]; then \\
+        pnpm --dir "\${schema}" exec prisma generate || exit 1; \\
+      fi; \\
+    done
+
+RUN : "\${BUILD_SHA:?BUILD_SHA build-arg is required}" && \\
+    ${tool(`index "\${BUILD_SHA}" --build-source ${buildSource}`)}
+
+# Every member's module graph loads here, through the host's own entry reader, as
+# the user and NODE_ENV the image runs with, or the image is never pushed. It runs
+# in the builder so the tool above never reaches the final stage; it only reads.
+USER node
+RUN NODE_ENV=production ${tool('load')}
+
+FROM base
+WORKDIR /monorepo
+COPY --from=builder /monorepo /monorepo
+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"]
+`;
+}
+
+/** `--write` writes the rendered Dockerfile; `--check` throws when the committed one differs. */
+export function syncComposedDockerfile({ mode, root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, ...options }) {
+  if (mode !== 'write' && mode !== 'check') throw new Error(`mode must be write or check, got "${mode}"`);
+  const rendered = renderComposedDockerfile({ ...options, imageDir });
+  const relativeTarget = posix.join(imageDir, 'Dockerfile');
+  const target = join(root, relativeTarget);
+  if (mode === 'write') writeFileSync(target, rendered);
+  else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) {
+    throw new Error(`${relativeTarget} is stale. Run: xema-composed-image dockerfile --write (with the same options)`);
+  }
+  return relativeTarget;
+}

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

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { renderComposedDockerfile, syncComposedDockerfile } from './composed-image-dockerfile.mjs';
+
+const OPTIONS = {
+  toolingVersion: '0.9.0',
+  copy: ['packages', 'tooling/dev/', 'biomes'],
+  cacheId: 'alpha-composed-process',
+  buildSource: 'alpha',
+};
+
+test('the template carries every parameter and no per-repository literal', () => {
+  const text = renderComposedDockerfile(OPTIONS);
+  assert.match(text, /npm install --global --ignore-scripts @xemahq\/repo-build-tooling@0\.9\.0\n/);
+  assert.match(text, /^COPY packages\/ \.\/packages\/\nCOPY tooling\/dev\/ \.\/tooling\/dev\/\nCOPY biomes\/ \.\/biomes\/\nCOPY infra\/composed-process\/ \.\/infra\/composed-process\/$/m);
+  assert.match(text, /id=pnpm-store-alpha-composed-process,/);
+  assert.match(text, /id=pnpm-metadata-alpha-composed-process,/);
+  assert.match(text, /xema-composed-image index "\$\{BUILD_SHA\}" --build-source alpha/);
+  assert.doesNotMatch(text, /xema-base|composed-image\.mjs/);
+});
+
+test('every in-image step uses the pinned bin, and a custom image dir is threaded through', () => {
+  const text = renderComposedDockerfile({ ...OPTIONS, imageDir: 'infra/other' });
+  for (const command of ['filters', 'dirs', 'pins', 'index', 'load']) assert.match(text, new RegExp(`xema-composed-image ${command}[^\\n]* --image-dir infra/other|xema-composed-image ${command} --image-dir infra/other`));
+  assert.match(text, /COPY infra\/other\/ \.\/infra\/other\//);
+});
+
+test('nothing of the tool reaches the final stage; load runs in the builder as node, production', () => {
+  const text = renderComposedDockerfile(OPTIONS);
+  const [builder, final] = text.split('\nFROM base\n');
+  assert.match(builder, /USER node\nRUN NODE_ENV=production xema-composed-image load/);
+  assert.doesNotMatch(final, /xema-composed-image|repo-build-tooling|npm install/);
+  assert.match(final, /COPY --from=builder \/monorepo \/monorepo/);
+  assert.match(final, /CMD \["node", "\/monorepo\/xema-composed-process"\]/);
+});
+
+test('the tool version, the directories and the ids are validated', () => {
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, toolingVersion: '^0.9.0' }), /exact x\.y\.z/);
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, toolingVersion: undefined }), /exact x\.y\.z/);
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, copy: [] }), /at least one/);
+  for (const bad of ['../x', '/abs', 'a b', 'a;b']) assert.throws(() => renderComposedDockerfile({ ...OPTIONS, copy: [bad] }), /repository-relative/);
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, cacheId: 'Bad_Id' }), /--cache-id/);
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, buildSource: 'a//b' }), /--build-source/);
+  assert.match(renderComposedDockerfile({ ...OPTIONS, buildSource: 'repos/alpha' }), /--build-source repos\/alpha/);
+});
+
+test('--write renders and --check refuses a stale or missing file', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-dockerfile-'));
+  fs.mkdirSync(path.join(root, 'infra/composed-process'), { recursive: true });
+  assert.throws(() => syncComposedDockerfile({ mode: 'check', root, ...OPTIONS }), /is stale/);
+  assert.equal(syncComposedDockerfile({ mode: 'write', root, ...OPTIONS }), 'infra/composed-process/Dockerfile');
+  syncComposedDockerfile({ mode: 'check', root, ...OPTIONS });
+  assert.throws(() => syncComposedDockerfile({ mode: 'check', root, ...OPTIONS, toolingVersion: '0.9.1' }), /is stale/);
+  assert.throws(() => syncComposedDockerfile({ mode: 'sideways', root, ...OPTIONS }), /write or check/);
+});

package/src/composed-image-paths.mjs

@@ -0,0 +1,2 @@
+// Where a repository keeps its composed-process image: the one place this is spelled.
+export const COMPOSED_IMAGE_DIR = 'infra/composed-process';