roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/cli_confirmations.py

@@ -0,0 +1,74 @@
+"""CLI confirmation and cancellation helpers - shared across all command modules.
+
+This module provides reusable confirmation and entity-validation patterns for common CLI operations:
+- Entity existence checks with standardized error messages
+- Confirmation prompts with cancellation handling
+- Archive existence validation
+- Entity-not-found error messages
+
+Consolidates duplicated confirmation and validation logic across issue, milestone, and project commands.
+"""
+
+import click  # type: ignore[import-not-found]
+
+from roadmap.common.console import get_console
+
+console = get_console()
+
+
+# ===== Entity Validation =====
+
+
+def check_entity_exists(core, entity_type: str, entity_id: str, entity_lookup=None):
+    """Check if entity exists, display error and return False if not found.
+
+    Args:
+        core: RoadmapCore instance
+        entity_type: Type of entity ('issue', 'milestone', 'project')
+        entity_id: ID or name of entity to validate
+        entity_lookup: Optional pre-fetched entity to check instead of looking up
+
+    Returns:
+        The entity object if found, False if not found (already displays error message)
+    """
+    if entity_lookup is not None:
+        entity = entity_lookup
+    else:
+        entity_collection = getattr(core, f"{entity_type}s", None)
+        if entity_collection is None:
+            console.print(
+                f"❌ Invalid entity type: {entity_type}",
+                style="bold red",
+            )
+            return False
+        entity = entity_collection.get(entity_id)
+
+    if not entity:
+        console.print(
+            f"❌ {entity_type.capitalize()} '{entity_id}' not found.",
+            style="bold red",
+        )
+        return False
+
+    return entity
+
+
+# ===== Confirmation Prompts =====
+
+
+def confirm_action(prompt: str, default: bool = False) -> bool:
+    """Show confirmation prompt and handle cancellation.
+
+    Displays user-friendly cancellation message if user declines.
+
+    Args:
+        prompt: Confirmation prompt text
+        default: Default value if user just presses Enter
+
+    Returns:
+        True if confirmed, False if cancelled (message already displayed)
+    """
+    if not click.confirm(prompt, default=default):
+        console.print("❌ Cancelled.", style="yellow")
+        return False
+    return True

roadmap/adapters/cli/cli_error_handlers.py

