@toolbaux/guardian 0.1.14 → 0.1.16

package/dist/cli.js

@@ -343,9 +343,11 @@ program
     .command("mcp-serve")
     .description("Start Guardian MCP server for Claude Code / Cursor integration")
     .option("--specs <dir>", "Specs directory", ".specs")
+    .option("--quiet", "Suppress stderr output (for clients that merge streams)", false)
     .action(async (options) => {
     await runMcpServe({
         specs: options.specs,
+        quiet: options.quiet,
     });
 });
 program.parseAsync().catch((error) => {

package/dist/commands/init.js

@@ -6,7 +6,8 @@
  *   2. .specs/ directory
  *   3. Pre-commit hook that auto-runs extract + context injection
  *   4. Injects guardian context block into CLAUDE.md
- *   5. Adds .specs/ to .gitignore exclusion (tracked by default)
+ *   5. Claude Code hooks (.claude/settings.json + MCP-first enforcement)
+ *   6. Adds .specs/ to .gitignore exclusion (tracked by default)
  *
  * Safe to run multiple times — only creates what's missing.
  */
@@ -22,6 +23,26 @@ const DEFAULT_CONFIG = {
         mode: "full",
     },
 };
+const CLAUDE_CODE_HOOK_SCRIPT = `#!/bin/bash
+# Guardian MCP-first hook — ensures AI tools use Guardian MCP before reading source files.
+# Installed by: guardian init
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+cat >&2 <<BLOCK
+BLOCKED: Use Guardian MCP tools before reading source files.
+
+Use these MCP tools first:
+  - guardian_orient  — get codebase overview
+  - guardian_search  — find features by keyword
+  - guardian_context — deep dive into a specific area
+
+Then you can read individual files as needed.
+BLOCK
+
+exit 2
+`;
 const HOOK_SCRIPT = `#!/bin/sh
 # guardian pre-commit hook — keeps architecture context fresh
 # Installed by: guardian init
@@ -157,7 +178,9 @@ export async function runInit(options) {
         await fs.writeFile(claudeMdPath, content, "utf8");
         console.log("  ✓ Created CLAUDE.md with guardian context block");
     }
-    // 5. Run initial extract + context injection
+    // 5. Set up Claude Code hooks (.claude/settings.json + hook script)
+    await setupClaudeCodeHooks(root, specsDir);
+    // 6. Run initial extract + context injection
     console.log("\n  Running initial extraction...");
     try {
         const { runExtract } = await import("./extract.js");
@@ -208,3 +231,62 @@ async function dirExists(p) {
         return false;
     }
 }
+async function setupClaudeCodeHooks(root, specsDir) {
+    const claudeDir = path.join(root, ".claude");
+    const hooksDir = path.join(claudeDir, "hooks");
+    const settingsPath = path.join(claudeDir, "settings.json");
+    const hookScriptPath = path.join(hooksDir, "mcp-first.sh");
+    await fs.mkdir(hooksDir, { recursive: true });
+    // Write the hook script
+    if (!(await fileExists(hookScriptPath))) {
+        await fs.writeFile(hookScriptPath, CLAUDE_CODE_HOOK_SCRIPT, "utf8");
+        await fs.chmod(hookScriptPath, 0o755);
+        console.log("  ✓ Created Claude Code MCP-first hook (.claude/hooks/mcp-first.sh)");
+    }
+    else {
+        console.log("  · Claude Code hook already exists");
+    }
+    // Write or merge .claude/settings.json
+    let settings = {};
+    if (await fileExists(settingsPath)) {
+        try {
+            settings = JSON.parse(await fs.readFile(settingsPath, "utf8"));
+        }
+        catch {
+            // Corrupted file — overwrite
+        }
+    }
+    // Add MCP server config
+    if (!settings.mcpServers)
+        settings.mcpServers = {};
+    const mcpServers = settings.mcpServers;
+    if (!mcpServers.guardian) {
+        mcpServers.guardian = {
+            command: "guardian",
+            args: ["mcp-serve", "--specs", specsDir],
+        };
+    }
+    // Add PreToolUse hook
+    const hookEntry = {
+        matcher: "Read|Glob|Grep",
+        hooks: [
+            {
+                type: "command",
+                if: "Read(//*/src/*)|Glob(*src*)|Grep(*src*)",
+                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/mcp-first.sh',
+            },
+        ],
+    };
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    if (!hooks.PreToolUse) {
+        hooks.PreToolUse = [hookEntry];
+        console.log("  ✓ Configured Claude Code PreToolUse hook in .claude/settings.json");
+    }
+    else {
+        console.log("  · Claude Code PreToolUse hook already configured");
+    }
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    console.log("  ✓ Updated .claude/settings.json (MCP server + hooks)");
+}

package/dist/commands/mcp-serve.js

@@ -258,11 +258,45 @@ async function impact(args) {
 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`);
