changebook 0.4.8 → 0.4.10

package/README.md

@@ -50,6 +50,9 @@ your other servers.
 | `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 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 hook-context install\|uninstall\|status [dir]` | Claude Code `SessionStart` hook: pushes the fresh atlas map into **every** session at turn 0 — no tool call to remember, and generated on the spot so it can't go stale. Writes to `.claude/settings.json`; running the command **is** the consent, and it refuses to touch a config it can't parse. |
+| `changebook hook-impact install\|uninstall\|status [dir]` | Claude Code `PreToolUse` hook: **before every edit**, tells the agent which modules depend on the file it is about to touch, plus any open alert and repeat-offender history. Never blocks an edit, never touches the network on the critical path (reads a short-lived cache in `.git/` and refreshes it out of band), warns once per file per session, and stays **silent** when there is nothing to say. |
+| `changebook impact` / `changebook context [dir]` | What those two hooks run. Both read from stdin/disk, print a JSON payload (or nothing) and always exit 0 — you don't call them by hand. |
 | `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. |

package/dist/analyze.js

@@ -6,12 +6,12 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
+import { commitDiff, execFileAsync, FICHEROS_GENERADOS, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, projectNameFor, 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());
-    const projectName = path.basename(cwd);
+    const projectName = projectNameFor(cwd);
     let rawDiff;
     let commitHash;
     let committedAt;
@@ -124,7 +124,9 @@ async function commitMeta(cwd, ref) {
 }
 async function gitDiffHead(cwd) {
     try {
-        const { stdout } = await execFileAsync("git", ["diff", "HEAD", "-U0"], {
+        // Mismos ficheros excluidos que en commitDiff: el atlas no se analiza a sí
+        // mismo (ver FICHEROS_GENERADOS).
+        const { stdout } = await execFileAsync("git", ["diff", "HEAD", "-U0", "--", ...FICHEROS_GENERADOS], {
             cwd,
             encoding: "utf8",
             maxBuffer: GIT_MAX_BUFFER_BYTES,

package/dist/context.js

@@ -28,6 +28,38 @@ import { fetchBriefSection } from "./sync.js";
 import { commitAliasesShort, derivaContraHead } from "./tools.js";
 /** Hard ceiling on the critical path: past this, emit nothing and move on. */
 const CONTEXT_TIMEOUT_MS = 2_000;
+/**
+ * A timeout that can lose the race without punishing the winner.
+ *
+ * The naive form — `new Promise(r => setTimeout(r, ms))` raced against the real
+ * work — has a bug that measurement makes obvious and reading never does: when
+ * the work wins, the timer is still pending, and Node will not exit until it
+ * fires. The process is done and just sits there. Measured 2026-07-26:
+ * `changebook context` took 2.18s wall clock to produce a payload it already had
+ * in ~200ms, on the session-start path, under a doc comment promising it would
+ * "never block it, slow it, or exit non-zero". It had been slowing every session
+ * by two seconds.
+ *
+ * `unref()` is the fix: the timer still fires if anything else is keeping the
+ * loop alive, but it never keeps the loop alive by itself. `cancelar()` is belt
+ * and braces for the long-lived case (the MCP server), where an unref'd timer
+ * would still fire pointlessly.
+ *
+ * Shared by both hooks on purpose. The defect existed independently in two
+ * places, which is the usual sign that the shape — not the instance — was wrong.
+ */
+export function presupuestoDeTiempo(ms) {
+    let cancelar = () => { };
+    const vencido = new Promise((resolve) => {
+        const t = setTimeout(() => resolve(null), ms);
+        t.unref?.();
+        cancelar = () => {
+            clearTimeout(t);
+            resolve(null);
+        };
+    });
+    return { vencido, cancelar };
+}
 async function buildPayload(db, dir) {
     // Logged out → silent no-op. A fresh clone with the hook installed but no
     // session must open exactly as fast as before.
@@ -60,24 +92,20 @@ async function buildPayload(db, dir) {
     }
     return drift ? `${section}\n\n${drift}` : section;
 }
-// ── SessionStart hook install (opt-in, per repo) ─────────────────────────────
-//
-// The push channel lives in `.claude/settings.json` under hooks.SessionStart.
-// Consent is the act of running `changebook hook-context install` (or saying
-// yes to init's offer) — this file is often committed and shared, so we NEVER
-// write it silently and NEVER clobber a config we can't parse.
 // `2>/dev/null || true`: if `changebook` isn't on PATH for some teammate, the
 // shell error is swallowed and the hook exits 0 — a missing binary must not
-// make a session-start hook look failed. printContext already emits only the
-// JSON payload (or nothing) on stdout.
-const HOOK_COMMAND = "changebook context 2>/dev/null || true";
-// Recognisable substring to find/remove our own entry without touching others.
-const HOOK_MARKER = "changebook context";
+// make a hook look failed. Both commands emit only the JSON payload (or
+// nothing) on stdout.
+export const CONTEXT_HOOK = {
+    event: "SessionStart",
+    command: "changebook context 2>/dev/null || true",
+    marker: "changebook context",
+};
 function settingsPath(dir) {
     return path.join(path.resolve(dir), ".claude", "settings.json");
 }
-function groupHasMarker(g) {
-    return (g.hooks ?? []).some((h) => (h.command ?? "").includes(HOOK_MARKER));
+function groupHasMarker(g, marker) {
+    return (g.hooks ?? []).some((h) => (h.command ?? "").includes(marker));
 }
 function readSettings(file) {
     let raw;
@@ -97,53 +125,71 @@ function readSettings(file) {
         return null; // unparseable → caller must refuse, never clobber
     }
 }
-export function contextHookInstalled(dir) {
+export function settingsHookInstalled(dir, spec) {
     const s = readSettings(settingsPath(dir));
-    return Boolean(s?.hooks?.SessionStart?.some(groupHasMarker));
+    return Boolean(s?.hooks?.[spec.event]?.some((g) => groupHasMarker(g, spec.marker)));
 }
-export function installContextHook(dir) {
+export function installSettingsHook(dir, spec) {
     const file = settingsPath(dir);
     const settings = readSettings(file);
     if (settings === null) {
         throw new Error(`Refusing to touch ${file}: it isn't valid JSON. Fix or remove it, then retry.`);
     }
     const hooks = (settings.hooks ??= {});
