recce-cloud-nightly 1.27.0.20251130__py3-none-any.whl → 1.31.0.20260101__py3-none-any.whl

recce_cloud/VERSION

@@ -1 +1 @@
-1.27.0.20251130
+1.31.0.20260101

recce_cloud/api/base.py

@@ -109,3 +109,24 @@ class BaseRecceCloudClient(ABC):
             Empty dictionary or acknowledgement
         """
         pass
+
+    @abstractmethod
+    def get_session_download_urls(
+        self,
+        cr_number: Optional[int] = None,
+        session_type: Optional[str] = None,
+    ) -> Dict:
+        """
+        Get download URLs for artifacts from a session.
+
+        Args:
+            cr_number: Change request number (PR/MR number) for CR sessions
+            session_type: Session type ("cr", "prod", "dev")
+
+        Returns:
+            Dictionary containing:
+                - session_id: Session ID
+                - manifest_url: Presigned URL for manifest.json download
+                - catalog_url: Presigned URL for catalog.json download
+        """
+        pass

recce_cloud/api/client.py

@@ -121,6 +121,42 @@ class RecceCloudClient:
             presigned_urls[key] = self._replace_localhost_with_docker_internal(url)
         return presigned_urls
 
+    def get_download_urls_by_session_id(self, org_id: str, project_id: str, session_id: str) -> dict:
+        """
+        Get presigned S3 download URLs for a session.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+
+        Returns:
+            dict with keys:
+                - manifest_url: Presigned URL for downloading manifest.json
+                - catalog_url: Presigned URL for downloading catalog.json
+
+        Raises:
+            RecceCloudException: If the request fails
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/download-url"
+        response = self._request("GET", api_url)
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+        data = response.json()
+        if data["presigned_urls"] is None:
+            raise RecceCloudException(
+                reason="No presigned URLs returned from the server.",
+                status_code=404,
+            )
+
+        presigned_urls = data["presigned_urls"]
+        for key, url in presigned_urls.items():
+            presigned_urls[key] = self._replace_localhost_with_docker_internal(url)
+        return presigned_urls
+
     def update_session(self, org_id: str, project_id: str, session_id: str, adapter_type: str) -> dict:
         """
         Update session metadata with adapter type.

recce_cloud/api/github.py

@@ -27,6 +27,7 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         branch: str,
         adapter_type: str,
         cr_number: Optional[int] = None,
+        commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
@@ -74,3 +75,32 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         }
 
         return self._make_request("POST", url, json=payload)
+
+    def get_session_download_urls(
+        self,
+        cr_number: Optional[int] = None,
+        session_type: Optional[str] = None,
+    ) -> Dict:
+        """
+        Get download URLs for artifacts from a GitHub session.
+
+        Args:
+            cr_number: PR number for pull request sessions
+            session_type: Session type ("cr", "prod", "dev")
+
+        Returns:
+            Dictionary containing session_id, manifest_url, catalog_url
+        """
+        url = f"{self.api_host}/api/v2/github/{self.repository}/session-download-url"
+
+        # Build query parameters
+        params = {}
+
+        # For prod session, set base=true
+        if session_type == "prod":
+            params["base"] = "true"
+        # For CR session, include pr_number
+        elif session_type == "cr" and cr_number is not None:
+            params["pr_number"] = cr_number
+
+        return self._make_request("GET", url, params=params)

recce_cloud/api/gitlab.py

@@ -80,3 +80,32 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
         }
 
         return self._make_request("POST", url, json=payload)
+
+    def get_session_download_urls(
+        self,
+        cr_number: Optional[int] = None,
+        session_type: Optional[str] = None,
+    ) -> Dict:
+        """
+        Get download URLs for artifacts from a GitLab session.
+
+        Args:
+            cr_number: MR IID for merge request sessions
+            session_type: Session type ("cr", "prod", "dev")
+
+        Returns:
+            Dictionary containing session_id, manifest_url, catalog_url
+        """
+        url = f"{self.api_host}/api/v2/gitlab/{self.project_path}/session-download-url"
+
+        # Build query parameters
+        params = {}
+
+        # For prod session, set base=true
+        if session_type == "prod":
+            params["base"] = "true"
+        # For CR session, include mr_iid
+        elif session_type == "cr" and cr_number is not None:
+            params["mr_iid"] = cr_number
+
+        return self._make_request("GET", url, params=params)

recce_cloud/cli.py

@@ -14,6 +14,10 @@ from rich.logging import RichHandler
 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.download import (
+    download_from_existing_session,
+    download_with_platform_apis,
+)
 from recce_cloud.upload import upload_to_existing_session, upload_with_platform_apis
 
 # Configure logging
@@ -241,5 +245,190 @@ def upload(target_path, session_id, cr, session_type, dry_run):
         upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
 
 
+@cloud_cli.command()
+@click.option(
+    "--target-path",
+    type=click.Path(),
+    default="target",
+    help="Path to directory where artifacts will be downloaded (default: 'target')",
+)
+@click.option(
+    "--session-id",
+    envvar="RECCE_SESSION_ID",
+    help="Recce Cloud session ID to download artifacts from (or use RECCE_SESSION_ID env var). "
+    "If not provided, session will be found automatically using platform-specific APIs (GitHub/GitLab).",
+)
+@click.option(
+    "--prod",
+    is_flag=True,
+    help="Download production/base session instead of PR/MR session",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be downloaded without actually downloading",
+)
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Overwrite existing files without prompting",
+)
+def download(target_path, session_id, prod, dry_run, force):
+    """
+    Download dbt artifacts (manifest.json, catalog.json) from Recce Cloud.
+
+    \b
+    Authentication (auto-detected):
+    - RECCE_API_TOKEN (for --session-id workflow)
+    - GITHUB_TOKEN (GitHub Actions)
+    - CI_JOB_TOKEN (GitLab CI)
+
+    \b
+    Common Examples:
+      # Auto-find and download current PR/MR session
+      recce-cloud download
+
+      # Download project's production/base session
+      recce-cloud download --prod
+
+      # Download from specific session ID
+      recce-cloud download --session-id abc123
+
+      # Download prod session to target-base
+      recce-cloud download --prod --target-path target-base
+
+      # Force overwrite existing files
+      recce-cloud download --force
+    """
+    console = Console()
+
+    # Validate flag combinations
+    if session_id and prod:
+        console.print("[yellow]Warning:[/yellow] --prod is ignored when --session-id is provided")
+
+    # Determine session type from --prod flag
+    session_type = "prod" if prod else None
+
+    # 1. Auto-detect CI environment information
+    console.rule("CI Environment Detection", style="blue")
+    try:
+        ci_info = CIDetector.detect()
+        ci_info = CIDetector.apply_overrides(ci_info, session_type=session_type)
+
+        # Display detected CI information immediately
+        if ci_info:
+            info_table = []
+            if ci_info.platform:
+                info_table.append(f"[cyan]Platform:[/cyan] {ci_info.platform}")
+
+            if ci_info.repository:
+                info_table.append(f"[cyan]Repository:[/cyan] {ci_info.repository}")
+
+            if ci_info.session_type:
+                info_table.append(f"[cyan]Session Type:[/cyan] {ci_info.session_type}")
+
+            # Only show CR number and URL for CR sessions (not for prod)
+            if ci_info.session_type == "cr" and ci_info.cr_number is not None:
+                if ci_info.platform == "github-actions":
+                    info_table.append(f"[cyan]PR Number:[/cyan] {ci_info.cr_number}")
+                elif ci_info.platform == "gitlab-ci":
+                    info_table.append(f"[cyan]MR Number:[/cyan] {ci_info.cr_number}")
+                else:
+                    info_table.append(f"[cyan]CR Number:[/cyan] {ci_info.cr_number}")
+
+            # Only show CR URL for CR sessions
+            if ci_info.session_type == "cr" and ci_info.cr_url:
+                if ci_info.platform == "github-actions":
+                    info_table.append(f"[cyan]PR URL:[/cyan] {ci_info.cr_url}")
+                elif ci_info.platform == "gitlab-ci":
+                    info_table.append(f"[cyan]MR URL:[/cyan] {ci_info.cr_url}")
+                else:
+                    info_table.append(f"[cyan]CR URL:[/cyan] {ci_info.cr_url}")
+
+            for line in info_table:
+                console.print(line)
+        else:
+            console.print("[yellow]No CI environment detected[/yellow]")
+    except Exception as e:
+        console.print(f"[yellow]Warning:[/yellow] Failed to detect CI environment: {e}")
+        console.print("Continuing without CI metadata...")
+        ci_info = None
+
+    # 2. Handle dry-run mode (before authentication or API calls)
+    if dry_run:
+        console.rule("Dry Run Summary", style="yellow")
+        console.print("[yellow]Dry run mode enabled - no actual download will be performed[/yellow]")
+        console.print()
+
+        # Display platform information if detected
+        if ci_info and ci_info.platform:
+            console.print("[cyan]Platform Information:[/cyan]")
+            console.print(f"  • Platform: {ci_info.platform}")
+            if ci_info.repository:
+                console.print(f"  • Repository: {ci_info.repository}")
+            if ci_info.session_type:
+                console.print(f"  • Session Type: {ci_info.session_type}")
+            if ci_info.session_type == "cr" and ci_info.cr_number is not None:
+                console.print(f"  • CR Number: {ci_info.cr_number}")
+            console.print()
+
+        # Display download summary
+        console.print("[cyan]Download Workflow:[/cyan]")
+        if session_id:
+            console.print("  • Download from specific session ID")
+            console.print(f"  • Session ID: {session_id}")
+        else:
+            if prod:
+                console.print("  • Download project's production/base session")
+            else:
+                console.print("  • Auto-detect and download PR/MR session")
+
+            if ci_info and ci_info.platform in ["github-actions", "gitlab-ci"]:
+                console.print("  • Platform-specific APIs will be used")
+            else:
+                console.print("  • [yellow]Warning: Platform not supported for auto-session discovery[/yellow]")
+
+        console.print()
+        console.print("[cyan]Download destination:[/cyan]")
+        console.print(f"  • Target path: {os.path.abspath(target_path)}")
+        console.print("  • Files: manifest.json, catalog.json")
+        if force:
+            console.print("  • Will overwrite existing files")
+        elif os.path.exists(target_path):
+            console.print("  • [yellow]Warning: Target path exists (use --force to overwrite)[/yellow]")
+
+        console.print()
+        console.print("[green]✓[/green] Dry run completed successfully")
+        sys.exit(0)
+
+    # 3. Choose download workflow based on whether session_id is provided
+    if session_id:
+        # Generic workflow: Download from existing session using session ID
+        # This workflow requires RECCE_API_TOKEN
+        token = os.getenv("RECCE_API_TOKEN")
+        if not token:
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided")
+            console.print("Set RECCE_API_TOKEN environment variable for session-based download")
+            sys.exit(2)
+
+        download_from_existing_session(console, token, session_id, target_path, force)
+    else:
+        # Platform-specific workflow: Use platform APIs to find session and download
+        # 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 download requires CI environment")
+            console.print("Either run in GitHub Actions/GitLab CI or provide --session-id for generic download")
+            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")
+
+        download_with_platform_apis(console, token, ci_info, target_path, force)
+
+
 if __name__ == "__main__":
     cloud_cli()

recce_cloud/download.py

@@ -0,0 +1,230 @@
+"""
+Download helper functions for recce-cloud CLI.
+"""
+
+import os
+import sys
+
+import requests
+
+from recce_cloud.api.client import RecceCloudClient
+from recce_cloud.api.exceptions import RecceCloudException
+from recce_cloud.api.factory import create_platform_client
+
+
+def _ensure_target_directory(console, target_path: str, force: bool = False):
+    """
+    Ensure target directory exists or can be created.
+
+    Args:
+        console: Rich console for output
+        target_path: Path to target directory
+        force: Whether to overwrite existing directory
+
+    Raises:
+        SystemExit: If directory exists without force flag or cannot be created
+    """
+    if os.path.exists(target_path):
+        if not force:
+            console.print(f"[red]Error:[/red] Target path already exists: {target_path}")
+            console.print("Use --force to overwrite existing directory")
+            sys.exit(3)
+        console.print(f"[yellow]Warning:[/yellow] Overwriting existing path: {target_path}")
+    else:
+        # Create target directory
+        try:
+            os.makedirs(target_path, exist_ok=True)
+        except Exception as e:
+            console.print(f"[red]Error:[/red] Failed to create target path: {target_path}")
+            console.print(f"Reason: {e}")
+            sys.exit(3)
+
+
+def _download_artifact(console, url: str, target_path: str, artifact_name: str):
+    """
+    Download a single artifact file from URL.
+
+    Args:
+        console: Rich console for output
+        url: Download URL
+        target_path: Path where file should be saved
+        artifact_name: Human-readable name for error messages (e.g., "manifest.json")
+
+    Raises:
+        SystemExit: If download fails
+    """
+    console.print(f'Downloading {artifact_name} to "{target_path}"')
+    try:
+        response = requests.get(url)
+        if response.status_code != 200:
+            raise Exception(f"Download failed with status {response.status_code}: {response.text}")
+        with open(target_path, "wb") as f:
+            f.write(response.content)
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Failed to download {artifact_name}")
+        console.print(f"Reason: {e}")
+        sys.exit(4)
+
+
+def _download_artifacts(console, manifest_url: str, catalog_url: str, target_path: str):
+    """
+    Download manifest.json and catalog.json to target directory.
+
+    Args:
+        console: Rich console for output
+        manifest_url: URL for manifest.json
+        catalog_url: URL for catalog.json
+        target_path: Target directory path
+
+    Raises:
+        SystemExit: If any download fails
+    """
+    manifest_path = os.path.join(target_path, "manifest.json")
+    catalog_path = os.path.join(target_path, "catalog.json")
+
+    _download_artifact(console, manifest_url, manifest_path, "manifest.json")
+    _download_artifact(console, catalog_url, catalog_path, "catalog.json")
+
+
+def download_from_existing_session(console, token: str, session_id: str, target_path: str, force: bool = False):
+    """
+    Download artifacts from an existing Recce Cloud session using session ID.
+
+    This is the generic workflow that requires a pre-existing session ID.
+    """
+    try:
+        client = RecceCloudClient(token)
+    except Exception as e:
+        console.print("[red]Error:[/red] Failed to initialize API client")
+        console.print(f"Reason: {e}")
+        sys.exit(2)
+
+    # Get session info (org_id, project_id)
+    console.print(f'Downloading artifacts for session ID "{session_id}"')
+    try:
+        session = client.get_session(session_id)
+        if session.get("status") == "error":
+            console.print(f"[red]Error:[/red] {session.get('message')}")
+            sys.exit(2)
+
+        org_id = session.get("org_id")
+        if org_id is None:
+            console.print(f"[red]Error:[/red] Session ID {session_id} does not belong to any organization.")
+            sys.exit(2)
+
+        project_id = session.get("project_id")
+        if project_id is None:
+            console.print(f"[red]Error:[/red] Session ID {session_id} does not belong to any project.")
+            sys.exit(2)
+
+    except RecceCloudException as e:
+        console.print("[red]Error:[/red] Failed to get session info")
+        console.print(f"Reason: {e.reason}")
+        sys.exit(2)
+    except Exception as e:
+        console.print("[red]Error:[/red] Failed to get session info")
+        console.print(f"Reason: {e}")
+        sys.exit(2)
+
+    # Get presigned URLs
+    try:
+        presigned_urls = client.get_download_urls_by_session_id(org_id, project_id, session_id)
+    except RecceCloudException as e:
+        console.print("[red]Error:[/red] Failed to get download URLs")
+        console.print(f"Reason: {e.reason}")
+        sys.exit(4)
+    except Exception as e:
+        console.print("[red]Error:[/red] Failed to get download URLs")
+        console.print(f"Reason: {e}")
+        sys.exit(4)
+
+    # Ensure target directory exists
+    _ensure_target_directory(console, target_path, force)
+
+    # Download artifacts
+    _download_artifacts(console, presigned_urls["manifest_url"], presigned_urls["catalog_url"], target_path)
+
+    # Success!
+    console.rule("Downloaded Successfully", style="green")
+    console.print(
+        f'Downloaded dbt artifacts from Recce Cloud for session ID "{session_id}" to "{os.path.abspath(target_path)}"'
+    )
+    sys.exit(0)
+
+
+def download_with_platform_apis(console, token: str, ci_info, target_path: str, force: bool = False):
+    """
+    Download artifacts using platform-specific APIs (GitHub Actions or GitLab CI).
+
+    This workflow uses session-download-url to find and download artifacts.
+    """
+    # Validate platform support
+    if ci_info.platform not in ["github-actions", "gitlab-ci"]:
+        console.print("[red]Error:[/red] Platform-specific download requires GitHub Actions or GitLab CI environment")
+        console.print(f"Detected platform: {ci_info.platform or 'unknown'}")
+        console.print(
+            "Either run this command in a supported CI environment or provide --session-id for generic download"
+        )
+        sys.exit(1)
+
+    # Create platform-specific client
+    try:
+        client = create_platform_client(token, ci_info)
+    except ValueError as e:
+        console.print("[red]Error:[/red] Failed to create platform client")
+        console.print(f"Reason: {e}")
+        sys.exit(2)
+
+    # Get session download URLs
+    console.rule("Finding session and getting download URLs", style="blue")
+
+    # Determine what to display based on session type
+    if ci_info.session_type == "prod":
+        console.print("Looking for production/base session...")
+    elif ci_info.session_type == "cr":
+        console.print(f"Looking for PR/MR session (CR #{ci_info.cr_number})...")
+    else:
+        console.print("Looking for session...")
+
+    try:
+        download_response = client.get_session_download_urls(
+            cr_number=ci_info.cr_number,
+            session_type=ci_info.session_type,
+        )
+
+        session_id = download_response.get("session_id")
+        presigned_urls = download_response.get("presigned_urls", {})
+        manifest_download_url = presigned_urls.get("manifest_url")
+        catalog_download_url = presigned_urls.get("catalog_url")
+
+        if not session_id or not manifest_download_url or not catalog_download_url:
+            console.print("[red]Error:[/red] Incomplete response from session-download-url API")
+            console.print(f"Response: {download_response}")
+            sys.exit(4)
+
+        console.print(f"[green]Session ID:[/green] {session_id}")
+
+    except RecceCloudException as e:
+        console.print("[red]Error:[/red] Failed to get session download URLs")
+        console.print(f"Reason: {e.reason}")
+        sys.exit(4)
+    except Exception as e:
+        console.print("[red]Error:[/red] Failed to get session download URLs")
+        console.print(f"Reason: {e}")
+        sys.exit(4)
+
+    # Ensure target directory exists
+    _ensure_target_directory(console, target_path, force)
+
+    # Download artifacts
+    _download_artifacts(console, manifest_download_url, catalog_download_url, target_path)
+
+    # Success!
+    console.rule("Downloaded Successfully", style="green")
+    console.print(f'Downloaded dbt artifacts from Recce Cloud for session ID "{session_id}"')
+    console.print(f'Artifacts saved to: "{os.path.abspath(target_path)}"')
+
+    if ci_info.cr_url:
+        console.print(f"Change request: {ci_info.cr_url}")
+
+    sys.exit(0)

recce_cloud/hatch_build.py

@@ -0,0 +1,20 @@
+"""Custom hatch build hook to read README from package root directory."""
+
+from pathlib import Path
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class CustomMetadataHook(MetadataHookInterface):
+    """Read README from package root directory for recce-cloud package."""
+
+    PLUGIN_NAME = "custom"
+
+    def update(self, metadata: dict) -> None:
+        """Update metadata with README content from parent directory."""
+        readme_path = Path(self.root) / "README.md"
+        if readme_path.exists():
+            metadata["readme"] = {
+                "content-type": "text/markdown",
+                "text": readme_path.read_text(encoding="utf-8"),
+            }

recce_cloud/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "recce-cloud-nightly"
+dynamic = ["version", "readme"]
+description = "Lightweight CLI for Recce Cloud operations"
+authors = [{name = "InfuseAI Dev Team", email = "dev@infuseai.io"}]
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+
+dependencies = [
+    "click>=7.1",
+    "requests>=2.28.1",
+    "rich>=12.0.0",
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+]
+
+[project.scripts]
+recce-cloud = "recce_cloud.cli:cloud_cli"
+
+[project.urls]
+"Bug Tracker" = "https://github.com/InfuseAI/recce/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "VERSION"
+pattern = "(?P<version>.+)"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.metadata.hooks.custom]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.hatch.build.targets.wheel.sources]
+"." = "recce_cloud"