@xemahq/repo-build-tooling 0.22.0 → 0.24.0

package/README.md

@@ -34,7 +34,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>... [--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 |
-| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents (root `lint` only without turbo; typecheck is CI-only there); CI is the proof |
+| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents, and `test` and `openapi:current` (where defined) only on the packages the push changed; a fleet-wide change runs only `lint` and `typecheck` on the full graph; root `lint` only without turbo; a park-only push (`refs/xema-session/*`) skips |
 | `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.22.0",
+  "version": "0.24.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-install-git-hooks": "src/install-git-hooks.mjs",
     "xema-prepush-sanity": "src/prepush-sanity.mjs",
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
@@ -37,6 +38,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",
+    "./install-git-hooks": "./src/install-git-hooks.mjs",
     "./package.json": "./package.json",
     "./prepush-sanity": "./src/prepush-sanity.mjs",
     "./promote-image": "./src/promote-image.mjs",
@@ -46,12 +48,12 @@
     "./service-image": "./src/service-image.mjs"
   },
   "dependencies": {
-    "@xemahq/release-policy": "^14.0.0"
+    "@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-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/prepush-sanity.test.mjs && node --test src/service-image.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-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/prepush-sanity.test.mjs && node --test src/service-image.test.mjs && node --test src/install-git-hooks.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:0b63df80f6c68f70cb652dfc51f08288aeac11bbee2445cfa6fc440242a7bcf9"
+    "sourceDigest": "sha256:5a6b2b46f5f22f0becd6c31ddb6992e245b73fd5d510228a90c51b30ac0ce8df"
   }
 }

package/src/install-git-hooks.mjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// `xema-install-git-hooks` — run from `prepare`: install the lefthook git hooks, but only where hooks can exist.
+//
+// `prepare` runs on EVERY `pnpm install`, and one of those installs happens
+// inside the service Docker image build, which has neither a `.git` directory
+// (the build context excludes it) nor a `git` binary. A bare
+// `"prepare": "lefthook install"` therefore fails the image build outright:
+//
+//     . prepare: Error: exec: "git": executable file not found in $PATH
+//     ERROR: failed to solve: process "... pnpm install --offline
+//            --filter ${SERVICE}... --frozen-lockfile" exit code: 1
+//
+// That is not a hook problem to work around — it is a category error. Git
+// hooks are a property of a developer's WORKING TREE; an image build has no
+// working tree to hook, so there is nothing to install and nothing has gone
+// wrong. This script says exactly that, out loud, and exits 0.
+//
+// What it does NOT do is swallow a real failure. In an actual git work tree
+// the install must succeed: a non-zero `lefthook install` propagates, because
+// a developer whose pre-push hook silently failed to install is a developer
+// who finds out from CI instead. The two outcomes are distinguished by a
+// deterministic fact — "is there a git work tree here" — never by an `|| true`.
+//
+// ── WHY THIS SCRIPT RESOLVES THE BINARY ITSELF ────────────────────────────
+//
+// It used to `spawnSync('lefthook', …)`, i.e. rely on PATH / the caller's
+// `.bin/`. Inside the AGGREGATOR checkout that is unreachable for a carved
+// repository, and the failure was silent in both halves:
+//
+//   1. `lefthook install` bakes an ABSOLUTE path to the binary that ran it
+//      into the generated hook (measured: re-running `install` from a
+//      different binary rewrites that line). A carved repo's hook was baked by
+//      a `pnpm install` run INSIDE that repo — the escape hatch — so it points
+//      at `repos/<repo>/node_modules/.pnpm/lefthook-*/bin/lefthook`.
+//   2. That store is exactly what `.claude/rules/package-store-ownership.md`
+//      forbids and `tooling/dev/repair-package-stores.mjs` deletes. Afterwards
+//      the baked path dangles, and every remaining fallback in lefthook's
+//      generated hook misses too: lefthook is not on PATH, and a carved repo
+//      root is not an aggregator workspace member, so it has no `node_modules`
+//      and no `.bin/` at all.
+//   3. lefthook's generated hook ends its search with
+//      `echo "Can't find lefthook in PATH"` — and NO non-zero exit. So the
+//      hook printed a warning and returned 0. Measured 2026-08-17: every one
+//      of the ten carved repositories' `pre-push` hooks was in this state, so
+//      every local push in this checkout was unguarded while LOOKING guarded.
+//
+// The fix is the pattern `package-store-ownership.md` already documents for
+// carved root scripts: resolve by PATH-INDEPENDENT node resolution instead of
+// a binary name. `createRequire(...).resolve('lefthook/bin/index.js')` walks up
+// from this file — `repos/<repo>/node_modules` (absent) → the aggregator's
+// `node_modules` (present) — and in a standalone clone it finds the repo's own
+// copy on the first hop. Same script, both topologies, no per-machine config.
+//
+// ── AND WHY IT HARDENS THE GENERATED HOOK ─────────────────────────────────
+//
+// Resolving the binary fixes today's breakage. It does not fix the SHAPE of
+// the defect: a baked absolute path can dangle again — another store repair,
+// a `pnpm store prune`, a different machine, a moved checkout — and lefthook's
+// template would once more warn-and-return-0. A gate whose only failure mode
+// is a message nobody reads is the failure this repository names most often.
+//
+// So after installing, every generated hook's dead-end branch is rewritten to
+// print the reason and `exit 1`. An unresolvable lefthook now REFUSES the
+// push instead of waving it through; `git push --no-verify` remains the
+// deliberate, visible bypass.
+//
+// The rewrite ASSERTS rather than assumes: the marker must be present exactly
+// once in freshly generated content, and if lefthook's template ever changes
+// so it is not, this fails loudly instead of leaving hooks quietly unhardened.
+//
+// ── AND WHY IT SWEEPS SUBMODULES ──────────────────────────────────────────
+//
+// A carved repository's root is not an aggregator workspace member, so its own
+// `prepare` NEVER runs from an aggregator install — which is why the fix above
+// would otherwise be inert in the only checkout that has the bug. The
+// aggregator install already owns every `node_modules` beneath `repos/`
+// (`package-store-ownership.md`); it therefore owns the hooks baked against
+// them. Each submodule that carries a lefthook config gets the same install +
+// hardening, from the same resolved binary.
+//
+// In a standalone carved clone this loop is naturally inert — those
+// repositories have no submodules — so one byte-identical script serves both.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** Printed with a stable prefix so the reason is greppable in build logs. */
+const TAG = '[prepare:git-hooks]';
+
+/** The directory `prepare` runs in: the repository (or aggregator) root. */
+const ROOT = process.cwd();
+
+function skip(reason) {
+  console.log(`${TAG} skipped — ${reason}. Nothing to install here.`);
+  process.exit(0);
+}
+
+function die(message) {
+  console.error(`${TAG} ${message}`);
+  process.exit(1);
+}
+
+// ── 1. Is there anything to hook at all? ──────────────────────────────────
+//
+// `git rev-parse --git-dir` is the cheapest total answer to "is this a git
+// work tree": it is non-zero outside one, and ENOENT when git is absent
+// entirely. Both are the same verdict — no tree, no hooks.
+// This is a dev tool, not service code, so it may read the process env.
+if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') {
+  skip("CI runner: git hooks belong to a developer's working tree");
+}
+
+const probe = spawnSync('git', ['rev-parse', '--git-dir'], { stdio: 'ignore' });
+
+if (probe.error?.code === 'ENOENT') {
+  skip('no `git` executable on PATH (image build / CI container)');
+}
+if (probe.error) {
+  skip(`could not probe for a git work tree (${probe.error.message})`);
+}
+if (probe.status !== 0) {
+  skip('not inside a git work tree (installed as a dependency or tarball)');
+}
+
+// ── 2. One-time migration off the hand-rolled `.husky/` directory ─────────
+//
+// This repository used to point `core.hooksPath` at a tracked `.husky/`, wired
+// up by every developer running `git config core.hooksPath .husky` BY HAND —
+// which is why almost nobody was wired up. lefthook writes into `.git/hooks`,
+// and a stale `core.hooksPath` silently wins over it, so the install would
+// report success while no hook ever fired.
+//
+// Cleared ONLY when it points at a directory that no longer exists. A
+// `core.hooksPath` someone set deliberately, to somewhere real, is left alone.
+const hooksPath = spawnSync('git', ['config', '--get', 'core.hooksPath'], {
+  encoding: 'utf8',
+});
+const configured = (hooksPath.stdout ?? '').trim();
+if (configured.length > 0 && !existsSync(configured)) {
+  console.log(
+    `${TAG} clearing core.hooksPath -> ${configured} (that directory is gone; ` +
+      'it would silently win over the hooks installed below)',
+  );
+  const unset = spawnSync('git', ['config', '--unset', 'core.hooksPath'], {
+    stdio: 'inherit',
+  });
+  if (unset.status !== 0) {
+    die(
+      'could not clear core.hooksPath. Run `git config --unset core.hooksPath` ' +
+        'yourself, or the hooks below will not fire.',
+    );
+  }
+}
+
+// ── 3. Resolve the lefthook launcher, PATH-independently ──────────────────
+//
+// See the header. `lefthook`'s npm package exposes `bin/index.js`, a Node
+// launcher that execs the platform binary; the binary reports its OWN absolute
+// path to `lefthook install`, which is the path that gets baked into the hook.
+// So resolving the launcher is enough to fix what gets baked.
+//
+// Resolved from the repository root, not from this file: when installed as a
+// dependency this file lives in a package store that cannot see the repo's
+// own `lefthook` devDependency.
+const require = createRequire(join(ROOT, 'package.json'));
+
+let launcher;
+try {
+  launcher = require.resolve('lefthook/bin/index.js');
+} catch {
+  // Reachable when the tree was installed with `--ignore-scripts` semantics or
+  // a filtered/production install that omits root devDependencies. Loud, but
+  // not fatal: the hooks are a dev affordance, and the install itself is fine.
+  skip('`lefthook` is not installed (root devDependencies were not installed)');
+}
+
+// ── 4. Hardening the generated hook ───────────────────────────────────────
+
+/**
+ * lefthook's dead end. Present verbatim in every hook it generates (2.1.10),
+ * as the `else` arm of the binary search in `call_lefthook`. It prints and
+ * falls out of the function, so the hook exits 0 and the operation proceeds
+ * completely unverified.
+ */
+const DEAD_END = '      echo "Can\'t find lefthook in PATH"\n';
+
+/** Proof our rewrite is already applied — makes the pass idempotent. */
+const SENTINEL = '# xema:lefthook-unresolved-is-fatal';
+
+/**
+ * The replacement. Single-quoted so nothing in it is expanded by `sh`, and
+ * written to stderr because that is where a refusal belongs. `exit 1` inside a
+ * shell function exits the whole hook, which is exactly the intent.
+ */
+const REFUSAL = [
+  `      ${SENTINEL}`,
+  "      echo 'lefthook is installed as a git hook here, but its binary cannot' >&2",
+  "      echo 'be found — so THIS HOOK JUST VERIFIED NOTHING.' >&2",
+  "      echo '' >&2",
+  "      echo 'Refusing the operation rather than letting it through unguarded.' >&2",
+  "      echo '' >&2",
+  "      echo '  Fix: run `pnpm install` in the checkout that owns this tree' >&2",
+  "      echo '       node_modules. That re-runs prepare, which re-bakes this' >&2",
+  "      echo '       hook against a binary that exists.' >&2",
+  "      echo '  Deliberate bypass: git push --no-verify' >&2",
+  '      exit 1',
+  '',
+].join('\n');
+
+/**
+ * Rewrite one generated hook so an unresolvable lefthook is fatal.
+ * @returns {'hardened'|'already'} never silently "nothing to do".
+ */
+function hardenHookFile(file) {
+  const source = readFileSync(file, 'utf8');
+
+  if (source.includes(SENTINEL)) return 'already';
+
+  const occurrences = source.split(DEAD_END).length - 1;
+  if (occurrences !== 1) {
+    die(
+      `cannot harden ${file}: expected lefthook's "can't find" branch exactly ` +
+        `once, found ${occurrences}. lefthook's hook template has changed — ` +
+        're-derive this rewrite rather than leaving hooks unhardened.',
+    );
+  }
+
+  writeFileSync(file, source.replace(DEAD_END, REFUSAL), { mode: 0o755 });
+  return 'hardened';
+}
+
+// ── 5. Install + harden, here and in every hooked submodule ───────────────
+
+/** Absolute path to a work tree's hooks directory, per git itself. */
+function hooksDirOf(cwd) {
+  const out = spawnSync(
+    'git',
+    ['rev-parse', '--path-format=absolute', '--git-path', 'hooks'],
+    { cwd, encoding: 'utf8' },
+  );
+  if (out.status !== 0) return null;
+  const dir = (out.stdout ?? '').trim();
+  return dir.length > 0 ? dir : null;
+}
+
+function installIn(cwd, label) {
+  const install = spawnSync(process.execPath, [launcher, 'install'], {
+    cwd,
+    stdio: 'inherit',
+  });
+
+  if (install.error) {
+    die(`failed to run \`lefthook install\` in ${label}: ${install.error.message}`);
+  }
+  if (install.status !== 0) {
+    die(
+      `\`lefthook install\` exited ${install.status} in ${label}. Git hooks are ` +
+        'NOT installed; fix this rather than pushing without them.',
+    );
+  }
+
+  const dir = hooksDirOf(cwd);
+  if (dir === null || !existsSync(dir)) {
+    die(`\`lefthook install\` reported success in ${label} but ${dir ?? 'its hooks directory'} does not exist.`);
+  }
+
+  // Harden every hook lefthook generated — identified by the search function
+  // it writes, so a pre-existing hand-written hook is never touched.
+  let hardened = 0;
+  for (const name of readdirSync(dir)) {
+    if (name.endsWith('.sample')) continue;
+    const file = join(dir, name);
+    if (!statSync(file).isFile()) continue;
+    const body = readFileSync(file, 'utf8');
+    if (!body.includes('call_lefthook')) continue;
+    if (hardenHookFile(file) === 'hardened') hardened += 1;
+  }
+
+  if (hardened > 0) {
+    console.log(`${TAG} ${label}: hardened ${hardened} hook(s) — an unresolvable lefthook now exits 1.`);
+  }
+}
+
+installIn(ROOT, '.');
+
+// Submodules that carry their own lefthook config. Read from `.gitmodules`
+// rather than `git submodule foreach`, which would spawn a shell per entry
+// across a 28-submodule tree for a question two greps answer.
+const CONFIGS = ['lefthook.yml', 'lefthook.yaml', '.lefthook.yml', '.lefthook.yaml'];
+
+const gitmodules = resolve(ROOT, '.gitmodules');
+if (existsSync(gitmodules)) {
+  const listed = spawnSync(
+    'git',
+    ['config', '--file', gitmodules, '--get-regexp', String.raw`^submodule\..*\.path$`],
+    { encoding: 'utf8' },
+  );
+
+  // Exit 1 means "no matching keys", which is a legitimate empty answer.
+  if (listed.status !== 0 && listed.status !== 1) {
+    die(`could not read submodule paths from ${gitmodules} (exit ${listed.status}).`);
+  }
+
+  const paths = (listed.stdout ?? '')
+    .split('\n')
+    .map((line) => line.split(' ').slice(1).join(' ').trim())
+    .filter((p) => p.length > 0);
+
+  for (const rel of paths) {
+    const dir = resolve(dirname(gitmodules), rel);
+    if (!CONFIGS.some((name) => existsSync(join(dir, name)))) continue;
+    // An uninitialised submodule is an empty directory, not a work tree.
+    if (spawnSync('git', ['rev-parse', '--git-dir'], { cwd: dir, stdio: 'ignore' }).status !== 0) {
+      console.log(`${TAG} ${rel}: not initialised — skipping (run \`git submodule update --init\`).`);
+      continue;
+    }
+    installIn(dir, rel);
+  }
+}

