xtrm-tools 2.1.6 → 2.1.7

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.1.4",
+  "version": "2.1.7",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",
@@ -39,5 +39,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

package/config/hooks.json

@@ -47,6 +47,11 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "script": "main-guard-post-push.mjs",
+        "timeout": 5000
+      },
       {
         "matcher": "Bash",
         "script": "beads-close-memory-prompt.mjs",

package/hooks/README.md

@@ -168,6 +168,25 @@ Installed globally to `~/.claude/hooks/` by `xtrm install`. Require Node.js.
 
 ---
 
+### main-guard-post-push.mjs
+
+**Purpose**: After a successful `git push` from a non-protected branch, injects a reminder for the next PR workflow steps.
+
+**Trigger**: PostToolUse (`Bash`) — only fires when command matches `git push` and appears successful.
+
+**Behavior**:
+- No blocking (informational only)
+- Skips protected branches (`main`/`master`)
+- Skips explicit pushes targeting protected branches
+
+**Guidance injected**:
+- `gh pr create --fill`
+- `gh pr merge --squash`
+- `git checkout main && git pull --ff-only`
+- Reminder to keep beads issue state updated
+
+---
+
 ### beads-gate-utils.mjs
 
 **Purpose**: Shared utility module imported by all beads gate hooks. Not registered as a hook itself.

package/hooks/beads-stop-gate.mjs

@@ -39,6 +39,7 @@ withSafeBdContext(() => {
     if (!claimed) process.exit(0);         // no active claim for this session
 
     const ip = getInProgress(cwd);
+    if (ip === null || ip.count === 0) process.exit(0); // claim is stale — allow stop
     const summary = ip?.summary ?? `  Claimed: ${claimed}`;
 
     process.stderr.write(

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({
+  systemMessage:
+    `✅ Pushed '${branch}'. Next workflow steps:\n\n` +
+    '  1. gh pr create --fill\n' +
+    '  2. gh pr merge --squash\n' +
+    '  3. git checkout main && git pull --ff-only\n\n' +
+    'Before/after merge, ensure beads state is updated (e.g. bd close <id>).',
+}));
+process.stdout.write('\n');
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,11 @@
     "config",
     "hooks",
     "skills",
-    "project-skills"
+    "project-skills",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!project-skills/service-skills-set/.claude/skills/using-service-skills/scripts/test_*.py",
+    "!skills/documenting/tests/**"
   ],
   "publishConfig": {
     "access": "public"
@@ -32,15 +36,18 @@
     "url": "https://github.com/Jaggerxtrm/xtrm-tools/issues"
   },
   "scripts": {
+    "sync:cli-version": "node scripts/sync-cli-version.mjs",
+    "prebuild": "npm run sync:cli-version",
     "build": "npm run build --workspace cli",
     "typecheck": "npm run typecheck --workspace cli",
     "start": "node cli/dist/index.cjs",
     "lint": "echo 'No linting configured'",
     "test": "npm test --workspace cli",
-    "prepublishOnly": "npm run build"
+    "version": "npm run sync:cli-version && git add cli/package.json",
+    "prepublishOnly": "npm run sync:cli-version && npm run build"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "comment-json": "^4.2.3",

package/project-skills/{py-quality-gate → quality-gates}/.claude/settings.json

@@ -1,6 +1,16 @@
 {
   "hooks": {
     "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|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_PROJECT_DIR/.claude/hooks/quality-check.cjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "hooks": [

package/project-skills/quality-gates/.claude/skills/using-quality-gates/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: using-quality-gates
+description: 'Quality Gates workflow for Claude Code. Use when editing code in projects with quality enforcement. Covers the full cycle: TDD guard (write failing test first) → implement → auto-lint/typecheck. Activates on code edits, quality issues, or when user asks about testing/linting workflow.'
+---
+
+# Using Quality Gates
+
+**Quality Gates** provides automated code quality enforcement through PostToolUse hooks:
+
+1. **TypeScript Quality Gate** — Runs after TS/JS edits: TypeScript + ESLint + Prettier
+2. **Python Quality Gate** — Runs after Python edits: Ruff + Mypy
+
+**Separate Installation Required for TDD:**
+- **TDD Guard** is a separate tool (not included) — See "TDD Guard Setup" below
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  QUALITY GATES (this skill)                                     │
+│  ─────────────────────────────                                  │
+│  PostToolUse Hooks (installed by this skill):                   │
+│  • .claude/hooks/quality-check.cjs  → TS/JS files              │
+│  • .claude/hooks/quality-check.py   → Python files             │
+│  • .claude/settings.json            → Hook registration        │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────┐
+│  TDD GUARD (separate installation)                              │
+│  ───────────────────────────────────                            │
+│  PreToolUse Hook (requires xtrm install project tdd-guard):    │
+│  • Global CLI: npm install -g tdd-guard                        │
+│  • Test reporter: tdd-guard-vitest / tdd-guard-pytest / etc.   │
+│  • Hook: .claude/hooks/tdd-guard-pretool-bridge.cjs            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+### Step 1: Install This Skill
+
+```bash
+xtrm install project quality-gates
+```
+
+This installs:
+- `.claude/hooks/quality-check.cjs` — TypeScript/JavaScript checks
+- `.claude/hooks/quality-check.py` — Python checks
+- `.claude/settings.json` — PostToolUse hook registration
+- `.claude/skills/using-quality-gates/` — This documentation
+
+### Step 2: Install Language Dependencies
+
+**TypeScript Projects:**
+```bash
+npm install --save-dev typescript eslint prettier
+```
+
+**Python Projects:**
+```bash
+pip install ruff mypy
+```
+
+### Step 3: (Optional) Install TDD Guard
+
+For test-first enforcement, install TDD Guard separately:
+
+```bash
+# 1. Install global CLI
+npm install -g tdd-guard
+
+# 2. Install project-skill for hook wiring
+xtrm install project tdd-guard
+
+# 3. Install test reporter (choose one)
+npm install --save-dev tdd-guard-vitest    # Vitest
+npm install --save-dev tdd-guard-jest      # Jest
+pip install tdd-guard-pytest               # pytest
+```
+
+**Configure test reporter** (see https://github.com/nizos/tdd-guard):
+
+**Vitest:**
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { VitestReporter } from 'tdd-guard-vitest'
+
+export default defineConfig({
+  test: {
+    reporters: ['default', new VitestReporter('/path/to/project')],
+  },
+})
+```
+
+**pytest:**
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+tdd_guard_project_root = "/path/to/project"
+```
+
+## How Quality Gates Work
+
+### TypeScript Quality Gate (PostToolUse)
+
+**Runs after:** Every `.ts`, `.tsx`, `.js`, `.jsx` file edit
+
+**Checks:**
+1. TypeScript compilation (type errors)
+2. ESLint validation (style, best practices)
+3. Prettier formatting (consistency)
+
+**Configuration** (`.claude/hooks/hook-config.json`):
+```json
+{
+  "typescript": { "enabled": true, "showDependencyErrors": false },
+  "eslint": { "enabled": true, "autofix": true },
+  "prettier": { "enabled": true, "autofix": true },
+  "general": { "autofixSilent": true }
+}
+```
+
+### Python Quality Gate (PostToolUse)
+
+**Runs after:** Every `.py` file edit
+
+**Checks:**
+1. Ruff linting (errors, style, best practices)
+2. Ruff formatting (Black-compatible)
+3. Mypy type checking (static types)
+
+**Configuration** (environment variables):
+```bash
+CLAUDE_HOOKS_RUFF_ENABLED=true
+CLAUDE_HOOKS_MYPY_ENABLED=true
+CLAUDE_HOOKS_AUTOFIX=true
+```
+
+## Exit Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | All checks passed | Continue |
+| 1 | Fatal error (missing deps) | Install missing tool |
+| 2 | Blocking errors | Claude must fix |
+
+## Handling Quality Gate Errors
+
+When blocked with exit code 2:
+
+1. **Read the error output** — Specific issues listed
+2. **Auto-fix applies automatically** — ESLint/Prettier/Ruff fix what they can
+3. **Fix remaining issues manually** — Type errors, complex violations
+4. **Gate re-runs on next edit** — No manual trigger needed
+
+**Example:**
+```
+[ERROR] TypeScript compilation failed:
+  src/auth.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'
+
+[WARN] Auto-fix applied: 2 issues fixed
+[BLOCK] 1 issue remains - fix before continuing
+```
+
+## TDD Guard Integration
+
+When TDD Guard is installed alongside Quality Gates:
+
+```
+User Request: "Add feature X"
+        ↓
+┌───────────────────────────────────┐
+│ TDD Guard (PreToolUse)            │
+│ Checks: Failing test exists?      │
+│ • NO → BLOCK: "Write test first"  │
+│ • YES → Allow implementation      │
+└───────────────────────────────────┘
+        ↓
+Implementation (Write/Edit)
+        ↓
+┌───────────────────────────────────┐
+│ Quality Gates (PostToolUse)       │
+│ Runs: Lint + Typecheck + Format   │
+│ • Errors → BLOCK, fix issues      │
+│ • Pass → Continue                 │
+└───────────────────────────────────┘
+        ↓
+Tests pass → Commit
+```
+
+## Troubleshooting
+
+**"ESLint not found" / "Prettier not found"**
+```bash
+npm install --save-dev eslint prettier
+```
+
+**"Ruff not found" / "Mypy not found"**
+```bash
+pip install ruff mypy
+```
+
+**"tdd-guard: command not found"**
+```bash
+npm install -g tdd-guard
+```
+
+**"TDD Guard: No failing test found"**
+- Write a failing test first
+- Ensure test reporter is configured
+- Run tests to generate reporter JSON
+
+**Hook not running**
+- Verify `.claude/settings.json` exists
+- Check hook script paths are correct
+- Ensure file extension matches (`.ts`/`.py`)
+
+## When This Skill Activates
+
+**Triggers:**
+- Quality gate reports errors
+- User asks about linting, type checking, or quality workflow
+- Session starts in a project with quality gates installed
+
+**Response Modes:**
+
+**Full Workflow Mode** (user mentions quality/testing, blocked by gate errors):
+- Explain complete quality pipeline
+- Provide troubleshooting guidance
+
+**Minimal Mode** (general coding tasks without quality context):
+- Complete the task directly
+- Brief note: "Consider adding tests. If TDD Guard is installed, write failing test first."
+
+## Files Installed
+
+```
+.claude/
+├── settings.json              # PostToolUse hook registration
+├── hooks/
+│   ├── quality-check.cjs      # TypeScript/JavaScript checks
+│   ├── quality-check.py       # Python checks
+│   └── hook-config.json       # TS hook configuration
+├── skills/
+│   └── using-quality-gates/   # This skill
+└── docs/
+    └── quality-gates-readme.md
+```
+
+## Related
+
+- **TDD Guard**: https://github.com/nizos/tdd-guard
+- **xtrm install project tdd-guard**: Install TDD Guard hooks

package/project-skills/quality-gates/README.md

@@ -0,0 +1,109 @@
+# Quality Gates
+
+**PostToolUse code quality hooks** for Claude Code. Runs automatically after file edits to enforce linting, type checking, and formatting standards.
+
+## What This Installs
+
+**TypeScript Quality Gate** (`.ts`, `.tsx`, `.js`, `.jsx`):
+- TypeScript compilation check
+- ESLint validation + auto-fix
+- Prettier formatting + auto-fix
+
+**Python Quality Gate** (`.py`):
+- Ruff linting + auto-fix
+- Ruff formatting + auto-fix
+- Mypy type checking
+
+## Installation
+
+```bash
+# 1. Install this skill
+xtrm install project quality-gates
+
+# 2. Install language dependencies
+npm install --save-dev typescript eslint prettier  # TypeScript
+pip install ruff mypy                               # Python
+```
+
+## What Gets Installed
+
+```
+.claude/
+├── settings.json              # PostToolUse hook registration
+├── hooks/
+│   ├── quality-check.cjs      # TypeScript/JavaScript checks
+│   ├── quality-check.py       # Python checks
+│   └── hook-config.json       # TS hook configuration
+├── skills/
+│   └── using-quality-gates/   # Skill documentation
+└── docs/
+    └── quality-gates-readme.md
+```
+
+## How It Works
+
+After every file edit:
+1. Hook detects file type (TS/JS or Python)
+2. Runs appropriate quality checks
+3. Auto-fixes issues when possible
+4. Returns exit code:
+   - `0` = All checks passed
+   - `2` = Blocking errors (Claude must fix)
+
+## Configuration
+
+### TypeScript
+
+Edit `.claude/hooks/hook-config.json`:
+
+```json
+{
+  "typescript": { "enabled": true, "showDependencyErrors": false },
+  "eslint": { "enabled": true, "autofix": true },
+  "prettier": { "enabled": true, "autofix": true }
+}
+```
+
+### Python
+
+Set environment variables:
+
+```bash
+export CLAUDE_HOOKS_RUFF_ENABLED=true
+export CLAUDE_HOOKS_MYPY_ENABLED=true
+export CLAUDE_HOOKS_AUTOFIX=true
+```
+
+## TDD Guard (Separate Installation)
+
+For test-first enforcement, install TDD Guard separately:
+
+```bash
+# 1. Global CLI
+npm install -g tdd-guard
+
+# 2. Project skill for hooks
+xtrm install project tdd-guard
+
+# 3. Test reporter (choose one)
+npm install --save-dev tdd-guard-vitest    # Vitest
+npm install --save-dev tdd-guard-jest      # Jest
+pip install tdd-guard-pytest               # pytest
+```
+
+See: https://github.com/nizos/tdd-guard
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| "ESLint not found" | `npm install --save-dev eslint prettier` |
+| "Ruff not found" | `pip install ruff mypy` |
+| "tdd-guard: command not found" | `npm install -g tdd-guard` |
+| Hook not running | Check `.claude/settings.json` exists |
+
+## Related
+
+- **TDD Guard**: https://github.com/nizos/tdd-guard
+- **Ruff**: https://docs.astral.sh/ruff/
+- **Mypy**: https://mypy.readthedocs.io/