roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/initialization/github/setup_validator.py

@@ -0,0 +1,78 @@
+"""GitHub setup validation utilities."""
+
+from roadmap.common.console import get_console
+
+console = get_console()
+
+
+class GitHubSetupValidator:
+    """Validates GitHub connectivity and permissions during setup."""
+
+    def __init__(self, github_client):  # type: ignore
+        """Initialize GitHubSetupValidator.
+
+        Args:
+            github_client: GitHub client instance.
+        """
+        self.client = github_client
+
+    def validate_authentication(self) -> tuple[bool, str | None]:
+        """Validate user authentication.
+
+        Returns:
+            Tuple of (success, username or error)
+        """
+        try:
+            user_response = self.client._make_request("GET", "/user")
+            user_info = user_response.json()
+            username = user_info.get("login", "unknown")
+            console.print(f"✅ Authenticated as: {username}")
+            return True, username
+        except Exception as e:
+            console.print(f"❌ Authentication failed: {e}", style="red")
+            return False, str(e)
+
+    def validate_repository_access(self, github_repo: str) -> tuple[bool, dict | None]:
+        """Validate repository access and permissions.
+
+        Returns:
+            Tuple of (success, repo_info or error_message)
+        """
+        try:
+            owner, repo = github_repo.split("/")
+            self.client.set_repository(owner, repo)
+            repo_info = self.client.test_repository_access()
+
+            repo_name = repo_info.get("full_name", github_repo)
+            console.print(f"✅ Repository access: {repo_name}")
+
+            # Check permissions
+            permissions = repo_info.get("permissions", {})
+            if permissions.get("admin") or permissions.get("push"):
+                console.print("✅ Write access: Available")
+            elif permissions.get("pull"):
+                console.print(
+                    "⚠️  Read-only access: Limited sync capabilities", style="yellow"
+                )
+            else:
+                console.print("❌ No repository access detected", style="red")
+
+            return True, repo_info
+        except Exception as e:
+            console.print(f"⚠️  Repository validation warning: {e}", style="yellow")
+            return False, {"error": str(e)}
+
+    def test_api_access(self, github_repo: str) -> bool:
+        """Test basic API calls."""
+        try:
+            issues_response = self.client._make_request(
+                "GET",
+                f"/repos/{github_repo}/issues",
+                params={"state": "open", "per_page": 1},
+            )
+            issues = issues_response.json()
+            console.print(f"✅ API test successful ({len(issues)} issue(s) found)")
+            return True
+        except Exception as e:
+            console.print(f"⚠️  API test warning: {e}", style="yellow")
+            return False

roadmap/common/logging/__init__.py

@@ -0,0 +1,113 @@
+"""Structured logging for roadmap CLI application."""
+
+import structlog  # noqa: F401
+
+from roadmap.common.logging.correlation import (
+    add_correlation_id,
+    clear_correlation_id,
+    correlation_id_var,
+    get_correlation_id,
+    set_correlation_id,
+)
+from roadmap.common.logging.decorators import (
+    get_current_user,
+    log_audit_event,
+    log_command,
+    log_operation_duration,
+    verbose_output,
+)
+from roadmap.common.logging.error_logging import (
+    ErrorClassification,
+    classify_error,
+    is_error_recoverable,
+    log_database_error,
+    log_error_with_context,
+    log_external_service_error,
+    log_validation_error,
+    suggest_recovery,
+)
+from roadmap.common.logging.formatters import (
+    SENSITIVE_KEYS,
+    StructuredFormatter,
+    include_structured_fields_in_message,
+    scrub_sensitive_data,
+)
+from roadmap.common.logging.loggers import (
+    get_application_logger,
+    get_domain_logger,
+    get_infrastructure_logger,
+    get_logger,
+    get_presentation_logger,
+    get_security_logger,
+)
+from roadmap.common.logging.performance_tracking import (
+    OperationTimer,
+    track_database_operation,
+    track_file_operation,
+    track_operation_time,
+    track_sync_operation,
+)
+from roadmap.common.logging.utils import (
+    configure_for_testing,
+    get_stack_trace,
+    log_operation,
+    log_operation_timing,
+    setup_logging,
+    should_sample,
+)
+
+__all__ = [
+    # Formatters and scrubbing
+    "StructuredFormatter",
+    "scrub_sensitive_data",
+    "include_structured_fields_in_message",
+    "SENSITIVE_KEYS",
+    # Correlation ID
+    "correlation_id_var",
+    "set_correlation_id",
+    "get_correlation_id",
+    "clear_correlation_id",
+    "add_correlation_id",
+    # Logger factories
+    "get_logger",
+    "get_domain_logger",
+    "get_application_logger",
+    "get_infrastructure_logger",
+    "get_presentation_logger",
+    "get_security_logger",
+    # Setup and utilities
+    "setup_logging",
+    "get_stack_trace",
+    "log_operation_timing",
+    "log_operation",
+    "should_sample",
+    "configure_for_testing",
+    # Decorators
+    "log_command",
+    "verbose_output",
+    "get_current_user",
+    "log_audit_event",
+    "log_operation_duration",
+    # Error logging
+    "ErrorClassification",
+    "classify_error",
+    "is_error_recoverable",
+    "log_database_error",
+    "log_error_with_context",
+    "log_external_service_error",
+    "log_validation_error",
+    "suggest_recovery",
+    # Performance tracking
+    "OperationTimer",
+    "track_database_operation",
+    "track_file_operation",
+    "track_operation_time",
+    "track_sync_operation",
+]
+
+# Initialize logging at module load time
+# This is the single source of truth for production logging configuration
+setup_logging(log_level="INFO", debug_mode=False, log_to_file=True)
+
+# Get default logger instance
+logger = get_logger("roadmap")

