roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/security/logging.py

@@ -0,0 +1,27 @@
+"""Security event logging utilities."""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from structlog import get_logger
+
+# Security logger
+security_logger = get_logger()
+
+
+def log_security_event(event_type: str, details: dict[str, Any] | None = None) -> None:
+    """Log a security event with structured data.
+
+    Args:
+        event_type: Type of security event
+        details: Additional event details
+    """
+    if details is None:
+        details = {}
+
+    # Log as structured data
+    security_logger.info(
+        event_type,
+        timestamp=datetime.now(UTC).isoformat(),
+        **details,
+    )

roadmap/common/security/path_validation.py

@@ -0,0 +1,137 @@
+"""Path validation and security utilities."""
+
+from pathlib import Path
+
+from .exceptions import PathValidationError
+from .logging import log_security_event
+
+
+def _check_traversal_patterns(path_str: str, allow_absolute: bool) -> None:
+    """Check for directory traversal patterns."""
+    if ".." in path_str and not allow_absolute:
+        raise PathValidationError(
+            f"Path contains potential directory traversal: {path_str}"
+        )
+
+
+def _resolve_path_safely(path: Path) -> Path:
+    """Resolve path safely, handling missing directories."""
+    try:
+        return path.resolve()
+    except (FileNotFoundError, OSError):
+        # If resolve() fails due to missing current directory, handle gracefully
+        if path.is_absolute():
+            return path
+        else:
+            # For relative paths when cwd is missing, return as-is (caller context should handle)
+            return path
+
+
+def _resolve_relative_to_base(path: Path, base_dir: Path) -> Path:
+    """Resolve path relative to base directory."""
+    try:
+        return path.resolve()
+    except (FileNotFoundError, OSError):
+        # If resolve fails, work with absolute version or relative to base
+        if path.is_absolute():
+            return path
+        else:
+            return base_dir / path
+
+
+def _resolve_base_safely(base_dir: Path) -> Path:
+    """Resolve base directory safely."""
+    try:
+        return base_dir.resolve()
+    except (FileNotFoundError, OSError):
+        return base_dir
+
+
+def _check_absolute_allowed(path: Path, allow_absolute: bool) -> None:
+    """Check if absolute path is allowed."""
+    if not allow_absolute and path.is_absolute():
+        raise PathValidationError(f"Absolute paths not allowed: {path}")
+
+
+def _check_within_base(
+    resolved_path: Path, resolved_base: Path, original_path: Path
+) -> None:
+    """Check if path is within base directory."""
+    try:
+        resolved_path.relative_to(resolved_base)
+    except ValueError as e:
+        raise PathValidationError(
+            f"Path outside allowed directory: {original_path}"
+        ) from e
+
+
+def _check_dangerous_components(resolved_path: Path) -> None:
+    """Check for dangerous path components."""
+    path_parts = resolved_path.parts
+    dangerous_parts = {"..", ".", "~"}
+    if any(part in dangerous_parts for part in path_parts):
+        raise PathValidationError(
+            f"Path contains dangerous components: {resolved_path}"
+        )
+
+
+def validate_path(
+    path: str | Path,
+    base_dir: str | Path | None = None,
+    allow_absolute: bool = False,
+) -> Path:
+    """Validate that a path is safe and within allowed boundaries.
+
+    Args:
+        path: Path to validate
+        base_dir: Base directory that path must be within (optional)
+        allow_absolute: Whether to allow absolute paths
+
+    Returns:
+        Resolved safe path
+
+    Raises:
+        PathValidationError: If path is unsafe or outside boundaries
+    """
+    try:
+        # Convert to Path object if string
+        if isinstance(path, str):
+            path = Path(path)
+
+        # If no base directory specified, just check for basic safety
+        if base_dir is None:
+            # Still check for directory traversal patterns
+            path_str = str(path)
+            _check_traversal_patterns(path_str, allow_absolute)
+            return _resolve_path_safely(path)
+
+        # Convert base_dir to Path if needed
+        if isinstance(base_dir, str):
+            base_dir = Path(base_dir)
+
+        # Resolve paths
+        resolved_path = _resolve_relative_to_base(path, base_dir)
+        resolved_base = _resolve_base_safely(base_dir)
+
+        # Validate
+        _check_absolute_allowed(path, allow_absolute)
+        _check_within_base(resolved_path, resolved_base, path)
+        _check_dangerous_components(resolved_path)
+
+        log_security_event(
+            "path_validated",
+            {
+                "path": str(path),
+                "resolved_path": str(resolved_path),
+                "base_dir": str(base_dir) if base_dir else None,
+            },
+        )
+
+        return resolved_path
+
+    except Exception as e:
+        log_security_event(
+            "path_validation_failed",
+            {"path": str(path), "base_dir": str(base_dir), "error": str(e)},
+        )
+        raise

