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

claude_mpm/cli/parsers/base_parser.py

@@ -11,11 +11,96 @@ and reduce duplication across command parsers.
 """
 
 import argparse
+import sys
 from typing import List, Optional
 
 from ...constants import CLICommands, CLIPrefix, LogLevel
 
 
+class SuggestingArgumentParser(argparse.ArgumentParser):
+    """
+    Custom ArgumentParser that suggests similar commands on error.
+
+    WHY: Provides better user experience by suggesting corrections for typos
+    and invalid commands instead of just showing an error message.
+
+    DESIGN DECISION: Extends ArgumentParser.error() to add suggestions before
+    exiting. This catches all parser errors including invalid subcommands and
+    invalid options.
+    """
+
+    def error(self, message: str) -> None:
+        """
+        Override error method to add command suggestions.
+
+        Args:
+            message: Error message from argparse
+        """
+        from ..utils import suggest_similar_commands
+
+        # Try to extract the invalid command/option from the error message
+        invalid_value = None
+        valid_choices = []
+
+        # Handle invalid subcommand errors
+        # Format: "argument COMMAND: invalid choice: 'tickts' (choose from ...)"
+        if "invalid choice:" in message:
+            try:
+                # Extract the invalid choice
+                parts = message.split("invalid choice: '")
+                if len(parts) > 1:
+                    invalid_value = parts[1].split("'")[0]
+
+                # Extract valid choices
+                if "(choose from" in message:
+                    choices_part = message.split("(choose from")[1]
+                    # Remove trailing parenthesis and split
+                    choices_str = choices_part.rstrip(")")
+                    # Parse choices - they may be quoted or unquoted
+                    valid_choices = [
+                        c.strip().strip("'\"")
+                        for c in choices_str.split(",")
+                        if c.strip()
+                    ]
+            except (IndexError, ValueError):
+                pass
+
+        # Handle unrecognized arguments (invalid options)
+        # Format: "unrecognized arguments: --verbos"
+        elif "unrecognized arguments:" in message:
+            try:
+                parts = message.split("unrecognized arguments:")
+                if len(parts) > 1:
+                    invalid_value = parts[1].strip().split()[0]
+
+                # Get common options from parser
+                valid_choices = []
+                for action in self._actions:
+                    for option in action.option_strings:
+                        valid_choices.append(option)
+            except (IndexError, ValueError):
+                pass
+
+        # Build error message with suggestions
+        from rich.console import Console
+
+        console = Console(stderr=True)
+
+        console.print(f"\n[red]Error:[/red] {message}\n", style="bold")
+
+        # Add suggestions if we found valid choices
+        if invalid_value and valid_choices:
+            suggestion = suggest_similar_commands(invalid_value, valid_choices)
+            if suggestion:
+                console.print(f"[yellow]{suggestion}[/yellow]\n")
+
+        # Show help hint
+        console.print(f"[dim]Run '{self.prog} --help' for usage information.[/dim]\n")
+
+        # Exit with error code
+        sys.exit(2)
+
+
 def _get_enhanced_version(base_version: str) -> str:
     """
     Get enhanced version string with build number if available.