package/src/install-git-hooks.test.mjs

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { after, describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'install-git-hooks.mjs');
+const made = [];
+
+after(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'xema-hooks-'));
+  made.push(dir);
+  return dir;
+}
+
+function run(cwd, env = {}) {
+  const base = { ...process.env, CI: '', GITHUB_ACTIONS: '' };
+  return spawnSync(process.execPath, [SCRIPT], { cwd, env: { ...base, ...env }, encoding: 'utf8' });
+}
+
+/** A git work tree whose `lefthook` is a stub that writes a lefthook-shaped hook. */
+function repoWithFakeLefthook() {
+  const dir = tempDir();
+  spawnSync('git', ['init', '-q'], { cwd: dir });
+  writeFileSync(join(dir, 'package.json'), '{}');
+  const bin = join(dir, 'node_modules', 'lefthook', 'bin');
+  mkdirSync(bin, { recursive: true });
+  writeFileSync(join(dir, 'node_modules', 'lefthook', 'package.json'), '{"name":"lefthook"}');
+  writeFileSync(
+    join(bin, 'index.js'),
+    [
+      "const fs = require('node:fs');",
+      "fs.mkdirSync('.git/hooks', { recursive: true });",
+      "fs.writeFileSync('.git/hooks/pre-push', 'call_lefthook() {\\n  if x; then\\n    :\\n  else\\n      echo \"Can\\'t find lefthook in PATH\"\\n  fi\\n}\\n');",
+    ].join('\n'),
+  );
+  return dir;
+}
+
+describe('xema-install-git-hooks', () => {
+  for (const env of [{ CI: 'true' }, { GITHUB_ACTIONS: 'true' }]) {
+    it(`is a no-op on CI (${Object.keys(env)[0]})`, () => {
+      const dir = repoWithFakeLefthook();
+      const out = run(dir, env);
+      assert.equal(out.status, 0);
+      assert.match(out.stdout, /skipped — CI runner/);
+      assert.equal(existsSync(join(dir, '.git', 'hooks', 'pre-push')), false);
+    });
+  }
+
+  it('is a no-op outside a git work tree', () => {
+    const dir = tempDir();
+    const out = run(dir, { GIT_CEILING_DIRECTORIES: dirname(dir) });
+    assert.equal(out.status, 0);
+    assert.match(out.stdout, /not inside a git work tree/);
+  });
+
+  it('skips when lefthook is not installed', () => {
+    const dir = tempDir();
+    spawnSync('git', ['init', '-q'], { cwd: dir });
+    writeFileSync(join(dir, 'package.json'), '{}');
+    const out = run(dir);
+    assert.equal(out.status, 0);
+    assert.match(out.stdout, /`lefthook` is not installed/);
+  });
+
+  it('installs and hardens the hook outside CI, idempotently', () => {
+    const dir = repoWithFakeLefthook();
+    const first = run(dir);
+    assert.equal(first.status, 0, first.stderr);
+    assert.match(first.stdout, /hardened 1 hook/);
+    const hook = readFileSync(join(dir, '.git', 'hooks', 'pre-push'), 'utf8');
+    assert.match(hook, /xema:lefthook-unresolved-is-fatal/);
+    assert.match(hook, /exit 1/);
+    // Re-running regenerates then re-hardens; the stub rewrites the hook each time.
+    const second = run(dir);
+    assert.equal(second.status, 0, second.stderr);
+  });
+});

