@xemahq/repo-build-tooling 0.13.0 → 0.14.1

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 `--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.
+`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. 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.13.0",
+  "version": "0.14.1",
   "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)",
@@ -41,9 +41,9 @@
     "@xemahq/release-policy": "^14.0.0"
   },
   "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/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-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"
+    "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-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:a3994566dfeac8ede246a07315647fa7f10828b510cf5835a0640a8a97650f5c"
+    "sourceDigest": "sha256:c1fafb67e8735c78e8eb13a40fe3a3e9745ad5873b906d7c782e33734f86cf88"
   }
 }

package/src/composed-image-dockerfile.mjs

@@ -5,7 +5,7 @@
 // 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
+// (its own package version, never a flag). 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,
@@ -17,19 +17,16 @@ 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 { toolVersion } from './composed-image-stage.mjs';
 
 const TOKEN_REFERENCE = /_authToken\b|\$\{(?:NPM_TOKEN|GH_PACKAGES_TOKEN)\}/;
-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._-]+)*$/;
 export 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}"`);
-  }
+function validate({ copy, cacheId, buildSource }) {
   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('..')) {
@@ -46,9 +43,10 @@ export function npmrcUsesToken(npmrcText) {
 }
 
 /** The Dockerfile text. `usesToken` mounts the `npm_token` build secret; derive it with `npmrcUsesToken`. `imageDir` is where the repository keeps the image (and so where this is written). */
-export function renderComposedDockerfile({ toolingVersion, copy, cacheId, buildSource, usesToken, imageDir = COMPOSED_IMAGE_DIR }) {
+export function renderComposedDockerfile({ copy, cacheId, buildSource, usesToken, imageDir = COMPOSED_IMAGE_DIR }) {
   if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
-  validate({ toolingVersion, copy, cacheId, buildSource });
+  validate({ copy, cacheId, buildSource });
+  const toolingVersion = toolVersion();
   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}/`)])]

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

@@ -4,10 +4,11 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
+import { toolVersion } from './composed-image-stage.mjs';
+
 import { npmrcUsesToken, renderComposedDockerfile, syncComposedDockerfile } from './composed-image-dockerfile.mjs';
 
 const OPTIONS = {
-  toolingVersion: '0.9.0',
   copy: ['packages', 'tooling/dev/', 'biomes'],
   cacheId: 'alpha-composed-process',
   buildSource: 'alpha',
@@ -16,7 +17,7 @@ const OPTIONS = {
 
 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.ok(text.includes(`npm install --global --ignore-scripts @xemahq/repo-build-tooling@${toolVersion()}\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,/);
@@ -39,9 +40,7 @@ test('nothing of the tool reaches the final stage; load runs in the builder as n
   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/);
+test('the directories and the ids are validated', () => {
   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/);
@@ -56,7 +55,7 @@ test('--write renders and --check refuses a stale or missing file', () => {
   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: 'check', root, ...OPTIONS, cacheId: 'beta-composed-process' }), /is stale/);
   assert.throws(() => syncComposedDockerfile({ mode: 'sideways', root, ...OPTIONS }), /write or check/);
 });
 

package/src/composed-image-in-image-closure.test.mjs

