memtrace 0.3.33 → 0.3.35

package/lib/claude-integration.js

@@ -0,0 +1,447 @@
+"use strict";
+
+// Claude Code integration for Memtrace.
+//
+// Manages three pieces of user-level Claude Code configuration:
+//
+//   1. ~/.claude/MEMTRACE.md      — durable directive that Claude
+//                                    reads as ambient context. Owned
+//                                    entirely by us. We control the
+//                                    full file content; uninstall
+//                                    removes it cleanly.
+//
+//   2. ~/.claude/CLAUDE.md        — user-authored. We DO NOT
+//                                    overwrite. We append a single
+//                                    sentinel-bracketed breadcrumb
+//                                    line pointing at MEMTRACE.md,
+//                                    only if the file already exists.
+//                                    User edits outside our markers
+//                                    are preserved on uninstall.
+//
+//   3. ~/.claude/settings.json    — JSON. We add hook entries tagged
+//                                    with `_managed_by: "memtrace"`.
+//                                    All other entries pass through
+//                                    untouched. Uninstall walks the
+//                                    hooks arrays and drops only
+//                                    entries with our tag.
+//
+// Pure functions where possible — anything that touches the filesystem
+// is wrapped at the bottom for the install.js / uninstall.js entry
+// points. Pure parts are unit + property tested in
+// `test/claude-integration.test.js`.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+const BLOCK_BEGIN = "<!-- BEGIN MEMTRACE BLOCK · managed by `memtrace install` · remove with `memtrace uninstall` -->";
+const BLOCK_END = "<!-- END MEMTRACE BLOCK -->";
+const BLOCK_VERSION = "0.3.35";
+
+const MEMTRACE_MD_HEADER = `<!-- This file is managed by \`memtrace install\`.
+     User edits here will be overwritten on next install.
+     For your own Claude Code directives, edit CLAUDE.md instead. -->
+`;
+
+const MEMTRACE_MD_BODY = `# Memtrace is active on this machine
+
+For ANY code-discovery question — finding symbols, callers, impacts,
+evolution, "where is", "how does", "what calls", "why does",
+"trace through", "find the function that…" — invoke
+\`mcp__memtrace__find_symbol\` or \`mcp__memtrace__find_code\` FIRST.
+Memtrace returns exact \`file:start_line:end_line\` in one call.
+
+After a search hit, follow up with the graph tools that file/grep can't
+match: \`mcp__memtrace__get_symbol_context\` for callers/callees,
+\`mcp__memtrace__get_impact\` for blast radius,
+\`mcp__memtrace__get_evolution\` for history. Read source ONLY at the
+exact spans Memtrace returned, with a few lines of context.
+
+\`Read\` / \`Grep\` / \`Glob\` remain correct ONLY for:
+
+- Config files (\`.env\`, \`package.json\`, README, raw JSON/YAML/TOML)
+- File-inventory questions ("how many \`*.test.ts\` files exist")
+- Files confirmed outside every indexed repo
+- Reading exact lines you already have from a Memtrace result
+
+If Memtrace returns 0 results, broaden the query or call
+\`mcp__memtrace__list_indexed_repositories\` to confirm scope. Zero
+results, missing language stats, or partial-looking output are NOT
+permission to silently fall back to \`Grep\`.
+
+This file is generated by \`memtrace install\` and removed by
+\`memtrace uninstall\`. Edit CLAUDE.md for your own Claude Code rules
+— that file is not touched (we only append a single breadcrumb line
+pointing here, inside our marker block).
+`;
+
+const CLAUDE_MD_BREADCRUMB_LINES = [
+    BLOCK_BEGIN,
+    `<!-- block-version: ${BLOCK_VERSION} -->`,
+    "> 🧠 Memtrace is installed on this machine. **For code-discovery questions, call \\`mcp__memtrace__find_symbol\\` or \\`mcp__memtrace__find_code\\` BEFORE \\`Read\\` / \\`Grep\\` / \\`Glob\\`** — see [`MEMTRACE.md`](./MEMTRACE.md) for the full rule.",
+    BLOCK_END,
+];
+const CLAUDE_MD_BREADCRUMB = CLAUDE_MD_BREADCRUMB_LINES.join("\n");
+
+const HOOK_MANAGED_TAG = "memtrace";
+
+// ── Pure functions: MEMTRACE.md content ───────────────────────────────
+
+/**
+ * Build the canonical MEMTRACE.md body. Pure.
+ * @returns {string}
+ */
+function buildMemtraceMdContent() {
+    return MEMTRACE_MD_HEADER + "\n" + MEMTRACE_MD_BODY;
+}
+
+// ── Pure functions: CLAUDE.md sentinel-block management ───────────────
+
+/**
+ * Add or refresh the Memtrace breadcrumb block in an existing
+ * CLAUDE.md. Pure — takes current content, returns new content.
+ *
+ * Strict-symmetry design: the bytes WE own are exactly
+ *   `CLAUDE_MD_BREADCRUMB + "\n"`
+ * and we always append them at the very end of the file (or
+ * replace an existing block in place with the same shape). We
+ * never add a leading separator; the user's content is left
+ * byte-identical above us. This makes `apply` and `remove` exact
+ * inverses for any user content (idempotency + round-trip
+ * byte-identity hold).
+ *
+ *   - No existing block: append `CLAUDE_MD_BREADCRUMB + "\n"`.
+ *   - Existing block:    replace the inclusive span
+ *                        BLOCK_BEGIN..BLOCK_END(+optional \n)
+ *                        with `CLAUDE_MD_BREADCRUMB + "\n"`.
+ *
+ * @param {string} existing
+ * @returns {string}
+ */
+function applyClaudeMdBreadcrumb(existing) {
+    const beginIdx = existing.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        return existing + CLAUDE_MD_BREADCRUMB + "\n";
+    }
+    const endIdx = existing.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1) {
+        throw new Error(
+            "CLAUDE.md contains a BEGIN MEMTRACE BLOCK marker without a matching END marker. " +
+            "Repair the file manually or delete the partial block before retrying."
+        );
+    }
+    const blockEnd = endIdx + BLOCK_END.length;
+    const tailNewline = existing.charAt(blockEnd) === "\n" ? 1 : 0;
+    return (
+        existing.slice(0, beginIdx) +
+        CLAUDE_MD_BREADCRUMB + "\n" +
+        existing.slice(blockEnd + tailNewline)
+    );
+}
+
+/**
+ * Remove the Memtrace breadcrumb block from CLAUDE.md content.
+ * Pure. Idempotent. Strict inverse of `applyClaudeMdBreadcrumb`:
+ * removes exactly the bytes apply added, leaving everything else
+ * byte-identical.
+ *
+ * @param {string} existing
+ * @returns {string}
+ */
+function removeClaudeMdBreadcrumb(existing) {
+    const beginIdx = existing.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) return existing;
+    const endIdx = existing.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1) {
+        throw new Error(
+            "CLAUDE.md contains a BEGIN MEMTRACE BLOCK marker without a matching END marker. " +
+            "Repair the file manually before retrying."
+        );
+    }
+    const blockEnd = endIdx + BLOCK_END.length;
+    const tailNewline = existing.charAt(blockEnd) === "\n" ? 1 : 0;
+    return existing.slice(0, beginIdx) + existing.slice(blockEnd + tailNewline);
+}
+
+// ── Pure functions: settings.json hook merge ──────────────────────────
+
+/**
+ * Add Memtrace's hook entries to a parsed settings.json object.
+ * Pure — does NOT touch the filesystem; works on objects.
+ *
+ * The added hook entries carry `_managed_by: "memtrace"` so the
+ * uninstall path can identify and remove only our entries.
+ *
+ * @param {object} settings   parsed contents of settings.json (may be {})
+ * @param {string} hooksDir   absolute directory containing the hook scripts
+ * @returns {object}          new settings object (deep-copied)
+ */
+function applySettingsHooks(settings, hooksDir) {
+    const out = JSON.parse(JSON.stringify(settings || {}));
+    out.hooks = out.hooks || {};
+
+    const userPromptHook = {
+        type: "command",
+        command: path.join(hooksDir, "userprompt-claude.sh"),
+        _managed_by: HOOK_MANAGED_TAG,
+        _hook_kind: "userprompt-advisory",
+    };
+    const postToolHook = {
+        type: "command",
+        command: path.join(hooksDir, "posttool-mcp-telemetry.sh"),
+        _managed_by: HOOK_MANAGED_TAG,
+        _hook_kind: "posttool-mcp-telemetry",
+    };
+
+    // UserPromptSubmit — single matcher-less entry.
+    out.hooks.UserPromptSubmit = mergeHookList(
+        out.hooks.UserPromptSubmit || [],
+        { hooks: [userPromptHook] },
+        userPromptHook,
+    );
+
+    // PostToolUse — matcher narrowed to our MCP tools.
+    out.hooks.PostToolUse = mergeHookList(
+        out.hooks.PostToolUse || [],
+        { matcher: "mcp__memtrace__.*", hooks: [postToolHook] },
+        postToolHook,
+    );
+
+    return out;
+}
+
+/**
+ * Merge our hook into an existing hooks array. If a memtrace-managed
+ * entry already exists in any of the matchers, we update it in place
+ * (keep the surrounding matcher block) instead of duplicating.
+ *
+ * @param {Array} existing
+ * @param {object} ourEntry  shape `{ matcher?, hooks: [...] }`
+ * @param {object} ourHook   the inner hook object (with _managed_by)
+ * @returns {Array}
+ */
+function mergeHookList(existing, ourEntry, ourHook) {
+    const out = existing.map((block) => ({ ...block }));
+    let foundManagedBlock = -1;
+    for (let i = 0; i < out.length; i++) {
+        const block = out[i];
+        if (!block.hooks) continue;
+        const hasOurs = block.hooks.some(
+            (h) => h && h._managed_by === HOOK_MANAGED_TAG && h._hook_kind === ourHook._hook_kind,
+        );
+        if (hasOurs) {
+            foundManagedBlock = i;
+            break;
+        }
+    }
+    if (foundManagedBlock === -1) {
+        // Add our block as a new entry.
+        out.push(ourEntry);
+        return out;
+    }
+    // Replace just our hook entries inside the existing block, keep
+    // any user-added hooks in the same matcher untouched.
+    const block = { ...out[foundManagedBlock] };
+    block.hooks = block.hooks.filter(
+        (h) => !(h && h._managed_by === HOOK_MANAGED_TAG && h._hook_kind === ourHook._hook_kind),
+    );
+    block.hooks.push(ourHook);
+    out[foundManagedBlock] = block;
+    return out;
+}
+
+/**
+ * Remove all memtrace-managed hook entries from a parsed settings.json.
+ * Pure. Walks every hooks event type, drops entries tagged
+ * `_managed_by: "memtrace"`, and prunes empty containers.
+ *
+ * @param {object} settings
+ * @returns {object}
+ */
+function removeSettingsHooks(settings) {
+    const out = JSON.parse(JSON.stringify(settings || {}));
+    if (!out.hooks) return out;
+
+    for (const eventName of Object.keys(out.hooks)) {
+        const blocks = out.hooks[eventName];
+        if (!Array.isArray(blocks)) continue;
+        const cleaned = [];
+        for (const block of blocks) {
+            if (!block || !Array.isArray(block.hooks)) {
+                cleaned.push(block);
+                continue;
+            }
+            const filteredHooks = block.hooks.filter(
+                (h) => !(h && h._managed_by === HOOK_MANAGED_TAG),
+            );
+            if (filteredHooks.length === 0) {
+                // Block was entirely ours — drop it.
+                continue;
+            }
+            cleaned.push({ ...block, hooks: filteredHooks });
+        }
+        if (cleaned.length === 0) {
+            delete out.hooks[eventName];
+        } else {
+            out.hooks[eventName] = cleaned;
+        }
+    }
+    if (out.hooks && Object.keys(out.hooks).length === 0) {
+        delete out.hooks;
+    }
+    return out;
+}
+
+// ── Side-effecting wrappers for the installer entry point ─────────────
+
+/**
+ * Install Memtrace's Claude Code integration: write MEMTRACE.md,
+ * breadcrumb CLAUDE.md if it exists, register hooks in settings.json.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.claudeDir]   default `~/.claude`
+ * @param {string} [opts.hooksDir]    absolute dir where hook scripts live
+ * @returns {object}                  summary `{ wrote: [...], skipped: [...] }`
+ */
+function installToFs(opts = {}) {
+    const claudeDir = opts.claudeDir || path.join(os.homedir(), ".claude");
+    const hooksDir = opts.hooksDir;
+    if (!hooksDir) {
+        throw new Error("installToFs: opts.hooksDir is required (absolute path to hooks/)");
+    }
+
+    const summary = { wrote: [], skipped: [] };
+
+    fs.mkdirSync(claudeDir, { recursive: true });
+
+    // 1. Write MEMTRACE.md (always overwrite — we own this file).
+    const memtraceMdPath = path.join(claudeDir, "MEMTRACE.md");
+    fs.writeFileSync(memtraceMdPath, buildMemtraceMdContent());
+    summary.wrote.push(memtraceMdPath);
+
+    // 2. Breadcrumb in CLAUDE.md (only if file exists; we don't create it).
+    const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, "utf8");
+        const updated = applyClaudeMdBreadcrumb(existing);
+        if (updated !== existing) {
+            fs.writeFileSync(claudeMdPath, updated);
+            summary.wrote.push(claudeMdPath);
+        } else {
+            summary.skipped.push(claudeMdPath + " (already up to date)");
+        }
+    } else {
+        summary.skipped.push(claudeMdPath + " (does not exist; not creating)");
+    }
+
+    // 3. Register hooks in settings.json.
+    const settingsPath = path.join(claudeDir, "settings.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        } catch (e) {
+            throw new Error(
+                `Failed to parse ${settingsPath}: ${e.message}. ` +
+                "Repair manually before retrying."
+            );
+        }
+    }
+    const updated = applySettingsHooks(settings, hooksDir);
+    fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+    summary.wrote.push(settingsPath);
+
+    return summary;
+}
+
+/**
+ * Reverse of installToFs. Removes MEMTRACE.md, removes our
+ * breadcrumb from CLAUDE.md, removes our hooks from settings.json.
+ * Leaves all user-authored content intact.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.claudeDir]   default `~/.claude`
+ * @returns {object}                  summary `{ removed: [...], skipped: [...] }`
+ */
+function uninstallFromFs(opts = {}) {
+    const claudeDir = opts.claudeDir || path.join(os.homedir(), ".claude");
+    const summary = { removed: [], skipped: [] };
+
+    // 1. Remove MEMTRACE.md.
+    const memtraceMdPath = path.join(claudeDir, "MEMTRACE.md");
+    if (fs.existsSync(memtraceMdPath)) {
+        fs.unlinkSync(memtraceMdPath);
+        summary.removed.push(memtraceMdPath);
+    } else {
+        summary.skipped.push(memtraceMdPath + " (not present)");
+    }
+
+    // 2. Strip breadcrumb from CLAUDE.md.
+    const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, "utf8");
+        const updated = removeClaudeMdBreadcrumb(existing);
+        if (updated === "") {
+            // Our breadcrumb was the only content — remove the file.
+            fs.unlinkSync(claudeMdPath);
+            summary.removed.push(claudeMdPath + " (file was empty after cleanup)");
+        } else if (updated !== existing) {
+            fs.writeFileSync(claudeMdPath, updated);
+            summary.removed.push(claudeMdPath + " (breadcrumb removed)");
+        } else {
+            summary.skipped.push(claudeMdPath + " (no memtrace breadcrumb found)");
+        }
+    } else {
+        summary.skipped.push(claudeMdPath + " (not present)");
+    }
+
+    // 3. Strip our hooks from settings.json.
+    const settingsPath = path.join(claudeDir, "settings.json");
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+            const updated = removeSettingsHooks(settings);
+            const before = JSON.stringify(settings);
+            const after = JSON.stringify(updated);
+            if (before !== after) {
+                if (Object.keys(updated).length === 0) {
+                    fs.unlinkSync(settingsPath);
+                    summary.removed.push(settingsPath + " (file was empty after cleanup)");
+                } else {
+                    fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+                    summary.removed.push(settingsPath + " (memtrace hook entries removed)");
+                }
+            } else {
+                summary.skipped.push(settingsPath + " (no memtrace hook entries found)");
+            }
+        } catch (e) {
+            summary.skipped.push(settingsPath + ` (parse error: ${e.message})`);
+        }
+    } else {
+        summary.skipped.push(settingsPath + " (not present)");
+    }
+
+    return summary;
+}
+
+module.exports = {
+    // Constants — exported for tests
+    BLOCK_BEGIN,
+    BLOCK_END,
+    BLOCK_VERSION,
+    HOOK_MANAGED_TAG,
+    CLAUDE_MD_BREADCRUMB,
+
+    // Pure functions
+    buildMemtraceMdContent,
+    applyClaudeMdBreadcrumb,
+    removeClaudeMdBreadcrumb,
+    applySettingsHooks,
+    removeSettingsHooks,
+
+    // Side-effecting entry points
+    installToFs,
+    uninstallFromFs,
+};