changebook 0.4.5 → 0.4.6

package/dist/context.js

@@ -0,0 +1,162 @@
+/**
+ * `changebook context [dir]` — prints the FRESH atlas brief to stdout as a
+ * Claude Code SessionStart hook payload
+ * (`hookSpecificOutput.additionalContext`). Wired by `changebook init` into
+ * `.claude/settings.json` (with the user's consent), it pushes the map into
+ * the agent's context at turn 0 of EVERY session — headless included — so the
+ * brief stops being a tool the agent must remember to call and stops being a
+ * file that can go stale between commits: it is generated on the spot, per
+ * session.
+ *
+ * FAIL-OPEN, ABSOLUTE. This runs on the critical path of opening a session.
+ * Every failure mode — logged out, offline, no project, or merely slow — must
+ * print NOTHING and exit 0. A broken or slow atlas can never block or delay a
+ * user's session start. The whole body races a short timeout; on timeout or
+ * any throw, we emit nothing.
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+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;
+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.
+    if (!db.hasCredentials())
+        return null;
+    const targetDir = path.resolve(dir);
+    const { section, projectId } = await fetchBriefSection(db, targetDir);
+    if (!section)
+        return null;
+    // Drift line vs local HEAD: the anti-staleness signal. The brief itself is
+    // fresh (built now), but this tells the agent how far the working tree has
+    // moved past the last analyzed commit. Best-effort — never blocks the brief.
+    let drift = null;
+    if (projectId) {
+        try {
+            const latest = await db.rest(`changelog?select=commit_hash,hash_aliases&commit_hash=not.is.null&order=created_at.desc&limit=1&project_id=eq.${projectId}`);
+            const candidatos = [
+                latest[0]?.commit_hash ?? null,
+                ...commitAliasesShort(latest[0]?.hash_aliases),
+            ];
+            for (const c of candidatos) {
+                drift = await derivaContraHead(targetDir, c);
+                if (drift)
+                    break;
+            }
+        }
+        catch {
+            drift = null;
+        }
+    }
+    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";
+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 readSettings(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {}; // missing file → empty settings
+    }
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null; // unparseable → caller must refuse, never clobber
+    }
+}
+export function contextHookInstalled(dir) {
+    const s = readSettings(settingsPath(dir));
+    return Boolean(s?.hooks?.SessionStart?.some(groupHasMarker));
+}
+export function installContextHook(dir) {
+    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))
+        return "already";
+    sessionStart.push({
+        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+    return "installed";
+}
+export function uninstallContextHook(dir) {
+    const file = settingsPath(dir);
+    const settings = readSettings(file);
+    if (!settings || !settings.hooks?.SessionStart)
+        return "absent";
+    const before = settings.hooks.SessionStart;
+    // 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)),
+    }))
+        .filter((g) => (g.hooks ?? []).length > 0);
+    if (after.length === before.length && before.every((g) => !groupHasMarker(g))) {
+        return "absent";
+    }
+    if (after.length > 0)
+        settings.hooks.SessionStart = after;
+    else
+        delete settings.hooks.SessionStart;
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+    return "removed";
+}
+export async function printContext(db, dir) {
+    try {
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), CONTEXT_TIMEOUT_MS));
+        const additionalContext = await Promise.race([
+            buildPayload(db, dir),
+            timeout,
+        ]);
+        if (!additionalContext)
+            return;
+        // The SessionStart contract: stdout JSON whose additionalContext is
+        // injected into the agent's context. Anything else on stdout would be
+        // treated as context too, so we emit ONLY this object.
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "SessionStart",
+                additionalContext,
+            },
+        }));
+    }
+    catch {
+        // Swallow everything: opening a session must never fail because of us.
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/index.js

@@ -20,6 +20,7 @@ import { runGuard } from "./guard.js";
 import { hookStatus, installHook, uninstallHook } from "./hook.js";
 import { importHistory } from "./import.js";
 import { registerAgents } from "./init.js";
+import { contextHookInstalled, installContextHook, printContext, uninstallContextHook, } from "./context.js";
 import { login } from "./login.js";
 import { AUTH_HELP, Supabase } from "./supabase.js";
 import { syncContextFiles } from "./sync.js";
@@ -45,6 +46,11 @@ Usage:
   changebook guard [dir]    Check staged files against open atlas alerts
                           (what the pre-commit hook runs; exit 3 = block)
   changebook sync [dir]     Refresh the product map inside CLAUDE.md/AGENTS.md
+  changebook context [dir]  Print the fresh atlas brief as a Claude Code
+                          SessionStart hook payload (used by the push hook)
+  changebook hook-context install|uninstall|status [dir]
+                          Push the atlas into EVERY Claude Code session at turn 0
+                          via a SessionStart hook in .claude/settings.json
   changebook init [dir]     login + register MCP in every agent found + hook + sync
   changebook open           Open the web atlas in the browser
   changebook serve          Run the MCP server on stdio (default with no arguments)
@@ -179,6 +185,34 @@ async function main() {
             await syncContextFiles(db, arg ?? process.cwd());
             return;
         }
+        case "context": {
+            // Runs on the SessionStart critical path: NEVER requireCredentials (it
+            // would exit 1), NEVER print help. printContext fails open — logged out,
+            // offline or slow all resolve to zero output and exit 0.
+            await printContext(new Supabase(), arg ?? process.cwd());
+            return;
+        }
+        case "hook-context": {
+            const dir = process.argv[4] ?? process.cwd();
+            if (arg === "install") {
+                const r = installContextHook(dir);
+                console.error(r === "installed"
+                    ? `✓ SessionStart hook installed (${dir}/.claude/settings.json). Every Claude Code session now opens with the fresh atlas map.`
+                    : "SessionStart hook already installed.");
+            }
+            else if (arg === "uninstall") {
+                const r = uninstallContextHook(dir);
+                console.error(r === "removed"
+                    ? "✓ SessionStart hook removed."
+                    : "No ChangeBook SessionStart hook found.");
+            }
+            else {
+                console.error(contextHookInstalled(dir)
+                    ? `✓ ChangeBook SessionStart hook installed (${dir}/.claude/settings.json).`
+                    : "✗ No ChangeBook SessionStart hook. Install with: changebook hook-context install");
+            }
+            return;
+        }
         case "init": {
             let db = new Supabase();
             if (!db.hasCredentials()) {
@@ -197,6 +231,14 @@ async function main() {
                 console.error(error instanceof Error ? error.message : String(error));
             }
             await syncContextFiles(db, dir);
+            // Ofrecer el push, NUNCA instalarlo en silencio: .claude/settings.json se
+            // suele commitear y compartir, y meter un hook en el arranque de sesiones
+            // ajenas sin permiso explícito no se hace. Se ofrece el comando; correrlo
+            // ES el consentimiento.
+            if (!contextHookInstalled(dir)) {
+                console.error("\nOptional: push the atlas into EVERY Claude Code session at turn 0 " +
+                    "(no tool call needed, never stale):\n  changebook hook-context install");
+            }
             console.error(`✓ Ready. Ask your agent about the atlas, or open ${atlasWebUrl()}`);
             return;
         }

package/dist/sync.js

@@ -53,18 +53,21 @@ const MIN_PAIR_RATE = 0.6;
 // Same window/limit the web uses for the signals strip.
 const ALERT_WINDOW_DAYS = 14;
 const MAX_ALERTS = 3;
-export async function syncContextFiles(db, targetDir, opts = {}) {
+/**
+ * Trae del atlas los datos del bloque y los destila con buildSection, SIN
+ * escribir nada. Es el corazón compartido de `sync` (que lo escribe en
+ * CLAUDE.md/AGENTS.md) y de `context` (que lo empuja por stdout al hook
+ * SessionStart). Misma frontera por proyecto estricta que sync: proyecto que
+ * no casa → bloque vacío, jamás el de otro.
+ */
+export async function fetchBriefSection(db, targetDir) {
     const projectName = projectNameFor(targetDir);
-    // Frontera por proyecto también aquí (QA 2026-07-18): sin filtro, una
-    // cuenta con varios proyectos construiría el mapa de ESTE repo mezclando
-    // los datos de todos. Y si el proyecto aún no existe en el atlas, el mapa
-    // debe salir VACÍO — jamás el de otro proyecto.
+    // Frontera por proyecto (QA 2026-07-18): sin filtro, una cuenta con varios
+    // proyectos construiría el mapa de ESTE repo mezclando los datos de todos.
+    // Y si el proyecto aún no existe en el atlas, el mapa debe salir VACÍO.
     let projectFilter;
     let projectResolved = true;
     try {
-        // strict: el respaldo de proyecto único (0.4.2) es para tools que
-        // conversan con un agente; sync escribe este archivo en silencio y no
-        // puede adivinar — si el nombre no casa, mapa vacío y punto.
         projectFilter = await db.projectFilterFor(projectName, { strict: true });
     }
     catch {
@@ -78,19 +81,10 @@ export async function syncContextFiles(db, targetDir, opts = {}) {
             projectFilter),
         db.rest(`changelog?select=business_impact,created_at&order=created_at.desc&limit=${MAX_CHANGES}` +
             projectFilter),
-        // AI-detected regression warnings: best-effort — an error (older schema,
-        // RLS hiccup) must not block the sync of the rest of the map.
         db
-            .rest(
-        // resolved_at=is.null: a dismissed/auto-resolved alert inside the
-        // window must not resurface in every agent session as urgent.
-        `regression_alerts?select=module,plain,created_at&created_at=gte.${since}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}` +
+            .rest(`regression_alerts?select=module,plain,created_at&created_at=gte.${since}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}` +
             projectFilter)
             .catch(() => []),
-        // Auto-remediación fase 2: los encargos pendientes entran en el bloque
-        // para que CUALQUIER sesión arranque sabiéndolos y se ofrezca a atacarlos
-        // (proponer, no ejecutar — la aprobación sigue siendo del humano).
-        // Best-effort como las alertas.
         projectResolved && projectId
             ? db
                 .callRpc('list_agent_tasks', {
@@ -101,6 +95,10 @@ export async function syncContextFiles(db, targetDir, opts = {}) {
             : Promise.resolve([]),
     ]);
     const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks);
+    return { section, projectId, projectResolved };
+}
+export async function syncContextFiles(db, targetDir, opts = {}) {
+    const { section, projectId, projectResolved } = await fetchBriefSection(db, targetDir);
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const file = path.join(targetDir, name);
         const updated = await upsertSection(file, section, opts);

package/dist/tools.js

@@ -138,6 +138,13 @@ export function commitLabel(hash, aliasesRaw) {
     const aliases = commitAliasesShort(aliasesRaw);
     return aliases.length > 0 ? `${corto} (=${aliases.join(",")})` : corto;
 }
+export const FILE_COMMITS_CAP = 5;
+export function recentCommitsForFile(changelogIds, commitById, cap = FILE_COMMITS_CAP) {
+    const all = changelogIds
+        .map((id) => commitById.get(id))
+        .filter((c) => Boolean(c));
+    return { commits: all.slice(0, cap), more: Math.max(0, all.length - cap) };
+}
 // Consultation metering (never billing): each successful read leaves a row in
 // atlas_reads so the web can show "your agent consulted the atlas N times".
 // Best-effort and non-blocking — metering must never break or slow a read.
@@ -616,7 +623,7 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
     });
     server.registerTool("atlas_file_context", {
         title: "Context of the files you are about to edit",
-        description: `Everything the atlas knows about specific FILES: which module each belongs to, its risk, open regression alerts on those modules, how often they changed recently, and the CURRENT value of watched config constants (with the commit it comes from — no need to re-read the file for those).
+        description: `Everything the atlas knows about specific FILES: which module each belongs to, its risk, open regression alerts on those modules, how often they changed recently, the recent commits that touched each file (cite these instead of running git log), and the CURRENT value of watched config constants (with the commit it comes from — no need to re-read the file for those).
 
 Call this BEFORE editing a file — one cheap call instead of re-reading the code and its git history.
 
@@ -624,7 +631,7 @@ Args:
   - files (required): 1-8 repo-relative paths.
   - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
-Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_changed, last_note }], open_alerts, watched_values: [{ name, value, commit }] }] }`,
+Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_changed, last_note }], open_alerts, recent_commits: [{ commit, commit_aliases, date }], recent_commits_more, watched_values: [{ name, value, commit }] }] }`,
         inputSchema: {
             files: z.array(z.string().min(1).max(300)).min(1).max(8)
                 .describe("Repo-relative paths you are about to edit"),
@@ -643,10 +650,18 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             const pf = await db.projectFilterFor(project);
             const paths = [...new Set(files.map(normalizeRepoPath).filter(Boolean))];
             const perFile = await Promise.all(paths.map(async (file) => {
-                const rows = await db.rest(`change_module?select=module,risk,note,created_at&${fileContainsFilter(file)}&order=created_at.desc&limit=20` +
+                const rows = await db.rest(`change_module?select=changelog_id,module,risk,note,created_at&${fileContainsFilter(file)}&order=created_at.desc&limit=20` +
                     pf);
                 const byModule = new Map();
+                // Commits que tocaron ESTE archivo, del más nuevo al más viejo,
+                // deduplicados (un mismo análisis puede traer varias filas de
+                // change_module para el mismo archivo). El hash lo resuelve la
+                // consulta batcheada de abajo; aquí solo se guarda el orden.
+                const changelogIds = [];
                 for (const row of rows) {
+                    if (!changelogIds.includes(row.changelog_id)) {
+                        changelogIds.push(row.changelog_id);
+                    }
                     const name = (row.module ?? "").trim();
                     if (!name)
                         continue;
@@ -663,11 +678,38 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                         });
                     }
                 }
-                return { file, modules: [...byModule.values()] };
+                return { file, modules: [...byModule.values()], changelogIds };
             }));
             const moduleNames = [
                 ...new Set(perFile.flatMap((f) => f.modules.map((m) => m.module))),
             ];
