claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/diagnostics/checks/startup_log_check.py

@@ -0,0 +1,319 @@
+"""
+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 Any, ClassVar, Dict, Optional
+
+from ....core.enums import OperationResult, ValidationSeverity
+from ..models import DiagnosticResult
+from .base_check import BaseDiagnosticCheck
+
+
+class StartupLogCheck(BaseDiagnosticCheck):
+    """Analyze startup logs for errors and issues."""
+
+    # Common error patterns and their fixes
+    ERROR_PATTERNS: ClassVar[dict[str, dict[str, Any]]] = {
+        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=ValidationSeverity.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=ValidationSeverity.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=ValidationSeverity.ERROR,
+                message=f"Startup log check failed: {e!s}",
+                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 Path(log_file).open(
+                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]):
+        """Determine overall status based on analysis."""
+        if analysis["error_count"] > 0:
+            return ValidationSeverity.ERROR
+        if analysis["warning_count"] > 3 or analysis["warning_count"] > 0:
+            return ValidationSeverity.WARNING
+        return OperationResult.SUCCESS
+
+    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)"
+        if analysis["warning_count"] > 0:
+            return f"Startup successful with {analysis['warning_count']} warning(s)"
+        if analysis["startup_successful"]:
+            return "Last startup was successful"
+        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,286 @@
+"""
+Diagnostic runner service for orchestrating health checks.
+
+WHY: Coordinate execution of all diagnostic checks, handle errors gracefully,
+and aggregate results for reporting.
+"""
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import List, Type
+
+from claude_mpm.core.enums import ValidationSeverity
+from claude_mpm.core.logging_utils import get_logger
+
+from .checks import (
+    AgentCheck,
+    AgentSourcesCheck,
+    BaseDiagnosticCheck,
+    ClaudeCodeCheck,
+    CommonIssuesCheck,
+    ConfigurationCheck,
+    FilesystemCheck,
+    InstallationCheck,
+    InstructionsCheck,
+    MCPCheck,
+    MCPServicesCheck,
+    MonitorCheck,
+    SkillSourcesCheck,
+    StartupLogCheck,
+)
+from .models import DiagnosticResult, DiagnosticSummary
+
+logger = get_logger(__name__)
+
+
+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 = logger  # Add logger initialization
+        # Define check order (dependencies first)
+        self.check_classes: List[Type[BaseDiagnosticCheck]] = [
+            InstallationCheck,
+            ConfigurationCheck,
+            FilesystemCheck,
+            InstructionsCheck,  # Check instruction files early
+            ClaudeCodeCheck,
+            AgentCheck,
+            AgentSourcesCheck,  # Check agent sources configuration
+            SkillSourcesCheck,  # Check skill sources configuration
+            MCPCheck,
+            MCPServicesCheck,  # Check external MCP services
+            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=ValidationSeverity.ERROR,
+                    message=f"Check failed: {e!s}",
+                    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,
+            InstructionsCheck,
+        ]
+        # Level 2: May depend on level 1
+        level2 = [
+            ClaudeCodeCheck,
+            AgentCheck,
+            AgentSourcesCheck,
+            SkillSourcesCheck,
+            MCPCheck,
+            MCPServicesCheck,
+            MonitorCheck,
+            StartupLogCheck,
+        ]
+        # 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=ValidationSeverity.ERROR,
+                            message=f"Check initialization failed: {e!s}",
+                            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=ValidationSeverity.ERROR,
+                            message=f"Check execution failed: {e!s}",
+                            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": ClaudeCodeCheck,
+            "claude_code": ClaudeCodeCheck,
+            "agents": AgentCheck,
+            "agent": AgentCheck,
+            "agent-sources": AgentSourcesCheck,
+            "agent_sources": AgentSourcesCheck,
+            "sources": AgentSourcesCheck,
+            "mcp": MCPCheck,
+            "mcp_services": MCPServicesCheck,
+            "mcp-services": MCPServicesCheck,
+            "external": MCPServicesCheck,
+            "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=ValidationSeverity.ERROR,
+                    message=f"Check failed: {e!s}",
+                    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)