claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/services/core/models/stability.py

@@ -0,0 +1,264 @@
+"""
+Stability Monitoring Data Models for Claude MPM Framework
+===========================================================
+
+WHY: This module defines data structures for stability monitoring operations,
+including memory leak detection, log pattern matching, and resource usage tracking.
+
+DESIGN DECISION: Uses dataclasses for immutability and type safety. Provides
+clear data structures for proactive monitoring and crash prevention.
+
+ARCHITECTURE:
+- MemoryTrend: Memory usage trend analysis with leak detection
+- LogPatternMatch: Log pattern match with severity and context
+- ResourceUsage: Comprehensive resource usage snapshot
+"""
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List
+
+
+@dataclass
+class MemoryTrend:
+    """
+    Memory usage trend analysis result.
+
+    WHY: Provides structured data for memory leak detection, including
+    historical measurements, slope calculation, and leak detection status.
+
+    Attributes:
+        deployment_id: Unique deployment identifier
+        timestamps: List of measurement timestamps
+        memory_mb: List of memory measurements in megabytes
+        slope_mb_per_minute: Calculated memory growth rate (MB/minute)
+        is_leaking: Whether a memory leak was detected
+        window_size: Number of measurements in the analysis window
+        threshold_mb_per_minute: Leak detection threshold used
+    """
+
+    deployment_id: str
+    timestamps: List[datetime] = field(default_factory=list)
+    memory_mb: List[float] = field(default_factory=list)
+    slope_mb_per_minute: float = 0.0
+    is_leaking: bool = False
+    window_size: int = 0
+    threshold_mb_per_minute: float = 10.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation with datetimes converted to ISO format
+        """
+        data = asdict(self)
+        data["timestamps"] = [ts.isoformat() for ts in self.timestamps]
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryTrend":
+        """
+        Create MemoryTrend from dictionary.
+
+        Args:
+            data: Dictionary from JSON deserialization
+
+        Returns:
+            MemoryTrend instance
+        """
+        # Convert ISO strings to datetime
+        if isinstance(data.get("timestamps"), list):
+            data["timestamps"] = [
+                datetime.fromisoformat(ts) if isinstance(ts, str) else ts
+                for ts in data["timestamps"]
+            ]
+
+        return cls(**data)
+
+    @property
+    def latest_memory_mb(self) -> float:
+        """Get the most recent memory measurement."""
+        return self.memory_mb[-1] if self.memory_mb else 0.0
+
+    @property
+    def oldest_memory_mb(self) -> float:
+        """Get the oldest memory measurement in the window."""
+        return self.memory_mb[0] if self.memory_mb else 0.0
+
+    @property
+    def time_span_minutes(self) -> float:
+        """Get the time span covered by the measurements in minutes."""
+        if len(self.timestamps) < 2:
+            return 0.0
+        delta = self.timestamps[-1] - self.timestamps[0]
+        return delta.total_seconds() / 60.0
+
+
+@dataclass
+class LogPatternMatch:
+    """
+    Result of a log pattern match.
+
+    WHY: Contains all information about a detected error pattern in logs,
+    enabling analysis, alerting, and debugging of issues before they cause crashes.
+
+    Attributes:
+        deployment_id: Unique deployment identifier
+        pattern: Regex pattern that matched
+        line: The log line that matched
+        timestamp: When the match was detected
+        severity: Error severity level (ERROR, CRITICAL, WARNING)
+        line_number: Line number in log file (if available)
+        context: Additional context lines (before/after)
+    """
+
+    deployment_id: str
+    pattern: str
+    line: str
+    timestamp: datetime = field(default_factory=datetime.now)
+    severity: str = "ERROR"
+    line_number: int = 0
+    context: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation with datetime converted to ISO format
+        """
+        data = asdict(self)
+        data["timestamp"] = self.timestamp.isoformat()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LogPatternMatch":
+        """
+        Create LogPatternMatch from dictionary.
+
+        Args:
+            data: Dictionary from JSON deserialization
+
+        Returns:
+            LogPatternMatch instance
+        """
+        # Convert ISO string to datetime
+        if isinstance(data.get("timestamp"), str):
+            data["timestamp"] = datetime.fromisoformat(data["timestamp"])
+
+        return cls(**data)
+
+    @property
+    def is_critical(self) -> bool:
+        """Check if this match represents a critical error."""
+        return self.severity == "CRITICAL"
+
+
+@dataclass
+class ResourceUsage:
+    """
+    Comprehensive resource usage snapshot.
+
+    WHY: Provides detailed resource consumption metrics across multiple
+    resource types to enable preemptive action before exhaustion.
+
+    Attributes:
+        deployment_id: Unique deployment identifier
+        file_descriptors: Current file descriptor count
+        max_file_descriptors: Maximum file descriptors allowed (ulimit -n)
+        threads: Current thread count
+        connections: Current network connection count
+        disk_free_mb: Free disk space in working directory (MB)
+        is_critical: Whether any resource exceeds 80% threshold
+        timestamp: When the measurement was taken
+        details: Additional resource-specific details
+    """
+
+    deployment_id: str
+    file_descriptors: int = 0
+    max_file_descriptors: int = 0
+    threads: int = 0
+    connections: int = 0
+    disk_free_mb: float = 0.0
+    is_critical: bool = False
+    timestamp: datetime = field(default_factory=datetime.now)
+    details: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation with datetime converted to ISO format
+        """
+        data = asdict(self)
+        data["timestamp"] = self.timestamp.isoformat()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ResourceUsage":
+        """
+        Create ResourceUsage from dictionary.
+
+        Args:
+            data: Dictionary from JSON deserialization
+
+        Returns:
+            ResourceUsage instance
+        """
+        # Convert ISO string to datetime
+        if isinstance(data.get("timestamp"), str):
+            data["timestamp"] = datetime.fromisoformat(data["timestamp"])
+
+        return cls(**data)
+
+    @property
+    def fd_usage_percent(self) -> float:
+        """Calculate file descriptor usage percentage."""
+        if self.max_file_descriptors == 0:
+            return 0.0
+        return (self.file_descriptors / self.max_file_descriptors) * 100.0
+
+    @property
+    def is_fd_critical(self) -> bool:
+        """Check if file descriptor usage is critical (>80%)."""
+        return self.fd_usage_percent >= 80.0  # >= instead of > for 80% exactly
+
+    def get_critical_resources(self) -> List[str]:
+        """
+        Get list of resources at critical levels.
+
+        Returns:
+            List of resource names exceeding 80% threshold
+        """
+        critical = []
+
+        if self.is_fd_critical:
+            critical.append(
+                f"file_descriptors ({self.file_descriptors}/{self.max_file_descriptors})"
+            )
+
+        # Check thread count (threshold from details if available)
+        thread_threshold = self.details.get("thread_threshold", 1000)
+        if self.threads > thread_threshold * 0.8:
+            critical.append(f"threads ({self.threads})")
+
+        # Check connection count (threshold from details if available)
+        connection_threshold = self.details.get("connection_threshold", 500)
+        if self.connections > connection_threshold * 0.8:
+            critical.append(f"connections ({self.connections})")
+
+        # Check disk space (threshold from details if available)
+        disk_threshold_mb = self.details.get("disk_threshold_mb", 100)
+        if self.disk_free_mb < disk_threshold_mb:
+            critical.append(f"disk_space ({self.disk_free_mb:.1f}MB free)")
+
+        return critical
+
+
+__all__ = [
+    "LogPatternMatch",
+    "MemoryTrend",
+    "ResourceUsage",
+]

claude_mpm/services/core/models/toolchain.py

@@ -0,0 +1,306 @@
+"""
+Toolchain Data Models for Claude MPM Framework
+==============================================
+
+WHY: These models represent the structure of project toolchain analysis results.
+They provide a standardized way to represent detected languages, frameworks,
+deployment targets, and overall toolchain characteristics.
+
+DESIGN DECISION: Uses dataclasses with field validation and default values
+to ensure data consistency. Confidence levels are included to represent
+uncertainty in detection. Immutable where possible to prevent accidental
+modification of analysis results.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 1
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence level for detection results.
+
+    WHY: Not all detections are equally certain. This enum provides a
+    standardized way to communicate confidence levels to users and
+    enable threshold-based decision making.
+    """
+
+    HIGH = "high"  # >80% confidence, very strong indicators
+    MEDIUM = "medium"  # 50-80% confidence, good indicators
+    LOW = "low"  # 20-50% confidence, weak indicators
+    VERY_LOW = "very_low"  # <20% confidence, speculative
+
+
+@dataclass(frozen=True)
+class ToolchainComponent:
+    """Represents a component in the project's toolchain.
+
+    WHY: Toolchain components (languages, frameworks, tools) share common
+    attributes like name, version, and confidence. This base model enables
+    consistent representation across different component types.
+
+    DESIGN DECISION: Frozen dataclass to prevent modification after creation,
+    ensuring analysis results remain consistent. Version is optional as not
+    all components have detectable versions.
+    """
+
+    name: str
+    version: Optional[str] = None
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate component data after initialization."""
+        if not self.name or not self.name.strip():
+            raise ValueError("Component name cannot be empty")
+        if self.version is not None and not self.version.strip():
+            raise ValueError("Component version cannot be empty string")
+
+
+@dataclass(frozen=True)
+class LanguageDetection:
+    """Result of language detection analysis.
+
+    WHY: Projects often use multiple languages. This model captures both
+    primary (main codebase) and secondary (scripts, config) languages
+    with their relative proportions and confidence levels.
+
+    DESIGN DECISION: Includes percentage breakdown to help understand
+    language distribution. Confidence per language enables threshold-based
+    filtering of uncertain detections.
+    """
+
+    primary_language: str
+    primary_version: Optional[str] = None
+    primary_confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    secondary_languages: List[ToolchainComponent] = field(default_factory=list)
+    language_percentages: Dict[str, float] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate language detection data."""
+        if not self.primary_language or not self.primary_language.strip():
+            raise ValueError("Primary language cannot be empty")
+
+        # Validate language percentages sum to ~100% (allow small floating point error)
+        if self.language_percentages:
+            total = sum(self.language_percentages.values())
+            if not (99.0 <= total <= 101.0):
+                raise ValueError(f"Language percentages must sum to 100%, got {total}%")
+
+    @property
+    def all_languages(self) -> List[str]:
+        """Get list of all detected languages (primary + secondary)."""
+        languages = [self.primary_language]
+        languages.extend(comp.name for comp in self.secondary_languages)
+        return languages
+
+    @property
+    def high_confidence_languages(self) -> List[str]:
+        """Get languages detected with high confidence."""
+        languages = []
+        if self.primary_confidence == ConfidenceLevel.HIGH:
+            languages.append(self.primary_language)
+        languages.extend(
+            comp.name
+            for comp in self.secondary_languages
+            if comp.confidence == ConfidenceLevel.HIGH
+        )
+        return languages
+
+
+@dataclass(frozen=True)
+class Framework:
+    """Represents a detected framework or library.
+
+    WHY: Frameworks are critical for agent recommendation as different agents
+    specialize in different frameworks. This model captures framework identity,
+    version, type, and usage characteristics.
+
+    DESIGN DECISION: Includes framework type (web, testing, ORM, etc.) to
+    enable category-based recommendations. Popularity metric helps prioritize
+    agent recommendations for commonly-used frameworks.
+    """
+
+    name: str
+    version: Optional[str] = None
+    framework_type: Optional[str] = None  # web, testing, orm, cli, etc.
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    is_dev_dependency: bool = False
+    popularity_score: float = 0.0  # 0.0-1.0, higher = more popular/used
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate framework data."""
+        if not self.name or not self.name.strip():
+            raise ValueError("Framework name cannot be empty")
+        if not (0.0 <= self.popularity_score <= 1.0):
+            raise ValueError(
+                f"Popularity score must be 0.0-1.0, got {self.popularity_score}"
+            )
+
+    @property
+    def display_name(self) -> str:
+        """Get formatted display name with version."""
+        if self.version:
+            return f"{self.name} {self.version}"
+        return self.name
+
+
+@dataclass(frozen=True)
+class DeploymentTarget:
+    """Represents the detected deployment target environment.
+
+    WHY: Deployment target affects agent recommendations (e.g., DevOps agents
+    for Kubernetes, serverless agents for Lambda). This model captures the
+    deployment platform and configuration details.
+
+    DESIGN DECISION: Includes target type (cloud, container, serverless, etc.)
+    and platform-specific configuration. Confidence level enables fallback
+    to generic recommendations when deployment target is unclear.
+    """
+
+    target_type: str  # cloud, container, serverless, on-premise, edge
+    platform: Optional[str] = None  # aws, gcp, azure, kubernetes, docker, etc.
+    configuration: Dict[str, Any] = field(default_factory=dict)
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    requires_ops_agent: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate deployment target data."""
+        valid_types = {"cloud", "container", "serverless", "on-premise", "edge"}
+        if self.target_type not in valid_types:
+            raise ValueError(
+                f"Invalid target_type '{self.target_type}'. "
+                f"Must be one of: {valid_types}"
+            )
+
+    @property
+    def display_name(self) -> str:
+        """Get formatted display name."""
+        if self.platform:
+            return f"{self.target_type} ({self.platform})"
+        return self.target_type
+
+
+@dataclass
+class ToolchainAnalysis:
+    """Complete toolchain analysis result.
+
+    WHY: This is the primary output of toolchain analysis, aggregating all
+    detected components into a single structure. It provides a complete
+    picture of the project's technical stack.
+
+    DESIGN DECISION: Not frozen to allow caching and updating of analysis
+    results. Includes project_path for reference and validation. Provides
+    convenience methods for common queries (e.g., has framework, get languages).
+    """
+
+    project_path: Path
+    language_detection: LanguageDetection
+    frameworks: List[Framework] = field(default_factory=list)
+    deployment_target: Optional[DeploymentTarget] = None
+    build_tools: List[ToolchainComponent] = field(default_factory=list)
+    package_managers: List[ToolchainComponent] = field(default_factory=list)
+    development_tools: List[ToolchainComponent] = field(default_factory=list)
+    overall_confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    analysis_timestamp: Optional[float] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate toolchain analysis data."""
+        if not self.project_path.exists():
+            raise ValueError(f"Project path does not exist: {self.project_path}")
+        if not self.project_path.is_dir():
+            raise ValueError(f"Project path is not a directory: {self.project_path}")
+
+    def has_framework(self, framework_name: str) -> bool:
+        """Check if a specific framework is detected."""
+        return any(fw.name.lower() == framework_name.lower() for fw in self.frameworks)
+
+    def get_framework(self, framework_name: str) -> Optional[Framework]:
+        """Get framework by name (case-insensitive)."""
+        for fw in self.frameworks:
+            if fw.name.lower() == framework_name.lower():
+                return fw
+        return None
+
+    def get_frameworks_by_type(self, framework_type: str) -> List[Framework]:
+        """Get all frameworks of a specific type."""
+        return [
+            fw
+            for fw in self.frameworks
+            if fw.framework_type and fw.framework_type.lower() == framework_type.lower()
+        ]
+
+    @property
+    def primary_language(self) -> str:
+        """Get the primary language detected."""
+        return self.language_detection.primary_language
+
+    @property
+    def all_languages(self) -> List[str]:
+        """Get all detected languages."""
+        return self.language_detection.all_languages
+
+    @property
+    def web_frameworks(self) -> List[Framework]:
+        """Get all web frameworks."""
+        return self.get_frameworks_by_type("web")
+
+    @property
+    def is_web_project(self) -> bool:
+        """Check if this appears to be a web project."""
+        return len(self.web_frameworks) > 0
+
+    @property
+    def requires_devops_agent(self) -> bool:
+        """Check if project likely needs DevOps agent."""
+        if self.deployment_target and self.deployment_target.requires_ops_agent:
+            return True
+        # Check for containerization
+        return any(
+            tool.name.lower() in {"docker", "kubernetes", "terraform"}
+            for tool in self.development_tools
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert analysis to dictionary for serialization."""
+        return {
+            "project_path": str(self.project_path),
+            "language_detection": {
+                "primary_language": self.language_detection.primary_language,
+                "primary_version": self.language_detection.primary_version,
+                "primary_confidence": self.language_detection.primary_confidence.value,
+                "secondary_languages": [
+                    {"name": lang.name, "version": lang.version}
+                    for lang in self.language_detection.secondary_languages
+                ],
+                "language_percentages": self.language_detection.language_percentages,
+            },
+            "frameworks": [
+                {
+                    "name": fw.name,
+                    "version": fw.version,
+                    "type": fw.framework_type,
+                    "confidence": fw.confidence.value,
+                }
+                for fw in self.frameworks
+            ],
+            "deployment_target": (
+                {
+                    "type": self.deployment_target.target_type,
+                    "platform": self.deployment_target.platform,
+                    "confidence": self.deployment_target.confidence.value,
+                }
+                if self.deployment_target
+                else None
+            ),
+            "build_tools": [tool.name for tool in self.build_tools],
+            "package_managers": [pm.name for pm in self.package_managers],
+            "overall_confidence": self.overall_confidence.value,
+            "metadata": self.metadata,
+        }

claude_mpm/services/core/path_resolver.py

@@ -13,6 +13,7 @@ that was previously embedded in FrameworkLoader. It manages:
 The service consolidates path management logic while maintaining backward compatibility.
 """
 
+import os
 import subprocess
 from enum import Enum
 from pathlib import Path
@@ -74,10 +75,25 @@ class PathResolver(IPathResolver):
             return path_obj
 
         if base_dir is None:
-            base_dir = Path.cwd()
+            base_dir = self._get_working_dir()
 
         return (base_dir / path_obj).resolve()
 
+    def _get_working_dir(self) -> Path:
+        """Get working directory respecting CLAUDE_MPM_USER_PWD.
+
+        When Claude MPM runs from a global installation, CLAUDE_MPM_USER_PWD
+        contains the user's actual working directory. This ensures project-local
+        paths are resolved correctly.
+
+        Returns:
+            Path: The user's working directory
+        """
+        user_pwd = os.environ.get("CLAUDE_MPM_USER_PWD")
+        if user_pwd:
+            return Path(user_pwd)
+        return Path.cwd()
+
     def validate_path(self, path: Path, must_exist: bool = False) -> bool:
         """
         Validate a path for security and existence.
@@ -129,7 +145,7 @@ class PathResolver(IPathResolver):
             Project root path or None if not found
         """
         if start_path is None:
-            start_path = Path.cwd()
+            start_path = self._get_working_dir()
 
         start_path = start_path.resolve()
 
@@ -265,7 +281,7 @@ class PathResolver(IPathResolver):
 
         if agents_dir and agents_dir.exists():
             discovered_agents_dir = agents_dir
-            self.logger.info(f"Using custom agents directory: {discovered_agents_dir}")
+            self.logger.debug(f"Using custom agents directory: {discovered_agents_dir}")
         elif framework_path and framework_path != Path("__PACKAGED__"):
             # Prioritize templates directory over main agents directory
             templates_dir = (
@@ -299,7 +315,7 @@ class PathResolver(IPathResolver):
         paths = {"project": None, "user": None, "system": None}
 
         # Project-specific instructions
-        project_path = Path.cwd() / ".claude-mpm" / "INSTRUCTIONS.md"
+        project_path = self._get_working_dir() / ".claude-mpm" / "INSTRUCTIONS.md"
         if project_path.exists():
             paths["project"] = project_path
 
@@ -423,11 +439,11 @@ class PathResolver(IPathResolver):
         """Check common locations for claude-mpm."""
         candidates = [
             # Current directory (if we're already in claude-mpm)
-            Path.cwd(),
+            self._get_working_dir(),
             # Development location
             Path.home() / "Projects" / "claude-mpm",
             # Current directory subdirectory
-            Path.cwd() / "claude-mpm",
+            self._get_working_dir() / "claude-mpm",
         ]
 
         for candidate in candidates:
@@ -487,7 +503,7 @@ class PathResolver(IPathResolver):
             pass
 
         # Check if we're in development
-        if (Path.cwd() / "pyproject.toml").exists():
+        if (self._get_working_dir() / "pyproject.toml").exists():
             return DeploymentContext.DEVELOPMENT
 
         return DeploymentContext.UNKNOWN

claude_mpm/services/diagnostics/__init__.py

@@ -13,6 +13,6 @@ DESIGN DECISIONS:
 
 from .diagnostic_runner import DiagnosticRunner
 from .doctor_reporter import DoctorReporter
-from .models import DiagnosticResult, DiagnosticStatus
+from .models import DiagnosticResult
 
-__all__ = ["DiagnosticResult", "DiagnosticRunner", "DiagnosticStatus", "DoctorReporter"]
+__all__ = ["DiagnosticResult", "DiagnosticRunner", "DoctorReporter"]