claude-mpm 5.4.36__py3-none-any.whl → 5.4.62__py3-none-any.whl

claude_mpm/services/profile_manager.py

@@ -0,0 +1,337 @@
+"""
+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 Any, Dict, Optional, Set
+
+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/skills/git_skill_source_manager.py

@@ -991,12 +991,17 @@ class GitSkillSourceManager:
         progress_callback=None,
         skill_filter: Optional[Set[str]] = None,
     ) -> Dict[str, Any]:
-        """Deploy skills from cache to target directory with flat structure.
+        """Deploy skills from cache to target directory with flat structure and automatic cleanup.
 
         Flattens nested Git repository structure into Claude Code compatible
         flat directory structure. Each skill directory is copied with a
         hyphen-separated name derived from its path.
 
+        CRITICAL: When skill_filter is provided (agent-referenced skills), this function:
+        1. Deploys ONLY the filtered skills
+        2. REMOVES orphaned skills (deployed but not in filter)
+        3. Returns removed_count and removed_skills in result
+
         Transformation Example:
             Cache: collaboration/dispatching-parallel-agents/SKILL.md
             Deploy: collaboration-dispatching-parallel-agents/SKILL.md
@@ -1006,8 +1011,8 @@ class GitSkillSourceManager:
             force: Overwrite existing skills
             progress_callback: Optional callback(increment: int) called for each skill deployed
             skill_filter: Optional set of skill names to deploy (selective deployment).
-                         If None, deploys all skills. If provided, only deploys skills
-                         whose name matches an entry in the filter set.
+                         If None, deploys ALL skills WITHOUT cleanup.
+                         If provided, deploys ONLY filtered skills AND removes orphans.
 
         Returns:
             Dict with deployment results:
@@ -1018,7 +1023,9 @@ class GitSkillSourceManager:
                 "deployed_skills": List[str],
                 "skipped_skills": List[str],
                 "errors": List[str],
-                "filtered_count": int  # Number of skills filtered out
+                "filtered_count": int,  # Number of skills filtered out
+                "removed_count": int,   # Number of orphaned skills removed
+                "removed_skills": List[str]  # Names of removed orphaned skills
             }
 
         Example:
@@ -1026,10 +1033,10 @@ class GitSkillSourceManager:
             >>> result = manager.deploy_skills()
             >>> print(f"Deployed {result['deployed_count']} skills")
 
-            # Selective deployment based on agent requirements:
+            # Selective deployment based on agent requirements (with cleanup):
             >>> required = {"typescript-core", "react-patterns"}
             >>> result = manager.deploy_skills(skill_filter=required)
-            >>> print(f"Deployed {result['deployed_count']} of {len(required)} required skills")
+            >>> print(f"Deployed {result['deployed_count']}, removed {result['removed_count']} orphans")
         """
         if target_dir is None:
             target_dir = Path.home() / ".claude" / "skills"
@@ -1040,6 +1047,7 @@ class GitSkillSourceManager:
         skipped = []
         errors = []
         filtered_count = 0
+        removed_skills = []  # Track removed orphaned skills
 
         # Get all skills from all sources
         all_skills = self.get_all_skills()
@@ -1049,12 +1057,31 @@ class GitSkillSourceManager:
             original_count = len(all_skills)
             # Normalize filter to lowercase for case-insensitive matching
             normalized_filter = {s.lower() for s in skill_filter}
-            # Match against deployment_name (not display name) since skill_filter contains
-            # deployment-style names like "toolchains-python-frameworks-django"
+
+            def matches_filter(deployment_name: str) -> bool:
+                """Match using same fuzzy logic as ProfileManager.is_skill_enabled()"""
+                deployment_lower = deployment_name.lower()
+
+                # Exact match
+                if deployment_lower in normalized_filter:
+                    return True
+
+                # Fuzzy match: check if deployment name ends with or contains short name
+                # Example: "toolchains-python-frameworks-flask" matches "flask"
+                for short_name in normalized_filter:
+                    if deployment_lower.endswith(f"-{short_name}"):
+                        return True
+                    # Check if short name is contained as a segment
+                    if f"-{short_name}-" in deployment_lower:
+                        return True
+                    if deployment_lower.startswith(f"{short_name}-"):
+                        return True
+
+                return False
+
+            # Match against deployment_name using fuzzy matching
             all_skills = [
-                s
-                for s in all_skills
-                if s.get("deployment_name", "").lower() in normalized_filter
+                s for s in all_skills if matches_filter(s.get("deployment_name", ""))
             ]
             filtered_count = original_count - len(all_skills)
             self.logger.info(
@@ -1062,6 +1089,15 @@ class GitSkillSourceManager:
                 f"match agent requirements ({filtered_count} filtered out)"
             )
 
