@plumpslabs/kuma 2.3.24 → 2.3.25

package/README.md

@@ -142,6 +142,8 @@ Kuma consolidates everything into **3 coarse-grained tools**. Each action trigge
 | `arch_flow` | Layer 2 — Architecture flow mapping (Issue #17). |
 | `gotcha` | Layer 3 — Known gotchas & anti-regression shield (Issue #17/#21). |
 | `layers` | Show all 3 memory layers summary. |
+| `delete_node` | Delete specific node or record from disk & RAM immediately. |
+| `graph_health` | Monitor knowledge graph health, orphan nodes, and duplicate groups. |
 
 ### 🛡️ `kuma_safety` — Safety & Policy
 

package/dist/index.js

@@ -2558,7 +2558,7 @@ async function recordDomainFlow(params) {
       await addEdge({
         sourceId: fromId,
         targetId: toId,
-        type: "affects",
+        type: "depends_on",
         weight: 0.8,
         metadata: { reason: "arch_flow", domain: params.domain }
       });
@@ -8196,19 +8196,25 @@ function generateInitMdContent() {
     "- `status` \u2014 severity: `low` | `medium` | `high` | `critical` (default: `medium`)",
     "- `description` \u2014 optional workaround/fix description",
     "",
-    "### STEP 7: Record Arch Flow (RECORD INLINE \u2014 When Tracing Flow)",
+    "### STEP 7: Record Arch Flow (RECORD COMPLETE FLOW \u2014 Core Logic Only)",
     "```",
-    'kuma_memory({ action: "arch_flow", content: "domain: <name> | hops: <file1> \u2192 <file2> \u2192 <file3>" })',
+    'kuma_memory({ action: "arch_flow", content: "domain: <name> | hops: <core_file1> \u2192 <core_file2> \u2192 <core_file3>" })',
     "```",
-    "**When:** IMMEDIATELY after tracing EACH hop in a data/control flow. Record INLINE, then continue tracing the next hop.",
-    "**Why:** Architecture knowledge dissipates fast. Record each hop before moving to the next file/task.",
+    "**When:** AFTER tracing a COMPLETE architecture flow (not per hop).",
+    "**Why:** Record flow architecture for future sessions without cluttering the graph.",
+    "",
+    "**Rules:**",
+    "1. MAX 5 files per flow \u2014 record core business logic files only.",
+    "2. SKIP UI components (*.tsx, *.jsx), Controllers (*Controller.js), Schemas (*Schema.js), and simple CRUD services.",
+    "3. INCLUDE files with complex business logic, decision points, state mutations, or error handling.",
+    "4. Format hops separated by ` \u2192 ` (e.g. `domain: LeadDistributionFlow | hops: LeadRotationService.js \u2192 ProspectAssignmentService.js \u2192 ActivityLogService.js`).",
     "",
     "**\u26A0\uFE0F CRITICAL FORMAT \u2014 Content MUST use this exact syntax:**",
     "```",
-    "domain: <DomainName> | hops: <file1.tsx> \u2192 <file2.js> \u2192 <file3.ts> | gotchas: <optional> | decisions: <optional>",
+    "domain: <DomainName> | hops: <core_file1.js> \u2192 <core_file2.js> \u2192 <core_file3.js> | gotchas: <optional> | decisions: <optional>",
     "```",
     "- `domain:` \u2014 short domain name (e.g. `InviteUserFlow`, `LeadManagementFlow`)",
-    "- `hops:` \u2014 file names separated by ` \u2192 ` (NOT newlines, NOT commas)",
+    "- `hops:` \u2014 max 5 core file names separated by ` \u2192 `",
     "- `gotchas:` \u2014 optional comma-separated gotchas",
     "- `decisions:` \u2014 optional comma-separated decisions",
     "",
@@ -10377,6 +10383,11 @@ var MEMORY_ALIASES = {
   "read": "session",
   "fetch": "session",
   "current": "session",
+  // Graph health synonyms
+  "graph_health": "graph_health",
+  "graph-health": "graph_health",
+  "health-check": "graph_health",
+  "graph-status": "graph_health",
   // Decision synonyms
   "decision": "decision",
   "adr": "decision",
@@ -10408,7 +10419,6 @@ var MEMORY_ALIASES = {
   "task": "todo",
   "todos": "todo",
   "tasks": "todo",
-  // Context notes synonyms
   "context": "context",
   "notes": "context",
   "note": "context",
@@ -10513,6 +10523,8 @@ async function handleMemory(params) {
       return handleFeature(params);
     case "delete_node":
       return handleDeleteNode(params);
+    case "graph_health":
+      return handleGraphHealth(params);
     case "clear": {
       const { clearGraph: clearGraph2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
       await clearGraph2();
@@ -10564,14 +10576,26 @@ async function handleResearchSave(params) {
   });
   await saveResearchCache(scope, record, void 0, params.confidence);
   try {
-    const { upsertNode: upsertNode2, nodeId: nodeId2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
-    await upsertNode2({ id: nodeId2("file", scope), type: "file", name: scope });
-    await upsertNode2({
-      id: `research::${scope}`,
-      type: "research",
-      name: `research:${scope}`,
-      metadata: { confidence: params.confidence || 0.8 }
-    });
+    const { getDb: getDb2, flushDb: flushDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+    const db = await getDb2();
+    const fileId = `file::${scope}`;
+    const researchId = `research::${scope}`;
+    const now = Math.floor(Date.now() / 1e3);
+    db.run(`
+      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+      VALUES (?, 'file', ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
+        updated_at = excluded.updated_at
+    `, [fileId, scope, scope, JSON.stringify({ findings: [params.content || ""], confidence: params.confidence || 0.8 }), now]);
+    db.run(`
+      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+      VALUES (?, 'research', ?, null, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
+        updated_at = excluded.updated_at
+    `, [researchId, `research:${scope}`, JSON.stringify({ confidence: params.confidence || 0.8, last_findings: params.content || "" }), now]);
+    flushDb2(db);
   } catch {
   }
   try {
@@ -10787,12 +10811,20 @@ async function handleLayerAction(layer, params) {
 \u274C Wrong: hops: file1.js\\nfile2.js
 \u2705 Correct: domain: <name> | hops: file1.js \u2192 file2.js \u2192 file3.js`;
       }
-      const hops = hopsStr ? hopsStr.split("\u2192").map((h) => h.trim()).filter(Boolean).map((h, i, arr) => ({
+      const rawHops = hopsStr ? hopsStr.split("\u2192").map((h) => h.trim()).filter(Boolean) : [];
+      const coreHops = rawHops.filter((file) => {
+        if (file.endsWith(".tsx") || file.endsWith(".jsx")) return false;
+        if (file.includes("Controller")) return false;
+        if (file.includes("Schema") || file.includes("RequestSchema")) return false;
+        return true;
+      });
+      const limitedHopsList = coreHops.slice(0, 5);
+      const hops = limitedHopsList.map((h, i, arr) => ({
         from: i === 0 ? domain : arr[i - 1],
         to: h,
         relation: "flows",
         description: h
-      })) : [];
+      }));
       if (hops.length === 0) {
         return `\u274C **arch_flow format error:** no hops found after \u2192 separator.
 
@@ -10896,11 +10928,12 @@ async function handleDeleteNode(params) {
         return `\u26A0\uFE0F Unknown scope "${params.scope}". Supported: gotcha, todo, decision, checkpoint`;
     }
   }
-  if (params.target) {
+  if (params.target || params.scope) {
     const { flushDb: flushDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
-    if (params.target.includes("::") || params.target.includes(":") || params.target.includes("-")) {
+    const targetStr = params.target || "";
+    const targetId = params.scope && !targetStr.includes("::") ? `${targetStr}::${params.scope}` : targetStr;
+    if (targetId && (targetId.includes("::") || targetId.includes(":") || targetId.includes("-") || isNaN(parseInt(targetId, 10)))) {
       try {
-        const targetId = params.target;
         const domainName = targetId.startsWith("feature_domain::") ? targetId.replace("feature_domain::", "") : targetId;
         if (targetId.startsWith("feature_domain::")) {
           db.run("DELETE FROM nodes WHERE id LIKE ? OR id LIKE ? OR id LIKE ?", [
@@ -10914,16 +10947,18 @@ async function handleDeleteNode(params) {
           db.run("DELETE FROM nodes WHERE id = ?", [targetId]);
         }
         flushDb2(db);
-        return `\u{1F5D1}\uFE0F **Node & relations deleted instantly from RAM and Disk:** ${params.target}`;
+        return `\u{1F5D1}\uFE0F **Node & relations deleted instantly from RAM and Disk:** ${targetId}`;
       } catch (err) {
         return `\u274C Failed to delete node: ${err}`;
       }
     }
-    const id = parseInt(params.target, 10);
-    if (!isNaN(id)) {
-      db.run("DELETE FROM nodes WHERE rowid = ?", [id]);
-      flushDb2(db);
-      return `\u{1F5D1}\uFE0F **Node #${id} deleted.**`;
+    if (targetId) {
+      const id = parseInt(targetId, 10);
+      if (!isNaN(id)) {
+        db.run("DELETE FROM nodes WHERE rowid = ?", [id]);
+        flushDb2(db);
+        return `\u{1F5D1}\uFE0F **Node #${id} deleted.**`;
+      }
     }
   }
   return "\u26A0\uFE0F Provide `target` (node ID) to delete, or `scope` + `target` (numeric ID) for gotcha/todo/decision/checkpoint.\n\nExamples:\n- `delete_node`, target: 'function::sendMessage'\n- `delete_node`, scope: 'gotcha', target: '42'\n- `delete_node`, scope: 'todo', target: '7'\n- `delete_node`, scope: 'decision', target: '3'\n- `delete_node`, scope: 'checkpoint', target: '1'";
@@ -10984,6 +11019,68 @@ async function handleFeature(params) {
 \u{1F3F7}\uFE0F Tags: ${tags.length}
 \u26A0\uFE0F Risk: ${risk}`;
 }
+async function handleGraphHealth(_params) {
+  const { getDb: getDb2 } = await Promise.resolve().then(() => (init_kumaDb(), kumaDb_exports));
+  const db = await getDb2();
+  const getRows = (sql) => {
+    try {
+      const res = db.exec(sql);
+      if (!res.length) return [];
+      const cols = res[0].columns;
+      return res[0].values.map((val) => {
+        const obj = {};
+        cols.forEach((c, idx) => obj[c] = val[idx]);
+        return obj;
+      });
+    } catch {
+      return [];
+    }
+  };
+  const totalNodesRow = getRows("SELECT COUNT(*) as count FROM nodes")[0];
+  const totalNodes = totalNodesRow ? totalNodesRow.count : 0;
+  const totalEdgesRow = getRows("SELECT COUNT(*) as count FROM edges")[0];
+  const totalEdges = totalEdgesRow ? totalEdgesRow.count : 0;
+  const orphanRows = getRows(`
+    SELECT COUNT(*) as count FROM nodes
+    WHERE id NOT IN (SELECT DISTINCT source_id FROM edges UNION SELECT DISTINCT target_id FROM edges)
+  `);
+  const totalOrphans = orphanRows[0] ? orphanRows[0].count : 0;
+  const duplicateGroups = getRows(`
+    SELECT name, COUNT(*) as count FROM nodes GROUP BY name HAVING count > 1
+  `);
+  const typeStats = getRows(`
+    SELECT type, COUNT(*) as count FROM nodes GROUP BY type ORDER BY count DESC
+  `);
+  const lines = [
+    "\u{1F4CA} **Kuma Knowledge Graph Health Report**",
+    "\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\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    `\u2022 **Total Nodes:** ${totalNodes}`,
+    `\u2022 **Total Edges:** ${totalEdges}`,
+    `\u2022 **Orphan Nodes:** ${totalOrphans}`,
+    `\u2022 **Duplicate Groups:** ${duplicateGroups.length}`,
+    "",
+    "**Nodes by Type:**",
+    ...typeStats.map((s) => `  - \`${s.type}\`: ${s.count}`),
+    "",
+    "**Recommendations:**"
+  ];
+  const recs = [];
+  const crossLinks = typeStats.find((s) => s.type === "cross_service_link");
+  if (crossLinks && crossLinks.count > 50) {
+    recs.push("\u26A0\uFE0F Too many `cross_service_link` nodes. Run cleanup or delete obsolete feature domains.");
+  }
+  if (duplicateGroups.length > 0) {
+    recs.push(`\u26A0\uFE0F ${duplicateGroups.length} duplicate node groups detected. Delete duplicates using \`delete_node\`.`);
+  }
+  if (totalOrphans > 10) {
+    recs.push(`\u26A0\uFE0F ${totalOrphans} orphan nodes found (0 edges). Consider running \`heal\` or \`clear\`.`);
+  }
+  if (recs.length === 0) {
+    recs.push("\u2705 Graph health is optimal! Low noise, good signal-to-noise ratio.");
+  }
+  lines.push(...recs.map((r) => `  ${r}`));
+  return lines.join("\n");
+}
 async function handleLayersSummary(_params) {
   const { getLayersSummary: getLayersSummary2 } = await Promise.resolve().then(() => (init_domainRules(), domainRules_exports));
   return getLayersSummary2();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.24",
+  "version": "2.3.25",
   "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/packages/ide/studio/public/index.html

@@ -828,15 +828,56 @@ function renderHealth(data){
 }
 
 function setupSearch() {
+  var searchTimeout = null;
   document.getElementById("node-search").oninput = function() {
-    var query = this.value.toLowerCase().trim();
-    if (!network || !allNodes) return;
-    if (!query) { network.body.data.nodes.forEach(function(n){ network.body.data.nodes.update({id:n.id,opacity:1.0}); }); return; }
-    var matched = new Set();
-    allNodes.forEach(function(n){
-      if (n.name.toLowerCase().includes(query) || (n.file_path && n.file_path.toLowerCase().includes(query))) matched.add(n.id);
-    });
-    network.body.data.nodes.forEach(function(n){ network.body.data.nodes.update({ id: n.id, opacity: matched.has(n.id) ? 1.0 : 0.15 }); });
+    var self = this;
+    if (searchTimeout) clearTimeout(searchTimeout);
+    searchTimeout = setTimeout(function() {
+      var query = self.value.toLowerCase().trim();
+      if (!network || !allNodes) return;
+
+      if (!query) {
+        resetHighlight();
+        return;
+      }
+
+      var matched = new Set();
+      var firstMatchedId = null;
+      allNodes.forEach(function(n) {
+        if (n.name.toLowerCase().includes(query) || (n.file_path && n.file_path.toLowerCase().includes(query))) {
+          matched.add(n.id);
+          if (!firstMatchedId) firstMatchedId = n.id;
+        }
+      });
+
+      // Update Nodes
+      var nodeBatchUpdates = [];
+      network.body.data.nodes.forEach(function(n) {
+        var hit = matched.has(n.id);
+        nodeBatchUpdates.push({ id: n.id, opacity: hit ? 1.0 : 0.08, font: { color: hit ? '#ffffff' : 'rgba(255,255,255,0.04)', bold: hit } });
+      });
+      network.body.data.nodes.update(nodeBatchUpdates);
+
+      // Update Edges (Dim edges whose endpoints are both not in search results)
+      var edgeBatchUpdates = [];
+      network.body.data.edges.forEach(function(e) {
+        var hit = matched.has(e.from) || matched.has(e.to);
+        var def = edgeDefaults[e.id] || {};
+        var strokeColor = hit ? (def.color || '#64748b') : 'rgba(100,116,139,0.05)';
+        var fontColor = hit ? '#94a3b8' : 'rgba(148,163,184,0.03)';
+        edgeBatchUpdates.push({
+          id: e.id,
+          color: { color: strokeColor, highlight: '#c084fc', hover: '#38bdf8', opacity: hit ? 0.95 : 0.05 },
+          font: { color: fontColor, strokeWidth: 0, background: 'transparent' },
+          width: hit ? (def.width || 1.5) : 0.2
+        });
+      });
+      network.body.data.edges.update(edgeBatchUpdates);
+
+      if (firstMatchedId && matched.size < 10) {
+        network.focus(firstMatchedId, { scale: 1.2, animation: { duration: 300 } });
+      }
+    }, 150);
   };
 }
 </script>