@toolbaux/guardian 0.1.22 → 0.2.0

package/dist/commands/mcp-serve.js

@@ -17,6 +17,21 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline";
+import { spawn } from "node:child_process";
+// ── CLI proxy ──
+// Resolve the guardian CLI binary relative to this file (dist/cli.js).
+const CLI_BIN = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../cli.js");
+/** Run a guardian CLI subcommand and return stdout. */
+function runCli(args) {
+    return new Promise((resolve) => {
+        const proc = spawn(process.execPath, [CLI_BIN, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        proc.stdout.on("data", (d) => { out += d.toString(); });
+        proc.stderr.on("data", (d) => { err += d.toString(); });
+        proc.on("close", () => resolve(out.trim() || err.trim() || "{}"));
+    });
+}
 const metrics = {
     session_start: Date.now(),
     calls: [],
@@ -64,9 +79,11 @@ const metrics = {
         };
     },
 };
-// ── Response cache (dedup repeated queries) ──
+// ── Session flag — written on every guardian tool call so the PreToolUse hook knows guardian is active ──
+const SESSION_FLAG = "/tmp/guardian-last-call";
+// ── Response cache (dedup repeated queries within a session) ──
 const responseCache = new Map();
-const CACHE_TTL = 30_000; // 30s cache
+const CACHE_TTL = 30_000;
 function getCached(key) {
     const entry = responseCache.get(key);
     if (entry && Date.now() - entry.time < CACHE_TTL)
@@ -76,319 +93,100 @@ function getCached(key) {
 function setCache(key, text) {
     responseCache.set(key, { text, time: Date.now() });
 }
-// ── Intelligence loader ──
-let intel = null;
-let intelPath = "";
-let lastLoadTime = 0;
-async function loadIntel() {
-    // Reload if file changed (check every 5s max)
-    const now = Date.now();
-    if (intel && now - lastLoadTime < 5000)
-        return intel;
-    try {
-        const raw = await fs.readFile(intelPath, "utf8");
-        intel = JSON.parse(raw);
-        lastLoadTime = now;
-    }
-    catch {
-        // Return cached or empty
-        if (!intel) {
-            intel = { api_registry: {}, model_registry: {}, service_map: [], frontend_pages: [], meta: { project: "unknown", counts: {} } };
-        }
-    }
-    return intel;
-}
-// ── Function intelligence loader ──
-let funcIntel = null;
-let funcIntelPath = "";
-let funcIntelLoadTime = 0;
-async function loadFuncIntel() {
-    if (!funcIntelPath)
-        return null;
-    const now = Date.now();
-    if (funcIntel && now - funcIntelLoadTime < 5000)
-        return funcIntel;
-    try {
-        const raw = await fs.readFile(funcIntelPath, "utf8");
-        funcIntel = JSON.parse(raw);
-        funcIntelLoadTime = now;
-    }
-    catch {
-        // File may not exist yet — not an error
-    }
-    return funcIntel;
-}
-// ── Helpers ──
-const SKIP_SERVICES = new Set(["str", "dict", "int", "len", "float", "max", "join", "getattr", "lower", "open", "params.append", "updates.append"]);
-function compact(obj) {
-    return JSON.stringify(obj);
-}
-function normalize(p) {
-    return p.replace(/^\.\//, "").replace(/\/\//g, "/");
-}
-function findModule(data, file) {
-    const f = normalize(file);
-    return data.service_map?.find((m) => {
-        const mp = normalize(m.path || "");
-        return mp && (f.startsWith(mp + "/") || f === mp);
-    }) || data.service_map?.find((m) => {
-        // Fallback: match by module ID (handles doubled paths)
-        const mid = normalize(m.id || "");
-        return mid && f.includes(mid);
-    });
-}
-function findEndpointsInFile(data, file) {
-    const f = normalize(file);
-    const basename = path.basename(f);
-    return Object.values(data.api_registry || {}).filter((ep) => {
-        const ef = normalize(ep.file || "");
-        return ef && (f.includes(ef) || ef.includes(f) || ef.endsWith(basename));
-    });
-}
-function findModelsInFile(data, file) {
-    const f = normalize(file);
-    const basename = path.basename(f);
-    return Object.values(data.model_registry || {}).filter((m) => {
-        const mf = normalize(m.file || "");
-        return mf && (f.includes(mf) || mf.includes(f) || mf.endsWith(basename));
-    });
-}
-// ── Tool implementations (compact JSON, no redundancy) ──
+// ── Tool implementations — thin CLI proxies ──
+// All logic lives in `guardian search`. MCP tools are just structured wrappers.
+let specsInputDir = "";
 async function orient() {
-    // Read architecture-context.md first — it has the richest summary
-    const contextPath = path.join(path.dirname(intelPath), "architecture-context.md");
-    try {
-        const raw = await fs.readFile(contextPath, "utf8");
-        // Extract the content between guardian:context markers
-        const match = raw.match(/<!-- guardian:context[^>]*-->([\s\S]*?)<!-- \/guardian:context -->/);
-        if (match) {
-            // Parse the markdown into compact structured data
-            const content = match[1];
-            const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
-            // Extract key sections
-            const desc = raw.match(/Description: (.+)/)?.[1] || "";
-            const codeMap = lines.find((l) => l.startsWith("**Backend:**")) || "";
-            // Module map with exports
-            const moduleLines = lines.filter((l) => l.startsWith("- **backend/") || l.startsWith("- **frontend/"));
-            const modules = moduleLines.map((l) => {
-                const m = l.match(/\*\*([^*]+)\*\*\s*\(([^)]+)\)\s*[—–-]\s*(.*)/);
-                return m ? [m[1], m[2], m[3].slice(0, 60)] : null;
-            }).filter(Boolean);
-            // Dependencies
-            const deps = lines.filter((l) => l.includes("→")).map((l) => l.replace(/^- /, ""));
-            // High-coupling files
-            const coupling = lines.filter((l) => l.match(/score \d/)).map((l) => l.replace(/^- /, ""));
-            // Structural intelligence
-            const si = lines.filter((l) => l.includes("depth=")).map((l) => l.replace(/^- /, ""));
-            // Model-endpoint map
-            const modelEp = lines.filter((l) => l.includes("endpoints) ->")).map((l) => l.replace(/^- /, ""));
-            return compact({
-                desc: desc.slice(0, 120),
-                map: codeMap,
-                modules,
-                deps,
-                coupling: coupling.slice(0, 5),
-                si: si.slice(0, 5),
-                modelEp,
-            });
-        }
-    }
-    catch { }
-    // Fallback: build from codebase-intelligence.json
-    const d = await loadIntel();
-    const c = d.meta?.counts || {};
-    // Compute endpoint counts from api_registry (service_map counts are often 0)
-    const epByMod = {};
-    for (const ep of Object.values(d.api_registry || {})) {
-        epByMod[ep.module] = (epByMod[ep.module] || 0) + 1;
-    }
-    const mods = (d.service_map || []).filter((m) => m.file_count > 0);
-    const topMods = mods
-        .map((m) => ({ ...m, ep_count: epByMod[m.id] || 0 }))
-        .sort((a, b) => b.ep_count - a.ep_count)
-        .slice(0, 6);
-    return compact({
-        p: d.meta?.project,
-        ep: c.endpoints, mod: c.models, pg: c.pages, m: c.modules,
-        top: topMods.map((m) => [m.id, m.ep_count, m.layer]),
-        pages: (d.frontend_pages || []).map((p) => p.path),
-    });
+    return runCli(["search", "--orient", "--input", specsInputDir]);
 }
 async function context(args) {
-    const d = await loadIntel();
-    const t = args.target;
-    // Check if target is an endpoint (e.g. "POST /sessions/start")
-    const epMatch = t.match(/^(GET|POST|PUT|DELETE|PATCH)\s+(.+)$/i);
-    if (epMatch) {
-        const ep = d.api_registry?.[`${epMatch[1].toUpperCase()} ${epMatch[2]}`]
-            || Object.values(d.api_registry || {}).find((e) => e.method === epMatch[1].toUpperCase() && e.path === epMatch[2]);
-        if (!ep)
-            return compact({ err: "not found" });
-        const svcs = (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s));
-        return compact({
-            ep: `${ep.method} ${ep.path}`, h: ep.handler, f: ep.file, m: ep.module,
-            req: ep.request_schema, res: ep.response_schema,
-            calls: svcs, ai: ep.ai_operations?.length || 0,
-        });
-    }
-    // Otherwise treat as file path
-    const file = t.replace(/^\.\//, "");
-    const mod = findModule(d, file);
-    const eps = findEndpointsInFile(d, file);
-    const models = findModelsInFile(d, file);
-    const fileName = path.basename(file, path.extname(file));
-    const calledBy = [];
-    for (const ep of Object.values(d.api_registry || {})) {
-        if (ep.service_calls?.some((s) => s.toLowerCase().includes(fileName.toLowerCase()))) {
-            calledBy.push(`${ep.method} ${ep.path}`);
-        }
-    }
-    const calls = eps.flatMap((ep) => (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s)));
-    return compact({
-        f: file,
-        mod: mod ? [mod.id, mod.layer] : null,
-        ep: eps.map((e) => `${e.method} ${e.path}`),
-        models: models.map((m) => [m.name, m.fields?.length || 0]),
-        calls: [...new Set(calls)],
-        calledBy: calledBy.slice(0, 8),
-    });
+    return runCli(["search", "--file", args.target, "--input", specsInputDir]);
 }
 async function impact(args) {
-    const d = await loadIntel();
-    const file = args.target.replace(/^\.\//, "");
-    const eps = findEndpointsInFile(d, file);
-    const models = findModelsInFile(d, file);
-    const modelNames = new Set(models.map((m) => m.name));
-    const affectedEps = Object.values(d.api_registry || {}).filter((ep) => (ep.request_schema && modelNames.has(ep.request_schema)) ||
-        (ep.response_schema && modelNames.has(ep.response_schema)));
-    const mod = findModule(d, file);
-    const depMods = mod ? (d.service_map || []).filter((m) => m.imports?.includes(mod.id)) : [];
-    const affectedPages = (d.frontend_pages || []).filter((p) => p.api_calls?.some((call) => eps.some((ep) => call.includes(ep.path?.split("{")[0]))));
-    const total = eps.length + affectedEps.length + depMods.length + affectedPages.length;
-    return compact({
-        f: file,
-        risk: total > 5 ? "HIGH" : total > 2 ? "MED" : "LOW",
-        ep: eps.map((e) => `${e.method} ${e.path}`),
-        models: models.map((m) => m.name),
-        affectedEp: affectedEps.map((e) => `${e.method} ${e.path}`),
-        depMods: depMods.map((m) => m.id),
-        pages: affectedPages.map((p) => p.path),
-    });
+    return runCli(["search", "--impact", args.target, "--input", specsInputDir]);
 }
 async function search(args) {
-    const d = await loadIntel();
-    const q = args.query.toLowerCase();
-    // Endpoints: match path, handler, or service calls
-    const eps = Object.values(d.api_registry || {}).filter((ep) => ep.path?.toLowerCase().includes(q) || ep.handler?.toLowerCase().includes(q) ||
-        ep.service_calls?.some((s) => s.toLowerCase().includes(q))).slice(0, 8).map((ep) => `${ep.method} ${ep.path} [${ep.module}]`);
-    // Models: match name or fields
-    const models = Object.values(d.model_registry || {}).filter((m) => m.name?.toLowerCase().includes(q) || m.fields?.some((f) => f.toLowerCase().includes(q))).slice(0, 8).map((m) => `${m.name}:${m.fields?.length}f`);
-    // Modules: match id, imports, or exports
-    const mods = (d.service_map || []).filter((m) => m.id?.toLowerCase().includes(q) ||
-        m.imports?.some((i) => i.toLowerCase().includes(q))).slice(0, 5).map((m) => `${m.id}:${m.file_count}files,${m.endpoint_count}ep [${m.layer}]`);
-    // Exports: match exported symbol names across all modules
-    const exports = [];
-    for (const m of d.service_map || []) {
-        for (const sym of m.exports || []) {
-            if (sym.toLowerCase().includes(q)) {
-                exports.push(`${sym} [${m.id}]`);
+    return runCli(["search", "--query", args.query, "--format", "json", "--backend", "auto", "--input", specsInputDir]);
+}
+async function model(args) {
+    return runCli(["search", "--model", args.name, "--input", specsInputDir]);
+}
+/**
+ * guardian_grep — semantic grep via guardian search.
+ *
+ * Replaces raw Grep tool calls. Runs guardian BM25+vector search and returns
+ * matching symbols (file:line:name) and files, formatted like grep output.
+ * Claude gets richer context (call-graph, authority) with zero token overhead.
+ */
+async function grep(args) {
+    const raw = await runCli([
+        "search", "--query", args.query, "--format", "json", "--backend", "auto", "--input", specsInputDir,
+    ]);
+    try {
+        const data = JSON.parse(raw);
+        const lines = [`guardian_grep("${args.query}")`];
+        if (data.symbols?.length) {
+            lines.push("\nSymbols (file:line: name):");
+            for (const s of data.symbols.slice(0, 25)) {
+                lines.push(`  ${s.file}:${s.line}: ${s.name}`);
             }
         }
-    }
-    // Files: match file paths across all modules
-    const files = [];
-    for (const m of d.service_map || []) {
-        for (const f of m.files || []) {
-            if (f.toLowerCase().includes(q)) {
-                files.push(`${f} [${m.id}]`);
+        if (data.files?.length) {
+            lines.push("\nFiles:");
+            for (const f of data.files.slice(0, 15)) {
+                lines.push(`  ${f.file_path}`);
             }
         }
+        if (lines.length === 1)
+            lines.push("  (no matches — try a different query)");
+        return lines.join("\n");
     }
-    // Enums: match name or values
-    const enums = Object.values(d.enum_registry || {}).filter((e) => e.name?.toLowerCase().includes(q) || e.values?.some((v) => v.toLowerCase().includes(q))).slice(0, 5).map((e) => `${e.name}:${e.values?.length}vals [${e.file}]`);
-    // Background tasks: match name or kind
-    const tasks = (d.background_tasks || []).filter((t) => t.name?.toLowerCase().includes(q) || t.kind?.toLowerCase().includes(q)).slice(0, 5).map((t) => `${t.name} [${t.kind}] ${t.file}`);
-    // Frontend pages: match path or component
-    const pages = (d.frontend_pages || []).filter((p) => p.path?.toLowerCase().includes(q) || p.component?.toLowerCase().includes(q) ||
-        p.api_calls?.some((c) => c.toLowerCase().includes(q))).slice(0, 5).map((p) => `${p.path} → ${p.component}`);
-    // Functions: ranked search across names, literals, calls — capped at 10 to prevent flooding
-    const fnHits = [];
-    const fi = await loadFuncIntel();
-    if (fi) {
-        // Build a field map: file → field names (augments fn hits with model fields)
-        const fileToFields = new Map();
-        for (const m of Object.values(d.model_registry || {})) {
-            if (!m.file)
-                continue;
-            const existing = fileToFields.get(m.file) ?? [];
-            fileToFields.set(m.file, [...existing, ...(m.fields ?? [])]);
-        }
-        const scored = [];
-        const seen = new Set();
-        for (const fn of (fi.functions ?? [])) {
-            const nameNorm = (fn.name ?? "").toLowerCase();
-            const fileNorm = (fn.file ?? "").toLowerCase();
-            const callsNorm = (fn.calls ?? []).map((c) => c.toLowerCase());
-            const litsNorm = [...(fn.stringLiterals ?? []), ...(fn.regexPatterns ?? [])].map((l) => l.toLowerCase());
-            let score = 0;
-            if (nameNorm === q)
-                score = 1.0;
-            else if (nameNorm.includes(q))
-                score = 0.7;
-            else if (callsNorm.some((c) => c.includes(q)))
-                score = 0.5;
-            else if (litsNorm.some((l) => l.includes(q)))
-                score = 0.3;
-            else if (fileNorm.includes(q))
-                score = 0.2;
-            if (score > 0) {
-                scored.push({ fn, score });
-                seen.add(`${fn.file}:${fn.name}`);
-            }
-        }
-        // Also surface literal_index hits not already captured
-        const litIndex = fi.literal_index ?? {};
-        for (const [key, hits] of Object.entries(litIndex)) {
-            if (!key.includes(q))
-                continue;
-            for (const h of hits) {
-                const uid = `${h.file}:${h.function}`;
-                if (seen.has(uid))
-                    continue;
-                seen.add(uid);
-                const fn = fi.functions.find((f) => f.file === h.file && f.name === h.function);
-                scored.push({ fn: fn ?? { name: h.function, file: h.file, lines: [h.line, h.line], calls: [], stringLiterals: [], regexPatterns: [] }, score: 0.25 });
-            }
-        }
-        // Sort by score desc, take top 10
-        scored.sort((a, b) => b.score - a.score);
-        const projectRoot = process.cwd();
-        for (const { fn } of scored.slice(0, 10)) {
-            const relFile = fn.file?.startsWith("/") ? require("path").relative(projectRoot, fn.file) : fn.file;
-            const fields = fileToFields.get(fn.file) ?? [];
-            const fieldSuffix = fields.length > 0 ? ` fields:${fields.slice(0, 5).join(",")}` : "";
-            fnHits.push(`${fn.name} [${relFile}:${fn.lines?.[0]}]${fieldSuffix}`);
-        }
+    catch {
+        return raw; // passthrough if search returns plain text
     }
-    return compact({
-        ep: eps, mod: models, m: mods,
-        exports: exports.slice(0, 10),
-        files: files.slice(0, 8),
-        enums, tasks, pages,
-        ...(fnHits.length > 0 ? { fns: fnHits } : {}),
-    });
 }
-async function model(args) {
-    const d = await loadIntel();
-    const m = d.model_registry?.[args.name];
-    if (!m)
-        return compact({ err: "not found" });
-    const usedBy = Object.values(d.api_registry || {}).filter((ep) => ep.request_schema === args.name || ep.response_schema === args.name).map((ep) => `${ep.method} ${ep.path}`);
-    return compact({
-        name: m.name, fw: m.framework, f: m.file,
-        fields: m.fields, rels: m.relationships,
-        usedBy,
-    });
+/**
+ * guardian_glob — semantic file discovery via guardian search.
+ *
+ * Replaces raw Glob tool calls. Extracts meaningful keywords from the glob
+ * pattern and searches the guardian index for matching files. Falls back to
+ * guiding the user toward a more descriptive query for pure extension patterns.
+ */
+async function glob(args) {
+    // Extract keywords: "src/auth/**/*.ts" → "auth", "src/middleware/error*" → "middleware error"
+    const keywords = args.pattern
+        .replace(/\*\*?/g, " ")
+        .replace(/\.\w+$/, "") // strip trailing extension
+        .replace(/[[\]{}]/g, " ")
+        .split(/[/\s]+/)
+        .filter(s => s.length > 2 && !/^(src|lib|dist|app|index)$/.test(s))
+        .join(" ")
+        .trim();
+    if (!keywords) {
+        return [
+            `guardian_glob("${args.pattern}"): pattern has no meaningful keywords.`,
+            `Use guardian_search with a descriptive query instead, e.g.:`,
+            `  guardian_search("TypeScript source files") — or describe what you're looking for.`,
+        ].join("\n");
+    }
+    const raw = await runCli([
+        "search", "--query", keywords, "--format", "json", "--backend", "auto", "--input", specsInputDir,
+    ]);
+    try {
+        const data = JSON.parse(raw);
+        const files = data.files ?? [];
+        const lines = [
+            `guardian_glob("${args.pattern}") — searched: "${keywords}"`,
+            `\nMatching files:`,
+            ...files.slice(0, 20).map(f => `  ${f.file_path}`),
+        ];
+        if (files.length === 0)
+            lines.push("  (no matches)");
+        return lines.join("\n");
+    }
+    catch {
+        return raw;
+    }
 }
 // ── MCP protocol ──
 const TOOLS = [
@@ -446,6 +244,39 @@ const TOOLS = [
         description: "MCP usage stats for this session. Call at end to evaluate guardian's usefulness.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "guardian_grep",
+        description: [
+            "Semantic grep — find symbols and files matching a keyword or pattern.",
+            "Use INSTEAD of the Grep tool. Returns matching function/class names with file:line locations.",
+            "Backed by BM25 + call-graph authority so relevant source definitions surface first.",
+            "Example: guardian_grep('validate token') → auth.py:42: validate_token, middleware.py:18: check_jwt",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Keyword or phrase to search for (natural language OK)" },
+                path: { type: "string", description: "Optional: restrict to files under this path prefix" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "guardian_glob",
+        description: [
+            "Semantic file discovery — find files matching a path pattern.",
+            "Use INSTEAD of the Glob tool. Extracts keywords from the pattern and searches the guardian index.",
+            "Example: guardian_glob('src/auth/**/*.ts') → searches for 'auth typescript' files.",
+            "For pure extension globs with no path context, use guardian_search with a descriptive query.",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "Glob pattern (e.g. 'src/auth/**/*.ts', '**/middleware*')" },
+            },
+            required: ["pattern"],
+        },
+    },
 ];
 const TOOL_HANDLERS = {
     guardian_orient: orient,
@@ -453,7 +284,9 @@ const TOOL_HANDLERS = {
     guardian_impact: impact,
     guardian_search: search,
     guardian_model: model,
-    guardian_metrics: async () => compact(metrics.summary()),
+    guardian_metrics: async () => JSON.stringify(metrics.summary()),
+    guardian_grep: grep,
+    guardian_glob: glob,
 };
 function respond(id, result) {
     const msg = JSON.stringify({ jsonrpc: "2.0", id, result });
@@ -514,6 +347,8 @@ async function handleRequest(req) {
                 const result = await handler(toolArgs);
                 setCache(cacheKey, result);
                 metrics.record(toolName, toolArgs, result, false);
+                // Write session flag so the PreToolUse hook knows guardian was called recently
+                fs.writeFile(SESSION_FLAG, Date.now().toString(), "utf8").catch(() => { });
                 respond(req.id, {
                     content: [{ type: "text", text: result }],
                 });
@@ -537,30 +372,34 @@ async function handleRequest(req) {
 export async function runMcpServe(options) {
     const specsDir = path.resolve(options.specs);
     const quiet = options.quiet ?? false;
-    intelPath = path.join(specsDir, "machine", "codebase-intelligence.json");
-    funcIntelPath = path.join(specsDir, "machine", "function-intelligence.json");
-    // Pre-load intelligence
-    await loadIntel();
-    await loadFuncIntel();
+    specsInputDir = specsDir;
     // Log to stderr (stdout is for MCP protocol)
     if (!quiet) {
-        process.stderr.write(`Guardian MCP server started. Intelligence: ${intelPath}\n`);
+        process.stderr.write(`Guardian MCP server started. Specs: ${specsDir}\n`);
         process.stderr.write(`Tools: ${TOOLS.map((t) => t.name).join(", ")}\n`);
     }
     // Read JSON-RPC messages from stdin, line by line
     const rl = readline.createInterface({ input: process.stdin });
-    rl.on("line", async (line) => {
+    // Track in-flight async handlers so we can drain before exit.
+    // Previously all handlers were instant (in-process); now they spawn subprocesses.
+    const pending = [];
+    rl.on("line", (line) => {
         if (!line.trim())
             return;
-        try {
-            const req = JSON.parse(line);
-            await handleRequest(req);
-        }
-        catch (err) {
-            respondError(null, -32700, `Parse error: ${err.message}`);
-        }
+        const p = (async () => {
+            try {
+                const req = JSON.parse(line);
+                await handleRequest(req);
+            }
+            catch (err) {
+                respondError(null, -32700, `Parse error: ${err.message}`);
+            }
+        })();
+        pending.push(p);
     });
     rl.on("close", async () => {
+        // Drain all in-flight handlers before persisting metrics and exiting.
+        await Promise.allSettled(pending);
         // Persist session metrics to .specs/machine/mcp-metrics.jsonl
         const metricsPath = path.join(specsDir, "machine", "mcp-metrics.jsonl");
         try {