@xemahq/repo-build-tooling 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.28.0",
+  "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)",
@@ -52,6 +52,6 @@
     "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:741aec4b08022b9aa6702a86627e72163defa62b568c2dbacc2f9e29f14d85bf"
+    "sourceDigest": "sha256:a5327bf366fb31aeef8adb584888e52a5ae4da7aa5602eb672eb2876ed912a8b"
   }
 }

package/src/effective-input.mjs

@@ -2,7 +2,7 @@
 // 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>]… [--lane candidate|develop] --platform linux/<amd64|arm64> --base-image <name@sha256:digest>
+//   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`).
@@ -25,6 +25,7 @@ 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;
@@ -319,27 +320,22 @@ export function effectiveInputKey({ service, ...options }) {
   return effectiveInputKeys({ ...options, services: [service] })[service];
 }
 
-/** The registries' tag lanes. `Candidate` images are built by the owl candidate run, `Develop` ones by develop CI. */
-export const EffectiveInputLane = Object.freeze({ Candidate: 'candidate', Develop: 'develop' });
-const LANE_PREFIX = Object.freeze({ [EffectiveInputLane.Candidate]: 'cand', [EffectiveInputLane.Develop]: 'ei' });
-
-/** The one place a key becomes a registry tag: `cand-<key>` or `ei-<key>`. */
-export function effectiveInputTag(key, lane) {
+/**
+ * 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)`);
-  if (!Object.hasOwn(LANE_PREFIX, lane)) throw new Error(`lane must be one of ${Object.values(EffectiveInputLane).join(', ')}, got '${lane}'`);
-  return `${LANE_PREFIX[lane]}-${key}`;
+  return `ei-${key}`;
 }
 
 /**
- * The `--out` map: per service `{ schema, platform, key, parts, tags: { candidate, develop } }`. The tags are built only by
- * `effectiveInputTag`, so a consumer (release-policy's `prepare --effective-inputs`) reads them here and declares no prefix.
+ * 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, tags: Object.fromEntries(Object.values(EffectiveInputLane).map((lane) => [lane, effectiveInputTag(key, lane)])) },
-    ]),
+    Object.entries(keys).map(([service, { key, parts }]) => [service, { schema: KEY_SCHEMA, platform, key, parts, tag: effectiveInputTag(key) }]),
   );
 }
 
@@ -347,9 +343,9 @@ export function effectiveInputRecord(keys, platform) {
 // `--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>]... [--lane candidate|develop] --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 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', 'lane'];
+const SINGLE = ['platform', 'base-image', 'dockerfile', 'out'];
 
 export function parseArgs(argv) {
   const options = { service: [], script: [], 'build-arg': [] };
@@ -363,7 +359,6 @@ export function parseArgs(argv) {
   }
   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);
-  if (options.lane !== undefined && !Object.values(EffectiveInputLane).includes(options.lane)) throw new Error(USAGE);
   const buildArgs = {};
   for (const pair of options['build-arg']) {
     const eq = pair.indexOf('=');
@@ -374,7 +369,6 @@ export function parseArgs(argv) {
   }
   return {
     services: options.service,
-    lane: options.lane,
     platform: options.platform,
     baseImage: options['base-image'],
     dockerfile: resolve(options.dockerfile),
@@ -384,14 +378,14 @@ export function parseArgs(argv) {
   };
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (invokedDirectly(process.argv[1], import.meta.url)) {
   try {
-    const { out, lane, ...options } = parseArgs(process.argv.slice(2));
+    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, lane === undefined ? key : effectiveInputTag(key, lane)]));
+    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]}`);

package/src/effective-input.test.mjs

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict';
-import { execFileSync } from 'node:child_process';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+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 { EffectiveInputLane, canonicalJson, closureIn, effectiveInput, effectiveInputKeys, effectiveInputRecord, effectiveInputTag, installInputs, lockfileSlice, parseArgs, trackedFiles } from './effective-input.mjs';
+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'
@@ -199,18 +200,15 @@ 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', 'prod']), /usage/);
+  assert.throws(() => parseArgs([...argv, '--lane', 'develop']), /usage/);
   assert.throws(() => parseArgs([...argv, '--build-arg', 'A=2']), /given twice/);
 });
 
-test('tags name both lanes from one declaration and refuse a bad key or lane', () => {
+test('the tag is ei-<key>, and a bad key is refused', () => {
   const key = 'a'.repeat(64);
-  assert.equal(effectiveInputTag(key, EffectiveInputLane.Candidate), `cand-${key}`);
-  assert.equal(effectiveInputTag(key, EffectiveInputLane.Develop), `ei-${key}`);
-  assert.notEqual(effectiveInputTag(key, EffectiveInputLane.Candidate), effectiveInputTag(key, EffectiveInputLane.Develop));
-  assert.throws(() => effectiveInputTag(key, 'prod'), /lane must be one of/);
-  assert.throws(() => effectiveInputTag('abc', EffectiveInputLane.Develop), /not an effective-input key/);
-  assert.throws(() => effectiveInputTag('cand-' + key, EffectiveInputLane.Develop), /not an effective-input key/);
+  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', () => {
@@ -250,10 +248,43 @@ 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 both lane tags per service, from effectiveInputTag', () => {
+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.deepEqual(record['a-api'].tags, { candidate: effectiveInputTag(key, EffectiveInputLane.Candidate), develop: effectiveInputTag(key, EffectiveInputLane.Develop) });
-  assert.deepEqual(record['a-api'].tags, { candidate: `cand-${key}`, develop: `ei-${key}` });
+  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);