claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/services/pr/pr_template_service.py

@@ -0,0 +1,329 @@
+"""
+Pull Request Template Service
+==============================
+
+Generates consistent PR titles and descriptions for agent/skill improvements.
+
+Design Decisions:
+- Follows conventional commit format
+- Generates comprehensive PR descriptions with testing checklists
+- Supports both agent and skill PR types
+- Validates conventional commit message format
+
+Example:
+    >>> service = PRTemplateService()
+    >>> title = service.generate_pr_title("research", "improve memory efficiency", PRType.AGENT)
+    >>> print(title)
+    feat(agent): improve research - improve memory efficiency
+
+    >>> body = service.generate_agent_pr_body(
+    ...     agent_name="research",
+    ...     problem="Memory exhaustion with >50 files",
+    ...     solution="Add hard limit of 5 files per session",
+    ...     testing_notes="Tested with 100-file codebase",
+    ...     related_issues=["#157"]
+    ... )
+"""
+
+from enum import Enum
+from typing import List, Optional
+
+
+class PRType(Enum):
+    """Type of pull request."""
+
+    AGENT = "agent"
+    SKILL = "skill"
+
+
+class PRTemplateService:
+    """
+    Service for generating PR templates.
+
+    Generates consistent PR titles and descriptions following
+    conventional commit format and best practices.
+    """
+
+    # Conventional commit types
+    COMMIT_TYPES = {
+        "feat": "New feature or enhancement",
+        "fix": "Bug fix",
+        "docs": "Documentation changes",
+        "refactor": "Code refactoring without feature changes",
+        "test": "Adding or updating tests",
+        "chore": "Maintenance tasks",
+    }
+
+    def generate_pr_title(
+        self,
+        item_name: str,
+        brief_description: str,
+        pr_type: PRType,
+        commit_type: str = "feat",
+    ) -> str:
+        """
+        Generate PR title in conventional commit format.
+
+        Format: {commit_type}({scope}): {item} - {brief_description}
+
+        Args:
+            item_name: Agent or skill name (e.g., "research", "fastapi-testing")
+            brief_description: Brief description (e.g., "improve memory handling")
+            pr_type: Type of PR (agent or skill)
+            commit_type: Conventional commit type (default: "feat")
+
+        Returns:
+            Formatted PR title
+
+        Example:
+            >>> service = PRTemplateService()
+            >>> service.generate_pr_title("research", "improve memory handling", PRType.AGENT)
+            'feat(agent): improve research - improve memory handling'
+        """
+        scope = pr_type.value
+        return f"{commit_type}({scope}): improve {item_name} - {brief_description}"
+
+    def generate_agent_pr_body(
+        self,
+        agent_name: str,
+        problem: str,
+        solution: str,
+        testing_notes: str,
+        related_issues: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Generate PR body for agent improvements.
+
+        Args:
+            agent_name: Agent name (e.g., "research")
+            problem: Problem statement (what wasn't working)
+            solution: Solution overview (what was changed)
+            testing_notes: Testing performed
+            related_issues: Related issue numbers (e.g., ["#157", "#142"])
+
+        Returns:
+            Formatted PR body in markdown
+
+        Example:
+            >>> service = PRTemplateService()
+            >>> body = service.generate_agent_pr_body(
+            ...     agent_name="research",
+            ...     problem="Memory exhaustion when analyzing >50 files",
+            ...     solution="Add hard limit of 5 files per session with MCP summarizer",
+            ...     testing_notes="Tested with 100-file codebase, memory stayed under 4GB",
+            ...     related_issues=["#157"]
+            ... )
+        """
+        related_section = ""
+        if related_issues:
+            related_section = "\n\n## Related Issues\n\n"
+            for issue in related_issues:
+                # Check if it's just a number or already has #
+                issue_ref = issue if issue.startswith("#") else f"#{issue}"
+                related_section += f"Closes {issue_ref}\n"
+
+        return f"""## Problem Statement
+
+{problem}
+
+## Proposed Solution
+
+{solution}
+
+## Changes Made
+
+**Agent:** `{agent_name}`
+
+{self._format_changes_placeholder()}
+
+## Testing Performed
+
+{testing_notes}
+
+- [x] Validated YAML frontmatter syntax
+- [x] Tested agent with sample tasks
+- [x] Verified no regression in existing behavior
+{related_section}
+## Checklist
+
+- [x] Instructions are clear and unambiguous
+- [x] No conflicting guidance
+- [x] Follows agent architecture best practices
+- [x] Documentation updated if needed
+
+---
+🤖 Generated with Claude MPM Agent Improver
+Co-Authored-By: agent-improver <noreply@anthropic.com>
+"""
+
+    def generate_skill_pr_body(
+        self,
+        skill_name: str,
+        improvements: str,
+        justification: str,
+        examples: str,
+        related_issues: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Generate PR body for skill improvements.
+
+        Args:
+            skill_name: Skill name (e.g., "fastapi-testing")
+            improvements: Description of improvements made
+            justification: Why these improvements were needed
+            examples: Examples added or updated
+            related_issues: Related issue numbers
+
+        Returns:
+            Formatted PR body in markdown
+
+        Example:
+            >>> service = PRTemplateService()
+            >>> body = service.generate_skill_pr_body(
+            ...     skill_name="fastapi-testing",
+            ...     improvements="Added async test patterns and database handling",
+            ...     justification="Users struggled with async endpoint testing",
+            ...     examples="pytest-asyncio config, AsyncClient usage, DB rollback patterns",
+            ...     related_issues=["#203"]
+            ... )
+        """
+        related_section = ""
+        if related_issues:
+            related_section = "\n\n## Related Issues\n\n"
+            for issue in related_issues:
+                issue_ref = issue if issue.startswith("#") else f"#{issue}"
+                related_section += f"Requested by: Issue {issue_ref}\n"
+
+        return f"""## Skill Enhancement
+
+**Skill:** `{skill_name}`
+
+## Motivation
+
+{justification}
+
+## Improvements
+
+{improvements}
+
+## Examples Added
+
+{examples}
+
+## Testing
+
+- [x] Validated YAML frontmatter
+- [x] Verified skill syntax
+- [x] Tested examples in relevant project
+- [x] No conflicts with existing skills
+{related_section}
+---
+🤖 Generated with Claude MPM Skills Manager
+Co-Authored-By: skills-manager <noreply@anthropic.com>
+"""
+
+    def validate_conventional_commit(self, message: str) -> bool:
+        """
+        Validate that message follows conventional commit format.
+
+        Format: type(scope): description
+
+        Args:
+            message: Commit message to validate
+
+        Returns:
+            True if message follows conventional commit format
+
+        Example:
+            >>> service = PRTemplateService()
+            >>> service.validate_conventional_commit("feat(agent): improve research")
+            True
+            >>> service.validate_conventional_commit("improve research agent")
+            False
+        """
+        if not message:
+            return False
+
+        # Extract first line (title)
+        first_line = message.split("\n")[0]
+
+        # Check basic format: type(scope): description
+        if ":" not in first_line:
+            return False
+
+        # Split into type/scope and description
+        parts = first_line.split(":", 1)
+        if len(parts) != 2:
+            return False
+
+        type_scope = parts[0].strip()
+        description = parts[1].strip()
+
+        # Check type(scope) format
+        if "(" not in type_scope or ")" not in type_scope:
+            return False
+
+        # Extract type
+        commit_type = type_scope.split("(")[0].strip()
+
+        # Validate type is recognized
+        if commit_type not in self.COMMIT_TYPES:
+            return False
+
+        # Check description is not empty
+        if not description:
+            return False
+
+        return True
+
+    def _format_changes_placeholder(self) -> str:
+        """
+        Generate placeholder text for changes section.
+
+        Returns:
+            Formatted changes placeholder
+        """
+        return """_Detailed changes will be visible in the diff. Key modifications:_
+- [List specific instruction changes]
+- [List frontmatter updates if any]
+- [List any related file changes]"""
+
+    def generate_commit_message(
+        self,
+        item_name: str,
+        brief_description: str,
+        detailed_changes: str,
+        pr_type: PRType,
+        commit_type: str = "feat",
+    ) -> str:
+        """
+        Generate conventional commit message.
+
+        Args:
+            item_name: Agent or skill name
+            brief_description: Brief description
+            detailed_changes: Detailed list of changes
+            pr_type: Type (agent or skill)
+            commit_type: Conventional commit type
+
+        Returns:
+            Formatted commit message
+
+        Example:
+            >>> service = PRTemplateService()
+            >>> msg = service.generate_commit_message(
+            ...     "research",
+            ...     "improve memory efficiency",
+            ...     "- Add hard limit of 5 files\\n- Document MCP summarizer",
+            ...     PRType.AGENT
+            ... )
+        """
+        scope = pr_type.value
+        title = f"{commit_type}({scope}): improve {item_name} - {brief_description}"
+
+        return f"""{title}
+
+{detailed_changes}
+
+🤖 Generated with Claude MPM
+"""

claude_mpm/services/profile_manager.py

@@ -0,0 +1,331 @@
+"""
+Profile Manager Service
+======================
+
+Manages agent and skill filtering based on deployment profiles.
+
+A profile defines which agents and skills should be deployed, reducing
+context usage by limiting available agents to only what's needed for
+a specific project or workflow.
+
+Profile Structure:
+    profile:
+      name: framework-development
+      description: Python backend + TypeScript/Svelte dashboard
+
+    agents:
+      enabled:
+        - python-engineer
+        - typescript-engineer
+      disabled:
+        - java-engineer
+        - dart-engineer
+
+    skills:
+      enabled:
+        - flask
+        - pytest
+      disabled_categories:
+        - wordpress-*
+        - react-*
+
+Usage:
+    # Auto-detect project directory (searches for .claude-mpm in cwd and parents)
+    profile_manager = ProfileManager()
+
+    # Or explicitly specify project directory
+    profile_manager = ProfileManager(project_dir=Path("/path/to/project"))
+
+    profile_manager.load_profile("framework-development")
+
+    if profile_manager.is_agent_enabled("python-engineer"):
+        # Deploy agent
+        pass
+
+    if profile_manager.is_skill_enabled("flask"):
+        # Deploy skill
+        pass
+"""
+
+import fnmatch
+from pathlib import Path
+from typing import Optional, Set, Dict, Any
+
+import yaml
+
+from ..core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ProfileManager:
+    """
+    Manages deployment profiles for agent and skill filtering.
+
+    Provides methods to:
+    - Load profiles from YAML files
+    - Check if agents are enabled/disabled
+    - Check if skills are enabled/disabled (with glob pattern support)
+    - Get lists of enabled/disabled entities
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None, profiles_dir: Optional[Path] = None):
+        """
+        Initialize ProfileManager.
+
+        Args:
+            project_dir: Project root directory. If not provided, tries to find
+                         .claude-mpm directory in current or parent directories.
+            profiles_dir: Directory containing profile YAML files. If provided,
+                         takes precedence over project_dir.
+        """
+        if profiles_dir:
+            self.profiles_dir = profiles_dir
+        elif project_dir:
+            self.profiles_dir = Path(project_dir) / ".claude-mpm" / "profiles"
+        else:
+            # Try to find .claude-mpm directory automatically
+            self.profiles_dir = self._find_profiles_dir()
+
+        self.active_profile: Optional[str] = None
+        self._profile_data: Dict[str, Any] = {}
+
+        # Cached sets for performance
+        self._enabled_agents: Set[str] = set()
+        self._disabled_agents: Set[str] = set()
+        self._enabled_skills: Set[str] = set()
+        self._disabled_skill_patterns: list[str] = []
+
+    def _find_profiles_dir(self) -> Path:
+        """Find profiles directory by searching for .claude-mpm in cwd and parents.
+
+        Returns:
+            Path to profiles directory (may not exist yet)
+        """
+        current = Path.cwd()
+
+        # Search current directory and up to 5 parent directories
+        for _ in range(6):
+            profiles_dir = current / ".claude-mpm" / "profiles"
+            if profiles_dir.exists():
+                logger.debug(f"Found profiles directory at: {profiles_dir}")
+                return profiles_dir
+            if current.parent == current:  # Reached filesystem root
+                break
+            current = current.parent
+
+        # Fallback to cwd (directory may not exist yet, which is fine)
+        fallback = Path.cwd() / ".claude-mpm" / "profiles"
+        logger.debug(f"Profiles directory not found, using fallback: {fallback}")
+        return fallback
+
+    def load_profile(self, profile_name: str) -> bool:
+        """
+        Load profile from YAML file.
+
+        Args:
+            profile_name: Name of profile (without .yaml extension)
+
+        Returns:
+            bool: True if profile loaded successfully, False otherwise
+        """
+        profile_path = self.profiles_dir / f"{profile_name}.yaml"
+
+        logger.debug(f"Looking for profile at: {profile_path}")
+
+        if not profile_path.exists():
+            logger.warning(f"Profile not found: {profile_path}")
+            return False
+
+        try:
+            with profile_path.open("r") as f:
+                self._profile_data = yaml.safe_load(f) or {}
+
+            # Extract profile metadata
+            profile_info = self._profile_data.get("profile", {})
+            self.active_profile = profile_info.get("name", profile_name)
+
+            # Parse agents
+            agents_config = self._profile_data.get("agents", {})
+            self._enabled_agents = set(agents_config.get("enabled", []))
+            self._disabled_agents = set(agents_config.get("disabled", []))
+
+            # Parse skills
+            skills_config = self._profile_data.get("skills", {})
+            self._enabled_skills = set(skills_config.get("enabled", []))
+            self._disabled_skill_patterns = skills_config.get("disabled_categories", [])
+
+            logger.info(
+                f"Loaded profile '{self.active_profile}': "
+                f"{len(self._enabled_agents)} agents, "
+                f"{len(self._enabled_skills)} skills enabled"
+            )
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load profile {profile_name}: {e}")
+            return False
+
+    def is_agent_enabled(self, agent_name: str) -> bool:
+        """
+        Check if agent is enabled in active profile.
+
+        If no profile is loaded, all agents are enabled by default.
+
+        Args:
+            agent_name: Name of agent to check
+
+        Returns:
+            bool: True if agent should be deployed
+        """
+        if not self.active_profile:
+            # No profile active - all agents enabled
+            return True
+
+        # If enabled list exists, agent must be in it
+        if self._enabled_agents:
+            return agent_name in self._enabled_agents
+
+        # Otherwise, agent must NOT be in disabled list
+        return agent_name not in self._disabled_agents
+
+    def is_skill_enabled(self, skill_name: str) -> bool:
+        """
+        Check if skill is enabled in active profile.
+
+        Supports both short names (flask) and full names (toolchains-python-frameworks-flask).
+        Supports glob pattern matching for disabled_categories.
+
+        If no profile is loaded, all skills are enabled by default.
+
+        Args:
+            skill_name: Name of skill to check (e.g., "flask", "toolchains-python-frameworks-flask")
+
+        Returns:
+            bool: True if skill should be deployed
+        """
+        if not self.active_profile:
+            # No profile active - all skills enabled
+            return True
+
+        # Check if skill is explicitly disabled by pattern
+        for pattern in self._disabled_skill_patterns:
+            if fnmatch.fnmatch(skill_name, pattern):
+                logger.debug(f"Skill '{skill_name}' matched disabled pattern '{pattern}'")
+                return False
+
+        # If enabled list exists, check for match
+        if self._enabled_skills:
+            # Exact match
+            if skill_name in self._enabled_skills:
+                return True
+
+            # Check if full skill name ends with short name from enabled list
+            # Example: "toolchains-python-frameworks-flask" matches "flask"
+            for short_name in self._enabled_skills:
+                if skill_name.endswith(f"-{short_name}"):
+                    return True
+                # Also check if short name is contained as a segment
+                if f"-{short_name}-" in skill_name or skill_name.startswith(f"{short_name}-"):
+                    return True
+
+            return False
+
+        # No enabled list and didn't match disabled pattern - allow it
+        return True
+
+    def get_enabled_agents(self) -> Set[str]:
+        """
+        Get set of enabled agent names.
+
+        Returns:
+            Set[str]: Agent names that should be deployed
+        """
+        return self._enabled_agents.copy()
+
+    def get_disabled_agents(self) -> Set[str]:
+        """
+        Get set of disabled agent names.
+
+        Returns:
+            Set[str]: Agent names that should NOT be deployed
+        """
+        return self._disabled_agents.copy()
+
+    def get_enabled_skills(self) -> Set[str]:
+        """
+        Get set of explicitly enabled skill names.
+
+        Returns:
+            Set[str]: Skill names that should be deployed
+        """
+        return self._enabled_skills.copy()
+
+    def get_disabled_skill_patterns(self) -> list[str]:
+        """
+        Get list of disabled skill glob patterns.
+
+        Returns:
+            list[str]: Glob patterns for skills that should NOT be deployed
+        """
+        return self._disabled_skill_patterns.copy()
+
+    def get_filtering_summary(self) -> Dict[str, Any]:
+        """
+        Get summary of current profile filtering.
+
+        Returns:
+            Dict containing:
+            - active_profile: Name of active profile (or None)
+            - enabled_agents_count: Number of explicitly enabled agents
+            - disabled_agents_count: Number of explicitly disabled agents
+            - enabled_skills_count: Number of explicitly enabled skills
+            - disabled_patterns_count: Number of disabled skill patterns
+        """
+        return {
+            "active_profile": self.active_profile,
+            "enabled_agents_count": len(self._enabled_agents),
+            "disabled_agents_count": len(self._disabled_agents),
+            "enabled_skills_count": len(self._enabled_skills),
+            "disabled_patterns_count": len(self._disabled_skill_patterns),
+        }
+
+    def list_available_profiles(self) -> list[str]:
+        """
+        List all available profile names in profiles directory.
+
+        Returns:
+            list[str]: Profile names (without .yaml extension)
+        """
+        if not self.profiles_dir.exists():
+            return []
+
+        profiles = []
+        for profile_path in self.profiles_dir.glob("*.yaml"):
+            profiles.append(profile_path.stem)
+
+        return sorted(profiles)
+
+    def get_profile_description(self, profile_name: str) -> Optional[str]:
+        """
+        Get description of a profile without loading it fully.
+
+        Args:
+            profile_name: Name of profile
+
+        Returns:
+            Optional[str]: Profile description or None if not found
+        """
+        profile_path = self.profiles_dir / f"{profile_name}.yaml"
+
+        if not profile_path.exists():
+            return None
+
+        try:
+            with profile_path.open("r") as f:
+                data = yaml.safe_load(f) or {}
+                profile_info = data.get("profile", {})
+                return profile_info.get("description")
+        except Exception:
+            return None

claude_mpm/services/project/documentation_manager.py

@@ -369,7 +369,8 @@ class DocumentationManager:
         sorted_sections = sorted(
             sections.items(),
             key=lambda x: self.SECTION_PRIORITY.get(
-                self._get_section_key(x[0]), 50  # Default priority
+                self._get_section_key(x[0]),
+                50,  # Default priority
             ),
             reverse=True,  # Higher priority first
         )

claude_mpm/services/project/project_organizer.py

@@ -58,6 +58,10 @@ class ProjectOrganizer:
         ".mcp-vector-search/",
         ".kuzu-memory/",
         "kuzu-memories/",  # kuzu-memory database directory
+        # User-specific config files (should NOT be committed)
+        ".mcp.json",
+        ".claude.json",
+        ".claude/",
         # Python artifacts
         "__pycache__/",
         "*.py[cod]",

claude_mpm/services/project/toolchain_analyzer.py

@@ -318,7 +318,9 @@ class ToolchainAnalyzerService(BaseService, IToolchainAnalyzer):
                     else (
                         3
                         if f.confidence == ConfidenceLevel.MEDIUM
-                        else 2 if f.confidence == ConfidenceLevel.LOW else 1
+                        else 2
+                        if f.confidence == ConfidenceLevel.LOW
+                        else 1
                     )
                 ),
                 f.popularity_score,