kirograph 0.12.1

package/dist/mcp/tools.js

@@ -0,0 +1,779 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tools_exports = {};
+__export(tools_exports, {
+  ToolHandler: () => ToolHandler,
+  tools: () => tools
+});
+module.exports = __toCommonJS(tools_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+var import__ = __toESM(require("../index"));
+var import_errors = require("../errors");
+const MAX_OUTPUT = 15e3;
+function truncate(s) {
+  return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + "\n\u2026[truncated]" : s;
+}
+function clampLimit(value, defaultValue) {
+  const n = typeof value === "number" ? value : defaultValue;
+  return Math.max(1, Math.min(100, Math.round(n)));
+}
+function mapKind(kind) {
+  if (kind === "type_alias") return "type";
+  return kind;
+}
+function writeSessionMarker(projectRoot) {
+  try {
+    const hash = crypto.createHash("sha256").update(projectRoot).digest("hex").slice(0, 16);
+    fs.writeFileSync(`/tmp/kirograph-consulted-${hash}`, String(Date.now()));
+  } catch {
+  }
+}
+const tools = [
+  {
+    name: "kirograph_search",
+    description: "Quick symbol search by name. Returns locations only (no code). Use kirograph_context for comprehensive task context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: 'Symbol name or partial name (e.g., "auth", "signIn", "UserService")' },
+        kind: {
+          type: "string",
+          description: "Filter by node kind",
+          enum: ["function", "method", "class", "interface", "type_alias", "variable", "route", "component"]
+        },
+        limit: { type: "number", description: "Max results 1-100 (default: 10)", default: 10 },
+        projectPath: { type: "string", description: "Project root path (optional, defaults to current project)" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "kirograph_context",
+    description: "PRIMARY TOOL: Build comprehensive context for a task or feature request. Returns entry points, related symbols, and key code \u2014 often enough to understand the codebase without additional tool calls.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Description of the task, bug, or feature to build context for" },
+        maxNodes: { type: "number", description: "Max symbols to include (default: 20)", default: 20 },
+        includeCode: { type: "boolean", description: "Include code snippets (default: true)", default: true },
+        projectPath: { type: "string", description: "Project root path (optional, defaults to current project)" }
+      },
+      required: ["task"]
+    }
+  },
+  {
+    name: "kirograph_callers",
+    description: "Find all functions/methods that call a specific symbol.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Symbol name to find callers for" },
+        limit: { type: "number", description: "Max results 1-100 (default: 20)", default: 20 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["symbol"]
+    }
+  },
+  {
+    name: "kirograph_callees",
+    description: "Find all functions/methods that a specific symbol calls.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Symbol name to find callees for" },
+        limit: { type: "number", description: "Max results 1-100 (default: 20)", default: 20 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["symbol"]
+    }
+  },
+  {
+    name: "kirograph_impact",
+    description: "Analyze what code would be affected by changing a symbol. Use before making changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Symbol name to analyze impact for" },
+        depth: { type: "number", description: "Traversal depth (default: 2)", default: 2 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["symbol"]
+    }
+  },
+  {
+    name: "kirograph_node",
+    description: "Get details about a specific symbol, optionally including its source code.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Symbol name to look up" },
+        includeCode: { type: "boolean", description: "Include source code (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["symbol"]
+    }
+  },
+  {
+    name: "kirograph_status",
+    description: "Check index health and statistics.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_files",
+    description: "List the indexed file structure of the project. Supports filtering by path prefix, glob pattern, or depth.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filterPath: { type: "string", description: 'Filter by directory path prefix (e.g., "src/")' },
+        pattern: { type: "string", description: 'Filter by glob pattern (e.g., "**/*.ts")' },
+        maxDepth: { type: "number", description: "Limit tree depth" },
+        format: {
+          type: "string",
+          description: 'Output format: "tree" (default, visual tree), "flat" (one path per line), "grouped" (grouped by directory)',
+          enum: ["tree", "flat", "grouped"],
+          default: "tree"
+        },
+        includeMetadata: { type: "boolean", description: "Include language and symbol count (default: true)", default: true },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_dead_code",
+    description: "Find symbols with no incoming references (potential dead code). Only includes unexported symbols.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max results 1-100 (default: 50)", default: 50 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_circular_deps",
+    description: "Find circular import dependencies in the codebase.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_path",
+    description: "Find the shortest path between two symbols in the graph.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Source symbol name" },
+        to: { type: "string", description: "Target symbol name" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["from", "to"]
+    }
+  },
+  {
+    name: "kirograph_architecture",
+    description: "Get the high-level software architecture: packages, layers, and their dependencies. Requires enableArchitecture=true in config. Call this first on a new task to orient yourself without reading files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        level: {
+          type: "string",
+          description: 'View level: "packages" (package graph), "layers" (architectural layers), or "both" (default)',
+          enum: ["packages", "layers", "both"],
+          default: "both"
+        },
+        includeFiles: { type: "boolean", description: "Include per-file package/layer assignments (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_coupling",
+    description: "Show coupling metrics for packages: afferent (Ca), efferent (Ce), and instability (Ce/(Ca+Ce)). High instability = depends on many others; low instability = depended on by many. Requires enableArchitecture=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sortBy: {
+          type: "string",
+          description: 'Sort order: "instability" (default), "afferent", or "efferent"',
+          enum: ["instability", "afferent", "efferent"],
+          default: "instability"
+        },
+        limit: { type: "number", description: "Max results (default: 20)", default: 20 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_package",
+    description: "Drill into one package: files it contains, symbols it exports, packages it depends on, and packages that depend on it. Requires enableArchitecture=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        package: { type: "string", description: "Package name or path (partial match accepted)" },
+        includeFiles: { type: "boolean", description: "List files in the package (default: true)", default: true },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["package"]
+    }
+  },
+  {
+    name: "kirograph_hotspots",
+    description: "Find the most-connected symbols in the codebase by total edge degree (incoming + outgoing). Useful for identifying load-bearing code, core abstractions, or blast-radius hot zones.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max results 1-100 (default: 20)", default: 20 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_surprising",
+    description: "Find non-obvious cross-file connections: direct edges between symbols in structurally distant parts of the codebase. High-score pairs indicate unexpected coupling worth investigating.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max results 1-100 (default: 20)", default: 20 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_diff",
+    description: "Compare the current graph against a saved snapshot. Shows added/removed symbols and relationships since the snapshot was taken. Use `kirograph snapshot` CLI command to save a snapshot first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        snapshot: { type: "string", description: "Snapshot label to compare against. Omit to use the latest saved snapshot." },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_type_hierarchy",
+    description: "Traverse the type hierarchy of a class or interface (base types and derived types).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "Class or interface name" },
+        direction: {
+          type: "string",
+          description: 'Direction: "up" for base types, "down" for derived types, "both" for all (default)',
+          enum: ["up", "down", "both"],
+          default: "both"
+        },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["symbol"]
+    }
+  }
+];
+class ToolHandler {
+  constructor(cg) {
+    this.connections = /* @__PURE__ */ new Map();
+    this.defaultCg = cg;
+  }
+  setDefaultKiroGraph(cg) {
+    this.defaultCg = cg;
+  }
+  /** Close all cached cross-project connections. */
+  closeAll() {
+    for (const cg of this.connections.values()) {
+      try {
+        cg.close();
+      } catch {
+      }
+    }
+    this.connections.clear();
+  }
+  async getConnection(projectPath) {
+    if (!projectPath) return this.defaultCg;
+    const resolved = path.resolve(projectPath);
+    if (this.connections.has(resolved)) return this.connections.get(resolved);
+    try {
+      const cg = await import__.default.open(resolved);
+      this.connections.set(resolved, cg);
+      return cg;
+    } catch {
+      return null;
+    }
+  }
+  async handle(toolName, args) {
+    try {
+      const text = await this.dispatch(toolName, args);
+      return { content: [{ type: "text", text: truncate(text) }] };
+    } catch (err) {
+      (0, import_errors.logError)("MCP tool error", { tool: toolName, error: err });
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+  }
+  async dispatch(toolName, args) {
+    const cg = await this.getConnection(args.projectPath);
+    if (!cg) return "KiroGraph not initialized. Run `kirograph init` in your project first.";
+    writeSessionMarker(cg.getProjectRoot());
+    switch (toolName) {
+      case "kirograph_search": {
+        const limit = clampLimit(args.limit, 10);
+        const results = cg.searchNodes(
+          args.query,
+          args.kind,
+          limit
+        );
+        if (results.length === 0) return `No symbols found matching "${args.query}".`;
+        return results.map(
+          (r) => `${mapKind(r.node.kind)} ${r.node.name}
+  File: ${r.node.filePath}:${r.node.startLine}
+  Qualified: ${r.node.qualifiedName}`
+        ).join("\n\n");
+      }
+      case "kirograph_context": {
+        const ctx = await cg.buildContext(args.task, {
+          maxNodes: args.maxNodes ?? 20,
+          includeCode: args.includeCode ?? true
+        });
+        const lines = [ctx.summary, ""];
+        if (ctx.entryPoints.length === 0) {
+          lines.push("No matching symbols found. If this is a new feature, consider using kirograph_files to explore the codebase structure.");
+        } else {
+          lines.push("## Entry Points");
+          for (const n of ctx.entryPoints) {
+            lines.push(`- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`);
+            if (ctx.codeSnippets.has(n.id)) {
+              lines.push("```", ctx.codeSnippets.get(n.id), "```");
+            }
+          }
+          if (ctx.relatedNodes.length > 0) {
+            lines.push("", "## Related Symbols");
+            for (const n of ctx.relatedNodes.slice(0, 10)) {
+              lines.push(`- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`);
+            }
+          }
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_callers": {
+        const limit = clampLimit(args.limit, 20);
+        const results = cg.searchNodes(args.symbol, void 0, 5);
+        if (results.length === 0) return `Symbol "${args.symbol}" not found in index.`;
+        const node = results[0].node;
+        const callers = await cg.getCallers(node.id, limit);
+        if (callers.length === 0) return `No callers found for \`${node.name}\`.`;
+        return `Callers of \`${node.name}\`:
+` + callers.map(
+          (n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`
+        ).join("\n");
+      }
+      case "kirograph_callees": {
+        const limit = clampLimit(args.limit, 20);
+        const results = cg.searchNodes(args.symbol, void 0, 5);
+        if (results.length === 0) return `Symbol "${args.symbol}" not found in index.`;
+        const node = results[0].node;
+        const callees = await cg.getCallees(node.id, limit);
+        if (callees.length === 0) return `\`${node.name}\` doesn't call any indexed symbols.`;
+        return `\`${node.name}\` calls:
+` + callees.map(
+          (n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`
+        ).join("\n");
+      }
+      case "kirograph_impact": {
+        const results = cg.searchNodes(args.symbol, void 0, 5);
+        if (results.length === 0) return `Symbol "${args.symbol}" not found in index.`;
+        const node = results[0].node;
+        const affected = await cg.getImpactRadius(node.id, args.depth ?? 2);
+        if (affected.length === 0) return `No dependents found for \`${node.name}\`.`;
+        return `Changing \`${node.name}\` may affect ${affected.length} symbol(s):
+` + affected.map((n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`).join("\n");
+      }
+      case "kirograph_node": {
+        const results = cg.searchNodes(args.symbol, void 0, 5);
+        if (results.length === 0) return `Symbol "${args.symbol}" not found in index.`;
+        const node = results[0].node;
+        const lines = [
+          `${mapKind(node.kind)} \`${node.name}\``,
+          `File: ${node.filePath}:${node.startLine}-${node.endLine}`,
+          `Qualified: ${node.qualifiedName}`,
+          node.signature ? `Signature: ${node.signature}` : "",
+          node.docstring ? `Docs: ${node.docstring}` : ""
+        ].filter(Boolean);
+        if (args.includeCode) {
+          const src = cg.getNodeSource(node);
+          if (src) lines.push("", "```", src, "```");
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_status": {
+        const stats = await cg.getStats();
+        const langLine = Object.entries(stats.filesByLanguage).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k}=${v}`).join(", ");
+        const dbMb = (stats.dbSizeBytes / 1024 / 1024).toFixed(2);
+        const semanticLines = stats.embeddingsEnabled ? [
+          `  Semantic search: enabled`,
+          `  Semantic model:  ${stats.embeddingModel}`,
+          `  Semantic engine: ${stats.semanticEngine === "sqlite-vec" ? `sqlite-vec (${stats.vecIndexCount} entries in ANN index)` : stats.semanticEngine === "orama" ? `orama hybrid (${stats.vecIndexCount} docs in index)` : stats.semanticEngine === "pglite" ? `pglite+pgvector (${stats.vecIndexCount} rows in DB)` : stats.semanticEngine === "lancedb" ? `lancedb (${stats.vecIndexCount} entries in ANN index)` : stats.semanticEngine === "qdrant" ? `qdrant (${stats.vecIndexCount} points in collection)` : stats.semanticEngine === "typesense" ? `typesense (${stats.vecIndexCount} documents in collection)` : "in-process cosine"}`,
+          `  Embeddings:      ${stats.embeddingCount} / ${stats.embeddableNodeCount || stats.nodes} embeddable symbols`,
+          ...stats.engineFallback ? [`  \u26A0 Engine fallback: ${stats.engineFallback}`] : []
+        ] : [`  Semantic search: disabled`];
+        const frameworkLine = stats.frameworks.length > 0 ? `  Frameworks: ${stats.frameworks.join(", ")}` : `  Frameworks: none detected`;
+        const archLine = stats.architectureEnabled ? stats.architectureStats ? `  Architecture: enabled \u2014 ${stats.architectureStats.packages} packages, ${stats.architectureStats.layers} layers, ${stats.architectureStats.packageDeps} deps` : `  Architecture: enabled (not yet analyzed \u2014 run kirograph index)` : `  Architecture: disabled`;
+        const threshold = stats.syncWarningThreshold ?? 10;
+        const pendingFiles = stats.pendingFiles ?? 0;
+        const syncRunning = stats.syncRunning ?? false;
+        const syncLines = [];
+        if (syncRunning) {
+          syncLines.push(`  \u26A0 Sync is currently running in the background.`);
+        }
+        if (threshold > 0 && pendingFiles >= threshold) {
+          syncLines.push(
+            `  \u26A0 Index may be incomplete \u2014 ${pendingFiles} file${pendingFiles !== 1 ? "s" : ""} pending sync.` + (syncRunning ? " Sync is running in background." : " Run `kirograph sync` to update.") + ` Would you like to wait before proceeding?`
+          );
+        }
+        return [
+          `KiroGraph Status`,
+          `  Project: ${cg.getProjectRoot()}`,
+          `  Files indexed: ${stats.files}`,
+          `  Symbols: ${stats.nodes}`,
+          `  Relationships: ${stats.edges}`,
+          `  By kind: ${Object.entries(stats.nodesByKind).map(([k, v]) => `${k}=${v}`).join(", ")}`,
+          langLine ? `  By language: ${langLine}` : "",
+          frameworkLine,
+          archLine,
+          `  DB size: ${dbMb} MB`,
+          ...semanticLines,
+          ...syncLines
+        ].filter(Boolean).join("\n");
+      }
+      case "kirograph_files": {
+        let renderTree2 = function(nodes, prefix) {
+          for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            const isLast = i === nodes.length - 1;
+            const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+            const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+            const meta = includeMetadata && node.type === "file" && node.language ? `  [${node.language}${node.symbolCount ? ` \xB7 ${node.symbolCount} symbols` : ""}]` : "";
+            lines.push(`${prefix}${connector}${node.name}${meta}`);
+            if (node.children?.length) renderTree2(node.children, childPrefix);
+          }
+        };
+        var renderTree = renderTree2;
+        const format = args.format ?? "tree";
+        const includeMetadata = args.includeMetadata !== false;
+        const tree = cg.getFiles({
+          filterPath: args.filterPath,
+          pattern: args.pattern,
+          maxDepth: args.maxDepth
+        });
+        if (format === "flat") {
+          let flattenTree2 = function(nodes) {
+            for (const node of nodes) {
+              if (node.type === "file") {
+                const meta = includeMetadata && node.language ? ` [${node.language}${node.symbolCount ? ` \xB7 ${node.symbolCount}` : ""}]` : "";
+                flat.push(`${node.path}${meta}`);
+              }
+              if (node.children?.length) flattenTree2(node.children);
+            }
+          };
+          var flattenTree = flattenTree2;
+          const flat = [];
+          flattenTree2(tree);
+          return flat.length > 0 ? flat.join("\n") : "No indexed files found.";
+        }
+        if (format === "grouped") {
+          let groupTree2 = function(nodes) {
+            for (const node of nodes) {
+              if (node.type === "file") {
+                const dir = node.path.includes("/") ? node.path.slice(0, node.path.lastIndexOf("/")) : ".";
+                if (!groups.has(dir)) groups.set(dir, []);
+                groups.get(dir).push(node);
+              }
+              if (node.children?.length) groupTree2(node.children);
+            }
+          };
+          var groupTree = groupTree2;
+          const groups = /* @__PURE__ */ new Map();
+          groupTree2(tree);
+          const lines2 = [];
+          for (const [dir, files] of [...groups.entries()].sort()) {
+            lines2.push(`${dir}/`);
+            for (const f of files) {
+              const meta = includeMetadata && f.language ? ` [${f.language}${f.symbolCount ? ` \xB7 ${f.symbolCount}` : ""}]` : "";
+              lines2.push(`  ${f.name}${meta}`);
+            }
+          }
+          return lines2.length > 0 ? lines2.join("\n") : "No indexed files found.";
+        }
+        const lines = [];
+        renderTree2(tree, "");
+        return lines.length > 0 ? lines.join("\n") : "No indexed files found.";
+      }
+      case "kirograph_dead_code": {
+        const limit = clampLimit(args.limit, 50);
+        const dead = cg.findDeadCode(limit);
+        if (dead.length === 0) return "No dead code detected.";
+        return `Potential dead code (${dead.length} unexported symbols with no incoming references):
+` + dead.map((n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`).join("\n");
+      }
+      case "kirograph_circular_deps": {
+        const cycles = cg.findCircularDependencies();
+        if (cycles.length === 0) return "No circular dependencies found.";
+        return `Found ${cycles.length} circular dependency cycle(s):
+` + cycles.map((cycle, i) => `Cycle ${i + 1}: ${cycle.join(" \u2192 ")}`).join("\n");
+      }
+      case "kirograph_path": {
+        const fromResults = cg.searchNodes(args.from, void 0, 3);
+        const toResults = cg.searchNodes(args.to, void 0, 3);
+        if (fromResults.length === 0) return `Symbol "${args.from}" not found in index.`;
+        if (toResults.length === 0) return `Symbol "${args.to}" not found in index.`;
+        const fromNode = fromResults[0].node;
+        const toNode = toResults[0].node;
+        const pathNodes = await cg.findPath(fromNode.id, toNode.id);
+        if (pathNodes.length === 0) return `No path found between \`${fromNode.name}\` and \`${toNode.name}\`.`;
+        return `Path from \`${fromNode.name}\` to \`${toNode.name}\` (${pathNodes.length} nodes):
+` + pathNodes.map((n, i) => `${i + 1}. ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`).join("\n");
+      }
+      case "kirograph_type_hierarchy": {
+        const results = cg.searchNodes(args.symbol, void 0, 5);
+        if (results.length === 0) return `Symbol "${args.symbol}" not found in index.`;
+        const node = results[0].node;
+        const direction = args.direction ?? "both";
+        const hierarchy = cg.getTypeHierarchy(node.id, direction);
+        if (hierarchy.length === 0) return `No type hierarchy found for \`${node.name}\`.`;
+        return `Type hierarchy for \`${node.name}\` (direction: ${direction}):
+` + hierarchy.map((n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`).join("\n");
+      }
+      case "kirograph_architecture": {
+        if (!cg.isArchitectureEnabled()) {
+          return "Architecture analysis is disabled. Set enableArchitecture=true in .kirograph/config.json and re-index.";
+        }
+        const level = args.level ?? "both";
+        const includeFiles = args.includeFiles === true;
+        const arch = cg.getArchitecture();
+        const lines = ["# Architecture"];
+        if ((level === "packages" || level === "both") && arch.packages.length > 0) {
+          lines.push("\n## Packages");
+          for (const pkg of arch.packages) {
+            const meta = [pkg.language, pkg.version].filter(Boolean).join(", ");
+            lines.push(`- **${pkg.name}** (${pkg.path}) [${pkg.source}${meta ? " \xB7 " + meta : ""}]`);
+          }
+          if (arch.packageDeps.length > 0) {
+            lines.push("\n## Package Dependencies");
+            for (const dep of arch.packageDeps) {
+              const src = arch.packages.find((p) => p.id === dep.sourcePkg)?.name ?? dep.sourcePkg;
+              const tgt = arch.packages.find((p) => p.id === dep.targetPkg)?.name ?? dep.targetPkg;
+              lines.push(`- ${src} \u2192 ${tgt} (${dep.depCount} import${dep.depCount !== 1 ? "s" : ""})`);
+            }
+          }
+        }
+        if ((level === "layers" || level === "both") && arch.layers.length > 0) {
+          lines.push("\n## Layers");
+          for (const layer of arch.layers) {
+            const fileCount = Object.values(arch.fileLayers).filter((fl) => fl.some((l) => l.layerId === layer.id)).length;
+            lines.push(`- **${layer.name}** [${layer.source}] \u2014 ${fileCount} file${fileCount !== 1 ? "s" : ""}`);
+          }
+          if (arch.layerDeps.length > 0) {
+            lines.push("\n## Layer Dependencies");
+            for (const dep of arch.layerDeps) {
+              const src = dep.sourceLayer.replace("layer:", "");
+              const tgt = dep.targetLayer.replace("layer:", "");
+              lines.push(`- ${src} \u2192 ${tgt} (${dep.depCount})`);
+            }
+          }
+        }
+        if (includeFiles && (level === "packages" || level === "both")) {
+          lines.push("\n## File \u2192 Package");
+          for (const [file, pkgIds] of Object.entries(arch.filePackages).slice(0, 50)) {
+            const names = pkgIds.map((id) => arch.packages.find((p) => p.id === id)?.name ?? id).join(", ");
+            lines.push(`- ${file}: ${names}`);
+          }
+          if (Object.keys(arch.filePackages).length > 50) lines.push("  \u2026(truncated)");
+        }
+        if (arch.packages.length === 0 && arch.layers.length === 0) {
+          return "No architecture data found. Run `kirograph index` with enableArchitecture=true.";
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_coupling": {
+        if (!cg.isArchitectureEnabled()) {
+          return "Architecture analysis is disabled. Set enableArchitecture=true in .kirograph/config.json and re-index.";
+        }
+        const sortBy = args.sortBy ?? "instability";
+        const limit = clampLimit(args.limit, 20);
+        const arch = cg.getArchitecture();
+        if (arch.coupling.length === 0) {
+          return "No coupling data. Run `kirograph index` with enableArchitecture=true.";
+        }
+        const sorted = [...arch.coupling].sort((a, b) => {
+          if (sortBy === "afferent") return b.afferent - a.afferent;
+          if (sortBy === "efferent") return b.efferent - a.efferent;
+          return b.instability - a.instability;
+        }).slice(0, limit);
+        const lines = [
+          `Coupling Metrics (sorted by ${sortBy}):`,
+          "",
+          "Package                          Ca    Ce    I",
+          "\u2500".repeat(52)
+        ];
+        for (const c of sorted) {
+          const pkg = arch.packages.find((p) => p.id === c.packageId);
+          const name = (pkg?.name ?? c.packageId).slice(0, 32).padEnd(32);
+          const ca = String(c.afferent).padStart(4);
+          const ce = String(c.efferent).padStart(4);
+          const inst = c.instability.toFixed(2).padStart(5);
+          lines.push(`${name}  ${ca}  ${ce}  ${inst}`);
+        }
+        lines.push("", "Ca=afferent (depended on by), Ce=efferent (depends on), I=instability (Ce/(Ca+Ce))");
+        return lines.join("\n");
+      }
+      case "kirograph_package": {
+        if (!cg.isArchitectureEnabled()) {
+          return "Architecture analysis is disabled. Set enableArchitecture=true in .kirograph/config.json and re-index.";
+        }
+        const query = args.package.toLowerCase();
+        const includeFiles = args.includeFiles !== false;
+        const arch = cg.getArchitecture();
+        const pkg = arch.packages.find(
+          (p) => p.name.toLowerCase().includes(query) || p.path.toLowerCase().includes(query) || p.id.toLowerCase().includes(query)
+        );
+        if (!pkg) return `Package "${args.package}" not found. Use kirograph_architecture to list all packages.`;
+        const lines = [
+          `## Package: ${pkg.name}`,
+          `Path: ${pkg.path}`,
+          `Source: ${pkg.source}${pkg.manifestPath ? ` (${pkg.manifestPath})` : ""}`,
+          ...pkg.version ? [`Version: ${pkg.version}`] : [],
+          ...pkg.language ? [`Language: ${pkg.language}`] : []
+        ];
+        const deps = arch.packageDeps.filter((d) => d.sourcePkg === pkg.id);
+        const dependents = arch.packageDeps.filter((d) => d.targetPkg === pkg.id);
+        const coupling = arch.coupling.find((c) => c.packageId === pkg.id);
+        if (coupling) {
+          lines.push("", `Coupling: Ca=${coupling.afferent} Ce=${coupling.efferent} I=${coupling.instability.toFixed(2)}`);
+        }
+        if (deps.length > 0) {
+          lines.push("", `Depends on (${deps.length}):`);
+          for (const dep of deps) {
+            const name = arch.packages.find((p) => p.id === dep.targetPkg)?.name ?? dep.targetPkg;
+            lines.push(`  \u2192 ${name} (${dep.depCount} import${dep.depCount !== 1 ? "s" : ""})`);
+          }
+        }
+        if (dependents.length > 0) {
+          lines.push("", `Depended on by (${dependents.length}):`);
+          for (const dep of dependents) {
+            const name = arch.packages.find((p) => p.id === dep.sourcePkg)?.name ?? dep.sourcePkg;
+            lines.push(`  \u2190 ${name} (${dep.depCount} import${dep.depCount !== 1 ? "s" : ""})`);
+          }
+        }
+        if (pkg.externalDeps && pkg.externalDeps.length > 0) {
+          lines.push("", `External deps (${pkg.externalDeps.length}): ${pkg.externalDeps.slice(0, 10).join(", ")}${pkg.externalDeps.length > 10 ? "\u2026" : ""}`);
+        }
+        if (includeFiles) {
+          const files = Object.entries(arch.filePackages).filter(([, ids]) => ids.includes(pkg.id)).map(([f]) => f).sort();
+          if (files.length > 0) {
+            lines.push("", `Files (${files.length}):`);
+            for (const f of files.slice(0, 30)) lines.push(`  ${f}`);
+            if (files.length > 30) lines.push(`  \u2026and ${files.length - 30} more`);
+          }
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_hotspots": {
+        const limit = clampLimit(args.limit, 20);
+        const hotspots = cg.findHotspots(limit);
+        if (hotspots.length === 0) return "No symbols found in index.";
+        const lines = [`Top ${hotspots.length} most-connected symbols (by edge degree):
+`];
+        for (const n of hotspots) {
+          lines.push(`${mapKind(n.kind)} \`${n.name}\` \u2014 degree ${n.degree} (in: ${n.inDegree}, out: ${n.outDegree})`);
+          lines.push(`  File: ${n.filePath}:${n.startLine}`);
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_surprising": {
+        const limit = clampLimit(args.limit, 20);
+        const connections = cg.findSurprisingConnections(limit);
+        if (connections.length === 0) return "No surprising cross-file connections found.";
+        const lines = [`Top ${connections.length} surprising cross-file connections:
+`];
+        for (const c of connections) {
+          lines.push(`${mapKind(c.source.kind)} \`${c.source.name}\` ${c.kind}\u2192 ${mapKind(c.target.kind)} \`${c.target.name}\` (score: ${c.score.toFixed(2)})`);
+          lines.push(`  ${c.source.filePath} \u2192 ${c.target.filePath}`);
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_diff": {
+        const sm = cg.createSnapshotManager();
+        const snapshot = args.snapshot ? sm.load(args.snapshot) : sm.loadLatest();
+        if (!snapshot) {
+          return args.snapshot ? `Snapshot "${args.snapshot}" not found. Use \`kirograph snapshot list\` to see available snapshots.` : "No snapshots found. Run `kirograph snapshot` to save one first.";
+        }
+        const diff = sm.diff(snapshot, sm.currentSnapshot());
+        const fromDate = new Date(diff.from.timestamp).toISOString().slice(0, 19).replace("T", " ");
+        const lines = [
+          `Graph diff: "${diff.from.label}" (${fromDate}) \u2192 current`,
+          ``,
+          `Symbols: +${diff.addedNodes.length} added, -${diff.removedNodes.length} removed`,
+          `Edges:   +${diff.addedEdges.length} added, -${diff.removedEdges.length} removed`
+        ];
+        if (diff.addedNodes.length > 0) {
+          lines.push(`
+## Added symbols (${diff.addedNodes.length})`);
+          for (const n of diff.addedNodes.slice(0, 30)) {
+            lines.push(`+ ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}`);
+          }
+          if (diff.addedNodes.length > 30) lines.push(`  \u2026and ${diff.addedNodes.length - 30} more`);
+        }
+        if (diff.removedNodes.length > 0) {
+          lines.push(`
+## Removed symbols (${diff.removedNodes.length})`);
+          for (const n of diff.removedNodes.slice(0, 30)) {
+            lines.push(`- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}`);
+          }
+          if (diff.removedNodes.length > 30) lines.push(`  \u2026and ${diff.removedNodes.length - 30} more`);
+        }
+        return lines.join("\n");
+      }
+      default:
+        return `Unknown tool: ${toolName}`;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ToolHandler,
+  tools
+});
+//# sourceMappingURL=tools.js.map