claude-mpm 3.9.11__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/utils/error_handler.py

@@ -6,73 +6,84 @@ Inspired by awesome-claude-code's comprehensive error handling approach.
 
 import logging
 import sys
-from typing import Optional, Type, Callable, Any, Dict, List
-from functools import wraps
 import traceback
 from datetime import datetime
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, Type
 
 logger = logging.getLogger(__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()
-    
+
     def get_user_friendly_message(self) -> str:
         """Get a user-friendly error message."""
         lines = [f"❌ Error: {str(self)}"]
-        
+
         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 +92,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
-        
+
         # 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 +183,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 +208,17 @@ 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 decorator
 
 
@@ -209,18 +227,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 +248,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

@@ -13,22 +13,19 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, Optional, Union
 
-
-class FileOperationError(Exception):
-    """Exception raised for file operation errors."""
-    pass
+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
     """
@@ -36,46 +33,71 @@ def ensure_directory(path: Union[str, Path]) -> Path:
     try:
         path.mkdir(parents=True, exist_ok=True)
         return path
-    except Exception as e:
-        raise FileOperationError(f"Failed to create directory {path}: {e}")
+    except (OSError, PermissionError) as e:
+        raise FileOperationError(
+            f"Failed to create directory: {e}",
+            context={
+                "path": str(path),
+                "operation": "mkdir",
+                "error_type": type(e).__name__,
+            },
+        )
 
 
-def safe_read_file(path: Union[str, Path], encoding: str = 'utf-8') -> str:
+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 Exception as e:
-        raise FileOperationError(f"Failed to read file {path}: {e}")
+    except FileNotFoundError as e:
+        raise FileOperationError(
+            f"File not found: {path}",
+            context={
+                "path": str(path),
+                "operation": "read",
+                "encoding": encoding,
+                "error_type": "FileNotFoundError",
+            },
+        )
+    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__,
+            },
+        )
 
 
 def safe_write_file(
-    path: Union[str, Path], 
-    content: str, 
-    encoding: str = 'utf-8',
-    create_dirs: bool = True
+    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
     """
@@ -89,22 +111,22 @@ def safe_write_file(
 
 
 def atomic_write(
-    path: Union[str, Path], 
-    content: str, 
-    encoding: str = 'utf-8',
-    create_dirs: bool = True
+    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
     """
@@ -112,25 +134,21 @@ def atomic_write(
     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'
+            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():
+            if "temp_path" in locals():
                 os.unlink(temp_path)
         except:
             pass
@@ -140,10 +158,10 @@ def atomic_write(
 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
     """
@@ -151,7 +169,7 @@ def get_file_info(path: Union[str, Path]) -> Optional[Dict[str, Any]]:
     try:
         if not path.exists():
             return None
-            
+
         stat = path.stat()
         return {
             "path": str(path),
@@ -160,40 +178,38 @@ def get_file_info(path: Union[str, Path]) -> Optional[Dict[str, Any]]:
             "created": stat.st_ctime,
             "is_file": path.is_file(),
             "is_dir": path.is_dir(),
-            "permissions": oct(stat.st_mode)[-3:]
+            "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
+    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}")
 
@@ -201,13 +217,13 @@ def safe_copy_file(
 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
     """
@@ -224,13 +240,13 @@ def safe_remove_file(path: Union[str, Path]) -> bool:
 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
     """
@@ -242,20 +258,17 @@ def read_json_file(path: Union[str, Path]) -> Any:
 
 
 def write_json_file(
-    path: Union[str, Path], 
-    data: Any, 
-    indent: int = 2,
-    atomic: bool = True
+    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
     """
@@ -269,23 +282,23 @@ def write_json_file(
         raise FileOperationError(f"Failed to write JSON file {path}: {e}")
 
 
-def backup_file(path: Union[str, Path], backup_suffix: str = '.backup') -> Path:
+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

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