roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/configuration/github/config_manager.py

@@ -0,0 +1,154 @@
+"""GitHub configuration management utilities."""
+
+import yaml
+from structlog import get_logger
+
+from roadmap.common.console import get_console
+from roadmap.common.constants import SyncBackend
+from roadmap.core.utils.git_remote_parser import get_github_from_git_remote
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+logger = get_logger()
+console = get_console()
+
+
+class GitHubConfigManager:
+    """Manages GitHub configuration in roadmap config file."""
+
+    def __init__(self, core: RoadmapCore):
+        """Initialize GitHubConfigManager.
+
+        Args:
+            core: Core roadmap instance.
+        """
+        self.core = core
+        self.config_file = core.roadmap_dir / "config.yaml"
+
+    def save_github_config(
+        self, github_repo: str, sync_backend: SyncBackend = SyncBackend.GITHUB
+    ) -> None:
+        """Save GitHub repository configuration.
+
+        Args:
+            github_repo: GitHub repository (owner/repo)
+            sync_backend: Backend to use (SyncBackend.GITHUB or SyncBackend.GIT)
+
+        Raises:
+            ValueError: If github_repo is invalid format
+        """
+        # Validate repository format
+        if not github_repo or "/" not in github_repo:
+            log = logger.bind(github_repo=github_repo, operation="save_github_config")
+            log.error("invalid_github_repo_format")
+            raise ValueError(
+                f"Invalid GitHub repository format: '{github_repo}'. "
+                "Expected format: 'owner/repo'"
+            )
+
+        try:
+            if self.config_file.exists():
+                with open(self.config_file) as f:
+                    loaded = yaml.safe_load(f)
+                    config = loaded if isinstance(loaded, dict) else {}
+            else:
+                config: dict = {}
+
+            config["github"] = {
+                "repository": github_repo,
+                "enabled": True,
+                "sync_enabled": True,
+                "sync_backend": sync_backend.value,
+                "webhook_secret": None,
+                "sync_settings": {
+                    "bidirectional": True,
+                    "auto_close": True,
+                    "sync_labels": True,
+                    "sync_milestones": True,
+                },
+            }
+
+            with open(self.config_file, "w") as f:
+                yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+            log = logger.bind(
+                github_repo=github_repo,
+                sync_backend=sync_backend.value,
+                operation="save_github_config",
+            )
+            log.info("github_config_saved")
+            get_console().print("⚙️  Configuration saved")
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except Exception as e:
+            log = logger.bind(
+                github_repo=github_repo,
+                sync_backend=sync_backend.value,
+                error=str(e),
+                operation="save_github_config",
+            )
+            log.error("github_config_save_failed")
+            raise
+
+    def auto_detect_and_update(self) -> tuple[str | None, str | None]:
+        """Auto-detect GitHub owner/repo from git remote and update config if needed.
+
+        Returns:
+            Tuple of (owner, repo) or (None, None) if not detected or disabled
+        """
+        # Check if auto-detection is enabled in config
+        if self.config_file.exists():
+            try:
+                with open(self.config_file) as f:
+                    loaded = yaml.safe_load(f)
+                    config = loaded if isinstance(loaded, dict) else {}
+                    github_config = config.get("github", {})
+                    sync_settings = github_config.get("sync_settings", {})
+
+                    # Check if auto-detection is disabled
+                    if not sync_settings.get("auto_detect_from_git", True):
+                        return None, None
+
+                    # If owner/repo already set, don't override
+                    if github_config.get("repository"):
+                        return None, None
+            except Exception as e:
+                logger.debug("config_read_failed", error=str(e))
+
+        # Try to auto-detect from git remote
+        owner, repo = get_github_from_git_remote(self.core.root_path)
+
+        if owner and repo:
+            try:
+                github_repo = f"{owner}/{repo}"
+                logger.info(
+                    "github_auto_detected",
+                    owner=owner,
+                    repo=repo,
+                    repository=github_repo,
+                )
+
+                # Update config with detected values
+                if self.config_file.exists():
+                    with open(self.config_file) as f:
+                        loaded = yaml.safe_load(f)
+                        config = loaded if isinstance(loaded, dict) else {}
+                else:
+                    config = {}
+
+                if "github" not in config:
+                    config["github"] = {}
+
+                config["github"]["repository"] = github_repo
+                config["github"]["enabled"] = True
+
+                with open(self.config_file, "w") as f:
+                    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+                return owner, repo
+
+            except Exception as e:
+                logger.debug("github_auto_config_failed", error=str(e))
+
+        return None, None