package/src/prepush-sanity.mjs

@@ -4,8 +4,12 @@
 // 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,
+// With turbo (a `turbo.json` and a turbo dependency): turbo `lint`, `typecheck`,
+// `test` (unit) and `openapi:current`, each where turbo.json defines it (D136: a cheap
+// pre-push let a stale openapi spec through, and every red costs ~1h of CI). `lint` and
+// `typecheck` run on the packages the pushed commits change plus their dependents; `test`
+// and `openapi:current` only on the packages the push itself changes, and one line names the
+// dependents whose tests are left to CI (an affected-set run took 36 min for a widely used package). A change to the lockfile,
 // turbo.json, or anything in the root package.json other than its `scripts`
 // table invalidates everything and runs the full graph. A repo whose turbo carries no `lint` task also runs its root `lint`
 // script. Without turbo: the root `lint` script only (typecheck needs a build, which the hook never runs; CI has it).
@@ -17,7 +21,9 @@
 // session park (`refs/xema-session/*`) grades nothing either: a park is not a
 // landing, and the work is graded when it lands on a branch.
 //
-// Never builds for its own sake, never runs tests, docker or `pnpm check`.
+// A fleet-wide change runs `lint` and `typecheck` on the full graph and says it
+// leaves `test` and `openapi:current` to CI: never the full suite. Never builds
+// for its own sake, never runs docker, image builds or `pnpm check`.
 //
 // Usage (lefthook `pre-push` with `use_stdin: true`):
 //   xema-prepush-sanity
