xtrm-tools 0.7.0 → 0.7.1

package/plugins/xtrm-tools/.mcp.json

@@ -1,18 +0,0 @@
-{
-  "mcpServers": {
-    "github-grep": {
-      "type": "http",
-      "url": "https://mcp.grep.app"
-    },
-    "deepwiki": {
-      "type": "http",
-      "url": "https://mcp.deepwiki.com/mcp"
-    },
-    "gitnexus": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "gitnexus", "mcp"],
-      "env": {}
-    }
-  }
-}

package/plugins/xtrm-tools/hooks/README.md

@@ -1,61 +0,0 @@
-# Hooks
-
-Claude Code hooks that extend agent behavior with automated checks, workflow enhancements, and safety guardrails.
-
-## Overview
-
-Hooks intercept specific events in the Claude Code lifecycle. Following architecture decisions in v2.0.0+, the hook ecosystem is designed exclusively for Claude Code.
-
-*Note: In v2.1.15+, several older hooks (`skill-suggestion.py`, `skill-discovery.py`, `gitnexus-impact-reminder.py`, and `type-safety-enforcement.py`) were removed or superseded by native capabilities, CLI commands, and consolidated quality gates.*
-
-## Project Hooks
-
-### gitnexus-hook.cjs
-
-**Purpose**: Enriches tool calls with knowledge graph context via `gitnexus augment`. Now supports Serena tools and uses a deduplication cache for efficiency.
-
-**Trigger**: PostToolUse (Grep|Glob|Bash|Serena edit tools)
-
-## Beads Issue Tracking Gates
-
-The beads gate hooks integrate the `bd` (beads) issue tracker directly into Claude's workflow, ensuring no code changes happen without an active ticket.
-
-**Installation**: Installed with `xtrm install all` or included when `beads`+`dolt` is available.
-
-### Core Gates
-- **`beads-edit-gate.mjs`** (PreToolUse) — Blocks writes/edits without an active issue claim.
-- **`beads-commit-gate.mjs`** (PreToolUse) — Blocks commits with an unresolved session claim.
-- **`beads-stop-gate.mjs`** (Stop) — Blocks session stop while a claim remains open.
-- **`beads-close-memory-prompt.mjs`** (PostToolUse) — Prompts memory handoff after `bd close`.
-
-### Compaction & State Preservation (v2.1.18+)
-- **`beads-pre-compact.mjs`** (PreCompact) — Saves the currently `in_progress` beads state before Claude clears context.
-- **`beads-session-start.mjs`** (SessionStart) — Restores the `in_progress` state when the session restarts after compaction.
-
-*Note: As of v2.1.18+, hook blocking messages are quieted and compacted to save tokens.*
-
-## Hook Timeouts
-
-Adjust hook execution timeouts in `settings.json` if commands take longer than expected:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "hooks": [{
-        "timeout": 5000  // Timeout in milliseconds (5000ms = 5 seconds)
-      }]
-    }]
-  }
-}
-```
-
-## Creating Custom Hooks
-
-To create new project-specific hooks, use the `hook-development` global skill. Follow the canonical structure defined in the `xtrm-tools` core libraries.
-
-For debugging orphaned hooks, use `xtrm clean`.
-
-## Pi Extensions Migration
-
-Core workflow hooks have been migrated to native Pi Extensions for better performance and integration. See the [Pi Extensions Migration Guide](../docs/pi-extensions-migration.md) for details.

package/plugins/xtrm-tools/hooks/beads-claim-sync.mjs

@@ -1,154 +0,0 @@
-#!/usr/bin/env node
-// beads-claim-sync — PostToolUse hook
-// bd update --claim → set kv claim
-// bd close         → set closed-this-session kv for memory gate
-
-import { spawnSync } from 'node:child_process';
-import { readFileSync, existsSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
-import { join, dirname, isAbsolute } from 'node:path';
-import { resolveSessionId } from './beads-gate-utils.mjs';
-import { logEvent } from './xtrm-logger.mjs';
-
-function readInput() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-function isBeadsProject(cwd) {
-  return existsSync(join(cwd, '.beads'));
-}
-
-// In a git worktree, --git-common-dir returns an absolute path to the main .git dir.
-// In a regular repo it returns '.git' (relative). Use this to find the canonical main root
-// so claim files are always written/deleted from the same location across sessions.
-function resolveMainRoot(cwd) {
-  const r = spawnSync('git', ['rev-parse', '--git-common-dir'], {
-    cwd, encoding: 'utf8', stdio: 'pipe',
-  });
-  const commonDir = r.stdout?.trim();
-  if (commonDir && isAbsolute(commonDir)) return dirname(commonDir);
-  return cwd;
-}
-
-// Returns a per-session claim filename: 'statusline-claim' for the main session,
-// 'statusline-claim-<worktreeName>' for worktree sessions.
-// Prevents cross-session contamination when multiple worktrees run simultaneously.
-function resolveClaimFileName(cwd) {
-  const m = cwd.match(/\/\.xtrm\/worktrees\/([^/]+)/);
-  return m ? `statusline-claim-${m[1]}` : 'statusline-claim';
-}
-
-function isShellTool(toolName) {
-  return toolName === 'Bash' || toolName === 'bash' || toolName === 'execute_shell_command';
-}
-
-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;
-}
-
-
-
-
-function main() {
-  const input = readInput();
-  if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
-  if (!isShellTool(input.tool_name)) process.exit(0);
-
-  const cwd = input.cwd || process.cwd();
-  if (!isBeadsProject(cwd)) process.exit(0);
-
-  const command = input.tool_input?.command || '';
-  const sessionId = resolveSessionId(input);
-
-  // Auto-claim: bd update <id> --claim (fire regardless of exit code — bd returns 1 for "already in_progress")
-  if (/\bbd\s+update\b/.test(command) && /--claim\b/.test(command)) {
-    const match = command.match(/\bbd\s+update\s+(\S+)/);
-    if (match) {
-      const issueId = match[1];
-      const result = spawnSync('bd', ['kv', 'set', `claimed:${sessionId}`, issueId], {
-        cwd,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 5000,
-      });
-
-      if (result.status !== 0) {
-        const err = (result.stderr || result.stdout || '').toString().trim();
-        if (err) process.stderr.write(`Beads claim sync warning: ${err}\n`);
-        process.exit(0);
-      }
-
-      // Write claim state for statusline — per-worktree file under main root.
-      try {
-        const xtrmDir = join(resolveMainRoot(cwd), '.xtrm');
-        mkdirSync(xtrmDir, { recursive: true });
-        writeFileSync(join(xtrmDir, resolveClaimFileName(cwd)), issueId);
-      } catch { /* non-fatal */ }
-
-      logEvent({
-        cwd,
-        runtime: 'claude',
-        sessionId,
-        layer: 'bd',
-        kind: 'bd.claimed',
-        outcome: 'allow',
-        issueId,
-      });
-
-      process.stdout.write(JSON.stringify({
-        additionalContext: `\n✅ **Beads**: Session \`${sessionId}\` claimed issue \`${issueId}\`.`,
-      }));
-      process.stdout.write('\n');
-      process.exit(0);
-    }
-  }
-
-  // On bd close: mark closed-this-session for memory gate
-  if (/\bbd\s+close\b/.test(command) && commandSucceeded(input)) {
-    const match = command.match(/\bbd\s+close\s+(\S+)/);
-    const closedIssueId = match?.[1];
-
-    // Clear claim state for statusline — per-worktree file under main root.
-    try { unlinkSync(join(resolveMainRoot(cwd), '.xtrm', resolveClaimFileName(cwd))); } catch { /* ok if missing */ }
-
-    // Mark this issue as closed this session (memory gate reads this)
-    if (closedIssueId) {
-      spawnSync('bd', ['kv', 'set', `closed-this-session:${sessionId}`, closedIssueId], {
-        cwd,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 5000,
-      });
-
-      logEvent({
-        cwd,
-        runtime: 'claude',
-        sessionId,
-        layer: 'bd',
-        kind: 'bd.closed',
-        outcome: 'allow',
-        issueId: closedIssueId,
-      });
-    }
-
-    process.stdout.write(JSON.stringify({
-      additionalContext: `\n🔓 **Beads**: Issue closed. Evaluate insights, then acknowledge:\n  \`bd remember "<insight>"\` (or note "nothing to persist")`,
-    }));
-    process.stdout.write('\n');
-    process.exit(0);
-  }
-
-  process.exit(0);
-}
-
-main();

