@toolbaux/guardian 0.1.23 → 0.2.1

package/README.md

@@ -41,21 +41,24 @@ Developer writes code
     ↓ (save)
 VSCode extension (5s debounce)
     ↓
-guardian extract → .specs/
-guardian generate --ai-context → .specs/
-guardian context → CLAUDE.md (between markers)
+guardian extract → .specs/ + guardian.db (BM25 search index)
+guardian generate --ai-context → reads from guardian.db, writes CLAUDE.md
 Status bar: "✓ Guardian: stable · 35 ep · 8 pg"
     ↓ (git commit)
 Pre-commit hook: extract + context → auto-staged
     ↓
-Claude Code / Cursor reads CLAUDE.md → fresh architecture context
+Claude Code reads CLAUDE.md at session start
+Claude Code calls MCP tools (guardian_search, guardian_grep, guardian_glob…)
+    ↓ fresh, indexed context on every query
 ```
 
 After `guardian init`, your project gets:
-- `.specs/` directory with architecture snapshots
+- `.specs/` directory with architecture snapshots + `guardian.db` (SQLite search index)
 - `CLAUDE.md` with auto-injected context (refreshed on every save and commit)
 - Pre-commit hook that keeps context fresh automatically
-- `guardian.config.json` for project settings (roots auto-detected at runtime)
+- `.mcp.json` wiring Claude Code and Cursor to Guardian's MCP server
+- `guardian.config.json` with a unique `project_id` and auto-detected roots
+- MCP-first hook: Claude Code is nudged to call `guardian_search` before reading source files
 
 ## Claude Code / Cursor Integration
 
@@ -85,16 +88,18 @@ The block between markers is replaced on every save (VSCode extension) and every
 
 Guardian includes an MCP server that Claude Code and Cursor connect to automatically. The VSCode extension sets this up on first activation — no manual config needed.
 
-**6 compact tools available to AI:**
+**8 compact tools available to AI:**
 
 | Tool | Tokens | Purpose |
 |------|--------|---------|
 | `guardian_orient` | ~100 | Project summary at session start |
 | `guardian_context` | ~50-80 | File or endpoint dependencies before editing |
 | `guardian_impact` | ~30 | What breaks if you change a file |
-| `guardian_search` | ~70 | Find endpoints, models, modules by keyword |
+| `guardian_search` | ~70 | Find endpoints, models, modules, and functions by keyword |
 | `guardian_model` | ~90 | Full field details (only when needed) |
 | `guardian_metrics` | ~50 | Session usage stats |
+| `guardian_grep` | ~40 | Semantic grep — search symbols and literals across the codebase |
+| `guardian_glob` | ~30 | Semantic file discovery — find files by pattern with module context |
 
 All responses are compact JSON — no pretty-printing, no verbose keys. Repeated calls are cached (30s TTL). Usage metrics tracked per session.
 
@@ -113,6 +118,19 @@ All responses are compact JSON — no pretty-printing, no verbose keys. Repeated
 
 > **Note:** After `.mcp.json` is created or modified, you must **restart your Claude Code / Cursor session** (or reload the VSCode window) for the MCP server to connect. MCP config is only read at session start.
 
+### MCP-First Hook
+
+`guardian init` also installs a Claude Code hook that encourages AI tools to call Guardian before reading source files directly. The hook is session-scoped — once any `guardian_*` tool is called, file reads are unblocked for the rest of the session. No repeated interruptions.
+
+The block message tells Claude exactly what to call:
+```
+Call one of these first:
+  guardian_search("your query")  — find files/symbols/endpoints by keyword
+  guardian_grep("pattern")       — semantic grep (replaces Grep tool)
+  guardian_glob("src/auth/**")   — semantic file discovery (replaces Glob tool)
+  guardian_orient()              — get codebase overview
+```
+
 ## VSCode Extension
 
 Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=toolbaux.toolbaux-guardian):
@@ -137,14 +155,21 @@ Cmd+Shift+P → "Extensions: Install from VSIX"
 ## Key Commands
 
 ```bash
-# One-time setup — creates config, .specs/, pre-commit hook, CLAUDE.md
+# One-time setup — config, .specs/, guardian.db, pre-commit hook, .mcp.json, CLAUDE.md
 guardian init
 
-# Extract architecture (run after major changes, or let the hook do it)
+# Extract architecture + build search index (guardian.db built automatically)
 guardian extract
 
