xtrm-tools 2.0.0

package/project-skills/py-quality-gate/.claude/hooks/quality-check.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""
+Python Quality Gate - PostToolUse hook for Claude Code.
+Runs ruff (linting/formatting) and mypy (type checking) on edited Python files.
+
+Exit codes:
+  0 - All checks passed
+  1 - Fatal error
+  2 - Blocking errors found (Claude must fix)
+"""
+
+import json
+import os
+import sys
+import subprocess
+import shutil
+from pathlib import Path
+
+# Colors for output
+class Colors:
+    RED = '\x1b[0;31m'
+    GREEN = '\x1b[0;32m'
+    YELLOW = '\x1b[0;33m'
+    BLUE = '\x1b[0;34m'
+    CYAN = '\x1b[0;36m'
+    RESET = '\x1b[0m'
+
+def log_info(msg: str):
+    print(f"{Colors.BLUE}[INFO]{Colors.RESET} {msg}", file=sys.stderr)
+
+def log_error(msg: str):
+    print(f"{Colors.RED}[ERROR]{Colors.RESET} {msg}", file=sys.stderr)
+
+def log_success(msg: str):
+    print(f"{Colors.GREEN}[OK]{Colors.RESET} {msg}", file=sys.stderr)
+
+def log_warning(msg: str):
+    print(f"{Colors.YELLOW}[WARN]{Colors.RESET} {msg}", file=sys.stderr)
+
+def log_debug(msg: str):
+    if os.environ.get('CLAUDE_HOOKS_DEBUG', 'false').lower() == 'true':
+        print(f"{Colors.CYAN}[DEBUG]{Colors.RESET} {msg}", file=sys.stderr)
+
+def find_project_root(file_path: str) -> str:
+    """Find project root by looking for pyproject.toml, setup.py, or .git"""
+    path = Path(file_path).parent
+    while path != path.parent:
+        if (path / 'pyproject.toml').exists() or \
+           (path / 'setup.py').exists() or \
+           (path / '.git').exists():
+            return str(path)
+        path = path.parent
+    return str(path)
+
+def is_python_file(file_path: str) -> bool:
+    """Check if file is a Python source file"""
+    return file_path.endswith('.py') and not file_path.endswith('__init__.py')
+
+def check_ruff(file_path: str, project_root: str, autofix: bool = False) -> tuple[bool, list[str], list[str]]:
+    """
+    Run ruff linting and formatting checks.
+    Returns: (passed, errors, autofixes)
+    """
+    errors = []
+    autofixes = []
+    
+    # Check if ruff is available
+    ruff_path = shutil.which('ruff')
+    if not ruff_path:
+        log_debug('Ruff not found in PATH - skipping ruff checks')
+        return True, errors, autofixes
+    
+    log_info('Running Ruff linting...')
+    
+    # Run ruff check
+    cmd = ['ruff', 'check', '--output-format=full', file_path]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            if autofix:
+                log_warning('Ruff issues found, attempting auto-fix...')
+                fix_cmd = ['ruff', 'check', '--fix', file_path]
+                fix_result = subprocess.run(fix_cmd, capture_output=True, text=True, cwd=project_root)
+                
+                if fix_result.returncode == 0:
+                    log_success('Ruff auto-fixed all issues!')
+                    autofixes.append('Ruff auto-fixed linting issues')
+                else:
+                    errors.append(f'Ruff found issues that could not be auto-fixed')
+                    errors.extend(result.stdout.strip().split('\n'))
+            else:
+                errors.append(f'Ruff found linting issues in {os.path.basename(file_path)}')
+                errors.extend(result.stdout.strip().split('\n'))
+        else:
+            log_success('Ruff linting passed')
+            
+    except Exception as e:
+        log_debug(f'Ruff check error: {e}')
+    
+    # Run ruff format check
+    log_info('Running Ruff format check...')
+    format_cmd = ['ruff', 'format', '--check', file_path]
+    try:
+        result = subprocess.run(format_cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            if autofix:
+                log_warning('Ruff format issues found, auto-formatting...')
+                format_fix_cmd = ['ruff', 'format', file_path]
+                format_fix_result = subprocess.run(format_fix_cmd, capture_output=True, text=True, cwd=project_root)
+                
+                if format_fix_result.returncode == 0:
+                    log_success('Ruff auto-formatted the file!')
+                    autofixes.append('Ruff auto-formatted the file')
+                else:
+                    errors.append(f'Ruff formatting issues in {os.path.basename(file_path)}')
+            else:
+                errors.append(f'Ruff formatting issues in {os.path.basename(file_path)}')
+        else:
+            log_success('Ruff formatting correct')
+            
+    except Exception as e:
+        log_debug(f'Ruff format error: {e}')
+    
+    return len(errors) == 0, errors, autofixes
+
+def check_mypy(file_path: str, project_root: str) -> tuple[bool, list[str]]:
+    """
+    Run mypy type checking.
+    Returns: (passed, errors)
+    """
+    errors = []
+    
+    # Check if mypy is available
+    mypy_path = shutil.which('mypy')
+    if not mypy_path:
+        log_debug('Mypy not found in PATH - skipping type checking')
+        return True, errors
+    
+    log_info('Running Mypy type checking...')
+    
+    cmd = ['mypy', '--pretty', file_path]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+        
+        if result.returncode != 0:
+            errors.append(f'Mypy found type errors in {os.path.basename(file_path)}')
+            if result.stdout:
+                errors.extend(result.stdout.strip().split('\n'))
+            if result.stderr:
+                errors.extend(result.stderr.strip().split('\n'))
+        else:
+            log_success('Mypy type checking passed')
+            
+    except Exception as e:
+        log_debug(f'Mypy error: {e}')
+    
+    return len(errors) == 0, errors
+
+def check_pytest_suggestions(file_path: str, project_root: str):
+    """Suggest running tests if test file exists"""
+    base_name = file_path.replace('.py', '')
+    test_paths = [
+        f'{base_name}_test.py',
+        f'{base_name}_tests.py',
+        f'test_{Path(file_path).name}',
+    ]
+    
+    # Check same directory
+    for test_path in test_paths:
+        if Path(test_path).exists():
+            log_warning(f'💡 Related test found: {os.path.basename(test_path)}')
+            log_warning('   Consider running: pytest')
+            return
+    
+    # Check __tests__ directory
+    tests_dir = Path(file_path).parent / '__tests__'
+    if tests_dir.exists():
+        for test_path in tests_dir.glob(f'test_{Path(file_path).name}'):
+            log_warning(f'💡 Related test found: __tests__/{test_path.name}')
+            log_warning('   Consider running: pytest')
+            return
+    
+    log_warning(f'💡 No test file found for {os.path.basename(file_path)}')
+
+def print_summary(errors: list[str], autofixes: list[str]):
+    """Print summary of errors and autofixes"""
+    if autofixes:
+        print(f'\n{Colors.BLUE}═══ Auto-fixes Applied ═══{Colors.RESET}', file=sys.stderr)
+        for fix in autofixes:
+            print(f'{Colors.GREEN}✨{Colors.RESET} {fix}', file=sys.stderr)
+        print(f'{Colors.GREEN}Automatically fixed {len(autofixes)} issue(s)!{Colors.RESET}', file=sys.stderr)
+    
+    if errors:
+        print(f'\n{Colors.BLUE}═══ Quality Check Summary ═══{Colors.RESET}', file=sys.stderr)
+        for error in errors:
+            print(f'{Colors.RED}❌{Colors.RESET} {error}', file=sys.stderr)
+        print(f'\n{Colors.RED}Found {len(errors)} issue(s) that MUST be fixed!{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.RED}══════════════════════════════════════{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.RED}❌ ALL ISSUES ARE BLOCKING ❌{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.RED}══════════════════════════════════════{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.RED}Fix EVERYTHING above until all checks are ✅ GREEN{Colors.RESET}', file=sys.stderr)
+
+def parse_json_input() -> dict:
+    """Parse JSON input from stdin"""
+    input_data = sys.stdin.read().strip()
+    
+    if not input_data:
+        log_warning('No JSON input provided.')
+        print(f'\n{Colors.YELLOW}👉 Hook executed but no input to process.{Colors.RESET}', file=sys.stderr)
+        sys.exit(0)
+    
+    try:
+        return json.loads(input_data)
+    except json.JSONDecodeError as e:
+        log_error(f'Failed to parse JSON: {e}')
+        sys.exit(1)
+
+def extract_file_path(input_data: dict) -> str | None:
+    """Extract file path from tool input"""
+    tool_input = input_data.get('tool_input', {})
+    return tool_input.get('file_path') or tool_input.get('path')
+
+def main():
+    """Main entry point"""
+    print('', file=sys.stderr)
+    print(f'📦 Python Quality Check - Starting...', file=sys.stderr)
+    print('─────────────────────────────────────', file=sys.stderr)
+    
+    # Parse input
+    input_data = parse_json_input()
+    file_path = extract_file_path(input_data)
+    
+    if not file_path:
+        log_warning('No file path found in JSON input.')
+        print(f'\n{Colors.YELLOW}👉 No file to check - tool may not be file-related.{Colors.RESET}', file=sys.stderr)
+        sys.exit(0)
+    
+    # Check if file exists
+    if not Path(file_path).exists():
+        log_info(f'File does not exist: {file_path}')
+        print(f'\n{Colors.YELLOW}👉 File skipped - doesn\'t exist.{Colors.RESET}', file=sys.stderr)
+        sys.exit(0)
+    
+    # Skip non-Python files
+    if not is_python_file(file_path):
+        log_info(f'Skipping non-Python file: {file_path}')
+        print(f'\n{Colors.GREEN}✅ No checks needed for {os.path.basename(file_path)}{Colors.RESET}', file=sys.stderr)
+        sys.exit(0)
+    
+    # Update header
+    print('', file=sys.stderr)
+    print(f'🔍 Validating: {os.path.basename(file_path)}', file=sys.stderr)
+    print('─────────────────────────────────────', file=sys.stderr)
+    log_info(f'Checking: {file_path}')
+    
+    # Find project root
+    project_root = find_project_root(file_path)
+    log_debug(f'Project root: {project_root}')
+    
+    # Get config from environment
+    autofix = os.environ.get('CLAUDE_HOOKS_AUTOFIX', 'true').lower() == 'true'
+    ruff_enabled = os.environ.get('CLAUDE_HOOKS_RUFF_ENABLED', 'true').lower() != 'false'
+    mypy_enabled = os.environ.get('CLAUDE_HOOKS_MYPY_ENABLED', 'true').lower() != 'false'
+    
+    all_errors = []
+    all_autofixes = []
+    
+    # Run ruff checks
+    if ruff_enabled:
+        ruff_passed, ruff_errors, ruff_autofixes = check_ruff(file_path, project_root, autofix)
+        all_errors.extend(ruff_errors)
+        all_autofixes.extend(ruff_autofixes)
+    
+    # Run mypy checks
+    if mypy_enabled:
+        mypy_passed, mypy_errors = check_mypy(file_path, project_root)
+        all_errors.extend(mypy_errors)
+    
+    # Print summary
+    print_summary(all_errors, all_autofixes)
+    
+    # Exit with appropriate code
+    if all_errors:
+        print(f'\n{Colors.RED}🛑 FAILED - Fix issues in your edited file! 🛑{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.CYAN}💡 CLAUDE.md CHECK:{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.CYAN}  → What CLAUDE.md pattern would have prevented this?{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.YELLOW}📋 NEXT STEPS:{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.YELLOW}  1. Fix the issues listed above{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.YELLOW}  2. The hook will run again automatically{Colors.RESET}', file=sys.stderr)
+        print(f'{Colors.YELLOW}  3. Continue once all checks pass{Colors.RESET}', file=sys.stderr)
+        sys.exit(2)
+    else:
+        print(f'\n{Colors.GREEN}✅ Quality check passed for {os.path.basename(file_path)}{Colors.RESET}', file=sys.stderr)
+        if all_autofixes:
+            print(f'\n{Colors.YELLOW}👉 File quality verified. Auto-fixes applied. Continue with your task.{Colors.RESET}', file=sys.stderr)
+        else:
+            print(f'\n{Colors.YELLOW}👉 File quality verified. Continue with your task.{Colors.RESET}', file=sys.stderr)
+        
+        # Suggest tests
+        check_pytest_suggestions(file_path, project_root)
+        
+        sys.exit(0)
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception as e:
+        log_error(f'Fatal error: {e}')
+        sys.exit(1)

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

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/quality-check.py\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-skills/py-quality-gate/.claude/skills/using-py-quality-gate/SKILL.md

@@ -0,0 +1,112 @@
+# Using PY Quality Gate
+
+**PY Quality Gate** enforces Python code quality with ruff (linting/formatting) and mypy (type checking). Runs automatically on every file edit.
+
+## What It Does
+
+- **Ruff linting** - Fast Python linting (10-100x faster than flake8)
+- **Ruff formatting** - Code formatting (Black-compatible)
+- **Mypy type checking** - Static type validation
+- **Auto-fix** - Automatically fixes issues when possible
+- **Fast feedback** - Runs in <1s for most files
+
+## How It Works
+
+When you edit a Python file:
+
+1. PostToolUse hook fires after Write/Edit
+2. Runs `quality-check.py` with the file path
+3. Checks ruff lint, ruff format, mypy types
+4. Auto-fixes issues if configured
+5. Returns exit code 2 if blocking errors found
+
+## Requirements
+
+- Python 3.8+
+- ruff installed (`pip install ruff`)
+- mypy installed (`pip install mypy`) - optional
+
+## Installation
+
+```bash
+# Install project skill
+xtrm install project py-quality-gate
+
+# Install dependencies
+pip install ruff mypy
+```
+
+## Configuration
+
+Configure via environment variables in your shell or `.env`:
+
+```bash
+# Enable/disable checks
+export CLAUDE_HOOKS_RUFF_ENABLED=true
+export CLAUDE_HOOKS_MYPY_ENABLED=true
+
+# Auto-fix settings
+export CLAUDE_HOOKS_AUTOFIX=true
+
+# Debug mode
+export CLAUDE_HOOKS_DEBUG=true
+```
+
+## Ruff Configuration
+
+Create `pyproject.toml` or `ruff.toml` in your project:
+
+```toml
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4"]
+```
+
+## Mypy Configuration
+
+Create `mypy.ini` or `pyproject.toml`:
+
+```ini
+[mypy]
+python_version = 3.8
+warn_return_any = True
+warn_unused_configs = True
+disallow_untyped_defs = False
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed |
+| 1 | Fatal error (hook crashed) |
+| 2 | Blocking errors found (Claude must fix) |
+
+## Troubleshooting
+
+**"ruff: command not found"**
+- Install: `pip install ruff` or `pipx install ruff`
+
+**"mypy: command not found"**
+- Install: `pip install mypy`
+- Or set `CLAUDE_HOOKS_MYPY_ENABLED=false`
+
+**Hook not running**
+- Verify PostToolUse hook in `.claude/settings.json`
+- Check Python path is correct
+
+## Test Suggestions
+
+The hook automatically suggests running pytest if related test files exist:
+- `test_<filename>.py`
+- `<filename>_test.py`
+- `__tests__/test_<filename>.py`
+
+## See Also
+
+- Full documentation: `.claude/docs/py-quality-gate-readme.md`
+- Ruff docs: https://docs.astral.sh/ruff/
+- Mypy docs: https://mypy.readthedocs.io/

package/project-skills/py-quality-gate/README.md

@@ -0,0 +1,147 @@
+# PY Quality Gate
+
+**Python quality gate** for Claude Code. Runs ruff (linting/formatting) and mypy (type checking) automatically on every file edit.
+
+## What It Does
+
+PY Quality Gate enforces Python code quality standards in real-time:
+
+| Check | Description | Auto-fix |
+|-------|-------------|----------|
+| **Ruff lint** | Code style, best practices, errors | Yes |
+| **Ruff format** | Black-compatible formatting | Yes |
+| **Mypy types** | Static type checking | No |
+
+## Installation
+
+```bash
+# Install project skill
+xtrm install project py-quality-gate
+
+# Install Python dependencies
+pip install ruff mypy
+```
+
+## How It Works
+
+The quality gate runs as a `PostToolUse` hook:
+
+1. You edit a Python file
+2. After the edit completes, the hook fires
+3. `quality-check.py` validates the file
+4. Issues are reported with auto-fix when possible
+5. Exit code 2 blocks if critical errors found
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Enable/disable checks
+export CLAUDE_HOOKS_RUFF_ENABLED=true
+export CLAUDE_HOOKS_MYPY_ENABLED=true
+
+# Auto-fix settings
+export CLAUDE_HOOKS_AUTOFIX=true
+
+# Debug mode
+export CLAUDE_HOOKS_DEBUG=true
+```
+
+### Ruff Configuration
+
+Create `pyproject.toml` in your project:
+
+```toml
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4"]
+ignore = ["E501"]  # Line length (handled by formatter)
+```
+
+### Mypy Configuration
+
+Create `mypy.ini` in your project:
+
+```ini
+[mypy]
+python_version = 3.8
+warn_return_any = True
+warn_unused_configs = True
+disallow_untyped_defs = False
+ignore_missing_imports = True
+```
+
+## Features
+
+### Ruff Linting
+- 10-100x faster than flake8
+- Auto-fixes supported
+- 500+ built-in rules
+- Compatible with Black
+
+### Ruff Formatting
+- Black-compatible formatter
+- Fast and consistent
+- Auto-fixes formatting issues
+
+### Mypy Type Checking
+- Static type validation
+- Catches type errors before runtime
+- Configurable strictness
+
+### Smart Test Suggestions
+- Detects related test files
+- Suggests running pytest
+- Supports multiple test naming conventions
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed |
+| 1 | Fatal error (hook crashed) |
+| 2 | Blocking errors found |
+
+## Troubleshooting
+
+**Ruff not found**
+```bash
+pip install ruff
+# or
+pipx install ruff
+```
+
+**Mypy not found**
+```bash
+pip install mypy
+```
+
+**Hook not running**
+- Verify PostToolUse hook in `.claude/settings.json`
+- Check Python path: `which python3`
+
+**False positives from dependencies**
+- Add to `mypy.ini`: `ignore_missing_imports = True`
+- Add to `pyproject.toml`: exclude patterns
+
+## Quick Commands
+
+```bash
+# Run ruff manually
+ruff check .
+ruff format .
+
+# Run mypy manually
+mypy .
+
+# Run pytest
+pytest
+```
+
+## Reference
+
+Inspired by: https://github.com/bartolli/claude-code-typescript-hooks

package/project-skills/service-skills-set/.claude/git-hooks/doc_reminder.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook: Documentation reminder.
+
+Warns when behavior-changing source files are staged for commit without
+corresponding SSOT documentation updates. Always exits 0 (non-blocking).
+
+Usage: called automatically by .githooks/pre-commit
+"""
+import subprocess
+import sys
+
+# Source paths that indicate behavior-changing code.
+# If any staged file starts with one of these, the reminder fires.
+SOURCE_PATHS = [
+    "scripts/core/",
+    "scripts/data/",
+    "scripts/ingestion/",
+    "mcp_server/",
+    "alembic/",
+]
+
+# Proxy for "agent already ran /documenting".
+# If any of these are also staged, the reminder is suppressed.
+SSOT_PATHS = [
+    ".serena/memories/",
+]
+
+# Colors
+YELLOW = "\033[1;33m"
+BLUE   = "\033[0;34m"
+NC     = "\033[0m"
+
+
+def get_staged_files() -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        capture_output=True, text=True
+    )
+    return [f for f in result.stdout.splitlines() if f]
+
+
+def main() -> None:
+    staged = get_staged_files()
+    if not staged:
+        sys.exit(0)
+
+    source_changed = [f for f in staged if any(f.startswith(p) for p in SOURCE_PATHS)]
+    ssot_changed   = [f for f in staged if any(f.startswith(p) for p in SSOT_PATHS)]
+
+    if source_changed and not ssot_changed:
+        print()
+        print(f"{YELLOW}[doc-hook] ⚠  Source changes staged without SSOT updates.{NC}")
+        print(f"{BLUE}[doc-hook]    If this commit changes behavior or architecture, run /documenting first.{NC}")
+        print(f"[doc-hook]    Changed source paths:")
+        for f in source_changed[:6]:
+            print(f"[doc-hook]      - {f}")
+        if len(source_changed) > 6:
+            print(f"[doc-hook]      ... and {len(source_changed) - 6} more")
+        print(f"[doc-hook]    Commit proceeds — this is a reminder, not a block.")
+        print()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()