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

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

@@ -0,0 +1,471 @@
+# 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/shared/core/project.py

@@ -16,58 +16,6 @@ from typing import Any
 CACHE_DIR_NAME = ".moai/cache"
 
 
-def find_project_root(start_path: str | Path = ".") -> Path:
-    """Find MoAI-ADK project root by searching upward for .moai/config.json
-
-    Traverses up the directory tree until it finds .moai/config.json or CLAUDE.md,
-    which indicates the project root. This ensures cache and other files are
-    always created in the correct location, regardless of where hooks execute.
-
-    Args:
-        start_path: Starting directory (default: current directory)
-
-    Returns:
-        Project root Path. If not found, returns start_path as absolute path.
-
-    Examples:
-        >>> find_project_root(".")
-        Path("/Users/user/my-project")
-        >>> find_project_root(".claude/hooks/alfred")
-        Path("/Users/user/my-project")  # Found root 3 levels up
-
-    Notes:
-        - Searches for .moai/config.json first (most reliable)
-        - Falls back to CLAUDE.md if config.json not found
-        - Max depth: 10 levels up (prevent infinite loop)
-        - Returns absolute path for consistency
-
-    TDD History:
-        - RED: 4 test scenarios (root, nested, not found, symlinks)
-        - GREEN: Minimal upward search with .moai/config.json detection
-        - REFACTOR: Add CLAUDE.md fallback, max depth limit, absolute path return
-    """
-    current = Path(start_path).resolve()
-    max_depth = 10  # Prevent infinite loop
-
-    for _ in range(max_depth):
-        # Check for .moai/config.json (primary indicator)
-        if (current / ".moai" / "config.json").exists():
-            return current
-
-        # Check for CLAUDE.md (secondary indicator)
-        if (current / "CLAUDE.md").exists():
-            return current
-
-        # Move up one level
-        parent = current.parent
-        if parent == current:  # Reached filesystem root
-            break
-        current = parent
-
-    # Not found - return start_path as absolute
-    return Path(start_path).resolve()
-
-
 class TimeoutError(Exception):
     """Signal-based timeout exception"""
     pass
@@ -298,7 +246,7 @@ def count_specs(cwd: str) -> dict[str, int]:
     Counts the number of SPECs with status: completed.
 
     Args:
-        cwd: Project root directory path (or any subdirectory, will search upward)
+        cwd: Project root directory path
 
     Returns:
         SPEC progress dictionary. Includes the following keys:
@@ -316,19 +264,15 @@ def count_specs(cwd: str) -> dict[str, int]:
 
     Notes:
         - SPEC File Location: .moai/specs/SPEC-{ID}/spec.md
-        - Completion condition: Include "status: completed" in YAML front matter
+        - Completion condition: Include “status: completed” in YAML front matter
         - If parsing fails, the SPEC is considered incomplete.
-        - Automatically finds project root to locate .moai/specs/
 
     TDD History:
         - RED: 5 items scenario test (0/0, 2/5, 5/5, no directory, parsing error)
         - GREEN: SPEC search with Path.iterdir(), YAML parsing implementation
         - REFACTOR: Strengthened exception handling, improved percentage calculation safety
-        - UPDATE: Add project root detection for consistent path resolution
     """
-    # Find project root to ensure we read specs from correct location
-    project_root = find_project_root(cwd)
-    specs_dir = project_root / ".moai" / "specs"
+    specs_dir = Path(cwd) / ".moai" / "specs"
 
     if not specs_dir.exists():
         return {"completed": 0, "total": 0, "percentage": 0}
@@ -372,7 +316,7 @@ def get_project_language(cwd: str) -> str:
     """Determine the primary project language (prefers config.json).
 
     Args:
-        cwd: Project root directory (or any subdirectory, will search upward).
+        cwd: Project root directory.
 
     Returns:
         Language string in lower-case.
@@ -380,11 +324,8 @@ def get_project_language(cwd: str) -> str:
     Notes:
         - Reads ``.moai/config.json`` first for a quick answer.
         - Falls back to ``detect_language`` if configuration is missing.
-        - Automatically finds project root to locate .moai/config.json
     """
-    # Find project root to ensure we read config from correct location
-    project_root = find_project_root(cwd)
-    config_path = project_root / ".moai" / "config.json"
+    config_path = Path(cwd) / ".moai" / "config.json"
     if config_path.exists():
         try:
             config = json.loads(config_path.read_text())
@@ -395,8 +336,8 @@ def get_project_language(cwd: str) -> str:
             # Fall back to detection on parse errors
             pass
 
-    # Fall back to the original language detection routine (use project root)
-    return detect_language(str(project_root))
+    # Fall back to the original language detection routine
+    return detect_language(cwd)
 
 
 # @CODE:CONFIG-INTEGRATION-001
@@ -441,9 +382,7 @@ def get_version_check_config(cwd: str) -> dict[str, Any]:
         "cache_ttl_hours": 24
     }
 
-    # Find project root to ensure we read config from correct location
-    project_root = find_project_root(cwd)
-    config_path = project_root / ".moai" / "config.json"
+    config_path = Path(cwd) / ".moai" / "config.json"
     if not config_path.exists():
         return defaults
 
@@ -621,13 +560,8 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
         # Graceful degradation: skip caching on import errors
         VersionCache = None
 
-    # 1. Find project root (ensure cache is always in correct location)
-    # This prevents creating .moai/cache in wrong locations when hooks run
-    # from subdirectories like .claude/hooks/alfred/
-    project_root = find_project_root(cwd)
-
-    # 2. Initialize cache (skip if VersionCache couldn't be imported)
-    cache_dir = project_root / CACHE_DIR_NAME
+    # 1. Initialize cache (skip if VersionCache couldn't be imported)
+    cache_dir = Path(cwd) / CACHE_DIR_NAME
     version_cache = VersionCache(cache_dir) if VersionCache else None
 
     # 2. Get current installed version first (needed for cache validation)
@@ -738,7 +672,6 @@ def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
 
 
 __all__ = [
-    "find_project_root",
     "detect_language",
     "get_git_info",
     "count_specs",

moai_adk/templates/.claude/hooks/alfred/shared/handlers/user.py

@@ -4,6 +4,9 @@
 Handling the UserPromptSubmit event
 """
 
+from datetime import datetime
+from pathlib import Path
+
 from core import HookPayload, HookResult
 from core.context import get_jit_context
 
@@ -29,11 +32,27 @@ def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
         - GREEN: Recommend documents by calling get_jit_context()
         - REFACTOR: Message conditional display (only when there is a file)
         - UPDATE: Migrated to Claude Code standard Hook schema with snake_case fields
+        - FEATURE: Command execution logging for tracking double-run debugging
     """
     user_prompt = payload.get("userPrompt", "")
     cwd = payload.get("cwd", ".")
     context_files = get_jit_context(user_prompt, cwd)
 
+    # Command execution logging (DEBUG feature for tracking invocations)
+    if user_prompt.startswith("/alfred:"):
+        try:
+            log_dir = Path(cwd) / ".moai" / "logs"
+            log_dir.mkdir(parents=True, exist_ok=True)
+
+            log_file = log_dir / "command-invocations.log"
+            timestamp = datetime.now().isoformat()
+
+            with open(log_file, "a", encoding="utf-8") as f:
+                f.write(f"{timestamp} | {user_prompt}\n")
+        except Exception:
+            # Silently fail if logging fails (don't interrupt main flow)
+            pass
+
     system_message = f"📎 Loaded {len(context_files)} context file(s)" if context_files else None
 
     return HookResult(system_message=system_message, context_files=context_files)