claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

claude_mpm/services/diagnostics/diagnostic_runner.py

@@ -6,24 +6,31 @@ and aggregate results for reporting.
 """
 
 import asyncio
-import logging
 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,
-    ClaudeDesktopCheck,
+    ClaudeCodeCheck,
     CommonIssuesCheck,
     ConfigurationCheck,
     FilesystemCheck,
     InstallationCheck,
     InstructionsCheck,
     MCPCheck,
+    MCPServicesCheck,
     MonitorCheck,
+    SkillSourcesCheck,
     StartupLogCheck,
 )
-from .models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+from .models import DiagnosticResult, DiagnosticSummary
+
+logger = get_logger(__name__)
 
 
 class DiagnosticRunner:
@@ -42,17 +49,19 @@ class DiagnosticRunner:
         """
         self.verbose = verbose
         self.fix = fix
-        self.logger = logging.getLogger(__name__)
-
+        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
-            ClaudeDesktopCheck,
+            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,
@@ -88,7 +97,7 @@ class DiagnosticRunner:
                 self.logger.error(f"Check {check_class.__name__} failed: {e}")
                 error_result = DiagnosticResult(
                     category=check_class.__name__.replace("Check", ""),
-                    status=DiagnosticStatus.ERROR,
+                    status=ValidationSeverity.ERROR,
                     message=f"Check failed: {e!s}",
                     details={"error": str(e)},
                 )
@@ -117,9 +126,12 @@ class DiagnosticRunner:
         ]
         # Level 2: May depend on level 1
         level2 = [
-            ClaudeDesktopCheck,
+            ClaudeCodeCheck,
             AgentCheck,
+            AgentSourcesCheck,
+            SkillSourcesCheck,
             MCPCheck,
+            MCPServicesCheck,
             MonitorCheck,
             StartupLogCheck,
         ]