@@ -111,15 +196,18 @@ def create_main_parser(
     WHY: This creates the foundation parser that other modules will extend
     with their specific subcommands and arguments.
 
+    DESIGN DECISION: Uses SuggestingArgumentParser to provide helpful suggestions
+    for typos and invalid commands, improving user experience.
+
     Args:
         prog_name: The program name to use
         version: The version string to display
 
     Returns:
-        Configured ArgumentParser instance ready for subparser addition
+        Configured SuggestingArgumentParser instance ready for subparser addition
     """
-    # Main parser
-    parser = argparse.ArgumentParser(
+    # Main parser with suggestion support
+    parser = SuggestingArgumentParser(
         prog=prog_name,
         description=f"Claude Multi-Agent Project Manager v{version} - Orchestrate Claude with agent delegation and ticket tracking",
         epilog="By default, runs an orchestrated Claude session. Use 'claude-mpm' for interactive mode or 'claude-mpm -i \"prompt\"' for non-interactive mode.\n\nTo pass arguments to Claude CLI, use -- separator: claude-mpm run -- --model sonnet --temperature 0.1",
@@ -199,6 +287,11 @@ def add_top_level_run_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Force operations even with warnings (e.g., large .claude.json file)",
     )
+    run_group.add_argument(
+        "--reload-agents",
+        action="store_true",
+        help="Force rebuild of all system agents by deleting local claude-mpm agents",
+    )
 
     # Dependency checking options (for backward compatibility at top level)
     dep_group_top = parser.add_argument_group(
@@ -296,6 +389,13 @@ def create_parser(
     except ImportError:
         pass
 
+    try:
+        from .auto_configure_parser import add_auto_configure_subparser
+
+        add_auto_configure_subparser(subparsers)
+    except ImportError:
+        pass
+
     try:
         from .memory_parser import add_memory_subparser
 
@@ -303,6 +403,13 @@ def create_parser(
     except ImportError:
         pass
 
+    try:
+        from .skills_parser import add_skills_subparser
+
+        add_skills_subparser(subparsers)
+    except ImportError:
+        pass
+
     try:
         from .config_parser import add_config_subparser
 
@@ -324,6 +431,13 @@ def create_parser(
     except ImportError:
         pass
 
+    try:
+        from .local_deploy_parser import add_local_deploy_arguments
+
+        add_local_deploy_arguments(subparsers)
+    except ImportError:
+        pass
+
     try:
         from .mcp_parser import add_mcp_subparser
 
@@ -345,6 +459,14 @@ def create_parser(
     except ImportError:
         pass
 
+    # Add uninstall command parser
+    try:
+        from ..commands.uninstall import add_uninstall_parser
+
+        add_uninstall_parser(subparsers)
+    except ImportError:
+        pass
+
     # Add debug command parser
     try:
         from .debug_parser import add_debug_subparser
@@ -382,6 +504,14 @@ def create_parser(
     except ImportError:
         pass
 
+    # Add search command parser
+    try:
+        from .search_parser import add_search_subparser
+
+        add_search_subparser(subparsers)
+    except ImportError:
+        pass
+
     # Import and add additional command parsers from commands module
     try:
         from ..commands.aggregate import add_aggregate_parser
@@ -401,6 +531,16 @@ def create_parser(
         from ..commands.doctor import add_doctor_parser
 
         add_doctor_parser(subparsers)
+
+        # Add upgrade command
+        from ..commands.upgrade import add_upgrade_parser
+
+        add_upgrade_parser(subparsers)
+
+        # Add verify command for MCP service verification
+        from ..commands.verify import add_parser as add_verify_parser
+
+        add_verify_parser(subparsers)
     except ImportError:
         # Commands module may not be available during testing or refactoring
         pass

claude_mpm/cli/parsers/configure_parser.py

@@ -25,11 +25,11 @@ def add_configure_subparser(subparsers) -> argparse.ArgumentParser:
     Returns:
         The configured configure subparser
     """
-    # Configure command - interactive TUI configuration
+    # Configure command - interactive configuration
     configure_parser = subparsers.add_parser(
         CLICommands.CONFIGURE.value,
-        help="Interactive terminal-based configuration interface for managing agents and behaviors",
-        description="Launch an interactive Rich-based TUI for configuring claude-mpm agents, templates, and behavior files",
+        help="Interactive configuration interface for managing agents and behaviors",
+        description="Launch an interactive Rich-based menu for configuring claude-mpm agents, templates, and behavior files",
     )
 
     # Add common arguments
@@ -58,6 +58,11 @@ def add_configure_subparser(subparsers) -> argparse.ArgumentParser:
         action="store_true",
         help="Jump directly to behavior file management",
     )
+    nav_group.add_argument(
+        "--startup",
+        action="store_true",
+        help="Configure startup services and agents",
+    )
     nav_group.add_argument(
         "--version-info",
         action="store_true",
@@ -122,21 +127,12 @@ def add_configure_subparser(subparsers) -> argparse.ArgumentParser:
     # Display options
     display_group = configure_parser.add_argument_group("display options")
     display_group.add_argument(
-        "--no-colors", action="store_true", help="Disable colored output in the TUI"
-    )
-    display_group.add_argument(
-        "--compact", action="store_true", help="Use compact display mode"
-    )
-    display_group.add_argument(
-        "--force-rich",
+        "--no-colors",
         action="store_true",
-        help="Force use of Rich menu interface instead of full-screen Textual TUI",
+        help="Disable colored output in the interface",
     )
     display_group.add_argument(
-        "--no-textual",
-        dest="use_textual",
-        action="store_false",
-        help="Disable Textual TUI and use Rich menu interface",
+        "--compact", action="store_true", help="Use compact display mode"
     )
 
     return configure_parser

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",