claude-mpm 4.21.3__py3-none-any.whl → 5.1.9__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/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,

claude_mpm/services/runner_configuration_service.py

@@ -10,10 +10,14 @@ This service handles:
 5. Hook service registration
 
 Extracted from ClaudeRunner to follow Single Responsibility Principle.
+
+DEPENDENCY INJECTION:
+This service uses protocol-based dependency injection to avoid circular imports
+when registering the SessionManagementService.
 """
 
 import os
-from typing import Any, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
 
 from claude_mpm.core.base_service import BaseService
 from claude_mpm.core.config import Config
@@ -22,6 +26,13 @@ from claude_mpm.core.logger import get_project_logger
 from claude_mpm.core.shared.config_loader import ConfigLoader
 from claude_mpm.services.core.interfaces import RunnerConfigurationInterface
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class RunnerConfigurationService(BaseService, RunnerConfigurationInterface):
     """Service for configuring and initializing ClaudeRunner components."""
@@ -168,6 +179,7 @@ class RunnerConfigurationService(BaseService, RunnerConfigurationInterface):
             "launch_method": kwargs.get("launch_method", "exec"),
             "enable_websocket": kwargs.get("enable_websocket", False),
             "websocket_port": kwargs.get("websocket_port", 8765),
+            "use_native_agents": kwargs.get("use_native_agents", False),
         }
 
         # Initialize main configuration using ConfigLoader
@@ -494,12 +506,14 @@ class RunnerConfigurationService(BaseService, RunnerConfigurationInterface):
             )
             return None
 
-    def register_session_management_service(self, container, runner):
+    def register_session_management_service(
+        self, container, runner: "ClaudeRunnerProtocol"
+    ):
         """Register session management service in the DI container.
 
         Args:
             container: DI container instance
-            runner: ClaudeRunner instance dependency
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
 
         Returns:
             Initialized session management service or None if failed

claude_mpm/services/self_upgrade_service.py

@@ -4,9 +4,11 @@ Self-Upgrade Service
 
 Handles version checking and self-upgrade functionality for claude-mpm.
 Supports pip, pipx, and npm installations with automatic detection.
+Also checks Claude Code version compatibility.
 
 WHY: Users should be notified of updates and have an easy way to upgrade
-without manually running installation commands.
+without manually running installation commands. Claude Code version checking
+ensures compatibility with required features.
 
 DESIGN DECISIONS:
 - Detects installation method (pip/pipx/npm/editable)
@@ -14,9 +16,11 @@ DESIGN DECISIONS:
 - Interactive upgrade prompts with confirmation
 - Automatic restart after upgrade
 - Graceful failure handling (never breaks existing installation)
+- Claude Code version detection and compatibility checking
 """
 
 import os
+import re
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -47,17 +51,23 @@ class SelfUpgradeService:
     Capabilities:
     - Detect current installation method
     - Check PyPI/npm for latest version
+    - Check Claude Code version and compatibility
     - Prompt user for upgrade confirmation
     - Execute upgrade command
     - Restart after upgrade
     """
 
+    # Claude Code version requirements
+    CLAUDE_CODE_MIN_VERSION = "1.0.92"
+    CLAUDE_CODE_RECOMMENDED_VERSION = "2.0.30"
+
     def __init__(self):
         """Initialize the self-upgrade service."""
         self.logger = get_logger("SelfUpgradeService")
         self.version_checker = PackageVersionChecker()
         self.current_version = self._get_current_version()
         self.installation_method = self._detect_installation_method()
+        self.claude_code_version = self._get_claude_code_version()
 
     def _get_current_version(self) -> str:
         """
@@ -117,6 +127,109 @@ class SelfUpgradeService:
         # Default to pip
         return InstallationMethod.PIP
 
+    def _get_claude_code_version(self) -> Optional[str]:
+        """
+        Get the installed Claude Code version.
+
+        Returns:
+            Version string (e.g., "2.0.30") or None if not installed
+        """
+        try:
+            # Try to get Claude Code version via CLI
+            result = subprocess.run(
+                ["claude", "--version"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                # Parse version from output
+                # Expected format: "Claude Code 2.0.30" or similar
+                match = re.search(r"(\d+\.\d+\.\d+)", result.stdout)
+                if match:
+                    return match.group(1)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            # Claude Code not installed or command not found
+            pass
+        except Exception as e:
+            self.logger.debug(f"Failed to detect Claude Code version: {e}")
+
+        return None
+
+    def check_claude_code_compatibility(self) -> Dict[str, any]:
+        """
+        Check Claude Code version compatibility.
+
+        Returns:
+            Dict with compatibility information:
+            {
+                "installed": bool,
+                "version": str or None,
+                "meets_minimum": bool,
+                "is_recommended": bool,
+                "status": str,
+                "message": str
+            }
+        """
+        if not self.claude_code_version:
+            return {
+                "installed": False,
+                "version": None,
+                "meets_minimum": False,
+                "is_recommended": False,
+                "status": "not_installed",
+                "message": (
+                    "Claude Code is not installed or not in PATH.\n"
+                    "   Install from: https://docs.anthropic.com/en/docs/claude-code"
+                ),
+            }
+
+        try:
+            current = version.parse(self.claude_code_version)
+            minimum = version.parse(self.CLAUDE_CODE_MIN_VERSION)
+            recommended = version.parse(self.CLAUDE_CODE_RECOMMENDED_VERSION)
+
+            meets_minimum = current >= minimum
+            is_recommended = current >= recommended
+
+            if is_recommended:
+                status = "optimal"
+                message = f"Claude Code v{self.claude_code_version} (optimal version)"
+            elif meets_minimum:
+                status = "compatible"
+                message = (
+                    f"Claude Code v{self.claude_code_version} is compatible\n"
+                    f"   Recommended: Upgrade to v{self.CLAUDE_CODE_RECOMMENDED_VERSION}+ for best experience"
+                )
+            else:
+                status = "outdated"
+                message = (
+                    f"Claude Code v{self.claude_code_version} is outdated\n"
+                    f"   Minimum required: v{self.CLAUDE_CODE_MIN_VERSION}\n"
+                    f"   Recommended: v{self.CLAUDE_CODE_RECOMMENDED_VERSION}+"
+                )
+
+            return {
+                "installed": True,
+                "version": self.claude_code_version,
+                "meets_minimum": meets_minimum,
+                "is_recommended": is_recommended,
+                "status": status,
+                "message": message,
+            }
+
+        except Exception as e:
+            self.logger.debug(f"Version comparison failed: {e}")
+            return {
+                "installed": True,
+                "version": self.claude_code_version,
+                "meets_minimum": False,
+                "is_recommended": False,
+                "status": "unknown",
+                "message": f"Unable to verify Claude Code version: {e}",
+            }
+
     async def check_for_update(
         self, cache_ttl: Optional[int] = None
     ) -> Optional[Dict[str, any]]:
@@ -212,7 +325,7 @@ class SelfUpgradeService:
 
     def prompt_for_upgrade(self, update_info: Dict[str, any]) -> bool:
         """