-    const sessionStart = (hooks.SessionStart ??= []);
-    if (sessionStart.some(groupHasMarker))
+    const list = (hooks[spec.event] ??= []);
+    if (list.some((g) => groupHasMarker(g, spec.marker)))
         return "already";
-    sessionStart.push({
-        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    // El matcher solo se escribe si lo hay: un `matcher` presente y vacío es
+    // "todas las tools" en Claude Code, y en SessionStart no significa nada.
+    // Escribir la clave igualmente dejaría un campo mudo en un archivo que la
+    // gente lee y commitea.
+    list.push({
+        ...(spec.matcher ? { matcher: spec.matcher } : {}),
+        hooks: [{ type: "command", command: spec.command }],
     });
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
     return "installed";
 }
-export function uninstallContextHook(dir) {
+export function uninstallSettingsHook(dir, spec) {
     const file = settingsPath(dir);
     const settings = readSettings(file);
-    if (!settings || !settings.hooks?.SessionStart)
+    if (!settings?.hooks?.[spec.event])
         return "absent";
-    const before = settings.hooks.SessionStart;
+    const before = settings.hooks[spec.event];
     // Drop our command from every group, then drop groups left empty. Foreign
     // hooks in the same group (unusual, but possible) are preserved.
     const after = before
         .map((g) => ({
         ...g,
-        hooks: (g.hooks ?? []).filter((h) => !(h.command ?? "").includes(HOOK_MARKER)),
+        hooks: (g.hooks ?? []).filter((h) => !(h.command ?? "").includes(spec.marker)),
     }))
         .filter((g) => (g.hooks ?? []).length > 0);
-    if (after.length === before.length && before.every((g) => !groupHasMarker(g))) {
+    if (after.length === before.length &&
+        before.every((g) => !groupHasMarker(g, spec.marker))) {
         return "absent";
     }
     if (after.length > 0)
-        settings.hooks.SessionStart = after;
+        settings.hooks[spec.event] = after;
     else
-        delete settings.hooks.SessionStart;
+        delete settings.hooks[spec.event];
     if (Object.keys(settings.hooks).length === 0)
         delete settings.hooks;
     fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
     return "removed";
 }
+// Envoltorios del canal SessionStart. Se mantienen con su nombre porque son la
+// superficie que ya consume index.ts (y, a través de él, `init`): generalizar
+// por dentro no es motivo para renombrar por fuera.
+export function contextHookInstalled(dir) {
+    return settingsHookInstalled(dir, CONTEXT_HOOK);
+}
+export function installContextHook(dir) {
+    return installSettingsHook(dir, CONTEXT_HOOK);
+}
+export function uninstallContextHook(dir) {
+    return uninstallSettingsHook(dir, CONTEXT_HOOK);
+}
 /**
  * The pulse and the brief, composed. Separate from printContext so the WHOLE
  * thing — including the pulse — stays inside the single timeout race: adding
@@ -170,11 +216,12 @@ async function buildSessionContext(db, dir) {
 }
 export async function printContext(db, dir) {
     try {
-        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), CONTEXT_TIMEOUT_MS));
+        const { vencido, cancelar } = presupuestoDeTiempo(CONTEXT_TIMEOUT_MS);
         const additionalContext = await Promise.race([
             buildSessionContext(db, dir),
-            timeout,
+            vencido,
         ]);
+        cancelar();
         if (!additionalContext)
             return;
         // The SessionStart contract: stdout JSON whose additionalContext is

package/dist/credentials.js

@@ -61,6 +61,48 @@ export function clearCredentials() {
         return false;
     }
 }
+const INFLIGHT_FILE = path.join(DIR, "refresh-inflight.json");
+/**
+ * Deja constancia en disco de que ALGUIEN va a gastar el refresh token.
+ *
+ * Supabase lo rota **al recibir la peticion**, asi que entre "sale la peticion"
+ * y "guardamos el token nuevo" hay una ventana en la que el token del disco ya
+ * esta muerto sin que nadie lo sepa. Si el proceso no sobrevive a esa ventana
+ * —el `analyze` post-commit corre desacoplado en segundo plano, y basta con
+ * apagar el equipo o matar la terminal— el siguiente arranque reenvia el viejo,
+ * Supabase lo trata como robo y cierra la sesion.
+ *
+ * Esta marca no PUEDE evitarlo: nada del lado del cliente sobrevive a un
+ * `kill -9`. Lo que evita es que sea inexplicable. Sin ella, el usuario ve
+ * "Invalid Refresh Token: Already Used" y no tiene forma de saber por que; con
+ * ella se le puede decir cuando se quedo a medias la renovacion.
+ */
+export function markRefreshInFlight(now = new Date()) {
+    try {
+        fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(INFLIGHT_FILE, JSON.stringify({ at: now.toISOString(), pid: process.pid }), { mode: 0o600 });
+    }
+    catch {
+        // Es un diagnostico, no una garantia: si no se puede escribir, seguimos.
+    }
+}
+export function clearRefreshInFlight() {
+    try {
+        fs.rmSync(INFLIGHT_FILE, { force: true });
+    }
+    catch {
+        // idem
+    }
+}
+export function readRefreshInFlight() {
+    try {
+        const data = JSON.parse(fs.readFileSync(INFLIGHT_FILE, "utf8"));
+        return typeof data.at === "string" ? data : null;
+    }
+    catch {
+        return null;
+    }
+}
 const LOCK_FILE = path.join(DIR, "refresh.lock");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/git.js

@@ -4,7 +4,7 @@
  * normalization live here — a drift between them would make the same commit
  * compress differently across subcommands and break the server-side dedup.
  */
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import * as path from "node:path";
 import { promisify } from "node:util";
 export const execFileAsync = promisify(execFile);
@@ -60,12 +60,44 @@ export function usableSummary(message) {
     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. */
+/**
+ * Ficheros que ESCRIBE el propio ChangeBook y que por tanto no puede analizar.
+ *
+ * `sync` regenera el bloque del mapa dentro de CLAUDE.md/AGENTS.md, y `analyze`
+ * lo dispara en cada commit. Sin excluirlos se cierra un bucle: commiteas el
+ * mapa regenerado -> el análisis lo ve -> nace/actualiza el módulo "Mapeo de
+ * módulos" -> pasa a ser el más reciente -> el mapa se reordena -> vuelve a
+ * estar sucio. Cuesta un diff de una línea cada dos por tres y el 2026-07-25
+ * costó un conflicto de merge real.
+ *
+ * No es una preferencia de ruido: una herramienta que se mide a sí misma
+ * inventa actividad que no existe. Los 6 "cambios" del módulo del mapa son
+ * exactamente eso.
+ *
+ * Un commit que SOLO toca estos ficheros produce un diff vacío y `analyze` lo
+ * salta con su mensaje de siempre — que es la respuesta correcta: regenerar el
+ * mapa no es un cambio de producto.
+ */
+export const FICHEROS_GENERADOS = [
+    ":(exclude)CLAUDE.md",
+    ":(exclude)AGENTS.md",
+    ":(exclude)**/CLAUDE.md",
+    ":(exclude)**/AGENTS.md",
+];
 export async function commitDiff(cwd, hash) {
     try {
         const { stdout } = await execFileAsync("git", 
         // --end-of-options so a ref that starts with "-" (e.g. "-n5") is treated
         // as a revision, never as a git option (argument injection).
-        ["show", "--pretty=format:", "-U0", "--end-of-options", hash], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
+        [
+            "show",
+            "--pretty=format:",
+            "-U0",
+            "--end-of-options",
+            hash,
+            "--",
+            ...FICHEROS_GENERADOS,
+        ], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
         return stdout;
     }
     catch (error) {
@@ -82,4 +114,47 @@ export function gitErrorMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * El nombre del proyecto al que reportar desde `dir`.
+ *
+ * NACE DE UN FLECO REAL. El 2026-07-25 trabajé en un worktree llamado `seo-wt` y
+ * el atlas creó un proyecto `seo-wt` en la cuenta de Raúl: gastó un análisis y
+ * dejó 4 módulos huérfanos en su selector de proyectos. No fue un bug del
+ * servidor: los cuatro sitios del CLI que deducen el nombre lo sacaban de
+ * `path.basename(cwd)`, y en un worktree eso NO es el nombre del repo.
+ *
+ * Un worktree enlazado es el MISMO repositorio: sus commits van al mismo sitio y
+ * su historia es la misma. Reportar a otro proyecto parte el atlas en dos por un
+ * detalle de cómo tienes montado el disco, y encima en silencio.
+ *
+ * Orden: `CHANGEBOOK_PROJECT` manda siempre (quien quiera un proyecto aparte por
+ * worktree lo dice y ya); si no, el nombre del árbol PRINCIPAL; y si no se puede
+ * averiguar, el basename de siempre.
+ *
+ * Se detecta comparando `--git-dir` con `--git-common-dir`: en el árbol principal
+ * son el mismo; en un worktree enlazado el primero es `.git/worktrees/<nombre>`.
+ */
+export function projectNameFor(dir, env = process.env) {
+    const explicito = env.CHANGEBOOK_PROJECT?.trim();
+    if (explicito)
+        return explicito;
+    const base = path.basename(path.resolve(dir));
+    try {
+        const gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+            cwd: dir, encoding: "utf8", timeout: 5_000,
+        }).trim();
+        const comun = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+            cwd: dir, encoding: "utf8", timeout: 5_000,
+        }).trim();
+        if (!gitDir || !comun || gitDir === comun)
+            return base;
+        // Worktree enlazado: el árbol principal es el padre del git-dir común.
+        const principal = path.basename(path.dirname(comun));
+        return principal || base;
+    }
+    catch {
+        // Sin git, o con una versión que no soporta estas banderas: como siempre.
+        return base;
+    }
+}
 //# sourceMappingURL=git.js.map