@xemahq/repo-build-tooling 0.25.0 → 0.25.1

package/README.md

@@ -37,7 +37,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents, and `test` and `openapi:current` (where defined) only on the packages the push changed; a fleet-wide change runs only `lint` and `typecheck` on the full graph; root `lint` only without turbo; a park-only push (`refs/xema-session/*`) skips |
 | `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 `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source` and `--base <ref@sha256:…>`, the digest-pinned image the stages start FROM; a reference without a digest is refused; `--copy` and `--stage-dir` optional). The assemble stage copies per package only `package.json` and its plain `files` entries (what `pnpm pack` ships), so a README or test edit changes no image; a package without a `files` array or with a glob entry is refused; `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. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`, `--base <ref@sha256:…>`, the digest-pinned image the stages start FROM (a reference without a digest is refused), and `--node-major <n>`, that base's Node major, rendered as the `dev.xema.composed-image.node-major` label, which `stage` compares with the runner's Node; `--copy` and `--stage-dir` optional). The assemble stage copies per package only `package.json` and its plain `files` entries (what `pnpm pack` ships), so a README or test edit changes no image; a package without a `files` array or with a glob entry is refused; `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. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -54,6 +54,6 @@
     "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs && node --test src/service-image.test.mjs && node --test src/install-git-hooks.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:60086692452e7d72167195fe99ab5634a798fd8b2461a6e0b09bb27b894b7aa4"
+    "sourceDigest": "sha256:d6fa7e246feba0804afe8de72c9ef8286cfd3a9517d5e7dca81a9fec1b3c127a"
   }
 }

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

@@ -28,7 +28,7 @@ function renderedEntries() {
     root,
     copy: ['tooling/dev'],
     cacheId: 'alpha-composed-process',
-    buildSource: 'alpha', base: BASE,
+    buildSource: 'alpha', base: BASE, nodeMajor: '22',
     usesToken: true,
     exec: fakePnpm(root),
   });

package/src/composed-image-paths.mjs

@@ -3,3 +3,6 @@ export const COMPOSED_IMAGE_DIR = 'infra/composed-process';
 
 // The one entry the prebuilt image runs from the bind-mounted tool directory: loads only `node:` and relative modules.
 export const IN_IMAGE_ENTRY = 'src/composed-image-in-image.mjs';
+
+/** The image label that carries the Node major of the pinned base: a digest reference does not name it, and the stage compares the runner's Node with it. */
+export const NODE_MAJOR_LABEL = 'dev.xema.composed-image.node-major';

package/src/composed-image-pnpm-context.test.mjs

@@ -13,7 +13,7 @@ function setup({ store = true, cache = true } = {}) {
   write(root, 'package.json', { name: 'r', packageManager: 'pnpm@10.33.0+sha512.abc' });
   write(root, 'pnpm-lock.yaml', 'lockfileVersion: 9\n');
   write(root, 'tooling/dev/x.txt', 'x');
-  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) }).dockerfile);
+  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', base: BASE, nodeMajor: '22', usesToken: false, exec: fakePnpm(root) }).dockerfile);
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-home-'));
   const storePath = path.join(home, '.pnpm-store', 'v10');
   const cacheDir = path.join(home, 'cache');
@@ -89,7 +89,7 @@ test('the lockfile-only command is the one the generated Dockerfile runs (no dri
   assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--offline']);
   assert.equal(lockfileOnlyCommand(['--filter', 'x'], { offline: false })[3], '--prefer-offline');
   assert.ok(words.includes('--config.inject-workspace-packages=true') && words.includes('--config.dedupe-injected-deps=false'));
-  const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) });
+  const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', base: BASE, nodeMajor: '22', usesToken: false, exec: fakePnpm(root) });
   assert.ok(text.includes('pnpm install --lockfile-only --offline ${INJECT} --filter @t/alpha-api... --filter @t/alpha-db-api... &&'));
   assert.ok(text.includes('INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false"'));
 });

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

@@ -7,7 +7,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix } from 'node:path';
 
-import { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY } from './composed-image-paths.mjs';
+import { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY, NODE_MAJOR_LABEL } from './composed-image-paths.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
 import { npmrcUsesToken } from './composed-image-dockerfile.mjs';
 import { IGNORED_DIRECTORIES, IGNORED_FILE_PATTERNS, packageSources } from './composed-image-package-files.mjs';
@@ -20,7 +20,10 @@ const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
 const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
 const DIGEST_REFERENCE = /^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9._-]+)?@sha256:[0-9a-f]{64}$/;
 