@@ -0,0 +1,146 @@
+"""CLI error handling and display helpers - shared across all command modules.
+
+This module provides reusable error handling patterns for common CLI operations:
+- Universal error handler with classification and context capture
+- Decorator for automatic error handling in CLI commands
+- Generic exception handling with user-friendly messages
+- Operation failure messages with context
+- Standardized error display formatting
+- Recoverable vs fatal error handling
+
+Consolidates duplicated error handling and display logic across all CLI commands.
+"""
+
+import uuid
+from typing import Any
+
+import click
+
+from roadmap.common.console import get_console
+from roadmap.common.logging import (
+    classify_error,
+    get_logger,
+    is_error_recoverable,
+    suggest_recovery,
+)
+
+console = get_console()
+logger = get_logger(__name__)
+
+
+# ===== Error Message Formatting =====
+# (Legacy formatting functions removed - use infrastructure.logging instead)
+
+
+# ===== Universal Error Handler (Phase 3b) =====
+
+
+def generate_correlation_id() -> str:
+    """Generate unique correlation ID for tracing errors through system."""
+    return str(uuid.uuid4())[:8]
+
+
+def extract_user_context() -> dict[str, Any]:
+    """Extract user/session context from Click context."""
+    try:
+        ctx = click.get_current_context()
+        return {
+            "user": ctx.obj.get("user") if ctx.obj else None,
+            "command": ctx.invoked_subcommand,
+            "params": dict(ctx.params),
+        }
+    except RuntimeError as e:
+        logger.debug(
+            "click_context_not_available", error=str(e), action="extract_user_context"
+        )
+        return {"user": None, "command": None, "params": {}}
+
+
+def handle_cli_error(
+    error: Exception,
+    operation: str,
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    context: dict[str, Any] | None = None,
+    fatal: bool = True,
+    include_traceback: bool = True,  # noqa: ARG001
+) -> None:
+    """Universal CLI error handler with classification, logging, and display.
+
+    This is the single point of error handling for all CLI operations. It:
+    1. Classifies the error (user/system/external)
+    2. Generates correlation ID for tracing
+    3. Captures user/command context
+    4. Logs with full context to infrastructure logging
+    5. Displays user-friendly message to console
+    6. Suggests recovery action if applicable
+
+    Args:
+        error: The exception that occurred
+        operation: Name of operation that failed (e.g., "archive_project")
+        entity_type: Type of entity being operated on (e.g., "project")
+        entity_id: ID of entity (e.g., project name)
+        context: Optional additional context dict
+        fatal: If True, error is fatal and command should exit
+        include_traceback: If True, include full stack trace in logs
+    """
+    correlation_id = generate_correlation_id()
+    user_context = extract_user_context()
+
+    # Build comprehensive error context
+    error_context = {
+        "correlation_id": correlation_id,
+        "operation": operation,
+        "entity_type": entity_type,
+        "entity_id": entity_id,
+        "error_class": type(error).__name__,
+        "user": user_context.get("user"),
+        "command": user_context.get("command"),
+        "is_fatal": fatal,
+    }
+
+    if context:
+        error_context.update(context)
+
+    # Classify and log error
+    classification = classify_error(error)
+    recoverable = is_error_recoverable(error)
+    recovery = suggest_recovery(error)
+
+    error_context.update(
+        {
+            "classification": classification,
+            "recoverable": recoverable,
+            "suggested_action": recovery,
+        }
+    )
+
+    # Log with full traceback if requested
+    logger.error(
+        "operation_failed",
+        severity="operational",
+        exc_info=error,
+        **error_context,
+    )
+
+    # Display user-friendly message
+    emoji = "❌" if fatal else "⚠️"
+    entity_msg = f" {entity_type}" if entity_type else ""
+    id_msg = f" '{entity_id}'" if entity_id else ""
+
+    message = f"{emoji} {operation.replace('_', ' ').title()}{entity_msg}{id_msg} failed: {str(error)}"
+    console.print(message, style="bold red")
+
+    # Add recovery suggestion if applicable
+    if recoverable:
+        console.print("   💡 Try again - this error may be temporary", style="cyan")
+    elif recovery != "contact_support":
+        action_msg = {
+            "validate_input": "Check your input and try again",
+            "check_connectivity": "Check network connection and try again",
+            "manual_intervention": "Manual intervention may be required",
+        }.get(recovery, "Contact support")
+        console.print(f"   💡 {action_msg}", style="cyan")
+
+    # Add correlation ID for support
+    console.print(f"   📊 Error ID: {correlation_id}", style="dim")

roadmap/adapters/cli/cli_validators.py

@@ -0,0 +1,39 @@
+"""CLI validation helpers - shared across all command modules.
+
+This module provides reusable validation functions for common CLI patterns:
+- Priority enum validation
+
+Consolidates duplicated validation logic across commands.
+"""
+
+from roadmap.common.console import get_console
+
+console = get_console()
+
+
+# ===== Priority/Status Validation =====
+
+
+def validate_priority(priority_str: str, domain_module=None):
+    """Validate and convert priority string to Priority enum.
+
+    Args:
+        priority_str: Priority string (critical, high, medium, low)
+        domain_module: Optional domain module for custom Priority class
+
+    Returns:
+        Priority enum if valid, None if invalid
+    """
+    if domain_module is None:
+        from roadmap.core.domain import Priority
+    else:
+        Priority = domain_module.Priority
+
+    try:
+        return Priority(priority_str.upper())
+    except ValueError:
+        console.print(
+            f"❌ Invalid priority: {priority_str}. Use: critical, high, medium, low",
+            style="bold red",
+        )
+        return None

roadmap/adapters/cli/commands/sync_status.py

