@xemahq/repo-build-tooling 0.14.1 → 0.15.0

package/README.md

@@ -29,11 +29,11 @@ pnpm exec xema-scrub-swagger-paths dist
 | `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-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `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 `--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`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. Run `xema-composed-image` with no arguments for the full usage.
+`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`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `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`, `cache/`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. 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.14.1",
+  "version": "0.15.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -41,9 +41,9 @@
     "@xemahq/release-policy": "^14.0.0"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/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-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-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-migrate.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:c1fafb67e8735c78e8eb13a40fe3a3e9745ad5873b906d7c782e33734f86cf88"
+    "sourceDigest": "sha256:d3f54741da7e081ed21ee59ca2b27600880be97f359fde67028b756528c66153"
   }
 }

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

@@ -0,0 +1,119 @@
+// `xema-composed-image pnpm-context <dir> (--subject <svc>... | --image-dir <composed>)`:
+// builds, on the CI runner and AFTER its `pnpm install --frozen-lockfile`, the pnpm context an
+// offline prebuilt image build consumes as the named BuildKit context `xema-pnpm`. The runner's
+// own pnpm store is the second context (`xema-pnpm-store`); it is never copied.
+//
+//   <dir>/staged.json         { tool, pnpm, storeDir, subjects[], imageDir? } — the sentinel the image checks
+//   <dir>/corepack/pnpm.tgz   `corepack pack pnpm@<root packageManager>`
+//   <dir>/cache/              pnpm `cache-dir` (registry metadata), seeded from the runner's and warmed
+//
+// stdout is exactly two lines for `$GITHUB_ENV`: `XEMA_PNPM_CONTEXT=<dir>` and
+// `XEMA_PNPM_STORE=<store root>`. Everything else goes to stderr. pnpm's own request-level
+// fetch retries apply; nothing here retries a command.
+import { execFileSync } from 'node:child_process';
+import { cpSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+import { memberClosure, memberFilters } from './composed-image-members.mjs';
+import { lockfileOnlyCommand } from './composed-image-prebuilt-dockerfile.mjs';
+import { toolVersion } from './composed-image-stage.mjs';
+
+/** Runs a command, returns stdout; stderr is the caller's. Injectable for tests. */
+const defaultExec = (file, args, { cwd } = {}) =>
+  execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], maxBuffer: 64 * 1024 * 1024 });
+
+/** `pnpm@10.33.0+sha512.…` → `10.33.0`. */
+function pnpmVersion(root) {
+  const manager = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager;
+  const found = typeof manager === 'string' ? /^pnpm@(\d+\.\d+\.\d+)(?:\+.*)?$/.exec(manager) : null;
+  if (found === null) throw new Error(`package.json packageManager must be pnpm@<x.y.z>, got ${JSON.stringify(manager)}`);
+  return found[1];
+}
+
+function seedCache(exec, source, target, log) {
+  mkdirSync(dirname(target), { recursive: true });
+  if (!existsSync(source)) {
+    mkdirSync(target);
+    return 'empty';
+  }
+  try {
+    exec('cp', ['-al', source, target], {});
+    return 'hardlinked';
+  } catch (error) {
+    log(`pnpm-context: cp -al failed (${String(error?.message ?? error).split('\n')[0]}); copying the cache instead`);
+    rmSync(target, { recursive: true, force: true });
+    cpSync(source, target, { recursive: true });
+    return 'copied';
+  }
+}
+
+/** A scratch tree holding exactly the deps stage's inputs, so `--lockfile-only` never touches the repository. */
+function scratchLockfileInputs({ root, imageDir, exec, copy }) {
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-pnpm-lock-'));
+  const put = (rel) => {
+    if (!existsSync(join(root, rel))) return;
+    mkdirSync(dirname(join(scratch, rel)), { recursive: true });
+    copyFileSync(join(root, rel), join(scratch, rel));
+  };
+  for (const rel of ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc']) put(rel);
+  for (const directory of memberClosure({ root, imageDir, exec })) put(`${directory}/package.json`);
+  for (const directory of copy) cpSync(join(root, directory), join(scratch, directory), { recursive: true });
+  return scratch;
+}
+
+export function buildPnpmContext({
+  root = process.cwd(),
+  dir,
+  subjects = [],
+  imageDir,
+  copy = [],
+  exec = defaultExec,
+  log = () => {},
+}) {
+  if (typeof dir !== 'string' || dir.length === 0) throw new Error('pnpm-context needs the output directory: pnpm-context <dir>');
+  if (subjects.length === 0 && imageDir === undefined) throw new Error('pnpm-context needs --subject <svc>… or --image-dir <composed>');
+  if (subjects.length > 0 && imageDir !== undefined) throw new Error('pnpm-context takes --subject or --image-dir, not both');
+  const target = resolve(dir);
+  if (existsSync(target) && readdirSync(target).length > 0) throw new Error(`${dir} already exists and is not empty`);
+
+  const pnpm = pnpmVersion(root);
+  const storePath = exec('pnpm', ['store', 'path'], { cwd: root }).trim();
+  const storeRoot = dirname(storePath);
+  if (storePath === '' || !existsSync(storePath)) {
+    throw new Error(`the runner's pnpm store ${storePath || '(unknown)'} does not exist — run pnpm install --frozen-lockfile before pnpm-context`);
+  }
+  const cacheSource = exec('pnpm', ['config', 'get', 'cache-dir'], { cwd: root }).trim();
+
+  mkdirSync(join(target, 'corepack'), { recursive: true });
+  exec('corepack', ['pack', `pnpm@${pnpm}`, '-o', join(target, 'corepack', 'pnpm.tgz')], { cwd: root });
+  const cache = join(target, 'cache');
+  log(`pnpm-context: cache ${seedCache(exec, cacheSource, cache, log)} from ${cacheSource}`);
+
+  // Warm: the exact metadata requests the offline image build will make, answered from the registry once, here.
+  const base = [`--config.cache-dir=${cache}`];
+  if (subjects.length > 0) {
+    const tmp = mkdtempSync(join(tmpdir(), 'xema-pnpm-deploy-'));
+    try {
+      for (const subject of subjects) {
+        exec('pnpm', ['deploy', '--prod', '--ignore-scripts', '--prefer-offline', ...base, '--filter', subject, join(tmp, subject.replace(/[^A-Za-z0-9._-]/g, '_'))], { cwd: root });
+        log(`pnpm-context: warmed ${subject}`);
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  } else {
+    const scratch = scratchLockfileInputs({ root, imageDir, exec, copy });
+    try {
+      const [file, ...args] = lockfileOnlyCommand(memberFilters({ root, imageDir }).flatMap((f) => f.split(' ')));
+      exec(file, [...args, ...base], { cwd: scratch });
+      log(`pnpm-context: warmed the ${imageDir} lockfile-only resolve`);
+    } finally {
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+
+  const sentinel = { tool: toolVersion(), pnpm, storeDir: storeRoot, subjects: [...subjects], ...(imageDir === undefined ? {} : { imageDir }) };
+  writeFileSync(join(target, 'staged.json'), `${JSON.stringify(sentinel, null, 2)}\n`);
+  return { context: target, store: storeRoot };
+}

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

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { buildPnpmContext } from './composed-image-pnpm-context.mjs';
+import { lockfileOnlyCommand, renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
+import { CLOSURE, fakePnpm, workspace, write } from './composed-image-fixture.test.mjs';
+
+function setup({ store = true, cache = true } = {}) {
+  const root = workspace();
+  write(root, 'package.json', { name: 'r', packageManager: 'pnpm@10.33.0+sha512.abc' });
+  write(root, 'pnpm-lock.yaml', 'lockfileVersion: 9\n');
+  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');
+  if (store) fs.mkdirSync(storePath, { recursive: true });
+  if (cache) write(home, 'cache/metadata-v1.3/registry.npmjs.org/x.json', '{}');
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-out-')), 'ctx');
+  const pnpmLs = fakePnpm(root, CLOSURE);
+  const calls = [];
+  const exec = (file, args, options = {}) => {
+    calls.push({ file, args, cwd: options.cwd, scratch: options.cwd !== root && options.cwd !== undefined ? fs.readdirSync(options.cwd) : undefined });
+    if (file === 'pnpm' && args[0] === 'ls') return pnpmLs(file, args, options);
+    if (file === 'pnpm' && args[0] === 'store') return `${storePath}\n`;
+    if (file === 'pnpm' && args[0] === 'config') return `${cacheDir}\n`;
+    if (file === 'corepack') {
+      fs.writeFileSync(args[args.indexOf('-o') + 1], 'tgz');
+      return '';
+    }
+    if (file === 'cp') {
+      fs.cpSync(args[1], args[2], { recursive: true });
+      return '';
+    }
+    return '';
+  };
+  return { root, out, exec, calls, storePath, home };
+}
+
+test('--subject: writes corepack tgz, a seeded and warmed cache dir, and the sentinel; returns the two env values', () => {
+  const { root, out, exec, calls, home } = setup();
+  const result = buildPnpmContext({ root, dir: out, subjects: ['svc-a', 'svc-b'], exec });
+  assert.deepEqual(result, { context: out, store: path.join(home, '.pnpm-store') });
+  assert.equal(fs.readFileSync(path.join(out, 'corepack/pnpm.tgz'), 'utf8'), 'tgz');
+  assert.ok(fs.existsSync(path.join(out, 'cache/metadata-v1.3/registry.npmjs.org/x.json')));
+  const staged = JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8'));
+  assert.deepEqual(Object.keys(staged), ['tool', 'pnpm', 'storeDir', 'subjects']);
+  assert.equal(staged.pnpm, '10.33.0');
+  assert.deepEqual(staged.subjects, ['svc-a', 'svc-b']);
+  assert.deepEqual(calls.find((c) => c.file === 'corepack').args.slice(0, 2), ['pack', 'pnpm@10.33.0']);
+  const deploys = calls.filter((c) => c.args[0] === 'deploy');
+  assert.equal(deploys.length, 2);
+  for (const d of deploys) {
+    for (const flag of ['--prod', '--ignore-scripts', '--prefer-offline', `--config.cache-dir=${path.join(out, 'cache')}`]) assert.ok(d.args.includes(flag), flag);
+    assert.ok(!fs.existsSync(d.args.at(-1)), 'the deploy target is deleted');
+  }
+});
+
+test('refuses a non-empty directory, a missing store, and a bad invocation, writing nothing', () => {
+  const full = setup();
+  write(full.out, 'old', 'x');
+  assert.throws(() => buildPnpmContext({ root: full.root, dir: full.out, subjects: ['s'], exec: full.exec }), /not empty/);
+  const none = setup({ store: false });
+  assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, subjects: ['s'], exec: none.exec }), /pnpm store .* does not exist/);
+  assert.equal(fs.existsSync(none.out), false);
+  assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, exec: none.exec }), /--subject/);
+  assert.throws(() => buildPnpmContext({ root: none.root, dir: none.out, subjects: ['s'], imageDir: 'x', exec: none.exec }), /not both/);
+});
+
+test('--image-dir: runs the generator\'s lockfile-only command on a scratch copy and leaves the repository lockfile alone', () => {
+  const { root, out, exec, calls } = setup({ cache: false });
+  buildPnpmContext({ root, dir: out, imageDir: 'infra/composed-process', exec });
+  const resolve = calls.find((c) => c.args.includes('--lockfile-only'));
+  assert.notEqual(resolve.cwd, root);
+  assert.ok(resolve.scratch.includes('pnpm-lock.yaml') && resolve.scratch.includes('package.json'));
+  assert.ok(resolve.args.includes(`--config.cache-dir=${path.join(out, 'cache')}`));
+  assert.equal(fs.existsSync(resolve.cwd), false, 'the scratch tree is deleted');
+  assert.equal(fs.readFileSync(path.join(root, 'pnpm-lock.yaml'), 'utf8'), 'lockfileVersion: 9\n');
+  assert.equal(JSON.parse(fs.readFileSync(path.join(out, 'staged.json'), 'utf8')).imageDir, 'infra/composed-process');
+});
+
+test('the lockfile-only command is the one the generated Dockerfile runs (no drift)', () => {
+  const root = workspace();
+  const words = lockfileOnlyCommand(['--filter', '@t/alpha-api...']);
+  assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--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', usesToken: false, exec: fakePnpm(root) });
+  assert.ok(text.includes('pnpm install --lockfile-only --prefer-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"'));
+});
+
+test('a failed cp -al falls back to a copy and logs why', () => {
+  const { root, out, exec, home } = setup();
+  const logs = [];
+  const failing = (file, args, options) => {
+    if (file === 'cp') throw new Error('cross-device link');
+    return exec(file, args, options);
+  };
+  buildPnpmContext({ root, dir: out, subjects: ['s'], exec: failing, log: (m) => logs.push(m) });
+  assert.ok(logs.some((m) => /cp -al failed \(cross-device link\)/.test(m)));
+  assert.ok(fs.existsSync(path.join(out, 'cache/metadata-v1.3/registry.npmjs.org/x.json')));
+  assert.ok(home);
+});

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

