weavatrix 0.1.0

package/src/mcp/tools-impact.mjs

@@ -0,0 +1,189 @@
+// Impact tools: transitive blast radius of one node (get_dependents), the structural diff of the
+// last rebuild (graph_diff), and the blast radius of the current change set (change_impact).
+// Hot-reloadable (re-imported by catalog.mjs on change).
+import {readFileSync} from 'node:fs'
+import {spawnSync} from 'node:child_process'
+import {
+    isSymbol, degreeOf, labelOf, resolveNodeInfo, ambiguityNote,
+    rawGraph, prevGraphPathFor, edgeEndpoint, diffGraphs, formatGraphDiff,
+} from './graph-context.mjs'
+import {readCoverageForRepo} from '../analysis/coverage-reports.js'
+
+// Transitive blast-radius: who is affected if this node changes. Walks REVERSE dependency edges
+// (calls/imports/inherits — not structural `contains`) out to `depth`. For a symbol, also seeds its
+// containing file, because importers depend on the file rather than the individual symbol.
+export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
+    const info = resolveNodeInfo(g, label)
+    const n = info.node
+    if (!n) return `No node found matching "${label}".`
+    const note = ambiguityNote(label, info)
+    const maxDepth = Math.max(1, Math.min(6, Number(depth) || 3))
+    const cap = Math.max(5, Math.min(120, Number(max_nodes) || 40))
+    const id = String(n.id)
+    const seeds = new Set([id])
+    let containingFile = null
+    if (isSymbol(id)) {
+        const container = (g.inn.get(id) || []).find((e) => e.relation === 'contains')
+        if (container) {
+            containingFile = String(container.id)
+            seeds.add(containingFile)
+        }
+    }
+    const depthOf = new Map([...seeds].map((s) => [s, 0]))
+    const relOf = new Map()
+    let frontier = [...seeds]
+    for (let d = 0; d < maxDepth && frontier.length; d++) {
+        const next = []
+        for (const cur of frontier) {
+            for (const e of g.inn.get(cur) || []) {
+                if (e.relation === 'contains') continue // structural nesting is not a dependency
+                const nid = String(e.id)
+                if (depthOf.has(nid)) continue
+                depthOf.set(nid, d + 1)
+                relOf.set(nid, e.relation || 'rel')
+                next.push(nid)
+            }
+        }
+        frontier = next
+    }
+    const ranked = [...depthOf.entries()]
+        .filter(([nid]) => !seeds.has(nid))
+        .map(([nid, d]) => ({id: nid, d, deg: degreeOf(g, nid)}))
+        .sort((a, b) => a.d - b.d || b.deg - a.deg)
+    if (!ranked.length) return [note, `No dependents found for ${n.label ?? id} within depth ${maxDepth} — nothing in the graph calls, imports, or inherits it.`].filter(Boolean).join('\n')
+    const shown = ranked.slice(0, cap)
+    return [
+        note,
+        `Dependents of ${n.label ?? id} (reverse calls/imports/inherits, depth ≤${maxDepth}): ${ranked.length} found, showing ${shown.length} by proximity + connectivity.`,
+        containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)}.` : null,
+        ...shown.map((r) => `  [d${r.d}] ${relOf.get(r.id) || 'rel'}  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
+    ].filter(Boolean).join('\n')
+}
+
+// Re-query the last rebuild's before/after pair (graph.prev.json vs graph.json), optionally scoped.
+export function tGraphDiff(g, args, ctx) {
+    const prevPath = prevGraphPathFor(ctx.graphPath)
+    let prev
+    try { prev = JSON.parse(readFileSync(prevPath, 'utf8')) } catch {
+        return `No previous graph state at ${prevPath} — rebuild_graph saves one automatically (a single prior state is kept).`
+    }
+    const current = rawGraph(ctx)
+    const filter = args.path ? String(args.path).replace(/\\/g, '/') : null
+    const scope = (graph) => filter ? {
+        nodes: (graph.nodes || []).filter((n) => String(n.id).startsWith(filter)),
+        links: (graph.links || []).filter((l) => String(edgeEndpoint(l.source)).startsWith(filter) || String(edgeEndpoint(l.target)).startsWith(filter))
+    } : graph
+    return [
+        `Graph diff (previous rebuild state → current)${filter ? `, scoped to ${filter}` : ''}:`,
+        formatGraphDiff(diffGraphs(scope(prev), scope(current)))
+    ].join('\n')
+}
+
+// ---- change impact -------------------------------------------------------------------------------
+function gitLines(repoRoot, args) {
+    const res = spawnSync('git', ['-C', repoRoot, ...args], {encoding: 'utf8', timeout: 8000})
+    if (res.status !== 0) return null
+    return String(res.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
+}
+
+function resolveImpactBase(repoRoot, requested) {
+    const candidates = requested ? [requested] : ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
+    for (const ref of candidates) {
+        const ok = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {encoding: 'utf8', timeout: 8000})
+        if (ok.status === 0) return ref
+    }
+    return null
+}
+
+// Blast radius of a change, without any GitHub API: diff the CURRENT change (branch
+// commits since the merge-base + staged/unstaged + untracked) against a base ref, map the changed
+// files and their symbols onto the graph, and walk REVERSE dependency edges — everything the change
+// can break, ranked by proximity + connectivity, with file-level test coverage attached so the
+// untested part of the blast radius stands out. The pre-PR review, in one call.
+export function tChangeImpact(g, args, ctx) {
+    if (!ctx.repoRoot) return 'change_impact needs the repo root (not provided to this server).'
+    // Explicit file list (e.g. a PR's changed files) skips the local git diff entirely — this is how
+    // a NOT-checked-out PR gets its impact assessed.
+    const explicit = Array.isArray(args.files)
+        ? [...new Set(args.files.map((f) => String(f).replace(/\\/g, '/').trim()).filter(Boolean))]
+        : null
+    let changed
+    let sourceLabel
+    if (explicit) {
+        if (!explicit.length) return 'files was provided but empty — pass repo-relative paths, or omit it to diff the local change.'
+        changed = explicit
+        sourceLabel = `for ${changed.length} provided file(s)`
+    } else {
+        const base = resolveImpactBase(ctx.repoRoot, args.base ? String(args.base).trim() : '')
+        if (!base) return `Could not resolve a base ref${args.base ? ` ("${args.base}")` : ''} — pass base explicitly (e.g. origin/main or HEAD~1).`
+        const committed = gitLines(ctx.repoRoot, ['diff', '--name-only', `${base}...HEAD`])
+        if (committed === null) return `git diff against ${base} failed — is ${ctx.repoRoot} a git repository?`
+        const uncommitted = gitLines(ctx.repoRoot, ['diff', '--name-only', 'HEAD']) || []
+        const untracked = gitLines(ctx.repoRoot, ['ls-files', '--others', '--exclude-standard']) || []
+        changed = [...new Set([...committed, ...uncommitted, ...untracked])]
+        sourceLabel = `vs ${base}`
+        if (!changed.length) return `No changes vs ${base} — working tree clean and no branch commits.`
+    }
+
+    const changedSet = new Set(changed)
+    const seeds = new Set()
+    const unmapped = []
+    for (const file of changed) {
+        if (!g.byId.has(file)) { unmapped.push(file); continue }
+        seeds.add(file)
+        for (const e of g.out.get(file) || []) if (e.relation === 'contains') seeds.add(String(e.id))
+    }
+    if (!seeds.size) {
+        return [
+            `${changed.length} changed file(s) ${sourceLabel}, but none are in the graph — new files or non-code.`,
+            `Run rebuild_graph and retry for the full picture.`,
+            `Changed: ${changed.slice(0, 20).join(', ')}${changed.length > 20 ? ', …' : ''}`,
+        ].join('\n')
+    }
+
+    const maxDepth = Math.max(1, Math.min(4, Number(args.depth) || 2))
+    const cap = Math.max(5, Math.min(120, Number(args.max_nodes) || 40))
+    const depthOf = new Map([...seeds].map((s) => [s, 0]))
+    const relOf = new Map()
+    let frontier = [...seeds]
+    for (let d = 0; d < maxDepth && frontier.length; d++) {
+        const next = []
+        for (const cur of frontier) {
+            for (const e of g.inn.get(cur) || []) {
+                if (e.relation === 'contains') continue
+                const nid = String(e.id)
+                if (depthOf.has(nid)) continue
+                depthOf.set(nid, d + 1)
+                relOf.set(nid, e.relation || 'rel')
+                next.push(nid)
+            }
+        }
+        frontier = next
+    }
+    const fileOfNode = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
+    const impacted = [...depthOf.entries()]
+        .filter(([nid]) => !seeds.has(nid) && !changedSet.has(fileOfNode(nid)))
+        .map(([nid, d]) => ({id: nid, d, deg: degreeOf(g, nid), file: fileOfNode(nid)}))
+        .sort((a, b) => a.d - b.d || b.deg - a.deg)
+
+    // coverage overlay from EXISTING reports (fractions 0..1) — see coverage_map for details
+    const knownFiles = (rawGraph(ctx).nodes || []).filter((n) => !String(n.id).includes('#') && n.source_file).map((n) => n.source_file)
+    const coverage = readCoverageForRepo(ctx.repoRoot, knownFiles)
+    const covOf = (file) => coverage.get(String(file).replace(/\\/g, '/'))?.pct ?? null
+    const pctStr = (v) => (v == null ? 'cov n/a' : `cov ${Math.round(v * 100)}%`)
+
+    const shown = impacted.slice(0, cap)
+    const untestedHotspots = shown.filter((n) => { const c = covOf(n.file); return c != null && c < 0.5 && n.deg >= 5 })
+    return [
+        `Change impact ${sourceLabel}: ${changed.length} changed file(s) → ${seeds.size} graph seed(s) incl. their symbols${unmapped.length ? `; ${unmapped.length} file(s) not in the graph (new/non-code — rebuild_graph refreshes)` : ''}.`,
+        impacted.length
+            ? `${impacted.length} impacted node(s) within ${maxDepth} reverse hop(s), showing ${shown.length}:`
+            : `Nothing else in the graph depends on the changed code within ${maxDepth} hop(s).`,
+        ...shown.map((n) => `  [d${n.d}] ${relOf.get(n.id) || 'rel'}  ${labelOf(g, n.id)}  (deg ${n.deg}, ${pctStr(covOf(n.file))})  [${n.id}]`),
+        untestedHotspots.length ? `` : null,
+        untestedHotspots.length ? `Untested hotspots in the blast radius (<50% coverage, deg ≥5) — cover these before shipping:` : null,
+        ...untestedHotspots.slice(0, 10).map((n) => `  ${labelOf(g, n.id)}  (${pctStr(covOf(n.file))}, deg ${n.deg})  ${n.file}`),
+        ``,
+        `Drill into any node with get_dependents / read_source; per-symbol coverage via coverage_map.`,
+    ].filter((x) => x != null).join('\n')
+}

