claude-mpm 4.1.1__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/command_deployment_service.py

@@ -0,0 +1,173 @@
+"""Service for deploying MPM slash commands to user's Claude configuration.
+
+This service handles:
+1. Copying command markdown files from source to user's ~/.claude/commands directory
+2. Creating the commands directory if it doesn't exist
+3. Overwriting existing commands to ensure they're up-to-date
+"""
+
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List
+
+from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.logger import get_logger
+
+
+class CommandDeploymentService(BaseService):
+    """Service for deploying MPM slash commands."""
+
+    def __init__(self):
+        """Initialize the command deployment service."""
+        super().__init__(name="command_deployment")
+
+        # Source commands directory in the package
+        self.source_dir = Path(__file__).parent.parent / "commands"
+
+        # Target directory in user's home
+        self.target_dir = Path.home() / ".claude" / "commands"
+
+    async def _initialize(self) -> None:
+        """Initialize the service."""
+
+    async def _cleanup(self) -> None:
+        """Cleanup service resources."""
+
+    def deploy_commands(self, force: bool = False) -> Dict[str, Any]:
+        """Deploy MPM slash commands to user's Claude configuration.
+
+        Args:
+            force: Force deployment even if files exist
+
+        Returns:
+            Dictionary with deployment results
+        """
+        result = {
+            "success": False,
+            "deployed": [],
+            "errors": [],
+            "target_dir": str(self.target_dir),
+        }
+
+        try:
+            # Check if source directory exists
+            if not self.source_dir.exists():
+                self.logger.warning(
+                    f"Source commands directory not found: {self.source_dir}"
+                )
+                result["errors"].append(
+                    f"Source directory not found: {self.source_dir}"
+                )
+                return result
+
+            # Create target directory if it doesn't exist
+            self.target_dir.mkdir(parents=True, exist_ok=True)
+            self.logger.debug(f"Ensured target directory exists: {self.target_dir}")
+
+            # Get all .md files from source directory
+            command_files = list(self.source_dir.glob("*.md"))
+
+            if not command_files:
+                self.logger.info("No command files found to deploy")
+                result["success"] = True
+                return result
+
+            # Deploy each command file
+            for source_file in command_files:
+                target_file = self.target_dir / source_file.name
+
+                try:
+                    # Check if file exists and if we should overwrite
+                    if target_file.exists() and not force:
+                        # Check if source is newer
+                        if source_file.stat().st_mtime <= target_file.stat().st_mtime:
+                            self.logger.debug(
+                                f"Skipping {source_file.name} - target is up to date"
+                            )
+                            continue
+
+                    # Copy the file
+                    shutil.copy2(source_file, target_file)
+                    self.logger.info(f"Deployed command: {source_file.name}")
+                    result["deployed"].append(source_file.name)
+
+                except Exception as e:
+                    error_msg = f"Failed to deploy {source_file.name}: {e}"
+                    self.logger.error(error_msg)
+                    result["errors"].append(error_msg)
+
+            result["success"] = len(result["errors"]) == 0
+
+            if result["deployed"]:
+                self.logger.info(
+                    f"Successfully deployed {len(result['deployed'])} commands to {self.target_dir}"
+                )
+
+            return result
+
+        except Exception as e:
+            error_msg = f"Command deployment failed: {e}"
+            self.logger.error(error_msg)
+            result["errors"].append(error_msg)
+            return result
+
+    def list_available_commands(self) -> List[str]:
+        """List available commands in the source directory.
+
+        Returns:
+            List of command file names
+        """
+        if not self.source_dir.exists():
+            return []
+
+        return [f.name for f in self.source_dir.glob("*.md")]
+
+    def list_deployed_commands(self) -> List[str]:
+        """List deployed commands in the target directory.
+
+        Returns:
+            List of deployed command file names
+        """
+        if not self.target_dir.exists():
+            return []
+
+        return [f.name for f in self.target_dir.glob("mpm*.md")]
+
+    def remove_deployed_commands(self) -> int:
+        """Remove all deployed MPM commands from target directory.
+
+        Returns:
+            Number of files removed
+        """
+        if not self.target_dir.exists():
+            return 0
+
+        removed = 0
+        for file in self.target_dir.glob("mpm*.md"):
+            try:
+                file.unlink()
+                self.logger.info(f"Removed command: {file.name}")
+                removed += 1
+            except Exception as e:
+                self.logger.error(f"Failed to remove {file.name}: {e}")
+
+        return removed
+
+
+def deploy_commands_on_startup(force: bool = False) -> None:
+    """Convenience function to deploy commands during startup.
+
+    Args:
+        force: Force deployment even if files exist
+    """
+    service = CommandDeploymentService()
+    result = service.deploy_commands(force=force)
+
+    if result["deployed"]:
+        logger = get_logger("startup")
+        logger.info(f"MPM commands deployed: {', '.join(result['deployed'])}")
+
+    if result["errors"]:
+        logger = get_logger("startup")
+        for error in result["errors"]:
+            logger.warning(f"Command deployment issue: {error}")

