claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/cli/parsers/debug_parser.py

@@ -0,0 +1,319 @@
+"""
+Debug command parser for claude-mpm CLI.
+
+This module contains all arguments specific to debugging tools,
+providing developer-focused commands for monitoring and analysis.
+"""
+
+import argparse
+
+from .base_parser import add_common_arguments
+
+
+def add_debug_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the debug subparser with all debugging commands.
+
+    This provides professional debugging tools for developers working
+    on claude-mpm, particularly for dashboard and event monitoring.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured debug subparser
+    """
+    # Main debug parser
+    debug_parser = subparsers.add_parser(
+        "debug",
+        help="Development debugging tools",
+        description="Professional debugging tools for claude-mpm developers",
+    )
+
+    # Add common arguments (logging, etc.)
+    add_common_arguments(debug_parser)
+
+    # Create subparsers for debug commands
+    debug_subparsers = debug_parser.add_subparsers(
+        dest="debug_command", help="Debug commands", metavar="SUBCOMMAND", required=True
+    )
+
+    # SocketIO event debugging
+    _add_socketio_parser(debug_subparsers)
+
+    # Connection debugging
+    _add_connections_parser(debug_subparsers)
+
+    # Services debugging
+    _add_services_parser(debug_subparsers)
+
+    # Agents debugging
+    _add_agents_parser(debug_subparsers)
+
+    # Hooks debugging
+    _add_hooks_parser(debug_subparsers)
+
+    # Cache debugging
+    _add_cache_parser(debug_subparsers)
+
+    # Performance debugging
+    _add_performance_parser(debug_subparsers)
+
+    return debug_parser
+
+
+def _add_socketio_parser(subparsers):
+    """Add SocketIO debugging subcommand."""
+    socketio_parser = subparsers.add_parser(
+        "socketio",
+        help="Monitor and debug SocketIO events in real-time",
+        aliases=["events", "socket"],
+        description="""
+Professional SocketIO event monitoring tool for dashboard development.
+
+This tool provides real-time monitoring of all SocketIO events with:
+- Live event streaming with formatted output
+- Event statistics and aggregation
+- Tool usage tracking
+- Session monitoring
+- Connection health checks
+- Event filtering and export capabilities
+
+Examples:
+  # Monitor all events in real-time
+  claude-mpm debug socketio
+
+  # Show event summary statistics
+  claude-mpm debug socketio --summary
+
+  # Filter specific event types
+  claude-mpm debug socketio --filter PreToolUse PostToolUse
+
+  # Save events to file for analysis
+  claude-mpm debug socketio --output events.jsonl
+
+  # Connect to specific server
+  claude-mpm debug socketio --host localhost --port 8765
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Connection settings
+    conn_group = socketio_parser.add_argument_group("connection settings")
+    conn_group.add_argument(
+        "--host", default="localhost", help="SocketIO server host (default: localhost)"
+    )
+    conn_group.add_argument(
+        "--port", type=int, default=8765, help="SocketIO server port (default: 8765)"
+    )
+    conn_group.add_argument(
+        "--max-reconnect",
+        type=int,
+        default=10,
+        help="Maximum reconnection attempts (default: 10)",
+    )
+    conn_group.add_argument(
+        "--reconnect-delay",
+        type=float,
+        default=1.0,
+        help="Reconnection delay in seconds (default: 1.0)",
+    )
+
+    # Display modes (mutually exclusive)
+    display_group = socketio_parser.add_argument_group("display modes")
+    mode_group = display_group.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--live",
+        action="store_true",
+        help="Live event monitoring with formatted output (default)",
+    )
+    mode_group.add_argument(
+        "--summary",
+        action="store_true",
+        help="Show aggregated event statistics and summary",
+    )
+    mode_group.add_argument(
+        "--raw", action="store_true", help="Display raw JSON output for each event"
+    )
+    mode_group.add_argument(
+        "--pretty",
+        action="store_true",
+        help="Enhanced formatted output with colors and icons",
+    )
+
+    # Filtering and output
+    filter_group = socketio_parser.add_argument_group("filtering and output")
+    filter_group.add_argument(
+        "--filter",
+        nargs="+",
+        dest="filter_types",
+        metavar="TYPE",
+        help="Filter specific event types (e.g., PreToolUse PostToolUse)",
+    )
+    filter_group.add_argument(
+        "--output", "-o", metavar="FILE", help="Save events to file in JSONL format"
+    )
+    filter_group.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress output except errors (useful with --output)",
+    )
+
+
+def _add_connections_parser(subparsers):
+    """Add connections debugging subcommand."""
+    connections_parser = subparsers.add_parser(
+        "connections",
+        help="Show active SocketIO server connections",
+        aliases=["conn", "servers"],
+        description="""
+Display information about active SocketIO servers and their status.
+
+This command shows:
+- All running SocketIO server instances
+- Port numbers and process IDs
+- Connection health status
+- Server start times
+
+Examples:
+  # Show all active servers
+  claude-mpm debug connections
+
+  # Show detailed information
+  claude-mpm debug connections --verbose
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    connections_parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show detailed connection information in JSON format",
+    )
+    connections_parser.add_argument(
+        "--check-health",
+        action="store_true",
+        help="Perform health checks on each server",
+    )
+    connections_parser.add_argument(
+        "--cleanup", action="store_true", help="Clean up stale server entries"
+    )
+
+
+def _add_services_parser(subparsers):
+    """Add services debugging subcommand."""
+    services_parser = subparsers.add_parser(
+        "services",
+        help="Debug service container and dependencies",
+        description="Inspect services, dependencies, and health status",
+    )
+
+    services_group = services_parser.add_mutually_exclusive_group()
+    services_group.add_argument(
+        "--list", action="store_true", help="List all registered services"
+    )
+    services_group.add_argument(
+        "--status", action="store_true", help="Show service health status"
+    )
+    services_group.add_argument(
+        "--dependencies", action="store_true", help="Show service dependency graph"
+    )
+    services_group.add_argument(
+        "--trace",
+        metavar="SERVICE",
+        help="Trace service resolution for specific service",
+    )
+
+
+def _add_agents_parser(subparsers):
+    """Add agents debugging subcommand."""
+    agents_parser = subparsers.add_parser(
+        "agents",
+        help="Debug deployed agents and memory",
+        description="Inspect deployed agents, memory, and traces",
+    )
+
+    agents_group = agents_parser.add_mutually_exclusive_group()
+    agents_group.add_argument(
+        "--deployed", action="store_true", help="List all deployed agents"
+    )
+    agents_group.add_argument(
+        "--memory", action="store_true", help="Show agent memory status"
+    )
+    agents_group.add_argument(
+        "--trace", metavar="AGENT", help="Trace specific agent execution"
+    )
+    agents_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Show detailed information"
+    )
+
+
+def _add_hooks_parser(subparsers):
+    """Add hooks debugging subcommand."""
+    hooks_parser = subparsers.add_parser(
+        "hooks",
+        help="Debug hook system",
+        description="List hooks, trace execution, analyze performance",
+    )
+
+    hooks_group = hooks_parser.add_mutually_exclusive_group()
+    hooks_group.add_argument(
+        "--list", action="store_true", help="List all registered hooks"
+    )
+    hooks_group.add_argument(
+        "--trace", metavar="HOOK", help="Trace specific hook execution"
+    )
+    hooks_group.add_argument(
+        "--performance", action="store_true", help="Analyze hook performance"
+    )
+    hooks_parser.add_argument(
+        "--test", action="store_true", help="Run test execution when tracing"
+    )
+
+
+def _add_cache_parser(subparsers):
+    """Add cache debugging subcommand."""
+    cache_parser = subparsers.add_parser(
+        "cache",
+        help="Debug cache system",
+        description="Inspect, clear, and analyze cache",
+    )
+
+    cache_group = cache_parser.add_mutually_exclusive_group()
+    cache_group.add_argument(
+        "--inspect", action="store_true", help="Inspect cache contents"
+    )
+    cache_group.add_argument("--clear", action="store_true", help="Clear all cache")
+    cache_group.add_argument(
+        "--stats", action="store_true", help="Show cache performance statistics"
+    )
+    cache_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Show detailed cache information"
+    )
+    cache_parser.add_argument(
+        "--confirm",
+        "-y",
+        action="store_true",
+        help="Skip confirmation for clear operation",
+    )
+
+
+def _add_performance_parser(subparsers):
+    """Add performance debugging subcommand."""
+    performance_parser = subparsers.add_parser(
+        "performance",
+        help="Performance profiling and analysis",
+        description="Profile operations and analyze bottlenecks",
+    )
+
+    perf_group = performance_parser.add_mutually_exclusive_group()
+    perf_group.add_argument(
+        "--profile",
+        metavar="OPERATION",
+        help="Profile specific operation (agent_load, service_init, cache_ops, memory_ops)",
+    )
+    perf_group.add_argument(
+        "--benchmark", action="store_true", help="Run performance benchmarks"
+    )

claude_mpm/cli/parsers/local_deploy_parser.py

@@ -0,0 +1,227 @@
+"""
+Local Deploy parser module for claude-mpm CLI.
+
+WHY: Provides argument parsing for local deployment management commands.
+Extracted from the monolithic parser.py for better organization.
+
+DESIGN DECISION: Supports multiple subcommands (start, stop, restart, status, etc.)
+with command-specific arguments for comprehensive process management.
+"""
+
+from pathlib import Path
+
+
+def add_local_deploy_arguments(subparsers) -> None:
+    """
+    Add local-deploy command and its subcommands to the parser.
+
+    WHY: Provides a comprehensive CLI for managing local development deployments
+    with process monitoring, health checks, and auto-restart capabilities.
+
+    Args:
+        subparsers: The subparsers object to add commands to
+    """
+    # Main local-deploy command
+    local_deploy_parser = subparsers.add_parser(
+        "local-deploy",
+        help="Manage local development deployments with process monitoring",
+        description=(
+            "Manage local development deployments with comprehensive process management, "
+            "health monitoring, and auto-restart capabilities."
+        ),
+    )
+
+    # Create subparsers for local-deploy subcommands
+    local_deploy_subparsers = local_deploy_parser.add_subparsers(
+        dest="local_deploy_command",
+        help="Local deployment commands",
+    )
+
+    # ===== START command =====
+    start_parser = local_deploy_subparsers.add_parser(
+        "start",
+        help="Start a new local deployment",
+        description="Start a new local deployment with process monitoring and optional auto-restart",
+    )
+    start_parser.add_argument(
+        "--command",
+        "-c",
+        required=True,
+        help="Command to execute (e.g., 'npm run dev' or 'python manage.py runserver')",
+    )
+    start_parser.add_argument(
+        "--working-directory",
+        "-d",
+        type=Path,
+        help="Working directory for the process (default: current directory)",
+    )
+    start_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        help="Port number for the deployment",
+    )
+    start_parser.add_argument(
+        "--auto-find-port",
+        action="store_true",
+        default=True,
+        help="Automatically find alternative port if specified port is unavailable (default: enabled)",
+    )
+    start_parser.add_argument(
+        "--no-auto-find-port",
+        action="store_false",
+        dest="auto_find_port",
+        help="Disable automatic port finding",
+    )
+    start_parser.add_argument(
+        "--auto-restart",
+        action="store_true",
+        help="Enable automatic restart on crashes",
+    )
+    start_parser.add_argument(
+        "--log-file",
+        type=Path,
+        help="Path to log file for monitoring error patterns",
+    )
+    start_parser.add_argument(
+        "--env",
+        "-e",
+        action="append",
+        help="Environment variables in KEY=VALUE format (can be specified multiple times)",
+    )
+
+    # ===== STOP command =====
+    stop_parser = local_deploy_subparsers.add_parser(
+        "stop",
+        help="Stop a running deployment",
+        description="Stop a running deployment with graceful shutdown",
+    )
+    stop_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to stop",
+    )
+    stop_parser.add_argument(
+        "--timeout",
+        "-t",
+        type=int,
+        default=10,
+        help="Timeout in seconds for graceful shutdown (default: 10)",
+    )
+    stop_parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Force kill immediately without graceful shutdown",
+    )
+
+    # ===== RESTART command =====
+    restart_parser = local_deploy_subparsers.add_parser(
+        "restart",
+        help="Restart a deployment",
+        description="Restart a deployment with the same configuration",
+    )
+    restart_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to restart",
+    )
+    restart_parser.add_argument(
+        "--timeout",
+        "-t",
+        type=int,
+        default=10,
+        help="Timeout in seconds for graceful shutdown (default: 10)",
+    )
+
+    # ===== STATUS command =====
+    status_parser = local_deploy_subparsers.add_parser(
+        "status",
+        help="Show comprehensive deployment status",
+        description="Show comprehensive status including process info, health, and restart history",
+    )
+    status_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to check",
+    )
+    status_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output status in JSON format",
+    )
+
+    # ===== HEALTH command =====
+    health_parser = local_deploy_subparsers.add_parser(
+        "health",
+        help="Show health status",
+        description="Show health check status including HTTP, process, and resource checks",
+    )
+    health_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to check",
+    )
+
+    # ===== LIST command =====
+    list_parser = local_deploy_subparsers.add_parser(
+        "list",
+        help="List all deployments",
+        description="List all local deployments with their status",
+    )
+    list_parser.add_argument(
+        "--status",
+        "-s",
+        choices=["running", "stopped", "crashed", "stopping"],
+        help="Filter deployments by status",
+    )
+
+    # ===== MONITOR command =====
+    monitor_parser = local_deploy_subparsers.add_parser(
+        "monitor",
+        help="Live monitoring dashboard",
+        description="Display live monitoring dashboard for a deployment",
+    )
+    monitor_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to monitor",
+    )
+    monitor_parser.add_argument(
+        "--refresh",
+        "-r",
+        type=int,
+        default=2,
+        help="Refresh interval in seconds (default: 2)",
+    )
+
+    # ===== HISTORY command =====
+    history_parser = local_deploy_subparsers.add_parser(
+        "history",
+        help="Show restart history",
+        description="Show restart history and statistics for a deployment",
+    )
+    history_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to check",
+    )
+
+    # ===== ENABLE-AUTO-RESTART command =====
+    enable_auto_restart_parser = local_deploy_subparsers.add_parser(
+        "enable-auto-restart",
+        help="Enable auto-restart for a deployment",
+        description="Enable automatic restart on crashes for a deployment",
+    )
+    enable_auto_restart_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to enable auto-restart for",
+    )
+
+    # ===== DISABLE-AUTO-RESTART command =====
+    disable_auto_restart_parser = local_deploy_subparsers.add_parser(
+        "disable-auto-restart",
+        help="Disable auto-restart for a deployment",
+        description="Disable automatic restart on crashes for a deployment",
+    )
+    disable_auto_restart_parser.add_argument(
+        "deployment_id",
+        help="Deployment ID to disable auto-restart for",
+    )
+
+
+__all__ = ["add_local_deploy_arguments"]

claude_mpm/cli/parsers/mcp_parser.py

@@ -177,4 +177,19 @@ def add_mcp_subparser(subparsers) -> argparse.ArgumentParser:
         help="Show setup instructions for Claude Code",
     )
 
+    # External MCP services management
+    external_mcp_parser = mcp_subparsers.add_parser(
+        MCPCommands.EXTERNAL.value, help="Manage external MCP services"
+    )
+    external_mcp_parser.add_argument(
+        "external_action",
+        nargs="?",
+        choices=["setup", "list", "check", "fix-browser", "detect"],
+        default="list",
+        help="External service action (default: list)",
+    )
+    external_mcp_parser.add_argument(
+        "--force", action="store_true", help="Force overwrite existing configuration"
+    )
+
     return mcp_parser

claude_mpm/cli/parsers/monitor_parser.py

@@ -58,8 +58,18 @@ def add_monitor_subparser(subparsers) -> argparse.ArgumentParser:
         default=8766,
         help="Dashboard port (default: 8766)",
     )
-    start_monitor_parser.add_argument(
-        "--background", action="store_true", help="Run server in background"
+    # Add mutually exclusive group for foreground/background modes
+    mode_group = start_monitor_parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--foreground",
+        action="store_true",
+        help="Run server in foreground mode (blocks terminal)",
+    )
+    mode_group.add_argument(
+        "--background",
+        action="store_true",
+        default=None,  # None allows us to detect when not specified
+        help="Run server in background/daemon mode (default behavior)",
     )
     start_monitor_parser.add_argument(
         "--force",