moai-adk 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+"""SessionStart Hook: Show Project Information
+
+Claude Code Event: SessionStart
+Purpose: Display project status, language, Git info, and SPEC progress when session starts
+Execution: Triggered automatically when Claude Code session begins
+
+Output: System message with formatted project summary
+"""
+
+import json
+import signal
+import sys
+from pathlib import Path
+from typing import Any
+
+# Setup import path for shared modules
+HOOKS_DIR = Path(__file__).parent
+SHARED_DIR = HOOKS_DIR / "shared"
+if str(SHARED_DIR) not in sys.path:
+    sys.path.insert(0, str(SHARED_DIR))
+
+from handlers import handle_session_start
+
+
+class HookTimeoutError(Exception):
+    """Hook execution timeout exception"""
+    pass
+
+
+def _timeout_handler(signum, frame):
+    """Signal handler for 5-second timeout"""
+    raise HookTimeoutError("Hook execution exceeded 5-second timeout")
+
+
+def main() -> None:
+    """Main entry point for SessionStart hook
+
+    Displays project information including:
+    - Programming language
+    - Git branch and status
+    - SPEC progress (completed/total)
+    - Recent checkpoints
+
+    Exit Codes:
+        0: Success
+        1: Error (timeout, JSON parse failure, handler exception)
+    """
+    # Set 5-second timeout
+    signal.signal(signal.SIGALRM, _timeout_handler)
+    signal.alarm(5)
+
+    try:
+        # Read JSON payload from stdin
+        input_data = sys.stdin.read()
+        data = json.loads(input_data) if input_data.strip() else {}
+
+        # Call handler
+        result = handle_session_start(data)
+
+        # Output result as JSON
+        print(json.dumps(result.to_dict()))
+        sys.exit(0)
+
+    except HookTimeoutError:
+        # Timeout - return minimal valid response
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "systemMessage": "⚠️ Session start timeout - continuing without project info"
+        }
+        print(json.dumps(timeout_response))
+        print("SessionStart hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"JSON parse error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"SessionStart JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"SessionStart error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"SessionStart unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        signal.alarm(0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -6,11 +6,15 @@ Project information inquiry (language, Git, SPEC progress, etc.)
 
 import json
 import signal
+import socket
 import subprocess
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
+# Cache directory for version check results
+CACHE_DIR_NAME = ".moai/cache"
+
 
 class TimeoutError(Exception):
     """Signal-based timeout exception"""
@@ -336,11 +340,184 @@ def get_project_language(cwd: str) -> str:
     return detect_language(cwd)
 
 
-def get_package_version_info() -> dict[str, Any]:
-    """Check MoAI-ADK current and latest version from PyPI
+# @CODE:CONFIG-INTEGRATION-001
+def get_version_check_config(cwd: str) -> dict[str, Any]:
+    """Read version check configuration from .moai/config.json
 
-    Compares the installed version with the latest version available on PyPI.
-    Returns version information for SessionStart hook to display update recommendations.
+    Returns version check settings with sensible defaults.
+    Supports frequency-based cache TTL configuration.
+
+    Args:
+        cwd: Project root directory path
+
+    Returns:
+        dict with keys:
+            - "enabled": Boolean (default: True)
+            - "frequency": "always" | "daily" | "weekly" | "never" (default: "daily")
+            - "cache_ttl_hours": TTL in hours based on frequency
+
+    Frequency to TTL mapping:
+        - "always": 0 hours (no caching)
+        - "daily": 24 hours
+        - "weekly": 168 hours (7 days)
+        - "never": infinity (never check)
+
+    TDD History:
+        - RED: 8 test scenarios (defaults, custom, disabled, TTL, etc.)
+        - GREEN: Minimal config reading with defaults
+        - REFACTOR: Add validation and error handling
+    """
+    # TTL mapping by frequency
+    TTL_BY_FREQUENCY = {
+        "always": 0,
+        "daily": 24,
+        "weekly": 168,
+        "never": float('inf')
+    }
+
+    # Default configuration
+    defaults = {
+        "enabled": True,
+        "frequency": "daily",
+        "cache_ttl_hours": 24
+    }
+
+    config_path = Path(cwd) / ".moai" / "config.json"
+    if not config_path.exists():
+        return defaults
+
+    try:
+        config = json.loads(config_path.read_text())
+
+        # Extract moai.version_check section
+        moai_config = config.get("moai", {})
+        version_check_config = moai_config.get("version_check", {})
+
+        # Read enabled flag (default: True)
+        enabled = version_check_config.get("enabled", defaults["enabled"])
+
+        # Read frequency (default: "daily")
+        frequency = moai_config.get("update_check_frequency", defaults["frequency"])
+
+        # Validate frequency
+        if frequency not in TTL_BY_FREQUENCY:
+            frequency = defaults["frequency"]
+
+        # Calculate TTL from frequency
+        cache_ttl_hours = TTL_BY_FREQUENCY[frequency]
+
+        # Allow explicit cache_ttl_hours override
+        if "cache_ttl_hours" in version_check_config:
+            cache_ttl_hours = version_check_config["cache_ttl_hours"]
+
+        return {
+            "enabled": enabled,
+            "frequency": frequency,
+            "cache_ttl_hours": cache_ttl_hours
+        }
+
+    except (OSError, json.JSONDecodeError, KeyError):
+        # Config read or parse error - return defaults
+        return defaults
+
+
+# @CODE:NETWORK-DETECT-001
+def is_network_available(timeout_seconds: float = 0.1) -> bool:
+    """Quick network availability check using socket.
+
+    Does NOT check PyPI specifically, just basic connectivity.
+    Returns immediately on success (< 50ms typically).
+    Returns False on any error without raising exceptions.
+
+    Args:
+        timeout_seconds: Socket timeout in seconds (default 0.1s)
+
+    Returns:
+        True if network appears available, False otherwise
+
+    Examples:
+        >>> is_network_available()
+        True  # Network is available
+        >>> is_network_available(timeout_seconds=0.001)
+        False  # Timeout too short, returns False
+
+    TDD History:
+        - RED: 3 test scenarios (success, failure, timeout)
+        - GREEN: Minimal socket.create_connection implementation
+        - REFACTOR: Add error handling for all exception types
+    """
+    try:
+        # Try connecting to Google's public DNS server (8.8.8.8:53)
+        # This is a reliable host that's typically reachable
+        connection = socket.create_connection(("8.8.8.8", 53), timeout=timeout_seconds)
+        connection.close()
+        return True
+    except (socket.timeout, OSError, Exception):
+        # Any connection error means network is unavailable
+        # This includes: timeout, connection refused, network unreachable, etc.
+        return False
+
+
+# @CODE:VERSION-DETECT-MAJOR-001
+def is_major_version_change(current: str, latest: str) -> bool:
+    """Detect if version change is a major version bump.
+
+    A major version change is when the first (major) component increases:
+    - 0.8.1 → 1.0.0: True (0 → 1)
+    - 1.2.3 → 2.0.0: True (1 → 2)
+    - 0.8.1 → 0.9.0: False (0 → 0, minor changed)
+    - 1.2.3 → 1.3.0: False (1 → 1)
+
+    Args:
+        current: Current version string (e.g., "0.8.1")
+        latest: Latest version string (e.g., "1.0.0")
+
+    Returns:
+        True if major version increased, False otherwise
+
+    Examples:
+        >>> is_major_version_change("0.8.1", "1.0.0")
+        True
+        >>> is_major_version_change("0.8.1", "0.9.0")
+        False
+        >>> is_major_version_change("dev", "1.0.0")
+        False  # Invalid versions return False
+
+    TDD History:
+        - RED: 4 test scenarios (0→1, 1→2, minor, invalid)
+        - GREEN: Minimal version parsing and comparison
+        - REFACTOR: Improve error handling for invalid versions
+    """
+    try:
+        # Parse version strings into integer components
+        current_parts = [int(x) for x in current.split(".")]
+        latest_parts = [int(x) for x in latest.split(".")]
+
+        # Compare major version (first component)
+        if len(current_parts) >= 1 and len(latest_parts) >= 1:
+            return latest_parts[0] > current_parts[0]
+
+        # If parsing succeeds but empty, no major change
+        return False
+
+    except (ValueError, AttributeError, IndexError):
+        # Invalid version format - return False (no exception)
+        return False
+
+
+# @CODE:VERSION-CACHE-INTEGRATION-001
+def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
+    """Check MoAI-ADK current and latest version with caching and offline support.
+
+    Execution flow:
+    1. Try to load from cache (< 50ms)
+    2. If cache invalid, check network
+    3. If network available, query PyPI
+    4. If network unavailable, return current version only
+    5. Save result to cache for next time
+
+    Args:
+        cwd: Project root directory (for cache location)
 
     Returns:
         dict with keys:
@@ -348,44 +525,121 @@ def get_package_version_info() -> dict[str, Any]:
             - "latest": Latest version available on PyPI
             - "update_available": Boolean indicating if update is available
             - "upgrade_command": Recommended upgrade command (if update available)
+            - "release_notes_url": URL to release notes (Phase 3)
+            - "is_major_update": Boolean indicating major version change (Phase 3)
 
     Note:
-        - Has 1-second timeout to avoid blocking SessionStart
-        - Returns graceful fallback if PyPI check fails
-        - Handles version parsing gracefully
+        - Cache hit (< 24 hours): Returns in ~20ms, no network access
+        - Cache miss + online: Query PyPI (1s timeout), cache result
+        - Cache miss + offline: Return current version only (~100ms)
+        - Offline + cached: Return from cache in ~20ms
+
+    TDD History:
+        - RED: 5 test scenarios (network detection, cache integration, offline mode)
+        - GREEN: Integrate VersionCache with network detection
+        - REFACTOR: Extract cache directory constant, improve error handling
+        - Phase 3: Add release_notes_url and is_major_update fields (@CODE:VERSION-INTEGRATE-FIELDS-001)
     """
+    import importlib.util
     import urllib.error
     import urllib.request
     from importlib.metadata import PackageNotFoundError, version
 
+    # Import VersionCache from the same directory (using dynamic import for testing compatibility)
+    try:
+        version_cache_path = Path(__file__).parent / "version_cache.py"
+        spec = importlib.util.spec_from_file_location("version_cache", version_cache_path)
+        if spec and spec.loader:
+            version_cache_module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(version_cache_module)
+            VersionCache = version_cache_module.VersionCache
+        else:
+            # Skip caching if module can't be loaded
+            VersionCache = None
+    except (ImportError, OSError):
+        # Graceful degradation: skip caching on import errors
+        VersionCache = None
+
+    # 1. Initialize cache (skip if VersionCache couldn't be imported)
+    cache_dir = Path(cwd) / CACHE_DIR_NAME
+    version_cache = VersionCache(cache_dir) if VersionCache else None
+
+    # 2. Get current installed version first (needed for cache validation)
+    current_version = "unknown"
+    try:
+        current_version = version("moai-adk")
+    except PackageNotFoundError:
+        current_version = "dev"
+        # Dev mode - skip cache and return immediately
+        return {
+            "current": "dev",
+            "latest": "unknown",
+            "update_available": False,
+            "upgrade_command": ""
+        }
+
+    # 3. Try to load from cache (fast path with version validation)
+    if version_cache and version_cache.is_valid():
+        cached_info = version_cache.load()
+        if cached_info:
+            # Only use cache if the cached version matches current installed version
+            # This prevents stale cache when package is upgraded locally
+            if cached_info.get("current") == current_version:
+                # Ensure new fields exist for backward compatibility
+                if "release_notes_url" not in cached_info:
+                    # Add missing fields to old cached data
+                    cached_info.setdefault("release_notes_url", None)
+                    cached_info.setdefault("is_major_update", False)
+                return cached_info
+            # else: cache is stale (version changed), fall through to re-check
+
+    # 4. Cache miss or stale - need to query PyPI
     result = {
-        "current": "unknown",
+        "current": current_version,
         "latest": "unknown",
         "update_available": False,
         "upgrade_command": ""
     }
 
-    # Get current version
-    try:
-        result["current"] = version("moai-adk")
-    except PackageNotFoundError:
-        result["current"] = "dev"
+    # 5. Check if version check is enabled in config
+    config = get_version_check_config(cwd)
+    if not config["enabled"]:
+        # Version check disabled - return only current version
+        return result
+
+    # 6. Check network before PyPI query
+    if not is_network_available():
+        # Offline mode - return current version only
         return result
 
-    # Get latest version from PyPI (with 1-second timeout)
+    # 7. Network available - query PyPI
+    pypi_data = None
     try:
         with timeout_handler(1):
             url = "https://pypi.org/pypi/moai-adk/json"
             headers = {"Accept": "application/json"}
             req = urllib.request.Request(url, headers=headers)
             with urllib.request.urlopen(req, timeout=0.8) as response:
-                data = json.load(response)
-                result["latest"] = data.get("info", {}).get("version", "unknown")
+                pypi_data = json.load(response)
+                result["latest"] = pypi_data.get("info", {}).get("version", "unknown")
+
+                # Extract release notes URL from project_urls
+                try:
+                    project_urls = pypi_data.get("info", {}).get("project_urls", {})
+                    release_url = project_urls.get("Changelog", "")
+                    if not release_url:
+                        # Fallback to GitHub releases URL pattern
+                        release_url = f"https://github.com/modu-ai/moai-adk/releases/tag/v{result['latest']}"
+                    result["release_notes_url"] = release_url
+                except (KeyError, AttributeError, TypeError):
+                    result["release_notes_url"] = None
+
     except (urllib.error.URLError, TimeoutError, Exception):
-        # Network error or timeout - return with unknown latest version
-        return result
+        # PyPI query failed - return current version
+        result["release_notes_url"] = None
+        pass
 
-    # Compare versions (simple comparison)
+    # 7. Compare versions (simple comparison)
     if result["current"] != "unknown" and result["latest"] != "unknown":
         try:
             # Parse versions for comparison
@@ -400,10 +654,20 @@ def get_package_version_info() -> dict[str, Any]:
             if latest_parts > current_parts:
                 result["update_available"] = True
                 result["upgrade_command"] = f"uv pip install --upgrade moai-adk>={result['latest']}"
+
+                # Detect major version change
+                result["is_major_update"] = is_major_version_change(result["current"], result["latest"])
+            else:
+                result["is_major_update"] = False
         except (ValueError, AttributeError):
             # Version parsing failed - skip comparison
+            result["is_major_update"] = False
             pass
 
+    # 8. Save result to cache (if caching is available)
+    if version_cache:
+        version_cache.save(result)
+
     return result
 
 
@@ -412,5 +676,8 @@ __all__ = [
     "get_git_info",
     "count_specs",
     "get_project_language",
+    "get_version_check_config",
+    "is_network_available",
+    "is_major_version_change",
     "get_package_version_info",
 ]

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"]