claude_mpm/services/command_handler_service.py

@@ -29,11 +29,9 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
 
     async def _initialize(self) -> None:
         """Initialize the service. No special initialization needed."""
-        pass
 
     async def _cleanup(self) -> None:
         """Cleanup service resources. No cleanup needed."""
-        pass
 
     def handle_mpm_command(self, prompt: str) -> bool:
         """Handle /mpm: commands directly without going to Claude.
@@ -59,12 +57,11 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             # Route to appropriate handler
             if command == "test":
                 return self._handle_test_command(args)
-            elif command == "agents":
+            if command == "agents":
                 return self._handle_agents_command(args)
-            else:
-                print(f"Unknown command: {command}")
-                print("Available commands: test, agents")
-                return True
+            print(f"Unknown command: {command}")
+            print("Available commands: test, agents")
+            return True
 
         except KeyboardInterrupt:
             print("\nCommand interrupted")
@@ -175,28 +172,29 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
                     "success": success,
                     "command": command,
                     "args": args,
-                    "message": "Test command executed"
-                    if success
-                    else "Test command failed",
+                    "message": (
+                        "Test command executed" if success else "Test command failed"
+                    ),
                 }
-            elif command == "agents":
+            if command == "agents":
                 success = self._handle_agents_command(args)
                 return {
                     "success": success,
                     "command": command,
                     "args": args,
-                    "message": "Agents command executed"
-                    if success
-                    else "Agents command failed",
-                }
-            else:
-                return {
-                    "success": False,
-                    "command": command,
-                    "args": args,
-                    "error": f"Unknown command: {command}",
-                    "available_commands": self.get_available_commands(),
+                    "message": (
+                        "Agents command executed"
+                        if success
+                        else "Agents command failed"
+                    ),
                 }
+            return {
+                "success": False,
+                "command": command,
+                "args": args,
+                "error": f"Unknown command: {command}",
+                "available_commands": self.get_available_commands(),
+            }
         except Exception as e:
             return {"success": False, "command": command, "args": args, "error": str(e)}
 

claude_mpm/services/core/__init__.py

@@ -40,37 +40,37 @@ from .interfaces import (  # Core dependency injection; Configuration management
 )
 
 __all__ = [
-    # Core interfaces
-    "IServiceContainer",
-    "ServiceType",
-    "IConfigurationService",
-    "IConfigurationManager",
-    "IAgentRegistry",
+    # Service interfaces
+    "AgentDeploymentInterface",
     "AgentMetadata",
-    "IHealthMonitor",
+    # Base classes
+    "BaseService",
+    "CacheEntry",
     "HealthStatus",
+    "HookServiceInterface",
+    "IAgentRegistry",
+    "ICacheService",
+    "IConfigurationManager",
+    "IConfigurationService",
+    "IErrorHandler",
+    "IEventBus",
+    "IHealthMonitor",
+    "IPerformanceMonitor",
     "IPromptCache",
-    "CacheEntry",
-    "ITemplateManager",
-    "TemplateRenderContext",
+    # Core interfaces
+    "IServiceContainer",
     "IServiceFactory",
-    "IEventBus",
-    "IStructuredLogger",
     "IServiceLifecycle",
-    "IErrorHandler",
-    "IPerformanceMonitor",
-    "ICacheService",
-    # Service interfaces
-    "AgentDeploymentInterface",
-    "MemoryServiceInterface",
-    "HookServiceInterface",
-    "SocketIOServiceInterface",
-    "ProjectAnalyzerInterface",
-    "TicketManagerInterface",
+    "IStructuredLogger",
+    "ITemplateManager",
     # Registry
     "InterfaceRegistry",
-    # Base classes
-    "BaseService",
-    "SyncBaseService",
+    "MemoryServiceInterface",
+    "ProjectAnalyzerInterface",
+    "ServiceType",
     "SingletonService",
+    "SocketIOServiceInterface",
+    "SyncBaseService",
+    "TemplateRenderContext",
+    "TicketManagerInterface",
 ]