@xemahq/repo-build-tooling 0.10.1 → 0.11.0

package/README.md

@@ -1,138 +1,46 @@
-# `@xemahq/repo-build-tooling`
-
-This package belongs to Layer 1 — dev-time build tooling shared by every Xema
-repository. Nothing here ever ships inside a service image; every consumer
-declares it as a `devDependency`.
-
-## Why it is a package and not a file
-
-It used to be a file — five byte-identical copies of one 700-line script, one
-per repository that needed it, kept honest by a boundary check that ran each
-copy's `--self-test`.
-
-That arrangement could not hold the invariant it existed for. A defect found in
-one copy is fixed in one copy; the other four keep shipping it until someone
-remembers. Exactly that happened: three of the five copies deliberately carried
-*less* behaviour than the other two (they detected a leak shape without
-rewriting it), which was a reasonable decision at the time and then became a
-permanent, undocumented divergence nobody re-examined. A parity check on N
-copies is a workaround for not having one artifact.
-
-## How the two resolution modes work
-
-This is the standard shape in this fleet, and getting it wrong is the single
-most common source of "green locally, red in CI":
-
-- **Inside the `xema-monorepo` aggregator**, the root `package.json`'s
-  `pnpm.overrides` maps `@xemahq/repo-build-tooling` to `workspace:*`, so it
-  resolves to this directory. Editing the tool and rebuilding a service in the
-  same checkout needs no publish, no version bump and no registry round-trip.
-- **Inside each independent repository's own CI**, there is no aggregator and no
-  sibling checkout. The declared semver range is what resolves, from npm.
-
-So the range in a consumer's `package.json` is the real contract, and the local
-link is a development convenience layered on top. A symbol added here is not
-available to a consumer until this package is published AND that consumer's
-range admits the new version — the aggregator will happily compile against the
-local source and tell you nothing.
-
-## Contents
-
-### `xema-scrub-swagger-paths <dist-dir> [<dist-dir>…]`
-
-Post-build sanitizer for `@nestjs/swagger` plugin output, and the verification
-step for the same property. The plugin writes `require()` literals into
-`_OPENAPI_METADATA_FACTORY()` at `nest build` time — they exist in no source
-file — so this is the only thing in the fleet that can see them, and it runs
-immediately after `nest build` in all 54 services that use the plugin.
-
-It rewrites specifiers that name the builder's private install layout into the
-target package's public specifier, then re-reads the output from disk and fails
-the build if any leak survives.
-
-The rewrite is **derived and proved**, never tabled: the replacement comes from
-the target package's own `exports` map, and is accepted only if the emitted
-re-export chain (read statically — package code is never executed) reaches the
-same module. It refuses rather than guesses. That matters because the two
-packages that leak most are opposites — `@xemahq/kernel-contracts` exports only
-`./*` and has no root export, so rewriting to the bare name would swap one crash
-for another, while `@xemahq/platform-common` exports both `.` and `./dist/*`.
-
-`--self-test` proves, on a scratch tree with no build and no fixtures, that a
-missing/empty/no-`.js` directory each FAIL, that the detector matches every leak
-shape and no clean literal, and that a residual leak fails the run. This step's
-failure mode is silence, so "0 leaks" and "0 files read" must never be
-indistinguishable.
-
-### `xema-composed-image <command>`
-
-The build-time half of a repository's composed-process image (the runtime half,
-the `xema-composed-process` host, is `@xemahq/xema-service-nest`'s). One image per
-build carries every composable platform service of the repository at one commit.
-
-- `members --write|--check` derives that set from the tracked biome manifests and
-  writes or verifies `infra/composed-process/image-build-inputs.json`. A member is a
-  `kind: service` with `scheduler: platform`; workers, jobs and runtime-scheduled
-  services never are. A service is left out, with its reason printed, when its
-  `src/main.ts` is not one top-level `void bootstrapXemaService(…)`, it has its own
-  `Dockerfile`, it bakes cross-repository inputs, or the canonical Dockerfile
-  installs a toolchain for it. Options say where the repository keeps those facts:
-  `--manifests <glob>` (repeatable, default `**/xema-biome.json`),
-  `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>` (both optional).
-- Inside the image build: `filters` and `dirs` name the members' closures,
-  `pins <committed-lockfile>` refuses a re-resolution that moves a registry pin,
-  `index <commit> --build-source <repo>` writes the member index the host reads
-  (graded by `@xemahq/contracts/process-topology`, resolved from the members) and
-  links the host bin, and `load` evaluates every member's entry through the host's
-  `readServiceEntry`. `--build-source` is the `repo` the repository's subjects carry
-  in an edition's image lock.
-
-- `coordinate --image-name <name>` is the image's release coordinate: the content tag
-  and whether GHCR already serves it (only 200 and 404 are answers). The tag is computed
-  ONLY by the repository's own `@xemahq/distribution-source-hash` (`xema-compute-image-tag`,
-  resolved from the repository root); the command refuses when it is not installed, and never
-  hashes anything itself. Environment: `SHA`, `REGISTRY`, `REGISTRY_ORG`, `REGISTRY_USER`,
-  `REGISTRY_TOKEN`, optional `TAG_ARGS_FILE`, `GITHUB_OUTPUT`. Outputs `image`, `content_tag`,
-  `exists`, `entry`. The registry check is also exported as `./ghcr-manifest`
-  (`ghcrManifestExists`, `acquireGhcrPullToken`).
-- `load-image <image>` runs the member-load check inside the shipped image (`docker run`), as its own user and `NODE_ENV`; `load` runs in the builder and cannot prove that.
-- `smoke-refusal <image> [--member <biomeId>/<componentKey>]x2` boots the pushed image
-  with two members on one port and fails unless the host refuses at the declaration, names
-  the collision, and constructs no member. Needs only `docker`.
-- `dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>`
-  renders `infra/composed-process/Dockerfile` from one template. The builder stage installs
-  this tool at the EXACT version (so the hashed image directory moves when the tool does),
-  runs every step above, and runs `load` last as `node` with `NODE_ENV=production`. Nothing here
-  ships in an image: the final stage copies `/monorepo` only.
-
-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
-becoming a junk drawer:
-
-- Nothing with a runtime consumer. If a service imports it at run time it is not
-  build tooling and belongs in an SDK package.
-- Nothing with a single consumer. A tool used by one repository stays in that
-  repository until a second one needs it.
+# @xemahq/repo-build-tooling
+
+> Dev-time build tooling shared by every Xema repository
+
+## Overview
+
+Command-line tools that more than one Xema repository runs at build or check time. Nothing here ships in a service image; consumers declare it as a `devDependency`.
+
+## When to use it
+
+- To run the shared build and readiness checks in a repository, locally or in CI.
+
+## Installation
+
+```bash
+pnpm add -D @xemahq/repo-build-tooling
+```
+
+## Usage
+
+```bash
+pnpm exec xema-readiness
+pnpm exec xema-service-bootstrap --check
+pnpm exec xema-scrub-swagger-paths dist
+```
+
+| Bin | What it does |
+| --- | --- |
+| `xema-readiness` | Runs the ordered checks between a source change and a push |
+| `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
+| `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
+| `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `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.
+
+Every step refuses rather than skips. The package has no dependencies.
+
+## Resolution
+
+Inside the `xema-monorepo` aggregator, `@xemahq/repo-build-tooling` resolves to this directory through a workspace override. In an independent repository's CI it resolves from npm by the declared range, so a change here reaches a consumer only after it is published and the consumer's range admits it.
+
+## License
+
+Apache-2.0 &copy; Xema — [xema.dev](https://xema.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.10.1",
+  "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.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -39,9 +39,9 @@
     "./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 && node --test src/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.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 && 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:35b4aafd2345b2d892fff707b22790985f6ae1e20f75d0f7467f3401f8b583d2"
+    "sourceDigest": "sha256:8a0729af873e6dee7bc38a38408c3f0f57447884e6461ad36e06e8165cf28f4b"
   }
 }

