@plumpslabs/kuma 2.4.3 → 2.4.5

package/hooks/kuma-agy-hooks.js

@@ -0,0 +1,37 @@
+/**
+ * 🐻 Kuma MCP — Antigravity Lifecycle Hook
+ * Intercepts file writes to warn about known gotchas and fragile files.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+function runHook() {
+  try {
+    const input = process.env.AGY_TOOL_INPUT ? JSON.parse(process.env.AGY_TOOL_INPUT) : {};
+    const targetFile = input.TargetFile || input.file || "";
+
+    if (!targetFile) {
+      process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+      return;
+    }
+
+    const gotchasFile = path.resolve(process.cwd(), ".kuma", "KNOWN_GOTCHAS.md");
+    if (fs.existsSync(gotchasFile)) {
+      const content = fs.readFileSync(gotchasFile, "utf-8");
+      const baseName = path.basename(targetFile);
+      if (content.includes(baseName) || content.includes(targetFile)) {
+        process.stdout.write(JSON.stringify({
+          decision: "allow",
+          systemMessage: `⚠️ Kuma Gotcha Warning: ${baseName} has recorded gotchas in .kuma/KNOWN_GOTCHAS.md. Review before editing!`
+        }) + "\n");
+        return;
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+  } catch {
+    process.stdout.write(JSON.stringify({ decision: "allow" }) + "\n");
+  }
+}
+
+runHook();

package/hooks.json

@@ -0,0 +1,17 @@
+{
+  "kuma-safety": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "replace_file_content|write_to_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"import('fs').then(fs=>{const p=['hooks/kuma-agy-hooks.js','.agents/hooks/kuma-agy-hooks.js','../hooks/kuma-agy-hooks.js'].find(x=>fs.existsSync(x));if(p)import('./'+p);else process.stdout.write(JSON.stringify({decision:'allow'})+'\\n');}).catch(()=>process.stdout.write(JSON.stringify({decision:'allow'})+'\\n'))\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/install.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 🐻 Kuma — Universal Installation Script
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
+#   curl -fsSL ... | bash -s -- --target /path
+#   ./install.sh                # from cloned repo
+
+GH_RAW="https://raw.githubusercontent.com/plumpslabs/kuma/main"
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || echo "")"
+CLONED=false
+[ -n "$HERE" ] && [ -f "$HERE/package.json" ] && [ -f "$HERE/dist/index.js" ] && CLONED=true
+
+TARGET="${PWD}"
+f=""; for a in "$@"; do [ "$f" = "--target" ] && TARGET="$a" && break; f="$a"; done
+
+GLOBAL=false
+for a in "$@"; do [ "$a" = "--global" ] && GLOBAL=true && break; done
+
+ALL=false
+for a in "$@"; do [ "$a" = "--all" ] && ALL=true && break; done
+
+echo "🐻 Kuma Safety Engine — Installer"
+echo "Target: $TARGET"
+$CLONED && echo "Source: local repo" || echo "Source: remote repo"
+echo ""
+
+# 1. Verify Node.js
+if ! command -v node >/dev/null 2>&1; then
+  echo "❌ Node.js is required but not found. Please install Node.js >= 18." >&2
+  exit 1
+fi
+
+NODE_MAJOR=$(node -v | cut -d'.' -f1 | tr -d 'v')
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  echo "❌ Node.js >= 18 is required. Current version: $(node -v)" >&2
+  exit 1
+fi
+echo "✅ Node.js $(node -v) detected"
+
+# 2. Global CLI Install (if requested or missing)
+if $GLOBAL; then
+  echo "📦 Installing @plumpslabs/kuma globally..."
+  if command -v npm >/dev/null 2>&1; then
+    npm install -g @plumpslabs/kuma
+  elif command -v pnpm >/dev/null 2>&1; then
+    pnpm add -g @plumpslabs/kuma
+  fi
+fi
+
+# 3. Initialize target repository
+echo "🔧 Configuring AI agent environments in $TARGET..."
+
+mkdir -p "$TARGET"
+if $CLONED; then
+  (cd "$TARGET" && node "$HERE/dist/index.js" init --merge ${ALL:+--all})
+else
+  (cd "$TARGET" && npx -y @plumpslabs/kuma init --merge ${ALL:+--all})
+fi
+
+# 4. Configure MCP for detected environments (non-destructive merge)
+echo ""
+echo "🔌 Configuring MCP Server integrations..."
+
+merge_mcp_config() {
+  local mcp_path="$1"
+  local label="$2"
+  node -e "
+    const fs = require('fs');
+    let data = {};
+    if (fs.existsSync('$mcp_path')) {
+      try { data = JSON.parse(fs.readFileSync('$mcp_path', 'utf-8')); } catch(e) {}
+    }
+    data.mcpServers = data.mcpServers || {};
+    if (!data.mcpServers.kuma) {
+      data.mcpServers.kuma = { command: 'npx', args: ['-y', '@plumpslabs/kuma'] };
+      fs.writeFileSync('$mcp_path', JSON.stringify(data, null, 2) + '\n', 'utf-8');
+      console.log('  ✅ Added kuma to $label ($mcp_path)');
+    } else {
+      console.log('  ℹ️  kuma already registered in $label');
+    }
+  "
+}
+
+# Claude Code / Desktop
+if [ -d "$TARGET/.claude" ] || [ -f "$TARGET/CLAUDE.md" ]; then
+  mkdir -p "$TARGET/.claude"
+  merge_mcp_config "$TARGET/.mcp.json" "Claude Code"
+fi
+
+# Cursor
+if [ -d "$TARGET/.cursor" ] || [ -f "$TARGET/.cursorrules" ]; then
+  mkdir -p "$TARGET/.cursor"
+  merge_mcp_config "$TARGET/.cursor/mcp.json" "Cursor"
+fi
+
+# Antigravity / Gemini CLI
+if [ -d "$TARGET/.agents" ] || [ -f "$TARGET/GEMINI.md" ]; then
+  mkdir -p "$TARGET/.agents"
+  merge_mcp_config "$TARGET/.agents/mcp_config.json" "Antigravity"
+fi
+
+# OpenCode
+if [ -d "$TARGET/.opencode" ] || [ -f "$TARGET/opencode.json" ] || [ -f "$TARGET/opencode.jsonc" ]; then
+  OPENCODE_CONF="$TARGET/opencode.json"
+  node -e "
+    const fs = require('fs');
+    let data = { '\$schema': 'https://opencode.ai/config.json' };
+    const confPath = fs.existsSync('$TARGET/opencode.jsonc') ? '$TARGET/opencode.jsonc' : '$OPENCODE_CONF';
+    if (fs.existsSync(confPath)) {
+      try { data = JSON.parse(fs.readFileSync(confPath, 'utf-8')); } catch(e) {}
+    }
+    data.mcp = data.mcp || {};
+    if (!data.mcp.kuma) {
+      data.mcp.kuma = { type: 'local', command: ['npx', '-y', '@plumpslabs/kuma'], enabled: true };
+      fs.writeFileSync(confPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+      console.log('  ✅ Added kuma to OpenCode (' + confPath + ')');
+    } else {
+      console.log('  ℹ️  kuma already registered in OpenCode');
+    }
+  "
+fi
+
+echo ""
+echo "🎉 Kuma setup complete!"
+echo "• Rules & hooks: Active in target configuration files"
+echo "• MCP tools: kuma_context, kuma_memory, kuma_safety ready"
+echo "• Studio dashboard: run 'npx @plumpslabs/kuma studio' to visualize"

package/mcp_config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "kuma": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@plumpslabs/kuma"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "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",
@@ -11,7 +11,17 @@
   "files": [
     "dist/",
     "packages/ide/studio/dist/",
-    "packages/ide/studio/public/"
+    "packages/ide/studio/public/",
+    "plugin.json",
+    "mcp_config.json",
+    "install.sh",
+    "INSTALL.md",
+    "hooks.json",
+    "hooks/",
+    "skills/",
+    "commands/",
+    "agents/",
+    ".claude-plugin/"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.7.0",
@@ -65,7 +75,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --no-splitting --clean --out-dir dist",
     "build:studio": "cd packages/ide/studio && tsup src/index.ts --format esm --clean --out-dir dist",
-    "build:all": "pnpm run build && pnpm run build:studio",
+    "build:all": "npm run build && npm run build:studio",
     "dev": "tsup src/index.ts --format esm --watch --out-dir dist",
     "start": "node dist/index.js",
     "studio": "node dist/index.js studio",

package/packages/ide/studio/dist/index.js

@@ -163,11 +163,34 @@ async function getDashboardData() {
       `SELECT json_group_array(json_object('source',source_id,'target',target_id,'relation',type,'weight',weight)) FROM edges`
     );
     const gotchas = jsonRows(
-      `SELECT json_group_array(json_object('id',id,'file_path',file_path,'description',REPLACE(REPLACE(description,char(10),' '),char(13),''),'severity',severity,'workaround',REPLACE(REPLACE(COALESCE(workaround,''),char(10),' '),char(13),''),'added_by',COALESCE(added_by,'agent'),'created_at',created_at)) FROM (SELECT * FROM known_gotchas ORDER BY created_at DESC)`
+      `SELECT json_group_array(json_object('id',id,'file_path',file_path,'description',REPLACE(REPLACE(description,char(10),' '),char(13),''),'severity',severity,'workaround',REPLACE(REPLACE(COALESCE(workaround,''),char(10),' '),char(13),''),'added_by',COALESCE(added_by,'agent'),'status',COALESCE(status,'active'),'scope_package',COALESCE(scope_package,''),'verified_by',COALESCE(verified_by,''),'created_at',created_at,'updated_at',COALESCE(updated_at,created_at))) FROM (SELECT * FROM known_gotchas ORDER BY created_at DESC)`
+    );
+    const flows = jsonRows(
+      `SELECT json_group_array(json_object('id',id,'name',name,'file_path',COALESCE(file_path,''),'metadata',COALESCE(metadata,'{}'),'updated_at',updated_at)) FROM (SELECT * FROM nodes WHERE type = 'arch_flow' ORDER BY updated_at DESC)`
+    );
+    const decisions = jsonRows(
+      `SELECT json_group_array(json_object('id',id,'name',name,'metadata',COALESCE(metadata,'{}'),'created_at',created_at)) FROM (SELECT * FROM nodes WHERE type = 'decision' ORDER BY created_at DESC)`
     );
     const features = jsonRows(
       `SELECT json_group_array(json_object('id',id,'name',name,'metadata',COALESCE(metadata,'{}'))) FROM (SELECT * FROM nodes WHERE type = 'feature' ORDER BY updated_at DESC)`
     );
+    let workspace = { isWorkspace: false, packages: [] };
+    try {
+      const root = projectRootFromDb(dbPath);
+      const rootPkgPath = path.join(root, "package.json");
+      if (fs.existsSync(rootPkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(rootPkgPath, "utf-8"));
+        const pnpmWs = path.join(root, "pnpm-workspace.yaml");
+        const isWs = Boolean(pkg.workspaces || fs.existsSync(pnpmWs));
+        workspace = {
+          isWorkspace: isWs,
+          name: pkg.name || path.basename(root),
+          version: pkg.version || "1.0.0",
+          type: isWs ? fs.existsSync(pnpmWs) ? "pnpm" : "npm/yarn" : "single-package"
+        };
+      }
+    } catch {
+    }
     let injectionCount = 0;
     let injectionSavedMs = 0;
     try {
@@ -219,7 +242,7 @@ async function getDashboardData() {
       recentSessions
     };
     const staleness = detectStaleNodes(db, dbPath);
-    return { stats, nodes, edges, gotchas, efficiency, staleness, injections: { count: injectionCount, savedMs: injectionSavedMs, savedFormatted: Math.round(injectionSavedMs / 6e4) + " min" } };
+    return { stats, nodes, edges, gotchas, flows, decisions, workspace, efficiency, staleness, injections: { count: injectionCount, savedMs: injectionSavedMs, savedFormatted: Math.round(injectionSavedMs / 6e4) + " min" } };
   } finally {
     db.close();
   }