@@ -62,11 +68,68 @@ export function stripJsonc(text) {
   return out;
 }
 
+/** The tasks pre-push runs on the affected packages, in this order, where turbo.json defines them. */
+export const SANITY_TASKS = ['lint', 'typecheck', 'test', 'openapi:current'];
+/** The subset that also runs on the full graph and on dependents; the rest would be the full suite, which is CI's. */
+export const FULL_GRAPH_TASKS = ['lint', 'typecheck'];
+
+/** Package directories (a package.json below the root) among tracked file paths; node_modules never counts. */
+export function packageDirs(files) {
+  return [...new Set(files.filter((f) => f.endsWith('/package.json') && !f.includes('node_modules/')).map((f) => f.slice(0, -'/package.json'.length)))];
+}
+
+/** Paths no task reads: root-level markdown and changesets. */
+export function isInert(path) {
+  return /^[^/]*\.md$/.test(path) || path.startsWith('.changeset/');
+}
+
+/** Changed paths that sit in no workspace package and that some task may read (tsconfig.base.json, biome.json, tooling/**). They invalidate every package. */
+export function outsidePackages(changed, dirs) {
+  return changed.filter((p) => !isInert(p) && !dirs.some((d) => p.startsWith(`${d}/`)));
+}
+
+/** A push with changes whose plan holds no task checked nothing, and must say so rather than pass; null when it is fine. */
+export function emptyPlanFailure(changed, plannedTasks) {
+  if (changed.length === 0 || plannedTasks > 0) return null;
+  return `no task was planned for a push that changes ${changed.slice(0, 10).join(', ')}${changed.length > 10 ? ` (+${changed.length - 10} more)` : ''} — nothing was checked`;
+}
+
+/**
+ * The turbo runs for a push. `range` '' is the full graph: lint and typecheck only. Otherwise lint and
+ * typecheck run on the affected set (changed packages plus dependents), while test and openapi:current
+ * run only on the packages the push itself changed: a widely used package has dozens of dependents and
+ * their tests cost ~36 min (authorization-nest: 78 packages, 195 tasks). CI runs those.
+ */
+export function planRuns(tasks, range) {
+  if (!range) {
+    const full = tasks.filter((t) => FULL_GRAPH_TASKS.includes(t));
+    return { runs: full.length > 0 ? [{ tasks: full, filter: null }] : [], leftToCi: tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t)) };
+  }
+  const affected = tasks.filter((t) => FULL_GRAPH_TASKS.includes(t));
+  const changedOnly = tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t));
+  const runs = [];
+  if (affected.length > 0) runs.push({ tasks: affected, filter: `...[${range}]` });
+  if (changedOnly.length > 0) runs.push({ tasks: changedOnly, filter: `[${range}]` });
+  return { runs, leftToCi: [] };
+}
+
+/** Package names in `affected` that are not in `changed`, sorted; the root workspace `//` is never a package. */
+export function dependentsOnly(affected, changed) {
+  const own = new Set(changed);
+  return [...new Set(affected)].filter((n) => n !== '//' && !own.has(n)).sort();
+}
+
+/** The one line naming the dependents whose test and openapi:current are left to CI. */
+export function dependentsLine(dependents, tasks) {
+  if (dependents.length === 0 || tasks.length === 0) return '';
+  return `pre-push: ${tasks.join(' ')} ran only on the changed packages; ${dependents.length} dependent(s) are left to CI: ${dependents.join(', ')}`;
+}
+
 /** 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);
+  return SANITY_TASKS.filter((t) => t in defined);
 }
 
 /** The refs git writes on a pre-push hook's stdin, one sha graded once, deletes dropped. */
@@ -178,9 +241,19 @@ function rangeFor(ctx, base, sha) {
     console.error('pre-push: lockfile, turbo.json or root package.json beyond its scripts changed — fleet-wide, running the FULL graph.');
     return '';
   }
+  const files = (rev) => (ctx.gitOut(['ls-tree', '-r', '--name-only', rev]) ?? '').split('\n').filter(Boolean);
+  const outside = outsidePackages(changed, packageDirs([...files(base), ...files(sha)]));
+  if (outside.length > 0) {
+    console.error(`pre-push: ${outside.slice(0, 10).join(', ')}${outside.length > 10 ? ` (+${outside.length - 10} more)` : ''} sit outside any workspace package — fleet-wide, running the FULL graph.`);
+    return '';
+  }
   return `${base}...${sha}`;
 }
 
+function changedPaths(ctx, base, sha) {
+  return base ? (ctx.gitOut(['diff', '--name-only', `${base}...${sha}`]) ?? '').split('\n').filter(Boolean) : [];
+}
+
 function turboBin(root, env) {
   const local = join(root, 'node_modules', '.bin', 'turbo');
   if (existsSync(local)) return local;
@@ -205,8 +278,22 @@ function hasRootLint(dir) {
   }
 }
 
+/** How many tasks turbo plans for `tasks` under `filter`. */
+function dryTaskCount(ctx, bin, dir, tasks, filter) {
+  const dry = spawnSync(bin, ['run', ...tasks, `--filter=${filter}`, '--dry=json'], { cwd: dir, env: ctx.env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (dry.status !== 0) throw new Error(`turbo --dry=json failed for --filter=${filter}`);
+  return (JSON.parse(dry.stdout).tasks ?? []).length;
+}
+
+/** Package names turbo would run `tasks` for under `filter`; an unreadable plan throws rather than hide a dependent. */
+function dryPackages(ctx, bin, dir, tasks, filter) {
+  const dry = spawnSync(bin, ['run', ...tasks, `--filter=${filter}`, '--dry=json'], { cwd: dir, env: ctx.env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (dry.status !== 0) throw new Error(`turbo --dry=json failed for --filter=${filter}`);
+  return JSON.parse(dry.stdout).packages ?? [];
+}
+
 /** Run the sanity tasks in `dir`; `range` '' is the full graph. Returns the verdict. */
-function runHere(ctx, dir, range, bin) {
+function runHere(ctx, dir, range, bin, changed) {
   if (!bin) {
     // Without turbo nothing orders the builds a workspace typecheck needs, and the hook never
     // builds: typecheck there is CI's.
@@ -221,16 +308,29 @@ function runHere(ctx, dir, range, bin) {
     return false;
   }
   if (tasks.length === 0) {
-    console.log('pre-push: turbo.json defines none of lint, typecheck — FAILED');
+    console.log(`pre-push: turbo.json defines none of ${SANITY_TASKS.join(', ')} — 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);
+    const failure = emptyPlanFailure(changed, dryTaskCount(ctx, bin, dir, tasks, `...[${range}]`));
+    if (failure) {
+      console.log(`pre-push: ${failure} — FAILED`);
+      return false;
+    }
+  }
+  const { runs, leftToCi } = planRuns(tasks, range);
+  if (leftToCi.length > 0) console.log(`pre-push: ${leftToCi.join(' ')} not run on the full graph — that is the full suite, CI runs it.`);
+  let ok = true;
+  for (const run of runs) {
+    const where = run.filter ? (run.filter.startsWith('...') ? `affected by ${range}, plus dependents` : `only the packages ${range} changes`) : 'full graph';
+    console.log(`pre-push: turbo run ${run.tasks.join(' ')} (${where})`);
+    const filterArgs = run.filter ? [`--filter=${run.filter}`] : [];
+    ok = ctx.inherit(bin, ['run', ...run.tasks, ...filterArgs, '--continue=dependencies-successful'], dir) && ok;
+  }
+  if (range) {
+    const changedOnly = tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t));
+    const line = dependentsLine(dependentsOnly(dryPackages(ctx, bin, dir, tasks, `...[${range}]`), dryPackages(ctx, bin, dir, tasks, `[${range}]`)), changedOnly);
+    if (line) console.log(line);
   }
   // Lint that turbo does not carry is the root `lint` script CI runs.
   if (!tasks.includes('lint') && hasRootLint(dir)) {
@@ -272,7 +372,7 @@ 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) {
+function gradeFromExport(ctx, sha, base, range, bin, changed) {
   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;
@@ -289,7 +389,7 @@ function gradeFromExport(ctx, sha, base, range, bin) {
       console.log('pre-push: install of the export failed');
       return false;
     }
-    return runHere(ctx, scratch, exportRange, bin);
+    return runHere(ctx, scratch, exportRange, bin, changed);
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }
@@ -299,12 +399,17 @@ function gradeSha(ctx, ref, bin) {
   const { sha } = ref;
   const base = pickBase(ctx, ref);
   const range = rangeFor(ctx, base, sha);
+  const changed = changedPaths(ctx, base, sha);
+  if (range && changed.length > 0 && changed.every(isInert)) {
+    console.log(`pre-push: only paths no task reads changed (${changed.slice(0, 10).join(', ')}) — nothing to grade.`);
+    return true;
+  }
   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);
+    return runHere(ctx, ctx.root, range, bin, changed);
   }
   if (bin) {
     let tasks = [];
@@ -315,7 +420,7 @@ function gradeSha(ctx, ref, bin) {
     }
     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);
+      return runHere(ctx, ctx.root, range, bin, changed);
     }
   }
   console.log(
@@ -323,7 +428,7 @@ function gradeSha(ctx, ref, bin) {
       ? `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);
+  return gradeFromExport(ctx, sha, base, bin ? range : '', bin, changed);
 }
 
 export function main(stdin) {

package/src/prepush-sanity.test.mjs

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
-import { blockingPath, isFleetWide, parkOnly, parseRefs, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
+import { blockingPath, dependentsLine, emptyPlanFailure, isInert, outsidePackages, packageDirs, dependentsOnly, isFleetWide, planRuns, parkOnly, parseRefs, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
 
 const VERB = fileURLToPath(new URL('./prepush-sanity.mjs', import.meta.url));
 const SHA_A = 'a'.repeat(40);
@@ -18,6 +18,7 @@ test('stripJsonc drops comments outside strings only', () => {
 
 test('turboTasks keeps lint and typecheck, and throws on unparsable turbo.json', () => {
   assert.deepEqual(turboTasks('{"tasks":{"build":{},"typecheck":{},"lint":{}}}'), ['lint', 'typecheck']);
+  assert.deepEqual(turboTasks('{"tasks":{"openapi:current":{},"test":{},"build":{},"typecheck":{},"lint":{}}}'), ['lint', 'typecheck', 'test', 'openapi:current']);
   assert.deepEqual(turboTasks('{"pipeline":{"typecheck":{}}}'), ['typecheck']);
   assert.throws(() => turboTasks('{ nope'));
 });
@@ -162,3 +163,43 @@ test('a park-only push skips and says why; a park beside develop still grades',
     rmSync(r.dir, { recursive: true, force: true });
   }
 });
+
+test('planRuns: affected set for lint and typecheck, changed packages only for test and openapi:current', () => {
+  const tasks = ['lint', 'typecheck', 'test', 'openapi:current'];
+  assert.deepEqual(planRuns(tasks, 'A...B'), {
+    runs: [
+      { tasks: ['lint', 'typecheck'], filter: '...[A...B]' },
+      { tasks: ['test', 'openapi:current'], filter: '[A...B]' },
+    ],
+    leftToCi: [],
+  });
+  assert.deepEqual(planRuns(['test'], 'A...B').runs, [{ tasks: ['test'], filter: '[A...B]' }]);
+});
+
+test('planRuns: a root-file change runs lint and typecheck on all and leaves the rest to CI', () => {
+  assert.deepEqual(planRuns(['lint', 'typecheck', 'test'], ''), { runs: [{ tasks: ['lint', 'typecheck'], filter: null }], leftToCi: ['test'] });
+  assert.deepEqual(planRuns(['test'], ''), { runs: [], leftToCi: ['test'] });
+});
+
+test('dependentsOnly and dependentsLine name the dependents left to CI', () => {
+  const dependents = dependentsOnly(['//', 'b', 'a', 'c', 'a'], ['c']);
+  assert.deepEqual(dependents, ['a', 'b']);
+  assert.match(dependentsLine(dependents, ['test', 'openapi:current']), /test openapi:current ran only on the changed packages; 2 dependent\(s\) are left to CI: a, b/);
+  assert.equal(dependentsLine([], ['test']), '');
+  assert.equal(dependentsLine(['a'], []), '');
+});
+
+test('a path outside every workspace package is fleet-wide; package files and inert files are not', () => {
+  const dirs = packageDirs(['package.json', 'packages/a/package.json', 'packages/a/node_modules/x/package.json', 'apps/b/package.json']);
+  assert.deepEqual(dirs.sort(), ['apps/b', 'packages/a']);
+  assert.deepEqual(outsidePackages(['tsconfig.base.json', 'biome.json', 'tooling/ci/x.mjs'], dirs), ['tsconfig.base.json', 'biome.json', 'tooling/ci/x.mjs']);
+  assert.deepEqual(outsidePackages(['packages/a/src/x.ts', 'apps/b/package.json', 'README.md', '.changeset/x.md'], dirs), []);
+  assert.equal(isInert('README.md'), true);
+  assert.equal(isInert('tooling/README.md'), false);
+});
+
+test('zero planned tasks for a push with changes is a failure naming the paths, never green', () => {
+  assert.match(emptyPlanFailure(['tsconfig.base.json'], 0), /tsconfig\.base\.json.*nothing was checked/);
+  assert.equal(emptyPlanFailure(['packages/a/x.ts'], 3), null);
+  assert.equal(emptyPlanFailure([], 0), null);
+});