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

claude_mpm/constants.py

@@ -38,9 +38,14 @@ class CLICommands(str, Enum):
     CONFIG = "config"
     CONFIGURE = "configure"
     AGGREGATE = "aggregate"
+    ANALYZE = "analyze"
+    ANALYZE_CODE = "analyze-code"
     CLEANUP = "cleanup-memory"
     MCP = "mcp"
     DOCTOR = "doctor"
+    DASHBOARD = "dashboard"
+    UPGRADE = "upgrade"
+    SKILLS = "skills"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -97,6 +102,15 @@ class MonitorCommands(str, Enum):
     PORT = "port"
 
 
+class DashboardCommands(str, Enum):
+    """Dashboard subcommand constants."""
+
+    START = "start"
+    STOP = "stop"
+    STATUS = "status"
+    OPEN = "open"
+
+
 class ConfigCommands(str, Enum):
     """Config subcommand constants."""
 
@@ -128,6 +142,7 @@ class MCPCommands(str, Enum):
     TEST = "test"
     CONFIG = "config"
     SERVER = "server"
+    EXTERNAL = "external"
 
 
 class TicketCommands(str, Enum):
@@ -144,6 +159,17 @@ class TicketCommands(str, Enum):
     WORKFLOW = "workflow"
 
 
+class SkillsCommands(str, Enum):
+    """Skills subcommand constants."""
+
+    LIST = "list"
+    DEPLOY = "deploy"
+    VALIDATE = "validate"
+    UPDATE = "update"
+    INFO = "info"
+    CONFIG = "config"
+
+
 class CLIFlags(str, Enum):
     """CLI flag constants (without prefix)."""
 
@@ -217,7 +243,7 @@ class Paths(str, Enum):
 
     CLAUDE_AGENTS_DIR = ".claude/agents"
     CLAUDE_CONFIG_DIR = ".claude"
-    MPM_LOG_DIR = ".claude-mpm/logs"
+    MPM_LOG_DIR = ".claude-mpm/logs/mpm"
     MPM_SESSION_DIR = ".claude-mpm/session"
     MPM_PROMPTS_DIR = ".claude-mpm/prompts"
 

claude_mpm/core/__init__.py

@@ -1,20 +1,56 @@
-"""Core components for Claude MPM."""
-
-from .claude_runner import ClaudeRunner
-from .config import Config
-
-# Import DI components
-from .container import DIContainer, ServiceLifetime, get_container
-from .factories import (
-    AgentServiceFactory,
-    ConfigurationFactory,
-    ServiceFactory,
-    SessionManagerFactory,
-    get_factory_registry,
-)
-from .injectable_service import InjectableService
-from .mixins import LoggerMixin
-from .service_registry import ServiceRegistry, get_service_registry, initialize_services
+"""Core components for Claude MPM.
+
+Lazy imports for all components to avoid loading heavy dependencies
+when only importing lightweight utilities (constants, logging_utils, etc).
+"""
+
+
+# Lazy imports via __getattr__ to prevent loading heavy dependencies
+# when hooks only need lightweight utilities
+def __getattr__(name):
+    """Lazy load core components only when accessed using dictionary-based mapping."""
+    from importlib import import_module
+
+    # Dictionary mapping: name -> (module_path, attribute_name)
+    _LAZY_IMPORTS = {
+        # Core components
+        "ClaudeRunner": ("claude_mpm.core.claude_runner", "ClaudeRunner"),
+        "Config": ("claude_mpm.core.config", "Config"),
+        # Dependency injection
+        "DIContainer": ("claude_mpm.core.container", "DIContainer"),
+        "ServiceLifetime": ("claude_mpm.core.container", "ServiceLifetime"),
+        "get_container": ("claude_mpm.core.container", "get_container"),
+        # Factories
+        "AgentServiceFactory": ("claude_mpm.core.factories", "AgentServiceFactory"),
+        "ConfigurationFactory": ("claude_mpm.core.factories", "ConfigurationFactory"),
+        "ServiceFactory": ("claude_mpm.core.factories", "ServiceFactory"),
+        "SessionManagerFactory": ("claude_mpm.core.factories", "SessionManagerFactory"),
+        "get_factory_registry": ("claude_mpm.core.factories", "get_factory_registry"),
+        # Services and utilities
+        "InjectableService": (
+            "claude_mpm.core.injectable_service",
+            "InjectableService",
+        ),
+        "LoggerMixin": ("claude_mpm.core.mixins", "LoggerMixin"),
+        # Service registry
+        "ServiceRegistry": ("claude_mpm.core.service_registry", "ServiceRegistry"),
+        "get_service_registry": (
+            "claude_mpm.core.service_registry",
+            "get_service_registry",
+        ),
+        "initialize_services": (
+            "claude_mpm.core.service_registry",
+            "initialize_services",
+        ),
+    }
+
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_path)
+        return getattr(module, attr_name)
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
 
 __all__ = [
     "AgentServiceFactory",

claude_mpm/core/agent_name_normalizer.py

@@ -1,9 +1,10 @@
 """Agent name normalization utilities for consistent naming across the system."""
 
-import logging
 from typing import Optional
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class AgentNameNormalizer:

claude_mpm/core/agent_registry.py

@@ -14,7 +14,7 @@ This module provides:
 import contextlib
 import warnings
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
 
@@ -379,7 +379,7 @@ class AgentRegistryAdapter:
         }
 
         nickname = nicknames.get(agent_name, agent_name.title())
