purecontext-mcp 1.2.0 → 1.5.0

package/dist/server/tools/trace-invocation-chain.js

@@ -0,0 +1,280 @@
+/**
+ * trace-invocation-chain.ts
+ *
+ * MCP tool: trace_invocation_chain
+ *
+ * Trace multi-hop call chains from a start symbol forward through callees,
+ * returning all discovered paths as ordered symbol lists. Useful for questions
+ * like "what execution path leads from this API endpoint to a background worker?"
+ *
+ * Strategy: query-time text scan (same as get_call_hierarchy) — no pre-built
+ * call edges required. Scans symbol source text for `identifier(` patterns and
+ * matches them against all indexed symbols in the repo.
+ *
+ * Cycle detection: back-edges are included as leaf nodes with `cyclic: true`
+ * so the traversal terminates and the caller can see the cycle.
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { getSymbolsByRepo } from '../../core/db/symbol-store.js';
+import { getFileContent } from '../../core/db/file-store.js';
+import { buildMeta } from './_meta.js';
+export const name = 'trace_invocation_chain';
+export const description = 'Trace all call chains from a start symbol forward through its callees, ' +
+    'returning each discovered path as an ordered list of symbols. ' +
+    'Use endHint to truncate chains at a symbol matching a glob pattern ' +
+    '(e.g. "*Worker", "*Service"). ' +
+    'Cycles are detected and annotated with cyclic=true rather than looping. ' +
+    'Useful for multi-hop traces like "route handler → service → background worker". ' +
+    'Use search_symbols to find the symbolId or name of the start symbol first.';
+export const inputSchema = {
+    repoId: z.string().describe('Repository ID returned by index_folder or list_repos'),
+    startSymbol: z
+        .string()
+        .min(1)
+        .describe('Name (or symbolId) of the entry point symbol to start tracing from. ' +
+        'If multiple symbols share the name, all are used as starting points.'),
+    endHint: z
+        .string()
+        .optional()
+        .describe('Glob-style pattern for terminal symbols (e.g. "*Worker", "*Job", "Background*"). ' +
+        'Chains stop when a symbol matching this pattern is found, even before maxDepth. ' +
+        'Supports * as wildcard. When omitted, chains end at leaves (no further callees).'),
+    maxDepth: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Maximum chain depth (default 6)'),
+    maxChains: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe('Maximum number of chains to return (default 50)'),
+    includeDynamicCalls: z
+        .boolean()
+        .optional()
+        .describe('When true, include symbols tagged with frameworkMeta.dynamicDispatch=true ' +
+        '(e.g. method_missing handlers) as potential callees. Default false.'),
+};
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+// Keywords that match `\bword(` but are not function calls.
+const CALL_SKIP = new Set([
+    'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'catch',
+    'finally', 'try', 'new', 'return', 'throw', 'typeof', 'instanceof',
+    'function', 'class', 'import', 'export', 'const', 'let', 'var',
+    'async', 'await', 'yield', 'delete', 'void', 'in', 'of', 'super',
+    'this', 'true', 'false', 'null', 'undefined',
+]);
+/** Callable symbol kinds — only these are expanded as callee targets. */
+const CALLABLE_KINDS = new Set([
+    'function', 'method', 'hook', 'composable', 'route', 'middleware',
+]);
+function extractCallNames(text) {
+    const names = new Set();
+    const re = /\b([A-Za-z_$][\w$]*)\s*\(/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const n = m[1];
+        if (!CALL_SKIP.has(n))
+            names.add(n);
+    }
+    return names;
+}
+/** Glob-style match: only * as wildcard, anchored to full string. */
+function globMatch(pattern, value) {
+    const escaped = pattern.replace(/[$()+.?[\\\]^{|}]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`).test(value);
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, startSymbol, endHint, maxDepth = 6, maxChains = 50, includeDynamicCalls = false, } = args;
+    const db = openDatabase(repoId);
+    try {
+        const repo = getRepo(db, repoId);
+        if (!repo) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: `Repository not found: ${repoId}` }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // ── Load all symbols ─────────────────────────────────────────────────────
+        const allSymbols = getSymbolsByRepo(db, repoId, 1_000_000);
+        // Build name → SymbolRecord[] index (both full name and short name for methods)
+        const byName = new Map();
+        const byId = new Map();
+        for (const sym of allSymbols) {
+            byId.set(sym.id, sym);
+            const names = [sym.name];
+            if (sym.name.includes('.'))
+                names.push(sym.name.split('.').pop());
+            for (const n of names) {
+                const list = byName.get(n) ?? [];
+                list.push(sym);
+                byName.set(n, list);
+            }
+        }
+        // ── Resolve start symbol(s) ──────────────────────────────────────────────
+        // Support both name lookup and direct symbolId
+        let startSymbols;
+        if (byId.has(startSymbol)) {
+            startSymbols = [byId.get(startSymbol)];
+        }
+        else {
+            startSymbols = byName.get(startSymbol) ?? [];
+        }
+        if (startSymbols.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            chains: [],
+                            truncated: false,
+                            error: `Symbol not found: ${startSymbol}`,
+                            _meta: buildMeta({ timingMs: Date.now() - t0 }),
+                        }),
+                    },
+                ],
+            };
+        }
+        // ── File content cache ───────────────────────────────────────────────────
+        const fileCache = new Map();
+        function getContent(filePath) {
+            if (!fileCache.has(filePath)) {
+                fileCache.set(filePath, getFileContent(db, repoId, filePath));
+            }
+            return fileCache.get(filePath) ?? null;
+        }
+        function symbolText(sym) {
+            const buf = getContent(sym.filePath);
+            if (!buf)
+                return '';
+            return buf.slice(sym.startByte, Math.min(sym.endByte, buf.length)).toString('utf8');
+        }
+        /** Direct callees of a symbol (by text scan). */
+        function calleesOf(sym) {
+            const text = symbolText(sym);
+            const callNames = extractCallNames(text);
+            const seen = new Set();
+            const result = [];
+            for (const cname of callNames) {
+                const candidates = byName.get(cname) ?? [];
+                for (const cand of candidates) {
+                    if (cand.id === sym.id)
+                        continue;
+                    if (!CALLABLE_KINDS.has(cand.kind))
+                        continue;
+                    if (!includeDynamicCalls) {
+                        // Skip dynamic dispatch symbols unless explicitly included
+                        const meta = cand.frameworkMeta;
+                        if (meta?.['dynamicDispatch'] === true)
+                            continue;
+                    }
+                    if (!seen.has(cand.id)) {
+                        seen.add(cand.id);
+                        result.push(cand);
+                    }
+                }
+            }
+            return result;
+        }
+        // ── DFS to collect chains ────────────────────────────────────────────────
+        const chains = [];
+        let overallTruncated = false;
+        function toChainNode(sym, cyclic = false) {
+            return {
+                symbolId: sym.id,
+                name: sym.name,
+                kind: sym.kind,
+                filePath: sym.filePath,
+                signature: sym.signature,
+                ...(cyclic ? { cyclic: true } : {}),
+            };
+        }
+        function dfs(sym, currentPath, visitedInPath, depth) {
+            if (chains.length >= maxChains) {
+                overallTruncated = true;
+                return;
+            }
+            // Check if this symbol matches endHint
+            const matchesEnd = endHint ? globMatch(endHint, sym.name) : false;
+            if (matchesEnd) {
+                // Terminal: endHint matched
+                const nodes = [...currentPath.map((s) => toChainNode(s)), toChainNode(sym)];
+                chains.push({ nodes, truncatedByDepth: false, endedAtHint: true });
+                return;
+            }
+            if (depth >= maxDepth) {
+                // Truncated by depth
+                const nodes = [...currentPath, sym].map((s) => toChainNode(s));
+                chains.push({ nodes, truncatedByDepth: true, endedAtHint: false });
+                return;
+            }
+            const callees = calleesOf(sym);
+            if (callees.length === 0) {
+                // Leaf node — emit chain
+                const nodes = [...currentPath, sym].map((s) => toChainNode(s));
+                chains.push({ nodes, truncatedByDepth: false, endedAtHint: false });
+                return;
+            }
+            // Expand callees
+            for (const callee of callees) {
+                if (chains.length >= maxChains) {
+                    overallTruncated = true;
+                    break;
+                }
+                if (visitedInPath.has(callee.id)) {
+                    // Cycle detected — emit current path with cyclic leaf
+                    const nodes = [
+                        ...currentPath.map((s) => toChainNode(s)),
+                        toChainNode(sym),
+                        toChainNode(callee, true),
+                    ];
+                    chains.push({ nodes, truncatedByDepth: false, endedAtHint: false });
+                    continue;
+                }
+                const nextPath = [...currentPath, sym];
+                const nextVisited = new Set(visitedInPath);
+                nextVisited.add(sym.id);
+                dfs(callee, nextPath, nextVisited, depth + 1);
+            }
+        }
+        for (const start of startSymbols) {
+            if (chains.length >= maxChains) {
+                overallTruncated = true;
+                break;
+            }
+            dfs(start, [], new Set([start.id]), 0);
+        }
+        const tokenEstimate = Math.ceil(chains.reduce((sum, c) => sum + c.nodes.reduce((s, n) => s + n.name.length + n.filePath.length + 40, 0), 0) / 4);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        chains,
+                        totalChains: chains.length,
+                        truncated: overallTruncated,
+                        startSymbol,
+                        _tokenEstimate: tokenEstimate,
+                        _meta: buildMeta({ timingMs: Date.now() - t0 }),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=trace-invocation-chain.js.map

package/dist/server/tools/trace-invocation-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-invocation-chain.js","sourceRoot":"","sources":["../../../src/server/tools/trace-invocation-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,MAAM,CAAC,MAAM,IAAI,GAAG,wBAAwB,CAAC;AAE7C,MAAM,CAAC,MAAM,WAAW,GACtB,yEAAyE;IACzE,gEAAgE;IAChE,qEAAqE;IACrE,gCAAgC;IAChC,0EAA0E;IAC1E,kFAAkF;IAClF,4EAA4E,CAAC;AAE/E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACnF,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,sEAAsE;QACtE,sEAAsE,CACvE;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mFAAmF;QACnF,kFAAkF;QAClF,kFAAkF,CACnF;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CAAC,iCAAiC,CAAC;IAC9C,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,iDAAiD,CAAC;IAC9D,mBAAmB,EAAE,CAAC;SACnB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,4EAA4E;QAC5E,qEAAqE,CACtE;CACJ,CAAC;AAsBF,iFAAiF;AAEjF,4DAA4D;AAC5D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO;IAC7D,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY;IAClE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;IAC9D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO;IAChE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW;CAC7C,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY;CAClE,CAAC,CAAC;AAEH,SAAS,gBAAgB,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,EAAE,GAAG,4BAA4B,CAAC;IACxC,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,qEAAqE;AACrE,SAAS,SAAS,CAAC,OAAe,EAAE,KAAa;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnF,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAO7B;IACC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACtB,MAAM,EACJ,MAAM,EACN,WAAW,EACX,OAAO,EACP,QAAQ,GAAG,CAAC,EACZ,SAAS,GAAG,EAAE,EACd,mBAAmB,GAAG,KAAK,GAC5B,GAAG,IAAI,CAAC;IAET,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,yBAAyB,MAAM,EAAE,EAAE,CAAC;qBACnE;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,4EAA4E;QAC5E,MAAM,UAAU,GAAG,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QAE3D,gFAAgF;QAChF,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACtB,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,CAAC;YACnE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACjC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACf,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,+CAA+C;QAC/C,IAAI,YAA4B,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1B,YAAY,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAC/C,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,MAAM,EAAE,EAAE;4BACV,SAAS,EAAE,KAAK;4BAChB,KAAK,EAAE,qBAAqB,WAAW,EAAE;4BACzC,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;yBAChD,CAAC;qBACH;iBACF;aACF,CAAC;QACJ,CAAC;QAED,4EAA4E;QAC5E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;QACnD,SAAS,UAAU,CAAC,QAAgB;YAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;QACzC,CAAC;QAED,SAAS,UAAU,CAAC,GAAiB;YACnC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,CAAC;YACpB,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtF,CAAC;QAED,iDAAiD;QACjD,SAAS,SAAS,CAAC,GAAiB;YAClC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,MAAM,MAAM,GAAmB,EAAE,CAAC;YAElC,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC9B,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC3C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;oBAC9B,IAAI,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE;wBAAE,SAAS;oBACjC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;wBAAE,SAAS;oBAC7C,IAAI,CAAC,mBAAmB,EAAE,CAAC;wBACzB,2DAA2D;wBAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,aAAoD,CAAC;wBACvE,IAAI,IAAI,EAAE,CAAC,iBAAiB,CAAC,KAAK,IAAI;4BAAE,SAAS;oBACnD,CAAC;oBACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;wBACvB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;wBAClB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,4EAA4E;QAC5E,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,IAAI,gBAAgB,GAAG,KAAK,CAAC;QAE7B,SAAS,WAAW,CAAC,GAAiB,EAAE,MAAM,GAAG,KAAK;YACpD,OAAO;gBACL,QAAQ,EAAE,GAAG,CAAC,EAAE;gBAChB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpC,CAAC;QACJ,CAAC;QAED,SAAS,GAAG,CACV,GAAiB,EACjB,WAA2B,EAC3B,aAA0B,EAC1B,KAAa;YAEb,IAAI,MAAM,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;gBAC/B,gBAAgB,GAAG,IAAI,CAAC;gBACxB,OAAO;YACT,CAAC;YAED,uCAAuC;YACvC,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAElE,IAAI,UAAU,EAAE,CAAC;gBACf,4BAA4B;gBAC5B,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC5E,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnE,OAAO;YACT,CAAC;YAED,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;gBACtB,qBAAqB;gBACrB,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC/D,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,OAAO;YACT,CAAC;YAED,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAE/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,yBAAyB;gBACzB,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC/D,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpE,OAAO;YACT,CAAC;YAED,iBAAiB;YACjB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;oBAC/B,gBAAgB,GAAG,IAAI,CAAC;oBACxB,MAAM;gBACR,CAAC;gBAED,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;oBACjC,sDAAsD;oBACtD,MAAM,KAAK,GAAG;wBACZ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;wBACzC,WAAW,CAAC,GAAG,CAAC;wBAChB,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC;qBAC1B,CAAC;oBACF,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;oBACpE,SAAS;gBACX,CAAC;gBAED,MAAM,QAAQ,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC;gBACvC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;gBAC3C,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACxB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,IAAI,MAAM,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;gBAC/B,gBAAgB,GAAG,IAAI,CAAC;gBACxB,MAAM;YACR,CAAC;YACD,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAC7B,MAAM,CAAC,MAAM,CACX,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CACT,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC,CAAC,EAC/E,CAAC,CACF,GAAG,CAAC,CACN,CAAC;QAEF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;wBACE,MAAM;wBACN,WAAW,EAAE,MAAM,CAAC,MAAM;wBAC1B,SAAS,EAAE,gBAAgB;wBAC3B,WAAW;wBACX,cAAc,EAAE,aAAa;wBAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;qBAChD,EACD,IAAI,EACJ,CAAC,CACF;iBACF;aACF;SACF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.2.0";
+export declare const VERSION = "1.5.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '1.2.0';
+export const VERSION = '1.5.0';
 //# sourceMappingURL=version.js.map

package/docs/02-installation.md

@@ -177,43 +177,115 @@ Your API key is issued by your team's PureContext administrator. See [Team Setup
 
 Installing PureContext gives your AI agent access to the tools. Adding the agent instructions tells it *how* to use them efficiently — which tool to pick for each situation, in what order to call them, and what patterns to avoid.
 
-Two instruction files are provided at the repository root:
+Without them, an AI agent given access to PureContext may default to reading entire files (wasting tokens) rather than using `search_symbols`, or may not know to call `list_repos` first to get the `repoId` required by every tool. The instructions encode the correct workflow: check if indexed → search by name or meaning → retrieve source only for what you'll use.
+
+### Recommended: `purecontext-mcp install`
+
+PureContext ships with a multi-IDE installer that writes the workflow rules into the conventions file each tool expects. Run it once inside your project root:
+
+```bash
+npx purecontext-mcp install all
+```
 
-**`AGENT_INSTRUCTIONS_SHORT.md`** — A compact reference (~2 KB). Covers the mandatory first step, the complete tool selection table, the core rules, and the most common usage patterns. Use this for agents with limited system prompt space or when you want minimal overhead.
+This auto-detects which AI tools are configured in the project (by looking for marker files such as `.cursor/`, `.windsurfrules`, `CLAUDE.md`, `.continue/`, etc.) and installs the rules for each.
 
-**`AGENT_INSTRUCTIONS.md`** — The full reference (~15 KB). Adds detailed parameter notes, every usage pattern, known limitations, decision trees, and anti-patterns. Use this when you want the agent to have complete context, especially for complex multi-step workflows.
+When no `--scope` flag is given, the CLI prompts you to choose where to install:
 
-### Adding instructions to Claude Code
+```
+Where should PureContext be installed?
+  1) Local  — this project only
+  2) Global — all projects (user-level config)
+  3) Both
+```
 
-Add the short version to your project's `CLAUDE.md`:
+Pass `--scope` to skip the prompt:
 
 ```bash
-cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+npx purecontext-mcp install all --scope=local    # this project only
+npx purecontext-mcp install all --scope=global   # user-level, all projects
+npx purecontext-mcp install all --scope=both     # both places at once
 ```
 
-Or add the full version if the project is large and complex:
+For a single tool:
 
 ```bash
-cat AGENT_INSTRUCTIONS.md >> CLAUDE.md
+npx purecontext-mcp install cursor --scope=global
+npx purecontext-mcp install windsurf
+npx purecontext-mcp install continue
+# ...etc.
 ```
 
-Claude Code reads `CLAUDE.md` at the start of every session. The instructions become part of every conversation in that project automatically — no need to repeat them.
+Useful flags:
 
-### Adding instructions to Cursor
+```bash
+npx purecontext-mcp install --list           # show detection state, write nothing
+npx purecontext-mcp install all --dry-run    # preview which writers would run
+```
 
-Paste the contents of `AGENT_INSTRUCTIONS_SHORT.md` into your Cursor rules file (`.cursorrules` in the project root, or via Cursor Settings → Rules).
+### Supported tools
 
-### Adding instructions to Windsurf
+| Tool | Local | Global | Notes |
+|------|-------|--------|-------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks | Global registers seven hook events — see [Claude Code hooks](#claude-code-hooks) below. |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` | MDC frontmatter with `alwaysApply: true`. |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` | Marked block appended or replaced in place. |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` | JSON-aware merge; other fields are preserved. |
+| `cline` | `.clinerules` | local only | No known global config path. |
+| `roo-code` | `.roo/rules-code.md` | local only | No known global config path. |
+| `vscode` | `.github/copilot-instructions.md` | local only | Picked up by GitHub Copilot in VS Code. |
+| `claude-desktop` | always global | always global | Merges MCP server entry; leaves other servers untouched. |
 
