@xemahq/repo-build-tooling 0.27.3 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.27.3",
+  "version": "0.29.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)",
@@ -25,6 +25,7 @@
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
+    "xema-effective-input": "src/effective-input.mjs",
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
@@ -36,6 +37,7 @@
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
+    "./effective-input": "./src/effective-input.mjs",
     "./package.json": "./package.json",
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
@@ -47,9 +49,9 @@
     "@xemahq/release-policy": "^16.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-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.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-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs && node --test src/staged-image-proof.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-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.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-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs && node --test src/staged-image-proof.test.mjs && node --test src/effective-input.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:d6ac6c711e4edb7ef2d2fa6531089a4f443381fd1e622ee2a060eb36a229ee6c"
+    "sourceDigest": "sha256:a5327bf366fb31aeef8adb584888e52a5ae4da7aa5602eb672eb2876ed912a8b"
   }
 }

package/src/effective-input.mjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+// The EFFECTIVE-INPUT key of one image: a content hash of every input that decides its bytes, computed from
+// SOURCES, before any build, so a lane can skip build, stage and push when the key is already in the registry.
+//
+//   xema-effective-input --service <pkg> [--service <pkg>]… --platform linux/<amd64|arm64> --base-image <name@sha256:digest>
+//        --dockerfile <file> [--script <file>]… [--build-arg NAME=VALUE]… [--out <file>]
+//
+// Run from the workspace root (the repository, or an aggregator workspace root: the staging actions' `context-root`).
+// It prints the key. The key is the same from either root for the same inputs, because nothing in it is a root-relative
+// path: workspace packages are keyed by NAME and hashed over their package-relative tracked files, the lockfile is
+// reduced to a slice (the closure's importers, rewritten to package names, and the entries reachable from them), and of
+// the root files only the compile-steering ones (`.npmrc`, `tsconfig*.json`) enter, by name. The whole root
+// `package.json`, lockfile and workspace file differ by root and are the PROVE step's business (xema-service-image).
+//
+// Build args the Dockerfile receives from CI are part of `tooling.buildArgs` (name -> value, sorted), except
+// the ones that are only a per-root or per-commit fact: `REPO_DIR` and `SERVICE_PATH` are paths that differ by root
+// (the service is keyed by name and its files by package-relative path), `BUILD_SHA` is the commit (the key is a
+// CONTENT key, and a commit tag would make every commit a new image). They are refused as inputs, not hashed.
+//
+// One enumeration: the closure is the one the stage builds (`turbo run build --filter "<service>..." --dry=json`), and
+// the root files come from `rootBuildInputNames` of @xemahq/repo-build-tooling (the prove step's own list).
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, readlinkSync, writeFileSync } from 'node:fs';
+import { join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { invokedDirectly } from './invoked-directly.mjs';
+import { rootBuildInputNames } from './staged-image-proof.mjs';
+
+export const KEY_SCHEMA = 1;
+/** Build args that are a root-relative path or the commit, never part of the key. */
+export const NON_CONTENT_BUILD_ARGS = Object.freeze(['REPO_DIR', 'SERVICE_PATH', 'BUILD_SHA']);
+const DIGEST_PINNED = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
+const COMPILE_ROOT_FILE = /^(\.npmrc|tsconfig[^/]*\.json)$/;
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/** Canonical JSON: keys sorted recursively, no whitespace. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const unquote = (key) => (key.startsWith("'") && key.endsWith("'") ? key.slice(1, -1) : key);
+
+/** The top-level sections of a pnpm v9 lockfile, each as `{ entryKey: [body lines] }` (entries are the 2-space keys). */
+export function lockSections(text) {
+  const sections = {};
+  let section;
+  let entry;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    if (!line.startsWith(' ')) {
+      section = line.endsWith(':') ? line.slice(0, -1) : undefined;
+      if (section !== undefined) sections[section] = {};
+      entry = undefined;
+    } else if (section !== undefined && /^ {2}\S/.test(line)) {
+      entry = unquote(line.trim().replace(/:( \{\})?$/, ''));
+      sections[section][entry] = [];
+    } else if (entry !== undefined) {
+      sections[section][entry].push(line);
+    }
+  }
+  return sections;
+}
+
+/** `{ dependencyName: { specifier, version } }` per section of an importer body (a pnpm importer's 4/6/8-space layout). */
+function importerDependencies(lines) {
+  const sections = {};
+  let section;
+  let name;
+  for (const line of lines) {
+    const indent = line.length - line.trimStart().length;
+    const text = line.trim();
+    if (indent === 4) {
+      section = text.replace(/:$/, '');
+      sections[section] = {};
+    } else if (indent === 6 && section !== undefined) {
+      name = unquote(text.replace(/:$/, ''));
+      sections[section][name] = {};
+    } else if (indent === 8 && name !== undefined) {
+      const [field, ...rest] = text.split(': ');
+      sections[section][name][field] = unquote(rest.join(': '));
+    }
+  }
+  return sections;
+}
+
+/** `{ name: version }` of a snapshot body's dependency sections. */
+function snapshotDependencies(lines) {
+  const deps = {};
+  let inside = false;
+  for (const line of lines) {
+    const indent = line.length - line.trimStart().length;
+    const text = line.trim();
+    if (indent === 4) inside = DEPENDENCY_SECTIONS.includes(text.replace(/:$/, ''));
+    else if (indent === 6 && inside) {
+      const at = text.indexOf(': ');
+      deps[unquote(text.slice(0, at))] = unquote(text.slice(at + 2));
+    }
+  }
+  return deps;
+}
+
+/** An alias (`wrap-ansi-cjs: wrap-ansi@7.0.0`) names its target's snapshot; a plain version belongs to the dependency's own name. */
+const ALIAS_TARGET = /^(?:npm:)?(@?[^@(]+@.*)$/;
+const snapshotKey = (name, version) => ALIAS_TARGET.exec(version)?.[1] ?? `${name}@${version}`;
+const packageKey = (key) => key.replace(/\(.*$/, '');
+
+export const LOCKFILE_VERSION = '9.0';
+
+/** The lockfile's declared version, refused unless it is the one this parser reads. */
+export function assertLockfileVersion(lockText) {
+  const declared = /^lockfileVersion:\s*'?([^'\s]+)'?\s*$/m.exec(lockText)?.[1];
+  if (declared !== LOCKFILE_VERSION) {
+    throw new Error(`lockfileVersion '${declared}' is not '${LOCKFILE_VERSION}', the only pnpm lockfile format effective-input reads`);
+  }
+}
+
+/** `pnpm-workspace.yaml` minus its `packages` block, comments and blank lines: the install settings it carries. */
+export function workspaceSettings(yamlText) {
+  const kept = [];
+  let inPackages = false;
+  for (const line of yamlText.split('\n')) {
+    if (/^\S/.test(line)) inPackages = /^packages\s*:/.test(line);
+    if (inPackages) continue;
+    const text = line.replace(/\s+$/, '');
+    if (text.trim() === '' || text.trim().startsWith('#')) continue;
+    kept.push(text);
+  }
+  return kept.join('\n');
+}
+
+/**
+ * What steers the install and so the bytes, beyond the closure's own entries: the lockfile's `settings`, `overrides`
+ * and `patchedDependencies`, the root `package.json`'s `packageManager` and `pnpm` block, and the workspace file's
+ * settings. Each is canonical data; none depends on the root's path.
+ */
+export function installInputs({ lockText, packageJson, workspaceYaml }) {
+  assertLockfileVersion(lockText);
+  const { settings = {}, overrides = {}, patchedDependencies = {} } = lockSections(lockText);
+  const manifest = JSON.parse(packageJson);
+  return {
+    lock: { settings, overrides, patchedDependencies },
+    packageManager: manifest.packageManager ?? null,
+    pnpm: manifest.pnpm ?? null,
+    workspace: sha256(workspaceSettings(workspaceYaml)),
+  };
+}
+
+/**
+ * The lockfile slice of a closure: its importers (keyed by package name, a `link:<path>` version rewritten to
+ * `link:<package name>`), plus the snapshots reachable from them and each one's `packages` entry. `packages` is
+ * `[{ name, dir }]`, `dir` relative to the lockfile's root.
+ */
+export function lockfileSlice(lockText, packages) {
+  assertLockfileVersion(lockText);
+  const { importers = {}, packages: registry = {}, snapshots = {} } = lockSections(lockText);
+  const nameByDir = new Map(packages.map((p) => [posix.normalize(p.dir), p.name]));
+  const slice = { importers: {}, snapshots: {}, packages: {} };
+  const pending = [];
+  for (const { name, dir } of packages) {
+    const body = importers[posix.normalize(dir)];
+    if (body === undefined) throw new Error(`the lockfile has no importer for ${name} (${dir})`);
+    const sections = importerDependencies(body);
+    for (const deps of Object.values(sections)) {
+      for (const [dep, entry] of Object.entries(deps)) {
+        if (entry.version?.startsWith('link:')) {
+          const target = nameByDir.get(posix.join(dir, entry.version.slice(5)));
+          if (target === undefined) throw new Error(`${name} links ${entry.version}, which is not in the closure`);
+          entry.version = `link:${target}`;
+        } else if (entry.version !== undefined) {
+          pending.push(snapshotKey(dep, entry.version));
+        }
+      }
+    }
+    slice.importers[name] = sections;
+  }
+  while (pending.length > 0) {
+    const key = pending.pop();
+    if (Object.hasOwn(slice.snapshots, key)) continue;
+    const body = snapshots[key];
+    if (body === undefined) throw new Error(`the lockfile has no snapshot ${key}`);
+    slice.snapshots[key] = body.map((l) => l.trim());
+    const entry = registry[packageKey(key)];
+    if (entry === undefined) throw new Error(`the lockfile has no packages entry ${packageKey(key)}`);
+    slice.packages[packageKey(key)] = entry.map((l) => l.trim());
+    for (const [dep, version] of Object.entries(snapshotDependencies(body))) pending.push(snapshotKey(dep, version));
+  }
+  return slice;
+}
+
+/** sha256 over the sorted `<path>\0<git mode>\0<sha256>\n` lines of `files` (`{ relativePath: { bytes, mode } }`). */
+export function packageDigest(files) {
+  const hash = createHash('sha256');
+  for (const path of Object.keys(files).sort()) hash.update(`${path}\0${files[path].mode}\0${sha256(files[path].bytes)}\n`);
+  return hash.digest('hex');
+}
+
+/**
+ * The key and its parts. `packages` is `[{ name, files }]` (`files`: package-relative path -> `{ bytes, mode }`), `lockSlice` the
+ * result of `lockfileSlice`, `tooling` `{ dockerfile, scripts: { name: bytes }, buildArgs: { NAME: value }, stageTool: { name, version } }`,
+ * `rootConfig` `{ fileName: bytes }`, `install` the result of `installInputs`.
+ */
+export function effectiveInput({ service, platform, baseImage, packages, lockSlice, install, tooling, rootConfig }) {
+  if (!/^linux\/(amd64|arm64)$/.test(platform)) throw new Error(`platform must be linux/amd64 or linux/arm64, got '${platform}'`);
+  if (typeof baseImage !== 'string' || !DIGEST_PINNED.test(baseImage)) {
+    throw new Error(`the base image must be digest-pinned (<name>@sha256:<64 hex>), got '${baseImage}': a tag names mutable bytes`);
+  }
+  const excluded = Object.keys(tooling.buildArgs ?? {}).filter((n) => NON_CONTENT_BUILD_ARGS.includes(n));
+  if (excluded.length > 0) throw new Error(`build arg(s) ${excluded.join(', ')} are paths or the commit and are not key inputs: leave them out`);
+  const parts = {
+    schema: KEY_SCHEMA,
+    service,
+    platform,
+    baseImage,
+    tooling: {
+      buildArgs: tooling.buildArgs ?? {},
+      dockerfile: sha256(tooling.dockerfile),
+      scripts: Object.fromEntries(Object.entries(tooling.scripts).map(([name, bytes]) => [name, sha256(bytes)])),
+      stageTool: tooling.stageTool,
+    },
+    rootConfig: Object.fromEntries(Object.entries(rootConfig).map(([name, bytes]) => [name, sha256(bytes)])),
+    workspace: Object.fromEntries(packages.map((p) => [p.name, packageDigest(p.files)])),
+    lock: sha256(canonicalJson(lockSlice)),
+    install,
+  };
+  return { key: sha256(canonicalJson(parts)), parts };
+}
+
+// ── Gathering from a workspace root ─────────────────────────────────────────────────────────────────────────────────
+
+const run = (file, args, cwd) => execFileSync(file, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28 });
+
+/**
+ * The workspace package graph, from ONE `turbo query` (the whole graph, so a package with no build task is not dropped):
+ * `Map<name, { name, dir, dependencies: string[] }>`, `dir` relative to `root`.
+ */
+export function packageGraph(root) {
+  const query = 'query { packages { items { name path directDependencies { items { name } } } } }';
+  const items = JSON.parse(run('pnpm', ['exec', 'turbo', 'query', query], root)).data.packages.items;
+  return new Map(items.filter((p) => p.name !== '//').map((p) => [p.name, { name: p.name, dir: p.path, dependencies: p.directDependencies.items.map((d) => d.name) }]));
+}
+
+/** `[{ name, dir }]` of `service` and every workspace package it depends on, sorted by name. */
+export function closureIn(graph, service) {
+  const seen = new Map();
+  const pending = [service];
+  while (pending.length > 0) {
+    const name = pending.pop();
+    if (seen.has(name)) continue;
+    const entry = graph.get(name);
+    if (entry === undefined) throw new Error(`'${name}' is not a package of this workspace`);
+    seen.set(name, { name, dir: entry.dir });
+    pending.push(...entry.dependencies.filter((d) => graph.has(d)));
+  }
+  return [...seen.values()].sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+const GIT_MODES = new Set(['100644', '100755', '120000']);
+
+/** The package-relative tracked files of `dir` (git, run inside it: a submodule or the repository), each with its git mode. */
+export function trackedFiles(root, dir) {
+  const cwd = join(root, dir);
+  const out = run('git', ['ls-files', '-s', '-z', '--', '.'], cwd);
+  const files = {};
+  for (const record of out.split('\0').filter(Boolean)) {
+    const tab = record.indexOf('\t');
+    const [mode] = record.slice(0, tab).split(' ');
+    const path = record.slice(tab + 1);
+    if (!GIT_MODES.has(mode)) throw new Error(`${dir}/${path} has git mode ${mode}, which effective-input does not key (a nested repository?)`);
+    files[path] = { mode, bytes: mode === '120000' ? Buffer.from(readlinkSync(join(cwd, path))) : readFileSync(join(cwd, path)) };
+  }
+  return files;
+}
+
+/** The key and parts of each of `services`, from one package-graph query and one read of the lockfile and tooling. */
+export function effectiveInputKeys({ root, services, platform, baseImage, dockerfile, scripts, buildArgs = {} }) {
+  if (!Array.isArray(services) || services.length === 0) throw new Error('at least one service is required');
+  const names = scripts.map((x) => posix.basename(x));
+  const duplicate = names.find((n, i) => names.indexOf(n) !== i);
+  if (duplicate !== undefined) throw new Error(`two --script files are named '${duplicate}': the key names scripts by file name`);
+  const graph = packageGraph(root);
+  const toolManifest = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8'));
+  const rootConfig = Object.fromEntries(rootBuildInputNames(root).filter((n) => COMPILE_ROOT_FILE.test(n)).map((n) => [n, readFileSync(join(root, n))]));
+  const lockText = readFileSync(join(root, 'pnpm-lock.yaml'), 'utf8');
+  const install = installInputs({ lockText, packageJson: readFileSync(join(root, 'package.json'), 'utf8'), workspaceYaml: readFileSync(join(root, 'pnpm-workspace.yaml'), 'utf8') });
+  const tooling = {
+    dockerfile: readFileSync(dockerfile),
+    scripts: Object.fromEntries(scripts.map((s) => [posix.basename(s), readFileSync(s)])),
+    buildArgs,
+    stageTool: { name: toolManifest.name, version: toolManifest.version },
+  };
+  const filesByPackage = new Map();
+  const filesOf = ({ name, dir }) => {
+    if (!filesByPackage.has(name)) filesByPackage.set(name, trackedFiles(root, dir));
+    return filesByPackage.get(name);
+  };
+  return Object.fromEntries(services.map((service) => {
+    const closure = closureIn(graph, service);
+    return [service, effectiveInput({
+      service,
+      platform,
+      baseImage,
+      packages: closure.map((p) => ({ name: p.name, files: filesOf(p) })),
+      lockSlice: lockfileSlice(lockText, closure),
+      install,
+      tooling,
+      rootConfig,
+    })];
+  }));
+}
+
+/** The key and parts of one service (`effectiveInputKeys` of one). */
+export function effectiveInputKey({ service, ...options }) {
+  return effectiveInputKeys({ ...options, services: [service] })[service];
+}
+
+/**
+ * The one place a key becomes its registry tag: `ei-<key>`. INTERIM: this is to move to `@xemahq/contracts/distribution`
+ * (edition's ruling), the single home of the prefix; until it is published this is the one copy.
+ */
+export function effectiveInputTag(key) {
+  if (!/^[0-9a-f]{64}$/.test(key)) throw new Error(`'${key}' is not an effective-input key (64 lowercase hex)`);
+  return `ei-${key}`;
+}
+
+/**
+ * The `--out` map: per service `{ schema, platform, key, parts, tag }`. `tag` is built only by `effectiveInputTag`, so a consumer
+ * (release-policy's `prepare --effective-inputs`) reads it here and declares no prefix.
+ */
+export function effectiveInputRecord(keys, platform) {
+  return Object.fromEntries(
+    Object.entries(keys).map(([service, { key, parts }]) => [service, { schema: KEY_SCHEMA, platform, key, parts, tag: effectiveInputTag(key) }]),
+  );
+}
+
+// Only what the key can see is keyed: the closure's tracked files, the lockfile, the install settings, the Dockerfile, the
+// `--script` files and the build args. A file the Dockerfile COPYs from OUTSIDE the closure (an entrypoint, infra/docker/*)
+// is keyed only if it is passed as --script: the COPY sources are not derived (ARG-expanded paths such as REPO_DIR make that
+// root-dependent), so the caller must list them.
+const USAGE = 'usage: xema-effective-input --service <pkg> [--service <pkg>]... --platform linux/<amd64|arm64> --base-image <name@sha256:digest> --dockerfile <file> [--script <file>]... [--build-arg NAME=VALUE]... [--out <file>]  (--script: every file the Dockerfile COPYs from outside the closure)';
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const SINGLE = ['platform', 'base-image', 'dockerfile', 'out'];
+
+export function parseArgs(argv) {
+  const options = { service: [], script: [], 'build-arg': [] };
+  for (let i = 0; i < argv.length; i += 2) {
+    const name = argv[i]?.startsWith('--') ? argv[i].slice(2) : undefined;
+    const value = argv[i + 1];
+    if (name === undefined || value === undefined || ![...SINGLE, 'service', 'script', 'build-arg'].includes(name)) throw new Error(USAGE);
+    if (Array.isArray(options[name])) options[name].push(value);
+    else if (Object.hasOwn(options, name)) throw new Error(`--${name} is given twice`);
+    else options[name] = value;
+  }
+  for (const required of ['platform', 'base-image', 'dockerfile']) if (!Object.hasOwn(options, required)) throw new Error(USAGE);
+  if (options.service.length === 0) throw new Error(USAGE);
+  const buildArgs = {};
+  for (const pair of options['build-arg']) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`--build-arg wants NAME=VALUE, got '${pair}'`);
+    const name = pair.slice(0, eq);
+    if (Object.hasOwn(buildArgs, name)) throw new Error(`build arg ${name} is given twice`);
+    buildArgs[name] = pair.slice(eq + 1);
+  }
+  return {
+    services: options.service,
+    platform: options.platform,
+    baseImage: options['base-image'],
+    dockerfile: resolve(options.dockerfile),
+    scripts: options.script.map((s) => resolve(s)),
+    buildArgs,
+    out: options.out,
+  };
+}
+
+if (invokedDirectly(process.argv[1], import.meta.url)) {
+  try {
+    const { out, ...options } = parseArgs(process.argv.slice(2));
+    const keys = effectiveInputKeys({ root: process.cwd(), ...options });
+    if (out !== undefined) {
+      writeFileSync(out, `${JSON.stringify(effectiveInputRecord(keys, options.platform), null, 2)}\n`);
+    }
+    const shown = Object.fromEntries(Object.entries(keys).map(([service, { key }]) => [service, key]));
+    process.stdout.write(options.services.length === 1 ? `${shown[options.services[0]]}\n` : `${JSON.stringify(shown)}\n`);
+  } catch (error) {
+    console.error(`::error::${error.message.split('\n')[0]}`);
+    console.error(error.message);
+    process.exit(1);
+  }
+}

