@plumpslabs/kuma 2.2.7 → 2.3.0

package/dist/{agentDetector-HROEABDO.js → agentDetector-FDRVUNJY.js}

@@ -1,6 +1,6 @@
 import {
   getProjectRoot
-} from "./chunk-T55NCW63.js";
+} from "./chunk-IXMWW5WA.js";
 
 // src/utils/agentDetector.ts
 import fs from "fs";

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

@@ -1,6 +1,6 @@
 import {
   getProjectRoot
-} from "./chunk-T55NCW63.js";
+} from "./chunk-IXMWW5WA.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-6NEMSUKP.js

@@ -0,0 +1,304 @@
+import {
+  getKumaDir
+} from "./chunk-IXMWW5WA.js";
+
+// src/engine/kumaDb.ts
+import initSqlJs from "sql.js";
+import fs from "fs";
+import path from "path";
+var DB_FILENAME = "kuma.db";
+var dbInstance = null;
+var initPromise = null;
+async function getDb() {
+  if (dbInstance) return dbInstance;
+  if (initPromise) return initPromise;
+  initPromise = initDb();
+  return initPromise;
+}
+async function initDb() {
+  const SQL = await initSqlJs();
+  const kumaDir = getKumaDir();
+  const dbPath = path.join(kumaDir, DB_FILENAME);
+  if (!fs.existsSync(kumaDir)) {
+    fs.mkdirSync(kumaDir, { recursive: true });
+  }
+  let db;
+  if (fs.existsSync(dbPath)) {
+    const buffer = fs.readFileSync(dbPath);
+    db = new SQL.Database(buffer);
+  } else {
+    db = new SQL.Database();
+  }
+  db.run("PRAGMA journal_mode=WAL");
+  db.run("PRAGMA synchronous=NORMAL");
+  createSchema(db);
+  saveDb(db);
+  dbInstance = db;
+  return db;
+}
+function saveDb(db) {
+  const d = db ?? dbInstance;
+  if (!d) return;
+  try {
+    const kumaDir = getKumaDir();
+    const dbPath = path.join(kumaDir, DB_FILENAME);
+    const data = d.export();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(dbPath, buffer);
+  } catch (err) {
+    console.error(`[KumaDB] Failed to save database: ${err}`);
+  }
+}
+function createSchema(db) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS nodes (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL CHECK(type IN ('function','file','api_route','db_table','test','class','interface','type','module','variable')),
+      name TEXT NOT NULL,
+      file_path TEXT,
+      metadata TEXT DEFAULT '{}',
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS edges (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_id TEXT NOT NULL REFERENCES nodes(id),
+      target_id TEXT NOT NULL REFERENCES nodes(id),
+      type TEXT NOT NULL CHECK(type IN ('calls','imports','defines','tests','routes','implements','extends','depends_on','owns','modified_by')),
+      weight REAL DEFAULT 1.0,
+      metadata TEXT DEFAULT '{}',
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+      UNIQUE(source_id, target_id, type)
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      started_at INTEGER NOT NULL,
+      ended_at INTEGER,
+      goal TEXT,
+      tool_calls INTEGER DEFAULT 0,
+      edits INTEGER DEFAULT 0,
+      rollbacks INTEGER DEFAULT 0,
+      failures INTEGER DEFAULT 0,
+      safety_score INTEGER
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS tool_calls (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id INTEGER REFERENCES sessions(id),
+      tool_name TEXT NOT NULL,
+      params TEXT,
+      success INTEGER DEFAULT 1,
+      duration_ms INTEGER,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS experiences (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool_name TEXT NOT NULL,
+      params_hash TEXT NOT NULL,
+      success INTEGER NOT NULL DEFAULT 1,
+      duration_ms INTEGER,
+      error_pattern TEXT,
+      context_file TEXT,
+      context_action TEXT,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS experience_patterns (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      antecedent_tool TEXT NOT NULL,
+      antecedent_hash TEXT NOT NULL,
+      consequent_tool TEXT NOT NULL,
+      confidence REAL DEFAULT 0.0,
+      count INTEGER DEFAULT 1,
+      avg_duration_ms INTEGER DEFAULT 0,
+      success_rate REAL DEFAULT 1.0,
+      last_seen_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+      UNIQUE(antecedent_tool, antecedent_hash, consequent_tool)
+    )
+  `);
+  try {
+    db.run(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+        name,
+        metadata,
+        content='nodes',
+        content_rowid='rowid'
+      )
+    `);
+  } catch {
+    console.warn("[KumaDB] FTS5 not available, full-text search disabled");
+  }
+  db.run(`CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_tool_calls_created ON tool_calls(created_at)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_experiences_tool ON experiences(tool_name)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_experiences_hash ON experiences(params_hash)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_experiences_created ON experiences(created_at)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_patterns_antecedent ON experience_patterns(antecedent_tool)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_patterns_confidence ON experience_patterns(confidence DESC)`);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS research_cache (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope TEXT NOT NULL UNIQUE,
+      version INTEGER DEFAULT 1,
+      confidence REAL DEFAULT 0.0,
+      content_hash TEXT,
+      record TEXT NOT NULL,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS change_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id INTEGER REFERENCES sessions(id),
+      file_path TEXT NOT NULL,
+      change_type TEXT NOT NULL CHECK(change_type IN ('modified','created','deleted','renamed')),
+      symbol TEXT,
+      diff_summary TEXT,
+      git_commit_hash TEXT,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS health_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      score INTEGER NOT NULL,
+      risk_level TEXT NOT NULL DEFAULT 'low',
+      checks TEXT DEFAULT '[]',
+      summary TEXT,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+    )
+  `);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_research_scope ON research_cache(scope)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_research_updated ON research_cache(updated_at)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_session ON change_log(session_id)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_file ON change_log(file_path)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_change_log_created ON change_log(created_at)`);
+  db.run(`CREATE INDEX IF NOT EXISTS idx_health_created ON health_snapshots(created_at)`);
+}
+async function getResearchCache(scope) {
+  try {
+    const db = await getDb();
+    const stmt = db.prepare("SELECT record, content_hash, updated_at FROM research_cache WHERE scope = ?");
+    stmt.bind([scope]);
+    if (stmt.step()) {
+      const row = stmt.getAsObject();
+      stmt.free();
+      return row.record;
+    }
+    stmt.free();
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function saveResearchCache(scope, record, contentHash, confidence) {
+  try {
+    const db = await getDb();
+    const stmt = db.prepare("SELECT id FROM research_cache WHERE scope = ?");
+    stmt.bind([scope]);
+    const hasExisting = stmt.step();
+    stmt.free();
+    if (hasExisting) {
+      db.run(
+        `UPDATE research_cache SET record = ?, content_hash = COALESCE(?, content_hash), confidence = COALESCE(?, confidence), version = version + 1, updated_at = strftime('%s','now') WHERE scope = ?`,
+        [record, contentHash || null, confidence ?? null, scope]
+      );
+    } else {
+      db.run(
+        `INSERT INTO research_cache (scope, record, content_hash, confidence, version) VALUES (?, ?, ?, ?, 1)`,
+        [scope, record, contentHash || null, confidence ?? null]
+      );
+    }
+    saveDb();
+  } catch (err) {
+    console.error(`[KumaDB] Failed to save research cache: ${err}`);
+  }
+}
+async function recordChange(entry) {
+  try {
+    const db = await getDb();
+    db.run(
+      `INSERT INTO change_log (session_id, file_path, change_type, symbol, diff_summary, git_commit_hash) VALUES (?, ?, ?, ?, ?, ?)`,
+      [entry.sessionId ?? null, entry.filePath, entry.changeType, entry.symbol ?? null, entry.diffSummary ?? null, entry.gitCommitHash ?? null]
+    );
+    saveDb();
+  } catch (err) {
+    console.error(`[KumaDB] Failed to record change: ${err}`);
+  }
+}
+async function getChanges(params) {
+  try {
+    const db = await getDb();
+    const { sessionId, filePath, since, limit = 50 } = params;
+    let sql = `SELECT cl.*, s.goal FROM change_log cl LEFT JOIN sessions s ON s.id = cl.session_id WHERE 1=1`;
+    const bind = [];
+    if (sessionId) {
+      sql += ` AND cl.session_id = ?`;
+      bind.push(sessionId);
+    }
+    if (filePath) {
+      sql += ` AND cl.file_path LIKE ?`;
+      bind.push(`%${filePath}%`);
+    }
+    if (since) {
+      sql += ` AND cl.created_at >= ?`;
+      bind.push(since);
+    }
+    sql += ` ORDER BY cl.created_at DESC LIMIT ?`;
+    bind.push(limit);
+    const stmt = db.prepare(sql);
+    stmt.bind(bind);
+    const results = [];
+    while (stmt.step()) {
+      results.push(stmt.getAsObject());
+    }
+    stmt.free();
+    if (results.length === 0) return "No changes found.";
+    const lines = [`\u{1F4CB} **Change Log** \u2014 ${results.length} change(s)`];
+    for (const r of results) {
+      const icon = r.change_type === "deleted" ? "\u274C" : r.change_type === "created" ? "\u2728" : "\u{1F4DD}";
+      lines.push(`  ${icon} **${r.file_path}** (${r.change_type})`);
+      if (r.symbol) lines.push(`     Symbol: ${r.symbol}`);
+      if (r.goal) lines.push(`     Goal: ${r.goal}`);
+    }
+    return lines.join("\n");
+  } catch (err) {
+    return `Error getting changes: ${err}`;
+  }
+}
+async function saveHealthSnapshot(score, riskLevel, checks, summary) {
+  try {
+    const db = await getDb();
+    db.run(
+      `INSERT INTO health_snapshots (score, risk_level, checks, summary) VALUES (?, ?, ?, ?)`,
+      [score, riskLevel, checks, summary]
+    );
+    saveDb();
+  } catch (err) {
+    console.error(`[KumaDB] Failed to save health snapshot: ${err}`);
+  }
+}
+
+export {
+  getDb,
+  saveDb,
+  getResearchCache,
+  saveResearchCache,
+  recordChange,
+  getChanges,
+  saveHealthSnapshot
+};