roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/output_manager.py

@@ -0,0 +1,319 @@
+"""Unified output management for CLI commands.
+
+Centralizes all CLI output handling across:
+- Multiple formats (table/json/csv/markdown)
+- Terminal vs file output
+- Test-friendly rendering (ANSI stripping)
+- Format auto-detection
+
+This replaces scattered console.print() and click.secho() calls with
+a unified interface that supports exporting to files.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from roadmap.adapters.cli.layout import SmartTableLayout
+from roadmap.common.models import TableData
+from roadmap.common.output_formatter import OutputFormatter
+
+
+class OutputManager:
+    """Unified output management for CLI commands.
+
+    Handles rendering of TableData in multiple formats:
+    - table: Pretty Rich table (default, terminal-friendly)
+    - plain: ASCII table (POSIX-compliant, no ANSI codes)
+    - json: Machine-readable JSON (API/data export)
+    - csv: RFC 4180 CSV (Excel/Sheets import)
+    - markdown: Markdown table (documentation)
+    - html: HTML table with styling (email/web)
+
+    Can output to terminal or file with automatic format detection.
+
+    Example:
+        # Terminal output
+        manager = OutputManager(format='table')
+        manager.render_table(table_data)
+
+        # File output
+        manager = OutputManager(
+            format='csv',
+            output_file=Path('/tmp/export.csv')
+        )
+        manager.render_table(table_data)
+
+        # In Click commands
+        @click.option('--format', type=click.Choice(['table', 'json', 'csv', 'html']))
+        @click.option('--output', type=click.Path())
+        def list_items(format, output):
+            manager = OutputManager(
+                format=format or 'table',
+                output_file=Path(output) if output else None
+            )
+            table_data = IssueTableFormatter.issues_to_table_data(items)
+            manager.render_table(table_data)
+    """
+
+    VALID_FORMATS = {"table", "plain", "json", "csv", "markdown", "html"}
+
+    def __init__(
+        self,
+        format: str = "table",
+        output_file: Path | None = None,
+        force_plain: bool = False,
+    ):
+        """Initialize OutputManager.
+
+        Args:
+            format: Output format (table/plain/json/csv/markdown/html)
+            output_file: Optional file path to save output
+            force_plain: Force plain text output (for testing)
+
+        Raises:
+            ValueError: If format is not valid
+        """
+        if format not in self.VALID_FORMATS:
+            raise ValueError(
+                f"Invalid format '{format}'. Must be one of: {', '.join(self.VALID_FORMATS)}"
+            )
+
+        self.format = format
+        self.output_file = output_file
+        self.force_plain = force_plain
+
+        # Determine color support
+        should_use_colors = self._should_use_colors()
+
+        # Initialize console for Rich output
+        # Use test-safe settings that work with Click's test runner
+        is_testing = self._is_testing_environment()
+        self.console = Console(
+            file=sys.stdout,
+            force_terminal=should_use_colors and not is_testing,
+            no_color=not should_use_colors or is_testing or force_plain,
+            width=80 if is_testing else 120,
+        )
+
+        # Initialize smart layout system for responsive table rendering
+        self.layout = SmartTableLayout()
+
+    @staticmethod
+    def _is_testing_environment() -> bool:
+        """Detect if running in a test environment."""
+        return any(
+            [
+                "PYTEST_CURRENT_TEST" in os.environ,
+                "pytest" in sys.modules,
+                "_pytest" in [m.split(".")[0] for m in sys.modules.keys()],
+                os.environ.get("NO_COLOR") in ("1", "true"),
+            ]
+        )
+
+    @staticmethod
+    def _should_use_colors() -> bool:
+        """Detect if terminal supports colors.
+
+        Checks:
+        1. NO_COLOR env var (standard no-color support)
+        2. FORCE_COLOR env var (force colors even in non-TTY)
+        3. Terminal type (dumb, emacs, etc. don't support colors)
+        4. isatty() - check if stdout is a terminal
+        5. CI environment detection
+
+        Returns:
+            True if colors should be used, False otherwise
+        """
+        # Check NO_COLOR first (highest priority to disable)
+        if os.environ.get("NO_COLOR", "").lower() in ("1", "true", "yes"):
+            return False
+
+        # Check FORCE_COLOR (explicit enable)
+        if os.environ.get("FORCE_COLOR", "").lower() in ("1", "true", "yes"):
+            return True
+
+        # Check terminal type
+        term = os.environ.get("TERM", "").lower()
+        if term in ("dumb", "emacs", "milk"):
+            return False
+
+        # Check if stdout is a TTY
+        try:
+            if not sys.stdout.isatty():
+                return False
+        except (AttributeError, Exception):
+            # If isatty() fails, assume no colors
+            return False
+
+        # Check for CI environments (usually don't support interactive colors)
+        ci_env_vars = [
+            "CI",
+            "CONTINUOUS_INTEGRATION",
+            "GITHUB_ACTIONS",
+            "GITLAB_CI",
+            "TRAVIS",
+            "CIRCLECI",
+            "JENKINS_URL",
+            "BUILDKITE",
+            "DRONE",
+        ]
+        if any(var in os.environ for var in ci_env_vars):
+            # CI is set, but some CI systems do support colors
+            # Check for specific ones that support colors
+            if os.environ.get("GITHUB_ACTIONS") == "true":
+                return True  # GitHub Actions supports colors
+            if os.environ.get("GITLAB_CI") == "true":
+                return True  # GitLab CI supports colors
+            # Others might not, so be conservative
+            return False
+
+        # Default: use colors (most modern terminals support them)
+        return True
+
+    def render_table(self, table_data: TableData) -> None:
+        """Render a table in the configured format.
+
+        Handles both terminal output and file saves.
+        Automatically detects test environment and strips ANSI codes.
+        For 'table' format, uses smart responsive layout system.
+
+        Args:
+            table_data: TableData object to render
+        """
+        formatter = OutputFormatter(table_data)
+
+        if self.format == "table":
+            # Use smart responsive layout for 'table' format
+            renderable = self.layout.render(table_data)
+            self.console.print(renderable)
+
+        elif self.format == "plain":
+            # Plain ASCII for POSIX compatibility
+            content = formatter.to_plain_text()
+            self._output_content(content)
+
+        elif self.format == "json":
+            # JSON for data export
+            content = formatter.to_json()
+            self._output_content(content)
+
+        elif self.format == "csv":
+            # CSV for spreadsheet import
+            content = formatter.to_csv()
+            self._output_content(content)
+
+        elif self.format == "markdown":
+            # Markdown for documentation
+            content = formatter.to_markdown()
+            self._output_content(content)
+
+        elif self.format == "html":
+            # HTML for email/web
+            content = formatter.to_html()
+            self._output_content(content)
+
+    def render_rich(self, renderable) -> None:
+        """Render a Rich-compatible object.
+
+        Useful for rendering non-table objects like Panels, etc.
+
+        Args:
+            renderable: Any Rich-compatible renderable object
+        """
+        self.console.print(renderable)
+
+    def _output_content(self, content: str) -> None:
+        """Output content to file or stdout.
+
+        Args:
+            content: String content to output
+        """
+        if self.output_file:
+            self.output_file.parent.mkdir(parents=True, exist_ok=True)
+            self.output_file.write_text(content)
+            click.secho(f"✅ Saved to {self.output_file}", fg="green")
+        else:
+            click.echo(content)
+
+    def print_message(
+        self, message: str, style: str | None = None, fg: str | None = None
+    ) -> None:
+        """Print a simple message (not a table).
+
+        Useful for status messages, warnings, etc.
+
+        Args:
+            message: Message to print
+            style: Rich style (e.g., 'bold red')
+            fg: Click color (e.g., 'green')
+        """
+        if self.format in {"json", "csv", "markdown"}:
+            # Skip non-data messages in data export formats
+            return
+
+        if self.format == "table" or self.format == "plain":
+            if fg:
+                click.secho(message, fg=fg)
+            elif style:
+                self.console.print(message, style=style)
+            else:
+                click.echo(message)
+
+    def print_styled(
+        self,
+        text: str,
+        color: str | None = None,
+        bold: bool = False,
+        italic: bool = False,
+    ) -> None:
+        """Print styled text (terminal output only).
+
+        Args:
+            text: Text to print
+            color: Color name (red, green, yellow, etc.)
+            bold: Make bold
+            italic: Make italic
+        """
+        if self.format in {"json", "csv", "markdown"}:
+            return
+
+        if color or bold or italic:
+            click.secho(text, fg=color, bold=bold)
+        else:
+            click.echo(text)
+
+    def print_section_header(self, title: str) -> None:
+        """Print a section header.
+
+        Args:
+            title: Section title
+        """
+        if self.format in {"json", "csv", "markdown"}:
+            return
+
+        click.secho(f"\n{title}", fg="cyan", bold=True)
+
+
+# Convenience function for quick output
+def create_output_manager(
+    format: str | None = None, output_file: str | None = None
+) -> OutputManager:
+    """Create an OutputManager with optional CLI arguments.
+
+    Useful for Click commands with --format and --output options.
+
+    Args:
+        format: Output format or None (uses 'table' default)
+        output_file: Path to output file or None (uses stdout)
+
+    Returns:
+        Configured OutputManager instance
+    """
+    return OutputManager(
+        format=format or "table",
+        output_file=Path(output_file) if output_file else None,
+    )

roadmap/adapters/cli/presentation/base_presenter.py

@@ -0,0 +1,121 @@
+"""Base presenter class for all CLI presenters.
+
+This module provides an abstract base class that defines the interface for all
+presenters in the CLI layer. All presenters should inherit from BasePresenter
+to ensure consistent method signatures and behavior.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from rich.console import Console
+
+from roadmap.common.console import get_console
+
+
+class BasePresenter(ABC):
+    """Abstract base class for all CLI presenters.
+
+    Defines the standard interface that all presenters must implement.
+    Presenters are responsible for formatting and rendering data to the console.
+
+    Example:
+        class MyPresenter(BasePresenter):
+            def render(self, data: dict) -> None:
+                console = get_console()
+                console.print(data["title"])
+    """
+
+    @abstractmethod
+    def render(self, data: Any) -> None:
+        """Render data to console.
+
+        This is the main entry point for presentation. Implementers should
+        format the provided data and output it using the console.
+
+        Args:
+            data: The data to render. Type depends on specific presenter.
+
+        Raises:
+            ValueError: If data is invalid or incomplete
+        """
+        pass
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Common Utility Methods (Optional for subclasses to use)
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _get_console() -> Console:
+        """Get the standard console instance.
+
+        Returns:
+            The global console instance for output
+        """
+        return get_console()
+
+    @staticmethod
+    def _render_header(title: str, style: str = "bold cyan") -> None:
+        """Render a section header.
+
+        Args:
+            title: Header text
+            style: Rich style string (default: bold cyan)
+        """
+        console = get_console()
+        console.print(f"\n[{style}]{title}[/{style}]")
+
+    @staticmethod
+    def _render_section(title: str, content: str, style: str = "dim") -> None:
+        """Render a named section with indented content.
+
+        Args:
+            title: Section title
+            content: Section content
+            style: Rich style for title (default: dim)
+        """
+        console = get_console()
+        console.print(f"[{style}]{title}:[/{style}] {content}")
+
+    @staticmethod
+    def _render_footer(message: str | None = None) -> None:
+        """Render footer content.
+
+        Args:
+            message: Optional footer message
+        """
+        console = get_console()
+        if message:
+            console.print(f"\n[dim]{message}[/dim]")
+        else:
+            console.print()
+
+    @staticmethod
+    def _render_warning(message: str) -> None:
+        """Render a warning message.
+
+        Args:
+            message: Warning text
+        """
+        console = get_console()
+        console.print(f"[yellow]⚠️  {message}[/yellow]")
+
+    @staticmethod
+    def _render_error(message: str) -> None:
+        """Render an error message.
+
+        Args:
+            message: Error text
+        """
+        console = get_console()
+        console.print(f"[red]❌ {message}[/red]")
+
+    @staticmethod
+    def _render_success(message: str) -> None:
+        """Render a success message.
+
+        Args:
+            message: Success text
+        """
+        console = get_console()
+        console.print(f"[green]✅ {message}[/green]")

roadmap/adapters/cli/presentation/cleanup_presenter.py

@@ -0,0 +1,235 @@
+"""Presenter for cleanup command output."""
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from roadmap.core.services.health.backup_cleanup_service import (
+    BackupCleanupResult as BackupResult,
+)
+from roadmap.core.services.health.file_repair_service import FileRepairResult
+
+
+class CleanupPresenter:
+    """Handles all console output for cleanup operations."""
+
+    def __init__(self):
+        """Initialize presenter."""
+        pass
+
+    def present_no_roadmap(self) -> None:
+        """Show message that roadmap is not initialized."""
+        click.secho(
+            "❌ Roadmap not initialized. Run 'roadmap init' first.",
+            fg="red",
+            bold=True,
+        )
+
+    def present_no_issues_dir(self) -> None:
+        """Show message that issues directory not found."""
+        click.secho("📋 No issues directory found.", fg="yellow")
+
+    def present_folder_check_clean(self) -> None:
+        """Show message that all issues are in correct folders."""
+        click.secho(
+            "✅ All issues appear to be in correct folders.",
+            fg="green",
+        )
+
+    def present_folder_issues(self, issues: dict[str, Any]) -> None:
+        """Show folder structure issues found."""
+        if "misplaced" in issues and issues["misplaced"]:
+            click.secho(
+                f"\n⚠️  Found {len(issues['misplaced'])} issue(s) in wrong folders:\n",
+                fg="yellow",
+                bold=True,
+            )
+            for item in issues["misplaced"]:
+                click.secho(f"  • {item['issue_id']}: {item['title']}", fg="cyan")
+                click.echo(f"    Current: {item['current_location']}")
+                click.echo(f"    Expected: {item['expected_location']}")
+            click.echo()
+
+        if "orphaned" in issues and issues["orphaned"]:
+            click.secho(
+                f"\n⚠️  Found {len(issues['orphaned'])} orphaned issue(s):\n",
+                fg="yellow",
+                bold=True,
+            )
+            for item in issues["orphaned"]:
+                click.secho(f"  • {item['issue_id']}: {item['title']}", fg="cyan")
+                click.echo(f"    Location: {item['location']}")
+            click.echo()
+
+    def present_duplicates_check_clean(self) -> None:
+        """Show message that no duplicates found."""
+        click.secho(
+            "✅ No duplicate issues found.",
+            fg="green",
+        )
+
+    def present_duplicate_issues(
+        self, duplicates: dict[str, list[Path]], roadmap_dir: Path
+    ) -> None:
+        """Show duplicate issues found."""
+        click.secho(
+            f"\n⚠️  Found {len(duplicates)} issue(s) with multiple copies:\n",
+            fg="yellow",
+            bold=True,
+        )
+
+        for issue_id, files in sorted(duplicates.items()):
+            click.secho(f"  Issue ID: {issue_id}", fg="cyan")
+            for file_path in sorted(files):
+                click.echo(f"    • {file_path.relative_to(roadmap_dir)}")
+            click.echo()
+
+    def present_malformed_check_clean(self) -> None:
+        """Show message that no malformed files found."""
+        click.secho(
+            "✅ No malformed YAML files found.",
+            fg="green",
+        )
+
+    def present_malformed_files(self, malformed_files: list[str]) -> None:
+        """Show malformed files found."""
+        click.secho(
+            f"\n⚠️  Found {len(malformed_files)} malformed file(s):\n",
+            fg="yellow",
+            bold=True,
+        )
+
+        for file_rel in malformed_files:
+            click.secho(f"  • {file_rel}", fg="cyan")
+        click.echo()
+
+    def present_backup_cleanup_dry_run(
+        self, files_to_delete: list[dict[str, Any]]
+    ) -> None:
+        """Show what backups would be deleted in dry-run mode."""
+        total_size = sum(f["size"] for f in files_to_delete)
+        size_mb = total_size / (1024 * 1024)
+
+        click.secho(
+            f"\n🔍 [DRY RUN] Would delete {len(files_to_delete)} backup file(s) ({size_mb:.2f} MB):\n",
+            fg="blue",
+            bold=True,
+        )
+        for backup in files_to_delete:
+            click.secho(
+                f"  • {backup['path'].name} ({backup['size']} bytes)",
+                fg="cyan",
+            )
+        click.secho(
+            f"\nWould free approximately {size_mb:.2f} MB of disk space.",
+            fg="green",
+        )
+
+    def present_backup_cleanup_result(self, result: BackupResult) -> None:
+        """Show backup cleanup results."""
+        click.secho(
+            f"✅ Cleaned up {result.deleted_count} backup file(s), freed ~{result.freed_mb:.2f} MB",
+            fg="green",
+            bold=True,
+        )
+        if result.failed_count > 0:
+            click.secho(
+                f"⚠️  {result.failed_count} file(s) failed to delete", fg="yellow"
+            )
+
+    def present_malformed_repair_result(self, result: FileRepairResult) -> None:
+        """Show malformed file repair results."""
+        if result.fixed_files:
+            click.secho(
+                f"✅ Fixed {len(result.fixed_files)} file(s)",
+                fg="green",
+            )
+            for file_rel in result.fixed_files:
+                click.echo(f"  • {file_rel}")
+
+        if result.errors:
+            click.secho(
+                f"⚠️  Could not fix {len(result.errors)} file(s)",
+                fg="yellow",
+            )
+            for file_rel in result.errors:
+                click.echo(f"  • {file_rel}")
+
+    def present_folder_moves(self, moves_to_make: list[dict[str, Any]]) -> None:
+        """Show folder moves that will be made."""
+        click.secho(
+            f"\n🔧 Resolving {len(moves_to_make)} issue(s) with folder structure problems:\n",
+            fg="blue",
+            bold=True,
+        )
+
+        for move in moves_to_make:
+            click.secho(
+                f"    {move['issue_id']}: {move['from']} → {move['to']}",
+                fg="cyan",
+            )
+
+    def present_folder_moves_result(self, moved_count: int, failed_count: int) -> None:
+        """Show folder move results."""
+        click.secho(
+            f"✅ Moved {moved_count} issue file(s) to correct folders",
+            fg="green",
+            bold=True,
+        )
+        if failed_count > 0:
+            click.secho(f"⚠️  {failed_count} file(s) failed to move", fg="yellow")
+
+    def present_duplicate_resolution(
+        self, duplicates: dict[str, list[Path]], roadmap_dir: Path
+    ) -> None:
+        """Show duplicate issue resolution."""
+        click.secho(
+            f"\n�� Resolving {len(duplicates)} duplicate issue(s) (keeping latest):\n",
+            fg="blue",
+            bold=True,
+        )
+
+        for issue_id, files in sorted(duplicates.items()):
+            click.secho(f"  Issue ID: {issue_id}", fg="cyan")
+
+            sorted_files = sorted(files, key=lambda f: f.stat().st_mtime, reverse=True)
+            keeper = sorted_files[0]
+            to_remove = sorted_files[1:]
+
+            click.secho(f"    Keeping: {keeper.relative_to(roadmap_dir)}", fg="green")
+            for f in to_remove:
+                click.secho(f"    Removing: {f.relative_to(roadmap_dir)}", fg="red")
+
+    def present_duplicate_resolution_result(
+        self, deleted_count: int, failed_count: int
+    ) -> None:
+        """Show duplicate resolution results."""
+        click.secho(
+            f"✅ Deleted {deleted_count} duplicate file(s)",
+            fg="green",
+            bold=True,
+        )
+        if failed_count > 0:
+            click.secho(f"⚠️  {failed_count} file(s) failed to delete", fg="yellow")
+
+    def present_cleanup_error(self, error: str) -> None:
+        """Show cleanup error."""
+        click.secho(f"❌ Cleanup failed: {error}", fg="red", bold=True)
+
+    def present_dry_run_skipped(self) -> None:
+        """Show message about dry-run skipping certain operations."""
+        click.echo(
+            "\n[DRY RUN] Folder and duplicate resolution skipped in preview mode"
+        )
+
+    def present_no_backups(self) -> None:
+        """Show message that no backups found."""
+        click.secho("📋 No backup files found.", fg="yellow")
+
+    def present_no_cleanup_needed(self) -> None:
+        """Show message that no cleanup is needed."""
+        click.secho(
+            "✅ No backup files need to be cleaned up.",
+            fg="green",
+        )