roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/decorators.py

@@ -0,0 +1,208 @@
+"""Click command decorators for structured output with filtering/sorting.
+
+Provides @with_output_support decorator that adds:
+- --format flag (rich, plain, json, csv, markdown)
+- --columns flag (select columns)
+- --sort-by flag (sort results)
+- --filter flag (filter results)
+
+Usage:
+    @click.command()
+    @with_output_support(
+        available_columns=["id", "name", "status"],
+        column_types={"id": ColumnType.INTEGER, "status": ColumnType.ENUM, ...}
+    )
+    def list_issues(format, columns, sort_by, filter):
+        # Command logic returns TableData
+        return TableData(...)
+"""
+
+from collections.abc import Callable
+from functools import wraps
+
+import click
+
+from roadmap.adapters.cli.layout import SmartTableLayout
+from roadmap.common.console import get_console
+from roadmap.common.models import ColumnType, TableData
+from roadmap.common.utils.cli_helpers import (
+    ColumnSelector,
+    FilterSpecParser,
+    OutputFormatHandler,
+    SortSpecParser,
+)
+
+
+def with_output_support(
+    available_columns: list[str] | None = None,
+    column_types: dict[str, ColumnType] | None = None,
+):
+    """Add output formatting support to Click commands.
+
+    Adds three flags to command:
+    - --format: Output format (rich, plain, json, csv, markdown)
+    - --columns: Columns to display (comma-separated)
+    - --sort-by: Sort specification (format: col:asc,col2:desc)
+    - --filter: Filter specification (format: col=value,col2>=5)
+
+    Args:
+        available_columns: List of valid column names for selection.
+        column_types: Dict mapping column names to ColumnType for filter validation.
+
+    Example:
+        @click.command()
+        @with_output_support(
+            available_columns=["id", "title", "status", "created"],
+            column_types={
+                "id": ColumnType.INTEGER,
+                "status": ColumnType.ENUM,
+                "created": ColumnType.DATETIME,
+            }
+        )
+        def list_issues(format, columns, sort_by, filter):
+            issues = issue_service.list_all()
+            table = build_table_from_issues(issues)
+            return table
+
+    Returns:
+        Decorator function.
+    """
+    available_columns = available_columns or []
+    column_types = column_types or {}
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(
+            *args, format=None, columns=None, sort_by=None, filter_spec=None, **kwargs
+        ):
+            # Call original command with all non-format-related params
+            result = func(*args, **kwargs)
+
+            # If result is TableData, apply formatting/filtering/sorting
+            if isinstance(result, TableData):
+                # Parse and apply column selection
+                if columns:
+                    selected_cols = ColumnSelector.parse(columns, available_columns)
+                    if selected_cols:
+                        result = result.select_columns(selected_cols)
+
+                # Parse and apply sorting
+                if sort_by:
+                    sort_spec = SortSpecParser.parse(sort_by, available_columns)
+                    if sort_spec:
+                        result = result.sort(sort_spec)
+
+                # Parse and apply filtering
+                if filter_spec and column_types:
+                    filters = FilterSpecParser.parse(filter_spec, column_types)
+                    if filters:
+                        for filt in filters:
+                            # Simple equality filtering for now
+                            if filt.operator == "=":
+                                result = result.filter(filt.column, filt.value)
+
+                # Render in requested format
+                if format and format.lower() != "rich":
+                    output = OutputFormatHandler.render(result, format.lower())
+                    console = get_console()
+                    console.print(output)
+                    return  # Don't return TableData, output already printed
+                elif format and format.lower() == "rich":
+                    # Use smart responsive layout for 'rich' format
+                    layout = SmartTableLayout()
+                    renderable = layout.render(result)
+                    console = get_console()
+                    console.print(renderable)
+                    return  # Rich was printed directly
+                else:
+                    # Default: return TableData (backwards compat)
+                    return result
+
+            return result
+
+        # Add Click options (decorators are applied bottom-up)
+        wrapper = click.option(
+            "--filter",
+            "filter_spec",
+            help=FilterSpecParser.get_help_text() if column_types else None,
+        )(wrapper)
+
+        wrapper = click.option(
+            "--sort-by",
+            help=SortSpecParser.get_help_text() if available_columns else None,
+        )(wrapper)
+
+        wrapper = click.option(
+            "--columns",
+            help=ColumnSelector.get_help_text(available_columns)
+            if available_columns
+            else None,
+        )(wrapper)
+
+        wrapper = click.option(
+            "--format",
+            type=click.Choice(
+                ["rich", "plain", "json", "csv", "markdown"], case_sensitive=False
+            ),
+            default="rich",
+            help="Output format (rich=default, plain=POSIX, json=machine-readable, csv=analysis)",
+        )(wrapper)
+
+        return wrapper
+
+    return decorator
+
+
+def add_output_flags(
+    available_columns: list[str] | None = None,
+    column_types: dict[str, ColumnType] | None = None,
+) -> Callable:
+    """Simpler decorator that just adds flags without automatic processing.
+
+    Use this if you want manual control over how formatting is applied.
+    The flags are added to the command, and you handle them manually.
+
+    Example:
+        @click.command()
+        @add_output_flags(available_columns=["id", "name"])
+        def my_command(format, columns, sort_by, filter):
+            # You handle the flags manually
+            ...
+
+    Returns:
+        Decorator function.
+    """
+    available_columns = available_columns or []
+    column_types = column_types or {}
+
+    def decorator(func: Callable) -> Callable:
+        func = click.option(
+            "--format",
+            type=click.Choice(
+                ["rich", "plain", "json", "csv", "markdown"], case_sensitive=False
+            ),
+            default="rich",
+            help="Output format",
+        )(func)
+
+        func = click.option(
+            "--columns",
+            help=ColumnSelector.get_help_text(available_columns)
+            if available_columns
+            else None,
+        )(func)
+
+        func = click.option(
+            "--sort-by",
+            help=SortSpecParser.get_help_text() if available_columns else None,
+        )(func)
+
+        func = click.option(
+            "--filter",
+            "filter_spec",
+            help=FilterSpecParser.get_help_text() if column_types else None,
+        )(func)
+
+        return func
+
+    return decorator