-function validate({ copy, cacheId, buildSource, stageDir, base }) {
+const NODE_MAJOR = /^[1-9][0-9]*$/;
+
+function validate({ copy, cacheId, buildSource, stageDir, base, nodeMajor }) {
+  if (!NODE_MAJOR.test(nodeMajor ?? '')) throw new Error(`--node-major must be the Node major of the --base image (e.g. 22), got "${nodeMajor}"`);
   if (!DIGEST_REFERENCE.test(base ?? '')) throw new Error(`--base must be an image reference pinned by digest (<ref>@sha256:<64 hex>), got "${base}"`);
   for (const directory of [...(copy ?? []), stageDir]) {
     if (!DIRECTORY.test(directory) || directory.startsWith('/') || directory.split('/').includes('..')) {
@@ -175,11 +178,12 @@ export function renderPrebuiltDockerfile({
   usesToken,
   stageDir = DEFAULT_STAGE_DIR,
   base,
+  nodeMajor,
   exec,
   prodPackages = [],
 }) {
   if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
-  validate({ copy, cacheId, buildSource, stageDir, base });
+  validate({ copy, cacheId, buildSource, stageDir, base, nodeMajor });
   const toolingVersion = toolVersion();
   const workspaceFile = join(root, 'pnpm-workspace.yaml');
   const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
@@ -309,6 +313,7 @@ RUN ${toolMount} \\
 #                keeps their paths under /.
 FROM base
 WORKDIR /monorepo
+LABEL ${NODE_MAJOR_LABEL}="${nodeMajor}"
 COPY --from=deps /monorepo /monorepo
 COPY --from=assemble --exclude=node_modules/.pnpm /monorepo /monorepo
 COPY --from=assemble --parents /monorepo/node_modules/.pnpm/*@file+* /

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

@@ -17,7 +17,7 @@ function installed(root, name, { gyp = false, optional = {} } = {}) {
 }
 
 function options(root, extra = {}) {
-  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', base: BASE, usesToken: true, exec: fakePnpm(root), prodPackages: [], ...extra };
+  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', base: BASE, nodeMajor: '22', usesToken: true, exec: fakePnpm(root), prodPackages: [], ...extra };
 }
 
 test('the closure comes from pnpm ls with the members filters, and the filters are literal per member', () => {
@@ -233,3 +233,11 @@ test('--check fails when the rendered base or a files entry changed', () => {
   fs.writeFileSync(path.join(root, 'packages/sdks/lib-a/package.json'), JSON.stringify({ name: '@t/lib-a', files: ['dist', 'assets/data.json', 'extra'] }));
   assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root) }), /Dockerfile is stale/);
 });
+
+test('the Node major is a required, rendered fact of the digest-pinned base, and the render carries it as a label', () => {
+  const root = workspace();
+  assert.throws(() => renderPrebuiltDockerfile(options(root, { nodeMajor: undefined })), /--node-major/);
+  assert.throws(() => renderPrebuiltDockerfile(options(root, { nodeMajor: '22.1' })), /--node-major/);
+  const { dockerfile } = renderPrebuiltDockerfile(options(root));
+  assert.match(dockerfile, /^LABEL dev\.xema\.composed-image\.node-major="22"$/m);
+});

package/src/composed-image-stage.mjs

@@ -16,7 +16,7 @@ import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSy
 import { dirname, join, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { COMPOSED_IMAGE_DIR, NODE_MAJOR_LABEL } from './composed-image-paths.mjs';
 import { memberClosure, readMembers } from './composed-image-members.mjs';
 import { clientSchemaProblems, memberPrismaSchema } from './composed-migrate.mjs';
 
@@ -80,10 +80,10 @@ export async function stageBuildOutputs({
 
   const problems = [];
   const dockerfile = renderedDockerfile(root, imageDir);
-  const fromNode = /^FROM\s+\S*node:(\d+)[-@\s]/m.exec(dockerfile);
-  if (fromNode === null) problems.push(`${imageDir}/Dockerfile has no base FROM …node:<major>-…`);
-  else if (fromNode[1] !== String(nodeMajor)) {
-    problems.push(`the runner's Node ${nodeMajor} differs from the image's Node ${fromNode[1]} (${imageDir}/Dockerfile)`);
+  const declared = new RegExp(`^LABEL ${NODE_MAJOR_LABEL.replaceAll('.', '\\.')}="(\\d+)"$`, 'm').exec(dockerfile);
+  if (declared === null) problems.push(`${imageDir}/Dockerfile declares no base Node major (LABEL ${NODE_MAJOR_LABEL}): render it with --node-major`);
+  else if (declared[1] !== String(nodeMajor)) {
+    problems.push(`the runner's Node ${nodeMajor} differs from the image's Node ${declared[1]} (${imageDir}/Dockerfile)`);
   }
   const pinned = /@xemahq\/repo-build-tooling@(\d+\.\d+\.\d+)/.exec(dockerfile);
   if (pinned === null) problems.push(`${imageDir}/Dockerfile header pins no @xemahq/repo-build-tooling@<x.y.z>`);

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

@@ -8,7 +8,7 @@ import { fakePnpm, formatNoop, workspace, write } from './composed-image-fixture
 
 function ready(extra = {}) {
   const root = workspace(extra);
-  write(root, 'infra/composed-process/Dockerfile', `# @generated (@xemahq/repo-build-tooling@${toolVersion()})\nFROM mirror.gcr.io/library/node:22-bookworm-slim@sha256:abc AS base\n`);
+  write(root, 'infra/composed-process/Dockerfile', `# @generated (@xemahq/repo-build-tooling@${toolVersion()})\nFROM ghcr.io/example/base/node-runtime@sha256:${'a'.repeat(64)} AS base\nLABEL dev.xema.composed-image.node-major="22"\n`);
   return root;
 }
 const stage = (root, extra = {}) => stageBuildOutputs({ root, dir: '.xema-stage', exec: fakePnpm(root), nodeMajor: '22', formatSpawn: formatNoop, ...extra });
@@ -55,18 +55,18 @@ test('refuses a member without dist/main.js and a schema without a generated cli
   await assert.rejects(stage(root), (e) => /alpha\/alpha-api: .*dist\/main\.js does not exist/.test(e.message) && /alpha-db-api: .*no node_modules\/\.prisma/.test(e.message));
 });
 
-test('refuses a runner Node major that differs from the image base, and an absent Dockerfile or FROM', async () => {
+test('refuses a runner Node major that differs from the image base, and an absent Dockerfile or Node-major label', async () => {
   const root = ready();
   await assert.rejects(stage(root, { nodeMajor: '24' }), /Node 24 differs from the image's Node 22/);
   fs.writeFileSync(path.join(root, 'infra/composed-process/Dockerfile'), `# (@xemahq/repo-build-tooling@${toolVersion()})\nFROM scratch\n`);
-  await assert.rejects(stage(root), /no base FROM/);
+  await assert.rejects(stage(root), /declares no base Node major/);
   fs.rmSync(path.join(root, 'infra/composed-process/Dockerfile'));
   await assert.rejects(stage(root), /Dockerfile is absent/);
 });
 
 test('refuses a tool version that differs from the rendered Dockerfile pin', async () => {
   const root = ready();
-  write(root, 'infra/composed-process/Dockerfile', '# (@xemahq/repo-build-tooling@0.0.1)\nFROM node:22-slim AS base\n');
+  write(root, 'infra/composed-process/Dockerfile', '# (@xemahq/repo-build-tooling@0.0.1)\nFROM ghcr.io/example/base/node-runtime@sha256:abc AS base\n');
   await assert.rejects(stage(root), /pins 0\.0\.1/);
 });
 

package/src/composed-image.mjs

@@ -72,7 +72,7 @@
 //   dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>
 //            render `<image-dir>/Dockerfile` from the package's template
 //            (`composed-image-dockerfile.mjs`).
-//   dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> [--copy <dir>]… [--stage-dir <dir>]
+//   dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> --node-major <n> [--copy <dir>]… [--stage-dir <dir>]
 //            render the Dockerfile that ASSEMBLES the image from `stage` output, and its
 //            `Dockerfile.dockerignore` (`composed-image-prebuilt-dockerfile.mjs`).
 //
@@ -328,12 +328,12 @@ const USAGE =
   '  load-image <image>\n' +
   '  smoke-refusal <image> [--member <biomeId>/<componentKey>]x2\n' +
   '  dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>\n' +
-  '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> [--copy <dir>]… [--stage-dir <dir>]';
+  '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> --node-major <n> [--copy <dir>]… [--stage-dir <dir>]';
 
 const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output', 'also', 'subject']);
 const BOOLEAN = new Set(['prebuilt', 'each']);
 const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source', 'base',
-  'image-name', 'service', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
+  'image-name', 'service', 'cache-id', 'node-major', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
 ]);
 
 export function parseArguments(argv) {
@@ -454,6 +454,7 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
           buildSource: options['build-source'],
           stageDir: options['stage-dir'],
           base: options.base,
+          nodeMajor: options['node-major'],
         });
         log(`composed prebuilt Dockerfile ${targets.join(', ')} ${options.mode === 'write' ? 'written' : 'current'}`);
         return;