-# Search your codebase by concept
+# Extract without DB (CI environments that don't need search)
+guardian extract --backend file
+
+# Search your codebase by concept (uses guardian.db when available)
 guardian search --query "session"
+guardian search --query "auth" --types functions,endpoints
+
+# Inject fresh context into CLAUDE.md
+guardian context --output CLAUDE.md
 
 # Compute architectural drift
 guardian drift
@@ -229,19 +254,20 @@ npm install && npm run build && npm link
 
 ```bash
 guardian init                          # config, .specs dir, pre-commit hook, CLAUDE.md
-guardian extract                       # full architecture + UX snapshots + docs
-guardian extract --backend sqlite      # same + builds guardian.db with FTS index
+guardian extract                       # full architecture + UX snapshots + guardian.db (default: sqlite)
+guardian extract --backend file        # file-only mode, skips guardian.db
 guardian generate --ai-context         # compact ~3K token AI context only
 ```
 
 ### Search & Context
 
 ```bash
-guardian search --query "session"                  # search models, endpoints, components
-guardian search --query "auth" --types models,endpoints
-guardian context --focus "auth"                     # focused AI context block
-guardian context --output CLAUDE.md                 # inject between auto-context markers
-guardian summary                                   # executive summary
+guardian search --query "session"                        # search models, endpoints, components, functions
+guardian search --query "auth" --types models,endpoints  # filter by type
+guardian search --query "validate token" --types functions  # function-level search (uses guardian.db)
+guardian context --focus "auth"                          # focused AI context block
+guardian context --output CLAUDE.md                      # inject between auto-context markers
+guardian summary                                         # executive summary
 ```
 
 ### Architectural Metrics
@@ -283,11 +309,16 @@ guardian feature-context --spec feature-specs/billing.yaml
 
 ```json
 {
+  "project_id": "auto-generated-uuid",
   "project": {
     "description": "Short product description for generated docs",
     "backendRoot": "./backend",
     "frontendRoot": "./frontend"
   },
+  "ignore": {
+    "directories": ["bench-repos", "fixtures", "vendor"],
+    "paths": ["src/generated"]
+  },
   "frontend": {
     "routeDirs": ["app"],
     "aliases": { "@": "./frontend" }
@@ -309,6 +340,8 @@ guardian feature-context --spec feature-specs/billing.yaml
 }
 ```
 
+> **Tip:** Use `ignore.directories` to exclude directories that Guardian indexes but aren't part of your project (e.g. benchmark repos, vendor directories, generated code). Guardian scans all source files under the project root by design — configure ignores to keep the search index clean.
+
 </details>
 
 <details>
