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

claude_mpm/services/command_deployment_service.py

@@ -4,11 +4,13 @@ This service handles:
 1. Copying command markdown files from source to user's ~/.claude/commands directory
 2. Creating the commands directory if it doesn't exist
 3. Overwriting existing commands to ensure they're up-to-date
+4. Parsing and validating YAML frontmatter for namespace metadata (Phase 1 - 1M-400)
 """
 
-import shutil
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional, Tuple
+
+import yaml
 
 from claude_mpm.core.base_service import BaseService
 from claude_mpm.core.logger import get_logger
@@ -17,6 +19,16 @@ from claude_mpm.core.logger import get_logger
 class CommandDeploymentService(BaseService):
     """Service for deploying MPM slash commands."""
 
+    # Deprecated commands that have been replaced (cleanup on startup)
+    DEPRECATED_COMMANDS = [
+        "mpm-agents.md",  # Replaced by mpm-agents-list.md
+        "mpm-auto-configure.md",  # Replaced by mpm-agents-auto-configure.md
+        "mpm-config.md",  # Replaced by mpm-config-view.md
+        "mpm-organize.md",  # Replaced by mpm-ticket-organize.md
+        "mpm-resume.md",  # Replaced by mpm-session-resume.md
+        "mpm-ticket.md",  # Replaced by mpm-ticket-view.md
+    ]
+
     def __init__(self):
         """Initialize the command deployment service."""
         super().__init__(name="command_deployment")
@@ -39,6 +51,106 @@ class CommandDeploymentService(BaseService):
     async def _cleanup(self) -> None:
         """Cleanup service resources."""
 
+    def _parse_frontmatter(self, content: str) -> Tuple[Optional[Dict[str, Any]], str]:
+        """Parse YAML frontmatter from command file.
+
+        Ticket: 1M-400 Phase 1 - Enhanced Flat Naming with Namespace Metadata
+
+        Args:
+            content: Command file content
+
+        Returns:
+            Tuple of (frontmatter_dict, content_without_frontmatter)
+            If no frontmatter found, returns (None, original_content)
+        """
+        if not content.startswith("---\n"):
+            return None, content
+
+        try:
+            # Split on closing ---
+            parts = content.split("\n---\n", 1)
+            if len(parts) != 2:
+                return None, content
+
+            frontmatter_str = parts[0].replace("---\n", "", 1)
+            body = parts[1]
+
+            frontmatter = yaml.safe_load(frontmatter_str)
+            return frontmatter, body
+        except yaml.YAMLError as e:
+            self.logger.warning(f"YAML parsing error: {e}")
+            return None, content
+
+    def _validate_frontmatter(
+        self, frontmatter: Dict[str, Any], filepath: Path
+    ) -> List[str]:
+        """Validate frontmatter schema.
+
+        Ticket: 1M-400 Phase 1 - Enhanced Flat Naming with Namespace Metadata
+
+        Args:
+            frontmatter: Parsed frontmatter dictionary
+            filepath: Path to command file (for error reporting)
+
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        required_fields = ["namespace", "command", "category", "description"]
+
+        for field in required_fields:
+            if field not in frontmatter:
+                errors.append(f"Missing required field: {field}")
+
+        # Validate category
+        valid_categories = ["agents", "config", "tickets", "session", "system"]
+        if (
+            "category" in frontmatter
+            and frontmatter["category"] not in valid_categories
+        ):
+            errors.append(
+                f"Invalid category: {frontmatter['category']} "
+                f"(must be one of {valid_categories})"
+            )
+
+        # Validate data types
+        if "aliases" in frontmatter and not isinstance(frontmatter["aliases"], list):
+            errors.append("Field 'aliases' must be a list")
+
+        if "deprecated_aliases" in frontmatter and not isinstance(
+            frontmatter["deprecated_aliases"], list
+        ):
+            errors.append("Field 'deprecated_aliases' must be a list")
+
+        return errors
+
+    def _strip_deprecated_aliases(self, content: str) -> str:
+        """Strip deprecated_aliases from frontmatter to hide them from Claude Code UI.
+
+        This prevents deprecated aliases from appearing in the command list while
+        maintaining backward compatibility through command routing.
+
+        Args:
+            content: Command file content with frontmatter
+
+        Returns:
+            Content with deprecated_aliases removed from frontmatter
+        """
+        frontmatter, body = self._parse_frontmatter(content)
+
+        if not frontmatter or "deprecated_aliases" not in frontmatter:
+            return content
+
+        # Remove deprecated_aliases from frontmatter
+        frontmatter_copy = frontmatter.copy()
+        del frontmatter_copy["deprecated_aliases"]
+
+        # Reconstruct the file with modified frontmatter
+        frontmatter_yaml = yaml.dump(
+            frontmatter_copy, default_flow_style=False, sort_keys=False
+        )
+        return f"---\n{frontmatter_yaml}---\n{body}"
+
     def deploy_commands(self, force: bool = False) -> Dict[str, Any]:
         """Deploy MPM slash commands to user's Claude configuration.
 
@@ -83,17 +195,38 @@ class CommandDeploymentService(BaseService):
                 target_file = self.target_dir / source_file.name
 
                 try:
-                    # Check if file exists and if we should overwrite
-                    if target_file.exists() and not force:
-                        # Check if source is newer
-                        if source_file.stat().st_mtime <= target_file.stat().st_mtime:
-                            self.logger.debug(
-                                f"Skipping {source_file.name} - target is up to date"
+                    # Validate frontmatter if present (1M-400 Phase 1)
+                    content = source_file.read_text()
+                    frontmatter, _ = self._parse_frontmatter(content)
+
+                    if frontmatter:
+                        validation_errors = self._validate_frontmatter(
+                            frontmatter, source_file
+                        )
+                        if validation_errors:
+                            self.logger.warning(
+                                f"Frontmatter validation issues in {source_file.name}: "
+                                f"{'; '.join(validation_errors)}"
                             )
-                            continue
+                            # Continue deployment but log warnings
 
-                    # Copy the file
-                    shutil.copy2(source_file, target_file)
+                    # Check if file exists and if we should overwrite
+                    if (
+                        target_file.exists()
+                        and not force
+                        and source_file.stat().st_mtime <= target_file.stat().st_mtime
+                    ):
+                        self.logger.debug(
+                            f"Skipping {source_file.name} - target is up to date"
+                        )
+                        continue
+
+                    # Strip deprecated_aliases from content before deployment
+                    # This prevents them from appearing in Claude Code's command list UI
+                    cleaned_content = self._strip_deprecated_aliases(content)
+
+                    # Write the cleaned content to target
+                    target_file.write_text(cleaned_content)
                     self.logger.info(f"Deployed command: {source_file.name}")
                     result["deployed"].append(source_file.name)
 
@@ -159,21 +292,84 @@ class CommandDeploymentService(BaseService):
 
         return removed
 
+    def remove_deprecated_commands(self) -> int:
+        """Remove deprecated MPM commands that have been replaced.
+
+        This method cleans up old command files that have been superseded by
+        new hierarchical command names. It's called automatically on startup
+        to ensure users don't have both old and new versions.
+
+        Returns:
+            Number of deprecated files removed
+        """
+        if not self.target_dir.exists():
+            self.logger.debug(
+                f"Target directory does not exist: {self.target_dir}, skipping deprecated command cleanup"
+            )
+            return 0
+
+        removed = 0
+        self.logger.info("Cleaning up deprecated commands...")
+
+        # Mapping of deprecated commands to their replacements for informative logging
+        replacement_map = {
+            "mpm-agents.md": "mpm-agents-list.md",
+            "mpm-auto-configure.md": "mpm-agents-auto-configure.md",
+            "mpm-config.md": "mpm-config-view.md",
+            "mpm-organize.md": "mpm-ticket-organize.md",
+            "mpm-resume.md": "mpm-session-resume.md",
+            "mpm-ticket.md": "mpm-ticket-view.md",
+        }
+
+        for deprecated_cmd in self.DEPRECATED_COMMANDS:
+            deprecated_file = self.target_dir / deprecated_cmd
+            replacement = replacement_map.get(deprecated_cmd, "a newer command")
+
+            if deprecated_file.exists():
+                try:
+                    deprecated_file.unlink()
+                    self.logger.debug(
+                        f"Removed deprecated command: {deprecated_cmd} (replaced by {replacement})"
+                    )
+                    removed += 1
+                except Exception as e:
+                    # Log error but don't fail startup - this is non-critical
+                    self.logger.warning(
+                        f"Failed to remove deprecated command {deprecated_cmd}: {e}"
+                    )
+
+        if removed > 0:
+            self.logger.info(f"Removed {removed} deprecated command(s)")
+        else:
+            self.logger.debug("No deprecated commands found to remove")
+
+        return removed
+
 
 def deploy_commands_on_startup(force: bool = False) -> None:
     """Convenience function to deploy commands during startup.
 
