@xemahq/repo-build-tooling 0.10.2 → 0.12.0

package/src/composed-image-prisma-check.mjs

@@ -0,0 +1,127 @@
+// `xema-composed-image prisma-check`, INSIDE the image build, on the TARGET arch.
+// Every member that owns a Prisma schema carries its generated client(s) in
+// `<member>/node_modules/.prisma/<client>/`, generated on the CI runner and staged
+// without running anything. Each client's schema must be the member's own schema as
+// `prisma format` writes it, or the client is stale. The image carries no native engine: the only supported
+// client is Rust-free (a wasm query compiler plus a driver adapter). This refuses any
+// native engine file, compiles the wasm, checks the client matches the member's
+// `prisma` CLI, and constructs it. It never connects.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { readMembers } from './composed-image-members.mjs';
+import { clientSchemaProblems, memberPrismaSchema } from './composed-migrate.mjs';
+
+const NATIVE_ENGINE = [/^libquery_engine-.*\.node$/, /^query-engine-/, /\.so\.node$/, /\.dll\.node$/, /\.dylib\.node$/];
+const WASM_COMPILER = /^query_compiler.*_bg\.wasm$/;
+
+/** Split a client directory's file names into native engine files (refused) and wasm query compilers (required). */
+export function classifyClientFiles(files) {
+  return {
+    native: files.filter((file) => NATIVE_ENGINE.some((pattern) => pattern.test(file))).sort(),
+    wasm: files.filter((file) => WASM_COMPILER.test(file)).sort(),
+  };
+}
+
+function cliVersion(memberRequire, memberDirectory) {
+  const direct = join(memberDirectory, 'node_modules', 'prisma', 'package.json');
+  const path = existsSync(direct) ? direct : memberRequire.resolve('prisma/package.json');
+  return JSON.parse(readFileSync(path, 'utf8')).version;
+}
+
+/** Every client's schema verdict, the formats run concurrently: `Map<clientDir, problem|undefined>`. */
+async function schemaVerdicts({ root, imageDir, formatSpawn, concurrency }) {
+  const jobs = [];
+  for (const [, directory] of readMembers({ root, imageDir })) {
+    try {
+      if (memberPrismaSchema(root, directory) === undefined) continue;
+    } catch {
+      continue; // reported by the main pass
+    }
+    const container = join(root, directory, 'node_modules', '.prisma');
+    if (!existsSync(container)) continue;
+    for (const entry of readdirSync(container, { withFileTypes: true }).filter((e) => e.isDirectory())) {
+      jobs.push({ root, memberDir: directory, clientDir: join(container, entry.name) });
+    }
+  }
+  const verdicts = await clientSchemaProblems(jobs, { spawn: formatSpawn, concurrency });
+  return new Map(jobs.map((job, i) => [job.clientDir, verdicts[i]]));
+}
+
+export async function prismaCheck({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, log = console.log, formatSpawn, concurrency } = {}) {
+  const problems = [];
+  const stale = await schemaVerdicts({ root, imageDir, formatSpawn, concurrency });
+  let clients = 0;
+  for (const [key, directory] of readMembers({ root, imageDir })) {
+    const memberDirectory = join(root, directory);
+    let schema;
+    try {
+      schema = memberPrismaSchema(root, directory);
+    } catch (error) {
+      problems.push(`${key}: ${error.message}`);
+      continue;
+    }
+    const container = join(memberDirectory, 'node_modules', '.prisma');
+    const dirs = existsSync(container) ? readdirSync(container, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort() : [];
+    if (schema === undefined && dirs.length === 0) continue;
+    if (schema === undefined) {
+      problems.push(`${key}: ships node_modules/.prisma/${dirs.join(', ')} but has no prisma/schema.prisma`);
+      continue;
+    }
+    if (dirs.length === 0) {
+      problems.push(`${key}: ${directory}/node_modules/.prisma has no generated client`);
+      continue;
+    }
+    const memberRequire = createRequire(join(memberDirectory, 'package.json'));
+    for (const name of dirs) {
+      clients += 1;
+      const label = `${key} (.prisma/${name})`;
+      const clientDirectory = join(container, name);
+      const staleProblem = stale.get(clientDirectory);
+      if (staleProblem !== undefined) {
+        problems.push(`${label}: ${staleProblem}`);
+        continue;
+      }
+      const { native, wasm } = classifyClientFiles(readdirSync(clientDirectory));
+      if (native.length > 0) {
+        problems.push(`${label}: native engine file(s) ${native.join(', ')} — the image carries no native engine; generate a Rust-free client`);
+        continue;
+      }
+      if (wasm.length === 0) {
+        problems.push(`${label}: no query_compiler*_bg.wasm — not a Rust-free client`);
+        continue;
+      }
+      for (const file of wasm) {
+        try {
+          await WebAssembly.compile(readFileSync(join(clientDirectory, file)));
+        } catch (error) {
+          problems.push(`${label}: ${file} does not compile: ${error?.message ?? String(error)}`);
+        }
+      }
+      try {
+        const client = memberRequire(clientDirectory);
+        const generated = client.Prisma?.prismaVersion?.client;
+        const cli = cliVersion(memberRequire, memberDirectory);
+        if (generated !== cli) problems.push(`${label}: generated client is ${generated}, the member's prisma CLI is ${cli}`);
+        let PrismaPg;
+        try {
+          ({ PrismaPg } = memberRequire('@prisma/adapter-pg'));
+        } catch (error) {
+          problems.push(`${label}: Rust-free client but the member cannot resolve @prisma/adapter-pg (${error?.message ?? error})`);
+          continue;
+        }
+        const instance = new client.PrismaClient({
+          adapter: new PrismaPg({ connectionString: 'postgresql://prisma-check@127.0.0.1:1/prisma-check' }),
+        });
+        await instance.$disconnect();
+      } catch (error) {
+        problems.push(`${label}: the client does not construct: ${error?.message ?? String(error)}`);
+      }
+    }
+  }
+  if (problems.length > 0) throw new Error(`prisma clients cannot run in this image:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  log(`composed prisma-check: ${clients} generated client(s) are Rust-free and construct on ${process.platform}/${process.arch}`);
+  return clients;
+}

package/src/composed-image-prisma-check.test.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { classifyClientFiles, prismaCheck } from './composed-image-prisma-check.mjs';
+import { formatNoop, workspace, write } from './composed-image-fixture.test.mjs';
+
+test('native engine files are separated from wasm query compilers', () => {
+  assert.deepEqual(classifyClientFiles(['index.js', 'query_compiler_fast_bg.wasm', 'query_compiler_fast_bg.js']), { native: [], wasm: ['query_compiler_fast_bg.wasm'] });
+  for (const native of ['libquery_engine-debian-openssl-3.0.x.so.node', 'query-engine-debian-openssl-3.0.x', 'a.dll.node', 'a.dylib.node']) {
+    assert.deepEqual(classifyClientFiles([native, 'index.js']).native, [native]);
+  }
+  assert.deepEqual(classifyClientFiles(['index.js']), { native: [], wasm: [] });
+});
+
+test('any native engine file is refused outright, as is a client with no wasm compiler', async () => {
+  const root = workspace();
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/libquery_engine-debian-openssl-3.0.x.so.node', 'x');
+  await assert.rejects(prismaCheck({ root, log() {}, formatSpawn: formatNoop }), /native engine file\(s\) libquery_engine-debian-openssl-3\.0\.x\.so\.node/);
+  const bare = workspace();
+  await assert.rejects(prismaCheck({ root: bare, log() {}, formatSpawn: formatNoop }), /no query_compiler\*_bg\.wasm/);
+});
+
+test('a shipped client with no schema, a schema directory and a non-default config path are refused', async () => {
+  const noSchema = workspace();
+  write(noSchema, 'biomes/alpha/api/alpha-api/node_modules/.prisma/alpha-api/index.js', '//');
+  await assert.rejects(prismaCheck({ root: noSchema, log() {}, formatSpawn: formatNoop }), /alpha\/alpha-api: ships node_modules\/\.prisma\/alpha-api but has no prisma\/schema\.prisma/);
+  const dir = workspace();
+  write(dir, 'biomes/alpha/api/alpha-db-api/prisma/schema/a.prisma', '');
+  await assert.rejects(prismaCheck({ root: dir, log() {}, formatSpawn: formatNoop }), /multi-file schema/);
+  const config = workspace();
+  write(config, 'biomes/alpha/api/alpha-db-api/prisma.config.ts', "export default { schema: 'db/schema.prisma' };\n");
+  await assert.rejects(prismaCheck({ root: config, log() {}, formatSpawn: formatNoop }), /supports only "prisma\/schema\.prisma"/);
+});
+
+test('a stale client (the source gained a field after generation) is refused; the matching one gets past the schema check', async () => {
+  const stale = workspace();
+  write(stale, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', 'datasource db {}\nmodel A { id Int @id }\n');
+  await assert.rejects(prismaCheck({ root: stale, log() {}, formatSpawn: formatNoop }), /differs from the member's prisma\/schema\.prisma .*stale/);
+  await assert.rejects(prismaCheck({ root: workspace(), log() {}, formatSpawn: formatNoop }), (e) => !/stale/.test(e.message));
+});

package/src/composed-image-stage.mjs

@@ -0,0 +1,148 @@
+// `xema-composed-image stage <dir>`: gathers the build outputs the CI runner made
+// (`turbo run build prisma:generate` over the members' closures) into one build-step
+// directory the `--prebuilt` Dockerfile copies from. Docker compiles nothing; this
+// is the only place outputs enter an image, so it is also where they are refused.
+//
+//   <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>/tool/                                     this package (package.json + src, no tests):
+//                                                   bind-mounted into the build, never copied into a layer
+//
+// Staged outputs must be pure JS/wasm: native code comes only from the arch-native
+// install inside the image. Nothing is written with a timestamp or an unsorted order.
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, symlinkSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { memberClosure, readMembers } from './composed-image-members.mjs';
+import { clientSchemaProblems, memberPrismaSchema } from './composed-migrate.mjs';
+
+export const DEFAULT_OUTPUTS = Object.freeze(['dist']);
+const TOOL_PACKAGE = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Every file under `dir` (symlinks included, not followed), relative, sorted. */
+function listFiles(dir, prefix = '') {
+  const found = [];
+  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()) found.push(...listFiles(join(dir, entry.name), rel));
+    else found.push(rel);
+  }
+  return found;
+}
+
+function copyFiles(sourceDir, targetDir, files) {
+  for (const rel of files) {
+    const source = join(sourceDir, rel);
+    const target = join(targetDir, rel);
+    mkdirSync(dirname(target), { recursive: true });
+    if (lstatSync(source).isSymbolicLink()) symlinkSync(readlinkSync(source), target);
+    else copyFileSync(source, target);
+  }
+}
+
+function renderedDockerfile(root, imageDir) {
+  const path = join(root, imageDir, 'Dockerfile');
+  if (!existsSync(path)) throw new Error(`${imageDir}/Dockerfile is absent — render it first: xema-composed-image dockerfile --prebuilt --write`);
+  return readFileSync(path, 'utf8');
+}
+
+/** Copy `package.json` + `src/` (no `*.test.mjs`) of this package to `<dir>/tool`. */
+function copyTool(target) {
+  const files = ['package.json', ...listFiles(join(TOOL_PACKAGE, 'src')).filter((f) => !f.endsWith('.test.mjs')).map((f) => `src/${f}`)];
+  copyFiles(TOOL_PACKAGE, target, files);
+  return files.length;
+}
+
+export function toolVersion() {
+  return JSON.parse(readFileSync(join(TOOL_PACKAGE, 'package.json'), 'utf8')).version;
+}
+
+/** Stage the closure's outputs under `dir`; returns counts. Throws once, naming every offender. */
+export async function stageBuildOutputs({
+  root = process.cwd(),
+  imageDir = COMPOSED_IMAGE_DIR,
+  dir,
+  outputs = DEFAULT_OUTPUTS,
+  also = [],
+  exec,
+  nodeMajor = process.versions.node.split('.')[0],
+  formatSpawn,
+  concurrency,
+}) {
+  if (typeof dir !== 'string' || dir.length === 0) throw new Error('stage needs the build-step directory: stage <dir>');
+  if (outputs.length === 0) throw new Error('--output needs at least one directory');
+  const target = join(root, dir);
+  if (existsSync(target) && readdirSync(target).length > 0) throw new Error(`${dir} already exists and is not empty`);
+
+  const problems = [];
+  const dockerfile = renderedDockerfile(root, imageDir);
+  const fromNode = /^FROM\s+\S*node:(\d+)[-@\s]/m.exec(dockerfile);
+  if (fromNode === null) problems.push(`${imageDir}/Dockerfile has no base FROM …node:<major>-…`);
+  else if (fromNode[1] !== String(nodeMajor)) {
+    problems.push(`the runner's Node ${nodeMajor} differs from the image's Node ${fromNode[1]} (${imageDir}/Dockerfile)`);
+  }
+  const pinned = /@xemahq\/repo-build-tooling@(\d+\.\d+\.\d+)/.exec(dockerfile);
+  if (pinned === null) problems.push(`${imageDir}/Dockerfile header pins no @xemahq/repo-build-tooling@<x.y.z>`);
+  else if (pinned[1] !== toolVersion()) {
+    problems.push(`this tool is ${toolVersion()} but ${imageDir}/Dockerfile pins ${pinned[1]}`);
+  }
+
+  const members = readMembers({ root, imageDir }).map(([key, directory]) => ({ key, directory }));
+  const memberDirectories = new Set(members.map((m) => m.directory));
+  const closure = memberClosure({ root, imageDir, exec, also });
+  const schemaJobs = [];
+  for (const { key, directory } of members) {
+    if (!closure.includes(directory)) problems.push(`${key}: ${directory} is not in the closure pnpm selected`);
+    if (!existsSync(join(root, directory, 'dist', 'main.js'))) problems.push(`${key}: ${directory}/dist/main.js does not exist — build it first`);
+    let schema;
+    try {
+      schema = memberPrismaSchema(root, directory);
+    } catch (error) {
+      problems.push(`${key}: ${error.message}`);
+      continue;
+    }
+    const clients = join(root, directory, 'node_modules', '.prisma');
+    const hasClient = existsSync(clients) && readdirSync(clients, { withFileTypes: true }).some((e) => e.isDirectory());
+    if (schema !== undefined && !hasClient) problems.push(`${key}: ${directory} has prisma/schema.prisma but no node_modules/.prisma/<client>/ — run prisma generate`);
+    if (schema !== undefined && hasClient) {
+      for (const entry of readdirSync(clients, { withFileTypes: true }).filter((e) => e.isDirectory())) {
+        schemaJobs.push({ key, root, memberDir: directory, clientDir: join(clients, entry.name) });
+      }
+    }
+    if (schema === undefined && hasClient) problems.push(`${key}: ${directory} ships node_modules/.prisma/<client>/ but has no prisma/schema.prisma`);
+  }
+
+  // The formats run concurrently; their problems are reported in member order.
+  const verdicts = await clientSchemaProblems(schemaJobs, { spawn: formatSpawn, concurrency });
+  verdicts.forEach((problem, i) => {
+    if (problem !== undefined) problems.push(`${schemaJobs[i].key}: ${problem}`);
+  });
+
+  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'));
+    for (const rel of sources) {
+      const source = join(root, rel);
+      if (!existsSync(source)) 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)`);
+      plan.push({ source, destination: join(target, 'out', rel), files });
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`cannot stage ${dir}:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+
+  mkdirSync(target, { recursive: true });
+  let fileCount = 0;
+  for (const { source, destination, files } of plan) {
+    copyFiles(source, destination, files);
+    fileCount += files.length;
+  }
+  const toolFiles = copyTool(join(target, 'tool'));
+  return { packages: closure.length, outputs: plan.length, files: fileCount, toolFiles };
+}

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

@@ -0,0 +1,153 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+
+import { stageBuildOutputs, toolVersion } from './composed-image-stage.mjs';
+import { fakePnpm, formatNoop, workspace, write } from './composed-image-fixture.test.mjs';
+
+function ready(extra = {}) {
+  const root = workspace(extra);
+  write(root, 'infra/composed-process/Dockerfile', `# @generated (@xemahq/repo-build-tooling@${toolVersion()})\nFROM mirror.gcr.io/library/node:22-bookworm-slim@sha256:abc AS base\n`);
+  return root;
+}
+const stage = (root, extra = {}) => stageBuildOutputs({ root, dir: '.xema-stage', exec: fakePnpm(root), nodeMajor: '22', formatSpawn: formatNoop, ...extra });
+const files = (dir) => fs.readdirSync(dir, { recursive: true }).map(String).sort();
+
+test('stages dist of every closure package, the members prisma clients, and the tool without tests', async () => {
+  const root = ready();
+  const result = await stage(root);
+  assert.equal(result.packages, 3);
+  const staged = files(path.join(root, '.xema-stage/out'));
+  for (const expected of [
+    'biomes/alpha/api/alpha-api/dist/main.js',
+    'biomes/alpha/api/alpha-db-api/dist/main.js',
+    'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/index.js',
+    'packages/sdks/lib-a/dist/index.js',
+  ]) assert.ok(staged.includes(expected), expected);
+  const tool = files(path.join(root, '.xema-stage/tool'));
+  assert.ok(tool.includes('package.json') && tool.includes('src/composed-image.mjs') && tool.includes('src/composed-migrate.mjs'));
+  assert.equal(tool.filter((f) => f.endsWith('.test.mjs')).length, 0);
+  assert.deepEqual(files(path.join(root, '.xema-stage')).filter((f) => !/^(out|tool)(\/|$)/.test(f)), []);
+});
+
+test('--output replaces the default list', async () => {
+  const root = ready();
+  write(root, 'packages/sdks/lib-a/generated/x.js', '//\n');
+  await stage(root, { outputs: ['generated'] });
+  const staged = files(path.join(root, '.xema-stage/out'));
+  assert.ok(staged.includes('packages/sdks/lib-a/generated/x.js'));
+  assert.ok(!staged.includes('packages/sdks/lib-a/dist/index.js'));
+});
+
+test('refuses a native addon anywhere in the staged outputs, naming it', async () => {
+  const root = ready();
+  write(root, 'packages/sdks/lib-a/dist/native/addon.node', 'x');
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/libquery_engine-darwin.so.node', 'x');
+  await assert.rejects(stage(root), (e) => /lib-a\/dist\/native\/addon\.node/.test(e.message) && /libquery_engine-darwin\.so\.node/.test(e.message));
+  assert.equal(fs.existsSync(path.join(root, '.xema-stage')), false);
+});
+
+test('refuses a member without dist/main.js and a schema without a generated client', async () => {
+  const root = ready();
+  fs.rmSync(path.join(root, 'biomes/alpha/api/alpha-api/dist/main.js'));
+  fs.rmSync(path.join(root, 'biomes/alpha/api/alpha-db-api/node_modules'), { recursive: true });
+  await assert.rejects(stage(root), (e) => /alpha\/alpha-api: .*dist\/main\.js does not exist/.test(e.message) && /alpha-db-api: .*no node_modules\/\.prisma/.test(e.message));
+});
+
+test('refuses a runner Node major that differs from the image base, and an absent Dockerfile or FROM', async () => {
+  const root = ready();
+  await assert.rejects(stage(root, { nodeMajor: '24' }), /Node 24 differs from the image's Node 22/);
+  fs.writeFileSync(path.join(root, 'infra/composed-process/Dockerfile'), `# (@xemahq/repo-build-tooling@${toolVersion()})\nFROM scratch\n`);
+  await assert.rejects(stage(root), /no base FROM/);
+  fs.rmSync(path.join(root, 'infra/composed-process/Dockerfile'));
+  await assert.rejects(stage(root), /Dockerfile is absent/);
+});
+
+test('refuses a tool version that differs from the rendered Dockerfile pin', async () => {
+  const root = ready();
+  write(root, 'infra/composed-process/Dockerfile', '# (@xemahq/repo-build-tooling@0.0.1)\nFROM node:22-slim AS base\n');
+  await assert.rejects(stage(root), /pins 0\.0\.1/);
+});
+
+test('refuses a non-empty directory and is deterministic', async () => {
+  const root = ready();
+  write(root, '.xema-stage/old', 'x');
+  await assert.rejects(stage(root), /not empty/);
+  fs.rmSync(path.join(root, '.xema-stage'), { recursive: true });
+  await stage(root);
+  const first = files(path.join(root, '.xema-stage'));
+  fs.rmSync(path.join(root, '.xema-stage'), { recursive: true });
+  await stage(root);
+  assert.deepEqual(files(path.join(root, '.xema-stage')), first);
+});
+
+test('refuses a shipped client with no schema, a schema directory and a non-default config path', async () => {
+  const noSchema = ready();
+  write(noSchema, 'biomes/alpha/api/alpha-api/node_modules/.prisma/alpha-api/index.js', '//');
+  await assert.rejects(stage(noSchema), /ships node_modules\/\.prisma\/<client>\/ but has no prisma\/schema\.prisma/);
+  const dir = ready();
+  write(dir, 'biomes/alpha/api/alpha-db-api/prisma/schema/a.prisma', '');
+  await assert.rejects(stage(dir), /multi-file schema/);
+  const config = ready();
+  write(config, 'biomes/alpha/api/alpha-db-api/prisma.config.ts', "export default { schema: 'db/schema.prisma' };\n");
+  await assert.rejects(stage(config), /supports only/);
+});
+
+test('refuses a client generated from another schema than the member carries; the matching one stages', async () => {
+  const stale = ready();
+  write(stale, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', 'datasource db {}\nmodel A { id Int @id }\n');
+  await assert.rejects(stage(stale), /alpha-db-api: .*differs from the member's prisma\/schema\.prisma .*stale/);
+  assert.equal((await stage(ready())).packages, 3);
+});
+
+/** An `exec` that answers per-name probes (`--filter <name>`) and the closure listing (`--filter <name>...`). */
+function alsoPnpm(root, known) {
+  return (_file, args) => {
+    const filters = args.flatMap((a, i) => (args[i - 1] === '--filter' ? [a] : []));
+    const names = filters.filter((f) => !f.endsWith('...'));
+    if (names.length > 0) return JSON.stringify(known.filter((p) => p.name === names[0]).map((p) => ({ name: p.name, path: path.join(root, p.dir) })));
+    const wanted = new Set(filters.map((f) => f.slice(0, -3)));
+    const dirs = new Set(['biomes/alpha/api/alpha-api', 'biomes/alpha/api/alpha-db-api', 'packages/sdks/lib-a']);
+    for (const p of known) if (wanted.has(p.name)) for (const d of p.closure) dirs.add(d);
+    return JSON.stringify([...dirs].map((dir) => ({ name: dir, path: path.join(root, dir) })));
+  };
+}
+const EXTRA = [{ name: '@t/extra', dir: 'packages/sdks/extra', closure: ['packages/sdks/extra', 'packages/sdks/extra-dep'] },
+  { name: '@t/lib-a', dir: 'packages/sdks/lib-a', closure: ['packages/sdks/lib-a'] }];
+
+function withExtra() {
+  const root = ready();
+  write(root, 'packages/sdks/extra/package.json', { name: '@t/extra' });
+  write(root, 'packages/sdks/extra/dist/index.js', '// extra\n');
+  write(root, 'packages/sdks/extra-dep/dist/index.js', '// dep\n');
+  return root;
+}
+
+test('--also stages the named package closure without member checks, and a member named again is idempotent', async () => {
+  const root = withExtra();
+  const result = await stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra', '@t/lib-a'] });
+  assert.equal(result.packages, 5);
+  const staged = files(path.join(root, '.xema-stage/out'));
+  for (const expected of ['packages/sdks/extra/dist/index.js', 'packages/sdks/extra-dep/dist/index.js', 'packages/sdks/lib-a/dist/index.js']) {
+    assert.ok(staged.includes(expected), expected);
+  }
+  assert.ok(!staged.some((f) => f.startsWith('packages/sdks/extra/node_modules')));
+});
+
+test('--also refuses an unknown package and a native addon in the extra closure', async () => {
+  const root = withExtra();
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/nope'] }), /--also @t\/nope: no workspace package/);
+  assert.equal(fs.existsSync(path.join(root, '.xema-stage')), false);
+  write(root, 'packages/sdks/extra-dep/dist/a.node', 'x');
+  await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /extra-dep\/dist\/a\.node/);
+});
+
+test('filters and the argument parser carry --also', async () => {
+  const root = ready();
+  const { memberFilters } = await import('./composed-image-members.mjs');
+  const { parseArguments } = await import('./composed-image.mjs');
+  assert.deepEqual(memberFilters({ root, also: ['@t/extra', '@t/lib-a', '@t/extra'] }).slice(-2), ['--filter @t/extra...', '--filter @t/lib-a...']);
+  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']);
+});

package/src/composed-image-sync-injected.mjs

@@ -0,0 +1,91 @@
+// `xema-composed-image sync-injected`, INSIDE the image build, after the source and the
+// staged outputs are copied. The production install ran from manifests only, so each
+// injected workspace copy (`node_modules/.pnpm/<name>@file+…/node_modules/<name>`) holds
+// just what existed then (its package.json). This copies every `files` entry of the
+// workspace package into its injected copy, which is exactly what `pnpm deploy` injects.
+import { cpSync, existsSync, lstatSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { readMembers } from './composed-image-members.mjs';
+
+const GLOB = /[*?[\]{}!]/;
+const SKIPPED = new Set(['node_modules', '.git']);
+
+/** `name -> repository-relative directory` for every workspace package under `root`. */
+export function workspacePackages(root, prefix = '', found = new Map()) {
+  const dir = join(root, prefix);
+  const manifestPath = join(dir, 'package.json');
+  if (prefix !== '' && existsSync(manifestPath)) {
+    const name = JSON.parse(readFileSync(manifestPath, 'utf8')).name;
+    if (typeof name === 'string') found.set(name, prefix);
+  }
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && !SKIPPED.has(entry.name)) workspacePackages(root, prefix === '' ? entry.name : `${prefix}/${entry.name}`, found);
+  }
+  return found;
+}
+
+/** Injected package directories: real directories in a `.pnpm/*@file+*` entry's node_modules. */
+function injectedCopies(root) {
+  const store = join(root, 'node_modules', '.pnpm');
+  if (!existsSync(store)) return [];
+  const copies = [];
+  for (const entry of readdirSync(store).sort()) {
+    if (!entry.includes('@file+')) continue;
+    const modules = join(store, entry, 'node_modules');
+    if (!existsSync(modules)) continue;
+    for (const name of readdirSync(modules).sort()) {
+      const candidates = name.startsWith('@') ? readdirSync(join(modules, name)).sort().map((n) => join(modules, name, n)) : [join(modules, name)];
+      for (const candidate of candidates) {
+        const stat = lstatSync(candidate);
+        if (stat.isDirectory() && existsSync(join(candidate, 'package.json'))) copies.push(candidate);
+      }
+    }
+  }
+  return copies;
+}
+
+export function syncInjected({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, log = console.log } = {}) {
+  const workspace = workspacePackages(root);
+  const memberDirectories = new Set(readMembers({ root, imageDir }).map(([, directory]) => directory));
+  const nonMembers = [...workspace.values()].filter((directory) => !memberDirectories.has(directory));
+  const copies = injectedCopies(root);
+  const problems = [];
+  if (copies.length === 0 && nonMembers.length > 0) {
+    problems.push(`no injected workspace copy found under node_modules/.pnpm, but the closure has ${nonMembers.length} non-member package(s)`);
+  }
+  let synced = 0;
+  for (const copy of copies) {
+    const name = JSON.parse(readFileSync(join(copy, 'package.json'), 'utf8')).name;
+    const directory = workspace.get(name);
+    if (directory === undefined) {
+      problems.push(`${copy}: injected package "${name}" maps to no workspace package`);
+      continue;
+    }
+    const files = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8')).files;
+    if (!Array.isArray(files)) {
+      problems.push(`${name} (${directory}): no "files" field — nothing says what to inject`);
+      continue;
+    }
+    const globs = files.filter((entry) => typeof entry !== 'string' || GLOB.test(entry));
+    if (globs.length > 0) {
+      problems.push(`${name} (${directory}): "files" has glob or non-string entries (${globs.join(', ')}); list plain paths`);
+      continue;
+    }
+    for (const entry of files) {
+      const source = join(root, directory, entry);
+      if (!existsSync(source)) {
+        problems.push(`${name} (${directory}): files entry "${entry}" does not exist`);
+        continue;
+      }
+      const target = join(copy, entry);
+      rmSync(target, { recursive: true, force: true }); // never write through a hardlink into the store
+      cpSync(source, target, { recursive: true, verbatimSymlinks: true });
+    }
+    synced += 1;
+  }
+  if (problems.length > 0) throw new Error(`injected workspace copies cannot be synced:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  log(`composed sync-injected: ${synced} injected workspace cop${synced === 1 ? 'y' : 'ies'} synced`);
+  return synced;
+}

package/src/composed-image-sync-injected.test.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+
+import { syncInjected } from './composed-image-sync-injected.mjs';
+import { workspace, write } from './composed-image-fixture.test.mjs';
+
+function injected(root, entry, name, extra = {}) {
+  write(root, `node_modules/.pnpm/${entry}/node_modules/${name}/package.json`, { name, ...extra });
+}
+
+test('copies every files entry into the injected copy, and nothing else', () => {
+  const root = workspace();
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist', 'README.md'] });
+  write(root, 'packages/sdks/lib-a/README.md', '# a\n');
+  write(root, 'packages/sdks/lib-a/src/secret.ts', '//\n');
+  injected(root, '@t+lib-a@file+packages+sdks+lib-a_peer', '@t/lib-a');
+  fs.symlinkSync(path.join(root, 'packages'), path.join(root, 'node_modules/.pnpm/@t+lib-a@file+packages+sdks+lib-a_peer/node_modules/dep-link'));
+  const messages = [];
+  assert.equal(syncInjected({ root, log: (m) => messages.push(m) }), 1);
+  const target = path.join(root, 'node_modules/.pnpm/@t+lib-a@file+packages+sdks+lib-a_peer/node_modules/@t/lib-a');
+  assert.ok(fs.existsSync(path.join(target, 'dist/index.js')));
+  assert.ok(fs.existsSync(path.join(target, 'README.md')));
+  assert.ok(!fs.existsSync(path.join(target, 'src')));
+  assert.match(messages[0], /1 injected workspace copy synced/);
+});
+
+test('refuses a name with no workspace package, no files, a glob, a missing entry, and zero copies', () => {
+  const root = workspace();
+  assert.throws(() => syncInjected({ root, log() {} }), /no injected workspace copy found/);
+  injected(root, 'ghost@file+x', 'ghost');
+  assert.throws(() => syncInjected({ root, log() {} }), /"ghost" maps to no workspace package/);
+  fs.rmSync(path.join(root, 'node_modules'), { recursive: true });
+
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a' });
+  injected(root, '@t+lib-a@file+a', '@t/lib-a');
+  assert.throws(() => syncInjected({ root, log() {} }), /no "files" field/);
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist/**'] });
+  assert.throws(() => syncInjected({ root, log() {} }), /glob/);
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist', 'missing.txt'] });
+  assert.throws(() => syncInjected({ root, log() {} }), /"missing\.txt" does not exist/);
+});