@xemahq/repo-build-tooling 0.11.0 → 0.13.0

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>]…` output (requires `--tooling-version`, `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. Run `xema-composed-image` with no arguments for the full usage.
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--tooling-version`, `--copy`, `--cache-id` and `--build-source`. `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--tooling-version`, `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.11.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.",
+  "version": "0.13.0",
+  "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)",
   "homepage": "https://xema.dev",
@@ -32,16 +32,18 @@
     "./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",
     "./service-bootstrap": "./src/service-bootstrap.mjs"
   },
+  "dependencies": {
+    "@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/ghcr-manifest.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs"
+    "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"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:8a0729af873e6dee7bc38a38408c3f0f57447884e6461ad36e06e8165cf28f4b"
+    "sourceDigest": "sha256:a3994566dfeac8ede246a07315647fa7f10828b510cf5835a0640a8a97650f5c"
   }
 }

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

@@ -0,0 +1,60 @@
+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 from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), 'composed-image.mjs');
+const HASH = 'a'.repeat(64);
+
+function consumer() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'coordinate-cli-'));
+  const hashDir = path.join(root, 'node_modules', '@xemahq', 'distribution-source-hash');
+  fs.mkdirSync(hashDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(hashDir, 'package.json'),
+    JSON.stringify({ name: '@xemahq/distribution-source-hash', bin: { 'xema-compute-image-tag': 'bin.js' } }),
+  );
+  fs.writeFileSync(path.join(hashDir, 'bin.js'), `console.log('${HASH}');\n`);
+  fs.writeFileSync(path.join(root, 'package.json'), '{}');
+  return root;
+}
+
+// The release-policy develop-images CLI runs the coordinate under an allow-listed
+// environment with no registry credential and parses these two stdout lines.
+test('the CLI prints content_tag and cross_repo_pins under an environment with no registry credential', () => {
+  const root = consumer();
+  try {
+    const tagArgs = path.join(root, 'tag-args.txt');
+    fs.writeFileSync(tagArgs, `--vendored\nd=r@${'b'.repeat(40)}:s\n`);
+    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--image-name', 'img'], {
+      cwd: root,
+      encoding: 'utf8',
+      env: { PATH: process.env.PATH, SHA: 'b'.repeat(40), REGISTRY: 'ghcr.io', REGISTRY_ORG: 'org', TAG_ARGS_FILE: tagArgs },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, new RegExp(`^content_tag=${HASH}$`, 'm'));
+    assert.match(result.stdout, /^cross_repo_pins=1$/m);
+    assert.doesNotMatch(result.stdout, /exists=/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('the CLI fails with the real message when the hash package is not installed', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'coordinate-cli-'));
+  try {
+    fs.writeFileSync(path.join(root, 'package.json'), '{}');
+    const result = spawnSync(process.execPath, [BIN, 'coordinate', '--image-name', 'img'], {
+      cwd: root,
+      encoding: 'utf8',
+      env: { PATH: process.env.PATH, SHA: 'b'.repeat(40), REGISTRY: 'ghcr.io', REGISTRY_ORG: 'org' },
+    });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /distribution-source-hash is not installed/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/composed-image-coordinate.mjs

@@ -1,5 +1,5 @@
 // `xema-composed-image coordinate --image-name <name>`: the release coordinate of a
-// repository's composed-process image, and whether the registry already serves it.
+// repository's composed-process image and how many cross-repository inputs it hashes.
 //
 // 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
@@ -8,23 +8,34 @@
 // 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.
+// The coordinate is PURE: it computes and prints, and never probes the registry, so
+// it needs no registry credential and runs under an environment that carries none.
+// Whether the registry serves the tag is the caller's own question.
 //
-// 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.
+// Environment: SHA (40-hex commit), REGISTRY, REGISTRY_ORG, 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';
+const VENDORED_FLAG = '--vendored';
+
+/**
+ * The number of cross-repository pinned inputs in the hash input set: each
+ * `--vendored <dest>=<repo>@<commit>:<src>` pair of the tag arguments. Every tag
+ * argument flag takes exactly one value, so the arguments are read as flag/value pairs.
+ */
+export function countCrossRepoPins(tagArgs) {
+  if (tagArgs.length % 2 !== 0) throw new Error('TAG_ARGS_FILE must hold flag/value pairs, one argument per line');
+  let pins = 0;
+  for (let i = 0; i < tagArgs.length; i += 2) if (tagArgs[i] === VENDORED_FLAG) pins += 1;
+  return pins;
+}
 
 function required(env, name) {
   const value = env[name];
@@ -65,8 +76,8 @@ export function resolveHashBin(root) {
   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 }) {
+/** `{ image, content_tag, cross_repo_pins, entry }` for the composed image of the repository at `root`. */
+export function composedCoordinate({ root, imageName, imageDir, env = process.env, 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`);
@@ -93,16 +104,7 @@ export async function composedCoordinate({ root, imageName, imageDir, env = proc
     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}`;
+  const image = `${registry}/${org}/${imageName}`;
   // 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 = {
@@ -113,7 +115,7 @@ export async function composedCoordinate({ root, imageName, imageDir, env = proc
     imageRepository: image,
     contentHash,
   };
-  return { image, content_tag: contentHash, exists: String(exists), entry: JSON.stringify(entry) };
+  return { image, content_tag: contentHash, cross_repo_pins: String(countCrossRepoPins(tagArgs)), entry: JSON.stringify(entry) };
 }
 
 /** Print the outputs, append them to GITHUB_OUTPUT when set. */
@@ -122,5 +124,5 @@ export function emitCoordinate(outputs, { env = process.env, log = console.log }
     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'}`);
+  log(`${outputs.image}:${outputs.content_tag} (${outputs.cross_repo_pins} cross-repo pins)`);
 }

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

@@ -4,26 +4,11 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { composedCoordinate, emitCoordinate, resolveHashBin } from './composed-image-coordinate.mjs';
+import { composedCoordinate, countCrossRepoPins, 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, {});
-    },
-  };
-}
+const ENV = { SHA, REGISTRY: 'ghcr.io', REGISTRY_ORG: 'xema-dev' };
 
 /** 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, exportsMap } = {}) {
@@ -44,67 +29,77 @@ function consumer({ withHash = true, exportsMap } = {}) {
   return root;
 }
 
-test('the hash comes from the consumer\'s own bin, called with the service, directory, commit and tag args', async () => {
+test('the hash comes from the consumer\'s own bin, called with the service, directory, commit and tag args', () => {
   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({
+  const out = 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.equal(out.cross_repo_pins, '1');
+  assert.equal('exists' in out, false);
   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 composed subject with no tag arguments has zero cross-repo pins', () => {
+  const out = composedCoordinate({ root: consumer(), imageName: 'a', imageDir: 'd', env: ENV });
+  assert.equal(out.cross_repo_pins, '0');
+});
+
+test('every --vendored input counts, other tag arguments do not', () => {
+  assert.equal(countCrossRepoPins([]), 0);
+  assert.equal(countCrossRepoPins(['--vendored', 'a=r@' + SHA + ':p', '--build-step-dir', 'x', '--vendored', 'b=r@' + SHA + ':q']), 2);
+  assert.throws(() => countCrossRepoPins(['--vendored']), /flag\/value pairs/);
 });
 
-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 }),
+test('the coordinate is pure: no registry credential is needed and no fetch is made', () => {
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = () => {
+    throw new Error('coordinate must not touch the network');
+  };
+  try {
+    const out = composedCoordinate({ root: consumer(), imageName: 'a', imageDir: 'd', env: { ...ENV } });
+    assert.equal(out.content_tag, HASH);
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+});
+
+test('a repository without the hash package is refused, never hashed another way', () => {
+  assert.throws(
+    () => composedCoordinate({ root: consumer({ withHash: false }), imageName: 'a', imageDir: 'd', env: ENV }),
     /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 () => {
+test('the inputs are checked: commit, registry settings, tag args file, digest shape', () => {
   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/,
-  );
+  const base = { root, imageName: 'a', imageDir: 'd' };
+  assert.throws(() => composedCoordinate({ ...base, env: { ...ENV, SHA: 'abc' } }), /40-hex/);
+  assert.throws(() => composedCoordinate({ ...base, env: { ...ENV, REGISTRY_ORG: '' } }), /REGISTRY_ORG is required/);
+  assert.throws(() => composedCoordinate({ ...base, env: { ...ENV, TAG_ARGS_FILE: path.join(root, 'nope') } }), /TAG_ARGS_FILE .* absent/);
+  assert.throws(() => composedCoordinate({ ...base, imageName: '', env: ENV }), /--image-name/);
+  assert.throws(() => composedCoordinate({ ...base, env: ENV, hash: () => 'not-a-digest' }), /not a sha256/);
 });
 
 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/);
+  emitCoordinate({ image: 'i', content_tag: HASH, cross_repo_pins: '0', entry: '{}' }, { env: { GITHUB_OUTPUT: file }, log: (l) => lines.push(l) });
+  assert.equal(fs.readFileSync(file, 'utf8'), `image=i\ncontent_tag=${HASH}\ncross_repo_pins=0\nentry={}\n`);
+  assert.match(lines.at(-1), /0 cross-repo pins/);
 });
 
 test('a package whose exports map lacks ./package.json still resolves, as published 0.2.2 does', () => {

package/src/composed-image-members.mjs

@@ -43,10 +43,15 @@ function packageName(root, directory) {
   return manifest.name;
 }
 
-/** The pnpm `--filter <package>...` arguments covering every member's closure. */
+/**
+ * The pnpm `--filter <package>...` arguments covering every member's closure, then
+ * each `also` package's (a workspace package name); a name a member already
+ * selected is listed once.
+ */
 export function memberFilters(options = {}) {
   const root = options.root ?? process.cwd();
-  return readMembers(options).map(([, directory]) => `--filter ${packageName(root, directory)}...`);
+  const names = readMembers(options).map(([, directory]) => packageName(root, directory));
+  return [...new Set([...names, ...(options.also ?? [])])].map((name) => `--filter ${name}...`);
 }
 
 
@@ -66,21 +71,30 @@ export function memberManifests({ root = process.cwd(), imageDir = COMPOSED_IMAG
 
 const defaultExec = (file, args, { cwd }) => execFileSync(file, args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
 
-/**
- * The workspace packages the members' filters select (the members and everything
- * they depend on inside the workspace): repository-relative directories, sorted.
- * `exec(file, args, { cwd })` returns stdout; injectable for tests.
- */
-export function memberClosure({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec = defaultExec } = {}) {
-  const words = memberFilters({ root, imageDir }).flatMap((filter) => filter.split(' '));
-  const listing = exec('pnpm', ['ls', '-r', '--depth', '-1', '--json', ...words], { cwd: root });
+function parseListing(listing) {
   let packages;
   try {
     packages = JSON.parse(listing);
   } catch (error) {
     throw new Error(`pnpm ls did not print JSON: ${error.message}`);
   }
-  if (!Array.isArray(packages) || packages.length === 0) throw new Error('pnpm ls selected no workspace package');
+  if (!Array.isArray(packages)) throw new Error('pnpm ls did not print a JSON array');
+  return packages;
+}
+
+/**
+ * The workspace packages the members' filters select (the members and everything
+ * they depend on inside the workspace): repository-relative directories, sorted.
+ * `exec(file, args, { cwd })` returns stdout; injectable for tests.
+ */
+export function memberClosure({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec = defaultExec, also = [] } = {}) {
+  for (const name of also) {
+    const found = parseListing(exec('pnpm', ['ls', '-r', '--depth', '-1', '--json', '--filter', name], { cwd: root }));
+    if (!found.some((pkg) => pkg?.name === name)) throw new Error(`--also ${name}: no workspace package has that name`);
+  }
+  const words = memberFilters({ root, imageDir, also }).flatMap((filter) => filter.split(' '));
+  const packages = parseListing(exec('pnpm', ['ls', '-r', '--depth', '-1', '--json', ...words], { cwd: root }));
+  if (packages.length === 0) throw new Error('pnpm ls selected no workspace package');
   const real = realpathSync(root);
   const directories = new Set();
   for (const pkg of packages) {

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

@@ -123,7 +123,9 @@ export function renderPrebuiltDockerfile({
 #   assemble  source of the closure + the staged outputs, the injected copies synced to
 #             their \`files\`, then the proofs on the target arch: Prisma clients run, the
 #             member index is written, every member loads ALONE as \`node\`, production.
-#   (final)   \`/monorepo\` from assemble. Nothing of the tool ships.
+#   (final)   \`/monorepo\` of assemble, shipped as THREE layers so a commit that changes only
+#             members' code re-pushes only the layers that changed (see the final stage).
+#             Nothing of the tool ships.
 #
 # The \`--filter <package>...\` words below are LITERAL: the content hash of this image reads
 # them to narrow the lockfile to the members' closures.
@@ -168,9 +170,22 @@ USER node
 RUN ${toolMount} \\
   NODE_ENV=production node ${node} load --each${dirFlag}
 
+# The final stage is layered by how often each part changes, so a registry and a node
+# already holding the stable layers fetch only the rest. The three copies overlay to
+# exactly assemble's /monorepo (proven by a tree diff of both images).
+#   1 deps       root manifests, the external .pnpm store, and the injected stubs that hold
+#                only package.json. Stable while the lockfile and the closure's package.json
+#                files are unchanged.
+#   2 assemble   members, dist, Prisma clients, member index, migrate script: everything
+#                but the .pnpm store, whose packages layer 1 already carries.
+#   3 injected   the workspace copies \`node_modules/.pnpm/*@file+*\`: \`sync-injected\` fills
+#                them from the members' files, so they change with every commit. \`--parents\`
+#                keeps their paths under /.
 FROM base
 WORKDIR /monorepo
-COPY --from=assemble /monorepo /monorepo
+COPY --from=deps /monorepo /monorepo
+COPY --from=assemble --exclude=node_modules/.pnpm /monorepo /monorepo
+COPY --from=assemble --parents /monorepo/node_modules/.pnpm/*@file+* /
 ENV NODE_ENV=production
 # Set by the IMAGE, never by a deployment (kernel \`COMPOSED_PROCESS_ENV.MemberIndex\`).
 ENV XEMA_COMPOSED_MEMBER_INDEX=/monorepo/xema-composed-member-index.json

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

@@ -39,7 +39,7 @@ test('the tool is only bind-mounted, and the final stage carries nothing of it',
   assert.doesNotMatch(dockerfile, /\bnpm install|COPY \.xema-stage\/tool/);
   const final = dockerfile.split('\nFROM base\n')[1];
   assert.doesNotMatch(final, /xema-composed-image|repo-build-tooling|npm install|\/opt\//);
-  assert.match(final, /COPY --from=assemble \/monorepo \/monorepo/);
+  assert.doesNotMatch(final, /COPY --from=assemble \/monorepo \/monorepo/);
   assert.match(dockerfile, /USER node\nRUN --mount=\S+ \\\n {2}NODE_ENV=production node \/opt\/xema-composed-image\/src\/composed-image\.mjs load --each\n/);
   assert.match(dockerfile, /cp \/opt\/xema-composed-image\/src\/composed-migrate\.mjs \/monorepo\/xema-composed-migrate\.mjs/);
 });
@@ -101,3 +101,16 @@ test('a token-using repository gets single-backslash line continuations (a doubl
   assert.match(dockerfile, /--mount=type=secret,id=npm_token,required=true \\\n/);
   for (const line of dockerfile.split('\n')) assert.doesNotMatch(line, /\\\\\s*$/, `line ends with a doubled backslash: ${line}`);
 });
+
+test('the final stage is layered: deps, then assemble without the .pnpm store, then the injected copies', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  const final = dockerfile.split('\nFROM base\n')[1];
+  const copies = final.split('\n').filter((line) => line.startsWith('COPY '));
+  assert.deepEqual(copies, [
+    'COPY --from=deps /monorepo /monorepo',
+    'COPY --from=assemble --exclude=node_modules/.pnpm /monorepo /monorepo',
+    'COPY --from=assemble --parents /monorepo/node_modules/.pnpm/*@file+* /',
+  ]);
+  assert.ok(final.indexOf('ENV NODE_ENV=production') > final.lastIndexOf('COPY --from=assemble'));
+  assert.match(final, /USER node\nCMD \["node", "\/monorepo\/xema-composed-process"\]\n$/);
+});

package/src/composed-image-stage.mjs

@@ -3,7 +3,8 @@
 // directory the `--prebuilt` Dockerfile copies from. Docker compiles nothing; this
 // is the only place outputs enter an image, so it is also where they are refused.
 //
-//   <dir>/out/<package dir>/<output>/               every closure package's outputs (default: dist)
+//   <dir>/out/<package dir>/<output>/               every closure package's outputs (default: dist);
+//                                                   `--also <pkg>` adds that package's closure (no member checks)
 //   <dir>/out/<member>/node_modules/.prisma/        every member's generated Prisma clients
 //   <dir>/tool/                                     this package (package.json + src, no tests):
 //                                                   bind-mounted into the build, never copied into a layer
@@ -65,6 +66,7 @@ export async function stageBuildOutputs({
   imageDir = COMPOSED_IMAGE_DIR,
   dir,
   outputs = DEFAULT_OUTPUTS,
+  also = [],
   exec,
   nodeMajor = process.versions.node.split('.')[0],
   formatSpawn,
@@ -90,7 +92,7 @@ export async function stageBuildOutputs({
 
   const members = readMembers({ root, imageDir }).map(([key, directory]) => ({ key, directory }));
   const memberDirectories = new Set(members.map((m) => m.directory));
-  const closure = memberClosure({ root, imageDir, exec });
+  const closure = memberClosure({ root, imageDir, exec, also });
   const schemaJobs = [];
   for (const { key, directory } of members) {
     if (!closure.includes(directory)) problems.push(`${key}: ${directory} is not in the closure pnpm selected`);

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

@@ -100,3 +100,54 @@ test('refuses a client generated from another schema than the member carries; th
   await assert.rejects(stage(stale), /alpha-db-api: .*differs from the member's prisma\/schema\.prisma .*stale/);
   assert.equal((await stage(ready())).packages, 3);
 });
+
+/** An `exec` that answers per-name probes (`--filter <name>`) and the closure listing (`--filter <name>...`). */
+function alsoPnpm(root, known) {
+  return (_file, args) => {
+    const filters = args.flatMap((a, i) => (args[i - 1] === '--filter' ? [a] : []));
+    const names = filters.filter((f) => !f.endsWith('...'));
+    if (names.length > 0) return JSON.stringify(known.filter((p) => p.name === names[0]).map((p) => ({ name: p.name, path: path.join(root, p.dir) })));
+    const wanted = new Set(filters.map((f) => f.slice(0, -3)));
+    const dirs = new Set(['biomes/alpha/api/alpha-api', 'biomes/alpha/api/alpha-db-api', 'packages/sdks/lib-a']);
+    for (const p of known) if (wanted.has(p.name)) for (const d of p.closure) dirs.add(d);
+    return JSON.stringify([...dirs].map((dir) => ({ name: dir, path: path.join(root, dir) })));
+  };
+}
+const EXTRA = [{ name: '@t/extra', dir: 'packages/sdks/extra', closure: ['packages/sdks/extra', 'packages/sdks/extra-dep'] },
+  { name: '@t/lib-a', dir: 'packages/sdks/lib-a', closure: ['packages/sdks/lib-a'] }];
+
+function withExtra() {
+  const root = ready();
+  write(root, 'packages/sdks/extra/package.json', { name: '@t/extra' });
+  write(root, 'packages/sdks/extra/dist/index.js', '// extra\n');
+  write(root, 'packages/sdks/extra-dep/dist/index.js', '// dep\n');
+  return root;
+}
+
+test('--also stages the named package closure without member checks, and a member named again is idempotent', async () => {
+  const root = withExtra();
+  const result = await stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra', '@t/lib-a'] });
+  assert.equal(result.packages, 5);
+  const staged = files(path.join(root, '.xema-stage/out'));
+  for (const expected of ['packages/sdks/extra/dist/index.js', 'packages/sdks/extra-dep/dist/index.js', 'packages/sdks/lib-a/dist/index.js']) {
+    assert.ok(staged.includes(expected), expected);
+  }
+  assert.ok(!staged.some((f) => f.startsWith('packages/sdks/extra/node_modules')));
+});
+
+test('--also refuses an unknown package and a native addon in the extra closure', async () => {
+  const root = withExtra();
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/nope'] }), /--also @t\/nope: no workspace package/);
+  assert.equal(fs.existsSync(path.join(root, '.xema-stage')), false);
+  write(root, 'packages/sdks/extra-dep/dist/a.node', 'x');
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /extra-dep\/dist\/a\.node/);
+});
+
+test('filters and the argument parser carry --also', async () => {
+  const root = ready();
+  const { memberFilters } = await import('./composed-image-members.mjs');
+  const { parseArguments } = await import('./composed-image.mjs');
+  assert.deepEqual(memberFilters({ root, also: ['@t/extra', '@t/lib-a', '@t/extra'] }).slice(-2), ['--filter @t/extra...', '--filter @t/lib-a...']);
+  assert.equal(memberFilters({ root, also: ['@t/alpha-api'] }).filter((f) => f === '--filter @t/alpha-api...').length, 1);
+  assert.deepEqual(parseArguments(['stage', 'd', '--also', 'a', '--also', 'b']).options.also, ['a', 'b']);
+});

package/src/composed-image.mjs

@@ -24,7 +24,8 @@
 //            derive the member set and write / verify
 //            `<image-dir>/image-build-inputs.json` (its existence at a commit IS
 //            the repository's composed-process declaration).
-//   filters  print `--filter <package>...` for every member, so install and
+//   filters [--also <pkg>]…
+//            print `--filter <package>...` for every member (and each --also package), so install and
 //            build cover exactly the members' closures.
 //   dirs     print every member's directory, one per line.
 //   pins <committed-lockfile>
@@ -38,10 +39,11 @@
 //   load --each
 //            the same check, one `node` process PER member, so a member that only
 //            loads because another loaded first is caught (the prebuilt image's gate).
-//   stage <dir> [--output <rel>]…
+//   stage <dir> [--output <rel>]… [--also <pkg>]…
 //            gather the runner's build outputs (default `dist`) and the members'
 //            generated Prisma clients into a build-step directory, with this tool,
-//            for the `--prebuilt` Dockerfile (`composed-image-stage.mjs`).
+//            for the `--prebuilt` Dockerfile (`composed-image-stage.mjs`). Each `--also`
+//            workspace package adds its closure's built outputs (no Prisma checks).
 //   sync-injected | prisma-check
 //            IN-IMAGE proofs of the prebuilt build: the injected workspace copies hold
 //            their packages' `files`; every Prisma client runs on the target arch.
@@ -53,8 +55,9 @@
 //            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
-//            (`composed-image-coordinate.mjs`; environment-driven, GITHUB_OUTPUT).
+//            `xema-compute-image-tag`) and its cross-repository pin count; pure, no
+//            registry probe or credential (`composed-image-coordinate.mjs`;
+//            environment-driven, GITHUB_OUTPUT).
 //   smoke-refusal <image> [--member <biomeId>/<componentKey>]x2
 //            boot the pushed image with a declaration the host must refuse
 //            (`smoke-refusal.mjs`).
@@ -93,7 +96,7 @@ 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 './registry-fetch.mjs';
+import { describeErrorChain } from '@xemahq/release-policy/registry';
 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';
@@ -454,18 +457,18 @@ export function loadMembersEach({ root = process.cwd(), imageDir = COMPOSED_IMAG
 const USAGE =
   'usage: xema-composed-image <command> [--root <dir>] [--image-dir <dir>]\n' +
   '  members --write|--check [--manifests <glob>]… [--canonical-dockerfile <path>] [--cross-repo-manifest <path>]\n' +
-  '  filters | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each]\n' +
-  '  stage <dir> [--output <rel>]…   | sync-injected | prisma-check | migrate <member> [--root <dir>]\n' +
-  '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG REGISTRY_USER REGISTRY_TOKEN [TAG_ARGS_FILE])\n' +
+  '  filters [--also <pkg>]… | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each]\n' +
+  '  stage <dir> [--output <rel>]… [--also <pkg>]…   | sync-injected | prisma-check | migrate <member> [--root <dir>]\n' +
+  '  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>]';
 
-const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output']);
+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',
+  'image-name', 'tooling-version', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also',
 ]);
 
 export function parseArguments(argv) {
@@ -518,7 +521,7 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
       return;
     }
     case 'filters':
-      write(`${memberFilters({ root, imageDir }).join(' ')}\n`);
+      write(`${memberFilters({ root, imageDir, also: options.also }).join(' ')}\n`);
       return;
     case 'dirs':
       write(`${readMembers({ root, imageDir }).map(([, directory]) => directory).join('\n')}\n`);
@@ -541,7 +544,7 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
       log(`composed members: all ${loadMembers({ root, imageDir })} module graph(s) load`);
       return;
     case 'stage': {
-      return stageBuildOutputs({ root, imageDir, dir: argument, outputs: options.output }).then((staged) => {
+      return stageBuildOutputs({ root, imageDir, dir: argument, outputs: options.output, also: options.also }).then((staged) => {
         log(`composed stage ${argument}: ${staged.packages} package(s), ${staged.outputs} output dir(s), ${staged.files} file(s), tool ${staged.toolFiles} file(s)`);
       });
     }
@@ -556,9 +559,8 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
 
     }
     case 'coordinate':
-      return composedCoordinate({ root, imageDir, imageName: options['image-name'] }).then((outputs) =>
-        emitCoordinate(outputs, { log }),
-      );
+      emitCoordinate(composedCoordinate({ root, imageDir, imageName: options['image-name'] }), { log });
+      return;
     case 'load-image':
       runImageLoad({ image: argument, log });
       return;

package/src/composed-image.test.mjs

@@ -238,12 +238,12 @@ test('the bin runs through a symlink, as npm installs it, and exits non-zero on
   );
 });
 
-test('the new commands parse their options; coordinate is asynchronous and refuses without an image name', async () => {
+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']);
   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']);
-  await assert.rejects(main(['coordinate'], { log() {} }), /--image-name/);
+  assert.throws(() => main(['coordinate'], { log() {} }), /--image-name/);
   assert.throws(() => main(['dockerfile', '--write'], { log() {} }), /exact x\.y\.z/);
   assert.throws(() => main(['smoke-refusal'], { log() {} }), /usage/);
 });

package/src/ghcr-manifest.mjs

@@ -1,72 +0,0 @@
-// Is a content-addressed image coordinate already in GHCR? Shared by every
-// repository that plans a build from a content tag (service matrix, composed image).
-//
-// Only 200 and 404 are answers; anything else throws, so an unreachable or
-// unauthorised registry can never read as "missing" and trigger a rebuild.
-
-import { registryFetch } from './registry-fetch.mjs';
-
-const MANIFEST_ACCEPT = [
-  'application/vnd.oci.image.index.v1+json',
-  'application/vnd.oci.image.manifest.v1+json',
-  'application/vnd.docker.distribution.manifest.list.v2+json',
-  'application/vnd.docker.distribution.manifest.v2+json',
-].join(', ');
-
-function assertNonEmpty(value, label) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${label} is missing or empty`);
-  }
-  return value;
-}
-
-function basicAuthorization(user, token) {
-  return `Basic ${Buffer.from(`${user}:${token}`, 'utf8').toString('base64')}`;
-}
-
-/**
- * Acquire a pull-only GHCR bearer token for one repository.
- *
- * The endpoint is deliberately fixed to the configured GHCR host. Following a
- * challenge-provided realm while carrying the long-lived credential would let
- * an untrusted/misconfigured registry redirect that credential elsewhere.
- */
-export async function acquireGhcrPullToken({ registry, repository, user, token, fetchImpl = fetch }) {
-  if (registry !== 'ghcr.io') {
-    throw new Error(`GHCR manifest check cannot send credentials to registry '${registry}'`);
-  }
-  assertNonEmpty(user, 'REGISTRY_USER');
-  assertNonEmpty(token, 'REGISTRY_TOKEN');
-  const url = new URL(`https://${registry}/token`);
-  url.searchParams.set('service', registry);
-  url.searchParams.set('scope', `repository:${repository}:pull`);
-  const response = await registryFetch(fetchImpl, url, {
-    method: 'GET',
-    headers: { Authorization: basicAuthorization(user, token), Accept: 'application/json' },
-  });
-  if (response.status !== 200) {
-    throw new Error(`${registry}: pull-token request for ${repository} returned HTTP ${response.status}`);
-  }
-  let body;
-  try {
-    body = await response.json();
-  } catch {
-    throw new Error(`${registry}: pull-token response for ${repository} was not JSON`);
-  }
-  if (typeof body?.token !== 'string' || body.token.length === 0) {
-    throw new Error(`${registry}: pull-token response for ${repository} contained no token`);
-  }
-  return body.token;
-}
-
-/** Returns `true` only for a proven existing manifest and `false` only for 404. */
-export async function ghcrManifestExists({ registry, repository, contentHash, user, token, fetchImpl = fetch }) {
-  const bearer = await acquireGhcrPullToken({ registry, repository, user, token, fetchImpl });
-  const response = await registryFetch(fetchImpl, `https://${registry}/v2/${repository}/manifests/${contentHash}`, {
-    method: 'HEAD',
-    headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
-  });
-  if (response.status === 200) return true;
-  if (response.status === 404) return false;
-  throw new Error(`${registry}: manifest lookup for ${repository}:${contentHash} returned HTTP ${response.status}`);
-}

package/src/ghcr-manifest.test.mjs

@@ -1,96 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-
-import { acquireGhcrPullToken, ghcrManifestExists } from './ghcr-manifest.mjs';
-
-const HASH = 'a'.repeat(64);
-const COMMON = { registry: 'ghcr.io', repository: 'xema-dev/alpha-api', user: 'runner', token: 'secret' };
-
-function response(status, body) {
-  return {
-    status,
-    async json() {
-      if (body instanceof Error) throw body;
-      return body;
-    },
-  };
-}
-
-test('a pull token is requested with the exact repository scope', async () => {
-  let captured;
-  const token = await acquireGhcrPullToken({
-    ...COMMON,
-    fetchImpl: async (url, init) => {
-      captured = { url: String(url), init };
-      return response(200, { token: 'bearer-token' });
-    },
-  });
-  assert.equal(token, 'bearer-token');
-  const url = new URL(captured.url);
-  assert.equal(url.origin + url.pathname, 'https://ghcr.io/token');
-  assert.equal(url.searchParams.get('service'), 'ghcr.io');
-  assert.equal(url.searchParams.get('scope'), 'repository:xema-dev/alpha-api:pull');
-  assert.equal(captured.init.method, 'GET');
-  assert.match(captured.init.headers.Authorization, /^Basic /);
-});
-
-test('the long-lived credential can only be sent to GHCR', async () => {
-  let called = false;
-  await assert.rejects(
-    acquireGhcrPullToken({
-      ...COMMON,
-      registry: 'registry.example.com',
-      fetchImpl: async () => {
-        called = true;
-        return response(200, { token: 'bearer-token' });
-      },
-    }),
-    /cannot send credentials/,
-  );
-  assert.equal(called, false);
-});
-
-test('a missing credential is refused before any request', async () => {
-  await assert.rejects(acquireGhcrPullToken({ ...COMMON, token: '', fetchImpl: async () => assert.fail('requested') }), /REGISTRY_TOKEN/);
-});
-
-test('token acquisition fails closed on every uncertain response', async () => {
-  for (const status of [401, 403, 404, 429, 500]) {
-    await assert.rejects(acquireGhcrPullToken({ ...COMMON, fetchImpl: async () => response(status, {}) }), new RegExp(`HTTP ${status}`));
-  }
-  for (const body of [{}, { token: '' }, new Error('invalid json')]) {
-    await assert.rejects(acquireGhcrPullToken({ ...COMMON, fetchImpl: async () => response(200, body) }), /token response/);
-  }
-});
-
-test('only authenticated 200 and 404 are classified', async () => {
-  for (const [status, expected] of [[200, true], [404, false]]) {
-    const calls = [];
-    const exists = await ghcrManifestExists({
-      ...COMMON,
-      contentHash: HASH,
-      fetchImpl: async (url, init) => {
-        calls.push({ url: String(url), init });
-        return calls.length === 1 ? response(200, { token: 'bearer-token' }) : response(status, {});
-      },
-    });
-    assert.equal(exists, expected);
-    assert.equal(calls[1].url, `https://ghcr.io/v2/xema-dev/alpha-api/manifests/${HASH}`);
-    assert.equal(calls[1].init.method, 'HEAD');
-    assert.equal(calls[1].init.headers.Authorization, 'Bearer bearer-token');
-  }
-  for (const status of [401, 403, 429, 500]) {
-    let count = 0;
-    await assert.rejects(
-      ghcrManifestExists({
-        ...COMMON,
-        contentHash: HASH,
-        fetchImpl: async () => {
-          count += 1;
-          return count === 1 ? response(200, { token: 'bearer-token' }) : response(status, {});
-        },
-      }),
-      new RegExp(`HTTP ${status}`),
-    );
-  }
-});

package/src/registry-fetch.mjs

@@ -1,82 +0,0 @@
-// The one place a registry request is sent and a network failure is named.
-//
-// Node's fetch rejects with `TypeError: fetch failed` and keeps the real reason
-// (ENOTFOUND, ECONNREFUSED, a TLS error, a timeout) in `error.cause`. Letting that
-// escape as a bare message hides which request failed and why.
-
-/** The URL with credentials and every query value removed; only the query keys remain. */
-export function redactUrl(input) {
-  let url;
-  try {
-    url = new URL(String(input));
-  } catch {
-    return '<unparseable url>';
-  }
-  url.username = '';
-  url.password = '';
-  const keys = [...new Set(url.searchParams.keys())];
-  url.search = '';
-  url.hash = '';
-  return keys.length > 0 ? `${url.href}?${keys.map((key) => `${key}=<redacted>`).join('&')}` : url.href;
-}
-
-function describeOne(error) {
-  if (!(error instanceof Error)) return String(error);
-  const details = ['code', 'errno', 'syscall', 'hostname', 'address', 'port']
-    .filter((key) => error[key] !== undefined)
-    .map((key) => `${key}=${error[key]}`);
-  const head = `${error.name}: ${error.message}`;
-  return details.length > 0 ? `${head} (${details.join(', ')})` : head;
-}
-
-/** One line per link of the `cause` chain, outermost first. Bounded against cycles. */
-export function describeErrorChain(error) {
-  const lines = [];
-  const seen = new Set();
-  for (let current = error; current !== undefined && !seen.has(current) && lines.length < 10; ) {
-    lines.push(describeOne(current));
-    if (!(current instanceof Error)) break;
-    seen.add(current);
-    current = current.cause;
-  }
-  return lines;
-}
-
-/** Total attempts per request, the first included. */
-export const MAX_ATTEMPTS = 3;
-/** Fixed wait in milliseconds after failed attempt n (1-based); deterministic, no jitter. */
-export const RETRY_BACKOFF_MS = [1000, 3000];
-
-const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-function causeCode(error) {
-  for (let current = error, depth = 0; current instanceof Error && depth < 10; current = current.cause, depth += 1) {
-    if (current.code !== undefined) return String(current.code);
-  }
-  return 'unknown';
-}
-
-/**
- * Send one registry request. Only a transport failure (the fetch promise rejects) is
- * retried (an abort, `AbortError` or an aborted `init.signal`, is rethrown at once), up to MAX_ATTEMPTS with RETRY_BACKOFF_MS between attempts; any HTTP response,
- * whatever its status, is returned as is. The final failure is thrown naming the method,
- * the redacted URL and the attempt count, with the last error as `cause`. Headers are
- * never reported. `options.sleep` replaces the real wait (for tests).
- */
-export async function registryFetch(fetchImpl, url, init, { sleep = realSleep } = {}) {
-  const method = init?.method ?? 'GET';
-  for (let attempt = 1; ; attempt += 1) {
-    try {
-      return await fetchImpl(url, init);
-    } catch (error) {
-      if (error?.name === 'AbortError' || init?.signal?.aborted === true) throw error;
-      if (attempt >= MAX_ATTEMPTS) {
-        throw new Error(`${method} ${redactUrl(url)} failed after ${attempt} attempts`, { cause: error });
-      }
-      process.stderr.write(
-        `registry request failed (attempt ${attempt} of ${MAX_ATTEMPTS}): ${method} ${redactUrl(url)} cause=${causeCode(error)}; retrying\n`,
-      );
-      await sleep(RETRY_BACKOFF_MS[attempt - 1]);
-    }
-  }
-}

package/src/registry-fetch.test.mjs

@@ -1,151 +0,0 @@
-import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import net from 'node:net';
-import os from 'node:os';
-import path from 'node:path';
-import test from 'node:test';
-import { fileURLToPath } from 'node:url';
-
-import { MAX_ATTEMPTS, RETRY_BACKOFF_MS, describeErrorChain, redactUrl, registryFetch } from './registry-fetch.mjs';
-
-const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), 'composed-image.mjs');
-
-async function closedPort() {
-  const server = net.createServer();
-  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
-  const { port } = server.address();
-  await new Promise((resolve) => server.close(resolve));
-  return port;
-}
-
-test('redactUrl drops credentials, query values and the fragment', () => {
-  const out = redactUrl('https://user:pw@ghcr.io/token?service=ghcr.io&scope=secret-scope#frag');
-  assert.equal(out, 'https://ghcr.io/token?service=<redacted>&scope=<redacted>');
-  assert.equal(redactUrl('not a url'), '<unparseable url>');
-});
-
-test('a refused connection names the method, the URL and the cause code, never the headers', async () => {
-  const port = await closedPort();
-  const url = `http://127.0.0.1:${port}/v2/org/img/manifests/abc?access_token=SECRETQ`;
-  const error = await registryFetch(fetch, url, { method: 'HEAD', headers: { Authorization: 'Bearer SECRETH' } }, { sleep: async () => {} }).then(
-    () => assert.fail('expected the request to fail'),
-    (caught) => caught,
-  );
-  const text = [error.message, ...describeErrorChain(error)].join('\n');
-  assert.match(error.message, new RegExp(`^HEAD http://127\\.0\\.0\\.1:${port}/v2/org/img/manifests/abc\\?access_token=<redacted> failed after 3 attempts$`));
-  assert.match(text, /ECONNREFUSED/);
-  assert.doesNotMatch(text, /SECRETQ|SECRETH/);
-});
-
-test('describeErrorChain walks the cause chain and survives a cycle', () => {
-  const inner = Object.assign(new Error('getaddrinfo ENOTFOUND ghcr.io'), { code: 'ENOTFOUND', hostname: 'ghcr.io' });
-  const outer = new TypeError('fetch failed', { cause: inner });
-  inner.cause = outer;
-  const lines = describeErrorChain(outer);
-  assert.equal(lines.length, 2);
-  assert.match(lines[1], /code=ENOTFOUND, hostname=ghcr\.io/);
-});
-
-test('the CLI prints the failing request and the cause chain to stderr and exits 1', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fetch-cause-'));
-  try {
-    const hashDir = path.join(root, 'node_modules', '@xemahq', 'distribution-source-hash');
-    fs.mkdirSync(hashDir, { recursive: true });
-    fs.writeFileSync(
-      path.join(hashDir, 'package.json'),
-      JSON.stringify({ name: '@xemahq/distribution-source-hash', bin: { 'xema-compute-image-tag': 'bin.js' } }),
-    );
-    fs.writeFileSync(path.join(hashDir, 'bin.js'), `console.log('${'a'.repeat(64)}');\n`);
-    fs.writeFileSync(path.join(root, 'package.json'), '{}');
-    const preload = path.join(root, 'preload.mjs');
-    fs.writeFileSync(
-      preload,
-      `globalThis.fetch = async () => { throw new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo ENOTFOUND ghcr.io'), { code: 'ENOTFOUND', hostname: 'ghcr.io' }) }); };\n`,
-    );
-    const result = spawnSync(process.execPath, ['--import', preload, BIN, 'coordinate', '--image-name', 'img'], {
-      cwd: root,
-      encoding: 'utf8',
-      env: {
-        PATH: process.env.PATH,
-        SHA: 'b'.repeat(40),
-        REGISTRY: 'ghcr.io',
-        REGISTRY_ORG: 'org',
-        REGISTRY_USER: 'u',
-        REGISTRY_TOKEN: 'TOPSECRET',
-      },
-    });
-    assert.equal(result.status, 1);
-    assert.match(result.stderr, /GET https:\/\/ghcr\.io\/token\?service=<redacted>&scope=<redacted> failed after 3 attempts/);
-    assert.match(result.stderr, /caused by TypeError: fetch failed/);
-    assert.match(result.stderr, /caused by Error: getaddrinfo ENOTFOUND ghcr\.io \(code=ENOTFOUND, hostname=ghcr\.io\)/);
-    assert.doesNotMatch(result.stderr, /TOPSECRET/);
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-const transportError = () =>
-  new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo EAI_AGAIN ghcr.io'), { code: 'EAI_AGAIN' }) });
-
-test('a transient transport failure is retried once and then returns the response', async () => {
-  let calls = 0;
-  const waits = [];
-  const response = new Response('ok', { status: 200 });
-  const fetchImpl = async () => {
-    calls += 1;
-    if (calls === 1) throw transportError();
-    return response;
-  };
-  const result = await registryFetch(fetchImpl, 'https://ghcr.io/token?scope=x', { method: 'GET' }, { sleep: async (ms) => waits.push(ms) });
-  assert.equal(calls, 2);
-  assert.equal(result, response);
-  assert.deepEqual(waits, [RETRY_BACKOFF_MS[0]]);
-});
-
-test('three transport failures throw naming 3 attempts and keep the cause chain', async () => {
-  let calls = 0;
-  const waits = [];
-  const fetchImpl = async () => {
-    calls += 1;
-    throw transportError();
-  };
-  const error = await registryFetch(fetchImpl, 'https://ghcr.io/v2/o/i/manifests/a', { method: 'HEAD' }, { sleep: async (ms) => waits.push(ms) }).then(
-    () => assert.fail('expected failure'),
-    (caught) => caught,
-  );
-  assert.equal(calls, MAX_ATTEMPTS);
-  assert.deepEqual(waits, [1000, 3000]);
-  assert.equal(error.message, 'HEAD https://ghcr.io/v2/o/i/manifests/a failed after 3 attempts');
-  assert.match(describeErrorChain(error).join('\n'), /fetch failed[\s\S]*code=EAI_AGAIN/);
-});
-
-test('an HTTP error status is returned after one call, never retried', async () => {
-  let calls = 0;
-  const fetchImpl = async () => {
-    calls += 1;
-    return new Response('down', { status: 503 });
-  };
-  const result = await registryFetch(fetchImpl, 'https://ghcr.io/token', { method: 'GET' }, { sleep: async () => assert.fail('must not sleep') });
-  assert.equal(calls, 1);
-  assert.equal(result.status, 503);
-});
-
-test('an abort is rethrown at once, never retried', async () => {
-  let calls = 0;
-  const controller = new AbortController();
-  controller.abort();
-  const fetchImpl = async () => {
-    calls += 1;
-    throw new Error('request failed');
-  };
-  const error = await registryFetch(fetchImpl, 'https://ghcr.io/token', { method: 'GET', signal: controller.signal }, { sleep: async () => assert.fail('must not sleep') }).then(
-    () => assert.fail('expected failure'),
-    (caught) => caught,
-  );
-  assert.equal(calls, 1);
-  assert.equal(error.message, 'request failed');
-  let named = 0;
-  await registryFetch(async () => { named += 1; throw new DOMException('aborted', 'AbortError'); }, 'https://ghcr.io/token', {}, { sleep: async () => assert.fail('must not sleep') }).catch(() => {});
-  assert.equal(named, 1);
-});