changebook 0.2.0

package/dist/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * ChangeBook for coding agents — MCP server (stdio) + CLI.
+ *
+ * MCP mode lets agents (Claude Code, Codex, Cursor…) query the ChangeBook
+ * "product memory" — the module map and analyzed change history stored in
+ * Supabase — instead of re-reading the codebase. All tools are read-only.
+ * The CLI subcommands feed and connect that memory without the VS Code
+ * extension: login, analyze, sync, init, open.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { analyze } from "./analyze.js";
+import { atlasWebUrl, openInBrowser } from "./browser.js";
+import { clearCredentials, credentialsPath } from "./credentials.js";
+import { hookStatus, installHook, uninstallHook } from "./hook.js";
+import { importHistory } from "./import.js";
+import { registerAgents } from "./init.js";
+import { login } from "./login.js";
+import { AUTH_HELP, Supabase } from "./supabase.js";
+import { syncContextFiles } from "./sync.js";
+import { registerTools } from "./tools.js";
+const HELP = `changebook — the ChangeBook product memory, from any terminal
+
+Usage:
+  changebook login          Sign in via the browser (stores ~/.changebook/credentials.json)
+  changebook logout         Forget the stored session
+  changebook analyze [dir]  Analyze uncommitted changes and update the atlas
+  changebook analyze --commit [ref]   Analyze one commit (deduped; used by the git hook)
+  changebook import [dir] [--commits N]
+                          Backfill the last N commits (default 25) via the
+                          Anthropic Batch API — 50% cheaper, non-interactive
+  changebook hook install|uninstall|status [dir]
+                          Git post-commit hook: analyze every new commit automatically
+  changebook sync [dir]     Refresh the product map inside CLAUDE.md/AGENTS.md
+  changebook init [dir]     login + register MCP (Claude Code, Codex) + hook + sync
+  changebook open           Open the web atlas in the browser
+  changebook serve          Run the MCP server on stdio (default with no arguments)
+
+Environment: CHANGEBOOK_REFRESH_TOKEN / CHANGEBOOK_ACCESS_TOKEN override the stored
+session (CI/headless); CHANGEBOOK_PROJECT scopes queries to one project.`;
+function requireCredentials(db) {
+    if (!db.hasCredentials()) {
+        console.error(AUTH_HELP);
+        process.exit(1);
+    }
+}
+async function serve(db) {
+    const server = new McpServer({
+        name: "changebook-mcp-server",
+        version: "0.2.0",
+    });
+    registerTools(server, db);
+    if (!db.hasCredentials()) {
+        // Don't exit: keep serving so the agent gets the actionable message from
+        // the tools themselves, but make the problem visible in the client logs.
+        console.error(AUTH_HELP);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("changebook-mcp-server running on stdio");
+}
+/** `[dir] [--commit [ref]]` in any order → analyze options. */
+function parseAnalyzeArgs(args) {
+    let dir;
+    let commit;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--commit") {
+            commit = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "HEAD";
+        }
+        else if (!args[i].startsWith("--")) {
+            dir = args[i];
+        }
+    }
+    return { dir, commit };
+}
+/** `[dir] [--commits N]` in any order → import options. */
+function parseImportArgs(args) {
+    let dir;
+    let commits;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--commits") {
+            const raw = args[i + 1];
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`--commits needs a positive integer (got "${raw ?? ""}").`);
+            }
+            commits = n;
+            i++;
+        }
+        else if (!args[i].startsWith("--")) {
+            dir = args[i];
+        }
+    }
+    return { dir, commits };
+}
+async function main() {
+    const [command, arg] = process.argv.slice(2);
+    switch (command) {
+        case undefined:
+        case "serve":
+            await serve(new Supabase());
+            return;
+        case "login":
+            await login();
+            return;
+        case "logout":
+            console.error(clearCredentials()
+                ? `✓ Session removed from ${credentialsPath()}`
+                : "No stored session.");
+            return;
+        case "analyze": {
+            const db = new Supabase();
+            requireCredentials(db);
+            await analyze(db, parseAnalyzeArgs(process.argv.slice(3)));
+            return;
+        }
+        case "import": {
+            const db = new Supabase();
+            requireCredentials(db);
+            await importHistory(db, parseImportArgs(process.argv.slice(3)));
+            return;
+        }
+        case "hook": {
+            const dir = process.argv[4] ?? process.cwd();
+            if (arg === "install")
+                await installHook(dir);
+            else if (arg === "uninstall")
+                await uninstallHook(dir);
+            else
+                await hookStatus(dir);
+            return;
+        }
+        case "sync": {
+            const db = new Supabase();
+            requireCredentials(db);
+            await syncContextFiles(db, arg ?? process.cwd());
+            return;
+        }
+        case "init": {
+            let db = new Supabase();
+            if (!db.hasCredentials()) {
+                await login();
+                db = new Supabase(); // pick up the freshly stored credentials
+            }
+            for (const line of await registerAgents())
+                console.error(line);
+            const dir = arg ?? process.cwd();
+            // The living-atlas part: analyze every new commit automatically. Not a
+            // git repo (or a foreign hook already there) → explain and move on.
+            try {
+                await installHook(dir);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+            }
+            await syncContextFiles(db, dir);
+            console.error(`✓ Ready. Ask your agent about the atlas, or open ${atlasWebUrl()}`);
+            return;
+        }
+        case "open": {
+            const url = atlasWebUrl();
+            console.error(url);
+            openInBrowser(url);
+            return;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            console.error(HELP);
+            return;
+        default:
+            console.error(`Unknown command "${command}".\n\n${HELP}`);
+            process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/init.js

@@ -0,0 +1,76 @@
+/**
+ * `changebook init [dir]` — one-command setup for coding agents:
+ *   1. Sign in if needed (browser flow).
+ *   2. Register the MCP server in Claude Code (user scope) and Codex.
+ *   3. Sync the product map into the project's CLAUDE.md / AGENTS.md.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileAsync } from "./git.js";
+/** Absolute invocation of this package's server entry, install-agnostic. */
+function serverCommand() {
+    const entry = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+    return { command: process.execPath, args: [entry, "serve"] };
+}
+export async function registerAgents() {
+    const done = [];
+    const { command, args } = serverCommand();
+    // On Windows `claude` is a .cmd shim: execFile can't launch it without a
+    // shell (Node throws EINVAL since CVE-2024-27980). Run through the shell there
+    // and quote the path arguments so spaces (e.g. "Program Files") survive; the
+    // rest are constant literals, so there's no injection surface.
+    const isWin = process.platform === "win32";
+    const quote = (s) => (isWin ? `"${s}"` : s);
+    // Claude Code: user scope, so every project sees the atlas tools.
+    try {
+        await execFileAsync("claude", [
+            "mcp",
+            "add",
+            "--scope",
+            "user",
+            "changebook",
+            "--",
+            quote(command),
+            ...args.map(quote),
+        ], isWin ? { shell: true } : {});
+        done.push("Claude Code: MCP server registered (user scope).");
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (/already exists/i.test(msg)) {
+            done.push("Claude Code: already configured.");
+        }
+        else if (/ENOENT|not recognized|command not found/i.test(msg)) {
+            done.push("Claude Code: `claude` CLI not found — install it and run `changebook init` again.");
+        }
+        else {
+            done.push(`Claude Code: could not register (${msg.split("\n")[0]}).`);
+        }
+    }
+    // Codex reads ~/.codex/config.toml; append our server if it's not there.
+    const codexDir = path.join(os.homedir(), ".codex");
+    const codexConfig = path.join(codexDir, "config.toml");
+    if (fs.existsSync(codexDir)) {
+        const current = fs.existsSync(codexConfig)
+            ? fs.readFileSync(codexConfig, "utf8")
+            : "";
+        if (current.includes("[mcp_servers.changebook]")) {
+            done.push("Codex: already configured.");
+        }
+        else {
+            const argsToml = args.map((a) => JSON.stringify(a)).join(", ");
+            const block = `\n[mcp_servers.changebook]\n` +
+                `command = ${JSON.stringify(command)}\n` +
+                `args = [${argsToml}]\n`;
+            fs.appendFileSync(codexConfig, block);
+            done.push("Codex: MCP server added to ~/.codex/config.toml.");
+        }
+    }
+    else {
+        done.push("Codex: ~/.codex not found — skipped.");
+    }
+    return done;
+}
+//# sourceMappingURL=init.js.map

package/dist/login.js

@@ -0,0 +1,109 @@
+/**
+ * `changebook login` — browser-based sign-in, no token copy-pasting.
+ *
+ * Flow (loopback, same trust model as the web→editor handoff):
+ *   1. Start an HTTP server on 127.0.0.1 with an ephemeral port.
+ *   2. Open https://changebook.app/?connect=cli&port=<p>&state=<s>. The web
+ *      app (where the user is signed in) shows an explicit Authorize button.
+ *   3. On click it redirects to http://127.0.0.1:<p>/callback with the
+ *      session tokens in the URL fragment — the fragment never leaves the
+ *      machine; a tiny page reads it and POSTs it to this server.
+ *   4. We verify `state`, store the refresh token in ~/.changebook/ and exit.
+ */
+import { randomBytes } from "node:crypto";
+import * as http from "node:http";
+import { atlasWebUrl, openInBrowser } from "./browser.js";
+import { credentialsPath, saveCredentials } from "./credentials.js";
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const CALLBACK_PAGE = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>ChangeBook</title></head>
+<body style="font-family: sans-serif; max-width: 480px; margin: 80px auto; text-align: center;">
+<p id="msg">Conectando…</p>
+<script>
+  const params = new URLSearchParams(window.location.hash.slice(1));
+  const payload = {
+    access_token: params.get("access_token"),
+    refresh_token: params.get("refresh_token"),
+    state: params.get("state"),
+  };
+  history.replaceState(null, "", "/callback"); // drop tokens from the URL bar
+  fetch("/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  }).then((r) => {
+    document.getElementById("msg").textContent = r.ok
+      ? "✓ Sesión conectada. Ya puedes volver al terminal."
+      : "No se pudo completar el login. Vuelve al terminal e inténtalo de nuevo.";
+  });
+</script>
+</body></html>`;
+export async function login() {
+    const state = randomBytes(16).toString("hex");
+    const tokens = await new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            if (req.method === "GET" && req.url?.startsWith("/callback")) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(CALLBACK_PAGE);
+                return;
+            }
+            if (req.method === "POST" && req.url === "/token") {
+                let raw = "";
+                req.on("data", (chunk) => {
+                    raw += chunk;
+                    if (raw.length > 16_384)
+                        req.destroy();
+                });
+                req.on("end", () => {
+                    try {
+                        const data = JSON.parse(raw);
+                        if (data.state !== state) {
+                            res.writeHead(400);
+                            res.end();
+                            return;
+                        }
+                        if (!data.refresh_token) {
+                            res.writeHead(400);
+                            res.end();
+                            return;
+                        }
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end('{"ok":true}');
+                        server.close();
+                        resolve({
+                            access_token: data.access_token ?? undefined,
+                            refresh_token: data.refresh_token,
+                        });
+                    }
+                    catch {
+                        res.writeHead(400);
+                        res.end();
+                    }
+                });
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        });
+        server.on("error", reject);
+        // Loopback only: nothing outside this machine can reach the server.
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("Could not open a loopback port."));
+                return;
+            }
+            const url = `${atlasWebUrl()}/?connect=cli&port=${address.port}&state=${state}`;
+            console.error("Opening your browser to sign in to ChangeBook…");
+            console.error(`If it doesn't open, visit:\n\n  ${url}\n`);
+            openInBrowser(url);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error("Login timed out after 5 minutes. Run `changebook login` again."));
+        }, LOGIN_TIMEOUT_MS).unref();
+    });
+    saveCredentials(tokens);
+    console.error(`✓ Signed in. Session stored in ${credentialsPath()}`);
+}
+//# sourceMappingURL=login.js.map

