@xemahq/repo-build-tooling 0.9.0 → 0.9.1

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.1",
   "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:b9de4f5bf70260506dc8fc6c2e2bad30aba714198303f5440888071880721d98"
   }
 }

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
@@ -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 };
@@ -438,6 +442,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 +519,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/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`);