xtrm-tools 2.0.0

package/hooks/serena-workflow-reminder.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+import sys
+import os
+
+# Add script directory to path to allow importing shared modules
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+from agent_context import AgentContext
+
+def get_skill_reminder(agent_type):
+    folder = f".{agent_type}"
+    return f"""
+*** MANDATORY SKILL: Using Serena LSP ***
+You are REQUIRED to use semantic tools for all code interactions to ensure safety and token efficiency.
+
+RULES:
+1. READING: NEVER read full code files >300 lines.
+   - START with `get_symbols_overview(depth=1)` to map the file.
+   - READ specific parts with `find_symbol(include_body=True)`.
+2. EDITING: NEVER use the generic `Edit` or `replace` tool on code.
+   - USE `replace_symbol_body` for atomic updates.
+   - USE `insert_after_symbol` / `insert_before_symbol` for additions.
+   - ALWAYS run `find_referencing_symbols` before changing signatures.
+3. SEARCH: USE `search_for_pattern` instead of grep/find.
+
+Ref: ~/{folder}/skills/using-serena-lsp/SKILL.md
+"""
+
+CODE_EXTENSIONS = {'.py', '.ts', '.js', '.jsx', '.tsx', '.go', '.rs', '.java', '.cpp', '.c', '.h'}
+
+def count_lines(filepath):
+    try:
+        with open(filepath, 'r') as f:
+            return sum(1 for _ in f)
+    except:
+        return 0
+
+try:
+    ctx = AgentContext()
+    event = ctx.event
+
+    if event == 'SessionStart':
+        ctx.allow(additional_context=get_skill_reminder(ctx.agent_type))
+
+    elif event in ['PreToolUse', 'BeforeTool']:
+        tool_name = ctx.tool_name
+        
+        # Rule 1: Block Reading Large Code Files
+        if tool_name in ['Read', 'read_file']:
+            file_path = ctx.get_file_path()
+            _, ext = os.path.splitext(file_path)
+            if ext in CODE_EXTENSIONS:
+                loc = count_lines(file_path)
+                if loc > 300:
+                    ctx.block(
+                        reason=f"VIOLATION: Reading full file of {loc} lines is forbidden. Use 'get_symbols_overview' and 'find_symbol' to save tokens.",
+                        system_message="⚠️ Blocked inefficient file read. Use Serena semantic tools."
+                    )
+
+        # Rule 2: Block Generic Edits on Code
+        if tool_name in ['Edit', 'replace']:
+            file_path = ctx.get_file_path()
+            _, ext = os.path.splitext(file_path)
+            if ext in CODE_EXTENSIONS:
+                 ctx.block(
+                    reason=f"VIOLATION: Generic '{tool_name}' is unsafe for code. Use 'replace_symbol_body' or 'insert_after_symbol' for surgical edits.",
+                    system_message="⚠️ Blocked unsafe edit. Use Serena semantic tools."
+                )
+
+    ctx.fail_open()
+
+except Exception as e:
+    # Fail safe: log error but allow operation
+    print(f"Hook Error: {e}", file=sys.stderr)
+    sys.exit(0)