-Paste the contents into your Windsurf workspace memory or rules configuration.
+### Claude Code hooks
 
-### Adding instructions to any other agent
+When you run `npx purecontext-mcp install claude` (or the standalone `npx purecontext-mcp hooks --install`), PureContext registers seven hook events in `~/.claude/settings.json`. Each hook is a CLI-style command — no scripts are copied to `~/.claude/hooks/`; the hook logic lives inside the installed package and updates automatically when you upgrade.
 
-The files are plain Markdown. Paste the contents into whatever system prompt, memory, or rules configuration your agent supports. The short version works well for constrained contexts. The full version is better when you can afford the space.
+| Hook event | Command | What it does |
+|------------|---------|--------------|
+| `PostToolUse` | `hook-posttooluse` | Re-indexes files modified by Edit/Write/MultiEdit |
+| `PreToolUse` | `hook-pretooluse` | Soft edit guard — suggests read tools before editing unread files |
+| `PreCompact` | `hook-precompact` | Injects the list of indexed repos before context is compacted |
+| `WorktreeCreate` | `hook-worktree-create` | Auto-indexes a newly created agent worktree |
+| `WorktreeRemove` | `hook-worktree-remove` | Fires when an agent worktree is removed (reserved for cleanup) |
+| `TaskCompleted` | `hook-taskcompleted` | Post-task diagnostics: complexity hotspots, TODO count, suggested tools |
+| `SubagentStart` | `hook-subagentstart` | Injects a condensed repo orientation for newly spawned subagents |
 
