claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/cli/parsers/auto_configure_parser.py

@@ -0,0 +1,245 @@
+"""
+Auto-Configuration Parser for Claude MPM CLI
+============================================
+
+WHY: This module provides argument parsing for auto-configuration commands,
+enabling users to customize detection, recommendation, and deployment behavior.
+
+DESIGN DECISION: Follows existing parser patterns in the codebase, using
+add_common_arguments for consistency. Provides sensible defaults while
+allowing full customization.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 5
+"""
+
+import argparse
+from pathlib import Path
+
+from .base_parser import add_common_arguments
+
+
+def add_auto_configure_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the auto-configure subparser for automated agent configuration.
+
+    WHY: Auto-configuration simplifies onboarding by detecting project toolchain
+    and deploying appropriate agents automatically.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured auto-configure subparser
+    """
+    # Auto-configure command
+    auto_configure_parser = subparsers.add_parser(
+        "auto-configure",
+        help="Auto-configure agents based on project toolchain detection",
+        description="""
+Auto-configure agents for your project based on detected toolchain.
+
+This command analyzes your project to detect languages, frameworks, and
+deployment targets, then recommends and deploys appropriate specialized
+agents automatically.
+
+The command provides safety features including:
+  • Preview mode to see changes before applying
+  • Confidence thresholds to ensure quality matches
+  • Validation gates to block invalid configurations
+  • Rollback on failure to maintain consistency
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive configuration with confirmation
+  claude-mpm auto-configure
+
+  # Preview configuration without deploying
+  claude-mpm auto-configure --preview
+
+  # Auto-approve deployment (for scripts)
+  claude-mpm auto-configure --yes
+
+  # Require 90% confidence for recommendations
+  claude-mpm auto-configure --min-confidence 0.9
+
+  # JSON output for scripting
+  claude-mpm auto-configure --json
+
+  # Configure specific project directory
+  claude-mpm auto-configure --project-path /path/to/project
+        """,
+    )
+    add_common_arguments(auto_configure_parser)
+
+    # Configuration mode
+    mode_group = auto_configure_parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--preview",
+        "--dry-run",
+        dest="preview",
+        action="store_true",
+        help="Show what would be configured without deploying (preview mode)",
+    )
+    mode_group.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompts and deploy automatically",
+    )
+
+    # Configuration options
+    auto_configure_parser.add_argument(
+        "--min-confidence",
+        type=float,
+        default=0.8,
+        metavar="FLOAT",
+        help="Minimum confidence threshold for recommendations (0.0-1.0, default: 0.8)",
+    )
+
+    auto_configure_parser.add_argument(
+        "--project-path",
+        type=Path,
+        metavar="PATH",
+        help="Project path to analyze (default: current directory)",
+    )
+
+    return auto_configure_parser
+
+
+def add_agents_detect_subparser(agents_subparsers) -> argparse.ArgumentParser:
+    """
+    Add the agents detect subparser for toolchain detection.
+
+    WHY: Allows users to see what toolchain is detected without making changes,
+    useful for debugging and verification.
+
+    Args:
+        agents_subparsers: The agents subparsers object
+
+    Returns:
+        The configured detect subparser
+    """
+    detect_parser = agents_subparsers.add_parser(
+        "detect",
+        help="Detect project toolchain without deploying",
+        description="""
+Detect and display project toolchain without making any changes.
+
+This command analyzes your project to detect:
+  • Programming languages and versions
+  • Frameworks and libraries
+  • Deployment targets and platforms
+
+Useful for debugging toolchain detection and verifying what would be
+detected before running auto-configure.
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Detect toolchain in current directory
+  claude-mpm agents detect
+
+  # Detect with verbose output showing evidence
+  claude-mpm agents detect --verbose
+
+  # JSON output for scripting
+  claude-mpm agents detect --json
+
+  # Detect specific project
+  claude-mpm agents detect --project-path /path/to/project
+        """,
+    )
+    add_common_arguments(detect_parser)
+
+    detect_parser.add_argument(
+        "--project-path",
+        type=Path,
+        metavar="PATH",
+        help="Project path to analyze (default: current directory)",
+    )
+
+    return detect_parser
+
+
+def add_agents_recommend_subparser(
+    agents_subparsers,
+) -> argparse.ArgumentParser:
+    """
+    Add the agents recommend subparser for agent recommendations.
+
+    WHY: Allows users to see what agents would be recommended without deploying,
+    useful for reviewing recommendations before committing to deployment.
+
+    Args:
+        agents_subparsers: The agents subparsers object
+
+    Returns:
+        The configured recommend subparser
+    """
+    recommend_parser = agents_subparsers.add_parser(
+        "recommend",
+        help="Show recommended agents without deploying",
+        description="""
+Show recommended agents based on project toolchain without deploying.
+
+This command analyzes your project toolchain and recommends appropriate
+agents with detailed reasoning for each recommendation. No changes are
+made to your project.
+
+Useful for:
+  • Reviewing recommendations before deployment
+  • Understanding why agents are recommended
+  • Adjusting confidence thresholds
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Show recommendations with reasoning
+  claude-mpm agents recommend
+
+  # Require 90% confidence for recommendations
+  claude-mpm agents recommend --min-confidence 0.9
+
+  # JSON output for scripting
+  claude-mpm agents recommend --json
+
+  # Hide detailed reasoning
+  claude-mpm agents recommend --no-reasoning
+
+  # Recommend for specific project
+  claude-mpm agents recommend --project-path /path/to/project
+        """,
+    )
+    add_common_arguments(recommend_parser)
+
+    recommend_parser.add_argument(
+        "--project-path",
+        type=Path,
+        metavar="PATH",
+        help="Project path to analyze (default: current directory)",
+    )
+
+    recommend_parser.add_argument(
+        "--min-confidence",
+        type=float,
+        default=0.8,
+        metavar="FLOAT",
+        help="Minimum confidence threshold for recommendations (0.0-1.0, default: 0.8)",
+    )
+
+    recommend_parser.add_argument(
+        "--show-reasoning",
+        action="store_true",
+        default=True,
+        help="Show detailed reasoning for recommendations (default)",
+    )
+
+    recommend_parser.add_argument(
+        "--no-reasoning",
+        dest="show_reasoning",
+        action="store_false",
+        help="Hide detailed reasoning for recommendations",
+    )
+
+    return recommend_parser

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",
@@ -301,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
 
@@ -329,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
 
@@ -423,6 +525,11 @@ def create_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
 

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