roadmap/common/configuration/github/token_resolver.py

@@ -0,0 +1,84 @@
+"""GitHub token resolution and management utilities."""
+
+import os
+
+import click
+from structlog import get_logger
+
+from roadmap.common.console import get_console
+
+console = get_console()
+logger = get_logger()
+
+
+class GitHubTokenResolver:
+    """Resolves GitHub tokens from multiple sources."""
+
+    def __init__(self, cred_manager=None):  # type: ignore
+        """Initialize GitHubTokenResolver.
+
+        Args:
+            cred_manager: Optional credential manager instance.
+        """
+        self.cred_manager = cred_manager
+
+    def get_existing_token(self) -> str | None:
+        """Get existing stored token."""
+        if not self.cred_manager:
+            return None
+        try:
+            return self.cred_manager.get_token()
+        except Exception as e:
+            logger.debug("stored_token_retrieval_failed", error=str(e))
+            return None
+
+    def resolve_token(
+        self,
+        cli_token: str | None,
+        interactive: bool,
+        yes: bool,
+        existing_token: str | None,
+    ) -> tuple[str | None, bool]:
+        """Resolve which token to use.
+
+        Returns:
+            Tuple of (token, should_continue)
+        """
+        # Priority: CLI arg > environment > stored > prompt
+        env_token = os.environ.get("ROADMAP_GITHUB_TOKEN")
+
+        if cli_token:
+            return cli_token, True
+
+        if env_token:
+            console.print(
+                "ℹ️  Using GitHub token from environment variable ROADMAP_GITHUB_TOKEN",
+                style="dim",
+            )
+            return env_token, True
+
+        if existing_token:
+            if interactive and not yes:
+                console.print("🔍 Found existing GitHub credentials")
+                if click.confirm("Use existing GitHub credentials?"):
+                    console.print("✅ Using existing GitHub credentials")
+                    return existing_token, True
+            else:
+                return existing_token, True
+
+        # Need to get token from user
+        if interactive and not yes:
+            console.print(
+                "To integrate with GitHub you'll need a personal access token with 'repo' scope."
+            )
+            console.print("→ Create one: https://github.com/settings/tokens")
+            token = click.prompt("Paste your GitHub token", hide_input=True)
+            return token, True
+
+        # Non-interactive without token
+        console.print(
+            "❌ Non-interactive mode requires providing a token via --github-token "
+            "or setting ROADMAP_GITHUB_TOKEN, or use --skip-github to skip integration.",
+            style="bold red",
+        )
+        return None, False

roadmap/common/console.py