-        today = datetime.now().strftime("%Y-%m-%d")
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
 
         return f"""**{nickname}**: {task}
 

claude_mpm/core/agent_session_manager.py

@@ -3,7 +3,7 @@
 import json
 import uuid
 from collections import defaultdict
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Dict, Optional
 
@@ -53,10 +53,10 @@ class AgentSessionManager:
             if not self.session_locks.get(session_id, False):
                 # Check if session is still fresh (not too old)
                 created = datetime.fromisoformat(session_data["created_at"])
-                if datetime.now() - created < timedelta(hours=1):
+                if datetime.now(timezone.utc) - created < timedelta(hours=1):
                     # Use this session
                     self.session_locks[session_id] = True
-                    session_data["last_used"] = datetime.now().isoformat()
+                    session_data["last_used"] = datetime.now(timezone.utc).isoformat()
                     session_data["use_count"] += 1
                     logger.info(f"Reusing session {session_id} for {agent_type} agent")
                     return session_id
@@ -85,8 +85,8 @@ class AgentSessionManager:
         session_data = {
             "id": session_id,
             "agent_type": agent_type,
-            "created_at": datetime.now().isoformat(),
-            "last_used": datetime.now().isoformat(),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "last_used": datetime.now(timezone.utc).isoformat(),
             "use_count": 0,
             "tasks_completed": [],
         }
@@ -122,7 +122,7 @@ class AgentSessionManager:
                 sessions[session_id]["tasks_completed"].append(
                     {
                         "task": task[:100],  # Truncate long tasks
-                        "timestamp": datetime.now().isoformat(),
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
                         "success": success,
                     }
                 )
@@ -135,7 +135,7 @@ class AgentSessionManager:
         Args:
             max_age_hours: Maximum age in hours
         """
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         max_age = timedelta(hours=max_age_hours)
 
         for agent_type in list(self.agent_sessions.keys()):
@@ -207,9 +207,9 @@ class AgentSessionManager:
         try:
             data = {
                 "agent_sessions": dict(self.agent_sessions),
-                "updated_at": datetime.now().isoformat(),
+                "updated_at": datetime.now(timezone.utc).isoformat(),
             }
-            with open(session_file, "w") as f:
+            with session_file.open("w") as f:
                 json.dump(data, f, indent=2)
         except Exception as e:
             logger.error(f"Failed to save agent sessions: {e}")
@@ -219,7 +219,7 @@ class AgentSessionManager:
         session_file = self.session_dir / "agent_sessions.json"
         if session_file.exists():
             try:
-                with open(session_file) as f:
+                with session_file.open() as f:
                     data = json.load(f)
                     self.agent_sessions = defaultdict(
                         dict, data.get("agent_sessions", {})

claude_mpm/core/api_validator.py

@@ -0,0 +1,330 @@
+"""API Key Validation Module for Claude MPM.
+
+This module validates API keys for various services on startup to ensure
+proper configuration and prevent runtime failures. It follows the principle
+of failing fast with clear error messages rather than degrading gracefully.
+"""
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+from claude_mpm.core.logger import get_logger
+
+
+class APIKeyValidator:
+    """Validates API keys for various services on framework startup."""
+
+    def __init__(self, config: Optional[Dict] = None):
+        """Initialize the API validator.
+
+        Args:
+            config: Optional configuration dictionary
+        """
+        self.logger = get_logger("api_validator")
+        self.config = config or {}
+        self.errors: List[str] = []
+        self.warnings: List[str] = []
+
+    def validate_all_keys(
+        self, strict: bool = True
+    ) -> Tuple[bool, List[str], List[str]]:
+        """Validate all configured API keys.
+
+        Args:
+            strict: If True, validation failures raise exceptions.
+                   If False, failures are logged as warnings.
+
+        Returns:
+            Tuple of (success, errors, warnings)
+        """
+        self.errors = []
+        self.warnings = []
+
+        # Check if validation is enabled
+        if not self.config.get("validate_api_keys", True):
+            self.logger.info("API key validation disabled in config")
+            return True, [], []
+
+        # Validate OpenAI key if configured
+        openai_key = os.getenv("OPENAI_API_KEY")
+        if openai_key:
+            self._validate_openai_key(openai_key)
+
+        # Validate Anthropic key if configured
+        anthropic_key = os.getenv("ANTHROPIC_API_KEY")
+        if anthropic_key:
+            self._validate_anthropic_key(anthropic_key)
+
+        # Validate GitHub token if configured
+        github_token = os.getenv("GITHUB_TOKEN")
+        if github_token:
+            self._validate_github_token(github_token)
+
+        # Validate custom API keys from config
+        custom_apis = self.config.get("custom_api_validations", {})
+        for api_name, validation_config in custom_apis.items():
+            self._validate_custom_api(api_name, validation_config)
+
+        # Report results
+        if self.errors:
+            error_msg = "API Key Validation Failed:\n" + "\n".join(self.errors)
+            if strict:
+                self.logger.error(error_msg)
+                raise ValueError(error_msg)
+            self.logger.warning(error_msg)
+
+        if self.warnings:
+            for warning in self.warnings:
+                self.logger.warning(warning)
+
+        if not self.errors:
+            self.logger.info("✅ All configured API keys validated successfully")
+
+        return not bool(self.errors), self.errors, self.warnings
+
+    def _validate_openai_key(self, api_key: str) -> bool:
+        """Validate OpenAI API key.
+
+        Args:
+            api_key: The OpenAI API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a lightweight request to validate the key
+            response = requests.get(
+                "https://api.openai.com/v1/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ OpenAI API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ OpenAI API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ OpenAI API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ OpenAI API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ OpenAI API returned unexpected status: {response.status_code}"
+            )
+            return True  # Assume valid for unexpected status codes
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ OpenAI API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to OpenAI API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ OpenAI API validation failed with error: {e}")
+            return False
+
+    def _validate_anthropic_key(self, api_key: str) -> bool:
+        """Validate Anthropic API key.
+
+        Args:
+            api_key: The Anthropic API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a minimal request to validate the key
+            # Using a very small max_tokens to minimize cost
+            response = requests.post(
+                "https://api.anthropic.com/v1/messages",
+                headers={
+                    "x-api-key": api_key,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                json={
+                    "model": "claude-3-haiku-20240307",  # Use cheapest model
+                    "messages": [{"role": "user", "content": "test"}],
+                    "max_tokens": 1,
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ Anthropic API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ Anthropic API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 400:
+                # Bad request but key is valid (we sent minimal request on purpose)
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ Anthropic API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ Anthropic API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ Anthropic API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to Anthropic API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ Anthropic API validation failed with error: {e}")
+            return False
+
+    def _validate_github_token(self, token: str) -> bool:
+        """Validate GitHub personal access token.
+
+        Args:
+            token: The GitHub token to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Check token validity with minimal request
+            response = requests.get(
+                "https://api.github.com/user",
+                headers={
+                    "Authorization": f"token {token}",
+                    "Accept": "application/vnd.github.v3+json",
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ GitHub token is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ GitHub token lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 200:
+                self.logger.debug("✅ GitHub token validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ GitHub API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ GitHub API validation timed out - assuming token is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to GitHub API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ GitHub token validation failed with error: {e}")
+            return False
+
+    def _validate_custom_api(self, api_name: str, validation_config: Dict) -> bool:
+        """Validate a custom API key based on configuration.
+
+        Args:
+            api_name: Name of the API
+            validation_config: Configuration for validating this API
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            env_var = validation_config.get("env_var")
+            if not env_var:
+                return True
+
+            api_key = os.getenv(env_var)
+            if not api_key:
+                return True  # Not configured, skip validation
+
+            # Get validation endpoint and method
+            endpoint = validation_config.get("endpoint")
+            method = validation_config.get("method", "GET").upper()
+            headers = validation_config.get("headers", {})
+
+            # Replace {API_KEY} placeholder in headers
+            for key, value in headers.items():
+                if isinstance(value, str):
+                    headers[key] = value.replace("{API_KEY}", api_key)
+
+            # Make validation request
+            if method == "GET":
+                response = requests.get(endpoint, headers=headers, timeout=10)
+            elif method == "POST":
+                body = validation_config.get("body", {})
+                response = requests.post(
+                    endpoint, headers=headers, json=body, timeout=10
+                )
+            else:
+                self.warnings.append(
+                    f"⚠️ Unsupported validation method for {api_name}: {method}"
+                )
+                return True
+
+            # Check expected status codes
+            valid_status_codes = validation_config.get("valid_status_codes", [200])
+            if response.status_code in valid_status_codes:
+                self.logger.debug(f"✅ {api_name} API key validated successfully")
+                return True
+            if response.status_code == 401:
+                self.errors.append(
+                    f"❌ {api_name} API key is invalid (401 Unauthorized)"
+                )
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    f"❌ {api_name} API key lacks permissions (403 Forbidden)"
+                )
+                return False
+            self.warnings.append(
+                f"⚠️ {api_name} API returned status: {response.status_code}"
+            )
+            return True
+
+        except Exception as e:
+            self.warnings.append(f"⚠️ {api_name} API validation failed: {e}")
+            return True
+
+
+def validate_api_keys(config: Optional[Dict] = None, strict: bool = True) -> bool:
+    """Convenience function to validate all API keys.
+
+    Args:
+        config: Optional configuration dictionary
+        strict: If True, raise exception on validation failure
+
+    Returns:
+        True if all validations passed, False otherwise
+
+    Raises:
+        ValueError: If strict=True and any validation fails
+    """
+    validator = APIKeyValidator(config)
+    success, _errors, _warnings = validator.validate_all_keys(strict=strict)
+    return success