+            // Commits recientes por archivo (T2: el agente que va a editar dejaba
+            // de necesitar `git log -- <archivo>`). UNA consulta batcheada para
+            // TODOS los archivos, no una por archivo: es la tool que corre antes
+            // de cada edición. hash_aliases entra por el espejo post-squash — el
+            // hash servido tiene que existir en el main del consultante.
+            const allChangelogIds = [
+                ...new Set(perFile.flatMap((f) => f.changelogIds)),
+            ];
+            const commitById = new Map();
+            if (allChangelogIds.length > 0) {
+                const commitRows = await db
+                    .rest(`changelog?select=id,commit_hash,created_at,hash_aliases&id=in.(${allChangelogIds.join(",")})`)
+                    .catch(() => []);
+                for (const r of commitRows) {
+                    if (!r.commit_hash)
+                        continue;
+                    commitById.set(r.id, {
+                        commit: r.commit_hash.slice(0, 7),
+                        commit_aliases: commitAliasesShort(r.hash_aliases),
+                        date: day(r.created_at),
+                    });
+                }
+            }
+            const commitsByFile = new Map();
+            for (const f of perFile) {
+                commitsByFile.set(f.file, recentCommitsForFile(f.changelogIds, commitById));
+            }
             const [alerts, watched] = await Promise.all([
                 moduleNames.length
                     ? db.rest(`regression_alerts?select=module,plain,evidence_symbol,evidence_expect&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(moduleNames))})&order=created_at.desc&limit=10` +
@@ -752,6 +794,13 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                             ? ` (as of commit ${w.commit_hash.slice(0, 7)})`
                             : ""));
                 }
