roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/formatters/text/operations.py

@@ -0,0 +1,325 @@
+"""CLI operation feedback formatting.
+
+This module provides both functional and class-based formatters for operation results.
+Use OperationFormatter class for new code. Legacy functions remain for backward compatibility.
+"""
+
+
+class OperationFormatter:
+    """Unified formatter for all operation results.
+
+    Provides a consistent interface for formatting operation successes, failures,
+    and entity details across the CLI. This class consolidates all formatting logic
+    that was previously scattered across multiple functions.
+    """
+
+    @staticmethod
+    def success(
+        emoji: str,
+        action: str,
+        entity_title: str | None = None,
+        entity_id: str | None = None,
+        details: dict[str, str] | None = None,
+    ) -> str:
+        """Format a successful operation as a string.
+
+        Args:
+            emoji: Emoji to display (e.g., "✅", "🚫", "📊")
+            action: Action verb (e.g., "Blocked", "Closed", "Updated")
+            entity_title: Title/name of the entity affected (e.g., issue title)
+            entity_id: ID of the entity (displayed separately as cyan)
+            details: Optional dict of additional details to display
+
+        Returns:
+            Formatted string for console output
+        """
+        lines = []
+
+        # Main success line: emoji + action + title
+        if entity_title:
+            lines.append(f"{emoji} {action} issue: {entity_title}")
+        else:
+            lines.append(f"{emoji} {action}")
+
+        # Entity ID line (if provided)
+        if entity_id:
+            lines.append(f"   ID: {entity_id}")
+
+        # Extra details (if provided)
+        if details:
+            for key, value in details.items():
+                lines.append(f"   {key}: {value}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def failure(
+        action: str,
+        entity_id: str | None = None,
+        error: str | None = None,
+        suggestion: str | None = None,
+    ) -> str:
+        """Format a failed operation as a string.
+
+        Args:
+            action: Action that failed (e.g., "block", "close", "update")
+            entity_id: ID of the entity that failed (optional)
+            error: Error message/reason for failure
+            suggestion: Suggested recovery action
+
+        Returns:
+            Formatted string for console output
+        """
+        lines = []
+
+        # Main failure line
+        if entity_id:
+            lines.append(f"❌ Failed to {action} issue: {entity_id}")
+        else:
+            lines.append(f"❌ Failed to {action}")
+
+        # Error details (if provided)
+        if error:
+            lines.append(f"   Error: {error}")
+
+        # Suggestion (if provided)
+        if suggestion:
+            lines.append(f"   💡 {suggestion}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def entity(
+        entity_id: str,
+        entity_title: str | None = None,
+        entity_type: str = "item",
+        status: str | None = None,
+        details: dict[str, str] | None = None,
+    ) -> str:
+        """Format entity details as a string.
+
+        Args:
+            entity_id: ID of the entity
+            entity_title: Title/name of the entity
+            entity_type: Type of entity (e.g., "issue", "milestone")
+            status: Current status of entity
+            details: Additional details dict
+
+        Returns:
+            Formatted string for console output
+        """
+        lines = []
+
+        # ID and title
+        if entity_title:
+            lines.append(f"📋 {entity_type.title()}: {entity_title}")
+        lines.append(f"   ID: {entity_id}")
+
+        # Status
+        if status:
+            lines.append(f"   Status: {status}")
+
+        # Additional details
+        if details:
+            for key, value in details.items():
+                lines.append(f"   {key}: {value}")
+
+        return "\n".join(lines)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Legacy Functions (Backward Compatibility)
+# ─────────────────────────────────────────────────────────────────────────────
+# These functions are deprecated. Use OperationFormatter class instead.
+# They are retained for backward compatibility with existing code.
+
+
+def format_operation_success(
+    emoji: str,
+    action: str,
+    entity_title: str | None = None,
+    entity_id: str | None = None,
+    reason: str | None = None,
+    extra_details: dict[str, str] | None = None,
+) -> list[str]:
+    """Format a successful operation message with consistent styling.
+
+    Returns a list of formatted lines for console output.
+
+    Args:
+        emoji: Emoji to display (e.g., "✅", "🚫", "📊")
+        action: Action verb (e.g., "Blocked", "Closed", "Updated")
+        entity_title: Title/name of the entity affected (e.g., issue title)
+        entity_id: ID of the entity (displayed separately as cyan)
+        reason: Optional reason for the operation
+        extra_details: Optional dict of additional details to display
+
+    Returns:
+        List of formatted output lines
+    """
+    lines = []
+
+    # Main success line: emoji + action + title
+    if entity_title:
+        lines.append(f"{emoji} {action} issue: {entity_title}")
+    else:
+        lines.append(f"{emoji} {action}")
+
+    # Entity ID line (if provided)
+    if entity_id:
+        lines.append(f"   ID: {entity_id}")
+
+    # Reason line (if provided)
+    if reason:
+        lines.append(f"   Reason: {reason}")
+
+    # Extra details (if provided)
+    if extra_details:
+        for key, value in extra_details.items():
+            lines.append(f"   {key}: {value}")
+
+    return lines
+
+
+def format_operation_failure(
+    action: str,
+    entity_id: str | None = None,
+    error: str | None = None,
+    suggestion: str | None = None,
+) -> list[str]:
+    """Format a failed operation message with consistent styling.
+
+    Returns a list of formatted lines for console output.
+
+    Args:
+        action: Action that failed (e.g., "block", "close", "update")
+        entity_id: ID of the entity that failed (optional)
+        error: Error message/reason for failure
+        suggestion: Suggested recovery action
+
+    Returns:
+        List of formatted output lines
+    """
+    lines = []
+
+    # Main failure line
+    if entity_id:
+        lines.append(f"❌ Failed to {action} issue: {entity_id}")
+    else:
+        lines.append(f"❌ Failed to {action}")
+
+    # Error details (if provided)
+    if error:
+        lines.append(f"   Error: {error}")
+
+    # Suggestion (if provided)
+    if suggestion:
+        lines.append(f"   💡 {suggestion}")
+
+    return lines
+
+
+def format_entity_details(
+    entity_id: str,
+    entity_title: str | None = None,
+    entity_type: str = "item",
+    status: str | None = None,
+    details: dict[str, str] | None = None,
+) -> list[str]:
+    """Format entity details for consistent display across commands.
+
+    Args:
+        entity_id: ID of the entity
+        entity_title: Title/name of the entity
+        entity_type: Type of entity (e.g., "issue", "milestone")
+        status: Current status of entity
+        details: Additional details dict
+
+    Returns:
+        List of formatted output lines
+    """
+    lines = []
+
+    # ID and title
+    if entity_title:
+        lines.append(f"📋 {entity_type.title()}: {entity_title}")
+    lines.append(f"   ID: {entity_id}")
+
+    # Status
+    if status:
+        lines.append(f"   Status: {status}")
+
+    # Additional details
+    if details:
+        for key, value in details.items():
+            lines.append(f"   {key}: {value}")
+
+    return lines
+
+
+def format_list_items(
+    items: list[dict[str, str]],
+    show_count: int | None = None,
+    more_suffix: str = "... and {count} more",
+) -> list[str]:
+    """Format a list of items consistently.
+
+    Args:
+        items: List of dicts with 'id' and 'title' keys minimum
+        show_count: Maximum items to show (None = show all)
+        more_suffix: Format string for "... and X more" suffix
+
+    Returns:
+        List of formatted output lines
+    """
+    lines = []
+
+    # Determine how many to show
+    items_to_show = items
+    remaining = 0
+    if show_count and len(items) > show_count:
+        items_to_show = items[:show_count]
+        remaining = len(items) - show_count
+
+    # Format each item
+    for item in items_to_show:
+        item_id = item.get("id", "")[:8]  # Show first 8 chars of ID
+        title = item.get("title", "")
+        lines.append(f"   • {item_id} - {title}")
+
+    # Add "... and X more" if truncated
+    if remaining > 0:
+        lines.append(more_suffix.format(count=remaining))
+
+    return lines
+
+
+# Console wrapper functions for CLI commands that need to print and potentially exit
+def print_operation_success(
+    console,
+    emoji: str,
+    action: str,
+    entity_title: str | None = None,
+    entity_id: str | None = None,
+    reason: str | None = None,
+    extra_details: dict[str, str] | None = None,
+) -> None:
+    """Print a successful operation message to console."""
+    lines = format_operation_success(
+        emoji, action, entity_title, entity_id, reason, extra_details
+    )
+    for line in lines:
+        console.print(line)
+
+
+def print_operation_failure(
+    console,
+    action: str,
+    entity_id: str | None = None,
+    error: str | None = None,
+    suggestion: str | None = None,
+) -> None:
+    """Print a failed operation message to console."""
+    lines = format_operation_failure(action, entity_id, error, suggestion)
+    for line in lines:
+        console.print(line)

roadmap/common/formatters/text/status_badges.py

@@ -0,0 +1,57 @@
+"""Status badge and percentage formatting."""
+
+from rich.text import Text
+
+
+def format_status_badge(status: str) -> Text:
+    """Format a status as a colored badge.
+
+    Args:
+        status: Status value
+
+    Returns:
+        Styled Text badge
+    """
+    status_lower = str(status).lower()
+
+    # Map status values to colors
+    status_colors = {
+        "closed": "bold green",
+        "in-progress": "bold blue",
+        "in_progress": "bold blue",
+        "todo": "bold yellow",
+        "blocked": "bold red",
+        "review": "bold magenta",
+        "open": "bold green",
+        "active": "bold green",
+        "on-hold": "bold yellow",
+        "on_hold": "bold yellow",
+        "planning": "bold blue",
+        "completed": "bold green",
+        "cancelled": "bold red",
+        "critical": "bold red",
+        "high": "bold yellow",
+        "medium": "bold blue",
+        "low": "bold green",
+    }
+
+    style = status_colors.get(status_lower, "white")
+    return Text(f"[{status}]", style=style)
+
+
+def format_percentage(value: float, decimals: int = 1) -> str:
+    """Format a numeric value as a percentage.
+
+    Args:
+        value: Decimal value (0.0-1.0 or 0-100)
+        decimals: Number of decimal places
+
+    Returns:
+        Formatted percentage string
+    """
+    if value <= 1.0:
+        value = value * 100
+    return f"{value:.{decimals}f}%"
+
+
+__all__ = ["format_status_badge", "format_percentage"]

