@plumpslabs/kuma 2.2.8 → 2.3.1

package/dist/chunk-4CKTTORL.js

@@ -0,0 +1,172 @@
+import {
+  sessionMemory
+} from "./chunk-6W7YV4AF.js";
+import {
+  getProjectRoot
+} from "./chunk-E2KFPEBT.js";
+
+// src/engine/kumaMemory.ts
+import fs from "fs";
+import path from "path";
+var MEMORY_DIR = ".kuma/memories";
+function scoreMemoryRelevance(context, limit = 5) {
+  const results = [];
+  const kumaDir = path.join(getProjectRoot(), MEMORY_DIR);
+  if (!fs.existsSync(kumaDir)) return [];
+  const terms = context.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+  if (terms.length === 0) return [];
+  try {
+    const files = fs.readdirSync(kumaDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(kumaDir, file), "utf-8");
+        const lower = content.toLowerCase();
+        let matchCount = 0;
+        for (const term of terms) {
+          if (lower.includes(term)) matchCount++;
+        }
+        const score = Math.round(matchCount / terms.length * 100);
+        if (score > 0) {
+          const topic = file.replace(/\.md$/, "");
+          const firstLine = content.split("\n").slice(0, 3).join(" ").substring(0, 150);
+          results.push({
+            topic,
+            content: firstLine,
+            score,
+            reason: `${matchCount}/${terms.length} terms matched`
+          });
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function formatScoredMemories(memories, context) {
+  if (memories.length === 0) return "";
+  const lines = [
+    `\u{1F9E0} **Relevant Memories** (for "${context.substring(0, 40)}")`,
+    "\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"
+  ];
+  for (const m of memories) {
+    const bar = "\u2588".repeat(Math.round(m.score / 10)) + "\u2591".repeat(Math.round(10 - m.score / 10));
+    lines.push(`  **${m.topic}** \u2014 ${bar} ${m.score}%`);
+    lines.push(`  ${m.content.substring(0, 100)}`);
+    lines.push(`  \u{1F4A1} ${m.reason}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function recordDecision(decision) {
+  try {
+    const entry = [
+      "",
+      `## ${decision.title}`,
+      `- **Date:** ${decision.timestamp || (/* @__PURE__ */ new Date()).toISOString()}`,
+      `- **Context:** ${decision.context}`,
+      `- **Options:** ${decision.options.join(", ")}`,
+      `- **Rationale:** ${decision.rationale}`,
+      `- **Outcome:** ${decision.outcome}`,
+      ""
+    ].join("\n");
+    const existing = sessionMemory.getMemoryContent("decisions");
+    sessionMemory.writeMemory("decisions", existing + entry);
+    sessionMemory.recordToolCall("kuma_decision", { title: decision.title });
+    recordDecisionToGraph(decision).catch(() => {
+    });
+    return `\u2705 Decision "${decision.title}" recorded.`;
+  } catch (err) {
+    return `Error recording decision: ${err}`;
+  }
+}
+async function recordDecisionToGraph(decision) {
+  try {
+    const { upsertNode, addEdge } = await import("./kumaGraph-VUTLTOFY.js");
+    const decisionId = `decision::${decision.title.replace(/[^a-zA-Z0-9_\-\s]/g, "").trim().replace(/\s+/g, "-")}`;
+    await upsertNode({
+      id: decisionId,
+      type: "variable",
+      name: `ADR: ${decision.title.substring(0, 80)}`,
+      metadata: {
+        type: "architectural-decision",
+        context: decision.context.substring(0, 200),
+        rationale: decision.rationale.substring(0, 200),
+        outcome: decision.outcome,
+        timestamp: decision.timestamp
+      }
+    });
+    const filePathMatches = decision.context.matchAll(/["']?([\w./-]+\.\w+)["']?/g);
+    for (const match of filePathMatches) {
+      const possiblePath = match[1];
+      if (possiblePath.includes("/") && (possiblePath.endsWith(".ts") || possiblePath.endsWith(".js") || possiblePath.endsWith(".json") || possiblePath.endsWith(".md"))) {
+        try {
+          const fileId = `file::${possiblePath}`;
+          await upsertNode({ id: fileId, type: "file", name: possiblePath });
+          await addEdge({ sourceId: decisionId, targetId: fileId, type: "depends_on", metadata: { reason: "adr-context" } });
+        } catch {
+        }
+      }
+    }
+    if (decision.outcome && decision.outcome !== "implemented") {
+      try {
+        const outcomeId = `decision-outcome::${decision.outcome.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase()}`;
+        await upsertNode({ id: outcomeId, type: "variable", name: `Outcome: ${decision.outcome.substring(0, 60)}` });
+        await addEdge({ sourceId: decisionId, targetId: outcomeId, type: "depends_on" });
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+var decisionCooldown = 0;
+function shouldRecordDecision() {
+  const history = sessionMemory.getToolCallHistory(30);
+  const edits = history.filter((c) => c.toolName === "precise_diff_editor");
+  if (edits.length > decisionCooldown + 10 && edits.length >= 10) {
+    decisionCooldown = edits.length;
+    return {
+      worth: true,
+      title: `Significant edits (${edits.length} changes)`
+    };
+  }
+  return { worth: false };
+}
+function getProactiveMemories() {
+  const summary = sessionMemory.getSummary();
+  const goal = summary.currentGoal || "";
+  const modifiedFiles = summary.modifiedFiles || [];
+  const context = [goal, ...modifiedFiles.map((f) => f.filePath || "")].join(" ");
+  if (!context.trim()) return "";
+  const memories = scoreMemoryRelevance(context, 3);
+  return formatScoredMemories(memories, goal || "current context");
+}
+function formatDecisionTemplate() {
+  return [
+    "\u{1F4DD} **Decision Recording Template**",
+    "\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",
+    "",
+    "Use kuma_decision({ action: 'record', ... }) to log important decisions:",
+    "",
+    "```",
+    "kuma_decision({",
+    "  action: 'record',",
+    "  title: 'Why Redis instead of in-memory cache',",
+    "  context: 'Need stateless auth for mobile clients',",
+    "  options: ['Redis', 'In-memory', 'Database'],",
+    "  rationale: 'Latency <10ms with persistence required',",
+    "  outcome: 'Redis chosen'",
+    "})",
+    "```",
+    "",
+    "\u{1F4A1} Call kuma_decision({ action: 'suggest' }) to check if now is a good time to record."
+  ].join("\n");
+}
+
+export {
+  scoreMemoryRelevance,
+  recordDecision,
+  shouldRecordDecision,
+  getProactiveMemories,
+  formatDecisionTemplate
+};

package/dist/{chunk-IR6HFFDU.js → chunk-5WSPGLXS.js}

@@ -1,6 +1,6 @@
 import {
   getProjectRoot
-} from "./chunk-T55NCW63.js";
+} from "./chunk-E2KFPEBT.js";
 
 // src/cli/init.ts
 import fs from "fs";
@@ -252,50 +252,68 @@ function generateInitMdContent() {
     "",
     "_(Auto-generated by `kuma init` \u2014 edit this file directly to customize rules)_",
     "",
-    "## Code Search",
+    "## Kuma V3 \u2014 3 Coarse-Grained Tools",
     "",
-    "- Use the **smart_grep** tool to search code \u2014 NOT bash grep/ripgrep manually",
-    "- smart_grep returns line numbers + context, caches results, respects .gitignore",
+    "Kuma provides 3 pipeline-driven tools. Each action triggers a multi-step deterministic workflow internally.",
     "",
-    "## Reading Code",
+    "### \u{1F9E0} kuma_context \u2014 Context & Research (call FIRST every session)",
     "",
-    "- Use the **smart_file_picker** tool to read files with smart chunking",
-    "- For large files, use startLine/endLine to read specific ranges",
+    '- `kuma_context({ action: "init" })` \u2014 Load project brief, detect stack, show structure',
+    '- **`kuma_context({ action: "research", scope: "..." })` \u2014 WAJIB before editing unfamiliar code**',
+    "  - 5-step pipeline: load cache \u2192 check staleness \u2192 query graph \u2192 impact analysis \u2192 decision lookup",
+    '- `kuma_context({ action: "impact", target: "symbol" })` \u2014 Analyze change effects',
+    '- `kuma_context({ action: "navigate", target: "flow" })` \u2014 Trace code flow',
+    '- `kuma_context({ action: "changes" })` \u2014 View session change log',
+    '- `kuma_context({ action: "health" })` \u2014 Project health score 0-100',
     "",
-    "## Editing Code",
+    "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
     "",
-    "- Use the **precise_diff_editor** tool to edit files (fuzzy matching + auto-backup)",
-    "- DO NOT create Python/Node scripts to patch files; use precise_diff_editor directly",
-    "- DO NOT use bash sed/cat/awk to modify source files",
+    '- `kuma_memory({ action: "research_save", scope: "...", ... })` \u2014 Save research results',
+    '- `kuma_memory({ action: "decision", decisionAction: "record", ... })` \u2014 ADR-style decision',
+    '- `kuma_memory({ action: "session" })` \u2014 Session summary',
+    '- `kuma_memory({ action: "heal" })` \u2014 Self-heal knowledge graph',
+    '- `kuma_memory({ action: "search", query: "..." })` \u2014 Search memories + graph',
+    '- `kuma_memory({ action: "changes" })` \u2014 View change log',
     "",
-    "## Creating Files",
+    "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
     "",
-    "- Use the **batch_file_writer** tool to create new files (up to 15 at once)",
-    "- Before creating a file, ask: does this need to exist, or can it merge into an existing module?",
+    '- `kuma_safety({ action: "guard", guardGoal: "..." })` \u2014 Anti-pattern, drift, loop detection',
+    '- `kuma_safety({ action: "check", ... })` \u2014 Pre-execution safety check',
+    '- `kuma_safety({ action: "audit" })` \u2014 Query safety audit trail',
+    '- `kuma_safety({ action: "lock", lockAction: "acquire", ... })` \u2014 Multi-agent file lock',
+    '- `kuma_safety({ action: "health" })` \u2014 Safety score 0-100',
+    '- `kuma_safety({ action: "override", ... })` \u2014 Logged safety bypass',
     "",
-    "## Running Tasks",
+    "## Mandatory Research Pipeline",
     "",
-    "- Use the **execute_safe_test** tool for test/build/lint/typecheck",
-    "- Always run typecheck after editing TypeScript files",
+    "**Before editing any unfamiliar code, you MUST call:**",
     "",
-    "## Code Review",
+    '    kuma_context({ action: "research", scope: "<area>" })',
     "",
-    "- Use the **code_reviewer** tool after making changes",
-    "- Supports focus: correctness, security, performance, over-engineering",
+    "This runs: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup.",
+    "Only after reviewing the structured result should you make changes.",
     "",
-    "## Session Awareness",
+    "After editing, save what you learned:",
     "",
-    "- Start each session by calling **kuma_init()** to load context",
-    "- Use **get_session_memory()** to recall what happened before",
-    "- Use **kuma_reflect** / **kuma_guard** to stay on track",
-    "- Use **write_memory()** to persist decisions and glossary terms",
+    '    kuma_memory({ action: "research_save", scope: "<area>", confidence: 0-1 })',
     "",
     "## General Rules",
     "",
-    "- When a tool errors, READ the error carefully before acting",
-    "- After 3+ edits without running tests, stop and verify",
-    "- If a tool fails, check the message \u2014 don't retry blindly",
-    "- Detect conventions first with **project_conventions()**",
+    '- **Call `kuma_context({ action: "init" })` at session start** \u2014 always',
+    '- **Research before edit** \u2014 always call `kuma_context({ action: "research" })` first',
+    '- **Save after research** \u2014 use `kuma_memory({ action: "research_save" })` to persist',
+    '- **Record decisions** \u2014 use `kuma_memory({ action: "decision" })` for significant changes',
+    '- **Verify with guard** \u2014 use `kuma_safety({ action: "guard" })` after editing',
+    '- **Check changes** \u2014 use `kuma_context({ action: "changes" })` to track what you modified',
+    "",
+    "## What Kuma Does NOT Do (Use Agent Native Tools)",
+    "",
+    "- Editing files \u2014 use your AI agent's native edit tools",
+    "- Searching code \u2014 use your agent's native grep/search",
+    "- Running commands \u2014 use your agent's native terminal",
+    "- Creating files \u2014 use your agent's native file creation",
+    "- Git operations \u2014 use your agent's native git tools",
+    "- Linting/testing \u2014 use your agent's native run commands",
     "",
     "---",
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"

package/dist/{chunk-QPVPFUCQ.js → chunk-6W7YV4AF.js}

@@ -1,6 +1,7 @@
 // src/engine/sessionMemory.ts
 import fs from "fs";
 import path from "path";
+import { execSync } from "child_process";
 var SessionMemory = class {
   state;
   initialized = false;
@@ -299,15 +300,41 @@ No unresolved issues.`;
   }
   recordToolCall(toolName, params) {
     this.ensureInit();
+    const timestamp = Date.now();
     this.state.toolCalls.push({
       toolName,
       params,
-      timestamp: Date.now()
+      timestamp
     });
     if (this.state.toolCalls.length > 100) {
       this.state.toolCalls = this.state.toolCalls.slice(-100);
     }
     this.save();
+    this.autoTrackToDb(toolName, params, timestamp).catch(() => {
+    });
+  }
+  /**
+   * Auto-track tool calls to the database sessions + tool_calls + experiences tables.
+   * This is the passive observability pipeline — every tool call gets recorded
+   * automatically without requiring the tool to explicitly write to the DB.
+   */
+  async autoTrackToDb(toolName, params, timestamp) {
+    try {
+      const { getDb, saveDb } = await import("./kumaDb-PA7XVERC.js");
+      const db = await getDb();
+      db.run(
+        `INSERT INTO tool_calls (tool_name, params, success, duration_ms, created_at) VALUES (?, ?, 1, 0, ?)`,
+        [toolName, JSON.stringify(params), Math.floor(timestamp / 1e3)]
+      );
+      const paramsHash = simpleHash(JSON.stringify(params));
+      const filePath = params.filePath || params.file_path || params.target || null;
+      db.run(
+        `INSERT INTO experiences (tool_name, params_hash, success, context_file, context_action, created_at) VALUES (?, ?, 1, ?, ?, ?)`,
+        [toolName, paramsHash, filePath, params.action || null, Math.floor(timestamp / 1e3)]
+      );
+      saveDb(db);
+    } catch {
+    }
   }
   setConventions(conventions) {
     this.ensureInit();
@@ -557,6 +584,47 @@ No unresolved issues.`;
     }
     return { isLooping: false };
   }
+  // ============================================================
+  // V3: Change Tracking (Selective Undo)
+  // ============================================================
+  /**
+   * Track a file change with symbol-level detail.
+   * Stores in memory.json AND writes to change_log in DB.
+   */
+  async trackChange(filePath, changeType, symbol) {
+    this.ensureInit();
+    if (changeType === "modified" || changeType === "created") {
+      this.addModifiedFile(filePath);
+    }
+    try {
+      const { recordChange } = await import("./kumaDb-PA7XVERC.js");
+      const gitHash = this.getGitHead();
+      await recordChange({ filePath, changeType, symbol, gitCommitHash: gitHash || void 0 });
+    } catch {
+    }
+    this.save();
+  }
+  /**
+   * Get the current git HEAD hash.
+   */
+  getGitHead() {
+    try {
+      return execSync("git rev-parse HEAD", { encoding: "utf-8", timeout: 3e3 }).trim();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get changes for selective undo, grouped by session.
+   */
+  getChangesGrouped() {
+    this.ensureInit();
+    return [{
+      sessionId: String(this.state.startTime),
+      files: Array.from(this.state.modifiedFiles.keys()),
+      goal: this.state.currentGoal
+    }];
+  }
   ensureInit() {
     if (!this.initialized) {
       this.init({
@@ -566,47 +634,17 @@ No unresolved issues.`;
     }
   }
 };
-var sessionMemory = new SessionMemory();
-function getSessionMemory(topic) {
-  return sessionMemory.getSummary(topic);
-}
-function searchSessionMemory(params) {
-  const { query, limit = 20 } = params;
-  sessionMemory.recordToolCall("search_session_memory", { query, limit });
-  const results = sessionMemory.searchMemory(query, limit);
-  if (results.length === 0) {
-    return `\u{1F50D} **Search Memory** \u2014 No results for "${query}".`;
-  }
-  const lines = [
-    `\u{1F50D} **Search Memory** \u2014 ${results.length} results for "${query}"`,
-    ""
-  ];
-  for (const r of results) {
-    const icon = r.type.startsWith("tool:") ? "\u{1F6E0}\uFE0F" : r.type.startsWith("file:") ? r.type.includes("created") ? "\u2728" : "\u{1F4DD}" : r.type.startsWith("failure") ? "\u274C" : r.type.startsWith("memory") ? "\u{1F9E0}" : r.type === "search" ? "\u{1F50E}" : r.type === "dependency" ? "\u{1F517}" : "\u{1F4C4}";
-    const timeStr = r.timestamp ? new Date(r.timestamp).toLocaleTimeString() : "";
-    lines.push(`${icon} ${timeStr ? `[${timeStr}] ` : ""}${r.content}`);
-  }
-  lines.push("", `\u{1F4A1} Use get_session_memory({topic: "..."}) to load a specific memory topic.`);
-  return lines.join("\n");
-}
-function handleWriteMemory(params) {
-  const { topic, content, mode = "append" } = params;
-  const existing = sessionMemory.getMemoryContent(topic);
-  let finalContent = content;
-  if (mode === "prepend") {
-    finalContent = content + "\n\n" + existing;
-  } else if (mode === "append") {
-    finalContent = existing + "\n\n" + content;
-  }
-  sessionMemory.writeMemory(topic, finalContent);
-  sessionMemory.recordToolCall("write_memory", { topic, mode });
-  return `\u2705 Memory "${topic}" updated (mode: ${mode}).`;
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(36);
 }
+var sessionMemory = new SessionMemory();
 
 export {
-  SessionMemory,
-  sessionMemory,
-  getSessionMemory,
-  searchSessionMemory,
-  handleWriteMemory
+  sessionMemory
 };

package/dist/{chunk-T55NCW63.js → chunk-E2KFPEBT.js}

@@ -132,6 +132,22 @@ function validateFileExtension(filePath) {
 function getProjectRoot() {
   return process.env.AGENT_PROJECT_ROOT ?? process.cwd();
 }
+function isReadable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isWritable(dirPath) {
+  try {
+    fs.accessSync(dirPath, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function getBackupPath(filePath, timestamp) {
   const ts = timestamp ?? Date.now();
   const root = getProjectRoot();
@@ -158,6 +174,8 @@ export {
   validateFilePath,
   validateFileExtension,
   getProjectRoot,
+  isReadable,
+  isWritable,
   getBackupPath,
   ensureBackupDir,
   getKumaDir,

package/dist/chunk-WG47POMW.js

@@ -0,0 +1,71 @@
+import {
+  sessionMemory
+} from "./chunk-6W7YV4AF.js";
+import {
+  getProjectRoot
+} from "./chunk-E2KFPEBT.js";
+
+// src/utils/kumaShared.ts
+import { execSync } from "child_process";
+function getSessionStats(inputGoal) {
+  const summary = sessionMemory.getSummary();
+  const goal = inputGoal || summary.currentGoal || "";
+  const modifiedFiles = sessionMemory.getModifiedFiles();
+  const toolCalls = sessionMemory.getToolCallHistory(50);
+  const failedFiles = sessionMemory.getFailedFiles();
+  const loop = sessionMemory.detectLoop();
+  return {
+    goal,
+    modifiedFiles,
+    toolCalls,
+    toolCallCount: toolCalls.length,
+    failedFiles,
+    hasLoop: loop.isLooping,
+    loopMessage: loop.message,
+    hasRunTests: toolCalls.some((c) => c.toolName === "execute_safe_test")
+  };
+}
+function getGitDiffStat(timeout = 3e3) {
+  try {
+    const root = getProjectRoot();
+    return execSync("git diff --stat", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+function getUnresolvedCount(failedFiles) {
+  let count = 0;
+  for (const f of failedFiles) {
+    for (const ff of f.failures) {
+      if (!ff.resolved) count++;
+    }
+  }
+  return count;
+}
+function buildDriftMessages(modifiedFiles, hasRunTests, unresolvedCount, gitStat, loopMessage) {
+  const drifts = [];
+  if (modifiedFiles > 0 && !hasRunTests) {
+    drifts.push(`${modifiedFiles} file(s) edited but no test run`);
+  }
+  if (loopMessage) {
+    drifts.push(loopMessage);
+  }
+  if (unresolvedCount > 0) {
+    drifts.push(`${unresolvedCount} unresolved failure(s)`);
+  }
+  if (gitStat) {
+    drifts.push(`Git diff: ${gitStat}`);
+  }
+  return drifts;
+}
+
+export {
+  getSessionStats,
+  getGitDiffStat,
+  getUnresolvedCount,
+  buildDriftMessages
+};