@@ -62,6 +62,19 @@ export function onlyBuiltDependencies(workspaceYaml) {
   return names;
 }
 
+/** The install-flag word the rendered RUN keeps as a shell variable; `injectFlags()` is what it expands to. */
+export const INJECT_TOKEN = '${INJECT}';
+export const injectFlags = () => ['--config.inject-workspace-packages=true', '--config.dedupe-injected-deps=false'];
+
+/**
+ * The deps stage's `--lockfile-only` resolve, as words (`INJECT_TOKEN` stands for `injectFlags()`).
+ * The Dockerfile renderer and `xema-composed-image pnpm-context` both read THIS function, so the
+ * metadata the context warms is exactly what the image resolves.
+ */
+export const lockfileOnlyWords = (filters) => ['pnpm', 'install', '--lockfile-only', '--prefer-offline', INJECT_TOKEN, ...filters];
+/** The same command with the inject words expanded: `[file, ...args]`. */
+export const lockfileOnlyCommand = (filters) => lockfileOnlyWords(filters).flatMap((w) => (w === INJECT_TOKEN ? injectFlags() : [w]));
+
 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. */
@@ -143,9 +156,9 @@ ${parts(manifestSources)}
 RUN ${store} \\
   ${metadata} \\
 ${secret}  ${toolMount} \\
