claude-mpm 3.1.1__py3-none-any.whl → 3.1.2__py3-none-any.whl

claude_mpm/cli/utils.py

@@ -0,0 +1,171 @@
+"""
+Utility functions for the CLI.
+
+WHY: This module contains shared utility functions used across different CLI commands.
+Centralizing these functions reduces code duplication and provides a single place
+for common CLI operations.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from ..core.logger import get_logger
+
+
+def get_user_input(input_arg: Optional[str], logger) -> str:
+    """
+    Get user input based on command line arguments.
+    
+    WHY: This function handles the three ways users can provide input:
+    1. Direct text via -i/--input
+    2. File path via -i/--input
+    3. stdin (for piping)
+    
+    DESIGN DECISION: We check if the input is a file path first, then fall back
+    to treating it as direct text. This allows maximum flexibility.
+    
+    Args:
+        input_arg: The value of the -i/--input argument
+        logger: Logger instance for output
+        
+    Returns:
+        The user input as a string
+    """
+    if input_arg:
+        # Check if it's a file path
+        input_path = Path(input_arg)
+        if input_path.exists():
+            logger.info(f"Reading input from file: {input_path}")
+            return input_path.read_text()
+        else:
+            logger.info("Using command line input")
+            return input_arg
+    else:
+        # Read from stdin
+        logger.info("Reading input from stdin")
+        return sys.stdin.read()
+
+
+def get_agent_versions_display() -> Optional[str]:
+    """
+    Get formatted agent versions display as a string.
+    
+    WHY: This function provides a single source of truth for agent version
+    information that can be displayed both at startup and on-demand via the
+    /mpm agents command. This ensures consistency in how agent versions are
+    presented to users.
+    
+    Returns:
+        Formatted string containing agent version information, or None if failed
+    """
+    try:
+        from ..services.agent_deployment import AgentDeploymentService
+        deployment_service = AgentDeploymentService()
+        
+        # Get deployed agents
+        verification = deployment_service.verify_deployment()
+        if not verification.get("agents_found"):
+            return None
+            
+        output_lines = []
+        output_lines.append("\nDeployed Agent Versions:")
+        output_lines.append("-" * 40)
+        
+        # Sort agents by name for consistent display
+        agents = sorted(verification["agents_found"], key=lambda x: x.get('name', x.get('file', '')))
+        
+        for agent in agents:
+            name = agent.get('name', 'unknown')
+            version = agent.get('version', 'unknown')
+            # Format: name (version)
+            output_lines.append(f"  {name:<20} {version}")
+        
+        # Add base agent version info
+        try:
+            import json
+            base_agent_path = deployment_service.base_agent_path
+            if base_agent_path.exists():
+                base_data = json.loads(base_agent_path.read_text())
+                # Parse version the same way as AgentDeploymentService
+                raw_version = base_data.get('base_version') or base_data.get('version', 0)
+                base_version_tuple = deployment_service._parse_version(raw_version)
+                base_version_str = deployment_service._format_version_display(base_version_tuple)
+                output_lines.append(f"\n  Base Agent Version:  {base_version_str}")
+        except:
+            pass
+        
+        # Check for agents needing migration
+        if verification.get("agents_needing_migration"):
+            output_lines.append(f"\n  ⚠️  {len(verification['agents_needing_migration'])} agent(s) need migration to semantic versioning")
+            output_lines.append(f"     Run 'claude-mpm agents deploy' to update")
+            
+        output_lines.append("-" * 40)
+        return "\n".join(output_lines)
+    except Exception as e:
+        # Log error but don't fail
+        logger = get_logger("cli")
+        logger.debug(f"Failed to get agent versions: {e}")
+        return None
+
+
+def list_agent_versions_at_startup() -> None:
+    """
+    List deployed agent versions at startup.
+    
+    WHY: Users want to see what agents are available when they start a session.
+    This provides immediate feedback about the deployed agent environment.
+    """
+    agent_versions = get_agent_versions_display()
+    if agent_versions:
+        print(agent_versions)
+        print()  # Extra newline after the display
+
+
+def setup_logging(args) -> object:
+    """
+    Set up logging based on parsed arguments.
+    
+    WHY: This centralizes logging setup logic, handling the deprecated --debug flag
+    and the new --logging argument consistently across all commands.
+    
+    Args:
+        args: Parsed command line arguments
+        
+    Returns:
+        Logger instance
+    """
+    from ..core.logger import setup_logging as core_setup_logging, get_logger
+    from ..constants import LogLevel
+    
+    # Handle deprecated --debug flag
+    if hasattr(args, 'debug') and args.debug and args.logging == LogLevel.INFO.value:
+        args.logging = LogLevel.DEBUG.value
+    
+    # Only setup logging if not OFF
+    if args.logging != LogLevel.OFF.value:
+        logger = core_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)
+    
+    return logger
+
+
+def ensure_directories() -> None:
+    """
+    Ensure required directories exist on first run.
+    
+    WHY: Claude-mpm needs certain directories to function properly. Rather than
+    failing when they don't exist, we create them automatically for a better
+    user experience.
+    """
+    try:
+        from ..init import ensure_directories as init_ensure_directories
+        init_ensure_directories()
+    except Exception:
+        # Continue even if initialization fails
+        # The individual commands will handle missing directories as needed
+        pass

claude_mpm/cli_enhancements.py

@@ -1,6 +1,25 @@
 """
 Enhanced CLI operations for claude-mpm.
 