package/src/composed-image-dockerfile.mjs

@@ -23,7 +23,7 @@ const VERSION = /^\d+\.\d+\.\d+$/;
 const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
 const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
 const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
-const NODE_BASE =
+export const NODE_BASE =
   'mirror.gcr.io/library/node:22-bookworm-slim@sha256:d649c27dae7ba0137b3cef5dd75baa422c08dc3d9e3fc0c23dfb172dc3cc6436';
 
 function validate({ toolingVersion, copy, cacheId, buildSource }) {
@@ -55,10 +55,10 @@ 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 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  '
+    ? '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.

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

@@ -84,3 +84,9 @@ test('the token use is derived from .npmrc, deterministically', () => {
   fs.writeFileSync(path.join(root, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
   assert.throws(() => syncComposedDockerfile({ mode: 'check', root, ...OPTIONS }), /is stale/);
 });
+
+test('a token-using repository gets single-backslash line continuations (a doubled one is a parse error)', () => {
+  const text = renderComposedDockerfile({ ...OPTIONS, usesToken: true });
+  assert.match(text, /--mount=type=secret,id=npm_token,required=true \\\n/);
+  for (const line of text.split('\n')) assert.doesNotMatch(line, /\\\\\s*$/, `line ends with a doubled backslash: ${line}`);
+});

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

@@ -0,0 +1,55 @@
+// Shared fixture for the prebuilt-image tests: a tiny workspace with two members
+// (one with a Prisma schema) and one non-member dependency.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function write(root, rel, content) {
+  fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+  fs.writeFileSync(path.join(root, rel), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+}
+
+export const MEMBERS = Object.freeze({ 'alpha/alpha-api': 'biomes/alpha/api/alpha-api', 'alpha/alpha-db-api': 'biomes/alpha/api/alpha-db-api' });
+export const CLOSURE = Object.freeze(['biomes/alpha/api/alpha-api', 'biomes/alpha/api/alpha-db-api', 'packages/sdks/lib-a']);
+
+export function workspace({ built = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-prebuilt-'));
+  write(root, 'biomes/alpha/xema-biome.json', {
+    xema: {
+      id: 'alpha',
+      components: [
+        { key: 'alpha-api', kind: 'service', scheduler: 'platform', artifact: { path: 'api/alpha-api' } },
+        { key: 'alpha-db-api', kind: 'service', scheduler: 'platform', artifact: { path: 'api/alpha-db-api' } },
+      ],
+    },
+  });
+  write(root, 'infra/composed-process/image-build-inputs.json', { workspacePackages: Object.values(MEMBERS) });
+  write(root, 'pnpm-workspace.yaml', "packages:\n  - 'biomes/*/api/*'\n\nonlyBuiltDependencies:\n  - 'esbuild'\n  # a note\n  - prisma\n\n  - \"@prisma/engines\" # trailing\nother: 1\n");
+  write(root, '.npmrc', 'registry=https://registry.npmjs.org/\n');
+  write(root, 'biomes/alpha/api/alpha-api/package.json', { name: '@t/alpha-api' });
+  write(root, 'biomes/alpha/api/alpha-db-api/package.json', { name: '@t/alpha-db-api' });
+  write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', 'datasource db {}\n');
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist'] });
+  if (built) {
+    write(root, 'biomes/alpha/api/alpha-api/dist/main.js', '// main\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/dist/main.js', '// main\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/index.js', '// client\n');
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma', 'datasource db {}\n');
+    write(root, 'packages/sdks/lib-a/dist/index.js', '// lib\n');
+  }
+  return root;
+}
+
+/** An `exec` standing in for `pnpm ls -r --depth -1 --json …`. */
+export function fakePnpm(root, closure = CLOSURE) {
+  const calls = [];
+  const exec = (file, args, options) => {
+    calls.push({ file, args, options });
+    return JSON.stringify(closure.map((dir) => ({ name: dir, path: path.join(root, dir) })));
+  };
+  exec.calls = calls;
+  return exec;
+}
+
+/** A `prisma format` stand-in that leaves the schema as it is (already formatted). */
+export const formatNoop = () => ({ status: 0, stdout: '', stderr: '' });

package/src/composed-image-members.mjs

@@ -0,0 +1,94 @@
+// The member set a repository's committed declaration names, and the workspace closure
+// those members select. Shared by the build-time tool, the stage command and the
+// prebuilt Dockerfile renderer, so all of them see one answer.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, posix, relative } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+
+export const IMAGE_BUILD_INPUTS_FILE = 'image-build-inputs.json';
+
+/** The `<biomeId>/<componentKey>` of the one service whose artifact is `directory`. */
+function memberKey(root, directory) {
+  for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
+    const manifestPath = join(root, dir, 'xema-biome.json');
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const matches = (manifest.xema?.components ?? []).filter(
+      (component) =>
+        component.kind === 'service' &&
+        typeof component.artifact?.path === 'string' &&
+        posix.normalize(posix.join(dir, component.artifact.path)) === directory,
+    );
+    if (matches.length !== 1) {
+      throw new Error(`${dir}/xema-biome.json declares ${matches.length} service(s) at ${directory}, not exactly one`);
+    }
+    return `${manifest.xema.id}/${matches[0].key}`;
+  }
+  throw new Error(`no biome manifest above ${directory}`);
+}
+
+/** `[key, directory]` for every member the committed declaration names. */
+export function readMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const inputs = join(root, imageDir, IMAGE_BUILD_INPUTS_FILE);
+  const directories = JSON.parse(readFileSync(inputs, 'utf8')).workspacePackages ?? [];
+  if (directories.length === 0) throw new Error(`${inputs} declares no workspacePackages`);
+  return directories.map((directory) => [memberKey(root, directory), directory]);
+}
+
+function packageName(root, directory) {
+  const manifest = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8'));
+  if (typeof manifest.name !== 'string') throw new Error(`${directory}/package.json has no name`);
+  return manifest.name;
+}
+
+/** The pnpm `--filter <package>...` arguments covering every member's closure. */
+export function memberFilters(options = {}) {
+  const root = options.root ?? process.cwd();
+  return readMembers(options).map(([, directory]) => `--filter ${packageName(root, directory)}...`);
+}
+
+
+/** The biome manifest (`xema-biome.json`) above every member, repository-relative and sorted: what `index` reads to name a member. */
+export function memberManifests({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const manifests = new Set();
+  for (const [, directory] of readMembers({ root, imageDir })) {
+    for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
+      if (existsSync(join(root, dir, 'xema-biome.json'))) {
+        manifests.add(posix.join(dir, 'xema-biome.json'));
+        break;
+      }
+    }
+  }
+  return [...manifests].sort();
+}
+
+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 });
+  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');
+  const real = realpathSync(root);
+  const directories = new Set();
+  for (const pkg of packages) {
+    if (typeof pkg?.path !== 'string') throw new Error('pnpm ls listed a package with no path');
+    let rel = relative(root, pkg.path);
+    if (rel.startsWith('..')) rel = relative(real, pkg.path);
+    if (rel.startsWith('..')) throw new Error(`pnpm ls listed ${pkg.path}, outside ${root}`);
+    if (rel !== '') directories.add(rel.split('\\').join('/'));
+  }
+  return [...directories].sort();
+}

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

