claude-mpm 4.21.0__py3-none-any.whl → 5.0.2__py3-none-any.whl

claude_mpm/config/agent_presets.py

@@ -0,0 +1,258 @@
+"""Agent preset configurations for common development scenarios.
+
+This module defines preset bundles of agents for typical development workflows.
+Presets enable users to deploy entire agent stacks with a single command like:
+    claude-mpm agents deploy --preset python-dev
+
+Design Decision: Presets use agent IDs from AUTO-DEPLOY-INDEX.md format
+(e.g., "universal/memory-manager", "engineer/backend/python-engineer").
+
+Trade-offs:
+- Simplicity: Static lists are easy to maintain
+- Flexibility: Dynamic functions allow auto-detection (future enhancement)
+- Discoverability: Presets shown in CLI help and error messages
+"""
+
+from typing import Any, Callable, Dict, List, Union
+
+# Type for preset resolver (can be static list or dynamic function)
+PresetResolver = Union[List[str], Callable[[], List[str]]]
+
+PRESETS: Dict[str, Dict[str, Any]] = {
+    "minimal": {
+        "description": "6 core agents for any project",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/python-engineer",  # Will be language-specific in future
+            "qa/qa",
+            "ops/core/ops",
+        ],
+        "use_cases": ["Micro projects", "Quick prototypes", "Learning"],
+    },
+    "python-dev": {
+        "description": "Python backend development stack (8 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/python-engineer",
+            "qa/qa",
+            "qa/api-qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["FastAPI projects", "Django projects", "Python APIs"],
+    },
+    "python-fullstack": {
+        "description": "Python backend + React frontend (12 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "universal/code-analyzer",
+            "documentation/documentation",
+            "documentation/ticketing",
+            "engineer/backend/python-engineer",
+            "engineer/frontend/react-engineer",
+            "qa/qa",
+            "qa/api-qa",
+            "qa/web-qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["FastAPI + React", "Django + React", "Full-stack Python"],
+    },
+    "javascript-backend": {
+        "description": "Node.js backend development (8 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/javascript-engineer",
+            "qa/qa",
+            "qa/api-qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["Express.js", "Fastify", "Koa", "Node.js APIs"],
+    },
+    "react-dev": {
+        "description": "React frontend development (9 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/frontend/react-engineer",
+            "engineer/data/typescript-engineer",
+            "qa/qa",
+            "qa/web-qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["React SPAs", "Component libraries", "Frontend projects"],
+    },
+    "nextjs-fullstack": {
+        "description": "Next.js full-stack development (13 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "universal/code-analyzer",
+            "documentation/documentation",
+            "engineer/frontend/nextjs-engineer",
+            "engineer/frontend/react-engineer",
+            "engineer/data/typescript-engineer",
+            "qa/qa",
+            "qa/web-qa",
+            "ops/core/ops",
+            "ops/platform/vercel-ops",
+            "security/security",
+            "documentation/ticketing",
+        ],
+        "use_cases": ["Next.js apps", "Vercel deployments", "Full-stack TypeScript"],
+    },
+    "rust-dev": {
+        "description": "Rust systems development (7 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/rust-engineer",
+            "qa/qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["Rust systems", "CLI tools", "WebAssembly"],
+    },
+    "golang-dev": {
+        "description": "Go backend development (8 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/golang-engineer",
+            "qa/qa",
+            "qa/api-qa",
+            "ops/core/ops",
+            "security/security",
+        ],
+        "use_cases": ["Go APIs", "Microservices", "Cloud-native apps"],
+    },
+    "java-dev": {
+        "description": "Java/Spring Boot development (9 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/java-engineer",
+            "qa/qa",
+            "qa/api-qa",
+            "ops/core/ops",
+            "security/security",
+            "documentation/ticketing",
+        ],
+        "use_cases": ["Spring Boot", "Java EE", "Enterprise applications"],
+    },
+    "mobile-flutter": {
+        "description": "Flutter mobile development (8 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/mobile/dart-engineer",
+            "qa/qa",
+            "ops/core/ops",
+            "security/security",
+            "documentation/ticketing",
+        ],
+        "use_cases": ["Flutter apps", "Cross-platform mobile", "iOS/Android"],
+    },
+    "data-eng": {
+        "description": "Data engineering stack (10 agents)",
+        "agents": [
+            "universal/memory-manager",
+            "universal/research",
+            "documentation/documentation",
+            "engineer/backend/python-engineer",
+            "engineer/data/data-engineer",
+            "qa/qa",
+            "ops/core/ops",
+            "security/security",
+            "documentation/ticketing",
+            "universal/code-analyzer",
+        ],
+        "use_cases": ["dbt projects", "Airflow", "Data pipelines", "ETL"],
+    },
+}
+
+
+def get_preset_names() -> List[str]:
+    """Get list of all available preset names.
+
+    Returns:
+        List of preset names (e.g., ['minimal', 'python-dev', ...])
+
+    Example:
+        >>> names = get_preset_names()
+        >>> 'minimal' in names
+        True
+    """
+    return list(PRESETS.keys())
+
+
+def get_preset_info(preset_name: str) -> Dict[str, Any]:
+    """Get preset metadata (description, use cases, agent count).
+
+    Args:
+        preset_name: Name of preset (e.g., 'python-dev')
+
+    Returns:
+        Dict with keys:
+        - name: Preset name
+        - description: Human-readable description
+        - agent_count: Number of agents in preset
+        - use_cases: List of use case strings
+
+    Raises:
+        ValueError: If preset name is invalid
+
+    Example:
+        >>> info = get_preset_info('minimal')
+        >>> info['agent_count']
+        6
+    """
+    if preset_name not in PRESETS:
+        raise ValueError(f"Unknown preset: {preset_name}")
+
+    preset = PRESETS[preset_name]
+    return {
+        "name": preset_name,
+        "description": preset["description"],
+        "agent_count": len(preset["agents"]),
+        "use_cases": preset["use_cases"],
+    }
+
+
+def get_preset_agents(preset_name: str) -> List[str]:
+    """Get agent list for preset.
+
+    Args:
+        preset_name: Name of preset (e.g., 'python-dev')
+
+    Returns:
+        List of agent IDs (e.g., ["universal/memory-manager", ...])
+
+    Raises:
+        ValueError: If preset name is invalid
+
+    Example:
+        >>> agents = get_preset_agents('minimal')
+        >>> len(agents)
+        6
+        >>> 'universal/memory-manager' in agents
+        True
+    """
+    if preset_name not in PRESETS:
+        raise ValueError(f"Unknown preset: {preset_name}")
+
+    return PRESETS[preset_name]["agents"]

