claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/cli_module/refactoring_guide.md

@@ -0,0 +1,253 @@
+# CLI Refactoring Guide
+
+This guide shows how to refactor the main() function in `/src/claude_mpm/cli.py` to reduce complexity from 16 to under 10.
+
+## Current Issues
+
+1. **High Cyclomatic Complexity (16)**
+   - Multiple nested conditionals
+   - Duplicate argument definitions
+   - Mixed concerns in one function
+
+2. **Code Duplication**
+   - Arguments defined twice (global level + run subcommand)
+   - Similar patterns repeated for each command
+
+3. **Poor Maintainability**
+   - Adding new commands requires multiple changes
+   - Hard to test individual components
+
+## Refactoring Steps
+
+### Step 1: Update imports in cli.py
+
+```python
+# Add to imports
+from .cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+```
+
+### Step 2: Replace main() function
+
+Replace the entire `main()` function with:
+
+```python
+def main(argv: Optional[list] = None):
+    """Main CLI entry point with reduced complexity."""
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        description=f"Claude Multi-Agent Project Manager v{__version__}",
+        epilog="By default, runs an orchestrated Claude session."
+    )
+    
+    # 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:
+        if hook_manager:
+            hook_manager.stop_service()
+```
+
+### Step 3: Extract helper functions
+
+Add these helper functions after main():
+
+```python
+def _setup_logging(args):
+    """Set up logging based on arguments."""
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        from .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")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service init failed: {e}")
+        return None
+```
+
+### Step 4: Update command handler signatures
+
+Ensure all command handlers accept `**kwargs`:
+
+```python
+def run_session(args, hook_manager=None, **kwargs):
+    """Run an orchestrated Claude session."""
+    # ... existing implementation
+
+def list_tickets(args, **kwargs):
+    """List recent tickets."""
+    # ... existing implementation
+
+def show_info(args, hook_manager=None, **kwargs):
+    """Show framework and configuration information."""
+    # ... existing implementation
+```
+
+## Benefits Achieved
+
+### Complexity Reduction
+- **Before**: Cyclomatic complexity of 16
+- **After**: Cyclomatic complexity of ~8
+
+### Code Organization
+- Centralized argument definitions
+- No duplicate argument definitions
+- Clear separation of concerns
+- Easier to add new commands
+
+### Maintainability
+- New commands can be added with a single `register()` call
+- Arguments are defined once and reused
+- Helper functions are testable in isolation
+- Registry pattern allows for extension
+
+## Adding New Commands
+
+With the registry system, adding a new command is simple:
+
+```python
+# In your code or plugin
+def my_command(args, **kwargs):
+    """Implementation of your command."""
+    print(f"Running my command with args: {args}")
+    return 0
+
+# Register it
+cmd_registry.register(
+    name='mycommand',
+    help_text='Description of my command',
+    handler=my_command,
+    argument_groups=['framework'],  # Reuse existing argument groups
+    extra_args={
+        'custom_arg': {
+            'flags': ['--custom'],
+            'type': str,
+            'help': 'A custom argument for this command'
+        }
+    }
+)
+```
+
+## Testing
+
+The refactored code is easier to test:
+
+```python
+# Test argument registry
+def test_argument_registry():
+    registry = ArgumentRegistry()
+    parser = argparse.ArgumentParser()
+    registry.apply_arguments(parser, groups=['logging'])
+    
+    # Verify logging arguments were added
+    args = parser.parse_args(['--logging', 'DEBUG'])
+    assert args.logging == 'DEBUG'
+
+# Test command registry
+def test_command_registry():
+    arg_reg = ArgumentRegistry()
+    cmd_reg = CommandRegistry(arg_reg)
+    
+    called = False
+    def test_handler(args, **kwargs):
+        nonlocal called
+        called = True
+        return 0
+    
+    cmd_reg.register('test', 'Test command', test_handler)
+    
+    parser = argparse.ArgumentParser()
+    cmd_reg.setup_subcommands(parser)
+    
+    args = parser.parse_args(['test'])
+    result = cmd_reg.execute_command(args)
+    
+    assert called
+    assert result == 0
+```
+
+## Migration Checklist
+
+- [ ] Create `/src/claude_mpm/cli/` directory
+- [ ] Create `args.py` with ArgumentRegistry
+- [ ] Create `commands.py` with CommandRegistry
+- [ ] Create `__init__.py` to export classes
+- [ ] Update imports in `cli.py`
+- [ ] Replace main() function
+- [ ] Add helper functions
+- [ ] Update command handler signatures
+- [ ] Test the refactored CLI
+- [ ] Verify complexity is reduced to ≤10

