claude-mpm 4.0.29__py3-none-any.whl → 4.0.31__py3-none-any.whl

claude_mpm/services/diagnostics/checks/startup_log_check.py

@@ -0,0 +1,322 @@
+"""
+Check startup log health and analyze for common issues.
+
+WHY: Startup logs contain valuable diagnostic information about agent deployment,
+MCP configuration, memory loading, and other startup issues that may not be
+immediately visible to users.
+
+DESIGN DECISIONS:
+- Parse the most recent startup log file
+- Identify common error patterns and provide fixes
+- Count errors, warnings, and info messages
+- Provide actionable recommendations based on log content
+"""
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+
+from ..models import DiagnosticResult, DiagnosticStatus
+from .base_check import BaseDiagnosticCheck
+
+
+class StartupLogCheck(BaseDiagnosticCheck):
+    """Analyze startup logs for errors and issues."""
+    
+    # Common error patterns and their fixes
+    ERROR_PATTERNS = {
+        r"Agent deployment.*failed": (
+            "Agent deployment failure",
+            "Check agent configuration in .claude/agents/ and run 'claude-mpm deploy'"
+        ),
+        r"MCP.*not found": (
+            "MCP server not found",
+            "Install MCP server: npm install -g @modelcontextprotocol/server"
+        ),
+        r"Port \d+ .*in use": (
+            "Port binding conflict",
+            "Kill the process using the port or use --websocket-port to specify a different port"
+        ),
+        r"Memory loading.*error": (
+            "Memory loading failure",
+            "Check .claude-mpm/memory/ permissions and run 'claude-mpm memory validate'"
+        ),
+        r"Permission denied": (
+            "Permission error",
+            "Check file permissions in project directory and .claude-mpm/"
+        ),
+        r"ModuleNotFoundError|ImportError": (
+            "Missing Python dependency",
+            "Install missing dependencies: pip install -e . or pip install claude-mpm[agents]"
+        ),
+        r"Socket\.IO.*failed|socketio.*error": (
+            "Socket.IO initialization failure",
+            "Install monitor dependencies: pip install claude-mpm[monitor]"
+        ),
+        r"Configuration.*invalid|yaml.*error": (
+            "Configuration file error",
+            "Validate configuration: claude-mpm config validate"
+        ),
+        r"claude\.json.*large|memory.*issue": (
+            "Large .claude.json file",
+            "Run 'claude-mpm cleanup-memory' to archive old conversations"
+        ),
+        r"Failed to start.*daemon": (
+            "Daemon startup failure",
+            "Check system resources and try: claude-mpm monitor stop && claude-mpm monitor start"
+        ),
+    }
+    
+    # Warning patterns that should be noted
+    WARNING_PATTERNS = {
+        r"agent.*source.*tracking": "Agent source tracking warning",
+        r"dependency.*missing": "Missing optional dependency",
+        r"deprecated": "Deprecation warning",
+        r"Socket\.IO.*not available": "Monitor mode unavailable",
+        r"Response logging.*disabled": "Response logging is disabled",
+    }
+    
+    @property
+    def name(self) -> str:
+        return "startup_log_check"
+    
+    @property
+    def category(self) -> str:
+        return "Startup Log"
+    
+    def run(self) -> DiagnosticResult:
+        """Run startup log diagnostics."""
+        try:
+            # Find the latest startup log
+            log_file = self._find_latest_log()
+            
+            if not log_file:
+                return DiagnosticResult(
+                    category=self.category,
+                    status=DiagnosticStatus.WARNING,
+                    message="No startup logs found",
+                    details={
+                        "recommendation": "Startup logging will be created on next run"
+                    }
+                )
+            
+            # Parse the log file
+            analysis = self._analyze_log_file(log_file)
+            
+            # Determine status based on findings
+            status = self._determine_status(analysis)
+            message = self._create_message(analysis)
+            
+            # Build details
+            details = {
+                "log_file": str(log_file),
+                "last_startup": analysis["timestamp"],
+                "errors": analysis["error_count"],
+                "warnings": analysis["warning_count"],
+                "info_messages": analysis["info_count"],
+            }
+            
+            # Add specific issues found
+            if analysis["errors_found"]:
+                details["errors_found"] = analysis["errors_found"]
+            
+            if analysis["warnings_found"]:
+                details["warnings_found"] = analysis["warnings_found"]
+            
+            # Add recommendations
+            if analysis["recommendations"]:
+                details["recommendations"] = analysis["recommendations"]
+            
+            # Create sub-results if verbose
+            sub_results = []
+            if self.verbose and analysis["errors_found"]:
+                for error_type, fix in analysis["errors_found"]:
+                    sub_results.append(
+                        DiagnosticResult(
+                            category="Error",
+                            status=DiagnosticStatus.ERROR,
+                            message=error_type,
+                            details={"fix": fix}
+                        )
+                    )
+            
+            return DiagnosticResult(
+                category=self.category,
+                status=status,
+                message=message,
+                details=details,
+                sub_results=sub_results if self.verbose else [],
+                fix_command=self._get_fix_command(analysis)
+            )
+            
+        except Exception as e:
+            return DiagnosticResult(
+                category=self.category,
+                status=DiagnosticStatus.ERROR,
+                message=f"Startup log check failed: {str(e)}",
+                details={"error": str(e)}
+            )
+    
+    def _find_latest_log(self) -> Optional[Path]:
+        """Find the most recent startup log file."""
+        log_dir = Path.cwd() / ".claude-mpm" / "logs" / "startup"
+        
+        if not log_dir.exists():
+            return None
+        
+        log_files = sorted(
+            log_dir.glob("startup-*.log"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True
+        )
+        
+        return log_files[0] if log_files else None
+    
+    def _analyze_log_file(self, log_file: Path) -> Dict[str, Any]:
+        """Analyze the contents of a startup log file."""
+        analysis = {
+            "timestamp": None,
+            "error_count": 0,
+            "warning_count": 0,
+            "info_count": 0,
+            "debug_count": 0,
+            "errors_found": [],
+            "warnings_found": [],
+            "recommendations": [],
+            "startup_successful": False,
+        }
+        
+        try:
+            with open(log_file, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+            
+            # Extract timestamp from filename or first line
+            match = re.search(r'(\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2})', log_file.name)
+            if match:
+                timestamp_str = match.group(1)
+                # Convert to readable format
+                dt = datetime.strptime(timestamp_str, "%Y-%m-%d-%H-%M-%S")
+                analysis["timestamp"] = dt.strftime("%Y-%m-%d %H:%M:%S")
+            
+            # Process each line
+            for line in lines:
+                # Count log levels
+                if " - ERROR - " in line:
+                    analysis["error_count"] += 1
+                    self._check_error_patterns(line, analysis)
+                elif " - WARNING - " in line:
+                    analysis["warning_count"] += 1
+                    self._check_warning_patterns(line, analysis)
+                elif " - INFO - " in line:
+                    analysis["info_count"] += 1
+                elif " - DEBUG - " in line:
+                    analysis["debug_count"] += 1
+                
+                # Check for successful startup indicators
+                if "Claude session completed successfully" in line:
+                    analysis["startup_successful"] = True
+                elif "Starting Claude MPM session" in line:
+                    analysis["startup_successful"] = True  # At least startup began
+            
+            # Generate recommendations based on findings
+            self._generate_recommendations(analysis)
+            
+        except Exception as e:
+            analysis["error_count"] += 1
+            analysis["errors_found"].append(("Failed to parse log", str(e)))
+        
+        return analysis
+    
+    def _check_error_patterns(self, line: str, analysis: Dict[str, Any]) -> None:
+        """Check line for known error patterns."""
+        for pattern, (error_type, fix) in self.ERROR_PATTERNS.items():
+            if re.search(pattern, line, re.IGNORECASE):
+                # Avoid duplicates
+                if (error_type, fix) not in analysis["errors_found"]:
+                    analysis["errors_found"].append((error_type, fix))
+                break
+    
+    def _check_warning_patterns(self, line: str, analysis: Dict[str, Any]) -> None:
+        """Check line for known warning patterns."""
+        for pattern, warning_type in self.WARNING_PATTERNS.items():
+            if re.search(pattern, line, re.IGNORECASE):
+                # Avoid duplicates
+                if warning_type not in analysis["warnings_found"]:
+                    analysis["warnings_found"].append(warning_type)
+                break
+    
+    def _generate_recommendations(self, analysis: Dict[str, Any]) -> None:
+        """Generate recommendations based on analysis."""
+        recommendations = []
+        
+        # High error count
+        if analysis["error_count"] > 5:
+            recommendations.append(
+                "High error count detected. Review full log for systematic issues."
+            )
+        
+        # No successful startup
+        if not analysis["startup_successful"] and analysis["error_count"] > 0:
+            recommendations.append(
+                "Startup may have failed. Check error messages above."
+            )
+        
+        # Specific error recommendations
+        if any("MCP" in error[0] for error in analysis["errors_found"]):
+            recommendations.append(
+                "MCP issues detected. Run 'claude-mpm doctor' for full diagnostics."
+            )
+        
+        if any("Agent" in error[0] for error in analysis["errors_found"]):
+            recommendations.append(
+                "Agent issues detected. Run 'claude-mpm agents validate' to check agents."
+            )
+        
+        if any("memory" in error[0].lower() for error in analysis["errors_found"]):
+            recommendations.append(
+                "Memory issues detected. Run 'claude-mpm cleanup-memory' to free space."
+            )
+        
+        analysis["recommendations"] = recommendations
+    
+    def _determine_status(self, analysis: Dict[str, Any]) -> DiagnosticStatus:
+        """Determine overall status based on analysis."""
+        if analysis["error_count"] > 0:
+            return DiagnosticStatus.ERROR
+        elif analysis["warning_count"] > 3:
+            return DiagnosticStatus.WARNING
+        elif analysis["warning_count"] > 0:
+            return DiagnosticStatus.WARNING
+        else:
+            return DiagnosticStatus.OK
+    
+    def _create_message(self, analysis: Dict[str, Any]) -> str:
+        """Create summary message based on analysis."""
+        if analysis["error_count"] > 0:
+            return f"Startup has {analysis['error_count']} error(s)"
+        elif analysis["warning_count"] > 0:
+            return f"Startup successful with {analysis['warning_count']} warning(s)"
+        elif analysis["startup_successful"]:
+            return "Last startup was successful"
+        else:
+            return "Startup log is clean"
+    
+    def _get_fix_command(self, analysis: Dict[str, Any]) -> Optional[str]:
+        """Get the most relevant fix command based on errors found."""
+        if not analysis["errors_found"]:
+            return None
+        
+        # Priority order for fix commands
+        for error_type, fix in analysis["errors_found"]:
+            if "claude-mpm" in fix:
+                # Extract claude-mpm command from fix suggestion
+                match = re.search(r'(claude-mpm [^\'"\n]+)', fix)
+                if match:
+                    return match.group(1)
+            elif "pip install" in fix:
+                match = re.search(r'(pip install [^\'"\n]+)', fix)
+                if match:
+                    return match.group(1)
+        
+        return None

claude_mpm/services/diagnostics/diagnostic_runner.py

@@ -0,0 +1,247 @@
+"""
+Diagnostic runner service for orchestrating health checks.
+
+WHY: Coordinate execution of all diagnostic checks, handle errors gracefully,
+and aggregate results for reporting.
+"""
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import List, Optional, Type
+
+from .checks import (
+    AgentCheck,
+    BaseDiagnosticCheck,
+    ClaudeDesktopCheck,
+    CommonIssuesCheck,
+    ConfigurationCheck,
+    FilesystemCheck,
+    InstallationCheck,
+    MCPCheck,
+    MonitorCheck,
+    StartupLogCheck,
+)
+from .models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+
+
+class DiagnosticRunner:
+    """Orchestrate diagnostic checks and aggregate results.
+    
+    WHY: Provides a single entry point for running all diagnostics with
+    proper error handling, parallel execution, and result aggregation.
+    """
+    
+    def __init__(self, verbose: bool = False, fix: bool = False):
+        """Initialize diagnostic runner.
+        
+        Args:
+            verbose: Include detailed information in results
+            fix: Attempt to fix issues automatically (future feature)
+        """
+        self.verbose = verbose
+        self.fix = fix
+        self.logger = logging.getLogger(__name__)
+        
+        # Define check order (dependencies first)
+        self.check_classes: List[Type[BaseDiagnosticCheck]] = [
+            InstallationCheck,
+            ConfigurationCheck,
+            FilesystemCheck,
+            ClaudeDesktopCheck,
+            AgentCheck,
+            MCPCheck,
+            MonitorCheck,
+            StartupLogCheck,  # Check startup logs for recent issues
+            CommonIssuesCheck,
+        ]
+    
+    def run_diagnostics(self) -> DiagnosticSummary:
+        """Run all diagnostic checks synchronously.
+        
+        Returns:
+            DiagnosticSummary with all results
+        """
+        summary = DiagnosticSummary()
+        
+        # Run checks in order
+        for check_class in self.check_classes:
+            try:
+                check = check_class(verbose=self.verbose)
+                
+                # Skip if check shouldn't run
+                if not check.should_run():
+                    self.logger.debug(f"Skipping {check.name}")
+                    continue
+                
+                self.logger.debug(f"Running {check.name}")
+                result = check.run()
+                summary.add_result(result)
+                
+                # If fix mode is enabled and there's a fix available
+                if self.fix and result.has_issues and result.fix_command:
+                    self._attempt_fix(result)
+                    
+            except Exception as e:
+                self.logger.error(f"Check {check_class.__name__} failed: {e}")
+                error_result = DiagnosticResult(
+                    category=check_class.__name__.replace("Check", ""),
+                    status=DiagnosticStatus.ERROR,
+                    message=f"Check failed: {str(e)}",
+                    details={"error": str(e)}
+                )
+                summary.add_result(error_result)
+        
+        return summary
+    
+    def run_diagnostics_parallel(self) -> DiagnosticSummary:
+        """Run diagnostic checks in parallel for faster execution.
+        
+        WHY: Some checks may involve I/O or network operations, running them
+        in parallel can significantly speed up the overall diagnostic process.
+        
+        Returns:
+            DiagnosticSummary with all results
+        """
+        summary = DiagnosticSummary()
+        
+        # Group checks by dependency level
+        # Level 1: No dependencies
+        level1 = [InstallationCheck, FilesystemCheck, ConfigurationCheck]
+        # Level 2: May depend on level 1
+        level2 = [ClaudeDesktopCheck, AgentCheck, MCPCheck, MonitorCheck]
+        # Level 3: Depends on others
+        level3 = [CommonIssuesCheck]
+        
+        for level in [level1, level2, level3]:
+            level_results = self._run_level_parallel(level)
+            for result in level_results:
+                summary.add_result(result)
+        
+        return summary
+    
+    def _run_level_parallel(self, check_classes: List[Type[BaseDiagnosticCheck]]) -> List[DiagnosticResult]:
+        """Run a group of checks in parallel.
+        
+        Args:
+            check_classes: List of check classes to run
+            
+        Returns:
+            List of DiagnosticResults
+        """
+        results = []
+        
+        with ThreadPoolExecutor(max_workers=len(check_classes)) as executor:
+            future_to_check = {}
+            
+            for check_class in check_classes:
+                try:
+                    check = check_class(verbose=self.verbose)
+                    if check.should_run():
+                        future = executor.submit(check.run)
+                        future_to_check[future] = check_class.__name__
+                except Exception as e:
+                    self.logger.error(f"Failed to create check {check_class.__name__}: {e}")
+                    results.append(DiagnosticResult(
+                        category=check_class.__name__.replace("Check", ""),
+                        status=DiagnosticStatus.ERROR,
+                        message=f"Check initialization failed: {str(e)}",
+                        details={"error": str(e)}
+                    ))
+            
+            for future in as_completed(future_to_check):
+                check_name = future_to_check[future]
+                try:
+                    result = future.result(timeout=10)
+                    results.append(result)
+                except Exception as e:
+                    self.logger.error(f"Check {check_name} failed: {e}")
+                    results.append(DiagnosticResult(
+                        category=check_name.replace("Check", ""),
+                        status=DiagnosticStatus.ERROR,
+                        message=f"Check execution failed: {str(e)}",
+                        details={"error": str(e)}
+                    ))
+        
+        return results
+    
+    def run_specific_checks(self, check_names: List[str]) -> DiagnosticSummary:
+        """Run only specific diagnostic checks.
+        
+        Args:
+            check_names: List of check names to run (e.g., ["installation", "agents"])
+            
+        Returns:
+            DiagnosticSummary with results from specified checks
+        """
+        summary = DiagnosticSummary()
+        
+        # Map check names to classes
+        check_map = {
+            "installation": InstallationCheck,
+            "configuration": ConfigurationCheck,
+            "config": ConfigurationCheck,
+            "filesystem": FilesystemCheck,
+            "fs": FilesystemCheck,
+            "claude": ClaudeDesktopCheck,
+            "claude_desktop": ClaudeDesktopCheck,
+            "agents": AgentCheck,
+            "agent": AgentCheck,
+            "mcp": MCPCheck,
+            "monitor": MonitorCheck,
+            "monitoring": MonitorCheck,
+            "common": CommonIssuesCheck,
+            "issues": CommonIssuesCheck,
+        }
+        
+        for name in check_names:
+            check_class = check_map.get(name.lower())
+            if not check_class:
+                self.logger.warning(f"Unknown check: {name}")
+                continue
+            
+            try:
+                check = check_class(verbose=self.verbose)
+                if check.should_run():
+                    result = check.run()
+                    summary.add_result(result)
+            except Exception as e:
+                self.logger.error(f"Check {name} failed: {e}")
+                error_result = DiagnosticResult(
+                    category=check_class.__name__.replace("Check", ""),
+                    status=DiagnosticStatus.ERROR,
+                    message=f"Check failed: {str(e)}",
+                    details={"error": str(e)}
+                )
+                summary.add_result(error_result)
+        
+        return summary
+    
+    def _attempt_fix(self, result: DiagnosticResult):
+        """Attempt to fix an issue automatically.
+        
+        Args:
+            result: DiagnosticResult with fix_command
+        """
+        if not result.fix_command:
+            return
+        
+        self.logger.info(f"Attempting to fix: {result.message}")
+        self.logger.info(f"Running: {result.fix_command}")
+        
+        # In a real implementation, this would execute the fix command
+        # For now, we just log it
+        # TODO: Implement actual fix execution with proper safeguards
+        
+    async def run_diagnostics_async(self) -> DiagnosticSummary:
+        """Run diagnostics asynchronously (future enhancement).
+        
+        WHY: For integration with async frameworks and better performance
+        with I/O-bound checks.
+        
+        Returns:
+            DiagnosticSummary with all results
+        """
+        # Convert sync execution to async for now
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.run_diagnostics)