-        Prompt user to upgrade.
+        Prompt user to upgrade with enhanced formatting.
 
         Args:
             update_info: Update information dict
@@ -224,11 +337,19 @@ class SelfUpgradeService:
         latest = update_info["latest"]
         method = update_info.get("installation_method", "unknown")
 
-        print("\n🎉 New version available!")
+        # Enhanced notification with release notes link
+        print("\n" + "=" * 70)
+        print("📢 Update Available for claude-mpm")
+        print("=" * 70)
         print(f"   Current: v{current}")
         print(f"   Latest:  v{latest}")
-        print(f"   Installation method: {method}")
-        print(f"\nTo upgrade, run: {update_info['upgrade_command']}")
+        print(f"   Method:  {method}")
+        print()
+        print(f"   Upgrade: {update_info['upgrade_command']}")
+        print(
+            f"   Release: https://github.com/bobmatnyc/claude-mpm/releases/tag/v{latest}"
+        )
+        print("=" * 70)
 
         try:
             response = input("\nWould you like to upgrade now? [y/N]: ").strip().lower()
@@ -237,6 +358,24 @@ class SelfUpgradeService:
             print("\n")
             return False
 
+    def display_update_notification(self, update_info: Dict[str, any]) -> None:
+        """
+        Display a non-interactive update notification.
+
+        Args:
+            update_info: Update information dict
+        """
+        current = update_info["current"]
+        latest = update_info["latest"]
+        command = update_info.get("upgrade_command", "pip install --upgrade claude-mpm")
+
+        print(f"\nℹ️  Update available: v{current} → v{latest}")
+        print(f"   Run: {command}")
+        print(
+            f"   Release notes: https://github.com/bobmatnyc/claude-mpm/releases/tag/v{latest}"
+        )
+        print()
+
     def perform_upgrade(self, update_info: Dict[str, any]) -> Tuple[bool, str]:
         """
         Perform the upgrade.
@@ -309,13 +448,15 @@ class SelfUpgradeService:
             print("Please restart claude-mpm manually.")
 
     async def check_and_prompt_on_startup(
-        self, auto_upgrade: bool = False
+        self, auto_upgrade: bool = False, check_claude_code: bool = True
     ) -> Optional[Dict[str, any]]:
         """
         Check for updates on startup and optionally prompt user.
+        Also checks Claude Code version compatibility.
 
         Args:
             auto_upgrade: If True, upgrade without prompting (use with caution)
+            check_claude_code: If True, also check Claude Code compatibility
 
         Returns:
             Update info if available, None otherwise
@@ -325,14 +466,31 @@ class SelfUpgradeService:
             return None
 
         try:
+            # Check Claude Code compatibility first
+            if check_claude_code:
+                claude_compat = self.check_claude_code_compatibility()
+                if not claude_compat["installed"]:
+                    print("\n⚠️  Claude Code Not Detected")
+                    print("   " + claude_compat["message"])
+                elif claude_compat["status"] == "outdated":
+                    print("\n⚠️  Claude Code Outdated")
+                    print("   " + claude_compat["message"].replace("\n", "\n   "))
+                elif claude_compat["status"] == "compatible":
+                    # Only show if verbose or debug
+                    self.logger.debug(claude_compat["message"])
+
+            # Check for claude-mpm updates
             update_info = await self.check_for_update()
 
             if update_info and update_info.get("update_available"):
-                if auto_upgrade or self.prompt_for_upgrade(update_info):
+                if auto_upgrade:
                     success, message = self.perform_upgrade(update_info)
                     print(message)
                     if success:
                         self.restart_after_upgrade()
+                else:
+                    # Just display notification, don't prompt during startup
+                    self.display_update_notification(update_info)
 
                 return update_info