package/src/effective-input.test.mjs

@@ -0,0 +1,290 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test } from 'node:test';
+
+import { canonicalJson, closureIn, effectiveInput, effectiveInputKeys, effectiveInputRecord, effectiveInputTag, installInputs, lockfileSlice, parseArgs, trackedFiles } from './effective-input.mjs';
+
+const DIGEST = `ghcr.io/x/node-runtime@sha256:${'a'.repeat(64)}`;
+const lock = (prefix, settings = 'autoInstallPeers: true') => `lockfileVersion: '9.0'
+
+settings:
+  ${settings}
+
+overrides:
+  left-pad: 1.3.0
+
+patchedDependencies:
+  tiny@1.0.0:
+    hash: aaa
+    path: patches/tiny.patch
+
+importers:
+
+  .:
+    devDependencies:
+      turbo:
+        specifier: ^2.0.0
+        version: 2.0.1
+
+  ${prefix}apps/svc:
+    dependencies:
+      '@x/lib':
+        specifier: workspace:*
+        version: link:../../packages/lib
+      left-pad:
+        specifier: ^1.0.0
+        version: 1.3.0
+
+  ${prefix}packages/lib:
+    dependencies:
+      tiny:
+        specifier: ^1.0.0
+        version: 1.0.0(peer@1.0.0)
+
+packages:
+
+  left-pad@1.3.0:
+    resolution: {integrity: sha512-LEFT}
+
+  tiny@1.0.0:
+    resolution: {integrity: sha512-TINY}
+
+  peer@1.0.0:
+    resolution: {integrity: sha512-PEER}
+
+  unused@9.9.9:
+    resolution: {integrity: sha512-UNUSED}
+
+snapshots:
+
+  left-pad@1.3.0: {}
+
+  tiny@1.0.0(peer@1.0.0):
+    dependencies:
+      peer: 1.0.0
+
+  peer@1.0.0: {}
+`;
+
+/** A workspace root at `prefix` ('' = a repository, 'repos/r/' = an aggregator), each package its own git repo. */
+function workspace(prefix, { svcSource = 'export const a = 1;\n', libSource = 'export const b = 1;\n' } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'effective-input-'));
+  const files = { [`${prefix}apps/svc/src/main.ts`]: svcSource, [`${prefix}packages/lib/src/index.ts`]: libSource };
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(join(root, dirname(path)), { recursive: true });
+    writeFileSync(join(root, path), content);
+  }
+  for (const dir of [`${prefix}apps/svc`, `${prefix}packages/lib`]) {
+    execFileSync('git', ['init', '-q'], { cwd: join(root, dir) });
+    execFileSync('git', ['add', '.'], { cwd: join(root, dir) });
+  }
+  const dirs = [{ name: '@x/lib', dir: `${prefix}packages/lib` }, { name: 'svc', dir: `${prefix}apps/svc` }];
+  return { root, dirs, prefix };
+}
+
+const PACKAGE_JSON = JSON.stringify({ packageManager: 'pnpm@10.0.0', pnpm: { onlyBuiltDependencies: ['esbuild'], overrides: { a: '1' }, patchedDependencies: { b: 'p' } } });
+const WORKSPACE_YAML = '# header\npackages:\n  - "apps/*"\n  - "packages/*"\n\nonlyBuiltDependencies:\n  - esbuild\ninjectWorkspacePackages: true\n';
+const install = (over = {}) => installInputs({ lockText: lock(''), packageJson: PACKAGE_JSON, workspaceYaml: WORKSPACE_YAML, ...over });
+
+const base = {
+  service: 'svc',
+  platform: 'linux/arm64',
+  baseImage: DIGEST,
+  tooling: { dockerfile: 'FROM x', scripts: { 'split.mjs': 's' }, buildArgs: { INSTALL_COSIGN: 'no' }, stageTool: { name: 't', version: '1.0.0' } },
+  rootConfig: { '.npmrc': 'a=b', 'tsconfig.base.json': '{}' },
+};
+
+function keyOf(ws, overrides = {}) {
+  const packages = ws.dirs.map(({ name, dir }) => ({ name, files: trackedFiles(ws.root, dir) }));
+  return effectiveInput({ ...base, packages, lockSlice: lockfileSlice(lock(ws.prefix), ws.dirs), install: install(), ...overrides }).key;
+}
+
+test('the same inputs give the same key from a repository root and from an aggregator root', () => {
+  const repo = workspace('');
+  const aggregator = workspace('repos/r/');
+  try {
+    assert.equal(keyOf(repo), keyOf(aggregator));
+    assert.equal(keyOf(repo), keyOf(repo));
+    assert.match(keyOf(repo), /^[0-9a-f]{64}$/);
+  } finally {
+    rmSync(repo.root, { recursive: true });
+    rmSync(aggregator.root, { recursive: true });
+  }
+});
+
+test('each input class changes the key', () => {
+  const ws = workspace('');
+  const changed = workspace('', { libSource: 'export const b = 2;\n' });
+  try {
+    const original = keyOf(ws);
+    const variants = {
+      'workspace source (transitive package)': keyOf(changed),
+      'lockfile slice': effectiveInput({
+        ...base,
+        packages: ws.dirs.map(({ name, dir }) => ({ name, files: trackedFiles(ws.root, dir) })),
+        install: install(),
+        lockSlice: lockfileSlice(lock('').replace('sha512-TINY', 'sha512-OTHER'), ws.dirs),
+      }).key,
+      'file mode (executable bit)': (() => {
+        const files = Object.fromEntries(Object.entries(trackedFiles(ws.root, 'packages/lib')).map(([k, v]) => [k, { ...v, mode: '100755' }]));
+        return effectiveInput({ ...base, install: install(), lockSlice: lockfileSlice(lock(''), ws.dirs), packages: [{ name: '@x/lib', files }, { name: 'svc', files: trackedFiles(ws.root, 'apps/svc') }] }).key;
+      })(),
+      'lock settings': keyOf(ws, { install: install({ lockText: lock('', 'autoInstallPeers: false') }) }),
+      'lock overrides': keyOf(ws, { install: install({ lockText: lock('').replace('left-pad: 1.3.0', 'left-pad: 1.2.0') }) }),
+      'lock patchedDependencies': keyOf(ws, { install: install({ lockText: lock('').replace('hash: aaa', 'hash: bbb') }) }),
+      'package.json packageManager': keyOf(ws, { install: install({ packageJson: PACKAGE_JSON.replace('10.0.0', '10.1.0') }) }),
+      'package.json pnpm block': keyOf(ws, { install: install({ packageJson: PACKAGE_JSON.replace('esbuild', 'sharp') }) }),
+      'pnpm-workspace.yaml settings': keyOf(ws, { install: install({ workspaceYaml: WORKSPACE_YAML.replace('true', 'false') }) }),
+      dockerfile: keyOf(ws, { tooling: { ...base.tooling, dockerfile: 'FROM y' } }),
+      'stage script': keyOf(ws, { tooling: { ...base.tooling, scripts: { 'split.mjs': 't' } } }),
+      'stage tool version': keyOf(ws, { tooling: { ...base.tooling, stageTool: { name: 't', version: '1.0.1' } } }),
+      'build arg': keyOf(ws, { tooling: { ...base.tooling, buildArgs: { INSTALL_COSIGN: 'yes' } } }),
+      'base image digest': keyOf(ws, { baseImage: `ghcr.io/x/node-runtime@sha256:${'b'.repeat(64)}` }),
+      arch: keyOf(ws, { platform: 'linux/amd64' }),
+      'root compile config': keyOf(ws, { rootConfig: { ...base.rootConfig, '.npmrc': 'a=c' } }),
+    };
+    for (const [name, key] of Object.entries(variants)) assert.notEqual(key, original, `${name} must change the key`);
+    assert.equal(new Set(Object.values(variants)).size, Object.keys(variants).length, 'the classes are distinct');
+  } finally {
+    rmSync(ws.root, { recursive: true });
+    rmSync(changed.root, { recursive: true });
+  }
+});
+
+test('a lockfile entry outside the closure does not change the key', () => {
+  const ws = workspace('');
+  try {
+    const slice = (text) => canonicalJson(lockfileSlice(text, ws.dirs));
+    assert.equal(slice(lock('')), slice(lock('').replace('sha512-UNUSED', 'sha512-ELSE')));
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a tag-only base image is refused, with the reason', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => keyOf(ws, { baseImage: 'ghcr.io/x/node-runtime:22' }), /digest-pinned/);
+    assert.throws(() => keyOf(ws, { baseImage: 'ghcr.io/x/node-runtime@sha256:abc' }), /digest-pinned/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a per-root path or the commit is refused as a build arg', () => {
+  const ws = workspace('');
+  try {
+    for (const name of ['REPO_DIR', 'SERVICE_PATH', 'BUILD_SHA']) {
+      assert.throws(() => keyOf(ws, { tooling: { ...base.tooling, buildArgs: { [name]: 'x' } } }), new RegExp(name));
+    }
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a workspace link outside the closure and a missing snapshot fail fast', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => lockfileSlice(lock(''), ws.dirs.filter((d) => d.name === 'svc')), /not in the closure/);
+    assert.throws(() => lockfileSlice(lock('').replace('  peer@1.0.0: {}\n', ''), ws.dirs), /no snapshot/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('the command line takes repeated build args and refuses a duplicate', () => {
+  const argv = ['--service', 's', '--service', 't', '--platform', 'linux/arm64', '--base-image', DIGEST, '--dockerfile', 'D', '--build-arg', 'A=1', '--build-arg', 'B=2=3'];
+  assert.deepEqual(parseArgs(argv).buildArgs, { A: '1', B: '2=3' });
+  assert.deepEqual(parseArgs(argv).services, ['s', 't']);
+  assert.throws(() => parseArgs([...argv, '--lane', 'develop']), /usage/);
+  assert.throws(() => parseArgs([...argv, '--build-arg', 'A=2']), /given twice/);
+});
+
+test('the tag is ei-<key>, and a bad key is refused', () => {
+  const key = 'a'.repeat(64);
+  assert.equal(effectiveInputTag(key), `ei-${key}`);
+  assert.throws(() => effectiveInputTag('abc'), /not an effective-input key/);
+  assert.throws(() => effectiveInputTag('ei-' + key), /not an effective-input key/);
+});
+
+test('the closure is walked transitively from the package graph, including a package with no build task, and refuses an unknown service', () => {
+  const graph = new Map([
+    ['svc', { name: 'svc', dir: 'apps/svc', dependencies: ['mid', 'external'] }],
+    ['mid', { name: 'mid', dir: 'packages/mid', dependencies: ['leaf', 'svc-cycle-free'] }],
+    ['leaf', { name: 'leaf', dir: 'packages/leaf', dependencies: [] }],
+    ['svc-cycle-free', { name: 'svc-cycle-free', dir: 'packages/c', dependencies: ['mid'] }],
+    ['other', { name: 'other', dir: 'apps/other', dependencies: [] }],
+  ]);
+  assert.deepEqual(closureIn(graph, 'svc').map((p) => p.name), ['leaf', 'mid', 'svc', 'svc-cycle-free']);
+  assert.deepEqual(closureIn(graph, 'other').map((p) => p.name), ['other']);
+  assert.throws(() => closureIn(graph, 'nope'), /not a package/);
+});
+
+test('the workspace file keys its settings, not its package globs, comments or blank lines', () => {
+  const ws = workspace('');
+  try {
+    const original = keyOf(ws);
+    assert.equal(keyOf(ws, { install: install({ workspaceYaml: WORKSPACE_YAML.replace('"apps/*"', '"repos/*/apps/*"').replace('# header', '# other') + '\n\n' }) }), original);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('a lockfileVersion other than 9.0 is refused by name', () => {
+  const ws = workspace('');
+  try {
+    assert.throws(() => lockfileSlice(lock('').replace("'9.0'", "'6.0'"), ws.dirs), /lockfileVersion '6.0' is not '9.0'/);
+    assert.throws(() => install({ lockText: 'settings:\n' }), /lockfileVersion 'undefined'/);
+  } finally {
+    rmSync(ws.root, { recursive: true });
+  }
+});
+
+test('two scripts with the same file name are refused', () => {
+  assert.throws(() => effectiveInputKeys({ root: '.', services: ['s'], platform: 'linux/arm64', baseImage: DIGEST, dockerfile: 'D', scripts: ['a/x.mjs', 'b/x.mjs'] }), /two --script files are named 'x.mjs'/);
+});
+
+test('the --out map carries the tag per service, from effectiveInputTag', () => {
+  const key = 'c'.repeat(64);
+  const record = effectiveInputRecord({ 'a-api': { key, parts: { x: 1 } } }, 'linux/amd64');
+  assert.equal(record['a-api'].tag, effectiveInputTag(key));
+  assert.equal(record['a-api'].tag, `ei-${key}`);
+  assert.equal(record['a-api'].key, key);
+  assert.equal('tags' in record['a-api'], false);
+});
+
+// The failure this guards: through a pnpm bin shim `argv[1]` is a symlink, and a bin that compares it to its own real path
+// runs nothing and exits 0. A run with no arguments must print the usage line and exit 1; silence is the failure.
+const USAGE_RUN = (command, args, cwd) => spawnSync(command, args, { cwd, encoding: 'utf8' });
+const assertUsage = (result) => {
+  assert.equal(result.status, 1, `exit ${result.status}, stdout '${result.stdout}', stderr '${result.stderr}'`);
+  assert.match(result.stderr, /usage: xema-effective-input/);
+};
+
+test('the bin runs through a symlink to it', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ei-bin-link-'));
+  try {
+    const link = join(dir, 'xema-effective-input');
+    symlinkSync(fileURLToPath(new URL('./effective-input.mjs', import.meta.url)), link);
+    assertUsage(USAGE_RUN(process.execPath, [link], dir));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('the bin runs through `pnpm exec` from an installed copy', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ei-bin-pnpm-'));
+  try {
+    const packageDir = fileURLToPath(new URL('..', import.meta.url));
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'consumer', private: true, dependencies: { '@xemahq/repo-build-tooling': `link:${packageDir}` } }));
+    const install = USAGE_RUN('pnpm', ['install', '--offline', '--ignore-workspace'], dir);
+    assert.equal(install.status, 0, install.stderr);
+    assertUsage(USAGE_RUN('pnpm', ['exec', 'xema-effective-input'], dir));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/invoked-directly.mjs

@@ -0,0 +1,38 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// Side-effect free ON PURPOSE: a CLI imports this to decide whether it was run, and must not execute anything (readiness.mjs, which
+// used to hold it, refuses at import time when the cwd has no package.json).
+/**
+ * Was this module RUN, or merely imported (by its own test)?
+ *
+ * BOTH SIDES ARE REALPATH'D, and that is the whole correctness of it. pnpm's
+ * isolated linker puts the package at `node_modules/.pnpm/<pkg>@<ver>/...` and
+ * symlinks `node_modules/@scope/<pkg>` to it, so `process.argv[1]` and
+ * `import.meta.url` can name the SAME FILE by two different paths. Comparing
+ * them unresolved gives an answer that depends on HOW THE PACKAGE WAS LINKED —
+ * true through pnpm's bin shim, which invokes the realpath, and false when the
+ * symlinked path is invoked. A predicate whose answer depends on the linker is
+ * not a predicate.
+ *
+ * The failure mode is the one this whole tool exists to prevent: a false answer
+ * takes the import branch, `run()` is never called, and the process exits 0 —
+ * a chain reporting success without running. Caught by a peer, not by me, and
+ * not by any test, which is why `invokedDirectly` is exported and asserted
+ * below against a REAL symlink.
+ *
+ * `fileURLToPath` rather than `new URL(...).pathname`: the latter is not the
+ * documented conversion and is wrong independently of the symlink — it breaks on
+ * a Windows drive letter and on any percent-encoded character, and a single
+ * SPACE in a checkout path is enough to produce one.
+ */
+export function invokedDirectly(argv1, metaUrl) {
+  if (argv1 === undefined) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    // An unresolvable path cannot be this module; never guess YES, because a
+    // wrong YES runs the chain from a context that did not ask for it.
+    return false;
+  }
+}

package/src/readiness.mjs

@@ -63,11 +63,12 @@
  */
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, readdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 
+import { invokedDirectly } from './invoked-directly.mjs';
+
 // THE ROOT IS THE CONSUMER'S REPOSITORY, NEVER THIS PACKAGE'S LOCATION.
 // This ships as a bin from `@xemahq/repo-build-tooling`, so `import.meta.url`
 // resolves inside `node_modules` — deriving the root from it would grade the
@@ -744,39 +745,9 @@ function run() {
   return 0;
 }
 
-/**
- * Was this module RUN, or merely imported (by its own test)?
- *
- * BOTH SIDES ARE REALPATH'D, and that is the whole correctness of it. pnpm's
- * isolated linker puts the package at `node_modules/.pnpm/<pkg>@<ver>/...` and
- * symlinks `node_modules/@scope/<pkg>` to it, so `process.argv[1]` and
- * `import.meta.url` can name the SAME FILE by two different paths. Comparing
- * them unresolved gives an answer that depends on HOW THE PACKAGE WAS LINKED —
- * true through pnpm's bin shim, which invokes the realpath, and false when the
- * symlinked path is invoked. A predicate whose answer depends on the linker is
- * not a predicate.
- *
- * The failure mode is the one this whole tool exists to prevent: a false answer
- * takes the import branch, `run()` is never called, and the process exits 0 —
- * a chain reporting success without running. Caught by a peer, not by me, and
- * not by any test, which is why `invokedDirectly` is exported and asserted
- * below against a REAL symlink.
- *
- * `fileURLToPath` rather than `new URL(...).pathname`: the latter is not the
- * documented conversion and is wrong independently of the symlink — it breaks on
- * a Windows drive letter and on any percent-encoded character, and a single
- * SPACE in a checkout path is enough to produce one.
- */
-export function invokedDirectly(argv1, metaUrl) {
-  if (argv1 === undefined) return false;
-  try {
-    return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
-  } catch {
-    // An unresolvable path cannot be this module; never guess YES, because a
-    // wrong YES runs the chain from a context that did not ask for it.
-    return false;
-  }
-}
+// `invokedDirectly` lives in its own side-effect-free module (this one does work at import time); re-exported so every importer of it
+// from here, and its test, keep working.
+export { invokedDirectly };
 
 const INVOKED_DIRECTLY = invokedDirectly(process.argv[1], import.meta.url);