xtrm-tools 0.7.0 → 0.7.2

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);
-});

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

@@ -1,236 +0,0 @@
-#!/usr/bin/env node
-// beads-gate-core.mjs — pure decision functions for beads gate hooks
-// Import from sibling hooks using: import { ... } from './beads-gate-core.mjs';
-//
-// All functions are pure: they return decision objects, never call process.exit()
-// or write to stdout/stderr. Side effects belong in entrypoint wrappers.
-//
-// Dependencies: beads-gate-utils.mjs (adapters)
-
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import {
-  resolveCwd,
-  resolveSessionId,
-  isBeadsProject,
-  getSessionClaim,
-  getTotalWork,
-  getInProgress,
-  isIssueInProgress,
-  resolveWorktreeRoot,
-} from './beads-gate-utils.mjs';
-
-// ── Input parsing ────────────────────────────────────────────────────────────
-
-/**
- * Read and parse hook input from stdin. Returns null on parse error.
- * Entrypoints should exit 0 if this returns null (fail-open).
- */
-export function readHookInput() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// ── Session context resolution ───────────────────────────────────────────────
-
-/**
- * Resolve session context from hook input.
- * Returns { cwd, sessionId, isBeadsProject } or null if cwd can't be resolved.
- */
-export function resolveSessionContext(input) {
-  const cwd = resolveCwd(input);
-  if (!cwd) return null;
-  return {
-    cwd,
-    sessionId: resolveSessionId(input),
-    isBeadsProject: isBeadsProject(cwd),
-  };
-}
-
-// ── Claim and work state resolution ──────────────────────────────────────────
-
-/**
- * Resolve the claim and work state for a session.
- * Returns { claimed, claimId, totalWork, inProgress } or null if bd unavailable.
- */
-export function resolveClaimAndWorkState(ctx) {
-  if (!ctx.isBeadsProject) {
-    return { claimed: false, claimId: null, totalWork: 0, inProgress: null };
-  }
-
-  const totalWork = getTotalWork(ctx.cwd);
-  if (totalWork === null) return null; // bd unavailable
-
-  const inProgress = getInProgress(ctx.cwd);
-
-  if (ctx.sessionId) {
-    const claimId = getSessionClaim(ctx.sessionId, ctx.cwd);
-    if (claimId === null) return null; // bd kv unavailable
-    return {
-      claimed: !!claimId,
-      claimId: claimId || null,
-      claimInProgress: claimId ? isIssueInProgress(claimId, ctx.cwd) : false,
-      totalWork,
-      inProgress,
-    };
-  }
-
-  // No session_id: fallback to global in_progress check
-  return {
-    claimed: false,
-    claimId: null,
-    claimInProgress: false,
-    totalWork,
-    inProgress,
-  };
-}
-
-// ── Decision functions ───────────────────────────────────────────────────────
-
-/**
- * Decide whether a file edit is within the active worktree boundary.
- * If the session cwd is inside .xtrm/worktrees/<name>, block any edit whose
- * resolved path falls outside that worktree root.
- * Returns { allow: boolean, filePath?: string, worktreeRoot?: string }
- */
-export function decideWorktreeBoundary(input, cwd) {
-  const filePath = input?.tool_input?.file_path;
-  if (!filePath) return { allow: true };
-
-  const worktreeRoot = resolveWorktreeRoot(cwd);
-  if (!worktreeRoot) return { allow: true }; // not in a worktree — no constraint
-
-  const abs = resolve(cwd, filePath);
-  if (abs === worktreeRoot || abs.startsWith(worktreeRoot + '/')) return { allow: true };
-
-  return { allow: false, filePath: abs, worktreeRoot };
-}
-
-/**
- * Decide whether to allow or block an edit operation.
- * Returns { allow: boolean, reason?: string, sessionId?: string }
- */
-export function decideEditGate(ctx, state) {
-  // Not a beads project → allow
-  if (!ctx.isBeadsProject) {
-    return { allow: true };
-  }
-
-  // bd unavailable → fail open
-  if (state === null) {
-    return { allow: true };
-  }
-
-  // Session has an active claim → allow
-  if (state.claimed) {
-    return { allow: true };
-  }
-
-  // No trackable work → allow (clean-start state)
-  if (state.totalWork === 0) {
-    return { allow: true };
-  }
-
-  // Has session_id but no claim + has work → block
-  if (ctx.sessionId) {
-    return {
-      allow: false,
-      reason: 'no_claim_with_work',
-      sessionId: ctx.sessionId,
-    };
-  }
-
-  // Fallback: no session_id, check global in_progress
-  if (state.inProgress && state.inProgress.count > 0) {
-    return { allow: true };
-  }
-
-  // No session_id, no in_progress, but has open work → block
-  if (state.totalWork > 0) {
-    return {
-      allow: false,
-      reason: 'no_claim_fallback',
-    };
-  }
-
-  return { allow: true };
-}
-
-/**
- * Decide whether to allow or block a git commit operation.
- * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
- */
-export function decideCommitGate(ctx, state) {
-  // Not a beads project → allow
-  if (!ctx.isBeadsProject) {
-    return { allow: true };
-  }
-
-  // bd unavailable → fail open
-  if (state === null) {
-    return { allow: true };
-  }
-
-  // No active claim → allow (nothing to close)
-  if (!state.claimed) {
-    return { allow: true };
-  }
-
-  // Claimed issue is no longer in_progress → allow (closed or transferred to another agent)
-  if (!state.claimInProgress) {
-    return { allow: true };
-  }
-
-  // Session's own claimed issue is still in_progress → block (need to close first)
-  return {
-    allow: false,
-    reason: 'unclosed_claim',
-    summary: `  Claimed: ${state.claimId} (still in_progress)`,
-    claimed: state.claimId,
-  };
-}
-
-/**
- * Decide whether to allow or block a stop operation.
- * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
- */
-export function decideStopGate(ctx, state) {
-  // Not a beads project → allow
-  if (!ctx.isBeadsProject) {
-    return { allow: true };
-  }
-
-  // bd unavailable → fail open
-  if (state === null) {
-    return { allow: true };
-  }
-
-  // No active claim → allow
-  if (!state.claimed) {
-    // But check for global in_progress (no session_id fallback)
-    if (!ctx.sessionId && state.inProgress && state.inProgress.count > 0) {
-      return {
-        allow: false,
-        reason: 'global_in_progress',
-        summary: state.inProgress.summary,
-      };
-    }
-    return { allow: true };
-  }
-
-  // Claimed issue is no longer in_progress → allow (stale claim)
-  if (!state.claimInProgress) {
-    return { allow: true };
-  }
-
-  // Session's own claimed issue is still in_progress → block
-  return {
-    allow: false,
-    reason: 'unclosed_claim',
-    summary: `  Claimed: ${state.claimId} (still in_progress)`,
-    claimed: state.claimId,
-  };
-}

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

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-// beads-gate-messages.mjs — centralized message templates for beads gate hooks
-// Import from sibling hooks using: import { ... } from './beads-gate-messages.mjs';
-//
-// All user-facing strings live here. Edit this file to change messaging.
-// Policy logic lives in beads-gate-core.mjs.
-
-// ── Shared workflow steps ────────────────────────────────────────────
-
-export const SESSION_CLOSE_PROTOCOL =
-  '  bd close <id> --reason="..."\n' +
-  '  xt end\n';
-
-export const COMMIT_NEXT_STEPS =
-  '  bd close <id> --reason="..."   ← closes issue\n' +
-  '  xt end                          ← push, PR, merge, worktree cleanup\n';
-
-// ── Edit gate messages ───────────────────────────────────────────
-
-export function editBlockMessage(_sessionId) {
-  return (
-    '🚫 No active claim — claim an issue first.\n' +
-    '  bd update <id> --claim\n'
-  );
-}
-
-export function editBlockFallbackMessage() {
-  return (
-    '🚫 No active issue — create one before editing.\n' +
-    '  bd create --title="<task>" --type=task --priority=2\n' +
-    '  bd update <id> --claim\n'
-  );
-}
-
-// ── Commit gate messages ─────────────────────────────────────────
-
-export function commitBlockMessage(summary, claimed) {
-  const issueSummary = summary ?? `  Claimed: ${claimed}`;
-  return (
-    '🚫 Close open issues before committing.\n\n' +
-    `${issueSummary}\n\n` +
-    'Next steps:\n' + COMMIT_NEXT_STEPS
-  );
-}
-
-// ── Stop gate messages ───────────────────────────────────────────
-
-export function stopBlockMessage(summary, claimed) {
-  const issueSummary = summary ?? `  Claimed: ${claimed}`;
-  return (
-    '🚫 Unresolved issues — close before stopping.\n\n' +
-    `${issueSummary}\n\n` +
-    'Next steps:\n' + SESSION_CLOSE_PROTOCOL
-  );
-}
-
-// ── Memory gate messages ─────────────────────────────────────────
-
-export function memoryPromptMessage(claimId, sessionId) {
-  const claimLine = claimId ? `claim \`${claimId}\` was closed.\n` : '';
-  const ackCmd = `bd kv set "memory-gate-done:${sessionId}"`;
-  return (
-    `\u25cf Memory gate: ${claimLine}` +
-    'For each candidate insight, check ALL 4:\n' +
-    '  1. Hard to rediscover from code/docs?\n' +
-    '  2. Not obvious from the current implementation?\n' +
-    '  3. Will affect a future decision?\n' +
-    '  4. Still relevant in ~14 days?\n' +
-    'KEEP (all 4 yes) → `bd remember "<insight>"`\n' +
-    'SKIP examples: file maps, flag inventories, per-issue summaries,\n' +
-    '  wording tweaks, facts obvious from reading the source.\n' +
-    `KEEP: \`${ackCmd} "saved: <key>"\`\n` +
-    `SKIP: \`${ackCmd} "nothing novel — <one-line reason>"\`\n`
-  );
-}