xtrm-tools 0.7.3 → 0.7.7

package/.xtrm/skills/default/hook-development/scripts/test-hook.sh

@@ -0,0 +1,252 @@
+#!/bin/bash
+# Hook Testing Helper
+# Tests a hook with sample input and shows output
+
+set -euo pipefail
+
+# Usage
+show_usage() {
+  echo "Usage: $0 [options] <hook-script> <test-input.json>"
+  echo ""
+  echo "Options:"
+  echo "  -h, --help      Show this help message"
+  echo "  -v, --verbose   Show detailed execution information"
+  echo "  -t, --timeout N Set timeout in seconds (default: 60)"
+  echo ""
+  echo "Examples:"
+  echo "  $0 validate-bash.sh test-input.json"
+  echo "  $0 -v -t 30 validate-write.sh write-input.json"
+  echo ""
+  echo "Creates sample test input with:"
+  echo "  $0 --create-sample <event-type>"
+  exit 0
+}
+
+# Create sample input
+create_sample() {
+  event_type="$1"
+
+  case "$event_type" in
+    PreToolUse)
+      cat <<'EOF'
+{
+  "session_id": "test-session",
+  "transcript_path": "/tmp/transcript.txt",
+  "cwd": "/tmp/test-project",
+  "permission_mode": "ask",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/tmp/test.txt",
+    "content": "Test content"
+  }
+}
+EOF
+      ;;
+    PostToolUse)
+      cat <<'EOF'
+{
+  "session_id": "test-session",
+  "transcript_path": "/tmp/transcript.txt",
+  "cwd": "/tmp/test-project",
+  "permission_mode": "ask",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Bash",
+  "tool_result": "Command executed successfully"
+}
+EOF
+      ;;
+    Stop|SubagentStop)
+      cat <<'EOF'
+{
+  "session_id": "test-session",
+  "transcript_path": "/tmp/transcript.txt",
+  "cwd": "/tmp/test-project",
+  "permission_mode": "ask",
+  "hook_event_name": "Stop",
+  "reason": "Task appears complete"
+}
+EOF
+      ;;
+    UserPromptSubmit)
+      cat <<'EOF'
+{
+  "session_id": "test-session",
+  "transcript_path": "/tmp/transcript.txt",
+  "cwd": "/tmp/test-project",
+  "permission_mode": "ask",
+  "hook_event_name": "UserPromptSubmit",
+  "user_prompt": "Test user prompt"
+}
+EOF
+      ;;
+    SessionStart|SessionEnd)
+      cat <<'EOF'
+{
+  "session_id": "test-session",
+  "transcript_path": "/tmp/transcript.txt",
+  "cwd": "/tmp/test-project",
+  "permission_mode": "ask",
+  "hook_event_name": "SessionStart"
+}
+EOF
+      ;;
+    *)
+      echo "Unknown event type: $event_type"
+      echo "Valid types: PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit, SessionStart, SessionEnd"
+      exit 1
+      ;;
+  esac
+}
+
+# Parse arguments
+VERBOSE=false
+TIMEOUT=60
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help)
+      show_usage
+      ;;
+    -v|--verbose)
+      VERBOSE=true
+      shift
+      ;;
+    -t|--timeout)
+      TIMEOUT="$2"
+      shift 2
+      ;;
+    --create-sample)
+      create_sample "$2"
+      exit 0
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ $# -ne 2 ]; then
+  echo "Error: Missing required arguments"
+  echo ""
+  show_usage
+fi
+
+HOOK_SCRIPT="$1"
+TEST_INPUT="$2"
+
+# Validate inputs
+if [ ! -f "$HOOK_SCRIPT" ]; then
+  echo "❌ Error: Hook script not found: $HOOK_SCRIPT"
+  exit 1
+fi
+
+if [ ! -x "$HOOK_SCRIPT" ]; then
+  echo "⚠️  Warning: Hook script is not executable. Attempting to run with bash..."
+  HOOK_SCRIPT="bash $HOOK_SCRIPT"
+fi
+
+if [ ! -f "$TEST_INPUT" ]; then
+  echo "❌ Error: Test input not found: $TEST_INPUT"
+  exit 1
+fi
+
+# Validate test input JSON
+if ! jq empty "$TEST_INPUT" 2>/dev/null; then
+  echo "❌ Error: Test input is not valid JSON"
+  exit 1
+fi
+
+echo "🧪 Testing hook: $HOOK_SCRIPT"
+echo "📥 Input: $TEST_INPUT"
+echo ""
+
+if [ "$VERBOSE" = true ]; then
+  echo "Input JSON:"
+  jq . "$TEST_INPUT"
+  echo ""
+fi
+
+# Set up environment
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-/tmp/test-project}"
+export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(pwd)}"
+export CLAUDE_ENV_FILE="${CLAUDE_ENV_FILE:-/tmp/test-env-$$}"
+
+if [ "$VERBOSE" = true ]; then
+  echo "Environment:"
+  echo "  CLAUDE_PROJECT_DIR=$CLAUDE_PROJECT_DIR"
+  echo "  CLAUDE_PLUGIN_ROOT=$CLAUDE_PLUGIN_ROOT"
+  echo "  CLAUDE_ENV_FILE=$CLAUDE_ENV_FILE"
+  echo ""
+fi
+
+# Run the hook
+echo "▶️  Running hook (timeout: ${TIMEOUT}s)..."
+echo ""
+
+start_time=$(date +%s)
+
+set +e
+output=$(timeout "$TIMEOUT" bash -c "cat '$TEST_INPUT' | $HOOK_SCRIPT" 2>&1)
+exit_code=$?
+set -e
+
+end_time=$(date +%s)
+duration=$((end_time - start_time))
+
+# Analyze results
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Results:"
+echo ""
+echo "Exit Code: $exit_code"
+echo "Duration: ${duration}s"
+echo ""
+
+case $exit_code in
+  0)
+    echo "✅ Hook approved/succeeded"
+    ;;
+  2)
+    echo "🚫 Hook blocked/denied"
+    ;;
+  124)
+    echo "⏱️  Hook timed out after ${TIMEOUT}s"
+    ;;
+  *)
+    echo "⚠️  Hook returned unexpected exit code: $exit_code"
+    ;;
+esac
+
+echo ""
+echo "Output:"
+if [ -n "$output" ]; then
+  echo "$output"
+  echo ""
+
+  # Try to parse as JSON
+  if echo "$output" | jq empty 2>/dev/null; then
+    echo "Parsed JSON output:"
+    echo "$output" | jq .
+  fi
+else
+  echo "(no output)"
+fi
+
+# Check for environment file
+if [ -f "$CLAUDE_ENV_FILE" ]; then
+  echo ""
+  echo "Environment file created:"
+  cat "$CLAUDE_ENV_FILE"
+  rm -f "$CLAUDE_ENV_FILE"
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ $exit_code -eq 0 ] || [ $exit_code -eq 2 ]; then
+  echo "✅ Test completed successfully"
+  exit 0
+else
+  echo "❌ Test failed"
+  exit 1
+fi