@@ -162,7 +174,7 @@ class DiagnosticRunner:
                     results.append(
                         DiagnosticResult(
                             category=check_class.__name__.replace("Check", ""),
-                            status=DiagnosticStatus.ERROR,
+                            status=ValidationSeverity.ERROR,
                             message=f"Check initialization failed: {e!s}",
                             details={"error": str(e)},
                         )
@@ -178,7 +190,7 @@ class DiagnosticRunner:
                     results.append(
                         DiagnosticResult(
                             category=check_name.replace("Check", ""),
-                            status=DiagnosticStatus.ERROR,
+                            status=ValidationSeverity.ERROR,
                             message=f"Check execution failed: {e!s}",
                             details={"error": str(e)},
                         )
@@ -204,11 +216,17 @@ class DiagnosticRunner:
             "config": ConfigurationCheck,
             "filesystem": FilesystemCheck,
             "fs": FilesystemCheck,
-            "claude": ClaudeDesktopCheck,
-            "claude_desktop": ClaudeDesktopCheck,
+            "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,
@@ -230,7 +248,7 @@ class DiagnosticRunner:
                 self.logger.error(f"Check {name} failed: {e}")
                 error_result = DiagnosticResult(
                     category=check_class.__name__.replace("Check", ""),
-                    status=DiagnosticStatus.ERROR,
+                    status=ValidationSeverity.ERROR,
                     message=f"Check failed: {e!s}",
                     details={"error": str(e)},
                 )

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -8,7 +8,9 @@ formatting for terminal display and JSON export.
 import json
 import sys
 
-from .models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+from claude_mpm.core.enums import OperationResult, ValidationSeverity
+
+from .models import DiagnosticResult, DiagnosticSummary
 
 
 class DoctorReporter:
@@ -20,10 +22,10 @@ class DoctorReporter:
 
     # Status symbols and colors
     STATUS_SYMBOLS = {
-        DiagnosticStatus.OK: "✅",
-        DiagnosticStatus.WARNING: "⚠️ ",
-        DiagnosticStatus.ERROR: "❌",
-        DiagnosticStatus.SKIPPED: "⏭️ ",
+        OperationResult.SUCCESS: "✅",
+        ValidationSeverity.WARNING: "⚠️ ",
+        ValidationSeverity.ERROR: "❌",
+        OperationResult.SKIPPED: "⏭️ ",
     }
 
     # ANSI color codes
@@ -94,11 +96,11 @@ class DoctorReporter:
         # Main result line
         line = f"{indent_str}{symbol} {result.category}: "
 
-        if result.status == DiagnosticStatus.OK:
+        if result.status == OperationResult.SUCCESS:
             line += self._color("OK", color)
-        elif result.status == DiagnosticStatus.WARNING:
+        elif result.status == ValidationSeverity.WARNING:
             line += self._color("Warning", color)
-        elif result.status == DiagnosticStatus.ERROR:
+        elif result.status == ValidationSeverity.ERROR:
             line += self._color("Error", color)
         else:
             line += self._color("Skipped", color)
@@ -163,9 +165,9 @@ class DoctorReporter:
 
         # Overall health
         overall = summary.overall_status
-        if overall == DiagnosticStatus.OK:
+        if overall == OperationResult.SUCCESS:
             print(self._color("\n✅ System is healthy!", "green"))
-        elif overall == DiagnosticStatus.WARNING:
+        elif overall == ValidationSeverity.WARNING:
             print(
                 self._color(
                     "\n⚠️  System has minor issues that should be addressed.", "yellow"
@@ -242,40 +244,91 @@ class DoctorReporter:
         print(json.dumps(output, indent=2))
 
     def _report_markdown(self, summary: DiagnosticSummary):
-        """Generate Markdown-formatted report."""
-        print("# Claude MPM Doctor Report\n")
-
-        # Summary table
-        print("## Summary\n")
-        print("| Status | Count |")
-        print("|--------|-------|")
-        print(f"| ✅ OK | {summary.ok_count} |")
-        print(f"| ⚠️  Warning | {summary.warning_count} |")
-        print(f"| ❌ Error | {summary.error_count} |")
-        print(f"| ⏭️  Skipped | {summary.skipped_count} |")
+        """Generate comprehensive Markdown-formatted report."""
+        import datetime
+        import platform
+        import sys
+
+        # Header with timestamp and system info
+        print("# Claude MPM Doctor Report")
+        print()
+        now = datetime.datetime.now(datetime.timezone.utc)
+        print(f"**Generated:** {now.strftime('%Y-%m-%d %H:%M:%S %Z')}")
+        print(
+            f"**System:** {platform.system()} {platform.release()} ({platform.machine()})"
+        )
+        print(f"**Python:** {sys.version.split()[0]}")
+        print(f"**claude-mpm:** {self._get_version()}")
+
+        # Get current working directory for context
+        from pathlib import Path
+
+        cwd = Path.cwd()
+        print(f"**Working Directory:** {cwd}")
+
+        print()
+        print("---")
+        print()
+
+        # System Overview
+        print("## System Overview\n")
+        self._print_system_overview_markdown(summary)
+        print()
+
+        # Summary Statistics
+        print("## Summary Statistics\n")
+        print("| Status | Count | Percentage |")
+        print("|--------|-------|------------|")
+        total = (
+            summary.ok_count
+            + summary.warning_count
+            + summary.error_count
+            + summary.skipped_count
+        )
+        if total > 0:
+            print(
+                f"| ✅ OK | {summary.ok_count} | {summary.ok_count * 100 // total}% |"
+            )
+            print(
+                f"| ⚠️  Warning | {summary.warning_count} | {summary.warning_count * 100 // total}% |"
+            )
+            print(
+                f"| ❌ Error | {summary.error_count} | {summary.error_count * 100 // total}% |"
+            )
+            print(
+                f"| ⏭️  Skipped | {summary.skipped_count} | {summary.skipped_count * 100 // total}% |"
+            )
         print()
 
-        # Detailed results
-        print("## Diagnostic Results\n")
+        # Overall Health Status
+        overall = summary.overall_status
+        if overall == OperationResult.SUCCESS:
+            print("### 🎉 Overall Status: **Healthy**")
+            print("Your Claude MPM installation is functioning properly.\n")
+        elif overall == ValidationSeverity.WARNING:
+            print("### ⚠️ Overall Status: **Needs Attention**")
+            print("Your installation has minor issues that should be addressed.\n")
+        else:
+            print("### ❌ Overall Status: **Critical Issues**")
+            print(
+                "Your installation has critical issues that need immediate attention.\n"
+            )
 
+        # MCP Services Status (if available)
+        self._print_mcp_services_markdown(summary)
+
+        # Installation Details
+        self._print_installation_details_markdown(summary)
+
+        # Detailed Diagnostic Results
+        print("## Detailed Diagnostic Results\n")
         for result in summary.results:
-            symbol = self.STATUS_SYMBOLS.get(result.status, "?")
-            print(f"### {symbol} {result.category}\n")
-            print(f"**Status:** {result.status.value}")
-            print(f"**Message:** {result.message}\n")
-
-            if result.fix_command:
-                print(f"**Fix:** `{result.fix_command}`")
-                if result.fix_description:
-                    print(f"_{result.fix_description}_\n")
-
-            if self.verbose and result.details:
-                print("**Details:**")
-                for key, value in result.details.items():
-                    print(f"- {key}: {value}")
-                print()
+            self._print_result_markdown(result)
+
+        # Recommendations Section
+        self._print_recommendations_markdown(summary)
 
-        # Fixes section
+        # Fixes Section
         fixes = [
             (r.category, r.fix_command, r.fix_description)
             for r in summary.results
@@ -283,13 +336,37 @@ class DoctorReporter:
         ]
 
         if fixes:
-            print("## Suggested Fixes\n")
+            print("## 🔧 Suggested Fixes\n")
+            print("Run these commands to fix identified issues:\n")
+            print("```bash")
             for category, command, description in fixes:
-                print(f"- **{category}:** `{command}`")
+                print(f"# Fix: {category}")
                 if description:
-                    print(f"  - {description}")
+                    print(f"# {description}")
+                print(command)
+                print()
+            print("```")
             print()
 
+        # Footer with generation metadata
+        print("---")
+        print()
+        print("## Report Metadata")
+        print()
+        print("- **Tool:** `claude-mpm doctor`")
+        print(f"- **Version:** {self._get_version()}")
+        print(f"- **Generated:** {now.strftime('%Y-%m-%d %H:%M:%S %Z')}")
+        if self.verbose:
+            print("- **Verbose Mode:** Enabled")
+        print()
+        print("---")
+        print()
+        print("🤖 *Generated with [Claude Code](https://claude.com/claude-code)*")
+        print()
+        print(
+            "*For more information, run `claude-mpm doctor --verbose` or visit the [documentation](https://github.com/bobmatnyc/claude-mpm).*"
+        )
+
     def _color(self, text: str, color: str) -> str:
         """Apply color to text if colors are enabled."""
         if not self.use_color:
@@ -299,13 +376,13 @@ class DoctorReporter:
         reset_code = self.COLORS["reset"]
         return f"{color_code}{text}{reset_code}"
 
-    def _get_status_color(self, status: DiagnosticStatus) -> str:
+    def _get_status_color(self, status) -> str:
         """Get color for a status."""
         color_map = {
-            DiagnosticStatus.OK: "green",
-            DiagnosticStatus.WARNING: "yellow",
-            DiagnosticStatus.ERROR: "red",
-            DiagnosticStatus.SKIPPED: "gray",
+            OperationResult.SUCCESS: "green",
+            ValidationSeverity.WARNING: "yellow",
+            ValidationSeverity.ERROR: "red",
+            OperationResult.SKIPPED: "gray",
         }
         return color_map.get(status, "reset")
 
@@ -318,3 +395,184 @@ class DoctorReporter:
             return service.get_version()
         except Exception:
             return "unknown"
+
+    def _print_system_overview_markdown(self, summary: DiagnosticSummary):
+        """Print system overview in markdown format."""
+        import platform
+        import sys
+
+        print("| Component | Value |")
+        print("|-----------|-------|")
+        print(f"| Platform | {platform.system()} {platform.release()} |")
+        print(f"| Python Version | {sys.version.split()[0]} |")
+
+        # Extract key details from results
+        for result in summary.results:
+            if result.category == "Installation":
+                if result.details.get("claude_mpm_version"):
+                    print(
+                        f"| Claude MPM Version | {result.details['claude_mpm_version']} |"
+                    )
+                if result.details.get("installation_method"):
+                    print(
+                        f"| Installation Method | {result.details['installation_method']} |"
+                    )
+            elif result.category == "Claude Code":
+                if result.details.get("version"):
+                    print(f"| Claude Code (CLI) | {result.details['version']} |")
+
+    def _print_mcp_services_markdown(self, summary: DiagnosticSummary):
+        """Print MCP services status table in markdown."""
+        # Find MCP Services result
+        mcp_services_result = None
+        for result in summary.results:
+            if result.category == "MCP Services":
+                mcp_services_result = result
+                break
+
+        if not mcp_services_result or not mcp_services_result.details.get("services"):
+            return
+
+        print("## MCP Services Status\n")
+        print("| Service | Installed | Accessible | Version | Status |")
+        print("|---------|-----------|------------|---------|--------|")
+
+        services = mcp_services_result.details.get("services", {})
+        for service_name, service_info in services.items():
+            installed = "✅" if service_info.get("installed") else "❌"
+            accessible = "✅" if service_info.get("accessible") else "❌"
+            version = service_info.get("version")
+            if version:
+                version = str(version)[:20]  # Truncate long versions
+            else:
+                version = "N/A"
+            status = service_info.get("status", "unknown")
+
+            # Map status to emoji
+            if status == "ok":
+                status_emoji = "✅"
+            elif status == "warning":
+                status_emoji = "⚠️"
+            elif status == "error":
+                status_emoji = "❌"
+            else:
+                status_emoji = "❓"
+
+            print(
+                f"| {service_name} | {installed} | {accessible} | {version} | {status_emoji} |"
+            )
+        print()
+
+    def _print_installation_details_markdown(self, summary: DiagnosticSummary):
+        """Print installation details in markdown."""
+        # Find installation result
+        install_result = None
+        for result in summary.results:
+            if result.category == "Installation":
+                install_result = result
+                break
+
+        if not install_result:
+            return
+
+        print("## Installation Details\n")
+
+        # Print sub-results if available
+        if install_result.sub_results and self.verbose:
+            for sub in install_result.sub_results:
+                if sub.category == "Python Version":
+                    print("### Python Environment")
+                    print(f"- **Version:** {sub.message}")
+                elif sub.category == "Installation Method":
+                    print("### Installation Method")
+                    print(f"- **Method:** {sub.message}")
+                    if sub.details.get("container_type"):
+                        print(f"- **Container:** {sub.details['container_type']}")
+                    if sub.details.get("pipx_metadata"):
+                        metadata = sub.details["pipx_metadata"]
+                        if metadata.get("version"):
+                            print(f"- **Pipx Version:** {metadata['version']}")
+                elif sub.category == "Dependencies":
+                    print("### Dependencies")
+                    print(f"- **Status:** {sub.message}")
+                    if sub.details.get("installed"):
+                        print(
+                            f"- **Installed Packages:** {len(sub.details['installed'])}"
+                        )
+            print()
+
+    def _print_result_markdown(self, result: DiagnosticResult):
+        """Print a single result in markdown format."""
+        symbol = self.STATUS_SYMBOLS.get(result.status, "?")
+        print(f"### {symbol} {result.category}\n")
+
+        # Status badge
+        status_badge_map = {
+            OperationResult.SUCCESS: "![OK](https://img.shields.io/badge/status-OK-green)",
+            ValidationSeverity.WARNING: "![Warning](https://img.shields.io/badge/status-Warning-yellow)",
+            ValidationSeverity.ERROR: "![Error](https://img.shields.io/badge/status-Error-red)",
+            OperationResult.SKIPPED: "![Skipped](https://img.shields.io/badge/status-Skipped-gray)",
+        }
+        status_badge = status_badge_map.get(result.status, "")
+
+        print(f"{status_badge}")
+        print(f"\n**Message:** {result.message}\n")
+
+        if result.fix_command:
+            print("**Fix Available:**")
+            print("```bash")
+            print(result.fix_command)
+            print("```")
+            if result.fix_description:
+                print(f"*{result.fix_description}*\n")
+
+        if self.verbose and result.details:
+            print("<details>")
+            print("<summary>Details</summary>\n")
+            print("```json")
+            import json
+
+            print(json.dumps(result.details, indent=2, default=str))
+            print("```")
+            print("</details>\n")
+
+    def _print_recommendations_markdown(self, summary: DiagnosticSummary):
+        """Print recommendations based on diagnostic results."""
+        recommendations = []
+
+        # Analyze results for recommendations
+
+        # Check specific conditions
+        for result in summary.results:
+            if (
+                result.category == "Installation"
+                and result.status != OperationResult.SUCCESS
+            ):
+                if "pipx" not in str(result.details.get("installation_method", "")):
+                    recommendations.append(
+                        "Consider using pipx for isolated installation: `pipx install claude-mpm`"
+                    )
+
+            if result.category == "MCP Services":
+                services = result.details.get("services", {})
+                missing = [
+                    s for s, info in services.items() if not info.get("installed")
+                ]
+                if missing:
+                    recommendations.append(
+                        f"Install missing MCP services for enhanced features: {', '.join(missing)}"
+                    )
+
+            if (
+                result.category == "Claude Code"
+                and result.status == ValidationSeverity.WARNING
+            ):
+                recommendations.append(
+                    "Update Claude Code (CLI) to the latest version for best compatibility"
+                )
+
+        if recommendations:
+            print("## 📋 Recommendations\n")
+            for i, rec in enumerate(recommendations, 1):
+                print(f"{i}. {rec}")
+            print()

claude_mpm/services/diagnostics/models.py

@@ -7,16 +7,29 @@ consistency across all checks and reporting.
 
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
+from ...core.enums import OperationResult, ValidationSeverity
 
-class DiagnosticStatus(Enum):
-    """Status levels for diagnostic results."""
 
-    OK = "ok"
-    WARNING = "warning"
-    ERROR = "error"
-    SKIPPED = "skipped"
+class DiagnosticStatus(str, Enum):
+    """Backward compatibility wrapper for diagnostic status values.
+
+    WHY: Provides backward compatibility for tests and code that use
+    DiagnosticStatus instead of the consolidated OperationResult/ValidationSeverity.
+
+    DESIGN DECISION: Maps to the appropriate consolidated enum values:
+    - OK → OperationResult.SUCCESS
+    - WARNING → ValidationSeverity.WARNING
+    - ERROR → ValidationSeverity.ERROR
+
+    Note: This is a compatibility layer. New code should use OperationResult
+    and ValidationSeverity directly.
+    """
+
+    OK = "success"  # Maps to OperationResult.SUCCESS
+    WARNING = "warning"  # Maps to ValidationSeverity.WARNING
+    ERROR = "error"  # Maps to ValidationSeverity.ERROR
 
 
 @dataclass
@@ -25,10 +38,13 @@ class DiagnosticResult:
 
     WHY: Standardized result format ensures consistent reporting
     and makes it easy to aggregate and display results.
+
+    Note: status uses Union[OperationResult, ValidationSeverity] to support both
+    operation results (SUCCESS, SKIPPED) and validation results (WARNING, ERROR).
     """
 
     category: str  # e.g., "Installation", "Agents", "MCP Server"
-    status: DiagnosticStatus
+    status: Union[OperationResult, ValidationSeverity]
     message: str
     details: Dict[str, Any] = field(default_factory=dict)
     fix_command: Optional[str] = None
@@ -50,16 +66,16 @@ class DiagnosticResult:
     @property
     def has_issues(self) -> bool:
         """Check if this result indicates any issues."""
-        return self.status in (DiagnosticStatus.WARNING, DiagnosticStatus.ERROR)
+        return self.status in (ValidationSeverity.WARNING, ValidationSeverity.ERROR)
 
     @property
     def severity_level(self) -> int:
         """Get numeric severity level for sorting."""
         severity_map = {
-            DiagnosticStatus.OK: 0,
-            DiagnosticStatus.SKIPPED: 1,
-            DiagnosticStatus.WARNING: 2,
-            DiagnosticStatus.ERROR: 3,
+            OperationResult.SUCCESS: 0,
+            OperationResult.SKIPPED: 1,
+            ValidationSeverity.WARNING: 2,
+            ValidationSeverity.ERROR: 3,
         }
         return severity_map.get(self.status, 0)
 
@@ -84,13 +100,13 @@ class DiagnosticSummary:
         self.results.append(result)
         self.total_checks += 1
 
-        if result.status == DiagnosticStatus.OK:
+        if result.status == OperationResult.SUCCESS:
             self.ok_count += 1
-        elif result.status == DiagnosticStatus.WARNING:
+        elif result.status == ValidationSeverity.WARNING:
             self.warning_count += 1
-        elif result.status == DiagnosticStatus.ERROR:
+        elif result.status == ValidationSeverity.ERROR:
             self.error_count += 1
-        elif result.status == DiagnosticStatus.SKIPPED:
+        elif result.status == OperationResult.SKIPPED:
             self.skipped_count += 1
 
     @property
@@ -99,13 +115,13 @@ class DiagnosticSummary:
         return self.warning_count > 0 or self.error_count > 0
 
     @property
-    def overall_status(self) -> DiagnosticStatus:
+    def overall_status(self) -> Union[OperationResult, ValidationSeverity]:
         """Get overall system status."""
         if self.error_count > 0:
-            return DiagnosticStatus.ERROR
+            return ValidationSeverity.ERROR
         if self.warning_count > 0:
-            return DiagnosticStatus.WARNING
-        return DiagnosticStatus.OK
+            return ValidationSeverity.WARNING
+        return OperationResult.SUCCESS
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization."""

claude_mpm/services/event_aggregator.py

@@ -18,7 +18,7 @@ import sys
 import threading
 import time
 from collections import defaultdict
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 try:
@@ -267,7 +267,9 @@ class EventAggregator:
         try:
             # Extract event metadata
             event_type = event_data.get("type", "unknown")
-            timestamp = event_data.get("timestamp", datetime.utcnow().isoformat() + "Z")
+            timestamp = event_data.get(
+                "timestamp", datetime.now(timezone.utc).isoformat() + "Z"
+            )
             data = event_data.get("data", {})
 
             # Update statistics
@@ -489,7 +491,7 @@ class EventAggregator:
         for filepath in session_files:
             try:
                 # Load just the metadata, not the full session
-                with open(filepath) as f:
+                with filepath.open() as f:
                     data = json.load(f)
 
                 sessions.append(