+    This function:
+    1. Removes deprecated commands that have been replaced
+    2. Deploys current command files
+
     Args:
         force: Force deployment even if files exist
     """
     service = CommandDeploymentService()
+    logger = get_logger("startup")
+
+    # Clean up deprecated commands BEFORE deploying new ones
+    removed_count = service.remove_deprecated_commands()
+    if removed_count > 0:
+        logger.info(f"Cleaned up {removed_count} deprecated command(s)")
+
+    # Deploy current commands
     result = service.deploy_commands(force=force)
 
     if result["deployed"]:
-        logger = get_logger("startup")
         logger.info(f"MPM commands deployed: {', '.join(result['deployed'])}")
 
     if result["errors"]:
-        logger = get_logger("startup")
         for error in result["errors"]:
             logger.warning(f"Command deployment issue: {error}")

claude_mpm/services/command_handler_service.py

@@ -12,6 +12,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict, List
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult
 from claude_mpm.services.core.interfaces import CommandHandlerInterface
 
 
@@ -169,7 +170,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "test":
                 success = self._handle_test_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -179,7 +180,7 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
             if command == "agents":
                 success = self._handle_agents_command(args)
                 return {
-                    "success": success,
+                    OperationResult.SUCCESS.value: success,
                     "command": command,
                     "args": args,
                     "message": (
@@ -189,14 +190,19 @@ class CommandHandlerService(BaseService, CommandHandlerInterface):
                     ),
                 }
             return {
-                "success": False,
+                OperationResult.SUCCESS.value: False,
                 "command": command,
                 "args": args,
-                "error": f"Unknown command: {command}",
+                OperationResult.ERROR.value: f"Unknown command: {command}",
                 "available_commands": self.get_available_commands(),
             }
         except Exception as e:
-            return {"success": False, "command": command, "args": args, "error": str(e)}
+            return {
+                OperationResult.SUCCESS.value: False,
+                "command": command,
+                "args": args,
+                OperationResult.ERROR.value: str(e),
+            }
 
     def get_command_help(self, command: str) -> str:
         """Get help text for a specific command.

