@xemahq/biome-bundle-pack 0.0.0-stage → 0.2.0

package/src/pack-directory.mjs

@@ -0,0 +1,148 @@
+// `packBiomeDirectory`: a BUILT biome directory packed as one content-addressed bundle, the same bundle format the
+// repository pipeline writes (`seal-bundle.mjs`), so a host loads either alike. The user builds; this stages and packs.
+//
+// The directory is one standalone project: its `xema-biome.json` (the biome manifest), `package.json` and `pnpm-lock.yaml`
+// at its root, its build outputs where its components' entrypoints name them. Staging copies it (minus `node_modules` and
+// `.git`) outside the directory, installs its production closure for the target platform from the frozen lockfile and cuts
+// the host-provided packages out (`stage.mjs`). What is recorded:
+//   - members: every service and worker component, `entry` the module its entrypoint names (`node-module`) or `dist/main.js`;
+//     a member that owns a database key and a `prisma/migrations` directory carries those migrations;
+//   - hostAbi: the versions of the host-provided packages the biome's own install resolved. A biome whose install resolves
+//     no host-provided SDK or no kernel contracts declares no host ABI and is refused; there is no override;
+//   - build: `deriveBiomeBuildFacts` over the biome's own manifest;
+//   - buildSource: the git checkout's origin and HEAD (a dirty tree is fine: the content digest names the actual bytes),
+//     or `buildSource` when given; a directory that is no git checkout is refused unless it is given.
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, posix, relative, resolve } from 'node:path';
+
+import { parseBiomeManifest, isServerBiomeManifest, BiomeComponentEntrypointKind, BiomeComponentKind, BiomeComponentProtocolKind } from '@xemahq/contracts/biome';
+import { KERNEL_CONTRACTS_PACKAGE, deriveBiomeBuildFacts } from '@xemahq/contracts/biome-bundle';
+import { NODE_COMPOSED_HOST_ABI_ID, hostProvidedPackages } from '@xemahq/host-abi-node';
+
+import { copyBiomeContent } from './biome-content.mjs';
+import { resolveBuildSource } from './bundle-build-source.mjs';
+import { memberEntryFacts } from './member-required-env.mjs';
+import { sealBundle } from './seal-bundle.mjs';
+import { stageBundle, standaloneInstall } from './stage.mjs';
+import { currentPlatform, platformArch } from './target-platform.mjs';
+
+export const BIOME_MANIFEST_FILE = 'xema-biome.json';
+const LOCKFILE = 'pnpm-lock.yaml';
+const DEFAULT_ENTRY = 'dist/main.js';
+const MIGRATIONS_DIRECTORY = 'prisma/migrations';
+const PRISMA_MIGRATIONS_ENGINE = 'prisma';
+const NOT_COPIED = new Set(['node_modules', '.git']);
+const WORK_PREFIX = 'xema-pack-dir-';
+
+/** `exec` for the build source's git calls: spawnSync-shaped `{ status, stdout }`; a command that cannot start is an error. */
+function gitExec(file, args, { cwd }) {
+  const result = spawnSync(file, args, { cwd, encoding: 'utf8' });
+  if (result.error) {throw new Error(`cannot run ${file}: ${result.error.message}`, { cause: result.error });}
+  return { status: result.status ?? 1, stdout: result.stdout };
+}
+
+/** The module a component's entrypoint names, relative to the directory: `node-module` names it (a missing extension is `.js`); everything else runs `dist/main.js`. */
+export function memberEntry(component) {
+  const { entrypoint } = component;
+  if (entrypoint.kind !== BiomeComponentEntrypointKind.NodeModule) {return DEFAULT_ENTRY;}
+  return posix.extname(entrypoint.module) === '' ? `${entrypoint.module}.js` : entrypoint.module;
+}
+
+function memberComponents(manifest) {
+  return manifest.xema.components.filter((component) => component.kind === BiomeComponentKind.Service || component.kind === BiomeComponentKind.Worker);
+}
+
+/** The migrations a member ships: only a service that owns a database key and a `prisma/migrations` directory with SQL in every migration. */
+function memberMigrations({ stage, component }) {
+  const owns = component.protocol.kind === BiomeComponentProtocolKind.Http && component.protocol.databaseKey !== undefined;
+  const directory = join(stage, MIGRATIONS_DIRECTORY);
+  if (!owns || !existsSync(directory)) {return undefined;}
+  const names = readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  for (const name of names) {
+    if (!existsSync(join(directory, name, 'migration.sql'))) {throw new Error(`${MIGRATIONS_DIRECTORY}/${name} has no migration.sql`);}
+  }
+  return names.length === 0 ? undefined : { engine: PRISMA_MIGRATIONS_ENGINE, path: MIGRATIONS_DIRECTORY };
+}
+
+function readManifest(dir) {
+  const file = join(dir, BIOME_MANIFEST_FILE);
+  if (!existsSync(file)) {throw new Error(`${dir} has no ${BIOME_MANIFEST_FILE}: it is not a biome directory`);}
+  const manifest = parseBiomeManifest(JSON.parse(readFileSync(file, 'utf8')));
+  if (!isServerBiomeManifest(manifest)) {throw new Error(`${file} is a ${manifest.xema.target} biome: only a server biome is packed as a bundle`);}
+  return manifest;
+}
+
+/** `{ id, kernelContracts, identityPackages }` from the versions the biome's own install resolved; refuses a biome that resolves no host ABI. */
+function hostAbiOf({ hostVersions, hostAbiId }) {
+  const kernelContracts = hostVersions[KERNEL_CONTRACTS_PACKAGE];
+  const identityPackages = Object.fromEntries(Object.entries(hostVersions).filter(([name]) => name !== KERNEL_CONTRACTS_PACKAGE));
+  if (kernelContracts === undefined || Object.keys(identityPackages).length === 0) {
+    throw new Error(`the biome declares no host ABI: its install resolves ${Object.keys(hostVersions).join(', ') || 'none of the host-provided packages'}, but a bundle for the ${hostAbiId} host needs ${KERNEL_CONTRACTS_PACKAGE} and the host SDK among its dependencies`);
+  }
+  return { id: hostAbiId, kernelContracts, identityPackages };
+}
+
+function copyDirectory({ dir, stage, out }) {
+  const skipped = resolve(out);
+  cpSync(dir, stage, {
+    recursive: true,
+    verbatimSymlinks: true,
+    filter: (source) => !NOT_COPIED.has(relative(dir, source).split('/')[0]) && resolve(source) !== skipped,
+  });
+}
+
+/**
+ * Pack the built biome directory `dir` as one bundle under `out`. `platform` is `linux/amd64` or `linux/arm64` (default: this
+ * machine's arch). Returns `{ biome, members, archiveDigest, contentDigest, directory, archive }`.
+ * TEST SEAMS: `install` replaces the production install, `exec` the git calls of the build source, `captureMember` the capture of each
+ * member's entry (`({ packageRoot, entryPath }) => { requiredEnvVars: string[], kind: 'http'|'worker' }`, read from the user's own installed build in `dir`).
+ */
+export async function packBiomeDirectory({ dir, out, platform = currentPlatform(), buildSource, hostAbiId = NODE_COMPOSED_HOST_ABI_ID, install, exec = gitExec, captureMember = memberEntryFacts, log = () => undefined }) {
+  const manifest = readManifest(dir);
+  const arch = platformArch(platform);
+  const components = memberComponents(manifest);
+  if (components.length === 0) {throw new Error(`${join(dir, BIOME_MANIFEST_FILE)} declares no service or worker component: there is nothing to pack`);}
+  if (!existsSync(join(dir, LOCKFILE))) {
+    throw new Error(`${dir} has no ${LOCKFILE}: a biome directory is packed from its frozen lockfile (run pnpm install in it, and commit the lockfile)`);
+  }
+  const source = resolveBuildSource({ root: dir, explicit: buildSource, exec, allowDirty: true });
+  const work = mkdtempSync(join(tmpdir(), WORK_PREFIX));
+  try {
+    const stage = join(work, 'bundle');
+    mkdirSync(stage);
+    copyDirectory({ dir, stage, out });
+    const entries = components.map((component) => ({ component, entry: memberEntry(component) }));
+    const missing = entries.filter(({ entry }) => !existsSync(join(stage, entry)));
+    if (missing.length > 0) {
+      throw new Error(`build the biome first: ${missing.map(({ component, entry }) => `${component.key} runs ${entry}, which does not exist`).join('; ')}`);
+    }
+    const { hostVersions } = await stageBundle({
+      stage,
+      memberDirectories: ['.'],
+      hostProvided: hostProvidedPackages(hostAbiId),
+      install: install ?? standaloneInstall({ arch }),
+    });
+    const contributionKinds = copyBiomeContent({ root: dir, stage, manifests: [BIOME_MANIFEST_FILE] });
+    const members = entries
+      .map(({ component, entry }) => ({ member: component.key, entry, migrations: memberMigrations({ stage, component }), ...captureMember({ packageRoot: dir, entryPath: join(dir, entry) }) }))
+      .sort((a, b) => (a.member < b.member ? -1 : 1));
+    const sealed = sealBundle({
+      stage,
+      out,
+      manifest: {
+        biome: manifest.xema.id,
+        members,
+        buildSource: source,
+        hostAbi: hostAbiOf({ hostVersions, hostAbiId }),
+        contributionKinds,
+        build: deriveBiomeBuildFacts(manifest),
+      },
+    });
+    log(`packed ${manifest.xema.id} (${members.length} member(s)): ${sealed.archiveDigest}`);
+    return { biome: manifest.xema.id, members: members.map(({ member }) => member), ...sealed };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}

package/src/pack-directory.test.mjs

@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test, { after } from 'node:test';
+
+import { BiomeBundleManifestSchema } from '@xemahq/contracts/biome-bundle';
+
+import { memberEntryFacts } from './member-required-env.mjs';
+import { memberEntry, packBiomeDirectory } from './pack-directory.mjs';
+
+const AUDIT = path.join(import.meta.dirname, '..', '..', '..', '..', 'biomes', 'audit', 'xema-biome.json');
+const SOURCE = `acme/biome@${'a'.repeat(40)}`;
+const temps = [];
+after(() => {
+  for (const dir of temps) {fs.rmSync(dir, { recursive: true, force: true });}
+});
+
+function temp(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  temps.push(dir);
+  return dir;
+}
+
+/** A built biome directory: the audit biome's manifest, `dist/main.js`, a package.json and a lockfile. */
+function biomeDirectory({ lockfile = true, built = true } = {}) {
+  const dir = temp('xema-biome-dir-');
+  fs.copyFileSync(AUDIT, path.join(dir, 'xema-biome.json'));
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'acme-biome', version: '1.0.0' }));
+  if (lockfile) {fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), "lockfileVersion: '9.0'\n");}
+  if (built) {
+    fs.mkdirSync(path.join(dir, 'dist'));
+    fs.writeFileSync(path.join(dir, 'dist', 'main.js'), 'module.exports = {};\n');
+  }
+  return dir;
+}
+
+/** The install seam: a pnpm tree holding the host-provided packages and one ordinary dependency. */
+function fakeInstall({ withHost = true } = {}) {
+  return ({ treeRoot }) => {
+    const entries = [['left-pad', '1.3.0'], ...(withHost ? [['@xemahq/contracts', '3.2.1'], ['@xemahq/xema-service-nest', '0.9.0'], ['@nestjs/common', '11.0.0']] : [])];
+    for (const [name, version] of entries) {
+      const pkg = path.join(treeRoot, 'node_modules', '.pnpm', `${name.replace('/', '+')}@${version}`, 'node_modules', name);
+      fs.mkdirSync(pkg, { recursive: true });
+      fs.writeFileSync(path.join(pkg, 'package.json'), JSON.stringify({ name, version }));
+      fs.mkdirSync(path.join(treeRoot, 'node_modules', path.dirname(name)), { recursive: true });
+      const link = path.join(treeRoot, 'node_modules', name);
+      fs.symlinkSync(path.relative(path.dirname(link), pkg), link, 'dir');
+    }
+  };
+}
+
+const pack = (dir, options = {}) => packBiomeDirectory({ dir, out: temp('xema-out-'), platform: 'linux/amd64', buildSource: SOURCE, install: fakeInstall(), captureMember: () => ({ requiredEnvVars: ['JWT_ISSUER', 'DATABASE_URL'], kind: 'http' }), ...options });
+
+test('a built biome directory packs to a bundle the contracts accept, carrying its build facts and host ABI', async () => {
+  const packed = await pack(biomeDirectory());
+  assert.equal(packed.biome, 'audit');
+  assert.deepEqual(packed.members, ['audit-log-api']);
+  assert.match(packed.archiveDigest, /^sha256:[0-9a-f]{64}$/);
+});
+
+test('the manifest names the members, the host ABI the install resolved and the build facts', async () => {
+  const out = temp('xema-out-');
+  const packed = await pack(biomeDirectory(), { out });
+  const manifest = BiomeBundleManifestSchema.parse(JSON.parse(fs.readFileSync(path.join(out, packed.directory, 'xema-bundle.json'), 'utf8')));
+  assert.deepEqual(manifest.members, [{ member: 'audit-log-api', entry: 'dist/main.js', requiredEnvVars: ['JWT_ISSUER', 'DATABASE_URL'], kind: 'http' }]);
+  assert.deepEqual(manifest.hostAbi, { id: 'node-composed', kernelContracts: '3.2.1', identityPackages: { '@nestjs/common': '11.0.0', '@xemahq/xema-service-nest': '0.9.0' } });
+  assert.deepEqual(manifest.build.services, ['audit-log-api']);
+  assert.equal(manifest.buildSource.repository, 'acme/biome');
+});
+
+test('host-provided packages are cut out of the bundle and ordinary ones stay', async () => {
+  const out = temp('xema-out-');
+  const packed = await pack(biomeDirectory(), { out });
+  const modules = path.join(out, packed.directory, 'node_modules');
+  assert.ok(fs.existsSync(path.join(modules, 'left-pad')));
+  assert.ok(!fs.existsSync(path.join(modules, '@xemahq/contracts')));
+  assert.ok(!fs.existsSync(path.join(modules, '@nestjs/common')));
+});
+
+test('the same directory packs to the same digest', async () => {
+  const dir = biomeDirectory();
+  assert.equal((await pack(dir)).archiveDigest, (await pack(dir)).archiveDigest);
+});
+
+test('a directory without a lockfile is refused', async () => {
+  await assert.rejects(pack(biomeDirectory({ lockfile: false })), /has no pnpm-lock\.yaml/);
+});
+
+test('an unbuilt directory is refused, naming the missing entry', async () => {
+  await assert.rejects(pack(biomeDirectory({ built: false })), /build the biome first: audit-log-api runs dist\/main\.js/);
+});
+
+test('a biome whose install resolves no host ABI is refused', async () => {
+  await assert.rejects(pack(biomeDirectory(), { install: fakeInstall({ withHost: false }) }), /declares no host ABI/);
+});
+
+test('a directory that is no git checkout is refused unless a build source is given', async () => {
+  await assert.rejects(pack(biomeDirectory(), { buildSource: undefined, exec: () => ({ status: 128, stdout: '' }) }), /not a git checkout/);
+});
+
+test('a dirty checkout is packed: the content digest names the bytes', async () => {
+  const exec = (file, args) => ({ status: 0, stdout: args[0] === 'rev-parse' ? 'b'.repeat(40) : args[0] === 'remote' ? 'git@github.com:acme/biome.git' : ' M dist/main.js\n' });
+  const out = temp('xema-out-');
+  const packed = await pack(biomeDirectory(), { buildSource: undefined, exec, out });
+  const manifest = JSON.parse(fs.readFileSync(path.join(out, packed.directory, 'xema-bundle.json'), 'utf8'));
+  assert.deepEqual(manifest.buildSource, { repository: 'acme/biome', commit: 'b'.repeat(40) });
+});
+
+test('memberEntry reads a node-module entrypoint and defaults to dist/main.js', () => {
+  assert.equal(memberEntry({ entrypoint: { kind: 'node-module', module: 'dist/worker' } }), 'dist/worker.js');
+  assert.equal(memberEntry({ entrypoint: { kind: 'node-module', module: 'dist/worker.js' } }), 'dist/worker.js');
+  assert.equal(memberEntry({ entrypoint: { kind: 'oci-default' } }), 'dist/main.js');
+});
+
+test('a worker entry is packed with kind "worker", and the manifest the contracts accept carries it', async () => {
+  const out = temp('xema-out-');
+  const packed = await pack(biomeDirectory(), { out, captureMember: () => ({ requiredEnvVars: ['TEMPORAL_ADDRESS'], kind: 'worker' }) });
+  const manifest = BiomeBundleManifestSchema.parse(JSON.parse(fs.readFileSync(path.join(out, packed.directory, 'xema-bundle.json'), 'utf8')));
+  assert.deepEqual(manifest.members, [{ member: 'audit-log-api', entry: 'dist/main.js', requiredEnvVars: ['TEMPORAL_ADDRESS'], kind: 'worker' }]);
+});
+
+/** A package whose installed `@xemahq/xema-service-nest` captures `captured` for any entry. */
+function memberWithSdk(captured) {
+  const root = temp('xema-member-');
+  const sdk = path.join(root, 'node_modules', '@xemahq', 'xema-service-nest');
+  fs.mkdirSync(sdk, { recursive: true });
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'member' }));
+  fs.writeFileSync(path.join(sdk, 'package.json'), JSON.stringify({ name: '@xemahq/xema-service-nest', main: 'index.js' }));
+  fs.writeFileSync(path.join(sdk, 'index.js'), `exports.readServiceEntry = () => (${JSON.stringify(captured)});\n`);
+  return root;
+}
+
+test('one capture yields the required names and the kind of the entry', () => {
+  const worker = memberWithSdk({ entry: { kind: 'worker', options: { requiredEnvVars: ['B_NAME', 'A_NAME', 'A_NAME'] } }, envWrites: {} });
+  assert.deepEqual(memberEntryFacts({ packageRoot: worker, entryPath: 'main.js' }), { requiredEnvVars: ['A_NAME', 'B_NAME'], kind: 'worker' });
+  const http = memberWithSdk({ entry: { kind: 'service', options: {} }, envWrites: {} });
+  assert.deepEqual(memberEntryFacts({ packageRoot: http, entryPath: 'main.js' }), { requiredEnvVars: [], kind: 'http' });
+});
+
+test('an entry whose captured kind is unknown is refused, never read as http', () => {
+  const unknown = memberWithSdk({ entry: { kind: 'cron', options: {} }, envWrites: {} });
+  assert.throws(() => memberEntryFacts({ packageRoot: unknown, entryPath: 'main.js' }), /unknown captured entry kind "cron"/);
+});