claude_mpm/config/agent_sources.py

@@ -0,0 +1,325 @@
+"""Configuration for agent sources (Git repositories)."""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from claude_mpm.models.git_repository import GitRepository
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentSourceConfiguration:
+    """Configuration for agent sources.
+
+    This class manages the configuration of Git repositories that contain
+    agent markdown files. It supports:
+    - System repository (bobmatnyc/claude-mpm-agents) with disable option
+    - Multiple custom repositories with priority-based resolution
+    - YAML persistence for configuration
+    - Repository management (add, remove, enable, disable)
+
+    Attributes:
+        disable_system_repo: If True, don't include default system repository
+                            (default: True as of v4.5.0 - git sources are now preferred)
+        repositories: List of custom Git repositories
+    """
+
+    disable_system_repo: bool = True  # Changed from False to True in v4.5.0
+    repositories: list[GitRepository] = field(default_factory=list)
+
+    @classmethod
+    def create_default_configuration(cls) -> "AgentSourceConfiguration":
+        """Create default configuration with git sources enabled.
+
+        Returns:
+            AgentSourceConfiguration with default git repository configured
+
+        Example:
+            >>> config = AgentSourceConfiguration.create_default_configuration()
+            >>> print(config.repositories[0].url)
+            'https://github.com/bobmatnyc/claude-mpm-agents'
+        """
+        # Create default git repository
+        default_repo = GitRepository(
+            url="https://github.com/bobmatnyc/claude-mpm-agents",
+            subdirectory="agents",
+            enabled=True,
+            priority=100,
+        )
+
+        return cls(
+            disable_system_repo=True,  # Disable built-in templates, use git sources
+            repositories=[default_repo],
+        )
+
+    @classmethod
+    def load(cls, config_path: Optional[Path] = None) -> "AgentSourceConfiguration":
+        """Load configuration from YAML file.
+
+        Args:
+            config_path: Path to YAML configuration file.
+                        Defaults to ~/.claude-mpm/config/agent_sources.yaml
+
+        Returns:
+            AgentSourceConfiguration instance
+
+        Example:
+            >>> config = AgentSourceConfiguration.load()
+            >>> print(config.repositories)
+        """
+        if config_path is None:
+            config_path = Path.home() / ".claude-mpm" / "config" / "agent_sources.yaml"
+
+        # If file doesn't exist, create default configuration with git sources
+        if not config_path.exists():
+            logger.info(
+                f"Configuration file not found at {config_path}, creating default with git sources"
+            )
+            default_config = cls.create_default_configuration()
+            # Save the default configuration for future use
+            try:
+                default_config.save(config_path)
+            except Exception as e:
+                logger.warning(f"Could not save default configuration: {e}")
+            return default_config
+
+        try:
+            with open(config_path) as f:
+                data = yaml.safe_load(f)
+
+            if not data:
+                logger.warning(
+                    f"Empty configuration file at {config_path}, using defaults"
+                )
+                return cls()
+
+            # Parse configuration
+            # Note: Default changed from False to True in v4.5.0
+            # For backward compatibility, if key is missing, use new default (True)
+            disable_system_repo = data.get("disable_system_repo", True)
+
+            # Parse repositories
+            repositories = []
+            for repo_data in data.get("repositories", []):
+                repo = GitRepository(
+                    url=repo_data["url"],
+                    subdirectory=repo_data.get("subdirectory"),
+                    enabled=repo_data.get("enabled", True),
+                    priority=repo_data.get("priority", 100),
+                )
+                repositories.append(repo)
+
+            return cls(
+                disable_system_repo=disable_system_repo, repositories=repositories
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to load configuration from {config_path}: {e}")
+            logger.info("Using default configuration")
+            return cls()
+
+    def save(
+        self, config_path: Optional[Path] = None, include_comments: bool = True
+    ) -> None:
+        """Save configuration to YAML file.
+
+        Args:
+            config_path: Path to YAML configuration file.
+                        Defaults to ~/.claude-mpm/config/agent_sources.yaml
+            include_comments: Whether to include helpful comments in the YAML file
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> config.save()
+        """
+        if config_path is None:
+            config_path = Path.home() / ".claude-mpm" / "config" / "agent_sources.yaml"
+
+        # Ensure parent directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            with open(config_path, "w") as f:
+                # Write header comments if requested
+                if include_comments:
+                    f.write("# Claude MPM Agent Sources Configuration\n")
+                    f.write("#\n")
+                    f.write(
+                        "# This file configures where Claude MPM discovers agent templates.\n"
+                    )
+                    f.write(
+                        "# Git sources are the recommended approach for agent management.\n"
+                    )
+                    f.write("#\n")
+                    f.write(
+                        "# disable_system_repo: Set to true to use git sources instead of built-in templates\n"
+                    )
+                    f.write(
+                        "# repositories: List of git repositories containing agent markdown files\n"
+                    )
+                    f.write("#\n")
+                    f.write(
+                        "# Default repository: https://github.com/bobmatnyc/claude-mpm-agents\n"
+                    )
+                    f.write("#\n\n")
+
+                # Build YAML data structure
+                data = {
+                    "disable_system_repo": self.disable_system_repo,
+                    "repositories": [
+                        {
+                            "url": repo.url,
+                            "subdirectory": repo.subdirectory,
+                            "enabled": repo.enabled,
+                            "priority": repo.priority,
+                        }
+                        for repo in self.repositories
+                    ],
+                }
+
+                yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
+
+            logger.info(f"Configuration saved to {config_path}")
+
+        except Exception as e:
+            logger.error(f"Failed to save configuration to {config_path}: {e}")
+            raise
+
+    def get_system_repo(self) -> Optional[GitRepository]:
+        """Get system repository if not disabled.
+
+        Returns:
+            GitRepository for system repo, or None if disabled
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> system_repo = config.get_system_repo()
+            >>> print(system_repo.url)
+            'https://github.com/bobmatnyc/claude-mpm-agents'
+        """
+        if self.disable_system_repo:
+            return None
+
+        return GitRepository(
+            url="https://github.com/bobmatnyc/claude-mpm-agents",
+            subdirectory="agents",
+            enabled=True,
+            priority=100,
+        )
+
+    def get_enabled_repositories(self) -> list[GitRepository]:
+        """Get all enabled repositories sorted by priority.
+
+        Returns repositories in priority order (lower priority number = higher precedence).
+        Includes system repository if not disabled.
+
+        Returns:
+            List of enabled GitRepository instances, sorted by priority
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> repos = config.get_enabled_repositories()
+            >>> for repo in repos:
+            ...     print(f"{repo.identifier} (priority: {repo.priority})")
+        """
+        repos = []
+
+        # Add system repo if not disabled
+        system_repo = self.get_system_repo()
+        if system_repo:
+            repos.append(system_repo)
+
+        # Add enabled custom repositories
+        repos.extend([r for r in self.repositories if r.enabled])
+
+        # Sort by priority (lower number = higher precedence)
+        return sorted(repos, key=lambda r: r.priority)
+
+    def add_repository(self, repo: GitRepository) -> None:
+        """Add a new repository.
+
+        Args:
+            repo: GitRepository to add
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> repo = GitRepository(url="https://github.com/owner/repo")
+            >>> config.add_repository(repo)
+        """
+        self.repositories.append(repo)
+        logger.info(f"Added repository: {repo.identifier}")
+
+    def remove_repository(self, identifier: str) -> bool:
+        """Remove repository by identifier.
+
+        Args:
+            identifier: Repository identifier (e.g., "owner/repo" or "owner/repo/subdirectory")
+
+        Returns:
+            True if repository was removed, False if not found
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> repo = GitRepository(url="https://github.com/owner/repo")
+            >>> config.add_repository(repo)
+            >>> removed = config.remove_repository("owner/repo")
+            >>> print(removed)
+            True
+        """
+        for i, repo in enumerate(self.repositories):
+            if repo.identifier == identifier:
+                removed_repo = self.repositories.pop(i)
+                logger.info(f"Removed repository: {removed_repo.identifier}")
+                return True
+
+        logger.warning(f"Repository not found: {identifier}")
+        return False
+
+    def validate(self) -> list[str]:
+        """Validate configuration.
+
+        Checks:
+        - All repositories pass validation
+        - No duplicate repository identifiers
+        - Priority values are reasonable
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        Example:
+            >>> config = AgentSourceConfiguration()
+            >>> errors = config.validate()
+            >>> if errors:
+            ...     print("Validation errors:", errors)
+        """
+        errors = []
+
+        # Validate each repository
+        for repo in self.repositories:
+            repo_errors = repo.validate()
+            if repo_errors:
+                errors.append(f"Repository {repo.identifier}: {', '.join(repo_errors)}")
+
+        # Check for duplicate identifiers
+        identifiers = [repo.identifier for repo in self.repositories]
+        duplicates = {id for id in identifiers if identifiers.count(id) > 1}
+
+        if duplicates:
+            errors.append(
+                f"Duplicate repository identifiers found: {', '.join(duplicates)}"
+            )
+
+        return errors
+
+    def __repr__(self) -> str:
+        """Return string representation of configuration."""
+        return (
+            f"AgentSourceConfiguration("
+            f"system_repo={'disabled' if self.disable_system_repo else 'enabled'}, "
+            f"custom_repos={len(self.repositories)})"
+        )