-### What the instructions do
+Running `hooks --install` more than once is safe. It replaces existing PureContext entries (including old `.mjs`-path style entries from versions prior to 1.8.0) while leaving other tools' hooks untouched.
 
-Without them, an AI agent given access to PureContext may default to reading entire files (wasting tokens) rather than using `search_symbols`, or may not know to call `list_repos` first to get the `repoId` required by every tool. The instructions encode the correct workflow: check if indexed → search by name or meaning → retrieve source only for what you'll use.
+To see the current registration status without making changes:
+
+```bash
+npx purecontext-mcp hooks --list
+```
+
+### Idempotency
+
+Every writer is safe to re-run. The Markdown writers wrap their content in HTML comment markers:
+
+```html
+<!-- purecontext-mcp-start -->
+... PureContext workflow rules ...
+<!-- purecontext-mcp-end -->
+```
+
+On re-run, the marked block is replaced in place. Anything outside the markers (your own rules, other tools' rules) is preserved. The JSON writers (`continue`, `claude-desktop`) parse and merge structurally rather than re-emitting the whole file.
+
+### Manual install (if you'd rather paste)
+
+The two source-of-truth files are at the repository root:
+
+- **`AGENT_INSTRUCTIONS_SHORT.md`** — Compact (~2 KB). Mandatory first step, tool selection table, core rules, common usage patterns. Use for agents with limited system prompt space.
+- **`AGENT_INSTRUCTIONS.md`** — Full (~15 KB). Adds parameter notes, every usage pattern, known limitations, decision trees, anti-patterns. Use for complex multi-step workflows.
+
+To use these manually:
+
+```bash
+# Claude Code
+cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+
+# Cursor — paste into .cursorrules or via Cursor Settings → Rules
+# Windsurf — paste into .windsurfrules or workspace memory
+# Anything else — paste into whatever rule/memory config it supports
+```
 
 ---
 

package/docs/05-cli-reference.md

@@ -37,6 +37,95 @@ purecontext-mcp config --check
 purecontext-mcp config
 ```
 
+### `install`
+
+Write PureContext workflow rules into the conventions file each AI tool expects.
+
+```bash
+# Auto-detect installed tools and install rules for all of them
+npx purecontext-mcp install all
+
+# Install for a specific tool
+npx purecontext-mcp install cursor
+npx purecontext-mcp install windsurf
+npx purecontext-mcp install continue
+npx purecontext-mcp install cline
+npx purecontext-mcp install roo-code
+npx purecontext-mcp install vscode
+npx purecontext-mcp install claude
+npx purecontext-mcp install claude-desktop
+```
+
+When no `--scope` flag is given, the CLI prompts interactively:
+
+```
+Where should PureContext be installed?
+  1) Local  — this project only
+  2) Global — all projects (user-level config)
+  3) Both
+```
+
+Pass `--scope` to skip the prompt:
+
+```bash
+npx purecontext-mcp install all --scope=global   # user-level for all IDEs
+npx purecontext-mcp install cursor --scope=both  # project + home dir
+npx purecontext-mcp install all --scope=local    # this project only
+```
+
+Useful flags:
+
+```bash
+npx purecontext-mcp install --list              # show detection state, write nothing
+npx purecontext-mcp install all --dry-run       # preview which writers would run
+npx purecontext-mcp install all --scope=global  # install globally without prompt
+```
+
+**Scope behaviour per tool:**
+
+| Tool | Local | Global |
+|------|-------|--------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` |
+| `cline` | `.clinerules` | local only (no global path) |
+| `roo-code` | `.roo/rules-code.md` | local only (no global path) |
+| `vscode` | `.github/copilot-instructions.md` | local only (no global path) |
+| `claude-desktop` | always global | always global |
+
+All writers are idempotent: re-running updates the marked block in place without touching anything outside it.
+
+### `hooks`
+
+Install or inspect Claude Code hook registrations.
+
+```bash
+# Register all PureContext hooks in ~/.claude/settings.json
+npx purecontext-mcp hooks --install
+
+# List current hook registration status
+npx purecontext-mcp hooks --list
+```
+
+Hooks are registered as CLI commands in `~/.claude/settings.json`. Re-running `--install` is safe — it replaces existing PureContext entries (including any old `.mjs`-path style entries from earlier versions) while leaving other tools' hooks untouched.
+
+### `hook-*` (Claude Code hook handlers)
+
+These are the hook handlers invoked by Claude Code. They are not meant to be called directly; they are registered by `hooks --install` and executed automatically by Claude Code as events fire.
+
+| Command | Hook event | What it does |
+|---------|-----------|--------------|
+| `hook-posttooluse` | `PostToolUse` | Re-indexes files modified by Edit/Write/MultiEdit |
+| `hook-pretooluse` | `PreToolUse` | Soft edit guard — suggests read tools before editing |
+| `hook-precompact` | `PreCompact` | Injects the list of indexed repos before context compaction |
+| `hook-worktree-create` | `WorktreeCreate` | Auto-indexes a newly created agent worktree |
+| `hook-worktree-remove` | `WorktreeRemove` | Fires when an agent worktree is removed (no-op, reserved) |
+| `hook-taskcompleted` | `TaskCompleted` | Post-task diagnostics: complexity hotspots, TODO count, tool suggestions |
+| `hook-subagentstart` | `SubagentStart` | Injects condensed repo orientation for newly spawned subagents |
+
+All handlers read from stdin (the JSON payload Claude Code sends) and write a `systemMessage` JSON object to stdout when they have context to inject. They always exit 0 and never block tool execution.
+
 ### `keys`
 
 Manage API keys for hosted deployments.