claude-mpm 5.1.9__py3-none-any.whl → 5.4.14__py3-none-any.whl

claude_mpm/services/skills_deployer.py

@@ -82,6 +82,8 @@ class SkillsDeployerService(LoggerMixin):
         toolchain: Optional[List[str]] = None,
         categories: Optional[List[str]] = None,
         force: bool = False,
+        selective: bool = True,
+        project_root: Optional[Path] = None,
     ) -> Dict:
         """Deploy skills from GitHub repository.
 
@@ -89,14 +91,17 @@ class SkillsDeployerService(LoggerMixin):
         1. Downloads skills from GitHub collection
         2. Parses manifest for metadata
         3. Filters by toolchain and categories
-        4. Deploys to ~/.claude/skills/
-        5. Warns about Claude Code restart
+        4. (If selective=True) Filters to only agent-referenced skills
+        5. Deploys to ~/.claude/skills/
+        6. Warns about Claude Code restart
 
         Args:
             collection: Collection name to deploy from (default: uses default collection)
             toolchain: Filter by toolchain (e.g., ['python', 'javascript'])
             categories: Filter by categories (e.g., ['testing', 'debugging'])
             force: Overwrite existing skills
+            selective: If True, only deploy skills referenced by agents (default)
+            project_root: Project root directory (for finding agents, auto-detected if None)
 
         Returns:
             Dict containing:
@@ -107,10 +112,14 @@ class SkillsDeployerService(LoggerMixin):
             - restart_required: True if Claude Code needs restart
             - restart_instructions: Message about restarting
             - collection: Collection name used for deployment
+            - selective_mode: True if selective deployment was used
+            - total_available: Total skills available before filtering
 
         Example:
             >>> result = deployer.deploy_skills(collection="obra-superpowers")
             >>> result = deployer.deploy_skills(toolchain=['python'])  # Uses default
+            >>> # Deploy all skills (not just agent-referenced)
+            >>> result = deployer.deploy_skills(selective=False)
             >>> if result['restart_required']:
             >>>     print(result['restart_instructions'])
         """
@@ -152,7 +161,7 @@ class SkillsDeployerService(LoggerMixin):
 
         self.logger.info(f"Found {len(skills)} skills in repository")
 
-        # Step 3: Filter skills
+        # Step 3: Filter skills by toolchain and categories
         filtered_skills = self._filter_skills(skills, toolchain, categories)
 
         self.logger.info(
@@ -160,6 +169,56 @@ class SkillsDeployerService(LoggerMixin):
             f" (toolchain={toolchain}, categories={categories})"
         )
 
+        # Step 3.5: Apply selective filtering (only agent-referenced skills)
+        total_available = len(filtered_skills)
+        if selective:
+            # Auto-detect project root if not provided
+            if project_root is None:
+                # Try to find project root by looking for .claude directory
+                # Start from current directory and walk up
+                current = Path.cwd()
+                while current != current.parent:
+                    if (current / ".claude").exists():
+                        project_root = current
+                        break
+                    current = current.parent
+
+            if project_root:
+                agents_dir = Path(project_root) / ".claude" / "agents"
+            else:
+                # Fallback to current directory's .claude/agents
+                agents_dir = Path.cwd() / ".claude" / "agents"
+
+            from claude_mpm.services.skills.selective_skill_deployer import (
+                get_required_skills_from_agents,
+            )
+
+            required_skill_names = get_required_skills_from_agents(agents_dir)
+
+            if required_skill_names:
+                # Filter to only required skills
+                # Match on either 'name' or 'skill_id' field
+                filtered_skills = [
+                    s
+                    for s in filtered_skills
+                    if s.get("name") in required_skill_names
+                    or s.get("skill_id") in required_skill_names
+                ]
+
+                self.logger.info(
+                    f"Selective deployment: {len(filtered_skills)}/{total_available} skills "
+                    f"(agent-referenced only)"
+                )
+            else:
+                self.logger.warning(
+                    f"No skills found in agent frontmatter at {agents_dir}. "
+                    f"Deploying all {total_available} skills."
+                )
+        else:
+            self.logger.info(
+                f"Selective mode disabled: deploying all {total_available} skills"
+            )
+
         # Step 4: Deploy skills
         deployed = []
         skipped = []
@@ -228,6 +287,8 @@ class SkillsDeployerService(LoggerMixin):
             "restart_required": restart_required,
             "restart_instructions": restart_instructions,
             "collection": collection_name,
+            "selective_mode": selective,
+            "total_available": total_available,
         }
 
     def list_available_skills(self, collection: Optional[str] = None) -> Dict:

claude_mpm/services/socketio/event_normalizer.py

@@ -78,10 +78,13 @@ class NormalizedEvent:
     subtype: str = ""  # Specific event type
     timestamp: str = ""  # ISO format timestamp
     data: Dict[str, Any] = field(default_factory=dict)  # Event payload
+    correlation_id: Optional[str] = (
+        None  # For correlating related events (e.g., pre_tool/post_tool)
+    )
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for emission."""
-        return {
+        result = {
             "event": self.event,
             "source": self.source,
             "type": self.type,
@@ -89,6 +92,10 @@ class NormalizedEvent:
             "timestamp": self.timestamp,
             "data": self.data,
         }
+        # Include correlation_id if present
+        if self.correlation_id:
+            result["correlation_id"] = self.correlation_id
+        return result
 
 
 class EventNormalizer:
@@ -218,6 +225,11 @@ class EventNormalizer:
             # Get or generate timestamp
             timestamp = self._extract_timestamp(event_data)
 
+            # Extract correlation_id if present
+            correlation_id = None
+            if isinstance(event_data, dict):
+                correlation_id = event_data.get("correlation_id")
+
             # Create normalized event
             normalized = NormalizedEvent(
                 event="claude_event",
@@ -226,6 +238,7 @@ class EventNormalizer:
                 subtype=subtype,
                 timestamp=timestamp,
                 data=data,
+                correlation_id=correlation_id,
             )
 
             self.stats["normalized"] += 1
@@ -281,6 +294,7 @@ class EventNormalizer:
                 "timestamp", datetime.now(timezone.utc).isoformat()
             ),
             data=event_data.get("data", {}),
+            correlation_id=event_data.get("correlation_id"),
         )
 
     def _extract_event_info(self, event_data: Any) -> Tuple[str, str, Dict[str, Any]]:

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

@@ -4,10 +4,14 @@ 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 supports both new (.claude-mpm/agents/) and
-  legacy (.claude/agents/)
+- 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
 
@@ -102,10 +106,11 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
 
     Design Rationale:
         - Primary detection: Virtual deployment state (.mpm_deployment_state)
-        - Fallback detection: Physical .md files (.claude-mpm/agents/, .claude/agents/)
+        - 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]"
@@ -115,24 +120,17 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
     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
+    # Only checking project-level deployment in simplified architecture
     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:
@@ -162,42 +160,17 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
                 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"):
+    # 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)
 
-    # 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)
+    # 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