roadmap/common/logging/audit_logging.py

@@ -0,0 +1,5 @@
+"""Audit logging utilities for tracking user actions and data changes.
+
+Placeholder for future audit logging implementation.
+Currently audit logging functionality is not active in v1.0.
+"""

roadmap/common/logging/correlation.py

@@ -0,0 +1,45 @@
+"""Correlation ID tracking for distributed tracing across operations."""
+
+import contextvars
+import uuid
+
+# Context variable for correlation ID tracking across async operations
+correlation_id_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "correlation_id", default=None
+)
+
+
+def add_correlation_id(logger, _method_name, event_dict):
+    """Structlog processor to add correlation ID to all log entries."""
+    cid = correlation_id_var.get()
+    if cid:
+        event_dict["correlation_id"] = cid
+    return event_dict
+
+
+def set_correlation_id(correlation_id: str | None = None) -> str:
+    """Set correlation ID for current context.
+
+    Args:
+        correlation_id: Optional correlation ID (generates UUID if None)
+
+    Returns:
+        The correlation ID that was set
+    """
+    cid = correlation_id or str(uuid.uuid4())
+    correlation_id_var.set(cid)
+    return cid
+
+
+def get_correlation_id() -> str | None:
+    """Get correlation ID from current context.
+
+    Returns:
+        Current correlation ID or None
+    """
+    return correlation_id_var.get()
+
+
+def clear_correlation_id() -> None:
+    """Clear correlation ID from current context."""
+    correlation_id_var.set(None)

roadmap/common/logging/decorators.py

