@xemahq/repo-build-tooling 0.21.2 → 0.22.0

package/src/service-image-in-image.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// `prove`: the IN-IMAGE half of a per-service image (`xema-service-image`). The Dockerfile's
+// proof stage runs it on the TARGET platform, `--network=none`, with the staged app and this
+// tool bind-mounted, the stage manifest COPYed into <proof dir>, and the repository's root build
+// inputs COPYed from the build context into <proof dir>/context:
+//
+//   node <tool>/src/service-image-in-image.mjs prove <app dir> <proof dir> --service <service> --commit <sha>
+//
+// The image's content tag is computed from the build context, not from the stage, so the stage
+// must be proved to be the build context's. `prove` refuses the image unless: the manifest names
+// <service>; it was staged at <sha> (the BUILD_SHA the image is built for, so a stale stage
+// cannot ship); the root build inputs in the build context (`ROOT_BUILD_INPUT`: the lockfile,
+// the root manifest, the workspace, .npmrc, .pnpmfile.cjs, turbo.json, tsconfig*.json) are
+// exactly the ones the stage hashed, which also proves the Dockerfile COPYs every one of them
+// (and so the content tag covers them); this tool is the version the stage recorded; this
+// process runs on the manifest's platform; the Node ABI is the stager's when the app carries
+// Node addons; every package's addons load here (`process.dlopen`: an ELF for the right
+// machine can still need a newer glibc than the image has), where a package that ships several
+// builds needs one that loads; Prisma computes, HERE, the binaryTarget whose schema engine was
+// staged, and that engine has the staged sha256 and reports the pinned version; dist/main.js
+// exists. It then writes <proof dir>/verified.json, which the final stage ships, so the image
+// cannot be built without the proof.
+//
+// Loads only `node:` builtins and relative modules that do too (Prisma's own modules are
+// resolved from the app).
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { prismaEnginesDirectories, verifySchemaEngine } from './composed-image-prisma-engine.mjs';
+import { currentPlatform } from './service-image-platform.mjs';
+
+export const MANIFEST_FILE = 'xema-service-image.json';
+export const MANIFEST_SCHEMA = 2;
+export const VERIFIED_FILE = 'verified.json';
+export const LOCKFILE = 'pnpm-lock.yaml';
+/** The proof dir's subdirectory the Dockerfile COPYs the root build inputs into. */
+export const CONTEXT_DIRECTORY = 'context';
+/**
+ * Repository-root files that steer the runner's install and build, so they decide the staged
+ * bytes. The stage hashes every one present; the Dockerfile must COPY each into the proof
+ * context, which puts it in the content tag.
+ */
+export const ROOT_BUILD_INPUT = /^(pnpm-lock\.yaml|package\.json|pnpm-workspace\.yaml|\.npmrc|\.pnpmfile\.cjs|turbo\.json|tsconfig[^/]*\.json)$/;
+export const TOOL_NAME = '@xemahq/repo-build-tooling';
+const TOOL_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const sha256File = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+/** The version of the tool running this code (the stage's copy, in the image). */
+export const ownToolVersion = () => JSON.parse(readFileSync(join(TOOL_DIRECTORY, 'package.json'), 'utf8')).version;
+
+/** Load one Node addon the way `require` does. */
+const dlopen = (file) => process.dlopen({ exports: {} }, file);
+
+const getBinaryTarget = (enginesDir) =>
+  createRequire(join(enginesDir, 'package.json'))('@prisma/get-platform').getBinaryTargetForCurrentPlatform();
+
+/** The problems that keep the root build inputs in `contextDir` from being the ones `inputs` recorded. */
+function contextProblems(contextDir, inputs) {
+  const problems = [];
+  const carried = existsSync(contextDir) ? readdirSync(contextDir).sort() : [];
+  for (const name of Object.keys(inputs).sort()) {
+    if (!carried.includes(name)) {
+      problems.push(`${name} is a root build input of the stage, and the build context does not carry it: ` +
+        `COPY it into /proof/${CONTEXT_DIRECTORY}/ in the Dockerfile and admit it in its .dockerignore, so the content tag covers it`);
+    } else if (sha256File(join(contextDir, name)) !== inputs[name]) {
+      problems.push(`the build context's ${name} is not the one the stage was built from: re-stage`);
+    }
+  }
+  for (const name of carried) {
+    if (!Object.hasOwn(inputs, name)) problems.push(`the build context carries ${name}, which the stage did not hash as a root build input`);
+  }
+  return problems;
+}
+
+/** Each package's addons (`natives`: package dir -> its target ELF files) must load: one per package. */
+function loadProblems(appDir, natives, load) {
+  const problems = [];
+  for (const [owner, files] of Object.entries(natives)) {
+    const addons = files.filter((file) => file.endsWith('.node'));
+    const failures = [];
+    for (const addon of addons) {
+      try {
+        load(join(appDir, addon));
+        break;
+      } catch (error) {
+        failures.push(`${addon}: ${String(error.message).split('\n')[0]}`);
+      }
+    }
+    if (addons.length > 0 && failures.length === addons.length) {
+      problems.push(`no Node addon of ${owner} loads on this image:\n${failures.map((f) => `      ${f}`).join('\n')}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Check a staged app against its manifest and the build context, on this platform. Throws once,
+ * naming every failed check. `platform`, `nodeAbi`, `binaryTarget`, `version`, `load` and
+ * `toolVersion` are injectable for tests.
+ */
+export async function prove({
+  appDir,
+  proofDir,
+  service,
+  commit,
+  platform = currentPlatform(),
+  nodeAbi = process.versions.modules,
+  binaryTarget = getBinaryTarget,
+  version,
+  load = dlopen,
+  toolVersion = ownToolVersion(),
+  log = console.log,
+}) {
+  const manifest = JSON.parse(readFileSync(join(proofDir, MANIFEST_FILE), 'utf8'));
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    throw new Error(`the stage manifest is schema ${manifest.schema}, this proof reads schema ${MANIFEST_SCHEMA}: re-stage with this tool`);
+  }
+  const problems = [];
+  if (manifest.service !== service) problems.push(`the stage is for '${manifest.service}', this build is for '${service}'`);
+  if (manifest.commit !== commit) problems.push(`the stage was built at ${manifest.commit}, this image is for ${commit}: re-stage`);
+  problems.push(...contextProblems(join(proofDir, CONTEXT_DIRECTORY), manifest.inputs));
+  if (manifest.tool?.name !== TOOL_NAME || manifest.tool?.version !== toolVersion) {
+    problems.push(`the stage was made by ${manifest.tool?.name}@${manifest.tool?.version}, this proof is ${TOOL_NAME}@${toolVersion}`);
+  }
+  const onPlatform = manifest.platform === platform;
+  if (!onPlatform) problems.push(`the stage is for ${manifest.platform}, this build runs on ${platform}`);
+  const addons = Object.values(manifest.natives).flat().filter((file) => file.endsWith('.node'));
+  const sameAbi = addons.length === 0 || manifest.nodeAbi === nodeAbi;
+  if (!sameAbi) {
+    problems.push(`the app carries Node addons (${addons.join(', ')}) built for Node ABI ${manifest.nodeAbi}, the image's Node is ABI ${nodeAbi}`);
+  }
+  if (onPlatform && sameAbi) problems.push(...loadProblems(appDir, manifest.natives, load));
+  if (!existsSync(join(appDir, 'dist', 'main.js'))) problems.push('dist/main.js does not exist');
+
+  const enginesDirs = existsSync(join(appDir, 'node_modules', '.pnpm')) ? prismaEnginesDirectories(appDir) : [];
+  if (manifest.prisma === null && enginesDirs.length > 0) problems.push('the app carries a prisma CLI, but the stage staged no schema engine');
+  if (manifest.prisma !== null && enginesDirs.length === 0) problems.push('the stage staged a schema engine, but the app carries no prisma CLI');
+  for (const enginesDir of manifest.prisma === null ? [] : enginesDirs) {
+    const target = await binaryTarget(enginesDir);
+    if (target !== manifest.prisma.binaryTarget) {
+      problems.push(`Prisma computes binaryTarget ${target} here, the stage staged ${manifest.prisma.binaryTarget}`);
+      continue;
+    }
+    const engine = join(enginesDir, `schema-engine-${target}`);
+    if (!existsSync(engine)) {
+      problems.push(`${engine} does not exist`);
+      continue;
+    }
+    if (sha256File(engine) !== manifest.prisma.sha256) {
+      problems.push(`${engine} is not the schema engine the stage fetched and verified (sha256 ${manifest.prisma.sha256})`);
+      continue;
+    }
+    try {
+      log(`prisma schema engine: ${engine} (${verifySchemaEngine(engine, manifest.prisma.enginesVersion, version)})`);
+    } catch (error) {
+      problems.push(error.message);
+    }
+  }
+  if (problems.length > 0) throw new Error(`the staged ${manifest.service} is not this image's:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  copyFileSync(join(proofDir, MANIFEST_FILE), join(proofDir, VERIFIED_FILE));
+  log(`proved ${service} at ${commit} on ${platform}`);
+  return manifest;
+}
+
+const USAGE = 'usage: service-image-in-image.mjs prove <app dir> <proof dir> --service <service> --commit <40-hex sha>';
+
+export function parseProveArgs(argv) {
+  const [verb, appDir, proofDir, ...rest] = argv;
+  if (verb !== 'prove' || appDir === undefined || proofDir === undefined || rest.length !== 4) throw new Error(USAGE);
+  const options = {};
+  for (let i = 0; i < rest.length; i += 2) {
+    const name = { '--service': 'service', '--commit': 'commit' }[rest[i]];
+    if (name === undefined || Object.hasOwn(options, name)) throw new Error(USAGE);
+    options[name] = rest[i + 1];
+  }
+  if (!/^[a-z0-9@][a-z0-9@/._-]*$/.test(options.service ?? '')) throw new Error(`--service must name a workspace package\n${USAGE}`);
+  if (!/^[0-9a-f]{40}$/.test(options.commit ?? '')) throw new Error(`--commit must be the 40-hex commit the image is built for (BUILD_SHA)\n${USAGE}`);
+  return { appDir: resolve(appDir), proofDir: resolve(proofDir), service: options.service, commit: options.commit };
+}
+
+// realpath both sides: Node resolves the entry module's symlinks, `process.argv[1]` keeps them.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  Promise.resolve()
+    .then(() => prove(parseProveArgs(process.argv.slice(2))))
+    .catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
+}

package/src/service-image-platform.mjs

@@ -0,0 +1,128 @@
+// The target platform of a per-service image (`xema-service-image`), and the proof that a
+// staged tree holds native code for that platform only. Loads only `node:` builtins: the
+// in-image `prove` step imports it from the bind-mounted tool directory.
+import { closeSync, existsSync, openSync, readSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The image platforms this recipe builds, keyed by Docker's `TARGETARCH`. `node` is Node's
+ * `process.arch`, `elfMachine` the ELF `e_machine` of native code for it, `prismaBinaryTarget`
+ * the binaryTarget Prisma's get-platform computes inside the runtime base image
+ * (node:22-bookworm-slim + openssl 3.0). The in-image `prove` step re-computes the last one on
+ * the target and refuses the image when it differs, so a base image change cannot ship a
+ * schema engine Prisma would not use.
+ */
+export const IMAGE_PLATFORMS = Object.freeze({
+  amd64: Object.freeze({ node: 'x64', elfMachine: 62, prismaBinaryTarget: 'debian-openssl-3.0.x' }),
+  arm64: Object.freeze({ node: 'arm64', elfMachine: 183, prismaBinaryTarget: 'linux-arm64-openssl-3.0.x' }),
+});
+
+/** `linux/<arch>` → `<arch>`; refuses any platform this recipe does not build. */
+export function platformArch(platform) {
+  const match = /^linux\/([a-z0-9]+)$/.exec(String(platform ?? ''));
+  if (match === null || !Object.hasOwn(IMAGE_PLATFORMS, match[1])) {
+    throw new Error(`--platform must be one of ${Object.keys(IMAGE_PLATFORMS).map((a) => `linux/${a}`).join(', ')}, got '${platform}'`);
+  }
+  return match[1];
+}
+
+/** The `linux/<arch>` this Node process runs on (the in-image check of the target). */
+export function currentPlatform(nodeArch = process.arch) {
+  const arch = Object.keys(IMAGE_PLATFORMS).find((key) => IMAGE_PLATFORMS[key].node === nodeArch);
+  if (arch === undefined) throw new Error(`Node arch '${nodeArch}' is not an image platform this recipe builds`);
+  return `linux/${arch}`;
+}
+
+const MACH_O = new Set([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe]);
+
+/** What the first bytes of a file say it is: `{ format: 'elf', machine }`, `{ format: 'mach-o' }`, `{ format: 'pe' }` or `undefined`. */
+export function nativeFormat(header) {
+  if (header.length >= 20 && header[0] === 0x7f && header[1] === 0x45 && header[2] === 0x4c && header[3] === 0x46) {
+    const littleEndian = header[5] === 1;
+    return { format: 'elf', machine: littleEndian ? header.readUInt16LE(18) : header.readUInt16BE(18) };
+  }
+  if (header.length >= 4 && MACH_O.has(header.readUInt32BE(0))) return { format: 'mach-o' };
+  if (header.length >= 2 && header[0] === 0x4d && header[1] === 0x5a) return { format: 'pe' };
+  return undefined;
+}
+
+function readHeader(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(20);
+    const read = readSync(fd, buffer, 0, 20, 0);
+    return buffer.subarray(0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The directory of the nearest `package.json` at or above `dir`, stopping at `root` (`root` itself when none). */
+function owningPackage(root, rel) {
+  const parts = rel.split('/').slice(0, -1);
+  for (let n = parts.length; n > 0; n -= 1) {
+    const candidate = parts.slice(0, n).join('/');
+    if (existsSync(join(root, candidate, 'package.json'))) return candidate;
+  }
+  return '.';
+}
+
+/**
+ * Every native file under `root` for `arch` (relative, sorted), and the problems that keep the tree out
+ * of a linux/`arch` image. Native code is judged PER PACKAGE (the nearest `package.json`): a package may
+ * ship prebuilt binaries for several platforms and load the one for the platform it runs on
+ * (`@temporalio/core-bridge` carries `releases/<triple>/index.node`). A package is refused when it
+ * carries native code (an ELF object, a Mach-O, a `.node` addon; a PE header counts only on
+ * `.node`/`.exe`/`.dll`, as `MZ` also opens ordinary data) and NONE of it is an ELF for `arch`: then the
+ * binary it would load was built for another machine (a host build) and cannot run here.
+ * `natives` lists the ELF objects for `arch`; `byPackage` groups them by owning package (the in-image
+ * proof loads each package's addons on the target); `foreign` the other platforms' files a refused
+ * package did not cause. Symlinks are not followed.
+ */
+export function scanNatives(root, arch) {
+  const { elfMachine } = IMAGE_PLATFORMS[arch];
+  const packages = new Map(); // package dir -> { target: [], foreign: [] }
+  const record = (rel, isTarget, why) => {
+    const owner = owningPackage(root, rel);
+    if (!packages.has(owner)) packages.set(owner, { target: [], foreign: [] });
+    const entry = packages.get(owner);
+    if (isTarget) entry.target.push(rel);
+    else entry.foreign.push(`${rel}: ${why}`);
+  };
+  const walk = (dir, prefix) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const kind = nativeFormat(readHeader(join(dir, entry.name)));
+      if (kind?.format === 'elf') {
+        if (kind.machine === elfMachine) record(rel, true);
+        else record(rel, false, `ELF e_machine ${kind.machine}, the linux/${arch} image needs ${elfMachine}`);
+      } else if (kind?.format === 'mach-o') {
+        record(rel, false, 'a Mach-O binary');
+      } else if (kind?.format === 'pe' && /\.(node|exe|dll)$/.test(entry.name)) {
+        record(rel, false, 'a Windows binary');
+      } else if (entry.name.endsWith('.node')) {
+        record(rel, false, 'a native addon that is not an ELF object');
+      }
+    }
+  };
+  walk(root, '');
+  const natives = [];
+  const byPackage = {};
+  const foreign = [];
+  const problems = [];
+  for (const [owner, { target, foreign: others }] of [...packages].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    natives.push(...target);
+    if (target.length > 0) byPackage[owner] = [...target].sort();
+    if (target.length === 0) {
+      problems.push(`${owner} carries native code and none of it is for linux/${arch}:\n${others.map((o) => `      ${o}`).join('\n')}`);
+    } else {
+      foreign.push(...others.map((o) => o.slice(0, o.indexOf(': '))));
+    }
+  }
+  return { natives: natives.sort(), byPackage, foreign: foreign.sort(), problems };
+}

package/src/service-image-stage.mjs

@@ -0,0 +1,253 @@
+// `xema-service-image stage`: the CI runner's half of a per-service image. The service is
+// built on the runner (`turbo run build prisma:generate --filter <service>...`, the lane's
+// step) and DEPLOYED here, for the image's target platform, into the build-step directory:
+//
+//   <stage>/service/app/                     `pnpm deploy --prod` of the service: dist, the
+//                                            production node_modules for linux/<arch>, the Prisma
+//                                            client and the target's Prisma schema engine
+//   <stage>/service/xema-service-image.json  the manifest the in-image `prove` step checks
+//   <stage>/tool/                            this package (bind-mounted for `prove`, never shipped)
+//
+// The Dockerfile COPYs `app/` and runs nothing but the proof: no install, no build, no network.
+// The image's content tag is computed from the commit's build context, never from the stage, so
+// the manifest binds the stage to it: the commit (with no uncommitted change to a tracked file),
+// the sha256 of every root build input (`ROOT_BUILD_INPUT`), which the Dockerfile COPYs into the
+// proof context and so into the tag, and the tool's version, which the lockfile pins (the stage
+// refuses to run as any tool but the one the repository root installs).
+// The per-repo, single-service counterpart of `xema-composed-image stage`; it shares its tool
+// copy, its build-script rule (`rebuildList`) and its Prisma engine proof. The one difference is
+// where production dependencies are installed: here, on the runner, selected for the TARGET
+// platform with `--os/--cpu/--libc`, never for the host, and then scanned (`scanNatives`).
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+
+import { REBUILD_EXCLUDED, onlyBuiltDependencies, rebuildList } from './composed-image-prebuilt-dockerfile.mjs';
+import { prismaEnginesDirectories } from './composed-image-prisma-engine.mjs';
+import { copyTool, toolVersion } from './composed-image-stage.mjs';
+import { LOCKFILE, MANIFEST_FILE, MANIFEST_SCHEMA, ROOT_BUILD_INPUT, TOOL_NAME, sha256File } from './service-image-in-image.mjs';
+import { IMAGE_PLATFORMS, platformArch, scanNatives } from './service-image-platform.mjs';
+
+export { LOCKFILE, MANIFEST_FILE, MANIFEST_SCHEMA, ROOT_BUILD_INPUT };
+
+export const DEFAULT_STAGE_DIR = '.xema-stage';
+export const SERVICE_STAGE_SUBDIRECTORY = 'service';
+export const APP_DIRECTORY = 'app';
+/** Where Prisma publishes its engines, by engines commit and binaryTarget. */
+export const PRISMA_ENGINES_URL = 'https://binaries.prisma.sh/all_commits';
+const TOOL_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The deploy command: xema-base `service-prebuilt`'s deploy flags, plus the target selection. */
+export const deployArgs = ({ service, arch, destination }) => [
+  'deploy',
+  '--prod',
+  '--offline',
+  '--ignore-scripts',
+  '--os=linux',
+  `--cpu=${arch}`,
+  '--libc=glibc',
+  '--config.force-legacy-deploy=false',
+  '--config.inject-workspace-packages=true',
+  '--config.dedupe-injected-deps=true',
+  '--filter',
+  service,
+  destination,
+];
+
+const runPnpm = (args, cwd) => execFileSync('pnpm', args, { cwd, stdio: 'inherit' });
+const runGit = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8' });
+
+/** `<name>` of a `node_modules/.pnpm` entry (`@scope+name@1.0.0_peer@2…` → `@scope/name`). */
+export function pnpmEntryName(entry) {
+  const at = entry.indexOf('@', entry.startsWith('@') ? 1 : 0);
+  if (at <= 0) return undefined;
+  const flat = entry.slice(0, at);
+  return flat.startsWith('@') ? flat.replace('+', '/') : flat;
+}
+
+/** The production closure of a deploy: `[{ name, dir }]`, one per `node_modules/.pnpm` entry. */
+export function deployedPackages(appDir) {
+  const store = join(appDir, 'node_modules', '.pnpm');
+  if (!existsSync(store)) return [];
+  const packages = [];
+  for (const entry of readdirSync(store).sort()) {
+    const name = pnpmEntryName(entry);
+    if (name === undefined) continue;
+    const dir = join(store, entry, 'node_modules', name);
+    if (existsSync(join(dir, 'package.json'))) packages.push({ name, dir });
+  }
+  return packages;
+}
+
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+async function get(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`GET ${url}: ${response.status} ${response.statusText}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** The sha256 Prisma publishes next to `url` (`<url>.sha256`: `<hex>  <name>`). */
+async function publishedSha256(url) {
+  const [hex] = (await get(`${url}.sha256`)).toString('utf8').trim().split(/\s+/);
+  if (!/^[a-f0-9]{64}$/.test(hex)) throw new Error(`${url}.sha256 is not a sha256`);
+  return hex;
+}
+
+/**
+ * The schema engine at `enginesVersion` (the engines commit the lockfile pins, through the
+ * deploy's @prisma/engines-version) for `binaryTarget`, fetched from Prisma for every stage and
+ * written to `enginesDir`. Both the download and the engine must match the checksums Prisma
+ * publishes. There is no cache: Prisma's own downloader keeps one across runs in the home
+ * directory, honours mirror variables and retries, so it is not used.
+ */
+export async function downloadSchemaEngine({ enginesDir, binaryTarget, enginesVersion }) {
+  if (!/^[a-f0-9]{40}$/.test(enginesVersion)) throw new Error(`@prisma/engines-version ${enginesVersion} is not an engines commit`);
+  const url = `${PRISMA_ENGINES_URL}/${enginesVersion}/${binaryTarget}/schema-engine`;
+  const [zippedSha256, engineSha256, zipped] = await Promise.all([publishedSha256(`${url}.gz`), publishedSha256(url), get(`${url}.gz`)]);
+  if (sha256(zipped) !== zippedSha256) throw new Error(`${url}.gz has sha256 ${sha256(zipped)}, Prisma publishes ${zippedSha256}`);
+  const engine = gunzipSync(zipped);
+  if (sha256(engine) !== engineSha256) throw new Error(`${url} has sha256 ${sha256(engine)}, Prisma publishes ${engineSha256}`);
+  const file = join(enginesDir, `schema-engine-${binaryTarget}`);
+  writeFileSync(file, engine);
+  chmodSync(file, 0o755);
+}
+
+/**
+ * The commit, the root build inputs (name -> sha256) and the problems that keep them from
+ * naming the stage: an uncommitted change to a tracked file, or a root build input git does
+ * not track (the content tag is computed from the commit, so it could not see either).
+ */
+function buildInputs(root, git) {
+  const problems = [];
+  const commit = git(['rev-parse', 'HEAD'], root).trim();
+  const changed = git(['status', '--porcelain', '--untracked-files=no'], root).trim();
+  if (changed !== '') problems.push(`tracked files differ from ${commit}, which the image's tag is computed from:\n${changed}`);
+  const present = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && ROOT_BUILD_INPUT.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  if (!present.includes(LOCKFILE)) problems.push(`${LOCKFILE} does not exist at ${root}`);
+  const tracked = present.length === 0 ? new Set() : new Set(git(['ls-files', '-z', '--', ...present], root).split('\0'));
+  const inputs = {};
+  for (const name of present) {
+    if (tracked.has(name)) inputs[name] = sha256File(join(root, name));
+    else problems.push(`${name} steers the build and git does not track it, so no image tag can cover it`);
+  }
+  return { commit, inputs, problems };
+}
+
+/** The problem when this code is not the @xemahq/repo-build-tooling the repository root installs. */
+function toolProblem(root) {
+  const installed = join(root, 'node_modules', ...TOOL_NAME.split('/'));
+  const here = realpathSync(TOOL_DIRECTORY);
+  if (existsSync(installed) && realpathSync(installed) === here) return undefined;
+  return `this xema-service-image (${here}) is not the ${TOOL_NAME} the repository root installs: run \`pnpm exec xema-service-image\` from the root, so the lockfile pins the tool that stages`;
+}
+
+/**
+ * Deploy, complete and check one service for one platform. Throws once, naming every offender.
+ * `deploy` and `fetchEngine` are injectable for tests.
+ */
+export async function stageService({
+  root = process.cwd(),
+  service,
+  path,
+  platform,
+  stageDir = DEFAULT_STAGE_DIR,
+  deploy = runPnpm,
+  fetchEngine = downloadSchemaEngine,
+  git = runGit,
+  log = console.log,
+}) {
+  if (typeof service !== 'string' || service === '') throw new Error('stage needs --service <workspace package>');
+  if (typeof path !== 'string' || path === '') throw new Error('stage needs --path <service directory>');
+  const arch = platformArch(platform);
+  const servicePath = posix.normalize(path);
+  const serviceDir = join(root, servicePath);
+
+  const problems = [];
+  const manifestPath = join(serviceDir, 'package.json');
+  if (!existsSync(manifestPath)) throw new Error(`${servicePath}/package.json does not exist`);
+  const name = JSON.parse(readFileSync(manifestPath, 'utf8')).name;
+  if (name !== service) problems.push(`${servicePath}/package.json is '${name}', not '${service}'`);
+  if (!existsSync(join(serviceDir, 'dist', 'main.js'))) problems.push(`${servicePath}/dist/main.js does not exist: build the service first`);
+  const schema = existsSync(join(serviceDir, 'prisma', 'schema.prisma'));
+  const clientDir = join(serviceDir, 'node_modules', '.prisma');
+  const client = existsSync(clientDir) && readdirSync(clientDir, { withFileTypes: true }).some((e) => e.isDirectory());
+  if (schema && !client) problems.push(`${servicePath} has prisma/schema.prisma but no node_modules/.prisma/<client>/: run prisma generate`);
+  if (!schema && client) problems.push(`${servicePath} has node_modules/.prisma/<client>/ but no prisma/schema.prisma`);
+  const { commit, inputs, problems: inputProblems } = buildInputs(root, git);
+  problems.push(...inputProblems);
+  const wrongTool = toolProblem(root);
+  if (wrongTool !== undefined) problems.push(wrongTool);
+  const stageRoot = join(root, stageDir);
+  if (existsSync(stageRoot) && readdirSync(stageRoot).length > 0) problems.push(`${stageDir} already exists and is not empty`);
+  if (problems.length > 0) throw new Error(`cannot stage ${service}:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+
+  const serviceStage = join(stageRoot, SERVICE_STAGE_SUBDIRECTORY);
+  const appDir = join(serviceStage, APP_DIRECTORY);
+  mkdirSync(serviceStage, { recursive: true });
+  deploy(deployArgs({ service, arch, destination: resolve(appDir) }), root);
+  if (!existsSync(join(appDir, 'dist', 'main.js'))) problems.push(`the deploy of ${service} has no dist/main.js: is dist excluded from the package's files?`);
+
+  // A dependency whose build script matters would have to run on the target; this recipe runs none.
+  const workspaceFile = join(root, 'pnpm-workspace.yaml');
+  const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
+  const prodPackages = deployedPackages(appDir);
+  try {
+    for (const needsBuild of rebuildList({ built, prodPackages })) {
+      problems.push(`${needsBuild} is in the production closure and needs its build script on linux/${arch}; ` +
+        `this recipe runs no scripts (only ${REBUILD_EXCLUDED.join(', ')} are handled)`);
+    }
+  } catch (error) {
+    problems.push(error.message);
+  }
+
+  if (client) cpSync(clientDir, join(appDir, 'node_modules', '.prisma'), { recursive: true, verbatimSymlinks: true });
+
+  let prisma = null;
+  const enginesDirs = prodPackages.some((p) => p.name === 'prisma') ? prismaEnginesDirectories(appDir) : [];
+  const binaryTarget = IMAGE_PLATFORMS[arch].prismaBinaryTarget;
+  for (const enginesDir of enginesDirs) {
+    const { enginesVersion } = createRequire(join(enginesDir, 'package.json'))('@prisma/engines-version');
+    if (prisma !== null && prisma.enginesVersion !== enginesVersion) {
+      problems.push(`the deploy carries two Prisma engines versions (${prisma.enginesVersion}, ${enginesVersion})`);
+      continue;
+    }
+    await fetchEngine({ enginesDir, binaryTarget, enginesVersion });
+    if (!existsSync(join(enginesDir, `schema-engine-${binaryTarget}`))) {
+      problems.push(`the download did not produce schema-engine-${binaryTarget} in ${enginesDir}`);
+      continue;
+    }
+    prisma = { enginesVersion, binaryTarget, sha256: sha256File(join(enginesDir, `schema-engine-${binaryTarget}`)) };
+  }
+
+  const { natives, byPackage, foreign, problems: nativeProblems } = scanNatives(appDir, arch);
+  problems.push(...nativeProblems);
+  if (problems.length > 0) throw new Error(`cannot stage ${service} for linux/${arch}:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    service,
+    path: servicePath,
+    platform: `linux/${arch}`,
+    commit,
+    inputs,
+    nodeAbi: process.versions.modules,
+    natives: byPackage,
+    foreignNatives: foreign.length,
+    prisma,
+    tool: { name: TOOL_NAME, version: toolVersion() },
+  };
+  writeFileSync(join(serviceStage, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+  const toolFiles = copyTool(join(stageRoot, 'tool'));
+  log(`staged ${service} for linux/${arch}: ${prodPackages.length} packages, ${natives.length} native files ` +
+    `(${foreign.length} other-platform files in multi-platform packages), ` +
+    `prisma ${prisma === null ? 'none' : `${prisma.enginesVersion} ${prisma.binaryTarget}`}, tool ${toolFiles} files`);
+  return manifest;
+}

package/src/service-image.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// `xema-service-image`: ONE service's image, built on the CI runner and COPYed into Docker.
+//
+// The per-repository, single-service counterpart of `xema-composed-image`. The lane builds
+// the service on the runner (`turbo run build prisma:generate --filter <service>...`), then:
+//
+//   xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64|arm64> [--stage-dir <dir>]
+//            `pnpm deploy --prod --offline --ignore-scripts` of the service for the TARGET
+//            platform into `<stage>/service/app`, with its Prisma client and the target's schema
+//            engine (fetched and checksum-verified, never cached); refuses a package with no
+//            native binary for the target, dependencies whose build script would have to run,
+//            uncommitted tracked changes and any tool but the one the root installs; writes the
+//            manifest (commit, root build inputs, tool version) and the tool the Dockerfile's
+//            proof stage runs (`service-image-stage.mjs`).
+//
+// The Dockerfile then runs only `prove` (`service-image-in-image.mjs`, on the target, offline)
+// and COPYs `app/`: no install, no build, no registry token in the image build.
+// ═══════════════════════════════════════════════════════════════════════════
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { DEFAULT_STAGE_DIR, stageService } from './service-image-stage.mjs';
+
+const USAGE = 'usage: xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64|arm64> [--stage-dir <dir>]';
+const OPTIONS = new Set(['service', 'path', 'platform', 'stage-dir']);
+
+export function parseStageArgs(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    const name = flag?.startsWith('--') ? flag.slice(2) : undefined;
+    if (name === undefined || !OPTIONS.has(name)) throw new Error(`unknown argument '${flag}'\n${USAGE}`);
+    if (value === undefined || value.startsWith('--')) throw new Error(`${flag} needs a value\n${USAGE}`);
+    if (Object.hasOwn(options, name)) throw new Error(`${flag} is given twice`);
+    options[name] = value;
+  }
+  for (const required of ['service', 'path', 'platform']) {
+    if (!Object.hasOwn(options, required)) throw new Error(`--${required} is required\n${USAGE}`);
+  }
+  return { service: options.service, path: options.path, platform: options.platform, stageDir: options['stage-dir'] ?? DEFAULT_STAGE_DIR };
+}
+
+async function main(argv) {
+  const [verb, ...rest] = argv;
+  if (verb !== 'stage') throw new Error(USAGE);
+  await stageService(parseStageArgs(rest));
+}
+
+// realpath both sides: Node resolves the entry module's symlinks (a pnpm bin shim runs this file
+// through node_modules), `process.argv[1]` keeps them.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`::error::${error.message.split('\n')[0]}`);
+    console.error(error.message);
+    process.exit(1);
+  });
+}