moai-adk 0.15.1__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/shared/core/version_cache.py

@@ -1,198 +0,0 @@
-#!/usr/bin/env python3
-# @CODE:VERSION-CACHE-001
-"""Version information cache with TTL support
-
-TTL-based caching system for version check results to minimize network calls
-during SessionStart hook execution.
-
-SPEC: SPEC-UPDATE-ENHANCE-001 - SessionStart 버전 체크 시스템 강화
-Phase 1: Cache System Implementation
-"""
-
-import json
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-
-class VersionCache:
-    """TTL-based version information cache
-
-    Caches version check results with configurable Time-To-Live (TTL)
-    to avoid excessive network calls to PyPI during SessionStart events.
-
-    Attributes:
-        cache_dir: Directory to store cache file
-        ttl_hours: Time-to-live in hours (default 24)
-        cache_file: Path to the cache JSON file
-
-    Examples:
-        >>> cache = VersionCache(Path(".moai/cache"), ttl_hours=24)
-        >>> cache.save({"current_version": "0.8.1", "latest_version": "0.9.0"})
-        True
-        >>> cache.is_valid()
-        True
-        >>> data = cache.load()
-        >>> data["current_version"]
-        '0.8.1'
-    """
-
-    def __init__(self, cache_dir: Path, ttl_hours: int = 4):
-        """Initialize cache with TTL in hours
-
-        Args:
-            cache_dir: Directory where cache file will be stored
-            ttl_hours: Time-to-live in hours (default 4)
-        """
-        self.cache_dir = Path(cache_dir)
-        self.ttl_hours = ttl_hours
-        self.cache_file = self.cache_dir / "version-check.json"
-
-    def _calculate_age_hours(self, last_check_iso: str) -> float:
-        """Calculate age in hours from ISO timestamp (internal helper)
-
-        Normalizes timezone-aware and naive datetimes for consistent comparison.
-
-        Args:
-            last_check_iso: ISO format timestamp string
-
-        Returns:
-            Age in hours
-
-        Raises:
-            ValueError: If timestamp parsing fails
-        """
-        last_check = datetime.fromisoformat(last_check_iso)
-
-        # Normalize to naive datetime (remove timezone for comparison)
-        if last_check.tzinfo is not None:
-            last_check = last_check.replace(tzinfo=None)
-
-        now = datetime.now()
-        return (now - last_check).total_seconds() / 3600
-
-    def is_valid(self) -> bool:
-        """Check if cache exists and is not expired
-
-        Returns:
-            True if cache file exists and is within TTL, False otherwise
-
-        Examples:
-            >>> cache = VersionCache(Path(".moai/cache"))
-            >>> cache.is_valid()
-            False  # No cache file exists yet
-        """
-        if not self.cache_file.exists():
-            return False
-
-        try:
-            with open(self.cache_file, "r") as f:
-                data = json.load(f)
-
-            age_hours = self._calculate_age_hours(data["last_check"])
-            return age_hours < self.ttl_hours
-
-        except (json.JSONDecodeError, KeyError, ValueError, OSError):
-            # Corrupted or invalid cache file
-            return False
-
-    def load(self) -> dict[str, Any] | None:
-        """Load cached version info if valid
-
-        Returns:
-            Cached version info dictionary if valid, None otherwise
-
-        Examples:
-            >>> cache = VersionCache(Path(".moai/cache"))
-            >>> data = cache.load()
-            >>> data is None
-            True  # No valid cache exists
-        """
-        if not self.is_valid():
-            return None
-
-        try:
-            with open(self.cache_file, "r") as f:
-                return json.load(f)
-        except (json.JSONDecodeError, OSError):
-            # Graceful degradation on read errors
-            return None
-
-    def save(self, version_info: dict[str, Any]) -> bool:
-        """Save version info to cache file
-
-        Creates cache directory if it doesn't exist.
-        Updates last_check timestamp to current time if not provided.
-
-        Args:
-            version_info: Version information dictionary to cache
-
-        Returns:
-            True on successful save, False on error
-
-        Examples:
-            >>> cache = VersionCache(Path(".moai/cache"))
-            >>> cache.save({"current_version": "0.8.1"})
-            True
-        """
-        try:
-            # Create cache directory if it doesn't exist
-            self.cache_dir.mkdir(parents=True, exist_ok=True)
-
-            # Update last_check timestamp only if not provided (for testing)
-            if "last_check" not in version_info:
-                version_info["last_check"] = datetime.now(timezone.utc).isoformat()
-
-            # Write to cache file
-            with open(self.cache_file, "w") as f:
-                json.dump(version_info, f, indent=2)
-
-            return True
-
-        except (OSError, TypeError):
-            # Graceful degradation on write errors
-            return False
-
-    def clear(self) -> bool:
-        """Clear/remove cache file
-
-        Returns:
-            True if cache file was removed or didn't exist, False on error
-
-        Examples:
-            >>> cache = VersionCache(Path(".moai/cache"))
-            >>> cache.clear()
-            True
-        """
-        try:
-            if self.cache_file.exists():
-                self.cache_file.unlink()
-            return True
-        except OSError:
-            return False
-
-    def get_age_hours(self) -> float:
-        """Get age of cache in hours
-
-        Returns:
-            Age in hours, or 0.0 if cache doesn't exist or is invalid
-
-        Examples:
-            >>> cache = VersionCache(Path(".moai/cache"))
-            >>> cache.get_age_hours()
-            0.0  # No cache exists
-        """
-        if not self.cache_file.exists():
-            return 0.0
-
-        try:
-            with open(self.cache_file, "r") as f:
-                data = json.load(f)
-
-            return self._calculate_age_hours(data["last_check"])
-
-        except (json.JSONDecodeError, KeyError, ValueError, OSError):
-            return 0.0
-
-
-__all__ = ["VersionCache"]

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

