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

moai_adk/templates/.claude/hooks/alfred/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 = 24):
+        """Initialize cache with TTL in hours
+
+        Args:
+            cache_dir: Directory where cache file will be stored
+            ttl_hours: Time-to-live in hours (default 24)
+        """
+        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) as e:
+            # 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/notification__handle_events.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+"""Notification Hook: Handle System Notifications
+
+Claude Code Event: Notification
+Purpose: Process system notifications and alerts from Claude Code
+Execution: Triggered when Claude Code sends notification events
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+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_notification
+
+
+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 Notification hook
+
+    Currently a stub for future functionality:
+    - Filter and categorize notifications
+    - Send alerts to external systems (Slack, email)
+    - Log important events
+    - Trigger automated responses
+
+    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_notification(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": "⚠️ Notification handler timeout"
+        }
+        print(json.dumps(timeout_response))
+        print("Notification 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"Notification 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"Notification error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"Notification 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/post_tool__log_changes.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+"""PostToolUse Hook: Log Tool Usage and Changes
+
+Claude Code Event: PostToolUse
+Purpose: Log tool execution results and track changes for audit trail
+Execution: Triggered after Edit, Write, or MultiEdit tools are used
+Matcher: Edit|Write|MultiEdit
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+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_post_tool_use
+
+
+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 PostToolUse hook
+
+    Currently a stub for future functionality:
+    - Change tracking and audit logging
+    - Metrics collection (files modified, lines changed)
+    - Integration with external monitoring systems
+
+    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_post_tool_use(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": "⚠️ PostToolUse timeout - continuing"
+        }
+        print(json.dumps(timeout_response))
+        print("PostToolUse 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"PostToolUse 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"PostToolUse error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"PostToolUse 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/pre_tool__auto_checkpoint.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+"""PreToolUse Hook: Automatic Safety Checkpoint Creation
+
+Claude Code Event: PreToolUse
+Purpose: Detect risky operations and automatically create Git checkpoints before execution
+Execution: Triggered before Edit, Write, or MultiEdit tools are used
+Matcher: Edit|Write|MultiEdit
+
+Output: System message with checkpoint information (if created)
+
+Risky Operations Detected:
+- Bash: rm -rf, git merge, git reset --hard
+- Edit/Write: CLAUDE.md, config.json, critical files
+- MultiEdit: Operations affecting ≥10 files
+"""
+
+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_pre_tool_use
+
+
+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 PreToolUse hook
+
+    Analyzes tool usage and creates checkpoints for risky operations:
+    1. Detects dangerous patterns (rm -rf, git reset, etc.)
+    2. Creates Git checkpoint: checkpoint/before-{operation}-{timestamp}
+    3. Logs checkpoint to .moai/checkpoints.log
+    4. Returns guidance message to user
+
+    Exit Codes:
+        0: Success (checkpoint created or not needed)
+        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_pre_tool_use(data)
+
+        # Output result as JSON
+        print(json.dumps(result.to_dict()))
+        sys.exit(0)
+
+    except HookTimeoutError:
+        # Timeout - return minimal valid response (allow operation to continue)
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "systemMessage": "⚠️ Checkpoint creation timeout - operation proceeding without checkpoint"
+        }
+        print(json.dumps(timeout_response))
+        print("PreToolUse hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error - allow operation to continue
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"JSON parse error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"PreToolUse JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error - allow operation to continue
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"PreToolUse error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"PreToolUse 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/session_end__cleanup.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+"""SessionEnd Hook: Session Cleanup and Finalization
+
+Claude Code Event: SessionEnd
+Purpose: Clean up resources and finalize session when Claude Code exits
+Execution: Triggered when Claude Code session ends
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+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_end
+
+
+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 SessionEnd hook
+
+    Currently a stub for future functionality:
+    - Clear temporary caches
+    - Save session metrics
+    - Upload analytics (if enabled)
+    - Cleanup background processes
+
+    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_end(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": "⚠️ SessionEnd cleanup timeout - session ending anyway"
+        }
+        print(json.dumps(timeout_response))
+        print("SessionEnd 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"SessionEnd 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"SessionEnd error: {e}"}
+        }
+        print(json.dumps(error_response))
+        print(f"SessionEnd unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        signal.alarm(0)
+
+
+if __name__ == "__main__":
+    main()