@@ -0,0 +1,184 @@
+"""Console utilities for CLI operations.
+
+Provides centralized console instances configured for the current environment:
+- get_console() → Rich console for successful output (stdout)
+- get_console_stderr() → Console for errors/warnings (stderr)
+- is_plain_mode() → Auto-detect plain text mode for POSIX compliance
+
+Plain mode is auto-detected based on:
+- Output is not a terminal (piped/redirected)
+- ROADMAP_OUTPUT=plain environment variable
+- NO_COLOR=1 environment variable
+- Running in CI/CD environment
+
+This separation ensures:
+- Success output to stdout (can be piped, has colors)
+- Errors to stderr (never interferes with data)
+- POSIX compliance (no ANSI codes when piped)
+- Machine-readable output (can parse stdout, ignore stderr)
+"""
+
+import os
+import sys
+
+from rich.console import Console
+
+
+def is_plain_mode() -> bool:
+    """Detect if we should use plain text output (no ANSI codes).
+
+    Returns True if any of:
+    - Output is redirected/piped (not a terminal)
+    - ROADMAP_OUTPUT=plain environment variable set
+    - NO_COLOR=1 for POSIX compliance
+    - Running in CI/CD environment
+    - In testing environment
+
+    Returns:
+        bool: True if plain mode should be used
+    """
+    return any(
+        [
+            # Explicit plain mode request
+            os.environ.get("ROADMAP_OUTPUT") == "plain",
+            # POSIX NO_COLOR standard
+            os.environ.get("NO_COLOR") in ("1", "true", "True", "TRUE"),
+            # User forced no colors
+            os.environ.get("FORCE_COLOR") == "0",
+            # Output is piped/redirected (not interactive)
+            not sys.stdout.isatty(),
+            not sys.stderr.isatty(),
+            # CI/CD environments
+            any(
+                ci_var in os.environ
+                for ci_var in [
+                    "CI",
+                    "CONTINUOUS_INTEGRATION",
+                    "GITHUB_ACTIONS",
+                    "TRAVIS",
+                    "CIRCLECI",
+                    "JENKINS_URL",
+                    "GITLAB_CI",
+                ]
+            ),
+            # Testing environment
+            any(
+                test_var in os.environ
+                for test_var in [
+                    "PYTEST_CURRENT_TEST",
+                    "_PYTEST_RAISE",
+                    "UNITTEST_MODE",
+                ]
+            ),
+        ]
+    )
+
+
+def is_testing_environment() -> bool:
+    """Detect if we're running in a testing environment.
+
+    Returns True if any of the following conditions are met:
+    - pytest is running
+    - NO_COLOR environment variable is set
+    - TERM is set to 'dumb'
+    - Output is not a terminal
+    - Running under CI/CD
+    """
+    return any(
+        [
+            # Pytest detection
+            "PYTEST_CURRENT_TEST" in os.environ,
+            "pytest" in sys.modules,
+            hasattr(sys, "_called_from_test"),
+            # Explicit color disabling
+            os.environ.get("NO_COLOR") in ("1", "true", "True", "TRUE"),
+            os.environ.get("FORCE_COLOR") == "0",
+            # Terminal detection
+            os.environ.get("TERM") in ("dumb", ""),
+            not sys.stdout.isatty(),
+            not sys.stderr.isatty(),
+            # CI/CD environments
+            any(
+                ci_var in os.environ
+                for ci_var in [
+                    "CI",
+                    "CONTINUOUS_INTEGRATION",
+                    "GITHUB_ACTIONS",
+                    "TRAVIS",
+                    "CIRCLECI",
+                    "JENKINS_URL",
+                    "GITLAB_CI",
+                ]
+            ),
+            # Test frameworks
+            any(
+                test_var in os.environ
+                for test_var in [
+                    "PYTEST_CURRENT_TEST",
+                    "_PYTEST_RAISE",
+                    "UNITTEST_MODE",
+                ]
+            ),
+        ]
+    )
+
+
+def get_console() -> Console:
+    """Get a console instance configured for successful output (stdout).
+
+    Returns a console configured for:
+    - Rich output when in interactive terminal (colors, tables, styles)
+    - Plain text output when piped/testing (POSIX compliance)
+    - No ANSI codes when plain mode is detected
+
+    Returns a fresh instance each time to ensure file handle is current.
+
+    Returns:
+        Console: Configured Rich Console instance
+    """
+    plain = is_plain_mode()
+
+    # Use fresh instance each time to ensure file handle is correct
+    # This is critical for testing with CliRunner which replaces sys.stdout
+    if plain:
+        return Console(
+            file=sys.stdout,
+            force_terminal=False,
+            no_color=True,
+            width=80,
+            legacy_windows=False,
+            force_interactive=False,
+            force_jupyter=False,
+        )
+
+    # Interactive mode: full Rich features
+    return Console(file=sys.stdout)
+
+
+def get_console_stderr() -> Console:
+    """Get a console instance configured for error output (stderr).
+
+    Returns a console that outputs to stderr for:
+    - Error messages
+    - Warnings
+    - Diagnostic information
+
+    This ensures errors don't interfere with stdout data.
+
+    Returns:
+        Console: Console instance writing to stderr
+    """
+    plain = is_plain_mode()
+
+    # In testing/plain mode: no terminal, no colors
+    if plain:
+        return Console(
+            file=sys.stderr,
+            force_terminal=False,
+            no_color=True,
+            width=80,
+            legacy_windows=False,
+        )
+
+    # Interactive mode: use stderr with colors
+    return Console(file=sys.stderr)

roadmap/common/constants.py

