claude-mpm 3.9.11__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/cli/parsers/__init__.py

@@ -0,0 +1,29 @@
+"""
+CLI parsers package for claude-mpm.
+
+This package contains modular parser components that were extracted from the
+monolithic parser.py file to improve maintainability and organization.
+
+WHY: The original parser.py was 1,166 lines with a single 961-line function.
+Breaking it into focused modules makes it easier to maintain and test.
+
+DESIGN DECISION: Each parser module handles a specific command domain:
+- base_parser.py: Common arguments and main parser setup
+- run_parser.py: Run command arguments
+- agent_parser.py: Agent management commands
+- memory_parser.py: Memory management commands
+- tickets_parser.py: Ticket management commands
+- config_parser.py: Configuration commands
+- monitor_parser.py: Monitoring commands
+- mcp_parser.py: MCP Gateway commands
+"""
+
+from .base_parser import add_common_arguments, create_parser, preprocess_args
+from .run_parser import add_run_arguments
+
+__all__ = [
+    "create_parser",
+    "add_common_arguments",
+    "add_run_arguments",
+    "preprocess_args",
+]

claude_mpm/cli/parsers/agents_parser.py

@@ -0,0 +1,136 @@
+from pathlib import Path
+
+"""
+Agents command parser for claude-mpm CLI.
+
+WHY: This module contains all arguments specific to agent management commands,
+extracted from the monolithic parser.py for better organization.
+
+DESIGN DECISION: Agent commands are complex with multiple subcommands for
+deployment, listing, validation, etc., warranting their own module.
+"""
+
+import argparse
+
+from ...constants import AgentCommands, CLICommands
+from .base_parser import add_common_arguments
+
+
+def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the agents subparser with all agent management commands.
+
+    WHY: Agent management has multiple complex subcommands (list, deploy, validate, etc.)
+    that need their own argument structures.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured agents subparser
+    """
+    # Agents command with subcommands
+    agents_parser = subparsers.add_parser(
+        CLICommands.AGENTS.value, help="Manage agents and deployment"
+    )
+    add_common_arguments(agents_parser)
+
+    agents_subparsers = agents_parser.add_subparsers(
+        dest="agents_command", help="Agent commands", metavar="SUBCOMMAND"
+    )
+
+    # List agents
+    list_agents_parser = agents_subparsers.add_parser(
+        AgentCommands.LIST.value, help="List available agents"
+    )
+    list_agents_parser.add_argument(
+        "--system", action="store_true", help="List system agents"
+    )
+    list_agents_parser.add_argument(
+        "--deployed", action="store_true", help="List deployed agents"
+    )
+    list_agents_parser.add_argument(
+        "--by-tier",
+        action="store_true",
+        help="List agents grouped by precedence tier (PROJECT > USER > SYSTEM)",
+    )
+
+    # View agent details
+    view_agent_parser = agents_subparsers.add_parser(
+        AgentCommands.VIEW.value,
+        help="View detailed information about a specific agent",
+    )
+    view_agent_parser.add_argument("agent_name", help="Name of the agent to view")
+    view_agent_parser.add_argument(
+        "--show-dependencies", action="store_true", help="Show agent dependencies"
+    )
+    view_agent_parser.add_argument(
+        "--show-config", action="store_true", help="Show agent configuration"
+    )
+
+    # Deploy agents
+    deploy_agents_parser = agents_subparsers.add_parser(
+        AgentCommands.DEPLOY.value, help="Deploy agents to target directory"
+    )
+    deploy_agents_parser.add_argument(
+        "--target", type=Path, help="Target directory (default: .claude/)"
+    )
+    deploy_agents_parser.add_argument(
+        "--agents", nargs="*", help="Specific agents to deploy (default: all)"
+    )
+    deploy_agents_parser.add_argument(
+        "--force", action="store_true", help="Force deployment even if target exists"
+    )
+    deploy_agents_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # Validate agents
+    validate_agents_parser = agents_subparsers.add_parser(
+        AgentCommands.FIX.value, help="Validate agent configurations"
+    )
+    validate_agents_parser.add_argument(
+        "--agents", nargs="*", help="Specific agents to validate (default: all)"
+    )
+    validate_agents_parser.add_argument(
+        "--strict", action="store_true", help="Use strict validation rules"
+    )
+
+    # Clean agents
+    clean_agents_parser = agents_subparsers.add_parser(
+        AgentCommands.CLEAN.value, help="Remove deployed system agents"
+    )
+    clean_agents_parser.add_argument(
+        "--target", type=Path, help="Target directory (default: .claude/)"
+    )
+
+    # Dependencies management
+    deps_list_parser = agents_subparsers.add_parser(
+        "deps-list", help="List agent dependencies and their status"
+    )
+    deps_list_parser.add_argument(
+        "--agents", nargs="*", help="Specific agents to check (default: all)"
+    )
+    deps_list_parser.add_argument(
+        "--missing-only", action="store_true", help="Show only missing dependencies"
+    )
+    deps_list_parser.add_argument(
+        "--format",
+        choices=["text", "pip", "json"],
+        default="text",
+        help="Output format for dependency list",
+    )
+
+    deps_fix_parser = agents_subparsers.add_parser(
+        "deps-fix", help="Fix missing agent dependencies with robust retry logic"
+    )
+    deps_fix_parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=3,
+        help="Maximum retry attempts per package (default: 3)",
+    )
+
+    return agents_parser

claude_mpm/cli/parsers/base_parser.py

@@ -0,0 +1,331 @@
+from pathlib import Path
+
+"""
+Base parser module for claude-mpm CLI.
+
+WHY: This module contains the main parser factory and common argument definitions
+that are shared across all commands. Extracted from the monolithic parser.py.
+
+DESIGN DECISION: Common arguments are defined once and reused to ensure consistency
+and reduce duplication across command parsers.
+"""
+
+import argparse
+from typing import List, Optional
+
+from ...constants import CLICommands, CLIPrefix, LogLevel
+
+
+def add_common_arguments(parser: argparse.ArgumentParser, version: str = None) -> None:
+    """
+    Add common arguments that apply to all commands.
+
+    WHY: These arguments are needed across multiple commands, so we centralize them
+    to ensure consistency and avoid duplication.
+
+    Args:
+        parser: The argument parser to add arguments to
+        version: Version string to display (only needed for main parser)
+    """
+    # Version - only add to main parser, not subparsers
+    if version is not None:
+        parser.add_argument(
+            "--version", action="version", version=f"%(prog)s {version}"
+        )
+
+    # Logging arguments
+    logging_group = parser.add_argument_group("logging options")
+    logging_group.add_argument(
+        "-d",
+        "--debug",
+        action="store_true",
+        help="Enable debug logging (deprecated, use --logging DEBUG)",
+    )
+    logging_group.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging (deprecated, use --logging INFO)",
+    )
+    logging_group.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress all output except errors (deprecated, use --logging ERROR)",
+    )
+    logging_group.add_argument(
+        "--logging",
+        choices=[level.value for level in LogLevel],
+        help="Set logging level (overrides -d, -v, -q flags)",
+    )
+
+    # Configuration arguments
+    config_group = parser.add_argument_group("configuration options")
+    config_group.add_argument("--config", type=Path, help="Path to configuration file")
+    config_group.add_argument(
+        "--project-dir", type=Path, help="Project directory (overrides auto-detection)"
+    )
+
+
+def create_main_parser(
+    prog_name: str = "claude-mpm", version: str = "0.0.0"
+) -> argparse.ArgumentParser:
+    """
+    Create the main argument parser with basic setup.
+
+    WHY: This creates the foundation parser that other modules will extend
+    with their specific subcommands and arguments.
+
+    Args:
+        prog_name: The program name to use
+        version: The version string to display
+
+    Returns:
+        Configured ArgumentParser instance ready for subparser addition
+    """
+    # Main parser
+    parser = argparse.ArgumentParser(
+        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",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Add common arguments to main parser with version
+    add_common_arguments(parser, version=version)
+
+    return parser
+
+
+def add_top_level_run_arguments(parser: argparse.ArgumentParser) -> None:
+    """
+    Add run-specific arguments at top level for backward compatibility.
+
+    WHY: This maintains backward compatibility - users can run `claude-mpm -i "prompt"`
+    without specifying the 'run' command.
+
+    Args:
+        parser: The argument parser to add arguments to
+    """
+    # Add run-specific arguments at top level for default behavior
+    # NOTE: We don't add claude_args here because REMAINDER interferes with subcommands
+    run_group = parser.add_argument_group("run options (when no command specified)")
+
+    run_group.add_argument(
+        "--no-hooks",
+        action="store_true",
+        help="Disable hook service (runs without hooks)",
+    )
+    run_group.add_argument(
+        "--no-tickets", action="store_true", help="Disable automatic ticket creation"
+    )
+    run_group.add_argument(
+        "--intercept-commands",
+        action="store_true",
+        help="Enable command interception in interactive mode (intercepts /mpm: commands)",
+    )
+    run_group.add_argument(
+        "--no-native-agents",
+        action="store_true",
+        help="Disable deployment of Claude Code native agents",
+    )
+    run_group.add_argument(
+        "--launch-method",
+        choices=["exec", "subprocess"],
+        default="exec",
+        help="Method to launch Claude: exec (replace process) or subprocess (child process)",
+    )
+    # Monitor options - consolidated monitoring and management interface
+    run_group.add_argument(
+        "--monitor",
+        action="store_true",
+        help="Enable monitoring and management interface with WebSocket server and dashboard (default port: 8765)",
+    )
+    run_group.add_argument(
+        "--websocket-port",
+        type=int,
+        default=8765,
+        help="WebSocket server port (default: 8765)",
+    )
+    run_group.add_argument(
+        "--resume",
+        type=str,
+        nargs="?",
+        const="last",
+        help="Resume a session (last session if no ID specified, or specific session ID)",
+    )
+    run_group.add_argument(
+        "--force",
+        action="store_true",
+        help="Force operations even with warnings (e.g., large .claude.json file)",
+    )
+
+    # Dependency checking options (for backward compatibility at top level)
+    dep_group_top = parser.add_argument_group(
+        "dependency options (when no command specified)"
+    )
+    dep_group_top.add_argument(
+        "--no-check-dependencies",
+        action="store_false",
+        dest="check_dependencies",
+        help="Skip agent dependency checking at startup",
+    )
+    dep_group_top.add_argument(
+        "--force-check-dependencies",
+        action="store_true",
+        help="Force dependency checking even if cached results exist",
+    )
+    dep_group_top.add_argument(
+        "--no-prompt",
+        action="store_true",
+        help="Never prompt for dependency installation (non-interactive mode)",
+    )
+    dep_group_top.add_argument(
+        "--force-prompt",
+        action="store_true",
+        help="Force interactive prompting even in non-TTY environments (use with caution)",
+    )
+
+    # Input/output options
+    io_group = parser.add_argument_group(
+        "input/output options (when no command specified)"
+    )
+    io_group.add_argument(
+        "-i",
+        "--input",
+        type=str,
+        help="Input text or file path (for non-interactive mode)",
+    )
+    io_group.add_argument(
+        "--non-interactive",
+        action="store_true",
+        help="Run in non-interactive mode (read from stdin or --input)",
+    )
+
+
+def create_parser(
+    prog_name: str = "claude-mpm", version: str = "0.0.0"
+) -> argparse.ArgumentParser:
+    """
+    Create the main argument parser with all subcommands.
+
+    WHY: This factory function creates a complete parser with all commands and their
+    arguments. It's the single entry point for creating the CLI parser, ensuring
+    consistency across the application.
+
+    DESIGN DECISION: We use subparsers for commands to provide a clean, git-like
+    interface while maintaining backward compatibility with the original CLI.
+
+    Args:
+        prog_name: The program name to use
+        version: The version string to display
+
+    Returns:
+        Configured ArgumentParser instance
+    """
+    # Create main parser
+    parser = create_main_parser(prog_name, version)
+
+    # Add top-level run arguments for backward compatibility
+    add_top_level_run_arguments(parser)
+
+    # Create subparsers for commands
+    subparsers = parser.add_subparsers(
+        dest="command", help="Available commands", metavar="COMMAND"
+    )
+
+    # Import and add core subparsers one by one to avoid issues
+    try:
+        from .run_parser import add_run_subparser
+
+        add_run_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .tickets_parser import add_tickets_subparser
+
+        add_tickets_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .agents_parser import add_agents_subparser
+
+        add_agents_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .memory_parser import add_memory_subparser
+
+        add_memory_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .config_parser import add_config_subparser
+
+        add_config_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .monitor_parser import add_monitor_subparser
+
+        add_monitor_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .mcp_parser import add_mcp_subparser
+
+        add_mcp_subparser(subparsers)
+    except ImportError:
+        pass
+
+    # Import and add additional command parsers from commands module
+    try:
+        from ..commands.aggregate import add_aggregate_parser
+
+        add_aggregate_parser(subparsers)
+
+        from ..commands.cleanup import add_cleanup_parser
+
+        add_cleanup_parser(subparsers)
+    except ImportError:
+        # Commands module may not be available during testing or refactoring
+        pass
+
+    return parser
+
+
+def preprocess_args(argv: Optional[List[str]] = None) -> List[str]:
+    """
+    Preprocess arguments to handle --mpm: prefix commands.
+
+    WHY: We support both --mpm:command and regular command syntax for flexibility
+    and backward compatibility. This function normalizes the input.
+
+    Args:
+        argv: List of command line arguments, or None to use sys.argv[1:]
+
+    Returns:
+        Processed list of arguments with prefixes removed
+    """
+    import sys
+
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Convert --mpm:command to command for argparse compatibility
+    processed_args = []
+    for arg in argv:
+        if arg.startswith(CLIPrefix.MPM.value):
+            # Extract command after prefix
+            command = arg[len(CLIPrefix.MPM.value) :]
+            processed_args.append(command)
+        else:
+            processed_args.append(arg)
+
+    return processed_args

claude_mpm/cli/parsers/config_parser.py

@@ -0,0 +1,85 @@
+from pathlib import Path
+
+"""
+Config command parser for claude-mpm CLI.
+
+WHY: This module contains all arguments specific to configuration management,
+extracted from the monolithic parser.py for better organization.
+
+DESIGN DECISION: Configuration commands handle validation and management
+of claude-mpm settings and warrant their own module.
+"""
+
+import argparse
+
+from ...constants import CLICommands, ConfigCommands
+from .base_parser import add_common_arguments
+
+
+def add_config_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the config subparser with all configuration management commands.
+
+    WHY: Configuration management has multiple subcommands for validation,
+    viewing, and editing that need their own argument structures.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured config subparser
+    """
+    # Config command with subcommands
+    config_parser = subparsers.add_parser(
+        CLICommands.CONFIG.value, help="Validate and manage configuration"
+    )
+    add_common_arguments(config_parser)
+
+    config_subparsers = config_parser.add_subparsers(
+        dest="config_command", help="Config commands", metavar="SUBCOMMAND"
+    )
+
+    # Validate config
+    validate_config_parser = config_subparsers.add_parser(
+        ConfigCommands.VALIDATE.value, help="Validate configuration files"
+    )
+    validate_config_parser.add_argument(
+        "--config-file",
+        type=Path,
+        help="Specific config file to validate (default: all)",
+    )
+    validate_config_parser.add_argument(
+        "--strict", action="store_true", help="Use strict validation rules"
+    )
+    validate_config_parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Attempt to fix validation errors automatically",
+    )
+
+    # View config
+    view_config_parser = config_subparsers.add_parser(
+        ConfigCommands.VIEW.value, help="View current configuration"
+    )
+    view_config_parser.add_argument(
+        "--section", help="Specific configuration section to view"
+    )
+    view_config_parser.add_argument(
+        "--format",
+        choices=["yaml", "json", "table"],
+        default="yaml",
+        help="Output format (default: yaml)",
+    )
+    view_config_parser.add_argument(
+        "--show-defaults", action="store_true", help="Include default values in output"
+    )
+
+    # Status config
+    status_config_parser = config_subparsers.add_parser(
+        ConfigCommands.STATUS.value, help="Show configuration status"
+    )
+    status_config_parser.add_argument(
+        "--verbose", action="store_true", help="Show detailed status information"
+    )
+
+    return config_parser