claude-mpm 4.13.2__py3-none-any.whl → 4.18.2__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",
@@ -336,6 +424,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
 

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/shared/output_formatters.py

@@ -7,6 +7,8 @@ from typing import Any, Dict, List, Optional, Union
 
 import yaml
 
+from claude_mpm.core.enums import OutputFormat
+
 
 class OutputFormatter:
     """Handles formatting output in different formats."""
@@ -104,13 +106,13 @@ class OutputFormatter:
         return str(data)
 
 
-def format_output(data: Any, format_type: str = "text", **kwargs) -> str:
+def format_output(data: Any, format_type: str = OutputFormat.TEXT, **kwargs) -> str:
     """
     Format data according to the specified format.
 
     Args:
         data: Data to format
-        format_type: Output format ('json', 'yaml', 'table', 'text')
+        format_type: Output format (use OutputFormat enum or string)
         **kwargs: Additional formatting options
 
     Returns:
@@ -118,20 +120,23 @@ def format_output(data: Any, format_type: str = "text", **kwargs) -> str:
     """
     formatter = OutputFormatter()
 
-    if format_type == "json":
+    # Convert to string for comparison (handles both enum and string inputs)
+    fmt = str(format_type).lower()
+
+    if fmt == OutputFormat.JSON:
         return formatter.format_json(data, **kwargs)
-    if format_type == "yaml":
+    if fmt == OutputFormat.YAML:
         return formatter.format_yaml(data)
-    if format_type == "table":
+    if fmt == OutputFormat.TABLE:
         return formatter.format_table(data, **kwargs)
-    if format_type == "text":
+    if fmt == OutputFormat.TEXT:
         return formatter.format_text(data)
     # Fallback to text format
     return formatter.format_text(data)
 
 
 def format_success_message(
-    message: str, data: Any = None, format_type: str = "text"
+    message: str, data: Any = None, format_type: str = OutputFormat.TEXT
 ) -> str:
     """
     Format a success message with optional data.
@@ -139,12 +144,13 @@ def format_success_message(
     Args:
         message: Success message
         data: Optional data to include
-        format_type: Output format
+        format_type: Output format (use OutputFormat enum or string)
 
     Returns:
         Formatted success message
     """
-    if format_type in ("json", "yaml"):
+    fmt = str(format_type).lower()
+    if fmt in (OutputFormat.JSON, OutputFormat.YAML):
         result = {"success": True, "message": message}
         if data is not None:
             result["data"] = data
@@ -158,7 +164,7 @@ def format_success_message(
 
 
 def format_error_message(
-    message: str, details: Any = None, format_type: str = "text"
+    message: str, details: Any = None, format_type: str = OutputFormat.TEXT
 ) -> str:
     """
     Format an error message with optional details.
@@ -166,12 +172,13 @@ def format_error_message(
     Args:
         message: Error message
         details: Optional error details
-        format_type: Output format
+        format_type: Output format (use OutputFormat enum or string)
 
     Returns:
         Formatted error message
     """
-    if format_type in ("json", "yaml"):
+    fmt = str(format_type).lower()
+    if fmt in (OutputFormat.JSON, OutputFormat.YAML):
         result = {"success": False, "error": message}
         if details is not None:
             result["details"] = details
@@ -187,7 +194,7 @@ def format_error_message(
 def format_list_output(
     items: List[Any],
     title: Optional[str] = None,
-    format_type: str = "text",
+    format_type: str = OutputFormat.TEXT,
     headers: Optional[List[str]] = None,
 ) -> str:
     """
@@ -196,29 +203,31 @@ def format_list_output(
     Args:
         items: List of items to format
         title: Optional title for the list
-        format_type: Output format
+        format_type: Output format (use OutputFormat enum or string)
         headers: Optional headers for table format
 
     Returns:
         Formatted list output
     """
+    fmt = str(format_type).lower()
+
     if not items:
         empty_msg = f"No {title.lower() if title else 'items'} found"
-        if format_type in ("json", "yaml"):
+        if fmt in (OutputFormat.JSON, OutputFormat.YAML):
             return format_output({"items": [], "message": empty_msg}, format_type)
         return empty_msg
 
-    if format_type in ("json", "yaml"):
+    if fmt in (OutputFormat.JSON, OutputFormat.YAML):
         result = {"items": items}
         if title:
             result["title"] = title
         return format_output(result, format_type)
 
-    if format_type == "table":
+    if fmt == OutputFormat.TABLE:
         output = ""
         if title:
             output += f"{title}\n{'=' * len(title)}\n\n"
-        output += format_output(items, "table", headers=headers)
+        output += format_output(items, OutputFormat.TABLE, headers=headers)
         return output
 
     # Text format
@@ -228,5 +237,5 @@ def format_list_output(
         lines.append("=" * len(title))
         lines.append("")
 
-    lines.append(format_output(items, "text"))
+    lines.append(format_output(items, OutputFormat.TEXT))
     return "\n".join(lines)