+                // Commits recientes que tocaron este archivo: cita estos hashes en
+                // vez de correr `git log -- <archivo>`.
+                const rc = commitsByFile.get(f.file);
+                if (rc && rc.commits.length > 0) {
+                    const parts = rc.commits.map((c) => `${c.commit}${c.commit_aliases.length ? ` (=${c.commit_aliases.join(",")})` : ""} (${c.date})`);
+                    lines.push(`- Recent commits: ${parts.join(", ")}${rc.more > 0 ? ` (+${rc.more} more)` : ""}`);
+                }
                 lines.push("");
             }
             if (!ancla)
@@ -761,7 +810,7 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             // descripción lo prometía y solo viajaba en el texto (bug cazado por
             // el verificador adversarial del benchmark).
             const salida = toolResult(contextText, {
-                files: perFile.map((f) => ({
+                files: perFile.map(({ changelogIds: _drop, ...f }) => ({
                     ...f,
                     open_alerts: f.modules.flatMap((m) => (alertsByModule.get(m.module) ?? []).map((plain) => ({
                         module: m.module,
@@ -772,6 +821,8 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                         value: w.value,
                         commit: w.commit_hash?.slice(0, 7) ?? null,
                     })),
+                    recent_commits: commitsByFile.get(f.file)?.commits ?? [],
+                    recent_commits_more: commitsByFile.get(f.file)?.more ?? 0,
                 })),
             });
             recordRead(db, "atlas_file_context", pf, servedCharsOf(salida), Date.now() - t0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "mcpName": "io.github.raulbr90/changebook",
   "description": "ChangeBook for coding agents: MCP server (product memory for Claude Code/Codex) + CLI to sign in, analyze changes and sync the product map.",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.raulbr90/changebook",
   "description": "Query your product's living memory: module map + analyzed change history. Read-only MCP tools.",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.4.5",
+      "version": "0.4.6",
       "transport": {
         "type": "stdio"
       }