@xemahq/repo-build-tooling 0.23.0 → 0.25.0

package/README.md

@@ -37,7 +37,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `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.
+`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` and `--base <ref@sha256:…>`, the digest-pinned image the stages start FROM; a reference without a digest is refused; `--copy` and `--stage-dir` optional). The assemble stage copies per package only `package.json` and its plain `files` entries (what `pnpm pack` ships), so a README or test edit changes no image; a package without a `files` array or with a glob entry is refused; `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.
 
 Every step refuses rather than skips. The package has no dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.23.0",
+  "version": "0.25.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:1e968ed2990de85680e206c3dcb98c5467bb3c01166ace6b1e81be91e5344fb1"
+    "sourceDigest": "sha256:60086692452e7d72167195fe99ab5634a798fd8b2461a6e0b09bb27b894b7aa4"
   }
 }

package/src/composed-image-fixture.test.mjs

@@ -9,6 +9,8 @@ export function write(root, rel, content) {
   fs.writeFileSync(path.join(root, rel), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
 }
 
+export const BASE = 'ghcr.io/example/base/node-runtime@sha256:' + 'a'.repeat(64);
+
 export const MEMBERS = Object.freeze({ 'alpha/alpha-api': 'biomes/alpha/api/alpha-api', 'alpha/alpha-db-api': 'biomes/alpha/api/alpha-db-api' });
 export const CLOSURE = Object.freeze(['biomes/alpha/api/alpha-api', 'biomes/alpha/api/alpha-db-api', 'packages/sdks/lib-a']);
 
@@ -26,10 +28,12 @@ export function workspace({ built = true } = {}) {
   write(root, 'infra/composed-process/image-build-inputs.json', { workspacePackages: Object.values(MEMBERS) });
   write(root, 'pnpm-workspace.yaml', "packages:\n  - 'biomes/*/api/*'\n\nonlyBuiltDependencies:\n  - 'esbuild'\n  # a note\n  - prisma\n\n  - \"@prisma/engines\" # trailing\nother: 1\n");
   write(root, '.npmrc', 'registry=https://registry.npmjs.org/\n');
-  write(root, 'biomes/alpha/api/alpha-api/package.json', { name: '@t/alpha-api' });
-  write(root, 'biomes/alpha/api/alpha-db-api/package.json', { name: '@t/alpha-db-api' });
+  write(root, 'biomes/alpha/api/alpha-api/package.json', { name: '@t/alpha-api', files: ['dist'] });
+  write(root, 'biomes/alpha/api/alpha-db-api/package.json', { name: '@t/alpha-db-api', files: ['dist', 'prisma'] });
   write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', 'datasource db {}\n');
-  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist'] });
+  write(root, 'biomes/alpha/api/alpha-api/README.md', '# readme\n');
+  write(root, 'biomes/alpha/api/alpha-api/src/main.test.ts', '// test\n');
+  write(root, 'packages/sdks/lib-a/package.json', { name: '@t/lib-a', files: ['dist', 'assets/data.json'] });
   if (built) {
     write(root, 'biomes/alpha/api/alpha-api/dist/main.js', '// main\n');
     write(root, 'biomes/alpha/api/alpha-db-api/dist/main.js', '// main\n');

package/src/composed-image-in-image-closure.test.mjs

@@ -9,7 +9,7 @@ import test, { after } from 'node:test';
 
 import { renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { copyTool } from './composed-image-stage.mjs';
-import { fakePnpm, workspace } from './composed-image-fixture.test.mjs';
+import { BASE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
 
 const temps = [];
 after(() => {
@@ -28,7 +28,7 @@ function renderedEntries() {
     root,
     copy: ['tooling/dev'],
     cacheId: 'alpha-composed-process',
-    buildSource: 'alpha',
+    buildSource: 'alpha', base: BASE,
     usesToken: true,
     exec: fakePnpm(root),
   });

package/src/composed-image-package-files.mjs

@@ -0,0 +1,33 @@
+// What one workspace package contributes to the assemble stage's build context: its
+// `package.json` plus the `files` entries `pnpm pack` ships. Nothing else of the directory
+// (README, tests, configs) enters the context, so editing it changes no image.
+import { readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+
+/** Directories and files the prebuilt `.dockerignore` keeps out of the context (the staged outputs bring them back). */
+export const IGNORED_DIRECTORIES = Object.freeze(['node_modules', 'dist', '.turbo', 'coverage']);
+export const IGNORED_FILE_PATTERNS = Object.freeze(['*.tsbuildinfo', '*.log']);
+
+const GLOB = /[*?[\]{}!]/;
+const ignoredFile = (name) => name.endsWith('.tsbuildinfo') || name.endsWith('.log');
+
+/**
+ * Repository-relative COPY sources for `directory`: `package.json` and each plain `files` entry. An entry the
+ * `.dockerignore` excludes (e.g. `dist`) is built output, staged separately, and is not a source here.
+ * A package with no `files` array, or a glob entry, is refused: `files` is what says what ships.
+ */
+export function packageSources({ root, directory }) {
+  const files = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8')).files;
+  if (!Array.isArray(files)) throw new Error(`${directory}/package.json has no "files" field — nothing says which of its files ship in the image`);
+  const globs = files.filter((entry) => typeof entry !== 'string' || GLOB.test(entry));
+  if (globs.length > 0) throw new Error(`${directory}/package.json "files" has glob or non-string entries (${globs.join(', ')}); list plain paths`);
+  const entries = files.map((entry) => posix.normalize(entry).replace(/\/$/, ''));
+  for (const entry of entries) {
+    if (entry === '.' || entry.startsWith('/') || entry.split('/').includes('..')) throw new Error(`${directory}/package.json "files" entry "${entry}" is not inside the package`);
+  }
+  const shipped = entries.filter((entry) => {
+    const parts = entry.split('/');
+    return !parts.some((part) => IGNORED_DIRECTORIES.includes(part)) && !ignoredFile(parts.at(-1));
+  });
+  return [...new Set(['package.json', ...shipped])].map((entry) => posix.join(directory, entry));
+}

package/src/composed-image-pnpm-context.test.mjs

@@ -6,14 +6,14 @@ import test from 'node:test';
 
 import { buildPnpmContext, resolveCacheDir } from './composed-image-pnpm-context.mjs';
 import { lockfileOnlyCommand, renderPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
-import { CLOSURE, fakePnpm, workspace, write } from './composed-image-fixture.test.mjs';
+import { BASE, CLOSURE, fakePnpm, workspace, write } from './composed-image-fixture.test.mjs';
 
 function setup({ store = true, cache = true } = {}) {
   const root = workspace();
   write(root, 'package.json', { name: 'r', packageManager: 'pnpm@10.33.0+sha512.abc' });
   write(root, 'pnpm-lock.yaml', 'lockfileVersion: 9\n');
   write(root, 'tooling/dev/x.txt', 'x');
-  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', usesToken: false, exec: fakePnpm(root) }).dockerfile);
+  write(root, 'infra/composed-process/Dockerfile', renderPrebuiltDockerfile({ root, copy: ['tooling/dev'], cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) }).dockerfile);
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-pnpm-home-'));
   const storePath = path.join(home, '.pnpm-store', 'v10');
   const cacheDir = path.join(home, 'cache');
@@ -89,7 +89,7 @@ test('the lockfile-only command is the one the generated Dockerfile runs (no dri
   assert.deepEqual(words.slice(0, 4), ['pnpm', 'install', '--lockfile-only', '--offline']);
   assert.equal(lockfileOnlyCommand(['--filter', 'x'], { offline: false })[3], '--prefer-offline');
   assert.ok(words.includes('--config.inject-workspace-packages=true') && words.includes('--config.dedupe-injected-deps=false'));
-  const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', usesToken: false, exec: fakePnpm(root) });
+  const { dockerfile: text } = renderPrebuiltDockerfile({ root, cacheId: 'x', buildSource: 'repo', base: BASE, usesToken: false, exec: fakePnpm(root) });
   assert.ok(text.includes('pnpm install --lockfile-only --offline ${INJECT} --filter @t/alpha-api... --filter @t/alpha-db-api... &&'));
   assert.ok(text.includes('INJECT="--config.inject-workspace-packages=true --config.dedupe-injected-deps=false"'));
 });

package/src/composed-image-prebuilt-dockerfile.mjs

@@ -9,7 +9,8 @@ import { dirname, join, posix } from 'node:path';
 
 import { COMPOSED_IMAGE_DIR, IN_IMAGE_ENTRY } from './composed-image-paths.mjs';
 import { toolVersion } from './composed-image-stage.mjs';
-import { NODE_BASE, npmrcUsesToken } from './composed-image-dockerfile.mjs';
+import { npmrcUsesToken } from './composed-image-dockerfile.mjs';
+import { IGNORED_DIRECTORIES, IGNORED_FILE_PATTERNS, packageSources } from './composed-image-package-files.mjs';
 import { memberClosure, memberFilters, memberManifests } from './composed-image-members.mjs';
 import { needsPrismaSchemaEngine } from './composed-image-prisma-engine.mjs';
 
@@ -17,8 +18,10 @@ export const DEFAULT_STAGE_DIR = '.xema-stage';
 const DIRECTORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\/?$/;
 const CACHE_ID = /^[a-z0-9][a-z0-9-]*$/;
 const REPOSITORY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+const DIGEST_REFERENCE = /^[a-z0-9][a-z0-9._/-]*(:[A-Za-z0-9._-]+)?@sha256:[0-9a-f]{64}$/;
 
-function validate({ copy, cacheId, buildSource, stageDir }) {
+function validate({ copy, cacheId, buildSource, stageDir, base }) {
+  if (!DIGEST_REFERENCE.test(base ?? '')) throw new Error(`--base must be an image reference pinned by digest (<ref>@sha256:<64 hex>), got "${base}"`);
   for (const directory of [...(copy ?? []), stageDir]) {
     if (!DIRECTORY.test(directory) || directory.startsWith('/') || directory.split('/').includes('..')) {
       throw new Error(`"${directory}" is not a repository-relative directory`);
@@ -33,12 +36,7 @@ export function renderPrebuiltDockerignore({ stageDir = DEFAULT_STAGE_DIR } = {}
   return `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` — DO NOT EDIT.
 # Local build output stays out of the context; the staged outputs carry dist and node_modules/.prisma paths, so they are re-included LAST.
 .git
-**/node_modules
-**/dist
-**/.turbo
-**/coverage
-**/*.tsbuildinfo
-**/*.log
+${[...IGNORED_DIRECTORIES.map((d) => `**/${d}`), ...IGNORED_FILE_PATTERNS.map((p) => `**/${p}`)].join('\n')}
 !${stageDir}/**
 `;
 }
@@ -176,11 +174,12 @@ export function renderPrebuiltDockerfile({
   buildSource,
   usesToken,
   stageDir = DEFAULT_STAGE_DIR,
+  base,
   exec,
   prodPackages = [],
 }) {
   if (typeof usesToken !== 'boolean') throw new Error('usesToken must be a boolean derived from .npmrc');
-  validate({ copy, cacheId, buildSource, stageDir });
+  validate({ copy, cacheId, buildSource, stageDir, base });
   const toolingVersion = toolVersion();
   const workspaceFile = join(root, 'pnpm-workspace.yaml');
   const built = existsSync(workspaceFile) ? onlyBuiltDependencies(readFileSync(workspaceFile, 'utf8')) : [];
@@ -203,7 +202,7 @@ export function renderPrebuiltDockerfile({
     : '';
   const copies = [...new Set(copy.map((d) => posix.normalize(`${d}/`)))].map(copyLine).join('\n');
   const manifestSources = closure.map((directory) => `${directory}/package.json`);
-  const assembleSources = [...closure, ...manifests];
+  const assembleSources = [...closure.flatMap((directory) => packageSources({ root, directory })), ...manifests];
   const imageCopy = posix.normalize(`${imageDir}/`);
   const text = `# @generated by \`xema-composed-image dockerfile --prebuilt --write\` (@xemahq/repo-build-tooling@${toolingVersion}) — DO NOT EDIT.
 # Re-render with the same options; \`--check\` refuses a stale file (and a stale Dockerfile.dockerignore).
@@ -247,9 +246,8 @@ export function renderPrebuiltDockerfile({
 FROM scratch AS xema-pnpm
 FROM scratch AS xema-pnpm-store
 
-FROM ${NODE_BASE} AS base
+FROM ${base} AS base
 RUN corepack enable && \\
-    apt-get update && apt-get install -y --no-install-recommends openssl wget && rm -rf /var/lib/apt/lists/* && \\
     pnpm config set store-dir /root/.pnpm-store
 
 FROM base AS deps

package/src/composed-image-prebuilt-dockerfile.test.mjs

@@ -5,7 +5,7 @@ import test from 'node:test';
 
 import { depsCopyDirs, memberProdPackages, onlyBuiltDependencies, renderPrebuiltDockerfile, renderPrebuiltDockerignore, syncPrebuiltDockerfile } from './composed-image-prebuilt-dockerfile.mjs';
 import { parseArguments } from './composed-image.mjs';
-import { CLOSURE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
+import { BASE, CLOSURE, fakePnpm, workspace } from './composed-image-fixture.test.mjs';
 
 /** An installed package directory for the prod-closure listing: `{ name, dir }`. */
 function installed(root, name, { gyp = false, optional = {} } = {}) {
@@ -17,7 +17,7 @@ function installed(root, name, { gyp = false, optional = {} } = {}) {
 }
 
 function options(root, extra = {}) {
-  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', usesToken: true, exec: fakePnpm(root), prodPackages: [], ...extra };
+  return { root, copy: ['tooling/dev'], cacheId: 'alpha-composed-process', buildSource: 'alpha', base: BASE, usesToken: true, exec: fakePnpm(root), prodPackages: [], ...extra };
 }
 
 test('the closure comes from pnpm ls with the members filters, and the filters are literal per member', () => {
@@ -39,7 +39,7 @@ test('one COPY --parents per kind: manifests in deps, package dirs (and biome ma
   assert.equal(dockerfile.match(/^COPY --parents/gm).length, 2);
   const [deps, assemble] = dockerfile.split('FROM deps AS assemble');
   assert.match(deps, /COPY tooling\/dev\/ \.\/tooling\/dev\/\nCOPY --parents \\\n {4}biomes\/alpha\/api\/alpha-api\/package\.json \\\n {4}biomes\/alpha\/api\/alpha-db-api\/package\.json \\\n {4}packages\/sdks\/lib-a\/package\.json \\\n {4}\.\/\n/);
-  assert.match(assemble, /COPY --parents \\\n {4}biomes\/alpha\/api\/alpha-api \\\n {4}biomes\/alpha\/api\/alpha-db-api \\\n {4}packages\/sdks\/lib-a \\\n {4}biomes\/alpha\/xema-biome\.json \\\n {4}\.\/\n/);
+  assert.match(assemble, /COPY --parents \\\n {4}biomes\/alpha\/api\/alpha-api\/package\.json \\\n {4}biomes\/alpha\/api\/alpha-db-api\/package\.json \\\n {4}biomes\/alpha\/api\/alpha-db-api\/prisma \\\n {4}packages\/sdks\/lib-a\/package\.json \\\n {4}packages\/sdks\/lib-a\/assets\/data\.json \\\n {4}biomes\/alpha\/xema-biome\.json \\\n {4}\.\/\n/);
   assert.match(assemble, /COPY infra\/composed-process\/ \.\/infra\/composed-process\/\nCOPY \.xema-stage\/out\/ \.\/\n/);
 });
 
@@ -77,6 +77,8 @@ test('--write writes both files; --check refuses either stale, and a closure cha
   const targets = syncPrebuiltDockerfile({ mode: 'write', ...options(root) });
   assert.deepEqual(targets, ['infra/composed-process/Dockerfile', 'infra/composed-process/Dockerfile.dockerignore']);
   syncPrebuiltDockerfile({ mode: 'check', ...options(root) });
+  fs.mkdirSync(path.join(root, 'packages/sdks/lib-b'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'packages/sdks/lib-b/package.json'), JSON.stringify({ name: '@t/lib-b', files: ['dist'] }));
   assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root, { exec: fakePnpm(root, [...CLOSURE, 'packages/sdks/lib-b']) }) }), /Dockerfile is stale/);
   fs.appendFileSync(path.join(root, 'infra/composed-process/Dockerfile.dockerignore'), 'x\n');
   assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root) }), /Dockerfile\.dockerignore is stale/);
@@ -199,3 +201,35 @@ test('the Prisma schema engine step renders in deps only when the prod closure c
   const custom = renderPrebuiltDockerfile(options(root, { stageDir: 'build/stage', prodPackages: [installed(root, 'prisma')] })).dockerfile;
   assert.match(custom, /--mount=type=bind,source=build\/stage\/prisma-engines,target=\/xema-prisma-engines/);
 });
+
+test('FROM is the digest-pinned base, and the base RUN installs no OS package', () => {
+  const { dockerfile } = renderPrebuiltDockerfile(options(workspace()));
+  assert.match(dockerfile, new RegExp(`^FROM ${BASE} AS base\\nRUN corepack enable && \\\\\\n {4}pnpm config set store-dir /root/\\.pnpm-store\\n`, 'm'));
+  assert.doesNotMatch(dockerfile, /apt-get|node:22-bookworm/);
+  for (const base of [undefined, 'ghcr.io/example/base/node-runtime', 'ghcr.io/example/base/node-runtime:1', `x@sha256:${'a'.repeat(63)}`]) {
+    assert.throws(() => renderPrebuiltDockerfile(options(workspace(), { base })), /--base must be an image reference pinned by digest/);
+  }
+});
+
+test('the assemble COPY lists per package only package.json and the files entries, never README or tests', () => {
+  const assemble = renderPrebuiltDockerfile(options(workspace())).dockerfile.split('FROM deps AS assemble')[1].split('COPY infra/')[0];
+  assert.doesNotMatch(assemble, /README|\.test\.|\/src\b/);
+  assert.doesNotMatch(assemble, /alpha-api \\\n/, 'a package directory is never copied whole');
+  assert.doesNotMatch(assemble, /\/dist\b/, 'built output arrives from the stage dir');
+});
+
+test('a package with no files field or a glob entry is refused', () => {
+  const root = workspace();
+  fs.writeFileSync(path.join(root, 'packages/sdks/lib-a/package.json'), JSON.stringify({ name: '@t/lib-a' }));
+  assert.throws(() => renderPrebuiltDockerfile(options(root)), /packages\/sdks\/lib-a\/package\.json has no "files" field/);
+  fs.writeFileSync(path.join(root, 'packages/sdks/lib-a/package.json'), JSON.stringify({ name: '@t/lib-a', files: ['lib/**'] }));
+  assert.throws(() => renderPrebuiltDockerfile(options(root)), /glob/);
+});
+
+test('--check fails when the rendered base or a files entry changed', () => {
+  const root = workspace();
+  syncPrebuiltDockerfile({ mode: 'write', ...options(root) });
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root, { base: `other/base@sha256:${'b'.repeat(64)}` }) }), /Dockerfile is stale/);
+  fs.writeFileSync(path.join(root, 'packages/sdks/lib-a/package.json'), JSON.stringify({ name: '@t/lib-a', files: ['dist', 'assets/data.json', 'extra'] }));
+  assert.throws(() => syncPrebuiltDockerfile({ mode: 'check', ...options(root) }), /Dockerfile is stale/);
+});

package/src/composed-image.mjs

@@ -72,7 +72,7 @@
 //   dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>
 //            render `<image-dir>/Dockerfile` from the package's template
 //            (`composed-image-dockerfile.mjs`).
-//   dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]
+//   dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> [--copy <dir>]… [--stage-dir <dir>]
 //            render the Dockerfile that ASSEMBLES the image from `stage` output, and its
 //            `Dockerfile.dockerignore` (`composed-image-prebuilt-dockerfile.mjs`).
 //
@@ -328,11 +328,11 @@ const USAGE =
   '  load-image <image>\n' +
   '  smoke-refusal <image> [--member <biomeId>/<componentKey>]x2\n' +
   '  dockerfile --write|--check --copy <dir>… --cache-id <id> --build-source <repo>\n' +
-  '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> [--copy <dir>]… [--stage-dir <dir>]';
+  '  dockerfile --prebuilt --write|--check --cache-id <id> --build-source <repo> --base <ref@sha256:…> [--copy <dir>]… [--stage-dir <dir>]';
 
 const REPEATABLE = new Set(['manifests', 'copy', 'member', 'output', 'also', 'subject']);
 const BOOLEAN = new Set(['prebuilt', 'each']);
-const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source',
+const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source', 'base',
   'image-name', 'service', 'cache-id', 'copy', 'member', 'stage-dir', 'output', 'also', 'subject',
 ]);
 
@@ -453,6 +453,7 @@ export function main(argv, { log = console.log, write = (text) => process.stdout
           cacheId: options['cache-id'],
           buildSource: options['build-source'],
           stageDir: options['stage-dir'],
+          base: options.base,
         });
         log(`composed prebuilt Dockerfile ${targets.join(', ')} ${options.mode === 'write' ? 'written' : 'current'}`);
         return;

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);
+  });
+});