changebook 0.2.0

package/dist/supabase.js

@@ -0,0 +1,218 @@
+/**
+ * Minimal Supabase client for the ChangeBook MCP server.
+ *
+ * Talks to PostgREST directly with the user's JWT so Row Level Security scopes
+ * every query to the signed-in user. Refreshes the access token with the
+ * refresh token when needed (refresh does not require a captcha).
+ */
+import { loadCredentials, saveCredentials } from "./credentials.js";
+// Public defaults — the anon key is the same public key the web app ships.
+const DEFAULT_URL = "https://oyosihxkecspjkiligga.supabase.co";
+const DEFAULT_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im95b3NpaHhrZWNzcGpraWxpZ2dhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODMwMDYyNTUsImV4cCI6MjA5ODU4MjI1NX0.TU-UK1DToHmLHp9q7QEQ5eAa7V3sq3HtgCxPEa-DvDE";
+export const AUTH_HELP = `No ChangeBook session configured. Run:
+
+  changebook login
+
+It opens https://changebook.app in your browser, you click Authorize, and the
+session is stored in ~/.changebook/credentials.json.
+
+Alternative (CI / headless): set the CHANGEBOOK_REFRESH_TOKEN environment
+variable (and optionally CHANGEBOOK_ACCESS_TOKEN). To extract it manually, sign
+in at https://changebook.app, open the browser console and run:
+
+  JSON.parse(localStorage.getItem(Object.keys(localStorage).find(k => k.endsWith("-auth-token")))).refresh_token`;
+export class SupabaseError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class Supabase {
+    url;
+    anonKey;
+    accessToken;
+    refreshToken;
+    projectEnv;
+    projectFilterCache;
+    // In-flight refresh, shared by concurrent callers (single-flight).
+    refreshing;
+    // True when the tokens came from ~/.changebook/credentials.json: rotated
+    // refresh tokens must be written back there or the stored one goes stale.
+    persistRotation = false;
+    constructor(env = process.env) {
+        this.url = (env.CHANGEBOOK_SUPABASE_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+        this.anonKey = env.CHANGEBOOK_SUPABASE_ANON_KEY ?? DEFAULT_ANON_KEY;
+        this.accessToken = env.CHANGEBOOK_ACCESS_TOKEN?.trim() || undefined;
+        this.refreshToken = env.CHANGEBOOK_REFRESH_TOKEN?.trim() || undefined;
+        this.projectEnv = env.CHANGEBOOK_PROJECT?.trim() || undefined;
+        // Env vars belong to the caller's config and win; the credentials file
+        // written by `changebook login` is the fallback.
+        if (!this.accessToken && !this.refreshToken) {
+            const stored = loadCredentials();
+            if (stored) {
+                this.refreshToken = stored.refresh_token;
+                this.accessToken = stored.access_token;
+                this.persistRotation = true;
+            }
+        }
+    }
+    hasCredentials() {
+        return Boolean(this.accessToken || this.refreshToken);
+    }
+    /**
+     * PostgREST fragment scoping atlas queries to the CHANGEBOOK_PROJECT env var
+     * (matched by slug, then by exact name). Empty when unset, which queries
+     * across all of the account's projects — same behavior as before projects
+     * existed. Resolved once per process.
+     */
+    async projectFilter() {
+        if (this.projectFilterCache !== undefined)
+            return this.projectFilterCache;
+        if (!this.projectEnv) {
+            this.projectFilterCache = "";
+            return this.projectFilterCache;
+        }
+        const v = encodeURIComponent(this.projectEnv);
+        let rows = await this.rest(`projects?select=id&slug=eq.${v}&limit=1`);
+        if (rows.length === 0) {
+            rows = await this.rest(`projects?select=id&name=eq.${v}&limit=1`);
+        }
+        if (rows.length === 0) {
+            throw new SupabaseError(`No ChangeBook project matches CHANGEBOOK_PROJECT="${this.projectEnv}" (by slug or name). Unset it to query all projects.`, 404);
+        }
+        this.projectFilterCache = `&project_id=eq.${rows[0].id}`;
+        return this.projectFilterCache;
+    }
+    /** GET a PostgREST path (e.g. "changelog?select=...") as the signed-in user. */
+    async rest(pathWithQuery) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.restOnce(pathWithQuery);
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.restOnce(pathWithQuery);
+        }
+        if (!res.ok) {
+            const body = (await res.text()).slice(0, 300);
+            if (res.status === 401) {
+                throw new SupabaseError(`Session expired and could not be refreshed. ${AUTH_HELP}`, 401);
+            }
+            throw new SupabaseError(`Supabase request failed (${res.status}): ${body}`, res.status);
+        }
+        return (await res.json());
+    }
+    restOnce(pathWithQuery) {
+        return fetch(`${this.url}/rest/v1/${pathWithQuery}`, {
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                Accept: "application/json",
+            },
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    refresh() {
+        // Single-flight: two concurrent tool calls that both hit 401 must share one
+        // refresh, or the second spends an already-rotated token and Supabase's
+        // reuse detection can revoke the whole family.
+        this.refreshing ??= this.doRefresh().finally(() => {
+            this.refreshing = undefined;
+        });
+        return this.refreshing;
+    }
+    async doRefresh() {
+        // The credentials file is shared across processes (the MCP server, the
+        // post-commit hook, a second editor window). Any of them may have rotated
+        // the token since we loaded it, so pick up the freshest one on disk before
+        // spending ours — otherwise we replay a stale token and get logged out.
+        if (this.persistRotation) {
+            const stored = loadCredentials();
+            if (stored?.refresh_token)
+                this.refreshToken = stored.refresh_token;
+        }
+        if (!this.refreshToken) {
+            throw new SupabaseError(`Session expired. ${AUTH_HELP}`, 401);
+        }
+        let res = await this.refreshOnce(this.refreshToken);
+        // If the refresh was rejected and the session came from disk, another
+        // process may have rotated the token in the tiny window since we read it;
+        // reload once and retry with the newest before giving up.
+        if (!res.ok && this.persistRotation) {
+            const stored = loadCredentials();
+            if (stored?.refresh_token && stored.refresh_token !== this.refreshToken) {
+                this.refreshToken = stored.refresh_token;
+                res = await this.refreshOnce(this.refreshToken);
+            }
+        }
+        if (!res.ok) {
+            const body = (await res.text()).slice(0, 300);
+            throw new SupabaseError(`Could not refresh the ChangeBook session (${res.status}): ${body}\n\n${AUTH_HELP}`, res.status);
+        }
+        const data = (await res.json());
+        this.accessToken = data.access_token;
+        // Supabase rotates refresh tokens; keep the newest one for this process
+        // and, when the session came from `changebook login`, persist it on disk.
+        if (data.refresh_token)
+            this.refreshToken = data.refresh_token;
+        if (this.persistRotation && this.refreshToken) {
+            try {
+                saveCredentials({
+                    refresh_token: this.refreshToken,
+                    access_token: this.accessToken,
+                });
+            }
+            catch {
+                // Non-fatal: the in-memory session still works for this process.
+            }
+        }
+    }
+    refreshOnce(refreshToken) {
+        return fetch(`${this.url}/auth/v1/token?grant_type=refresh_token`, {
+            method: "POST",
+            headers: { apikey: this.anonKey, "Content-Type": "application/json" },
+            body: JSON.stringify({ refresh_token: refreshToken }),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    /**
+     * POST a Supabase Edge Function as the signed-in user, refreshing the
+     * access token once on 401. Returns status + parsed body so callers can
+     * surface the server's own error messages (quota, waitlist, …).
+     */
+    async invokeFunction(name, payload) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.invokeOnce(name, payload);
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.invokeOnce(name, payload);
+        }
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new SupabaseError(`Edge function ${name} returned a non-JSON response (${res.status}): ${text.slice(0, 200)}`, res.status);
+        }
+        return { status: res.status, body };
+    }
+    invokeOnce(name, payload) {
+        return fetch(`${this.url}/functions/v1/${name}`, {
+            method: "POST",
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(120_000),
+        });
+    }
+}
+//# sourceMappingURL=supabase.js.map

package/dist/sync.js

@@ -0,0 +1,268 @@
+/**
+ * `changebook-mcp sync` — writes/refreshes an auto-generated "product map"
+ * section into the project's CLAUDE.md and AGENTS.md.
+ *
+ * Why: those files are loaded into EVERY agent session (Claude Code reads
+ * CLAUDE.md, Codex reads AGENTS.md) and their stable content is prompt-cached,
+ * so a ~400-token map there orients the agent for near-zero marginal cost —
+ * cheaper than tool calls, paid once per cache window.
+ *
+ * The section lives between markers and is replaced in place; everything
+ * outside the markers is never touched.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const START = "<!-- changebook:start -->";
+const END = "<!-- changebook:end -->";
+// DB text (notes, alert bodies, business impact) is AI-written and gets embedded
+// between the markers that upsertSection splices on. If any of it contained a
+// literal marker, the next sync would splice at the wrong offset and corrupt the
+// file injected into every agent session. Break the HTML-comment opener so no
+// exact marker can be forged; both markers begin with "<!--".
+function sanitizeCell(text) {
+    return text.replace(/<!--/g, "<!- -");
+}
+const MAX_MODULES = 15;
+const MAX_CHANGES = 5;
+const MAX_COUPLINGS = 5;
+// El bloque entra en CADA sesión de agente del usuario, así que tiene un
+// presupuesto fijo (~500 tokens) y nunca crece sin control. Cuando no cabe
+// todo, se recorta por prioridad: regresiones > acoplamientos > hotspots >
+// módulos > últimos cambios.
+const SYNC_BUDGET_CHARS = 2_000;
+// Co-change pair thresholds — same spirit as the web's signals: at least 3
+// shared analyses and a ≥60% rate before we call it a dependency.
+const MIN_PAIR_COUNT = 3;
+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) {
+    const projectFilter = await db.projectFilter();
+    const since = new Date(Date.now() - ALERT_WINDOW_DAYS * 24 * 3600 * 1000).toISOString();
+    const [moduleRows, changes, alerts] = await Promise.all([
+        db.rest("change_module?select=changelog_id,module,domain,risk,files,note,created_at&order=created_at.desc&limit=500" +
+            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(`regression_alerts?select=module,plain,created_at&created_at=gte.${since}&order=created_at.desc&limit=${MAX_ALERTS}` +
+            projectFilter)
+            .catch(() => []),
+    ]);
+    const section = buildSection(moduleRows, changes, alerts);
+    for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+        const file = path.join(targetDir, name);
+        const updated = await upsertSection(file, section);
+        console.error(`${updated} ${name}`);
+    }
+}
+/** Exported for tests. */
+export function buildSection(rows, changes, alerts = []) {
+    // Newest-first rows: the first occurrence of a module is its latest state.
+    const seen = new Map();
+    for (const row of rows) {
+        const existing = seen.get(row.module);
+        if (existing)
+            existing.count += 1;
+        else
+            seen.set(row.module, { ...row, count: 1 });
+    }
+    const modules = [...seen.values()].slice(0, MAX_MODULES);
+    const head = [
+        START,
+        // Sin fecha a propósito: el bloque va al principio del CLAUDE.md/AGENTS.md
+        // del usuario y una fecha que cambia a diario invalidaría el prefijo de
+        // prompt-cache de TODO el archivo en cada sesión del agente. Las fechas
+        // útiles ya van por entrada (regresiones, últimos cambios).
+        "## Mapa del producto (ChangeBook · auto-generado)",
+        "",
+        "Este proyecto tiene memoria en ChangeBook. Antes de explorar código a mano, orienta con las tools MCP: `atlas_modules` (mapa), `atlas_recent_changes` (historia), `atlas_module_detail` (detalle + diffs).",
+        "",
+    ];
+    if (modules.length === 0) {
+        return [
+            ...head,
+            "_Aún no hay módulos analizados. Ejecuta un análisis desde la extensión o importa el historial de git._",
+            END,
+        ].join("\n");
+    }
+    const moduleLines = modules.map((m) => {
+        const files = Array.isArray(m.files)
+            ? m.files.slice(0, 3).map(String).join(", ")
+            : "";
+        const meta = [m.domain, m.risk && `riesgo ${m.risk}`]
+            .filter(Boolean)
+            .join(" · ");
+        const note = sanitizeCell((m.note ?? "").slice(0, 110));
+        return `- **${m.module}**${meta ? ` (${meta})` : ""}${files ? ` — ${files}` : ""}${note ? ` — ${note}` : ""}`;
+    });
+    // Prevention beats detection: give the agent the co-change dependencies
+    // and open warnings BEFORE it edits, not after something breaks.
+    const couplingLines = coChangePairs(rows).map((p) => `- **${p.a}** ↔ **${p.b}** — juntos en el ${Math.round(p.rate * 100)}% de sus cambios`);
+    // AI-detected regressions from the latest analyses: the most urgent thing
+    // an agent can know before editing — a change already broke a coupling.
+    const alertLines = alerts
+        .filter((a) => (a.plain ?? "").trim())
+        .map((a) => {
+        const mod = (a.module ?? "").trim();
+        return `- ${a.created_at.slice(0, 10)}${mod ? ` · **${mod}**` : ""} — ${sanitizeCell((a.plain ?? "").slice(0, 200))}`;
+    });
+    const hotspotLines = modules
+        .filter((m) => m.risk === "hotspot")
+        .slice(0, 5)
+        .map((m) => {
+        const note = sanitizeCell((m.note ?? "").slice(0, 110));
+        return `- **${m.module}** está marcado crítico${note ? ` — ${note}` : ""}`;
+    });
+    const changeLines = changes.map((c) => `- ${c.created_at.slice(0, 10)} — ${sanitizeCell((c.business_impact ?? "").slice(0, 140))}`);
+    // El orden de renderizado (legibilidad) y la prioridad de presupuesto
+    // (utilidad para el agente) son independientes: si no cabe todo, caen
+    // primero los últimos cambios y los módulos, nunca las regresiones.
+    const sections = [
+        { key: "modules", priority: 3, title: "### Módulos", lines: moduleLines },
+        {
+            key: "couplings",
+            priority: 1,
+            title: "### Módulos que cambian juntos (si tocas uno, revisa el otro)",
+            lines: couplingLines,
+        },
+        {
+            key: "alerts",
+            priority: 0,
+            title: "### Regresiones detectadas (resolver o verificar YA)",
+            lines: alertLines,
+        },
+        {
+            key: "hotspots",
+            priority: 2,
+            title: "### Avisos abiertos (revisar antes de modificar)",
+            lines: hotspotLines,
+        },
+        {
+            key: "changes",
+            priority: 4,
+            title: "### Últimos cambios",
+            lines: changeLines,
+        },
+    ];
+    let budget = SYNC_BUDGET_CHARS - head.join("\n").length - END.length;
+    const includedCount = new Map();
+    for (const s of [...sections].sort((a, b) => a.priority - b.priority)) {
+        if (s.lines.length === 0)
+            continue;
+        let cost = s.title.length + 2; // título + línea en blanco separadora
+        let count = 0;
+        for (const line of s.lines) {
+            if (cost + line.length > budget)
+                break;
+            cost += line.length + 1;
+            count += 1;
+        }
+        if (count > 0) {
+            includedCount.set(s.key, count);
+            budget -= cost;
+        }
+    }
+    const lines = [...head];
+    let first = true;
+    for (const s of sections) {
+        const count = includedCount.get(s.key) ?? 0;
+        if (count === 0)
+            continue;
+        if (!first)
+            lines.push("");
+        lines.push(s.title, ...s.lines.slice(0, count));
+        first = false;
+    }
+    lines.push(END);
+    return lines.join("\n");
+}
+/**
+ * Symmetric co-change pairs: modules that appear in the same analyses often
+ * enough that touching one without the other is a regression smell. Rate is
+ * relative to the less frequent module of the pair.
+ */
+// Module labels contain spaces, so pair keys use a separator that cannot
+// appear in a label.
+const PAIR_SEP = "\u0000";
+function coChangePairs(rows) {
+    const byAnalysis = new Map();
+    for (const r of rows) {
+        const label = (r.module ?? "").trim();
+        if (!label)
+            continue;
+        let set = byAnalysis.get(r.changelog_id);
+        if (!set) {
+            set = new Set();
+            byAnalysis.set(r.changelog_id, set);
+        }
+        set.add(label);
+    }
+    const appear = new Map();
+    const together = new Map();
+    for (const set of byAnalysis.values()) {
+        const mods = [...set].sort();
+        for (const m of mods)
+            appear.set(m, (appear.get(m) ?? 0) + 1);
+        for (let i = 0; i < mods.length; i++) {
+            for (let j = i + 1; j < mods.length; j++) {
+                const key = mods[i] + PAIR_SEP + mods[j];
+                together.set(key, (together.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, count] of together) {
+        if (count < MIN_PAIR_COUNT)
+            continue;
+        const [a, b] = key.split(PAIR_SEP);
+        const rate = count / Math.min(appear.get(a) ?? 1, appear.get(b) ?? 1);
+        if (rate >= MIN_PAIR_RATE)
+            pairs.push({ a, b, rate });
+    }
+    return pairs.sort((x, y) => y.rate - x.rate).slice(0, MAX_COUPLINGS);
+}
+/** Exported for tests. */
+export async function upsertSection(file, section) {
+    let content = null;
+    try {
+        content = await readFile(file, "utf8");
+    }
+    catch {
+        content = null;
+    }
+    if (content === null) {
+        await writeFile(file, section + "\n");
+        return "created";
+    }
+    // Migración del renombrado (AppAtlas → ChangeBook): si el archivo aún tiene
+    // el bloque con los marcadores antiguos, elimínalo antes de upsertar el
+    // nuevo — si no, quedarían dos mapas (uno obsoleto) en el mismo archivo.
+    const LEGACY_START = "<!-- appatlas:start -->";
+    const LEGACY_END = "<!-- appatlas:end -->";
+    const legacyStart = content.indexOf(LEGACY_START);
+    const legacyEnd = content.indexOf(LEGACY_END);
+    if (legacyStart !== -1 && legacyEnd !== -1 && legacyEnd > legacyStart) {
+        content = (content.slice(0, legacyStart) +
+            content.slice(legacyEnd + LEGACY_END.length)).replace(/\n{3,}/g, "\n\n");
+        await writeFile(file, content);
+    }
+    const start = content.indexOf(START);
+    const end = content.indexOf(END);
+    if (start !== -1 && end !== -1 && end > start) {
+        const next = content.slice(0, start) + section + content.slice(end + END.length);
+        // Idempotente: si el mapa no cambió, no tocar el archivo — reescribirlo
+        // actualizaría el mtime, ensuciaría git status y podría invalidar cachés.
+        if (next === content)
+            return "unchanged";
+        await writeFile(file, next);
+        return "updated";
+    }
+    const separator = content.endsWith("\n") ? "\n" : "\n\n";
+    await writeFile(file, content + separator + section + "\n");
+    return "appended";
+}
+//# sourceMappingURL=sync.js.map