+            # Cleanup: Remove skills from target directory that aren't in the filtered set
+            # This ensures only agent-referenced skills remain deployed
+            removed_skills = self._cleanup_unfiltered_skills(target_dir, all_skills)
+            if removed_skills:
+                self.logger.info(
+                    f"Removed {len(removed_skills)} orphaned skills not referenced by agents: {removed_skills[:10]}"
+                    + (f" (and {len(removed_skills) - 10} more)" if len(removed_skills) > 10 else "")
+                )
+
         self.logger.info(
             f"Deploying {len(all_skills)} skills to {target_dir} (force={force})"
         )
@@ -1103,6 +1139,7 @@ class GitSkillSourceManager:
         self.logger.info(
             f"Deployment complete: {len(deployed)} deployed, "
             f"{len(skipped)} skipped, {len(errors)} errors"
+            + (f", {len(removed_skills)} removed" if removed_skills else "")
         )
 
         return {
@@ -1113,8 +1150,108 @@ class GitSkillSourceManager:
             "skipped_skills": skipped,
             "errors": errors,
             "filtered_count": filtered_count,
+            "removed_count": len(removed_skills),
+            "removed_skills": removed_skills,
         }
 
+    def _cleanup_unfiltered_skills(
+        self, target_dir: Path, filtered_skills: List[Dict[str, Any]]
+    ) -> List[str]:
+        """Remove skills from target directory that aren't in the filtered skill list.
+
+        Uses fuzzy matching to handle both exact deployment names and short skill names.
+        For example:
+        - "toolchains-python-frameworks-flask" (deployed dir) matches "flask" (filter)
+        - "toolchains-elixir-frameworks-phoenix-liveview" matches "phoenix-liveview"
+
+        Args:
+            target_dir: Target deployment directory
+            filtered_skills: List of skills that should remain deployed
+
+        Returns:
+            List of skill names that were removed
+        """
+        import shutil
+
+        removed_skills = []
+
+        # Build set of deployment names (exact matches)
+        expected_deployments = {
+            skill.get("deployment_name").lower()
+            for skill in filtered_skills
+            if skill.get("deployment_name")
+        }
+
+        # Build helper function for fuzzy matching (matches logic from deploy_skills)
+        def should_keep_skill(deployed_dir_name: str) -> bool:
+            """Check if deployed skill matches any expected deployment using fuzzy matching.
+
+            Matches the same logic as matches_filter() in deploy_skills() at line 1053.
+            """
+            deployed_lower = deployed_dir_name.lower()
+
+            # Exact match
+            if deployed_lower in expected_deployments:
+                return True
+
+            # Fuzzy match: check if deployment name matches any short name pattern
+            # Example: "toolchains-elixir-frameworks-phoenix-liveview" matches "phoenix-liveview"
+            for expected_name in expected_deployments:
+                # Suffix match: deployment ends with "-shortname"
+                if deployed_lower.endswith(f"-{expected_name}"):
+                    return True
+                # Segment match: "-shortname-" appears in deployment
+                if f"-{expected_name}-" in deployed_lower:
+                    return True
+                # Prefix match: deployment starts with "shortname-"
+                if deployed_lower.startswith(f"{expected_name}-"):
+                    return True
+
+            return False
+
+        # Check each directory in target_dir
+        if not target_dir.exists():
+            return removed_skills
+
+        try:
+            for item in target_dir.iterdir():
+                # Skip files, only process directories
+                if not item.is_dir():
+                    continue
+
+                # Skip hidden directories
+                if item.name.startswith("."):
+                    continue
+
+                # Check if this skill directory should be kept (fuzzy matching)
+                if not should_keep_skill(item.name):
+                    try:
+                        # Security: Validate path is within target_dir
+                        if not self._validate_safe_path(target_dir, item):
+                            self.logger.error(
+                                f"Refusing to remove path outside target directory: {item}"
+                            )
+                            continue
+
+                        # Remove the skill directory
+                        if item.is_symlink():
+                            item.unlink()
+                        else:
+                            shutil.rmtree(item)
+
+                        removed_skills.append(item.name)
+                        self.logger.info(f"Removed orphaned skill: {item.name}")
+
+                    except Exception as e:
+                        self.logger.warning(
+                            f"Failed to remove skill directory {item.name}: {e}"
+                        )
+
+        except Exception as e:
+            self.logger.error(f"Error during skill cleanup: {e}")
+
+        return removed_skills
+
     def _deploy_single_skill(
         self, skill: Dict[str, Any], target_dir: Path, deployment_name: str, force: bool
     ) -> Dict[str, Any]: