claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/utils/error_handler.py

@@ -6,73 +6,77 @@ Inspired by awesome-claude-code's comprehensive error handling approach.
 
 import logging
 import sys
-from typing import Optional, Type, Callable, Any, Dict
+from datetime import datetime, timezone
 from functools import wraps
-import traceback
-from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Type
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class MPMError(Exception):
     """Base exception for claude-mpm errors."""
-    
-    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None, 
-                 suggestions: Optional[List[str]] = None):
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        suggestions: Optional[List[str]] = None,
+    ):
         """Initialize MPM error with details and suggestions."""
         super().__init__(message)
         self.details = details or {}
         self.suggestions = suggestions or []
-        self.timestamp = datetime.now()
-    
+        self.timestamp = datetime.now(timezone.utc)
+
     def get_user_friendly_message(self) -> str:
         """Get a user-friendly error message."""
-        lines = [f"❌ Error: {str(self)}"]
-        
+        lines = [f"❌ Error: {self!s}"]
+
         if self.details:
             lines.append("\nDetails:")
             for key, value in self.details.items():
                 lines.append(f"  {key}: {value}")
-        
+
         if self.suggestions:
             lines.append("\n💡 Suggestions:")
             for suggestion in self.suggestions:
                 lines.append(f"  - {suggestion}")
-        
-        return '\n'.join(lines)
+
+        return "\n".join(lines)
 
 
 class AgentLoadError(MPMError):
     """Raised when agent loading fails."""
-    pass
 
 
 class ValidationError(MPMError):
     """Raised when validation fails."""
-    pass
 
 
 class ExecutionError(MPMError):
     """Raised when agent execution fails."""
-    pass
 
 
 class ConfigurationError(MPMError):
     """Raised when configuration is invalid."""
-    pass
 
 
-def handle_errors(error_type: Type[Exception] = Exception, 
-                 fallback_value: Any = None,
-                 log_level: int = logging.ERROR) -> Callable:
+def handle_errors(
+    error_type: Type[Exception] = Exception,
+    fallback_value: Any = None,
+    log_level: int = logging.ERROR,
+) -> Callable:
     """
     Decorator for handling errors with detailed logging and user feedback.
-    
+
     Args:
         error_type: Type of exception to catch
         fallback_value: Value to return on error
         log_level: Logging level for errors
     """
+
     def decorator(func: Callable) -> Callable:
         @wraps(func)
         def wrapper(*args, **kwargs):