claude_mpm/cli_old/__init__.py

@@ -0,0 +1 @@
+"""CLI module for claude-mpm."""

claude_mpm/cli_old/ticket_cli.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Ticket Management CLI - delegates to aitrackdown.
+
+This module provides a wrapper that delegates all ticket operations
+to the aitrackdown command-line tool.
+"""
+
+import sys
+import subprocess
+import argparse
+
+
+def main():
+    """Main entry point that delegates to aitrackdown."""
+    parser = argparse.ArgumentParser(
+        description="Ticket management for Claude MPM (delegates to aitrackdown)",
+        add_help=False
+    )
+    
+    # Capture all arguments
+    parser.add_argument('command', nargs='?', help='Command to run')
+    parser.add_argument('args', nargs=argparse.REMAINDER, help='Arguments for the command')
+    
+    args = parser.parse_args()
+    
+    # Map common commands to aitrackdown equivalents
+    if args.command == 'create':
+        # Check if type is specified
+        if any(arg in ['-t', '--type'] for arg in args.args):
+            try:
+                type_idx = args.args.index('-t') if '-t' in args.args else args.args.index('--type')
+                if type_idx + 1 < len(args.args):
+                    ticket_type = args.args[type_idx + 1]
+                    # Remove type arguments
+                    remaining_args = args.args[:type_idx] + args.args[type_idx + 2:]
+                    
+                    if ticket_type == 'epic':
+                        cmd = ['aitrackdown', 'epic', 'create'] + remaining_args
+                    elif ticket_type == 'issue':
+                        cmd = ['aitrackdown', 'issue', 'create'] + remaining_args
+                    else:
+                        cmd = ['aitrackdown', 'task', 'create'] + remaining_args
+                else:
+                    cmd = ['aitrackdown', 'task', 'create'] + args.args
+            except:
+                cmd = ['aitrackdown', 'task', 'create'] + args.args
+        else:
+            cmd = ['aitrackdown', 'task', 'create'] + args.args
+    
+    elif args.command == 'list':
+        cmd = ['aitrackdown', 'task', 'list'] + args.args
+    
+    elif args.command in ['view', 'show']:
+        cmd = ['aitrackdown', 'task', 'show'] + args.args
+    
+    elif args.command == 'update':
+        cmd = ['aitrackdown', 'task', 'update'] + args.args
+    
+    elif args.command == 'close':
+        if args.args:
+            cmd = ['aitrackdown', 'task', 'complete', args.args[0]] + args.args[1:]
+        else:
+            cmd = ['aitrackdown', 'task', 'complete']
+    
+    elif args.command in ['help', '--help', '-h', None]:
+        print("Claude MPM Ticket Management (powered by aitrackdown)")
+        print()
+        print("Usage:")
+        print("  claude-mpm-ticket create <title> [options]")
+        print("  claude-mpm-ticket list [options]")
+        print("  claude-mpm-ticket view <id>")
+        print("  claude-mpm-ticket update <id> [options]")
+        print("  claude-mpm-ticket close <id>")
+        print()
+        print("Examples:")
+        print('  claude-mpm-ticket create "Fix bug" -p high')
+        print('  claude-mpm-ticket create "New feature" -t issue')
+        print('  claude-mpm-ticket create "Roadmap" -t epic')
+        print('  claude-mpm-ticket list')
+        print('  claude-mpm-ticket view TSK-0001')
+        print()
+        print("For full options, use: aitrackdown --help")
+        return
+    
+    else:
+        # Pass through to aitrackdown
+        cmd = ['aitrackdown'] + ([args.command] if args.command else []) + args.args
+    
+    # Execute the command
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as e:
+        sys.exit(e.returncode)
+    except FileNotFoundError:
+        print("Error: aitrackdown not found. Please ensure ai-trackdown-pytools is installed.")
+        print("Install with: pip install ai-trackdown-pytools")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration module for claude-mpm."""
+
+from .hook_config import HookConfig
+
+__all__ = ['HookConfig']

claude_mpm/config/hook_config.py