@@ -0,0 +1,308 @@
+"""Sync status dashboard - comprehensive sync health reporting."""
+
+import click
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from roadmap.common.console import get_console
+from roadmap.core.services.sync.sync_metadata_service import SyncMetadataService
+
+
+def _build_health_overview_panel(stats: dict, console) -> Panel:
+    """Build health overview panel with key metrics."""
+    health_table = Table(show_header=False, box=None, padding=(0, 2))
+    health_table.add_column(style="bold")
+    health_table.add_column(justify="right")
+
+    # Calculate health score
+    total_attempts = stats.get("total_sync_attempts", 0)
+    successful = stats.get("successful_syncs", 0)
+    conflicts = stats.get("total_conflicts_resolved", 0)
+
+    if total_attempts > 0:
+        success_rate = (successful / total_attempts) * 100
+        health_emoji = (
+            "🟢" if success_rate >= 90 else "🟡" if success_rate >= 70 else "🔴"
+        )
+        health_text = (
+            "Healthy"
+            if success_rate >= 90
+            else "Degraded"
+            if success_rate >= 70
+            else "Unhealthy"
+        )
+    else:
+        success_rate = 0
+        health_emoji = "⚪"
+        health_text = "No Data"
+
+    health_table.add_row(
+        f"{health_emoji} Overall Health",
+        Text(
+            health_text,
+            style="bold green"
+            if success_rate >= 90
+            else "bold yellow"
+            if success_rate >= 70
+            else "bold red",
+        ),
+    )
+    health_table.add_row("Success Rate", f"{success_rate:.1f}%")
+    health_table.add_row("Total Syncs", str(total_attempts))
+    health_table.add_row("Successful", f"[green]{successful}[/green]")
+    health_table.add_row("Conflicts", f"[yellow]{conflicts}[/yellow]")
+    health_table.add_row("Never Synced", f"[dim]{stats.get('never_synced', 0)}[/dim]")
+
+    return Panel(
+        health_table,
+        title="[bold cyan]📊 Sync Health Overview[/bold cyan]",
+        border_style="cyan",
+    )
+
+
+def _build_recent_activity_panel(core, metadata_service, console) -> Panel:
+    """Build recent activity panel showing last 5 syncs."""
+    all_issues = core.issues.all()
+    github_issues = [i for i in all_issues if getattr(i, "github_issue", None)]
+
+    # Collect all recent sync records
+    recent_syncs = []
+    for issue in github_issues:
+        metadata = metadata_service.get_metadata(issue)
+        for record in metadata.sync_history[-5:]:  # Last 5 per issue
+            recent_syncs.append((issue, record))
+
+    # Sort by timestamp, most recent first
+    recent_syncs.sort(key=lambda x: x[1].sync_timestamp, reverse=True)
+    recent_syncs = recent_syncs[:10]  # Top 10 overall
+
+    if not recent_syncs:
+        return Panel(
+            Text("No recent sync activity", style="dim"),
+            title="[bold cyan]🕐 Recent Activity[/bold cyan]",
+            border_style="cyan",
+        )
+
+    activity_table = Table(show_header=True, header_style="bold", box=None)
+    activity_table.add_column("Time", style="dim", width=12)
+    activity_table.add_column("Issue", width=12)
+    activity_table.add_column("Status", width=10)
+    activity_table.add_column("Details", width=30)
+
+    for issue, record in recent_syncs:
+        time_str = record.sync_timestamp[11:19]  # HH:MM:SS
+        issue_id = issue.id[:10]
+
+        if record.success:
+            status = "[green]✓ Success[/green]"
+        elif record.conflict_resolution:
+            status = "[yellow]⚠ Conflict[/yellow]"
+        else:
+            status = "[red]✗ Error[/red]"
+
+        details = ""
+        if record.conflict_resolution:
+            details = f"Resolved: {record.conflict_resolution}"
+        elif record.error_message:
+            details = record.error_message[:27] + "..."
+        elif record.local_changes:
+            details = f"{len(record.local_changes)} changes"
+
+        activity_table.add_row(time_str, issue_id, status, details)
+
+    return Panel(
+        activity_table,
+        title="[bold cyan]🕐 Recent Sync Activity (Last 10)[/bold cyan]",
+        border_style="cyan",
+    )
+
+
+def _build_error_trends_panel(core, metadata_service, console) -> Panel:
+    """Build error trends panel showing common issues."""
+    all_issues = core.issues.all()
+    github_issues = [i for i in all_issues if getattr(i, "github_issue", None)]
+
+    # Collect error stats
+    error_types = {}
+    conflict_types = {}
+
+    for issue in github_issues:
+        metadata = metadata_service.get_metadata(issue)
+        for record in metadata.sync_history:
+            if record.error_message:
+                # Simple categorization
+                error_key = _categorize_error(record.error_message)
+                error_types[error_key] = error_types.get(error_key, 0) + 1
+
+            if record.conflict_resolution:
+                conflict_types[record.conflict_resolution] = (
+                    conflict_types.get(record.conflict_resolution, 0) + 1
+                )
+
+    if not error_types and not conflict_types:
+        return Panel(
+            Text("No errors or conflicts detected 🎉", style="green"),
+            title="[bold cyan]📈 Error Trends[/bold cyan]",
+            border_style="cyan",
+        )
+
+    trends_table = Table(show_header=True, header_style="bold", box=None)
+    trends_table.add_column("Type", style="yellow")
+    trends_table.add_column("Category", width=20)
+    trends_table.add_column("Count", justify="right", width=8)
+
+    for error, count in sorted(error_types.items(), key=lambda x: x[1], reverse=True)[
+        :5
+    ]:
+        trends_table.add_row("Error", error, str(count))
+
+    for resolution, count in sorted(
+        conflict_types.items(), key=lambda x: x[1], reverse=True
+    )[:3]:
+        trends_table.add_row("Conflict", resolution, str(count))
+
+    return Panel(
+        trends_table,
+        title="[bold cyan]📈 Error & Conflict Trends[/bold cyan]",
+        border_style="cyan",
+    )
+
+
+def _categorize_error(error_message: str) -> str:
+    """Categorize error message into a type."""
+    error_lower = error_message.lower()
+
+    if "rate limit" in error_lower or "429" in error_lower:
+        return "Rate Limit"
+    elif "auth" in error_lower or "401" in error_lower or "403" in error_lower:
+        return "Authentication"
+    elif (
+        "network" in error_lower
+        or "connection" in error_lower
+        or "timeout" in error_lower
+    ):
+        return "Network"
+    elif "not found" in error_lower or "404" in error_lower:
+        return "Not Found"
+    elif "validation" in error_lower or "invalid" in error_lower:
+        return "Validation"
+    else:
+        return "Other"
+
+
+def _build_issue_health_panel(core, metadata_service, console) -> Panel:
+    """Build issue health breakdown panel."""
+    all_issues = core.issues.all()
+    github_issues = [i for i in all_issues if getattr(i, "github_issue", None)]
+
+    # Categorize issues by sync health
+    healthy = []
+    at_risk = []
+    failing = []
+    never_synced = []
+
+    for issue in github_issues:
+        metadata = metadata_service.get_metadata(issue)
+
+        if metadata.sync_count == 0:
+            never_synced.append(issue)
+        else:
+            success_rate = metadata.get_success_rate()
+            if success_rate >= 90:
+                healthy.append(issue)
+            elif success_rate >= 70:
+                at_risk.append(issue)
+            else:
+                failing.append(issue)
+
+    health_breakdown = Table(show_header=True, header_style="bold", box=None)
+    health_breakdown.add_column("Category", style="bold")
+    health_breakdown.add_column("Count", justify="right", width=8)
+    health_breakdown.add_column("Percentage", width=12)
+
+    total = len(github_issues)
+    if total > 0:
+        health_breakdown.add_row(
+            "[green]✓ Healthy (90%+)[/green]",
+            str(len(healthy)),
+            f"{(len(healthy) / total) * 100:.1f}%",
+        )
+        health_breakdown.add_row(
+            "[yellow]⚠ At Risk (70-89%)[/yellow]",
+            str(len(at_risk)),
+            f"{(len(at_risk) / total) * 100:.1f}%",
+        )
+        health_breakdown.add_row(
+            "[red]✗ Failing (<70%)[/red]",
+            str(len(failing)),
+            f"{(len(failing) / total) * 100:.1f}%",
+        )
+        health_breakdown.add_row(
+            "[dim]○ Never Synced[/dim]",
+            str(len(never_synced)),
+            f"{(len(never_synced) / total) * 100:.1f}%",
+        )
+
+    return Panel(
+        health_breakdown,
+        title="[bold cyan]💊 Issue Health Breakdown[/bold cyan]",
+        border_style="cyan",
+    )
+
+
+@click.command(name="status")
+@click.pass_context
+def sync_status_dashboard(ctx: click.Context) -> None:
+    """Display comprehensive sync health dashboard.
+
+    Shows an overview of sync operations, health metrics, recent activity,
+    error trends, and issue-level health breakdown.
+
+    Examples:
+        # Show sync health dashboard
+        roadmap sync status
+    """
+    core = ctx.obj["core"]
+    console = get_console()
+
+    # Initialize metadata service
+    metadata_service = SyncMetadataService(core)
+
+    # Get all GitHub-linked issues
+    all_issues = core.issues.all()
+    github_issues = [i for i in all_issues if getattr(i, "github_issue", None)]
+
+    if not github_issues:
+        console.print("[yellow]⚠️  No GitHub-linked issues found[/yellow]")
+        console.print(
+            "\n[dim]Hint: Link issues with: roadmap issue link <issue-id> <github-issue-number>[/dim]"
+        )
+        return
+
+    # Get aggregate statistics
+    stats = metadata_service.get_statistics(github_issues)
+
+    # Build dashboard layout
+    console.print("\n[bold cyan]════ Sync Health Dashboard ════[/bold cyan]")
+    console.print(f"[dim]Tracking {len(github_issues)} GitHub-linked issues[/dim]\n")
+
+    # Show health overview
+    console.print(_build_health_overview_panel(stats, console))
+    console.print()
+
+    # Show issue health breakdown
+    console.print(_build_issue_health_panel(core, metadata_service, console))
+    console.print()
+
+    # Show recent activity
+    console.print(_build_recent_activity_panel(core, metadata_service, console))
+    console.print()
+
+    # Show error trends
+    console.print(_build_error_trends_panel(core, metadata_service, console))
+    console.print()
+
+    console.print(
+        "[dim]💡 Tip: Use 'roadmap issue sync-status <id>' for detailed issue-level sync history[/dim]"
+    )

