moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

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/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 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  # noqa: E402
+from utils.timeout import CrossPlatformTimeout  # noqa: E402
+from utils.timeout import TimeoutError as PlatformTimeoutError  # noqa: E402
+
+
+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."""

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# Hook Configuration Utilities
+
+"""
+Hook 관련 설정 및 유틸리티 함수들
+- Hook timeout 설정 로드
+- Graceful degradation 설정 확인
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def load_hook_timeout() -> int:
+    """
+    .moai/config.json에서 Hook timeout 설정 로드
+
+    Returns:
+        int: timeout 값 (밀리초), 설정이 없으면 기본값 5000 반환
+    """
+    try:
+        config_path = Path(".moai/config.json")
+        if not config_path.exists():
+            return 5000  # 기본값
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        # hooks 섹션에서 timeout_ms 값 가져오기
+        hooks_config = config.get("hooks", {})
+        timeout_ms = hooks_config.get("timeout_ms", 5000)
+
+        return int(timeout_ms)
+    except (json.JSONDecodeError, FileNotFoundError, KeyError, ValueError):
+        logger.warning("Failed to load hook timeout from config, using default 5000ms")
+        return 5000
+
+
+def get_graceful_degradation() -> bool:
+    """
+    .moai/config.json에서 graceful_degradation 설정 로드
+
+    Returns:
+        bool: graceful_degradation 설정값, 설정이 없으면 기본값 True 반환
+    """
+    try:
+        config_path = Path(".moai/config.json")
+        if not config_path.exists():
+            return True  # 기본값
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        # hooks 섹션에서 graceful_degradation 값 가져오기
+        hooks_config = config.get("hooks", {})
+        return hooks_config.get("graceful_degradation", True)
+    except (json.JSONDecodeError, FileNotFoundError, KeyError):
+        logger.warning("Failed to load graceful_degradation from config, using default True")
+        return True
+
+
+def get_hook_execution_config() -> dict:
+    """
+    Hook 실행 관련 모든 설정 로드
+
+    Returns:
+        dict: Hook 설정 딕셔너리
+    """
+    try:
+        config_path = Path(".moai/config.json")
+        if not config_path.exists():
+            return {
+                "timeout_ms": 5000,
+                "graceful_degradation": True
+            }
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        hooks_config = config.get("hooks", {})
+
+        return {
+            "timeout_ms": hooks_config.get("timeout_ms", 5000),
+            "graceful_degradation": hooks_config.get("graceful_degradation", True)
+        }
+    except (json.JSONDecodeError, FileNotFoundError):
+        logger.warning("Failed to load hook config, using defaults")
+        return {
+            "timeout_ms": 5000,
+            "graceful_degradation": True
+        }

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

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# @CODE:TIMEOUT-001 | SPEC: SPEC-TIMEOUT-HANDLING-001
+"""Cross-Platform Timeout Handler for Windows & Unix Compatibility
+
+Provides a unified timeout mechanism that works on both Windows (threading-based)
+and Unix/POSIX systems (signal-based).
+
+Architecture:
+  - Windows: threading.Timer with exception injection
+  - Unix/POSIX: signal.SIGALRM (traditional approach)
+  - Both: Context manager for clean cancellation
+"""
+
+import platform
+import signal
+import threading
+from contextlib import contextmanager
+from typing import Callable, Optional
+
+
+class TimeoutError(Exception):
+    """Timeout exception raised when deadline exceeded"""
+    pass
+
+
+class CrossPlatformTimeout:
+    """Cross-platform timeout handler supporting Windows and Unix.
+
+    Windows: Uses threading.Timer to schedule timeout exception
+    Unix: Uses signal.SIGALRM for timeout handling
+
+    Usage:
+        # Context manager (recommended)
+        with CrossPlatformTimeout(5):
+            long_running_operation()
+
+        # Manual control
+        timeout = CrossPlatformTimeout(5)
+        timeout.start()
+        try:
+            long_running_operation()
+        finally:
+            timeout.cancel()
+    """
+
+    def __init__(self, timeout_seconds: float, callback: Optional[Callable] = None):
+        """Initialize timeout with duration in seconds.
+
+        Args:
+            timeout_seconds: Timeout duration in seconds (float or int)
+            callback: Optional callback to execute before raising TimeoutError
+        """
+        # Convert float to int for signal.alarm()
+        self.timeout_seconds = timeout_seconds
+        self.timeout_seconds_int = max(1, int(timeout_seconds))  # signal.alarm requires >=1
+        self.callback = callback
+        self.timer: Optional[threading.Timer] = None
+        self._is_windows = platform.system() == "Windows"
+        self._old_handler = None
+
+    def start(self) -> None:
+        """Start timeout countdown."""
+        # Handle zero/negative timeouts
+        if self.timeout_seconds <= 0:
+            if self.timeout_seconds == 0:
+                # Zero timeout: raise immediately
+                if self.callback:
+                    self.callback()
+                raise TimeoutError("Timeout of 0 seconds exceeded immediately")
+            else:
+                # Negative timeout: don't timeout at all
+                return
+
+        if self._is_windows:
+            self._start_windows_timeout()
+        else:
+            self._start_unix_timeout()
+
+    def cancel(self) -> None:
+        """Cancel timeout (must call before timeout expires)."""
+        if self._is_windows:
+            self._cancel_windows_timeout()
+        else:
+            self._cancel_unix_timeout()
+
+    def _start_windows_timeout(self) -> None:
+        """Windows: Use threading.Timer to raise exception."""
+        def timeout_handler():
+            if self.callback:
+                self.callback()
+            raise TimeoutError(
+                f"Operation exceeded {self.timeout_seconds}s timeout (Windows threading)"
+            )
+
+        self.timer = threading.Timer(self.timeout_seconds, timeout_handler)
+        self.timer.daemon = True
+        self.timer.start()
+
+    def _cancel_windows_timeout(self) -> None:
+        """Windows: Cancel timer thread."""
+        if self.timer:
+            self.timer.cancel()
+            self.timer = None
+
+    def _start_unix_timeout(self) -> None:
+        """Unix/POSIX: Use signal.SIGALRM for timeout."""
+        def signal_handler(signum, frame):
+            if self.callback:
+                try:
+                    self.callback()
+                except Exception:
+                    # Ignore callback exceptions, timeout error takes precedence
+                    pass
+            raise TimeoutError(
+                f"Operation exceeded {self.timeout_seconds}s timeout (Unix signal)"
+            )
+
+        # Save old handler to restore later
+        self._old_handler = signal.signal(signal.SIGALRM, signal_handler)
+        # Use integer timeout_seconds_int for signal.alarm()
+        signal.alarm(self.timeout_seconds_int)
+
+    def _cancel_unix_timeout(self) -> None:
+        """Unix/POSIX: Cancel alarm and restore old handler."""
+        signal.alarm(0)  # Cancel pending alarm
+        if self._old_handler is not None:
+            signal.signal(signal.SIGALRM, self._old_handler)
+            self._old_handler = None
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - always cancel."""
+        self.cancel()
+        return False  # Don't suppress exceptions
+
+
+@contextmanager
+def timeout_context(timeout_seconds: float, callback: Optional[Callable] = None):
+    """Decorator/context manager for timeout.
+
+    Usage:
+        with timeout_context(5):
+            slow_function()
+
+    Args:
+        timeout_seconds: Timeout duration in seconds (float or int)
+        callback: Optional callback to execute before raising TimeoutError
+
+    Yields:
+        CrossPlatformTimeout instance
+    """
+    timeout = CrossPlatformTimeout(timeout_seconds, callback=callback)
+    timeout.start()
+    try:
+        yield timeout
+    finally:
+        timeout.cancel()