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

claude_mpm/services/socketio/server/core.py

@@ -32,6 +32,7 @@ except ImportError:
 # Import VersionService for dynamic version retrieval
 import contextlib
 
+import claude_mpm
 from claude_mpm.services.version_service import VersionService
 
 from ....core.constants import SystemLimits, TimeoutConfig
@@ -271,7 +272,15 @@ class SocketIOServerCore:
             """Handle POST /api/events from hook handlers."""
             try:
                 # Parse JSON payload
-                event_data = await request.json()
+                payload = await request.json()
+
+                # Extract event data from payload (handles both direct and wrapped formats)
+                # ConnectionManagerService sends: {"namespace": "...", "event": "...", "data": {...}}
+                # Direct hook events may send data directly
+                if "data" in payload and isinstance(payload.get("data"), dict):
+                    event_data = payload["data"]
+                else:
+                    event_data = payload
 
                 # Log receipt with more detail
                 event_type = (
@@ -292,38 +301,96 @@ class SocketIOServerCore:
 
                     normalizer = EventNormalizer()
 
+                    # Map hook event names to dashboard subtypes
+                    # Comprehensive mapping of all known Claude Code hook event types
+                    subtype_map = {
+                        # User interaction events
+                        "UserPromptSubmit": "user_prompt_submit",
+                        "UserPromptCancel": "user_prompt_cancel",
+                        # Tool execution events
+                        "PreToolUse": "pre_tool_use",
+                        "PostToolUse": "post_tool_use",
+                        "ToolStart": "tool_start",
+                        "ToolUse": "tool_use",
+                        # Assistant events
+                        "AssistantResponse": "assistant_response",
+                        # Session lifecycle events
+                        "Start": "start",
+                        "Stop": "stop",
+                        "SessionStart": "session_start",
+                        # Subagent events
+                        "SubagentStart": "subagent_start",
+                        "SubagentStop": "subagent_stop",
+                        "SubagentEvent": "subagent_event",
+                        # Task events
+                        "Task": "task",
+                        "TaskStart": "task_start",
+                        "TaskComplete": "task_complete",
+                        # File operation events
+                        "FileWrite": "file_write",
+                        "Write": "write",
+                        # System events
+                        "Notification": "notification",
+                    }
+
+                    # Helper function to convert PascalCase to snake_case
+                    def to_snake_case(name: str) -> str:
+                        """Convert PascalCase event names to snake_case.
+
+                        Examples:
+                            UserPromptSubmit → user_prompt_submit
+                            PreToolUse → pre_tool_use
+                            TaskComplete → task_complete
+                        """
+                        import re
+
+                        return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+                    # Get hook event name and map to subtype
+                    hook_event_name = event_data.get("hook_event_name", "unknown")
+                    subtype = subtype_map.get(
+                        hook_event_name, to_snake_case(hook_event_name)
+                    )
+
+                    # Debug log for unmapped events to discover new event types
+                    if (
+                        hook_event_name not in subtype_map
+                        and hook_event_name != "unknown"
+                    ):
+                        self.logger.debug(
+                            f"Unmapped hook event: {hook_event_name} → {subtype}"
+                        )
+
                     # Create the format expected by normalizer
                     raw_event = {
                         "type": "hook",
-                        "subtype": event_data.get("hook_event_name", "unknown")
-                        .lower()
-                        .replace("submit", "")
-                        .replace("use", "_use"),
+                        "subtype": subtype,
                         "timestamp": event_data.get("timestamp"),
                         "data": event_data.get("hook_input_data", {}),
                         "source": "claude_hooks",
                         "session_id": event_data.get("session_id"),
                     }
 
-                    # Map hook event names to dashboard subtypes
-                    subtype_map = {
-                        "UserPromptSubmit": "user_prompt",
-                        "PreToolUse": "pre_tool",
-                        "PostToolUse": "post_tool",
-                        "Stop": "stop",
-                        "SubagentStop": "subagent_stop",
-                        "AssistantResponse": "assistant_response",
-                    }
-                    raw_event["subtype"] = subtype_map.get(
-                        event_data.get("hook_event_name"), "unknown"
-                    )
-
                     normalized = normalizer.normalize(raw_event, source="hook")
                     event_data = normalized.to_dict()
                     self.logger.debug(
                         f"Normalized event: type={event_data.get('type')}, subtype={event_data.get('subtype')}"
                     )
 
+                # Publish to EventBus for cross-component communication
+                # WHY: This allows other parts of the system to react to hook events
+                # without coupling to Socket.IO directly
+                try:
+                    from claude_mpm.services.event_bus import EventBus
+
+                    event_bus = EventBus.get_instance()
+                    event_type = f"hook.{event_data.get('subtype', 'unknown')}"
+                    event_bus.publish(event_type, event_data)
+                    self.logger.debug(f"Published to EventBus: {event_type}")
+                except Exception as e:
+                    # Non-fatal: EventBus publication failure shouldn't break event flow
+                    self.logger.warning(f"Failed to publish to EventBus: {e}")
+
                 # Broadcast to all connected dashboard clients via SocketIO
                 if self.sio:
                     # CRITICAL: Use the main server's broadcaster for proper event handling
@@ -390,6 +457,47 @@ class SocketIOServerCore:
         self.app.router.add_post("/api/events", api_events_handler)
         self.logger.info("✅ HTTP API endpoint registered at /api/events")
 
+        # Add health check endpoint
+        async def health_handler(request):
+            """Handle GET /api/health for health checks."""
+            try:
+                # Get server status
+                uptime_seconds = 0
+                if self.stats.get("start_time"):
+                    uptime_seconds = int(
+                        (
+                            datetime.now(timezone.utc) - self.stats["start_time"]
+                        ).total_seconds()
+                    )
+
+                health_data = {
+                    "status": "healthy",
+                    "service": "claude-mpm-socketio",
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "uptime_seconds": uptime_seconds,
+                    "connected_clients": len(self.connected_clients),
+                    "total_events": self.stats.get("events_sent", 0),
+                    "buffered_events": self.stats.get("events_buffered", 0),
+                }
+
+                return web.json_response(health_data)
+            except Exception as e:
+                self.logger.error(f"Error in health check: {e}")
+                return web.json_response(
+                    {
+                        "status": "unhealthy",
+                        "service": "claude-mpm-socketio",
+                        "error": str(e),
+                    },
+                    status=503,
+                )
+
+        self.app.router.add_get("/api/health", health_handler)
+        self.app.router.add_get("/health", health_handler)  # Alias for convenience
+        self.logger.info(
+            "✅ Health check endpoints registered at /api/health and /health"
+        )
+
         # Add working directory endpoint
         async def working_directory_handler(request):
             """Handle GET /api/working-directory to provide current working directory."""
@@ -591,9 +699,9 @@ class SocketIOServerCore:
                 self.app.router.add_get("/version.json", version_handler)
 
                 # Serve static assets (CSS, JS) from the dashboard static directory
-                dashboard_static_path = (
-                    get_project_root() / "src" / "claude_mpm" / "dashboard" / "static"
-                )
+                # Use package-relative path (works for both dev and installed package)
+                package_root = Path(claude_mpm.__file__).parent
+                dashboard_static_path = package_root / "dashboard" / "static"
                 if dashboard_static_path.exists():
                     self.app.router.add_static(
                         "/static/", dashboard_static_path, name="dashboard_static"
@@ -606,6 +714,37 @@ class SocketIOServerCore:
                         f"⚠️  Static assets directory not found at: {dashboard_static_path}"
                     )
 
+                # Serve Svelte dashboard build
+                svelte_build_path = (
+                    package_root / "dashboard" / "static" / "svelte-build"
+                )
+                if svelte_build_path.exists():
+                    # Serve Svelte dashboard at /svelte route
+                    async def svelte_handler(request):
+                        svelte_index = svelte_build_path / "index.html"
+                        if svelte_index.exists():
+                            self.logger.debug(
+                                f"Serving Svelte dashboard from: {svelte_index}"
+                            )
+                            return web.FileResponse(svelte_index)
+                        return web.Response(
+                            text="Svelte dashboard not available", status=404
+                        )
+
+                    self.app.router.add_get("/svelte", svelte_handler)
+
+                    # Serve Svelte app assets at /_app/ (needed for SvelteKit builds)
+                    svelte_app_path = svelte_build_path / "_app"
+                    if svelte_app_path.exists():
+                        self.app.router.add_static(
+                            "/_app/", svelte_app_path, name="svelte_app"
+                        )
+                        self.logger.info(
+                            f"✅ Svelte dashboard available at /svelte (build: {svelte_build_path})"
+                        )
+                else:
+                    self.logger.debug(f"Svelte build not found at: {svelte_build_path}")
+
             else:
                 self.logger.warning("⚠️  No dashboard found, serving fallback response")
 

claude_mpm/services/version_control/git_operations.py

@@ -18,6 +18,11 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
+# Privileged users who can push directly to main branch
+# All other users must use feature branches and PRs
+PRIVILEGED_GIT_USERS = ["bobmatnyc@users.noreply.github.com"]
+PROTECTED_BRANCHES = ["main", "master"]
+
 
 @dataclass
 class GitBranchInfo:
@@ -101,6 +106,94 @@ class GitOperationsManager:
         if not self._is_git_repository():
             raise GitOperationError(f"Not a Git repository: {project_root}")
 
+    def _get_current_git_user(self) -> str:
+        """
+        Get the current Git user email.
+
+        Returns:
+            Git user email configured in repository or globally
+
+        Raises:
+            GitOperationError: If git user.email is not configured
+        """
+        try:
+            result = self._run_git_command(["config", "user.email"])
+            email = result.stdout.strip()
+            if not email:
+                raise GitOperationError(
+                    "Git user.email is not configured. "
+                    "Please configure it with: git config user.email 'your@email.com'"
+                )
+            return email
+        except GitOperationError as e:
+            raise GitOperationError(
+                "Git user.email is not configured. "
+                "Please configure it with: git config user.email 'your@email.com'"
+            ) from e
+
+    def _is_privileged_user(self) -> bool:
+        """
+        Check if the current Git user is privileged to push to protected branches.
+
+        Returns:
+            True if user email is in PRIVILEGED_GIT_USERS, False otherwise
+        """
+        try:
+            current_user = self._get_current_git_user()
+            return current_user in PRIVILEGED_GIT_USERS
+        except GitOperationError:
+            # If we can't determine user, assume not privileged
+            return False
+
+    def _enforce_branch_protection(
+        self, target_branch: str, operation: str
+    ) -> Optional[GitOperationResult]:
+        """
+        Enforce branch protection rules for protected branches.
+
+        Args:
+            target_branch: Branch being operated on
+            operation: Operation being performed (e.g., "push", "merge")
+
+        Returns:
+            GitOperationResult with error if protection violated, None if allowed
+        """
+        # Check if target branch is protected
+        if target_branch not in PROTECTED_BRANCHES:
+            return None
+
+        # Check if user is privileged
+        if self._is_privileged_user():
+            return None
+
+        # Get current user for error message
+        try:
+            current_user = self._get_current_git_user()
+        except GitOperationError:
+            current_user = "unknown"
+
+        # Build helpful error message
+        error_message = (
+            f"Direct {operation} to '{target_branch}' branch is restricted.\n"
+            f"Only {', '.join(PRIVILEGED_GIT_USERS)} can {operation} directly to protected branches.\n"
+            f"Current user: {current_user}\n\n"
+            f"Please use the feature branch workflow:\n"
+            f"  1. git checkout -b feature/your-feature-name\n"
+            f"  2. Make your changes and commit\n"
+            f"  3. git push -u origin feature/your-feature-name\n"
+            f"  4. Create a Pull Request on GitHub for review"
+        )
+
+        return GitOperationResult(
+            success=False,
+            operation=f"{operation}_branch_protection",
+            message=f"Branch protection: {operation} to '{target_branch}' denied",
+            error=error_message,
+            branch_before=self.get_current_branch(),
+            branch_after=self.get_current_branch(),
+            execution_time=0.0,
+        )
+
     def _is_git_repository(self) -> bool:
         """Check if the directory is a Git repository."""
         return self.git_dir.exists() and self.git_dir.is_dir()
@@ -503,6 +596,11 @@ class GitOperationsManager:
         start_time = datetime.now(timezone.utc)
         current_branch = self.get_current_branch()
 
+        # Enforce branch protection for target branch
+        protection_result = self._enforce_branch_protection(target_branch, "merge")
+        if protection_result:
+            return protection_result
+
         try:
             # Switch to target branch
             if current_branch != target_branch:
@@ -659,6 +757,11 @@ class GitOperationsManager:
         if not branch_name:
             branch_name = current_branch
 
+        # Enforce branch protection
+        protection_result = self._enforce_branch_protection(branch_name, "push")
+        if protection_result:
+            return protection_result
+
         try:
             # Build push command
             push_args = ["push"]

claude_mpm/utils/agent_filters.py

@@ -0,0 +1,261 @@
+"""
+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.
+
+ARCHITECTURE:
+- SOURCE: ~/.claude-mpm/cache/remote-agents/ (git repository cache)
+- DEPLOYMENT: .claude/agents/ (project-level deployment location)
+
+DESIGN DECISIONS:
+- BASE_AGENT is a build tool, not a deployable agent - filter everywhere
+- Deployed agent detection checks .claude/agents/ for all deployed agents
+- Supports both virtual (.mpm_deployment_state) and physical (.md files) detection
+- 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 in .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
+        - Only checks project-level deployment (simplified architecture)
+
+    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
+
+    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
+    # Only checking project-level deployment in simplified architecture
+    deployment_state_paths = [
+        project_dir / ".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 project deployment location (.claude/agents/)
+    agents_dir = project_dir / ".claude" / "agents"
+    if agents_dir.exists():
+        for file in agents_dir.glob("*.md"):
+            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                deployed.add(file.stem)
+
+    # NOTE: .claude/templates/ contains PM instruction templates, NOT deployed agents
+    # It should NOT be checked here. Agents are deployed to:
+    # - .mpm_deployment_state (virtual deployment)
+    # - .claude/agents/*.md (project deployment)
+
+    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/gitignore.py

@@ -212,6 +212,9 @@ def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
         entries_to_add = [
             ".claude-mpm/",
             ".claude/agents/",
+            ".mcp.json",
+            ".claude.json",
+            ".claude/",
         ]
 
         added, existing = manager.ensure_entries(entries_to_add)