claude-mpm 4.20.3__py3-none-any.whl → 5.1.8__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,6 +195,21 @@ class CommandDeploymentService(BaseService):
                 target_file = self.target_dir / source_file.name
 
                 try:
+                    # 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 deployment but log warnings
+
                     # Check if file exists and if we should overwrite
                     if (
                         target_file.exists()
@@ -94,8 +221,12 @@ class CommandDeploymentService(BaseService):
                         )
                         continue
 
-                    # Copy the file
-                    shutil.copy2(source_file, target_file)
+                    # 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)
 
@@ -161,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/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

@@ -87,9 +87,7 @@ from .process import (  # Process lifecycle; State persistence
 )
 
 # Project interfaces (project analysis and toolchain detection)
-from .project import (  # Toolchain analysis
-    IToolchainAnalyzer,
-)
+from .project import IToolchainAnalyzer  # Toolchain analysis
 
 # Restart interfaces (auto-restart management)
 from .restart import (  # Crash detection; Restart policy; Restart orchestration

claude_mpm/services/core/interfaces/health.py

@@ -29,10 +29,7 @@ USAGE:
 from abc import ABC, abstractmethod
 from typing import List
 
-from claude_mpm.services.core.models.health import (
-    DeploymentHealth,
-    HealthCheckResult,
-)
+from claude_mpm.services.core.models.health import DeploymentHealth, HealthCheckResult
 
 
 class IHealthCheck(ABC):

claude_mpm/services/core/interfaces.py

@@ -20,7 +20,62 @@ focused modules for better maintainability and testing.
 """
 
 # Re-export everything from the new modular structure for backward compatibility
-from .interfaces import *
+from .interfaces import (  # noqa: F401
+    AgentCapabilitiesInterface,
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    CommandHandlerInterface,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    ICrashDetector,
+    IDeploymentStateManager,
+    IErrorHandler,
+    IEventBus,
+    IHealthCheck,
+    IHealthCheckManager,
+    IHealthMonitor,
+    ILocalProcessManager,
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IModelProvider,
+    IModelRouter,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IResourceMonitor,
+    IRestartManager,
+    IRestartPolicy,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryHookInterface,
+    MemoryServiceInterface,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+    ProjectAnalyzerInterface,
+    RunnerConfigurationInterface,
+    ServiceType,
+    SessionManagementInterface,
+    SocketIOServiceInterface,
+    SubprocessLauncherInterface,
+    SystemInstructionsInterface,
+    T,
+    TemplateRenderContext,
+    TicketManagerInterface,
+    UtilityServiceInterface,
+    VersionServiceInterface,
+)
 
 # All interface definitions have been moved to the interfaces/ package
 # This file now serves as a compatibility layer that delegates to the modular structure

claude_mpm/services/core/models/__init__.py

@@ -27,17 +27,8 @@ from .process import (
     StartConfig,
     is_port_protected,
 )
-from .restart import (
-    CircuitBreakerState,
-    RestartAttempt,
-    RestartConfig,
-    RestartHistory,
-)
-from .stability import (
-    LogPatternMatch,
-    MemoryTrend,
-    ResourceUsage,
-)
+from .restart import CircuitBreakerState, RestartAttempt, RestartConfig, RestartHistory
+from .stability import LogPatternMatch, MemoryTrend, ResourceUsage
 from .toolchain import (
     ConfidenceLevel,
     DeploymentTarget,

claude_mpm/services/core/models/agent_config.py

@@ -19,6 +19,9 @@ from typing import Any, Dict, List, Optional
 
 from ....core.enums import OperationResult, ValidationSeverity
 
+# Backward compatibility alias (consolidated in Phase 3A Batch 25)
+ConfigurationStatus = OperationResult
+
 
 class AgentSpecialization(str, Enum):
     """Agent specialization categories.

claude_mpm/services/core/models/process.py

@@ -25,6 +25,9 @@ from typing import Any, Dict, List, Optional
 
 from claude_mpm.core.enums import ServiceState
 
+# Backward compatibility alias (consolidated in Phase 3A Batch 24)
+ProcessStatus = ServiceState
+
 
 @dataclass
 class DeploymentState:
@@ -230,6 +233,7 @@ __all__ = [
     "PROTECTED_PORT_RANGES",
     "DeploymentState",
     "ProcessInfo",
+    "ProcessStatus",  # Backward compatibility alias for ServiceState
     "StartConfig",
     "is_port_protected",
 ]

claude_mpm/services/diagnostics/checks/__init__.py

@@ -6,6 +6,7 @@ diagnostic components.
 """
 
 from .agent_check import AgentCheck
+from .agent_sources_check import AgentSourcesCheck
 from .base_check import BaseDiagnosticCheck
 from .claude_code_check import ClaudeCodeCheck
 from .common_issues_check import CommonIssuesCheck
@@ -16,10 +17,12 @@ from .instructions_check import InstructionsCheck
 from .mcp_check import MCPCheck
 from .mcp_services_check import MCPServicesCheck
 from .monitor_check import MonitorCheck
+from .skill_sources_check import SkillSourcesCheck
 from .startup_log_check import StartupLogCheck
 
 __all__ = [
     "AgentCheck",
+    "AgentSourcesCheck",
     "BaseDiagnosticCheck",
     "ClaudeCodeCheck",
     "CommonIssuesCheck",
@@ -30,5 +33,6 @@ __all__ = [
     "MCPCheck",
     "MCPServicesCheck",
     "MonitorCheck",
+    "SkillSourcesCheck",
     "StartupLogCheck",
 ]

claude_mpm/services/diagnostics/checks/agent_check.py

@@ -188,7 +188,6 @@ class AgentCheck(BaseDiagnosticCheck):
     def _check_agent_versions(self) -> DiagnosticResult:
         """Check if deployed agents are up-to-date."""
         try:
-
             from ....services.agents.deployment.agent_version_manager import (
                 AgentVersionManager,
             )
@@ -258,7 +257,6 @@ class AgentCheck(BaseDiagnosticCheck):
     def _validate_agents(self) -> DiagnosticResult:
         """Validate agent configurations."""
         try:
-
             from ....services.agents.deployment.agent_validator import AgentValidator
 
             AgentValidator()