@@ -0,0 +1,42 @@
+"""Configuration for hook service integration."""
+
+import os
+from pathlib import Path
+
+
+class HookConfig:
+    """Hook service configuration."""
+    
+    # Service settings
+    DEFAULT_PORT = 8080
+    PORT_RANGE_START = 8080
+    PORT_RANGE_END = 8090
+    
+    # Timeouts
+    SERVICE_START_TIMEOUT = 3.0  # seconds
+    REQUEST_TIMEOUT = 30  # seconds
+    HEALTH_CHECK_TIMEOUT = 2.0  # seconds
+    
+    # Paths
+    HOOK_SERVICE_LOG_DIR = Path.home() / ".claude-mpm" / "logs"
+    HOOK_SERVICE_PID_DIR = Path.home() / ".claude-mpm" / "run"
+    
+    # Enable/disable hooks by default
+    HOOKS_ENABLED_BY_DEFAULT = True
+    
+    # Hook service endpoints
+    HEALTH_ENDPOINT = "/health"
+    SUBMIT_HOOK_ENDPOINT = "/hooks/submit"
+    PRE_DELEGATION_HOOK_ENDPOINT = "/hooks/pre-delegation"
+    POST_DELEGATION_HOOK_ENDPOINT = "/hooks/post-delegation"
+    TICKET_EXTRACTION_HOOK_ENDPOINT = "/hooks/ticket-extraction"
+    
+    @classmethod
+    def get_hook_service_url(cls, port: int) -> str:
+        """Get the hook service URL for a given port."""
+        return f"http://localhost:{port}"
+    
+    @classmethod
+    def is_hooks_enabled(cls) -> bool:
+        """Check if hooks are enabled via environment variable."""
+        return os.environ.get("CLAUDE_MPM_HOOKS_ENABLED", str(cls.HOOKS_ENABLED_BY_DEFAULT)).lower() in ("true", "1", "yes")

claude_mpm/constants.py

