claude-mpm 4.1.2__py3-none-any.whl → 4.1.3__py3-none-any.whl

claude_mpm/services/cli/startup_checker.py

@@ -0,0 +1,370 @@
+"""Startup checking service for CLI commands.
+
+WHY: This service extracts startup validation logic from run.py to improve
+separation of concerns, testability, and reusability across CLI commands.
+
+DESIGN DECISIONS:
+- Interface-based design for dependency injection
+- Single responsibility: startup validation only
+- Returns structured warnings for better handling
+- Non-blocking: warns but doesn't prevent execution
+- Reusable across multiple CLI commands
+"""
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from claude_mpm.core.logger import get_logger
+
+
+# Interface Definition
+class IStartupChecker(ABC):
+    """Interface for startup checking service."""
+
+    @abstractmethod
+    def check_configuration(self) -> List["StartupWarning"]:
+        """Validate configuration and return warnings."""
+
+    @abstractmethod
+    def check_memory(self, resume_enabled: bool = False) -> Optional["StartupWarning"]:
+        """Check Claude.json memory usage."""
+
+    @abstractmethod
+    def check_environment(self) -> List["StartupWarning"]:
+        """Validate environment and paths."""
+
+    @abstractmethod
+    def get_startup_warnings(
+        self, resume_enabled: bool = False
+    ) -> List["StartupWarning"]:
+        """Collect all startup warnings."""
+
+
+@dataclass
+class StartupWarning:
+    """Structured warning information."""
+
+    category: str  # 'config', 'memory', 'environment'
+    message: str
+    suggestion: Optional[str] = None
+    severity: str = "warning"  # 'info', 'warning', 'error'
+
+
+class StartupCheckerService(IStartupChecker):
+    """Service for startup validation and health checks."""
+
+    def __init__(self, config_service):
+        """Initialize the startup checker.
+
+        Args:
+            config_service: Configuration service instance (IConfigurationService)
+        """
+        self.config_service = config_service
+        self.logger = get_logger("StartupChecker")
+
+    def check_configuration(self) -> List[StartupWarning]:
+        """Validate configuration and return warnings.
+
+        Checks:
+        - Response logging directory exists and is writable
+        - Agent deployment configuration
+        - Memory management configuration
+        - Common configuration issues
+
+        Returns:
+            List of configuration warnings
+        """
+        warnings = []
+
+        try:
+            # Check response logging configuration
+            response_logging = self.config_service.get("response_logging", {})
+            if response_logging.get("enabled", False):
+                log_dir = response_logging.get("directory")
+                if log_dir:
+                    warnings.extend(self._check_log_directory(log_dir))
+
+            # Check memory management configuration
+            memory_config = self.config_service.get("memory_management", {})
+            if memory_config.get("auto_cleanup", False):
+                cleanup_threshold = memory_config.get("cleanup_threshold_mb", 100)
+                if cleanup_threshold < 50:
+                    warnings.append(
+                        StartupWarning(
+                            category="config",
+                            message=f"Memory cleanup threshold very low: {cleanup_threshold}MB",
+                            suggestion="Consider increasing to at least 50MB",
+                            severity="warning",
+                        )
+                    )
+
+            # Check for deprecated configuration keys
+            warnings.extend(self._check_deprecated_keys())
+
+            # Check configuration file access
+            warnings.extend(self._check_config_file_access())
+
+        except Exception as e:
+            self.logger.warning(f"Configuration check failed: {e}")
+            warnings.append(
+                StartupWarning(
+                    category="config",
+                    message=f"Configuration check failed: {e}",
+                    severity="info",
+                )
+            )
+
+        return warnings
+
+    def check_memory(self, resume_enabled: bool = False) -> Optional[StartupWarning]:
+        """Check .claude.json memory usage.
+
+        WHY: Large .claude.json files (>500KB) cause significant memory issues
+        when using --resume. Claude Code loads the entire conversation history
+        into memory, leading to 2GB+ memory consumption.
+
+        Args:
+            resume_enabled: Whether --mpm-resume is being used
+
+        Returns:
+            Warning if memory issue detected, None otherwise
+        """
+        if not resume_enabled:
+            return None
+
+        try:
+            claude_json_path = Path.cwd() / ".claude.json"
+            if not claude_json_path.exists():
+                self.logger.debug("No .claude.json file found")
+                return None
+
+            file_size = claude_json_path.stat().st_size
+
+            # Only warn if file is larger than 500KB
+            if file_size > 500 * 1024:
+                formatted_size = self._format_file_size(file_size)
+                return StartupWarning(
+                    category="memory",
+                    message=f"Large .claude.json file detected ({formatted_size})",
+                    suggestion="Consider running 'claude-mpm cleanup-memory' to archive old conversations",
+                    severity="warning",
+                )
+
+            self.logger.info(f".claude.json size: {self._format_file_size(file_size)}")
+
+        except Exception as e:
+            self.logger.warning(f"Failed to check .claude.json size: {e}")
+
+        return None
+
+    def check_environment(self) -> List[StartupWarning]:
+        """Validate environment and paths.
+
+        Checks:
+        - Python version compatibility
+        - Virtual environment activation
+        - Required directories exist
+        - File permissions
+
+        Returns:
+            List of environment warnings
+        """
+        warnings = []
+
+        try:
+            # Check Python version
+            import sys
+
+            if sys.version_info < (3, 8):
+                warnings.append(
+                    StartupWarning(
+                        category="environment",
+                        message=f"Python {sys.version_info.major}.{sys.version_info.minor} detected",
+                        suggestion="Python 3.8+ is recommended for optimal performance",
+                        severity="info",
+                    )
+                )
+
+            # Check for common missing directories
+            warnings.extend(self._check_required_directories())
+
+        except Exception as e:
+            self.logger.warning(f"Environment check failed: {e}")
+            warnings.append(
+                StartupWarning(
+                    category="environment",
+                    message=f"Environment check failed: {e}",
+                    severity="info",
+                )
+            )
+
+        return warnings
+
+    def get_startup_warnings(
+        self, resume_enabled: bool = False
+    ) -> List[StartupWarning]:
+        """Collect all startup warnings.
+
+        Args:
+            resume_enabled: Whether --mpm-resume is being used
+
+        Returns:
+            Complete list of startup warnings
+        """
+        all_warnings = []
+
+        # Collect configuration warnings
+        all_warnings.extend(self.check_configuration())
+
+        # Check memory if resume is enabled
+        memory_warning = self.check_memory(resume_enabled)
+        if memory_warning:
+            all_warnings.append(memory_warning)
+
+        # Collect environment warnings
+        all_warnings.extend(self.check_environment())
+
+        return all_warnings
+
+    def display_warnings(self, warnings: List[StartupWarning]) -> None:
+        """Display warnings to the user.
+
+        Args:
+            warnings: List of warnings to display
+        """
+        if not warnings:
+            return
+
+        # Group warnings by severity
+        errors = [w for w in warnings if w.severity == "error"]
+        warnings_list = [w for w in warnings if w.severity == "warning"]
+        info = [w for w in warnings if w.severity == "info"]
+
+        # Display errors first
+        for warning in errors:
+            print(f"❌ {warning.message}")
+            if warning.suggestion:
+                print(f"   {warning.suggestion}")
+
+        # Display warnings
+        for warning in warnings_list:
+            print(f"⚠️  {warning.message}")
+            if warning.suggestion:
+                print(f"   💡 {warning.suggestion}")
+
+        # Display info last
+        for warning in info:
+            print(f"ℹ️  {warning.message}")
+            if warning.suggestion:
+                print(f"   {warning.suggestion}")
+
+        if errors or warnings_list:
+            print()  # Add spacing after warnings
+
+    # Private helper methods
+
+    def _check_log_directory(self, log_dir: str) -> List[StartupWarning]:
+        """Check if log directory exists and is writable."""
+        warnings = []
+        log_path = Path(log_dir)
+
+        if not log_path.exists():
+            warnings.append(
+                StartupWarning(
+                    category="config",
+                    message=f"Response logging directory does not exist: {log_path}",
+                    suggestion=f"Run: mkdir -p {log_path}",
+                    severity="warning",
+                )
+            )
+        elif not log_path.is_dir():
+            warnings.append(
+                StartupWarning(
+                    category="config",
+                    message=f"Response logging path is not a directory: {log_path}",
+                    severity="warning",
+                )
+            )
+        elif not os.access(log_path, os.W_OK):
+            warnings.append(
+                StartupWarning(
+                    category="config",
+                    message=f"Response logging directory is not writable: {log_path}",
+                    suggestion=f"Run: chmod 755 {log_path}",
+                    severity="warning",
+                )
+            )
+
+        return warnings
+
+    def _check_deprecated_keys(self) -> List[StartupWarning]:
+        """Check for deprecated configuration keys."""
+        warnings = []
+        deprecated_keys = ["legacy_mode", "old_agent_format", "deprecated_logging"]
+
+        for key in deprecated_keys:
+            if self.config_service.get(key) is not None:
+                warnings.append(
+                    StartupWarning(
+                        category="config",
+                        message=f"Deprecated configuration key found: {key}",
+                        suggestion="Consider removing this key from your configuration",
+                        severity="info",
+                    )
+                )
+
+        return warnings
+
+    def _check_config_file_access(self) -> List[StartupWarning]:
+        """Check configuration file accessibility."""
+        warnings = []
+
+        try:
+            # Try to get config file path from config service
+            config_file = getattr(self.config_service, "config_file", None)
+            if config_file and Path(config_file).exists():
+                if not os.access(config_file, os.R_OK):
+                    warnings.append(
+                        StartupWarning(
+                            category="config",
+                            message=f"Configuration file is not readable: {config_file}",
+                            suggestion=f"Run: chmod 644 {config_file}",
+                            severity="warning",
+                        )
+                    )
+        except Exception as e:
+            self.logger.debug(f"Config file access check failed: {e}")
+
+        return warnings
+
+    def _check_required_directories(self) -> List[StartupWarning]:
+        """Check for required directories."""
+        warnings = []
+
+        # Check .claude directory
+        claude_dir = Path.cwd() / ".claude"
+        if not claude_dir.exists():
+            self.logger.debug(
+                ".claude directory does not exist (will be created on first use)"
+            )
+        elif not claude_dir.is_dir():
+            warnings.append(
+                StartupWarning(
+                    category="environment",
+                    message=".claude path exists but is not a directory",
+                    severity="warning",
+                )
+            )
+
+        return warnings
+
+    def _format_file_size(self, size_bytes: int) -> str:
+        """Format file size in human readable format."""
+        if size_bytes < 1024:
+            return f"{size_bytes} B"
+        if size_bytes < 1024 * 1024:
+            return f"{size_bytes / 1024:.1f} KB"
+        return f"{size_bytes / (1024 * 1024):.1f} MB"

