@toolbaux/guardian 0.2.0 → 0.2.2

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
 
@@ -115,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):
@@ -139,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
@@ -239,11 +262,12 @@ 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
@@ -285,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" }
@@ -311,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>
@@ -318,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

@@ -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/init.js

@@ -204,8 +204,6 @@ export async function runInit(options) {
         const { runExtract } = await import("./extract.js");
         await runExtract({
             projectRoot: root,
-            backendRoot: options.backendRoot,
-            frontendRoot: options.frontendRoot,
             output: specsDir,
             includeFileGraph: true,
             backend: options.backend,
@@ -213,8 +211,6 @@ export async function runInit(options) {
         const { runGenerate } = await import("./generate.js");
         await runGenerate({
             projectRoot: root,
-            backendRoot: options.backendRoot,
-            frontendRoot: options.frontendRoot,
             output: specsDir,
             aiContext: true,
         });

package/dist/db/fts-builder.js

@@ -296,6 +296,29 @@ export function populateFTSIndex(store, intel, arch, funcIntel) {
         mergeArchitectureRows(rowMap, arch);
     if (funcIntel)
         mergeFunctionIntelRows(rowMap, funcIntel);
+    // Deduplicate paths where one is a suffix of another — caused when the snapshot
+    // stores some paths relative to backendRoot ("db/store.ts") and others relative
+    // to the workspace root ("src/db/store.ts"). Keep the longer (workspace-relative)
+    // path and merge any unique tokens from the shorter entry into it.
+    const paths = Array.from(rowMap.keys());
+    for (const shorter of paths) {
+        for (const longer of paths) {
+            if (shorter === longer)
+                continue;
+            if (longer.endsWith("/" + shorter) && rowMap.has(shorter) && rowMap.has(longer)) {
+                const s = rowMap.get(shorter);
+                const l = rowMap.get(longer);
+                // Merge any tokens the shorter row had that the longer lacks
+                for (const field of ["symbol_name", "endpoint", "body", "module"]) {
+                    if (s[field] && !l[field].includes(s[field])) {
+                        l[field] = l[field] ? l[field] + " " + s[field] : s[field];
+                    }
+                }
+                rowMap.delete(shorter);
+                break;
+            }
+        }
+    }
     store.rebuildSearchIndex(Array.from(rowMap.values()));
     // Per-function index — enables symbol-level search results with line numbers.
     if (funcIntel?.functions?.length) {

package/dist/db/sqlite-specs-store.js

@@ -592,6 +592,16 @@ export class SqliteSpecsStore {
             return [];
         }
     }
+    /** Return all file_path values currently in the search index. Useful for tests and diagnostics. */
+    listIndexedFilePaths() {
+        try {
+            const rows = this.db.prepare("SELECT file_path FROM search_fts").all();
+            return rows.map(r => r.file_path);
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Store API endpoint facts.
      * Called from populateFTSIndex() after reading intel/arch objects.

package/package.json

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