-    const mods = (d.service_map || []).filter((m) => m.id?.toLowerCase().includes(q)).slice(0, 5).map((m) => `${m.id}:${m.endpoint_count}ep`);
-    return compact({ ep: eps, mod: models, m: mods });
+    // 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}]`);
+            }
+        }
+    }
+    // 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}]`);
+            }
+        }
+    }
+    // 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}`);
+    return compact({
+        ep: eps, mod: models, m: mods,
+        exports: exports.slice(0, 10),
+        files: files.slice(0, 8),
+        enums, tasks, pages,
+    });
 }
 async function model(args) {
     const d = await loadIntel();
@@ -307,7 +341,7 @@ const TOOLS = [
     },
     {
         name: "guardian_search",
-        description: "Find endpoints, models, modules by keyword. Returns compact one-line results.",
+        description: "Find endpoints, models, modules, exported symbols, files, enums, tasks, and pages by keyword. Returns compact one-line results.",
         inputSchema: {
             type: "object",
             properties: {
@@ -422,12 +456,15 @@ async function handleRequest(req) {
 // ── Entry point ──
 export async function runMcpServe(options) {
     const specsDir = path.resolve(options.specs);
+    const quiet = options.quiet ?? false;
     intelPath = path.join(specsDir, "machine", "codebase-intelligence.json");
     // Pre-load intelligence
     await loadIntel();
     // Log to stderr (stdout is for MCP protocol)
-    process.stderr.write(`Guardian MCP server started. Intelligence: ${intelPath}\n`);
-    process.stderr.write(`Tools: ${TOOLS.map((t) => t.name).join(", ")}\n`);
+    if (!quiet) {
+        process.stderr.write(`Guardian MCP server started. Intelligence: ${intelPath}\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) => {
@@ -450,10 +487,12 @@ export async function runMcpServe(options) {
                 session_end: new Date().toISOString(),
             });
             await fs.appendFile(metricsPath, entry + "\n", "utf8");
-            process.stderr.write(`Guardian metrics saved to ${metricsPath}\n`);
+            if (!quiet)
+                process.stderr.write(`Guardian metrics saved to ${metricsPath}\n`);
         }
         catch { }
-        process.stderr.write("Guardian MCP server stopped.\n");
+        if (!quiet)
+            process.stderr.write("Guardian MCP server stopped.\n");
         process.exit(0);
     });
 }

package/dist/extract/codebase-intel.js

@@ -68,16 +68,21 @@ export function buildCodebaseIntelligence(architecture, ux) {
             values: en.values,
         };
     }
-    // service_map
-    const serviceMap = architecture.modules.map((m) => ({
-        id: m.id,
-        path: m.path,
-        type: m.type,
-        layer: m.layer,
-        file_count: m.files.length,
-        endpoint_count: m.endpoints.length,
-        imports: m.imports,
-    }));
+    // service_map (with exports and files for search)
+    const serviceMap = architecture.modules.map((m) => {
+        const allExports = (m.exports || []).flatMap((e) => (e.exports || []).map((x) => x.name));
+        return {
+            id: m.id,
+            path: m.path,
+            type: m.type,
+            layer: m.layer,
+            file_count: m.files.length,
+            endpoint_count: m.endpoints.length,
+            imports: m.imports,
+            exports: [...new Set(allExports)],
+            files: m.files,
+        };
+    });
     // frontend_pages
     const frontendPages = ux.pages.map((p) => ({
         path: p.path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolbaux/guardian",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
   "keywords": [