package/src/mcp-rg.mjs

@@ -0,0 +1,51 @@
+import { readdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import process from 'node:process'
+
+const rgInInstall = (base) => [
+    join(base, 'resources', 'app', 'node_modules', '@vscode', 'ripgrep', 'bin', 'rg.exe'),
+    join(base, 'resources', 'app', 'node_modules', '@vscode', 'ripgrep-universal', 'bin', 'win32-x64', 'rg.exe'),
+]
+
+function editorRgCandidates() {
+    if (process.platform !== 'win32') return []
+    const local = process.env.LOCALAPPDATA || ''
+    const pf = process.env.PROGRAMFILES || ''
+    const roots = [local && join(local, 'Programs', 'Microsoft VS Code'), local && join(local, 'Programs', 'cursor'), pf && join(pf, 'Microsoft VS Code')].filter(Boolean)
+    const out = []
+    for (const root of roots) {
+        if (!existsSync(root)) continue
+        out.push(...rgInInstall(root))
+        try {
+            for (const d of readdirSync(root, {withFileTypes: true})) if (d.isDirectory()) out.push(...rgInInstall(join(root, d.name)))
+        } catch { /* optional editor install probe */ }
+    }
+    return out
+}
+
+export function createRgResolver(selfDir) {
+    let rgPath
+    return function resolveRg() {
+        if (rgPath !== undefined) return rgPath
+        rgPath = null
+        const env = (process.env.WEAVATRIX_RG_CMD || '').replace(/^"|"$/g, '')
+        if (env && existsSync(env)) return (rgPath = env)
+        try {
+            const {rgPath: bundledRg} = createRequire(import.meta.url)('@vscode/ripgrep')
+            if (bundledRg && existsSync(bundledRg)) return (rgPath = bundledRg)
+        } catch { /* optional bundled ripgrep module */ }
+        try {
+            const unpackedRg = join(selfDir, '..', '..', 'node_modules', '@vscode', 'ripgrep', 'bin', process.platform === 'win32' ? 'rg.exe' : 'rg')
+            if (existsSync(unpackedRg)) return (rgPath = unpackedRg)
+        } catch { /* optional packaged ripgrep path */ }
+        for (const c of editorRgCandidates()) if (existsSync(c)) return (rgPath = c)
+        try {
+            const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['rg'], {encoding: 'utf8'})
+            const p = probe.status === 0 ? probe.stdout.split(/\r?\n/)[0].trim() : ''
+            if (p && existsSync(p)) return (rgPath = p)
+        } catch { /* optional PATH probe */ }
+        return rgPath
+    }
+}