@@ -1,21 +0,0 @@
-#!/usr/bin/env python3
-"""Event handlers for Alfred Hooks
-
-Claude Code Event Handlers
-"""
-
-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/shared/handlers/notification.py

@@ -1,154 +0,0 @@
-#!/usr/bin/env python3
-"""Notification and control handlers
-
-Notification, Stop, SubagentStop event handling
-"""
-
-import json
-from datetime import datetime
-from pathlib import Path
-
-from core import HookPayload, HookResult
-
-
-def _get_command_state_file(cwd: str) -> Path:
-    """Get the path to command state tracking file"""
-    state_dir = Path(cwd) / ".moai" / "memory"
-    state_dir.mkdir(parents=True, exist_ok=True)
-    return state_dir / "command-execution-state.json"
-
-
-def _load_command_state(cwd: str) -> dict:
-    """Load current command execution state"""
-    try:
-        state_file = _get_command_state_file(cwd)
-        if state_file.exists():
-            with open(state_file, "r", encoding="utf-8") as f:
-                return json.load(f)
-    except Exception:
-        pass
-    return {"last_command": None, "last_timestamp": None, "is_running": False}
-
-
-def _save_command_state(cwd: str, state: dict) -> None:
-    """Save command execution state"""
-    try:
-        state_file = _get_command_state_file(cwd)
-        with open(state_file, "w", encoding="utf-8") as f:
-            json.dump(state, f, indent=2)
-    except Exception:
-        pass
-
-
-def _is_duplicate_command(current_cmd: str, last_cmd: str, last_timestamp: str) -> bool:
-    """Check if current command is a duplicate of the last one within 3 seconds"""
-    if not last_cmd or not last_timestamp or current_cmd != last_cmd:
-        return False
-
-    try:
-        last_time = datetime.fromisoformat(last_timestamp)
-        current_time = datetime.now()
-        time_diff = (current_time - last_time).total_seconds()
-        # Consider it a duplicate if same command within 3 seconds
-        return time_diff < 3
-    except Exception:
-        return False
-
-
-def handle_notification(payload: HookPayload) -> HookResult:
-    """Notification event handler
-
-    Detects and warns about duplicate command executions
-    (When the same /alfred: command is triggered multiple times within 3 seconds)
-    """
-    cwd = payload.get("cwd", ".")
-    notification = payload.get("notification", {})
-
-    # Extract command information from notification
-    current_cmd = None
-    if isinstance(notification, dict):
-        # Check if notification contains command information
-        text = notification.get("text", "") or str(notification)
-        if "/alfred:" in text:
-            # Extract /alfred: command
-            import re
-
-            match = re.search(r"/alfred:\S+", text)
-            if match:
-                current_cmd = match.group()
-
-    if not current_cmd:
-        return HookResult()
-
-    # Load current state
-    state = _load_command_state(cwd)
-    last_cmd = state.get("last_command")
-    last_timestamp = state.get("last_timestamp")
-
-    # Check for duplicate
-    if _is_duplicate_command(current_cmd, last_cmd, last_timestamp):
-        warning_msg = (
-            f"⚠️ Duplicate command detected: '{current_cmd}' "
-            f"is running multiple times within 3 seconds.\n"
-            f"This may indicate a system issue. Check logs in `.moai/logs/command-invocations.log`"
-        )
-
-        # Update state - mark as duplicate detected
-        state["duplicate_detected"] = True
-        state["duplicate_command"] = current_cmd
-        state["duplicate_timestamp"] = datetime.now().isoformat()
-        _save_command_state(cwd, state)
-
-        return HookResult(system_message=warning_msg, continue_execution=True)
-
-    # Update state with current command
-    state["last_command"] = current_cmd
-    state["last_timestamp"] = datetime.now().isoformat()
-    state["is_running"] = True
-    state["duplicate_detected"] = False
-    _save_command_state(cwd, state)
-
-    return HookResult()
-
-
-def handle_stop(payload: HookPayload) -> HookResult:
-    """Stop event handler
-
-    Marks command execution as complete
-    """
-    cwd = payload.get("cwd", ".")
-    state = _load_command_state(cwd)
-    state["is_running"] = False
-    state["last_timestamp"] = datetime.now().isoformat()
-    _save_command_state(cwd, state)
-
-    return HookResult()
-
-
-def handle_subagent_stop(payload: HookPayload) -> HookResult:
-    """SubagentStop event handler
-
-    Records when a sub-agent finishes execution
-    """
-    cwd = payload.get("cwd", ".")
-
-    # Extract subagent name if available
-    subagent_name = (
-        payload.get("subagent", {}).get("name")
-        if isinstance(payload.get("subagent"), dict)
-        else None
-    )
-
-    try:
-        state_file = _get_command_state_file(cwd).parent / "subagent-execution.log"
-        timestamp = datetime.now().isoformat()
-
-        with open(state_file, "a", encoding="utf-8") as f:
-            f.write(f"{timestamp} | Subagent Stop | {subagent_name}\n")
-    except Exception:
-        pass
-
-    return HookResult()
-
-
-__all__ = ["handle_notification", "handle_stop", "handle_subagent_stop"]

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

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

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

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