@xemahq/repo-build-tooling 0.18.0 → 0.19.0

package/README.md

@@ -33,6 +33,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `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>... --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; 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 |
+| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents (plain scripts without turbo); CI is the proof |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 
 `xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.18.0",
+  "version": "0.19.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-prepush-sanity": "src/prepush-sanity.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-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
     "./package.json": "./package.json",
+    "./prepush-sanity": "./src/prepush-sanity.mjs",
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
@@ -45,9 +47,9 @@
     "@xemahq/release-policy": "^14.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-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-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.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-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-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:aba8ae8794d81525b38c0dfcfefae6abb58b1075eebdc18d261e661c0e07b2fd"
+    "sourceDigest": "sha256:83e791d902527383230de73310281ab3f1b6c8a79a640e686ffba5bd4b102def"
   }
 }

package/src/prepush-sanity.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// Pre-push: cheap sanity on what the push changes. CI is the proof (owner
+// 10-13/10-14). One verb for every repository's lefthook `pre-push`, so the
+// logic is not copied per repo.
+//
+// With turbo (a `turbo.json` and a turbo dependency): turbo `lint` and `typecheck` run only on the packages
+// the pushed commits change plus their dependents. A change to the lockfile,
+// root package.json or turbo.json invalidates everything and runs the full
+// graph. A repo whose turbo carries no `lint` task also runs its root `lint`
+// script. Without turbo: root `typecheck` and `lint` scripts.
+//
+// The pushed SHA is what is graded. In place when the tree is clean and the SHA
+// is HEAD, or when no differing path lies in a package the run reads or at the
+// repository root; otherwise from a `git archive` export. A delete-only push
+// (or no ref on stdin) grades nothing.
+//
+// Never builds for its own sake, never runs tests, docker or `pnpm check`.
+//
+// Usage (lefthook `pre-push` with `use_stdin: true`):
+//   xema-prepush-sanity
+// ═══════════════════════════════════════════════════════════════════════════
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ZERO_SHA = /^0+$/;
+const GIT_ENV = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_PREFIX',
+];
+
+/** turbo.json is JSONC: strip comments outside strings. */
+export function stripJsonc(text) {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j;
+    } else if (c === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+    } else if (c === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 1;
+    } else {
+      out += c;
+    }
+  }
+  return out;
+}
+
+/** The sanity tasks a turbo.json defines. An unparsable file throws: "no tasks" would report green. */
+export function turboTasks(text) {
+  const cfg = JSON.parse(stripJsonc(text));
+  const defined = cfg.tasks ?? cfg.pipeline ?? {};
+  return ['lint', 'typecheck'].filter((t) => t in defined);
+}
+
+/** The refs git writes on a pre-push hook's stdin, one sha graded once, deletes dropped. */
+export function parseRefs(stdin) {
+  const seen = new Set();
+  const refs = [];
+  for (const line of stdin.split('\n')) {
+    const [, sha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+    if (!sha || !/^[0-9a-f]+$/.test(sha) || ZERO_SHA.test(sha) || seen.has(sha)) continue;
+    seen.add(sha);
+    refs.push({ sha, remoteRef: remoteRef ?? '', remoteSha: remoteSha ?? '' });
+  }
+  return refs;
+}
+
+/** True when a changed path invalidates every package. */
+export function isFleetWide(changedPaths) {
+  return changedPaths.some((p) => p === 'pnpm-lock.yaml' || p === 'package.json' || p === 'turbo.json');
+}
+
+/**
+ * First differing path that stops the working tree standing in for the pushed
+ * SHA, or null. `taskDirs` are the package directories the run reads;
+ * `isOwned(path)` says a package.json sits above the path. Root-level *.md files
+ * are the one root exception: no task reads them.
+ */
+export function blockingPath(paths, taskDirs, isOwned) {
+  const dirs = taskDirs.filter((d) => d && d !== '.');
+  for (const p of paths) {
+    if (dirs.some((d) => p === d || p.startsWith(`${d}/`))) return { path: p, why: 'is in a package this run reads' };
+    if (!isOwned(p) && !/^[^/]*\.md$/.test(p)) return { path: p, why: 'is at the repository root' };
+  }
+  return null;
+}
+
+/** One turbo cache for the in-place run and every scratch export; an inherited value wins. */
+export function turboCacheDir(inherited, root) {
+  return inherited || join(root, '.turbo', 'cache');
+}
+
+function cleanEnv(root) {
+  const env = { ...process.env };
+  for (const k of GIT_ENV) delete env[k];
+  env.TURBO_CACHE_DIR = turboCacheDir(env.TURBO_CACHE_DIR, root);
+  // Appended, never prepended: it only fills a gap (the aggregator owns node_modules).
+  const sup = spawnSync('git', ['rev-parse', '--show-superproject-working-tree'], { cwd: root, env, encoding: 'utf8' });
+  const superproject = sup.status === 0 ? sup.stdout.trim() : '';
+  if (superproject && existsSync(join(superproject, 'node_modules', '.bin'))) {
+    env.PATH = `${env.PATH ?? ''}${delimiter}${join(superproject, 'node_modules', '.bin')}`;
+  }
+  return env;
+}
+
+function createContext(root) {
+  const env = cleanEnv(root);
+  const git = (args, cwd = root) => spawnSync('git', args, { cwd, env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  const gitOut = (args, cwd = root) => {
+    const r = git(args, cwd);
+    return r.status === 0 ? r.stdout : null;
+  };
+  const inherit = (cmd, args, cwd) => spawnSync(cmd, args, { cwd, env, stdio: ['ignore', 'inherit', 'inherit'] }).status === 0;
+  return { root, env, git, gitOut, inherit };
+}
+
+function pickBase(ctx, { remoteSha, remoteRef }) {
+  if (remoteSha && /^[0-9a-f]+$/.test(remoteSha) && !ZERO_SHA.test(remoteSha) && ctx.git(['cat-file', '-e', `${remoteSha}^{commit}`]).status === 0) {
+    return remoteSha;
+  }
+  const target = remoteRef.replace(/^refs\/heads\//, '');
+  for (const cand of [`origin/${target}`, 'origin/develop']) {
+    const out = ctx.gitOut(['rev-parse', '--verify', '-q', `${cand}^{commit}`]);
+    if (out) return out.trim();
+  }
+  return '';
+}
+
+/** `A...B` naming the change, or '' for the full graph. */
+function rangeFor(ctx, base, sha) {
+  if (!base) {
+    console.error('pre-push: no base to diff against — running the FULL graph.');
+    return '';
+  }
+  const changed = (ctx.gitOut(['diff', '--name-only', `${base}...${sha}`]) ?? '').split('\n').filter(Boolean);
+  if (isFleetWide(changed)) {
+    console.error('pre-push: lockfile, root package.json or turbo.json changed — fleet-wide, running the FULL graph.');
+    return '';
+  }
+  return `${base}...${sha}`;
+}
+
+function turboBin(root, env) {
+  const local = join(root, 'node_modules', '.bin', 'turbo');
+  if (existsSync(local)) return local;
+  const r = spawnSync('sh', ['-c', 'command -v turbo'], { env, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : '';
+}
+
+function declaresTurbo(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    return Boolean(pkg.dependencies?.turbo ?? pkg.devDependencies?.turbo);
+  } catch {
+    return false;
+  }
+}
+
+function hasRootLint(dir) {
+  try {
+    return Boolean(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).scripts?.lint);
+  } catch {
+    return false;
+  }
+}
+
+/** Run the sanity tasks in `dir`; `range` '' is the full graph. Returns the verdict. */
+function runHere(ctx, dir, range, bin) {
+  if (!bin) {
+    console.log('pre-push: pnpm run typecheck && pnpm run lint (this repository declares no turbo)');
+    const typecheck = ctx.inherit('pnpm', ['run', 'typecheck'], dir);
+    const lint = ctx.inherit('pnpm', ['run', 'lint'], dir);
+    return typecheck && lint;
+  }
+  let tasks;
+  try {
+    tasks = turboTasks(readFileSync(join(dir, 'turbo.json'), 'utf8'));
+  } catch (error) {
+    console.log(`pre-push: could not read the tasks from turbo.json (${error.message}) — FAILED`);
+    return false;
+  }
+  if (tasks.length === 0) {
+    console.log('pre-push: turbo.json defines none of lint, typecheck — FAILED');
+    return false;
+  }
+  let ok;
+  if (range) {
+    console.log(`pre-push: turbo run ${tasks.join(' ')} (affected by ${range}, plus dependents)`);
+    ok = ctx.inherit(bin, ['run', ...tasks, `--filter=...[${range}]`, '--continue=dependencies-successful'], dir);
+  } else {
+    console.log(`pre-push: turbo run ${tasks.join(' ')} (full graph)`);
+    ok = ctx.inherit(bin, ['run', ...tasks, '--continue=dependencies-successful'], dir);
+  }
+  // Lint that turbo does not carry is the root `lint` script CI runs.
+  if (!tasks.includes('lint') && hasRootLint(dir)) {
+    console.log('pre-push: pnpm run lint');
+    ok = ctx.inherit('pnpm', ['run', 'lint'], dir) && ok;
+  }
+  return ok;
+}
+
+function inPlaceSafe(ctx, sha, range, tasks, bin) {
+  if (!range || !bin) return false;
+  const dry = spawnSync(bin, ['run', ...tasks, `--filter=...[${range}]`, '--dry=json'], { cwd: ctx.root, env: ctx.env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (dry.status !== 0) return false;
+  let taskDirs;
+  try {
+    taskDirs = (JSON.parse(dry.stdout).tasks ?? []).map((t) => t.directory);
+  } catch {
+    return false;
+  }
+  const paths = [
+    ctx.gitOut(['diff', '--name-only', '-z', 'HEAD']) ?? '',
+    ctx.gitOut(['ls-files', '-z', '--others', '--exclude-standard']) ?? '',
+    ctx.gitOut(['diff', '--name-only', '-z', 'HEAD', sha]) ?? '',
+  ].flatMap((s) => s.split('\0').filter(Boolean));
+  const isOwned = (p) => {
+    let dir = dirname(p);
+    while (dir !== '.' && dir !== '/') {
+      if (existsSync(join(ctx.root, dir, 'package.json'))) return true;
+      dir = dirname(dir);
+    }
+    return false;
+  };
+  const blocked = blockingPath(paths, taskDirs, isOwned);
+  if (blocked) console.error(`pre-push: ${blocked.path} ${blocked.why}`);
+  return blocked === null;
+}
+
+function exportTo(ctx, rev, dir) {
+  return spawnSync('sh', ['-c', 'git archive "$1" | tar -x -C "$2"', 'sh', rev, dir], { cwd: ctx.root, env: ctx.env }).status === 0;
+}
+
+function gradeFromExport(ctx, sha, base, range, bin) {
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-prepush-'));
+  try {
+    const sh = (args) => ctx.git(['-c', 'user.email=gate@local', '-c', 'user.name=gate', ...args], scratch).status === 0;
+    if (!sh(['init', '-q', '.'])) return false;
+    let exportRange = '';
+    if (range) {
+      // Two commits (base, then the graded tree) so turbo can diff them as it would a checkout.
+      if (!exportTo(ctx, base, scratch) || !sh(['add', '-A']) || !sh(['commit', '-qm', 'base'])) return false;
+      for (const name of readdirSync(scratch)) if (name !== '.git') rmSync(join(scratch, name), { recursive: true, force: true });
+      exportRange = 'HEAD~1...HEAD';
+    }
+    if (!exportTo(ctx, sha, scratch) || !sh(['add', '-A']) || !sh(['commit', '-qm', 'graded', '--allow-empty'])) return false;
+    if (!ctx.inherit('pnpm', ['install', '--frozen-lockfile', '--prefer-offline'], scratch)) {
+      console.log('pre-push: install of the export failed');
+      return false;
+    }
+    return runHere(ctx, scratch, exportRange, bin);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+function gradeSha(ctx, ref, bin) {
+  const { sha } = ref;
+  const base = pickBase(ctx, ref);
+  const range = rangeFor(ctx, base, sha);
+  const head = (ctx.gitOut(['rev-parse', 'HEAD']) ?? '').trim();
+  const short = (rev) => (ctx.gitOut(['rev-parse', '--short', rev]) ?? rev).trim();
+  const clean = (ctx.gitOut(['status', '--porcelain']) ?? '') === '';
+  if (sha === head && clean) {
+    console.log(`pre-push: grading HEAD ${short(head)} in place (clean tree).`);
+    return runHere(ctx, ctx.root, range, bin);
+  }
+  if (bin) {
+    let tasks = [];
+    try {
+      tasks = turboTasks(readFileSync(join(ctx.root, 'turbo.json'), 'utf8'));
+    } catch {
+      // runHere reports an unreadable turbo.json as the failure it is.
+    }
+    if (tasks.length > 0 && inPlaceSafe(ctx, sha, range, tasks, bin)) {
+      console.log(`pre-push: grading ${short(sha)} in place — no differing path is in a package this run reads.`);
+      return runHere(ctx, ctx.root, range, bin);
+    }
+  }
+  console.log(
+    sha === head
+      ? `pre-push: grading ${short(sha)} from an export — the tree is dirty, so it is not what is being pushed.`
+      : `pre-push: grading ${short(sha)} from an export — the commit being PUSHED, which is not HEAD ${short(head)}.`,
+  );
+  return gradeFromExport(ctx, sha, base, bin ? range : '', bin);
+}
+
+export function main(stdin) {
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', env: Object.fromEntries(Object.entries(process.env).filter(([k]) => !GIT_ENV.includes(k))) });
+  if (top.status !== 0) {
+    console.error('pre-push: not inside a git repository — FAILED');
+    return 1;
+  }
+  const ctx = createContext(top.stdout.trim());
+  const refs = parseRefs(stdin);
+  if (refs.length === 0) {
+    console.log('pre-push: no ref on stdin — this push updates nothing, nothing to grade.');
+    return 0;
+  }
+  // Turbo is used only where the repository declares it; a declared turbo that does not
+  // resolve is an uninstalled checkout, and fails rather than skipping the proof.
+  let bin = '';
+  if (existsSync(join(ctx.root, 'turbo.json')) && declaresTurbo(ctx.root)) {
+    bin = turboBin(ctx.root, ctx.env);
+    if (!bin) {
+      console.log('pre-push: no turbo binary resolves — run `pnpm install --frozen-lockfile` — FAILED');
+      console.log('::error::pre-push FAILED — turbo:unavailable');
+      return 1;
+    }
+  }
+  const failed = refs.filter((ref) => !gradeSha(ctx, ref, bin)).map((ref) => ctx.gitOut(['rev-parse', '--short', ref.sha])?.trim() ?? ref.sha);
+  if (failed.length === 0) {
+    console.log(`pre-push: GREEN — lint typecheck passed on ${refs.length} pushed commit(s).`);
+    return 0;
+  }
+  console.log(`::error::pre-push FAILED — ${failed.join(' ')}`);
+  console.log(`pre-push: FAILED — ${failed.join(' ')}`);
+  return 1;
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main(process.stdin.isTTY ? '' : readFileSync(0, 'utf8'));
+}

package/src/prepush-sanity.test.mjs

@@ -0,0 +1,124 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { blockingPath, isFleetWide, parseRefs, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
+
+const VERB = fileURLToPath(new URL('./prepush-sanity.mjs', import.meta.url));
+const SHA_A = 'a'.repeat(40);
+const SHA_B = 'b'.repeat(40);
+
+test('stripJsonc drops comments outside strings only', () => {
+  const text = '{ // c\n "a": "x//y", /* b */ "b": 1 }';
+  assert.deepEqual(JSON.parse(stripJsonc(text)), { a: 'x//y', b: 1 });
+});
+
+test('turboTasks keeps lint and typecheck, and throws on unparsable turbo.json', () => {
+  assert.deepEqual(turboTasks('{"tasks":{"build":{},"typecheck":{},"lint":{}}}'), ['lint', 'typecheck']);
+  assert.deepEqual(turboTasks('{"pipeline":{"typecheck":{}}}'), ['typecheck']);
+  assert.throws(() => turboTasks('{ nope'));
+});
+
+test('parseRefs dedupes shas and drops deletes and junk', () => {
+  const zero = '0'.repeat(40);
+  const stdin = [`refs/heads/x ${SHA_A} refs/heads/develop ${SHA_B}`, `refs/heads/y ${SHA_A} refs/heads/z ${SHA_B}`, `(delete) ${zero} refs/heads/old ${SHA_B}`, ''].join('\n');
+  assert.deepEqual(parseRefs(stdin), [{ sha: SHA_A, remoteRef: 'refs/heads/develop', remoteSha: SHA_B }]);
+  assert.deepEqual(parseRefs(''), []);
+});
+
+test('isFleetWide flags only the lockfile, root package.json and turbo.json', () => {
+  assert.equal(isFleetWide(['pnpm-lock.yaml']), true);
+  assert.equal(isFleetWide(['package.json']), true);
+  assert.equal(isFleetWide(['packages/a/package.json', 'src/x.ts']), false);
+});
+
+test('blockingPath: package reads and repo-root files block, root markdown does not', () => {
+  const owned = (p) => p.startsWith('packages/');
+  assert.equal(blockingPath(['packages/a/src/x.ts'], ['packages/a'], owned)?.why, 'is in a package this run reads');
+  assert.equal(blockingPath(['packages/b/src/x.ts'], ['packages/a'], owned), null);
+  assert.equal(blockingPath(['tsconfig.base.json'], [], owned)?.why, 'is at the repository root');
+  assert.equal(blockingPath(['README.md'], [], owned), null);
+});
+
+function repo(scripts) {
+  const dir = mkdtempSync(join(tmpdir(), 'prepush-sanity-test-'));
+  const run = (...args) => execFileSync('git', args, { cwd: dir, stdio: 'pipe' });
+  run('init', '-q', '-b', 'develop');
+  run('config', 'user.email', 't@t');
+  run('config', 'user.name', 't');
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 't', private: true, scripts }));
+  run('add', '-A');
+  run('commit', '-qm', 'init');
+  const sha = run('rev-parse', 'HEAD').toString().trim();
+  return { dir, sha };
+}
+
+function hook(dir, stdin) {
+  return spawnSync('node', [VERB], { cwd: dir, input: stdin, encoding: 'utf8' });
+}
+
+test('no turbo: a failing typecheck refuses the push, a passing one is green', () => {
+  const bad = repo({ typecheck: 'exit 1', lint: 'exit 0' });
+  const good = repo({ typecheck: 'exit 0', lint: 'exit 0' });
+  try {
+    const refused = hook(bad.dir, `refs/heads/x ${bad.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    assert.equal(refused.status, 1, refused.stdout + refused.stderr);
+    assert.match(refused.stdout, /pre-push: FAILED/);
+    const green = hook(good.dir, `refs/heads/x ${good.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    assert.equal(green.status, 0, green.stdout + green.stderr);
+    assert.match(green.stdout, /GREEN/);
+  } finally {
+    rmSync(bad.dir, { recursive: true, force: true });
+    rmSync(good.dir, { recursive: true, force: true });
+  }
+});
+
+test('a delete-only push and a manual run grade nothing', () => {
+  const r = repo({ typecheck: 'exit 1', lint: 'exit 1' });
+  try {
+    const del = hook(r.dir, `(delete) ${'0'.repeat(40)} refs/heads/old ${r.sha}\n`);
+    assert.equal(del.status, 0, del.stdout + del.stderr);
+    assert.match(del.stdout, /nothing to grade/);
+    assert.equal(hook(r.dir, '').status, 0);
+  } finally {
+    rmSync(r.dir, { recursive: true, force: true });
+  }
+});
+
+test('turboCacheDir defaults to the repo root and keeps an inherited value', () => {
+  assert.equal(turboCacheDir('', '/r'), '/r/.turbo/cache');
+  assert.equal(turboCacheDir(undefined, '/r'), '/r/.turbo/cache');
+  assert.equal(turboCacheDir('/shared', '/r'), '/shared');
+});
+
+test('the turbo invocation receives TURBO_CACHE_DIR', () => {
+  const r = repo({});
+  try {
+    writeFileSync(join(r.dir, 'package.json'), JSON.stringify({ name: 't', private: true, devDependencies: { turbo: '^2' } }));
+    writeFileSync(join(r.dir, 'turbo.json'), JSON.stringify({ tasks: { typecheck: {} } }));
+    mkdirSync(join(r.dir, 'node_modules', '.bin'), { recursive: true });
+    const fake = join(r.dir, 'node_modules', '.bin', 'turbo');
+    const seen = join(r.dir, 'seen.txt');
+    writeFileSync(fake, `#!/bin/sh\nprintf '%s' "$TURBO_CACHE_DIR" > '${seen}'\n`);
+    chmodSync(fake, 0o755);
+    writeFileSync(join(r.dir, '.gitignore'), 'node_modules\nseen.txt\n');
+    execFileSync('git', ['add', '-A'], { cwd: r.dir });
+    execFileSync('git', ['commit', '-qm', 'turbo'], { cwd: r.dir });
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: r.dir }).toString().trim();
+    const stdin = `refs/heads/x ${sha} refs/heads/develop ${'0'.repeat(40)}\n`;
+    const env = { ...process.env };
+    delete env.TURBO_CACHE_DIR;
+    const run = (e) => spawnSync('node', [VERB], { cwd: r.dir, input: stdin, encoding: 'utf8', env: e });
+    const first = run(env);
+    assert.equal(first.status, 0, first.stdout + first.stderr);
+    assert.equal(readFileSync(seen, 'utf8'), join(realpathSync(r.dir), '.turbo', 'cache'));
+    const second = run({ ...env, TURBO_CACHE_DIR: '/inherited/cache' });
+    assert.equal(second.status, 0, second.stdout + second.stderr);
+    assert.equal(readFileSync(seen, 'utf8'), '/inherited/cache');
+  } finally {
+    rmSync(r.dir, { recursive: true, force: true });
+  }
+});

package/src/promote-image-provenance.mjs

@@ -75,10 +75,17 @@ function verifiedStatement({ subject, digest, type, predicateType, what, noun, p
   return { statement, payloadDigest };
 }
 
-/** The predicate types of every attestation on `subject`, listed without verifying any signature. A registry error is an error. */
+// cosign v2 exits 1 with this exact stderr line (and empty stdout) for an image that carries no attestations.
+const NO_ATTESTATIONS_LINE = 'Error: found no attestations';
+
+/**
+ * The predicate types of every attestation on `subject`, listed without verifying any signature. cosign v2's
+ * "found no attestations" exit is an empty listing; any other failure is an error.
+ */
 function attestationTypes(subject, label, run) {
   const listed = run('cosign', ['download', 'attestation', subject]);
   if (listed.error) throw new Error(`${label}: could not run cosign to list the attestations of ${subject}: ${listed.error.message}`);
+  if (listed.status === 1 && String(listed.stderr ?? '').split('\n').some((line) => line.trim() === NO_ATTESTATIONS_LINE)) return [];
   if (listed.status !== 0) throw new Error(`${label}: listing the attestations of ${subject} failed: ${describeFailure(listed)}`);
   return listed.stdout.split('\n').map((text) => text.trim()).filter(Boolean).map((line) => {
     try {
@@ -99,7 +106,11 @@ export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, rel
   const subject = `${releaseRef}@${digest}`;
   const label = 'reuse';
   // (a) presence, without identity verification: only the predicate types are read
-  if (!attestationTypes(subject, label, run).includes(IMAGE_PROMOTION_PREDICATE_TYPE)) return undefined;
+  const types = attestationTypes(subject, label, run);
+  if (types.length === 0) {
+    throw new Error(`${label}: release image ${subject} carries no attestations; a lane-built release image always has some; needs a human`);
+  }
+  if (!types.includes(IMAGE_PROMOTION_PREDICATE_TYPE)) return undefined;
   // (b) a promotion attestation is present: any verification failure is an error
   const found = verifiedStatement({
     subject, digest, type: IMAGE_PROMOTION_PREDICATE_TYPE, predicateType: IMAGE_PROMOTION_PREDICATE_TYPE,

package/src/promote-image.test.mjs

@@ -60,7 +60,7 @@ if (tool === 'cosign') {
   if (args[0] === 'download' && args[1] === 'attestation') {
     if (state.downloadErrors[subject]) fail(state.downloadErrors[subject]);
     const listed = state.attestations[subject];
-    if (!listed) fail('Error: no attestations found for ' + subject + '\\n');
+    if (!listed || listed.statements.length === 0) fail('Error: found no attestations\\nerror during command execution: found no attestations\\n');
     for (const statement of listed.statements) {
       process.stdout.write(JSON.stringify({ payloadType: 'application/vnd.in-toto+json', payload: Buffer.from(statement).toString('base64'), signatures: [] }) + '\\n');
     }
@@ -246,6 +246,17 @@ test('a registry error listing the attestations is an error, not a miss', () =>
   );
 });
 
+test('reuse: a release digest with no attestations at all (cosign v2) is an error, not a miss', () => {
+  refused({ tags: { [`${RELEASE}:${TAG}`]: OTHER } }, /reuse: release image .* carries no attestations; .* needs a human/);
+});
+
+test('reuse: exit 1 with any other stderr is an error', () => {
+  refused(
+    { tags: { [`${RELEASE}:${TAG}`]: OTHER }, downloadErrors: { [`${RELEASE}@${OTHER}`]: 'Error: GET https://ghcr.io/v2/x/manifests/y: UNAUTHORIZED\n' } },
+    /reuse: listing the attestations of .* failed: .*UNAUTHORIZED/,
+  );
+});
+
 test('a promotion attestation signed by the wrong identity is refused, not a miss', () => {
   refused(promotedRelease({ identity: DEVELOP_IDENTITY }), /reuse: .* has no image-promotion\/v1 attestation signed by/);
 });
@@ -322,6 +333,13 @@ test('a registry error listing the dev attestations is an error, not a miss', ()
   );
 });
 
+test('copy: exit 1 with a non-"found no attestations" stderr is an error, not a miss', () => {
+  refused(
+    provenDevelop({ downloadErrors: { [`${DEV}@${DIGEST}`]: 'Error: GET https://ghcr.io/v2/x/manifests/y: UNAUTHORIZED\n' } }),
+    /copy: listing the attestations of .* failed: .*UNAUTHORIZED/,
+  );
+});
+
 test('leg (a): provenance signed by a unit-branch workflow is refused before any copy', () => {
   const r = refused(
     provenDevelop({ attestations: { [`${DEV}@${DIGEST}`]: { identity: DEVELOP_IDENTITY.replace('refs/heads/develop', 'refs/heads/unit/x'), statements: [provenance()] } } }),