@@ -0,0 +1,134 @@
+"""Application-wide constants and enums."""
+
+from enum import StrEnum
+
+
+class Priority(StrEnum):
+    """Issue priority levels."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class Status(StrEnum):
+    """Issue status values."""
+
+    TODO = "todo"
+    IN_PROGRESS = "in-progress"
+    BLOCKED = "blocked"
+    REVIEW = "review"
+    CLOSED = "closed"
+    ARCHIVED = "archived"  # Soft-deleted (duplicate or obsolete)
+
+
+class MilestoneStatus(StrEnum):
+    """Milestone status values."""
+
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class ProjectStatus(StrEnum):
+    """Project status values."""
+
+    PLANNING = "planning"
+    ACTIVE = "active"
+    ON_HOLD = "on-hold"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+class RiskLevel(StrEnum):
+    """Risk level values for projects and milestones."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class IssueType(StrEnum):
+    """Issue type categories."""
+
+    FEATURE = "feature"
+    BUG = "bug"
+    OTHER = "other"
+
+
+class SyncBackend(StrEnum):
+    """Sync backend types."""
+
+    GITHUB = "github"
+    GIT = "git"
+
+
+# Application Configuration Defaults
+# ============================================================================
+
+# File and path defaults
+DEFAULT_ROADMAP_FILE = "ROADMAP.md"
+DEFAULT_CONFIG_FILE = ".roadmaprc"
+DEFAULT_DATA_DIR = ".roadmap"
+DEFAULT_CACHE_FILE = ".roadmap_cache.json"
+
+# GitHub API defaults
+GITHUB_API_BASE = "https://api.github.com"
+GITHUB_GRAPHQL_ENDPOINT = "https://api.github.com/graphql"
+GITHUB_API_TIMEOUT = 30  # seconds
+GITHUB_RATE_LIMIT_THRESHOLD = 10  # remaining requests before warning
+
+# Display defaults
+DEFAULT_TABLE_WIDTH = 80
+DEFAULT_MAX_ITEMS_DISPLAY = 20
+DEFAULT_DATE_FORMAT = "%Y-%m-%d"
+DEFAULT_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# Caching defaults
+CACHE_TTL_DEFAULT = 3600  # 1 hour in seconds
+CACHE_TTL_LONG = 86400  # 24 hours in seconds
+CACHE_TTL_SHORT = 300  # 5 minutes in seconds
+
+# Batch operation defaults
+DEFAULT_BATCH_SIZE = 50
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY = 1  # seconds
+DEFAULT_BACKOFF_FACTOR = 2
+
+# Progress tracking defaults
+PROGRESS_REFRESH_INTERVAL = 0.1  # seconds
+PROGRESS_BAR_LENGTH = 30
+
+# Logging defaults
+LOG_LEVEL_DEFAULT = "INFO"
+LOG_FORMAT_DEFAULT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+# Error handling defaults
+ERROR_MESSAGE_MAX_LENGTH = 500
+VALIDATION_ERROR_MAX_FIELDS = 10
+
+# Authentication defaults
+AUTH_TOKEN_ENV_VAR = "GITHUB_TOKEN"
+AUTH_TIMEOUT = 30  # seconds
+
+# Git defaults
+GIT_TIMEOUT = 60  # seconds
+GIT_MAX_OUTPUT_LINES = 1000
+GIT_COMMIT_MESSAGE_MAX_LENGTH = 72
+
+# Project analysis defaults
+ANALYSIS_MIN_SAMPLE_SIZE = 5
+ANALYSIS_MAX_HISTORICAL_DAYS = 365
+ANALYSIS_TREND_WINDOW = 7  # days
+
+# Performance defaults
+PERFORMANCE_ENABLE_CACHE = True
+PERFORMANCE_ENABLE_ASYNC = True
+PERFORMANCE_THREAD_POOL_SIZE = 4
+PERFORMANCE_CONNECTION_POOL_SIZE = 10
+
+# Validation defaults
+VALIDATION_TITLE_MIN_LENGTH = 1
+VALIDATION_TITLE_MAX_LENGTH = 500
+VALIDATION_DESCRIPTION_MAX_LENGTH = 5000
+VALIDATION_NAME_PATTERN = r"^[a-zA-Z0-9_-]+$"