package/plugins/xtrm-tools/hooks/beads-commit-gate.mjs

@@ -1,70 +0,0 @@
-#!/usr/bin/env node
-// beads-commit-gate — Claude Code PreToolUse hook
-// Blocks `git commit` when this session still has an unclosed claim in bd kv.
-// Falls back to global in_progress check when session_id is unavailable.
-// Forces: close issues first, THEN commit.
-// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
-//
-// Installed by: xtrm install
-
-import {
-  readHookInput,
-  resolveSessionContext,
-  resolveClaimAndWorkState,
-  decideCommitGate,
-} from './beads-gate-core.mjs';
-import { withSafeBdContext } from './beads-gate-utils.mjs';
-import { commitBlockMessage } from './beads-gate-messages.mjs';
-import { logEvent } from './xtrm-logger.mjs';
-
-const input = readHookInput();
-if (!input) process.exit(0);
-
-if ((input.tool_name ?? '') !== 'Bash') process.exit(0);
-
-const command = input.tool_input?.command ?? '';
-// Strip quoted strings to avoid matching patterns inside --reason "..." or similar args
-const commandUnquoted = command.replace(/'[^']*'|"[^"]*"/g, '');
-
-withSafeBdContext(() => {
-  const ctx = resolveSessionContext(input);
-  if (!ctx || !ctx.isBeadsProject) process.exit(0);
-
-  // Only intercept git commit for the claim-gate check
-  if (!/\bgit\s+commit\b/.test(commandUnquoted)) process.exit(0);
-
-  const state = resolveClaimAndWorkState(ctx);
-  const decision = decideCommitGate(ctx, state);
-
-  if (decision.allow) {
-    logEvent({
-      cwd: ctx.cwd,
-      runtime: 'claude',
-      sessionId: ctx.sessionId,
-      layer: 'gate',
-      kind: 'gate.commit.allow',
-      outcome: 'allow',
-      toolName: 'Bash',
-      issueId: state?.claimId ?? null,
-    });
-    process.exit(0);
-  }
-
-  // Block with structured decision
-  const reason = commitBlockMessage(decision.summary, decision.claimed);
-  logEvent({
-    cwd: ctx.cwd,
-    runtime: 'claude',
-    sessionId: ctx.sessionId,
-    layer: 'gate',
-    kind: 'gate.commit.block',
-    outcome: 'block',
-    toolName: 'Bash',
-    issueId: decision.claimed ?? null,
-    message: reason,
-    extra: { reason_code: decision.reason },
-  });
-  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
-  process.stdout.write('\n');
-  process.exit(0);
-});

