@xemahq/repo-build-tooling 0.9.1 → 0.10.0

package/README.md

@@ -108,6 +108,25 @@ build carries every composable platform service of the repository at one commit.
 Every step refuses rather than skips. The tool has no dependencies: the host and
 the kernel schema are resolved from the members being built.
 
+### `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]`
+
+Generates the descriptors `@xemahq/xema-service-nest` boots from, out of the
+repository's own `xema-biome.json` manifests. For every `kind: service` component
+it writes `src/generated/<name>.bootstrap.generated.ts` (a `BiomeServiceDescriptor`),
+and for every `kind: worker` component `src/generated/<key>.worker-descriptor.generated.ts`
+(a `XemaWorkerDescriptor`; a `shared-oci-image` worker lands in the package of the
+component whose image it shares). Only packages that declare
+`@xemahq/xema-service-nest` are written to.
+
+`requirements.scaling.concurrency.maximumPerInstance` becomes
+`maximumConcurrentRequests` on a service and `maximumConcurrentActivities` on a
+worker. A component without a positive integer there is refused, naming the
+manifest and the component.
+
+`--check` writes nothing and fails on any drift. A run that finds no manifest, or no
+service or worker to generate, fails rather than reporting success. Run it from the
+repository root, or pass `--root`.
+
 ## Scope boundary
 
 Dev-time tooling that **more than one repository** runs. Two rules keep it from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -25,7 +25,8 @@
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
     "xema-readiness": "src/readiness.mjs",
-    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
+    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
+    "xema-service-bootstrap": "src/service-bootstrap.mjs"
   },
   "exports": {
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
@@ -34,12 +35,13 @@
     "./ghcr-manifest": "./src/ghcr-manifest.mjs",
     "./package.json": "./package.json",
     "./readiness": "./src/readiness.mjs",
-    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs"
+    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
+    "./service-bootstrap": "./src/service-bootstrap.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/load-image.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 && node --test src/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:b9de4f5bf70260506dc8fc6c2e2bad30aba714198303f5440888071880721d98"
+    "sourceDigest": "sha256:525d85f0cc251fa763bc18261159ae689b59c3465d9da0d3c9f6037445d68713"
   }
 }

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

@@ -70,13 +70,14 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 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';
 
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { composedCoordinate, emitCoordinate } from './composed-image-coordinate.mjs';
+import { describeErrorChain } from './registry-fetch.mjs';
 import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
 import { runImageLoad } from './load-image.mjs';
 import { runRefusalSmoke } from './smoke-refusal.mjs';
@@ -263,8 +264,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)',
@@ -551,7 +554,9 @@ if (invokedPath !== undefined && import.meta.url === pathToFileURL(invokedPath).
     // the verdict is in, so the step ends here rather than on their timers.
     process.exit(0);
   } catch (error) {
-    console.error(`xema-composed-image: ${error.message}`);
+    const [head, ...causes] = describeErrorChain(error);
+    console.error(`xema-composed-image: ${error?.message ?? head}`);
+    for (const cause of causes) console.error(`  caused by ${cause}`);
     process.exit(1);
   }
 }

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/ghcr-manifest.mjs

@@ -4,6 +4,8 @@
 // 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',
@@ -38,7 +40,7 @@ export async function acquireGhcrPullToken({ registry, repository, user, token,
   const url = new URL(`https://${registry}/token`);
   url.searchParams.set('service', registry);
   url.searchParams.set('scope', `repository:${repository}:pull`);
-  const response = await fetchImpl(url, {
+  const response = await registryFetch(fetchImpl, url, {
     method: 'GET',
     headers: { Authorization: basicAuthorization(user, token), Accept: 'application/json' },
   });
@@ -60,7 +62,7 @@ export async function acquireGhcrPullToken({ registry, repository, user, 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 fetchImpl(`https://${registry}/v2/${repository}/manifests/${contentHash}`, {
+  const response = await registryFetch(fetchImpl, `https://${registry}/v2/${repository}/manifests/${contentHash}`, {
     method: 'HEAD',
     headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
   });

package/src/registry-fetch.mjs

@@ -0,0 +1,82 @@
+// 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

@@ -0,0 +1,151 @@
+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);
+});