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

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -0,0 +1,283 @@
+"""
+Reporter for formatting and displaying diagnostic results.
+
+WHY: Provide clear, actionable output from diagnostic checks with proper
+formatting for terminal display and JSON export.
+"""
+
+import json
+import sys
+from typing import Dict, List, Optional
+
+from .models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+
+
+class DoctorReporter:
+    """Format and display diagnostic results.
+    
+    WHY: Consistent, user-friendly output that clearly shows system health
+    status and provides actionable fixes for any issues.
+    """
+    
+    # Status symbols and colors
+    STATUS_SYMBOLS = {
+        DiagnosticStatus.OK: "✅",
+        DiagnosticStatus.WARNING: "⚠️ ",
+        DiagnosticStatus.ERROR: "❌",
+        DiagnosticStatus.SKIPPED: "⏭️ "
+    }
+    
+    # ANSI color codes
+    COLORS = {
+        "reset": "\033[0m",
+        "bold": "\033[1m",
+        "red": "\033[91m",
+        "green": "\033[92m",
+        "yellow": "\033[93m",
+        "blue": "\033[94m",
+        "gray": "\033[90m"
+    }
+    
+    def __init__(self, use_color: bool = True, verbose: bool = False):
+        """Initialize reporter.
+        
+        Args:
+            use_color: Whether to use ANSI color codes
+            verbose: Whether to include detailed information
+        """
+        self.use_color = use_color and sys.stdout.isatty()
+        self.verbose = verbose
+    
+    def report(self, summary: DiagnosticSummary, format: str = "terminal"):
+        """Generate and output diagnostic report.
+        
+        Args:
+            summary: DiagnosticSummary with all results
+            format: Output format ("terminal", "json", "markdown")
+        """
+        if format == "json":
+            self._report_json(summary)
+        elif format == "markdown":
+            self._report_markdown(summary)
+        else:
+            self._report_terminal(summary)
+    
+    def _report_terminal(self, summary: DiagnosticSummary):
+        """Generate terminal-formatted report."""
+        # Header
+        self._print_header()
+        
+        # Results by category
+        for result in summary.results:
+            self._print_result(result)
+        
+        # Summary
+        self._print_summary(summary)
+        
+        # Fix suggestions
+        self._print_fixes(summary)
+    
+    def _print_header(self):
+        """Print report header."""
+        print()
+        print(self._color("Claude MPM Doctor Report", "bold"))
+        print("=" * 40)
+        print()
+    
+    def _print_result(self, result: DiagnosticResult, indent: int = 0):
+        """Print a single diagnostic result."""
+        indent_str = "  " * indent
+        
+        # Status symbol and category
+        symbol = self.STATUS_SYMBOLS.get(result.status, "?")
+        color = self._get_status_color(result.status)
+        
+        # Main result line
+        line = f"{indent_str}{symbol} {result.category}: "
+        
+        if result.status == DiagnosticStatus.OK:
+            line += self._color("OK", color)
+        elif result.status == DiagnosticStatus.WARNING:
+            line += self._color("Warning", color)
+        elif result.status == DiagnosticStatus.ERROR:
+            line += self._color("Error", color)
+        else:
+            line += self._color("Skipped", color)
+        
+        print(line)
+        
+        # Message
+        message_indent = "   " + indent_str
+        print(f"{message_indent}{result.message}")
+        
+        # Details (in verbose mode)
+        if self.verbose and result.details:
+            for key, value in result.details.items():
+                if key not in ["error", "issues"]:  # Skip complex fields
+                    print(f"{message_indent}{self._color(key, 'gray')}: {value}")
+        
+        # Fix suggestion
+        if result.fix_command:
+            fix_indent = "   " + indent_str
+            print(f"{fix_indent}{self._color('→ Fix:', 'blue')} Run '{result.fix_command}'")
+            if result.fix_description:
+                print(f"{fix_indent}  {self._color(result.fix_description, 'gray')}")
+        
+        # Sub-results (in verbose mode)
+        if self.verbose and result.sub_results:
+            for sub_result in result.sub_results:
+                self._print_result(sub_result, indent + 1)
+        
+        if indent == 0:
+            print()  # Extra line between top-level results
+    
+    def _print_summary(self, summary: DiagnosticSummary):
+        """Print summary statistics."""
+        print(self._color("─" * 40, "gray"))
+        
+        status_line = f"Summary: "
+        parts = []
+        
+        if summary.ok_count > 0:
+            parts.append(self._color(f"{summary.ok_count} OK", "green"))
+        if summary.warning_count > 0:
+            parts.append(self._color(f"{summary.warning_count} Warning{'s' if summary.warning_count != 1 else ''}", "yellow"))
+        if summary.error_count > 0:
+            parts.append(self._color(f"{summary.error_count} Error{'s' if summary.error_count != 1 else ''}", "red"))
+        if summary.skipped_count > 0:
+            parts.append(self._color(f"{summary.skipped_count} Skipped", "gray"))
+        
+        status_line += " | ".join(parts)
+        print(status_line)
+        
+        # Overall health
+        overall = summary.overall_status
+        if overall == DiagnosticStatus.OK:
+            print(self._color("\n✅ System is healthy!", "green"))
+        elif overall == DiagnosticStatus.WARNING:
+            print(self._color("\n⚠️  System has minor issues that should be addressed.", "yellow"))
+        else:
+            print(self._color("\n❌ System has critical issues that need immediate attention!", "red"))
+    
+    def _print_fixes(self, summary: DiagnosticSummary):
+        """Print consolidated fix suggestions."""
+        fixes = []
+        
+        for result in summary.results:
+            if result.fix_command and result.has_issues:
+                fixes.append((result.category, result.fix_command, result.fix_description))
+        
+        if fixes:
+            print()
+            print(self._color("Suggested Fixes:", "bold"))
+            print(self._color("─" * 40, "gray"))
+            
+            for i, (category, command, description) in enumerate(fixes, 1):
+                print(f"{i}. {category}:")
+                print(f"   {self._color(command, 'blue')}")
+                if description:
+                    print(f"   {self._color(description, 'gray')}")
+                print()
+            
+            if self.verbose:
+                print(self._color("Run 'claude-mpm doctor --fix' to attempt automatic fixes", "gray"))
+            else:
+                print(self._color("Run 'claude-mpm doctor --verbose' for more details", "gray"))
+    
+    def _report_json(self, summary: DiagnosticSummary):
+        """Generate JSON-formatted report."""
+        output = summary.to_dict()
+        
+        # Add metadata
+        output["metadata"] = {
+            "tool": "claude-mpm doctor",
+            "version": self._get_version(),
+            "verbose": self.verbose
+        }
+        
+        # Add fix suggestions
+        fixes = []
+        for result in summary.results:
+            if result.fix_command and result.has_issues:
+                fixes.append({
+                    "category": result.category,
+                    "command": result.fix_command,
+                    "description": result.fix_description
+                })
+        output["fixes"] = fixes
+        
+        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} |")
+        print()
+        
+        # Detailed results
+        print("## 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()
+        
+        # Fixes section
+        fixes = [(r.category, r.fix_command, r.fix_description) 
+                 for r in summary.results if r.fix_command and r.has_issues]
+        
+        if fixes:
+            print("## Suggested Fixes\n")
+            for category, command, description in fixes:
+                print(f"- **{category}:** `{command}`")
+                if description:
+                    print(f"  - {description}")
+            print()
+    
+    def _color(self, text: str, color: str) -> str:
+        """Apply color to text if colors are enabled."""
+        if not self.use_color:
+            return text
+        
+        color_code = self.COLORS.get(color, "")
+        reset_code = self.COLORS["reset"]
+        return f"{color_code}{text}{reset_code}"
+    
+    def _get_status_color(self, status: DiagnosticStatus) -> str:
+        """Get color for a status."""
+        color_map = {
+            DiagnosticStatus.OK: "green",
+            DiagnosticStatus.WARNING: "yellow",
+            DiagnosticStatus.ERROR: "red",
+            DiagnosticStatus.SKIPPED: "gray"
+        }
+        return color_map.get(status, "reset")
+    
+    def _get_version(self) -> str:
+        """Get claude-mpm version."""
+        try:
+            from ..version_service import VersionService
+            service = VersionService()
+            return service.get_version()
+        except Exception:
+            return "unknown"

claude_mpm/services/diagnostics/models.py

@@ -0,0 +1,120 @@
+"""
+Data models for the diagnostic system.
+
+WHY: Define clear data structures for diagnostic results to ensure
+consistency across all checks and reporting.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class DiagnosticStatus(Enum):
+    """Status levels for diagnostic results."""
+    OK = "ok"
+    WARNING = "warning"
+    ERROR = "error"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class DiagnosticResult:
+    """Result from a diagnostic check.
+    
+    WHY: Standardized result format ensures consistent reporting
+    and makes it easy to aggregate and display results.
+    """
+    category: str  # e.g., "Installation", "Agents", "MCP Server"
+    status: DiagnosticStatus
+    message: str
+    details: Dict[str, Any] = field(default_factory=dict)
+    fix_command: Optional[str] = None
+    fix_description: Optional[str] = None
+    sub_results: List['DiagnosticResult'] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "category": self.category,
+            "status": self.status.value,
+            "message": self.message,
+            "details": self.details,
+            "fix_command": self.fix_command,
+            "fix_description": self.fix_description,
+            "sub_results": [r.to_dict() for r in self.sub_results]
+        }
+    
+    @property
+    def has_issues(self) -> bool:
+        """Check if this result indicates any issues."""
+        return self.status in (DiagnosticStatus.WARNING, DiagnosticStatus.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
+        }
+        return severity_map.get(self.status, 0)
+
+
+@dataclass
+class DiagnosticSummary:
+    """Summary of all diagnostic results.
+    
+    WHY: Provides a high-level overview of system health
+    and quick access to issues that need attention.
+    """
+    total_checks: int = 0
+    ok_count: int = 0
+    warning_count: int = 0
+    error_count: int = 0
+    skipped_count: int = 0
+    results: List[DiagnosticResult] = field(default_factory=list)
+    
+    def add_result(self, result: DiagnosticResult):
+        """Add a result to the summary."""
+        self.results.append(result)
+        self.total_checks += 1
+        
+        if result.status == DiagnosticStatus.OK:
+            self.ok_count += 1
+        elif result.status == DiagnosticStatus.WARNING:
+            self.warning_count += 1
+        elif result.status == DiagnosticStatus.ERROR:
+            self.error_count += 1
+        elif result.status == DiagnosticStatus.SKIPPED:
+            self.skipped_count += 1
+    
+    @property
+    def has_issues(self) -> bool:
+        """Check if there are any warnings or errors."""
+        return self.warning_count > 0 or self.error_count > 0
+    
+    @property
+    def overall_status(self) -> DiagnosticStatus:
+        """Get overall system status."""
+        if self.error_count > 0:
+            return DiagnosticStatus.ERROR
+        elif self.warning_count > 0:
+            return DiagnosticStatus.WARNING
+        else:
+            return DiagnosticStatus.OK
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "summary": {
+                "total_checks": self.total_checks,
+                "ok": self.ok_count,
+                "warnings": self.warning_count,
+                "errors": self.error_count,
+                "skipped": self.skipped_count,
+                "overall_status": self.overall_status.value
+            },
+            "results": [r.to_dict() for r in self.results]
+        }

claude_mpm/services/mcp_gateway/core/interfaces.py

@@ -413,7 +413,7 @@ class IMCPGateway(IMCPLifecycle):
     Main interface for MCP gateway implementation.
 
     Orchestrates tool registry, communication, and request handling.
-    Acts as a protocol bridge between Claude Desktop and internal tools.
+    Acts as a protocol bridge between Claude Code and internal tools.
     """
 
     @abstractmethod

claude_mpm/services/mcp_gateway/main.py

@@ -442,7 +442,7 @@ Examples:
   # Run with debug logging
   python -m claude_mpm.services.mcp_gateway.main --debug
 
-  # Run as MCP server for Claude Desktop
+  # Run as MCP server for Claude Code
   python -m claude_mpm.services.mcp_gateway.main --stdio
         """,
     )

claude_mpm/services/mcp_gateway/server/mcp_gateway.py

@@ -6,8 +6,8 @@ MCP protocol gateway using Anthropic's official MCP package.
 Handles stdio-based communication, request routing, and tool invocation.
 Acts as a bridge between Claude Code and internal tools.
 
-NOTE: MCP is ONLY for Claude Code - NOT for Claude Desktop.
-Claude Desktop uses a different system for agent deployment.
+NOTE: MCP is ONLY for Claude Code - NOT for Claude Code.
+Claude Code uses a different system for agent deployment.
 
 Part of ISS-0035: MCP Gateway Implementation - Core Gateway and Tool Registry
 """
@@ -339,7 +339,7 @@ class MCPGateway(BaseMCPService, IMCPGateway):
         to handle incoming requests from Claude Code.
 
         WHY: We use stdio (stdin/stdout) as it's the standard communication
-        method for MCP servers in Claude Desktop. This ensures compatibility
+        method for MCP servers in Claude Code. This ensures compatibility
         and allows the server to be launched as a subprocess.
         """
         try:

claude_mpm/services/mcp_gateway/server/stdio_handler.py

@@ -24,7 +24,7 @@ class StdioHandler(BaseMCPService, IMCPCommunication):
     STDIO-based communication handler for MCP.
 
     WHY: The MCP protocol uses stdio (stdin/stdout) for communication between
-    Claude Desktop and MCP servers. This handler manages the low-level
+    Claude Code and MCP servers. This handler manages the low-level
     message exchange, ensuring proper JSON-RPC formatting and error handling.
 
     DESIGN DECISIONS:

claude_mpm/services/mcp_gateway/server/stdio_server.py

@@ -3,7 +3,7 @@ Simplified MCP Stdio Server
 ============================
 
 A proper stdio-based MCP server that communicates via JSON-RPC over stdin/stdout.
-This server is spawned on-demand by Claude Desktop/Code and exits when the connection closes.
+This server is spawned on-demand by Claude Code/Code and exits when the connection closes.
 
 WHY: MCP servers should be simple stdio-based processes that Claude can spawn and control.
 They should NOT run as persistent background services with lock files.
@@ -45,7 +45,7 @@ def apply_backward_compatibility_patches():
     Apply backward compatibility patches for MCP protocol differences.
     
     This function patches the MCP Server to handle missing clientInfo
-    in initialize requests from older Claude Desktop versions.
+    in initialize requests from older Claude Code versions.
     """
     try:
         from mcp.server import Server
@@ -114,7 +114,7 @@ class SimpleMCPServer:
     A simple stdio-based MCP server implementation.
 
     WHY: This server follows the MCP specification for stdio communication,
-    making it compatible with Claude Desktop/Code's MCP client.
+    making it compatible with Claude Code/Code's MCP client.
 
     DESIGN DECISIONS:
     - No persistent state or lock files

claude_mpm/services/mcp_gateway/tools/ticket_tools.py

@@ -3,9 +3,9 @@ MCP Tool Adapters for aitrackdown Ticket Management
 ====================================================
 
 Provides MCP tool wrappers for common aitrackdown operations, enabling
-ticket management through Claude Desktop's MCP interface.
+ticket management through Claude Code's MCP interface.
 
-WHY: These tools allow Claude Desktop to interact with aitrackdown for
+WHY: These tools allow Claude Code to interact with aitrackdown for
 ticket management without requiring direct CLI access, providing a
 seamless integration experience.
 

claude_mpm/services/socketio/handlers/registry.py

@@ -70,21 +70,31 @@ class EventHandlerRegistry:
             )
             return
 
