moai-adk 0.8.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/tags.py

@@ -38,9 +38,22 @@ from pathlib import Path
 from typing import Iterable, List, Optional
 
 DEFAULT_CODE_EXTS = (
-    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs",
-    ".java", ".kt", ".rb", ".php", ".c", ".cpp", ".cs",
-    ".swift", ".scala"
+    ".py",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".rb",
+    ".php",
+    ".c",
+    ".cpp",
+    ".cs",
+    ".swift",
+    ".scala",
 )
 
 
@@ -88,35 +101,49 @@ def _load_rules(cwd: str) -> List[Rule]:
 
     # Defaults (ordered)
     return [
-        Rule(
-            include=[".moai/specs/**", "**/SPEC-*/spec.md"],
-            expect="@SPEC:",
-            exclude=[]
-        ),
+        Rule(include=[".moai/specs/**", "**/SPEC-*/spec.md"], expect="@SPEC:", exclude=[]),
         Rule(
             include=[
-                "**/*_test.py", "**/test_*.py", "**/*.test.ts",
-                "**/*.test.tsx", "**/*.test.js", "**/*.test.jsx",
-                "**/*.test.go", "**/*.test.rs", "**/*.spec.ts",
-                "**/*.spec.tsx", "tests/**"
+                "**/*_test.py",
+                "**/test_*.py",
+                "**/*.test.ts",
+                "**/*.test.tsx",
+                "**/*.test.js",
+                "**/*.test.jsx",
+                "**/*.test.go",
+                "**/*.test.rs",
+                "**/*.spec.ts",
+                "**/*.spec.tsx",
+                "tests/**",
             ],
             expect="@TEST:",
-            exclude=[".claude/**"]
+            exclude=[".claude/**"],
         ),
         Rule(
             include=["docs/**/*.md", "**/README.md", "**/*.api.md"],
             expect="@DOC:",
-            exclude=[".claude/**"]
+            exclude=[".claude/**"],
         ),
         Rule(
             include=["**/*"],
             expect="@CODE:",
             exclude=[
-                "tests/**", "docs/**", ".moai/**", ".claude/**",
-                "**/*.md", "**/*.json", "**/*.yml", "**/*.yaml",
-                "**/*.toml", "**/*.lock", "**/*.svg", "**/*.png",
-                "**/*.jpg", "**/*.jpeg", "**/*.gif"
-            ]
+                "tests/**",
+                "docs/**",
+                ".moai/**",
+                ".claude/**",
+                "**/*.md",
+                "**/*.json",
+                "**/*.yml",
+                "**/*.yaml",
+                "**/*.toml",
+                "**/*.lock",
+                "**/*.svg",
+                "**/*.png",
+                "**/*.jpg",
+                "**/*.jpeg",
+                "**/*.gif",
+            ],
         ),
     ]
 
@@ -147,17 +174,22 @@ def _iter_recent_changes(cwd: str) -> Iterable[Path]:
         # Staged files
         r1 = subprocess.run(
             ["git", "diff", "--name-only", "--cached"],
-            cwd=cwd, capture_output=True, text=True, timeout=1
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=1,
         )
         # Modified (unstaged) tracked files
         r2 = subprocess.run(
-            ["git", "ls-files", "-m"],
-            cwd=cwd, capture_output=True, text=True, timeout=1
+            ["git", "ls-files", "-m"], cwd=cwd, capture_output=True, text=True, timeout=1
         )
         # Untracked (other) files respecting .gitignore
         r3 = subprocess.run(
             ["git", "ls-files", "-o", "--exclude-standard"],
-            cwd=cwd, capture_output=True, text=True, timeout=1
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=1,
         )
         names = set()
         if r1.returncode == 0:

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

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

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

@@ -0,0 +1,154 @@
+#!/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/{handlers → shared/handlers}/session.py

@@ -6,7 +6,7 @@ SessionStart, SessionEnd event handling
 
 from core import HookPayload, HookResult
 from core.checkpoint import list_checkpoints
-from core.project import count_specs, detect_language, get_git_info, get_package_version_info
+from core.project import count_specs, get_git_info, get_package_version_info
 
 
 def handle_session_start(payload: HookPayload) -> HookResult:
@@ -25,14 +25,14 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     Message Format:
         🚀 MoAI-ADK Session Started
-           Language: {language}
+           [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:
-        - CRITICAL: Language detection (must succeed - no try-except)
+        - 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)
@@ -51,9 +51,11 @@ def handle_session_start(payload: HookPayload) -> HookResult:
         - 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
@@ -64,9 +66,6 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     cwd = payload.get("cwd", ".")
 
-    # CRITICAL: Language detection - MUST succeed (no try-except)
-    language = detect_language(cwd)
-
     # OPTIONAL: Git info - skip if timeout/failure
     git_info = {}
     try:
@@ -113,17 +112,31 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     # Add version info first (at the top, right after title)
     if version_info and version_info.get("current") != "unknown":
-        version_line = f"   🗿 MoAI-ADK Ver: {version_info['current']}"
         if version_info.get("update_available"):
-            version_line += f" → {version_info['latest']} available ✨"
-        lines.append(version_line)
-
-        # Add upgrade recommendation if update is available
-        if version_info.get("update_available") and version_info.get("upgrade_command"):
-            lines.append(f"   ⬆️ Upgrade: {version_info['upgrade_command']}")
+            # 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 language info
-    lines.append(f"   🐍 Language: {language}")
 
     # Add Git info only if available (not degraded)
     if git_info:

moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/tool.py

@@ -54,8 +54,7 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
             checkpoint_branch = create_checkpoint(cwd, operation_type)
             if checkpoint_branch != "checkpoint-failed":
                 system_message = (
-                    f"🛡️ Checkpoint created: {checkpoint_branch}\n"
-                    f"   Operation: {operation_type}"
+                    f"🛡️ Checkpoint created: {checkpoint_branch}\n   Operation: {operation_type}"
                 )
                 return HookResult(system_message=system_message, continue_execution=True)
     except Exception:
@@ -66,10 +65,8 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
     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}건 더 존재)"
+        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"

moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/user.py

@@ -4,6 +4,9 @@
 Handling the UserPromptSubmit event
 """
 
+from datetime import datetime
+from pathlib import Path
+
 from core import HookPayload, HookResult
 from core.context import get_jit_context
 
@@ -29,11 +32,27 @@ def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
         - 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)