@@ -0,0 +1,150 @@
+"""Constants for Claude MPM."""
+
+from enum import Enum
+
+
+class CLIPrefix(str, Enum):
+    """CLI command prefix constants."""
+    MPM = "--mpm:"
+    
+    def __add__(self, other: str) -> str:
+        """Allow prefix + command concatenation."""
+        return self.value + other
+    
+    def wrap(self, flag: str) -> str:
+        """Wrap a flag with the prefix."""
+        if flag.startswith("--"):
+            return f"--mpm:{flag[2:]}"
+        elif flag.startswith("-"):
+            return f"-mpm:{flag[1:]}"
+        return self.value + flag
+
+
+class CLICommands(str, Enum):
+    """CLI command constants."""
+    RUN = "run"
+    TICKETS = "tickets"
+    INFO = "info"
+    AGENTS = "agents"
+    UI = "ui"
+    
+    def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
+        """Get command with prefix."""
+        return prefix + self.value
+    
+    @classmethod
+    def get_mpm_commands(cls) -> list[str]:
+        """Get list of MPM-specific commands with prefix."""
+        return [cmd.with_prefix() for cmd in cls]
+    
+    @classmethod
+    def is_mpm_command(cls, command: str) -> bool:
+        """Check if a command is an MPM command."""
+        # Check both with and without prefix
+        if command.startswith(CLIPrefix.MPM.value):
+            base_command = command[len(CLIPrefix.MPM.value):]
+            return base_command in [cmd.value for cmd in cls]
+        return command in [cmd.value for cmd in cls]
+
+
+class AgentCommands(str, Enum):
+    """Agent subcommand constants."""
+    LIST = "list"
+    DEPLOY = "deploy"
+    FORCE_DEPLOY = "force-deploy"
+    CLEAN = "clean"
+
+
+class CLIFlags(str, Enum):
+    """CLI flag constants (without prefix)."""
+    # Logging flags
+    DEBUG = "debug"
+    LOGGING = "logging"
+    LOG_DIR = "log-dir"
+    
+    # Framework flags
+    FRAMEWORK_PATH = "framework-path"
+    AGENTS_DIR = "agents-dir"
+    
+    # Hook flags
+    NO_HOOKS = "no-hooks"
+    
+    # Ticket flags
+    NO_TICKETS = "no-tickets"
+    
+    # Input/output flags
+    INPUT = "input"
+    NON_INTERACTIVE = "non-interactive"
+    
+    # Orchestration flags
+    SUBPROCESS = "subprocess"
+    INTERACTIVE_SUBPROCESS = "interactive-subprocess"
+    TODO_HIJACK = "todo-hijack"
+    
+    # Agent flags
+    NO_NATIVE_AGENTS = "no-native-agents"
+    
+    def with_prefix(self, short: bool = False) -> str:
+        """Get flag with MPM prefix."""
+        prefix = CLIPrefix.MPM.value
+        if short and self in [self.DEBUG, self.INPUT]:
+            # Short flags
+            return f"-mpm:{self.value[0]}"
+        return f"{prefix}{self.value}"
+
+
+class LogLevel(str, Enum):
+    """Logging level constants."""
+    OFF = "OFF"
+    INFO = "INFO"
+    DEBUG = "DEBUG"
+
+
+class OrchestratorMode(str, Enum):
+    """Orchestrator mode constants."""
+    SYSTEM_PROMPT = "system_prompt"
+    SUBPROCESS = "subprocess"
+    INTERACTIVE_SUBPROCESS = "interactive_subprocess"
+
+
+class EnvironmentVars(str, Enum):
+    """Environment variable constants."""
+    CLAUDE_CONFIG_DIR = "CLAUDE_CONFIG_DIR"
+    CLAUDE_MAX_PARALLEL_SUBAGENTS = "CLAUDE_MAX_PARALLEL_SUBAGENTS"
+    CLAUDE_TIMEOUT = "CLAUDE_TIMEOUT"
+    CLAUDE_MPM_DEBUG = "CLAUDE_MPM_DEBUG"
+    
+    # Default values
+    DEFAULT_MAX_AGENTS = "10"
+    DEFAULT_TIMEOUT = "600000"  # 10 minutes in milliseconds
+
+
+class Paths(str, Enum):
+    """Path constants."""
+    CLAUDE_AGENTS_DIR = ".claude/agents"
+    CLAUDE_CONFIG_DIR = ".claude"
+    MPM_LOG_DIR = ".claude-mpm/logs"
+    MPM_SESSION_DIR = ".claude-mpm/session"
+    MPM_PROMPTS_DIR = ".claude-mpm/prompts"
+    
+    
+class AgentMetadata(str, Enum):
+    """Agent metadata field constants."""
+    NAME = "name"
+    DESCRIPTION = "description"
+    VERSION = "version"
+    AUTHOR = "author"
+    TAGS = "tags"
+    TOOLS = "tools"
+    PRIORITY = "priority"
+    TIMEOUT = "timeout"
+    MAX_TOKENS = "max_tokens"
+    TEMPERATURE = "temperature"
+    
+    # Default values
+    DEFAULT_AUTHOR = "claude-mpm"
+    DEFAULT_VERSION = "1.0.0"
+    DEFAULT_PRIORITY = "medium"
+    DEFAULT_TIMEOUT = 600
+    DEFAULT_MAX_TOKENS = 8192
+    DEFAULT_TEMPERATURE = 0.5

claude_mpm/core/__init__.py

@@ -0,0 +1,45 @@
+"""Core components for Claude MPM."""
+
+from .simple_runner import SimpleClaudeRunner
+from .mixins import LoggerMixin
+
+# Import config components if needed
+try:
+    from .config import Config
+    from .config_aliases import ConfigAliases
+except ImportError:
+    pass
+
+# Import DI components
+try:
+    from .container import DIContainer, ServiceLifetime, get_container
+    from .service_registry import ServiceRegistry, get_service_registry, initialize_services
+    from .injectable_service import InjectableService
+    from .factories import (
+        ServiceFactory, HookManagerFactory, OrchestratorFactoryWrapper,
+        AgentServiceFactory, SessionManagerFactory, ConfigurationFactory,
+        get_factory_registry
+    )
+except ImportError:
+    pass
+
+__all__ = [
+    "SimpleClaudeRunner",
+    "LoggerMixin",
+    "Config",
+    "ConfigAliases",
+    "DIContainer",
+    "ServiceLifetime",
+    "get_container",
+    "ServiceRegistry",
+    "get_service_registry",
+    "initialize_services",
+    "InjectableService",
+    "ServiceFactory",
+    "HookManagerFactory",
+    "OrchestratorFactoryWrapper",
+    "AgentServiceFactory",
+    "SessionManagerFactory",
+    "ConfigurationFactory",
+    "get_factory_registry",
+]