claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/cli_module/args.py

@@ -0,0 +1,222 @@
+"""Argument registry for consolidating CLI argument definitions."""
+
+import argparse
+from pathlib import Path
+from typing import Dict, Any, Optional, Callable
+
+
+class ArgumentRegistry:
+    """Registry for managing CLI argument definitions.
+    
+    This class consolidates argument definitions to reduce duplication
+    and simplify the main CLI function.
+    """
+    
+    def __init__(self):
+        """Initialize the registry with common argument groups."""
+        self._arguments: Dict[str, Dict[str, Any]] = {}
+        self._groups: Dict[str, list] = {
+            'global': [],
+            'run': [],
+            'logging': [],
+            'framework': [],
+            'orchestration': []
+        }
+        self._register_common_arguments()
+    
+    def _register_common_arguments(self):
+        """Register all common argument definitions."""
+        # Version argument
+        self.register('version', {
+            'flags': ['--version'],
+            'action': 'version',
+            'help': 'Show version and exit',
+            'groups': ['global']
+        })
+        
+        # Logging arguments
+        self.register('debug', {
+            'flags': ['-d', '--debug'],
+            'action': 'store_true',
+            'help': 'Enable debug logging (deprecated, use --logging DEBUG)',
+            'groups': ['logging', 'global']
+        })
+        
+        self.register('logging', {
+            'flags': ['--logging'],
+            'choices': ['OFF', 'INFO', 'DEBUG'],
+            'default': 'OFF',
+            'help': 'Logging level (default: OFF)',
+            'groups': ['logging', 'global']
+        })
+        
+        self.register('log_dir', {
+            'flags': ['--log-dir'],
+            'type': Path,
+            'help': 'Custom log directory (default: ~/.claude-mpm/logs)',
+            'groups': ['logging', 'global']
+        })
+        
+        # Framework arguments
+        self.register('framework_path', {
+            'flags': ['--framework-path'],
+            'type': Path,
+            'help': 'Path to claude-mpm framework',
+            'groups': ['framework', 'global']
+        })
+        
+        self.register('agents_dir', {
+            'flags': ['--agents-dir'],
+            'type': Path,
+            'help': 'Custom agents directory to use',
+            'groups': ['framework', 'global']
+        })
+        
+        self.register('no_hooks', {
+            'flags': ['--no-hooks'],
+            'action': 'store_true',
+            'help': 'Disable hook service (runs without hooks)',
+            'groups': ['framework', 'global', 'run']
+        })
+        
+        # Run command arguments
+        self.register('no_tickets', {
+            'flags': ['--no-tickets'],
+            'action': 'store_true',
+            'help': 'Disable automatic ticket creation',
+            'groups': ['run']
+        })
+        
+        self.register('input', {
+            'flags': ['-i', '--input'],
+            'type': str,
+            'help': 'Input text or file path (for non-interactive mode)',
+            'groups': ['run']
+        })
+        
+        self.register('non_interactive', {
+            'flags': ['--non-interactive'],
+            'action': 'store_true',
+            'help': 'Run in non-interactive mode (read from stdin or --input)',
+            'groups': ['run']
+        })
+        
+        # Orchestration arguments
+        self.register('subprocess', {
+            'flags': ['--subprocess'],
+            'action': 'store_true',
+            'help': 'Use subprocess orchestration for agent delegations',
+            'groups': ['orchestration', 'run']
+        })
+        
+        self.register('interactive_subprocess', {
+            'flags': ['--interactive-subprocess'],
+            'action': 'store_true',
+            'help': 'Use interactive subprocess orchestration with pexpect control',
+            'groups': ['orchestration', 'run']
+        })
+        
+        self.register('todo_hijack', {
+            'flags': ['--todo-hijack'],
+            'action': 'store_true',
+            'help': 'Enable TODO hijacking to transform Claude\'s TODOs into agent delegations',
+            'groups': ['orchestration', 'run']
+        })
+        
+        # Ticket list arguments
+        self.register('limit', {
+            'flags': ['-n', '--limit'],
+            'type': int,
+            'default': 10,
+            'help': 'Number of tickets to show',
+            'groups': ['tickets']
+        })
+    
+    def register(self, name: str, definition: Dict[str, Any]):
+        """Register a new argument definition.
+        
+        Args:
+            name: Internal name for the argument
+            definition: Dictionary containing argument configuration:
+                - flags: List of flag strings (e.g., ['-d', '--debug'])
+                - groups: List of group names this argument belongs to
+                - All other kwargs are passed to add_argument()
+        """
+        self._arguments[name] = definition
+        
+        # Add to groups
+        for group in definition.get('groups', []):
+            if group not in self._groups:
+                self._groups[group] = []
+            self._groups[group].append(name)
+    
+    def apply_arguments(self, parser: argparse.ArgumentParser, 
+                       groups: Optional[list] = None,
+                       exclude: Optional[list] = None):
+        """Apply argument definitions to a parser.
+        
+        Args:
+            parser: ArgumentParser or subparser to add arguments to
+            groups: List of group names to include (None = all)
+            exclude: List of argument names to exclude
+        """
+        # Determine which arguments to add
+        if groups is None:
+            arg_names = list(self._arguments.keys())
+        else:
+            arg_names = []
+            for group in groups:
+                arg_names.extend(self._groups.get(group, []))
+            # Remove duplicates while preserving order
+            seen = set()
+            arg_names = [x for x in arg_names if not (x in seen or seen.add(x))]
+        
+        # Apply exclusions
+        if exclude:
+            arg_names = [n for n in arg_names if n not in exclude]
+        
+        # Add arguments to parser
+        for name in arg_names:
+            definition = self._arguments[name].copy()
+            flags = definition.pop('flags')
+            definition.pop('groups', None)  # Remove groups from kwargs
+            
+            # Special handling for version
+            if name == 'version' and hasattr(parser, '_version'):
+                definition['version'] = parser._version
+            
+            parser.add_argument(*flags, **definition)
+    
+    def get_argument_groups(self) -> Dict[str, list]:
+        """Get all argument groups and their members."""
+        return self._groups.copy()
+    
+    def get_argument_definition(self, name: str) -> Optional[Dict[str, Any]]:
+        """Get the definition for a specific argument."""
+        return self._arguments.get(name, {}).copy()
+    
+    def create_argument_group(self, parser: argparse.ArgumentParser,
+                            group_name: str,
+                            title: str,
+                            description: Optional[str] = None):
+        """Create an argument group and add arguments from a named group.
+        
+        Args:
+            parser: Parser to add the group to
+            group_name: Name of the argument group in registry
+            title: Title for the argument group
+            description: Optional description for the group
+        """
+        group = parser.add_argument_group(title, description)
+        
+        # Get arguments for this group
+        arg_names = self._groups.get(group_name, [])
+        
+        for name in arg_names:
+            definition = self._arguments[name].copy()
+            flags = definition.pop('flags')
+            definition.pop('groups', None)
+            
+            group.add_argument(*flags, **definition)
+        
+        return group