-  ${tokenExport}INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false" && \\
+  ${tokenExport}INJECT="${injectFlags().join(' ')}" && \\
   cp pnpm-lock.yaml /tmp/pnpm-lock.committed.yaml && \\
-  pnpm install --lockfile-only --prefer-offline \${INJECT} ${filters} && \\
+  ${lockfileOnlyWords(filters.split(' ')).join(' ')} && \\
   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}

package/src/composed-image-stage.mjs

@@ -5,7 +5,8 @@
 //
 //   <dir>/out/<package dir>/<output>/               every closure package's outputs (default: dist);
 //                                                   `--also <pkg>` adds that package's closure (no member checks)
-//   <dir>/out/<member>/node_modules/.prisma/        every member's generated Prisma clients
+//   <dir>/out/<pkg dir>/node_modules/.prisma/       the generated Prisma clients of every closure root that has
+//                                                   `prisma/schema.prisma` (members and `--also` roots alike)
 //   <dir>/tool/                                     this package (package.json + src, no tests):
 //                                                   bind-mounted into the build, never copied into a layer
 //
@@ -124,12 +125,25 @@ export async function stageBuildOutputs({
   const plan = []; // { source, destination, files }
   for (const directory of closure) {
     const sources = outputs.map((output) => posix.join(directory, output));
-    if (memberDirectories.has(directory)) sources.push(posix.join(directory, 'node_modules', '.prisma'));
+    // Members always (their checks above name a missing client); any other closure root when it carries a schema.
+    if (memberDirectories.has(directory) || existsSync(join(root, directory, 'prisma', 'schema.prisma'))) {
+      sources.push(posix.join(directory, 'node_modules', '.prisma'));
+    }
     for (const rel of sources) {
       const source = join(root, rel);
-      if (!existsSync(source)) continue;
+      if (!existsSync(source)) {
+        if (rel.endsWith('/node_modules/.prisma') && !memberDirectories.has(directory)) {
+          problems.push(`${directory} has prisma/schema.prisma but no generated client: run prisma generate`);
+        }
+        continue;
+      }
       const files = listFiles(source);
       for (const file of files) if (file.endsWith('.node')) problems.push(`${rel}/${file}: a native addon cannot be staged (the image installs native code itself, per arch)`);
+      if (rel.endsWith('/node_modules/.prisma')) {
+        for (const file of files) {
+          if (/^libquery_engine/.test(posix.basename(file))) problems.push(`${rel}/${file}: a query engine cannot be staged (the Prisma client must be pure JS/wasm)`);
+        }
+      }
       plan.push({ source, destination: join(target, 'out', rel), files });
     }
   }

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

@@ -151,3 +151,25 @@ test('filters and the argument parser carry --also', async () => {
   assert.equal(memberFilters({ root, also: ['@t/alpha-api'] }).filter((f) => f === '--filter @t/alpha-api...').length, 1);
   assert.deepEqual(parseArguments(['stage', 'd', '--also', 'a', '--also', 'b']).options.also, ['a', 'b']);
 });
+
+test('--also stages node_modules/.prisma of an extra closure root that has a schema, and refuses a query engine in it', async () => {
+  const root = withExtra();
+  write(root, 'packages/sdks/extra/prisma/schema.prisma', 'datasource db {}\n');
+  write(root, 'packages/sdks/extra/node_modules/.prisma/client/index.js', '// client\n');
+  const result = await stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] });
+  assert.ok(result.outputs >= 5);
+  assert.ok(files(path.join(root, '.xema-stage/out')).includes('packages/sdks/extra/node_modules/.prisma/client/index.js'));
+  fs.rmSync(path.join(root, '.xema-stage'), { recursive: true });
+  write(root, 'packages/sdks/extra/node_modules/.prisma/client/libquery_engine-linux-arm64-openssl-3.0.x.so', 'x');
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /extra\/node_modules\/\.prisma\/client\/libquery_engine.*pure JS\/wasm/);
+  fs.rmSync(path.join(root, 'packages/sdks/extra/node_modules/.prisma/client/libquery_engine-linux-arm64-openssl-3.0.x.so'));
+  write(root, 'packages/sdks/extra/node_modules/.prisma/client/query.node', 'x');
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /extra\/node_modules\/\.prisma\/client\/query\.node/);
+});
+
+test('--also refuses a non-member closure root with prisma/schema.prisma but no generated client', async () => {
+  const root = withExtra();
+  write(root, 'packages/sdks/extra/prisma/schema.prisma', 'datasource db {}\n');
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /packages\/sdks\/extra has prisma\/schema\.prisma but no generated client: run prisma generate/);
+  assert.equal(fs.existsSync(path.join(root, '.xema-stage')), false);
+});

