changebook 0.3.2 → 0.4.1

package/README.md

@@ -34,7 +34,9 @@ npx changebook init   # login (browser) + register in Claude Code/Codex + sync
 (one Authorize click — no token copy-pasting), registers the MCP server in
 **every coding agent it finds on the machine** — Claude Code, Codex, Cursor,
 Windsurf, Claude Desktop and VS Code (Copilot agent mode) — installs the
-post-commit hook so the atlas updates itself, and writes the product map
+git hooks (post-commit: the atlas updates itself; pre-commit: the signal
+guard warns before touching a module with an open alert), and writes the
+product map
 into the project's `CLAUDE.md`/`AGENTS.md`. It only touches agents that are
 actually installed, and merges into existing MCP configs without clobbering
 your other servers.
@@ -47,7 +49,8 @@ your other servers.
 | `changebook logout` | Forget the stored session. |
 | `changebook analyze [dir]` | Analyze the repo's uncommitted changes (`git diff HEAD`) and update the atlas — same pipeline as the VS Code extension, no editor needed. |
 | `changebook analyze --commit [ref]` | Analyze one commit. Deduped by hash server-side, so re-runs never bill. |
-| `changebook hook install\|uninstall\|status [dir]` | Git post-commit hook: every new commit is analyzed in the background (never blocks the commit). One hook covers Claude Code, Codex and manual commits — they all commit through git. |
+| `changebook hook install\|uninstall\|status [dir]` | Git hooks: every new commit is analyzed in the background (post-commit, never blocks), and the signal guard warns before you commit to a module with an open alert (pre-commit). One pair of hooks covers Claude Code, Codex and manual commits — they all commit through git. |
+| `changebook guard [dir]` | What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; `CHANGEBOOK_GUARD=block` makes findings abort the commit (bypass once with `git commit --no-verify`), `CHANGEBOOK_GUARD=off` silences it. |
 | `changebook sync [dir]` | Refresh the product map inside `CLAUDE.md`/`AGENTS.md`. |
 | `changebook init [dir]` | login + register MCP server + install hook + sync, in one go. |
 | `changebook open` | Open the web atlas in the browser. |

package/dist/analyze.js

