@toolbaux/guardian 0.1.15 → 0.1.17

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/@toolbaux/guardian.svg)](https://www.npmjs.com/package/@toolbaux/guardian)
 [![license](https://img.shields.io/npm/l/@toolbaux/guardian.svg)](./LICENSE)
 
+> **Beta Release** — Guardian is under active development. Core features (extract, context, drift, MCP server) are stable and used daily across multiple projects, but you may encounter minor issues with edge cases in framework detection or config handling. Bug reports and feedback welcome via [GitHub Issues](https://github.com/idocoding/guardian/issues).
+
 Architectural intelligence for codebases. One command turns your repo into compact, machine-readable context that AI coding tools can reason about without hallucinating.
 
 ```bash
@@ -53,7 +55,7 @@ After `guardian init`, your project gets:
 - `.specs/` directory with architecture snapshots
 - `CLAUDE.md` with auto-injected context (refreshed on every save and commit)
 - Pre-commit hook that keeps context fresh automatically
-- `guardian.config.json` with auto-detected backend/frontend roots
+- `guardian.config.json` for project settings (roots auto-detected at runtime)
 
 ## Claude Code / Cursor Integration
 
@@ -96,9 +98,8 @@ Guardian includes an MCP server that Claude Code and Cursor connect to automatic
 
 All responses are compact JSON — no pretty-printing, no verbose keys. Repeated calls are cached (30s TTL). Usage metrics tracked per session.
 
-**Manual setup** (if the extension doesn't auto-configure):
+**Setup:** `guardian init` and the VSCode extension auto-create `.mcp.json` at your project root. If you need to create it manually:
 
-Create `.mcp.json` at your project root:
 ```json
 {
   "mcpServers": {
@@ -110,6 +111,8 @@ Create `.mcp.json` at your project root:
 }
 ```
 
+> **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.
+
 ## VSCode Extension
 
 Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=toolbaux.toolbaux-guardian):
@@ -276,14 +279,14 @@ guardian feature-context --spec feature-specs/billing.yaml
 <details>
 <summary><strong>Configuration</strong></summary>
 
-`guardian.config.json` at project root (auto-created by `guardian init`):
+`guardian.config.json` at project root (auto-created by `guardian init`). Backend and frontend roots are auto-detected at runtime — only set them if auto-detection picks the wrong directory:
 
 ```json
 {
   "project": {
+    "description": "Short product description for generated docs",
     "backendRoot": "./backend",
-    "frontendRoot": "./frontend",
-    "description": "Short product description for generated docs"
+    "frontendRoot": "./frontend"
   },
   "frontend": {
     "routeDirs": ["app"],

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

@@ -15,10 +15,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_SPECS_DIR } from "../config.js";
 const DEFAULT_CONFIG = {
-    project: {
-        backendRoot: "./backend",
-        frontendRoot: "./frontend",
-    },
     docs: {
         mode: "full",
     },
@@ -78,32 +74,8 @@ export async function runInit(options) {
     // 2. Create guardian.config.json if missing
     const configPath = path.join(root, "guardian.config.json");
     if (!(await fileExists(configPath))) {
-        const config = { ...DEFAULT_CONFIG };
-        // Auto-detect roots
-        if (options.backendRoot) {
-            config.project.backendRoot = options.backendRoot;
-        }
-        else {
-            for (const candidate of ["./backend", "./server", "./api", "./src"]) {
-                if (await dirExists(path.join(root, candidate))) {
-                    config.project.backendRoot = candidate;
-                    break;
-                }
-            }
-        }
-        if (options.frontendRoot) {
-            config.project.frontendRoot = options.frontendRoot;
-        }
-        else {
-            for (const candidate of ["./frontend", "./client", "./web", "./app"]) {
-                if (await dirExists(path.join(root, candidate))) {
-                    config.project.frontendRoot = candidate;
-                    break;
-                }
-            }
-        }
-        await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
-        console.log(`  ✓ Created guardian.config.json (backend: ${config.project.backendRoot}, frontend: ${config.project.frontendRoot})`);
+        await fs.writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf8");
+        console.log("  ✓ Created guardian.config.json");
     }
     else {
         console.log("  · guardian.config.json already exists");
@@ -232,6 +204,36 @@ async function dirExists(p) {
     }
 }
 async function setupClaudeCodeHooks(root, specsDir) {
+    // Create .mcp.json at project root (MCP standard — works with Claude Code, Cursor, etc.)
+    const mcpJsonPath = path.join(root, ".mcp.json");
+    try {
+        let mcpConfig = {};
+        if (await fileExists(mcpJsonPath)) {
+            try {
+                mcpConfig = JSON.parse(await fs.readFile(mcpJsonPath, "utf8"));
+            }
+            catch {
+                // Corrupted — overwrite
+            }
+        }
+        if (!mcpConfig.mcpServers)
+            mcpConfig.mcpServers = {};
+        const servers = mcpConfig.mcpServers;
+        if (!servers.guardian) {
+            servers.guardian = {
+                command: "guardian",
+                args: ["mcp-serve", "--specs", specsDir],
+            };
+            await fs.writeFile(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf8");
+            console.log("  ✓ Created .mcp.json (MCP server config)");
+        }
+        else {
+            console.log("  · .mcp.json already has guardian MCP config");
+        }
+    }
+    catch (err) {
+        console.warn(`  ⚠ Could not create .mcp.json: ${err.message}`);
+    }
     const claudeDir = path.join(root, ".claude");
     const hooksDir = path.join(claudeDir, "hooks");
     const settingsPath = path.join(claudeDir, "settings.json");

package/dist/commands/mcp-serve.js

@@ -456,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) => {
@@ -484,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/package.json

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