package/src/seal-bundle.mjs

@@ -0,0 +1,38 @@
+// Seal a staged bundle tree: write its manifest (the content digest covers every file but the manifest), archive it
+// canonically and write `<out>/<hex>/` and `<out>/<hex>.tgz`, `<hex>` being the sha256 of the archive bytes.
+import { cpSync, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { BIOME_BUNDLE_MANIFEST_FILE } from '@xemahq/contracts/biome-bundle';
+
+import { archiveDigest, canonicalTar, gzipCanonical } from './bundle-archive.mjs';
+import { bundleContentDigest } from './bundle-content.mjs';
+import { bundleManifest } from './bundle-manifest.mjs';
+
+/** Write `bytes` to `path` through a sibling file and a rename, so a concurrent reader never sees half of it. */
+function writeAtomic(path, bytes) {
+  const partial = `${path}.partial-${process.pid}`;
+  writeFileSync(partial, bytes);
+  renameSync(partial, path);
+}
+
+/**
+ * `manifest` is `bundleManifest`'s input without `contentDigest`. Returns `{ archiveDigest, contentDigest, directory, archive }`
+ * (`directory` and `archive` are names under `out`).
+ */
+export function sealBundle({ stage, out, manifest }) {
+  const contentDigest = bundleContentDigest(stage);
+  writeFileSync(join(stage, BIOME_BUNDLE_MANIFEST_FILE), bundleManifest({ ...manifest, contentDigest }));
+  const archiveBytes = gzipCanonical(canonicalTar(stage));
+  const digest = archiveDigest(archiveBytes);
+  const directory = digest.slice('sha256:'.length);
+  const archive = `${directory}.tgz`;
+  mkdirSync(out, { recursive: true });
+  if (!existsSync(join(out, directory))) {
+    const partial = join(out, `${directory}.partial-${process.pid}`);
+    cpSync(stage, partial, { recursive: true, verbatimSymlinks: true });
+    renameSync(partial, join(out, directory));
+  }
+  writeAtomic(join(out, archive), archiveBytes);
+  return { archiveDigest: digest, contentDigest, directory, archive };
+}

package/src/stage.mjs

@@ -0,0 +1,60 @@
+// `stageBundle`: the ONE staging of a bundle's tree, used by the repository pipeline and by the `xema` CLI. The tree
+// already holds the biome's build outputs; staging installs its production closure, drops what a host must not receive
+// twice and returns the versions of the host-provided packages it resolved.
+//   1. `install({ treeRoot })`: the caller's production install (the repository pipeline runs its workspace re-resolve,
+//      `installProduction` below installs a standalone project);
+//   2. pnpm's own bookkeeping goes (it records the runner's store path and timestamps, which differ per host);
+//   3. the host-provided versions are read from the install, then the host-provided packages are cut out
+//      (`host-provided.mjs`).
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { excludeHostProvided, pnpmEntryName } from './host-provided.mjs';
+import { platformInstallFlags } from './target-platform.mjs';
+
+const PNPM_STATE_FILES = Object.freeze(['.modules.yaml', '.pnpm-workspace-state-v1.json']);
+
+/** The version of each `hostProvided` package the install put in `<treeRoot>/node_modules/.pnpm`: `{ <name>: <version> }`, sorted by name. */
+export function installedHostVersions({ treeRoot, hostProvided }) {
+  const pnpmDir = join(treeRoot, 'node_modules', '.pnpm');
+  const versions = {};
+  if (!existsSync(pnpmDir)) {return versions;}
+  for (const entry of readdirSync(pnpmDir).sort()) {
+    const name = pnpmEntryName(entry);
+    if (name === undefined || !hostProvided.includes(name)) {continue;}
+    const manifest = join(pnpmDir, entry, 'node_modules', name, 'package.json');
+    if (existsSync(manifest)) {versions[name] ??= JSON.parse(readFileSync(manifest, 'utf8')).version;}
+  }
+  return Object.fromEntries(Object.entries(versions).sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
+/**
+ * Stage the tree at `stage` for a bundle whose members live in `memberDirectories` (paths relative to `stage`).
+ * Returns `{ hostVersions, exclusion }`.
+ */
+export async function stageBundle({ stage, memberDirectories, hostProvided, install }) {
+  await install({ treeRoot: stage });
+  for (const state of PNPM_STATE_FILES) {rmSync(join(stage, 'node_modules', state), { force: true });}
+  const hostVersions = installedHostVersions({ treeRoot: stage, hostProvided });
+  const exclusion = excludeHostProvided({ treeRoot: stage, memberDirectories, hostProvided });
+  return { hostVersions, exclusion };
+}
+
+const defaultExec = (file, args, { cwd }) => execFileSync(file, args, { cwd, stdio: 'inherit' });
+
+/** The production install of a standalone project for `linux/<arch>` as `[file, ...args]`: frozen lockfile, no scripts. */
+export const productionInstallCommand = (arch) => [
+  'pnpm', 'install', '--prod', '--prefer-offline', '--ignore-scripts', '--frozen-lockfile', ...platformInstallFlags(arch),
+];
+
+/**
+ * The install of a standalone biome project (its own `package.json` and `pnpm-lock.yaml` at `treeRoot`). `--prefer-offline`,
+ * not `--offline`: a developer's store may be cold. The lockfile is frozen, so what is installed is what it pins.
+ */
+export function standaloneInstall({ arch, exec = defaultExec }) {
+  return ({ treeRoot }) => {
+    const [file, ...args] = productionInstallCommand(arch);
+    exec(file, args, { cwd: treeRoot });
+  };
+}

package/src/stage.test.mjs

@@ -0,0 +1,36 @@
+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 { productionInstallCommand, stageBundle } from './stage.mjs';
+import { platformInstallFlags } from './target-platform.mjs';
+
+test('the standalone install is frozen, scriptless and selected for the target platform', () => {
+  const command = productionInstallCommand('arm64');
+  for (const word of ['--prod', '--frozen-lockfile', '--ignore-scripts', '--prefer-offline', '--os=linux', '--cpu=arm64', '--libc=glibc']) {assert.ok(command.includes(word), word);}
+  assert.ok(!command.includes('--offline'));
+  assert.deepEqual(platformInstallFlags('amd64'), ['--os=linux', '--cpu=x64', '--libc=glibc']);
+  assert.throws(() => platformInstallFlags('riscv'), /no target platform/);
+});
+
+test('stageBundle drops pnpm state and reports the host versions it cut out', async () => {
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-stage-'));
+  try {
+    const pkg = path.join(stage, 'node_modules', '.pnpm', '@nestjs+common@11.0.0', 'node_modules', '@nestjs', 'common');
+    fs.mkdirSync(pkg, { recursive: true });
+    fs.writeFileSync(path.join(pkg, 'package.json'), JSON.stringify({ version: '11.0.0' }));
+    const result = await stageBundle({
+      stage,
+      memberDirectories: ['.'],
+      hostProvided: ['@nestjs/common'],
+      install: ({ treeRoot }) => fs.writeFileSync(path.join(treeRoot, 'node_modules', '.modules.yaml'), 'x'),
+    });
+    assert.deepEqual(result.hostVersions, { '@nestjs/common': '11.0.0' });
+    assert.ok(!fs.existsSync(path.join(stage, 'node_modules', '.modules.yaml')));
+    assert.ok(!fs.existsSync(path.join(stage, 'node_modules', '.pnpm', '@nestjs+common@11.0.0')));
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+});

package/src/target-platform.mjs

@@ -0,0 +1,35 @@
+// The target platforms a bundle's install is selected for, keyed by Docker's `TARGETARCH`. Loads only `node:` builtins.
+// A TWIN of the arch rows in repo-build-tooling's `service-image-platform.mjs` (`IMAGE_PLATFORMS`): that file is mounted
+// into the build image beside the in-image entries, which may import only relative modules, so it cannot import this
+// package. `service-image-platform-twin.test.mjs` in repo-build-tooling runs the same vectors through both copies; change
+// both together.
+
+/** `node` is Node's `process.arch`, what pnpm's `--cpu` takes; `libc` is the runtime base image's. */
+export const TARGET_PLATFORMS = Object.freeze({
+  amd64: Object.freeze({ node: 'x64', libc: 'glibc' }),
+  arm64: Object.freeze({ node: 'arm64', libc: 'glibc' }),
+});
+
+/** `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(TARGET_PLATFORMS, match[1])) {
+    throw new Error(`--platform must be one of ${Object.keys(TARGET_PLATFORMS).map((a) => `linux/${a}`).join(', ')}, got '${platform}'`);
+  }
+  return match[1];
+}
+
+/** The `linux/<arch>` of this Node process; refuses an arch with no row. */
+export function currentPlatform(nodeArch = process.arch) {
+  const arch = Object.keys(TARGET_PLATFORMS).find((key) => TARGET_PLATFORMS[key].node === nodeArch);
+  if (arch === undefined) {throw new Error(`Node arch '${nodeArch}' is not a platform bundles are built for`);}
+  return `linux/${arch}`;
+}
+
+/** The pnpm `--os/--cpu/--libc` words that select the packages for `linux/<arch>`. */
+export function platformInstallFlags(arch) {
+  if (!Object.hasOwn(TARGET_PLATFORMS, arch)) {
+    throw new Error(`no target platform for arch '${arch}'; known: ${Object.keys(TARGET_PLATFORMS).join(', ')}`);
+  }
+  return ['--os=linux', `--cpu=${TARGET_PLATFORMS[arch].node}`, `--libc=${TARGET_PLATFORMS[arch].libc}`];
+}