@@ -81,76 +85,82 @@ def handle_errors(error_type: Type[Exception] = Exception,
             except error_type as e:
                 # Log the error with full traceback
                 logger.log(log_level, f"Error in {func.__name__}: {e}", exc_info=True)
-                
+
                 # Provide user-friendly feedback
                 if isinstance(e, MPMError):
                     print(e.get_user_friendly_message(), file=sys.stderr)
                 else:
                     print(f"❌ Error: {e}", file=sys.stderr)
-                
+
                 return fallback_value
             except Exception as e:
                 # Catch unexpected errors
-                logger.critical(f"Unexpected error in {func.__name__}: {e}", exc_info=True)
+                logger.critical(
+                    f"Unexpected error in {func.__name__}: {e}", exc_info=True
+                )
                 print(f"❌ Unexpected error: {e}", file=sys.stderr)
                 print("💡 This might be a bug. Please report it.", file=sys.stderr)
                 return fallback_value
-        
+
         return wrapper
+
     return decorator
 
 
 class ErrorContext:
     """Context manager for enhanced error reporting."""
-    
+
     def __init__(self, operation: str, details: Optional[Dict[str, Any]] = None):
         """Initialize error context."""
         self.operation = operation
         self.details = details or {}
-    
+
     def __enter__(self):
         """Enter the context."""
         logger.debug(f"Starting operation: {self.operation}")
         return self
-    
+
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Exit the context, handling any errors."""
         if exc_type is None:
             logger.debug(f"Completed operation: {self.operation}")
-            return
-        
+            return None
+
         # Log the error with context
         logger.error(
             f"Error during {self.operation}: {exc_val}",
-            extra={'operation': self.operation, 'details': self.details},
-            exc_info=True
+            extra={"operation": self.operation, "details": self.details},
+            exc_info=True,
         )
-        
+
         # Don't suppress the exception
         return False
 
 
-def retry_on_error(max_attempts: int = 3, 
-                  delay: float = 1.0,
-                  backoff_factor: float = 2.0,
-                  exceptions: tuple = (Exception,)) -> Callable:
+def retry_on_error(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple = (Exception,),
+) -> Callable:
     """
     Decorator for retrying operations on error.
-    
+
     Args:
         max_attempts: Maximum number of attempts
         delay: Initial delay between attempts
         backoff_factor: Multiplier for delay after each failure
         exceptions: Tuple of exceptions to retry on
     """
+
     def decorator(func: Callable) -> Callable:
         @wraps(func)
         async def async_wrapper(*args, **kwargs):
             import asyncio
-            
+
             last_exception = None
             current_delay = delay
-            
+
             for attempt in range(max_attempts):
                 try:
                     return await func(*args, **kwargs)
@@ -166,16 +176,16 @@ def retry_on_error(max_attempts: int = 3,
                         logger.error(
                             f"All {max_attempts} attempts failed for {func.__name__}"
                         )
-            
+
             raise last_exception
-        
+
         @wraps(func)
         def sync_wrapper(*args, **kwargs):
             import time
-            
+
             last_exception = None
             current_delay = delay
-            
+
             for attempt in range(max_attempts):
                 try:
                     return func(*args, **kwargs)
@@ -191,16 +201,16 @@ def retry_on_error(max_attempts: int = 3,
                         logger.error(
                             f"All {max_attempts} attempts failed for {func.__name__}"
                         )
-            
+
             raise last_exception
-        
+
         # Return appropriate wrapper based on function type
         import asyncio
+
         if asyncio.iscoroutinefunction(func):
             return async_wrapper
-        else:
-            return sync_wrapper
-    
+        return sync_wrapper
+
     return decorator
 
 
@@ -209,18 +219,20 @@ def format_exception_chain(exc: Exception) -> str:
     lines = []
     current = exc
     level = 0
-    
+
     while current is not None:
         indent = "  " * level
-        lines.append(f"{indent}{'└─' if level > 0 else ''}{type(current).__name__}: {current}")
-        
-        if hasattr(current, '__cause__'):
+        lines.append(
+            f"{indent}{'└─' if level > 0 else ''}{type(current).__name__}: {current}"
+        )
+
+        if hasattr(current, "__cause__"):
             current = current.__cause__
             level += 1
         else:
             break
-    
-    return '\n'.join(lines)
+
+    return "\n".join(lines)
 
 
 # Setup patterns from awesome-claude-code
@@ -228,20 +240,20 @@ def suggest_setup_fix(error: Exception) -> List[str]:
     """Suggest fixes for common setup errors."""
     suggestions = []
     error_msg = str(error).lower()
-    
-    if 'git' in error_msg and 'not found' in error_msg:
+
+    if "git" in error_msg and "not found" in error_msg:
         suggestions.append("Install git from https://git-scm.com/downloads")
-    
-    if 'python' in error_msg and 'module' in error_msg:
+
+    if "python" in error_msg and "module" in error_msg:
         suggestions.append("Ensure you're in a virtual environment")
         suggestions.append("Run: pip install -e .")
-    
-    if 'permission' in error_msg:
+
+    if "permission" in error_msg:
         suggestions.append("Check file permissions")
         suggestions.append("You may need to run with appropriate privileges")
-    
-    if 'config' in error_msg or 'configuration' in error_msg:
+
+    if "config" in error_msg or "configuration" in error_msg:
         suggestions.append("Check your configuration files")
         suggestions.append("Run: mpm validate-config")
-    
-    return suggestions
+
+    return suggestions

claude_mpm/utils/file_utils.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""
+File utilities for Claude MPM.
+
+This module provides safe file operations with atomic writes,
+error handling, and directory management.
+"""
+
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from ..core.exceptions import FileOperationError
+
+
+def ensure_directory(path: Union[str, Path]) -> Path:
+    """
+    Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Directory path to ensure exists
+
+    Returns:
+        Path object for the directory
+
+    Raises:
+        FileOperationError: If directory cannot be created
+    """
+    path = Path(path)
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+    except (OSError, PermissionError) as e:
+        raise FileOperationError(
+            f"Failed to create directory: {e}",
+            context={
+                "path": str(path),
+                "operation": "mkdir",
+                "error_type": type(e).__name__,
+            },
+        ) from e
+
+
+def safe_read_file(path: Union[str, Path], encoding: str = "utf-8") -> str:
+    """
+    Safely read a file with error handling.
+
+    Args:
+        path: File path to read
+        encoding: Text encoding to use
+
+    Returns:
+        File contents as string
+
+    Raises:
+        FileOperationError: If file cannot be read
+    """
+    path = Path(path)
+    try:
+        return path.read_text(encoding=encoding)
+    except FileNotFoundError as e:
+        raise FileOperationError(
+            f"File not found: {path}",
+            context={
+                "path": str(path),
+                "operation": "read",
+                "encoding": encoding,
+                "error_type": "FileNotFoundError",
+            },
+        ) from e
+    except (OSError, PermissionError, UnicodeDecodeError) as e:
+        raise FileOperationError(
+            f"Failed to read file: {e}",
+            context={
+                "path": str(path),
+                "operation": "read",
+                "encoding": encoding,
+                "error_type": type(e).__name__,
+            },
+        ) from e
+
+
+def safe_write_file(
+    path: Union[str, Path],
+    content: str,
+    encoding: str = "utf-8",
+    create_dirs: bool = True,
+) -> None:
+    """
+    Safely write content to a file with directory creation.
+
+    Args:
+        path: File path to write
+        content: Content to write
+        encoding: Text encoding to use
+        create_dirs: Whether to create parent directories
+
+    Raises:
+        FileOperationError: If file cannot be written
+    """
+    path = Path(path)
+    try:
+        if create_dirs:
+            ensure_directory(path.parent)
+        path.write_text(content, encoding=encoding)
+    except Exception as e:
+        raise FileOperationError(f"Failed to write file {path}: {e}") from e
+
+
+def atomic_write(
+    path: Union[str, Path],
+    content: str,
+    encoding: str = "utf-8",
+    create_dirs: bool = True,
+) -> None:
+    """
+    Atomically write content to a file using a temporary file.
+
+    This prevents corruption if the write operation is interrupted.
+
+    Args:
+        path: File path to write
+        content: Content to write
+        encoding: Text encoding to use
+        create_dirs: Whether to create parent directories
+
+    Raises:
+        FileOperationError: If file cannot be written atomically
+    """
+    path = Path(path)
+    try:
+        if create_dirs:
+            ensure_directory(path.parent)
+
+        # Write to temporary file first
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding=encoding, dir=path.parent, delete=False, suffix=".tmp"
+        ) as temp_file:
+            temp_file.write(content)
+            temp_path = temp_file.name
+
+        # Atomically move temporary file to target
+        shutil.move(temp_path, path)
+
+    except Exception as e:
+        # Clean up temporary file if it exists
+        try:
+            if "temp_path" in locals():
+                Path(temp_path).unlink()
+        except Exception:
+            pass
+        raise FileOperationError(f"Failed to atomically write file {path}: {e}") from e
+
+
+def get_file_info(path: Union[str, Path]) -> Optional[Dict[str, Any]]:
+    """
+    Get file metadata safely.
+
+    Args:
+        path: File path to examine
+
+    Returns:
+        Dictionary with file information or None if file doesn't exist
+    """
+    path = Path(path)
+    try:
+        if not path.exists():
+            return None
+
+        stat = path.stat()
+        return {
+            "path": str(path),
+            "size": stat.st_size,
+            "modified": stat.st_mtime,
+            "created": stat.st_ctime,
+            "is_file": path.is_file(),
+            "is_dir": path.is_dir(),
+            "permissions": oct(stat.st_mode)[-3:],
+        }
+    except Exception:
+        return None
+
+
+def safe_copy_file(
+    src: Union[str, Path], dst: Union[str, Path], create_dirs: bool = True
+) -> None:
+    """
+    Safely copy a file with error handling.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+        create_dirs: Whether to create destination directories
+
+    Raises:
+        FileOperationError: If file cannot be copied
+    """
+    src = Path(src)
+    dst = Path(dst)
+
+    try:
+        if not src.exists():
+            raise FileOperationError(f"Source file does not exist: {src}")
+
+        if create_dirs:
+            ensure_directory(dst.parent)
+
+        shutil.copy2(src, dst)
+
+    except Exception as e:
+        raise FileOperationError(f"Failed to copy {src} to {dst}: {e}") from e
+
+
+def safe_remove_file(path: Union[str, Path]) -> bool:
+    """
+    Safely remove a file.
+
+    Args:
+        path: File path to remove
+
+    Returns:
+        True if file was removed, False if it didn't exist
+
+    Raises:
+        FileOperationError: If file cannot be removed
+    """
+    path = Path(path)
+    try:
+        if not path.exists():
+            return False
+        path.unlink()
+        return True
+    except Exception as e:
+        raise FileOperationError(f"Failed to remove file {path}: {e}") from e
+
+
+def read_json_file(path: Union[str, Path]) -> Any:
+    """
+    Read and parse a JSON file safely.
+
+    Args:
+        path: JSON file path
+
+    Returns:
+        Parsed JSON data
+
+    Raises:
+        FileOperationError: If file cannot be read or parsed
+    """
+    try:
+        content = safe_read_file(path)
+        return json.loads(content)
+    except json.JSONDecodeError as e:
+        raise FileOperationError(f"Invalid JSON in file {path}: {e}") from e
+
+
+def write_json_file(
+    path: Union[str, Path], data: Any, indent: int = 2, atomic: bool = True
+) -> None:
+    """
+    Write data to a JSON file safely.
+
+    Args:
+        path: JSON file path
+        data: Data to serialize to JSON
+        indent: JSON indentation level
+        atomic: Whether to use atomic write
+
+    Raises:
+        FileOperationError: If file cannot be written
+    """
+    try:
+        content = json.dumps(data, indent=indent, ensure_ascii=False)
+        if atomic:
+            atomic_write(path, content)
+        else:
+            safe_write_file(path, content)
+    except Exception as e:
+        raise FileOperationError(f"Failed to write JSON file {path}: {e}") from e
+
+
+def backup_file(path: Union[str, Path], backup_suffix: str = ".backup") -> Path:
+    """
+    Create a backup copy of a file.
+
+    Args:
+        path: File path to backup
+        backup_suffix: Suffix to add to backup filename
+
+    Returns:
+        Path to the backup file
+
+    Raises:
+        FileOperationError: If backup cannot be created
+    """
+    path = Path(path)
+    backup_path = path.with_suffix(path.suffix + backup_suffix)
+
+    try:
+        safe_copy_file(path, backup_path)
+        return backup_path
+    except Exception as e:
+        raise FileOperationError(f"Failed to create backup of {path}: {e}") from e

claude_mpm/utils/framework_detection.py

@@ -1,39 +1,40 @@
+from pathlib import Path
+
 """Framework source directory detection utilities.
 
 WHY: This module provides utilities to detect if we're in the framework source directory
 to prevent accidental overwrites of the template files during deployment.
 """
 
-from pathlib import Path
-from typing import Tuple, List
+from typing import List, Tuple
 
 
 def is_framework_source_directory(path: Path) -> Tuple[bool, List[str]]:
     """
     Check if the given path is the framework source directory.
-    
+
     WHY: We need to prevent deployment to the framework source directory itself
     to avoid overwriting template files.
-    
+
     Args:
         path: Path to check
-        
+
     Returns:
         Tuple of (is_framework_source, list of detected markers)
     """
     markers = []
-    
+
     # Check for framework source markers
     if (path / "src" / "claude_mpm").exists():
         markers.append("src/claude_mpm")
-    
+
     if (path / "pyproject.toml").exists():
         markers.append("pyproject.toml")
-    
+
     if (path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md").exists():
         markers.append("framework INSTRUCTIONS.md template")
-    
+
     # If we have multiple markers, it's likely the framework source
     is_framework = len(markers) >= 2
-    
-    return is_framework, markers
+
+    return is_framework, markers