claude_mpm/services/core/cache_manager.py

@@ -0,0 +1,311 @@
+"""
+Cache Manager Service for Framework Loader
+==========================================
+
+WHY: This service extracts and centralizes cache management logic from the FrameworkLoader,
+providing a clean interface for managing multiple cache types with different TTLs.
+
+DESIGN DECISION: Built on top of the existing FileSystemCache infrastructure while
+providing a specialized interface for framework-specific caching needs.
+
+EXTRACTED FROM: core/framework_loader.py (lines 89-140)
+- Reduces FrameworkLoader complexity by ~50 lines
+- Provides thread-safe, type-specific cache management
+
+NOTE: The ICacheManager interface has been moved to service_interfaces.py for
+better organization and to support dependency injection.
+"""
+
+import threading
+import time
+from typing import Any, Dict, Optional, Set, Tuple
+
+from claude_mpm.core.cache import FileSystemCache
+from claude_mpm.core.logger import get_logger
+
+# Import interface from consolidated location
+from .service_interfaces import ICacheManager
+
+
+class CacheManager(ICacheManager):
+    """
+    Centralized cache management service for framework loader.
+
+    This service manages multiple cache types with different TTLs:
+    - Agent capabilities (60s TTL)
+    - Deployed agents (30s TTL)
+    - Agent metadata (60s TTL)
+    - Memories (60s TTL)
+
+    Thread-safe implementation using locks for concurrent access.
+    """
+
+    # Default TTL values (in seconds)
+    DEFAULT_CAPABILITIES_TTL = 60
+    DEFAULT_DEPLOYED_AGENTS_TTL = 30
+    DEFAULT_METADATA_TTL = 60
+    DEFAULT_MEMORIES_TTL = 60
+
+    def __init__(
+        self,
+        capabilities_ttl: float = DEFAULT_CAPABILITIES_TTL,
+        deployed_agents_ttl: float = DEFAULT_DEPLOYED_AGENTS_TTL,
+        metadata_ttl: float = DEFAULT_METADATA_TTL,
+        memories_ttl: float = DEFAULT_MEMORIES_TTL,
+    ):
+        """
+        Initialize cache manager with configurable TTLs.
+
+        Args:
+            capabilities_ttl: TTL for agent capabilities cache
+            deployed_agents_ttl: TTL for deployed agents cache
+            metadata_ttl: TTL for agent metadata cache
+            memories_ttl: TTL for memories cache
+        """
+        self.logger = get_logger("cache_manager")
+
+        # TTL configuration
+        self.capabilities_ttl = capabilities_ttl
+        self.deployed_agents_ttl = deployed_agents_ttl
+        self.metadata_ttl = metadata_ttl
+        self.memories_ttl = memories_ttl
+
+        # Cache storage with timestamps
+        self._capabilities_cache: Optional[str] = None
+        self._capabilities_cache_time: float = 0
+
+        self._deployed_agents_cache: Optional[Set[str]] = None
+        self._deployed_agents_cache_time: float = 0
+
+        self._agent_metadata_cache: Dict[
+            str, Tuple[Optional[Dict[str, Any]], float]
+        ] = {}
+
+        self._memories_cache: Optional[Dict[str, Any]] = None
+        self._memories_cache_time: float = 0
+
+        # Thread safety
+        self._lock = threading.RLock()
+
+        # Underlying file system cache (optional, for persistence)
+        self._fs_cache = FileSystemCache(
+            max_size_mb=50,  # 50MB for framework caches
+            default_ttl=max(
+                capabilities_ttl, deployed_agents_ttl, metadata_ttl, memories_ttl
+            ),
+        )
+
+        self.logger.debug(
+            f"Cache manager initialized with TTLs: "
+            f"capabilities={capabilities_ttl}s, "
+            f"deployed_agents={deployed_agents_ttl}s, "
+            f"metadata={metadata_ttl}s, "
+            f"memories={memories_ttl}s"
+        )
+
+    def is_cache_valid(self, cache_time: float, ttl: float) -> bool:
+        """Check if a cache entry is still valid based on its timestamp and TTL."""
+        current_time = time.time()
+        age = current_time - cache_time
+        return age < ttl
+
+    # Agent capabilities cache
+    def get_capabilities(self) -> Optional[str]:
+        """Get cached agent capabilities."""
+        with self._lock:
+            if self._capabilities_cache is not None and self.is_cache_valid(
+                self._capabilities_cache_time, self.capabilities_ttl
+            ):
+                age = time.time() - self._capabilities_cache_time
+                self.logger.debug(f"Cache hit: agent capabilities (age: {age:.1f}s)")
+                return self._capabilities_cache
+
+            self.logger.debug("Cache miss: agent capabilities")
+            return None
+
+    def set_capabilities(self, value: str) -> None:
+        """Set agent capabilities cache."""
+        with self._lock:
+            self._capabilities_cache = value
+            self._capabilities_cache_time = time.time()
+            self.logger.debug("Updated agent capabilities cache")
+
+    # Deployed agents cache
+    def get_deployed_agents(self) -> Optional[Set[str]]:
+        """Get cached deployed agents set."""
+        with self._lock:
+            if self._deployed_agents_cache is not None and self.is_cache_valid(
+                self._deployed_agents_cache_time, self.deployed_agents_ttl
+            ):
+                age = time.time() - self._deployed_agents_cache_time
+                self.logger.debug(f"Cache hit: deployed agents (age: {age:.1f}s)")
+                return (
+                    self._deployed_agents_cache.copy()
+                )  # Return a copy to prevent external modification
+
+            self.logger.debug("Cache miss: deployed agents")
+            return None
+
+    def set_deployed_agents(self, agents: Set[str]) -> None:
+        """Set deployed agents cache."""
+        with self._lock:
+            self._deployed_agents_cache = agents.copy()  # Store a copy
+            self._deployed_agents_cache_time = time.time()
+            self.logger.debug(
+                f"Updated deployed agents cache with {len(agents)} agents"
+            )
+
+    # Agent metadata cache
+    def get_agent_metadata(
+        self, agent_file: str
+    ) -> Optional[Tuple[Optional[Dict[str, Any]], float]]:
+        """Get cached agent metadata for a specific file."""
+        with self._lock:
+            if agent_file in self._agent_metadata_cache:
+                cached_data, cached_mtime = self._agent_metadata_cache[agent_file]
+                # Check if cache is still valid
+                if self.is_cache_valid(cached_mtime, self.metadata_ttl):
+                    self.logger.debug(f"Cache hit: metadata for {agent_file}")
+                    return cached_data, cached_mtime
+
+            self.logger.debug(f"Cache miss: metadata for {agent_file}")
+            return None
+
+    def set_agent_metadata(
+        self, agent_file: str, metadata: Optional[Dict[str, Any]], mtime: float
+    ) -> None:
+        """Set agent metadata cache for a specific file."""
+        with self._lock:
+            self._agent_metadata_cache[agent_file] = (metadata, mtime)
+            self.logger.debug(f"Updated metadata cache for {agent_file}")
+
+    # Memories cache
+    def get_memories(self) -> Optional[Dict[str, Any]]:
+        """Get cached memories."""
+        with self._lock:
+            if self._memories_cache is not None and self.is_cache_valid(
+                self._memories_cache_time, self.memories_ttl
+            ):
+                age = time.time() - self._memories_cache_time
+                self.logger.debug(f"Cache hit: memories (age: {age:.1f}s)")
+                return self._memories_cache.copy()  # Return a copy
+
+            self.logger.debug("Cache miss: memories")
+            return None
+
+    def set_memories(self, memories: Dict[str, Any]) -> None:
+        """Set memories cache."""
+        with self._lock:
+            self._memories_cache = memories.copy()  # Store a copy
+            self._memories_cache_time = time.time()
+            self.logger.debug("Updated memories cache")
+
+    # Cache clearing methods
+    def clear_all(self) -> None:
+        """Clear all caches."""
+        with self._lock:
+            self.logger.info("Clearing all caches")
+
+            # Clear capabilities
+            self._capabilities_cache = None
+            self._capabilities_cache_time = 0
+
+            # Clear deployed agents
+            self._deployed_agents_cache = None
+            self._deployed_agents_cache_time = 0
+
+            # Clear metadata
+            self._agent_metadata_cache.clear()
+
+            # Clear memories
+            self._memories_cache = None
+            self._memories_cache_time = 0
+
+            # Clear underlying file system cache
+            self._fs_cache.clear()
+
+    def clear_agent_caches(self) -> None:
+        """Clear agent-related caches only."""
+        with self._lock:
+            self.logger.info("Clearing agent-related caches")
+
+            # Clear capabilities
+            self._capabilities_cache = None
+            self._capabilities_cache_time = 0
+
+            # Clear deployed agents
+            self._deployed_agents_cache = None
+            self._deployed_agents_cache_time = 0
+
+            # Clear metadata
+            self._agent_metadata_cache.clear()
+
+    def clear_memory_caches(self) -> None:
+        """Clear memory-related caches only."""
+        with self._lock:
+            self.logger.info("Clearing memory caches")
+
+            self._memories_cache = None
+            self._memories_cache_time = 0
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        with self._lock:
+            current_time = time.time()
+
+            stats = {
+                "capabilities": {
+                    "cached": self._capabilities_cache is not None,
+                    "age": (
+                        current_time - self._capabilities_cache_time
+                        if self._capabilities_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._capabilities_cache_time, self.capabilities_ttl
+                        )
+                        if self._capabilities_cache
+                        else False
+                    ),
+                },
+                "deployed_agents": {
+                    "cached": self._deployed_agents_cache is not None,
+                    "count": (
+                        len(self._deployed_agents_cache)
+                        if self._deployed_agents_cache
+                        else 0
+                    ),
+                    "age": (
+                        current_time - self._deployed_agents_cache_time
+                        if self._deployed_agents_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._deployed_agents_cache_time, self.deployed_agents_ttl
+                        )
+                        if self._deployed_agents_cache
+                        else False
+                    ),
+                },
+                "metadata": {"entries": len(self._agent_metadata_cache)},
+                "memories": {
+                    "cached": self._memories_cache is not None,
+                    "age": (
+                        current_time - self._memories_cache_time
+                        if self._memories_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._memories_cache_time, self.memories_ttl
+                        )
+                        if self._memories_cache
+                        else False
+                    ),
+                },
+                "fs_cache": self._fs_cache.get_stats() if self._fs_cache else {},
+            }
+
+            return stats