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

moai_adk/templates/.claude/commands/alfred/9-feedback.md

@@ -0,0 +1,149 @@
+---
+name: alfred:9-feedback
+description: "Interactive GitHub Issue creation - Step-by-step dialog to create issues without command arguments"
+allowed-tools:
+- Bash(gh:*)
+- Task
+- AskUserQuestion
+---
+
+# 🎯 MoAI-ADK Alfred 9-Feedback: Interactive GitHub Issue Creation
+
+> **Purpose**: Create GitHub Issues through an interactive multi-step dialog. Simple command → guided questions → automatic issue creation.
+
+## 📋 Command Purpose
+
+Enable developers to instantly report bugs, request features, suggest improvements, and ask questions through conversational dialogs. No command arguments needed—just run `/alfred:9-feedback` and answer questions.
+
+**Command Format**:
+```bash
+/alfred:9-feedback
+```
+
+That's it! Alfred guides you through the rest.
+
+---
+
+## 🚀 Interactive Execution Flow
+
+### Step 1: Start Command
+```bash
+/alfred:9-feedback
+```
+
+Alfred responds and proceeds to Step 2.
+
+---
+
+### Step 2: Select Issue Type (AskUserQuestion)
+
+**Question**: "What type of issue do you want to create?"
+
+**Options**:
+```
+[ ] 🐛 Bug Report - Something isn't working
+[ ] ✨ Feature Request - Suggest new functionality
+[ ] ⚡ Improvement - Enhance existing features
+[ ] ❓ Question/Discussion - Ask the team
+```
+
+**User Selection**: Selects one (e.g., 🐛 Bug Report)
+
+---
+
+### Step 3: Enter Issue Title (AskUserQuestion)
+
+**Question**: "What is the issue title? (Be concise)"
+
+**Example Input**:
+```
+Login button on homepage not responding to clicks
+```
+
+---
+
+### Step 4: Enter Description (AskUserQuestion)
+
+**Question**: "Provide a detailed description (optional—press Enter to skip)"
+
+**Example Input**:
+```
+When I click the login button on the homepage, nothing happens.
+Tested on Chrome 120.0 on macOS 14.2.
+Expected: Login modal should appear
+Actual: No response
+```
+
+Or just press Enter to skip.
+
+---
+
+### Step 5: Select Priority (AskUserQuestion)
+
+**Question**: "What's the priority level?"
+
+**Options**:
+```
+[ ] 🔴 Critical - System down, data loss, security breach
+[ ] 🟠 High - Major feature broken, significant impact
+[✓] 🟡 Medium - Normal priority (default)
+[ ] 🟢 Low - Minor issues, nice-to-have
+```
+
+**User Selection**: Selects priority (e.g., 🟠 High)
+
+---
+
+### Step 6: Create Issue (Automatic)
+
+Alfred automatically:
+1. Formats title with emoji: "🐛 [BUG] Login button not responding..."
+2. Prepares body with user description + metadata
+3. Assigns labels: bug, reported, priority-high
+4. Executes: `gh issue create --title ... --body ... --label ...`
+5. Parses issue number from response
+
+**Success Output**:
+```
+✅ GitHub Issue #234 created successfully!
+
+📋 Title: 🐛 [BUG] Login button not responding to clicks
+🔴 Priority: High
+🏷️  Labels: bug, reported, priority-high
+🔗 URL: https://github.com/owner/repo/issues/234
+
+💡 Next: Reference this issue in your commits or link to a SPEC document
+```
+
+---
+
+## ⚠️ Important Rules
+
+### ✅ What to Do
+
+- ✅ Ask all 4 questions in sequence (type → title → description → priority)
+- ✅ Preserve exact user wording in title and description
+- ✅ Use AskUserQuestion for all user inputs
+- ✅ Allow skipping description (optional field)
+- ✅ Show issue URL after creation
+
+### ❌ What NOT to Do
+
+- ❌ Accept command arguments (`/alfred:9-feedback --bug` is wrong—just use `/alfred:9-feedback`)
+- ❌ Skip questions or change order
+- ❌ Rephrase user's input
+- ❌ Create issues without labels
+
+---
+
+## 💡 Key Benefits
+
+1. **🚀 No Arguments Needed**: Just `/alfred:9-feedback`
+2. **💬 Conversational**: Intuitive step-by-step dialog
+3. **🏷️ Auto-labeled**: Labels applied automatically
+4. **🔗 Team Visible**: Issues immediately visible
+5. **⏱️ Fast**: Create issues in 30 seconds
+
+---
+
+**Supported since**: MoAI-ADK v0.7.0+

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

@@ -0,0 +1,206 @@
+#!/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 utils.timeout import CrossPlatformTimeout, TimeoutError as PlatformTimeoutError
+
+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))
+
+
+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 PlatformTimeoutError:
+        # 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
+        timeout.cancel()
+
+
+if __name__ == "__main__":
+    main()