moai-adk 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/TROUBLESHOOTING.md

@@ -1,471 +0,0 @@
-# Alfred Hooks Troubleshooting Guide
-
-This guide helps you diagnose and resolve common issues with MoAI-ADK's Alfred hooks system.
-
-## Quick Diagnosis
-
-Run this command to verify hook integrity:
-
-```bash
-# Test hook execution
-echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-```
-
-**Expected output**: JSON with `"continue": true` and a system message
-**If failed**: See error-specific sections below
-
----
-
-## Error 1: "Hook not found"
-
-### Symptom
-```
-error: Failed to spawn: `.claude/hooks/alfred/alfred_hooks.py`
-  Caused by: No such file or directory (os error 2)
-```
-
-### Root Causes
-1. **Project initialized with older MoAI-ADK version** (before hooks system)
-2. **Hooks directory deleted accidentally**
-3. **Template copy failed during `/alfred:0-project` initialization**
-4. **Working directory mismatch** (Claude Code started from wrong directory)
-
-### Solutions
-
-#### Solution 1: Update Project (Recommended)
-```bash
-# Re-run project initialization to restore hooks
-/alfred:0-project
-```
-
-#### Solution 2: Manual Template Copy
-```bash
-# Copy hooks from MoAI-ADK installation
-python3 -c "
-import moai_adk
-from pathlib import Path
-import shutil
-
-template_dir = Path(moai_adk.__file__).parent / 'templates' / '.claude' / 'hooks' / 'alfred'
-target_dir = Path('.claude/hooks/alfred')
-target_dir.parent.mkdir(parents=True, exist_ok=True)
-shutil.copytree(template_dir, target_dir, dirs_exist_ok=True)
-print(f'Copied hooks to {target_dir}')
-"
-```
-
-#### Solution 3: Verify File Existence
-```bash
-# Check all required files exist
-ls -la .claude/hooks/alfred/
-ls -la .claude/hooks/alfred/handlers/
-ls -la .claude/hooks/alfred/core/
-
-# Expected files:
-# .claude/hooks/alfred/alfred_hooks.py
-# .claude/hooks/alfred/handlers/__init__.py
-# .claude/hooks/alfred/handlers/session.py
-# .claude/hooks/alfred/handlers/user.py
-# .claude/hooks/alfred/handlers/tool.py
-# .claude/hooks/alfred/handlers/notification.py
-# .claude/hooks/alfred/core/__init__.py
-# .claude/hooks/alfred/core/project.py
-# .claude/hooks/alfred/core/context.py
-# .claude/hooks/alfred/core/checkpoint.py
-```
-
----
-
-## Error 2: "Import error: No module named 'handlers'"
-
-### Symptom
-```python
-ImportError: No module named 'handlers'
-ModuleNotFoundError: No module named 'core'
-```
-
-### Root Causes
-1. **Corrupted hooks directory** (partial copy, missing `__init__.py`)
-2. **Python path resolution issue** (sys.path manipulation failed)
-3. **Missing handler/core modules**
-
-### Solutions
-
-#### Solution 1: Verify Module Structure
-```bash
-# Check all __init__.py files exist
-find .claude/hooks/alfred -name "__init__.py"
-
-# Expected output:
-# .claude/hooks/alfred/handlers/__init__.py
-# .claude/hooks/alfred/core/__init__.py
-```
-
-#### Solution 2: Test Imports Manually
-```bash
-cd .claude/hooks/alfred && python3 -c "
-import sys
-from pathlib import Path
-sys.path.insert(0, str(Path.cwd()))
-
-from handlers import handle_session_start
-from core import HookResult
-print('✅ Imports successful')
-"
-```
-
-#### Solution 3: Re-initialize Hooks
-```bash
-# Force re-copy from template
-/alfred:0-project update --force
-```
-
----
-
-## Error 3: "Hook execution timeout"
-
-### Symptom
-```
-Hook timeout after 5 seconds
-⚠️ Hook execution timeout - continuing without session info
-```
-
-### Root Causes
-1. **Slow Git operations** (large repository, many branches)
-2. **Slow file I/O** (network drive, slow disk)
-3. **Heavy SPEC counting** (many `.moai/specs/` directories)
-4. **Subprocess hang** (rare, usually indicates system issue)
-
-### Solutions
-
-#### Solution 1: Identify Slow Operations
-```bash
-# Time hook execution
-time echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-
-# If >5 seconds, check:
-# - Git repository size: du -sh .git
-# - SPEC count: find .moai/specs -type d -name "SPEC-*" | wc -l
-# - Disk I/O: iotop (Linux) or sudo fs_usage (macOS)
-```
-
-#### Solution 2: Increase Timeout (Temporary Workaround)
-```bash
-# Edit alfred_hooks.py line 129
-# Change: signal.alarm(5)  # 5 seconds
-# To:     signal.alarm(10)  # 10 seconds
-
-# Location: .claude/hooks/alfred/alfred_hooks.py
-```
-
-**Note**: This is a workaround. File an issue if hooks consistently timeout.
-
-#### Solution 3: Disable Slow Features (Not Currently Supported)
-**Future enhancement**: Add `.moai/config.json` option to disable expensive checks:
-```json
-{
-  "hooks": {
-    "session_start": {
-      "skip_git_info": false,
-      "skip_spec_count": false
-    }
-  }
-}
-```
-
----
-
-## Error 4: "JSON parse error"
-
-### Symptom
-```
-JSON parse error: Expecting value: line 1 column 1 (char 0)
-```
-
-### Root Causes
-1. **Empty stdin** (Claude Code passed no payload)
-2. **Invalid JSON format** (malformed payload)
-3. **Encoding issues** (non-UTF-8 characters)
-
-### Solutions
-
-#### Solution 1: Test with Minimal Payload
-```bash
-# Empty payload (should work - returns empty dict)
-echo '' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-
-# Minimal valid payload
-echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-```
-
-#### Solution 2: Check Claude Code Version
-```bash
-# Ensure Claude Code is up-to-date
-claude-code --version
-
-# Update if needed
-pip install --upgrade claude-code
-```
-
----
-
-## Error 5: "Permission denied"
-
-### Symptom
-```
-PermissionError: [Errno 13] Permission denied: '.claude/hooks/alfred/alfred_hooks.py'
-```
-
-### Root Causes
-1. **File not executable** (missing execute permission)
-2. **Directory permissions** (parent directory not readable)
-3. **Ownership issues** (file owned by different user)
-
-### Solutions
-
-#### Solution 1: Fix Permissions
-```bash
-# Make executable
-chmod +x .claude/hooks/alfred/alfred_hooks.py
-
-# Fix directory permissions
-chmod -R u+rX .claude/hooks/alfred/
-```
-
-#### Solution 2: Check Ownership
-```bash
-# Check file owner
-ls -l .claude/hooks/alfred/alfred_hooks.py
-
-# Change owner if needed (replace USER with your username)
-sudo chown -R USER:USER .claude/hooks/alfred/
-```
-
----
-
-## Error 6: "UV environment issues"
-
-### Symptom
-```
-uv: command not found
-error: failed to create virtualenv
-```
-
-### Root Causes
-1. **UV not installed**
-2. **UV not in PATH**
-3. **Virtual environment corruption**
-
-### Solutions
-
-#### Solution 1: Install/Update UV
-```bash
-# Install UV
-pip install uv
-
-# Or update
-pip install --upgrade uv
-
-# Verify
-uv --version
-```
-
-#### Solution 2: Check PATH
-```bash
-# Find UV installation
-which uv
-
-# Add to PATH if needed
-export PATH="$HOME/.local/bin:$PATH"
-```
-
-#### Solution 3: Rebuild Virtual Environment
-```bash
-# Remove existing environment
-rm -rf .venv
-
-# Recreate
-uv venv
-uv sync
-```
-
----
-
-## Platform-Specific Issues
-
-### macOS: SIGALRM Not Working
-**Note**: SIGALRM is fully supported on macOS. If timeout protection isn't working:
-
-```bash
-# Verify Python version (3.8+ required)
-python3 --version
-
-# Test signal module
-python3 -c "import signal; print(hasattr(signal, 'SIGALRM'))"
-# Expected: True
-```
-
-### Windows: SIGALRM Not Available
-**Known Limitation**: SIGALRM is not available on Windows.
-
-**Workaround**: Hooks must complete in <2 seconds (no timeout protection).
-
-**Alternative**: Use threading-based timeout (future enhancement):
-```python
-import threading
-
-def run_with_timeout(func, timeout=5):
-    result = []
-    def wrapper():
-        result.append(func())
-
-    thread = threading.Thread(target=wrapper)
-    thread.start()
-    thread.join(timeout)
-
-    if thread.is_alive():
-        raise TimeoutError("Function timeout")
-    return result[0]
-```
-
-### Linux: Signal Conflicts
-If other tools use SIGALRM (rare), hooks may conflict.
-
-**Diagnosis**:
-```bash
-# Check for signal handlers
-python3 -c "
-import signal
-print('Current SIGALRM handler:', signal.getsignal(signal.SIGALRM))
-"
-```
-
----
-
-## Advanced Debugging
-
-### Enable Hook Logging
-```bash
-# Create custom hook wrapper with logging
-cat > .claude/hooks/alfred/debug_hooks.sh <<'EOF'
-#!/bin/bash
-EVENT=$1
-INPUT=$(cat)
-
-echo "[$(date)] Event: $EVENT" >> /tmp/alfred_hooks.log
-echo "[$(date)] Input: $INPUT" >> /tmp/alfred_hooks.log
-
-OUTPUT=$(echo "$INPUT" | uv run .claude/hooks/alfred/alfred_hooks.py "$EVENT" 2>&1)
-EXIT_CODE=$?
-
-echo "[$(date)] Output: $OUTPUT" >> /tmp/alfred_hooks.log
-echo "[$(date)] Exit: $EXIT_CODE" >> /tmp/alfred_hooks.log
-
-echo "$OUTPUT"
-exit $EXIT_CODE
-EOF
-
-chmod +x .claude/hooks/alfred/debug_hooks.sh
-
-# Update settings.json to use debug wrapper
-# "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/debug_hooks.sh SessionStart"
-```
-
-### Monitor Hook Performance
-```bash
-# Benchmark all hook events
-for event in SessionStart UserPromptSubmit PreToolUse PostToolUse SessionEnd; do
-  echo "Testing $event..."
-  time echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py $event > /dev/null
-done
-```
-
-### Validate Hook Output Schema
-```bash
-# Test output format
-OUTPUT=$(echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart)
-
-# Check required fields
-echo "$OUTPUT" | python3 -c "
-import json, sys
-data = json.load(sys.stdin)
-assert 'continue' in data, 'Missing continue field'
-assert isinstance(data['continue'], bool), 'continue must be boolean'
-print('✅ Valid hook output schema')
-"
-```
-
----
-
-## Getting Help
-
-### Collect Diagnostic Information
-```bash
-# Create diagnostic report
-cat > /tmp/hooks_diagnostic.txt <<EOF
-=== MoAI-ADK Hooks Diagnostic Report ===
-Date: $(date)
-
-=== Environment ===
-OS: $(uname -s)
-Python: $(python3 --version)
-UV: $(uv --version 2>&1)
-Claude Code: $(claude-code --version 2>&1)
-
-=== File Structure ===
-$(find .claude/hooks/alfred -type f 2>&1)
-
-=== Permissions ===
-$(ls -la .claude/hooks/alfred/ 2>&1)
-
-=== Hook Test ===
-$(echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart 2>&1)
-
-=== Settings ===
-$(cat .claude/settings.json 2>&1 | grep -A 10 "SessionStart")
-EOF
-
-cat /tmp/hooks_diagnostic.txt
-```
-
-### Report Issues
-1. **GitHub Issues**: https://github.com/modu-ai/moai-adk/issues
-2. **Include**: Diagnostic report (above) + error message + steps to reproduce
-3. **Security**: Do NOT include secrets, API keys, or sensitive paths
-
----
-
-## Preventive Maintenance
-
-### Regular Health Checks
-```bash
-# Add to .git/hooks/post-merge
-cat > .git/hooks/post-merge <<'EOF'
-#!/bin/bash
-# Verify hooks after pulling updates
-echo '{"cwd": "."}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart > /dev/null 2>&1
-if [ $? -ne 0 ]; then
-  echo "⚠️ Alfred hooks failed - run /alfred:0-project update"
-fi
-EOF
-
-chmod +x .git/hooks/post-merge
-```
-
-### Keep MoAI-ADK Updated
-```bash
-# Check version
-python3 -c "import moai_adk; print(moai_adk.__version__)"
-
-# Update
-pip install --upgrade moai-adk
-
-# Re-initialize project
-/alfred:0-project update
-```
-
----
-
-**Last Updated**: 2025-10-29
-**Applies To**: MoAI-ADK v0.7.0+
-**Hooks Architecture Version**: Hybrid Modular (9 modules)

moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py

@@ -1,209 +0,0 @@
-#!/usr/bin/env python3
-# @CODE:HOOKS-REFACTOR-001 | SPEC: SPEC-HOOKS-REFACTOR-001.md
-"""Alfred Hooks - Main entry point for MoAI-ADK Claude Code Hooks
-
-A main entry point that routes Claude Code events to the appropriate handlers.
-
-🏗️ Architecture:
-┌─────────────────────────────────────────────────────────────┐
-│ alfred_hooks.py (Router)                                    │
-├─────────────────────────────────────────────────────────────┤
-│ - CLI argument parsing                                      │
-│ - JSON I/O (stdin/stdout)                                   │
-│ - Event routing to handlers                                 │
-└─────────────────────────────────────────────────────────────┘
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│ handlers/ (Event Handlers)                                  │
-├─────────────────────────────────────────────────────────────┤
-│ - session.py: SessionStart, SessionEnd                      │
-│ - user.py: UserPromptSubmit                                 │
-│ - tool.py: PreToolUse, PostToolUse                          │
-│ - notification.py: Notification, Stop, SubagentStop         │
-└─────────────────────────────────────────────────────────────┘
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│ core/ (Business Logic)                                      │
-├─────────────────────────────────────────────────────────────┤
-│ - project.py: Language detection, Git info, SPEC progress   │
-│ - context.py: JIT Retrieval, workflow context               │
-│ - checkpoint.py: Event-Driven Checkpoint system             │
-│ - tags.py: TAG search/verification, library version cache   │
-└─────────────────────────────────────────────────────────────┘
-
-🛠️ Usage:
-    python alfred_hooks.py <event_name> < payload.json
-
-📣 Supported Events:
-    - SessionStart: Start Session (display project status)
-    - UserPromptSubmit: Prompt submission (JIT document loading)
-    - PreToolUse: Before using the tool (automatically creates checkpoint)
-    - SessionEnd, PostToolUse, Notification, Stop, SubagentStop
-
-🚦 Exit Codes:
-    - 0: Success
-    - 1: Error (no arguments, JSON parsing failure, exception thrown)
-
-🧪 TDD History:
-    - RED: Module separation design, event routing test
-    - GREEN: 1233 LOC → 9 items Module separation implementation (SRP compliance)
-    - REFACTOR: Import optimization, enhanced error handling
-
-Setup sys.path for package imports
-"""
-
-import json
-import signal
-import sys
-from pathlib import Path
-from typing import Any
-
-from core import HookResult
-from handlers import (
-    handle_notification,
-    handle_post_tool_use,
-    handle_pre_tool_use,
-    handle_session_end,
-    handle_session_start,
-    handle_stop,
-    handle_subagent_stop,
-    handle_user_prompt_submit,
-)
-
-# Add the hooks directory to sys.path to enable package imports
-HOOKS_DIR = Path(__file__).parent
-if str(HOOKS_DIR) not in sys.path:
-    sys.path.insert(0, str(HOOKS_DIR))
-
-
-class HookTimeoutError(Exception):
-    """Hook execution timeout exception"""
-    pass
-
-
-def _hook_timeout_handler(signum, frame):
-    """Signal handler for global hook timeout"""
-    raise HookTimeoutError("Hook execution exceeded 5-second timeout")
-
-
-def main() -> None:
-    """Main entry point - Claude Code Hook script with GLOBAL TIMEOUT PROTECTION
-
-    Receives the event name as a CLI argument and reads the JSON payload through stdin.
-    Calls the handler appropriate for the event and outputs the results to stdout as JSON.
-    Enforces a 5-second global timeout to prevent subprocess hangs from freezing Claude Code.
-
-    🛠️ Usage:
-        python alfred_hooks.py <event_name> < payload.json
-
-    📣 Supported Events:
-        - SessionStart: Start Session (display project status)
-        - UserPromptSubmit: Prompt submission (JIT document loading)
-        - SessionEnd, PreToolUse, PostToolUse, Notification, Stop, SubagentStop
-
-    🚦 Exit Codes:
-        - 0: Success
-        - 1: Error (timeout, no arguments, JSON parsing failure, exception thrown)
-
-    📝 Examples:
-        $ echo '{"cwd": "."}' | python alfred_hooks.py SessionStart
-        {"message": "🚀 MoAI-ADK Session Started\\n...", ...}
-
-    🗒️ Notes:
-        - Claude Code is automatically called (no need for direct user execution)
-        - JSON I/O processing through stdin/stdout
-        - Print error message to stderr
-        - UserPromptSubmit uses a special output schema (hookEventName + additionalContext)
-        - CRITICAL: 5-second global timeout prevents Claude Code freeze on subprocess hang
-
-    🧪 TDD History:
-        - RED: Event routing, JSON I/O, error handling testing
-        - GREEN: Handler map-based routing implementation
-        - REFACTOR: Error message clarification, exit code standardization, UserPromptSubmit schema separation
-        - HOTFIX: Added global SIGALRM timeout to prevent subprocess hang (Issue #66)
-
-    @TAG:HOOKS-TIMEOUT-001
-    """
-    # Set global 5-second timeout for entire hook execution
-    signal.signal(signal.SIGALRM, _hook_timeout_handler)
-    signal.alarm(5)
-
-    try:
-        # Check for event argument
-        if len(sys.argv) < 2:
-            print("Usage: alfred_hooks.py <event>", file=sys.stderr)
-            sys.exit(1)
-
-        event_name = sys.argv[1]
-
-        try:
-            # Read JSON from stdin
-            input_data = sys.stdin.read()
-            # Handle empty stdin gracefully (return empty dict)
-            if not input_data or not input_data.strip():
-                data = {}
-            else:
-                data = json.loads(input_data)
-
-            cwd = data.get("cwd", ".")
-
-            # Route to appropriate handler
-            handlers = {
-                "SessionStart": handle_session_start,
-                "UserPromptSubmit": handle_user_prompt_submit,
-                "SessionEnd": handle_session_end,
-                "PreToolUse": handle_pre_tool_use,
-                "PostToolUse": handle_post_tool_use,
-                "Notification": handle_notification,
-                "Stop": handle_stop,
-                "SubagentStop": handle_subagent_stop,
-            }
-
-            handler = handlers.get(event_name)
-            result = handler({"cwd": cwd, **data}) if handler else HookResult()
-
-            # Output Hook result as JSON
-            # Note: UserPromptSubmit uses to_user_prompt_submit_dict() for special schema
-            if event_name == "UserPromptSubmit":
-                print(json.dumps(result.to_user_prompt_submit_dict()))
-            else:
-                print(json.dumps(result.to_dict()))
-
-            sys.exit(0)
-
-        except json.JSONDecodeError as e:
-            # Return valid Hook response even on JSON parse error
-            error_response: dict[str, Any] = {
-                "continue": True,
-                "hookSpecificOutput": {"error": f"JSON parse error: {e}"}
-            }
-            print(json.dumps(error_response))
-            print(f"JSON parse error: {e}", file=sys.stderr)
-            sys.exit(1)
-        except Exception as e:
-            # Return valid Hook response even on unexpected error
-            error_response: dict[str, Any] = {
-                "continue": True,
-                "hookSpecificOutput": {"error": f"Hook error: {e}"}
-            }
-            print(json.dumps(error_response))
-            print(f"Unexpected error: {e}", file=sys.stderr)
-            sys.exit(1)
-
-    except HookTimeoutError:
-        # CRITICAL: Hook took too long - return minimal valid response to prevent Claude Code freeze
-        timeout_response: dict[str, Any] = {
-            "continue": True,
-            "systemMessage": "⚠️ Hook execution timeout - continuing without session info"
-        }
-        print(json.dumps(timeout_response))
-        print("Hook timeout after 5 seconds", file=sys.stderr)
-        sys.exit(1)
-
-    finally:
-        # Always cancel the alarm to prevent signal leakage
-        signal.alarm(0)
-
-
-if __name__ == "__main__":
-    main()