roadmap/adapters/cli/dtos/__init__.py

@@ -0,0 +1,155 @@
+"""CLI Data Transfer Objects (DTOs).
+
+This module provides lightweight data transfer objects for the CLI layer.
+DTOs decouple the CLI presentation layer from domain models, enabling:
+- Selective field exposure (hide implementation details)
+- Type conversion to CLI-friendly formats
+- Easier testing with mocks
+- Cleaner separation of concerns
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class BaseDTO:
+    """Base class for all DTOs with common functionality."""
+
+    @classmethod
+    def from_dict(cls, data: dict):
+        """Create DTO from dictionary (flexible initialization)."""
+        # Filter to only include known fields
+        fields = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in fields}
+        return cls(**filtered)
+
+
+@dataclass
+class IssueDTO(BaseDTO):
+    """CLI-level issue representation for presentation and commands.
+
+    This DTO provides a CLI-friendly view of issues, converting domain enums
+    to strings and hiding internal implementation details.
+
+    Attributes:
+        id: Unique issue identifier
+        title: Issue title/summary
+        priority: Priority level (string, not enum)
+        status: Current status (string, not enum)
+        issue_type: Type of issue (string, not enum)
+        assignee: Assigned user, if any
+        milestone: Associated milestone name, if any
+        due_date: When issue should be completed
+        estimated_hours: Estimated time in hours
+        actual_end_date: When issue was completed
+        progress_percentage: Completion percentage (0-100)
+        created: When issue was created
+        updated: Last update time
+    """
+
+    id: str
+    title: str
+    priority: str  # String, not enum (e.g., "high", "medium")
+    status: str  # String, not enum (e.g., "todo", "in_progress")
+    headline: str = ""  # Short summary for list views
+    issue_type: str = "other"  # String, not enum
+    assignee: str | None = None
+    milestone: str | None = None
+    due_date: datetime | None = None
+    estimated_hours: float | None = None
+    actual_end_date: datetime | None = None
+    progress_percentage: float | None = None
+    created: datetime | None = None
+    updated: datetime | None = None
+    # Extended fields for detailed views
+    content: str | None = None
+    labels: list[str] = field(default_factory=list)
+    github_issue: str | None = None
+    comments: list["CommentDTO"] = field(default_factory=list)
+
+
+@dataclass
+class MilestoneDTO(BaseDTO):
+    """CLI-level milestone representation.
+
+    Attributes:
+        id: Unique milestone identifier (usually name)
+        name: Milestone name
+        status: Status (string, not enum)
+        due_date: Target completion date
+        description: Milestone description
+        progress_percentage: Overall completion percentage
+        issue_count: Number of associated issues
+        completed_count: Number of completed issues
+    """
+
+    id: str
+    name: str
+    status: str  # String, not enum
+    headline: str = ""  # Short summary for list views
+    due_date: datetime | None = None
+    progress_percentage: float | None = None
+    issue_count: int = 0
+    completed_count: int = 0
+    created: datetime | None = None
+    updated: datetime | None = None
+
+
+@dataclass
+class ProjectDTO(BaseDTO):
+    """CLI-level project representation.
+
+    Attributes:
+        id: Unique project identifier
+        name: Project name
+        status: Status (string, not enum)
+        description: Project description
+        owner: Project owner/creator
+        target_end_date: Target completion date
+        actual_end_date: Actual completion date
+        milestone_count: Number of milestones
+        issue_count: Total number of issues
+    """
+
+    id: str
+    name: str
+    status: str  # String, not enum
+    headline: str = ""  # Short summary for list views
+    owner: str | None = None
+    target_end_date: datetime | None = None
+    actual_end_date: datetime | None = None
+    milestone_count: int = 0
+    issue_count: int = 0
+    created: datetime | None = None
+    updated: datetime | None = None
+
+
+@dataclass
+class CommentDTO(BaseDTO):
+    """CLI-level comment representation.
+
+    Attributes:
+        id: Unique comment identifier
+        author: Comment author name/username
+        body: Comment content (markdown)
+        created_at: When comment was created
+        updated_at: Last update time
+        in_reply_to: Optional comment ID this is a reply to
+    """
+
+    id: int
+    author: str
+    body: str
+    created_at: datetime
+    updated_at: datetime
+    in_reply_to: int | None = None
+
+
+__all__ = [
+    "BaseDTO",
+    "CommentDTO",
+    "IssueDTO",
+    "MilestoneDTO",
+    "ProjectDTO",
+]

roadmap/adapters/cli/exception_handler.py

@@ -0,0 +1,105 @@
+"""Centralized exception handling for CLI commands.
+
+This module provides error handling and formatting for all exceptions
+raised by CLI commands, ensuring consistent user-facing error messages
+and proper stderr output with correct exit codes.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from roadmap.common.console import get_console_stderr
+from roadmap.common.error_formatter import (
+    format_error_message,
+)
+from roadmap.common.errors.exceptions import RoadmapException
+
+
+def handle_cli_exception(
+    ctx: click.Context, error: Exception, show_traceback: bool = False
+) -> None:
+    """Centralized exception handler for CLI commands.
+
+    Catches RoadmapException instances and formats them for user output,
+    directing errors to stderr with proper exit codes. Other exceptions
+    are re-raised or logged as needed.
+
+    Args:
+        ctx: Click context
+        error: The exception to handle
+        show_traceback: Whether to show full traceback (for debugging)
+    """
+    stderr_console = get_console_stderr()
+
+    if isinstance(error, RoadmapException):
+        # Format using our error formatter, which respects plain mode
+        error_msg = format_error_message(error)
+        stderr_console.print(error_msg)
+        ctx.exit(error.exit_code)
+    else:
+        # For non-roadmap exceptions, show generic error message
+        error_msg = format_error_message(error)
+        stderr_console.print(error_msg)
+        if show_traceback:
+            stderr_console.print_exception()
+        ctx.exit(1)
+
+
+def with_exception_handler(
+    show_traceback: bool = False,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Wrap CLI commands with centralized exception handling.
+
+    Args:
+        show_traceback: Whether to show full traceback on error
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Implement exception handling decorator."""
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Execute wrapped function with exception handling."""
+            try:
+                return func(*args, **kwargs)
+            except click.Abort:
+                # Click.Abort is intentional, don't handle it
+                raise
+            except click.ClickException:
+                # Click exceptions are already formatted, re-raise
+                raise
+            except RoadmapException as e:
+                # Format roadmap exceptions for output
+                ctx = click.get_current_context()
+                handle_cli_exception(ctx, e, show_traceback=show_traceback)
+            except Exception as e:
+                # Unexpected exceptions get generic handling
+                ctx = click.get_current_context()
+                handle_cli_exception(ctx, e, show_traceback=show_traceback)
+
+        return click.pass_context(wrapper)
+
+    return decorator
+
+
+def setup_cli_exception_handling() -> None:
+    """Set up global exception handling for the CLI group.
+
+    This configures Click to use our custom exception handler for all
+    subcommands in the CLI group.
+
+    Args:
+        main_group: The Click group (main CLI) to configure
+    """
+
+    def handle_exception(ctx: click.Context, exc: Exception) -> None:
+        """Click exception callback."""
+        handle_cli_exception(ctx, exc, show_traceback=False)
+
+    # Note: Click's exception handling is context-specific;
+    # individual commands should use the decorator for best results
+    # The group-level handling provides a fallback

roadmap/adapters/cli/git/__init__.py

@@ -0,0 +1,8 @@
+"""Git integration and workflow commands.
+
+Commands for git operations and Git-roadmap integration.
+"""
+
+from .commands import git
+
+__all__ = ["git"]