@xemahq/repo-build-tooling 0.27.2 → 0.27.3

package/README.md

@@ -30,7 +30,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `stage-tree`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
-| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The final stage only COPYs |
+| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The stage reaches the build as the named context `xema-service` (`--build-context xema-service=.xema-stage`); the authoritative name is `STAGED_SERVICE_CONTEXT` in `@xemahq/distribution-source-hash`, whose image hash frames such a service from its tracked tree, closure, turbo globalDependencies and tsconfig chain, so the stage must be built from no other repository input. The final stage only COPYs |
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... [--release-index-workflow <file>] --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; with `--release-index-workflow`, a release tag that names an image index signed by that workflow on main, with exactly one `linux/amd64` child whose own digest passes that same reuse check, is instead `reused` with `evidence=release-index`, `digest` = the amd64 child A, `index_digest` = the index D and no predicate, but only when A's selected promotion statement promotes `--commit` itself (a rerun; a later commit with the same content takes the existing miss and attests its own promotion). On `evidence=release-index` the caller skips sign/attest, tags `:<sha>` and `main-<sha>` to the amd64 subject `digest` (release-arm64 resolves `:<sha>` to it and verifies its promotion), and points only the content tag (and `latest`, if it moves it) at the index `index_digest`. Any failed step keeps the miss, and two amd64 children are an error; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.27.2",
+  "version": "0.27.3",
   "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)",
@@ -47,9 +47,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"
+    "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"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:3a4f2d10146fe209afa48b5f783954e50bd239602444a7a59920cc7196169c6b"
+    "sourceDigest": "sha256:d6ac6c711e4edb7ef2d2fa6531089a4f443381fd1e622ee2a060eb36a229ee6c"
   }
 }

package/src/staged-image-proof.mjs

@@ -24,12 +24,23 @@ export const CONTEXT_DIRECTORY = 'context';
  * context, which puts it in the content tag.
  */
 export const ROOT_BUILD_INPUT = /^(pnpm-lock\.yaml|package\.json|pnpm-workspace\.yaml|\.npmrc|\.pnpmfile\.cjs|turbo\.json|tsconfig[^/]*\.json)$/;
-/** The repository-root files that are build inputs (`ROOT_BUILD_INPUT`), sorted. */
-export const rootBuildInputNames = (root) =>
-  readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && ROOT_BUILD_INPUT.test(entry.name))
-    .map((entry) => entry.name)
-    .sort();
+/**
+ * The repository-root files that are build inputs (`ROOT_BUILD_INPUT`), sorted. A root build input
+ * that is not a regular file (a symlink, a directory) is refused, naming it: the content tag frames
+ * a symlink's link text, not the file the build reads, so skipping or following it would let the
+ * staged bytes move under one tag.
+ */
+export const rootBuildInputNames = (root) => {
+  const entries = readdirSync(root, { withFileTypes: true }).filter((entry) => ROOT_BUILD_INPUT.test(entry.name));
+  const irregular = entries.filter((entry) => !entry.isFile()).map((entry) => entry.name);
+  if (irregular.length > 0) {
+    throw new Error(
+      `root build input(s) ${irregular.sort().map((name) => `"${name}"`).join(', ')} in "${root}" are not regular files ` +
+        `(a symlink or a directory); the content tag cannot bind them, so commit each as a regular file`,
+    );
+  }
+  return entries.map((entry) => entry.name).sort();
+};
 export const TOOL_NAME = '@xemahq/repo-build-tooling';
 const TOOL_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), '..');
 

package/src/staged-image-proof.test.mjs

@@ -0,0 +1,48 @@
+import { strict as assert } from 'node:assert';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, test } from 'node:test';
+
+import { rootBuildInputNames } from './staged-image-proof.mjs';
+
+const roots = [];
+after(() => {
+  for (const root of roots) rmSync(root, { recursive: true, force: true });
+});
+const freshRoot = () => {
+  const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), 'xema-staged-image-proof-')));
+  roots.push(root);
+  return root;
+};
+
+test('rootBuildInputNames lists the regular root build inputs, sorted, and nothing else', () => {
+  const root = freshRoot();
+  for (const name of ['turbo.json', 'package.json', 'tsconfig.base.json', 'README.md', '.node-version']) {
+    writeFileSync(join(root, name), '{}\n');
+  }
+  mkdirSync(join(root, 'services'));
+  assert.deepEqual(rootBuildInputNames(root), ['package.json', 'tsconfig.base.json', 'turbo.json']);
+});
+
+test('a symlinked root build input refuses, naming it', () => {
+  const root = freshRoot();
+  writeFileSync(join(root, 'package.json'), '{}\n');
+  mkdirSync(join(root, 'tooling'));
+  writeFileSync(join(root, 'tooling', 'turbo.json'), '{}\n');
+  symlinkSync('tooling/turbo.json', join(root, 'turbo.json'));
+  assert.throws(() => rootBuildInputNames(root), /root build input\(s\) "turbo\.json" .* are not regular files/);
+});
+
+test('a directory named like a root build input refuses', () => {
+  const root = freshRoot();
+  mkdirSync(join(root, 'tsconfig.json'));
+  assert.throws(() => rootBuildInputNames(root), /"tsconfig\.json" .* are not regular files/);
+});
+
+test('a symlink that is not a root build input is not this check\'s concern', () => {
+  const root = freshRoot();
+  writeFileSync(join(root, 'package.json'), '{}\n');
+  symlinkSync('package.json', join(root, 'README.md'));
+  assert.deepEqual(rootBuildInputNames(root), ['package.json']);
+});