package/src/mcp-server.mjs

@@ -0,0 +1,171 @@
+// weavatrix MCP server — the stdio entry point. The tool implementations live in src/mcp/*:
+//   graph-context.mjs  — graph load + indexes, node resolution, staleness, raw-graph cache, diffs
+//   tools-graph.mjs    — graph query tools        tools-impact.mjs  — dependents / diff / change impact
+//   tools-health.mjs   — audit / clones / coverage / endpoints
+//   tools-actions.mjs  — rebuild / open_repo / list_known_repos + the 'online' group
+//   catalog.mjs        — tool catalog, capability filter, hot-reload loader
+// Spawned by Claude Code / Codex as a plain Node child (node mcp-server.mjs <graph.json> <repoRoot>).
+// Speaks newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio transport).
+//
+// .mjs on purpose: guarantees ESM parsing regardless of the nearest package.json. The server itself
+// resolves nothing from node_modules at runtime (ripgrep is probed, with a pure-Node fallback); only
+// the graph BUILDER pulls in web-tree-sitter + its WASM grammars when a build is requested.
+//
+// STDOUT is the protocol channel — nothing but JSON-RPC frames may be written there. All diagnostics
+// go to stderr. Two argv forms:
+//   weavatrix-mcp <repoRoot> [caps]               — graph path derived from the standard layout
+//   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file (classic form)
+import {existsSync, statSync} from 'node:fs'
+import {join, dirname} from 'node:path'
+import {fileURLToPath} from 'node:url'
+import process from 'node:process'
+import {loadGraph} from './mcp/graph-context.mjs'
+import {loadHotApi, HOT_FILES} from './mcp/catalog.mjs'
+import {graphOutDirForRepo} from './graph/layout.js'
+
+const SERVER_INFO = {name: 'weavatrix', version: '0.0.1'}
+const DEFAULT_PROTOCOL = '2024-11-05'
+const log = (...a) => process.stderr.write(`[weavatrix] ${a.join(' ')}\n`)
+
+// argv[2] is a repo DIRECTORY in the npx form — derive the graph location from the standard layout;
+// otherwise it is the graph.json path and the repo root follows it.
+let GRAPH_PATH = process.argv[2]
+let repoArg = process.argv[3]
+// caps ABSENT (undefined) = no per-repo config → ALL tools. PRESENT (even the empty string, which a
+// registration may pass for a zero-capability selection) = explicit set — see catalog.loadHotApi.
+let CAPS_ARG = process.argv[4]
+try {
+    if (GRAPH_PATH && statSync(GRAPH_PATH).isDirectory()) {
+        repoArg = GRAPH_PATH.replace(/[\\/]+$/, '')
+        CAPS_ARG = process.argv[3]
+        GRAPH_PATH = join(graphOutDirForRepo(repoArg), 'graph.json')
+        if (!existsSync(GRAPH_PATH)) log(`no graph built yet for ${repoArg} — ask the agent to call rebuild_graph (or open_repo) once; it builds into the standard weavatrix-graphs layout`)
+    }
+} catch { /* argv[2] is not a directory → classic <graph.json> <repoRoot> form */ }
+// repo source root for search_code / read_source; null → those tools degrade.
+const REPO_ROOT = repoArg && existsSync(repoArg) ? repoArg : null
+
+// ---- hot reload of tool implementations -----------------------------------------------------------
+// Node caches modules at spawn, so edits to the tool code would otherwise be invisible until the MCP
+// client reconnects. Before each tools/list|call we stat the hot-reloadable files (HOT_FILES); when
+// any changed on disk we re-import them through catalog.loadHotApi with a cache-busting version and
+// swap the tool table, then notify the client. The stdio shell, graph-context (its caches), and the
+// analysis engines are NOT swapped — changing those still needs a reconnect.
+const MCP_DIR = join(dirname(fileURLToPath(import.meta.url)), 'mcp')
+function hotVersion() {
+    let v = 0
+    for (const f of HOT_FILES) {
+        try { const t = statSync(join(MCP_DIR, f)).mtimeMs; if (t > v) v = t } catch { /* missing file just doesn't bump the version */ }
+    }
+    return v
+}
+
+async function main() {
+    let api = await loadHotApi(0, CAPS_ARG)
+    let graph = null
+    let graphError = null
+    // ctx owns the CURRENT target: rebuild_graph reloads it, open_repo retargets graphPath/repoRoot
+    // at runtime. loadInto always reads ctx.graphPath so both paths share one loader.
+    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null}
+    const loadInto = () => { graph = loadGraph(ctx.graphPath); graphError = null; return graph }
+    ctx.reload = () => { api.resetStalenessCache(); try { return loadInto() } catch (e) { graphError = e.message; return null } }
+    try {
+        if (!ctx.graphPath) throw new Error('no graph.json path given (argv[2])')
+        loadInto()
+        log(`loaded ${graph.nodes.length} nodes / ${graph.links.length} edges from ${ctx.graphPath}`)
+    } catch (e) {
+        graphError = e.message
+        log(`failed to load graph: ${e.message}`)
+    }
+    log(`repo root: ${REPO_ROOT || '(none — source/action tools disabled)'}`)
+    log(`capabilities: ${api.caps ? [...api.caps].join(',') : 'all'} (${api.tools.length} tools)`)
+
+    let protocolVersion = DEFAULT_PROTOCOL
+    const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n')
+    const reply = (id, result) => send({jsonrpc: '2.0', id, result})
+    const fail = (id, code, message) => send({jsonrpc: '2.0', id, error: {code, message}})
+
+    let loadedVersion = hotVersion()
+    let lastFailedVersion = 0
+    const maybeHotReload = async () => {
+        const v = hotVersion()
+        if (v <= loadedVersion || v === lastFailedVersion) return
+        try {
+            api = await loadHotApi(v, CAPS_ARG)
+            loadedVersion = v
+            log(`hot-reloaded tool implementations from changed source (${api.tools.length} tools)`)
+            send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'})
+        } catch (e) {
+            lastFailedVersion = v // remember the broken version so we don't retry it every call
+            log(`hot-reload failed, keeping current tools: ${e.message}`)
+        }
+    }
+
+    const handle = async (msg) => {
+        const {id, method, params} = msg
+        const isNotification = id === undefined || id === null
+        if (method === 'initialize') {
+            if (params?.protocolVersion) protocolVersion = String(params.protocolVersion)
+            return reply(id, {protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo: SERVER_INFO})
+        }
+        if (method === 'notifications/initialized' || method === 'initialized') return
+        if (method === 'ping') return reply(id, {})
+        if (method === 'tools/list') {
+            await maybeHotReload()
+            return reply(id, {tools: api.tools.map(({name, description, inputSchema}) => ({name, description, inputSchema}))})
+        }
+        if (method === 'tools/call') {
+            await maybeHotReload()
+            const tool = api.byName.get(params?.name)
+            if (!tool) return reply(id, {content: [{type: 'text', text: `Unknown tool: ${params?.name}`}], isError: true})
+            // action tools (rebuild_graph) don't need a currently-loaded graph; read tools do
+            if (!graph && tool.cap !== 'build') return reply(id, {content: [{type: 'text', text: `Graph unavailable: ${graphError}`}], isError: true})
+            try {
+                let text = String(await tool.run(graph, params?.arguments || {}, ctx))
+                // Graph answers silently reflect a point-in-time build — surface staleness on every graph tool.
+                if (tool.cap === 'graph') {
+                    const warn = api.stalenessLine(ctx)
+                    if (warn) text += `\n\n${warn}`
+                }
+                return reply(id, {content: [{type: 'text', text}]})
+            } catch (e) {
+                log(`tool ${params?.name} threw: ${e.stack || e.message}`)
+                return reply(id, {content: [{type: 'text', text: `Tool error: ${e.message}`}], isError: true})
+            }
+        }
+        if (!isNotification) return fail(id, -32601, `Method not found: ${method}`)
+    }
+
+    let buf = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => {
+        buf += chunk
+        let nl
+        while ((nl = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, nl).trim()
+            buf = buf.slice(nl + 1)
+            if (!line) continue
+            let msg
+            try {
+                msg = JSON.parse(line)
+            } catch {
+                log(`bad JSON line: ${line.slice(0, 120)}`)
+                continue
+            }
+            // handle is async (rebuild_graph awaits a build) → catch rejections, not just sync throws
+            Promise.resolve().then(() => handle(msg)).catch((e) => {
+                log(`handler error: ${e.stack || e.message}`)
+                if (msg?.id != null) fail(msg.id, -32603, `Internal error: ${e.message}`)
+            })
+        }
+    })
+    process.stdin.on('end', () => process.exit(0))
+    log('ready')
+}
+
+// Guard: hot-reload re-imports of tool modules never touch this entry, but keep the start guard so a
+// stray re-import of the entry itself can never spawn a second stdio loop.
+if (!globalThis.__weavatrixMcpStarted) {
+    globalThis.__weavatrixMcpStarted = true
+    main()
+}