roadmap/common/security/temp_files.py

@@ -0,0 +1,41 @@
+"""Secure temporary file utilities."""
+
+import os
+import tempfile
+from pathlib import Path
+
+from .exceptions import SecurityError
+from .logging import log_security_event
+
+
+def create_secure_temp_file(prefix: str = "roadmap_", suffix: str = ".tmp") -> Path:
+    """Create a secure temporary file.
+
+    Args:
+        prefix: Prefix for temporary filename
+        suffix: Suffix for temporary filename
+
+    Returns:
+        Path to the secure temporary file
+
+    Raises:
+        SecurityError: If temporary file creation fails
+    """
+    try:
+        # Create secure temporary file
+        fd, temp_path = tempfile.mkstemp(prefix=prefix, suffix=suffix)
+        os.close(fd)  # Close the file descriptor
+
+        # Convert to Path object
+        temp_file = Path(temp_path)
+
+        # Set secure permissions (owner read/write only)
+        temp_file.chmod(0o600)
+
+        log_security_event("temp_file_created", {"path": str(temp_file)})
+
+        return temp_file
+
+    except Exception as e:
+        log_security_event("temp_file_creation_failed", {"error": str(e)})
+        raise SecurityError(f"Failed to create secure temporary file: {e}") from e

roadmap/common/services/__init__.py

@@ -0,0 +1,65 @@
+"""Service Utilities - Decorators, metrics, performance, and retry logic.
+
+This module contains cross-cutting concerns like logging, metrics, performance
+monitoring, and retry logic used by services.
+"""
+
+from .decorators import service_operation
+from .logging_utils import (
+    log_collection_operation,
+    log_entry,
+    log_event,
+    log_exit,
+    log_metric,
+    log_operation,
+    log_state_change,
+)
+from .metrics import MetricsCollector, OperationMetric, get_metrics_collector
+from .performance import OperationTimer, async_timed_operation, timed_operation
+from .profiling import (
+    OperationProfile,
+    PerformanceProfiler,
+    PerformanceReport,
+    get_profiler,
+)
+from .retry import (
+    API_RETRY,
+    DATABASE_RETRY,
+    NETWORK_RETRY,
+    RetryConfig,
+    async_retry,
+    retry,
+)
+
+__all__ = [
+    # Decorators
+    "service_operation",
+    # Logging
+    "log_collection_operation",
+    "log_entry",
+    "log_event",
+    "log_exit",
+    "log_metric",
+    "log_operation",
+    "log_state_change",
+    # Metrics
+    "MetricsCollector",
+    "OperationMetric",
+    "get_metrics_collector",
+    # Performance
+    "OperationTimer",
+    "async_timed_operation",
+    "timed_operation",
+    # Profiling
+    "OperationProfile",
+    "PerformanceProfiler",
+    "PerformanceReport",
+    "get_profiler",
+    # Retry
+    "API_RETRY",
+    "DATABASE_RETRY",
+    "NETWORK_RETRY",
+    "RetryConfig",
+    "async_retry",
+    "retry",
+]

roadmap/common/services/decorators.py

@@ -0,0 +1,183 @@
+"""Decorators for service operations with intelligent error handling and logging.
+
+Provides consistent patterns for:
+- Exception handling across service methods
+- Configurable logging levels for different failure scenarios
+- Optional stack trace capture for debugging
+- Production-ready error reporting
+
+The @service_operation decorator is the foundation for eliminating silent failures
+and providing production observability.
+"""
+
+import traceback as tb_module
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, Literal
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def service_operation(
+    default_return: Any = None,
+    error_message: str | None = None,
+    log_level: Literal["debug", "info", "warning", "error"] = "error",
+    include_traceback: bool = False,
+    log_success: bool = False,
+):
+    """Provide intelligent error handling for service methods.
+
+    **Key Features:**
+    - Mandatory error logging (no silent failures)
+    - Configurable logging severity based on failure type
+    - Optional stack traces for debugging
+    - Automatic error context enrichment
+    - Consistent return value handling
+
+    **Log Level Guidance:**
+
+    Use `"warning"` for operational failures (expected to sometimes fail):
+        - File not found, item not found, permission denied
+        - Intended for: get/list operations, optional checks, lookups
+        - Example: @service_operation(log_level="warning")
+
+    Use `"error"` for unexpected failures (should rarely happen):
+        - Database corruption, file system errors, system resource issues
+        - Intended for: create/update/delete, critical operations
+        - Example: @service_operation(log_level="error")
+
+    Use `"debug"` for health/status checks (non-critical, potentially noisy):
+        - Polling operations, availability checks, status queries
+        - Intended for: frequent checking operations
+        - Example: @service_operation(log_level="debug")
+
+    Use `"info"` sparingly for business milestones (use debug/warning otherwise)
+        - Intended for: significant business events worth tracking
+        - Example: @service_operation(log_level="info")
+
+    **Parameters:**
+
+    Args:
+        default_return: Value to return on error (default {})
+        error_message: Custom error message (auto-generated if None)
+        log_level: Logging severity - "debug"|"info"|"warning"|"error"
+        include_traceback: Include full stack trace in logs (for debugging)
+        log_success: Whether to log on successful completion
+
+    **Usage Examples:**
+
+    ```python
+    # Database read operation (expected to sometimes fail)
+    @service_operation(default_return=None, log_level="warning")
+    def get_issue(self, issue_id: str) -> Issue | None:
+        return self._find_issue(issue_id)
+
+    # File parsing with debugging support
+    @service_operation(
+        default_return=[],
+        log_level="warning",
+        include_traceback=True
+    )
+    def list_issues(self):
+        return FileEnumerationService.enumerate_and_parse(...)
+
+    # Database write operation (should rarely fail)
+    @service_operation(
+        default_return=False,
+        log_level="error",
+        include_traceback=True
+    )
+    def save_issue(self, issue):
+        return self.db.save(issue)
+
+    # Health check polling (less critical)
+    @service_operation(default_return=False, log_level="debug")
+    def is_healthy(self) -> bool:
+        return self.check_readiness()
+    ```
+
+    **Error Logging Output:**
+
+    When a decorated function raises an exception:
+
+    ```
+    WARNING: Error in get_issue | error=not found | error_type=FileNotFoundError | operation=get_issue
+    ERROR: Error in save_issue | error=connection lost | error_type=ConnectionError | operation=save_issue | traceback=<full trace>
+    DEBUG: Error in is_healthy | error=timeout | error_type=TimeoutError | operation=is_healthy
+    ```
+
+    **Testing:**
+
+    The decorator ensures all failures are logged. Test that:
+    - Successful calls don't log errors
+    - Failed calls log at the specified level
+    - Default return value is returned on error
+    - Exception details are captured in logs
+    - Traceback is included when requested
+    """
+    # Validate log level
+    valid_levels = {"debug", "info", "warning", "error"}
+    if log_level not in valid_levels:
+        raise ValueError(f"log_level must be one of {valid_levels}, got '{log_level}'")
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(self, *args, **kwargs) -> Any:
+            try:
+                result = func(self, *args, **kwargs)
+                if log_success:
+                    logger.debug(
+                        "operation_completed",
+                        operation=func.__name__,
+                    )
+                return result
+            except Exception as e:
+                _log_operation_error(
+                    func=func,
+                    error=e,
+                    error_message=error_message,
+                    log_level=log_level,
+                    include_traceback=include_traceback,
+                )
+                return default_return if default_return is not None else {}
+
+        return wrapper
+
+    return decorator
+
+
+def _log_operation_error(
+    func: Callable,
+    error: Exception,
+    error_message: str | None,
+    log_level: str,
+    include_traceback: bool,
+) -> None:
+    """Log operation errors consistently with context.
+
+    Captures error details and routes to appropriate logger method
+    based on configured log level.
+
+    Args:
+        func: The function that failed
+        error: The exception that was caught
+        error_message: Optional custom message
+        log_level: Logging level to use ("debug"|"info"|"warning"|"error")
+        include_traceback: Whether to include full stack trace
+    """
+    msg = error_message or f"Error in {func.__name__}"
+
+    log_data = {
+        "error": str(error),
+        "error_type": type(error).__name__,
+        "operation": func.__name__,
+    }
+
+    if include_traceback:
+        log_data["traceback"] = tb_module.format_exc()
+
+    # Route to appropriate logger method
+    log_func = getattr(logger, log_level, logger.error)
+    log_func(msg, **log_data)

roadmap/common/services/logging_utils.py

@@ -0,0 +1,208 @@
+"""Logging utilities for comprehensive structured logging across the application.
+
+Provides helpers for:
+- Method entry/exit logging with timing
+- Business logic event logging
+- State change tracking
+- Performance metrics
+- Contextual information capture
+"""
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@contextmanager
+def log_operation(
+    operation_name: str,
+    level: str = "info",
+    **context: Any,
+) -> Iterator[dict[str, Any]]:
+    """Context manager for logging operation execution with timing and context.
+
+    Logs operation entry, execution time, and exit. Captures any exceptions that occur.
+
+    Args:
+        operation_name: Name of the operation (e.g., "create_issue", "update_project")
+        level: Log level ("debug", "info", "warning")
+        **context: Additional context to include in logs (e.g., entity_id, count)
+
+    Yields:
+        Dictionary for tracking additional operation metrics
+
+    Example:
+        with log_operation("create_issue", entity_id=issue_id, priority="HIGH") as metrics:
+            result = create_issue()
+            metrics["result_count"] = 1
+
+    The context manager will log:
+        - Entry: "{operation_name}_start" with all context
+        - Exit: "{operation_name}_complete" with timing and metrics
+        - Error: "{operation_name}_failed" if exception occurs
+    """
+    start_time = time.time()
+    metrics: dict[str, Any] = {}
+    log_func = getattr(logger, level)
+
+    try:
+        log_func(f"{operation_name}_start", **context)
+        yield metrics
+
+    except Exception as e:
+        elapsed = time.time() - start_time
+        log_func(
+            f"{operation_name}_failed",
+            elapsed_seconds=round(elapsed, 3),
+            error_type=type(e).__name__,
+            **context,
+            **metrics,
+        )
+        raise
+
+    else:
+        elapsed = time.time() - start_time
+        log_func(
+            f"{operation_name}_complete",
+            elapsed_seconds=round(elapsed, 3),
+            **context,
+            **metrics,
+        )
+
+
+def log_entry(
+    operation_name: str,
+    level: str = "debug",
+    **parameters: Any,
+) -> None:
+    """Log method entry with parameters.
+
+    Args:
+        operation_name: Name of the operation
+        level: Log level
+        **parameters: Method parameters to log
+    """
+    log_func = getattr(logger, level)
+    log_func(f"{operation_name}_start", **parameters)
+
+
+def log_exit(
+    operation_name: str,
+    level: str = "debug",
+    elapsed_seconds: float | None = None,
+    **result: Any,
+) -> None:
+    """Log method exit with result and timing.
+
+    Args:
+        operation_name: Name of the operation
+        level: Log level
+        elapsed_seconds: Execution time in seconds
+        **result: Result information to log
+    """
+    log_func = getattr(logger, level)
+    if elapsed_seconds is not None:
+        result["elapsed_seconds"] = round(elapsed_seconds, 3)
+    log_func(f"{operation_name}_complete", **result)
+
+
+def log_event(
+    event_name: str,
+    level: str = "info",
+    **details: Any,
+) -> None:
+    """Log a business logic event or milestone.
+
+    Args:
+        event_name: Name of the event (e.g., "issue_assigned", "milestone_closed")
+        level: Log level
+        **details: Event details
+    """
+    log_func = getattr(logger, level)
+    log_func(event_name, **details)
+
+
+def log_state_change(
+    entity_type: str,
+    entity_id: str,
+    old_state: dict[str, Any],
+    new_state: dict[str, Any],
+    level: str = "info",
+) -> None:
+    """Log a state change for an entity.
+
+    Args:
+        entity_type: Type of entity (e.g., "Issue", "Milestone")
+        entity_id: Entity identifier
+        old_state: Previous state
+        new_state: New state
+        level: Log level
+    """
+    changes = {}
+    all_keys = set(old_state.keys()) | set(new_state.keys())
+
+    for key in all_keys:
+        old_val = old_state.get(key)
+        new_val = new_state.get(key)
+        if old_val != new_val:
+            changes[key] = {"from": old_val, "to": new_val}
+
+    log_func = getattr(logger, level)
+    log_func(
+        f"{entity_type.lower()}_state_changed",
+        entity_type=entity_type,
+        entity_id=entity_id,
+        changes=changes,
+    )
+
+
+def log_collection_operation(
+    collection_name: str,
+    count: int,
+    operation: str = "processed",
+    level: str = "debug",
+    **context: Any,
+) -> None:
+    """Log collection processing (e.g., parsed 5 issues).
+
+    Args:
+        collection_name: Name of the collection (e.g., "issues", "milestones")
+        count: Number of items processed
+        operation: Operation performed (e.g., "processed", "created", "updated")
+        level: Log level
+        **context: Additional context
+    """
+    log_func = getattr(logger, level)
+    log_func(
+        f"{collection_name}_{operation}",
+        count=count,
+        **context,
+    )
+
+
+def log_metric(
+    metric_name: str,
+    value: float | int,
+    unit: str = "",
+    level: str = "debug",
+    **context: Any,
+) -> None:
+    """Log a performance or business metric.
+
+    Args:
+        metric_name: Name of the metric (e.g., "query_time", "issue_count")
+        value: Metric value
+        unit: Unit of measurement (e.g., "ms", "seconds", "items")
+        level: Log level
+        **context: Additional context
+    """
+    log_func = getattr(logger, level)
+    data: dict[str, Any] = {"value": value}
+    if unit:
+        data["unit"] = unit
+    log_func(metric_name, **data, **context)