moai-adk 0.3.0__py3-none-any.whl

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

@@ -0,0 +1,238 @@
+# Alfred Hooks System
+
+**Event-Driven Context Management for MoAI-ADK**
+
+Alfred Hooks는 Claude Code의 이벤트 시스템과 통합되어 프로젝트 컨텍스트를 자동으로 관리하고, 위험한 작업 전에 checkpoint를 생성하며, JIT (Just-in-Time) 문서 로딩을 제공합니다.
+
+---
+
+## 📐 Architecture
+
+### Modular Design (9 Files, ≤284 LOC each)
+
+```
+.claude/hooks/alfred/
+├── alfred_hooks.py          # Main entry point (CLI router)
+├── core/                    # Core business logic
+│   ├── __init__.py         # Type definitions (HookPayload, HookResult)
+│   ├── project.py          # Language detection, Git info, SPEC counting
+│   ├── context.py          # JIT retrieval, workflow context
+│   ├── checkpoint.py       # Event-driven checkpoint creation
+│   └── tags.py             # TAG search, verification, caching
+└── handlers/                # Event handlers
+    ├── __init__.py         # Handler exports
+    ├── session.py          # SessionStart, SessionEnd
+    ├── user.py             # UserPromptSubmit
+    ├── compact.py          # PreCompact
+    ├── tool.py             # PreToolUse, PostToolUse
+    └── notification.py     # Notification, Stop, SubagentStop
+```
+
+### Design Principles
+
+- **Single Responsibility**: 각 모듈은 하나의 명확한 책임
+- **Separation of Concerns**: core (비즈니스 로직) vs handlers (이벤트 처리)
+- **CODE-FIRST**: 중간 캐시 없이 코드 직접 스캔 (mtime 기반 무효화)
+- **Context Engineering**: JIT Retrieval로 초기 컨텍스트 부담 최소화
+
+---
+
+## 🎯 Core Modules
+
+### `core/project.py` (284 LOC)
+
+**프로젝트 메타데이터 및 언어 감지**
+
+```python
+# Public API
+detect_language(cwd: str) -> str
+get_project_language(cwd: str) -> str
+get_git_info(cwd: str) -> dict[str, Any]
+count_specs(cwd: str) -> dict[str, int]
+```
+
+**Features**:
+- 20개 언어 자동 감지 (Python, TypeScript, Java, Go, Rust, etc.)
+- `.moai/config.json` 우선, fallback to auto-detection
+- Git 정보 조회 (branch, commit, changes)
+- SPEC 진행도 계산 (total, completed, percentage)
+
+### `core/context.py` (110 LOC)
+
+**JIT Context Retrieval 및 워크플로우 관리**
+
+```python
+# Public API
+get_jit_context(prompt: str, cwd: str) -> list[str]
+save_phase_context(phase: str, data: Any, ttl: int = 600)
+load_phase_context(phase: str, ttl: int = 600) -> Any | None
+clear_workflow_context()
+```
+
+**Features**:
+- 프롬프트 분석 기반 문서 자동 추천
+  - `/alfred:1-spec` → `spec-metadata.md`
+  - `/alfred:2-build` → `development-guide.md`
+- 워크플로우 단계별 컨텍스트 캐싱 (TTL 10분)
+- Anthropic Context Engineering 원칙 준수
+
+### `core/checkpoint.py` (244 LOC)
+
+**Event-Driven Checkpoint 자동화**
+
+```python
+# Public API
+detect_risky_operation(tool: str, args: dict, cwd: str) -> tuple[bool, str]
+create_checkpoint(cwd: str, operation: str) -> str
+log_checkpoint(cwd: str, branch: str, description: str)
+list_checkpoints(cwd: str, max_count: int = 10) -> list[dict]
+```
+
+**Features**:
+- 위험한 작업 자동 감지:
+  - Bash: `rm -rf`, `git merge`, `git reset --hard`
+  - Edit/Write: `CLAUDE.md`, `config.json`
+  - MultiEdit: ≥10 files
+- Git checkpoint 자동 생성: `checkpoint/before-{operation}-{timestamp}`
+- checkpoint 이력 관리 및 복구 가이드
+
+### `core/tags.py` (244 LOC)
+
+**CODE-FIRST TAG 시스템**
+
+```python
+# Public API
+search_tags(pattern: str, scope: list[str], cache_ttl: int = 60) -> list[dict]
+verify_tag_chain(tag_id: str) -> dict[str, Any]
+find_all_tags_by_type(tag_type: str) -> dict[str, list[str]]
+suggest_tag_reuse(keyword: str) -> list[str]
+get_library_version(library: str, cache_ttl: int = 86400) -> str | None
+set_library_version(library: str, version: str)
+```
+
+**Features**:
+- ripgrep 기반 TAG 검색 (JSON 출력 파싱)
+- mtime 기반 캐시 무효화 (CODE-FIRST 보장)
+- TAG 체인 검증 (@SPEC → @TEST → @CODE 완전성 확인)
+- 라이브러리 버전 캐싱 (TTL 24시간)
+
+---
+
+## 🎬 Event Handlers
+
+### `handlers/session.py`
+
+**SessionStart, SessionEnd 핸들러**
+
+- **SessionStart**: 프로젝트 정보 표시
+  - 언어, Git 상태, SPEC 진행도, 최근 checkpoint
+  - `systemMessage` 필드로 사용자에게 직접 표시
+- **SessionEnd**: 정리 작업 (stub)
+
+### `handlers/user.py`
+
+**UserPromptSubmit 핸들러**
+
+- JIT Context 추천 문서 리스트 반환
+- 사용자 프롬프트 패턴 분석 및 관련 문서 로드
+
+### `handlers/compact.py`
+
+**PreCompact 핸들러**
+
+- 세션 요약 트리거 (>70% 토큰 사용)
+- Compaction 권장 메시지 생성
+
+### `handlers/tool.py`
+
+**PreToolUse, PostToolUse 핸들러**
+
+- **PreToolUse**: 위험한 작업 감지 시 자동 checkpoint 생성
+- **PostToolUse**: 후처리 작업 (stub)
+
+### `handlers/notification.py`
+
+**Notification, Stop, SubagentStop 핸들러**
+
+- 기본 구현 (stub, 향후 확장 가능)
+
+---
+
+## 🧪 Testing
+
+### Test Suite
+
+```bash
+# Run all tests
+uv run pytest tests/unit/test_alfred_hooks_*.py -v --no-cov
+
+# Run specific module tests
+uv run pytest tests/unit/test_alfred_hooks_core_tags.py -v
+uv run pytest tests/unit/test_alfred_hooks_core_context.py -v
+uv run pytest tests/unit/test_alfred_hooks_core_project.py -v
+```
+
+### Test Coverage (18 tests)
+
+- ✅ **tags.py**: 7 tests (캐시, TAG 검증, 버전 관리)
+- ✅ **context.py**: 5 tests (JIT, 워크플로우 컨텍스트)
+- ✅ **project.py**: 6 tests (언어 감지, Git, SPEC 카운트)
+
+### Test Structure
+
+```python
+# Dynamic module loading for isolated testing
+def _load_{module}_module(module_name: str):
+    repo_root = Path(__file__).resolve().parents[2]
+    hooks_dir = repo_root / ".claude" / "hooks" / "alfred"
+    sys.path.insert(0, str(hooks_dir))
+    
+    module_path = hooks_dir / "core" / "{module}.py"
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
+    # ...
+```
+
+---
+
+## 🔄 Migration from moai_hooks.py
+
+### Before (Monolithic)
+
+- **1 file**: 1233 LOC
+- **Issues**: 
+  - 모든 기능이 하나의 파일에 집중
+  - 테스트 어려움, 유지보수 복잡
+  - 책임 분리 불명확
+
+### After (Modular)
+
+- **9 files**: ≤284 LOC each
+- **Benefits**:
+  - 명확한 책임 분리 (SRP)
+  - 독립적인 모듈 테스트 가능
+  - 확장 용이, 유지보수 간편
+  - Context Engineering 원칙 준수
+
+### Breaking Changes
+
+**없음** - 외부 API는 동일하게 유지됩니다.
+
+---
+
+## 📚 References
+
+### Internal Documents
+
+- **CLAUDE.md**: MoAI-ADK 사용자 가이드
+- **.moai/memory/development-guide.md**: SPEC-First TDD 워크플로우
+- **.moai/memory/spec-metadata.md**: SPEC 메타데이터 표준
+
+### External Resources
+
+- [Claude Code Hooks Documentation](https://docs.claude.com/en/docs/claude-code)
+- [Anthropic Context Engineering](https://docs.anthropic.com/claude/docs/context-engineering)
+
+---
+
+**Last Updated**: 2025-10-16  
+**Author**: @Alfred (MoAI-ADK SuperAgent)

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

@@ -0,0 +1,165 @@
+#!/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
+
+Claude Code 이벤트를 적절한 핸들러로 라우팅하는 메인 진입점
+
+Setup sys.path for package imports
+"""
+import sys
+from pathlib import Path
+
+# 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))
+
+# Now we can import from the package
+
+"""
+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                                 │
+│ - compact.py: PreCompact                                    │
+│ - 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: 세션 시작 (프로젝트 상태 표시)
+    - UserPromptSubmit: 프롬프트 제출 (JIT 문서 로딩)
+    - PreCompact: 컨텍스트 초과 경고 (새 세션 제안)
+    - PreToolUse: Tool 사용 전 (Checkpoint 자동 생성)
+    - SessionEnd, PostToolUse, Notification, Stop, SubagentStop
+
+Exit Codes:
+    - 0: 성공
+    - 1: 에러 (인수 없음, JSON 파싱 실패, 예외 발생)
+
+TDD History:
+    - RED: 모듈 분리 설계, 이벤트 라우팅 테스트
+    - GREEN: 1233 LOC → 9개 모듈 분리 구현 (SRP 준수)
+    - REFACTOR: Import 최적화, 에러 처리 강화
+"""
+
+import json
+
+from core import HookResult
+from handlers import (
+    handle_notification,
+    handle_post_tool_use,
+    handle_pre_compact,
+    handle_pre_tool_use,
+    handle_session_end,
+    handle_session_start,
+    handle_stop,
+    handle_subagent_stop,
+    handle_user_prompt_submit,
+)
+
+
+def main() -> None:
+    """메인 진입점 - Claude Code Hook 스크립트
+
+    CLI 인수로 이벤트명을 받고, stdin으로 JSON 페이로드를 읽습니다.
+    이벤트에 맞는 핸들러를 호출하고, 결과를 JSON으로 stdout에 출력합니다.
+
+    Usage:
+        python alfred_hooks.py <event_name> < payload.json
+
+    Supported Events:
+        - SessionStart: 세션 시작 (프로젝트 상태 표시)
+        - UserPromptSubmit: 프롬프트 제출 (JIT 문서 로딩)
+        - PreCompact: 컨텍스트 초과 경고 (새 세션 제안)
+        - SessionEnd, PreToolUse, PostToolUse, Notification, Stop, SubagentStop
+
+    Exit Codes:
+        - 0: 성공
+        - 1: 에러 (인수 없음, JSON 파싱 실패, 예외 발생)
+
+    Examples:
+        $ echo '{"cwd": "."}' | python alfred_hooks.py SessionStart
+        {"message": "🚀 MoAI-ADK Session Started\\n...", ...}
+
+    Notes:
+        - Claude Code가 자동으로 호출 (사용자 직접 실행 불필요)
+        - stdin/stdout으로 JSON I/O 처리
+        - stderr로 에러 메시지 출력
+        - UserPromptSubmit은 특별한 출력 스키마 사용 (hookEventName + additionalContext)
+
+    TDD History:
+        - RED: 이벤트 라우팅, JSON I/O, 에러 처리 테스트
+        - GREEN: 핸들러 맵 기반 라우팅 구현
+        - REFACTOR: 에러 메시지 명확화, exit code 표준화, UserPromptSubmit 스키마 분리
+    """
+    # 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()
+        data = json.loads(input_data)
+
+        cwd = data.get("cwd", ".")
+
+        # Route to appropriate handler
+        handlers = {
+            "SessionStart": handle_session_start,
+            "UserPromptSubmit": handle_user_prompt_submit,
+            "PreCompact": handle_pre_compact,
+            "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()
+
+        # UserPromptSubmit은 특별한 출력 스키마 사용
+        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:
+        print(f"JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Core module for Alfred Hooks
+
+공통 타입 정의 및 유틸리티 함수
+"""
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, NotRequired, TypedDict
+
+
+class HookPayload(TypedDict):
+    """Claude Code Hook 이벤트 페이로드 타입 정의
+
+    Claude Code가 Hook 스크립트에 전달하는 데이터 구조.
+    이벤트에 따라 필드가 다를 수 있으므로 NotRequired 사용.
+    """
+
+    cwd: str
+    userPrompt: NotRequired[str]  # UserPromptSubmit 이벤트만 포함
+    tool: NotRequired[str]  # PreToolUse/PostToolUse 이벤트
+    arguments: NotRequired[dict[str, Any]]  # Tool arguments
+
+
+@dataclass
+class HookResult:
+    """Hook 실행 결과"""
+
+    message: str | None = None
+    systemMessage: str | None = None  # 사용자에게 직접 표시되는 메시지
+    blocked: bool = False
+    contextFiles: list[str] = field(default_factory=list)
+    suggestions: list[str] = field(default_factory=list)
+    exitCode: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """일반 Hook용 딕셔너리 변환"""
+        return asdict(self)
+
+    def to_user_prompt_submit_dict(self) -> dict[str, Any]:
+        """UserPromptSubmit Hook 전용 출력 형식
+
+        Claude Code는 UserPromptSubmit에 대해 특별한 스키마를 요구:
+        {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "string (required)"
+        }
+
+        Returns:
+            Claude Code UserPromptSubmit Hook 스키마에 맞는 딕셔너리
+
+        Examples:
+            >>> result = HookResult(contextFiles=["tests/"])
+            >>> result.to_user_prompt_submit_dict()
+            {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}
+        """
+        # contextFiles를 additionalContext 문자열로 변환
+        if self.contextFiles:
+            context_str = "\n".join([f"📎 Context: {f}" for f in self.contextFiles])
+        else:
+            context_str = ""
+
+        # message가 있으면 추가
+        if self.message:
+            if context_str:
+                context_str = f"{self.message}\n\n{context_str}"
+            else:
+                context_str = self.message
+
+        # 빈 문자열이면 기본값 사용
+        if not context_str:
+            context_str = ""
+
+        return {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": context_str
+        }
+
+
+__all__ = ["HookPayload", "HookResult"]