@@ -0,0 +1,83 @@
+// The prebuilt image bind-mounts `copyTool`'s output (package.json + src/, NO node_modules) and
+// runs a .mjs entry from it. That entry's whole import closure must load without node_modules.
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test, { after } from 'node:test';
+
+import { renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
+import { copyTool } from './composed-image-stage.mjs';
+import { fakePnpm, workspace } from './composed-image-fixture.test.mjs';
+
+const temps = [];
+after(() => {
+  for (const dir of temps) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function temp(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  temps.push(dir);
+  return dir;
+}
+
+function renderedEntries() {
+  const root = workspace();
+  const { dockerfile } = renderPrebuiltDockerfile({
+    root,
+    copy: ['tooling/dev'],
+    cacheId: 'alpha-composed-process',
+    buildSource: 'alpha',
+    usesToken: true,
+    exec: fakePnpm(root),
+  });
+  const entries = [...new Set([...dockerfile.matchAll(/node \/opt\/xema-composed-image\/(\S+\.mjs)/g)].map((m) => m[1]))];
+  assert.ok(entries.length > 0, 'the rendered Dockerfile runs at least one tool entry');
+  return entries;
+}
+
+const LOCKFILE = "lockfileVersion: '9.0'\n\npackages:\n\n  left-pad@1.3.0:\n    resolution: {integrity: sha512-x}\n";
+
+test('every in-image entry runs from the copied tool directory with no node_modules', () => {
+  const tool = path.join(temp('xema-tool-'), 'tool');
+  copyTool(tool);
+  const root = temp('xema-root-');
+  fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), LOCKFILE);
+  const committed = path.join(root, 'committed.yaml');
+  fs.copyFileSync(path.join(root, 'pnpm-lock.yaml'), committed);
+  for (const entry of renderedEntries()) {
+    const result = spawnSync(process.execPath, [path.join(tool, entry), 'pins', committed, '--root', root], { encoding: 'utf8' });
+    assert.doesNotMatch(result.stderr, /ERR_MODULE_NOT_FOUND/, `${entry}: ${result.stderr}`);
+    assert.equal(result.status, 0, `${entry} exited ${result.status}: ${result.stderr}`);
+  }
+});
+
+const IMPORT_SPECIFIER =
+  /(?:^|[\s;])(?:import|export)\s+(?:[^'"`;]*?\s+from\s+)?['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/gm;
+
+function closureOffenders(entry) {
+  const seen = new Set();
+  const offenders = [];
+  const visit = (file) => {
+    if (seen.has(file)) return;
+    seen.add(file);
+    const source = fs.readFileSync(file, 'utf8');
+    for (const match of source.matchAll(IMPORT_SPECIFIER)) {
+      const specifier = match[1] ?? match[2];
+      if (specifier.startsWith('node:')) continue;
+      if (specifier.startsWith('./') || specifier.startsWith('../')) visit(path.resolve(path.dirname(file), specifier));
+      else offenders.push(`${path.basename(file)} imports ${specifier}`);
+    }
+  };
+  visit(entry);
+  return offenders;
+}
+
+test('every in-image entry imports only node: builtins and relative modules, transitively', () => {
+  const tool = path.join(temp('xema-tool-'), 'tool');
+  copyTool(tool);
+  for (const entry of renderedEntries()) {
+    assert.deepEqual(closureOffenders(path.join(tool, entry)), [], `${entry} reaches a bare package`);
+  }
+});

package/src/composed-image-in-image.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// THE IN-IMAGE HALF OF THE COMPOSED-PROCESS BUILD.
+//
+// The prebuilt Dockerfile bind-mounts a copy of this package's `package.json` + `src/`
+// (NO node_modules) and runs THIS file for `pins`, `index`, `load`, `sync-injected` and
+// `prisma-check`. So this module and everything it imports load only `node:` builtins and
+// relative modules; a bare package import would die with ERR_MODULE_NOT_FOUND in the image
+// (`composed-image-in-image-closure.test.mjs` proves it). `composed-image.mjs` re-exports
+// these functions and dispatches the same verbs outside Docker.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { readMembers } from './composed-image-members.mjs';
+import { syncInjected } from './composed-image-sync-injected.mjs';
+import { prismaCheck } from './composed-image-prisma-check.mjs';
+
+export const MEMBER_INDEX_FILE = 'xema-composed-member-index.json';
+export const HOST_LINK = 'xema-composed-process';
+
+const SDK = '@xemahq/xema-service-nest';
+const IDENTITY_PACKAGES = Object.freeze(['@nestjs/common', '@nestjs/core', '@nestjs/config', 'reflect-metadata', SDK]);
+const COMMIT = /^[a-f0-9]{40}$/;
+
+/** The registry packages (`name@version`) a v9 lockfile's `packages:` section pins. */
+export function registryPins(lockfilePath) {
+  const lines = readFileSync(lockfilePath, 'utf8').split('\n');
+  if (lines[0] !== "lockfileVersion: '9.0'") {
+    throw new Error(`${lockfilePath} is not a v9 lockfile (first line "${lines[0]}")`);
+  }
+  const start = lines.indexOf('packages:');
+  if (start === -1) throw new Error(`${lockfilePath} has no packages: section`);
+  const pins = new Set();
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line)) break;
+    const key = /^ {2}(\S.*):$/.exec(line)?.[1];
+    if (key === undefined) continue;
+    const unquoted = key.replace(/^'(.*)'$/, '$1');
+    // Workspace packages an injected install adds are `file:` entries, not registry pins.
+    if (!/@file:/.test(unquoted)) pins.add(unquoted);
+  }
+  return pins;
+}
+
+/** Refuse a re-resolved `<root>/pnpm-lock.yaml` that pins a registry package the committed lockfile does not. */
+export function assertPinsUnchanged({ root = process.cwd(), committedLockfile }) {
+  if (committedLockfile === undefined) throw new Error('pins needs the committed lockfile path');
+  const committed = registryPins(committedLockfile);
+  const added = [...registryPins(join(root, 'pnpm-lock.yaml'))].filter((pin) => !committed.has(pin));
+  if (added.length > 0) {
+    throw new Error(
+      `the injected re-resolution pinned registry package(s) the committed lockfile does not:\n${added
+        .map((pin) => `  - ${pin}`)
+        .join('\n')}`,
+    );
+  }
+  return committed.size;
+}
+
+function resolveFrom(root, directory, specifier) {
+  try {
+    return realpathSync(createRequire(join(root, directory, 'package.json')).resolve(specifier));
+  } catch (error) {
+    if (error?.code === 'MODULE_NOT_FOUND') return undefined;
+    throw error;
+  }
+}
+
+function packageRoot(file, name) {
+  for (let dir = dirname(file); dir !== dirname(dir); dir = dirname(dir)) {
+    const manifest = join(dir, 'package.json');
+    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === name) return dir;
+  }
+  throw new Error(`no ${name} package root above ${file}`);
+}
+
+/** Write the member index and the host link; returns the host bin path. */
+export function writeMemberIndex({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, commit, buildSourceRepository }) {
+  if (!COMMIT.test(commit ?? '')) throw new Error(`index needs the exact 40-hex build commit, got "${commit}"`);
+  if (typeof buildSourceRepository !== 'string' || buildSourceRepository.length === 0) {
+    throw new Error("index needs --build-source: the repository its subjects name in the image lock (their 'repo')");
+  }
+  const members = readMembers({ root, imageDir });
+  const problems = [];
+  const entries = {};
+  const identity = new Map();
+  for (const [key, directory] of members) {
+    const entry = `${directory}/dist/main.js`;
+    if (!existsSync(join(root, entry))) problems.push(`${key}: built entry ${entry} does not exist`);
+    entries[key] = { entry };
+    for (const specifier of IDENTITY_PACKAGES) {
+      const resolved = resolveFrom(root, directory, specifier);
+      if (resolved === undefined) {
+        // A member that does not depend on a package shares nothing that could
+        // be a second copy — except the host itself, which every member needs.
+        if (specifier === SDK) problems.push(`${key}: does not resolve ${SDK}`);
+        continue;
+      }
+      const seen = identity.get(specifier);
+      if (seen === undefined) identity.set(specifier, { resolved, key });
+      else if (seen.resolved !== resolved) {
+        problems.push(`${key} resolves ${specifier} at ${resolved}, ${seen.key} at ${seen.resolved}`);
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`the composed image cannot carry its members:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+  const document = { schemaVersion: 1, buildSource: { repository: buildSourceRepository, commit }, members: entries };
+  // Graded by the kernel's own schema, resolved through the members' module graph.
+  const { ComposedProcessMemberIndexSchema } = createRequire(join(root, members[0][1], 'package.json'))(
+    '@xemahq/contracts/process-topology',
+  );
+  ComposedProcessMemberIndexSchema.parse(document);
+  writeFileSync(join(root, MEMBER_INDEX_FILE), `${JSON.stringify(document, null, 2)}\n`);
+
+  const sdkRoot = packageRoot(identity.get(SDK).resolved, SDK);
+  const bin = JSON.parse(readFileSync(join(sdkRoot, 'package.json'), 'utf8')).bin?.[HOST_LINK];
+  if (typeof bin !== 'string') throw new Error(`${SDK} at ${sdkRoot} ships no "${HOST_LINK}" bin`);
+  // Relative to the REAL root: the SDK path is a realpath, and a root reached through a
+  // symlink (macOS /var, a bind mount) would otherwise yield a link that escapes it.
+  symlinkSync(relative(realpathSync(root), join(sdkRoot, bin)), join(root, HOST_LINK));
+  return { members: members.length, host: join(sdkRoot, bin) };
+}
+
+/** Every member's module graph loads, through the host's own entry reader. */
+export function loadMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const members = readMembers({ root, imageDir });
+  const problems = [];
+  for (const [key, directory] of members) {
+    try {
+      createRequire(join(root, directory, 'package.json'))(SDK).readServiceEntry(join(root, directory, 'dist', 'main.js'), {});
+    } catch (error) {
+      problems.push(`${key}: ${error?.message ?? String(error)}`);
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `${problems.length} of ${members.length} member(s) do not load:\n${problems.map((p) => `  - ${p}`).join('\n')}`,
+    );
+  }
+  return members.length;
+}
+
+export const LOAD_ONE = `const { createRequire } = require('node:module');
+const { join } = require('node:path');
+const [directory, sdk] = process.argv.slice(1);
+createRequire(join(directory, 'package.json'))(sdk).readServiceEntry(join(directory, 'dist', 'main.js'), {});
+process.exit(0);`;
+
+/** Every member loads ALONE: one `node` process per member, same environment and user. `spawn` is injectable. */
+export function loadMembersEach({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, spawn = spawnSync } = {}) {
+  const members = readMembers({ root, imageDir });
+  const problems = [];
+  for (const [key, directory] of members) {
+    const result = spawn(process.execPath, ['-e', LOAD_ONE, join(root, directory), SDK], {
+      cwd: join(root, directory),
+      env: process.env,
+      encoding: 'utf8',
+    });
+    if (result.error) problems.push(`${key}: ${result.error.message}`);
+    else if (result.status !== 0) {
+      const detail = String(result.stderr ?? '').trim().split('\n').filter(Boolean).slice(0, 8).join(' | ');
+      problems.push(`${key}: exited ${result.status ?? result.signal}${detail === '' ? '' : ` — ${detail}`}`);
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `${problems.length} of ${members.length} member(s) do not load on their own:\n${problems.map((p) => `  - ${p}`).join('\n')}`,
+    );
+  }
+  return members.length;
+}
+
+// ── the in-image bin ────────────────────────────────────────────────────────
+
+const USAGE =
+  'usage: composed-image-in-image <command> [--root <dir>] [--image-dir <dir>]\n' +
+  '  pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each] | sync-injected | prisma-check';
+
+function parseInImageArguments(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    if (name === 'each') {
+      options.each = true;
+      continue;
+    }
+    if (name !== 'root' && name !== 'image-dir' && name !== 'build-source') throw new Error(`unknown option ${arg}\n${USAGE}`);
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+    i += 1;
+    options[name] = value;
+  }
+  return { command: positional[0], argument: positional[1], options };
+}
+
+export function main(argv, { log = console.log } = {}) {
+  const { command, argument, options } = parseInImageArguments(argv);
+  const root = resolve(options.root ?? process.cwd());
+  const imageDir = options['image-dir'] ?? COMPOSED_IMAGE_DIR;
+  switch (command) {
+    case 'pins': {
+      const count = assertPinsUnchanged({ root, committedLockfile: argument });
+      log(`composed install: every registry pin is the committed lockfile's (${count})`);
+      return;
+    }
+    case 'index': {
+      const result = writeMemberIndex({ root, imageDir, commit: argument, buildSourceRepository: options['build-source'] });
+      log(`composed member index: ${result.members} member(s) at ${argument}; host ${result.host}`);
+      return;
+    }
+    case 'load':
+      if (options.each) {
+        log(`composed members: all ${loadMembersEach({ root, imageDir })} module graph(s) load on their own`);
+        return;
+      }
+      log(`composed members: all ${loadMembers({ root, imageDir })} module graph(s) load`);
+      return;
+    case 'sync-injected':
+      syncInjected({ root, imageDir, log });
+      return;
+    case 'prisma-check':
+      return prismaCheck({ root, imageDir, log }).then(() => undefined);
+    default:
+      throw new Error(USAGE);
+  }
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+if (invokedPath !== undefined && import.meta.url === pathToFileURL(invokedPath).href) {
+  try {
+    await main(process.argv.slice(2));
+    // A loaded member graph may hold handles its modules opened at evaluation; the verdict is in.
+    process.exit(0);
+  } catch (error) {
+    console.error(`xema-composed-image: ${error?.message ?? String(error)}`);
+    let depth = 0;
+    for (let cause = error?.cause; cause !== undefined && depth < 5; cause = cause?.cause, depth += 1) {
+      console.error(`  caused by ${cause?.message ?? String(cause)}`);
+    }
+    process.exit(1);
+  }
+}

package/src/composed-image-paths.mjs

@@ -1,2 +1,5 @@
 // Where a repository keeps its composed-process image: the one place this is spelled.
 export const COMPOSED_IMAGE_DIR = 'infra/composed-process';
+
+// The one entry the prebuilt image runs from the bind-mounted tool directory: loads only `node:` and relative modules.
+export const IN_IMAGE_ENTRY = 'src/composed-image-in-image.mjs';

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

@@ -6,18 +6,17 @@
 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 { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY } from './composed-image-paths.mjs';
+import { toolVersion } from './composed-image-stage.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}"`);
+function validate({ copy, cacheId, buildSource, stageDir }) {
   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`);
@@ -69,7 +68,6 @@ const parts = (sources) => sources.map((source) => `    ${source} \\`).join('\n'
 export function renderPrebuiltDockerfile({
   root = process.cwd(),
   imageDir = COMPOSED_IMAGE_DIR,
-  toolingVersion,
   copy = [],
   cacheId,
   buildSource,
@@ -78,7 +76,8 @@ export function renderPrebuiltDockerfile({
   exec,
 }) {
   if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
-  validate({ toolingVersion, copy, cacheId, buildSource, stageDir });
+  validate({ copy, cacheId, buildSource, stageDir });
+  const toolingVersion = toolVersion();
   const workspaceFile = join(root, 'pnpm-workspace.yaml');
   const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
   if (built.length === 0) {
@@ -90,7 +89,7 @@ export function renderPrebuiltDockerfile({
   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 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 secret = usesToken ? '  --mount=type=secret,id=npm_token,required=true \\\n' : '';

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

@@ -8,7 +8,7 @@ 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 };
+  return { root, 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', () => {
@@ -40,7 +40,7 @@ test('the tool is only bind-mounted, and the final stage carries nothing of it',
   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, /USER node\nRUN --mount=\S+ \\\n {2}NODE_ENV=production node \/opt\/xema-composed-image\/src\/composed-image-in-image\.mjs load --each\n/);
   assert.match(dockerfile, /cp \/opt\/xema-composed-image\/src\/composed-migrate\.mjs \/monorepo\/xema-composed-migrate\.mjs/);
 });
 

package/src/composed-image-stage.mjs

@@ -50,7 +50,7 @@ function renderedDockerfile(root, imageDir) {
 }
 
 /** Copy `package.json` + `src/` (no `*.test.mjs`) of this package to `<dir>/tool`. */
-function copyTool(target) {
+export function copyTool(target) {
   const files = ['package.json', ...listFiles(join(TOOL_PACKAGE, 'src')).filter((f) => !f.endsWith('.test.mjs')).map((f) => `src/${f}`)];
   copyFiles(TOOL_PACKAGE, target, files);
   return files.length;

package/src/composed-image.mjs

@@ -61,10 +61,10 @@
 //   smoke-refusal <image> [--member <biomeId>/<componentKey>]x2
 //            boot the pushed image with a declaration the host must refuse
 //            (`smoke-refusal.mjs`).
-//   dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>
+//   dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>
 //            render `<image-dir>/Dockerfile` from the package's template
 //            (`composed-image-dockerfile.mjs`).
-//   dockerfile --prebuilt --write|--check --tooling-version <x.y.z> --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]
+//   dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]
 //            render the Dockerfile that ASSEMBLES the image from `stage` output, and its
 //            `Dockerfile.dockerignore` (`composed-image-prebuilt-dockerfile.mjs`).
 //
@@ -88,15 +88,15 @@
 // would be refused by the host only when a deployment first composed it.
 // ═══════════════════════════════════════════════════════════════════════════
 
-import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, posix, relative, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { composedCoordinate, emitCoordinate } from './composed-image-coordinate.mjs';
 import { describeErrorChain } from '@xemahq/release-policy/registry';
+import { MEMBER_INDEX_FILE, assertPinsUnchanged, loadMembers, loadMembersEach, writeMemberIndex } from './composed-image-in-image.mjs';
 import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
 import { IMAGE_BUILD_INPUTS_FILE, memberClosure, memberFilters, readMembers } from './composed-image-members.mjs';
 import { syncPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
@@ -108,14 +108,19 @@ import { runImageLoad } from './load-image.mjs';
 import { runRefusalSmoke } from './smoke-refusal.mjs';
 
 export { COMPOSED_IMAGE_DIR, IMAGE_BUILD_INPUTS_FILE, memberClosure, memberFilters, readMembers };
-export const MEMBER_INDEX_FILE = 'xema-composed-member-index.json';
-export const HOST_LINK = 'xema-composed-process';
+export {
+  HOST_LINK,
+  LOAD_ONE,
+  MEMBER_INDEX_FILE,
+  assertPinsUnchanged,
+  loadMembers,
+  loadMembersEach,
+  registryPins,
+  writeMemberIndex,
+} from './composed-image-in-image.mjs';
 export const DEFAULT_MANIFEST_GLOBS = Object.freeze(['**/xema-biome.json']);
 
-const SDK = '@xemahq/xema-service-nest';
-const IDENTITY_PACKAGES = Object.freeze(['@nestjs/common', '@nestjs/core', '@nestjs/config', 'reflect-metadata', SDK]);
 const SUPPLY_CHAIN_ARG = /^ARG\s+(SUPPLY_CHAIN_[A-Z_]+_SERVICES)="([^"]*)"\s*$/gm;
-const COMMIT = /^[a-f0-9]{40}$/;
 
 export const ExclusionReason = Object.freeze({
   EntryShape: 'entry-shape',
@@ -302,156 +307,6 @@ export function syncImageBuildInputs({ mode, root = process.cwd(), imageDir = CO
 
 // ── the image build ─────────────────────────────────────────────────────────
 
-/** The registry packages (`name@version`) a v9 lockfile's `packages:` section pins. */
-export function registryPins(lockfilePath) {
-  const lines = readFileSync(lockfilePath, 'utf8').split('\n');
-  if (lines[0] !== "lockfileVersion: '9.0'") {
-    throw new Error(`${lockfilePath} is not a v9 lockfile (first line "${lines[0]}")`);
-  }
-  const start = lines.indexOf('packages:');
-  if (start === -1) throw new Error(`${lockfilePath} has no packages: section`);
-  const pins = new Set();
-  for (const line of lines.slice(start + 1)) {
-    if (/^\S/.test(line)) break;
-    const key = /^ {2}(\S.*):$/.exec(line)?.[1];
-    if (key === undefined) continue;
-    const unquoted = key.replace(/^'(.*)'$/, '$1');
-    // Workspace packages an injected install adds are `file:` entries, not registry pins.
-    if (!/@file:/.test(unquoted)) pins.add(unquoted);
-  }
-  return pins;
-}
-
-/** Refuse a re-resolved `<root>/pnpm-lock.yaml` that pins a registry package the committed lockfile does not. */
-export function assertPinsUnchanged({ root = process.cwd(), committedLockfile }) {
-  if (committedLockfile === undefined) throw new Error('pins needs the committed lockfile path');
-  const committed = registryPins(committedLockfile);
-  const added = [...registryPins(join(root, 'pnpm-lock.yaml'))].filter((pin) => !committed.has(pin));
-  if (added.length > 0) {
-    throw new Error(
-      `the injected re-resolution pinned registry package(s) the committed lockfile does not:\n${added
-        .map((pin) => `  - ${pin}`)
-        .join('\n')}`,
-    );
-  }
-  return committed.size;
-}
-
-function resolveFrom(root, directory, specifier) {
-  try {
-    return realpathSync(createRequire(join(root, directory, 'package.json')).resolve(specifier));
-  } catch (error) {
-    if (error?.code === 'MODULE_NOT_FOUND') return undefined;
-    throw error;
-  }
-}
-
-function packageRoot(file, name) {
-  for (let dir = dirname(file); dir !== dirname(dir); dir = dirname(dir)) {
-    const manifest = join(dir, 'package.json');
-    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === name) return dir;
-  }
-  throw new Error(`no ${name} package root above ${file}`);
-}
-
-/** Write the member index and the host link; returns the host bin path. */
-export function writeMemberIndex({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, commit, buildSourceRepository }) {
-  if (!COMMIT.test(commit ?? '')) throw new Error(`index needs the exact 40-hex build commit, got "${commit}"`);
-  if (typeof buildSourceRepository !== 'string' || buildSourceRepository.length === 0) {
-    throw new Error("index needs --build-source: the repository its subjects name in the image lock (their 'repo')");
-  }
-  const members = readMembers({ root, imageDir });
-  const problems = [];
-  const entries = {};
-  const identity = new Map();
-  for (const [key, directory] of members) {
-    const entry = `${directory}/dist/main.js`;
-    if (!existsSync(join(root, entry))) problems.push(`${key}: built entry ${entry} does not exist`);
-    entries[key] = { entry };
-    for (const specifier of IDENTITY_PACKAGES) {
-      const resolved = resolveFrom(root, directory, specifier);
-      if (resolved === undefined) {
-        // A member that does not depend on a package shares nothing that could
-        // be a second copy — except the host itself, which every member needs.
-        if (specifier === SDK) problems.push(`${key}: does not resolve ${SDK}`);
-        continue;
-      }
-      const seen = identity.get(specifier);
-      if (seen === undefined) identity.set(specifier, { resolved, key });
-      else if (seen.resolved !== resolved) {
-        problems.push(`${key} resolves ${specifier} at ${resolved}, ${seen.key} at ${seen.resolved}`);
-      }
-    }
-  }
-  if (problems.length > 0) {
-    throw new Error(`the composed image cannot carry its members:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
-  }
-  const document = { schemaVersion: 1, buildSource: { repository: buildSourceRepository, commit }, members: entries };
-  // Graded by the kernel's own schema, resolved through the members' module graph.
-  const { ComposedProcessMemberIndexSchema } = createRequire(join(root, members[0][1], 'package.json'))(
-    '@xemahq/contracts/process-topology',
-  );
-  ComposedProcessMemberIndexSchema.parse(document);
-  writeFileSync(join(root, MEMBER_INDEX_FILE), `${JSON.stringify(document, null, 2)}\n`);
-
-  const sdkRoot = packageRoot(identity.get(SDK).resolved, SDK);
-  const bin = JSON.parse(readFileSync(join(sdkRoot, 'package.json'), 'utf8')).bin?.[HOST_LINK];
-  if (typeof bin !== 'string') throw new Error(`${SDK} at ${sdkRoot} ships no "${HOST_LINK}" bin`);
-  // Relative to the REAL root: the SDK path is a realpath, and a root reached through a
-  // symlink (macOS /var, a bind mount) would otherwise yield a link that escapes it.
-  symlinkSync(relative(realpathSync(root), join(sdkRoot, bin)), join(root, HOST_LINK));
-  return { members: members.length, host: join(sdkRoot, bin) };
-}
-
-/** Every member's module graph loads, through the host's own entry reader. */
-export function loadMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
-  const members = readMembers({ root, imageDir });
-  const problems = [];
-  for (const [key, directory] of members) {
-    try {
-      createRequire(join(root, directory, 'package.json'))(SDK).readServiceEntry(join(root, directory, 'dist', 'main.js'), {});
-    } catch (error) {
-      problems.push(`${key}: ${error?.message ?? String(error)}`);
-    }
-  }
-  if (problems.length > 0) {
-    throw new Error(
-      `${problems.length} of ${members.length} member(s) do not load:\n${problems.map((p) => `  - ${p}`).join('\n')}`,
-    );
-  }
-  return members.length;
-}
-
-const LOAD_ONE = `const { createRequire } = require('node:module');
-const { join } = require('node:path');
-const [directory, sdk] = process.argv.slice(1);
-createRequire(join(directory, 'package.json'))(sdk).readServiceEntry(join(directory, 'dist', 'main.js'), {});
-process.exit(0);`;
-
-/** Every member loads ALONE: one `node` process per member, same environment and user. `spawn` is injectable. */
-export function loadMembersEach({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, spawn = spawnSync } = {}) {
-  const members = readMembers({ root, imageDir });
-  const problems = [];
-  for (const [key, directory] of members) {
-    const result = spawn(process.execPath, ['-e', LOAD_ONE, join(root, directory), SDK], {
-      cwd: join(root, directory),
-      env: process.env,
-      encoding: 'utf8',
-    });
-    if (result.error) problems.push(`${key}: ${result.error.message}`);
-    else if (result.status !== 0) {
-      const detail = String(result.stderr ?? '').trim().split('\n').filter(Boolean).slice(0, 8).join(' | ');
-      problems.push(`${key}: exited ${result.status ?? result.signal}${detail === '' ? '' : ` — ${detail}`}`);
-    }
-  }
-  if (problems.length > 0) {
-    throw new Error(
-      `${problems.length} of ${members.length} member(s) do not load on their own:\n${problems.map((p) => `  - ${p}`).join('\n')}`,
-    );
-  }
-  return members.length;
-}
-
 // ── the bin ─────────────────────────────────────────────────────────────────
 
 const USAGE =
