xtrm-tools 2.0.2 → 2.1.0

package/hooks/main-guard.mjs

@@ -0,0 +1,149 @@
+#!/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 { readFileSync } from 'node:fs';
+
+let branch = '';
+try {
+  branch = execSync('git branch --show-current', {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+} catch {}
+
+// Determine protected branches — env var override for tests and custom setups
+const protectedBranches = process.env.MAIN_GUARD_PROTECTED_BRANCHES
+  ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',').map(b => b.trim()).filter(Boolean)
+  : ['main', 'master'];
+
+// Not in a git repo or not on a protected branch — allow
+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 hookEventName = input.hook_event_name ?? 'PreToolUse';
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    systemMessage: reason,
+    hookSpecificOutput: {
+      hookEventName,
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+if (WRITE_TOOLS.has(tool)) {
+  deny(
+    `⛔ You are on '${branch}' — never edit files directly on master.\n\n` +
+    'Full workflow:\n' +
+    '  1. git checkout -b feature/<name>         ← start here\n' +
+    '  2. bd create + bd update in_progress      track your work\n' +
+    '  3. Edit files / write code\n' +
+    '  4. bd close <id> && git add && git commit\n' +
+    '  5. git push -u origin feature/<name>\n' +
+    '  6. gh pr create --fill && gh pr merge --squash\n' +
+    '  7. git checkout master && git reset --hard origin/master\n'
+  );
+}
+
+const WORKFLOW =
+  'Full workflow:\n' +
+  '  1. git checkout -b feature/<name>         \u2190 start here\n' +
+  '  2. bd create + bd update in_progress      track your work\n' +
+  '  3. Edit files / write code\n' +
+  '  4. bd close <id> && git add && git commit\n' +
+  '  5. git push -u origin feature/<name>\n' +
+  '  6. gh pr create --fill && gh pr merge --squash\n' +
+  '  7. git checkout master && git reset --hard origin/master\n';
+
+if (tool === 'Bash') {
+  const cmd = (input.tool_input?.command ?? '').trim().replace(/\s+/g, ' ');
+
+  // Emergency override — escape hatch for power users
+  if (process.env.MAIN_GUARD_ALLOW_BASH === '1') {
+    process.exit(0);
+  }
+
+  // Safe allowlist — non-mutating commands + explicit branch-exit paths.
+  // Important: do not allow generic checkout/switch forms, which include
+  // mutating variants such as `git checkout -- <path>`.
+  const SAFE_BASH_PATTERNS = [
+    /^git\s+(status|log|diff|branch|show|describe|fetch|remote|config)\b/,
+    /^git\s+pull\b/,
+    /^git\s+stash\b/,
+    /^git\s+worktree\b/,
+    /^git\s+checkout\s+-b\s+\S+/,
+    /^git\s+switch\s+-c\s+\S+/,
+    /^gh\s+/,
+    /^bd\s+/,
+  ];
+
+  if (SAFE_BASH_PATTERNS.some(p => p.test(cmd))) {
+    process.exit(0);
+  }
+
+  // Specific messages for common blocked operations
+  if (/^git\s+commit\b/.test(cmd)) {
+    deny(
+      `\u26D4 Don't commit directly to '${branch}' \u2014 use a feature branch.\n\n` +
+      WORKFLOW
+    );
+  }
+
+  if (/^git\s+push\b/.test(cmd)) {
+    const tokens = cmd.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(
+        `\u26D4 Don't push directly to '${branch}' \u2014 use the PR workflow.\n\n` +
+        'Next steps:\n' +
+        '  5. git push -u origin <feature-branch>     \u2190 push your branch\n' +
+        '  6. gh pr create --fill                      create PR\n' +
+        '     gh pr merge --squash                     merge it\n' +
+        '  7. git checkout master                      sync master\n' +
+        '     git reset --hard origin/master\n\n' +
+        "If you're not on a feature branch yet:\n" +
+        '  git checkout -b feature/<name>    (then re-commit and push)\n'
+      );
+    }
+    // Pushing to a feature branch — allow
+    process.exit(0);
+  }
+
+  // Default deny — block everything else on protected branches
+  deny(
+    `\u26D4 Bash is restricted on '${branch}' \u2014 use a feature branch for file writes and script execution.\n\n` +
+    'Allowed on protected branches:\n' +
+    '  git status / log / diff / branch / fetch / pull / stash\n' +
+    '  git checkout -b <name>   (create feature branch \u2014 the exit path)\n' +
+    '  git switch -c <name>     (same)\n' +
+    '  git worktree / config\n' +
+    '  gh <any>                 (GitHub CLI)\n' +
+    '  bd <any>                 (beads issue tracking)\n\n' +
+    'To run arbitrary commands:\n' +
+    '  1. git checkout -b feature/<name>   \u2190 move to a feature branch, or\n' +
+    '  2. MAIN_GUARD_ALLOW_BASH=1 <command>  (escape hatch, use sparingly)\n'
+  );
+}
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
     "dotenv": "^17.3.1",
     "fs-extra": "^11.2.0",
     "kleur": "^4.1.5",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "xtrm-tools": "^2.0.2"
   }
 }