package/src/mcp-source-tools.mjs

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { extname, join, relative } from 'node:path'
+
+const SEARCH_SKIP = new Set(['.git', 'node_modules', 'dist', 'build', 'out', '.next', 'coverage', 'vendor', '.venv', 'venv', 'env', 'target', '__pycache__', '.idea', '.vscode', '.cache', 'bin', 'obj', 'weavatrix-graphs'])
+const BINARY_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf', '.zip', '.gz', '.tar', '.exe', '.dll', '.so', '.dylib', '.woff', '.woff2', '.ttf', '.eot', '.mp4', '.mp3', '.wasm', '.class', '.jar', '.node', '.bin'])
+const MAX_SEARCH_FILE_BYTES = 1024 * 1024
+
+function rgSearch(repoRoot, resolveRg, query, { isRegex, glob, maxResults }) {
+    const rg = resolveRg()
+    if (!rg) return null
+    const args = ['--line-number', '--no-heading', '--color', 'never', '--max-columns', '400', '-m', '30', '-i']
+    if (!isRegex) args.push('--fixed-strings')
+    if (glob) args.push('-g', glob)
+    args.push('--', query, repoRoot)
+    const res = spawnSync(rg, args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 15000 })
+    if (res.status !== 0 && res.status !== 1) return null
+    const out = []
+    for (const line of (res.stdout || '').split(/\r?\n/)) {
+        const match = line.match(/^(.*?):(\d+):(.*)$/)
+        if (!match) continue
+        out.push({
+            file: relative(repoRoot, match[1]).replace(/\\/g, '/'),
+            line: Number(match[2]),
+            text: match[3].trim().slice(0, 300),
+        })
+        if (out.length >= maxResults) break
+    }
+    return out
+}
+
+function globToRe(glob) {
+    if (!glob) return null
+    try {
+        return new RegExp(glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.'), 'i')
+    } catch {
+        return null
+    }
+}
+
+function nodeGrep(repoRoot, query, { isRegex, glob, maxResults }) {
+    const out = []
+    let re = null
+    if (isRegex) {
+        try { re = new RegExp(query, 'i') } catch { return out }
+    }
+    const q = String(query).toLowerCase()
+    const globRe = globToRe(glob)
+    const stack = [repoRoot]
+    let filesScanned = 0
+    while (stack.length && out.length < maxResults) {
+        const dir = stack.pop()
+        let entries
+        try { entries = readdirSync(dir, { withFileTypes: true }) } catch { continue }
+        for (const ent of entries) {
+            if (out.length >= maxResults) break
+            const full = join(dir, ent.name)
+            if (ent.isDirectory()) {
+                if (!SEARCH_SKIP.has(ent.name)) stack.push(full)
+                continue
+            }
+            if (!ent.isFile() || BINARY_EXT.has(extname(ent.name).toLowerCase())) continue
+            const rel = relative(repoRoot, full).replace(/\\/g, '/')
+            if (globRe && !globRe.test(rel)) continue
+            let st
+            try { st = statSync(full) } catch { continue }
+            if (st.size > MAX_SEARCH_FILE_BYTES) continue
+            if (++filesScanned > 20000) return out
+            let text
+            try { text = readFileSync(full, 'utf8') } catch { continue }
+            if (text.indexOf('\0') >= 0) continue
+            const lines = text.split(/\r?\n/)
+            for (let i = 0; i < lines.length; i++) {
+                const ln = lines[i]
+                if (re ? re.test(ln) : ln.toLowerCase().includes(q)) {
+                    out.push({ file: rel, line: i + 1, text: ln.trim().slice(0, 300) })
+                    if (out.length >= maxResults) break
+                }
+            }
+        }
+    }
+    return out
+}
+
+export function searchCode({ repoRoot, resolveRg }, { query, is_regex = false, max_results = 40, glob } = {}) {
+    if (!query) return 'Provide a "query" string.'
+    if (!repoRoot || !existsSync(repoRoot)) return 'Source search unavailable: repo root not provided to this MCP server.'
+    const max = Math.max(1, Math.min(200, Number(max_results) || 40))
+    const opts = { isRegex: !!is_regex, glob: glob || null, maxResults: max }
+    let matches = rgSearch(repoRoot, resolveRg, query, opts)
+    const engine = matches ? 'ripgrep' : 'node'
+    if (!matches) matches = nodeGrep(repoRoot, query, opts)
+    const what = is_regex ? `/${query}/i` : `"${query}"`
+    if (!matches.length) return `No matches for ${what}${glob ? ` in ${glob}` : ''}.`
+    return [
+        `${matches.length} match${matches.length === 1 ? '' : 'es'} for ${what}${glob ? ` (glob ${glob})` : ''} [${engine}]:`,
+        ...matches.map((m) => `  ${m.file}:${m.line}:  ${m.text}`),
+    ].join('\n')
+}
+
+export function readSource({ repoRoot, resolveNode, isSymbol }, g, { label, path, start_line, before = 3, after = 40 } = {}) {
+    if (!repoRoot || !existsSync(repoRoot)) return 'Source read unavailable: repo root not provided to this MCP server.'
+    let file = null
+    let focusLine = null
+    let title
+    // label resolves first; a path alongside it narrows rather than overrides — the node's focus line
+    // survives when both point at the same file (label+path used to silently return the file head).
+    const n = label && g ? resolveNode(g, label) : null
+    if (n) {
+        const nodeFile = String(n.source_file || (isSymbol(n.id) ? String(n.id).split('#')[0] : n.id))
+        if (!path || nodeFile.replace(/\\/g, '/') === String(path).replace(/\\/g, '/')) {
+            file = nodeFile
+            const match = String(n.source_location || '').match(/L(\d+)/)
+            focusLine = match ? Number(match[1]) : null
+            title = `${n.label ?? n.id}  [${n.id}]`
+        }
+    }
+    if (!file) {
+        if (!path) return label ? `No node found matching "${label}".` : 'Provide "label" or "path".'
+        file = String(path)
+        title = file
+    }
+    // explicit anchor wins: window = start_line-before .. start_line+after (how a path read escapes the file head)
+    if (start_line != null && Number(start_line) > 0) focusLine = Math.floor(Number(start_line))
+    const abs = join(repoRoot, file)
+    if (!existsSync(abs)) return `File not found: ${file}`
+    let text
+    try { text = readFileSync(abs, 'utf8') } catch (e) { return `Could not read ${file}: ${e.message}` }
+    const lines = text.split(/\r?\n/)
+    if (focusLine) focusLine = Math.min(focusLine, lines.length) // an anchor past EOF shows the tail, not nothing
+    const b = Math.max(0, Number(before) || 0)
+    const a = Math.max(1, Number(after) || 40)
+    const start = focusLine ? Math.max(1, focusLine - b) : 1
+    const end = focusLine ? Math.min(lines.length, focusLine + a) : Math.min(lines.length, 1 + b + a)
+    const width = String(end).length
+    const body = []
+    for (let i = start; i <= end; i++) body.push(`${focusLine === i ? '>' : ' '}${String(i).padStart(width)}  ${lines[i - 1] ?? ''}`)
+    return [`Source: ${title}`, `${file}  (lines ${start}-${end} of ${lines.length})`, '', ...body].join('\n')
+}

package/src/process.js

@@ -0,0 +1,77 @@
+// Subprocess runner shared by the search engines and security sweeps.
+import { spawn } from "node:child_process";
+
+// Windows: .cmd/.ps1 shims (npx, etc.) can't be spawned directly by Node — they need a
+// shell. With shell:true Node does NOT quote args, so we build a quoted command line ourselves
+// (repo paths contain spaces). POSIX uses the normal argv array, no shell.
+export function winQuote(value) {
+  const s = String(value);
+  return /[\s&()[\]{}^=;!'+,`~|<>"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+export function runCommand(command, args = [], options = {}) {
+  // Windows: .cmd/.ps1/bare-name shims (npx, …) need a cmd.exe shell. But a real .exe
+  // (rg.exe, where.exe) must be spawned DIRECTLY — wrapping an .exe in the shell breaks stdin
+  // piping, which surfaced as "command returned no output".
+  const needsShell = process.platform === "win32" && !/\.exe$/i.test(command);
+  return new Promise((resolve, reject) => {
+    const child = needsShell
+      ? spawn([command, ...args].map(winQuote).join(" "), [], {
+          cwd: options.cwd || undefined,
+          env: { ...process.env, ...(options.env || {}) },
+          shell: true,
+          windowsHide: true
+        })
+      : spawn(command, args, {
+          cwd: options.cwd || undefined,
+          env: { ...process.env, ...(options.env || {}) },
+          windowsHide: true
+        });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let hardTimer = null;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (hardTimer) clearTimeout(hardTimer);
+      fn();
+    };
+    // On timeout, kill the WHOLE process tree. With shell:true the child is cmd.exe; child.kill() would only
+    // kill the shell, leaving npx→node→tool running and the stdio pipes open → 'close' never fires → the
+    // caller hangs forever. taskkill /T kills the tree; SIGKILL group on POSIX.
+    const killTree = () => {
+      if (process.platform === "win32" && child.pid) {
+        try {
+          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true });
+        } catch {
+          try { child.kill(); } catch { /* process may already be gone */ }
+        }
+      } else {
+        try { child.kill("SIGKILL"); } catch { /* process may already be gone */ }
+      }
+      // hard fallback: if 'close' still never fires after the kill, settle anyway so the caller can't hang
+      hardTimer = setTimeout(() => finish(() => reject(new Error("Command timed out"))), 4000);
+    };
+    const timer = options.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          killTree();
+        }, options.timeoutMs)
+      : null;
+
+    child.stdout?.on("data", (chunk) => (stdout += chunk));
+    child.stderr?.on("data", (chunk) => (stderr += chunk));
+    if (options.stdin) {
+      child.stdin.write(options.stdin);
+      child.stdin.end();
+    } else {
+      child.stdin?.end();
+    }
+    child.on("error", (error) => finish(() => reject(error)));
+    child.on("close", (code) => finish(() => (timedOut ? reject(new Error("Command timed out")) : resolve({ stdout, stderr, exitCode: code }))));
+  });
+}