@@ -0,0 +1,267 @@
+"""CLI command logging decorators for audit trail and observability.
+
+Provides decorators to automatically log CLI command execution, timing,
+user actions, and outcomes for comprehensive audit trail and debugging.
+"""
+
+import functools
+import os
+import sys
+import time
+from collections.abc import Callable
+from typing import Any
+
+import click  # type: ignore[import-not-found]
+
+from roadmap.common.logging.loggers import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_current_user() -> str:
+    """Get current user from environment."""
+    user = os.environ.get("USER") or os.environ.get("USERNAME")
+    return user if user else "unknown"
+
+
+def log_command(
+    command_name: str,
+    entity_type: str | None = None,
+    track_duration: bool = True,
+    log_args: bool = False,
+) -> Callable:
+    """Log CLI command execution with audit trail.
+
+    Args:
+        command_name: Name of the command (e.g., "issue_create")
+        entity_type: Type of entity affected (e.g., "issue", "milestone")
+        track_duration: Whether to track and log command execution time
+        log_args: Whether to log command arguments (use with caution for sensitive data)
+
+    Example:
+        @log_command("issue_create", entity_type="issue")
+        @click.command()
+        def create_issue(title, priority):
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            user = get_current_user()
+            start_time = time.time()
+
+            # Log command initiation
+            logger.info(
+                "command_initiated",
+                command_name=command_name,
+                user=user,
+                entity_type=entity_type,
+                args_logged=log_args,
+            )
+
+            if log_args:
+                logger.debug(
+                    "command_received_with_arguments",
+                    command=command_name,
+                    kwargs=kwargs,
+                )
+
+            try:
+                result = func(*args, **kwargs)
+
+                # Log successful completion
+                duration_ms = (time.time() - start_time) * 1000
+                logger.info(
+                    "command_completed",
+                    command_name=command_name,
+                    user=user,
+                    entity_type=entity_type,
+                    duration_ms=duration_ms if track_duration else None,
+                    status="success",
+                )
+
+                return result
+
+            except click.Abort:
+                # User cancelled (Ctrl+C or declined prompt)
+                duration_ms = (time.time() - start_time) * 1000
+                logger.info(
+                    "command_cancelled",
+                    command_name=command_name,
+                    user=user,
+                    entity_type=entity_type,
+                    duration_ms=duration_ms if track_duration else None,
+                )
+                raise
+
+            except Exception as e:
+                # Log error with context
+                duration_ms = (time.time() - start_time) * 1000
+                logger.error(
+                    "command_failed",
+                    command_name=command_name,
+                    user=user,
+                    entity_type=entity_type,
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    duration_ms=duration_ms if track_duration else None,
+                    is_user_error=isinstance(e, click.BadParameter | ValueError),
+                )
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def verbose_output(func: Callable) -> Callable:
+    """Add --verbose flag for controlling debug output visibility.
+
+    Suppresses debug logs by default for clean output.
+    When --verbose/-v is passed, all debug information is shown.
+
+    Works by disabling the console handler unless verbose is True.
+
+    Requires the decorated function to have a 'verbose' parameter.
+    Works with Click commands using @click.pass_context.
+
+    The decorator should be placed BEFORE @click.pass_context in the decorator stack.
+
+    Example:
+        @verbose_output
+        @click.pass_context
+        @click.command()
+        @click.option("--verbose", "-v", is_flag=True, ...)
+        def my_command(ctx, verbose):
+            # debug logs output suppressed unless verbose=True
+            ...
+    """
+    import logging
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        # Extract verbose flag from kwargs (it's passed as a Click option)
+        # Click passes options as keyword arguments after ctx
+        verbose = kwargs.get("verbose", False)
+
+        # Adjust console logging based on verbose flag
+        # Handler management requires standard logging API
+        # nosemgrep
+        roadmap_logger = logging.getLogger("roadmap")
+        original_levels = {}
+
+        # Find and adjust the console handler
+        for handler in roadmap_logger.handlers[:]:
+            if (
+                isinstance(handler, logging.StreamHandler)
+                and handler.stream == sys.stderr
+            ):
+                # Store original level for restoration later
+                original_levels[id(handler)] = handler.level
+
+                if verbose:
+                    # With --verbose, show INFO and above
+                    handler.setLevel(logging.INFO)
+                else:
+                    # Without --verbose, suppress to CRITICAL (effectively disable console output)
+                    handler.setLevel(logging.CRITICAL)
+
+        try:
+            return func(*args, **kwargs)
+        finally:
+            # Restore handler levels
+            for handler in roadmap_logger.handlers[:]:
+                if id(handler) in original_levels:
+                    handler.setLevel(original_levels[id(handler)])
+
+    return wrapper
+
+
+def log_audit_event(
+    action: str,
+    entity_type: str,
+    entity_id: str | None = None,
+    before: dict | None = None,
+    after: dict | None = None,
+    reason: str | None = None,
+) -> None:
+    """Log an auditable user action with before/after state.
+
+    Args:
+        action: Action performed (create, update, delete, archive, restore)
+        entity_type: Type of entity (issue, milestone, project)
+        entity_id: ID of the entity
+        before: Entity state before the action
+        after: Entity state after the action
+        reason: Reason for the action (if applicable)
+    """
+    user = get_current_user()
+    logger.info(
+        "audit_event",
+        action=action,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        user=user,
+        before=before,
+        after=after,
+        reason=reason,
+    )
+
+
+def log_operation_duration(
+    operation_name: str,
+    warn_threshold_ms: int = 5000,
+) -> Callable:
+    """Log operation duration and identify slow operations.
+
+    Args:
+        operation_name: Name of the operation
+        warn_threshold_ms: Threshold in milliseconds to warn about slow ops
+
+    Example:
+        @log_operation_duration("sync_issues", warn_threshold_ms=5000)
+        def sync_to_github():
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            start_time = time.time()
+
+            try:
+                result = func(*args, **kwargs)
+                duration_ms = (time.time() - start_time) * 1000
+
+                # Log at appropriate level based on duration
+                if duration_ms > warn_threshold_ms:
+                    logger.warning(
+                        "operation_slow",
+                        operation_name=operation_name,
+                        duration_ms=duration_ms,
+                        threshold_ms=warn_threshold_ms,
+                    )
+                else:
+                    logger.debug(
+                        "operation_completed",
+                        operation_name=operation_name,
+                        duration_ms=duration_ms,
+                    )
+
+                return result
+
+            except Exception as e:
+                duration_ms = (time.time() - start_time) * 1000
+                logger.error(
+                    "operation_failed",
+                    operation_name=operation_name,
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    duration_ms=duration_ms,
+                )
+                raise
+
+        return wrapper
+
+    return decorator