package/project-skills/py-quality-gate/.claude/settings.json

@@ -2,7 +2,7 @@
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/SKILL.md

@@ -20,7 +20,7 @@ immediately useful to any agent working on the service.
 
 ## Mandatory Two-Phase Workflow
 
-**Both phases are required. Never skip Phase 2.**
+**Use both phases every time.** Phase 1 gives structure; Phase 2 grounds the skill in real service behavior.
 
 ---
 
@@ -65,7 +65,7 @@ python3 "$CLAUDE_PROJECT_DIR/.claude/skills/creating-service-skills/scripts/deep
 
 ---
 
-### Phase 2: Agentic Deep Dive (Non-Negotiable)
+### Phase 2: Agentic Deep Dive
 
 After the skeleton exists, answer every research question by reading the actual
 source code. Use **Serena LSP tools exclusively** — never read entire files.
@@ -118,10 +118,10 @@ source code. Use **Serena LSP tools exclusively** — never read entire files.
 
 ---
 
-### Phase 2 Script Writing (Required — No Stubs)
+### Phase 2 Script Writing (Complete Implementation)
 
-After research is complete, replace ALL `[PENDING RESEARCH]` stubs in `scripts/`.
-Each script must be fully implemented — no TODOs, no placeholder SQL.
+After research is complete, replace all `[PENDING RESEARCH]` stubs in `scripts/`.
+Scripts should be ready to run end-to-end, without TODO markers or placeholder SQL.
 
 #### Mandatory DB Connection Pattern (all scripts that touch the DB)
 
@@ -207,10 +207,10 @@ Required features:
 
 See [references/script_quality_standards.md](references/script_quality_standards.md) for complete templates.
 
-#### `scripts/Makefile` (required — always present)
+#### `scripts/Makefile` (required)
 
-The scaffolder creates a stub `Makefile` in Phase 1. In Phase 2 you **must verify it is
-correct and complete** — it is the primary entry point users and agents use to run diagnostics.
+The scaffolder creates a stub `Makefile` in Phase 1. In Phase 2, verify it is
+correct and complete because it is the primary entry point for diagnostics.
 
 **Standard template** (copy verbatim, replace `<service-id>` comment only):
 
@@ -261,11 +261,11 @@ db:
 
 **Rules for the delegated Phase 2 agent:**
 
-1. **Do not remove or rename the standard targets** — they form the stable interface.
+1. **Keep standard targets stable** — avoid removing or renaming them because downstream workflows depend on them.
 2. **Add service-specific targets** below the standard block if the service needs them (e.g. `make auth`, `make schema`, `make backfill`).
-3. **The `_VENV` auto-detect path (`../../../../venv/bin/python3`) is fixed** — it resolves from `scripts/` → service dir → `skills/` → `.claude/` → project root → `venv/`. Do not change the depth.
-4. **Recipe lines use a real tab character**, not spaces. Makefile syntax requires this.
-5. **Verify with `make help`** after writing — the Python path shown must resolve to the project venv, not system python.
+3. **Keep the `_VENV` auto-detect path (`../../../../venv/bin/python3`) unchanged** — it resolves from `scripts/` → service dir → `skills/` → `.claude/` → project root → `venv/`.
+4. **Use real tab characters in recipe lines** so Makefile parsing works consistently.
+5. **Run `make help` after updates** and confirm the Python path resolves to the project venv.
 
 ---
 

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/references/script_quality_standards.md