@@ -0,0 +1,205 @@
+// `xema-composed-image dockerfile --prebuilt --write|--check`: renders
+// `<image-dir>/Dockerfile` AND `<image-dir>/Dockerfile.dockerignore` for the image that
+// is ASSEMBLED from build outputs made on the CI runner (`xema-composed-image stage`).
+// Docker compiles nothing. The full-build template (`composed-image-dockerfile.mjs`)
+// stays available for repositories that still build inside Docker.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { NODE_BASE, npmrcUsesToken } from './composed-image-dockerfile.mjs';
+import { memberClosure, memberFilters, memberManifests } from './composed-image-members.mjs';
+
+export const DEFAULT_STAGE_DIR = '.xema-stage';
+const VERSION = /^\d+\.\d+\.\d+$/;
+const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
+const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
+const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+
+function validate({ toolingVersion, copy, cacheId, buildSource, stageDir }) {
+  if (!VERSION.test(toolingVersion ?? '')) throw new Error(`--tooling-version must be an exact x.y.z version, got "${toolingVersion}"`);
+  for (const directory of [...(copy ?? []), stageDir]) {
+    if (!DIRECTORY.test(directory) || directory.startsWith('/') || directory.split('/').includes('..')) {
+      throw new Error(`"${directory}" is not a repository-relative directory`);
+    }
+  }
+  if (!CACHE_ID.test(cacheId ?? '')) throw new Error(`--cache-id must be lowercase [a-z0-9-], got "${cacheId}"`);
+  if (!REPOSITORY.test(buildSource ?? '')) throw new Error(`--build-source must name a repository, got "${buildSource}"`);
+}
+
+/** The ignore file: the build context carries sources, never local build output, except the staged outputs. */
+export function renderPrebuiltDockerignore({ stageDir = DEFAULT_STAGE_DIR } = {}) {
+  return `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` — DO NOT EDIT.
+# Local build output stays out of the context; the staged outputs carry dist and node_modules/.prisma paths, so they are re-included LAST.
+.git
+**/node_modules
+**/dist
+**/.turbo
+**/coverage
+**/*.tsbuildinfo
+**/*.log
+!${stageDir}/**
+`;
+}
+
+/** The `onlyBuiltDependencies:` items of a `pnpm-workspace.yaml` text (block list; comments skipped; ends at the next top-level key). */
+export function onlyBuiltDependencies(workspaceYaml) {
+  const names = [];
+  let inList = false;
+  for (const line of workspaceYaml.split('\n')) {
+    if (!inList) {
+      inList = /^onlyBuiltDependencies:\s*(#.*)?$/.test(line);
+      continue;
+    }
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    if (/^\S/.test(line)) break;
+    const item = /^\s+-\s+(?:'([^']*)'|"([^"]*)"|([^\s#]+))\s*(?:#.*)?$/.exec(line);
+    if (item === null) throw new Error(`pnpm-workspace.yaml: cannot read onlyBuiltDependencies item "${line.trim()}"`);
+    names.push(item[1] ?? item[2] ?? item[3]);
+  }
+  for (const name of names) {
+    if (!/^[@A-Za-z0-9._/-]+$/.test(name)) throw new Error(`pnpm-workspace.yaml: onlyBuiltDependencies "${name}" is not a package name`);
+  }
+  return names;
+}
+
+const parts = (sources) => sources.map((source) => `    ${source} \\`).join('\n');
+
+/** The prebuilt Dockerfile text. The closure and the members' literal filters are derived from `root` (`memberClosure`); `exec` is injectable for tests. */
+export function renderPrebuiltDockerfile({
+  root = process.cwd(),
+  imageDir = COMPOSED_IMAGE_DIR,
+  toolingVersion,
+  copy = [],
+  cacheId,
+  buildSource,
+  usesToken,
+  stageDir = DEFAULT_STAGE_DIR,
+  exec,
+}) {
+  if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
+  validate({ toolingVersion, copy, cacheId, buildSource, stageDir });
+  const workspaceFile = join(root, 'pnpm-workspace.yaml');
+  const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
+  if (built.length === 0) {
+    throw new Error('pnpm-workspace.yaml has no onlyBuiltDependencies: — `pnpm rebuild` would have nothing to build; refusing to render');
+  }
+  const closure = memberClosure({ root, imageDir, exec });
+  const filters = memberFilters({ root, imageDir }).join(' ');
+  const manifests = memberManifests({ root, imageDir });
+  const dirFlag = imageDir === COMPOSED_IMAGE_DIR ? '' : ` --image-dir ${imageDir}`;
+  const toolDir = '/opt/xema-composed-image';
+  const toolMount = `--mount=type=bind,source=${stageDir}/tool,target=${toolDir}`;
+  const node = `${toolDir}/src/composed-image.mjs`;
+  const store = `--mount=type=cache,id=pnpm-store-${cacheId},target=/root/.pnpm-store`;
+  const metadata = `--mount=type=cache,id=pnpm-metadata-${cacheId},target=/root/.cache/pnpm`;
+  const secret = usesToken ? '  --mount=type=secret,id=npm_token,required=true \\\n' : '';
+  const tokenExport = usesToken
+    ? 'export NPM_TOKEN="$(cat /run/secrets/npm_token)" && export GH_PACKAGES_TOKEN="$NPM_TOKEN" && \\\n  '
+    : '';
+  const copies = [...new Set(copy.map((d) => posix.normalize(`${d}/`)))].map((d) => `COPY ${d} ./${d}`).join('\n');
+  const manifestSources = closure.map((directory) => `${directory}/package.json`);
+  const assembleSources = [...closure, ...manifests];
+  const imageCopy = posix.normalize(`${imageDir}/`);
+  const text = `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
+# Re-render with the same options; \`--check\` refuses a stale file (and a stale Dockerfile.dockerignore).
+#
+# The COMPOSED-PROCESS image of this repository, ASSEMBLED from build outputs: ONE image
+# per build (repository at commit), every member of \`image-build-inputs.json\` in ONE module
+# graph behind the SDK's \`xema-composed-process\` host. Docker compiles nothing. The CI
+# runner ran \`turbo run build prisma:generate\` for the members' closures and
+# \`xema-composed-image stage ${stageDir}\` gathered the outputs into the build-step
+# directory \`${stageDir}/\` (\`out/\` = dist and generated Prisma clients, pure JS/wasm;
+# \`tool/\` = this tool, bind-mounted into the steps below and never copied into a layer).
+#
+# Stages:
+#   deps      arch-native. Inputs are the lockfile and the closure's manifests ONLY, so the
+#             layer is cached until one of them changes. Production install with the
+#             workspace packages INJECTED, then \`pnpm rebuild <names>\` runs the build scripts
+#             of the root \`onlyBuiltDependencies\` (Prisma engines, native addons) natively.
+#             The names are listed because a bare filtered \`pnpm rebuild\` would also run
+#             the members' own postinstall (no schema here); a name absent from the graph
+#             is tolerated. The list is rendered, so a change to it makes \`--check\` stale.
+#   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.
+#
+# The \`--filter <package>...\` words below are LITERAL: the content hash of this image reads
+# them to narrow the lockfile to the members' closures.
+FROM ${NODE_BASE} AS base
+RUN corepack enable && \\
+    apt-get update && apt-get install -y --no-install-recommends openssl wget && rm -rf /var/lib/apt/lists/* && \\
+    pnpm config set store-dir /root/.pnpm-store
+
+FROM base AS deps
+WORKDIR /monorepo
+ENV CI=true
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+${copies === '' ? '' : `${copies}\n`}COPY --parents \\
+${parts(manifestSources)}
+    ./
+RUN ${store} \\
+  ${metadata} \\
+${secret}  ${toolMount} \\
+  ${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} ${filters} && \\
+  node ${node} pins${dirFlag} /tmp/pnpm-lock.committed.yaml && \\
+  pnpm install --prod --prefer-offline --ignore-scripts \${INJECT} ${filters} --frozen-lockfile && \\
+  pnpm rebuild ${built.join(' ')} ${filters}
+
+FROM deps AS assemble
+COPY --parents \\
+${parts(assembleSources)}
+    ./
+COPY ${imageCopy} ./${imageCopy}
+COPY ${stageDir}/out/ ./
+ARG BUILD_SHA
+RUN ${toolMount} \\
+  T="node ${node}" && \\
+  $T sync-injected${dirFlag} && $T prisma-check${dirFlag} && \\
+  : "\${BUILD_SHA:?BUILD_SHA build-arg is required}" && $T index "\${BUILD_SHA}" --build-source ${buildSource}${dirFlag} && \\
+  cp ${toolDir}/src/composed-migrate.mjs /monorepo/xema-composed-migrate.mjs
+
+# Every member's module graph loads here, ALONE (one process each), through the host's own
+# entry reader, as the user and NODE_ENV the image runs with, or the image is never pushed.
+USER node
+RUN ${toolMount} \\
+  NODE_ENV=production node ${node} load --each${dirFlag}
+
+FROM base
+WORKDIR /monorepo
+COPY --from=assemble /monorepo /monorepo
+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
+USER node
+CMD ["node", "/monorepo/xema-composed-process"]
+`;
+  return { dockerfile: text, dockerignore: renderPrebuiltDockerignore({ stageDir }), closure };
+}
+
+/** `--write` writes both files; `--check` throws when either differs. */
+export function syncPrebuiltDockerfile({ mode, root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, exec, ...options }) {
+  if (mode !== 'write' && mode !== 'check') throw new Error(`mode must be write or check, got "${mode}"`);
+  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 { dockerfile, dockerignore } = renderPrebuiltDockerfile({ ...options, root, imageDir, exec, usesToken: npmrcUsesToken(readFileSync(npmrc, 'utf8')) });
+  const files = [
+    [posix.join(imageDir, 'Dockerfile'), dockerfile],
+    [posix.join(imageDir, 'Dockerfile.dockerignore'), dockerignore],
+  ];
+  const stale = [];
+  for (const [relativeTarget, rendered] of files) {
+    const target = join(root, relativeTarget);
+    if (mode === 'write') {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, rendered);
+    } else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) stale.push(relativeTarget);
+  }
+  if (stale.length > 0) {
+    throw new Error(`${stale.join(' and ')} ${stale.length > 1 ? 'are' : 'is'} stale. Run: xema-composed-image dockerfile --prebuilt --write (with the same options)`);
+  }
+  return files.map(([relativeTarget]) => relativeTarget);
+}