recce-cloud 1.33.1__tar.gz → 1.34.1__tar.gz

{recce_cloud-1.33.1 → recce_cloud-1.34.1}/.gitignore

@@ -17,6 +17,7 @@ build
 .DS_Store
 
 recce.yml
+STATUS.md
 
 # Ignore build artifacts from frontend
 recce/data
@@ -24,6 +25,14 @@ recce/data
 # ignore Claude logs and plans at any nesting
 **/docs/plans/**/*.md
 **/docs/plans/**/*.json
+**/docs/tasks/**/*.md
+**/docs/tasks/**/*.json
+**/docs/summaries/**/*.md
+**/docs/summaries/**/*.json
 
 # Git worktrees for isolated development
 .worktrees/
+
+# Claude output files
+output/*
+!output/.gitkeep

recce_cloud-1.34.1/PKG-INFO

@@ -0,0 +1,370 @@
+Metadata-Version: 2.4
+Name: recce-cloud
+Version: 1.34.1
+Summary: Lightweight CLI for Recce Cloud operations
+Project-URL: Bug Tracker, https://github.com/InfuseAI/recce/issues
+Author-email: InfuseAI Dev Team <dev@infuseai.io>
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: click>=7.1
+Requires-Dist: cryptography>=3.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28.1
+Requires-Dist: rich>=12.0.0
+Provides-Extra: dev
+Requires-Dist: flake8>=7.2.0; extra == 'dev'
+Requires-Dist: pytest>=4.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Recce Cloud CLI
+
+Lightweight command-line tool for managing dbt artifacts with Recce Cloud in
+CI/CD environments.
+
+## Overview
+
+The Recce Cloud CLI (`recce-cloud`) is a standalone tool designed for CI/CD
+pipelines that need to upload and download dbt artifacts (manifest.json and
+catalog.json) to/from Recce Cloud without the full `recce` package dependencies.
+
+**Key Features:**
+
+- Lightweight - minimal dependencies for fast CI/CD execution
+- Auto-detection - automatically detects CI platform, repository, and PR/MR
+  context
+- Upload/Download - push and pull dbt artifacts to/from Recce Cloud sessions
+- Flexible authentication - browser-based login, token-based auth, or CI tokens
+- Platform-specific - optimized for GitHub Actions and GitLab CI
+
+## Installation
+
+```bash
+pip install recce-cloud
+```
+
+## Quick Start
+
+### Local Development
+
+```bash
+# Login to Recce Cloud (opens browser for authentication)
+recce-cloud login
+
+# Initialize project binding (interactive)
+recce-cloud init
+
+# Check current status
+recce-cloud init --status
+
+# Logout
+recce-cloud logout
+```
+
+### GitHub Actions
+
+```yaml
+- name: Upload to Recce Cloud
+  run: recce-cloud upload
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Download from Recce Cloud
+  run: recce-cloud download --prod --target-path target-base
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### GitLab CI
+
+```yaml
+recce-upload:
+  script:
+    - recce-cloud upload
+
+recce-download:
+  script:
+    - recce-cloud download --prod --target-path target-base
+```
+
+## CI/CD Workflows
+
+### Upload Workflow
+
+The `recce-cloud upload` command automatically creates sessions in supported CI
+environments.
+
+```bash
+# Basic upload (auto-detects CI context)
+recce-cloud upload
+
+# Custom target path
+recce-cloud upload --target-path custom-target
+
+# Override PR number or session type
+recce-cloud upload --pr 123 --type pr
+
+# Generic workflow with session name (for other CI platforms)
+recce-cloud upload --session-name "PR-123" --yes
+```
+
+**Options:**
+
+| Option           | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `--target-path`  | Path to dbt target directory (default: `target`) |
+| `--session-id`   | Session ID for generic workflow                  |
+| `--session-name` | Session name for human-readable workflow         |
+| `--pr`           | Override PR/MR number                            |
+| `--type`         | Override session type: `pr`, `prod`, `dev`       |
+| `--yes`          | Auto-confirm session creation                    |
+| `--dry-run`      | Preview without uploading                        |
+
+### Download Workflow
+
+The `recce-cloud download` command retrieves artifacts from Recce Cloud
+sessions.
+
+```bash
+# Download current PR/MR session
+recce-cloud download
+
+# Download production/base session
+recce-cloud download --prod
+
+# Download to custom path
+recce-cloud download --prod --target-path target-base
+
+# Force overwrite existing files
+recce-cloud download --force
+
+# Generic workflow with session ID
+recce-cloud download --session-id abc123
+```
+
+**Options:**
+
+| Option          | Description                              |
+| --------------- | ---------------------------------------- |
+| `--target-path` | Download destination (default: `target`) |
+| `--session-id`  | Session ID for generic workflow          |
+| `--prod`        | Download production/base session         |
+| `--force`, `-f` | Overwrite existing files                 |
+| `--dry-run`     | Preview without downloading              |
+
+## Authentication
+
+The CLI supports multiple authentication methods (in priority order):
+
+1. **RECCE_API_TOKEN** - Environment variable (recommended for CI)
+2. **GITHUB_TOKEN** - GitHub Actions (must be explicitly set)
+3. **CI_JOB_TOKEN** - GitLab CI (auto-detected)
+4. **Stored credentials** - From `recce-cloud login`
+
+### Getting API Tokens
+
+**Recce Cloud API Token:**
+
+1. Log in to [Recce Cloud](https://cloud.datarecce.io)
+2. Go to Settings → API Tokens
+
+## CI/CD Integration Examples
+
+### GitHub Actions - Complete Workflow
+
+```yaml
+name: Recce CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  recce:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install dbt-core dbt-snowflake recce-cloud
+
+      # Download production artifacts for comparison
+      - name: Download base artifacts
+        run: recce-cloud download --prod --target-path target-base
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Build current PR
+      - name: Build dbt project
+        run: |
+          dbt deps
+          dbt build
+          dbt docs generate
+
+      # Upload current PR artifacts
+      - name: Upload to Recce Cloud
+        run: recce-cloud upload
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### GitLab CI - Complete Workflow
+
+```yaml
+stages:
+  - download
+  - build
+  - upload
+
+recce-download-base:
+  stage: download
+  image: python:3.11-slim
+  script:
+    - pip install recce-cloud
+    - recce-cloud download --prod --target-path target-base
+  artifacts:
+    paths:
+      - target-base/
+  only:
+    - merge_requests
+
+dbt-build:
+  stage: build
+  image: python:3.11-slim
+  script:
+    - pip install dbt-core dbt-snowflake
+    - dbt deps
+    - dbt build
+    - dbt docs generate
+  artifacts:
+    paths:
+      - target/
+  only:
+    - merge_requests
+
+recce-upload:
+  stage: upload
+  image: python:3.11-slim
+  script:
+    - pip install recce-cloud
+    - recce-cloud upload
+  dependencies:
+    - dbt-build
+  only:
+    - merge_requests
+```
+
+### Generic CI Platform
+
+For other CI platforms, use session name workflow with your PR/MR number:
+
+```bash
+export RECCE_API_TOKEN=your_token_here
+
+# Upload PR artifacts (creates session if not exists)
+recce-cloud upload --session-name "PR-${PR_NUMBER}" --yes
+
+# Upload production artifacts (in CD pipeline after merge)
+recce-cloud upload --type prod --yes
+```
+
+The `--session-name` option creates a human-readable session that's easy to
+track. Use `--yes` to auto-confirm session creation in CI environments.
+
+## Environment Variables
+
+| Variable           | Description                              |
+| ------------------ | ---------------------------------------- |
+| `RECCE_API_TOKEN`  | Recce Cloud API token                    |
+| `RECCE_SESSION_ID` | Default session ID for generic workflows |
+| `GITHUB_TOKEN`     | GitHub authentication (Actions)          |
+| `CI_JOB_TOKEN`     | GitLab CI job token (auto-detected)      |
+
+## Additional Commands
+
+Beyond upload and download, the CLI provides:
+
+```bash
+# List sessions in your project
+recce-cloud list
+
+# Delete a session
+recce-cloud delete --session-id abc123
+
+# Generate AI review for a session
+recce-cloud review --session-id abc123
+
+# Generate PR metrics report
+recce-cloud report --since 30d
+
+# Diagnose setup issues
+recce-cloud doctor
+
+# Show version
+recce-cloud version
+```
+
+Run `recce-cloud <command> --help` for detailed options.
+
+## Troubleshooting
+
+### Quick Diagnosis
+
+```bash
+recce-cloud doctor
+```
+
+This validates login status, project binding, and session availability.
+
+### Common Issues
+
+**Missing dbt artifacts:**
+
+```bash
+dbt build
+dbt docs generate  # Required before upload
+recce-cloud upload
+```
+
+**Authentication failed:**
+
+- For GitHub Actions: Set `GITHUB_TOKEN` in env
+- For GitLab CI: `CI_JOB_TOKEN` is auto-detected
+- For generic CI: Set `RECCE_API_TOKEN`
+
+**Platform not supported:**
+
+```bash
+# Use session name workflow for unsupported CI platforms
+recce-cloud upload --session-name "PR-${PR_NUMBER}" --yes
+```
+
+### Debug Mode
+
+```bash
+export RECCE_LOG_LEVEL=DEBUG
+recce-cloud upload
+```
+
+## Support
+
+- **Documentation:** [docs.reccehq.com](https://docs.reccehq.com)
+- **Issues:** [GitHub Issues](https://github.com/DataRecce/recce/issues)
+- **Community:** [Recce Slack](https://getdbt.slack.com/archives/C05C28V7CPP)
+- **Email:** <support@reccehq.com>
+
+## License
+
+Apache License 2.0 - See [LICENSE](../LICENSE) file for details.

recce_cloud-1.34.1/recce_cloud/VERSION

@@ -0,0 +1 @@
+1.34.1

{recce_cloud-1.33.1 → recce_cloud-1.34.1}/recce_cloud/api/base.py

@@ -74,7 +74,7 @@ class BaseRecceCloudClient(ABC):
         self,
         branch: str,
         adapter_type: str,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
@@ -84,9 +84,9 @@ class BaseRecceCloudClient(ABC):
         Args:
             branch: Branch name
             adapter_type: DBT adapter type (e.g., 'postgres', 'snowflake', 'bigquery')
-            cr_number: Change request number (PR/MR number) for CR sessions
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
             commit_sha: Commit SHA (GitLab requires this)
-            session_type: Session type ("cr", "prod", "dev") - determines if cr_number is used
+            session_type: Session type ("pr", "prod", "dev") - determines if pr_number is used
 
         Returns:
             Dictionary containing:
@@ -113,15 +113,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def get_session_download_urls(
         self,
-        cr_number: Optional[int] = None,
+        pr_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")
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod", "dev")
 
         Returns:
             Dictionary containing:
@@ -134,15 +134,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def delete_session(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Delete a session.
 
         Args:
-            cr_number: Change request number (PR/MR number) for CR sessions
-            session_type: Session type ("cr", "prod") - "prod" deletes base session
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod") - "prod" deletes base session
 
         Returns:
             Dictionary containing: