runbooks 1.0.3__py3-none-any.whl → 1.1.0__py3-none-any.whl

runbooks/common/cli_decorators.py

@@ -0,0 +1,219 @@
+"""
+CLI Decorators for runbooks package - Enterprise CLI Standardization
+
+Provides standard decorators for common CLI options, eliminating code duplication
+and ensuring consistent user experience across all runbooks modules.
+
+Following KISS & DRY principles - enhance existing structure without creating complexity.
+"""
+
+import click
+from functools import wraps
+from typing import Callable, Any
+
+
+def common_aws_options(f: Callable) -> Callable:
+    """
+    Standard AWS options for all runbooks commands.
+
+    Provides consistent AWS configuration options across all modules:
+    - --profile: AWS profile override (highest priority in 3-tier system)
+    - --region: AWS region override
+    - --dry-run: Safe analysis mode (enterprise default)
+
+    Usage:
+        @common_aws_options
+        @click.command()
+        def my_command(profile, region, dry_run, **kwargs):
+            # Your command logic here
+    """
+    @click.option(
+        '--profile',
+        help='AWS profile override (highest priority over environment variables)',
+        type=str
+    )
+    @click.option(
+        '--region',
+        help='AWS region override (default: us-east-1)',
+        type=str,
+        default='us-east-1'
+    )
+    @click.option(
+        '--dry-run',
+        is_flag=True,
+        default=True,
+        help='Safe analysis mode - no resource modifications (enterprise default)'
+    )
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def common_output_options(f: Callable) -> Callable:
+    """
+    Standard output options for all runbooks commands.
+
+    Provides consistent output formatting and export options:
+    - --output-format: JSON, CSV, table, PDF output formats
+    - --output-dir: Output directory for generated files
+    - --export: Enable multi-format export capability
+
+    Usage:
+        @common_output_options
+        @click.command()
+        def my_command(output_format, output_dir, export, **kwargs):
+            # Your command logic here
+    """
+    @click.option(
+        '--output-format',
+        type=click.Choice(['json', 'csv', 'table', 'pdf', 'markdown'], case_sensitive=False),
+        default='table',
+        help='Output format for results display'
+    )
+    @click.option(
+        '--output-dir',
+        default='./awso_evidence',
+        help='Directory for generated files and evidence packages',
+        type=click.Path()
+    )
+    @click.option(
+        '--export',
+        is_flag=True,
+        help='Enable multi-format export (CSV, JSON, PDF, HTML)'
+    )
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def mcp_validation_option(f: Callable) -> Callable:
+    """
+    MCP validation option for cost optimization and inventory modules.
+
+    Provides MCP (Model Context Protocol) validation capability for enhanced accuracy:
+    - --validate: Enable MCP validation with ≥99.5% accuracy target
+    - --confidence-threshold: Minimum confidence threshold (default: 99.5%)
+
+    Usage:
+        @mcp_validation_option
+        @click.command()
+        def my_command(validate, confidence_threshold, **kwargs):
+            # Your command logic with MCP validation
+    """
+    @click.option(
+        '--validate',
+        is_flag=True,
+        help='Enable MCP validation for enhanced accuracy (≥99.5% target)'
+    )
+    @click.option(
+        '--confidence-threshold',
+        type=float,
+        default=99.5,
+        help='Minimum confidence threshold for validation (default: 99.5%%)'
+    )
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def enterprise_options(f: Callable) -> Callable:
+    """
+    Enterprise-specific options for multi-account operations.
+
+    Provides enterprise deployment options:
+    - --all: Use all available AWS profiles
+    - --combine: Combine profiles from same AWS account
+    - --approval-required: Require human approval for operations
+
+    Usage:
+        @enterprise_options
+        @click.command()
+        def my_command(all_profiles, combine, approval_required, **kwargs):
+            # Your enterprise command logic
+    """
+    @click.option(
+        '--all',
+        'all_profiles',
+        is_flag=True,
+        help='Use all available AWS profiles for multi-account operations'
+    )
+    @click.option(
+        '--combine',
+        is_flag=True,
+        help='Combine profiles from the same AWS account for unified reporting'
+    )
+    @click.option(
+        '--approval-required',
+        is_flag=True,
+        default=True,
+        help='Require human approval for state-changing operations (enterprise default)'
+    )
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def performance_options(f: Callable) -> Callable:
+    """
+    Performance monitoring options for enterprise operations.
+
+    Provides performance monitoring and optimization options:
+    - --performance-target: Target execution time in seconds
+    - --timeout: Maximum execution timeout
+    - --parallel: Enable parallel processing where supported
+
+    Usage:
+        @performance_options
+        @click.command()
+        def my_command(performance_target, timeout, parallel, **kwargs):
+            # Your performance-monitored command
+    """
+    @click.option(
+        '--performance-target',
+        type=int,
+        default=30,
+        help='Target execution time in seconds (enterprise default: 30s)'
+    )
+    @click.option(
+        '--timeout',
+        type=int,
+        default=300,
+        help='Maximum execution timeout in seconds (default: 5 minutes)'
+    )
+    @click.option(
+        '--parallel',
+        is_flag=True,
+        help='Enable parallel processing for multi-resource operations'
+    )
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper
+
+
+def all_standard_options(f: Callable) -> Callable:
+    """
+    Convenience decorator applying all standard options.
+
+    Combines common_aws_options, common_output_options, mcp_validation_option,
+    enterprise_options, and performance_options for comprehensive CLI commands.
+
+    Usage:
+        @all_standard_options
+        @click.command()
+        def comprehensive_command(**kwargs):
+            # Command with all standard options available
+    """
+    @performance_options
+    @enterprise_options
+    @mcp_validation_option
+    @common_output_options
+    @common_aws_options
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper

runbooks/common/error_handling.py

@@ -0,0 +1,424 @@
+"""
+Error Handling Enhancement for runbooks package - Enterprise Error Management
+
+Provides standardized error handling decorators and utilities that build upon the existing
+enhanced_exception_handler.py infrastructure while adding commonly needed patterns.
+
+Following KISS & DRY principles - enhance existing structure with practical decorators.
+"""
+
+import sys
+import time
+from functools import wraps
+from typing import Callable, Dict, Any, Optional
+
+from botocore.exceptions import ClientError, NoCredentialsError, PartialCredentialsError, ProfileNotFound
+
+from .rich_utils import print_error, print_warning, print_info, print_success, console
+from .enhanced_exception_handler import (
+    EnterpriseExceptionHandler,
+    ErrorContext,
+    create_exception_handler,
+    enhanced_error_handling
+)
+
+
+def handle_aws_errors(module_name: str = "runbooks", enable_recovery: bool = True):
+    """
+    Decorator for standardized AWS error handling with Rich CLI formatting.
+
+    Provides consistent error handling across all runbooks modules with:
+    - AWS-specific error classification and guidance
+    - Profile override recommendations
+    - Rich CLI formatted error messages
+    - Automatic recovery suggestions
+
+    Args:
+        module_name: Name of the module using this decorator
+        enable_recovery: Enable interactive error recovery workflows
+
+    Usage:
+        @handle_aws_errors(module_name="finops")
+        def my_aws_operation(profile=None, region=None, **kwargs):
+            # Your AWS operation code here
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            # Extract common parameters for error context
+            profile = kwargs.get('profile')
+            region = kwargs.get('region', 'us-east-1')
+            operation = kwargs.get('operation', f.__name__)
+
+            # Create error context
+            context = ErrorContext(
+                module_name=module_name,
+                operation=operation,
+                aws_profile=profile,
+                aws_region=region,
+                user_context=kwargs
+            )
+
+            # Create exception handler
+            handler = create_exception_handler(module_name, enable_rich_output=True)
+
+            try:
+                return f(*args, **kwargs)
+
+            except ClientError as e:
+                error_code = e.response.get('Error', {}).get('Code', 'Unknown')
+                service = e.operation_name if hasattr(e, 'operation_name') else 'AWS'
+
+                # Handle specific AWS errors with targeted guidance
+                if error_code == 'ExpiredToken':
+                    print_error("AWS SSO token expired")
+                    profile_name = profile or "your-profile"
+                    print_info(f"Run: [bold green]aws sso login --profile {profile_name}[/]")
+                    sys.exit(1)
+
+                elif error_code in ['AccessDenied', 'UnauthorizedOperation', 'Forbidden']:
+                    print_error(f"Access denied: {e.response['Error']['Message']}")
+                    print_warning("Check IAM permissions for this operation")
+
+                    # Provide profile recommendations
+                    if operation in ['finops', 'cost-analysis']:
+                        print_info("Try using billing profile: [bold green]--profile BILLING_PROFILE[/]")
+                    elif operation in ['inventory', 'organizations']:
+                        print_info("Try using management profile: [bold green]--profile MANAGEMENT_PROFILE[/]")
+                    elif operation in ['operate', 'resource-management']:
+                        print_info("Try using ops profile: [bold green]--profile CENTRALISED_OPS_PROFILE[/]")
+
+                    sys.exit(1)
+
+                elif error_code in ['Throttling', 'ThrottlingException', 'RequestLimitExceeded']:
+                    print_warning(f"AWS API throttling detected: {error_code}")
+                    print_info("Implementing automatic retry with backoff...")
+                    time.sleep(2)  # Basic backoff
+                    return f(*args, **kwargs)  # Retry once
+
+                else:
+                    # Use enterprise exception handler for complex cases
+                    enhanced_error = handler.handle_aws_error(e, context, operation)
+                    if enable_recovery and enhanced_error.retry_possible:
+                        handler.create_error_recovery_workflow(enhanced_error, interactive=False)
+                    sys.exit(1)
+
+            except (NoCredentialsError, PartialCredentialsError, ProfileNotFound) as e:
+                enhanced_error = handler.handle_credentials_error(e, context)
+                if enable_recovery:
+                    handler.create_error_recovery_workflow(enhanced_error, interactive=True)
+                sys.exit(1)
+
+            except ConnectionError as e:
+                print_error(f"Network connection failed: {str(e)}")
+                print_info("Check your internet connection and try again")
+                sys.exit(1)
+
+            except Exception as e:
+                print_error(f"Unexpected error in {operation}: {str(e)}")
+                if kwargs.get('debug') or kwargs.get('verbose'):
+                    console.print_exception()
+                sys.exit(1)
+
+        return wrapper
+    return decorator
+
+
+def handle_performance_errors(target_seconds: int = 30, module_name: str = "runbooks"):
+    """
+    Decorator for performance monitoring and error handling.
+
+    Monitors operation execution time and provides performance guidance
+    when operations exceed enterprise targets.
+
+    Args:
+        target_seconds: Target execution time in seconds
+        module_name: Name of the module for error context
+
+    Usage:
+        @handle_performance_errors(target_seconds=15, module_name="finops")
+        def my_operation(**kwargs):
+            # Your operation code here
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            start_time = time.time()
+            operation = kwargs.get('operation', f.__name__)
+
+            try:
+                result = f(*args, **kwargs)
+                execution_time = time.time() - start_time
+
+                # Performance feedback
+                if execution_time <= target_seconds:
+                    print_success(f"⚡ Performance: {execution_time:.1f}s (target: <{target_seconds}s)")
+                else:
+                    print_warning(f"⚠️ Performance: {execution_time:.1f}s (exceeded {target_seconds}s target)")
+
+                    # Provide optimization suggestions
+                    if execution_time > target_seconds * 2:  # Significantly exceeded
+                        print_info("Performance optimization suggestions:")
+                        print_info(f"  • Consider using --parallel for {operation}")
+                        print_info("  • Try a different AWS region for better performance")
+                        print_info("  • Check for API throttling or network issues")
+
+                        # Create performance error for enterprise tracking
+                        context = ErrorContext(
+                            module_name=module_name,
+                            operation=operation,
+                            performance_context={
+                                'execution_time': execution_time,
+                                'target_seconds': target_seconds,
+                                'performance_ratio': execution_time / target_seconds
+                            }
+                        )
+
+                        handler = create_exception_handler(module_name)
+                        handler.handle_performance_error(operation, execution_time, target_seconds, context)
+
+                return result
+
+            except Exception as e:
+                execution_time = time.time() - start_time
+                print_error(f"❌ Operation failed after {execution_time:.1f}s: {str(e)}")
+                raise
+
+        return wrapper
+    return decorator
+
+
+def handle_validation_errors(f: Callable) -> Callable:
+    """
+    Decorator for data validation error handling.
+
+    Provides clear guidance for data validation failures with
+    suggestions for correction.
+
+    Usage:
+        @handle_validation_errors
+        def my_validation_function(data, **kwargs):
+            # Your validation code here
+    """
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        try:
+            return f(*args, **kwargs)
+
+        except (ValueError, TypeError) as e:
+            error_msg = str(e)
+
+            if 'profile' in error_msg.lower():
+                print_error(f"Profile validation error: {error_msg}")
+                print_info("Check available profiles: [bold green]aws configure list-profiles[/]")
+
+            elif 'region' in error_msg.lower():
+                print_error(f"Region validation error: {error_msg}")
+                print_info("Use valid AWS region like: [bold green]us-east-1, us-west-2, eu-west-1[/]")
+
+            elif 'format' in error_msg.lower():
+                print_error(f"Format validation error: {error_msg}")
+                print_info("Supported formats: [bold green]json, csv, table, pdf, markdown[/]")
+
+            else:
+                print_error(f"Data validation error: {error_msg}")
+                print_info("Review input parameters and try again")
+
+            sys.exit(1)
+
+        except Exception as e:
+            print_error(f"Validation failed: {str(e)}")
+            raise
+
+    return wrapper
+
+
+def graceful_degradation(fallback_function: Optional[Callable] = None,
+                        enable_fallback: bool = True):
+    """
+    Decorator for graceful degradation with fallback operations.
+
+    Automatically attempts fallback operations when primary operation fails,
+    providing seamless user experience with transparent recovery.
+
+    Args:
+        fallback_function: Optional fallback function to use
+        enable_fallback: Enable automatic fallback attempts
+
+    Usage:
+        @graceful_degradation(fallback_function=simple_analysis)
+        def complex_analysis(**kwargs):
+            # Complex operation that might fail
+
+        # Or with automatic fallback detection
+        @graceful_degradation()
+        def main_operation(**kwargs):
+            # Will attempt fallback_operation if this fails
+
+        def fallback_operation(**kwargs):
+            # Simpler fallback version
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            operation = kwargs.get('operation', f.__name__)
+
+            try:
+                print_info(f"🚀 Attempting primary operation: {operation}")
+                return f(*args, **kwargs)
+
+            except Exception as primary_error:
+                print_warning(f"⚠️ Primary operation failed: {operation}")
+                print_info(f"Error: {str(primary_error)}")
+
+                if not enable_fallback:
+                    raise primary_error
+
+                # Try fallback function if provided
+                if fallback_function:
+                    try:
+                        print_info(f"🔄 Attempting fallback: {fallback_function.__name__}")
+                        result = fallback_function(*args, **kwargs)
+                        print_success(f"✅ Fallback operation succeeded: {fallback_function.__name__}")
+                        return result
+
+                    except Exception as fallback_error:
+                        print_error(f"❌ Fallback operation failed: {fallback_function.__name__}")
+                        print_error(f"Primary error: {str(primary_error)}")
+                        print_error(f"Fallback error: {str(fallback_error)}")
+                        raise primary_error
+
+                # Try to find automatic fallback based on naming convention
+                fallback_name = f"fallback_{f.__name__}"
+                if hasattr(f.__module__, fallback_name):
+                    try:
+                        fallback_func = getattr(f.__module__, fallback_name)
+                        print_info(f"🔄 Attempting automatic fallback: {fallback_name}")
+                        result = fallback_func(*args, **kwargs)
+                        print_success(f"✅ Automatic fallback succeeded: {fallback_name}")
+                        return result
+
+                    except Exception:
+                        pass
+
+                # No fallback available, raise original error
+                print_error("❌ No fallback available, operation failed")
+                raise primary_error
+
+        return wrapper
+    return decorator
+
+
+def enterprise_error_context(module_name: str):
+    """
+    Context manager for enterprise error handling with comprehensive logging.
+
+    Provides enterprise-grade error handling with audit trails, performance
+    monitoring, and comprehensive error analysis.
+
+    Usage:
+        with enterprise_error_context("finops") as ctx:
+            ctx.set_operation("cost_analysis")
+            ctx.set_profile("BILLING_PROFILE")
+            # Your operation code here
+    """
+    class EnterpriseErrorContext:
+        def __init__(self, module_name: str):
+            self.module_name = module_name
+            self.handler = create_exception_handler(module_name)
+            self.context = ErrorContext(module_name=module_name, operation="unknown")
+
+        def set_operation(self, operation: str):
+            self.context.operation = operation
+
+        def set_profile(self, profile: str):
+            self.context.aws_profile = profile
+
+        def set_region(self, region: str):
+            self.context.aws_region = region
+
+        def add_user_context(self, **kwargs):
+            self.context.user_context.update(kwargs)
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc_value, traceback):
+            if exc_value is not None:
+                enhanced_error = self.handler.handle_exception(
+                    exc_value,
+                    self.context,
+                    {'context_manager': True}
+                )
+
+                # Try recovery for retryable errors
+                if enhanced_error.retry_possible:
+                    recovery_success = self.handler.create_error_recovery_workflow(
+                        enhanced_error,
+                        interactive=False
+                    )
+                    if recovery_success:
+                        return True  # Suppress exception
+
+            return False  # Let exception propagate
+
+    return EnterpriseErrorContext(module_name)
+
+
+# Utility functions for common error scenarios
+def validate_aws_profile(profile: str) -> bool:
+    """
+    Validate AWS profile exists and is accessible.
+
+    Args:
+        profile: AWS profile name to validate
+
+    Returns:
+        True if profile is valid and accessible
+
+    Raises:
+        SystemExit if profile validation fails
+    """
+    try:
+        import boto3
+        session = boto3.Session(profile_name=profile)
+        sts = session.client('sts')
+        identity = sts.get_caller_identity()
+        print_success(f"Profile validation successful: {profile}")
+        print_info(f"Account: {identity.get('Account', 'Unknown')}")
+        print_info(f"User: {identity.get('Arn', 'Unknown')}")
+        return True
+
+    except ProfileNotFound:
+        print_error(f"AWS profile not found: {profile}")
+        print_info("Check available profiles: [bold green]aws configure list-profiles[/]")
+        sys.exit(1)
+
+    except Exception as e:
+        print_error(f"Profile validation failed: {profile}")
+        print_error(f"Error: {str(e)}")
+        sys.exit(1)
+
+
+def check_aws_connectivity(region: str = 'us-east-1') -> bool:
+    """
+    Check basic AWS connectivity and service availability.
+
+    Args:
+        region: AWS region to test connectivity
+
+    Returns:
+        True if connectivity is successful
+    """
+    try:
+        import boto3
+        session = boto3.Session()
+        sts = session.client('sts', region_name=region)
+        sts.get_caller_identity()
+        print_success(f"AWS connectivity verified: {region}")
+        return True
+
+    except Exception as e:
+        print_warning(f"AWS connectivity issue: {str(e)}")
+        print_info("Check internet connection and AWS service status")
+        return False