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

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Session event handlers
+
+SessionStart, SessionEnd event handling
+"""
+
+from core import HookPayload, HookResult
+from core.checkpoint import list_checkpoints
+from core.project import count_specs, get_git_info, get_package_version_info
+
+
+def handle_session_start(payload: HookPayload) -> HookResult:
+    """SessionStart event handler with GRACEFUL DEGRADATION
+
+    When Claude Code Session starts, it displays a summary of project status.
+    You can check the language, Git status, SPEC progress, and checkpoint list at a glance.
+    All optional operations are wrapped in try-except to ensure hook completes quickly even if
+    Git commands, file I/O, or other operations timeout or fail.
+
+    Args:
+        payload: Claude Code event payload (cwd key required)
+
+    Returns:
+        HookResult(system_message=project status summary message)
+
+    Message Format:
+        🚀 MoAI-ADK Session Started
+           [Version: {version}] - optional if version check fails
+           [Branch: {branch} ({commit hash})] - optional if git fails
+           [Changes: {Number of Changed Files}] - optional if git fails
+           [SPEC Progress: {Complete}/{Total} ({percent}%)] - optional if specs fail
+           [Checkpoints: {number} available] - optional if checkpoint list fails
+
+    Graceful Degradation Strategy:
+        - OPTIONAL: Version info (skip if timeout/failure)
+        - OPTIONAL: Git info (skip if timeout/failure)
+        - OPTIONAL: SPEC progress (skip if timeout/failure)
+        - OPTIONAL: Checkpoint list (skip if timeout/failure)
+        - Always display SOMETHING to user, never return empty message
+
+    Note:
+        - Claude Code processes SessionStart in several stages (clear → compact)
+        - Display message only at "compact" stage to prevent duplicate output
+        - "clear" step returns minimal result (empty hookSpecificOutput)
+        - CRITICAL: All optional operations must complete within 2-3 seconds total
+
+    TDD History:
+        - RED: Session startup message format test
+        - GREEN: Generate status message by combining helper functions
+        - REFACTOR: Improved message format, improved readability, added checkpoint list
+        - FIX: Prevent duplicate output of clear step (only compact step is displayed)
+        - UPDATE: Migrated to Claude Code standard Hook schema
+        - HOTFIX: Add graceful degradation for timeout scenarios (Issue #66)
+        - Phase 3: Add major version warning and release notes display (@TEST:MAJOR-UPDATE-001-07/08)
+
+    @TAG:CHECKPOINT-EVENT-001
+    @TAG:HOOKS-TIMEOUT-001
+    @CODE:MAJOR-UPDATE-WARN-001
+    """
+    # Claude Code SessionStart runs in several stages (clear, compact, etc.)
+    # Ignore the "clear" stage and output messages only at the "compact" stage
+    event_phase = payload.get("phase", "")
+    if event_phase == "clear":
+        # Return minimal valid Hook result for clear phase
+        return HookResult(continue_execution=True)
+
+    cwd = payload.get("cwd", ".")
+
+    # OPTIONAL: Git info - skip if timeout/failure
+    git_info = {}
+    try:
+        git_info = get_git_info(cwd)
+    except Exception:
+        # Graceful degradation - continue without git info
+        pass
+
+    # OPTIONAL: SPEC progress - skip if timeout/failure
+    specs = {"completed": 0, "total": 0, "percentage": 0}
+    try:
+        specs = count_specs(cwd)
+    except Exception:
+        # Graceful degradation - continue without spec info
+        pass
+
+    # OPTIONAL: Checkpoint list - skip if timeout/failure
+    checkpoints = []
+    try:
+        checkpoints = list_checkpoints(cwd, max_count=10)
+    except Exception:
+        # Graceful degradation - continue without checkpoints
+        pass
+
+    # OPTIONAL: Package version info - skip if timeout/failure
+    version_info = {}
+    try:
+        version_info = get_package_version_info()
+    except Exception:
+        # Graceful degradation - continue without version info
+        pass
+
+    # Build message with available information
+    branch = git_info.get("branch", "N/A") if git_info else "N/A"
+    commit = git_info.get("commit", "N/A")[:7] if git_info else "N/A"
+    changes = git_info.get("changes", 0) if git_info else 0
+    spec_progress = f"{specs['completed']}/{specs['total']}" if specs["total"] > 0 else "0/0"
+
+    # system_message: displayed directly to the user
+    lines = [
+        "🚀 MoAI-ADK Session Started",
+        "",  # Blank line after title
+    ]
+
+    # Add version info first (at the top, right after title)
+    if version_info and version_info.get("current") != "unknown":
+        if version_info.get("update_available"):
+            # Check if this is a major version update
+            if version_info.get("is_major_update"):
+                # Major version warning
+                lines.append(
+                    f"   ⚠️  Major version update available: {version_info['current']} → {version_info['latest']}"
+                )
+                lines.append("   Breaking changes detected. Review release notes:")
+                if version_info.get("release_notes_url"):
+                    lines.append(f"   📝 {version_info['release_notes_url']}")
+            else:
+                # Regular update
+                lines.append(
+                    f"   🗿 MoAI-ADK Ver: {version_info['current']} → {version_info['latest']} available ✨"
+                )
+                if version_info.get("release_notes_url"):
+                    lines.append(f"   📝 Release Notes: {version_info['release_notes_url']}")
+
+            # Add upgrade recommendation
+            if version_info.get("upgrade_command"):
+                lines.append(f"   ⬆️  Upgrade: {version_info['upgrade_command']}")
+        else:
+            # No update available - show current version only
+            lines.append(f"   🗿 MoAI-ADK Ver: {version_info['current']}")
+
+
+    # Add Git info only if available (not degraded)
+    if git_info:
+        lines.append(f"   🌿 Branch: {branch} ({commit})")
+        lines.append(f"   📝 Changes: {changes}")
+
+        # Add last commit message if available
+        last_commit = git_info.get("last_commit", "")
+        if last_commit:
+            lines.append(f"   🔨 Last: {last_commit}")
+
+    # Add Checkpoint list (show only the latest 3 items)
+    if checkpoints:
+        lines.append(f"   🗂️  Checkpoints: {len(checkpoints)} available")
+        for cp in reversed(checkpoints[-3:]):  # Latest 3 items
+            branch_short = cp["branch"].replace("before-", "")
+            lines.append(f"      📌 {branch_short}")
+        lines.append("")  # Blank line before restore command
+        lines.append("   ↩️  Restore: /alfred:0-project restore")
+
+    # Add SPEC progress only if available (not degraded) - at the bottom
+    if specs["total"] > 0:
+        lines.append(f"   📋 SPEC Progress: {spec_progress} ({specs['percentage']}%)")
+
+    system_message = "\n".join(lines)
+
+    return HookResult(system_message=system_message)
+
+
+def handle_session_end(payload: HookPayload) -> HookResult:
+    """SessionEnd event handler (default implementation)"""
+    return HookResult()
+
+
+__all__ = ["handle_session_start", "handle_session_end"]

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# @CODE:HOOK-TOOL-001 | SPEC: TBD | TEST: tests/hooks/test_handlers.py
+"""Tool usage handlers
+
+PreToolUse, PostToolUse event handling
+"""
+
+from core import HookPayload, HookResult
+from core.checkpoint import create_checkpoint, detect_risky_operation
+from core.tags import scan_recent_changes_for_missing_tags
+
+
+def handle_pre_tool_use(payload: HookPayload) -> HookResult:
+    """PreToolUse event handler (Event-Driven Checkpoint integration)
+
+    Automatically creates checkpoints before dangerous operations.
+    Called before using the Claude Code tool, it notifies the user when danger is detected.
+
+    Args:
+        payload: Claude Code event payload
+                 (includes tool, arguments, cwd keys)
+
+    Returns:
+        HookResult(
+            system_message=checkpoint creation notification (when danger is detected);
+            continue_execution=True (always continue operation)
+        )
+
+    Checkpoint Triggers:
+        - Bash: rm -rf, git merge, git reset --hard
+        - Edit/Write: CLAUDE.md, config.json
+        - MultiEdit: ≥10 files
+
+    Examples:
+        Bash tool (rm -rf) detection:
+        → "🛡️ Checkpoint created: before-delete-20251015-143000"
+
+    Notes:
+        - Return continue_execution=True even after detection of danger (continue operation)
+        - Work continues even when checkpoint fails (ignores)
+        - Transparent background operation
+
+    @TAG:CHECKPOINT-EVENT-001
+    """
+    tool_name = payload.get("tool", "")
+    tool_args = payload.get("arguments", {})
+    cwd = payload.get("cwd", ".")
+
+    # Dangerous operation detection (best-effort)
+    try:
+        is_risky, operation_type = detect_risky_operation(tool_name, tool_args, cwd)
+        # Create checkpoint when danger is detected
+        if is_risky:
+            checkpoint_branch = create_checkpoint(cwd, operation_type)
+            if checkpoint_branch != "checkpoint-failed":
+                system_message = (
+                    f"🛡️ Checkpoint created: {checkpoint_branch}\n   Operation: {operation_type}"
+                )
+                return HookResult(system_message=system_message, continue_execution=True)
+    except Exception:
+        # Do not fail the hook if risk detection errors out
+        pass
+
+    # TAG Guard (gentle): warn when recent changes miss @TAG
+    issues = scan_recent_changes_for_missing_tags(cwd)
+    if issues:
+        # Summarize first few issues for display
+        preview = "\n".join(f" - {i.path} → 기대 태그: {i.expected}" for i in issues[:5])
+        more = "" if len(issues) <= 5 else f"\n (외 {len(issues) - 5}건 더 존재)"
+        msg = (
+            "⚠️ TAG 누락 감지: 생성/수정한 파일 중 @TAG가 없는 항목이 있습니다.\n"
+            f"{preview}{more}\n"
+            "권장 조치:\n"
+            "  1) SPEC/TEST/CODE/DOC 유형에 맞는 @TAG를 파일 상단 주석이나 헤더에 추가\n"
+            "  2) rg로 확인: rg '@(SPEC|TEST|CODE|DOC):' -n <경로>\n"
+        )
+        return HookResult(system_message=msg, continue_execution=True)
+
+    return HookResult(continue_execution=True)
+
+
+def handle_post_tool_use(payload: HookPayload) -> HookResult:
+    """PostToolUse event handler (default implementation)"""
+    return HookResult()
+
+
+__all__ = ["handle_pre_tool_use", "handle_post_tool_use"]

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""User interaction handlers
+
+Handling the UserPromptSubmit event
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from core import HookPayload, HookResult
+from core.context import get_jit_context
+
+
+def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
+    """UserPromptSubmit event handler
+
+    Analyze user prompts and automatically add relevant documents into context.
+    Follow the just-in-time (JIT) retrieval principle to load only the documents you need.
+
+    Args:
+        payload: Claude Code event payload
+                 (includes userPrompt, cwd keys)
+
+    Returns:
+        HookResult(
+            system_message=Number of Files loaded (or None),
+            context_files=Recommended document path list
+        )
+
+    TDD History:
+        - RED: JIT document loading scenario testing
+        - 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)
+
+
+__all__ = ["handle_user_prompt_submit"]

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-STOP | SPEC: Individual hook files for better UX
+"""Stop Hook: Handle Execution Interruption
+
+Claude Code Event: Stop
+Purpose: Handle graceful shutdown when execution is interrupted by user
+Execution: Triggered when user stops Claude Code execution (Ctrl+C, stop button)
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from utils.timeout import CrossPlatformTimeout, TimeoutError as PlatformTimeoutError
+
+# Setup import path for shared modules
+HOOKS_DIR = Path(__file__).parent
+SHARED_DIR = HOOKS_DIR / "shared"
+if str(SHARED_DIR) not in sys.path:
+    sys.path.insert(0, str(SHARED_DIR))
+
+from handlers import handle_stop
+
+
+
+
+def main() -> None:
+    """Main entry point for Stop hook
+
+    Currently a stub for future functionality:
+    - Save partial work before interruption
+    - Create recovery checkpoint
+    - Log interruption reason and context
+    - Notify external systems of stop event
+
+    Exit Codes:
+        0: Success
+        1: Error (timeout, JSON parse failure, handler exception)
+    """
+    # Set 5-second timeout
+    timeout = CrossPlatformTimeout(5)
+    timeout.start()
+
+    try:
+        # Read JSON payload from stdin
+        input_data = sys.stdin.read()
+        data = json.loads(input_data) if input_data.strip() else {}
+
+        # Call handler
+        result = handle_stop(data)
+
+        # Output result as JSON
+        print(json.dumps(result.to_dict()))
+        sys.exit(0)
+
+    except PlatformTimeoutError:
+        # Timeout - return minimal valid response
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "systemMessage": "⚠️ Stop handler timeout",
+        }
+        print(json.dumps(timeout_response))
+        print("Stop hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"JSON parse error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"Stop JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"Stop error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"Stop unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        timeout.cancel()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-SUBAGENT | SPEC: Individual hook files for better UX
+"""SubagentStop Hook: Handle Sub-agent Termination
+
+Claude Code Event: SubagentStop
+Purpose: Handle cleanup when a sub-agent execution completes or is terminated
+Execution: Triggered when Task tool completes (sub-agent finishes)
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from utils.timeout import CrossPlatformTimeout, TimeoutError as PlatformTimeoutError
+
+# Setup import path for shared modules
+HOOKS_DIR = Path(__file__).parent
+SHARED_DIR = HOOKS_DIR / "shared"
+if str(SHARED_DIR) not in sys.path:
+    sys.path.insert(0, str(SHARED_DIR))
+
+from handlers import handle_subagent_stop
+
+
+
+
+def main() -> None:
+    """Main entry point for SubagentStop hook
+
+    Currently a stub for future functionality:
+    - Collect sub-agent execution metrics
+    - Log sub-agent results and errors
+    - Update workflow state based on sub-agent outcome
+    - Trigger follow-up actions based on results
+
+    Exit Codes:
+        0: Success
+        1: Error (timeout, JSON parse failure, handler exception)
+    """
+    # Set 5-second timeout
+    timeout = CrossPlatformTimeout(5)
+    timeout.start()
+
+    try:
+        # Read JSON payload from stdin
+        input_data = sys.stdin.read()
+        data = json.loads(input_data) if input_data.strip() else {}
+
+        # Call handler
+        result = handle_subagent_stop(data)
+
+        # Output result as JSON
+        print(json.dumps(result.to_dict()))
+        sys.exit(0)
+
+    except PlatformTimeoutError:
+        # Timeout - return minimal valid response
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "systemMessage": "⚠️ SubagentStop handler timeout",
+        }
+        print(json.dumps(timeout_response))
+        print("SubagentStop hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"JSON parse error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"SubagentStop JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"SubagentStop error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"SubagentStop unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        timeout.cancel()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-DOCS | SPEC: Individual hook files for better UX
+"""UserPromptSubmit Hook: Just-In-Time Document Loading
+
+Claude Code Event: UserPromptSubmit
+Purpose: Analyze user prompt and recommend relevant documents to load into context
+Execution: Triggered when user submits a prompt
+
+Output: additionalContext with document path suggestions
+"""
+
+import json
+import sys
+from pathlib import Path
+from utils.timeout import CrossPlatformTimeout, TimeoutError as PlatformTimeoutError
+from typing import Any
+
+# Setup import path for shared modules
+HOOKS_DIR = Path(__file__).parent
+SHARED_DIR = HOOKS_DIR / "shared"
+if str(SHARED_DIR) not in sys.path:
+    sys.path.insert(0, str(SHARED_DIR))
+
+from handlers import handle_user_prompt_submit
+
+
+
+def main() -> None:
+    """Main entry point for UserPromptSubmit hook
+
+    Analyzes user prompt patterns and recommends relevant documents:
+    - /alfred:1-plan → spec-metadata.md
+    - /alfred:2-run → development-guide.md
+    - @TAG mentions → TAG documentation
+    - SPEC references → related SPEC files
+
+    Exit Codes:
+        0: Success
+        1: Error (timeout, JSON parse failure, handler exception)
+
+    Note: Uses special output schema for UserPromptSubmit:
+    {
+        "continue": true,
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "Document path suggestions..."
+        }
+    }
+    """
+    # Set 5-second timeout
+    timeout = CrossPlatformTimeout(5)
+    timeout.start()
+
+    try:
+        # Read JSON payload from stdin
+        input_data = sys.stdin.read()
+        data = json.loads(input_data) if input_data.strip() else {}
+
+        # Call handler
+        result = handle_user_prompt_submit(data)
+
+        # Output result using UserPromptSubmit-specific schema
+        print(json.dumps(result.to_user_prompt_submit_dict()))
+        sys.exit(0)
+
+    except PlatformTimeoutError:
+        # Timeout - return minimal valid response
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": "⚠️ JIT context timeout - continuing without suggestions",
+            },
+        }
+        print(json.dumps(timeout_response))
+        print("UserPromptSubmit hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "error": f"JSON parse error: {e}",
+            },
+        }
+        print(json.dumps(error_response))
+        print(f"UserPromptSubmit JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "error": f"UserPromptSubmit error: {e}",
+            },
+        }
+        print(json.dumps(error_response))
+        print(f"UserPromptSubmit unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        timeout.cancel()
+
+
+if __name__ == "__main__":
+    main()

moai_adk/templates/.claude/hooks/alfred/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for Alfred hooks."""