claude_mpm/services/core/__init__.py

@@ -16,7 +16,9 @@ from .interfaces import (  # Core dependency injection; Configuration management
     CacheEntry,
     HealthStatus,
     HookServiceInterface,
+    IAgentRecommender,
     IAgentRegistry,
+    IAutoConfigManager,
     ICacheService,
     IConfigurationManager,
     IConfigurationService,
@@ -31,6 +33,7 @@ from .interfaces import (  # Core dependency injection; Configuration management
     IServiceLifecycle,
     IStructuredLogger,
     ITemplateManager,
+    IToolchainAnalyzer,
     MemoryServiceInterface,
     ProjectAnalyzerInterface,
     ServiceType,
@@ -38,8 +41,21 @@ from .interfaces import (  # Core dependency injection; Configuration management
     TemplateRenderContext,
     TicketManagerInterface,
 )
+from .models import (  # Data models for services
+    AgentCapabilities,
+    AgentRecommendation,
+    ConfidenceLevel,
+    ConfigurationPreview,
+    ConfigurationResult,
+    DeploymentTarget,
+    Framework,
+    LanguageDetection,
+    ToolchainAnalysis,
+    ToolchainComponent,
+    ValidationResult,
+)
 
-__all__ = [
+__all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
     # Service interfaces
     "AgentDeploymentInterface",
     "AgentMetadata",
@@ -48,7 +64,9 @@ __all__ = [
     "CacheEntry",
     "HealthStatus",
     "HookServiceInterface",
+    "IAgentRecommender",
     "IAgentRegistry",
+    "IAutoConfigManager",
     "ICacheService",
     "IConfigurationManager",
     "IConfigurationService",
@@ -63,6 +81,7 @@ __all__ = [
     "IServiceLifecycle",
     "IStructuredLogger",
     "ITemplateManager",
+    "IToolchainAnalyzer",
     # Registry
     "InterfaceRegistry",
     "MemoryServiceInterface",
@@ -73,4 +92,17 @@ __all__ = [
     "SyncBaseService",
     "TemplateRenderContext",
     "TicketManagerInterface",
+    # Data models - Toolchain
+    "ConfidenceLevel",
+    "ToolchainComponent",
+    "LanguageDetection",
+    "Framework",
+    "DeploymentTarget",
+    "ToolchainAnalysis",
+    # Data models - Agent Configuration
+    "AgentCapabilities",
+    "AgentRecommendation",
+    "ConfigurationResult",
+    "ValidationResult",
+    "ConfigurationPreview",
 ]

claude_mpm/services/core/base.py

@@ -9,6 +9,7 @@ and lifecycle management.
 Part of TSK-0046: Service Layer Architecture Reorganization
 """
 
+import threading
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional
 
@@ -221,29 +222,48 @@ class SingletonService(SyncBaseService):
     """
     Base class for singleton services.
 
-    Ensures only one instance of the service exists.
+    Ensures only one instance of the service exists with thread-safe initialization.
+    Uses double-checked locking pattern to prevent race conditions.
+    Uses RLock (reentrant lock) to support recursive instantiation patterns.
     """
 
     _instances: Dict[type, "SingletonService"] = {}
+    _lock = threading.RLock()
 
     def __new__(cls, *args, **kwargs):
-        """Ensure only one instance exists."""
+        """Ensure only one instance exists with thread-safe initialization."""
+        # Fast path - check without lock
         if cls not in cls._instances:
-            cls._instances[cls] = super().__new__(cls)
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__new__(cls)
         return cls._instances[cls]
 
     @classmethod
     def get_instance(cls) -> "SingletonService":
-        """Get the singleton instance."""
+        """Get the singleton instance with thread-safe initialization."""
+        # Fast path - check without lock
         if cls not in cls._instances:
-            cls._instances[cls] = cls()
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    # Use object.__new__ to bypass __new__ recursion
+                    instance = object.__new__(cls)
+                    cls._instances[cls] = instance
+                    # Call __init__ explicitly after storing instance
+                    instance.__init__()
         return cls._instances[cls]
 
     @classmethod
     def clear_instance(cls) -> None:
-        """Clear the singleton instance (useful for testing)."""
-        if cls in cls._instances:
-            instance = cls._instances[cls]
-            if hasattr(instance, "shutdown") and not instance.is_shutdown:
-                instance.shutdown()
-            del cls._instances[cls]
+        """Clear the singleton instance (useful for testing).
+
+        Thread-safe implementation ensures proper cleanup.
+        """
+        with cls._lock:
+            if cls in cls._instances:
+                instance = cls._instances[cls]
+                if hasattr(instance, "shutdown") and not instance.is_shutdown:
+                    instance.shutdown()
+                del cls._instances[cls]

claude_mpm/services/core/interfaces/__init__.py

@@ -24,11 +24,13 @@ MODULES:
 """
 
 # Agent interfaces (agent management and operations)
-from .agent import (  # Agent registry; Agent deployment; Agent capabilities; System instructions; Subprocess management; Runner configuration
+from .agent import (  # Agent registry; Agent deployment; Agent capabilities; System instructions; Subprocess management; Runner configuration; Agent recommendation; Auto-configuration
     AgentCapabilitiesInterface,
     AgentDeploymentInterface,
     AgentMetadata,
+    IAgentRecommender,
     IAgentRegistry,
+    IAutoConfigManager,
     RunnerConfigurationInterface,
     SubprocessLauncherInterface,
     SystemInstructionsInterface,
@@ -41,6 +43,12 @@ from .communication import (  # WebSocket/SocketIO; Project analysis; Ticket man
     TicketManagerInterface,
 )
 
+# Health interfaces (health monitoring)
+from .health import (  # Health checks; Health monitoring
+    IHealthCheck,
+    IHealthCheckManager,
+)
+
 # Infrastructure interfaces (core framework services)
 from .infrastructure import (  # Type variables; Core dependency injection; Configuration management; Caching; Health monitoring; Template management; Service factory; Logging; Service lifecycle; Error handling; Performance monitoring; Event system
     CacheEntry,
@@ -63,6 +71,31 @@ from .infrastructure import (  # Type variables; Core dependency injection; Conf
     TemplateRenderContext,
 )
 
+# Model interfaces (content processing and model providers)
+from .model import (  # Model providers; Routing
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+
+# Process interfaces (local process management)
+from .process import (  # Process lifecycle; State persistence
+    IDeploymentStateManager,
+    ILocalProcessManager,
+)
+
+# Project interfaces (project analysis and toolchain detection)
+from .project import IToolchainAnalyzer  # Toolchain analysis
+
+# Restart interfaces (auto-restart management)
+from .restart import (  # Crash detection; Restart policy; Restart orchestration
+    ICrashDetector,
+    IRestartManager,
+    IRestartPolicy,
+)
+
 # Service interfaces (business services)
 from .service import (  # Version service; Command handling; Memory management; Session management; Utilities; Hook service
     CommandHandlerInterface,
@@ -74,6 +107,13 @@ from .service import (  # Version service; Command handling; Memory management;
     VersionServiceInterface,
 )
 
+# Stability interfaces (proactive monitoring and crash prevention)
+from .stability import (  # Memory leak detection; Log monitoring; Resource monitoring
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IResourceMonitor,
+)
+
 
 # Interface registry for dependency injection discovery
 class InterfaceRegistry:
@@ -118,6 +158,27 @@ class InterfaceRegistry:
         "socketio_service": SocketIOServiceInterface,
         "project_analyzer": ProjectAnalyzerInterface,
         "ticket_manager": TicketManagerInterface,
+        # Project interfaces
+        "toolchain_analyzer": IToolchainAnalyzer,
+        "agent_recommender": IAgentRecommender,
+        "auto_config_manager": IAutoConfigManager,
+        # Model interfaces
+        "model_provider": IModelProvider,
+        "model_router": IModelRouter,
+        # Process interfaces
+        "deployment_state_manager": IDeploymentStateManager,
+        "local_process_manager": ILocalProcessManager,
+        # Health interfaces
+        "health_check": IHealthCheck,
+        "health_check_manager": IHealthCheckManager,
+        # Restart interfaces
+        "crash_detector": ICrashDetector,
+        "restart_policy": IRestartPolicy,
+        "restart_manager": IRestartManager,
+        # Stability interfaces
+        "memory_leak_detector": IMemoryLeakDetector,
+        "log_monitor": ILogMonitor,
+        "resource_monitor": IResourceMonitor,
     }
 
     @classmethod
@@ -142,7 +203,7 @@ class InterfaceRegistry:
 
 
 # Re-export everything for backward compatibility
-__all__ = [
+__all__ = [  # noqa: RUF022 - Semantic grouping by domain preferred over alphabetical
     "AgentCapabilitiesInterface",
     "AgentDeploymentInterface",
     "AgentMetadata",
@@ -151,23 +212,47 @@ __all__ = [
     "HealthStatus",
     "HookServiceInterface",
     # Agent interfaces
+    "IAgentRecommender",
     "IAgentRegistry",
+    "IAutoConfigManager",
     "ICacheService",
     "IConfigurationManager",
     "IConfigurationService",
+    # Process interfaces
+    "IDeploymentStateManager",
     "IErrorHandler",
     "IEventBus",
+    # Health interfaces
+    "IHealthCheck",
+    "IHealthCheckManager",
     "IHealthMonitor",
+    # Infrastructure interfaces
+    "ILocalProcessManager",
+    # Restart interfaces
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+    # Stability interfaces
+    "IMemoryLeakDetector",
+    "ILogMonitor",
+    "IResourceMonitor",
+    # Model interfaces
+    "IModelProvider",
+    "IModelRouter",
     "IPerformanceMonitor",
     "IPromptCache",
-    # Infrastructure interfaces
     "IServiceContainer",
     "IServiceFactory",
     "IServiceLifecycle",
     "IStructuredLogger",
     "ITemplateManager",
+    # Project interfaces
+    "IToolchainAnalyzer",
     # Registry
     "InterfaceRegistry",
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
     "MemoryHookInterface",
     "MemoryServiceInterface",
     "ProjectAnalyzerInterface",