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

claude_mpm/utils/agent_filters.py

@@ -0,0 +1,288 @@
+"""
+Agent filtering utilities for claude-mpm.
+
+WHY: This module provides centralized filtering logic to remove non-deployable
+agents (BASE_AGENT) and already-deployed agents from user-facing displays.
+
+DESIGN DECISIONS:
+- BASE_AGENT is a build tool, not a deployable agent - filter everywhere
+- Deployed agent detection supports both new (.claude-mpm/agents/) and
+  legacy (.claude/agents/)
+- Case-insensitive BASE_AGENT detection for robustness
+- Pure functions for easy testing and reuse
+
+IMPLEMENTATION NOTES:
+- Related to ticket 1M-502 Phase 1: UX improvements for agent filtering
+- Addresses user confusion from seeing BASE_AGENT and deployed agents in lists
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+
+def is_base_agent(agent_id: str) -> bool:
+    """Check if agent is BASE_AGENT (build tool, not deployable).
+
+    BASE_AGENT is an internal build tool used to construct other agents.
+    It should never appear in user-facing agent lists or deployment menus.
+
+    Args:
+        agent_id: Agent identifier to check (may include path like "qa/BASE-AGENT")
+
+    Returns:
+        True if agent is BASE_AGENT (case-insensitive), False otherwise
+
+    Examples:
+        >>> is_base_agent("BASE_AGENT")
+        True
+        >>> is_base_agent("base-agent")
+        True
+        >>> is_base_agent("qa/BASE-AGENT")
+        True
+        >>> is_base_agent("ENGINEER")
+        False
+    """
+    if not agent_id:
+        return False
+
+    # Extract filename from path (handle cases like "qa/BASE-AGENT")
+    # 1M-502: Remote agents may have path prefixes like "qa/", "pm/", etc.
+    agent_name = agent_id.split("/")[-1]
+
+    normalized_id = agent_name.lower().replace("-", "").replace("_", "")
+    return normalized_id == "baseagent"
+
+
+def filter_base_agents(agents: List[Dict]) -> List[Dict]:
+    """Remove BASE_AGENT from agent list.
+
+    Filters out any agent with agent_id matching BASE_AGENT (case-insensitive).
+    This prevents users from seeing or selecting the internal build tool.
+
+    Args:
+        agents: List of agent dictionaries, each containing at least 'agent_id' key
+
+    Returns:
+        Filtered list with BASE_AGENT removed
+
+    Examples:
+        >>> agents = [
+        ...     {"agent_id": "ENGINEER", "name": "Engineer"},
+        ...     {"agent_id": "BASE_AGENT", "name": "Base Agent"},
+        ...     {"agent_id": "PM", "name": "PM"}
+        ... ]
+        >>> filtered = filter_base_agents(agents)
+        >>> len(filtered)
+        2
+        >>> "BASE_AGENT" in [a["agent_id"] for a in filtered]
+        False
+    """
+    return [a for a in agents if not is_base_agent(a.get("agent_id", ""))]
+
+
+def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
+    """Get set of currently deployed agent IDs.
+
+    Checks virtual deployment state (.mpm_deployment_state) first, then falls back
+    to physical .md files for backward compatibility. This ensures agents are detected
+    whether deployed virtually or as physical files.
+
+    Args:
+        project_dir: Project directory to check, defaults to current working directory
+
+    Returns:
+        Set of deployed agent IDs (leaf names like "python-engineer", "qa")
+
+    Examples:
+        >>> deployed = get_deployed_agent_ids()
+        >>> "python-engineer" in deployed  # If agent exists in deployment state
+        True
+        >>> "ENGINEER" in deployed  # If ENGINEER.md exists
+        True
+
+    Design Rationale:
+        - Primary detection: Virtual deployment state (.mpm_deployment_state)
+        - Fallback detection: Physical .md files (.claude-mpm/agents/, .claude/agents/)
+        - Returns leaf names for consistent comparison with agent_id formats
+        - Combines both detection methods for complete coverage
+        - Graceful error handling for malformed or missing state files
+
+    Related:
+        - Fixes checkbox interface showing all agents as "○ [Available]" instead of "● [Installed]"
+        - Matches detection logic from _is_agent_deployed() in agent_state_manager.py
+        - Related to ticket 1M-502: Virtual deployment state detection
+    """
+    deployed = set()
+
+    # Track if project_dir was explicitly provided
+    explicit_project_dir = project_dir is not None
+
+    if project_dir is None:
+        project_dir = Path.cwd()
+
+    # NEW: Check virtual deployment state (primary method)
+    # This is the current deployment model used by Claude Code
+    deployment_state_paths = [
+        project_dir / ".claude" / "agents" / ".mpm_deployment_state",
+    ]
+
+    # Only check user-level state if using default project directory
+    # This prevents test isolation issues when explicit project_dir is provided
+    if not explicit_project_dir:
+        deployment_state_paths.append(
+            Path.home() / ".claude" / "agents" / ".mpm_deployment_state"
+        )
+
+    for state_path in deployment_state_paths:
+        if state_path.exists():
+            try:
+                import json
+
+                with state_path.open() as f:
+                    state = json.load(f)
+
+                # Extract agent IDs from deployment state
+                # Agent IDs are leaf names (e.g., "python-engineer", "qa")
+                agents = state.get("last_check_results", {}).get("agents", {})
+                deployed.update(agents.keys())
+
+            except (json.JSONDecodeError, KeyError) as e:
+                # Log error but continue - don't break if state file is malformed
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.debug(f"Failed to read deployment state from {state_path}: {e}")
+                continue
+            except Exception as e:
+                # Catch unexpected errors - fail gracefully
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.debug(f"Unexpected error reading deployment state: {e}")
+                continue
+
+    # EXISTING: Check physical .md files (fallback for backward compatibility)
+    # Check new architecture
+    new_agents_dir = project_dir / ".claude-mpm" / "agents"
+    if new_agents_dir.exists():
+        for file in new_agents_dir.glob("*.md"):
+            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                deployed.add(file.stem)
+
+    # Check legacy architecture
+    legacy_agents_dir = project_dir / ".claude" / "agents"
+    if legacy_agents_dir.exists():
+        for file in legacy_agents_dir.glob("*.md"):
+            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                deployed.add(file.stem)
+
+    # Check .claude/templates/ directory (where agents are actually deployed)
+    templates_dir = project_dir / ".claude" / "templates"
+    if templates_dir.exists():
+        for file in templates_dir.glob("*.md"):
+            if file.stem not in {
+                "BASE-AGENT",
+                ".DS_Store",
+                "README",
+                "circuit-breakers",
+            }:
+                # Skip template/example files
+                if not any(x in file.stem for x in ["example", "template", "pm-"]):
+                    deployed.add(file.stem)
+
+    # Check user-level directory only if using default project directory
+    # This prevents test isolation issues when explicit project_dir is provided
+    if not explicit_project_dir:
+        user_agents_dir = Path.home() / ".claude" / "agents"
+        if user_agents_dir.exists():
+            for file in user_agents_dir.glob("*.md"):
+                if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                    deployed.add(file.stem)
+
+    return deployed
+
+
+def filter_deployed_agents(
+    agents: List[Dict], project_dir: Optional[Path] = None
+) -> List[Dict]:
+    """Remove already-deployed agents from list.
+
+    Filters agent list to show only agents that are not currently deployed.
+    This prevents users from attempting to re-deploy existing agents and
+    reduces confusion in deployment menus.
+
+    Args:
+        agents: List of agent dictionaries, each containing at least 'agent_id' key
+        project_dir: Project directory to check, defaults to current working directory
+
+    Returns:
+        Filtered list containing only non-deployed agents
+
+    Examples:
+        >>> agents = [
+        ...     {"agent_id": "ENGINEER", "name": "Engineer"},
+        ...     {"agent_id": "PM", "name": "PM"},
+        ...     {"agent_id": "QA", "name": "QA"}
+        ... ]
+        >>> # Assuming ENGINEER is deployed
+        >>> filtered = filter_deployed_agents(agents)
+        >>> "ENGINEER" not in [a["agent_id"] for a in filtered]
+        True
+
+    Design Rationale:
+        - Checks filesystem for actual deployed files (source of truth)
+        - Supports both new and legacy agent directory structures
+        - Preserves agent order for consistent UX
+    """
+    deployed_ids = get_deployed_agent_ids(project_dir)
+    return [a for a in agents if a.get("agent_id") not in deployed_ids]
+
+
+def apply_all_filters(
+    agents: List[Dict],
+    project_dir: Optional[Path] = None,
+    filter_base: bool = True,
+    filter_deployed: bool = False,
+) -> List[Dict]:
+    """Apply multiple filters to agent list in correct order.
+
+    Convenience function to apply common filtering combinations. Filters are
+    applied in this order:
+    1. BASE_AGENT filtering (if enabled)
+    2. Deployed agent filtering (if enabled)
+
+    Args:
+        agents: List of agent dictionaries to filter
+        project_dir: Project directory for deployment checks
+        filter_base: Remove BASE_AGENT from list (default: True)
+        filter_deployed: Remove deployed agents from list (default: False)
+
+    Returns:
+        Filtered agent list
+
+    Examples:
+        >>> agents = get_all_agents()
+        >>> # For display/info purposes - remove only BASE_AGENT
+        >>> filtered = apply_all_filters(
+        ...     agents, filter_base=True, filter_deployed=False
+        ... )
+        >>> # For deployment menus - remove BASE_AGENT and deployed agents
+        >>> deployable = apply_all_filters(
+        ...     agents, filter_base=True, filter_deployed=True
+        ... )
+
+    Usage Guidelines:
+        - Use filter_base=True (default) for all user-facing displays
+        - Use filter_deployed=True when showing deployment options
+        - Use filter_deployed=False when showing all available agents
+          (info/list commands)
+    """
+    result = agents
+
+    if filter_base:
+        result = filter_base_agents(result)
+
+    if filter_deployed:
+        result = filter_deployed_agents(result, project_dir)
+
+    return result

claude_mpm/utils/dependency_cache.py

@@ -333,7 +333,9 @@ class SmartDependencyChecker:
         return True, "No valid cache, checking needed"
 
     def get_or_check_dependencies(
-        self, loader, force_check: bool = False  # AgentDependencyLoader instance
+        self,
+        loader,
+        force_check: bool = False,  # AgentDependencyLoader instance
     ) -> Tuple[Dict, bool]:
         """
         Get dependency results from cache or perform check.

