moai-adk 0.3.6__py3-none-any.whl → 0.3.9__py3-none-any.whl

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

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""TAG search and verification system
+
+TAG 검색, 체인 검증, 라이브러리 버전 캐싱
+"""
+
+import json
+import subprocess
+import time
+from pathlib import Path
+
+# TAG search cache: {pattern: (results, mtime_hash, cached_at)}
+_tag_cache: dict[str, tuple[list[dict], float, float]] = {}
+
+# Library version cache: {lib_name: (version, timestamp)}
+_lib_version_cache: dict[str, tuple[str, float]] = {}
+
+
+def _get_dir_mtime_hash(paths: list[str]) -> float:
+    """Calculate a directory-wide mtime hash used for cache invalidation.
+
+    Args:
+        paths: List of directory paths to inspect.
+
+    Returns:
+        Highest modification timestamp (float) across all files.
+
+    Notes:
+        - Any file change bumps the hash and invalidates the cache.
+        - Missing or inaccessible directories are ignored.
+    """
+    max_mtime = 0.0
+    for path in paths:
+        path_obj = Path(path)
+        if not path_obj.exists():
+            continue
+
+        try:
+            for file_path in path_obj.rglob("*"):
+                if file_path.is_file():
+                    max_mtime = max(max_mtime, file_path.stat().st_mtime)
+        except (OSError, PermissionError):
+            # Skip directories we cannot read
+            continue
+
+    return max_mtime
+
+
+def search_tags(pattern: str, scope: list[str] | None = None, cache_ttl: int = 60) -> list[dict]:
+    """Search TAG markers using an in-memory cache.
+
+    Args:
+        pattern: Regex pattern (for example ``'@SPEC:AUTH-.*'``).
+        scope: List of directories to scan. Defaults to specs/src/tests.
+        cache_ttl: Cache time-to-live in seconds (default 60).
+
+    Returns:
+        List of matches such as ``{"file": "path", "line": 10, "tag": "...", "content": "..."}``.
+
+    Notes:
+        - Cache integrity relies on directory mtimes plus TTL.
+        - Cache hits avoid spawning ``rg`` while misses shell out (≈13ms).
+        - Uses ``rg --json`` output for structured parsing.
+    """
+    if scope is None:
+        scope = [".moai/specs/", "src/", "tests/"]
+
+    cache_key = f"{pattern}:{':'.join(scope)}"
+
+    current_mtime = _get_dir_mtime_hash(scope)
+    cache_entry = _tag_cache.get(cache_key)
+
+    # Serve cached results when still valid
+    if cache_entry:
+        cached_results, cached_mtime, cached_at = cache_entry
+        ttl_valid = time.time() - cached_at < cache_ttl
+
+        # Matching mtime and a fresh TTL means we can reuse the cache
+        if current_mtime == cached_mtime and ttl_valid:
+            return cached_results
+
+    # Cache miss → invoke ripgrep
+    cmd = ["rg", pattern, "--json"] + scope
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=5, check=False)
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        # Missing rg or a timeout returns an empty list
+        return []
+
+    matches = []
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        try:
+            data = json.loads(line)
+            if data.get("type") == "match":
+                matches.append(
+                    {
+                        "file": data["data"]["path"]["text"],
+                        "line": data["data"]["line_number"],
+                        "tag": data["data"]["lines"]["text"].strip(),
+                        "content": data["data"]["lines"]["text"],
+                    }
+                )
+        except (json.JSONDecodeError, KeyError):
+            # Ignore malformed JSON lines
+            continue
+
+    # Persist results with the current mtime snapshot
+    _tag_cache[cache_key] = (matches, _get_dir_mtime_hash(scope), time.time())
+
+    return matches
+
+
+def verify_tag_chain(spec_id: str) -> dict:
+    """Verify a TAG chain across ``@SPEC`` → ``@TEST`` → ``@CODE``.
+
+    Args:
+        spec_id: SPEC identifier (for example ``"AUTH-001"``).
+
+    Returns:
+        Dictionary with keys ``complete``, ``spec``, ``test``, ``code`` and ``orphans``.
+
+    Notes:
+        - Orphans capture TAGs found in code/tests without a SPEC.
+        - A chain is complete only when all three categories contain matches.
+        - Relies on ``search_tags`` so cached scans remain inexpensive.
+    """
+    chain = {
+        "spec": search_tags(f"@SPEC:{spec_id}", [".moai/specs/"]),
+        "test": search_tags(f"@TEST:{spec_id}", ["tests/"]),
+        "code": search_tags(f"@CODE:{spec_id}", ["src/"]),
+    }
+
+    orphans = []
+    if chain["code"] and not chain["spec"]:
+        orphans.extend(chain["code"])
+    if chain["test"] and not chain["spec"]:
+        orphans.extend(chain["test"])
+
+    return {
+        "complete": bool(chain["spec"] and chain["test"] and chain["code"]),
+        **chain,
+        "orphans": orphans,
+    }
+
+
+def find_all_tags_by_type(tag_type: str = "SPEC") -> dict:
+    """Return TAG IDs grouped by domain for the requested type.
+
+    Args:
+        tag_type: TAG category (``SPEC``, ``TEST``, ``CODE`` or ``DOC``).
+
+    Returns:
+        Dictionary like ``{"AUTH": ["AUTH-001", "AUTH-002"], ...}``.
+
+    Notes:
+        - Domain is derived from the ``FOO-123`` prefix.
+        - Deduplicates repeated matches within the same domain.
+        - Fetches data via ``search_tags`` so caching still applies.
+    """
+    tags = search_tags(f"@{tag_type}:([A-Z]+-[0-9]{{3}})")
+
+    by_domain = {}
+    for tag in tags:
+        # @SPEC:AUTH-001 → AUTH
+        try:
+            tag_id = tag["tag"].split(":")[1]
+            domain = "-".join(tag_id.split("-")[:-1])
+
+            if domain not in by_domain:
+                by_domain[domain] = []
+            if tag_id not in by_domain[domain]:
+                by_domain[domain].append(tag_id)
+        except IndexError:
+            # 파싱 실패 무시
+            continue
+
+    return by_domain
+
+
+def suggest_tag_reuse(keyword: str, tag_type: str = "SPEC") -> list[str]:
+    """Suggest existing TAG IDs that match the supplied keyword.
+
+    Args:
+        keyword: Keyword used to match domain names (case-insensitive).
+        tag_type: TAG category (defaults to ``SPEC``).
+
+    Returns:
+        A list of up to five suggested TAG IDs.
+
+    Notes:
+        - Encourages reuse to avoid creating duplicate TAGs.
+        - Performs a simple substring match against domain names.
+    """
+    all_tags = find_all_tags_by_type(tag_type)
+    suggestions = []
+
+    keyword_lower = keyword.lower()
+    for domain, tag_ids in all_tags.items():
+        if keyword_lower in domain.lower():
+            suggestions.extend(tag_ids)
+
+    return suggestions[:5]  # Cap results at five
+
+
+def get_library_version(lib_name: str, cache_ttl: int = 86400) -> str | None:
+    """Get the cached latest stable version for a library.
+
+    Args:
+        lib_name: Package name (for example ``"fastapi"``).
+        cache_ttl: Cache TTL in seconds (defaults to 24 hours).
+
+    Returns:
+        Cached version string or ``None`` when the cache is cold.
+
+    Notes:
+        - Cache hits skip costly web searches (saves 3–5 seconds).
+        - Agents should call ``set_library_version`` after fetching live data.
+    """
+    # Serve cached value when still within TTL
+    if lib_name in _lib_version_cache:
+        cached_version, cached_time = _lib_version_cache[lib_name]
+        if time.time() - cached_time < cache_ttl:
+            return cached_version
+
+    # Cache miss → agent needs to perform the web search
+    return None
+
+
+def set_library_version(lib_name: str, version: str):
+    """Persist a library version in the cache."""
+    _lib_version_cache[lib_name] = (version, time.time())
+
+
+__all__ = [
+    "search_tags",
+    "verify_tag_chain",
+    "find_all_tags_by_type",
+    "suggest_tag_reuse",
+    "get_library_version",
+    "set_library_version",
+]

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Event handlers for Alfred Hooks
+
+Claude Code 이벤트 핸들러들
+"""
+
+from .notification import handle_notification, handle_stop, handle_subagent_stop
+from .session import handle_session_end, handle_session_start
+from .tool import handle_post_tool_use, handle_pre_tool_use
+from .user import handle_user_prompt_submit
+
+__all__ = [
+    "handle_session_start",
+    "handle_session_end",
+    "handle_user_prompt_submit",
+    "handle_pre_tool_use",
+    "handle_post_tool_use",
+    "handle_notification",
+    "handle_stop",
+    "handle_subagent_stop",
+]

moai_adk/templates/.claude/hooks/alfred/handlers/notification.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Notification and control handlers
+
+Notification, Stop, SubagentStop 이벤트 처리
+"""
+
+from core import HookPayload, HookResult
+
+
+def handle_notification(payload: HookPayload) -> HookResult:
+    """Notification 이벤트 핸들러 (기본 구현)"""
+    return HookResult()
+
+
+def handle_stop(payload: HookPayload) -> HookResult:
+    """Stop 이벤트 핸들러 (기본 구현)"""
+    return HookResult()
+
+
+def handle_subagent_stop(payload: HookPayload) -> HookResult:
+    """SubagentStop 이벤트 핸들러 (기본 구현)"""
+    return HookResult()
+
+
+__all__ = ["handle_notification", "handle_stop", "handle_subagent_stop"]

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Session event handlers
+
+SessionStart, SessionEnd 이벤트 처리
+"""
+
+from core import HookPayload, HookResult
+from core.checkpoint import list_checkpoints
+from core.project import count_specs, detect_language, get_git_info
+
+
+def handle_session_start(payload: HookPayload) -> HookResult:
+    """SessionStart 이벤트 핸들러 (Checkpoint 목록 포함)
+
+    Claude Code 세션 시작 시 프로젝트 상태를 요약하여 표시합니다.
+    언어, Git 상태, SPEC 진행도, Checkpoint 목록을 한눈에 확인할 수 있습니다.
+
+    Args:
+        payload: Claude Code 이벤트 페이로드 (cwd 키 필수)
+
+    Returns:
+        HookResult(message=프로젝트 상태 요약 메시지, systemMessage=사용자 표시용)
+
+    Message Format:
+        🚀 MoAI-ADK Session Started
+           Language: {언어}
+           Branch: {브랜치} ({커밋 해시})
+           Changes: {변경 파일 수}
+           SPEC Progress: {완료}/{전체} ({퍼센트}%)
+           Checkpoints: {개수} available (최신 3개 표시)
+
+    TDD History:
+        - RED: 세션 시작 메시지 형식 테스트
+        - GREEN: helper 함수 조합하여 상태 메시지 생성
+        - REFACTOR: 메시지 포맷 개선, 가독성 향상, checkpoint 목록 추가
+
+    @TAG:CHECKPOINT-EVENT-001
+    """
+    cwd = payload.get("cwd", ".")
+    language = detect_language(cwd)
+    git_info = get_git_info(cwd)
+    specs = count_specs(cwd)
+    checkpoints = list_checkpoints(cwd, max_count=10)
+
+    branch = git_info.get("branch", "N/A")
+    commit = git_info.get("commit", "N/A")[:7]
+    changes = git_info.get("changes", 0)
+    spec_progress = f"{specs['completed']}/{specs['total']}"
+
+    # systemMessage: 사용자에게 직접 표시
+    lines = [
+        "🚀 MoAI-ADK Session Started",
+        f"   Language: {language}",
+        f"   Branch: {branch} ({commit})",
+        f"   Changes: {changes}",
+        f"   SPEC Progress: {spec_progress} ({specs['percentage']}%)",
+    ]
+
+    # Checkpoint 목록 추가 (최신 3개만 표시)
+    if checkpoints:
+        lines.append(f"   Checkpoints: {len(checkpoints)} available")
+        for cp in reversed(checkpoints[-3:]):  # 최신 3개
+            branch_short = cp["branch"].replace("before-", "")
+            lines.append(f"      - {branch_short}")
+        lines.append("   Restore: /alfred:0-project restore")
+
+    system_message = "\n".join(lines)
+
+    return HookResult(
+        message=system_message,  # Claude 컨텍스트용
+        systemMessage=system_message,  # 사용자 표시용
+    )
+
+
+def handle_session_end(payload: HookPayload) -> HookResult:
+    """SessionEnd 이벤트 핸들러 (기본 구현)"""
+    return HookResult()
+
+
+__all__ = ["handle_session_start", "handle_session_end"]

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Tool usage handlers
+
+PreToolUse, PostToolUse 이벤트 처리
+"""
+
+from core import HookPayload, HookResult
+from core.checkpoint import create_checkpoint, detect_risky_operation
+
+
+def handle_pre_tool_use(payload: HookPayload) -> HookResult:
+    """PreToolUse 이벤트 핸들러 (Event-Driven Checkpoint 통합)
+
+    위험한 작업 전 자동으로 checkpoint를 생성합니다.
+    Claude Code tool 사용 전에 호출되며, 위험 감지 시 사용자에게 알립니다.
+
+    Args:
+        payload: Claude Code 이벤트 페이로드
+                 (tool, arguments, cwd 키 포함)
+
+    Returns:
+        HookResult(
+            message=checkpoint 생성 알림 (위험 감지 시),
+            blocked=False (항상 작업 계속 진행)
+        )
+
+    Checkpoint Triggers:
+        - Bash: rm -rf, git merge, git reset --hard
+        - Edit/Write: CLAUDE.md, config.json
+        - MultiEdit: ≥10 files
+
+    Examples:
+        Bash tool (rm -rf) 감지:
+        → "🛡️ Checkpoint created: before-delete-20251015-143000"
+
+    Notes:
+        - 위험 감지 후에도 blocked=False 반환 (작업 계속)
+        - Checkpoint 실패 시에도 작업 진행 (무시)
+        - 투명한 백그라운드 동작
+
+    @TAG:CHECKPOINT-EVENT-001
+    """
+    tool_name = payload.get("tool", "")
+    tool_args = payload.get("arguments", {})
+    cwd = payload.get("cwd", ".")
+
+    # 위험한 작업 감지
+    is_risky, operation_type = detect_risky_operation(tool_name, tool_args, cwd)
+
+    # 위험 감지 시 checkpoint 생성
+    if is_risky:
+        checkpoint_branch = create_checkpoint(cwd, operation_type)
+
+        if checkpoint_branch != "checkpoint-failed":
+            message = (
+                f"🛡️ Checkpoint created: {checkpoint_branch}\n"
+                f"   Operation: {operation_type}\n"
+                f"   Restore: /alfred:0-project restore"
+            )
+
+            return HookResult(message=message, blocked=False)
+
+    return HookResult(blocked=False)
+
+
+def handle_post_tool_use(payload: HookPayload) -> HookResult:
+    """PostToolUse 이벤트 핸들러 (기본 구현)"""
+    return HookResult()
+
+
+__all__ = ["handle_pre_tool_use", "handle_post_tool_use"]

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""User interaction handlers
+
+UserPromptSubmit 이벤트 처리
+"""
+
+from core import HookPayload, HookResult
+from core.context import get_jit_context
+
+
+def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
+    """UserPromptSubmit 이벤트 핸들러
+
+    사용자 프롬프트를 분석하여 관련 문서를 자동으로 컨텍스트에 추가합니다.
+    JIT (Just-in-Time) Retrieval 원칙에 따라 필요한 문서만 로드합니다.
+
+    Args:
+        payload: Claude Code 이벤트 페이로드
+                 (userPrompt, cwd 키 포함)
+
+    Returns:
+        HookResult(
+            message=로드된 파일 수 (또는 None),
+            contextFiles=추천 문서 경로 리스트
+        )
+
+    TDD History:
+        - RED: JIT 문서 로딩 시나리오 테스트
+        - GREEN: get_jit_context() 호출하여 문서 추천
+        - REFACTOR: 메시지 조건부 표시 (파일 있을 때만)
+    """
+    user_prompt = payload.get("userPrompt", "")
+    cwd = payload.get("cwd", ".")
+    context_files = get_jit_context(user_prompt, cwd)
+
+    message = f"📎 Loaded {len(context_files)} context file(s)" if context_files else None
+
+    return HookResult(message=message, contextFiles=context_files)
+
+
+__all__ = ["handle_user_prompt_submit"]