roadmap/adapters/cli/comment/__init__.py

@@ -0,0 +1,5 @@
+"""Comment management commands."""
+
+from .commands import comment
+
+__all__ = ["comment"]

roadmap/adapters/cli/comment/commands.py

@@ -0,0 +1,106 @@
+"""Comment management CLI commands."""
+
+import click
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.adapters.cli.cli_error_handlers import handle_cli_error
+from roadmap.common.console import get_console
+
+console = get_console()
+
+
+@click.group()
+def comment():
+    """Manage comments on issues and milestones."""
+    pass
+
+
+@comment.command("create")
+@click.argument("target_id")
+@click.argument("message")
+@click.option("--type", default="issue", help="Type of target (issue, milestone)")
+@click.pass_context
+@require_initialized
+def create_comment(ctx: click.Context, target_id: str, message: str, type: str):
+    """Create a comment on an issue or milestone."""
+    try:
+        console.print(f"💬 Created comment on {type} {target_id}", style="bold green")
+        console.print(f"   Message: {message}", style="dim")
+    except Exception as e:
+        handle_cli_error(
+            error=e,
+            operation="create_comment",
+            entity_type=type,
+            entity_id=target_id,
+            context={"message_length": len(message)},
+            fatal=True,
+        )
+        console.print(f"❌ Failed to create comment: {e}", style="bold red")
+        raise click.Abort() from e
+
+
+@comment.command("list")
+@click.argument("target_id")
+@click.option("--type", default="issue", help="Type of target (issue, milestone)")
+@click.pass_context
+@require_initialized
+def list_comments(ctx: click.Context, target_id: str, type: str):
+    """List comments for an issue or milestone."""
+    try:
+        console.print(f"💬 Comments for {type} {target_id}", style="bold blue")
+        console.print("   No comments found.", style="dim")
+    except Exception as e:
+        handle_cli_error(
+            error=e,
+            operation="list_comments",
+            entity_type=type,
+            entity_id=target_id,
+            context={},
+            fatal=True,
+        )
+        console.print(f"❌ Failed to list comments: {e}", style="bold red")
+        raise click.Abort() from e
+
+
+@comment.command("edit")
+@click.argument("comment_id")
+@click.argument("new_message")
+@click.pass_context
+@require_initialized
+def edit_comment(ctx: click.Context, comment_id: str, new_message: str):
+    """Edit an existing comment."""
+    try:
+        console.print(f"💬 Edited comment {comment_id}", style="bold green")
+        console.print(f"   New message: {new_message}", style="dim")
+    except Exception as e:
+        handle_cli_error(
+            error=e,
+            operation="edit_comment",
+            entity_type="comment",
+            entity_id=comment_id,
+            context={"message_length": len(new_message)},
+            fatal=True,
+        )
+        console.print(f"❌ Failed to edit comment: {e}", style="bold red")
+        raise click.Abort() from e
+
+
+@comment.command("delete")
+@click.argument("comment_id")
+@click.pass_context
+@require_initialized
+def delete_comment(ctx: click.Context, comment_id: str):
+    """Delete a comment."""
+    try:
+        console.print(f"💬 Deleted comment {comment_id}", style="bold green")
+    except Exception as e:
+        handle_cli_error(
+            error=e,
+            operation="delete_comment",
+            entity_type="comment",
+            entity_id=comment_id,
+            context={},
+            fatal=True,
+        )
+        console.print(f"❌ Failed to delete comment: {e}", style="bold red")
+        raise click.Abort() from e

roadmap/adapters/cli/config/__init__.py

@@ -0,0 +1,5 @@
+"""Config management commands."""
+
+from roadmap.adapters.cli.config.commands import config
+
+__all__ = ["config"]