@@ -316,13 +349,15 @@ guardian feature-context --spec feature-specs/billing.yaml
 
 ```
 .specs/
+├── guardian.db                      ← SQLite search index (BM25 + function call graph)
 ├── machine/
 │   ├── architecture-context.md      ← AI context (~3K tokens)
 │   ├── architecture.snapshot.yaml   ← full architecture snapshot
 │   ├── ux.snapshot.yaml             ← frontend components + pages
 │   ├── codebase-intelligence.json   ← unified registry
-│   ├── drift.report.json            ← drift metrics
-│   ├── constraints.json             ← duplicates, cycles
+│   ├── function-intelligence.json   ← function call graph + literal index
+│   ├── structural-intelligence.json ← depth/complexity per module
+│   ├── drift.heatmap.json           ← file-level change frequency
 │   └── docs/                        ← generated markdown docs
 ├── human/
 │   ├── product-document.md          ← LLM-powered product doc

package/dist/cli.js

@@ -62,7 +62,7 @@ program
     .option("--no-file-graph", "Exclude file-level dependency graph")
     .option("--config <path>", "Path to guardian.config.json")
     .option("--docs-mode <mode>", "Docs mode (lean|full)")
-    .option("--backend <backend>", "Storage backend: 'file' (default) or 'sqlite' (also builds guardian.db + FTS index)")
+    .option("--backend <backend>", "Storage backend: 'sqlite' (default, builds guardian.db + FTS index) or 'file'")
     .action(async (projectRoot, options) => {
     await runExtract({
         projectRoot,
@@ -349,16 +349,12 @@ program
     .command("init")
     .description("Initialize guardian for a project (config, .specs dir, pre-commit hook, CLAUDE.md)")
     .argument("[projectRoot]", "Repo or project root", process.cwd())
-    .option("--backend-root <path>", "Path to backend root")
-    .option("--frontend-root <path>", "Path to frontend root")
     .option("--output <path>", "Output directory", DEFAULT_SPECS_DIR)
     .option("--skip-hook", "Skip pre-commit hook installation", false)
-    .option("--backend <backend>", "Storage backend: 'file' (default) or 'sqlite' (builds guardian.db + FTS index)")
+    .option("--backend <backend>", "Storage backend: 'sqlite' (default) or 'file'")
     .action(async (projectRoot, options) => {
     await runInit({
         projectRoot,
-        backendRoot: options.backendRoot,
-        frontendRoot: options.frontendRoot,
         output: options.output,
         skipHook: options.skipHook ?? false,
         backend: options.backend,

package/dist/commands/context.js

@@ -5,21 +5,90 @@ import { loadArchitectureDiff, loadHeatmap } from "../extract/compress.js";
 import { renderContextBlock } from "../extract/context-block.js";
 import { resolveMachineInputDir } from "../output-layout.js";
 import { DEFAULT_SPECS_DIR } from "../config.js";
+import { SqliteSpecsStore, DB_FILENAME } from "../db/sqlite-specs-store.js";
+/** Open a SqliteSpecsStore if guardian.db exists, return null otherwise. */
+async function tryOpenStore(specsDir) {
+    const dbPath = path.join(specsDir, DB_FILENAME);
+    try {
+        await fs.stat(dbPath);
+        const store = new SqliteSpecsStore(specsDir);
+        await store.init();
+        return store;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reconstruct the SI report shape renderContextBlock needs from module_metrics rows. */
+function siFromMetrics(rows) {
+    return rows.map(r => ({
+        feature: r.module,
+        structure: { nodes: r.nodes, edges: r.edges },
+        metrics: { depth: 0, fanout_avg: 0, fanout_max: 0, density: 0, has_cycles: false },
+        scores: { depth_score: 0, fanout_score: 0, density_score: 0, cycle_score: 0, query_score: 0 },
+        confidence: { value: r.confidence, level: r.confidence_level },
+        ambiguity: { level: "LOW" },
+        classification: {
+            depth_level: r.depth_level,
+            propagation: r.propagation,
+            compressible: r.compressible,
+        },
+        recommendation: {
+            primary: { pattern: r.pattern, confidence: r.confidence },
+            fallback: { pattern: "", condition: "" },
+            avoid: [],
+        },
+        guardrails: { enforce_if_confidence_above: 0.7 },
+        override: { allowed: true, requires_reason: true },
+    }));
+}
 export async function runContext(options) {
     const inputDir = await resolveMachineInputDir(options.input || DEFAULT_SPECS_DIR);
-    const { architecture, ux } = await loadSnapshots(inputDir);
+    // inputDir resolves to .specs/machine/; DB lives one level up at .specs/guardian.db
+    const specsDir = path.dirname(inputDir);
+    const store = await tryOpenStore(specsDir);
+    let architecture;
+    let ux;
+    let si;
+    try {
+        // ── Load snapshots: DB first, file fallback ─────────────────────────────
+        if (store) {
+            const archEntry = await store.readSpec("architecture.snapshot");
+            const uxEntry = await store.readSpec("ux.snapshot");
+            if (archEntry && uxEntry) {
+                architecture = yaml.load(archEntry.content);
+                ux = yaml.load(uxEntry.content);
+            }
+            else {
+                ({ architecture, ux } = await loadSnapshotsFromFiles(inputDir));
+            }
+        }
+        else {
+            ({ architecture, ux } = await loadSnapshotsFromFiles(inputDir));
+        }
+        // ── Load SI reports: module_metrics table first, file fallback ──────────
+        if (store) {
+            const rows = store.readModuleMetrics();
+            if (rows.length > 0) {
+                si = siFromMetrics(rows);
+            }
+        }
+        if (!si) {
+            try {
+                const siRaw = await fs.readFile(path.join(inputDir, "structural-intelligence.json"), "utf8");
+                si = JSON.parse(siRaw);
+            }
+            catch { /* not available */ }
+        }
+    }
+    finally {
+        if (store)
+            await store.close();
+    }
     const [diff, heatmap] = await Promise.all([
         loadArchitectureDiff(inputDir),
         loadHeatmap(inputDir)
     ]);
-    // Load structural intelligence if available
-    let si;
-    try {
-        const siPath = path.join(inputDir, "structural-intelligence.json");
-        const siRaw = await fs.readFile(siPath, "utf8");
-        si = JSON.parse(siRaw);
-    }
-    catch { /* not available */ }
     const content = renderContextBlock(architecture, ux, {
         focusQuery: options.focus,
         maxLines: normalizeMaxLines(options.maxLines),
@@ -38,16 +107,18 @@ export async function runContext(options) {
     await fs.writeFile(outputPath, next, "utf8");
     console.log(`Wrote ${outputPath}`);
 }
-async function loadSnapshots(inputDir) {
+async function loadSnapshotsFromFiles(inputDir) {
     const architecturePath = path.join(inputDir, "architecture.snapshot.yaml");
     const uxPath = path.join(inputDir, "ux.snapshot.yaml");
-    let architectureRaw;
-    let uxRaw;
     try {
-        [architectureRaw, uxRaw] = await Promise.all([
+        const [architectureRaw, uxRaw] = await Promise.all([
             fs.readFile(architecturePath, "utf8"),
             fs.readFile(uxPath, "utf8")
         ]);
+        return {
+            architecture: yaml.load(architectureRaw),
+            ux: yaml.load(uxRaw)
+        };
     }
     catch (error) {
         if (error.code === "ENOENT") {
@@ -55,10 +126,6 @@ async function loadSnapshots(inputDir) {
         }
         throw error;
     }
-    return {
-        architecture: yaml.load(architectureRaw),
-        ux: yaml.load(uxRaw)
-    };
 }
 async function readIfExists(filePath) {
     try {
@@ -75,37 +142,28 @@ function stripExistingSpecGuardBlocks(content) {
         .replace(/<!-- guardian:auto-context -->[\s\S]*?<!-- \/guardian:auto-context -->/g, "<!-- guardian:auto-context -->\n<!-- /guardian:auto-context -->")
         .replace(/\n{3,}/g, "\n\n");
 }
-/**
- * Inject context into a file that has <!-- guardian:auto-context --> markers.
- * Replaces content between the markers instead of appending.
- */
 function injectIntoAutoContext(existing, contextBlock) {
     const marker = "<!-- guardian:auto-context -->";
     const endMarker = "<!-- /guardian:auto-context -->";
     if (!existing.includes(marker)) {
-        // No auto-context markers — fall back to append behavior
         const cleaned = stripExistingSpecGuardBlocks(existing).trim();
         return cleaned.length > 0 ? `${cleaned}\n\n${contextBlock}\n` : `${contextBlock}\n`;
     }
-    // Replace content between markers
     const startIdx = existing.indexOf(marker);
     const endIdx = existing.indexOf(endMarker);
-    if (startIdx === -1 || endIdx === -1) {
+    if (startIdx === -1 || endIdx === -1)
         return existing;
-    }
     const before = existing.slice(0, startIdx + marker.length);
     const after = existing.slice(endIdx);
     return `${before}\n${contextBlock}\n${after}`;
 }
 function normalizeMaxLines(value) {
-    if (typeof value === "number" && Number.isFinite(value)) {
+    if (typeof value === "number" && Number.isFinite(value))
         return value;
-    }
     if (typeof value === "string" && value.trim().length > 0) {
         const parsed = Number.parseInt(value, 10);
-        if (Number.isFinite(parsed) && parsed > 0) {
+        if (Number.isFinite(parsed) && parsed > 0)
             return parsed;
-        }
     }
     return undefined;
 }

package/dist/commands/extract.js

@@ -5,13 +5,16 @@ import { runIntel } from "./intel.js";
 import { runGenerate } from "./generate.js";
 import { runContext } from "./context.js";
 export async function runExtract(options) {
+    // Default to sqlite so every extract builds guardian.db automatically.
+    // Pass --backend file to opt out (e.g. CI environments that don't need search).
+    const backend = options.backend ?? "sqlite";
     const { architecturePath, uxPath } = await extractProject(options);
     console.log(`Wrote ${architecturePath}`);
     console.log(`Wrote ${uxPath}`);
     // Auto-build codebase intelligence after every extract
     const specsDir = path.resolve(options.output);
     try {
-        await runIntel({ specs: specsDir, backend: options.backend });
+        await runIntel({ specs: specsDir, backend });
     }
     catch {
         // Non-fatal — intel build failure should not break extract

package/dist/commands/generate.js

@@ -1,26 +1,99 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import yaml from "js-yaml";
 import { buildSnapshots } from "../extract/index.js";
 import { renderContextBlock } from "../extract/context-block.js";
 import { getOutputLayout } from "../output-layout.js";
 import { DEFAULT_SPECS_DIR } from "../config.js";
 import { analyzeDepth } from "../extract/analyzers/depth.js";
+import { SqliteSpecsStore, DB_FILENAME } from "../db/sqlite-specs-store.js";
 export async function runGenerate(options) {
     if (!options.aiContext) {
         throw new Error("`guardian generate` currently supports `--ai-context` only.");
     }
     const outputRoot = path.resolve(options.output ?? DEFAULT_SPECS_DIR);
     const layout = getOutputLayout(outputRoot);
-    const { architecture, ux } = await buildSnapshots({
-        projectRoot: options.projectRoot,
-        backendRoot: options.backendRoot,
-        frontendRoot: options.frontendRoot,
-        output: outputRoot,
-        includeFileGraph: true,
-        configPath: options.configPath
-    });
-    // Load persisted Structural Intelligence reports emitted by `guardian extract`
-    const siReports = await loadStructuralIntelligenceReports(layout.machineDir);
+    // ── Load snapshots: DB first, full re-extraction as fallback ──────────────
+    // When guardian.db exists (built by extract), load snapshots from the specs
+    // table instead of re-analysing the whole codebase. This is ~10× faster.
+    let architecture;
+    let ux;
+    let siReports;
+    const dbPath = path.join(outputRoot, DB_FILENAME);
+    let store = null;
+    try {
+        await fs.stat(dbPath);
+        store = new SqliteSpecsStore(outputRoot);
+        await store.init();
+    }
+    catch {
+        store = null;
+    }
+    try {
+        if (store) {
+            const archEntry = await store.readSpec("architecture.snapshot");
+            const uxEntry = await store.readSpec("ux.snapshot");
+            if (archEntry && uxEntry) {
+                console.log("[guardian] Loading snapshots from guardian.db");
+                architecture = yaml.load(archEntry.content);
+                ux = yaml.load(uxEntry.content);
+            }
+            else {
+                console.log("[guardian] Snapshots not in DB — extracting from codebase");
+                ({ architecture, ux } = await buildSnapshots({
+                    projectRoot: options.projectRoot,
+                    backendRoot: options.backendRoot,
+                    frontendRoot: options.frontendRoot,
+                    output: outputRoot,
+                    includeFileGraph: true,
+                    configPath: options.configPath
+                }));
+            }
+            // SI from module_metrics, fall back to file
+            const metricRows = store.readModuleMetrics();
+            if (metricRows.length > 0) {
+                siReports = metricRows.map(r => ({
+                    feature: r.module,
+                    structure: { nodes: r.nodes, edges: r.edges },
+                    metrics: { depth: 0, fanout_avg: 0, fanout_max: 0, density: 0, has_cycles: false },
+                    scores: { depth_score: 0, fanout_score: 0, density_score: 0, cycle_score: 0, query_score: 0 },
+                    confidence: { value: r.confidence, level: r.confidence_level },
+                    ambiguity: { level: "LOW" },
+                    classification: {
+                        depth_level: r.depth_level,
+                        propagation: r.propagation,
+                        compressible: r.compressible,
+                    },
+                    recommendation: {
+                        primary: { pattern: r.pattern, confidence: r.confidence },
+                        fallback: { pattern: "", condition: "" },
+                        avoid: [],
+                    },
+                    guardrails: { enforce_if_confidence_above: 0.7 },
+                    override: { allowed: true, requires_reason: true },
+                }));
+            }
+            else {
+                siReports = await loadStructuralIntelligenceReports(layout.machineDir);
+            }
+        }
+        else {
+            console.log("[guardian] No guardian.db found — extracting from codebase");
+            ({ architecture, ux } = await buildSnapshots({
+                projectRoot: options.projectRoot,
+                backendRoot: options.backendRoot,
+                frontendRoot: options.frontendRoot,
+                output: outputRoot,
+                includeFileGraph: true,
+                configPath: options.configPath
+            }));
+            siReports = await loadStructuralIntelligenceReports(layout.machineDir);
+        }
+    }
+    finally {
+        if (store)
+            await store.close();
+    }
     // If a --focus query is provided, prepend a real-time SI report for that query
     if (options.focus) {
         try {