package/src/composed-image.mjs

@@ -44,6 +44,11 @@
 //            generated Prisma clients into a build-step directory, with this tool,
 //            for the `--prebuilt` Dockerfile (`composed-image-stage.mjs`). Each `--also`
 //            workspace package adds its closure's built outputs (no Prisma checks).
+//   pnpm-context <dir> (--subject <svc>… | --image-dir <composed>) [--copy <dir>]…
+//            CI-runner only, after `pnpm install --frozen-lockfile`: build the offline `xema-pnpm`
+//            build context (corepack pnpm.tgz, warmed metadata cache, staged.json) for the
+//            prebuilt Dockerfiles (`composed-image-pnpm-context.mjs`). stdout is
+//            `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` for `$GITHUB_ENV`.
 //   sync-injected | prisma-check
 //            IN-IMAGE proofs of the prebuilt build: the injected workspace copies hold
 //            their packages' `files`; every Prisma client runs on the target arch.
@@ -101,6 +106,7 @@ import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
 import { IMAGE_BUILD_INPUTS_FILE, memberClosure, memberFilters, readMembers } from './composed-image-members.mjs';
 import { syncPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { stageBuildOutputs } from './composed-image-stage.mjs';
+import { buildPnpmContext } from './composed-image-pnpm-context.mjs';
 import { syncInjected } from './composed-image-sync-injected.mjs';
 import { prismaCheck } from './composed-image-prisma-check.mjs';
 import { runMigrate } from './composed-migrate.mjs';
@@ -313,6 +319,7 @@ const USAGE =
   'usage: xema-composed-image <command> [--root <dir>] [--image-dir <dir>]\n' +
   '  members --write|--check [--manifests <glob>]… [--canonical-dockerfile <path>] [--cross-repo-manifest <path>]\n' +
   '  filters [--also <pkg>]… | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load [--each]\n' +
+  '  pnpm-context <dir> (--subject <svc>… | --image-dir <composed>) [--copy <dir>]…\n' +
   '  stage <dir> [--output <rel>]… [--also <pkg>]…   | sync-injected | prisma-check | migrate <member> [--root <dir>]\n' +
   '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG [TAG_ARGS_FILE])\n' +
   '  load-image <image>\n' +
@@ -320,10 +327,10 @@ const USAGE =
   '  dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>\n' +
   '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]';
 
-const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output', 'also']);
+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',
-  'image-name', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also',
+  'image-name', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
 ]);
 
 export function parseArguments(argv) {
@@ -403,6 +410,18 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
         log(`composed stage ${argument}: ${staged.packages} package(s), ${staged.outputs} output dir(s), ${staged.files} file(s), tool ${staged.toolFiles} file(s)`);
       });
     }
+    case 'pnpm-context': {
+      const result = buildPnpmContext({
+        root,
+        dir: argument,
+        subjects: options.subject,
+        imageDir: options.subject === undefined ? options['image-dir'] : undefined,
+        copy: options.copy,
+        log: (message) => process.stderr.write(`${message}\n`),
+      });
+      write(`XEMA_PNPM_CONTEXT=${result.context}\nXEMA_PNPM_STORE=${result.store}\n`);
+      return;
+    }
     case 'sync-injected':
       syncInjected({ root, imageDir, log });
       return;