+        # Add debug logging for deployment context
+        try:
+            from ....core.unified_paths import PathContext
+            deployment_context = PathContext.detect_deployment_context()
+            self.logger.info(f"Initializing event handlers in {deployment_context.value} mode")
+        except Exception as e:
+            self.logger.debug(f"Could not detect deployment context: {e}")
+
         handler_classes = handler_classes or self.DEFAULT_HANDLERS
+        self.logger.debug(f"Initializing {len(handler_classes)} handler classes")
 
         for handler_class in handler_classes:
             try:
+                self.logger.debug(f"Creating instance of {handler_class.__name__}")
                 handler = handler_class(self.server)
                 self.handlers.append(handler)
-                self.logger.info(f"Initialized handler: {handler_class.__name__}")
+                self.logger.info(f"✅ Initialized handler: {handler_class.__name__}")
             except Exception as e:
-                self.logger.error(f"Failed to initialize {handler_class.__name__}: {e}")
+                self.logger.error(f"❌ Failed to initialize {handler_class.__name__}: {e}")
                 import traceback
 
                 self.logger.error(f"Stack trace: {traceback.format_exc()}")
 
         self._initialized = True
-        self.logger.info(f"Registry initialized with {len(self.handlers)} handlers")
+        self.logger.info(f"🎯 Registry initialized with {len(self.handlers)} handlers")
 
     def register_all_events(self) -> None:
         """Register all events from all handlers.
@@ -97,27 +107,49 @@ class EventHandlerRegistry:
             self.logger.error("Registry not initialized. Call initialize() first.")
             raise RuntimeError("EventHandlerRegistry not initialized")
 
+        self.logger.info(f"🔄 Starting event registration for {len(self.handlers)} handlers")
+        
+        # Verify Socket.IO server is available
+        if not hasattr(self.server, 'core') or not self.server.core or not self.server.core.sio:
+            self.logger.error("❌ Socket.IO server instance not available for event registration")
+            raise RuntimeError("Socket.IO server not available")
+        
+        self.logger.debug(f"Socket.IO server available: {type(self.server.core.sio)}")
+
         registered_count = 0
         for handler in self.handlers:
             try:
+                self.logger.debug(f"Registering events for {handler.__class__.__name__}")
+                
+                # Get the number of registered events before and after
+                sio_events_before = len(getattr(self.server.core.sio, 'handlers', {}))
+                
                 handler.register_events()
+                
+                sio_events_after = len(getattr(self.server.core.sio, 'handlers', {}))
+                events_added = sio_events_after - sio_events_before
+                
                 registered_count += 1
-                self.logger.info(f"Registered events for {handler.__class__.__name__}")
+                self.logger.info(f"✅ Registered {events_added} events for {handler.__class__.__name__}")
+                
             except NotImplementedError:
                 # Handler has no events to register (like ProjectEventHandler)
                 self.logger.debug(
-                    f"No events to register for {handler.__class__.__name__}"
+                    f"⏭️  No events to register for {handler.__class__.__name__}"
                 )
             except Exception as e:
                 self.logger.error(
-                    f"Failed to register events for {handler.__class__.__name__}: {e}"
+                    f"❌ Failed to register events for {handler.__class__.__name__}: {e}"
                 )
                 import traceback
 
                 self.logger.error(f"Stack trace: {traceback.format_exc()}")
 
+        # Final verification
+        total_sio_events = len(getattr(self.server.core.sio, 'handlers', {}))
         self.logger.info(
-            f"Successfully registered events from {registered_count} handlers"
+            f"🎉 Event registration complete: {registered_count} handlers processed, "
+            f"{total_sio_events} total Socket.IO events registered"
         )
 
     def add_handler(self, handler_class: Type[BaseEventHandler]):