Merge pull request #1060 from DataRecce/feature/drc-2592-cli-add-recce-doctor-command-for-environment-diagnostics

feat(cli): Add recce-cloud doctor command for environment diagnostics (DRC-2592)

Author: wcchang1115

recce_cloud/recce_cloud/auth/login.py

@@ -251,10 +251,14 @@ def check_login_status() -> Tuple[bool, Optional[str]]:
     """
     Check current login status.
 
+    Checks for authentication token in this order:
+    1. RECCE_API_TOKEN environment variable
+    2. Stored token from profile (via get_api_token)
+
     Returns:
         Tuple of (is_logged_in, user_email_or_none).
     """
-    token = get_api_token()
+    token = os.getenv("RECCE_API_TOKEN") or get_api_token()
     if not token:
         return False, None
 

recce_cloud/recce_cloud/cli.py

@@ -7,6 +7,7 @@
 import os
 import subprocess
 import sys
+from typing import Optional
 
 import click
 from rich.console import Console
@@ -15,6 +16,7 @@
 from recce_cloud import __version__
 from recce_cloud.artifact import get_adapter_type, verify_artifacts_path
 from recce_cloud.ci_providers import CIDetector
+from recce_cloud.commands.diagnostics import doctor
 from recce_cloud.delete import (
     delete_existing_session,
     delete_with_platform_apis,
@@ -49,6 +51,10 @@ def cloud_cli():
     pass
 
 
+# Register commands from command modules
+cloud_cli.add_command(doctor)
+
+
 @cloud_cli.command()
 def version():
     """Show the version of recce-cloud."""
@@ -359,10 +365,89 @@ def init(org, project, status, clear):
         console.print(f"[red]Error:[/red] Failed to fetch data from Recce Cloud: {e}")
         sys.exit(1)
     except Exception as e:
-        console.print(f"[red]Error:[/red] {e}")
+        logger.debug("Unexpected error during init: %s", e, exc_info=True)
+        console.print(f"[red]Error:[/red] An unexpected error occurred: {e}")
+        console.print("  Try running 'recce-cloud login' again or check your network connection.")
         sys.exit(1)
 
 
+def _get_production_session_id(console: Console, token: str) -> Optional[str]:
+    """
+    Fetch the production session ID from Recce Cloud.
+
+    Returns the session ID if found, None otherwise (with error message printed).
+    """
+    from recce_cloud.api.client import RecceCloudClient
+    from recce_cloud.api.exceptions import RecceCloudException
+    from recce_cloud.config.project_config import get_project_binding
+
+    # Get project binding
+    binding = get_project_binding()
+    if not binding:
+        # Check environment variables as fallback
+        env_org = os.environ.get("RECCE_ORG")
+        env_project = os.environ.get("RECCE_PROJECT")
+        if env_org and env_project:
+            binding = {"org": env_org, "project": env_project}
+        else:
+            console.print("[red]Error:[/red] No project binding found")
+            console.print("Run 'recce-cloud init' to bind this directory to a project")
+            return None
+
+    org_slug = binding.get("org")
+    project_slug = binding.get("project")
+
+    try:
+        client = RecceCloudClient(token)
+
+        # Get org and project IDs
+        org_info = client.get_organization(org_slug)
+        if not org_info:
+            console.print(f"[red]Error:[/red] Organization '{org_slug}' not found")
+            return None
+        org_id = org_info.get("id")
+        if not org_id:
+            console.print(f"[red]Error:[/red] Organization '{org_slug}' response missing ID")
+            return None
+
+        project_info = client.get_project(org_id, project_slug)
+        if not project_info:
+            console.print(f"[red]Error:[/red] Project '{project_slug}' not found")
+            return None
+        project_id = project_info.get("id")
+        if not project_id:
+            console.print(f"[red]Error:[/red] Project '{project_slug}' response missing ID")
+            return None
+
+        # List sessions and find production session
+        sessions = client.list_sessions(org_id, project_id)
+        for session in sessions:
+            if session.get("is_base"):
+                session_id = session.get("id")
+                if not session_id:
+                    console.print("[red]Error:[/red] Production session found but has no ID")
+                    return None
+                session_name = session.get("name") or "(unnamed)"
+                session_id_display = session_id[:8] if len(session_id) >= 8 else session_id
+                console.print(
+                    f"[cyan]Info:[/cyan] Found production session '{session_name}' (ID: {session_id_display}...)"
+                )
+                return session_id
+
+        console.print("[red]Error:[/red] No production session found")
+        console.print("Create a production session first using 'recce-cloud upload --type prod' or via CI pipeline")
+        return None
+
+    except RecceCloudException as e:
+        console.print(f"[red]Error:[/red] Failed to fetch sessions: {e}")
+        return None
+    except Exception as e:
+        logger.debug("Unexpected error in _get_production_session_id: %s", e, exc_info=True)
+        console.print(f"[red]Error:[/red] Unexpected error: {e}")
+        console.print("  Check your network connection and try again.")
+        return None
+
+
 @cloud_cli.command()
 @click.option(
     "--target-path",
@@ -593,22 +678,41 @@ def upload(target_path, session_id, session_name, skip_confirmation, cr, session
             skip_confirmation=skip_confirmation,
         )
     else:
-        # Platform-specific workflow: Use platform APIs to create session and upload
+        # GitHub Action or GitLab CI/CD workflow: Use platform APIs to create session and upload
         # This workflow MUST use CI job tokens (CI_JOB_TOKEN or GITHUB_TOKEN)
         if not ci_info or not ci_info.access_token:
-            console.print("[red]Error:[/red] Platform-specific upload requires CI environment")
-            console.print(
-                "Either run in GitHub Actions/GitLab CI or provide --session-id/--session-name for generic upload"
-            )
-            sys.exit(2)
-
-        token = ci_info.access_token
-        if ci_info.platform == "github-actions":
-            console.print("[cyan]Info:[/cyan] Using GITHUB_TOKEN for platform-specific authentication")
-        elif ci_info.platform == "gitlab-ci":
-            console.print("[cyan]Info:[/cyan] Using CI_JOB_TOKEN for platform-specific authentication")
+            # If --type prod is specified outside CI, fetch the production session and upload to it
+            if session_type == "prod":
+                from recce_cloud.auth.profile import get_api_token
+
+                token = os.getenv("RECCE_API_TOKEN") or get_api_token()
+                if not token:
+                    console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+                    console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
+                    sys.exit(2)
+
+                # Fetch the production session ID
+                prod_session_id = _get_production_session_id(console, token)
+                if not prod_session_id:
+                    sys.exit(2)
+
+                upload_to_existing_session(
+                    console, token, prod_session_id, manifest_path, catalog_path, adapter_type, target_path
+                )
+            else:
+                console.print("[red]Error:[/red] Platform-specific upload requires CI environment")
+                console.print(
+                    "Either run in GitHub Actions/GitLab CI or provide --session-id/--session-name for generic upload"
+                )
+                sys.exit(2)
+        else:
+            token = ci_info.access_token
+            if ci_info.platform == "github-actions":
+                console.print("[cyan]Info:[/cyan] Using GITHUB_TOKEN for platform-specific authentication")
+            elif ci_info.platform == "gitlab-ci":
+                console.print("[cyan]Info:[/cyan] Using CI_JOB_TOKEN for platform-specific authentication")
 
-        upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
+            upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
 
 
 @cloud_cli.command(name="list")
@@ -682,16 +786,24 @@ def list_sessions_cmd(session_type, output_json):
         if not org_info:
             console.print(f"[red]Error:[/red] Organization '{org}' not found or you don't have access")
             sys.exit(2)
-        org_id = org_info["id"]
+        org_id = org_info.get("id")
+        if not org_id:
+            console.print(f"[red]Error:[/red] Organization '{org}' response missing ID")
+            sys.exit(2)
 
         project_info = client.get_project(org_id, project)
         if not project_info:
             console.print(f"[red]Error:[/red] Project '{project}' not found in organization '{org}'")
             sys.exit(2)
-        project_id = project_info["id"]
+        project_id = project_info.get("id")
+        if not project_id:
+            console.print(f"[red]Error:[/red] Project '{project}' response missing ID")
+            sys.exit(2)
 
     except Exception as e:
+        logger.debug("Failed to initialize client for list_sessions: %s", e, exc_info=True)
         console.print(f"[red]Error:[/red] Failed to initialize: {e}")
+        console.print("  Check your authentication and network connection.")
         sys.exit(2)
 
     # Helper to derive session type from fields:

recce_cloud/recce_cloud/commands/__init__.py

@@ -0,0 +1 @@
+# CLI commands - presentation layer

recce_cloud/recce_cloud/commands/diagnostics.py

@@ -0,0 +1,174 @@
+"""
+Diagnostics CLI commands.
+
+This module contains CLI presentation logic for diagnostic commands,
+delegating business logic to the diagnostic service.
+"""
+
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from recce_cloud.services.diagnostic_service import (
+    CheckStatus,
+    DiagnosticResults,
+    DiagnosticService,
+)
+
+
+class DiagnosticRenderer:
+    """Renders diagnostic results to the console."""
+
+    def __init__(self, console: Console):
+        self.console = console
+
+    def render_header(self) -> None:
+        """Render the diagnostic header."""
+        header = Panel(
+            "[bold]🩺 Recce Doctor[/bold]\n[dim]Checking your Recce Cloud setup...[/dim]",
+            expand=False,
+            padding=(0, 3),
+        )
+        self.console.print()
+        self.console.print(header)
+        self.console.print()
+        self.console.print("━" * 65)
+        self.console.print()
+
+    def render_login_check(self, results: DiagnosticResults) -> None:
+        """Render the login status check."""
+        self.console.print("[bold]1. Login Status[/bold] ($ recce-cloud login)")
+        check = results.login
+
+        if check.passed:
+            email = check.details.get("email", "Unknown")
+            self.console.print(f"[green]✓[/green] Logged in as [cyan]{email}[/cyan]")
+        else:
+            self._render_failure(check)
+
+        self.console.print()
+
+    def render_project_binding_check(self, results: DiagnosticResults) -> None:
+        """Render the project binding check."""
+        self.console.print("[bold]2. Project Binding[/bold] ($ recce-cloud init)")
+        check = results.project_binding
+
+        if check.passed:
+            org = check.details.get("org")
+            project = check.details.get("project")
+            source = check.details.get("source")
+            source_label = " (via env vars)" if source == "env_vars" else ""
+            self.console.print(f"[green]✓[/green] Bound to [cyan]{org}/{project}[/cyan]{source_label}")
+        else:
+            self._render_failure(check)
+
+        self.console.print()
+
+    def render_production_check(self, results: DiagnosticResults) -> None:
+        """Render the production metadata check."""
+        self.console.print("[bold]3. Production Metadata[/bold]")
+        check = results.production_metadata
+
+        if check.status == CheckStatus.SKIP:
+            self.console.print(f"[yellow]⚠[/yellow] {check.message}")
+        elif check.passed:
+            session_name = check.details.get("session_name", "(unnamed)")
+            relative_time = check.details.get("relative_time")
+            time_str = f" (uploaded {relative_time})" if relative_time else ""
+            self.console.print(f'[green]✓[/green] Found production session "[cyan]{session_name}[/cyan]"{time_str}')
+        else:
+            self._render_failure(check)
+
+        self.console.print()
+
+    def render_dev_session_check(self, results: DiagnosticResults) -> None:
+        """Render the dev session check."""
+        self.console.print("[bold]4. Dev Session[/bold]")
+        check = results.dev_session
+
+        if check.status == CheckStatus.SKIP:
+            self.console.print(f"[yellow]⚠[/yellow] {check.message}")
+        elif check.passed:
+            session_name = check.details.get("session_name", "(unnamed)")
+            relative_time = check.details.get("relative_time")
+            time_str = f" (uploaded {relative_time})" if relative_time else ""
+            self.console.print(f'[green]✓[/green] Found dev session "[cyan]{session_name}[/cyan]"{time_str}')
+        else:
+            self._render_failure(check)
+
+    def render_summary(self, results: DiagnosticResults) -> None:
+        """Render the summary section."""
+        self.console.print()
+        self.console.print("━" * 65)
+        self.console.print()
+
+        if results.all_passed:
+            self.console.print("[green]✓ All checks passed![/green] Your Recce setup is ready.")
+            self.console.print()
+            self.console.print("Next step:")
+            self.console.print("  $ recce-cloud review --session-name <session_name>")
+        else:
+            self.console.print(
+                f"[yellow]⚠ {results.passed_count}/{results.total_count} checks passed.[/yellow] "
+                "See above for remediation steps."
+            )
+
+    def render_all(self, results: DiagnosticResults) -> None:
+        """Render all diagnostic results."""
+        self.render_header()
+        self.render_login_check(results)
+        self.render_project_binding_check(results)
+        self.render_production_check(results)
+        self.render_dev_session_check(results)
+        self.render_summary(results)
+
+    def _render_failure(self, check) -> None:
+        """Render a failed check with its suggestion."""
+        self.console.print(f"[red]✗[/red] {check.message}")
+        if check.suggestion:
+            self.console.print()
+            self.console.print("[dim]→ To fix:[/dim]")
+            for line in check.suggestion.split("\n"):
+                self.console.print(f"  {line}")
+
+
+@click.command()
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output in JSON format for scripting",
+)
+def doctor(output_json: bool) -> None:
+    """
+    Check Recce Cloud setup and configuration.
+
+    Validates login status, project binding, and session availability.
+    Provides actionable suggestions when issues are found.
+
+    \b
+    Examples:
+      # Check setup status
+      recce-cloud doctor
+
+      # Machine-readable output
+      recce-cloud doctor --json
+    """
+    console = Console()
+
+    # Run diagnostic checks
+    service = DiagnosticService()
+    results = service.run_all_checks()
+
+    # Output results
+    if output_json:
+        console.print(json.dumps(results.to_dict(), indent=2, default=str))
+    else:
+        renderer = DiagnosticRenderer(console)
+        renderer.render_all(results)
+
+    # Exit with appropriate code
+    sys.exit(0 if results.all_passed else 1)

recce_cloud/recce_cloud/services/__init__.py

@@ -0,0 +1 @@
+# Services layer for business logic