claude_mpm/cli_module/commands.py

@@ -0,0 +1,203 @@
+"""Command registry for managing CLI subcommands."""
+
+import argparse
+from typing import Dict, Any, Optional, Callable, List
+from .args import ArgumentRegistry
+
+
+class CommandDefinition:
+    """Definition for a CLI command."""
+    
+    def __init__(self, name: str, help_text: str, 
+                 handler: Callable,
+                 argument_groups: Optional[List[str]] = None,
+                 extra_args: Optional[Dict[str, Dict[str, Any]]] = None):
+        """Initialize command definition.
+        
+        Args:
+            name: Command name
+            help_text: Help text for the command
+            handler: Function to call when command is executed
+            argument_groups: List of argument group names to include
+            extra_args: Additional command-specific arguments
+        """
+        self.name = name
+        self.help_text = help_text
+        self.handler = handler
+        self.argument_groups = argument_groups or []
+        self.extra_args = extra_args or {}
+
+
+class CommandRegistry:
+    """Registry for managing CLI subcommands.
+    
+    This class simplifies subcommand management and reduces
+    complexity in the main CLI function.
+    """
+    
+    def __init__(self, arg_registry: Optional[ArgumentRegistry] = None):
+        """Initialize the command registry.
+        
+        Args:
+            arg_registry: ArgumentRegistry instance for applying arguments
+        """
+        self._commands: Dict[str, CommandDefinition] = {}
+        self._arg_registry = arg_registry or ArgumentRegistry()
+        self._default_command: Optional[str] = None
+    
+    def register(self, name: str, help_text: str, handler: Callable,
+                 argument_groups: Optional[List[str]] = None,
+                 extra_args: Optional[Dict[str, Dict[str, Any]]] = None,
+                 is_default: bool = False):
+        """Register a new command.
+        
+        Args:
+            name: Command name
+            help_text: Help text for the command
+            handler: Function to call when command is executed
+            argument_groups: List of argument group names from ArgumentRegistry
+            extra_args: Additional command-specific arguments
+            is_default: Whether this is the default command
+        """
+        command = CommandDefinition(
+            name=name,
+            help_text=help_text,
+            handler=handler,
+            argument_groups=argument_groups,
+            extra_args=extra_args
+        )
+        
+        self._commands[name] = command
+        
+        if is_default:
+            self._default_command = name
+    
+    def setup_subcommands(self, parser: argparse.ArgumentParser) -> argparse._SubParsersAction:
+        """Set up all registered subcommands on the parser.
+        
+        Args:
+            parser: Main argument parser
+            
+        Returns:
+            The subparsers object
+        """
+        subparsers = parser.add_subparsers(
+            dest="command",
+            help="Available commands"
+        )
+        
+        for name, command in self._commands.items():
+            # Create subparser
+            subparser = subparsers.add_parser(
+                name,
+                help=command.help_text
+            )
+            
+            # Apply argument groups
+            if command.argument_groups:
+                self._arg_registry.apply_arguments(
+                    subparser,
+                    groups=command.argument_groups
+                )
+            
+            # Apply extra arguments
+            for arg_name, arg_config in command.extra_args.items():
+                flags = arg_config.pop('flags', [f'--{arg_name.replace("_", "-")}'])
+                subparser.add_argument(*flags, **arg_config)
+            
+            # Store handler reference
+            subparser.set_defaults(_handler=command.handler)
+        
+        return subparsers
+    
+    def execute_command(self, args: argparse.Namespace, **kwargs) -> Any:
+        """Execute the appropriate command handler.
+        
+        Args:
+            args: Parsed command line arguments
+            **kwargs: Additional keyword arguments to pass to handler
+            
+        Returns:
+            Result from the command handler
+        """
+        # Handle default command
+        command_name = args.command
+        if not command_name and self._default_command:
+            command_name = self._default_command
+            args.command = command_name
+            
+            # Apply default command's argument defaults
+            command = self._commands.get(command_name)
+            if command:
+                # Set defaults for arguments that might not be present
+                for group in command.argument_groups:
+                    for arg_name in self._arg_registry._groups.get(group, []):
+                        if not hasattr(args, arg_name):
+                            definition = self._arg_registry.get_argument_definition(arg_name)
+                            if definition and 'default' in definition:
+                                setattr(args, arg_name, definition['default'])
+                            elif definition and definition.get('action') == 'store_true':
+                                setattr(args, arg_name, False)
+        
+        # Get command handler
+        if hasattr(args, '_handler'):
+            handler = args._handler
+        else:
+            command = self._commands.get(command_name)
+            if command:
+                handler = command.handler
+            else:
+                return None
+        
+        # Execute handler
+        return handler(args, **kwargs)
+    
+    def get_command_names(self) -> List[str]:
+        """Get list of all registered command names."""
+        return list(self._commands.keys())
+    
+    def get_default_command(self) -> Optional[str]:
+        """Get the default command name."""
+        return self._default_command
+    
+    def has_command(self, name: str) -> bool:
+        """Check if a command is registered."""
+        return name in self._commands
+
+
+def register_standard_commands(registry: CommandRegistry):
+    """Register the standard claude-mpm commands.
+    
+    This function registers all the standard commands that claude-mpm
+    supports, reducing the setup code in main().
+    
+    Args:
+        registry: CommandRegistry instance to register commands with
+    """
+    # Import handlers (these would be refactored from cli.py)
+    from ..cli import run_session, list_tickets, show_info
+    
+    # Register run command (default)
+    registry.register(
+        name='run',
+        help_text='Run orchestrated Claude session (default)',
+        handler=run_session,
+        argument_groups=['run', 'orchestration'],
+        is_default=True
+    )
+    
+    # Register tickets command
+    registry.register(
+        name='tickets',
+        help_text='List recent tickets',
+        handler=list_tickets,
+        argument_groups=['tickets']
+    )
+    
+    # Register info command
+    registry.register(
+        name='info',
+        help_text='Show framework and configuration info',
+        handler=show_info,
+        argument_groups=[]  # No specific arguments needed
+    )