package/.xtrm/skills/default/hook-development/scripts/validate-hook-schema.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# Hook Schema Validator
+# Validates hooks.json structure and checks for common issues
+
+set -euo pipefail
+
+# Usage
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <path/to/hooks.json>"
+  echo ""
+  echo "Validates hook configuration file for:"
+  echo "  - Valid JSON syntax"
+  echo "  - Required fields"
+  echo "  - Hook type validity"
+  echo "  - Matcher patterns"
+  echo "  - Timeout ranges"
+  exit 1
+fi
+
+HOOKS_FILE="$1"
+
+if [ ! -f "$HOOKS_FILE" ]; then
+  echo "❌ Error: File not found: $HOOKS_FILE"
+  exit 1
+fi
+
+echo "🔍 Validating hooks configuration: $HOOKS_FILE"
+echo ""
+
+# Check 1: Valid JSON
+echo "Checking JSON syntax..."
+if ! jq empty "$HOOKS_FILE" 2>/dev/null; then
+  echo "❌ Invalid JSON syntax"
+  exit 1
+fi
+echo "✅ Valid JSON"
+
+# Check 2: Root structure
+echo ""
+echo "Checking root structure..."
+VALID_EVENTS=("PreToolUse" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
+
+for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
+  found=false
+  for valid_event in "${VALID_EVENTS[@]}"; do
+    if [ "$event" = "$valid_event" ]; then
+      found=true
+      break
+    fi
+  done
+
+  if [ "$found" = false ]; then
+    echo "⚠️  Unknown event type: $event"
+  fi
+done
+echo "✅ Root structure valid"
+
+# Check 3: Validate each hook
+echo ""
+echo "Validating individual hooks..."
+
+error_count=0
+warning_count=0
+
+for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
+  hook_count=$(jq -r ".\"$event\" | length" "$HOOKS_FILE")
+
+  for ((i=0; i<hook_count; i++)); do
+    # Check matcher exists
+    matcher=$(jq -r ".\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
+    if [ -z "$matcher" ]; then
+      echo "❌ $event[$i]: Missing 'matcher' field"
+      ((error_count++))
+      continue
+    fi
+
+    # Check hooks array exists
+    hooks=$(jq -r ".\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
+    if [ -z "$hooks" ] || [ "$hooks" = "null" ]; then
+      echo "❌ $event[$i]: Missing 'hooks' array"
+      ((error_count++))
+      continue
+    fi
+
+    # Validate each hook in the array
+    hook_array_count=$(jq -r ".\"$event\"[$i].hooks | length" "$HOOKS_FILE")
+
+    for ((j=0; j<hook_array_count; j++)); do
+      hook_type=$(jq -r ".\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
+
+      if [ -z "$hook_type" ]; then
+        echo "❌ $event[$i].hooks[$j]: Missing 'type' field"
+        ((error_count++))
+        continue
+      fi
+
+      if [ "$hook_type" != "command" ] && [ "$hook_type" != "prompt" ]; then
+        echo "❌ $event[$i].hooks[$j]: Invalid type '$hook_type' (must be 'command' or 'prompt')"
+        ((error_count++))
+        continue
+      fi
+
+      # Check type-specific fields
+      if [ "$hook_type" = "command" ]; then
+        command=$(jq -r ".\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
+        if [ -z "$command" ]; then
+          echo "❌ $event[$i].hooks[$j]: Command hooks must have 'command' field"
+          ((error_count++))
+        else
+          # Check for hardcoded paths
+          if [[ "$command" == /* ]] && [[ "$command" != *'${CLAUDE_PLUGIN_ROOT}'* ]]; then
+            echo "⚠️  $event[$i].hooks[$j]: Hardcoded absolute path detected. Consider using \${CLAUDE_PLUGIN_ROOT}"
+            ((warning_count++))
+          fi
+        fi
+      elif [ "$hook_type" = "prompt" ]; then
+        prompt=$(jq -r ".\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
+        if [ -z "$prompt" ]; then
+          echo "❌ $event[$i].hooks[$j]: Prompt hooks must have 'prompt' field"
+          ((error_count++))
+        fi
+
+        # Check if prompt-based hooks are used on supported events
+        if [ "$event" != "Stop" ] && [ "$event" != "SubagentStop" ] && [ "$event" != "UserPromptSubmit" ] && [ "$event" != "PreToolUse" ]; then
+          echo "⚠️  $event[$i].hooks[$j]: Prompt hooks may not be fully supported on $event (best on Stop, SubagentStop, UserPromptSubmit, PreToolUse)"
+          ((warning_count++))
+        fi
+      fi
+
+      # Check timeout
+      timeout=$(jq -r ".\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
+      if [ -n "$timeout" ] && [ "$timeout" != "null" ]; then
+        if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+          echo "❌ $event[$i].hooks[$j]: Timeout must be a number"
+          ((error_count++))
+        elif [ "$timeout" -gt 600 ]; then
+          echo "⚠️  $event[$i].hooks[$j]: Timeout $timeout seconds is very high (max 600s)"
+          ((warning_count++))
+        elif [ "$timeout" -lt 5 ]; then
+          echo "⚠️  $event[$i].hooks[$j]: Timeout $timeout seconds is very low"
+          ((warning_count++))
+        fi
+      fi
+    done
+  done
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+if [ $error_count -eq 0 ] && [ $warning_count -eq 0 ]; then
+  echo "✅ All checks passed!"
+  exit 0
+elif [ $error_count -eq 0 ]; then
+  echo "⚠️  Validation passed with $warning_count warning(s)"
+  exit 0
+else
+  echo "❌ Validation failed with $error_count error(s) and $warning_count warning(s)"
+  exit 1
+fi

package/.xtrm/skills/default/init-session/SKILL.md

@@ -0,0 +1,69 @@
+# Session Start
+
+Bootstrap context for a new session. Read the latest session report, load relevant memories, and orient to current project state.
+
+## When to Use
+
+**Trigger:** Start of any new session, after `/compact`, or when the user says "init", "start session", "what's the context?", "catch me up".
+
+## Execution Flow
+
+### 1. Read the latest session report
+
+```bash
+ls -t .xtrm/reports/ | head -1
+```
+
+Read the most recent report file. Pay attention to:
+- **Summary** — what was done, what state the project is in
+- **Open Issues with Context** — what's ready for next session
+- **Suggested Next Priority** — recommended work order
+- **Problems** — recurring issues to watch for
+
+Do NOT read the entire report into your response. Internalize it and give a concise 3-5 line summary to the user.
+
+### 2. Load relevant memories
+
+```bash
+bd memories <keyword>    # Search by topic
+bd recall <key>          # Get specific memory
+```
+
+Search for memories relevant to the user's likely task:
+- `bd memories specialist` — specialist workflow patterns
+- `bd memories bug` — known gotchas and fixes
+- `bd memories worktree` — worktree workflow notes
+- `bd memories executor` — executor behavior patterns
+
+If the user mentioned a topic, search for that specifically. Otherwise, load the 3-5 most recent/relevant memories.
+
+### 3. Check active work
+
+```bash
+bd list --status=in_progress   # Any unclosed claims from prior sessions
+bd ready                       # What's available to work on
+bd stats                       # Project health overview
+```
+
+If there are unclosed in_progress issues from prior sessions, flag them — they may be stale claims that need closing or represent interrupted work.
+
+### 4. Report to user
+
+Give a concise briefing:
+- What was done last session (from report)
+- Any open claims or interrupted work
+- Top 3 suggested next tasks (from report + `bd ready`)
+- Any relevant memories that affect today's work
+
+Keep it under 15 lines. The user wants orientation, not a novel.
+
+## Memory Protocol
+
+Throughout the session, use `bd remember` and `bd memories` for persistent knowledge:
+
+- **Before investigating a topic**: `bd memories <topic>` — check if prior sessions already discovered this
+- **After learning something non-obvious**: `bd remember "<insight>"` — save for future sessions
+- **Before fixing a bug**: `bd memories <error keyword>` — check if fix is already known
+- **After fixing a bug**: `bd remember "<what broke and why>"` — prevent rediscovery
+
+The memory system is the project's institutional knowledge. Use it aggressively — a redundant memory costs nothing, a missing one costs a full rediscovery cycle.