+WHY THIS FILE EXISTS:
+This module provides an alternative CLI implementation with enhanced error handling
+and validation features. It was created to explore advanced CLI patterns including:
+- Comprehensive prerequisite validation
+- User-friendly error messages with suggestions
+- Dry-run mode for testing
+- Profile validation and generation
+- Rich terminal output with status indicators
+
+CURRENT STATUS: This is an experimental/alternative CLI implementation that uses
+Click instead of argparse. It's kept separate from the main CLI to:
+1. Preserve the existing CLI behavior
+2. Allow testing of new features without breaking the main interface
+3. Provide a reference implementation for future CLI enhancements
+
+NOTE: This CLI is not currently used in production. The main CLI is in cli/__init__.py.
+To use this enhanced CLI, you would need to create a separate entry point or
+integrate selected features into the main CLI.
+
 Implements error handling and user guidance patterns from awesome-claude-code.
 """
 

claude_mpm/models/__init__.py

@@ -0,0 +1,24 @@
+"""
+Agent models package.
+
+WHY: This package centralizes all data models used for agent management,
+providing a single source of truth for data structures across the system.
+"""
+
+from .agent_definition import (
+    AgentDefinition,
+    AgentMetadata,
+    AgentType,
+    AgentSection,
+    AgentWorkflow,
+    AgentPermissions
+)
+
+__all__ = [
+    'AgentDefinition',
+    'AgentMetadata',
+    'AgentType',
+    'AgentSection',
+    'AgentWorkflow',
+    'AgentPermissions'
+]

claude_mpm/models/agent_definition.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+Agent Definition Models
+=======================
+
+Data models for agent definitions used by AgentManager.
+
+WHY: These models provide a structured representation of agent data to ensure
+consistency across the system. They separate the data structure from the
+business logic, following the separation of concerns principle.
+
+DESIGN DECISION: Using dataclasses for models because:
+- They provide automatic __init__, __repr__, and other methods
+- Type hints ensure better IDE support and runtime validation
+- Easy to serialize/deserialize for persistence
+- Less boilerplate than traditional classes
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Any
+
+
+class AgentType(str, Enum):
+    """Agent type classification.
+    
+    WHY: Enum ensures only valid agent types are used throughout the system,
+    preventing typos and making the code more maintainable.
+    """
+    CORE = "core"
+    PROJECT = "project"
+    CUSTOM = "custom"
+    SYSTEM = "system"
+    SPECIALIZED = "specialized"
+
+
+class AgentSection(str, Enum):
+    """Agent markdown section identifiers.
+    
+    WHY: Standardizes section names across the codebase, making it easier
+    to parse and update specific sections programmatically.
+    """
+    PRIMARY_ROLE = "Primary Role"
+    WHEN_TO_USE = "When to Use This Agent"
+    CAPABILITIES = "Core Capabilities"
+    AUTHORITY = "Authority & Permissions"
+    WORKFLOWS = "Agent-Specific Workflows"
+    ESCALATION = "Unique Escalation Triggers"
+    KPI = "Key Performance Indicators"
+    DEPENDENCIES = "Critical Dependencies"
+    TOOLS = "Specialized Tools/Commands"
+
+
+@dataclass
+class AgentPermissions:
+    """Agent authority and permissions.
+    
+    WHY: Separating permissions into a dedicated class allows for:
+    - Clear permission boundaries
+    - Easy permission checking and validation
+    - Future extension without modifying the main agent definition
+    """
+    exclusive_write_access: List[str] = field(default_factory=list)
+    forbidden_operations: List[str] = field(default_factory=list)
+    read_access: List[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentWorkflow:
+    """Agent workflow definition.
+    
+    WHY: Workflows are complex structures that benefit from their own model:
+    - Ensures consistent workflow structure
+    - Makes workflow validation easier
+    - Allows workflow-specific operations
+    """
+    name: str
+    trigger: str
+    process: List[str]
+    output: str
+    raw_yaml: Optional[str] = None
+
+
+@dataclass
+class AgentMetadata:
+    """Agent metadata information.
+    
+    WHY: Metadata is separated from the main definition because:
+    - It changes independently of agent behavior
+    - It's used for discovery and management, not execution
+    - Different services may need different metadata views
+    """
+    type: AgentType
+    model_preference: str = "claude-3-sonnet"
+    version: str = "1.0.0"
+    last_updated: Optional[datetime] = None
+    author: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+    specializations: List[str] = field(default_factory=list)
+    
+    def increment_serial_version(self) -> None:
+        """Increment the patch version number.
+        
+        WHY: Automatic version incrementing ensures every change is tracked
+        and follows semantic versioning principles.
+        """
+        parts = self.version.split('.')
+        if len(parts) == 3:
+            parts[2] = str(int(parts[2]) + 1)
+            self.version = '.'.join(parts)
+        else:
+            # If version format is unexpected, append .1
+            self.version = f"{self.version}.1"
+
+
+@dataclass
+class AgentDefinition:
+    """Complete agent definition.
+    
+    WHY: This is the main model that represents an agent's complete configuration:
+    - Combines all aspects of an agent in one place
+    - Provides a clear contract for what constitutes an agent
+    - Makes serialization/deserialization straightforward
+    
+    DESIGN DECISION: Using composition over inheritance:
+    - AgentMetadata, AgentPermissions, and AgentWorkflow are separate classes
+    - This allows each component to evolve independently
+    - Services can work with just the parts they need
+    """
+    # Core identifiers
+    name: str
+    title: str
+    file_path: str
+    
+    # Metadata
+    metadata: AgentMetadata
+    
+    # Agent behavior definition
+    primary_role: str
+    when_to_use: Dict[str, List[str]]  # {"select": [...], "do_not_select": [...]}
+    capabilities: List[str]
+    authority: AgentPermissions
+    workflows: List[AgentWorkflow]
+    escalation_triggers: List[str]
+    kpis: List[str]
+    dependencies: List[str]
+    tools_commands: str
+    
+    # Raw content for preservation
+    raw_content: str = ""
+    raw_sections: Dict[str, str] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API responses.
+        
+        WHY: Many parts of the system need agent data as dictionaries:
+        - JSON serialization for APIs
+        - Configuration storage
+        - Integration with other services
+        """
+        return {
+            "name": self.name,
+            "title": self.title,
+            "file_path": self.file_path,
+            "metadata": {
+                "type": self.metadata.type.value,
+                "model_preference": self.metadata.model_preference,
+                "version": self.metadata.version,
+                "last_updated": self.metadata.last_updated.isoformat() if self.metadata.last_updated else None,
+                "author": self.metadata.author,
+                "tags": self.metadata.tags,
+                "specializations": self.metadata.specializations
+            },
+            "primary_role": self.primary_role,
+            "when_to_use": self.when_to_use,
+            "capabilities": self.capabilities,
+            "authority": {
+                "exclusive_write_access": self.authority.exclusive_write_access,
+                "forbidden_operations": self.authority.forbidden_operations,
+                "read_access": self.authority.read_access
+            },
+            "workflows": [
+                {
+                    "name": w.name,
+                    "trigger": w.trigger,
+                    "process": w.process,
+                    "output": w.output
+                }
+                for w in self.workflows
+            ],
+            "escalation_triggers": self.escalation_triggers,
+            "kpis": self.kpis,
+            "dependencies": self.dependencies,
+            "tools_commands": self.tools_commands
+        }