claude_mpm/cli_module/migration_example.py

@@ -0,0 +1,183 @@
+"""Example migration showing how to refactor main() using registries.
+
+This file demonstrates how to reduce the complexity of the main() function
+from 16 to under 10 by using ArgumentRegistry and CommandRegistry.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm._version import __version__
+from claude_mpm.core.logger import get_logger, setup_logging
+from claude_mpm.services.hook_service_manager import HookServiceManager
+from claude_mpm.cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+
+
+def main_refactored(argv: Optional[list] = None):
+    """Refactored main CLI entry point with reduced complexity.
+    
+    This version uses registries to manage arguments and commands,
+    reducing cyclomatic complexity from 16 to approximately 8.
+    """
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser with basic info
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        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."
+    )
+    
+    # Store version for ArgumentRegistry
+    parser._version = f"claude-mpm {__version__}"
+    
+    # Apply global arguments
+    arg_registry.apply_arguments(parser, groups=['global'])
+    
+    # Apply run arguments at top level (for default behavior)
+    arg_registry.apply_arguments(parser, groups=['run'], exclude=['no_hooks'])
+    
+    # Set up subcommands
+    cmd_registry.setup_subcommands(parser)
+    
+    # Parse arguments
+    args = parser.parse_args(argv)
+    
+    # Set up logging
+    _setup_logging(args)
+    
+    # Initialize hook service
+    hook_manager = _initialize_hook_service(args)
+    
+    try:
+        # Execute command
+        result = cmd_registry.execute_command(args, hook_manager=hook_manager)
+        if result is None and not args.command:
+            parser.print_help()
+            return 1
+        return result or 0
+        
+    except KeyboardInterrupt:
+        get_logger("cli").info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger = get_logger("cli")
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        # Clean up hook service
+        if hook_manager:
+            hook_manager.stop_service()
+
+
+def _setup_logging(args):
+    """Set up logging based on arguments (extracted helper)."""
+    # Handle deprecated --debug flag
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    # Only setup logging if not OFF
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        # Minimal logger for CLI feedback
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled (extracted helper)."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        # Check if hooks are enabled via config
+        from claude_mpm.config.hook_config import HookConfig
+        
+        if not HookConfig.is_hooks_enabled():
+            get_logger("cli").info("Hooks disabled via configuration")
+            return None
+            
+        hook_manager = HookServiceManager(log_dir=args.log_dir)
+        if hook_manager.start_service():
+            logger = get_logger("cli")
+            logger.info(f"Hook service started on port {hook_manager.port}")
+            print(f"Hook service started on port {hook_manager.port}")
+            return hook_manager
+        else:
+            logger = get_logger("cli")
+            logger.warning("Failed to start hook service, continuing without hooks")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service initialization failed: {e}, continuing without hooks")
+        return None
+
+
+# Example of how to add custom commands
+def extend_with_custom_commands(cmd_registry: CommandRegistry):
+    """Example of adding custom commands to the registry."""
+    
+    def validate_command(args, **kwargs):
+        """Custom validation command."""
+        print("Running validation...")
+        # Implementation here
+        return 0
+    
+    # Register custom command
+    cmd_registry.register(
+        name='validate',
+        help_text='Validate project configuration and agent setup',
+        handler=validate_command,
+        argument_groups=['framework'],
+        extra_args={
+            'strict': {
+                'flags': ['--strict'],
+                'action': 'store_true',
+                'help': 'Enable strict validation mode'
+            }
+        }
+    )
+
+
+# Comparison with original main() function
+def complexity_comparison():
+    """Show the complexity reduction achieved.
+    
+    Original main() function:
+    - Cyclomatic complexity: 16
+    - Lines of code: ~230
+    - Duplicate argument definitions: 6 (for 'run' command)
+    - Mixed concerns: argument parsing, logging, hook service, command dispatch
+    
+    Refactored main_refactored() function:
+    - Cyclomatic complexity: ~8
+    - Lines of code: ~50
+    - Duplicate argument definitions: 0
+    - Separated concerns: registries handle definitions, helpers handle setup
+    
+    Benefits:
+    1. Centralized argument definitions eliminate duplication
+    2. Command registry simplifies adding new commands
+    3. Extracted helpers reduce nesting and conditionals
+    4. Easier to test individual components
+    5. Clear separation of concerns
+    """
+    pass
+
+
+if __name__ == "__main__":
+    # Example usage of refactored main
+    sys.exit(main_refactored())