package/hooks/skill-discovery.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+import json
+import sys
+import os
+import re
+
+# Add script directory to path to allow importing shared modules
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+from agent_context import AgentContext
+
+def get_first_sentence(text):
+    if not text:
+        return ""
+    # Remove newlines and extra spaces
+    text = re.sub(r'\s+', ' ', text).strip()
+    # Find the first period followed by a space or end of string
+    match = re.search(r'^(.*?)[.!?](\s|$)', text)
+    if match:
+        return match.group(0).strip()
+    return text
+
+def parse_skill_md(file_path):
+    try:
+        with open(file_path, 'r') as f:
+            content = f.read()
+            
+        # Extract YAML frontmatter
+        match = re.search(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+        if match:
+            frontmatter_raw = match.group(1)
+            # Basic YAML-like parsing using regex to avoid external dependency (PyYAML)
+            name_match = re.search(r'^name:\s*(.*)$', frontmatter_raw, re.MULTILINE)
+            desc_match = re.search(r'^description:\s*(?:>-\s*)?\n?\s*(.*)$', frontmatter_raw, re.MULTILINE | re.DOTALL)
+            
+            name = name_match.group(1).strip() if name_match else os.path.basename(os.path.dirname(file_path))
+            description = ""
+            
+            if desc_match:
+                desc_raw = desc_match.group(1).strip()
+                # If it was a folded scalar, it might have multiple lines
+                if '\n' in desc_raw:
+                    # Capture until next YAML key or end
+                    description = desc_raw.split('\n')[0].strip()
+                else:
+                    description = desc_raw
+            
+            return name, get_first_sentence(description)
+    except Exception as e:
+        print(f"Error parsing {file_path}: {e}", file=sys.stderr)
+    return None
+
+def main():
+    try:
+        ctx = AgentContext()
+        project_dir = os.environ.get('GEMINI_PROJECT_DIR', os.getcwd())
+        skills_root = os.path.join(project_dir, 'skills')
+        
+        if not os.path.exists(skills_root):
+            ctx.fail_open()
+
+        available_skills = []
+        for skill_dir in os.listdir(skills_root):
+            skill_path = os.path.join(skills_root, skill_dir)
+            if os.path.isdir(skill_path):
+                skill_md = os.path.join(skill_path, 'SKILL.md')
+                if os.path.exists(skill_md):
+                    result = parse_skill_md(skill_md)
+                    if result:
+                        name, desc = result
+                        available_skills.append(f"- {name}: {desc}")
+
+        if not available_skills:
+            ctx.fail_open()
+
+        context_msg = "## Available Local Agent Skills\n"
+        context_msg += "The following specialized skills are available in this repository. Use them when appropriate:\n"
+        context_msg += "\n".join(sorted(available_skills))
+        context_msg += "\n\nYou can activate a skill using `activate_skill(name='skill-name')`."
+
+        ctx.allow(
+            system_message="🚀 Loaded available local skills into context.",
+            additional_context=context_msg
+        )
+
+    except Exception as e:
+        print(f"Hook failed: {e}", file=sys.stderr)
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/hooks/skill-suggestion.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+import sys
+import os
+import re
+
+# Add script directory to path to allow importing shared modules
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+from agent_context import AgentContext
+
+# Configuration
+ORCHESTRATION_PATTERNS = [
+    r"review.*(code|security|quality)|code.*(review|audit)",
+    r"security.*(audit|review|scan)",
+    r"implement.*(feature|endpoint|api)|build.*feature",
+    r"(debug|investigate|root.*cause|crash|fix.*unknown)",
+    r"(refactor.*sprint|major.*refactor|migration|technical.*debt)",
+    r"validate.*(commit|staged)|pre.*commit",
+]
+
+CCS_PATTERNS = [
+    r"(fix|correggi|risolvi).*typo",
+    r"(fix|correggi).*spelling",
+    r"(add|aggiungi|crea|create).*test",
+    r"(genera|generate).*(test|unit|case)",
+    r"(estrai|extract).*(function|method|funzione|metodo)",
+    r"rename.*variable|rinomina.*variabile",
+    r"(add|aggiungi).*(doc|docstring|comment)",
+    r"(aggiorna|update).*comment",
+    r"(format|formatta|lint|indenta|indent)",
+    r"(add|aggiungi).*(type|typing|hint)",
+    r"(rimuovi|remove|elimina|delete).*(import|unused)",
+    r"(modifica|modify|cambia|change).*(name|nome)"
+]
+
+P_PATTERNS = [
+    r"analiz|analyz|esamina|studia|review|rivedi",
+    r"implementa|implement|create|crea",
+    r"spiega|explain|descri|describe",
+    r"^(come|how|what|cosa|perch|why)"
+]
+
+EXCLUDE_PATTERNS = [
+    r"archit|design|progett",
+    r"(add|implement|fix|patch).*(security|auth|oauth)|security.*(vuln|fix|patch)",
+    r"bug|debug|investig|indaga",
+    r"performance|ottimizz|optim",
+    r"migra|breaking.*change",
+    r"complex|compless"
+]
+
+CONVERSATIONAL_PATTERNS = [
+    r"^(ciao|hi|hello|hey|buongiorno|buonasera|salve)([!.]|$)",
+    r"^(good morning|good afternoon|good evening)([!.]|$)",
+    r"^(grazie|thanks|thank you|merci|thx)([!.]|$)",
+    r"^(grazie mille|thanks a lot|many thanks)([!.]|$)",
+    r"^(ok|okay|va bene|perfetto|perfect|fine|d'accordo|agreed?)([!.]|$)",
+    r"^(si|sì|yes|no|nope|yeah|yep)([!.]|$)",
+    r"^(arrivederci|addio|ciao|bye|goodbye|see you|ci vediamo)([!.]|$)",
+    r"^come stai\?$|^how are you\?$|^come va\?$",
+    r"^tutto bene\?$|^all good\?$|^everything ok\?$"
+]
+
+def matches(text, patterns):
+    for pattern in patterns:
+        if re.search(pattern, text, re.IGNORECASE):
+            return True
+    return False
+
+try:
+    ctx = AgentContext()
+    prompt = ctx.prompt
+
+    if not prompt:
+        ctx.fail_open()
+
+    ccs_available = not bool(os.environ.get('CLAUDECODE'))
+    ccs_hint = "CCS backend" if ccs_available else "Gemini or Qwen directly (CCS unavailable inside Claude Code)"
+
+    # 1. Check Exclusions
+    if matches(prompt, EXCLUDE_PATTERNS) or matches(prompt, CONVERSATIONAL_PATTERNS):
+        ctx.fail_open()
+
+    agent_name = ctx.agent_type.capitalize()
+
+    # 2. Check Explicit Delegation
+    if re.search(r'delegate', prompt, re.IGNORECASE):
+        ctx.allow(system_message=f"💡 {agent_name} Internal Reminder: User mentioned 'delegate'. Consider using the /delegating skill to offload this task.")
+
+    # 3. Check CCS Delegation (Simple Tasks)
+    if matches(prompt, CCS_PATTERNS):
+        ctx.allow(system_message=f"💡 {agent_name} Internal Reminder: This appears to be a simple, deterministic task (typo/test/format/doc). Consider using the /delegating skill ({ccs_hint}) for cost-optimized execution.")
+
+    # 4. Check Orchestration (Complex Tasks)
+    elif matches(prompt, ORCHESTRATION_PATTERNS) and not matches(prompt, EXCLUDE_PATTERNS):
+        ctx.allow(system_message=f"💡 {agent_name} Internal Reminder: This looks like a multi-agent task (review/implement/debug). Consider using the /delegating skill (Gemini+Qwen orchestration) instead of handling in main session.")
+
+    # 5. Check Prompt Improving (/p)
+    word_count = len(prompt.split())
+    is_vague = matches(prompt, P_PATTERNS)
+    
+    # Heuristic for very short command-like prompts
+    if word_count < 6 and not is_vague:
+        if matches(prompt, [r"(creare|create|fare|do|aggiungere|add|modificare|modify|controllare|check|verificare|verify|testare|test)"]):
+            is_vague = True
+
+    if is_vague:
+        ctx.allow(system_message=f"💡 {agent_name} Internal Reminder: This prompt appears vague or could benefit from structure. Consider using the /prompt-improving skill to add XML structure, examples, and thinking space before proceeding.")
+
+    ctx.fail_open()
+
+except Exception:
+    sys.exit(0)

package/hooks/test_agent_context.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Test AgentContext hook output formatting"""
+import json
+import sys
+from io import StringIO
+
+# Mock sys.stdin and sys.exit for testing
+class MockExit(Exception):
+    pass
+
+def test_hook_output(event_name, method_name, *args, **kwargs):
+    """Test a specific hook method and return its JSON output"""
+    import agent_context
+
+    # Prepare mock input
+    mock_input = {
+        "hook_event_name": event_name,
+        "tool_name": "Read",
+        "tool_input": {"file_path": "/test/file.txt"}
+    }
+
+    # Mock stdin
+    original_stdin = sys.stdin
+    original_exit = sys.exit
+    sys.stdin = StringIO(json.dumps(mock_input))
+
+    # Capture stdout
+    output_buffer = StringIO()
+    original_stdout = sys.stdout
+    sys.stdout = output_buffer
+
+    try:
+        ctx = agent_context.AgentContext()
+
+        # Call the method
+        method = getattr(ctx, method_name)
+        try:
+            method(*args, **kwargs)
+        except SystemExit:
+            pass  # Expected
+
+        # Get output
+        output = output_buffer.getvalue().strip()
+        return json.loads(output) if output else {}
+
+    finally:
+        sys.stdin = original_stdin
+        sys.stdout = original_stdout
+        sys.exit = original_exit
+
+def main():
+    print("Testing AgentContext hook output formats...\n")
+
+    # Test 1: PreToolUse allow() with systemMessage
+    print("Test 1: PreToolUse allow() with systemMessage")
+    output = test_hook_output("PreToolUse", "allow", system_message="Test message")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert "systemMessage" in output, "Should have systemMessage"
+    assert output["hookSpecificOutput"]["hookEventName"] == "PreToolUse"
+    assert output["hookSpecificOutput"]["permissionDecision"] == "allow"
+    assert "decision" not in output, "Should NOT have top-level 'decision'"
+    print("✓ PASS\n")
+
+    # Test 2: PreToolUse allow() with additionalContext
+    print("Test 2: PreToolUse allow() with additionalContext")
+    output = test_hook_output("PreToolUse", "allow", additional_context="Extra context")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert output["hookSpecificOutput"]["permissionDecision"] == "allow"
+    assert output["hookSpecificOutput"]["additionalContext"] == "Extra context"
+    print("✓ PASS\n")
+
+    # Test 3: UserPromptSubmit allow() with systemMessage (no permissionDecision)
+    print("Test 3: UserPromptSubmit allow() with systemMessage")
+    output = test_hook_output("UserPromptSubmit", "allow", system_message="Reminder")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert "systemMessage" in output
+    assert "permissionDecision" not in output.get("hookSpecificOutput", {}), \
+        "UserPromptSubmit should NOT have permissionDecision"
+    print("✓ PASS\n")
+
+    # Test 4: UserPromptSubmit allow() with additionalContext
+    print("Test 4: UserPromptSubmit allow() with additionalContext")
+    output = test_hook_output("UserPromptSubmit", "allow", additional_context="Context")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert output["hookSpecificOutput"]["additionalContext"] == "Context"
+    assert "permissionDecision" not in output["hookSpecificOutput"]
+    print("✓ PASS\n")
+
+    # Test 5: PreToolUse block()
+    print("Test 5: PreToolUse block()")
+    output = test_hook_output("PreToolUse", "block", "Dangerous operation")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert output["hookSpecificOutput"]["permissionDecisionReason"] == "Dangerous operation"
+    assert "decision" not in output, "Should NOT have top-level 'decision'"
+    print("✓ PASS\n")
+
+    # Test 6: UserPromptSubmit block() (should use continue: false)
+    print("Test 6: UserPromptSubmit block()")
+    output = test_hook_output("UserPromptSubmit", "block", "Blocked")
+    print(f"Output: {json.dumps(output, indent=2)}")
+    assert output.get("continue") == False, "Should have continue: false"
+    assert output.get("stopReason") == "Blocked"
+    assert "permissionDecision" not in output.get("hookSpecificOutput", {})
+    print("✓ PASS\n")
+
+    print("=" * 50)
+    print("All tests passed! ✓")
+    print("=" * 50)
+
+if __name__ == "__main__":
+    main()

package/hooks/type-safety-enforcement.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+import sys
+import os
+import subprocess
+
+# Add script directory to path to allow importing shared modules
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+from agent_context import AgentContext
+
+# Configuration
+STRICT_DIRS = ["mcp_server"]
+WARN_DIRS = ["scripts"]
+PROJECT_ROOT = os.environ.get('GEMINI_PROJECT_DIR', os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd()))
+VENV_PATH = os.path.join(PROJECT_ROOT, ".venv")
+
+# Colors
+RED = '\033[0;31m'
+YELLOW = '\033[1;33m'
+GREEN = '\033[0;32m'
+CYAN = '\033[0;36m'
+NC = '\033[0m'
+
+def is_strict_path(file_path):
+    rel_path = os.path.relpath(file_path, PROJECT_ROOT)
+    for d in STRICT_DIRS:
+        if rel_path.startswith(d):
+            return True
+    return False
+
+def run_mypy(target, is_strict):
+    if not os.path.exists(os.path.join(VENV_PATH, "bin", "activate")):
+        print(f"{YELLOW}⚠️  Venv not found at {VENV_PATH}, skipping check{NC}")
+        return True
+
+    cmd = f"source {VENV_PATH}/bin/activate && python -m mypy {target} --explicit-package-bases"
+    
+    try:
+        result = subprocess.run(cmd, shell=True, executable="/bin/bash", capture_output=True, text=True)
+        
+        if result.returncode != 0:
+            if is_strict:
+                print(f"{RED}❌ MYPY FAILED (STRICT MODE){NC}", file=sys.stderr)
+                print(result.stdout, file=sys.stderr)
+                print(f"\n{RED}🚫 COMMIT BLOCKED: Fix type errors in {target}{NC}", file=sys.stderr)
+                print(f"{CYAN}💡 Run: source .venv/bin/activate && python -m mypy {target}{NC}", file=sys.stderr)
+                return False
+            else:
+                print(f"{YELLOW}⚠️  MYPY WARNING (LENIENT MODE){NC}", file=sys.stderr)
+                print("\n".join(result.stdout.splitlines()[:20]), file=sys.stderr)
+                print(f"\n{YELLOW}⚡ Type errors exist in {target} (commit allowed){NC}", file=sys.stderr)
+                return True
+        else:
+            print(f"{GREEN}✅ MYPY PASSED: {target}{NC}", file=sys.stderr)
+            return True
+
+    except Exception as e:
+        print(f"Error running mypy: {e}", file=sys.stderr)
+        return True # Fail open
+
+try:
+    ctx = AgentContext()
+
+    # 1. Check Git Commits (Shell tools)
+    if ctx.is_shell_tool():
+        command = ctx.get_command()
+        if 'git commit' in command:
+            print(f"{CYAN}🔍 TYPE SAFETY CHECK: Validating staged Python files...{NC}", file=sys.stderr)
+            
+            # Get staged files
+            try:
+                staged = subprocess.check_output(
+                    "git diff --cached --name-only --diff-filter=ACM | grep '\.py$'", 
+                    shell=True, cwd=PROJECT_ROOT
+                ).decode().strip().splitlines()
+            except subprocess.CalledProcessError:
+                staged = []
+
+            if not staged:
+                print(f"{GREEN}✅ No Python files staged{NC}", file=sys.stderr)
+                ctx.allow()
+
+            failed = False
+            
+            # Check individual files
+            for f in staged:
+                full_path = os.path.join(PROJECT_ROOT, f)
+                if is_strict_path(full_path):
+                    if not run_mypy(full_path, True):
+                        failed = True
+
+            # If failed, block the tool
+            if failed:
+                ctx.block(reason="Type safety violations in strict directory.")
+            
+            ctx.allow()
+
+    # 2. Check Edits (Write/Edit tools)
+    elif ctx.is_write_tool() or ctx.is_edit_tool():
+        file_path = ctx.get_file_path()
+        if file_path.endswith('.py') and is_strict_path(file_path):
+            ctx.allow(system_message=f"""{YELLOW}⚠️  EDITING STRICT TYPE-SAFE FILE{NC}
+This file is in a STRICT zone ({', '.join(STRICT_DIRS)}).
+Any type errors will BLOCK commits.
+""")
+
+except Exception:
+    sys.exit(0)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "xtrm-tools",
+  "version": "2.0.0",
+  "description": "Claude Code tools installer (skills, hooks, MCP servers)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "xtrm": "./cli/dist/index.cjs"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "cli/dist",
+    "cli/package.json",
+    "config",
+    "hooks",
+    "skills",
+    "project-skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jaggerxtrm/xtrm-tools.git"
+  },
+  "homepage": "https://github.com/Jaggerxtrm/xtrm-tools#readme",
+  "bugs": {
+    "url": "https://github.com/Jaggerxtrm/xtrm-tools/issues"
+  },
+  "scripts": {
+    "build": "npm run build --prefix cli",
+    "start": "node cli/dist/index.cjs",
+    "lint": "echo 'No linting configured'",
+    "test": "echo 'No tests configured'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "comment-json": "^4.2.3",
+    "conf": "^12.0.0",
+    "dotenv": "^17.3.1",
+    "fs-extra": "^11.2.0",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  }
+}