package/plugins/xtrm-tools/hooks/beads-compact-restore.mjs

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-// Claude Code SessionStart hook — restore in_progress beads issues after context compaction.
-// Reads .beads/.last_active (written by beads-compact-save.mjs), reinstates statuses,
-// restores session state file, deletes the marker, and injects a brief agent context message.
-// Exit 0 in all paths (informational only).
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync, unlinkSync } from 'node:fs';
-import path from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-const lastActivePath = path.join(cwd, '.beads', '.last_active');
-
-if (!existsSync(lastActivePath)) process.exit(0);
-
-let ids = [];
-let serenaProject = null;
-
-try {
-  const raw = readFileSync(lastActivePath, 'utf8').trim();
-  if (raw.startsWith('{')) {
-    const parsed = JSON.parse(raw);
-    ids = Array.isArray(parsed.ids) ? parsed.ids.filter(Boolean) : [];
-    serenaProject = parsed.serenaProject ?? null;
-  } else {
-    // Backward compatibility: legacy newline format
-    ids = raw.split('\n').filter(Boolean);
-  }
-} catch {
-  // If file is malformed, just delete and continue fail-open.
-}
-
-// Clean up regardless of whether restore succeeds
-unlinkSync(lastActivePath);
-
-let restored = 0;
-for (const id of ids) {
-  try {
-    execSync(`bd update ${id} --status in_progress`, {
-      encoding: 'utf8',
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 5000,
-    });
-    restored++;
-  } catch {
-    // ignore — issue may no longer exist
-  }
-}
-
-if (restored > 0 || serenaProject) {
-  const parts = [];
-  if (restored > 0) {
-    parts.push(`Restored ${restored} in_progress issue${restored === 1 ? '' : 's'} from last session before compaction. Check \`bd list\` for details.`);
-  }
-  if (serenaProject) {
-    parts.push(`Serena was active on project "${serenaProject}" — re-activate with activate_project("${serenaProject}") before any symbol lookups.`);
-  }
-
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalSystemPrompt: parts.join(' '),
-      },
-    }) + '\n',
-  );
-}
-
-process.exit(0);