@@ -462,13 +317,13 @@ const USAGE =
   '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG [TAG_ARGS_FILE])\n' +
   '  load-image <image>\n' +
   '  smoke-refusal <image> [--member <biomeId>/<componentKey>]x2\n' +
-  '  dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>\n' +
-  '  dockerfile --prebuilt --write|--check --tooling-version <x.y.z> --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]';
+  '  dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>\n' +
+  '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]';
 
 const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output', 'also']);
 const BOOLEAN = new Set(['prebuilt', 'each']);
 const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source',
-  'image-name', 'tooling-version', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also',
+  'image-name', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also',
 ]);
 
 export function parseArguments(argv) {
@@ -573,7 +428,6 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
           mode: options.mode,
           root,
           imageDir,
-          toolingVersion: options['tooling-version'],
           copy: options.copy,
           cacheId: options['cache-id'],
           buildSource: options['build-source'],
@@ -586,7 +440,6 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
         mode: options.mode,
         root,
         imageDir,
-        toolingVersion: options['tooling-version'],
         copy: options.copy,
         cacheId: options['cache-id'],
         buildSource: options['build-source'],

package/src/composed-image.test.mjs

@@ -239,12 +239,13 @@ test('the bin runs through a symlink, as npm installs it, and exits non-zero on
 });
 
 test('the new commands parse their options; coordinate refuses without an image name', async () => {
-  const parsed = parseArguments(['dockerfile', '--write', '--copy', 'a', '--copy', 'b', '--cache-id', 'c', '--tooling-version', '1.2.3']);
+  const parsed = parseArguments(['dockerfile', '--write', '--copy', 'a', '--copy', 'b', '--cache-id', 'c']);
   assert.deepEqual(parsed.options.copy, ['a', 'b']);
   assert.equal(parsed.options['cache-id'], 'c');
   assert.deepEqual(parseArguments(['smoke-refusal', 'img', '--member', 'x/y', '--member', 'x/z']).options.member, ['x/y', 'x/z']);
   assert.throws(() => main(['coordinate'], { log() {} }), /--image-name/);
-  assert.throws(() => main(['dockerfile', '--write'], { log() {} }), /exact x\.y\.z/);
+  assert.throws(() => main(['dockerfile', '--write'], { log() {} }), /at least one/);
+  assert.throws(() => parseArguments(['dockerfile', '--write', '--tooling-version', '1.2.3']), /unknown option --tooling-version/);
   assert.throws(() => main(['smoke-refusal'], { log() {} }), /usage/);
 });