roadmap/common/initialization/github/__init__.py

@@ -0,0 +1,11 @@
+"""GitHub initialization services."""
+
+from roadmap.common.initialization.github.setup_service import (
+    GitHubInitializationService,
+)
+from roadmap.common.initialization.github.setup_validator import GitHubSetupValidator
+
+__all__ = [
+    "GitHubSetupValidator",
+    "GitHubInitializationService",
+]

roadmap/common/initialization/github/setup_service.py

@@ -0,0 +1,238 @@
+"""GitHub initialization service for setup workflow orchestration."""
+
+import click
+from structlog import get_logger
+
+from roadmap.adapters.github.github import GitHubClient
+from roadmap.common.configuration.github.config_manager import GitHubConfigManager
+from roadmap.common.configuration.github.token_resolver import GitHubTokenResolver
+from roadmap.common.console import get_console
+from roadmap.common.constants import SyncBackend
+from roadmap.common.initialization.github.setup_validator import GitHubSetupValidator
+from roadmap.infrastructure.coordination.core import RoadmapCore
+from roadmap.infrastructure.security.credentials import CredentialManager
+
+logger = get_logger()
+console = get_console()
+
+
+def show_github_setup_instructions(github_repo: str, yes: bool) -> bool:
+    """Show GitHub setup instructions and get user confirmation.
+
+    Returns:
+        True if user wants to continue, False to skip
+    """
+    console.print("🔗 GitHub Integration Setup", style="bold blue")
+    console.print(f"\nRepository: {github_repo}")
+    console.print("\nTo sync with GitHub, you'll need a personal access token.")
+    console.print("→ Open: https://github.com/settings/tokens")
+    console.print(
+        "→ Create token with 'repo' scope (or 'public_repo' for public repos)"
+    )
+    console.print("→ Required permissions: Issues, Pull requests, Repository metadata")
+    console.print()
+
+    if not yes and not click.confirm("Do you want to set up GitHub integration now?"):
+        console.print(
+            "⏭️  Skipping GitHub integration (you can set this up later with 'roadmap sync setup')"
+        )
+        return False
+
+    return True
+
+
+class GitHubInitializationService:
+    """Orchestrates GitHub integration setup during initialization."""
+
+    def __init__(self, core: RoadmapCore):
+        """Initialize GitHubInitializationService.
+
+        Args:
+            core: Core roadmap instance.
+        """
+        self.core = core
+        self.presenter = None  # Set by caller if needed
+
+    def setup(
+        self,
+        skip_github: bool,
+        github_repo: str | None,
+        detected_info: dict,
+        interactive: bool,
+        yes: bool,
+        github_token: str | None,
+        presenter=None,
+        sync_backend: SyncBackend = SyncBackend.GITHUB,
+    ) -> bool:
+        """Set up GitHub integration if requested.
+
+        Args:
+            skip_github: If True, skip GitHub setup
+            github_repo: GitHub repository (owner/repo)
+            detected_info: Auto-detected project information
+            interactive: If True, prompt user for input
+            yes: If True, answer yes to all prompts
+            github_token: GitHub personal access token
+            presenter: UI presenter for output
+            sync_backend: Backend to use (SyncBackend.GITHUB or SyncBackend.GIT)
+
+        Returns:
+            True if configured, False if skipped or failed
+        """
+        self.presenter = presenter
+
+        if skip_github:
+            return False
+
+        repo_name = github_repo or detected_info.get("git_repo")
+        if not repo_name:
+            return False
+
+        return self._configure_integration(
+            repo_name, interactive, yes, token=github_token, sync_backend=sync_backend
+        )
+
+    def _validate_setup_conditions(self, github_repo, interactive, yes, token):
+        """Validate prerequisites for GitHub integration setup.
+
+        Returns:
+            True if setup should proceed, False if user wants to skip
+        """
+        if GitHubClient is None or CredentialManager is None:
+            raise ImportError("GitHub integration dependencies not available")
+
+        if interactive and not yes:
+            if not show_github_setup_instructions(github_repo, yes):
+                return False
+
+        return True
+
+    def _resolve_and_test_token(self, token, interactive, yes):
+        """Resolve token and test GitHub connection."""
+        cred_manager = CredentialManager()  # type: ignore[call-arg]
+        token_resolver = GitHubTokenResolver(cred_manager)
+
+        existing_token = token_resolver.get_existing_token()
+        use_token, should_continue = token_resolver.resolve_token(
+            token, interactive, yes, existing_token
+        )
+
+        if not should_continue or not use_token:
+            return None
+
+        if self.presenter:
+            self.presenter.present_github_testing()
+        else:
+            console.print("🧪 Testing GitHub connection...", style="cyan")
+
+        return use_token
+
+    def _validate_github_access(self, use_token, github_repo, interactive, yes):
+        """Validate authentication and repository access."""
+        github_client = GitHubClient(use_token)  # type: ignore[call-arg]
+        validator = GitHubSetupValidator(github_client)
+
+        auth_success, _ = validator.validate_authentication()
+        if not auth_success:
+            if interactive and not yes:
+                if not click.confirm(
+                    "Continue without GitHub integration? (recommended to skip until token is fixed)"
+                ):
+                    return False
+            return False
+
+        repo_success, _ = validator.validate_repository_access(github_repo)
+        if not repo_success:
+            if interactive and not yes:
+                if not click.confirm("Continue with GitHub integration anyway?"):
+                    return False
+
+        return True
+
+    def _store_credentials_and_config(
+        self,
+        use_token: str,
+        existing_token: str | None,
+        github_repo: str,
+        sync_backend: SyncBackend = SyncBackend.GITHUB,
+    ) -> None:
+        """Store credentials and save configuration.
+
+        Args:
+            use_token: Token to store
+            existing_token: Previously stored token
+            github_repo: GitHub repository (owner/repo)
+            sync_backend: Backend to use (SyncBackend.GITHUB or SyncBackend.GIT)
+        """
+        if use_token != existing_token:
+            cred_manager = CredentialManager()  # type: ignore[call-arg]
+            cred_manager.store_token(use_token)
+            if self.presenter:
+                self.presenter.present_github_credentials_stored()
+            else:
+                console.print("✅ GitHub credentials stored", style="green")
+
+        config_manager = GitHubConfigManager(self.core)
+        # Always pass sync_backend explicitly for consistency and clarity
+        config_manager.save_github_config(github_repo, sync_backend=sync_backend)
+
+    def _configure_integration(
+        self,
+        github_repo: str,
+        interactive: bool,
+        yes: bool = False,
+        token: str | None = None,
+        sync_backend: SyncBackend = SyncBackend.GITHUB,
+    ) -> bool:
+        """Set up GitHub integration with credential flow.
+
+        Args:
+            github_repo: GitHub repository (owner/repo)
+            interactive: If True, prompt user for input
+            yes: If True, answer yes to all prompts
+            token: GitHub personal access token
+            sync_backend: Backend to use (SyncBackend.GITHUB or SyncBackend.GIT)
+
+        Returns:
+            True if setup successful, False otherwise
+        """
+        try:
+            # Validate setup conditions - this will prompt user if they want to proceed
+            setup_result = self._validate_setup_conditions(
+                github_repo, interactive, yes, token
+            )
+            if not setup_result:
+                return False
+
+            # Resolve and test token
+            use_token = self._resolve_and_test_token(token, interactive, yes)
+            if use_token is None:
+                return False
+
+            # Validate GitHub access
+            if not self._validate_github_access(
+                use_token, github_repo, interactive, yes
+            ):
+                return False
+
+            # Store credentials and config
+            cred_manager = CredentialManager()  # type: ignore[call-arg]
+            existing_token = GitHubTokenResolver(cred_manager).get_existing_token()
+            self._store_credentials_and_config(
+                use_token, existing_token, github_repo, sync_backend=sync_backend
+            )
+
+            return True
+
+        except ImportError:
+            if self.presenter:
+                self.presenter.present_github_unavailable("Dependencies not installed")
+            else:
+                console.print("⚠️  GitHub dependencies not installed", style="yellow")
+            return False
+        except Exception as e:
+            if self.presenter:
+                self.presenter.present_github_setup_failed(str(e))
+            else:
+                console.print(f"❌ GitHub setup failed: {e}", style="red")
+            return False