package/plugins/xtrm-tools/hooks/beads-compact-save.mjs

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-// Claude Code PreCompact hook — save in_progress beads issues before context is compacted.
-// Writes a compact bundle to .beads/.last_active for restore hook.
-// Bundle includes issue IDs and xtrm session state when available.
-// Exit 0 in all paths (informational only).
-
-import { execSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import path from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-const beadsDir = path.join(cwd, '.beads');
-
-if (!existsSync(beadsDir)) process.exit(0);
-
-let output = '';
-try {
-  output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  }).trim();
-} catch {
-  process.exit(0);
-}
-
-// Parse issue IDs — lines like "◐ proj-abc123 ● P1 Title"
-const ids = [];
-for (const line of output.split('\n')) {
-  const match = line.trim().match(/^[○◐●✓❄]\s+([\w-]+)\s/u);
-  if (match) ids.push(match[1]);
-}
-
-const bundle = {
-  ids,
-  savedAt: new Date().toISOString(),
-};
-
-// Detect active Serena project
-const serenaProjectYml = path.join(cwd, '.serena', 'project.yml');
-if (existsSync(serenaProjectYml)) {
-  try {
-    const yml = readFileSync(serenaProjectYml, 'utf8');
-    const m = yml.match(/^project_name:\s*["']?([^"'\n]+)["']?/m);
-    if (m) bundle.serenaProject = m[1].trim();
-  } catch {
-    // ignore — not critical
-  }
-}
-
-if (bundle.ids.length === 0 && !bundle.serenaProject) process.exit(0);
-
-writeFileSync(path.join(beadsDir, '.last_active'), JSON.stringify(bundle, null, 2) + '\n', 'utf8');
-
-process.exit(0);

package/plugins/xtrm-tools/hooks/beads-edit-gate.mjs

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-// beads-edit-gate — Claude Code PreToolUse hook
-// Blocks file edits when this session has not claimed a beads issue via bd kv.
-// Falls back to global in_progress check when session_id is unavailable.
-// Only active in projects with a .beads/ directory.
-// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
-//
-// Installed by: xtrm install
-
-import {
-  readHookInput,
-  resolveSessionContext,
-  resolveClaimAndWorkState,
-  decideEditGate,
-  decideWorktreeBoundary,
-} from './beads-gate-core.mjs';
-import { withSafeBdContext, resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
-import { editBlockMessage, editBlockFallbackMessage } from './beads-gate-messages.mjs';
-import { logEvent } from './xtrm-logger.mjs';
-
-const input = readHookInput();
-if (!input) process.exit(0);
-
-// Worktree boundary check — independent of beads, fires first
-const _cwd = resolveCwd(input);
-const _boundary = decideWorktreeBoundary(input, _cwd);
-if (!_boundary.allow) {
-  const _wbReason = `🚫 Edit outside worktree boundary.\n  File:    ${_boundary.filePath}\n  Allowed: ${_boundary.worktreeRoot}\n\n  All edits must stay within the active worktree.`;
-  logEvent({
-    cwd: _cwd,
-    runtime: 'claude',
-    sessionId: resolveSessionId(input),
-    layer: 'gate',
-    kind: 'gate.worktree.block',
-    outcome: 'block',
-    toolName: input.tool_name,
-    message: _wbReason,
-    extra: { file: _boundary.filePath, worktree_root: _boundary.worktreeRoot },
-  });
-  process.stdout.write(JSON.stringify({ decision: 'block', reason: _wbReason }));
-  process.stdout.write('\n');
-  process.exit(0);
-}
-
-withSafeBdContext(() => {
-  const ctx = resolveSessionContext(input);
-  if (!ctx || !ctx.isBeadsProject) process.exit(0);
-
-  const state = resolveClaimAndWorkState(ctx);
-  const decision = decideEditGate(ctx, state);
-
-  if (decision.allow) {
-    logEvent({
-      cwd: ctx.cwd,
-      runtime: 'claude',
-      sessionId: ctx.sessionId,
-      layer: 'gate',
-      kind: 'gate.edit.allow',
-      outcome: 'allow',
-      toolName: input.tool_name,
-      issueId: state?.claimId ?? null,
-      extra: { file: input.tool_input?.file_path ?? null },
-    });
-    process.exit(0);
-  }
-
-  // Block with appropriate message
-  const reason = decision.reason === 'no_claim_with_work'
-    ? editBlockMessage(decision.sessionId)
-    : editBlockFallbackMessage();
-  logEvent({
-    cwd: ctx.cwd,
-    runtime: 'claude',
-    sessionId: ctx.sessionId,
-    layer: 'gate',
-    kind: 'gate.edit.block',
-    outcome: 'block',
-    toolName: input.tool_name,
-    message: reason,
-    extra: { file: input.tool_input?.file_path ?? null, reason_code: decision.reason },
-  });
-  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
-  process.stdout.write('\n');
-  process.exit(0);
-});