roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/result.py

@@ -0,0 +1,396 @@
+"""Result type for functional error handling.
+
+This module provides a Result[T, E] type for railway-oriented programming,
+enabling explicit error handling without exceptions. Based on Rust's Result type.
+
+Examples:
+    >>> def divide(a: int, b: int) -> Result[float, str]:
+    ...     if b == 0:
+    ...         return Err("Division by zero")
+    ...     return Ok(a / b)
+    ...
+    >>> result = divide(10, 2)
+    >>> if result.is_ok():
+    ...     print(f"Success: {result.unwrap()}")
+    ...
+    >>> result = divide(10, 0)
+    >>> if result.is_err():
+    ...     print(f"Error: {result.unwrap_err()}")
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, NoReturn, TypeVar, Union
+
+T = TypeVar("T")  # Success type
+E = TypeVar("E")  # Error type
+U = TypeVar("U")  # Mapped success type
+
+
+@dataclass(frozen=True)
+class Ok(Generic[T]):
+    """Success variant of Result type.
+
+    Contains a successful value of type T.
+
+    Attributes:
+        value: The successful result value
+    """
+
+    value: T
+
+    def is_ok(self) -> bool:
+        """Check if this is an Ok variant.
+
+        Returns:
+            Always True for Ok
+        """
+        return True
+
+    def is_err(self) -> bool:
+        """Check if this is an Err variant.
+
+        Returns:
+            Always False for Ok
+        """
+        return False
+
+    def unwrap(self) -> T:
+        """Extract the success value.
+
+        Returns:
+            The contained value
+        """
+        return self.value
+
+    def unwrap_err(self) -> NoReturn:
+        """Attempt to extract error (raises exception).
+
+        Raises:
+            ValueError: Always, since Ok doesn't contain an error
+        """
+        raise ValueError(f"Called unwrap_err() on Ok value: {self.value}")
+
+    def unwrap_or(self, default: T) -> T:
+        """Extract value or return default.
+
+        Args:
+            default: Value to return if this is Err (unused)
+
+        Returns:
+            The contained value
+        """
+        return self.value
+
+    def unwrap_or_else(self, op: Callable[[E], T]) -> T:
+        """Extract value or compute from error.
+
+        Args:
+            op: Function to compute default from error (unused)
+
+        Returns:
+            The contained value
+        """
+        return self.value
+
+    def map(self, op: Callable[[T], U]) -> Result[U, E]:
+        """Map the success value through a function.
+
+        Args:
+            op: Function to transform the value
+
+        Returns:
+            Ok with transformed value
+        """
+        return Ok(op(self.value))
+
+    def map_err(self, op: Callable[[E], Any]) -> Result[T, Any]:
+        """Map the error through a function (no-op for Ok).
+
+        Args:
+            op: Function to transform error (unused)
+
+        Returns:
+            Self unchanged
+        """
+        return self
+
+    def and_then(self, op: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Chain another Result-returning operation.
+
+        Also known as flatMap or bind. Enables railway-oriented programming.
+
+        Args:
+            op: Function that takes success value and returns new Result
+
+        Returns:
+            Result from applying op to contained value
+        """
+        return op(self.value)
+
+    def or_else(self, op: Callable[[E], Result[T, Any]]) -> Result[T, Any]:
+        """Provide alternative on error (no-op for Ok).
+
+        Args:
+            op: Function to compute alternative Result (unused)
+
+        Returns:
+            Self unchanged
+        """
+        return self
+
+
+@dataclass(frozen=True)
+class Err(Generic[E]):
+    """Error variant of Result type.
+
+    Contains an error value of type E.
+
+    Attributes:
+        error: The error value
+    """
+
+    error: E
+
+    def is_ok(self) -> bool:
+        """Check if this is an Ok variant.
+
+        Returns:
+            Always False for Err
+        """
+        return False
+
+    def is_err(self) -> bool:
+        """Check if this is an Err variant.
+
+        Returns:
+            Always True for Err
+        """
+        return True
+
+    def unwrap(self) -> NoReturn:
+        """Attempt to extract value (raises exception).
+
+        Raises:
+            ValueError: Always, since Err doesn't contain a value
+        """
+        raise ValueError(f"Called unwrap() on Err value: {self.error}")
+
+    def unwrap_err(self) -> E:
+        """Extract the error value.
+
+        Returns:
+            The contained error
+        """
+        return self.error
+
+    def unwrap_or(self, default: T) -> T:
+        """Extract value or return default.
+
+        Args:
+            default: Value to return since this is Err
+
+        Returns:
+            The default value
+        """
+        return default
+
+    def unwrap_or_else(self, op: Callable[[E], T]) -> T:
+        """Extract value or compute from error.
+
+        Args:
+            op: Function to compute default from error
+
+        Returns:
+            Result of applying op to the error
+        """
+        return op(self.error)
+
+    def map(self, op: Callable[[T], U]) -> Result[U, E]:
+        """Map the success value through a function (no-op for Err).
+
+        Args:
+            op: Function to transform value (unused)
+
+        Returns:
+            Self unchanged (with correct type)
+        """
+        return Err(self.error)
+
+    def map_err(self, op: Callable[[E], Any]) -> Result[T, Any]:
+        """Map the error through a function.
+
+        Args:
+            op: Function to transform the error
+
+        Returns:
+            Err with transformed error
+        """
+        return Err(op(self.error))
+
+    def and_then(self, op: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Chain another Result-returning operation (no-op for Err).
+
+        Args:
+            op: Function to chain (unused)
+
+        Returns:
+            Self unchanged (with correct type)
+        """
+        return Err(self.error)
+
+    def or_else(self, op: Callable[[E], Result[T, Any]]) -> Result[T, Any]:
+        """Provide alternative on error.
+
+        Args:
+            op: Function to compute alternative Result from error
+
+        Returns:
+            Result from applying op to error
+        """
+        return op(self.error)
+
+
+# Type alias for Result[T, E]
+Result = Union[Ok[T], Err[E]]
+
+
+# Helper functions for working with Results
+
+
+def wrap_result(func: Callable[..., T]) -> Callable[..., Result[T, Exception]]:
+    """Decorator to convert exception-raising functions to Result-returning.
+
+    Catches any exception and returns it as Err, or Ok on success.
+
+    Args:
+        func: Function that may raise exceptions
+
+    Returns:
+        Wrapped function that returns Result[T, Exception]
+
+    Example:
+        >>> @wrap_result
+        ... def may_fail(x: int) -> int:
+        ...     if x < 0:
+        ...         raise ValueError("Negative")
+        ...     return x * 2
+        ...
+        >>> result = may_fail(5)  # Ok(10)
+        >>> result = may_fail(-1)  # Err(ValueError("Negative"))
+    """
+
+    def wrapper(*args: Any, **kwargs: Any) -> Result[T, Exception]:
+        try:
+            return Ok(func(*args, **kwargs))
+        except Exception as e:
+            return Err(e)
+
+    return wrapper
+
+
+def collect_results(results: list[Result[T, E]]) -> Result[list[T], E]:
+    """Collect a list of Results into a Result of list.
+
+    Returns Ok with list of all success values if all Results are Ok.
+    Returns the first Err if any Result is Err.
+
+    Args:
+        results: List of Result values
+
+    Returns:
+        Ok with list of values, or first Err encountered
+
+    Example:
+        >>> results = [Ok(1), Ok(2), Ok(3)]
+        >>> collect_results(results)  # Ok([1, 2, 3])
+        >>>
+        >>> results = [Ok(1), Err("fail"), Ok(3)]
+        >>> collect_results(results)  # Err("fail")
+    """
+    values: list[T] = []
+    for result in results:
+        if result.is_err():
+            return result  # type: ignore[return-value]
+        values.append(result.unwrap())
+    return Ok(values)
+
+
+def partition_results(results: list[Result[T, E]]) -> tuple[list[T], list[E]]:
+    """Partition a list of Results into successes and errors.
+
+    Args:
+        results: List of Result values
+
+    Returns:
+        Tuple of (success_values, error_values)
+
+    Example:
+        >>> results = [Ok(1), Err("a"), Ok(2), Err("b")]
+        >>> successes, errors = partition_results(results)
+        >>> successes  # [1, 2]
+        >>> errors  # ["a", "b"]
+    """
+    successes: list[T] = []
+    errors: list[E] = []
+    for result in results:
+        if result.is_ok():
+            successes.append(result.unwrap())
+        else:
+            errors.append(result.unwrap_err())
+    return successes, errors
+
+
+def all_ok(results: list[Result[T, E]]) -> bool:
+    """Check if all Results in a list are Ok.
+
+    Args:
+        results: List of Result values
+
+    Returns:
+        True if all are Ok, False if any are Err
+    """
+    return all(r.is_ok() for r in results)
+
+
+def any_err(results: list[Result[T, E]]) -> bool:
+    """Check if any Results in a list are Err.
+
+    Args:
+        results: List of Result values
+
+    Returns:
+        True if any are Err, False if all are Ok
+    """
+    return any(r.is_err() for r in results)
+
+
+def first_err(results: list[Result[T, E]]) -> Result[None, E]:
+    """Get the first error from a list of Results.
+
+    Args:
+        results: List of Result values
+
+    Returns:
+        First Err found, or Ok(None) if all are Ok
+    """
+    for result in results:
+        if result.is_err():
+            return Err(result.unwrap_err())
+    return Ok(None)
+
+
+# Export public API
+__all__ = [
+    "Ok",
+    "Err",
+    "Result",
+    "wrap_result",
+    "collect_results",
+    "partition_results",
+    "all_ok",
+    "any_err",
+    "first_err",
+]

roadmap/common/security/__init__.py

@@ -0,0 +1,48 @@
+"""Security utilities for roadmap CLI application.
+
+This package provides security functionality organized by concern:
+- exceptions: Security exception types
+- logging: Security event logging
+- path_validation: Path validation and safety checks
+- file_operations: Secure file and directory operations
+- filename_sanitization: Filename sanitization
+- temp_files: Secure temporary file handling
+- export_cleanup: Export validation and backup cleanup
+
+For backward compatibility, all public classes and functions are re-exported
+from the root module.
+"""
+
+from .exceptions import PathValidationError, SecurityError
+from .export_cleanup import cleanup_old_backups, validate_export_size
+from .file_operations import (
+    create_secure_directory,
+    create_secure_file,
+    secure_file_permissions,
+)
+from .filename_sanitization import sanitize_filename
+from .logging import log_security_event, security_logger
+from .path_validation import validate_path
+from .temp_files import create_secure_temp_file
+
+__all__ = [
+    # Exceptions
+    "SecurityError",
+    "PathValidationError",
+    # Logging
+    "log_security_event",
+    "security_logger",
+    # Path validation
+    "validate_path",
+    # File operations
+    "create_secure_file",
+    "create_secure_directory",
+    "secure_file_permissions",
+    # Filename sanitization
+    "sanitize_filename",
+    # Temp files
+    "create_secure_temp_file",
+    # Export/backup
+    "validate_export_size",
+    "cleanup_old_backups",
+]

roadmap/common/security/exceptions.py

@@ -0,0 +1,13 @@
+"""Security exceptions."""
+
+
+class SecurityError(Exception):
+    """Base exception for security-related errors."""
+
+    pass
+
+
+class PathValidationError(SecurityError):
+    """Exception raised for path validation failures."""
+
+    pass

roadmap/common/security/export_cleanup.py

@@ -0,0 +1,79 @@
+"""Export validation and backup cleanup utilities."""
+
+import time
+from pathlib import Path
+
+from .exceptions import SecurityError
+from .logging import log_security_event
+
+
+def validate_export_size(file_path: Path, max_size_mb: int = 100) -> None:
+    """Validate that an export file isn't too large.
+
+    Args:
+        file_path: Path to the export file
+        max_size_mb: Maximum allowed size in MB
+
+    Raises:
+        SecurityError: If file is too large
+    """
+    if not file_path.exists():
+        return
+
+    file_size_mb = file_path.stat().st_size / (1024 * 1024)
+
+    if file_size_mb > max_size_mb:
+        log_security_event(
+            "large_export_detected",
+            {
+                "path": str(file_path),
+                "size_mb": file_size_mb,
+                "max_size_mb": max_size_mb,
+            },
+        )
+        raise SecurityError(
+            f"Export file too large: {file_size_mb:.1f}MB > {max_size_mb}MB"
+        )
+
+
+def cleanup_old_backups(backup_dir: Path, retention_days: int = 30) -> int:
+    """Clean up old backup files for security.
+
+    Args:
+        backup_dir: Directory containing backup files
+        retention_days: Number of days to retain backups
+
+    Returns:
+        Number of files cleaned up
+    """
+    if not backup_dir.exists():
+        return 0
+
+    cutoff_time = time.time() - (retention_days * 24 * 60 * 60)
+    cleaned_count = 0
+
+    try:
+        for backup_file in backup_dir.glob("*.backup*"):
+            if backup_file.stat().st_mtime < cutoff_time:
+                backup_file.unlink()
+                cleaned_count += 1
+
+                log_security_event(
+                    "backup_cleaned",
+                    {
+                        "path": str(backup_file),
+                        "age_days": (time.time() - backup_file.stat().st_mtime)
+                        / (24 * 60 * 60),
+                    },
+                )
+
+        if cleaned_count > 0:
+            log_security_event(
+                "backup_cleanup_completed",
+                {"files_cleaned": cleaned_count, "retention_days": retention_days},
+            )
+
+    except Exception as e:
+        log_security_event("backup_cleanup_failed", {"error": str(e)})
+
+    return cleaned_count

roadmap/common/security/file_operations.py

@@ -0,0 +1,104 @@
+"""Secure file and directory operations."""
+
+from contextlib import contextmanager
+from pathlib import Path
+
+from ..utils.file_utils import ensure_directory_exists
+from .exceptions import SecurityError
+from .logging import log_security_event
+
+
+@contextmanager
+def create_secure_file(
+    path: str | Path, mode: str = "w", permissions: int = 0o600, **kwargs
+):
+    """Create a file with secure permissions as a context manager.
+
+    Args:
+        path: Path to the file to create
+        mode: File open mode (default: 'w')
+        permissions: File permissions (default: owner read/write only)
+        **kwargs: Additional arguments passed to open()
+
+    Yields:
+        File object
+
+    Raises:
+        SecurityError: If file creation fails or permissions cannot be set
+    """
+    path = Path(path)
+
+    try:
+        # Create parent directories if they don't exist
+        ensure_directory_exists(path.parent)
+
+        # Open file with specified mode
+        with open(path, mode, **kwargs) as f:
+            # Set secure permissions after file is created
+            try:
+                path.chmod(permissions)
+            except (OSError, PermissionError) as e:
+                # Log warning but don't fail - permissions might not be changeable
+                log_security_event(
+                    "permission_warning", {"path": str(path), "error": str(e)}
+                )
+
+            log_security_event(
+                "file_created", {"path": str(path), "permissions": oct(permissions)}
+            )
+
+            yield f
+
+    except Exception as e:
+        log_security_event("file_creation_failed", {"path": str(path), "error": str(e)})
+        raise SecurityError(f"Failed to create secure file {path}: {e}") from e
+
+
+def create_secure_directory(path: Path, permissions: int = 0o700) -> None:
+    """Create a directory with secure permissions.
+
+    Args:
+        path: Path to the directory to create
+        permissions: Directory permissions (default: owner only)
+
+    Raises:
+        SecurityError: If directory creation fails
+    """
+    try:
+        ensure_directory_exists(path, permissions=permissions)
+        # Note: ensure_directory_exists already sets permissions
+
+        log_security_event(
+            "directory_created", {"path": str(path), "permissions": oct(permissions)}
+        )
+    except Exception as e:
+        log_security_event(
+            "directory_creation_failed", {"path": str(path), "error": str(e)}
+        )
+        raise SecurityError(f"Failed to create secure directory {path}: {e}") from e
+
+
+def secure_file_permissions(path: Path, permissions: int = 0o600) -> None:
+    """Set secure permissions on an existing file.
+
+    Args:
+        path: Path to the file
+        permissions: Permissions to set (default: owner read/write only)
+
+    Raises:
+        SecurityError: If permission setting fails
+    """
+    try:
+        if not path.exists():
+            raise SecurityError(f"File does not exist: {path}")
+
+        path.chmod(permissions)
+
+        log_security_event(
+            "permissions_set", {"path": str(path), "permissions": oct(permissions)}
+        )
+    except Exception as e:
+        log_security_event(
+            "permission_setting_failed", {"path": str(path), "error": str(e)}
+        )
+        raise SecurityError(f"Failed to set secure permissions on {path}: {e}") from e

roadmap/common/security/filename_sanitization.py

@@ -0,0 +1,54 @@
+"""Filename sanitization utilities."""
+
+import os
+import re
+
+from .exceptions import SecurityError
+from .logging import log_security_event
+
+
+def sanitize_filename(filename: str, max_length: int = 255) -> str:
+    """Sanitize a filename to prevent security issues.
+
+    Args:
+        filename: Original filename
+        max_length: Maximum allowed filename length
+
+    Returns:
+        Sanitized filename
+    """
+    if not filename:
+        raise SecurityError("Filename cannot be empty")
+
+    # Remove or replace dangerous characters
+    # Windows: < > : " | ? * \0
+    # Unix: \0 /
+    # Generally dangerous: .. (relative path)
+
+    # Replace dangerous characters with underscores
+    sanitized = re.sub(r'[<>:"/\\|?*\0]', "_", filename)
+
+    # Replace relative path attempts
+    sanitized = sanitized.replace("..", "_")
+
+    # Remove leading/trailing whitespace and dots
+    sanitized = sanitized.strip(" .")
+
+    # Truncate to max length
+    if len(sanitized) > max_length:
+        name, ext = os.path.splitext(sanitized)
+        if ext:
+            max_name_length = max_length - len(ext)
+            sanitized = name[:max_name_length] + ext
+        else:
+            sanitized = sanitized[:max_length]
+
+    # Ensure we still have a valid filename
+    if not sanitized or sanitized in {".", ".."}:
+        sanitized = "safe_filename"
+
+    log_security_event(
+        "filename_sanitized", {"original": filename, "sanitized": sanitized}
+    )
+
+    return sanitized