claude_mpm/utils/gitignore.py

@@ -0,0 +1,241 @@
+"""GitIgnore management utilities.
+
+This module provides functionality to safely manage .gitignore entries,
+ensuring claude-mpm configuration directories are excluded from version control.
+
+Design Decisions:
+- In-memory set for duplicate detection (O(1) lookups)
+- Preserves existing file formatting and comments
+- Adds section headers for clarity
+- Handles edge cases (missing newlines, empty files, etc.)
+
+Trade-offs:
+- Simplicity: File append vs. full parse/rewrite (chosen append for safety)
+- Performance: Read entire file vs. streaming (file is small, simplicity wins)
+- Safety: Non-destructive append only, never modifies existing entries
+"""
+
+from pathlib import Path
+from typing import List, Set, Tuple
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class GitIgnoreManager:
+    """Manages .gitignore file updates safely and non-destructively.
+
+    Design Pattern: Builder pattern for fluent API
+    - Initialize with project directory
+    - Call ensure_entries() to add patterns
+    - Returns summary of changes made
+
+    Performance:
+    - Time Complexity: O(n) where n = existing .gitignore lines
+    - Space Complexity: O(n) for storing unique entries in set
+    - Expected Performance: <1ms for typical .gitignore files (<1000 lines)
+
+    Error Handling:
+    - FileNotFoundError: Creates new .gitignore if missing
+    - PermissionError: Propagated to caller for appropriate handling
+    - UnicodeDecodeError: Logged and treated as binary file (skip)
+    """
+
+    def __init__(self, project_dir: Path):
+        """Initialize with project directory.
+
+        Args:
+            project_dir: Path to project root (where .gitignore lives)
+        """
+        self.project_dir = Path(project_dir)
+        self.gitignore_path = self.project_dir / ".gitignore"
+
+    def ensure_entries(self, entries: List[str]) -> Tuple[List[str], List[str]]:
+        """Ensure specified entries exist in .gitignore.
+
+        Non-destructive operation that:
+        1. Reads existing entries (if file exists)
+        2. Identifies which entries are missing
+        3. Appends only missing entries with section header
+        4. Preserves all existing content and formatting
+
+        Args:
+            entries: List of gitignore patterns to add (e.g., [".claude-mpm/"])
+
+        Returns:
+            Tuple of (added_entries, existing_entries)
+            - added_entries: Patterns that were added to .gitignore
+            - existing_entries: Patterns that were already present
+
+        Example:
+            >>> manager = GitIgnoreManager(Path("."))
+            >>> added, existing = manager.ensure_entries([".claude-mpm/"])
+            >>> print(f"Added: {added}, Already present: {existing}")
+            Added: ['.claude-mpm/'], Already present: []
+        """
+        # Read existing entries
+        existing = self._read_existing_entries()
+
+        # Determine what needs to be added
+        to_add = [e for e in entries if e not in existing]
+        already_present = [e for e in entries if e in existing]
+
+        if to_add:
+            self._append_entries(to_add)
+            logger.info(f"Added {len(to_add)} entries to .gitignore: {to_add}")
+
+        if already_present:
+            logger.debug(f"Entries already in .gitignore: {already_present}")
+
+        return to_add, already_present
+
+    def _read_existing_entries(self) -> Set[str]:
+        """Read existing .gitignore entries.
+
+        Parses .gitignore file and extracts all non-comment, non-blank patterns.
+        Handles edge cases:
+        - File doesn't exist -> returns empty set
+        - File is binary -> logs warning, returns empty set
+        - File has no newline at end -> handled correctly
+
+        Returns:
+            Set of existing gitignore patterns (stripped, normalized)
+        """
+        if not self.gitignore_path.exists():
+            logger.debug(".gitignore does not exist, will create new file")
+            return set()
+
+        try:
+            with open(self.gitignore_path, encoding="utf-8") as f:
+                # Strip whitespace and comments, filter blanks
+                entries = {
+                    line.strip()
+                    for line in f
+                    if line.strip() and not line.strip().startswith("#")
+                }
+
+            logger.debug(f"Found {len(entries)} existing entries in .gitignore")
+            return entries
+
+        except UnicodeDecodeError:
+            logger.warning(
+                f".gitignore appears to be binary, cannot parse: {self.gitignore_path}"
+            )
+            return set()
+        except Exception as e:
+            logger.error(f"Error reading .gitignore: {e}")
+            raise
+
+    def _append_entries(self, entries: List[str]) -> None:
+        """Append entries to .gitignore with proper formatting.
+
+        Handles formatting edge cases:
+        - Ensures blank line before new section (if file exists and isn't empty)
+        - Adds section header comment for clarity
+        - Ensures each entry on its own line
+        - Handles missing trailing newline in existing file
+
+        Args:
+            entries: List of patterns to append
+
+        Raises:
+            PermissionError: If cannot write to .gitignore
+            OSError: If disk is full or other I/O error
+        """
+        mode = "a" if self.gitignore_path.exists() else "w"
+
+        try:
+            with open(self.gitignore_path, mode, encoding="utf-8") as f:
+                # Add blank line before entries if file exists and isn't empty
+                if mode == "a" and self.gitignore_path.stat().st_size > 0:
+                    # Check if last line has newline
+                    with open(self.gitignore_path, "rb") as check:
+                        check.seek(-1, 2)  # Seek to last byte
+                        last_byte = check.read(1)
+                        if last_byte != b"\n":
+                            f.write("\n")
+
+                    f.write("\n# Claude MPM configuration\n")
+                else:
+                    # New file or empty file - add header without extra blank line
+                    f.write("# Claude MPM configuration\n")
+
+                for entry in entries:
+                    f.write(f"{entry}\n")
+
+            logger.info(f"Updated .gitignore at {self.gitignore_path}")
+
+        except PermissionError:
+            logger.error(
+                f"Permission denied writing to .gitignore: {self.gitignore_path}"
+            )
+            raise
+        except OSError as e:
+            logger.error(f"I/O error writing to .gitignore: {e}")
+            raise
+
+
+def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
+    """Ensure claude-mpm directories are in .gitignore.
+
+    Convenience function that wraps GitIgnoreManager to add standard
+    claude-mpm configuration directories to .gitignore.
+
+    Standard Entries Added:
+    - .claude-mpm/: Main configuration directory
+    - .claude/agents/: Agent runtime files
+
+    Args:
+        project_dir: Project directory path (default: current directory)
+
+    Returns:
+        Dictionary with operation results:
+        - added: List of patterns that were added
+        - existing: List of patterns that were already present
+        - gitignore_path: Path to the .gitignore file
+
+    Example:
+        >>> result = ensure_claude_mpm_gitignore()
+        >>> if result["added"]:
+        ...     print(f"Added {len(result['added'])} entries to .gitignore")
+
+    Error Handling:
+        - PermissionError: Returns error dict with status="error"
+        - FileNotFoundError on parent dir: Returns error dict
+        - All other exceptions: Propagated to caller
+    """
+    try:
+        manager = GitIgnoreManager(Path(project_dir))
+
+        # Standard claude-mpm entries
+        entries_to_add = [
+            ".claude-mpm/",
+            ".claude/agents/",
+        ]
+
+        added, existing = manager.ensure_entries(entries_to_add)
+
+        return {
+            "status": "success",
+            "added": added,
+            "existing": existing,
+            "gitignore_path": str(manager.gitignore_path),
+        }
+
+    except PermissionError as e:
+        logger.error(f"Permission denied updating .gitignore: {e}")
+        return {
+            "status": "error",
+            "error": f"Permission denied: {e}",
+            "added": [],
+            "existing": [],
+        }
+    except FileNotFoundError as e:
+        logger.error(f"Project directory not found: {e}")
+        return {
+            "status": "error",
+            "error": f"Directory not found: {e}",
+            "added": [],
+            "existing": [],
+        }