@xemahq/repo-build-tooling 0.9.0 → 0.9.2

package/README.md

@@ -95,6 +95,7 @@ build carries every composable platform service of the repository at one commit.
   `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`).
+- `load-image <image>` runs the member-load check inside the shipped image (`docker run`), as its own user and `NODE_ENV`; `load` runs in the builder and cannot prove that.
 - `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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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)",
@@ -37,9 +37,9 @@
     "./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 && 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"
+    "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"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:89bea8bf6a2415cef4ea2dd5f199135d3ee71cba50d1c9eb93cc92f1b9eb1984"
+    "sourceDigest": "sha256:a1775245f7e0b751aeab7d53393103ddc32079c97043755a22b9fa261fa05134"
   }
 }

package/src/composed-image-coordinate.mjs

@@ -32,19 +32,33 @@ function required(env, name) {
   return value;
 }
 
+/**
+ * The consumer's own `package.json` of the hash package, found through Node's own
+ * `node_modules` lookup paths for the consumer, NOT through `require.resolve`: the
+ * package's `exports` map need not expose `./package.json`. Only an absent file
+ * means "not installed"; any other read error is rethrown as it is.
+ */
+function findHashManifest(root) {
+  for (const modulesDir of createRequire(join(root, 'package.json')).resolve.paths(HASH_PACKAGE) ?? []) {
+    const candidate = join(modulesDir, HASH_PACKAGE, 'package.json');
+    try {
+      readFileSync(candidate, 'utf8');
+      return candidate;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
+    }
+  }
+  return undefined;
+}
+
 /** 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 manifestPath = findHashManifest(root);
+  if (manifestPath === undefined) {
+    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',
+    );
   }
   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`);

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

@@ -26,7 +26,7 @@ function registry(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 } = {}) {
+function consumer({ withHash = true, exportsMap } = {}) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-coordinate-'));
   fs.writeFileSync(path.join(root, 'package.json'), '{"name":"consumer"}');
   if (withHash) {
@@ -34,7 +34,7 @@ function consumer({ withHash = true } = {}) {
     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' } }),
+      JSON.stringify({ name: '@xemahq/distribution-source-hash', version: '1.0.0', ...(exportsMap ? { exports: exportsMap } : {}), bin: { 'xema-compute-image-tag': 'dist/bin/compute-image-tag.js' } }),
     );
     fs.writeFileSync(
       path.join(pkg, 'dist/bin/compute-image-tag.js'),
@@ -106,3 +106,18 @@ test('emitCoordinate prints every output and appends them to GITHUB_OUTPUT', ()
   assert.equal(fs.readFileSync(file, 'utf8'), `image=i\ncontent_tag=${HASH}\nexists=false\nentry={}\n`);
   assert.match(lines.at(-1), /is missing — build/);
 });
+
+test('a package whose exports map lacks ./package.json still resolves, as published 0.2.2 does', () => {
+  const root = consumer({ exportsMap: { '.': './dist/index.js' } });
+  assert.equal(
+    resolveHashBin(root),
+    path.join(root, 'node_modules/@xemahq/distribution-source-hash', 'dist/bin/compute-image-tag.js'),
+  );
+});
+
+test('a read error other than absence is rethrown with its real message, not mapped to not installed', () => {
+  const root = consumer({ withHash: false });
+  // package.json is a directory: EISDIR, which is not "absent"
+  fs.mkdirSync(path.join(root, 'node_modules/@xemahq/distribution-source-hash/package.json'), { recursive: true });
+  assert.throws(() => resolveHashBin(root), (error) => error.code === 'EISDIR' && !/not installed/.test(error.message));
+});

package/src/composed-image-dockerfile.mjs

@@ -13,11 +13,12 @@
 // 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 { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
 
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.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-]*$/;
@@ -39,8 +40,14 @@ function validate({ toolingVersion, copy, cacheId, buildSource }) {
   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 }) {
+/** Whether the repository's `.npmrc` authenticates with a token (`_authToken`, `${NPM_TOKEN}`); a public-registry `.npmrc` needs none. */
+export function npmrcUsesToken(npmrcText) {
+  return TOKEN_REFERENCE.test(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 }) {
+  if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
   validate({ toolingVersion, copy, cacheId, buildSource });
   const dirFlag = imageDir === COMPOSED_IMAGE_DIR ? '' : ` --image-dir ${imageDir}`;
   const tool = (command) => `xema-composed-image ${command}${dirFlag}`;
@@ -48,6 +55,11 @@ 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 tokenExport = usesToken
+    ? '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.
 # Re-render with the same options; \`--check\` refuses a stale file.
@@ -90,13 +102,9 @@ 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
+${mount}  ${tokenEnv}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
+${mount}  ${tokenEnv}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.
@@ -106,9 +114,7 @@ RUN for schema in $(${tool('dirs')}); do \\
       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
+RUN ${mount ? `${mount.trimStart()}  ` : ''}${tokenEnv}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
@@ -134,9 +140,7 @@ RUN --mount=type=secret,id=npm_token,required=true \\
 # 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" && \\
+${mount}  ${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} $(cat /tmp/member-filters) && \\
   ${tool('pins')} /tmp/pnpm-lock.committed.yaml && \\
@@ -170,10 +174,16 @@ 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 });
+  validate(options);
+  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 rendered = renderComposedDockerfile({ ...options, usesToken: npmrcUsesToken(readFileSync(npmrc, 'utf8')), imageDir });
   const relativeTarget = posix.join(imageDir, 'Dockerfile');
   const target = join(root, relativeTarget);
-  if (mode === 'write') writeFileSync(target, rendered);
+  if (mode === 'write') {
+    mkdirSync(dirname(target), { recursive: true });
+    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)`);
   }

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

@@ -4,13 +4,14 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { renderComposedDockerfile, syncComposedDockerfile } from './composed-image-dockerfile.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',
+  usesToken: true,
 };
 
 test('the template carries every parameter and no per-repository literal', () => {
@@ -51,9 +52,35 @@ test('the tool version, the directories and the ids are validated', () => {
 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 });
+  fs.writeFileSync(path.join(root, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
   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/);
 });
+
+test('the npm_token secret is mounted only when .npmrc references a token', () => {
+  const withToken = renderComposedDockerfile(OPTIONS);
+  assert.equal(withToken.match(/type=secret,id=npm_token,required=true/g).length, 4);
+  assert.equal(withToken.match(/NPM_TOKEN="\$\(cat \/run\/secrets\/npm_token\)"/g).length, 4);
+  const without = renderComposedDockerfile({ ...OPTIONS, usesToken: false });
+  assert.doesNotMatch(without, /npm_token|NPM_TOKEN|GH_PACKAGES_TOKEN|type=secret/);
+  assert.match(without, /RUN --mount=type=cache,id=pnpm-store-alpha-composed-process,target=\/root\/.pnpm-store \\\n {2}pnpm fetch/);
+  assert.match(without, /RUN pnpm \$\(cat \/tmp\/member-filters\) run build/);
+  assert.throws(() => renderComposedDockerfile({ ...OPTIONS, usesToken: undefined }), /usesToken/);
+});
+
+test('the token use is derived from .npmrc, deterministically', () => {
+  assert.equal(npmrcUsesToken('//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n'), true);
+  assert.equal(npmrcUsesToken('@x:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=abc'), true);
+  assert.equal(npmrcUsesToken('registry=https://registry.npmjs.org/\nauto-install-peers=true\n'), false);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-dockerfile-npmrc-'));
+  assert.throws(() => syncComposedDockerfile({ mode: 'write', root, ...OPTIONS }), /\.npmrc is absent/);
+  fs.writeFileSync(path.join(root, '.npmrc'), 'registry=https://registry.npmjs.org/\n');
+  syncComposedDockerfile({ mode: 'write', root, ...OPTIONS });
+  const text = fs.readFileSync(path.join(root, 'infra/composed-process/Dockerfile'), 'utf8');
+  assert.doesNotMatch(text, /npm_token/);
+  fs.writeFileSync(path.join(root, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
+  assert.throws(() => syncComposedDockerfile({ mode: 'check', root, ...OPTIONS }), /is stale/);
+});

package/src/composed-image.mjs

@@ -35,6 +35,9 @@
 //            and the `xema-composed-process` link the image runs.
 //   load     evaluate every member's entry exactly as the host does
 //            (`readServiceEntry`) and refuse the image if any graph does not load.
+//   load-image <image>
+//            the same check against the SHIPPED image (`docker run`), as its own
+//            user and NODE_ENV: `load` runs in the builder, which is not what ships.
 //   coordinate --image-name <name>
 //            the image's content tag (computed ONLY by the repository's own
 //            `xema-compute-image-tag`) and whether GHCR already serves it
@@ -67,7 +70,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+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 { pathToFileURL } from 'node:url';
@@ -75,6 +78,7 @@ import { pathToFileURL } from 'node:url';
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { composedCoordinate, emitCoordinate } from './composed-image-coordinate.mjs';
 import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
+import { runImageLoad } from './load-image.mjs';
 import { runRefusalSmoke } from './smoke-refusal.mjs';
 
 export { COMPOSED_IMAGE_DIR };
@@ -259,8 +263,10 @@ export function syncImageBuildInputs({ mode, root = process.cwd(), imageDir = CO
   const rendered = renderImageBuildInputs(derived);
   const relativeTarget = posix.join(imageDir, IMAGE_BUILD_INPUTS_FILE);
   const target = join(root, relativeTarget);
-  if (mode === 'write') writeFileSync(target, rendered);
-  else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) {
+  if (mode === 'write') {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, rendered);
+  } else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) {
     throw new Error(
       `${relativeTarget} is stale — the composed image would not carry exactly the composable services. ` +
         'Run: xema-composed-image members --write (with the same options)',
@@ -438,6 +444,7 @@ const USAGE =
   '  members --write|--check [--manifests <glob>]… [--canonical-dockerfile <path>] [--cross-repo-manifest <path>]\n' +
   '  filters | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load\n' +
   '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG REGISTRY_USER REGISTRY_TOKEN [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>';
 
@@ -514,6 +521,9 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
       return composedCoordinate({ root, imageDir, imageName: options['image-name'] }).then((outputs) =>
         emitCoordinate(outputs, { log }),
       );
+    case 'load-image':
+      runImageLoad({ image: argument, log });
+      return;
     case 'smoke-refusal':
       runRefusalSmoke({ image: argument, members: options.member, log, write });
       return;

package/src/composed-image.test.mjs

@@ -247,3 +247,12 @@ test('the new commands parse their options; coordinate is asynchronous and refus
   assert.throws(() => main(['dockerfile', '--write'], { log() {} }), /exact x\.y\.z/);
   assert.throws(() => main(['smoke-refusal'], { log() {} }), /usage/);
 });
+
+test('members --write on a first run creates the missing image directory', () => {
+  const root = fixture();
+  assert.equal(fs.existsSync(path.join(root, 'infra/composed-process')), false);
+  main(['members', '--root', root, '--manifests', 'products/**/xema-biome.json', '--write'], { log() {} });
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(root, 'infra/composed-process/image-build-inputs.json'), 'utf8')), {
+    workspacePackages: ['products/pai/core/pai-core/api/pai-core-api'],
+  });
+});

package/src/load-image.mjs

@@ -0,0 +1,27 @@
+// `xema-composed-image load-image <image>`: proves every composed member module
+// loads in the SHIPPED image, not in the builder stage that produced it. It pipes
+// `load-members-in-image.mjs` into the image's own node, so the check sees the
+// final stage's filesystem, `node_modules`, prune, user and NODE_ENV. Needs only
+// `docker` and the image reference: no git history, no install.
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const LOAD_SCRIPT = fileURLToPath(new URL('./load-members-in-image.mjs', import.meta.url));
+
+/** Returns the number of member module graphs that loaded; throws naming each that did not. */
+export function runImageLoad({ image, spawn = spawnSync, log = console.log, script = () => readFileSync(LOAD_SCRIPT, 'utf8') }) {
+  if (!image) throw new Error('usage: xema-composed-image load-image <image>');
+  const result = spawn('docker', ['run', '--rm', '-i', '--entrypoint', 'node', image, '--input-type=module', '-'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    input: script(),
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`the shipped image ${image} does not load:\n${result.stderr ?? ''}`);
+  const count = Number.parseInt(String(result.stdout).trim(), 10);
+  if (!Number.isInteger(count) || count < 1) throw new Error(`the image load check reported no members: ${result.stdout}`);
+  log(`composed image ${image}: all ${count} member module graph(s) load in the shipped image`);
+  return count;
+}

package/src/load-image.test.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { runImageLoad } from './load-image.mjs';
+
+test('the check runs inside the image through its own node and passes on a clean load', () => {
+  const calls = [];
+  const lines = [];
+  const spawn = (command, args, options) => {
+    calls.push({ command, args, options });
+    return { status: 0, stdout: '3\n', stderr: '' };
+  };
+  assert.equal(runImageLoad({ image: 'img@sha256:x', spawn, log: (l) => lines.push(l), script: () => 'SCRIPT' }), 3);
+  assert.equal(calls[0].command, 'docker');
+  assert.deepEqual(calls[0].args, ['run', '--rm', '-i', '--entrypoint', 'node', 'img@sha256:x', '--input-type=module', '-']);
+  assert.equal(calls[0].options.input, 'SCRIPT');
+  assert.match(lines[0], /all 3 member module graph\(s\) load in the shipped image/);
+});
+
+test('a member that does not load fails the check with the image named', () => {
+  const spawn = () => ({ status: 1, stdout: '', stderr: '1 of 3 member(s) do not load:\n  - a/b: boom\n' });
+  assert.throws(() => runImageLoad({ image: 'img', spawn, script: () => '' }), /shipped image img does not load:[\s\S]*a\/b: boom/);
+});
+
+test('an image that reports no members is refused', () => {
+  const spawn = () => ({ status: 0, stdout: '', stderr: '' });
+  assert.throws(() => runImageLoad({ image: 'img', spawn, script: () => '' }), /reported no members/);
+});
+
+test('an image reference is required', () => {
+  assert.throws(() => runImageLoad({ spawn: () => ({}) }), /usage/);
+});

package/src/load-members-in-image.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// INVOKER: load-image.mjs, INSIDE the composed-process image (piped to the image's
+// own node on stdin). Self-contained on purpose: it resolves nothing from the
+// repository's checkout, only from the image's own filesystem, as the image's own
+// user and NODE_ENV.
+//
+// Evaluates every member's entry exactly as the host does (`readServiceEntry`),
+// from the member's own directory, and exits non-zero naming each that does not load.
+//
+// Usage: docker run -i --entrypoint node <image> --input-type=module - < load-members-in-image.mjs
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const indexPath = process.env.XEMA_COMPOSED_MEMBER_INDEX;
+if (!indexPath) throw new Error('XEMA_COMPOSED_MEMBER_INDEX is not set — not a composed-process image');
+const root = dirname(indexPath);
+const members = Object.entries(JSON.parse(readFileSync(indexPath, 'utf8')).members);
+if (members.length === 0) throw new Error('the image member index carries no members');
+
+const problems = [];
+for (const [key, { entry }] of members) {
+  try {
+    const memberDirectory = dirname(dirname(join(root, entry)));
+    createRequire(join(memberDirectory, 'package.json'))('@xemahq/xema-service-nest').readServiceEntry(join(root, entry), {});
+  } catch (error) {
+    problems.push(`${key}: ${error?.message ?? String(error)}`);
+  }
+}
+if (problems.length > 0) {
+  process.stderr.write(`${problems.length} of ${members.length} member(s) do not load:\n${problems.map((p) => `  - ${p}`).join('\n')}\n`);
+  process.exit(1);
+}
+process.stdout.write(`${members.length}\n`);