moai-adk 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

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

@@ -1,238 +0,0 @@
-# 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

@@ -1,165 +0,0 @@
-#!/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

@@ -1,79 +0,0 @@
-#!/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"]