@plumpslabs/kuma 2.3.6 → 2.3.7

package/dist/index.js

@@ -15,12 +15,21 @@ import {
   searchGraph,
   traceFlow
 } from "./chunk-K64NSHBR.js";
+import {
+  formatDecisionTemplate,
+  getProactiveMemories,
+  recordDecision,
+  scoreMemoryRelevance
+} from "./chunk-X5TPBDKO.js";
 import {
   buildDriftMessages,
   getGitDiffStat,
   getSessionStats,
   getUnresolvedCount
 } from "./chunk-FOQQ2CSL.js";
+import {
+  sessionMemory
+} from "./chunk-BI7KD3SG.js";
 import {
   addContextNote,
   addSecurityFinding,
@@ -47,15 +56,6 @@ import {
   updateDecisionStatus,
   updateTodoStatus
 } from "./chunk-GDNAWLHF.js";
-import {
-  formatDecisionTemplate,
-  getProactiveMemories,
-  recordDecision,
-  scoreMemoryRelevance
-} from "./chunk-X5TPBDKO.js";
-import {
-  sessionMemory
-} from "./chunk-BI7KD3SG.js";
 import {
   getProjectRoot,
   validateFilePath
@@ -87,7 +87,7 @@ var CONTEXT_ALIASES = {
   "refactor": "impact",
   // Navigate synonyms
   "trace": "navigate",
-  "flow": "navigate",
+  "flow-trace": "navigate",
   "navigate": "navigate",
   // Init synonyms
   "init": "init",
@@ -117,7 +117,14 @@ var CONTEXT_ALIASES = {
   "batch": "sync",
   "kuma_sync": "sync",
   "unified": "sync",
-  "state": "sync"
+  "state": "sync",
+  // Visualize synonyms (Issue #16)
+  "visualize": "visualize",
+  "graph": "visualize",
+  "diagram": "visualize",
+  "flow": "visualize",
+  "viz": "visualize",
+  "kuma_visualize": "visualize"
 };
 async function handleContext(params) {
   const rawAction = params.action || "init";
@@ -142,8 +149,10 @@ async function handleContext(params) {
       return handleHealth(params);
     case "sync":
       return handleSync(params);
+    case "visualize":
+      return handleVisualize(params);
     default:
-      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync`;
+      return `Unknown action "${action}". Use: init, research, impact, navigate, changes, rollback, researches, health, sync, visualize`;
   }
 }
 async function handleInit(_params) {
@@ -437,6 +446,15 @@ async function handleSync(params) {
   lines.push("\u{1F4A1} Sync complete \u2014 all state captured in a single roundtrip.");
   return lines.join("\n");
 }
+async function handleVisualize(params) {
+  const scope = params.scope;
+  const { generateVisualizeReport } = await import("./kumaVisualize-ODCWFSUY.js");
+  return await generateVisualizeReport({
+    scope,
+    type: "flowchart",
+    maxNodes: 40
+  });
+}
 function computeProjectHash(scope) {
   try {
     const root = getProjectRoot();
@@ -638,6 +656,15 @@ async function handleSearch(params) {
   const memResults = sessionMemory.searchMemory(query, limit);
   const { searchGraph: searchGraph2 } = await import("./kumaGraph-35TAIBWD.js");
   const graphResults = await searchGraph2(query, Math.min(limit, 10));
+  let hybridResults = "";
+  try {
+    const { hybridSearch, formatHybridResults } = await import("./kumaSearch-LG2OYEJY.js");
+    const semanticResults = await hybridSearch(query, 8);
+    if (semanticResults.length > 0) {
+      hybridResults = "\n" + formatHybridResults(query, semanticResults);
+    }
+  } catch {
+  }
   const lines = [`\u{1F50D} **Search Results** \u2014 "${query}"
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 `];
@@ -647,6 +674,10 @@ async function handleSearch(params) {
     lines.push("");
   }
   lines.push("**Knowledge Graph:**\n" + graphResults);
+  if (hybridResults) {
+    lines.push("");
+    lines.push(hybridResults);
+  }
   return lines.join("\n");
 }
 async function handleChanges2(params) {
@@ -711,7 +742,7 @@ async function handleDecisionLog(params) {
 }
 async function handleMine(params) {
   sessionMemory.recordToolCall("kuma_memory_mine", { scope: params.scope });
-  const { mineHistoricalDecisions } = await import("./kumaMiner-BIDSZE3Q.js");
+  const { mineHistoricalDecisions } = await import("./kumaMiner-P5KCUSF7.js");
   return await mineHistoricalDecisions({
     scope: params.scope,
     since: typeof params.since === "string" ? params.since : void 0,
@@ -1962,7 +1993,7 @@ async function handleVerify(params) {
   }
   _lastVerifyCall = now;
   sessionMemory.recordToolCall("kuma_safety_verify", { scope: params.scope || params.filePath });
-  const { runAutoVerification } = await import("./kumaVerifier-B4D7NOFT.js");
+  const { runAutoVerification } = await import("./kumaVerifier-LFRNIGSL.js");
   return await runAutoVerification({
     scope: params.scope || params.filePath,
     force: params.force,
@@ -1976,7 +2007,7 @@ function registerAllTools(server) {
     "kuma_context",
     "**Call FIRST every session.** Understand your project before making changes. Actions: init (load project brief), research (5-step pipeline: cache\u2192staleness\u2192graph\u2192impact\u2192decision), impact (analyze change effects), navigate (trace code flow), changes (view change log), health (project health score 0-100). RESEARCH IS REQUIRED before editing unfamiliar code.",
     {
-      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, health=project health score"),
+      action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, health=project health score"),
       scope: z.string().optional().describe("Research scope for research action (e.g. 'auth', 'database', 'api')"),
       target: z.string().optional().describe("Target symbol/file for impact/navigate/changes"),
       goal: z.string().optional().describe("Current goal (for init/health)"),
@@ -2161,7 +2192,7 @@ async function main() {
     console.error("");
     let killedCount = 0;
     try {
-      const { getRunningVerificationPid } = await import("./kumaVerifier-B4D7NOFT.js");
+      const { getRunningVerificationPid } = await import("./kumaVerifier-LFRNIGSL.js");
       const pid = getRunningVerificationPid();
       if (pid) {
         try {
@@ -2253,6 +2284,9 @@ async function main() {
     console.error("");
     process.exit(0);
   }
+  if (args[0] === "--hook") {
+    process.exit(0);
+  }
   if (args[0] === "init") {
     const flags = args.slice(1);
     if (flags.includes("--help") || flags.includes("-h")) {
@@ -2430,6 +2464,44 @@ async function main() {
       } catch (err) {
         console.error(`[${SERVER_NAME}] \u26A0\uFE0F Session DB record: ${err}`);
       }
+      try {
+        const fs7 = await import("fs");
+        const path7 = await import("path");
+        const hooksDir = path7.resolve(process.cwd(), ".kuma", "hooks");
+        if (!fs7.existsSync(hooksDir)) {
+          fs7.mkdirSync(hooksDir, { recursive: true });
+          const hookContent = `#!/bin/bash
+# Kuma auto-capture hook (post-commit)
+# Auto-updates knowledge graph after git commits
+if command -v npx &> /dev/null; then
+  npx -y @plumpslabs/kuma --hook post-commit 2>/dev/null || true
+fi
+`;
+          const gitHooksDir = path7.resolve(process.cwd(), ".git", "hooks");
+          if (fs7.existsSync(gitHooksDir)) {
+            const postCommitPath = path7.join(gitHooksDir, "post-commit");
+            if (!fs7.existsSync(postCommitPath)) {
+              fs7.writeFileSync(postCommitPath, hookContent, "utf-8");
+              try {
+                fs7.chmodSync(postCommitPath, 493);
+              } catch {
+              }
+              console.error(`[${SERVER_NAME}] \u2705 Created .git/hooks/post-commit for auto-capture`);
+            }
+          }
+        }
+      } catch (err) {
+        console.error(`[${SERVER_NAME}] \u26A0\uFE0F Auto-capture hook setup: ${err}`);
+      }
+      try {
+        const { buildSearchVectors } = await import("./kumaSearch-LG2OYEJY.js");
+        const vectors = await buildSearchVectors();
+        if (vectors.length > 0) {
+          console.error(`[${SERVER_NAME}] \u2705 Search vector cache pre-warmed (${vectors.length} documents)`);
+        }
+      } catch (err) {
+        console.error(`[${SERVER_NAME}] \u26A0\uFE0F Search vector cache: ${err}`);
+      }
       console.error(`[${SERVER_NAME}] \u2705 Cold start bootstrap complete`);
     } catch (err) {
       console.error(`[${SERVER_NAME}] \u26A0\uFE0F Cold start bootstrap error: ${err}`);

package/dist/kumaSearch-LG2OYEJY.js

@@ -0,0 +1,321 @@
+import {
+  getDb
+} from "./chunk-GDNAWLHF.js";
+import {
+  getProjectRoot
+} from "./chunk-E2KFPEBT.js";
+
+// src/engine/kumaSearch.ts
+import fs from "fs";
+import path from "path";
+var SYNONYM_MAP = {
+  timeout: ["timeout", "duration", "expiry", "ttl", "deadline", "latency"],
+  duration: ["duration", "timeout", "length", "period", "interval"],
+  delay: ["delay", "wait", "latency", "defer", "throttle"],
+  latency: ["latency", "delay", "response time", "speed", "performance"],
+  error: ["error", "failure", "exception", "bug", "fault", "crash"],
+  crash: ["crash", "panic", "oom", "out of memory", "segfault"],
+  fail: ["fail", "error", "break", "regression", "broken"],
+  auth: ["auth", "authentication", "login", "oauth", "session", "token", "credential"],
+  login: ["login", "signin", "auth", "authenticate"],
+  token: ["token", "jwt", "session", "api key", "secret"],
+  permission: ["permission", "access", "role", "rbac", "authorization", "acl"],
+  database: ["database", "db", "storage", "persistence", "sql", "nosql"],
+  query: ["query", "search", "fetch", "select", "lookup"],
+  index: ["index", "key", "lookup", "search"],
+  cache: ["cache", "memcached", "redis", "buffer", "temporary storage"],
+  api: ["api", "endpoint", "route", "rest", "graphql", "service"],
+  route: ["route", "endpoint", "path", "handler"],
+  request: ["request", "http", "call", "fetch", "invocation"],
+  response: ["response", "reply", "result", "output"],
+  performance: ["performance", "speed", "latency", "throughput", "efficiency"],
+  memory: ["memory", "ram", "heap", "allocation", "leak"],
+  cpu: ["cpu", "processor", "compute", "thread", "worker"],
+  architecture: ["architecture", "design", "pattern", "structure", "system"],
+  service: ["service", "microservice", "module", "component", "layer"],
+  config: ["config", "configuration", "setting", "env", "environment"],
+  deploy: ["deploy", "release", "rollout", "publish", "ship"],
+  build: ["build", "compile", "bundle", "transpile", "package"],
+  test: ["test", "spec", "unit test", "integration", "e2e"],
+  lint: ["lint", "format", "style", "prettier", "eslint"],
+  redis: ["redis", "cache", "session store", "message queue"],
+  postgres: ["postgres", "postgresql", "psql", "relational db", "sql"],
+  docker: ["docker", "container", "image", "dockerfile", "compose"],
+  typescript: ["typescript", "ts", "type system", "compiler"],
+  prisma: ["prisma", "orm", "database client", "schema"],
+  create: ["create", "add", "new", "make", "generate"],
+  update: ["update", "modify", "change", "edit", "patch"],
+  delete: ["delete", "remove", "drop", "clear", "purge"]
+};
+function expandQueryTerms(query) {
+  const terms = query.toLowerCase().split(/[\s_-]+/).filter((t) => t.length > 2);
+  const expanded = /* @__PURE__ */ new Map();
+  for (const term of terms) {
+    const sources = /* @__PURE__ */ new Set();
+    sources.add(term);
+    if (SYNONYM_MAP[term]) {
+      for (const syn of SYNONYM_MAP[term]) {
+        sources.add(syn);
+      }
+    }
+    for (const [key, synonyms] of Object.entries(SYNONYM_MAP)) {
+      if (synonyms.includes(term)) {
+        sources.add(key);
+      }
+    }
+    expanded.set(term, sources);
+  }
+  return expanded;
+}
+var _vectorCache = null;
+var VECTOR_CACHE_TTL = 3e5;
+async function buildSearchVectors() {
+  if (_vectorCache && Date.now() - _vectorCache.builtAt < VECTOR_CACHE_TTL) {
+    return _vectorCache.vectors;
+  }
+  const vectors = [];
+  try {
+    const db = await getDb();
+    const stmt = db.prepare("SELECT id, name, metadata, file_path FROM nodes ORDER BY updated_at DESC LIMIT 500");
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const name = row.name || "";
+      const metaStr = row.metadata || "{}";
+      let metaText = "";
+      try {
+        const meta = JSON.parse(metaStr);
+        metaText = Object.values(meta).join(" ");
+      } catch {
+      }
+      const filePath = row.file_path || "";
+      const nodeText = `${name} ${metaText} ${filePath}`.toLowerCase();
+      const rawTerms = extractTerms(nodeText);
+      const termCounts = /* @__PURE__ */ new Map();
+      for (const t of rawTerms) {
+        termCounts.set(t, (termCounts.get(t) || 0) + 1);
+      }
+      vectors.push({
+        terms: termCounts,
+        source: name || row.id,
+        sourceType: "graph"
+      });
+    }
+    stmt.free();
+  } catch {
+  }
+  try {
+    const root = getProjectRoot();
+    const memDir = path.join(root, ".kuma", "memories");
+    if (fs.existsSync(memDir)) {
+      const files = fs.readdirSync(memDir).filter((f) => f.endsWith(".md")).slice(0, 10);
+      for (const file of files) {
+        try {
+          const content = fs.readFileSync(path.join(memDir, file), "utf-8");
+          const text = content.toLowerCase();
+          const rawTerms = extractTerms(text);
+          const termCounts = /* @__PURE__ */ new Map();
+          for (const t of rawTerms) {
+            termCounts.set(t, (termCounts.get(t) || 0) + 1);
+          }
+          vectors.push({
+            terms: termCounts,
+            source: file.replace(/\.md$/, ""),
+            sourceType: "memory"
+          });
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  try {
+    const db = await getDb();
+    const stmt = db.prepare("SELECT scope, record FROM research_cache ORDER BY updated_at DESC LIMIT 50");
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const scope = row.scope || "";
+      const record = row.record || "";
+      const text = `${scope} ${record}`.toLowerCase();
+      const rawTerms = extractTerms(text);
+      const termCounts = /* @__PURE__ */ new Map();
+      for (const t of rawTerms) {
+        termCounts.set(t, (termCounts.get(t) || 0) + 1);
+      }
+      vectors.push({
+        terms: termCounts,
+        source: scope,
+        sourceType: "research"
+      });
+    }
+    stmt.free();
+  } catch {
+  }
+  const docCount = vectors.length || 1;
+  const docFreq = /* @__PURE__ */ new Map();
+  for (const vec of vectors) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const [term] of vec.terms) {
+      if (!seen.has(term)) {
+        docFreq.set(term, (docFreq.get(term) || 0) + 1);
+        seen.add(term);
+      }
+    }
+  }
+  for (const vec of vectors) {
+    const maxFreq = Math.max(1, ...Array.from(vec.terms.values()));
+    for (const [term, rawFreq] of vec.terms) {
+      const tf = 0.5 + 0.5 * rawFreq / maxFreq;
+      const docsWithTerm = docFreq.get(term) || 1;
+      const idf = Math.log(1 + (docCount - docsWithTerm + 0.5) / (docsWithTerm + 0.5));
+      vec.terms.set(term, tf * idf);
+    }
+  }
+  _vectorCache = { vectors, builtAt: Date.now() };
+  return vectors;
+}
+function extractTerms(text) {
+  return text.toLowerCase().split(/[\s,.;:!?()\[\]{}"'\/\\|@#$%^&*+=<>~`]+/).filter((t) => t.length > 2 && t.length < 50 && !/^\d+$/.test(t));
+}
+function cosineSimilarity(queryVec, docVec) {
+  let dotProduct = 0;
+  let queryMagnitude = 0;
+  let docMagnitude = 0;
+  for (const [term, qWeight] of queryVec) {
+    queryMagnitude += qWeight * qWeight;
+    const dWeight = docVec.get(term) || 0;
+    dotProduct += qWeight * dWeight;
+  }
+  for (const [, dWeight] of docVec) {
+    docMagnitude += dWeight * dWeight;
+  }
+  const mag = Math.sqrt(queryMagnitude) * Math.sqrt(docMagnitude);
+  if (mag === 0) return 0;
+  return dotProduct / mag;
+}
+async function hybridSearch(query, limit = 10) {
+  const results = [];
+  const expandedTerms = expandQueryTerms(query);
+  const allSearchTerms = /* @__PURE__ */ new Set();
+  for (const [, sources] of expandedTerms) {
+    for (const term of sources) {
+      allSearchTerms.add(term);
+    }
+  }
+  const searchTerms = Array.from(allSearchTerms);
+  const queryVector = /* @__PURE__ */ new Map();
+  for (const [originalTerm, sources] of expandedTerms) {
+    for (const term of sources) {
+      const weight = term === originalTerm ? 2 : 1;
+      queryVector.set(term, (queryVector.get(term) || 0) + weight);
+    }
+  }
+  try {
+    const db = await getDb();
+    const likeClauses = searchTerms.map(() => `name LIKE ?`).join(" OR ");
+    const sql = `SELECT id, name, type, file_path, metadata FROM nodes WHERE (${likeClauses}) LIMIT ${limit * 3}`;
+    const stmt = db.prepare(sql);
+    stmt.bind(searchTerms.map((t) => `%${t}%`));
+    const seen = /* @__PURE__ */ new Set();
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const name = row.name || "";
+      const filePath = row.file_path || "";
+      const sourceKey = name + filePath;
+      if (seen.has(sourceKey)) continue;
+      seen.add(sourceKey);
+      const lowerText = `${name} ${filePath}`.toLowerCase();
+      const matchedTerms = searchTerms.filter((t) => lowerText.includes(t));
+      const keywordScore = matchedTerms.length > 0 ? Math.round(matchedTerms.length / Math.max(1, searchTerms.length) * 100) : 0;
+      results.push({
+        source: name,
+        sourceType: "graph",
+        score: keywordScore,
+        keywordScore,
+        vectorScore: 0,
+        matchedTerms
+      });
+    }
+    stmt.free();
+  } catch (err) {
+    console.error(`[KumaSearch] DB search failed: ${err}`);
+  }
+  try {
+    const vectors = await buildSearchVectors();
+    for (const vec of vectors) {
+      const vectorScore = Math.round(cosineSimilarity(queryVector, vec.terms) * 100);
+      const existing = results.find((r) => r.source === vec.source);
+      if (existing) {
+        existing.vectorScore = vectorScore;
+        existing.score = Math.min(100, Math.round(existing.keywordScore * 0.6 + vectorScore * 0.4));
+        for (const [term] of vec.terms) {
+          if (queryVector.has(term) && !existing.matchedTerms.includes(term)) {
+            existing.matchedTerms.push(term);
+          }
+        }
+      } else if (vectorScore > 0) {
+        const matchedTerms = [];
+        for (const [term] of vec.terms) {
+          if (queryVector.has(term)) matchedTerms.push(term);
+        }
+        results.push({
+          source: vec.source,
+          sourceType: vec.sourceType,
+          score: Math.round(vectorScore * 0.4),
+          keywordScore: 0,
+          vectorScore,
+          matchedTerms
+        });
+      }
+    }
+  } catch (err) {
+    console.error(`[KumaSearch] Vector search failed: ${err}`);
+  }
+  const uniqueResults = Array.from(
+    new Map(results.map((r) => [r.source, r])).values()
+  );
+  return uniqueResults.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function formatHybridResults(query, results) {
+  const expandedTerms = expandQueryTerms(query);
+  const originalTerms = Array.from(expandedTerms.keys()).join(", ");
+  const totalSynonyms = Array.from(expandedTerms.values()).reduce(
+    (sum, s) => sum + s.size,
+    0
+  );
+  const lines = [
+    "**Hybrid Search** \u2014 " + query,
+    "----------------------------------------",
+    "",
+    "Expanded query: " + originalTerms + " (" + totalSynonyms + " total terms with synonyms)",
+    ""
+  ];
+  if (results.length === 0) {
+    lines.push("No results found. Try different keywords or research first.");
+    return lines.join("\n");
+  }
+  lines.push(results.length + " result(s) \u2014 ranked by hybrid relevance");
+  lines.push("");
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const typeIcon = r.sourceType === "graph" ? "file" : r.sourceType === "memory" ? "memory" : "research";
+    const matchType = r.vectorScore > r.keywordScore ? "semantic match" : r.keywordScore > 0 ? "keyword match" : "expanded match";
+    lines.push(i + 1 + ". [" + typeIcon + "] " + r.source + " \u2014 " + r.score + "%");
+    lines.push("   keyword: " + r.keywordScore + "% | vector: " + r.vectorScore + "% (" + matchType + ")");
+    if (r.matchedTerms.length > 0) {
+      lines.push("   Terms: " + r.matchedTerms.slice(0, 6).join(", "));
+    }
+    lines.push("");
+  }
+  lines.push("Hybrid search combines keyword matching with semantic synonym expansion.");
+  return lines.join("\n");
+}
+function clearSearchCache() {
+  _vectorCache = null;
+}
+export {
+  buildSearchVectors,
+  clearSearchCache,
+  expandQueryTerms,
+  formatHybridResults,
+  hybridSearch
+};

package/dist/kumaVisualize-ODCWFSUY.js

@@ -0,0 +1,248 @@
+import {
+  getDb
+} from "./chunk-GDNAWLHF.js";
+import "./chunk-E2KFPEBT.js";
+
+// src/engine/kumaVisualize.ts
+async function visualizeGraph(options = {}) {
+  const {
+    type = "flowchart",
+    scope,
+    maxNodes = 30,
+    // depth unused: kept for API consistency
+    format = "mermaid"
+  } = options;
+  try {
+    const db = await getDb();
+    let nodeSql = `SELECT id, type, name, file_path FROM nodes WHERE 1=1`;
+    const nodeBind = [];
+    if (scope) {
+      nodeSql += ` AND (name LIKE ? OR file_path LIKE ? OR id LIKE ?)`;
+      nodeBind.push(`%${scope}%`, `%${scope}%`, `%${scope}%`);
+    }
+    nodeSql += ` ORDER BY updated_at DESC LIMIT ?`;
+    nodeBind.push(maxNodes);
+    const nodeStmt = db.prepare(nodeSql);
+    nodeStmt.bind(nodeBind);
+    const nodes = [];
+    while (nodeStmt.step()) {
+      nodes.push(nodeStmt.getAsObject());
+    }
+    nodeStmt.free();
+    if (nodes.length === 0) {
+      return format === "mermaid" ? "```mermaid\nflowchart TD\n  Start[Empty Graph \u2014 No nodes found]\n```" : "\u{1F4ED} **Empty Graph** \u2014 No nodes found to visualize.";
+    }
+    const nodeIds = nodes.map((n) => n.id);
+    const edgeSql = `
+      SELECT e.source_id, e.target_id, e.type, e.weight,
+        sn.name AS source_name, tn.name AS target_name
+      FROM edges e
+      JOIN nodes sn ON sn.id = e.source_id
+      JOIN nodes tn ON tn.id = e.target_id
+      WHERE (e.source_id IN (${nodeIds.map(() => "?").join(",")})
+         OR e.target_id IN (${nodeIds.map(() => "?").join(",")}))
+        AND e.source_id != e.target_id
+      ORDER BY e.weight DESC
+      LIMIT 100
+    `;
+    const edgeBind = [...nodeIds, ...nodeIds];
+    const edgeStmt = db.prepare(edgeSql);
+    edgeStmt.bind(edgeBind);
+    const edges = [];
+    while (edgeStmt.step()) {
+      edges.push(edgeStmt.getAsObject());
+    }
+    edgeStmt.free();
+    switch (type) {
+      case "flowchart":
+        return formatFlowchart(nodes, edges, format);
+      case "dependency":
+        return formatDependencyGraph(nodes, edges, format);
+      case "mindmap":
+        return formatMindMap(nodes, edges, format);
+      default:
+        return formatFlowchart(nodes, edges, format);
+    }
+  } catch (err) {
+    return `Error generating visualization: ${err}`;
+  }
+}
+function formatFlowchart(nodes, edges, _format) {
+  void _format;
+  const lines = ["```mermaid", "flowchart TD"];
+  for (const node of nodes) {
+    const id = sanitizeId(node.id);
+    const name = truncate(node.name, 30);
+    const nodeType = node.type;
+    const shape = getNodeShape(nodeType);
+    if (shape) {
+      lines.push(`  ${id}${shape}${name}${reverseShape(shape)}`);
+    } else {
+      lines.push(`  ${id}[${name}]`);
+    }
+  }
+  for (const edge of edges) {
+    const sourceId = sanitizeId(edge.source_id);
+    const targetId = sanitizeId(edge.target_id);
+    const edgeType = edge.type;
+    void edge.weight;
+    const label = truncate(edgeType, 15);
+    const edgeStyle = getEdgeStyle(edgeType);
+    lines.push(`  ${sourceId}${edgeStyle}|${label}|${targetId}`);
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+function formatDependencyGraph(nodes, edges, _format) {
+  void _format;
+  const lines = ["```mermaid", "flowchart LR"];
+  const grouped = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const type = node.type || "unknown";
+    if (!grouped.has(type)) grouped.set(type, []);
+    grouped.get(type).push(node);
+  }
+  let subgraphIndex = 0;
+  for (const [type, typeNodes] of grouped) {
+    if (typeNodes.length < 1) continue;
+    lines.push(`  subgraph ${type.toUpperCase()}[${type.toUpperCase()}]`);
+    for (const node of typeNodes) {
+      const id = sanitizeId(node.id);
+      const name = truncate(node.name, 25);
+      lines.push(`    ${id}(${name})`);
+    }
+    lines.push("  end");
+    subgraphIndex++;
+  }
+  for (const edge of edges) {
+    const sourceId = sanitizeId(edge.source_id);
+    const targetId = sanitizeId(edge.target_id);
+    const edgeType = edge.type;
+    const style = getEdgeStyle(edgeType);
+    lines.push(`  ${sourceId}${style}|${edgeType}|${targetId}`);
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+function formatMindMap(nodes, edges, _format) {
+  void _format;
+  const lines = ["```mermaid", "mindmap"];
+  const hasIncoming = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    hasIncoming.add(edge.target_id);
+  }
+  const roots = nodes.filter((n) => !hasIncoming.has(n.id));
+  if (roots.length === 0 && nodes.length > 0) {
+    const root = nodes[0];
+    lines.push(`  root((${truncate(root.name, 25)}))`);
+    for (const node of nodes.slice(1)) {
+      lines.push(`    ${sanitizeId(node.id)}(${truncate(node.name, 25)})`);
+    }
+  } else {
+    for (const root of roots.slice(0, 3)) {
+      lines.push(`  root((${truncate(root.name, 25)}))`);
+    }
+    const others = nodes.filter((n) => !roots.includes(n));
+    for (const node of others.slice(0, 10)) {
+      const parent = edges.find((e) => e.source_id === node.id || e.target_id === node.id);
+      const indent = parent ? "    " : "  ";
+      lines.push(`${indent}${sanitizeId(node.id)}(${truncate(node.name, 25)})`);
+    }
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+function sanitizeId(id) {
+  const safe = id.replace(/[^a-zA-Z0-9_]/g, "_").replace(/^(\d)/, "n$1").substring(0, 40);
+  return safe || "n0";
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 3) + "...";
+}
+function getNodeShape(type) {
+  switch (type) {
+    case "function":
+      return "([";
+    case "file":
+      return "[";
+    case "test":
+      return "{";
+    case "api_route":
+      return "[[";
+    case "db_table":
+      return ">";
+    // database shape approximation
+    case "class":
+      return "[";
+    case "interface":
+      return "(";
+    case "module":
+      return "[";
+    case "variable":
+      return "(";
+    default:
+      return "[";
+  }
+}
+function reverseShape(shape) {
+  const map = {
+    "([": "])",
+    "[": "]",
+    "{": "}",
+    "[[": "]]",
+    ">": "<]",
+    "(": ")"
+  };
+  return map[shape] || "]";
+}
+function getEdgeStyle(type) {
+  switch (type) {
+    case "calls":
+      return " ==> ";
+    case "imports":
+      return " -.-> ";
+    case "defines":
+      return " --- ";
+    case "tests":
+      return " -.-> ";
+    case "routes":
+      return " ==> ";
+    case "implements":
+      return " -.-> ";
+    case "extends":
+      return " ==> ";
+    case "depends_on":
+      return " -.-> ";
+    case "owns":
+      return " --- ";
+    case "modified_by":
+      return " -.-> ";
+    default:
+      return " --- ";
+  }
+}
+async function generateVisualizeReport(options = {}) {
+  const diagram = await visualizeGraph(options);
+  const lines = [
+    "\u{1F3A8} **Knowledge Graph Visualization**",
+    "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    "",
+    diagram,
+    "",
+    "\u{1F4CB} **Rendering Instructions:**",
+    "- Paste the Mermaid code above into any Mermaid-compatible viewer",
+    "- GitHub: Mermaid code blocks render automatically",
+    "- VS Code: Install 'Markdown Preview Mermaid Support' extension",
+    "- Online: https://mermaid.live",
+    "",
+    "\u{1F4A1} Use `kuma_visualize({ type: 'dependency' })` for clustered view",
+    "\u{1F4A1} Use `kuma_visualize({ type: 'mindmap' })` for overview",
+    "\u{1F4A1} Use `kuma_visualize({ scope: 'auth' })` to filter by topic"
+  ];
+  return lines.join("\n");
+}
+export {
+  generateVisualizeReport,
+  visualizeGraph
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.6",
+  "version": "2.3.7",
   "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
   "type": "module",
   "main": "dist/index.js",

package/dist/{kumaMiner-BIDSZE3Q.js → kumaMiner-P5KCUSF7.js}

@@ -1,10 +1,10 @@
-import {
-  recordDecisionLog
-} from "./chunk-GDNAWLHF.js";
 import {
   recordDecision
 } from "./chunk-X5TPBDKO.js";
 import "./chunk-BI7KD3SG.js";
+import {
+  recordDecisionLog
+} from "./chunk-GDNAWLHF.js";
 import "./chunk-E2KFPEBT.js";
 
 // src/engine/kumaMiner.ts

package/dist/{kumaVerifier-B4D7NOFT.js → kumaVerifier-LFRNIGSL.js}

@@ -1,10 +1,10 @@
+import {
+  sessionMemory
+} from "./chunk-BI7KD3SG.js";
 import {
   getLatestVerifications,
   saveVerification
 } from "./chunk-GDNAWLHF.js";
-import {
-  sessionMemory
-} from "./chunk-BI7KD3SG.js";
 import "./chunk-E2KFPEBT.js";
 
 // src/engine/kumaVerifier.ts