@mgamil/mapx 0.2.4

package/dist/cli.js

@@ -0,0 +1,1835 @@
+import { Command } from "commander";
+import { resolve, join, dirname, relative, basename } from "node:path";
+import { existsSync, readFileSync, writeFileSync, readdirSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import * as readline from "node:readline";
+import { Store } from "./core/store.js";
+import { MapxGraph } from "./core/graph.js";
+import { Scanner, buildMatcher } from "./core/scanner.js";
+import { Config } from "./core/config.js";
+import { FlowTracer } from "./core/flow-tracer.js";
+import { AgentGenerator } from "./agents/generator.js";
+import { WorkspaceManager } from "./core/workspace-manager.js";
+import { LLMExporter } from "./exporters/llm-exporter.js";
+import { GraphExporter } from "./exporters/graph-exporter.js";
+import { DotExporter } from "./exporters/dot-exporter.js";
+import { SvgExporter } from "./exporters/svg-exporter.js";
+import { ToonExporter } from "./exporters/toon-exporter.js";
+import { calculateMetrics } from "./core/metrics.js";
+import { getChangedFiles, isGitRepo } from "./core/git-tracker.js";
+import { getBuiltinLanguages } from "./languages/registry.js";
+import { isLanguageInstalled, installLanguage, uninstallLanguage } from "./languages/installer.js";
+import { RouteRegistry } from "./frameworks/route-registry.js";
+const dynamicRequire = createRequire(import.meta.url);
+function readVersion() {
+  const base = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [join(base, "VERSION"), join(base, "..", "VERSION")]) {
+    if (existsSync(candidate)) return readFileSync(candidate, "utf-8").trim();
+  }
+  return "0.1.0";
+}
+function collectPatterns(val, memo) {
+  return memo.concat(val.split(",").map((s) => s.trim()));
+}
+function resolveDir(cmdOpts, programOpts) {
+  const raw = cmdOpts.dir || programOpts.dir || process.cwd();
+  return resolve(raw);
+}
+const PHASE_LABELS = {
+  discover: { active: "Discovering files", done: "Discovered files" },
+  index: { active: "Indexing files", done: "Indexed files" },
+  parse: { active: "Parsing files", done: "Parsed files" },
+  resolve: { active: "Resolving references", done: "Resolved references" },
+  detect: { active: "Detecting changes", done: "Detected changes" },
+  cluster: { active: "Detecting clusters", done: "Detected clusters" }
+};
+const SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2E26", "\u28BC", "\u28F4", "\u28F7", "\u28EF", "\u28DF", "\u287F", "\u28BF", "\u28FB", "\u28FD", "\u28FE"];
+let spinnerIdx = 0;
+function createProgressRenderer() {
+  let lastPhase = null;
+  let lastLineLen = 0;
+  const writeLine = (line) => {
+    const clear = lastLineLen > 0 ? "\r" + " ".repeat(lastLineLen) + "\r" : "\r";
+    process.stderr.write(clear + line);
+    lastLineLen = line.length;
+  };
+  const renderBar = (current, total, width = 20) => {
+    if (total === 0) {
+      const frame = SPINNER_FRAMES[spinnerIdx++ % SPINNER_FRAMES.length];
+      return `${frame} `;
+    }
+    const filled = Math.min(width, Math.max(0, Math.round(current / total * width)));
+    const empty = width - filled;
+    const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+    const pct = Math.round(current / total * 100);
+    return `${bar} ${pct}%`;
+  };
+  return (progress) => {
+    const { phase, current, total, file } = progress;
+    const label = PHASE_LABELS[phase];
+    const isNewPhase = phase !== lastPhase;
+    if (isNewPhase && lastPhase !== null) {
+      const prevLabel = PHASE_LABELS[lastPhase];
+      writeLine(`  \u2714 ${prevLabel.done}
+`);
+    }
+    lastPhase = phase;
+    const bar = renderBar(current, total);
+    const counter = total > 0 ? `${current}/${total}` : `${current}`;
+    let line = `  ${label.active} ${bar} ${counter}`;
+    if (file) {
+      const maxFileLen = Math.max(0, 60 - line.length);
+      const displayFile = file.length > maxFileLen && maxFileLen > 3 ? "\u2026" + file.slice(-(maxFileLen - 1)) : file.length <= maxFileLen ? file : "";
+      if (displayFile) {
+        line += ` ${displayFile}`;
+      }
+    }
+    writeLine(line);
+  };
+}
+const MAPX_MARKER_START = "<!-- mapx -->";
+const MAPX_MARKER_END = "<!-- /mapx -->";
+function readStubContent() {
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const stubPath = resolve(thisDir, "agents.stub.md");
+    return readFileSync(stubPath, "utf-8");
+  } catch {
+    return [
+      "# MapxGraph - LLM Integration Guide",
+      "",
+      "This project uses **MapxGraph** \u2014 a local code graph memory system that provides persistent, structured understanding of the codebase across LLM sessions.",
+      "",
+      "## Commands",
+      "",
+      "All commands accept a target directory. Three ways to specify:",
+      "",
+      "```bash",
+      "# 1. Positional path argument",
+      "mapx scan /path/to/project",
+      "",
+      "# 2. --dir / -d flag",
+      "mapx scan --dir /path/to/project",
+      'mapx query "MyClass" -d /path/to/project',
+      "",
+      "# 3. Global flag (works with any subcommand)",
+      "mapx -d /path/to/project scan",
+      "```",
+      "",
+      "```bash",
+      "mapx init [/path]                                # First-time setup",
+      "mapx uninit [/path]                              # Reverse installation",
+      "mapx scan [/path]                                # Full scan (survives Ctrl+C)",
+      "mapx update [/path]                              # Incremental update",
+      "mapx export [--dir /path]                        # LLM summary (8K tokens)",
+      "mapx export --format=json                        # Full JSON graph",
+      "mapx export --format=dot                         # GraphViz DOT",
+      "mapx export --format=svg                         # SVG visualization",
+      "mapx export -o summary.txt                       # Export to file",
+      "mapx export --format=svg -o graph.svg            # SVG to file",
+      "mapx query <term>                                # Search symbols",
+      "mapx deps <file>                                 # File dependencies",
+      "mapx summary [/path]                             # Project summary",
+      "mapx serve --dir /path                           # Start MCP server (stdio)",
+      "mapx serve --sse --port 3456 --dir /path         # SSE (HTTP) transport",
+      "```",
+      "",
+      "## MCP Tools",
+      "",
+      "- `mapx_scan` \u2014 Scan/update the code graph",
+      "- `mapx_query` \u2014 Search symbols by name",
+      "- `mapx_dependencies` \u2014 Get deps for a file",
+      "- `mapx_export` \u2014 Export graph (llm, json, dot, svg)",
+      "- `mapx_status` \u2014 Check scan status",
+      "",
+      "## When to Use",
+      "",
+      "1. Start of session: `mapx export`",
+      "2. Find something: `mapx query <term>`",
+      "3. Understand a file: `mapx deps <file>`",
+      "4. Files changed: `mapx update`",
+      "5. Major changes: `mapx scan`",
+      "6. Visual overview: `mapx export --format=svg -o graph.svg`",
+      "",
+      "## Supported Languages",
+      "",
+      "- **PHP**: classes, methods, functions, interfaces, traits, enums, constants",
+      "- **JavaScript**: classes, methods, functions, arrow functions",
+      "- **TypeScript**: classes, methods, functions, interfaces, enums, type aliases, properties"
+    ].join("\n");
+  }
+}
+function generateAgentsBlock() {
+  const content = readStubContent();
+  return `${MAPX_MARKER_START}
+${content}
+${MAPX_MARKER_END}`;
+}
+function hasMarkers(content) {
+  return content.includes(MAPX_MARKER_START) && content.includes(MAPX_MARKER_END);
+}
+function replaceBetweenMarkers(existing, block) {
+  const startIdx = existing.indexOf(MAPX_MARKER_START);
+  const endIdx = existing.indexOf(MAPX_MARKER_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return existing;
+  }
+  return existing.slice(0, startIdx) + block + existing.slice(endIdx + MAPX_MARKER_END.length);
+}
+function prompt(question, options) {
+  return new Promise((res) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const labels = options.map((o, i) => `  ${i + 1}) ${o}`);
+    process.stderr.write(question + "\n" + labels.join("\n") + "\n> ");
+    rl.question("", (answer) => {
+      rl.close();
+      const num = parseInt(answer.trim(), 10);
+      res(num >= 1 && num <= options.length ? num - 1 : options.length - 1);
+    });
+  });
+}
+function askQuestion(query) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve2) => rl.question(query, (ans) => {
+    rl.close();
+    resolve2(ans);
+  }));
+}
+async function selectProvidersInteractive() {
+  const generator = new AgentGenerator();
+  const providers = generator.listProviders();
+  console.log("\nWhich LLM/agent tools do you use in this project?");
+  console.log('Enter numbers separated by commas (e.g. 1,3), type "all" for all, or press Enter for default [1 (generic)]:');
+  providers.forEach((p, idx) => {
+    console.log(`  [${idx + 1}] ${p}`);
+  });
+  const answer = await askQuestion("\nSelection: ");
+  const input = answer.trim().toLowerCase();
+  if (!input) {
+    return ["generic"];
+  }
+  if (input === "all") {
+    return providers;
+  }
+  const parts = input.split(",").map((s) => parseInt(s.trim(), 10)).filter((n) => !isNaN(n) && n >= 1 && n <= providers.length);
+  const selected = parts.map((n) => providers[n - 1]);
+  return selected.length === 0 ? ["generic"] : selected;
+}
+function buildCLI() {
+  const program = new Command();
+  program.name("mapx").description("Multi-language code graph memory system for LLMs").version(readVersion()).option("-d, --dir <path>", "Target project directory (default: current directory)");
+  function detectLaravel(workspaceRoot) {
+    const composerPath = join(workspaceRoot, "composer.json");
+    if (existsSync(composerPath)) {
+      try {
+        const content = readFileSync(composerPath, "utf-8");
+        const composer = JSON.parse(content);
+        if (composer.require && composer.require["laravel/framework"]) {
+          return true;
+        }
+      } catch {
+      }
+    }
+    if (existsSync(join(workspaceRoot, "artisan"))) {
+      return true;
+    }
+    if (existsSync(join(workspaceRoot, "app", "Http", "Kernel.php"))) {
+      return true;
+    }
+    if (existsSync(join(workspaceRoot, "app")) && existsSync(join(workspaceRoot, "routes")) && existsSync(join(workspaceRoot, "config")) && existsSync(join(workspaceRoot, "database"))) {
+      return true;
+    }
+    return false;
+  }
+  async function confirmLaravelExcludes(noSuggestions) {
+    if (noSuggestions) return false;
+    if (!process.stdin.isTTY) {
+      return true;
+    }
+    console.log("\nDetected Laravel project.");
+    console.log("\nSuggested exclusions (recommended):");
+    console.log("  \u2713 database/migrations/**   (schema DDL \u2014 no app logic)");
+    console.log("  \u2713 database/seeders/**      (data fixtures)");
+    console.log("  \u2713 database/factories/**    (test data)");
+    console.log("  \u2713 storage/**               (runtime-generated)");
+    console.log("  \u2713 bootstrap/cache/**       (artisan-generated cache)");
+    console.log("  \u2713 public/**                (web assets)");
+    console.log("  \u2713 resources/views/**       (Blade templates \u2014 not yet supported)");
+    console.log("  \u2713 **/*.blade.php           (Blade files)");
+    const answer = await askQuestion("\nAdd these to .mapx/config.json? [Y/n] ");
+    return answer.toLowerCase() !== "n";
+  }
+  program.command("init").description("Initialize mapx for a project").argument("[path]", "Target directory").option("--name <name>", "Repository name").option("--no-agents", "Skip AGENTS.md creation").option("--no-suggestions", "Skip interactive framework suggestions").option("--no-mcp-configs", "Skip auto-generating MCP config files for detected agent tools").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const isLaravel = detectLaravel(dir);
+    let shouldAddLaravelExcludes = false;
+    if (isLaravel) {
+      shouldAddLaravelExcludes = await confirmLaravelExcludes(opts.suggestions === false);
+    }
+    const config = await Config.init(dir, opts.name, isLaravel, shouldAddLaravelExcludes);
+    if (opts.agents !== false) {
+      if (process.stdin.isTTY && opts.suggestions !== false) {
+        const selected = await selectProvidersInteractive();
+        console.log(`Generating integration files for: ${selected.join(", ")}...`);
+        const generator = new AgentGenerator();
+        const actions = generator.plan(selected, { dir });
+        for (const action of actions) {
+          generator.execute(action);
+          console.log(`  \u2713 Generated ${action.filename} (${action.status})`);
+        }
+      } else {
+        const generator = new AgentGenerator();
+        const actions = generator.plan(["generic"], { dir });
+        for (const action of actions) {
+          generator.execute(action);
+          console.log(`  \u2713 Generated ${action.filename} (${action.status})`);
+        }
+      }
+    }
+    if (opts.mcpConfigs !== false) {
+      const generator = new AgentGenerator();
+      const detected = generator.detectAgentTools(dir);
+      if (detected.length > 0) {
+        const mcpActions = generator.generateMcpConfigs(detected, { dir });
+        for (const action of mcpActions) {
+          if (action.status === "up_to_date") continue;
+          generator.executeMcpConfig(action);
+          const verb = action.status === "merge" ? "merged into" : action.status === "create" ? "created" : "updated";
+          console.log(`  \u2713 MCP config ${verb} ${action.filename} (${action.tool})`);
+        }
+      }
+    }
+    const gitignorePath = join(dir, ".gitignore");
+    const hasGitignore = existsSync(gitignorePath);
+    const isGit = isGitRepo(dir);
+    if (hasGitignore || isGit) {
+      const content = hasGitignore ? readFileSync(gitignorePath, "utf-8") : "";
+      const lines = content.split("\n").map((l) => l.trim());
+      if (!lines.includes(".mapx/") && !lines.includes(".mapx")) {
+        const entry = content.length > 0 && !content.endsWith("\n") ? "\n.mapx/\n" : ".mapx/\n";
+        writeFileSync(gitignorePath, content + entry);
+        console.log(`  \u2713 Added .mapx/ to .gitignore`);
+      }
+    }
+    console.log(`Initialized mapx in ${dir}/.mapx/`);
+    console.log(`Repo: ${config.repo.name}`);
+  });
+  program.command("uninit").description("Remove .mapx/ directory and reverse project integration changes").argument("[path]", "Target directory").option("-f, --force", "Skip confirmation prompt").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const hasMapx = existsSync(join(dir, ".mapx"));
+    if (!opts.force && process.stdin.isTTY) {
+      const answer = await askQuestion(`Are you sure you want to remove .mapx/ and reverse all mapx integrations in ${dir}? [y/N] `);
+      if (answer.trim().toLowerCase() !== "y") {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    const generator = new AgentGenerator();
+    generator.revert({ dir });
+    generator.revertMcpConfigs({ dir });
+    const gitignorePath = join(dir, ".gitignore");
+    if (existsSync(gitignorePath)) {
+      try {
+        const content = readFileSync(gitignorePath, "utf-8");
+        const lines = content.split("\n");
+        let removed = false;
+        const filteredLines = lines.filter((line) => {
+          const trimmed = line.trim();
+          if (trimmed === ".mapx" || trimmed === ".mapx/") {
+            removed = true;
+            return false;
+          }
+          return true;
+        });
+        if (removed) {
+          writeFileSync(gitignorePath, filteredLines.join("\n"), "utf-8");
+          console.log(`  \u2713 Removed .mapx/ from .gitignore`);
+        }
+      } catch (err) {
+        console.error(`  \u2717 Failed to update .gitignore: ${err.message}`);
+      }
+    }
+    if (hasMapx) {
+      try {
+        rmSync(join(dir, ".mapx"), { recursive: true, force: true });
+        console.log(`  \u2713 Removed .mapx/ directory`);
+      } catch (err) {
+        console.error(`  \u2717 Failed to remove .mapx/ directory: ${err.message}`);
+      }
+    }
+    console.log(`Successfully uninitialized mapx for project: ${dir}`);
+  });
+  program.command("scan").description("Full scan: parse all files, build graph").argument("[path]", "Target directory").option("--exclude <glob>", "Exclude glob pattern(s)", collectPatterns, []).option("--include <glob>", "Include glob pattern(s)", collectPatterns, []).option("--repo <name>", "Scan only a specific registered repository").option("--all", "Scan all registered repositories").option("--force", "Force re-parsing of all files (bypass cache)", false).action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir({}, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const onProgress = createProgressRenderer();
+    const scanner = new Scanner(store, config, graph, onProgress, {
+      excludes: opts.exclude,
+      includes: opts.include
+    });
+    const onSigInt = () => {
+      scanner.abort();
+      process.stderr.write("\n");
+    };
+    process.once("SIGINT", onSigInt);
+    let repoNames = void 0;
+    if (opts.repo) {
+      repoNames = [opts.repo];
+    } else if (opts.all) {
+      repoNames = ["all"];
+    }
+    const result = await scanner.scanFull(repoNames, { force: !!opts.force }).catch((err) => {
+      if (err.message.includes("Another scan is already running")) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    });
+    process.removeListener("SIGINT", onSigInt);
+    process.stderr.write("\r" + " ".repeat(80) + "\r");
+    if (result.interrupted) {
+      console.log(`Scan interrupted after ${result.filesScanned}/${result.totalFiles} files. Progress saved \u2014 run \`scan\` again to resume.`);
+    } else {
+      console.log(`Scanned ${result.filesScanned} files in ${result.durationMs}ms`);
+    }
+    console.log(`Languages: ${Object.entries(result.languageBreakdown).map(([l, c]) => `${l}: ${c}`).join(", ")}`);
+    console.log(`Found ${result.symbolsFound} symbols, ${result.edgesFound} edges`);
+  });
+  program.command("update").alias("sync").description("Incremental scan: re-scan only changed files").argument("[path]", "Target directory").option("--exclude <glob>", "Exclude glob pattern(s)", collectPatterns, []).option("--include <glob>", "Include glob pattern(s)", collectPatterns, []).option("--repo <name>", "Update only a specific registered repository").option("--all", "Update all registered repositories").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir({}, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const onProgress = createProgressRenderer();
+    const handleLockError = (err) => {
+      if (err.message.includes("Another scan is already running")) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    };
+    let repoNames = void 0;
+    if (opts.repo) {
+      repoNames = [opts.repo];
+    } else if (opts.all) {
+      repoNames = ["all"];
+    }
+    const scanner = new Scanner(store, config, graph, onProgress, {
+      excludes: opts.exclude,
+      includes: opts.include
+    });
+    process.once("SIGINT", () => scanner.abort());
+    const result = await scanner.scanIncremental(repoNames).catch(handleLockError);
+    process.stderr.write("\r" + " ".repeat(80) + "\r");
+    if (result.interrupted) {
+      console.log(`Update interrupted after ${result.filesScanned} files.`);
+    } else {
+      console.log(`Updated ${result.filesScanned} files in ${result.durationMs}ms`);
+      console.log(`${result.symbolsFound} symbols updated, ${result.edgesFound} edges updated`);
+    }
+  });
+  program.command("status").description("Show scan status, collected metrics, and changed files").argument("[path]", "Target directory").option("--exclude <glob>", "Exclude glob pattern(s)", collectPatterns, []).option("--include <glob>", "Include glob pattern(s)", collectPatterns, []).action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir({}, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const lastScan = store.getMeta("last_scan_time:" + config.repo.name) || store.getMeta("last_scan_time");
+    const lastCommit = store.getMeta("last_scan_commit:" + config.repo.name) || store.getMeta("last_scan_commit");
+    const schemaVer = store.getMeta("schema_version");
+    const dbPath = resolve(dir, ".mapx", "mapx.db");
+    const activeExcludes = [
+      ...config.settings.excludePatterns ?? [],
+      ...opts.exclude ?? []
+    ];
+    const activeIncludes = [
+      ...config.settings.includePatterns ?? [],
+      ...opts.include ?? []
+    ];
+    console.log("\n\u2500\u2500 Scan \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log(`  Project:     ${config.repo.name}`);
+    console.log(`  Framework:   ${config.repo.framework || "generic"}`);
+    console.log(`  Directory:   ${dir}`);
+    console.log(`  Last scan:   ${lastScan || "never"}`);
+    console.log(`  Last commit: ${lastCommit || "none"}`);
+    console.log(`  Schema:      v${schemaVer || "?"}`);
+    console.log(`  Excludes:    [${activeExcludes.join(", ")}]`);
+    console.log(`  Includes:    [${activeIncludes.join(", ")}]`);
+    const fileCount = store.getFileCount();
+    const symbolCount = store.getSymbolCount();
+    const edgeCount = store.getEdgeCount();
+    const breakdown = store.getLanguageBreakdown();
+    const verifiedEdgeCount = store.raw.prepare("SELECT COUNT(*) as cnt FROM edges WHERE verifiability = 'verified'").get()?.cnt || 0;
+    const inferredEdgeCount = store.raw.prepare("SELECT COUNT(*) as cnt FROM edges WHERE verifiability = 'inferred'").get()?.cnt || 0;
+    console.log("\n\u2500\u2500 Collected data \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log(`  Files:       ${fileCount}`);
+    console.log(`  Symbols:     ${symbolCount}`);
+    console.log(`  Edges:       ${edgeCount} (verified: ${verifiedEdgeCount}, inferred: ${inferredEdgeCount})`);
+    const langs = Object.entries(breakdown).sort((a, b) => b[1] - a[1]);
+    if (langs.length > 0) {
+      console.log(`  Languages:`);
+      for (const [lang, cnt] of langs) {
+        console.log(`    ${lang.padEnd(14)} ${cnt} files`);
+      }
+    }
+    const kindRows = store.raw.prepare(
+      "SELECT kind, COUNT(*) as cnt FROM symbols GROUP BY kind ORDER BY cnt DESC"
+    ).all();
+    if (kindRows.length > 0) {
+      console.log(`  Symbol kinds:`);
+      for (const row of kindRows) {
+        console.log(`    ${row.kind.padEnd(14)} ${row.cnt}`);
+      }
+    }
+    const edgeTypeRows = store.raw.prepare(
+      "SELECT edge_type, COUNT(*) as cnt FROM edges GROUP BY edge_type ORDER BY cnt DESC"
+    ).all();
+    if (edgeTypeRows.length > 0) {
+      console.log(`  Edge types:`);
+      for (const row of edgeTypeRows) {
+        console.log(`    ${row.edge_type.padEnd(14)} ${row.cnt}`);
+      }
+    }
+    if (fileCount > 0) {
+      const densityNum = edgeCount / Math.max(fileCount * (fileCount - 1), 1);
+      const density = (densityNum * 100).toFixed(2);
+      const connRows = store.raw.prepare(`
+          SELECT source_file, COUNT(*) as cnt FROM edges
+          GROUP BY source_file ORDER BY cnt DESC LIMIT 5
+        `).all();
+      console.log("\n\u2500\u2500 Graph metrics \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      console.log(`  Density:     ${density}%`);
+      const avgEdges = fileCount > 0 ? (edgeCount / fileCount).toFixed(1) : "0";
+      console.log(`  Avg edges/file: ${avgEdges}`);
+      if (connRows.length > 0) {
+        console.log(`  Most connected files:`);
+        for (const row of connRows) {
+          const rel = row.source_file.replace(dir + "/", "");
+          console.log(`    ${String(row.cnt).padStart(4)} edges  ${rel}`);
+        }
+      }
+    }
+    try {
+      const { statSync } = await import("node:fs");
+      const dbSize = statSync(dbPath).size;
+      const kb = (dbSize / 1024).toFixed(1);
+      console.log("\n\u2500\u2500 Storage \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      console.log(`  Database:    ${kb} KB  (${dbPath})`);
+    } catch {
+    }
+    console.log("\n\u2500\u2500 PageRank Importance \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    const topFiles = store.getTopFilesByPageRank(graph, 5);
+    const topSymbols = store.getTopSymbolsByPageRank(graph, 5);
+    if (topFiles.length > 0) {
+      console.log("  Top files by PageRank:");
+      for (const tf of topFiles) {
+        console.log(`    ${tf.pagerank.toFixed(6)}  ${tf.path}`);
+      }
+    } else {
+      console.log("  No ranked files (run a scan first)");
+    }
+    if (topSymbols.length > 0) {
+      console.log("\n  Top symbols by PageRank:");
+      for (const ts of topSymbols) {
+        const scope = ts.scope ? `${ts.scope}::` : "";
+        console.log(`    ${ts.pagerank.toFixed(6)}  ${scope}${ts.name} (${ts.filePath})`);
+      }
+    } else {
+      console.log("\n  No ranked symbols (run a scan first)");
+    }
+    const repoRoot = resolve(dir, config.repo.path);
+    let isStale = false;
+    if (!isGitRepo(repoRoot)) {
+      console.log("\n\u2500\u2500 Git \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      console.log("  Not a git repository");
+    } else {
+      const changes = getChangedFiles(repoRoot, lastCommit || void 0);
+      console.log("\n\u2500\u2500 Git changes since last scan \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      if (changes.length === 0) {
+        console.log("  No changes since last scan  (\u2713 index is current)");
+      } else {
+        isStale = true;
+        const byStatus = { added: 0, modified: 0, removed: 0, renamed: 0, unchanged: 0 };
+        for (const c of changes) byStatus[c.status] = (byStatus[c.status] || 0) + 1;
+        const summary = Object.entries(byStatus).filter(([, n]) => n > 0).map(([s, n]) => `${n} ${s}`).join(", ");
+        console.log(`  ${changes.length} changed files  (${summary})  (\u26A0 stale)`);
+        const icon = { added: "+", modified: "~", removed: "-", renamed: ">", unchanged: "=" };
+        for (const change of changes) {
+          console.log(`    ${icon[change.status]} ${change.path}`);
+        }
+      }
+    }
+    console.log("\n\u2500\u2500 Recommendations \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    if (isStale) {
+      console.log("  \u26A0 Index is stale. Run `mapx sync` or `mapx update` to bring it up to date.");
+    } else {
+      console.log("  \u2713 Index is up to date.");
+    }
+    console.log("");
+  });
+  program.command("query <term>").description("Search for symbols by name").option("-d, --dir <path>", "Target directory").action(async (term, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const results = store.searchSymbols(term);
+    if (results.length === 0) {
+      console.log(`No symbols matching "${term}"`);
+      return;
+    }
+    for (const sym of results) {
+      const scope = sym.scope ? `${sym.scope}::` : "";
+      console.log(`  ${sym.kind} ${scope}${sym.name}`);
+      console.log(`    @ ${sym.file_path}:${sym.start_line}`);
+      if (sym.signature && sym.signature !== sym.name) {
+        console.log(`    signature: ${sym.signature}`);
+      }
+    }
+  });
+  program.command("search <term>").description("Symbol search with kind/file/exact filters").option("-d, --dir <path>", "Target directory").option("--kind <kind>", "Filter by symbol kind (e.g. class, method)").option("--file <prefix>", "Filter by file path prefix").option("--exact", "Only match exact name", false).option("--limit <limit>", "Max results to return", "20").action(async (term, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store, graph } = await loadContext(dir);
+    const results = store.searchSymbolsFiltered({
+      term,
+      kind: opts.kind,
+      filePrefix: opts.file,
+      exact: !!opts.exact,
+      limit: parseInt(opts.limit, 10)
+    });
+    if (results.length === 0) {
+      console.log(`No symbols matching "${term}"`);
+      return;
+    }
+    const rankedAll = graph.getRankedSymbols();
+    const rankMap = /* @__PURE__ */ new Map();
+    for (const item of rankedAll) {
+      rankMap.set(`${item.filePath}::${item.name}`, item.pagerank);
+    }
+    for (const sym of results) {
+      const scope = sym.scope ? `${sym.scope}::` : "";
+      const key = `${sym.file_path}::${sym.name}`;
+      const pagerankVal = rankMap.get(key) || 0;
+      console.log(`  ${sym.kind} ${scope}${sym.name} [pagerank: ${pagerankVal.toFixed(6)}]`);
+      console.log(`    @ ${sym.file_path}:${sym.start_line}`);
+      if (sym.signature && sym.signature !== sym.name) {
+        console.log(`    signature: ${sym.signature}`);
+      }
+    }
+  });
+  program.command("callers <symbol>").description("Show callers of a symbol").option("-d, --dir <path>", "Target directory").option("--depth <depth>", "Traversal depth", "1").action(async (symbol, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const maxDepth = parseInt(opts.depth, 10);
+    const queue = [{ symName: symbol, depth: 0 }];
+    const visited = /* @__PURE__ */ new Set([symbol]);
+    const results = [];
+    while (queue.length > 0) {
+      const { symName, depth } = queue.shift();
+      if (depth >= maxDepth) continue;
+      const callers = store.getCallersOfSymbol(symName);
+      for (const edge of callers) {
+        const callerName = edge.source_symbol ? `${edge.source_symbol}` : "<top-level>";
+        const calleeName = edge.target_symbol || symName;
+        const meta = edge.metadata ? JSON.parse(edge.metadata) : {};
+        results.push({
+          caller: callerName,
+          callee: calleeName,
+          file: edge.source_file,
+          line: meta.startLine || 1,
+          depth: depth + 1
+        });
+        const nextSym = edge.source_symbol;
+        if (nextSym && !visited.has(nextSym)) {
+          visited.add(nextSym);
+          queue.push({ symName: nextSym, depth: depth + 1 });
+        }
+      }
+    }
+    if (results.length === 0) {
+      console.log(`No callers found for "${symbol}"`);
+      return;
+    }
+    console.log(`Callers of "${symbol}":`);
+    for (const res of results) {
+      const indent = "  ".repeat(res.depth);
+      console.log(`${indent}\u2190 ${res.caller} (calls ${res.callee})`);
+      console.log(`${indent}  @ ${res.file}:${res.line}`);
+    }
+  });
+  program.command("callees <symbol>").description("Show callees of a symbol").option("-d, --dir <path>", "Target directory").option("--depth <depth>", "Traversal depth", "1").action(async (symbol, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const maxDepth = parseInt(opts.depth, 10);
+    const queue = [{ symName: symbol, depth: 0 }];
+    const visited = /* @__PURE__ */ new Set([symbol]);
+    const results = [];
+    while (queue.length > 0) {
+      const { symName, depth } = queue.shift();
+      if (depth >= maxDepth) continue;
+      const callees = store.getCalleesOfSymbol(symName);
+      for (const edge of callees) {
+        const calleeName = edge.target_symbol || "<unknown>";
+        const callerName = edge.source_symbol || symName;
+        const meta = edge.metadata ? JSON.parse(edge.metadata) : {};
+        results.push({
+          caller: callerName,
+          callee: calleeName,
+          file: edge.target_file,
+          line: meta.startLine || 1,
+          depth: depth + 1
+        });
+        if (edge.target_symbol && !visited.has(edge.target_symbol)) {
+          visited.add(edge.target_symbol);
+          queue.push({ symName: edge.target_symbol, depth: depth + 1 });
+        }
+      }
+    }
+    if (results.length === 0) {
+      console.log(`No callees found for "${symbol}"`);
+      return;
+    }
+    console.log(`Callees of "${symbol}":`);
+    for (const res of results) {
+      const indent = "  ".repeat(res.depth);
+      console.log(`${indent}\u2192 ${res.callee} (called by ${res.caller})`);
+      console.log(`${indent}  @ ${res.file}:${res.line}`);
+    }
+  });
+  program.command("impact <symbol>").description("Show transitive blast-radius of changing a symbol").option("-d, --dir <path>", "Target directory").option("--depth <depth>", "Traversal depth", "3").option("--format <format>", "text | json", "text").action(async (symbol, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const maxDepth = parseInt(opts.depth, 10);
+    const queue = [{ symName: symbol, depth: 0 }];
+    const visited = /* @__PURE__ */ new Set([symbol]);
+    const items = [];
+    while (queue.length > 0) {
+      const { symName, depth } = queue.shift();
+      if (depth >= maxDepth) continue;
+      const callers = store.getCallersOfSymbol(symName);
+      for (const edge of callers) {
+        const callerName = edge.source_symbol || "<top-level>";
+        const key = `${edge.source_file}::${callerName}`;
+        if (visited.has(key)) continue;
+        visited.add(key);
+        let risk = "LOW";
+        const isStructural = ["import", "require", "extends", "implements"].includes(edge.edge_type);
+        const curDepth = depth + 1;
+        if (curDepth === 1) {
+          risk = isStructural ? "MEDIUM" : "HIGH";
+        } else if (curDepth === 2) {
+          risk = isStructural ? "LOW" : "MEDIUM";
+        } else {
+          risk = "LOW";
+        }
+        items.push({
+          symbol: callerName,
+          file: edge.source_file,
+          depth: curDepth,
+          edgeType: edge.edge_type,
+          risk
+        });
+        if (edge.source_symbol) {
+          queue.push({ symName: edge.source_symbol, depth: curDepth });
+        }
+      }
+    }
+    let recommendation = "No callers found \u2014 safe to change";
+    if (items.some((x) => x.risk === "HIGH")) {
+      recommendation = "Treat as BREAKING CHANGE \u2014 update all HIGH-risk callers";
+    } else if (items.length > 0) {
+      recommendation = "Low blast radius \u2014 proceed with caution";
+    }
+    if (opts.format === "json") {
+      console.log(JSON.stringify({
+        affected: items,
+        summary: {
+          high: items.filter((x) => x.risk === "HIGH").length,
+          medium: items.filter((x) => x.risk === "MEDIUM").length,
+          low: items.filter((x) => x.risk === "LOW").length
+        },
+        recommendation
+      }, null, 2));
+    } else {
+      if (items.length === 0) {
+        console.log(`No callers affected by changing "${symbol}"`);
+      } else {
+        console.log(`Impact analysis for "${symbol}":`);
+        for (const item of items) {
+          console.log(`  [${item.risk}] ${item.symbol} (${item.file}) [depth: ${item.depth}, type: ${item.edgeType}]`);
+        }
+      }
+      console.log(`
+Recommendation: ${recommendation}`);
+    }
+  });
+  program.command("node <symbol>").description("Show full symbol details and optional source code").option("-d, --dir <path>", "Target directory").option("--source", "Extract and display source code", false).action(async (symbol, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const { readFileSync: readFileSync2 } = await import("node:fs");
+    const sym = store.getSymbolByName(symbol);
+    if (!sym) {
+      console.error(`Error: Symbol "${symbol}" not found`);
+      process.exit(1);
+    }
+    const callers = store.getCallersOfSymbol(symbol);
+    const callees = store.getCalleesOfSymbol(symbol);
+    console.log(`Symbol: ${sym.scope ? `${sym.scope}::` : ""}${sym.name}`);
+    console.log(`Kind:   ${sym.kind}`);
+    console.log(`File:   ${sym.file_path}`);
+    console.log(`Lines:  ${sym.start_line}-${sym.end_line}`);
+    console.log(`Signature: ${sym.signature}`);
+    console.log(`Callers: ${callers.length}`);
+    console.log(`Callees: ${callees.length}`);
+    if (opts.source) {
+      try {
+        const absolutePath = resolve(dir, sym.file_path);
+        const content = readFileSync2(absolutePath, "utf8");
+        const lines = content.split("\n");
+        const start = sym.start_line - 1;
+        const end = sym.end_line;
+        const sliced = lines.slice(start, end).join("\n");
+        console.log("\nSource Code:");
+        console.log("----------------------------------------");
+        console.log(sliced);
+        console.log("----------------------------------------");
+      } catch (err) {
+        console.error(`Failed to read source code: ${err.message}`);
+      }
+    }
+  });
+  program.command("files").description("List indexed files with prefix/lang/sort filters").option("-d, --dir <path>", "Target directory").option("--path <prefix>", "Filter by path prefix").option("--lang <lang>", "Filter by language").option("--sort <sort>", "lines | path", "path").option("--limit <limit>", "Max files to return", "50").action(async (opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store } = await loadContext(dir);
+    const results = store.getFilesFiltered({
+      pathPrefix: opts.path,
+      lang: opts.lang,
+      sort: opts.sort,
+      limit: parseInt(opts.limit, 10)
+    });
+    if (results.length === 0) {
+      console.log("No files found matching filters");
+      return;
+    }
+    for (const file of results) {
+      console.log(`  ${file.path} (${file.language}, ${file.lines} lines, ${file.size_bytes} bytes)`);
+    }
+  });
+  program.command("deps <file>").description("Show dependencies for a file").option("-d, --dir <path>", "Target directory").action(async (file, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { store, graph } = await loadContext(dir);
+    const deps = graph.getDependencies(file);
+    const rdeps = graph.getReverseDependencies(file);
+    if (deps.length > 0) {
+      console.log("Dependencies:");
+      for (const dep of deps) {
+        console.log(`  \u2192 ${dep.target} (${dep.type})`);
+      }
+    } else {
+      console.log("No dependencies found");
+    }
+    if (rdeps.length > 0) {
+      console.log("\nDepended on by:");
+      for (const rdep of rdeps) {
+        console.log(`  \u2190 ${rdep.source} (${rdep.type})`);
+      }
+    }
+  });
+  program.command("trace [symbol-or-file]").description("Trace data flow paths from a starting symbol or file").option("-d, --dir <path>", "Target directory").option("--direction <dir>", "up | down | both", "both").option("--depth <n>", "Maximum traversal depth", "3").option("--max-depth <n>", "Maximum traversal depth (alias for --depth)").option("--format <fmt>", "text | dot | json", "text").option("--include-structural", "Include import/extends edges in trace", false).option("--sources", "Show entry points", false).option("--sinks", "Show terminal consumers", false).option("--to <target>", "Find the shortest path to target symbol/file").action(async (start, opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { config, store } = await loadContext(dir);
+    const tracer = new FlowTracer(store);
+    if (opts.sources) {
+      const sources = tracer.findSources(config.repo.name);
+      console.log(`
+Entry points (data sources) \u2014 ${sources.length} found:`);
+      for (const s of sources) {
+        let extra = "[no incoming data edges]";
+        if (s.file.includes("routes/")) {
+          const routes = store.getEdgesForFile(s.file).filter((e) => e.edge_type === "route");
+          extra = `[route file \u2014 ${routes.length} controller endpoints]`;
+        } else if (s.file.includes("app/Jobs/")) {
+          extra = "[dispatched externally \u2014 queue worker]";
+        } else if (s.file.includes("app/Listeners/")) {
+          extra = "[event listener \u2014 external trigger]";
+        } else if (s.file.includes("app/Http/Middleware/")) {
+          extra = "[middleware \u2014 filter chain entry]";
+        }
+        console.log(`  ${s.file.padEnd(40)} ${extra}`);
+      }
+      return;
+    }
+    if (opts.sinks) {
+      const sinks = tracer.findSinks(config.repo.name);
+      console.log(`
+Terminal consumers (data sinks) \u2014 ${sinks.length} found:`);
+      for (const s of sinks) {
+        const inEdges = store.getReverseEdges(s.file).filter((e) => [
+          "call",
+          "instantiation",
+          "param_type",
+          "return_type",
+          "relation",
+          "dispatch",
+          "notify",
+          "route"
+        ].includes(e.edge_type));
+        let extra = `[terminal \u2014 no outgoing data edges]`;
+        if (s.file.includes("DatabaseManager") || s.file.includes("database")) {
+          extra = `[DB facade \u2192 raw SQL \u2014 ${inEdges.length} in-edges]`;
+        } else if (s.file.includes("CacheManager") || s.file.includes("cache")) {
+          extra = `[Cache facade \u2192 Redis/Memcache \u2014 ${inEdges.length} in-edges]`;
+        } else if (s.file.includes("Mailer") || s.file.includes("mail")) {
+          extra = `[Mail facade \u2192 SMTP \u2014 ${inEdges.length} in-edges]`;
+        } else if (s.file.includes("QueueManager") || s.file.includes("queue")) {
+          extra = `[Queue::push \u2014 ${inEdges.length} in-edges]`;
+        }
+        console.log(`  ${s.file.padEnd(40)} ${extra}`);
+      }
+      return;
+    }
+    if (!start) {
+      console.error("Error: start symbol or file is required unless --sources or --sinks is specified.");
+      process.exit(1);
+    }
+    if (opts.to) {
+      const path = tracer.findCriticalPath(start, opts.to, config.repo.name);
+      if (!path) {
+        console.log(`No path found from "${start}" to "${opts.to}"`);
+        return;
+      }
+      console.log(`
+Critical data path: ${start} \u2192 ${opts.to}`);
+      console.log(`Length: ${path.nodes.length - 1} hops
+`);
+      for (let i = 0; i < path.nodes.length; i++) {
+        const node = path.nodes[i];
+        const indent = "  ".repeat(i);
+        const prefix = i === 0 ? "" : `\u2514\u2500[${node.incomingEdgeType}]\u2500\u2192  `;
+        const suffix = i === path.nodes.length - 1 ? "  \u2297" : "";
+        const name = node.symbol ? node.symbol : node.file;
+        console.log(`${indent}${prefix}${name}${suffix}`);
+      }
+      return;
+    }
+    const requestedDepth = opts.maxDepth !== void 0 ? opts.maxDepth : opts.depth;
+    const parsedDepth = parseInt(requestedDepth, 10);
+    const result = tracer.trace({
+      startSymbol: start,
+      direction: opts.direction,
+      maxDepth: parsedDepth,
+      includeStructural: !!opts.includeStructural,
+      repo: config.repo.name
+    });
+    if (opts.format === "json") {
+      const jsonOutput = {
+        start: result.start,
+        direction: result.direction,
+        maxDepth: parsedDepth,
+        nodeCount: result.nodeCount,
+        edgeCount: result.edgeCount,
+        maxDepthReached: result.maxDepthReached,
+        sources: result.sources.map((s) => ({ file: s.file, symbol: s.symbol })),
+        sinks: result.sinks.map((s) => ({ file: s.file, symbol: s.symbol })),
+        cycles: result.cycles,
+        nodes: Array.from(new Map(result.paths.flatMap((p) => p.nodes).map((n) => [`${n.file}::${n.symbol || ""}`, n])).values()).map((n) => ({
+          file: n.file,
+          symbol: n.symbol,
+          depth: n.depth,
+          incomingEdgeType: n.incomingEdgeType
+        })),
+        edges: Array.from(new Set(result.paths.flatMap((p) => {
+          const arr = [];
+          for (let i = 1; i < p.nodes.length; i++) {
+            arr.push(JSON.stringify({
+              from: p.nodes[i - 1].file,
+              to: p.nodes[i].file,
+              edgeType: p.nodes[i].incomingEdgeType,
+              fromSymbol: p.nodes[i - 1].symbol,
+              toSymbol: p.nodes[i].symbol
+            }));
+          }
+          return arr;
+        }))).map((s) => JSON.parse(s))
+      };
+      console.log(JSON.stringify(jsonOutput, null, 2));
+      return;
+    }
+    if (opts.format === "dot") {
+      const lines = [];
+      const safeStartName = (result.start.symbol || result.start.file).replace(/[^a-zA-Z0-9]/g, "_");
+      lines.push(`digraph Trace_${safeStartName} {`);
+      lines.push("  rankdir=TB;");
+      lines.push(`  label="Trace: ${result.start.symbol || result.start.file} (${result.direction}stream, depth\u2264${parsedDepth})";`);
+      lines.push("  fontsize=12;");
+      lines.push("  node [shape=box, style=filled, fontsize=10];");
+      lines.push("");
+      const uniqueNodes = /* @__PURE__ */ new Map();
+      const edgesSet = /* @__PURE__ */ new Set();
+      for (const p of result.paths) {
+        for (let i = 0; i < p.nodes.length; i++) {
+          const n = p.nodes[i];
+          const key = `${n.file}::${n.symbol || ""}`;
+          if (!uniqueNodes.has(key)) {
+            let shape = "box";
+            let color = "#E8F4FD";
+            const isStart = n.file === result.start.file && n.symbol === result.start.symbol;
+            const isSink = result.sinks.some((s) => s.file === n.file && s.symbol === n.symbol);
+            const isSource = result.sources.some((s) => s.file === n.file && s.symbol === n.symbol);
+            if (isStart) {
+              shape = "diamond";
+              color = "#FFE0B2";
+            } else if (isSink) {
+              shape = "octagon";
+              color = "#FFEBEE";
+            } else if (isSource) {
+              shape = "ellipse";
+              color = "#E8F5E9";
+            }
+            uniqueNodes.set(key, { file: n.file, symbol: n.symbol, shape, color });
+          }
+          if (i > 0) {
+            const fromNode = p.nodes[i - 1];
+            const toNode = p.nodes[i];
+            edgesSet.add(JSON.stringify({
+              from: `${fromNode.file}::${fromNode.symbol || ""}`,
+              to: `${toNode.file}::${toNode.symbol || ""}`,
+              type: toNode.incomingEdgeType
+            }));
+          }
+        }
+      }
+      for (const [key, n] of uniqueNodes.entries()) {
+        const label = n.symbol || n.file.split("/").pop() || n.file;
+        lines.push(`  "${key}" [label="${label}", fillcolor="${n.color}", shape=${n.shape}];`);
+      }
+      lines.push("");
+      for (const edgeStr of edgesSet) {
+        const e = JSON.parse(edgeStr);
+        lines.push(`  "${e.from}" -> "${e.to}" [label="${e.type}"];`);
+      }
+      lines.push("}");
+      console.log(lines.join("\n"));
+      return;
+    }
+    const dirSymbol = result.direction === "down" ? "\u2193 downstream" : result.direction === "up" ? "\u2191 upstream" : "\u2195 bidirectional";
+    console.log(`
+Trace: ${start}  ${dirSymbol}  depth\u2264${parsedDepth}`);
+    console.log("\u2500".repeat(53));
+    console.log("");
+    const printNode = (node, indentLevel) => {
+      const indent = "  ".repeat(indentLevel);
+      const prefix = indentLevel === 0 ? "" : `\u2514\u2500[${node.incomingEdgeType}]\u2500\u2192  `;
+      const displayName = node.symbol || node.file;
+      const filePart = node.symbol ? `  (${node.file})` : "";
+      const isSink = result.sinks.some((s) => s.file === node.file && s.symbol === node.symbol);
+      const sinkStr = isSink ? "  \u2297 sink" : "";
+      const cycle = result.cycles.find((c) => c.fromFile === node.file && c.fromSymbol === node.symbol);
+      const cycleStr = cycle ? "  \u21BB cycle" : "";
+      console.log(`${indent}${prefix}${displayName}${filePart}${sinkStr}${cycleStr}`);
+      if (!cycle) {
+        const children = [];
+        const seenChildKeys = /* @__PURE__ */ new Set();
+        for (const path of result.paths) {
+          const idx = path.nodes.findIndex((n) => n.file === node.file && n.symbol === node.symbol && n.depth === node.depth);
+          if (idx !== -1 && idx + 1 < path.nodes.length) {
+            const nextNode = path.nodes[idx + 1];
+            const key = `${nextNode.file}::${nextNode.symbol || ""}::${nextNode.depth}`;
+            if (!seenChildKeys.has(key)) {
+              seenChildKeys.add(key);
+              children.push(nextNode);
+            }
+          }
+        }
+        for (const child of children) {
+          printNode(child, indentLevel + 1);
+        }
+      }
+    };
+    const startNode = {
+      file: result.start.file,
+      symbol: result.start.symbol,
+      depth: 0,
+      incomingEdgeType: "start"
+    };
+    printNode(startNode, 0);
+    console.log("");
+    const cyclesStr = result.cycles.length > 0 ? `   Cycles: ${result.cycles.length}` : "";
+    console.log(`Nodes: ${result.nodeCount}   Edges: ${result.edgeCount}   Max depth: ${parsedDepth}${cyclesStr}`);
+    if (result.sinks.length > 0) {
+      const sinkNames = result.sinks.map((s) => s.symbol || s.file.split("/").pop() || s.file);
+      console.log(`Sinks: ${sinkNames.join(", ")}`);
+    }
+  });
+  program.command("export").description("Export code graph for LLM consumption").option("-d, --dir <path>", "Target directory").option("--format <format>", "Output format: llm, json, dot, svg, toon", "llm").option("--tokens <budget>", "Token budget for LLM export", "8192").option("--repo <name>", "Filter by repo name").option("-o, --output <file>", "Write output to file instead of stdout").option("--exclude <glob>", "Exclude glob pattern(s)", collectPatterns, []).option("--include <glob>", "Include glob pattern(s)", collectPatterns, []).option("--delimiter <delimiter>", "Delimiter for TOON format: comma, tab, pipe", "comma").option("--key-folding", "Collapse single-key chains into dotted paths for TOON", false).option("--cluster <mode>", "Cluster rendering mode for DOT/SVG: none, auto", "none").option("--depth <n>", "Maximum cluster nesting depth for DOT/SVG export", "3").option("--fallback-grid", "Force using fallback grid SVG export", false).action(async (opts) => {
+    const dir = resolveDir(opts, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const format = opts.format;
+    const tokenBudget = parseInt(opts.tokens, 10) || 8192;
+    const outputPath = opts.output;
+    const delimiter = opts.delimiter;
+    const keyFolding = !!opts.keyFolding;
+    const clusterMode = opts.cluster === "none" ? "none" : "auto";
+    const clusterDepth = opts.depth ? parseInt(opts.depth, 10) : 3;
+    const fallbackGrid = !!opts.fallbackGrid;
+    const clusterOpts = { cluster: clusterMode, depth: clusterDepth, forceFallback: fallbackGrid };
+    if (outputPath) {
+      const outputDir = resolve(outputPath, "..");
+      if (!existsSync(outputDir)) {
+        console.error(`Error: output directory does not exist: ${outputDir}`);
+        process.exit(1);
+      }
+      try {
+        writeFileSync(outputPath, "", "utf-8");
+      } catch {
+        console.error(`Error: cannot write to: ${resolve(outputPath)}`);
+        process.exit(1);
+      }
+    }
+    const excludes = [
+      ...config.settings.excludePatterns ?? [],
+      ...opts.exclude ?? []
+    ];
+    const includes = [
+      ...config.settings.includePatterns ?? [],
+      ...opts.include ?? []
+    ];
+    const matcher = buildMatcher(excludes, includes);
+    const allFiles = store.getAllFiles(opts.repo).map((f) => f.path);
+    const filteredFiles = allFiles.filter((f) => matcher(f));
+    let output;
+    switch (format) {
+      case "json": {
+        const exporter = new GraphExporter(store, graph);
+        output = exporter.exportAsJSONString(opts.repo, filteredFiles);
+        break;
+      }
+      case "dot": {
+        const exporter = new DotExporter(store, graph);
+        output = exporter.export(opts.repo, filteredFiles, clusterOpts);
+        break;
+      }
+      case "svg": {
+        const exporter = new SvgExporter(store, graph);
+        output = exporter.export(opts.repo, filteredFiles, clusterOpts);
+        break;
+      }
+      case "toon": {
+        const exporter = new ToonExporter(store, graph);
+        output = exporter.export({
+          format: "toon",
+          tokenBudget,
+          repo: opts.repo,
+          files: filteredFiles,
+          delimiter,
+          keyFolding
+        });
+        break;
+      }
+      case "llm":
+      default: {
+        const exporter = new LLMExporter(store, graph);
+        output = exporter.export({
+          format: "llm",
+          tokenBudget,
+          repo: opts.repo,
+          files: filteredFiles
+        });
+        break;
+      }
+    }
+    if (outputPath) {
+      writeFileSync(resolve(outputPath), output, "utf-8");
+      console.log(`Exported ${format} to ${resolve(outputPath)} (${Buffer.byteLength(output, "utf-8")} bytes)`);
+    } else {
+      console.log(output);
+    }
+  });
+  program.command("summary").description("Show project summary").argument("[path]", "Target directory").action(async (path) => {
+    const dir = path ? resolve(path) : resolveDir({}, program.opts());
+    const { store, graph, config } = await loadContext(dir);
+    const fileCount = store.getFileCount();
+    const symbolCount = store.getSymbolCount();
+    const edgeCount = store.getEdgeCount();
+    const breakdown = store.getLanguageBreakdown();
+    console.log(`Project: ${config.repo.name} (${dir})`);
+    console.log(`Files: ${fileCount}`);
+    console.log(`Symbols: ${symbolCount}`);
+    console.log(`Dependencies: ${edgeCount}`);
+    console.log(`Languages: ${Object.entries(breakdown).map(([l, c]) => `${l} (${c})`).join(", ")}`);
+  });
+  const langCmd = program.command("lang").description("Manage language grammars and configuration");
+  langCmd.command("list").description("List all supported languages, their extensions, tier, and status").action(() => {
+    const langs = getBuiltinLanguages();
+    console.log("Supported languages:");
+    for (const [name, def] of Object.entries(langs)) {
+      const installed = isLanguageInstalled(name) ? "Installed" : "Not Installed";
+      console.log(`  - ${name} (${def.extensions.join(", ")} | tier: ${def.tier} | status: ${installed})`);
+    }
+  });
+  langCmd.command("install <lang>").description("Install grammar and query files for an installable language").action(async (lang) => {
+    try {
+      console.log(`Installing language '${lang}'...`);
+      await installLanguage(lang);
+      console.log(`Successfully installed language '${lang}'.`);
+    } catch (err) {
+      console.error(`Error installing language '${lang}':`, err.message);
+      process.exit(1);
+    }
+  });
+  langCmd.command("uninstall <lang>").description("Uninstall grammar and query files for an installable language").action(async (lang) => {
+    try {
+      console.log(`Uninstalling language '${lang}'...`);
+      await uninstallLanguage(lang);
+      console.log(`Successfully uninstalled language '${lang}'.`);
+    } catch (err) {
+      console.error(`Error uninstalling language '${lang}':`, err.message);
+      process.exit(1);
+    }
+  });
+  program.command("serve").description("Start MCP server (stdio transport)").option("-d, --dir <path>", "Default target directory for MCP tools").option("--port <port>", "Port for SSE transport (default: 45123)", "45123").option("--sse", "Enable SSE transport instead of stdio").option("--ui", "Enable UI dashboard alongside MCP server").option("--ui-port <port>", "Port to run UI on (default: 45124)", "45124").option("--ui-host <host>", "Host to run UI on (default: 127.0.0.1)", "127.0.0.1").option("--ui-token <token>", "Bearer token for authorization").option("--debug", "Enable verbose debug logging of MCP calls to stderr").action(async (opts) => {
+    const defaultDir = resolveDir(opts, program.opts());
+    const { startMcpServer } = await import("./mcp.js");
+    if (opts.ui) {
+      const { startUiServer } = await import("./ui-server.js");
+      const uiPort = parseInt(opts.uiPort, 10) || 45124;
+      const uiHost = opts.uiHost || "127.0.0.1";
+      const uiToken = opts.uiToken;
+      startUiServer({ port: uiPort, host: uiHost, token: uiToken, dir: defaultDir });
+    }
+    await startMcpServer(defaultDir, {
+      sse: opts.sse,
+      port: parseInt(opts.port, 10) || 45123,
+      debug: opts.debug
+    });
+  });
+  program.command("ui").description("Start the Web Dashboard").argument("[path]", "Target directory").option("-d, --dir <path>", "Target directory").option("-p, --port <port>", "Port to run UI on (default: 45124)", "45124").option("--host <host>", "Host to run UI on (default: 127.0.0.1)", "127.0.0.1").option("--token <token>", "Bearer token for authorization").option("--no-open", "Do not open the dashboard in the browser automatically").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const port = parseInt(opts.port, 10) || 45124;
+    const host = opts.host || "127.0.0.1";
+    const token = opts.token;
+    const { startUiServer } = await import("./ui-server.js");
+    startUiServer({ port, host, token, dir });
+    const url = `http://${host}:${port}`;
+    console.log(`Mapx Web Dashboard started at ${url}`);
+    if (opts.open !== false) {
+      const { exec } = await import("node:child_process");
+      const openCmd = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+      exec(`${openCmd} ${url}`).unref();
+    }
+  });
+  program.command("metrics").description("Show coupling and instability metrics for files").argument("[path]", "Target directory").option("-d, --dir <path>", "Target directory").option("--lang <language>", "Filter metrics by language").option("--verified-only", "Only compute metrics using verified edges").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const { config, store } = await loadContext(dir);
+    const metrics = calculateMetrics(store, {
+      repo: config.repo.name,
+      language: opts.lang,
+      verifiedOnly: !!opts.verifiedOnly
+    });
+    if (metrics.length === 0) {
+      console.log("No metrics found.");
+      return;
+    }
+    console.log("\n\u2500\u2500 Coupling & Instability Metrics \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log(`${"File Path".padEnd(45)} | ${"Lang".padEnd(10)} | ${"Ca".padStart(4)} | ${"Ce".padStart(4)} | ${"Instability".padStart(11)}`);
+    console.log("-".repeat(85));
+    for (const m of metrics) {
+      const pathTrunc = m.path.length > 45 ? "..." + m.path.substring(m.path.length - 42) : m.path;
+      console.log(`${pathTrunc.padEnd(45)} | ${m.language.padEnd(10)} | ${String(m.afferent).padStart(4)} | ${String(m.efferent).padStart(4)} | ${m.instability.toFixed(4).padStart(11)}`);
+    }
+    console.log("");
+  });
+  program.command("clusters").description("List detected code clusters/modules").argument("[clusterOrPath]", "Target directory or a specific cluster name to inspect").option("-d, --dir <path>", "Target directory").option("--source <source>", "Filter by cluster source: namespace, directory, community, or all", "all").option("--json", "Output results as JSON").action(async (clusterOrPath, opts) => {
+    let dir = resolveDir(opts, program.opts());
+    let clusterQuery = void 0;
+    if (clusterOrPath) {
+      const resolvedPath = resolve(clusterOrPath);
+      if (existsSync(resolvedPath)) {
+        dir = resolvedPath;
+      } else {
+        clusterQuery = clusterOrPath;
+      }
+    }
+    const { config, store } = await loadContext(dir);
+    const source = opts.source;
+    const json = !!opts.json;
+    const clusters = store.getClusters(config.repo.name);
+    let filtered = clusters;
+    if (source && source !== "all") {
+      filtered = clusters.filter((c) => c.source === source);
+    }
+    if (clusterQuery) {
+      const targetCluster = clusters.find((c) => c.name === clusterQuery);
+      if (!targetCluster) {
+        console.error(`Cluster "${clusterQuery}" not found.`);
+        process.exit(1);
+      }
+      const files = store.getClusterFiles(targetCluster.name, config.repo.name);
+      const clusterEdges = store.getClusterEdges(targetCluster.name, config.repo.name);
+      if (json) {
+        console.log(JSON.stringify({
+          cluster: targetCluster,
+          files,
+          edges: clusterEdges
+        }, null, 2));
+        return;
+      }
+      console.log(`
+${targetCluster.name}  [${targetCluster.source}]  ${targetCluster.file_count} files`);
+      for (const f of files) {
+        console.log(`  ${f}`);
+      }
+      const dependsOn = clusterEdges.filter((e) => e.sourceCluster === targetCluster.name);
+      console.log("\nDepends on:");
+      if (dependsOn.length === 0) {
+        console.log("  (none)");
+      } else {
+        for (const dep of dependsOn) {
+          console.log(`  ${dep.targetCluster.padEnd(25)} [${dep.edgeCount} edges \u2014 dominant: ${dep.dominantType}]`);
+        }
+      }
+      const dependedOnBy = clusterEdges.filter((e) => e.targetCluster === targetCluster.name);
+      console.log("\nDepended on by:");
+      if (dependedOnBy.length === 0) {
+        console.log("  (none)");
+      } else {
+        for (const dep of dependedOnBy) {
+          console.log(`  ${dep.sourceCluster.padEnd(25)} [${dep.edgeCount} edges \u2014 dominant: ${dep.dominantType}]`);
+        }
+      }
+      console.log("");
+      return;
+    }
+    if (json) {
+      console.log(JSON.stringify({ clusters: filtered }, null, 2));
+      return;
+    }
+    const roots = [];
+    const childrenMap = /* @__PURE__ */ new Map();
+    for (const c of filtered) {
+      if (!c.parent_name) {
+        roots.push(c);
+      } else {
+        const parentName = c.parent_name;
+        if (!childrenMap.has(parentName)) {
+          childrenMap.set(parentName, []);
+        }
+        childrenMap.get(parentName).push(c);
+      }
+    }
+    for (const list of childrenMap.values()) {
+      list.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    roots.sort((a, b) => a.name.localeCompare(b.name));
+    const printTree = (node, indent) => {
+      const padding = "  ".repeat(indent);
+      const namePart = node.name;
+      const sourcePart = `(${node.source})`;
+      const filesPart = `[${node.file_count} files]`;
+      const formatted = `${padding}${namePart.padEnd(35 - indent * 2)}${sourcePart.padEnd(15)} ${filesPart}`;
+      console.log(formatted);
+      const children = childrenMap.get(node.name) || [];
+      for (const child of children) {
+        printTree(child, indent + 1);
+      }
+    };
+    console.log("");
+    for (const root of roots) {
+      printTree(root, 0);
+    }
+    const nsCount = filtered.filter((c) => c.source === "namespace").length;
+    const dirCount = filtered.filter((c) => c.source === "directory").length;
+    const commCount = filtered.filter((c) => c.source === "community").length;
+    console.log(`
+${filtered.length} clusters detected (${nsCount} namespace, ${dirCount} directory, ${commCount} community)
+`);
+  });
+  program.command("edges").description("Granular query of dependency edges").argument("[path]", "Target directory").option("-d, --dir <path>", "Target directory").option("--type <type>", "Filter edges by type").option("--from <file>", "Filter edges originating from a file pattern").option("--to <file>", "Filter edges targeting a file pattern").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const { config, store } = await loadContext(dir);
+    const edges = store.queryEdges({
+      repo: config.repo.name,
+      type: opts.type,
+      from: opts.from,
+      to: opts.to
+    });
+    if (edges.length === 0) {
+      console.log("No matching edges found.");
+      return;
+    }
+    console.log(`
+Found ${edges.length} matching edges:`);
+    for (const e of edges) {
+      const srcSym = e.source_symbol ? `#${e.source_symbol}` : "";
+      const tgtSym = e.target_symbol ? `#${e.target_symbol}` : "";
+      const infSuffix = e.verifiability === "inferred" ? " [inferred]" : "";
+      console.log(`- ${e.source_file}${srcSym} \u2192 ${e.target_file}${tgtSym} (${e.edge_type})${infSuffix}`);
+    }
+    console.log("");
+  });
+  program.command("routes").description("Show routes from all detected frameworks").argument("[path]", "Target directory").option("-d, --dir <path>", "Target directory").option("--framework <name>", "Filter by framework name").option("--method <verb>", "Filter by HTTP method (GET, POST, etc.)").option("--path-pattern <pattern>", "Filter by route path pattern").option("--json", "Output routes as JSON").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const routeRegistry = new RouteRegistry();
+    await routeRegistry.load(dir);
+    const routes = routeRegistry.queryRoutes({
+      framework: opts.framework,
+      method: opts.method,
+      path: opts.pathPattern
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(routes, null, 2));
+      return;
+    }
+    if (routes.length === 0) {
+      console.log("No routes found.");
+      return;
+    }
+    console.log(`
+Detected Routes (${routes.length}):`);
+    console.log("".padEnd(80, "-"));
+    console.log(`${"Framework".padEnd(12)} | ${"Method".padEnd(8)} | ${"Path".padEnd(30)} | ${"Handler"}`);
+    console.log("".padEnd(80, "-"));
+    for (const r of routes) {
+      const handler = r.handlerSymbol || r.handlerFile;
+      console.log(`${r.framework.padEnd(12)} | ${r.method.toUpperCase().padEnd(8)} | ${r.path.padEnd(30)} | ${handler}`);
+    }
+    console.log("".padEnd(80, "-"));
+    console.log("");
+  });
+  program.command("hooks").description("Show hooks from all detected frameworks").argument("[path]", "Target directory").option("-d, --dir <path>", "Target directory").option("--framework <name>", "Filter by framework name").option("--type <type>", "Filter by hook type").option("--name <pattern>", "Filter by hook name pattern").option("--json", "Output hooks as JSON").action(async (path, opts) => {
+    const dir = path ? resolve(path) : resolveDir(opts, program.opts());
+    const routeRegistry = new RouteRegistry();
+    await routeRegistry.load(dir);
+    const hooks = routeRegistry.queryHooks({
+      framework: opts.framework,
+      hookType: opts.type,
+      hookName: opts.name
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(hooks, null, 2));
+      return;
+    }
+    if (hooks.length === 0) {
+      console.log("No hooks found.");
+      return;
+    }
+    console.log(`
+Detected Hooks (${hooks.length}):`);
+    console.log("".padEnd(80, "-"));
+    console.log(`${"Framework".padEnd(12)} | ${"Type".padEnd(15)} | ${"Hook Name".padEnd(25)} | ${"Handler"}`);
+    console.log("".padEnd(80, "-"));
+    for (const h of hooks) {
+      const handler = h.handlerSymbol || h.handlerFile;
+      console.log(`${h.framework.padEnd(12)} | ${h.hookType.padEnd(15)} | ${h.hookName.padEnd(25)} | ${handler}`);
+    }
+    console.log("".padEnd(80, "-"));
+    console.log("");
+  });
+  const agentsCmd = program.command("agents").description("Manage LLM agent integration files");
+  agentsCmd.command("list").description("List all supported LLM integration providers").action(() => {
+    const generator = new AgentGenerator();
+    const providers = generator.listProviders();
+    console.log("\nSupported LLM integration providers:");
+    for (const p of providers) {
+      const temp = generator.getTemplate(p);
+      const appendStr = temp?.isAppend ? " (append-mode)" : "";
+      console.log(`  - ${p.padEnd(12)} -> ${temp?.filename}${appendStr}`);
+    }
+    console.log("");
+  });
+  agentsCmd.command("generate").description("Generate/overwrite LLM integration files").option("--providers <list>", "Comma-separated list of providers to generate").option("--all", "Generate integration files for all supported providers").option("--dry-run", "Show actions without writing files").option("--force", "Force overwrite of existing files without prompt").option("--mcp-port <number>", "Port for the MCP SSE transport server", "3456").action(async (opts) => {
+    const dir = program.opts().dir ? resolve(program.opts().dir) : process.cwd();
+    const generator = new AgentGenerator();
+    const available = generator.listProviders();
+    let targets = [];
+    if (opts.all) {
+      targets = available;
+    } else if (opts.providers) {
+      targets = opts.providers.split(",").map((s) => s.trim().toLowerCase()).filter((p) => available.includes(p));
+    } else {
+      if (process.stdin.isTTY) {
+        targets = await selectProvidersInteractive();
+      } else {
+        targets = ["generic"];
+      }
+    }
+    if (targets.length === 0) {
+      console.error("No valid providers specified.");
+      process.exit(1);
+    }
+    const actions = generator.plan(targets, { dir, mcpPort: parseInt(opts.mcpPort, 10) });
+    for (const action of actions) {
+      if (action.status === "up_to_date") {
+        console.log(`  - ${action.filename}: Up to date. Skipping.`);
+        continue;
+      }
+      if (action.status === "update_conflict" || action.status === "no_sentinel") {
+        console.log(`
+\u26A0\uFE0F Conflict/Modification detected in ${action.filename}:`);
+        if (action.diff) {
+          console.log(action.diff);
+        }
+        if (!opts.force) {
+          const confirm = await askQuestion(`Overwrite ${action.filename}? [y/N] `);
+          if (confirm.trim().toLowerCase() !== "y") {
+            console.log(`Skipped ${action.filename}.`);
+            continue;
+          }
+        }
+      }
+      if (opts.dryRun) {
+        console.log(`[DRY RUN] Would write to ${action.filepath} (status: ${action.status})`);
+      } else {
+        generator.execute(action);
+        console.log(`\u2713 Wrote to ${action.filename} (status: ${action.status})`);
+      }
+    }
+  });
+  agentsCmd.command("update").description("Update existing LLM integration files to the current MapxGraph version").option("--dry-run", "Show updates without writing files").option("--force", "Force overwrite of customized blocks without prompt").option("--mcp-port <number>", "Port for the MCP SSE transport server", "3456").action(async (opts) => {
+    const dir = program.opts().dir ? resolve(program.opts().dir) : process.cwd();
+    const generator = new AgentGenerator();
+    const available = generator.listProviders();
+    const existingProviders = available.filter((p) => {
+      const temp = generator.getTemplate(p);
+      return temp && existsSync(join(dir, temp.filename));
+    });
+    if (existingProviders.length === 0) {
+      console.log("No existing LLM integration files found to update.");
+      return;
+    }
+    const actions = generator.plan(existingProviders, { dir, mcpPort: parseInt(opts.mcpPort, 10) });
+    let updatedCount = 0;
+    for (const action of actions) {
+      if (action.status === "up_to_date") {
+        continue;
+      }
+      if (action.status === "update_conflict") {
+        console.log(`
+\u26A0\uFE0F Customized content detected in ${action.filename}:`);
+        if (action.diff) {
+          console.log(action.diff);
+        }
+        if (!opts.force) {
+          const confirm = await askQuestion(`Overwrite customizations in ${action.filename}? [y/N] `);
+          if (confirm.trim().toLowerCase() !== "y") {
+            console.log(`Skipped ${action.filename}.`);
+            continue;
+          }
+        }
+      }
+      if (opts.dryRun) {
+        console.log(`[DRY RUN] Would update ${action.filepath}`);
+      } else {
+        generator.execute(action);
+        console.log(`\u2713 Updated ${action.filename}`);
+        updatedCount++;
+      }
+    }
+    if (updatedCount === 0 && !opts.dryRun) {
+      console.log("All integration files are already up to date.");
+    }
+  });
+  agentsCmd.command("mcp").description("Auto-detect agent tools and generate/update MCP config files").option("--tools <list>", "Comma-separated list of tools to generate configs for (opencode, gemini-cli, cursor-mcp, vscode-mcp)").option("--all", "Generate MCP configs for all supported tools").option("--detect", "Only detect agent tools without writing files").option("--dry-run", "Show actions without writing files").action(async (opts) => {
+    const dir = program.opts().dir ? resolve(program.opts().dir) : process.cwd();
+    const generator = new AgentGenerator();
+    const allConfigs = generator.listMcpConfigs();
+    let targets;
+    if (opts.all) {
+      targets = allConfigs;
+    } else if (opts.tools) {
+      const requested = opts.tools.split(",").map((s) => s.trim().toLowerCase());
+      targets = allConfigs.filter((c) => requested.includes(c.name));
+    } else {
+      targets = generator.detectAgentTools(dir);
+    }
+    if (opts.detect) {
+      if (targets.length === 0) {
+        console.log("No agent tools detected in this project.");
+      } else {
+        console.log(`
+Detected agent tools (${targets.length}):`);
+        for (const t of targets) {
+          console.log(`  \u2713 ${t.name.padEnd(15)} \u2192 ${t.filename}`);
+        }
+      }
+      console.log(`
+All available targets:`);
+      for (const c of allConfigs) {
+        const detected = targets.includes(c);
+        const icon = detected ? "\u2713" : "\xB7";
+        console.log(`  ${icon} ${c.name.padEnd(15)} \u2192 ${c.filename}`);
+      }
+      return;
+    }
+    if (targets.length === 0) {
+      console.log("No agent tools detected. Use --all or --tools to specify targets.");
+      return;
+    }
+    const actions = generator.generateMcpConfigs(targets, { dir });
+    for (const action of actions) {
+      if (action.status === "up_to_date") {
+        console.log(`  - ${action.filename}: Up to date.`);
+        continue;
+      }
+      if (opts.dryRun) {
+        console.log(`[DRY RUN] Would ${action.status} ${action.filename} (${action.tool})`);
+      } else {
+        generator.executeMcpConfig(action);
+        const verb = action.status === "merge" ? "merged into" : action.status === "create" ? "created" : "updated";
+        console.log(`  \u2713 MCP config ${verb} ${action.filename} (${action.tool})`);
+      }
+    }
+  });
+  const workspacesCmd = program.command("workspaces").description("Manage multi-repository workspace contexts");
+  workspacesCmd.command("list").alias("show").description("List registered repositories and other discovered peer/submodule directories").action(async () => {
+    const dir = resolveDir({}, program.opts());
+    const { config } = await loadContext(dir);
+    console.log("\nRegistered repositories:");
+    const registeredPaths = /* @__PURE__ */ new Set();
+    for (const r of config.repos) {
+      const absPath = resolve(dir, r.path);
+      registeredPaths.add(absPath);
+      const fwStr = r.framework ? ` [${r.framework}]` : "";
+      console.log(`  - ${r.name.padEnd(15)} -> ${r.path} (active)${fwStr}`);
+    }
+    const submodules = WorkspaceManager.discoverSubmodules(dir);
+    const uninitSubmodules = submodules.filter((s) => !registeredPaths.has(resolve(dir, s.path)));
+    if (uninitSubmodules.length > 0) {
+      console.log("\nDiscovered submodules:");
+      for (const s of uninitSubmodules) {
+        const status = s.isInitialized ? "available" : "uninitialized";
+        console.log(`  - ${s.name.padEnd(15)} -> ${s.path} (${status})`);
+      }
+    }
+    const peers = WorkspaceManager.discoverPeerRepos(dir);
+    const uninitPeers = peers.filter((p) => !registeredPaths.has(resolve(dir, p.path)));
+    if (uninitPeers.length > 0) {
+      console.log("\nDiscovered peer repositories:");
+      for (const p of uninitPeers) {
+        console.log(`  - ${p.name.padEnd(15)} -> ${p.path} (available)`);
+      }
+    }
+    const wsFiles = readdirSync(dir).filter((f) => f.endsWith(".code-workspace"));
+    if (wsFiles.length > 0) {
+      console.log("\nDiscovered VS Code Workspace folders:");
+      for (const f of wsFiles) {
+        const wsFolderRepos = WorkspaceManager.discoverVSCodeWorkspace(join(dir, f), dir);
+        const uninitWs = wsFolderRepos.filter((p) => !registeredPaths.has(resolve(dir, p.path)));
+        for (const p of uninitWs) {
+          console.log(`  - ${p.name.padEnd(15)} -> ${p.path} (available)`);
+        }
+      }
+    }
+    console.log("");
+  });
+  workspacesCmd.command("add <path>").description("Register a repository path").option("--name <name>", "Repository name (defaults to folder name)").action(async (repoPath, opts) => {
+    const dir = resolveDir({}, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const absPath = resolve(dir, repoPath);
+    if (!existsSync(absPath)) {
+      console.error(`Error: Path ${repoPath} does not exist.`);
+      process.exit(1);
+    }
+    if (!isGitRepo(absPath)) {
+      console.error(`Error: Path ${repoPath} is not a git repository.`);
+      process.exit(1);
+    }
+    const relPath = relative(dir, absPath);
+    const name = opts.name || basename(absPath);
+    if (config.repos.some((r) => r.name === name || r.path === relPath)) {
+      console.log(`Repository already registered: ${name} (${relPath})`);
+      return;
+    }
+    config.addRepo(name, relPath);
+    await config.save();
+    console.log(`Registered repository: ${name} -> ${relPath}`);
+    console.log("Running initial full scan for the new repository...");
+    const onProgress = createProgressRenderer();
+    const scanner = new Scanner(store, config, graph, onProgress);
+    const result = await scanner.scanFull([name]);
+    console.log(`Scanned ${result.filesScanned} files, ${result.symbolsFound} symbols, ${result.edgesFound} edges in ${result.durationMs}ms`);
+  });
+  workspacesCmd.command("remove <name>").description("Unregister a repository by name or path").action(async (name) => {
+    const dir = resolveDir({}, program.opts());
+    const { config, store } = await loadContext(dir);
+    const repo = config.repos.find((r) => r.name === name || r.path === name);
+    if (!repo) {
+      console.error(`Error: Repository ${name} is not registered.`);
+      process.exit(1);
+    }
+    const repoName = repo.name;
+    config.removeRepo(name);
+    await config.save();
+    console.log(`Unregistered repository: ${repoName}`);
+    console.log(`Cleaning up stored data for repository: ${repoName}...`);
+    store.deleteRepo(repoName);
+    console.log(`Done.`);
+  });
+  workspacesCmd.command("discover").description("Discover unregistered submodules, peer repos, and VS Code workspace folders (read-only)").action(async () => {
+    const dir = resolveDir({}, program.opts());
+    const { config } = await loadContext(dir);
+    const registeredPaths = /* @__PURE__ */ new Set();
+    for (const r of config.repos) {
+      registeredPaths.add(resolve(dir, r.path));
+    }
+    let found = 0;
+    const submodules = WorkspaceManager.discoverSubmodules(dir);
+    const uninitSubs = submodules.filter((s) => !registeredPaths.has(resolve(dir, s.path)));
+    if (uninitSubs.length > 0) {
+      console.log("\nSubmodules:");
+      for (const s of uninitSubs) {
+        const status = s.isInitialized ? "available" : "uninitialized";
+        console.log(`  - ${s.name.padEnd(20)} -> ${s.path} (${status})`);
+      }
+      found += uninitSubs.length;
+    }
+    const peers = WorkspaceManager.discoverPeerRepos(dir);
+    const uninitPeers = peers.filter((p) => !registeredPaths.has(resolve(dir, p.path)));
+    if (uninitPeers.length > 0) {
+      console.log("\nPeer repositories:");
+      for (const p of uninitPeers) {
+        console.log(`  - ${p.name.padEnd(20)} -> ${p.path} (available)`);
+      }
+      found += uninitPeers.length;
+    }
+    const wsFiles = readdirSync(dir).filter((f) => f.endsWith(".code-workspace"));
+    const vsEntries = [];
+    for (const f of wsFiles) {
+      const wsFolderRepos = WorkspaceManager.discoverVSCodeWorkspace(join(dir, f), dir);
+      for (const p of wsFolderRepos) {
+        if (!registeredPaths.has(resolve(dir, p.path))) {
+          vsEntries.push({ name: p.name, path: p.path });
+        }
+      }
+    }
+    if (vsEntries.length > 0) {
+      console.log("\nVS Code workspace folders:");
+      for (const p of vsEntries) {
+        console.log(`  - ${p.name.padEnd(20)} -> ${p.path} (available)`);
+      }
+      found += vsEntries.length;
+    }
+    if (found === 0) {
+      console.log("No unregistered repositories discovered.");
+    } else {
+      console.log(`
+${found} unregistered repositor${found === 1 ? "y" : "ies"} discovered. Use \`mapx workspaces add <path>\` to register.`);
+    }
+  });
+  workspacesCmd.command("sync").description("Sync all discovered submodules, peer repos, and VS Code workspace folders").action(async () => {
+    const dir = resolveDir({}, program.opts());
+    const { config, store, graph } = await loadContext(dir);
+    const registeredPaths = /* @__PURE__ */ new Set();
+    for (const r of config.repos) {
+      registeredPaths.add(resolve(dir, r.path));
+    }
+    const toAdd = [];
+    const submodules = WorkspaceManager.discoverSubmodules(dir);
+    for (const s of submodules) {
+      if (s.isInitialized) {
+        const abs = resolve(dir, s.path);
+        if (!registeredPaths.has(abs)) {
+          toAdd.push({ name: s.name, path: s.path });
+          registeredPaths.add(abs);
+        }
+      }
+    }
+    const peers = WorkspaceManager.discoverPeerRepos(dir);
+    for (const p of peers) {
+      const abs = resolve(dir, p.path);
+      if (!registeredPaths.has(abs)) {
+        toAdd.push({ name: p.name, path: p.path });
+        registeredPaths.add(abs);
+      }
+    }
+    const wsFiles = readdirSync(dir).filter((f) => f.endsWith(".code-workspace"));
+    for (const f of wsFiles) {
+      const wsFolderRepos = WorkspaceManager.discoverVSCodeWorkspace(join(dir, f), dir);
+      for (const p of wsFolderRepos) {
+        const abs = resolve(dir, p.path);
+        if (!registeredPaths.has(abs)) {
+          toAdd.push({ name: p.name, path: p.path });
+          registeredPaths.add(abs);
+        }
+      }
+    }
+    if (toAdd.length === 0) {
+      console.log("No new repositories discovered to sync.");
+      return;
+    }
+    console.log(`Syncing ${toAdd.length} newly discovered repositories:`);
+    const scanner = new Scanner(store, config, graph, createProgressRenderer());
+    for (const item of toAdd) {
+      config.addRepo(item.name, item.path);
+      console.log(`  + Registered: ${item.name} -> ${item.path}`);
+    }
+    await config.save();
+    console.log("\nRunning initial full scan for new repositories...");
+    const newNames = toAdd.map((item) => item.name);
+    const result = await scanner.scanFull(newNames);
+    console.log(`Scanned ${result.filesScanned} files, ${result.symbolsFound} symbols, ${result.edgesFound} edges in ${result.durationMs}ms`);
+  });
+  return program;
+}
+async function loadContext(dir) {
+  const configPath = resolve(dir, ".mapx", "config.json");
+  if (!existsSync(configPath)) {
+    console.error(`MapxGraph not initialized in ${dir}. Run \`mapx init ${dir}\` first.`);
+    process.exit(1);
+  }
+  const config = await Config.load(dir);
+  const dbPath = resolve(dir, ".mapx", "mapx.db");
+  const store = new Store(dbPath);
+  const closeStore = () => {
+    try {
+      store.close();
+    } catch {
+    }
+  };
+  process.once("exit", closeStore);
+  process.once("SIGINT", () => {
+    closeStore();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    closeStore();
+    process.exit(143);
+  });
+  const graph = new MapxGraph(config.repo.name);
+  const files = store.getAllFiles();
+  for (const file of files) {
+    graph.addFileNode(
+      file.path,
+      file.language,
+      file.size_bytes,
+      file.lines
+    );
+  }
+  const symbols = store.getAllSymbols();
+  for (const sym of symbols) {
+    graph.addSymbolNode(
+      sym.name,
+      sym.file_path,
+      sym.name,
+      sym.kind,
+      sym.start_line,
+      sym.end_line,
+      sym.scope
+    );
+  }
+  const edges = store.getAllEdges();
+  for (const edge of edges) {
+    graph.addDependencyEdge({
+      sourceFile: edge.source_file,
+      targetFile: edge.target_file,
+      sourceSymbol: edge.source_symbol,
+      targetSymbol: edge.target_symbol,
+      edgeType: edge.edge_type,
+      repo: edge.repo,
+      weight: edge.weight,
+      verifiability: edge.verifiability,
+      targetRepo: edge.target_repo
+    });
+  }
+  return { config, store, graph };
+}
+export {
+  buildCLI,
+  loadContext
+};