graph-indexer 2.1.0 → 3.0.0

package/src/cli/hook.mjs

@@ -0,0 +1,356 @@
+/**
+ * `graph-indexer hook <event>`: agent hooks that put the index into the agent's normal loop.
+ *
+ * Reads the hook payload on stdin (Claude Code's format, which Codex, Copilot CLI, Devin and VS Code
+ * share; Gemini CLI and Cursor tool names are recognised too) and, only when it has something
+ * useful to add, prints the host's "additional context" field:
+ *
+ *   post-tool       after an edit: the edit checker on the edited file (syntax errors introduced,
+ *                   calls that no longer fit a changed signature, removed names still in use);
+ *                   after a search for a definition that did not find it: where it is defined;
+ *                   after a read: the indirection the lines involve, resolved (which override runs,
+ *                   which table entry handles a key, what reaches a method by a built name, what a
+ *                   decorator is — silent when there is none, never repeated in a session);
+ *                   while the agent is crawling (three or more searches and reads since its last
+ *                   edit): after a read, where the names used in the lines it read are defined, and
+ *                   after a grep for a name several definitions share, which definition is which
+ *   session-start   one line saying the index exists (builds it in the background if missing), plus
+ *                   the lookup rules when the repository's instruction files do not carry them
+ *   subagent-start  the line and the lookup rules, for subagents that do not read CLAUDE.md/AGENTS.md
+ *
+ * Staying quiet until the agent is crawling matters: context added to every search made "where is
+ * X" questions dearer in other projects' measurements. Fail-open by design: any error, timeout or
+ * irrelevant input prints nothing and exits 0. Context is phrased as facts.
+ *
+ * A resident process (the MCP server, or `graph-indexer daemon`) answers when one runs for the
+ * repository, with the index already open (src/cli/resident.mjs); otherwise the hook opens the
+ * index itself and starts a daemon for the next calls.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { findRepoRoot, dataDir, DATA_DIR_NAME } from '../util/paths.mjs';
+import { specForPath } from '../parse/languages.mjs';
+
+const MAX_CONTEXT = 1500;
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'edit', 'write', 'apply_patch', 'replace', 'write_file']);
+const GREP_TOOLS = new Set(['Grep', 'grep', 'search_file_content', 'grep_search']);
+const READ_TOOLS = new Set(['Read', 'read_file', 'read', 'view']);
+const SHELL_TOOLS = new Set(['Bash', 'shell', 'Shell', 'run_shell_command', 'exec_command']);
+// navigation calls since the last edit from which the agent counts as crawling
+const CRAWL = 3;
+const DEF_SEARCH = /\b(def|class|function|func|fn|interface|struct|trait|enum|type)\s+(\\?\(?)?\w/;
+const SEARCH_CMD = /(?:^|[|;&(]\s*|\s)(grep|egrep|fgrep|rg|ugrep|ag|ack|git\s+grep)\s+(.*)$/;
+const STOP_IDENTS = new Set(['function', 'return', 'import', 'export', 'const', 'class', 'async', 'await', 'self', 'this', 'true', 'false', 'null', 'None', 'TODO', 'FIXME', 'test', 'error', 'string']);
+
+async function readStdin() {
+    if (process.stdin.isTTY) return {};
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { return {}; }
+}
+
+/** Cursor's own hook events are camelCase (`postToolUse`) and take `additional_context`. */
+const isCursor = (input) => /^[a-z]/.test(input.hook_event_name ?? '') || input.cursor_version != null;
+
+/** What the hook prints for `context` in the calling host's format, or null for nothing. */
+function format(event, context, input = {}, max = MAX_CONTEXT) {
+    if (!context) return null;
+    const text = context.length > max ? context.slice(0, max - 1) + '…' : context;
+    const out = isCursor(input) ? { additional_context: text } : { hookSpecificOutput: { hookEventName: event, additionalContext: text } };
+    return JSON.stringify(out);
+}
+
+/** The text a tool returned, whatever the host's shape (string, Bash {stdout}, Grep {content}). */
+function responseText(input) {
+    const r = input.tool_response ?? input.tool_result ?? input.toolResult ?? null;
+    if (r == null) return null;
+    if (typeof r === 'string') return r;
+    if (typeof r.stdout === 'string') return r.stdout;
+    if (typeof r.content === 'string') return r.content;
+    if (typeof r.file?.content === 'string') return r.file.content;
+    if (Array.isArray(r.content)) return r.content.map(c => c?.text ?? '').join('\n');
+    return JSON.stringify(r);
+}
+
+/** Navigation calls since the last edit and definitions already shown, per session (crawl detector). */
+function sessionState(input) {
+    const id = String(input.session_id ?? input.sessionId ?? input.conversation_id ?? 'default').replace(/[^\w.-]/g, '_').slice(0, 80);
+    const file = path.join(os.tmpdir(), 'graph-indexer-hooks', `${id}.json`);
+    let st = { nav: 0, shown: [] };
+    try { st = { ...st, ...JSON.parse(fs.readFileSync(file, 'utf8')) }; } catch { /* first call */ }
+    return {
+        st,
+        save() {
+            try {
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                st.shown = st.shown.slice(-400);
+                fs.writeFileSync(file, JSON.stringify(st));
+            } catch { /* optional */ }
+        },
+    };
+}
+
+/** A file read through the shell: [file, from, to] for `sed -n 'a,bp' f`, `head -n N f`, `cat f`, `nl -ba f | sed -n …`. */
+export function shellRead(command) {
+    const c = String(command ?? '').replace(/^\s*cd\s+\S+\s*&&\s*/, '');
+    let m;
+    if ((m = /^(?:nl\s+-ba\s+|cat\s+-n\s+)(\S+)\s*\|\s*sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s*$/.exec(c))) return [m[1], +m[2], +m[3]];
+    if ((m = /^sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s+(\S+)\s*$/.exec(c))) return [m[3], +m[1], +m[2]];
+    if ((m = /^head\s+-(?:n\s*)?(\d+)\s+(\S+)\s*$/.exec(c))) return [m[2], 1, +m[1]];
+    if ((m = /^cat\s+(?:-n\s+)?(\S+\.\w+)\s*$/.exec(c))) return [m[1], 1, 2000];
+    return null;
+}
+
+/** Minimal shell-words split (quotes and escapes) for extracting a grep pattern. */
+function shellWords(s) {
+    const out = [];
+    let cur = '', q = null, any = false;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (q) { if (ch === q) q = null; else if (ch === '\\' && q === '"' && i + 1 < s.length) cur += s[++i]; else cur += ch; continue; }
+        if (ch === '"' || ch === "'") { q = ch; any = true; continue; }
+        if (ch === '\\' && i + 1 < s.length) { cur += s[++i]; any = true; continue; }
+        if (/\s/.test(ch)) { if (cur || any) out.push(cur); cur = ''; any = false; continue; }
+        if (ch === '|' || ch === ';' || ch === '&') { if (cur || any) out.push(cur); break; }
+        cur += ch;
+    }
+    if (cur || any) out.push(cur);
+    return out;
+}
+
+/** The pattern of a grep-like shell command (first non-option word, or the value of -e). */
+export function grepPattern(command) {
+    const m = SEARCH_CMD.exec(command ?? '');
+    if (!m) return null;
+    const words = shellWords(m[2]);
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        if (w === '-e' || w === '--regexp') return words[i + 1] ?? null;
+        if (w.startsWith('-')) { if (/^-(A|B|C|m|g|t|T|-type|-glob|-include|-exclude|-max-count)$/.test(w)) i++; continue; }
+        return w;
+    }
+    return null;
+}
+
+const hasIndex = (root) => fs.existsSync(path.join(root, DATA_DIR_NAME, 'index.db'));
+
+/** The index for one hook call when no resident process answers: opened, synced, closed after. */
+function localIndex(root) {
+    return async () => {
+        if (!hasIndex(root)) return null; // never build a whole index inside a tool hook
+        const { CodeIntel } = await import('../query/intel.mjs');
+        const intel = new CodeIntel({ root });
+        await intel.open();
+        return { intel, release: () => intel.close() };
+    };
+}
+
+async function afterEdit(root, input, acquire) {
+    const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? input.tool_input?.path ?? null;
+    if (!file) return null;
+    const rel = path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file;
+    if (rel.startsWith('..') || !specForPath(rel)) return null;
+    const ix = await acquire();
+    if (!ix) return null;
+    const { intel } = ix;
+    try {
+        const { checkChanges } = await import('../query/check.mjs');
+        const r = await checkChanges(intel, { files: [rel], tests: false });
+        if (r.error) return null;
+        const lines = [];
+        for (const e of r.syntax.slice(0, 3)) lines.push(`${e.path}:${e.line} has a syntax error introduced since the last commit (${e.missing ? `missing ${e.missing}` : 'unexpected code'}): ${e.text.slice(0, 100)}`);
+        for (const a of r.arity.slice(0, 4)) {
+            const sites = a.sites.slice(0, 4).map(x => `${x.path}:${x.line} (passes ${x.argc.n})`).join(', ');
+            lines.push(a.newCall ? `The call at ${sites} does not fit ${a.target}, which takes ${a.is} argument(s).`
+                : `${a.target} now takes ${a.is} argument(s) (was ${a.was}); ${a.sites.length} of its ${a.total} call sites no longer fit: ${sites}${a.sites.length > 4 ? ', …' : ''}.`);
+        }
+        for (const m of r.removed.slice(0, 3)) {
+            const uses = m.uses.slice(0, 4).map(u => `${u.path}:${u.line}`).join(', ');
+            lines.push(`${m.qname} no longer exists in ${m.path} but is still used ${m.total + m.imports.length} time(s): ${uses}${m.total > 4 ? ', …' : ''}.`);
+        }
+        if (!lines.length) return null;
+        return `graph-indexer check after this edit:\n- ${lines.join('\n- ')}\n(check_changes lists everything, including the tests to run.)`;
+    } finally { ix.release(); }
+}
+
+async function afterGrep(root, input, crawling, acquire) {
+    const shell = !GREP_TOOLS.has(input.tool_name);
+    const pattern = shell ? grepPattern(input.tool_input?.command) : input.tool_input?.pattern;
+    if (!pattern || pattern.length > 200) return null;
+    const { identifierOf } = await import('../query/textsearch.mjs');
+    const literal = shell && /(^|\s)(-F|--fixed-strings)\b/.test(input.tool_input?.command ?? '');
+    const ident = identifierOf(pattern, literal);
+    if (!ident || ident.length < 3 || STOP_IDENTS.has(ident)) return null;
+    const out = responseText(input);
+    // a search for a definition that did not find it: say where it is (always — it replaces the
+    // next search). A search for uses is left alone unless the agent is crawling.
+    const defSearch = DEF_SEARCH.test(pattern) || (out != null && out.trim() === '');
+    const foundDef = out != null && new RegExp(`\\b(def|class|function|func|fn|interface|struct|trait|enum|type)\\s+${ident}\\b`).test(out);
+    if (!(defSearch && !foundDef) && !crawling) return null;
+    const ix = await acquire();
+    if (!ix) return null;
+    const { intel } = ix;
+    try {
+        const defs = intel.store.all(`SELECT s.id, s.qname, s.kind, s.start_line, s.end_line, s.sig, f.path, f.is_test,
+                (SELECT COUNT(*) FROM refs r WHERE r.dst_id = s.id) AS uses
+            FROM symbols s JOIN files f ON f.id = s.file_id
+            WHERE s.name = ? AND s.kind IN ('function','method','class','interface','struct','trait','enum','type','field','property','constant','constructor')
+            ORDER BY uses DESC, f.is_test, f.path`, ident);
+        // one entry per qualified name (overloads, re-declarations)
+        const byQ = new Map();
+        for (const d of defs) { const p = byQ.get(d.qname); if (!p) byQ.set(d.qname, { ...d }); else p.uses += d.uses; }
+        const list = [...byQ.values()].filter(d => !d.is_test || d.uses > 0);
+        if (!list.length) return null;
+        if (defSearch && !foundDef) {
+            const shown = list.slice(0, 3).map(d => `${d.qname} → ${d.path}:${d.start_line}-${d.end_line}  ${String(d.sig ?? d.kind).replace(/\s+/g, ' ').slice(0, 110)}`);
+            return `graph-indexer: "${ident}" is defined at:\n  ${shown.join('\n  ')}${list.length > 3 ? `\n  (${list.length - 3} more definitions with this name)` : ''}`;
+        }
+        const unbound = intel.store.get(`SELECT COUNT(*) AS n FROM refs WHERE name = ? AND dst_id IS NULL AND kind IN ('call','new')`, ident)?.n ?? 0;
+        const totalUses = list.reduce((n, d) => n + d.uses, 0);
+        if (list.length === 1 && totalUses < 8) return null; // one definition, few uses: grep output is already clear
+        const shown = list.slice(0, 5).map(d => `${d.qname} (${d.path}:${d.start_line}, ${d.uses} bound use${d.uses === 1 ? '' : 's'})`);
+        const head = list.length === 1
+            ? `graph-indexer: "${ident}" is ${shown[0]}`
+            : `graph-indexer: "${ident}" names ${list.length} different definitions — ${shown.join('; ')}${list.length > 5 ? `; ${list.length - 5} more` : ''}`;
+        return `${head}.${unbound ? ` ${unbound} same-name call${unbound === 1 ? ' has' : 's have'} a receiver of unknown type.` : ''} find_references on one qualified name lists only its uses, with the enclosing function of each.`;
+    } finally { ix.release(); }
+}
+
+/**
+ * After a read: the indirection the lines involve, resolved (which override runs, which table entry
+ * handles a key, what reaches a method by a built name, what a decorator is) — always, since it is
+ * silent when there is none; and while the agent is crawling, where the names the lines use are defined.
+ */
+async function afterRead(root, input, state, crawling, acquire) {
+    let file = null, from = 1, to = 2000;
+    if (READ_TOOLS.has(input.tool_name)) {
+        file = input.tool_input?.file_path ?? input.tool_input?.path ?? input.tool_input?.absolute_path ?? null;
+        const off = Number(input.tool_input?.offset ?? 0), lim = Number(input.tool_input?.limit ?? 0);
+        if (off > 0) from = off;
+        if (lim > 0) to = from + lim - 1;
+    } else {
+        const r = shellRead(input.tool_input?.command);
+        if (!r) return null;
+        [file, from, to] = r;
+    }
+    if (!file) return null;
+    const cwd = input.cwd || root;
+    const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
+    const rel = path.relative(root, abs).split(path.sep).join('/');
+    if (rel.startsWith('..') || !specForPath(rel)) return null;
+    const ix = await acquire();
+    if (!ix) return null;
+    const { intel } = ix;
+    try {
+        await intel.revalidate([rel]); // a long-lived index may not have seen the file change yet
+        const out = [];
+        const { factsForRange, renderFacts } = await import('../query/facts.mjs');
+        state.st.facts ??= [];
+        const facts = factsForRange(intel, rel, from, to, { max: 4, shown: new Set(state.st.facts) });
+        if (facts.length) {
+            for (const f of facts) state.st.facts.push(f.key);
+            out.push(`graph-indexer, resolved for these lines:\n${renderFacts(facts).map(l => `  ${l}`).join('\n')}`);
+        }
+        if (crawling) {
+            const { definitionsUsed } = await import('../query/read.mjs');
+            const n = Math.max(1, to - from + 1);
+            const { rows } = definitionsUsed(intel, rel, from, to, { max: Math.min(12, Math.max(4, Math.round(n / 15))), skipIds: new Set(state.st.shown) });
+            for (const r of rows) state.st.shown.push(r.id);
+            if (rows.length) out.push(`graph-indexer: where names used in these lines are defined (read them directly instead of searching):\n${rows.map(r => `  ${r.qname} → ${r.path}:${r.start_line}  ${String(r.sig || r.kind).replace(/\s+/g, ' ').replace(/\s+#.*$/, '').slice(0, 100)}`).join('\n')}`);
+        }
+        return out.length ? out.join('\n') : null;
+    } finally { ix.release(); }
+}
+
+// the lookup rules, for sessions and subagents whose instruction files do not carry them
+const RULES = `How to look code up in this repository (graph-indexer):
+- Several things at once: several tool calls in one message, or one search with alternatives — not one search per turn.
+- The function or the 50–100 lines you need, not whole files; to find a definition, search for its definition line (\`def name\`, \`class Name\`) across the package in one search.
+- Exact uses of a function or class, even when other code shares its name: find_references (\`npx graph-indexer refs NAME\` in a shell). Before changing what other code relies on: change_impact; when you are done: check_changes, then run the tests it names, once.`;
+
+async function sessionLine(root, { rules = false, acquire }) {
+    if (!hasIndex(root)) return null; // being built in the background (spawnResident); say nothing yet
+    const ix = await acquire();
+    if (!ix) return null;
+    const { intel } = ix;
+    try {
+        const st = intel.stats();
+        const line = `graph-indexer has a live index of this repository (${st.files} files, ${st.symbols} symbols). Its MCP tools answer with exact locations: find_references (exact uses, even when other code shares the name), change_impact (what a change affects and which tests to run), check_changes (what an edit broke, and the closest tests), call_graph, read_code (symbols or ranges by name, with where each name they use is defined), search_text, search_code and outline.`;
+        // the managed block of `init` already carries the rules; otherwise add them
+        const carried = ['CLAUDE.md', 'AGENTS.md'].some(f => { try { return fs.readFileSync(path.join(root, f), 'utf8').includes('<!-- graph-indexer:start -->'); } catch { return false; } });
+        return rules || !carried ? `${line}\n${RULES}` : line;
+    } finally { ix.release(); }
+}
+
+/**
+ * One hook call: what the hook prints (in the calling host's format), or null. `acquire()` gives
+ * the index: opened for this call, or the resident process's own.
+ */
+export async function handleHook(event, input, { root, acquire }) {
+    let text = null, name = input.hook_event_name ?? null;
+    if (event === 'post-tool') {
+        name ??= 'PostToolUse';
+        const tool = input.tool_name ?? input.toolName ?? '';
+        const command = input.tool_input?.command;
+        const state = sessionState(input);
+        if (EDIT_TOOLS.has(tool)) {
+            state.st.nav = 0;
+            state.save();
+            text = await afterEdit(root, input, acquire);
+        } else if (GREP_TOOLS.has(tool) || (SHELL_TOOLS.has(tool) && grepPattern(command))) {
+            state.st.nav++;
+            state.save();
+            text = await afterGrep(root, input, state.st.nav >= CRAWL, acquire);
+        } else if (READ_TOOLS.has(tool) || (SHELL_TOOLS.has(tool) && shellRead(command))) {
+            state.st.nav++;
+            text = await afterRead(root, input, state, state.st.nav >= CRAWL, acquire);
+            state.save();
+        }
+    } else if (event === 'session-start' || event === 'subagent-start') {
+        name ??= event === 'session-start' ? 'SessionStart' : 'SubagentStart';
+        text = await sessionLine(root, { rules: event === 'subagent-start', acquire });
+    }
+    return format(name, text, input, event === 'post-tool' ? MAX_CONTEXT : 2500);
+}
+
+/**
+ * Start a resident process (`graph-indexer daemon`) so later hook calls skip opening the index; at
+ * session start it also builds a missing index. At most once a minute per repository, and never
+ * from a tool hook in a repository without an index.
+ */
+function spawnResident(root, event) {
+    const starting = event === 'session-start' || event === 'subagent-start';
+    if (!starting && !hasIndex(root)) return;
+    const bin = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/graph-indexer.mjs');
+    const off = process.env.GRAPH_INDEXER_RESIDENT === '0';
+    if (off && (!starting || hasIndex(root))) return;
+    try {
+        const mark = path.join(dataDir(root), 'resident.started');
+        try { if (Date.now() - fs.statSync(mark).mtimeMs < 60_000) return; } catch { /* first time */ }
+        fs.writeFileSync(mark, String(Date.now()));
+        // without a resident, still build a missing index in the background so the first query is fast
+        spawn(process.execPath, [bin, off ? 'index' : 'daemon', '--repo', root], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    } catch { /* optional */ }
+}
+
+export async function runHook(event, { repo = null, version = null } = {}) {
+    const deadlineMs = event === 'post-tool' ? 4000 : 3000;
+    const timer = setTimeout(() => process.exit(0), deadlineMs); // fail open: never hold the agent up
+    try {
+        const input = await readStdin();
+        const root = findRepoRoot(input.cwd || repo || process.cwd());
+        const { askResident, residentRequired } = await import('./resident.mjs');
+        const reply = await askResident(root, { op: 'hook', event, input }, { version, totalMs: 2000 });
+        let out = null;
+        if (reply) out = reply.out;
+        else if (!residentRequired()) {
+            out = await handleHook(event, input, { root, acquire: localIndex(root) });
+            spawnResident(root, event);
+        }
+        if (out) process.stdout.write(out + '\n');
+    } catch { /* fail open */ }
+    clearTimeout(timer);
+}

package/src/cli/init.mjs

@@ -0,0 +1,255 @@
+/**
+ * `graph-indexer init`: wire the MCP server into the coding agents used in this repository.
+ *
+ * Writes project-level MCP configuration (merged, never clobbering other servers) and, unless
+ * --no-instructions, a short managed block in AGENTS.md / CLAUDE.md naming the tools and when to
+ * use them (a few lines — long generated context files measurably hurt agents). For Claude Code it
+ * also writes, unless --no-helper, the structural helper sub-agent (.claude/agents/code-structure.md,
+ * src/cli/helper.mjs). Idempotent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRepoRoot } from '../util/paths.mjs';
+import { HELPER_NAME, claudeAgentFile } from './helper.mjs';
+
+const BLOCK_START = '<!-- graph-indexer:start -->';
+const BLOCK_END = '<!-- graph-indexer:end -->';
+// The lookup rules first, then graph-indexer for what a text search cannot answer exactly: the
+// arrangement that cost least in the fourth benchmark round (docs/AGENTIC-BENCHMARK.md). Sending
+// every read and search through graph-indexer cost more on issue fixes than the rules alone.
+const SNIPPET = `${BLOCK_START}
+## Looking code up (graph-indexer)
+- Explore in one pass: when you need several definitions or files, ask for them together — several tool calls in one message, or one search with alternatives — not one search per turn.
+- Read keyholes, not files: the function or the 50–100 lines you need (find the line first, then read that range).
+- To find where a name is defined, search for its definition line (\`def name\`, \`class Name\`, \`function name\`) across the package in one search, not directory by directory.
+- Check once: run the tests that cover your change when you are done; do not re-run a check nothing has changed.
+
+The \`graph-indexer\` MCP server answers what a text search cannot answer exactly:
+- Uses of a function, method or class that other code shares a name with: \`find_references\` (exact call sites, says when the list is complete; kind \`inherit\` for subclasses and implementations). Callers of callers: \`call_graph\`.
+- Before changing a signature other code relies on: \`change_impact\`; after: \`check_changes\`.
+${BLOCK_END}`;
+
+/** The managed instructions block `init` writes to CLAUDE.md / AGENTS.md (markers included). */
+export function managedBlock() { return SNIPPET; }
+
+const AGENTS = {
+    claude: { label: 'Claude Code', file: '.mcp.json', key: 'mcpServers', detect: ['.claude', 'CLAUDE.md', '.mcp.json'], instructions: 'CLAUDE.md' },
+    cursor: { label: 'Cursor', file: '.cursor/mcp.json', key: 'mcpServers', detect: ['.cursor', '.cursorrules'], instructions: 'AGENTS.md', workspaceVar: '${workspaceFolder}' },
+    vscode: { label: 'VS Code (Copilot)', file: '.vscode/mcp.json', key: 'servers', detect: ['.vscode'], instructions: 'AGENTS.md', workspaceVar: '${workspaceFolder}', vscode: true },
+    gemini: { label: 'Gemini CLI', file: '.gemini/settings.json', key: 'mcpServers', detect: ['.gemini', 'GEMINI.md'], instructions: 'AGENTS.md' },
+    codex: { label: 'Codex CLI', file: null, detect: ['AGENTS.md', '.codex'], instructions: 'AGENTS.md' },
+    // Kilo Code (CLI and VS Code, rebuilt on OpenCode) also reads opencode.json; an existing kilo.json is used instead
+    opencode: { label: 'OpenCode / Kilo Code', file: 'opencode.json', alt: ['kilo.json', '.kilo/kilo.json'], key: 'mcp', detect: ['opencode.json', 'opencode.jsonc', '.opencode', 'kilo.json', 'kilo.jsonc', '.kilo', '.kilocode'], instructions: 'AGENTS.md', opencode: true },
+    junie: { label: 'Junie', file: '.junie/mcp/mcp.json', key: 'mcpServers', detect: ['.junie'], instructions: 'AGENTS.md' },
+    // Zed runs project context servers in the project root; it reads the first of .rules, …, AGENTS.md, CLAUDE.md
+    zed: { label: 'Zed', file: '.zed/settings.json', key: 'context_servers', detect: ['.zed'], instructions: 'AGENTS.md', zed: true },
+    // Devin Desktop (formerly Windsurf) and Devin CLI load the Claude Code hooks in .claude/ by default
+    devin: { label: 'Devin Desktop / Devin CLI', file: null, detect: ['.devin', '.windsurf', '.windsurfrules'], instructions: 'AGENTS.md' },
+};
+
+function readJson(p) {
+    try { return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\s*\/\/.*$/gm, '')); } catch { return null; }
+}
+
+function serverEntry(agent, { local }) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const bin = path.resolve(here, '../../bin/graph-indexer.mjs');
+    const repoArgs = agent.workspaceVar ? ['--repo', agent.workspaceVar] : [];
+    const base = local
+        ? { command: process.execPath, args: [bin, 'serve', ...repoArgs] }
+        : { command: 'npx', args: ['-y', 'graph-indexer@3', 'serve', ...repoArgs] };
+    if (agent.opencode) return { type: 'local', command: [base.command, ...base.args], enabled: true };
+    if (agent.zed) return { ...base, env: {} };
+    return agent.vscode ? { type: 'stdio', ...base } : base;
+}
+
+/** The config file to edit: the agent's default, or an existing alternative it also reads. */
+function configFile(agent, repo) {
+    for (const f of agent.alt ?? []) if (fs.existsSync(path.join(repo, f))) return f;
+    return agent.file;
+}
+
+function upsertBlock(file, dryRun) {
+    const exists = fs.existsSync(file);
+    const text = exists ? fs.readFileSync(file, 'utf8') : '';
+    let next;
+    if (text.includes(BLOCK_START) && text.includes(BLOCK_END)) {
+        next = text.replace(new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`), SNIPPET);
+    } else {
+        next = (text.trimEnd() ? text.trimEnd() + '\n\n' : '') + SNIPPET + '\n';
+    }
+    if (next === text) return 'unchanged';
+    if (!dryRun) fs.writeFileSync(file, next);
+    return exists ? 'updated' : 'created';
+}
+
+/** An installed `graph-indexer` executable on PATH, if any (hooks start in ~0.1 s instead of npx's ~1 s). */
+function installedBin() {
+    for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+        if (!dir) continue;
+        const f = path.join(dir, process.platform === 'win32' ? 'graph-indexer.cmd' : 'graph-indexer');
+        try { if (fs.statSync(f).isFile()) return f; } catch { /* not here */ }
+    }
+    return null;
+}
+
+/** The command agents run for graph-indexer: this installation with --local, an installed binary, or npx. */
+function cliCommand(local) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const bin = path.resolve(here, '../../bin/graph-indexer.mjs');
+    if (local) return `${JSON.stringify(process.execPath)} ${JSON.stringify(bin)}`;
+    const installed = installedBin();
+    return installed ? JSON.stringify(installed) : 'npx -y graph-indexer@3';
+}
+
+/** The command that starts graph-indexer, as an argv array (for the OpenCode/Kilo Code plugin). */
+function cliArgv(local) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    if (local) return [process.execPath, path.resolve(here, '../../bin/graph-indexer.mjs')];
+    const installed = installedBin();
+    return installed ? [installed] : ['npx', '-y', 'graph-indexer@3'];
+}
+
+/**
+ * The OpenCode / Kilo Code plugin (integrations/opencode/graph-indexer.js): after reads, searches
+ * and edits it appends what the Claude Code hooks add as context. Kilo Code loads project plugins
+ * from .kilo/plugin/, OpenCode from .opencode/plugins/.
+ */
+function writeOpenCodePlugin(repo, local, dryRun) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const src = fs.readFileSync(path.resolve(here, '../../integrations/opencode/graph-indexer.js'), 'utf8')
+        .replace(/^const DAEMON = .*$/m, `const DAEMON = ${JSON.stringify([...cliArgv(local), 'daemon'])};`);
+    const kilo = ['kilo.json', 'kilo.jsonc', '.kilo', '.kilocode'].some(f => fs.existsSync(path.join(repo, f)));
+    const open = ['opencode.json', 'opencode.jsonc', '.opencode'].some(f => fs.existsSync(path.join(repo, f)));
+    const targets = [...(kilo ? ['.kilo/plugin/graph-indexer.js'] : []), ...(open || !kilo ? ['.opencode/plugins/graph-indexer.js'] : [])];
+    const out = [];
+    for (const rel of targets) {
+        const file = path.join(repo, rel);
+        const same = fs.existsSync(file) && fs.readFileSync(file, 'utf8') === src;
+        if (!same && !dryRun) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, src);
+        }
+        out.push(`${same ? 'already in' : 'written to'} ${rel}`);
+    }
+    return `OpenCode / Kilo Code plugin (definitions after reads, missed definitions, edit check): ${out.join(', ')}`;
+}
+
+/**
+ * Claude Code hooks (project .claude/settings.json), merged with existing ones: after edits the
+ * edit checker runs on the edited file, after a grep for a shared identifier the definitions are
+ * told apart, and sessions/subagents learn in one line that the index exists. Silent otherwise.
+ */
+function upsertClaudeHooks(repo, local, dryRun) {
+    const file = path.join(repo, '.claude', 'settings.json');
+    const cfg = readJson(file) ?? {};
+    const cmd = cliCommand(local);
+    const ours = (h) => /graph-indexer(\.mjs|\.cmd)?"?(@\d+)? hook /.test(h?.command ?? '');
+    const want = {
+        PostToolUse: { matcher: 'Edit|Write|MultiEdit|Grep|Bash|Read', hooks: [{ type: 'command', command: `${cmd} hook post-tool`, timeout: 10 }] },
+        SessionStart: { hooks: [{ type: 'command', command: `${cmd} hook session-start`, timeout: 10 }] },
+        SubagentStart: { hooks: [{ type: 'command', command: `${cmd} hook subagent-start`, timeout: 10 }] },
+    };
+    cfg.hooks ??= {};
+    const before = JSON.stringify(cfg.hooks);
+    for (const [event, entry] of Object.entries(want)) {
+        const list = (cfg.hooks[event] ?? []).map(e => ({ ...e, hooks: (e.hooks ?? []).filter(h => !ours(h)) })).filter(e => e.hooks.length);
+        list.push(entry);
+        cfg.hooks[event] = list;
+    }
+    const changed = before !== JSON.stringify(cfg.hooks);
+    if (changed && !dryRun) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+    }
+    return `Claude Code hooks: ${changed ? 'written to' : 'already in'} .claude/settings.json (post-edit check, grep disambiguation, session line)`;
+}
+
+/**
+ * The structural helper for Claude Code (.claude/agents/code-structure.md). A file of that name the
+ * user wrote is left alone; an earlier version of ours is updated.
+ */
+function upsertClaudeHelper(repo, dryRun) {
+    const rel = `.claude/agents/${HELPER_NAME}.md`;
+    const file = path.join(repo, rel);
+    const want = claudeAgentFile();
+    const have = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+    if (have === want) return `Claude Code: structural helper already in ${rel}`;
+    if (have != null && !have.includes("graph-indexer's index")) return `Claude Code: ${rel} exists and is not graph-indexer's, so it was left as is`;
+    if (!dryRun) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, want);
+    }
+    return `Claude Code: structural helper ${have == null ? 'written to' : 'updated in'} ${rel} (a sub-agent on a small model that answers call-site, caller, subclass and impact questions from the index)`;
+}
+
+export async function runInit({ opt, flag, repo: repoArg = null }) {
+    const repo = path.resolve(repoArg ?? opt('--repo') ?? findRepoRoot(process.cwd()));
+    const dryRun = flag('--dry-run');
+    const local = flag('--local');
+    const hooks = flag('--hooks');
+    const noInstructions = flag('--no-instructions');
+    const noHelper = flag('--no-helper');
+    const all = flag('--all');
+    const agentList = opt('--agents');
+    let chosen;
+    if (agentList) chosen = agentList.split(',').map(s => s.trim()).filter(k => AGENTS[k]);
+    else if (all) chosen = Object.keys(AGENTS);
+    else {
+        chosen = Object.entries(AGENTS).filter(([, a]) => a.detect.some(d => fs.existsSync(path.join(repo, d)))).map(([k]) => k);
+        if (!chosen.length) chosen = ['claude'];
+    }
+    const report = [];
+    for (const key of chosen) {
+        const a = AGENTS[key];
+        if (a.file) {
+            const rel = configFile(a, repo);
+            const file = path.join(repo, rel);
+            const raw = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+            const entry = serverEntry(a, { local });
+            // never rewrite a file whose comments or JSONC syntax a JSON round trip would lose
+            const cfg = raw == null ? {} : readJson(file);
+            if (!cfg || /^\s*\/\/|\/\*/m.test(raw ?? '')) {
+                const already = JSON.stringify(cfg?.[a.key]?.['graph-indexer'] ?? null) === JSON.stringify(entry);
+                report.push(already ? `${a.label}: already configured ${rel}`
+                    : `${a.label}: ${rel} has comments or is not plain JSON, so it was left as is; add under "${a.key}": "graph-indexer": ${JSON.stringify(entry)}`);
+                continue;
+            }
+            cfg[a.key] ??= {};
+            const before = JSON.stringify(cfg[a.key]['graph-indexer'] ?? null);
+            cfg[a.key]['graph-indexer'] = entry;
+            const changed = before !== JSON.stringify(entry);
+            if (changed && !dryRun) {
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+            }
+            report.push(`${a.label}: ${changed ? (before === 'null' ? 'added' : 'updated') : 'already configured'} ${rel}`);
+        } else if (key === 'codex') {
+            const entry = serverEntry(a, { local });
+            report.push(`Codex CLI: add to ~/.codex/config.toml →\n  [mcp_servers.graph-indexer]\n  command = "${entry.command}"\n  args = ${JSON.stringify(entry.args)}\n  cwd = "${repo}"`);
+        } else if (key === 'devin') {
+            const entry = serverEntry(a, { local });
+            report.push(`Devin: reads AGENTS.md${hooks ? ' and the Claude Code hooks in .claude/settings.json' : ' (and, with --hooks, the Claude Code hooks)'}; add the MCP server in Devin's MCP settings → command "${entry.command}", args ${JSON.stringify([...entry.args, '--repo', repo])}`);
+        }
+    }
+    if (!noHelper && chosen.includes('claude')) report.push(upsertClaudeHelper(repo, dryRun));
+    // Devin Desktop/CLI, Copilot CLI and Cursor also run the Claude Code hooks in .claude/settings.json
+    if (hooks && (chosen.includes('claude') || chosen.includes('devin'))) report.push(upsertClaudeHooks(repo, local, dryRun));
+    if (hooks && chosen.includes('opencode')) report.push(writeOpenCodePlugin(repo, local, dryRun));
+    if (!noInstructions) {
+        const targets = [...new Set(chosen.map(k => AGENTS[k].instructions))];
+        for (const t of targets) report.push(`${t}: ${upsertBlock(path.join(repo, t), dryRun)} graph-indexer instructions block`);
+    }
+    // keep the index out of version control
+    const gi = path.join(repo, '.gitignore');
+    const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+    if (!/^\/?\.graph-indexer\/?$/m.test(giText)) {
+        if (!dryRun) fs.writeFileSync(gi, (giText.trimEnd() ? giText.trimEnd() + '\n' : '') + '.graph-indexer/\n');
+        report.push('.gitignore: added .graph-indexer/');
+    }
+    process.stdout.write(`graph-indexer init ${dryRun ? '(dry run) ' : ''}in ${repo}\n  ${report.join('\n  ')}\n\n` +
+        `Other agents (Claude Desktop, JetBrains AI Assistant, Cline): add an MCP server with command "npx" and args ["-y","graph-indexer@3","serve","--repo","${repo}"].\n` +
+        `Build the index now with: npx graph-indexer index   (the server also builds it on first start)\n` +
+        (hooks ? '' : `Optional: graph-indexer init --hooks adds Claude Code hooks (edit check after each edit, grep disambiguation).\n`));
+}