xtrm-tools 0.5.0

package/hooks/gitnexus/gitnexus-hook.cjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Claude Code Hook — PostToolUse enrichment
+ *
+ * Fires AFTER Read/Grep/Glob/Bash/Serena tools complete.
+ * Extracts patterns from both tool input AND output, runs
+ * `gitnexus augment <pattern>`, and injects a [GitNexus: ...]
+ * block into Claude's context — mirroring pi-gitnexus behavior.
+ *
+ * Features:
+ *  - PostToolUse (vs old PreToolUse) — enriches actual result
+ *  - Session-keyed dedup cache (/tmp) — no redundant lookups
+ *  - Pattern extraction from output content (grep-style scanning)
+ *  - Serena tool support — extracts symbol names from name_path
+ *  - Graceful failure — always exits 0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const CODE_EXTS = new Set([
+  '.ts', '.tsx', '.js', '.mjs', '.cjs', '.py', '.go', '.rs',
+  '.java', '.kt', '.cpp', '.c', '.h', '.rb', '.php', '.cs',
+]);
+
+const SERENA_SYMBOL_TOOLS = new Set([
+  'mcp__serena__find_symbol',
+  'mcp__serena__find_referencing_symbols',
+  'mcp__serena__replace_symbol_body',
+  'mcp__serena__insert_after_symbol',
+  'mcp__serena__insert_before_symbol',
+]);
+
+const SERENA_FILE_TOOLS = new Set([
+  'mcp__serena__get_symbols_overview',
+  'mcp__serena__search_for_pattern',
+]);
+
+const SERENA_RENAME = 'mcp__serena__rename_symbol';
+
+function readInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function findGitNexusIndex(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, '.gitnexus'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+function getCacheFile(sessionId) {
+  const id = sessionId ? sessionId.replace(/[^a-zA-Z0-9_-]/g, '_') : 'default';
+  return path.join(os.tmpdir(), `gitnexus-aug-${id}`);
+}
+
+function loadCache(cacheFile) {
+  try {
+    return new Set(fs.readFileSync(cacheFile, 'utf-8').split('\n').filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+function saveToCache(cacheFile, pattern) {
+  try {
+    fs.appendFileSync(cacheFile, pattern + '\n');
+  } catch { /* graceful */ }
+}
+
+function symbolFromNamePath(namePath) {
+  if (!namePath) return null;
+  const parts = namePath.split('/').filter(Boolean);
+  const last = parts[parts.length - 1];
+  return last ? last.replace(/\[\d+\]$/, '') : null;
+}
+
+function symbolFromFilePath(filePath) {
+  if (!filePath) return null;
+  const ext = path.extname(filePath);
+  if (!CODE_EXTS.has(ext)) return null;
+  return path.basename(filePath, ext);
+}
+
+function extractFilePatternsFromOutput(content) {
+  if (!content || typeof content !== 'string') return [];
+  const patterns = new Set();
+  const lines = content.split('\n').slice(0, 50);
+  for (const line of lines) {
+    const m = line.match(/^([^\s:]+\.[a-z]{1,5}):\d+:/);
+    if (m) {
+      const ext = path.extname(m[1]);
+      if (CODE_EXTS.has(ext)) patterns.add(path.basename(m[1], ext));
+    }
+  }
+  return [...patterns];
+}
+
+function extractPatterns(toolName, toolInput, toolResponse) {
+  const patterns = [];
+  const content = typeof toolResponse === 'string'
+    ? toolResponse
+    : (toolResponse?.content ?? toolResponse?.output ?? '');
+
+  if (toolName === 'Read') {
+    const sym = symbolFromFilePath(toolInput.file_path);
+    if (sym) patterns.push(sym);
+  }
+
+  if (toolName === 'Grep') {
+    const raw = toolInput.pattern || '';
+    const cleaned = raw.replace(/[.*+?^${}()|[\]\\]/g, '').trim();
+    if (cleaned.length >= 3) patterns.push(cleaned);
+    patterns.push(...extractFilePatternsFromOutput(content));
+  }
+
+  if (toolName === 'Glob') {
+    const raw = toolInput.pattern || '';
+    const m = raw.match(/([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    if (m) patterns.push(m[1]);
+    patterns.push(...extractFilePatternsFromOutput(
+      Array.isArray(toolResponse) ? toolResponse.join('\n') : String(toolResponse || '')
+    ));
+  }
+
+  if (toolName === 'Bash') {
+    const cmd = toolInput.command || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return [];
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false, skipNext = false;
+    const flagsWithValues = new Set(['-e','-f','-m','-A','-B','-C','-g','--glob','-t','--type','--include','--exclude']);
+    for (const token of tokens) {
+      if (skipNext) { skipNext = false; continue; }
+      if (!foundCmd) { if (/\brg$|\bgrep$/.test(token)) foundCmd = true; continue; }
+      if (token.startsWith('-')) { if (flagsWithValues.has(token)) skipNext = true; continue; }
+      const cleaned = token.replace(/['"]/g, '').replace(/[.*+?^${}()|[\]\\]/g, '').trim();
+      if (cleaned.length >= 3) { patterns.push(cleaned); break; }
+    }
+    patterns.push(...extractFilePatternsFromOutput(content));
+  }
+
+  if (SERENA_SYMBOL_TOOLS.has(toolName)) {
+    const sym = symbolFromNamePath(toolInput.name_path_pattern || toolInput.name_path);
+    if (sym) patterns.push(sym);
+  }
+
+  if (toolName === SERENA_RENAME) {
+    if (toolInput.symbol_name) patterns.push(toolInput.symbol_name);
+  }
+
+  if (SERENA_FILE_TOOLS.has(toolName)) {
+    const sym = symbolFromFilePath(toolInput.relative_path || toolInput.file_path);
+    if (sym) patterns.push(sym);
+    const sub = toolInput.substring || toolInput.pattern || '';
+    const cleaned = sub.replace(/[.*+?^${}()|[\]\\]/g, '').trim();
+    if (cleaned.length >= 3) patterns.push(cleaned);
+  }
+
+  return [...new Set(patterns.filter(p => p && p.length >= 3))];
+}
+
+function runAugment(pattern, cwd) {
+  try {
+    const child = spawnSync('gitnexus', ['augment', pattern], {
+      encoding: 'utf-8',
+      timeout: 8000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return (child.stderr || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+function main() {
+  try {
+    const input = readInput();
+    if (input.hook_event_name !== 'PostToolUse') return;
+
+    const cwd = input.cwd || process.cwd();
+    if (!findGitNexusIndex(cwd)) return;
+
+    const toolName = input.tool_name || '';
+    const toolInput = input.tool_input || {};
+    const toolResponse = input.tool_response ?? input.tool_result ?? '';
+
+    const patterns = extractPatterns(toolName, toolInput, toolResponse);
+    if (patterns.length === 0) return;
+
+    const cacheFile = getCacheFile(input.session_id);
+    const cache = loadCache(cacheFile);
+
+    const results = [];
+    for (const pattern of patterns) {
+      if (cache.has(pattern)) continue;
+      const out = runAugment(pattern, cwd);
+      saveToCache(cacheFile, pattern);
+      if (out) results.push(out);
+    }
+
+    if (results.length > 0) {
+      process.stdout.write('[GitNexus]\n' + results.join('\n\n') + '\n');
+    }
+  } catch (err) {
+    process.stderr.write('GitNexus hook error: ' + err.message + '\n');
+  }
+}
+
+main();

package/hooks/guard-rules.mjs

@@ -0,0 +1,118 @@
+// Canonical guard rule definitions shared across hooks, policies, and extensions.
+// Pure data module: named exports only.
+
+export const WRITE_TOOLS = [
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'NotebookEdit',
+  'mcp__serena__rename_symbol',
+  'mcp__serena__replace_symbol_body',
+  'mcp__serena__insert_after_symbol',
+  'mcp__serena__insert_before_symbol',
+];
+
+export const DANGEROUS_BASH_PATTERNS = [
+  'sed\\s+-i',
+  'echo\\s+[^\\n]*>',
+  'printf\\s+[^\\n]*>',
+  'cat\\s+[^\\n]*>',
+  'tee\\b',
+  '(?:^|\\s)(?:vim|nano|vi)\\b',
+  '(?:^|\\s)mv\\b',
+  '(?:^|\\s)cp\\b',
+  '(?:^|\\s)rm\\b',
+  '(?:^|\\s)mkdir\\b',
+  '(?:^|\\s)touch\\b',
+  '(?:^|\\s)chmod\\b',
+  '(?:^|\\s)chown\\b',
+  '>>',
+  '(?:^|\\s)git\\s+add\\b',
+  '(?:^|\\s)git\\s+commit\\b',
+  '(?:^|\\s)git\\s+merge\\b',
+  '(?:^|\\s)git\\s+push\\b',
+  '(?:^|\\s)git\\s+reset\\b',
+  '(?:^|\\s)git\\s+checkout\\b',
+  '(?:^|\\s)git\\s+rebase\\b',
+  '(?:^|\\s)git\\s+stash\\b',
+  '(?:^|\\s)npm\\s+install\\b',
+  '(?:^|\\s)bun\\s+install\\b',
+  '(?:^|\\s)bun\\s+add\\b',
+  '(?:^|\\s)node\\s+(?:-e|--eval)\\b',
+  '(?:^|\\s)bun\\s+(?:-e|--eval)\\b',
+  '(?:^|\\s)python\\s+-c\\b',
+  '(?:^|\\s)perl\\s+-e\\b',
+  '(?:^|\\s)ruby\\s+-e\\b',
+];
+
+export const SAFE_BASH_PREFIXES = [
+  // Git read-only
+  'git status',
+  'git log',
+  'git diff',
+  'git show',
+  'git blame',
+  'git branch',
+  'git fetch',
+  'git remote',
+  'git config',
+  'git pull',
+  'git stash',
+  'git worktree',
+  'git checkout -b',
+  'git switch -c',
+  // Tools
+  'gh',
+  'bd',
+  'npx gitnexus',
+  'xtrm finish',
+  // Read-only filesystem
+  'cat',
+  'ls',
+  'head',
+  'tail',
+  'pwd',
+  'which',
+  'type',
+  'env',
+  'printenv',
+  'find',
+  'grep',
+  'rg',
+  'fd',
+  'wc',
+  'sort',
+  'uniq',
+  'cut',
+  'awk',
+  'jq',
+  'yq',
+  'bat',
+  'less',
+  'more',
+  'file',
+  'stat',
+  'du',
+  'tree',
+  // Allowed writes (specific paths)
+  'touch .beads/',
+];
+
+export const NATIVE_TEAM_TOOLS = [
+  'Task',
+  'TeamCreate',
+  'TeamDelete',
+  'SendMessage',
+  'TaskCreate',
+  'TaskUpdate',
+  'TaskList',
+  'TaskGet',
+  'TaskOutput',
+  'TaskStop',
+];
+
+export const INTERACTIVE_TOOLS = [
+  'AskUserQuestion',
+  'EnterPlanMode',
+  'EnterWorktree',
+];

package/hooks/hooks.json

@@ -0,0 +1,116 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash|execute_shell_command|bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-claim-sync.mjs",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.cjs",
+            "timeout": 30000
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.py",
+            "timeout": 30000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|mcp__serena__find_symbol|mcp__serena__get_symbols_overview|mcp__serena__search_for_pattern|mcp__serena__find_referencing_symbols|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__rename_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/gitnexus/gitnexus-hook.cjs",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-stop-gate.mjs",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-memory-gate.mjs",
+            "timeout": 8000
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-compact-restore.mjs",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/serena-workflow-reminder.py"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-edit-gate.mjs",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-commit-gate.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/beads-compact-save.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/branch-state.mjs",
+            "timeout": 3000
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/main-guard-post-push.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Claude Code PostToolUse hook — after successful feature-branch push,
+// inject next-step PR workflow guidance.
+// Exit 0 in all paths (informational only).
+//
+// Installed by: xtrm install
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+if ((input.tool_name ?? '') !== 'Bash') process.exit(0);
+const cmd = (input.tool_input?.command ?? '').trim().replace(/\s+/g, ' ');
+if (!/^git\s+push\b/.test(cmd)) process.exit(0);
+
+function commandSucceeded(payload) {
+  const tr = payload?.tool_response ?? payload?.tool_result ?? payload?.result;
+  if (!tr || typeof tr !== 'object') return true;
+
+  if (tr.success === false) return false;
+  if (tr.error) return false;
+
+  const numeric = [tr.exit_code, tr.exitCode, tr.status, tr.returncode]
+    .find((v) => Number.isInteger(v));
+  if (typeof numeric === 'number' && numeric !== 0) return false;
+
+  return true;
+}
+
+if (!commandSucceeded(input)) process.exit(0);
+
+const cwd = input.cwd || process.cwd();
+let branch = '';
+try {
+  branch = execSync('git branch --show-current', {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+} catch {
+  process.exit(0);
+}
+
+const protectedBranches = process.env.MAIN_GUARD_PROTECTED_BRANCHES
+  ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',').map((b) => b.trim()).filter(Boolean)
+  : ['main', 'master'];
+
+if (!branch || protectedBranches.includes(branch)) process.exit(0);
+
+const tokens = cmd.split(' ');
+const lastToken = tokens[tokens.length - 1] ?? '';
+const explicitlyProtectedTarget = protectedBranches
+  .some((b) => lastToken === b || lastToken.endsWith(`:${b}`));
+if (explicitlyProtectedTarget) process.exit(0);
+
+process.stdout.write(JSON.stringify({
+  additionalContext:
+    `✅ Pushed '${branch}'. Next steps:\n` +
+    '  1. gh pr create --fill\n' +
+    '  2. gh pr merge --squash\n' +
+    '  3. git checkout main && git reset --hard origin/main\n' +
+    'Ensure beads state is updated (e.g. bd close <id>).',
+}));
+process.stdout.write('\n');
+process.exit(0);

package/hooks/main-guard.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — block writes and direct master pushes
+// Exit 0: allow  |  Exit 2: block (message shown to user)
+//
+// Installed by: xtrm install
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { WRITE_TOOLS, SAFE_BASH_PREFIXES } from './guard-rules.mjs';
+
+let branch = '';
+try {
+  branch = execSync('git branch --show-current', {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+} catch {}
+
+const protectedBranches = process.env.MAIN_GUARD_PROTECTED_BRANCHES
+  ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',').map(b => b.trim()).filter(Boolean)
+  : ['main', 'master'];
+
+if (!branch || !protectedBranches.includes(branch)) {
+  process.exit(0);
+}
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const tool = input.tool_name ?? '';
+const cwd = input.cwd || process.cwd();
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+function getSessionState(cwd) {
+  const statePath = join(cwd, '.xtrm-session-state.json');
+  if (!existsSync(statePath)) return null;
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGitCCommand(cmd) {
+  const match = cmd.match(/^git\s+-C\s+(?:"[^"]+"|'[^']+'|\S+)\s+(.+)$/);
+  if (match?.[1]) return `git ${match[1]}`;
+  return cmd;
+}
+
+if (WRITE_TOOLS.includes(tool)) {
+  deny(`⛔ On '${branch}' — start on a feature branch and claim an issue.\n`
+    + '  git checkout -b feature/<name>  (or: git switch -c feature/<name>)\n'
+    + '  bd update <id> --claim\n');
+}
+
+if (tool === 'Bash') {
+  const cmd = (input.tool_input?.command ?? '').trim().replace(/\s+/g, ' ');
+  const normalizedCmd = normalizeGitCCommand(cmd);
+  const state = getSessionState(cwd);
+
+  if (process.env.MAIN_GUARD_ALLOW_BASH === '1') {
+    process.exit(0);
+  }
+
+  if (/^gh\s+pr\s+merge\b/.test(cmd)) {
+    if (!/--squash\b/.test(cmd)) {
+      deny('⛔ Squash only: gh pr merge --squash\n'
+        + '  (override: MAIN_GUARD_ALLOW_BASH=1 gh pr merge --merge)\n');
+    }
+    process.exit(0);
+  }
+
+  const SAFE_BASH_PATTERNS = [
+    ...SAFE_BASH_PREFIXES.map(prefix => new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`)),
+    ...protectedBranches.map(b => new RegExp(`^git\\s+reset\\s+--hard\\s+origin/${b}\\b`)),
+  ];
+
+  if (SAFE_BASH_PATTERNS.some(p => p.test(cmd) || p.test(normalizedCmd))) {
+    process.exit(0);
+  }
+
+  if (/\bgit\s+commit\b/.test(normalizedCmd)) {
+    deny(`⛔ No commits on '${branch}' — use a feature branch/worktree.\n`
+      + '  git checkout -b feature/<name>\n'
+      + '  bd update <id> --claim\n');
+  }
+
+  if (/\bgit\s+push\b/.test(normalizedCmd)) {
+    const tokens = normalizedCmd.split(' ');
+    const lastToken = tokens[tokens.length - 1];
+    const explicitProtected = protectedBranches.some(b => lastToken === b || lastToken.endsWith(`:${b}`));
+    const impliedProtected = tokens.length <= 3 && protectedBranches.includes(branch);
+    if (explicitProtected || impliedProtected) {
+      deny(`⛔ No direct push to '${branch}' — push a feature branch and open a PR.\n`
+        + '  git push -u origin <feature-branch> && gh pr create --fill\n');
+    }
+    process.exit(0);
+  }
+
+  const handoff = state?.worktreePath
+    ? `  Active worktree session recorded: ${state.worktreePath}\n  (Current workaround) use feature branch flow until worktree bug is fixed.\n`
+    : '  Exit: git checkout -b feature/<name>  (or: git switch -c feature/<name>)\n  Then: bd update <id> --claim\n';
+
+  deny(`⛔ Bash restricted on '${branch}'. Allowed: read-only commands, gh, bd, git checkout -b, git switch -c.\n`
+    + handoff
+    + '  Override: MAIN_GUARD_ALLOW_BASH=1 <cmd>\n');
+}
+
+process.exit(0);