@plumpslabs/kuma 2.1.5 → 2.1.8

package/README.md

@@ -166,6 +166,31 @@ Most tools make AI smarter. **Kuma makes AI not break things.**
 
 ---
 
+---
+
+## 🍵 Pair with Matcha
+
+**Kuma keeps AI agents safe. Matcha keeps AI agents deliberate.**
+
+[Matcha](https://github.com/plumpslabs/matcha) is an engineering philosophy
+ruleset that enforces deliberate thinking before, during, and after coding:
+
+- **5W1H Gate** — Why are we doing this? Is there a simpler path?
+- **Reuse Before Write** — Never write what already exists
+- **Clean Finish** — No temp, no debug, no unused code
+
+Where Kuma provides **runtime safety** (rollback, circuit breaker, sandbox),
+Matcha provides **session discipline** (planning gate, cleanup scan, intensity levels).
+
+```bash
+# Try them together
+npx @plumpslabs/matcha init     # Install matcha philosophy
+npx @plumpslabs/kuma init --all  # Install kuma safety tools
+```
+
+Both tools are designed to complement each other — Kuma handles the
+"can't break things" layer while Matcha handles the "think before you act" layer.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

package/dist/index.js

@@ -3662,7 +3662,10 @@ async function handleStaticAnalysis(params) {
 function detectAvailableTools(root) {
   const tools = [];
   const pkg = readPackageJson(root);
-  const allDeps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
+  const allDeps = {
+    ...pkg?.dependencies ?? {},
+    ...pkg?.devDependencies ?? {}
+  };
   const depNames = new Set(Object.keys(allDeps));
   const eslintConfigs = [
     ".eslintrc",
@@ -3974,80 +3977,140 @@ function formatToolNotAvailable(requested, available) {
   ].join("\n");
 }
 
-// src/tools/kumaReflect.ts
+// src/utils/kumaShared.ts
 import { execSync as execSync3 } from "child_process";
-async function handleReflect(params) {
+function getSessionStats(inputGoal) {
   const summary = sessionMemory.getSummary();
-  const goal = params.goal || summary.currentGoal || "";
+  const goal = inputGoal || summary.currentGoal || "";
   const modifiedFiles = sessionMemory.getModifiedFiles();
   const toolCalls = sessionMemory.getToolCallHistory(50);
   const failedFiles = sessionMemory.getFailedFiles();
   const loop = sessionMemory.detectLoop();
-  const unresolved = [];
-  for (const f of failedFiles) {
-    for (const ff of f.failures) {
-      if (!ff.resolved) {
-        unresolved.push({ task: f.task, error: ff.error.substring(0, 200) });
-      }
-    }
-  }
-  const hasRunTests = toolCalls.some(
-    (c) => c.toolName === "execute_safe_test"
-  );
-  let gitStat = "";
+  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();
-    gitStat = execSync3("git diff --stat", {
+    return execSync3("git diff --stat", {
       cwd: root,
       encoding: "utf-8",
-      timeout: 5e3
+      timeout
     }).trim();
   } catch {
+    return "";
   }
-  const drifts = [];
-  if (modifiedFiles.length > 0 && !hasRunTests) {
-    drifts.push(`${modifiedFiles.length} file(s) edited but no test run`);
-  }
-  if (loop.isLooping) {
-    drifts.push(loop.message);
-  }
-  if (unresolved.length > 0) {
-    drifts.push(`${unresolved.length} unresolved failure(s)`);
+}
+function getUnresolvedCount(failedFiles) {
+  let count = 0;
+  for (const f of failedFiles) {
+    for (const ff of f.failures) {
+      if (!ff.resolved) count++;
+    }
   }
-  if (gitStat) {
-    drifts.push(`Git diff: ${gitStat}`);
+  return count;
+}
+function getUnresolvedDetails(failedFiles) {
+  const result = [];
+  for (const f of failedFiles) {
+    for (const ff of f.failures) {
+      if (!ff.resolved) {
+        result.push({ task: f.task, error: ff.error.substring(0, 200) });
+      }
+    }
   }
-  const ladderViolations = [];
+  return result;
+}
+function checkLadderViolations(toolCalls, modifiedFiles, hasRunTests) {
+  const violations = [];
   const editCalls = toolCalls.filter(
     (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
   ).length;
   if (editCalls > 5) {
-    ladderViolations.push(
-      `${editCalls} file ops in a row \u2014 consider if all are needed`
-    );
+    violations.push(`${editCalls} file ops in a row \u2014 consider if all are needed`);
   }
   if (modifiedFiles.length > 5 && !hasRunTests) {
-    ladderViolations.push(
-      `${modifiedFiles.length} files modified without verification`
-    );
+    violations.push(`${modifiedFiles.length} files modified without verification`);
+  }
+  return violations;
+}
+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;
+}
+function getPrioritySuggestion(goal, warnings, hasLoop, unresolvedCount, modifiedFiles, hasRunTests, editCalls) {
+  if (warnings.some((w) => w.severity === "high" && w.pattern === "script-patching")) {
+    return "Remove patch scripts and use precise_diff_editor for all file modifications";
+  }
+  if (hasLoop) {
+    return "Switch approach \u2014 current tool is not making progress";
+  }
+  if (warnings.some((w) => w.pattern === "no-test-after-edit") || modifiedFiles > 0 && !hasRunTests) {
+    return "Run tests to verify your changes before continuing";
+  }
+  if (unresolvedCount > 0) {
+    return "Fix unresolved failures before continuing";
+  }
+  if (warnings.some((w) => w.pattern === "bash-grep")) {
+    return "Use smart_grep for code search instead of bash grep";
+  }
+  if (warnings.some((w) => w.pattern === "excessive-edits") || editCalls > 10) {
+    return "Consider if refactoring can be simplified \u2014 fewer files = fewer bugs";
   }
-  const onTrack = !loop.isLooping && unresolved.length === 0 && (modifiedFiles.length === 0 || hasRunTests);
-  let suggestion;
   if (!goal) {
-    suggestion = "No goal set \u2014 use goal parameter or setGoal";
-  } else if (loop.isLooping) {
-    suggestion = "Switch approach \u2014 current tool is not making progress";
-  } else if (unresolved.length > 0) {
-    suggestion = "Fix unresolved failures before continuing";
-  } else if (modifiedFiles.length > 0 && !hasRunTests) {
-    suggestion = "Run tests to verify changes";
-  } else if (modifiedFiles.length === 0 && !toolCalls.some((c) => ["smart_file_picker", "smart_grep"].includes(c.toolName))) {
-    suggestion = "Start by exploring what exists before writing code";
-  } else if (editCalls > 10) {
-    suggestion = "Consider if refactoring can be simplified \u2014 fewer files = fewer bugs";
-  } else {
-    suggestion = "On track";
+    return "No goal set \u2014 use goal parameter or setGoal to track intent";
   }
+  if (modifiedFiles === 0) {
+    return "Start by exploring what exists before writing code";
+  }
+  return "On track \u2014 continue with current approach";
+}
+
+// src/tools/kumaReflect.ts
+async function handleReflect(params) {
+  const stats = getSessionStats(params.goal);
+  const unresolved = getUnresolvedDetails(stats.failedFiles);
+  const gitStat = getGitDiffStat(5e3);
+  const ladderViolations = checkLadderViolations(stats.toolCalls, stats.modifiedFiles, stats.hasRunTests);
+  const drifts = buildDriftMessages(
+    stats.modifiedFiles.length,
+    stats.hasRunTests,
+    unresolved.length,
+    gitStat,
+    stats.loopMessage
+  );
+  const onTrack = !stats.hasLoop && unresolved.length === 0 && (stats.modifiedFiles.length === 0 || stats.hasRunTests);
+  const suggestion = getPrioritySuggestion(
+    stats.goal,
+    [],
+    stats.hasLoop,
+    unresolved.length,
+    stats.modifiedFiles.length,
+    stats.hasRunTests,
+    stats.toolCalls.filter(
+      (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
+    ).length
+  );
   return JSON.stringify(
     {
       onTrack,
@@ -4055,12 +4118,12 @@ async function handleReflect(params) {
       ...ladderViolations.length > 0 ? { ladderViolations } : {},
       suggestion,
       stats: {
-        goal,
-        modifiedFiles: modifiedFiles.length,
-        toolCalls: toolCalls.length,
+        goal: stats.goal,
+        modifiedFiles: stats.modifiedFiles.length,
+        toolCalls: stats.toolCallCount,
         unresolvedFailures: unresolved.length,
-        hasLoop: loop.isLooping,
-        hasRunTests
+        hasLoop: stats.hasLoop,
+        hasRunTests: stats.hasRunTests
       }
     },
     null,
@@ -4068,9 +4131,6 @@ async function handleReflect(params) {
   );
 }
 
-// src/tools/kumaGuard.ts
-import { execSync as execSync6 } from "child_process";
-
 // src/guards/antiPatternDetector.ts
 import fs11 from "fs";
 import path11 from "path";
@@ -4299,7 +4359,7 @@ function saveSnapshot(goal) {
     modifiedFiles: summary.modifiedFiles || [],
     unresolvedFailures: summary.unresolvedFailures || [],
     toolCallCount: summary.toolCallCount || 0,
-    gitDiffStat: getGitDiffStat(),
+    gitDiffStat: getGitDiffStat2(),
     completedSteps: summary.completedSteps || [],
     hasConventions: !!summary.hasConventions
   };
@@ -4357,7 +4417,7 @@ function formatSnapshot(snapshot) {
   lines.push('\u{1F4A1} Use kuma_guard({ check: "context" }) to create a new snapshot.');
   return lines.join("\n");
 }
-function getGitDiffStat() {
+function getGitDiffStat2() {
   try {
     const root = getProjectRoot();
     const stdout = execSync5("git diff --stat", {
@@ -4374,9 +4434,8 @@ function getGitDiffStat() {
 // src/tools/kumaGuard.ts
 async function handleKumaGuard(params) {
   const { check = "all", goal: inputGoal } = params;
-  const summary = sessionMemory.getSummary();
-  const goal = inputGoal || summary.currentGoal || "";
-  sessionMemory.recordToolCall("kuma_guard", { check, goal });
+  sessionMemory.recordToolCall("kuma_guard", { check, goal: inputGoal });
+  const stats = getSessionStats(inputGoal);
   const warnings = [];
   if (check === "all" || check === "anti-pattern") {
     warnings.push(...detectAllAntiPatterns());
@@ -4391,44 +4450,26 @@ async function handleKumaGuard(params) {
     });
   }
   const drifts = [];
-  const toolCalls = sessionMemory.getToolCallHistory(50);
-  const hasRunTests = toolCalls.some((c) => c.toolName === "execute_safe_test");
   if (check === "all" || check === "drift") {
-    const modifiedFiles = sessionMemory.getModifiedFiles();
-    const failedFiles = sessionMemory.getFailedFiles();
-    let unresolvedCount = 0;
-    for (const f of failedFiles) {
-      for (const ff of f.failures) {
-        if (!ff.resolved) unresolvedCount++;
-      }
-    }
-    if (modifiedFiles.length > 0 && !hasRunTests) {
-      drifts.push(`${modifiedFiles.length} file(s) edited but no test run`);
+    const unresolvedCount = getUnresolvedCount(stats.failedFiles);
+    const gitStat = getGitDiffStat();
+    const editCalls = stats.toolCalls.filter(
+      (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
+    ).length;
+    drifts.push(...buildDriftMessages(
+      stats.modifiedFiles.length,
+      stats.hasRunTests,
+      unresolvedCount,
+      gitStat
+    ));
+    if (stats.modifiedFiles.length > 0 && !stats.hasRunTests) {
       warnings.push({
         severity: "medium",
         pattern: "no-test-after-edit",
-        message: `${modifiedFiles.length} file(s) modified without running tests`,
+        message: `${stats.modifiedFiles.length} file(s) modified without running tests`,
         suggestion: 'Run execute_safe_test({ task: "typecheck" }) to verify changes'
       });
     }
-    if (unresolvedCount > 0) {
-      drifts.push(`${unresolvedCount} unresolved failure(s)`);
-    }
-    try {
-      const root = getProjectRoot();
-      const gitStat = execSync6("git diff --stat", {
-        cwd: root,
-        encoding: "utf-8",
-        timeout: 3e3
-      }).trim();
-      if (gitStat) {
-        drifts.push(`Git diff: ${gitStat}`);
-      }
-    } catch {
-    }
-    const editCalls = toolCalls.filter(
-      (c) => c.toolName === "precise_diff_editor" || c.toolName === "batch_file_writer"
-    ).length;
     if (editCalls > 5) {
       warnings.push({
         severity: "low",
@@ -4439,7 +4480,7 @@ async function handleKumaGuard(params) {
     }
   }
   if (check === "context") {
-    const snapshot = saveSnapshot(goal);
+    const snapshot = saveSnapshot(stats.goal);
     if (!snapshot) {
       return "\u26A0\uFE0F Could not create context snapshot. The .kuma directory might not be accessible.";
     }
@@ -4459,7 +4500,7 @@ async function handleKumaGuard(params) {
     suggestion = "Use smart_grep for code search instead of bash grep";
   } else if (warnings.some((w) => w.pattern === "excessive-edits")) {
     suggestion = "Pause and review: are all these edits necessary?";
-  } else if (!goal) {
+  } else if (!stats.goal) {
     suggestion = "No goal set \u2014 use goal parameter or setGoal to track intent";
   } else {
     suggestion = "On track \u2014 continue with current approach";
@@ -4471,12 +4512,12 @@ async function handleKumaGuard(params) {
     drifts,
     suggestion,
     stats: {
-      goal,
-      modifiedFiles: summary.modifiedFiles.length,
-      toolCalls: summary.toolCallCount ?? 0,
-      unresolvedFailures: summary.unresolvedFailures ? summary.unresolvedFailures.length : 0,
+      goal: stats.goal,
+      modifiedFiles: stats.modifiedFiles.length,
+      toolCalls: stats.toolCallCount,
+      unresolvedFailures: getUnresolvedCount(stats.failedFiles),
       hasLoop: loop.isLooping,
-      hasRunTests
+      hasRunTests: stats.hasRunTests
     }
   };
   return JSON.stringify(report, null, 2);
@@ -5826,15 +5867,16 @@ async function main() {
       process.cwd(),
       ".agents/skills/matcha/SKILL.md"
     );
-    const matchaCursor = path16.resolve(
+    const matchaRootSkills = path16.resolve(
       process.cwd(),
-      ".cursor/rules/matcha.mdc"
+      "skills/matcha/SKILL.md"
     );
-    const matchaWindsurf = path16.resolve(
+    const matchaAgentsMd = path16.resolve(process.cwd(), "AGENTS.md");
+    const matchaWindsurfRules = path16.resolve(
       process.cwd(),
-      ".windsurf/rules/matcha.md"
+      ".windsurfrules"
     );
-    if (fs16.existsSync(matchaSkills) || fs16.existsSync(matchaAgents) || fs16.existsSync(matchaCursor) || fs16.existsSync(matchaWindsurf)) {
+    if (fs16.existsSync(matchaSkills) || fs16.existsSync(matchaAgents) || fs16.existsSync(matchaRootSkills) || fs16.existsSync(matchaAgentsMd) || fs16.existsSync(matchaWindsurfRules)) {
       console.error(
         "\n\u{1F375} Hey, I see matcha is installed \u2014 they pair well together!"
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.1.5",
+  "version": "2.1.8",
   "description": "Zero-setup safety toolkit for AI coding agents. MCP server with code review, git analysis, file editing, session memory, and static analysis — works with Claude Code, Cursor, Gemini CLI.",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "dev": "tsup src/index.ts --format esm --watch --out-dir dist",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
+    "lint": "echo 'No linting configured'",
     "prepublishOnly": "npm run build",
     "test": "node --experimental-vm-modules node_modules/.bin/jest"
   },
@@ -33,6 +33,7 @@
     "@types/node": "^22.0.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.0",
+    "ts-node": "^10.9.2",
     "tsup": "^8.3.0",
     "typescript": "^5.9.3"
   },