@@ -6,6 +6,19 @@
 
 ---
 
+## Table of Contents
+
+- [Mandatory DB Connection Pattern](#mandatory-db-connection-pattern)
+- [Schema Verification Before Writing Any SQL](#schema-verification-before-writing-any-sql)
+- [Makefile Standard](#makefile-standard)
+- [Design Principles](#design-principles)
+- [health_probe.py Standards](#health_probepy-standards)
+- [log_hunter.py Standards](#log_hunterpy-standards)
+- [Specialist Script Standards](#specialist-script-standards)
+- [Common Pitfalls](#common-pitfalls)
+
+---
+
 ## Mandatory DB Connection Pattern
 
 **Every script that touches the database MUST use this exact pattern.** No exceptions.

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/references/service_skill_system_guide.md

@@ -5,6 +5,20 @@
 
 ---
 
+## Table of Contents
+
+- [1. System Overview](#1-system-overview)
+- [2. System Architecture](#2-system-architecture)
+- [3. Mandatory Two-Phase Workflow](#3-mandatory-two-phase-workflow)
+- [4. Service Type Classification](#4-service-type-classification)
+- [5. Directory Structure](#5-directory-structure)
+- [6. Skill Lifecycle](#6-skill-lifecycle)
+- [7. Quality Gates](#7-quality-gates)
+- [8. Best Practices](#8-best-practices)
+- [9. Anti-Patterns](#9-anti-patterns)
+
+---
+
 ## 1. System Overview
 
 The **Service Skill System** transforms an AI agent from a generic assistant into a service-aware operator. Each Docker service in your project gets a dedicated **skill package**: a structured combination of operational documentation and executable diagnostic scripts.

package/project-skills/service-skills-set/.claude/skills/scoping-service-skills/SKILL.md

@@ -24,7 +24,7 @@ in the conversation.
 
 ### Step 1 — Read the Registry
 
-Run this **immediately**, before any reasoning:
+Run this at the start, before deep task reasoning:
 
 ```bash
 python3 "$CLAUDE_PROJECT_DIR/.claude/skills/scoping-service-skills/scripts/scope.py"
@@ -73,7 +73,7 @@ Using the registry output, reason about which service(s) the task involves. Matc
 
 ### Step 4 — Output XML Scope Block
 
-Emit this block **before doing anything else**:
+Emit this block before moving into implementation:
 
 ```xml
 <scope>
@@ -120,15 +120,15 @@ For each `<service>` with `<load>now</load>`, immediately read the skill file:
 Read: .claude/skills/<service-id>/SKILL.md
 ```
 
-**Do not proceed with the task until all matched skills are loaded.**
+Load all matched skills before proceeding with the task.
 Adopt the expert persona, constraints, and diagnostic approach from each loaded skill.
 
 ---
 
 ### Step 6 — Execute
 
-Follow the workflow phases in order. For `investigation` tasks, **never skip the
-regression-test phase** — a fix without a test is incomplete.
+Follow the workflow phases in order. For `investigation` tasks, include the
+regression-test phase — it keeps fixes durable.
 
 ---
 
@@ -187,7 +187,7 @@ load-skill → answer
 
 ## Regression Test Binding
 
-When `intent = investigation` and a fix has been applied, always write a regression
+When `intent = investigation` and a fix has been applied, write a regression
 test. Use this decision tree:
 
 ```

package/project-skills/service-skills-set/.claude/skills/updating-service-skills/SKILL.md

@@ -109,7 +109,7 @@ Write to:
 - ✅ `.claude/skills/*/SKILL.md` — skill documentation updates
 - ✅ `.claude/skills/service-registry.json` — territory and sync timestamp updates
 
-Do not:
+Avoid:
 - ❌ Modify source code (read-only access to service territories)
 - ❌ Delete skills or registry entries
 

package/project-skills/service-skills-set/.claude/skills/using-service-skills/SKILL.md

@@ -78,8 +78,8 @@ If no registered expert covers the user's need:
 
 ## Session Start Hook
 
-The catalog injection is **not** handled by skill frontmatter hooks (SessionStart
-is not supported in skill-level hooks). It is configured in `.claude/settings.json`:
+The catalog injection is not handled by skill frontmatter hooks. Configure it in
+`.claude/settings.json` using `SessionStart`:
 
 ```json
 {

package/project-skills/service-skills-set/.claude/skills/using-service-skills/scripts/skill_activator.py

@@ -19,7 +19,7 @@ from pathlib import Path
 BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
 sys.path.insert(0, str(BOOTSTRAP_DIR))
 
-from bootstrap import RootResolutionError, get_project_root, load_registry  # noqa: E402
+from bootstrap import RootResolutionError, get_project_root, load_registry  # noqa: E402  # type: ignore[import-not-found]
 
 
 def match_territory(file_path: str, territory: list[str], project_root: Path) -> bool:
@@ -109,7 +109,7 @@ def main() -> None:
 
     try:
         project_root = Path(get_project_root())
-        services = load_registry()
+        services = load_registry().get("services", {})
     except (RootResolutionError, Exception):
         sys.exit(0)
 

package/project-skills/service-skills-set/.claude/skills/using-service-skills/scripts/test_skill_activator.py

@@ -0,0 +1,58 @@
+"""Tests for skill_activator.py — load_registry integration."""
+import io
+import json
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+scripts_dir = Path(__file__).parent
+sys.path.insert(0, str(scripts_dir))
+sys.path.insert(0, str(scripts_dir.parent.parent / "creating-service-skills" / "scripts"))
+
+import skill_activator
+
+
+REGISTRY_WITH_VERSION = {
+    "version": "1.0",
+    "services": {
+        "my-service": {
+            "territory": ["src/my-service/**"],
+            "name": "My Service",
+            "skill_path": ".claude/skills/my-service/SKILL.md",
+        }
+    },
+}
+
+HOOK_INPUT = json.dumps({
+    "tool_name": "Write",
+    "tool_input": {"file_path": "src/my-service/foo.py"},
+    "hook_event_name": "PreToolUse",
+    "session_id": "test",
+    "cwd": "/fake/project",
+})
+
+
+class TestMainWithVersionedRegistry(unittest.TestCase):
+    def test_main_does_not_crash_when_registry_has_version_key(self):
+        """main() must not crash with AttributeError when load_registry returns
+        {"version": ..., "services": {...}} — the full registry dict.
+        It should output valid JSON context for the matched service.
+        """
+        with patch("skill_activator.load_registry", return_value=REGISTRY_WITH_VERSION), \
+             patch("skill_activator.get_project_root", return_value="/fake/project"), \
+             patch("sys.stdin", io.StringIO(HOOK_INPUT)), \
+             patch("sys.stdout", new_callable=io.StringIO) as mock_stdout:
+            try:
+                skill_activator.main()
+            except SystemExit:
+                pass
+            output = mock_stdout.getvalue()
+
+        self.assertTrue(output, "Expected JSON output but got nothing")
+        result = json.loads(output)
+        self.assertIn("hookSpecificOutput", result)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/project-skills/ts-quality-gate/.claude/settings.json

@@ -2,7 +2,7 @@
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",

package/project-skills/main-guard/.claude/hooks/main-guard.cjs

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-/**
- * Main Guard - Git branch protection hook for Claude Code.
- * Blocks direct edits to main/master branches and enforces feature branch workflow.
- * 
- * Exit codes:
- *   0 - Allowed (not on protected branch, or operation allowed)
- *   1 - Fatal error
- *   2 - Blocked (attempted edit on protected branch)
- */
-
-const { execSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-// Colors
-const colors = {
-  red: '\x1b[0;31m',
-  green: '\x1b[0;32m',
-  yellow: '\x1b[0;33m',
-  blue: '\x1b[0;34m',
-  cyan: '\x1b[0;36m',
-  reset: '\x1b[0m',
-};
-
-function log(msg, color = '') {
-  console.error(`${color}${msg}${colors.reset}`);
-}
-
-function logInfo(msg) { log(`[INFO] ${msg}`, colors.blue); }
-function logError(msg) { log(`[ERROR] ${msg}`, colors.red); }
-function logSuccess(msg) { log(`[OK] ${msg}`, colors.green); }
-function logWarning(msg) { log(`[WARN] ${msg}`, colors.yellow); }
-
-/**
- * Get current git branch name
- */
-function getCurrentBranch() {
-  try {
-    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
-  } catch (e) {
-    logWarning('Could not determine git branch');
-    return null;
-  }
-}
-
-/**
- * Check if branch is protected
- */
-function isProtectedBranch(branch) {
-  if (!branch) return false;
-  
-  // Get protected branches from config or use defaults
-  const protectedPatterns = process.env.MAIN_GUARD_PROTECTED_BRANCHES 
-    ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',') 
-    : ['main', 'master', 'develop'];
-  
-  return protectedPatterns.some(pattern => {
-    const regex = new RegExp(`^${pattern.replace('*', '.*')}$`);
-    return regex.test(branch);
-  });
-}
-
-/**
- * Get feature branch name suggestion based on task
- */
-function suggestBranchName(input) {
-  const toolName = input.tool_name || '';
-  const prompt = input.user_prompt || '';
-  
-  // Extract potential task identifier
-  const match = prompt.match(/(?:issue|ticket|task|bug|feat)[#:-]?\s*(\d+|[a-z-]+)/i) ||
-                prompt.match(/^([a-z-]+)/i);
-  
-  if (match) {
-    const prefix = toolName.includes('Edit') || toolName.includes('Write') ? 'fix' : 'feat';
-    return `${prefix}/${match[1].toLowerCase().replace(/\s+/g, '-')}`;
-  }
-  
-  return 'feature/task';
-}
-
-/**
- * Parse JSON input from stdin
- */
-function parseInput() {
-  let inputData = '';
-  
-  try {
-    inputData = fs.readFileSync(0, 'utf8');
-  } catch (e) {
-    return null;
-  }
-  
-  if (!inputData.trim()) {
-    return null;
-  }
-  
-  try {
-    return JSON.parse(inputData);
-  } catch (e) {
-    logWarning('Invalid JSON input');
-    return null;
-  }
-}
-
-/**
- * Print blocked message with instructions
- */
-function printBlocked(branch, suggestedBranch) {
-  log('', colors.red);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('  🛑 BLOCKED: Direct edits to protected branches', colors.red);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('', colors.reset);
-  log(`  Current branch: ${colors.yellow}${branch}${colors.reset}`, colors.reset);
-  log('', colors.reset);
-  log('  You cannot edit files directly on a protected branch.', colors.reset);
-  log('  This prevents accidental commits and enforces code review.', colors.reset);
-  log('', colors.reset);
-  log('  📋 To proceed:', colors.cyan);
-  log(`     1. Create a feature branch: ${colors.green}git checkout -b ${suggestedBranch}${colors.reset}`, colors.reset);
-  log(`     2. Make your changes on that branch`, colors.reset);
-  log(`     3. Push and create a pull request`, colors.reset);
-  log('', colors.reset);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('', colors.reset);
-}
-
-/**
- * Print success message
- */
-function printSuccess(branch) {
-  log('', colors.green);
-  log(`✅ Git workflow check passed`, colors.green);
-  log(`   Branch: ${branch}`, colors.green);
-  log('', colors.reset);
-}
-
-/**
- * Main entry point
- */
-function main() {
-  log('');
-  log('🔒 Main Guard - Branch Protection Check', colors.blue);
-  log('─────────────────────────────────────────', colors.blue);
-  
-  // Parse input
-  const input = parseInput();
-  
-  // Get current branch
-  const branch = getCurrentBranch();
-  
-  if (!branch) {
-    logWarning('Not in a git repository - skipping branch protection');
-    log('', colors.yellow);
-    log('👉 Not a git repository - continuing without branch protection', colors.yellow);
-    log('', colors.reset);
-    process.exit(0);
-  }
-  
-  logInfo(`Current branch: ${branch}`);
-  
-  // Check if protected
-  if (isProtectedBranch(branch)) {
-    const suggestedBranch = suggestBranchName(input || {});
-    printBlocked(branch, suggestedBranch);
-    process.exit(2);
-  }
-  
-  // Not a protected branch - allow
-  printSuccess(branch);
-  process.exit(0);
-}
-
-// Handle errors
-process.on('unhandledRejection', (error) => {
-  logError(`Unhandled error: ${error.message}`);
-  process.exit(1);
-});
-
-// Run
-try {
-  main();
-} catch (error) {
-  logError(`Fatal error: ${error.message}`);
-  process.exit(1);
-}

package/project-skills/main-guard/.claude/settings.json

@@ -1,16 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/main-guard.cjs\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
-}