@@ -6,7 +6,8 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, } from "./git.js";
+import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
+import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI, truncateAtFileBoundary } from "./optimize.js";
 export async function analyze(db, options = {}) {
     const cwd = path.resolve(options.dir ?? process.cwd());
@@ -14,10 +15,16 @@ export async function analyze(db, options = {}) {
     let rawDiff;
     let commitHash;
     let committedAt;
+    // El mensaje del commit como resumen: enruta al modelo pequeño en el servidor
+    // (~3 veces más barato). Este es el camino del hook post-commit, o sea el que
+    // dispara en CADA commit, así que es donde más veces se cobra la diferencia.
+    // Analizando cambios sin commitear no hay mensaje todavía: va sin resumen.
+    let agentSummary;
     if (options.commit) {
         const meta = await commitMeta(cwd, options.commit);
         commitHash = meta.hash;
         committedAt = meta.committedAt;
+        agentSummary = usableSummary(meta.message) ?? undefined;
         rawDiff = await commitDiff(cwd, meta.hash);
         if (!rawDiff.trim()) {
             console.error(`Commit ${meta.hash.slice(0, 8)} has no analyzable diff (merge?). Skipped.`);
@@ -46,9 +53,13 @@ export async function analyze(db, options = {}) {
     const { status, body } = await db.invokeFunction("analyze-diff", {
         compressedDiff,
         rawDiffChars: rawDiff.length,
+        // Identidad de contenido calculada sobre el diff CRUDO, antes de
+        // comprimir: es lo único que coincide entre este hook y el webhook.
+        rawContentHash: canonicalDiffHash(rawDiff),
         projectName,
         commitHash,
         committedAt,
+        agentSummary,
     });
     if (status !== 200 || body.error) {
         // The server's messages are user-facing (quota, waitlist…): pass through.
@@ -90,11 +101,22 @@ async function commitMeta(cwd, ref) {
         const { stdout } = await execFileAsync("git", 
         // --end-of-options so a user-supplied ref beginning with "-" is treated as
         // a revision, not as a git option.
-        ["log", "-1", "--pretty=format:%H|%cI", "--end-of-options", ref], { cwd, encoding: "utf8" });
-        const [hash, committedAt] = stdout.trim().split("|");
+        // %B (mensaje entero) va detrás de la fecha a propósito: es el único
+        // campo que puede llevar "|" y saltos de línea, así que se corta por los
+        // DOS primeros separadores y el resto se queda entero. Con -1 no hace
+        // falta -z: solo hay un registro.
+        ["log", "-1", "--pretty=format:%H|%cI|%B", "--end-of-options", ref], { cwd, encoding: "utf8" });
+        const raw = stdout.trim();
+        const firstPipe = raw.indexOf("|");
+        const secondPipe = raw.indexOf("|", firstPipe + 1);
+        const hash = firstPipe < 0 ? raw : raw.slice(0, firstPipe);
         if (!hash)
             throw new Error("empty git log output");
-        return { hash, committedAt };
+        return {
+            hash,
+            committedAt: secondPipe < 0 ? raw.slice(firstPipe + 1) : raw.slice(firstPipe + 1, secondPipe),
+            message: secondPipe < 0 ? "" : raw.slice(secondPipe + 1),
+        };
     }
     catch (error) {
         throw new Error(`Could not resolve commit "${ref}" in "${cwd}": ${gitErrorMessage(error)}`);

package/dist/canonical.js

@@ -0,0 +1,44 @@
+/**
+ * Canonical content hash of a unified diff — mirror of the server's
+ * canonicalDiffContent/canonicalDiffHash in supabase/functions/_shared/
+ * analysis.ts. The npm package must be self-contained, so this is a
+ * deliberate duplicate pinned equal by test/canonicalParity.test.ts: drift
+ * breaks CI, never the dedup.
+ *
+ * Why the CLIENT computes it, on the RAW diff, BEFORE compressing: the CLI
+ * compresses with optimize.ts and the GitHub webhook sends the API patch
+ * as-is, so the texts that reach the server for the SAME change differ and
+ * no server-side hash can reconcile them (visto en vivo 2026-07-18: el
+ * squash de la PR #165 no dedupeó contra el análisis del hook). Only the raw
+ * content, canonicalized, is a stable identity across senders.
+ */
+import { createHash } from 'node:crypto';
+export function canonicalDiffContent(diff) {
+    const out = [];
+    let minusPath = '';
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('--- a/') || line === '--- /dev/null') {
+            minusPath = line === '--- /dev/null' ? '' : line.slice(6).trim();
+            continue;
+        }
+        if (line.startsWith('+++ b/') || line === '+++ /dev/null') {
+            const path = line === '+++ /dev/null' ? minusPath : line.slice(6).trim();
+            out.push(`F:${path}`);
+            continue;
+        }
+        if (line.startsWith('Binary files ')) {
+            out.push(line);
+            continue;
+        }
+        if (line.startsWith('+') || line.startsWith('-'))
+            out.push(line);
+    }
+    return out.join('\n');
+}
+export function canonicalDiffHash(diff) {
+    const canonical = canonicalDiffContent(diff);
+    return createHash('sha256')
+        .update((canonical || diff).replace(/\s+/g, ''))
+        .digest('hex');
+}
+//# sourceMappingURL=canonical.js.map

package/dist/git.js

@@ -11,6 +11,40 @@ export const GIT_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 // Mirror of the extension's default changebook.maxDiffCharacters (the server
 // rejects anything above 60k anyway).
 export const MAX_DIFF_CHARACTERS = 25_000;
+// ── El mensaje de commit como resumen ────────────────────────────────────────
+// El mensaje, cuando dice algo, ES el resumen del cambio: lo escribió quien lo
+// hizo y explica la intención, que es la mitad cara del análisis y la única que
+// el servidor no puede reconstruir del diff. Mandarlo hace que el servidor
+// enrute al modelo pequeño: medido, $0,063 contra $0,021 = 3 veces menos.
+//
+// Vive aquí por lo mismo que commitDiff: lo usan los DOS subcomandos (`analyze`,
+// que es el hook post-commit, e `import`, que es la historia), y tenerlo en uno
+// solo es exactamente el fallo que dejó al otro pagando el modelo caro.
+//
+// Copia deliberada de la del servidor (_shared/github.ts) y de la de la
+// extensión (src/util/summary.ts): los tres artefactos se publican por separado
+// y tienen que ser autocontenidos, igual que canonicalDiffHash.
+// test/summaryParity.test.ts fija que no se separen — si lo hacen no falla
+// nada, solo cambia la factura.
+//
+// Los dos filtros: un mensaje pobre ("fix", "wip") NO se manda, porque el
+// modelo pequeño se APOYA en el resumen y alimentarlo con ruido daría un
+// análisis peor Y más barato; y el largo se recorta por línea entera, porque el
+// servidor RECHAZA los que se pasan y un 400 no encarecería el análisis: lo
+// dejaría sin hacer.
+const MIN_USEFUL_SUMMARY_CHARS = 40;
+const MAX_AGENT_SUMMARY_CHARS = 2_400;
+/** El mensaje si sirve como resumen, recortado por línea entera; si no, null. */
+export function usableSummary(message) {
+    const text = message.trim();
+    if (text.length < MIN_USEFUL_SUMMARY_CHARS)
+        return null;
+    if (text.length <= MAX_AGENT_SUMMARY_CHARS)
+        return text;
+    const cut = text.slice(0, MAX_AGENT_SUMMARY_CHARS);
+    const lastBreak = cut.lastIndexOf("\n");
+    return (lastBreak > MIN_USEFUL_SUMMARY_CHARS ? cut.slice(0, lastBreak) : cut).trim();
+}
 /** `git show <hash> -U0` — the unified diff of a single commit, no context. */
 export async function commitDiff(cwd, hash) {
     try {

package/dist/guard.js

@@ -0,0 +1,276 @@
+/**
+ * `changebook guard` — the pre-commit signal guard. Checks the files staged
+ * for commit against the atlas' open regression alerts and warns when the
+ * commit is about to touch a module with an unresolved alert ("you're editing
+ * something that a previous change already broke").
+ *
+ * Contract with the pre-commit hook (see hook.ts):
+ *   exit 0 — pass (including every failure mode: offline, logged out, no
+ *            project in the atlas… a guard that blocks commits when the
+ *            network is down would get uninstalled the same day)
+ *   exit 3 — findings under CHANGEBOOK_GUARD=block; the hook maps it to a
+ *            failed commit. Any OTHER non-zero exit (node missing, crash)
+ *            deliberately does NOT block.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileAsync } from "./git.js";
+/** Exit code that asks the pre-commit hook to abort the commit. */
+export const EXIT_BLOCK = 3;
+// A commit should never feel slow because of us: whatever the network hasn't
+// answered by then is treated as "no findings".
+const GUARD_TIMEOUT_MS = 3_500;
+// Open alerts move at analysis speed (one per commit at most), so a short
+// cache makes rebases/amend streaks free without risking stale warnings.
+const CACHE_TTL_MS = 5 * 60_000;
+const MAX_ALERTS = 20;
+/**
+ * Same slug the backend derives from the project name (analysis.ts slugify):
+ * the CLI sends `path.basename(cwd)` as projectName and the server slugifies
+ * it, so reproducing that transform is how the guard finds its project row.
+ */
+export function slugifyProject(value) {
+    return value
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "") // strip diacritics left by NFD
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 50);
+}
+/**
+ * PostgREST `in.(...)` list. Module labels are human text ("Perfil y cuenta")
+ * so every value is double-quoted with `"` and `\` escaped — a comma or paren
+ * inside a label must never split the list.
+ */
+export function pgInList(values) {
+    return values
+        .map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`)
+        .join(",");
+}
+/**
+ * change_module rows → the UNION of files each module touched recently. The
+ * union, not the latest row: a module's changes touch different files each
+ * time, and an alerted module's alert applies to ALL of them — matching only
+ * the newest snapshot silently missed real hits (visto en vivo 2026-07-18:
+ * PublicAtlas.tsx pertenece a «Páginas legales» por filas anteriores y el
+ * guardián calló ante su alerta abierta).
+ */
+export function moduleFilesUnion(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const label = (row.module ?? "").trim();
+        if (!label)
+            continue;
+        const set = map.get(label) ?? new Set();
+        if (Array.isArray(row.files)) {
+            for (const f of row.files)
+                set.add(String(f));
+        }
+        map.set(label, set);
+    }
+    return new Map([...map.entries()].map(([k, v]) => [k, [...v]]));
+}
+/** Open alerts × staged files → warnings, deduped by (module, message). */
+export function guardFindings(staged, alerts, filesByModule) {
+    const stagedSet = new Set(staged);
+    const seen = new Set();
+    const findings = [];
+    for (const alert of alerts) {
+        const module = (alert.module ?? "").trim();
+        const plain = (alert.plain ?? "").trim();
+        if (!module || !plain)
+            continue;
+        const touched = (filesByModule.get(module) ?? []).filter((f) => stagedSet.has(f));
+        if (touched.length === 0)
+            continue;
+        const key = module + "\u0000" + plain;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        findings.push({ module, plain, staged: touched });
+    }
+    return findings;
+}
+async function gitPath(dir, name) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", name], { cwd: dir, encoding: "utf8" });
+    return path.resolve(dir, stdout.trim());
+}
+export async function stagedFiles(dir) {
+    // -z: NUL-separated, and crucially git does NOT octal-quote non-ASCII paths
+    // (default quotepath would emit "m\303\263dulo.ts", which never matches the
+    // real UTF-8 path the atlas stores → the alert is silenced). -z also covers
+    // paths with newlines. Product en español: rutas con acentos son plausibles.
+    const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], { cwd: dir, encoding: "utf8" });
+    return stdout.split("\0").filter(Boolean);
+}
+function loadCache(file) {
+    try {
+        const cache = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (Date.now() - cache.fetched_at > CACHE_TTL_MS)
+            return null;
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchSignals(db, dir, env) {
+    const cacheFile = await gitPath(dir, "changebook-guard-cache.json").catch(() => null);
+    const cached = cacheFile ? loadCache(cacheFile) : null;
+    if (cached) {
+        return {
+            alerts: cached.alerts,
+            filesByModule: new Map(Object.entries(cached.files)),
+            projectId: cached.project_id,
+            fromCache: true,
+        };
+    }
+    // Same project the analyze/hook pipeline reports to: CHANGEBOOK_PROJECT
+    // wins, otherwise the directory name, matched by server-side slug first.
+    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const slug = slugifyProject(candidate);
+    let projects = slug
+        ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
+        : [];
+    if (projects.length === 0) {
+        projects = await db.rest(`projects?select=id&name=eq.${encodeURIComponent(candidate)}&limit=1`);
+    }
+    let alerts = [];
+    let filesByModule = new Map();
+    const projectId = projects[0]?.id ?? null;
+    if (projectId) {
+        alerts = await db.rest(`regression_alerts?select=module,plain,created_at&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
+        const modules = [
+            ...new Set(alerts.map((a) => (a.module ?? "").trim()).filter(Boolean)),
+        ];
+        if (modules.length > 0) {
+            const rows = await db.rest(`change_module?select=module,files,created_at&project_id=eq.${projectId}&module=in.(${encodeURIComponent(pgInList(modules))})&order=created_at.desc&limit=200`);
+            filesByModule = moduleFilesUnion(rows);
+        }
+    }
+    if (cacheFile) {
+        const cache = {
+            fetched_at: Date.now(),
+            project_id: projectId,
+            alerts,
+            files: Object.fromEntries(filesByModule),
+        };
+        try {
+            fs.writeFileSync(cacheFile, JSON.stringify(cache));
+        }
+        catch {
+            // Cache is an optimization; a read-only .git dir must not break the guard.
+        }
+    }
+    return { alerts, filesByModule, projectId, fromCache: false };
+}
+/** One-line last-run trace so "why didn't it warn?" is answerable. */
+async function logRun(dir, message) {
+    try {
+        const file = await gitPath(dir, "changebook-guard.log");
+        fs.writeFileSync(file, `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // Best-effort only.
+    }
+}
+/**
+ * El aviso que ve el humano, como texto.
+ *
+ * Se construye aparte de imprimirlo para poder MEDIRLO: es lo que el guardián
+ * sirve de verdad, y su longitud es lo que se registra como chars_served
+ * (QA 2026-07-19). Cadena vacía cuando no hay nada que avisar.
+ */
+export function findingsMessage(findings, block) {
+    if (findings.length === 0)
+        return "";
+    const lines = [
+        `\n⚠ ChangeBook: ${findings.length === 1 ? "an open alert" : `${findings.length} open alerts`} on what you're about to commit:\n`,
+    ];
+    for (const f of findings) {
+        lines.push(`  • ${f.module} — ${f.plain}`);
+        lines.push(`    staged: ${f.staged.slice(0, 5).join(", ")}`);
+    }
+    lines.push(block
+        ? "\nCommit blocked (CHANGEBOOK_GUARD=block). Review the alert in your atlas (changebook open) or bypass once with: git commit --no-verify\n"
+        : "\nReview or dismiss the alert in your atlas: changebook open\n");
+    return lines.join("\n");
+}
+/**
+ * Returns the process exit code. Everything that can go wrong resolves to 0
+ * (pass): the guard informs, it does not gatekeep — except when the user
+ * explicitly opts into CHANGEBOOK_GUARD=block.
+ */
+export async function runGuard(db, dir, env = process.env) {
+    const mode = (env.CHANGEBOOK_GUARD ?? "").trim().toLowerCase();
+    if (mode === "off")
+        return 0;
+    if (!db.hasCredentials())
+        return 0;
+    let staged;
+    try {
+        staged = await stagedFiles(dir);
+    }
+    catch {
+        return 0;
+    }
+    if (staged.length === 0)
+        return 0;
+    let signals;
+    try {
+        signals = await Promise.race([
+            fetchSignals(db, dir, env),
+            new Promise((resolve) => {
+                // The caller process.exit()s right after, so the losing fetch never
+                // holds the commit hostage; unref keeps the timer from doing so either.
+                setTimeout(() => resolve(null), GUARD_TIMEOUT_MS).unref();
+            }),
+        ]);
+    }
+    catch (error) {
+        await logRun(dir, `error: ${error instanceof Error ? error.message.slice(0, 200) : String(error)}`);
+        return 0;
+    }
+    if (signals === null) {
+        await logRun(dir, `timeout after ${GUARD_TIMEOUT_MS}ms — passing`);
+        return 0;
+    }
+    const findings = guardFindings(staged, signals.alerts, signals.filesByModule);
+    const block = mode === "block";
+    const message = findingsMessage(findings, block);
+    // La consulta del guardián también es una consulta del atlas (QA
+    // 2026-07-18: el contador solo veía las tools MCP y el trabajo más
+    // constante del atlas era invisible). Solo las frescas — un rebase servido
+    // de caché no re-consulta nada. Best-effort y ACOTADO: jamás puede
+    // convertir un commit rápido en uno lento.
+    //
+    // chars_served = el aviso que el humano acaba viendo, 0 cuando todo está
+    // limpio (QA 2026-07-19). Antes se registraba siempre 0 y el guardián, que es
+    // el consumidor MÁS frecuente del atlas, no se distinguía de una consulta que
+    // no encontró nada. Con esto "revisó" y "avisó" son dos cosas separables en el
+    // dato, sin inventar ninguna valoración: esos caracteres se sirvieron de
+    // verdad. Lo que el guardián evita de verdad, un error, no se mide en
+    // caracteres y no se intenta.
+    if (!signals.fromCache && signals.projectId) {
+        await Promise.race([
+            db
+                .insertRow("atlas_reads", {
+                project_id: signals.projectId,
+                tool: "guard_precommit",
+                source: "guard",
+                chars_served: message.length,
+            })
+                .catch(() => { }),
+            new Promise((resolve) => {
+                setTimeout(resolve, 800).unref();
+            }),
+        ]);
+    }
+    await logRun(dir, `staged=${staged.length} openAlerts=${signals.alerts.length} findings=${findings.length}`);
+    if (findings.length === 0)
+        return 0;
+    console.error(message);
+    return block ? EXIT_BLOCK : 0;
+}
+//# sourceMappingURL=guard.js.map

package/dist/hook.js

@@ -1,33 +1,77 @@
 /**
- * `changebook hook install|uninstall|status [dir]` — git post-commit hook that
- * analyzes each new commit into the atlas, in the background, without ever
- * blocking the commit. One analysis per commit, deduped server-side by hash,
- * so the cost is bounded and re-runs are free. This one hook covers every
- * client that commits: Claude Code, Codex, the terminal, any editor.
+ * `changebook hook install|uninstall|status [dir]` — the pair of git hooks
+ * that make the atlas live:
+ *
+ *   post-commit  analyzes each new commit into the atlas, in the background,
+ *                without ever blocking the commit. One analysis per commit,
+ *                deduped server-side by hash, so the cost is bounded and
+ *                re-runs are free.
+ *   pre-commit   the signal guard: warns (never blocks, unless the user opts
+ *                into CHANGEBOOK_GUARD=block) when a staged file belongs to a
+ *                module with an open regression alert.
+ *
+ * These two hooks cover every client that commits: Claude Code, Codex, the
+ * terminal, any editor.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileAsync } from "./git.js";
-const MARKER = "# changebook post-commit hook";
-function hookScript() {
-    const entry = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+function cliEntry() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+}
+const POST_COMMIT_MARKER = "# changebook post-commit hook";
+const PRE_COMMIT_MARKER = "# changebook pre-commit guard";
+/** Exported for tests: the contract between this script and guard.ts. */
+export function postCommitScript() {
     // Background subshell + `|| true`: a broken analyze (offline, out of
     // credits, logged out) must never make `git commit` fail or feel slow.
     // The log keeps only the last run so it can't grow unbounded.
     return `#!/bin/sh
-${MARKER} — analyzes each commit into your ChangeBook atlas.
+${POST_COMMIT_MARKER} — analyzes each commit into your ChangeBook atlas.
 # Runs in the background and never blocks the commit. Remove with:
 #   changebook hook uninstall
-( ${JSON.stringify(process.execPath)} ${JSON.stringify(entry)} analyze --commit HEAD > "$(git rev-parse --git-dir)/changebook-hook.log" 2>&1 & ) || true
+( ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} analyze --commit HEAD > "$(git rev-parse --git-dir)/changebook-hook.log" 2>&1 & ) || true
+`;
+}
+/** Exported for tests: the contract between this script and guard.ts. */
+export function preCommitScript() {
+    // Foreground (a warning printed after the commit would be pointless) but
+    // fail-open by exit-code contract: ONLY the guard's deliberate exit 3
+    // (CHANGEBOOK_GUARD=block with findings) aborts the commit. A missing node,
+    // a crash, a network error — any other status — lets the commit through.
+    // The if/elif form is immune to `set -e`: a non-zero guard exit (crash,
+    // node missing, exit 3) is consumed by the condition instead of aborting the
+    // script mid-line. This matters when the line is pasted into a foreign
+    // pre-commit that runs under `set -e` (classic Husky) — only the deliberate
+    // exit 3 must block, never a crash.
+    return `#!/bin/sh
+${PRE_COMMIT_MARKER} — warns when a staged file belongs to a module with an
+# open ChangeBook alert. Warn-only unless CHANGEBOOK_GUARD=block. Remove with:
+#   changebook hook uninstall
+if ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} guard; then :; elif [ $? -eq 3 ]; then exit 1; fi
 `;
 }
-async function hookPath(dir) {
+const HOOKS = [
+    {
+        name: "post-commit",
+        marker: POST_COMMIT_MARKER,
+        script: postCommitScript,
+        installedNote: "Every new commit is analyzed into your atlas in the background (1 credit each; re-runs of the same commit are free).",
+    },
+    {
+        name: "pre-commit",
+        marker: PRE_COMMIT_MARKER,
+        script: preCommitScript,
+        installedNote: "Before each commit, you'll be warned if a staged file belongs to a module with an open alert (set CHANGEBOOK_GUARD=block to make it blocking, =off to silence it).",
+    },
+];
+async function hookPath(dir, name) {
     // --git-path (not --git-dir + "/hooks") resolves core.hooksPath — set by
     // Husky in most modern JS repos to .husky/ — and linked worktrees' common
-    // dir. Building <git-dir>/hooks/post-commit by hand ignores both, so the hook
+    // dir. Building <git-dir>/hooks/<name> by hand ignores both, so the hook
     // installed to a path git never runs and the atlas silently stops updating.
-    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks/post-commit"], {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", `hooks/${name}`], {
         cwd: dir,
         encoding: "utf8",
     }).catch(() => {
@@ -36,34 +80,84 @@ async function hookPath(dir) {
     // The path is relative to `dir`.
     return path.resolve(dir, stdout.trim());
 }
+/** Whether `child` resolves inside `parent` (not the same, actually within). */
+function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Refuse to install into a GLOBAL core.hooksPath. `git config --global
+ * core.hooksPath ~/.git-hooks` (a common setup) makes `--git-path hooks/…`
+ * resolve OUTSIDE this repo, so the post-commit would fire for EVERY repo on
+ * the machine — including private work repos — uploading their diffs and
+ * minting phantom projects. Husky's in-repo .husky/ stays inside the worktree
+ * and is fine; only a hooks dir outside both the worktree and the git-dir is
+ * the dangerous global case.
+ */
+async function assertHookInsideRepo(dir, file) {
+    const run = (args) => execFileAsync("git", args, { cwd: dir, encoding: "utf8" })
+        .then((r) => r.stdout.trim())
+        .catch(() => "");
+    const top = await run(["rev-parse", "--show-toplevel"]);
+    const common = await run(["rev-parse", "--git-common-dir"]);
+    const roots = [top, common && path.resolve(dir, common)].filter(Boolean);
+    if (roots.length > 0 && !roots.some((root) => isInside(root, file))) {
+        throw new Error(`Refusing to install: core.hooksPath points OUTSIDE this repo (${path.dirname(file)}), ` +
+            `so the hook would run for every repo on your machine and upload their diffs. ` +
+            `Install per-repo by unsetting the global hooksPath, or point it at an in-repo dir like .husky/.`);
+    }
+}
 export async function installHook(dir) {
-    const file = await hookPath(dir);
-    if (fs.existsSync(file)) {
-        const current = fs.readFileSync(file, "utf8");
-        if (!current.includes(MARKER)) {
-            throw new Error(`A post-commit hook already exists at ${file} and it isn't ChangeBook's — not overwriting it. Add this line to it manually if you want both:\n\n` +
-                hookScript().split("\n").slice(-2).join("\n"));
+    // Install each hook independently and report the conflicts together at the
+    // end: a foreign pre-commit (Husky, a repo's own guard) must not stop the
+    // post-commit analyzer from being installed, and vice versa.
+    const problems = [];
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        await assertHookInsideRepo(dir, file);
+        if (fs.existsSync(file)) {
+            const current = fs.readFileSync(file, "utf8");
+            if (!current.includes(hook.marker)) {
+                problems.push(`A ${hook.name} hook already exists at ${file} and it isn't ChangeBook's — not overwriting it. Add this to it manually if you want both:\n\n` +
+                    hook.script().split("\n").slice(4).join("\n"));
+                continue;
+            }
         }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, hook.script(), { mode: 0o755 });
+        console.error(`✓ ${hook.name} hook installed (${file}).`);
+        console.error(hook.installedNote);
     }
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, hookScript(), { mode: 0o755 });
-    console.error(`✓ post-commit hook installed (${file}).`);
-    console.error("Every new commit is analyzed into your atlas in the background (1 credit each; re-runs of the same commit are free).");
+    if (problems.length > 0)
+        throw new Error(problems.join("\n\n"));
 }
 export async function uninstallHook(dir) {
-    const file = await hookPath(dir);
-    if (!fs.existsSync(file) || !fs.readFileSync(file, "utf8").includes(MARKER)) {
-        console.error("No ChangeBook post-commit hook found.");
-        return;
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        if (!fs.existsSync(file) ||
+            !fs.readFileSync(file, "utf8").includes(hook.marker)) {
+            console.error(`No ChangeBook ${hook.name} hook found.`);
+            continue;
+        }
+        fs.unlinkSync(file);
+        console.error(`✓ ${hook.name} hook removed.`);
     }
-    fs.unlinkSync(file);
-    console.error("✓ post-commit hook removed.");
 }
 export async function hookStatus(dir) {
-    const file = await hookPath(dir);
-    const installed = fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(MARKER);
-    console.error(installed
-        ? `✓ ChangeBook post-commit hook installed (${file}).`
-        : "No ChangeBook post-commit hook in this repository. Install it with: changebook hook install");
+    let missing = false;
+    for (const hook of HOOKS) {
+        const file = await hookPath(dir, hook.name);
+        const installed = fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(hook.marker);
+        if (installed) {
+            console.error(`✓ ChangeBook ${hook.name} hook installed (${file}).`);
+        }
+        else {
+            missing = true;
+            console.error(`✗ No ChangeBook ${hook.name} hook in this repository.`);
+        }
+    }
+    if (missing) {
+        console.error("Install the missing hooks with: changebook hook install");
+    }
 }
 //# sourceMappingURL=hook.js.map