package/dist/optimize.js

@@ -0,0 +1,193 @@
+/**
+ * Diff compression before sending to the backend — same rules as the VS Code
+ * extension's src/util/optimize.ts (keep both in sync): one block per file
+ * with a stats header, generated files stubbed, comments and blank lines
+ * stripped to cut tokens without losing the actual change.
+ */
+// Per-file budget instead of a global one: without it a single huge file eats
+// the server's 60k cap and crowds out the rest of the commit.
+const PER_FILE_BUDGET_CHARS = 6_000;
+// Generated files are noise for the model (a package-lock.json alone can eat
+// the whole diff budget). They keep only their stats header line.
+const GENERATED_FILE_PATTERNS = [
+    // Dependency lockfiles (yarn.lock, Cargo.lock, etc. end in .lock).
+    /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|bun\.lockb|go\.sum)$/,
+    /\.lock$/,
+    // Build artifacts and vendored dependencies.
+    /(^|\/)(dist|build|out|node_modules|vendor|coverage|__snapshots__|\.next|\.nuxt)\//,
+    // Minified bundles, sourcemaps, test snapshots and vector/base64 assets.
+    /\.min\.(js|css)$/,
+    /\.(map|snap|svg)$/,
+];
+function isGeneratedPath(filePath) {
+    return GENERATED_FILE_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+// Filenames that frequently hold credentials. Redacted so a committed .env or
+// private key is never sent verbatim to the backend / model: keep the
+// `### path (+a/-r)` header, drop the body. Mirrored byte-for-byte in the VS
+// Code extension's src/util/optimize.ts to keep the dedup contract identical.
+const SENSITIVE_FILE_PATTERNS = [
+    /^\.env($|\.)/i,
+    /(^|[._-])secret/i,
+    /(^|[._-])secrets/i,
+    /(^|[._-])credential/i,
+    /(^|[._-])password/i,
+    /serviceaccount/i,
+    /(^|[._-])firebase.*config/i,
+    /(^|[._-])gcp.*key/i,
+    /(^|[._-])aws.*credentials/i,
+    /\.pem$/i,
+    /\.key$/i,
+    /\.pfx$/i,
+    /\.p12$/i,
+    /^id_(rsa|ed25519|ecdsa|dsa)/i,
+];
+function isSensitivePath(filePath) {
+    const slash = filePath.lastIndexOf("/");
+    const base = slash === -1 ? filePath : filePath.slice(slash + 1);
+    return SENSITIVE_FILE_PATTERNS.some((pattern) => pattern.test(base));
+}
+/** The regex pipeline shared by every git-mode chunk. */
+function compressDiffBody(input) {
+    return (input
+        // 1. Git headers and metadata (including the new/deleted/renamed/binary
+        //    file and mode-change lines, which used to leak into the context).
+        .replace(/^(diff --git|index|new file mode|deleted file mode|old mode|new mode|similarity index|dissimilarity index|rename from|rename to|copy from|copy to|Binary files|---|\+\+\+|@@).*$/gm, "")
+        // 2. JS/TS/Java/C line comments
+        .replace(/^[-+ ]?\s*\/\/.*$/gm, "")
+        // 3. JS/TS/Java/C block comments
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        // 4. Python/Ruby line comments
+        .replace(/^[-+ ]?\s*#.*$/gm, "")
+        // 5. Python docstrings (""" or ''')
+        .replace(/("""[\s\S]*?"""|'''[\s\S]*?''')/g, "")
+        // 6. Collapse spaces and tabs
+        .replace(/[ \t]+/g, " ")
+        // 7. Drop now-empty lines
+        .replace(/^\s*$/gm, "")
+        // 8. Collapse consecutive newlines
+        .replace(/\n{2,}/g, "\n")
+        .trim());
+}
+/**
+ * Extracts the file path from a chunk's `diff --git` header, handling git's
+ * QUOTED form for paths with spaces or non-ASCII characters
+ * (`diff --git "a/mi módulo.ts" "b/mi módulo.ts"`, octal-escaped under the
+ * default core.quotepath). Returns null if there's no recognizable header.
+ */
+function parseFilePath(chunk) {
+    const line = chunk.match(/^diff --git .*$/m)?.[0];
+    if (!line)
+        return null;
+    const quoted = line.match(/ "b\/((?:[^"\\]|\\.)*)"\s*$/);
+    if (quoted)
+        return unquoteGitPath(quoted[1]);
+    const idx = line.lastIndexOf(" b/");
+    if (idx !== -1) {
+        const path = line.slice(idx + 3).trim();
+        if (path)
+            return path;
+    }
+    return null;
+}
+/** Reverses git's C-style quoting (octal \NNN bytes, \t \n \" \\). */
+function unquoteGitPath(escaped) {
+    const bytes = [];
+    for (let i = 0; i < escaped.length; i++) {
+        if (escaped[i] !== "\\") {
+            bytes.push(escaped.charCodeAt(i));
+            continue;
+        }
+        const next = escaped[i + 1];
+        const octal = escaped.slice(i + 1, i + 4);
+        if (/^[0-7]{3}$/.test(octal)) {
+            bytes.push(parseInt(octal, 8));
+            i += 3;
+        }
+        else {
+            const map = {
+                t: 9,
+                n: 10,
+                r: 13,
+                '"': 34,
+                "\\": 92,
+            };
+            bytes.push(map[next] ?? next.charCodeAt(0));
+            i += 1;
+        }
+    }
+    try {
+        return new TextDecoder().decode(new Uint8Array(bytes));
+    }
+    catch {
+        return escaped;
+    }
+}
+function countLineChanges(chunk) {
+    let added = 0;
+    let removed = 0;
+    for (const line of chunk.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++"))
+            added += 1;
+        else if (line.startsWith("-") && !line.startsWith("---"))
+            removed += 1;
+    }
+    return { added, removed };
+}
+/**
+ * Truncates a per-file-formatted compressed diff at a FILE boundary (the last
+ * `### ` header at or before `limit`), never mid-header. A blind char slice
+ * would cut a trailing `### path (+a/-r)` header in half, so the server's
+ * extractTouchedFiles would miss those files and the atlas filter would drop
+ * their modules. Falls back to a plain slice if there's no boundary to cut at.
+ */
+export function truncateAtFileBoundary(diff, limit) {
+    if (diff.length <= limit)
+        return diff;
+    const boundary = diff.lastIndexOf("\n### ", limit);
+    if (boundary > 0)
+        return diff.slice(0, boundary);
+    return diff.slice(0, limit);
+}
+export function optimizeTokensForAI(rawInput) {
+    if (!rawInput) {
+        return "";
+    }
+    // Input without git-diff structure (loose patches): flat pipeline.
+    if (!rawInput.includes("diff --git ")) {
+        return compressDiffBody(rawInput);
+    }
+    // One block per file with a `### path (+a/-r)` header. That format is a
+    // CONTRACT with analyze-diff, which extracts the touched files from those
+    // lines to filter the atlas context — changing it means changing the server.
+    const parts = [];
+    for (const chunk of rawInput.split(/^(?=diff --git )/m)) {
+        const filePath = parseFilePath(chunk);
+        if (!filePath) {
+            const body = compressDiffBody(chunk);
+            if (body)
+                parts.push(body);
+            continue;
+        }
+        const { added, removed } = countLineChanges(chunk);
+        const stats = `(+${added}/-${removed})`;
+        if (isSensitivePath(filePath)) {
+            parts.push(`### ${filePath} ${stats} [omitido: archivo sensible]`);
+            continue;
+        }
+        if (isGeneratedPath(filePath)) {
+            parts.push(`### ${filePath} ${stats} [generado, omitido]`);
+            continue;
+        }
+        let body = compressDiffBody(chunk);
+        if (body.length > PER_FILE_BUDGET_CHARS) {
+            const cut = body.lastIndexOf("\n", PER_FILE_BUDGET_CHARS);
+            body =
+                body.slice(0, cut > 0 ? cut : PER_FILE_BUDGET_CHARS) +
+                    "\n[resto del archivo truncado]";
+        }
+        parts.push(body ? `### ${filePath} ${stats}\n${body}` : `### ${filePath} ${stats}`);
+    }
+    return parts.join("\n").trim();
+}
+//# sourceMappingURL=optimize.js.map