claude-mpm 3.3.2__py3-none-any.whl → 3.4.2__py3-none-any.whl

claude_mpm/cli_module/refactoring_guide.md

@@ -1,253 +0,0 @@
-# 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/core/agent_registry.py.bak

@@ -1,312 +0,0 @@
-"""Agent registry integration for Claude MPM."""
-
-import os
-import sys
-from pathlib import Path
-from typing import Optional, Dict, Any, List
-import importlib.util
-
-try:
-    from ..core.logger import get_logger
-except ImportError:
-    from core.logger import get_logger
-
-
-class SimpleAgentRegistry:
-    """Simple agent registry implementation."""
-    
-    def __init__(self, framework_path: Path):
-        self.framework_path = framework_path
-        self.agents = {}
-        self._discover_agents()
-    
-    def _discover_agents(self):
-        """Discover agents from the framework."""
-        agents_dir = self.framework_path / "src" / "claude_mpm" / "agents"
-        if agents_dir.exists():
-            for agent_file in agents_dir.glob("*.md"):
-                agent_id = agent_file.stem
-                self.agents[agent_id] = {
-                    'type': agent_id,
-                    'path': str(agent_file),
-                    'last_modified': agent_file.stat().st_mtime
-                }
-    
-    def listAgents(self, **kwargs):
-        """List all agents."""
-        return self.agents
-
-
-class AgentRegistryAdapter:
-    """
-    Adapter to integrate claude-multiagent-pm's agent registry.
-    
-    This adapter:
-    1. Locates the claude-multiagent-pm installation
-    2. Dynamically imports the agent registry
-    3. Provides a clean interface for agent operations
-    """
-    
-    def __init__(self, framework_path: Optional[Path] = None):
-        """
-        Initialize the agent registry adapter.
-        
-        Args:
-            framework_path: Path to claude-multiagent-pm (auto-detected if None)
-        """
-        self.logger = get_logger("agent_registry")
-        self.framework_path = framework_path or self._find_framework()
-        self.registry = None
-        self._initialize_registry()
-    
-    def _find_framework(self) -> Optional[Path]:
-        """Find claude-mpm installation.
-        
-        Search order:
-        1. CLAUDE_MPM_PATH environment variable
-        2. Current working directory (if it's claude-mpm)
-        3. Walk up from current file location
-        4. Common development locations
-        """
-        # Check environment variable first
-        env_path = os.environ.get("CLAUDE_MPM_PATH")
-        if env_path:
-            candidate = Path(env_path)
-            if self._is_valid_framework_path(candidate):
-                self.logger.info(f"Using claude-mpm from CLAUDE_MPM_PATH: {candidate}")
-                return candidate
-            else:
-                self.logger.warning(f"CLAUDE_MPM_PATH is set but invalid: {env_path}")
-        
-        # Check current working directory
-        cwd = Path.cwd()
-        if self._is_valid_framework_path(cwd):
-            return cwd
-            
-        # Check if we're running from within the installed package
-        current_file = Path(__file__).resolve()
-        for parent in current_file.parents:
-            if self._is_valid_framework_path(parent):
-                return parent
-            # Stop at site-packages or similar
-            if parent.name in ("site-packages", "dist-packages", "lib"):
-                break
-        
-        # Check common development locations
-        candidates = [
-            Path.home() / "Projects" / "claude-mpm",
-            Path.home() / "claude-mpm",
-        ]
-        
-        for candidate in candidates:
-            if self._is_valid_framework_path(candidate):
-                self.logger.info(f"Found claude-mpm at: {candidate}")
-                return candidate
-        
-        return None
-    
-    def _is_valid_framework_path(self, path: Path) -> bool:
-        """Check if a path is a valid claude-mpm installation."""
-        return (
-            path.exists() and 
-            (path / "src" / "claude_mpm").exists() and 
-            (path / "src" / "claude_mpm" / "agents").exists()
-        )
-    
-    def _initialize_registry(self):
-        """Initialize the agent registry."""
-        if not self.framework_path:
-            self.logger.warning("No framework path, registry unavailable")
-            return
-        
-        try:
-            # For now, create a simple registry implementation
-            # This will be replaced with proper agent discovery later
-            self.registry = SimpleAgentRegistry(self.framework_path)
-            self.logger.info("Agent registry initialized successfully")
-            
-        except Exception as e:
-            self.logger.error(f"Failed to initialize registry: {e}")
-    
-    def list_agents(self, **kwargs) -> Dict[str, Any]:
-        """
-        List available agents.
-        
-        Args:
-            **kwargs: Arguments to pass to AgentRegistry.listAgents()
-            
-        Returns:
-            Dictionary of agents with metadata
-        """
-        if not self.registry:
-            return {}
-        
-        try:
-            return self.registry.listAgents(**kwargs)
-        except Exception as e:
-            self.logger.error(f"Error listing agents: {e}")
-            return {}
-    
-    def get_agent_definition(self, agent_name: str) -> Optional[str]:
-        """
-        Get agent definition by name.
-        
-        Args:
-            agent_name: Name of the agent
-            
-        Returns:
-            Agent definition content or None
-        """
-        if not self.registry:
-            return None
-        
-        try:
-            # Try to load agent definition
-            agents = self.registry.listAgents()
-            for agent_id, metadata in agents.items():
-                if agent_name in agent_id or agent_name == metadata.get('type'):
-                    # Load the agent file
-                    agent_path = Path(metadata['path'])
-                    if agent_path.exists():
-                        return agent_path.read_text()
-            
-            return None
-            
-        except Exception as e:
-            self.logger.error(f"Error getting agent definition: {e}")
-            return None
-    
-    def select_agent_for_task(self, task_description: str, required_specializations: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
-        """
-        Select optimal agent for a task.
-        
-        Args:
-            task_description: Description of the task
-            required_specializations: Required agent specializations
-            
-        Returns:
-            Agent metadata or None
-        """
-        if not self.registry:
-            return None
-        
-        try:
-            # Get agents with required specializations
-            if required_specializations:
-                agents = self.registry.listAgents(specializations=required_specializations)
-            else:
-                agents = self.registry.listAgents()
-            
-            if not agents:
-                return None
-            
-            # For now, return the first matching agent
-            # In future, could implement more sophisticated selection
-            agent_id = next(iter(agents))
-            return {
-                'id': agent_id,
-                'metadata': agents[agent_id]
-            }
-            
-        except Exception as e:
-            self.logger.error(f"Error selecting agent: {e}")
-            return None
-    
-    def get_agent_hierarchy(self) -> Dict[str, List[str]]:
-        """
-        Get agent hierarchy (project → user → system).
-        
-        Returns:
-            Dictionary with hierarchy levels and agent names
-        """
-        if not self.registry:
-            return {
-                'project': [],
-                'user': [],
-                'system': []
-            }
-        
-        try:
-            # Get all agents
-            all_agents = self.registry.listAgents()
-            
-            hierarchy = {
-                'project': [],
-                'user': [],
-                'system': []
-            }
-            
-            # Categorize by path
-            for agent_id, metadata in all_agents.items():
-                agent_path = metadata.get('path', '')
-                
-                if 'project-specific' in agent_path:
-                    hierarchy['project'].append(agent_id)
-                elif 'user-agents' in agent_path or 'user-defined' in agent_path:
-                    hierarchy['user'].append(agent_id)
-                else:
-                    hierarchy['system'].append(agent_id)
-            
-            return hierarchy
-            
-        except Exception as e:
-            self.logger.error(f"Error getting hierarchy: {e}")
-            return {'project': [], 'user': [], 'system': []}
-    
-    def get_core_agents(self) -> List[str]:
-        """
-        Get list of core system agents.
-        
-        Returns:
-            List of core agent names
-        """
-        return [
-            'documentation',
-            'engineer', 
-            'qa',
-            'research',
-            'ops',
-            'security',
-            'version-control',
-            'data-engineer'
-        ]
-    
-    def format_agent_for_task_tool(self, agent_name: str, task: str, context: str = "") -> str:
-        """
-        Format agent delegation for Task Tool.
-        
-        Args:
-            agent_name: Name of the agent
-            task: Task description
-            context: Additional context
-            
-        Returns:
-            Formatted Task Tool prompt
-        """
-        # Map agent names to nicknames
-        nicknames = {
-            'documentation': 'Documenter',
-            'engineer': 'Engineer',
-            'qa': 'QA',
-            'research': 'Researcher',
-            'ops': 'Ops',
-            'security': 'Security',
-            'version-control': 'Versioner',
-            'data-engineer': 'Data Engineer'
-        }
-        
-        nickname = nicknames.get(agent_name, agent_name.title())
-        
-        from datetime import datetime
-        today = datetime.now().strftime("%Y-%m-%d")
-        
-        return f"""**{nickname}**: {task}
-
-TEMPORAL CONTEXT: Today is {today}. Apply date awareness to task execution.
-
-**Task**: {task}
-
-**Context**: {context}
-
-**Authority**: Agent has full authority for {agent_name} operations
-**Expected Results**: Completed task with operational insights"""