superset-showtime 0.1.0__tar.gz → 0.2.2__tar.gz

superset_showtime-0.2.2/.claude/settings.local.json

@@ -0,0 +1,36 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/max/code/superset/.github/workflows/**)",
+      "Bash(showtime stop:*)",
+      "Bash(python:*)",
+      "Bash(uv pip install:*)",
+      "Bash(aws configure:*)",
+      "Bash(env)",
+      "Bash(unset:*)",
+      "Bash(aws sts:*)",
+      "WebSearch",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(ruff check:*)",
+      "Bash(pytest:*)",
+      "Bash(make test:*)",
+      "Bash(uv pip compile:*)",
+      "Bash(chmod:*)",
+      "Read(//Users/max/code/**)",
+      "Bash(aws efs create-file-system:*)",
+      "Bash(export AWS_PROFILE=\"\")",
+      "Bash(AWS_PROFILE=\"\" aws efs create-file-system --tags Key=Name,Value=superset-examples Key=Purpose,Value=shared-examples-duckdb --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs create-file-system --tags Key=Name,Value=superset-examples Key=Purpose,Value=shared-examples-duckdb --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs create-file-system --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs describe-file-systems --query 'FileSystems[?Tags[?Key==`Name` && Value==`superset-examples`]]')",
+      "Bash(env -u AWS_PROFILE aws efs describe-file-systems)",
+      "Bash(env:*)",
+      "Bash(grep:*)",
+      "Bash(git grep:*)",
+      "Bash(git push:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

{superset_showtime-0.1.0 → superset_showtime-0.2.2}/CLAUDE.md

@@ -166,20 +166,25 @@ showtime stop 34809 --force
 
 ## Current Implementation Status
 
-### ✅ Working (Tested)
-- GitHub API integration with apache/superset
-- Circus tent emoji label parsing and creation
-- CLI commands: `list`, `status`, `start/stop` (with dry-run)
-- Beautiful help system that teaches label workflow
-- Comprehensive dry-run testing framework
-
-### 🚧 Partially Implemented
-- AWS operations (class exists, logic written, needs testing)
-- Per-SHA label parsing (designed, needs full implementation)
-- Trigger processing (framework exists, needs completion)
-
-### 📋 Not Implemented
-- Rolling update logic for zero-downtime
-- Real AWS integration testing
-- Feature flag configuration via labels
-- GitHub Actions workflow deployment
+### ✅ Fully Implemented (Production Ready)
+- **Blue-green deployment**: Zero-downtime updates with health checks
+- **AWS integration**: Complete ECS/ECR operations with DockerHub pulling
+- **Smart sync system**: Intelligent PR state detection and auto-sync
+- **GitHub Actions workflows**: Drop-in replacement for ephemeral-env.yml
+- **TTL-based cleanup**: Respects individual environment preferences
+- **SHA override support**: Deploy any specific commit for testing
+- **Freeze functionality**: Pin environments during testing
+- **Enhanced CLI**: Clickable links, full-width tables, real-time progress
+- **Unified label system**: Searchable namespaced labels with color themes
+
+### 🎯 Label System (Streamlined)
+- **Trigger labels**: `🎪 ⚡ showtime-trigger-start` (namespaced, searchable)
+- **State labels**: `🎪 abc123f 🚦 running` (color-coded status)
+- **Freeze support**: `🎪 🧊 showtime-freeze` (prevents auto-sync)
+- **Automatic creation**: Labels get proper colors/descriptions automatically
+
+### 📦 Ready for Deployment
+- **GitHub Actions**: `workflows-reference/showtime-trigger.yml` + `showtime-cleanup.yml`
+- **PyPI package**: Built with dependencies, ready for `pip install superset-showtime`
+- **Testing infrastructure**: Comprehensive dry-run and manual testing support
+- **Documentation**: Complete README with workflows and examples

{superset_showtime-0.1.0 → superset_showtime-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superset-showtime
-Version: 0.1.0
+Version: 0.2.2
 Summary: 🎪 Apache Superset ephemeral environment management with circus tent emoji state tracking
 Project-URL: Homepage, https://github.com/apache/superset-showtime
 Project-URL: Documentation, https://superset-showtime.readthedocs.io/
@@ -72,22 +72,34 @@ Description-Content-Type: text/markdown
 
 ## 🎯 What is Showtime?
 
-Superset Showtime replaces the complex GitHub Actions scripts for ephemeral environments with a simple, powerful CLI tool that uses **circus tent emoji labels** for state management.
+Superset Showtime is a CLI tool designed primarily for **GitHub Actions** to manage Apache Superset ephemeral environments. It uses **circus tent emoji labels** as a visual state management system and depends on Superset's existing build infrastructure.
 
-### The Problem We Solve
+## 🚀 Quick Start for Superset Contributors
+
+**Create an ephemeral environment:**
+1. Go to your PR in GitHub
+2. Add label: `🎪 ⚡ showtime-trigger-start`
+3. Watch the magic happen - labels will update automatically
+4. When you see `🎪 🚦 {sha} running`, your environment is ready!
+5. Get URL from `🎪 🌐 {sha} {ip}` → `http://{ip}:8080`
+6. **Every new commit automatically deploys a fresh environment** (zero-downtime)
+
+**To test a specific commit without auto-updates:**
+- Add label: `🎪 🧊 showtime-freeze` (prevents auto-sync on new commits)
 
-**Current Superset ephemeral environment issues:**
-- 🚨 **Stale environments** - New commits don't update existing environments
-- 💸 **Resource waste** - Multiple environments per PR, no automatic cleanup
-- 🔧 **Hard to maintain** - Complex GitHub Actions logic scattered across workflows
-- 👀 **Poor visibility** - Hard to see what environments exist and their status
+**Clean up when done:**
+```bash
+# Add this label:
+🎪 🛑 showtime-trigger-stop
+# All circus labels disappear, AWS resources cleaned up
+```
 
-### The Showtime Solution
+## 🎪 How It Works
 
 **🎪 GitHub labels become a visual state machine:**
 ```bash
 # User adds trigger label in GitHub UI:
-🎪 trigger-start
+🎪 ⚡ showtime-trigger-start
 
 # System responds with state labels:
 🎪 abc123f 🚦 building      # Environment abc123f is building
@@ -101,64 +113,40 @@ Superset Showtime replaces the complex GitHub Actions scripts for ephemeral envi
 🎪 abc123f 🌐 52-1-2-3      # Available at http://52.1.2.3:8080
 ```
 
-## 🚀 Quick Start for Superset Contributors
-
-### 1. As a Contributor (Using GitHub Labels)
+## 📊 For Maintainers (CLI Operations)
 
-**Create an ephemeral environment:**
-1. Go to your PR in GitHub
-2. Add label: `🎪 trigger-start`
-3. Watch the magic happen - labels will update automatically
-4. When you see `🎪 🚦 {sha} running`, your environment is ready!
-5. Get URL from `🎪 🌐 {sha} {ip}` → `http://{ip}:8080`
+> **Note**: CLI is mainly for debugging or developing Showtime itself. Primary interface is GitHub labels above.
 
-**Configure your environment:**
-```bash
-# Add these labels to enable Superset feature flags:
-🎪 conf-enable-ALERTS              # Enable alerts feature
-🎪 conf-enable-DASHBOARD_RBAC      # Enable dashboard RBAC
-🎪 conf-disable-SSH_TUNNELING      # Disable SSH tunneling
-```
-
-**Clean up when done:**
-```bash
-# Add this label:
-🎪 trigger-stop
-# All circus labels disappear, AWS resources cleaned up
-```
-
-### 2. As a Maintainer (Using CLI)
-
-**Install the CLI:**
+**Install CLI for debugging:**
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_token
 ```
 
-**Monitor all environments:**
+**Monitor and debug:**
 ```bash
 showtime list                    # See all active environments
-showtime status 1234            # Check specific PR environment
-showtime labels                 # Learn the complete label system
+showtime status 1234            # Debug specific environment
+showtime labels                 # Complete label reference
 ```
 
-**Test and debug:**
+**Testing/development:**
 ```bash
-showtime start 1234 --dry-run-aws      # Test environment creation
+showtime start 1234 --dry-run-aws      # Test without AWS costs
 showtime test-lifecycle 1234           # Full workflow simulation
 ```
 
+> **Dependency**: This CLI coordinates with Superset's existing GitHub Actions build infrastructure. It orchestrates environments but relies on Superset's build workflows for container creation.
+
 ## 🎪 Complete Label Reference
 
 ### 🎯 Trigger Labels (Add These to Your PR)
 
 | Label | Action | Result |
 |-------|---------|---------|
-| `🎪 trigger-start` | Create environment | Builds and deploys ephemeral environment |
-| `🎪 trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |
-| `🎪 trigger-sync` | Update to latest commit | Zero-downtime rolling update |
-| `🎪 conf-enable-ALERTS` | Enable feature flag | Sets `SUPERSET_FEATURE_ALERTS=True` |
-| `🎪 conf-disable-DASHBOARD_RBAC` | Disable feature flag | Sets `SUPERSET_FEATURE_DASHBOARD_RBAC=False` |
+| `🎪 ⚡ showtime-trigger-start` | Create environment | Builds and deploys ephemeral environment with blue-green deployment |
+| `🎪 🛑 showtime-trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |
+| `🎪 🧊 showtime-freeze` | Freeze environment | Prevents auto-sync on new commits (for testing specific SHAs) |
 
 ### 📊 State Labels (Automatically Managed)
 
@@ -168,16 +156,27 @@ showtime test-lifecycle 1234           # Full workflow simulation
 | `🎪 🎯 {sha}` | Active environment pointer | `🎪 🎯 abc123f` |
 | `🎪 🏗️ {sha}` | Building environment pointer | `🎪 🏗️ def456a` |
 | `🎪 {sha} 📅 {timestamp}` | Creation time | `🎪 abc123f 📅 2024-01-15T14-30` |
-| `🎪 {sha} 🌐 {ip-with-dashes}` | Environment IP | `🎪 abc123f 🌐 52-1-2-3` |
+| `🎪 {sha} 🌐 {ip:port}` | Environment URL | `🎪 abc123f 🌐 52.1.2.3:8080` |
 | `🎪 {sha} ⌛ {ttl}` | Time-to-live policy | `🎪 abc123f ⌛ 24h` |
 | `🎪 {sha} 🤡 {username}` | Who requested | `🎪 abc123f 🤡 maxime` |
-| `🎪 {sha} ⚙️ {config}` | Feature flags enabled | `🎪 abc123f ⚙️ alerts,debug` |
+
+## 🔧 Testing Configuration Changes
+
+**Approach**: Modify configuration directly in your PR code, then trigger environment.
+
+**Workflow**:
+1. Modify `superset_config.py` with your changes
+2. Push commit → Creates new SHA (e.g., `def456a`)
+3. Add `🎪 ⚡ showtime-trigger-start` → Deploys with your config
+4. Test environment reflects your exact code changes
+
+This approach creates traceable, reviewable changes that are part of your git history.
 
 ## 🔄 Complete Workflows
 
 ### Creating Your First Environment
 
-1. **Add trigger label** in GitHub UI: `🎪 trigger-start`
+1. **Add trigger label** in GitHub UI: `🎪 ⚡ showtime-trigger-start`
 2. **Watch state labels appear:**
    ```
    🎪 abc123f 🚦 building      ← Environment is building
@@ -187,17 +186,15 @@ showtime test-lifecycle 1234           # Full workflow simulation
 3. **Wait for completion:**
    ```
    🎪 abc123f 🚦 running       ← Now ready!
-   🎪 abc123f 🌐 52-1-2-3      ← Visit http://52.1.2.3:8080
+   🎪 abc123f 🌐 52.1.2.3:8080  ← Visit http://52.1.2.3:8080
    ```
 
-### Enabling Feature Flags
+### Testing Specific Commits
 
-1. **Add config label:** `🎪 conf-enable-ALERTS`
-2. **Watch config update:**
-   ```
-   🎪 abc123f ⚙️ standard     ← Before
-   🎪 abc123f ⚙️ alerts       ← After (feature enabled!)
-   ```
+1. **Add freeze label:** `🎪 🧊 showtime-freeze`
+2. **Result:** Environment won't auto-update on new commits
+3. **Use case:** Test specific SHA while continuing development
+4. **Override:** Add `🎪 ⚡ showtime-trigger-start` to force update despite freeze
 
 ### Rolling Updates (Automatic!)
 
@@ -230,18 +227,18 @@ You'll see:
 - **❌ External contributors** cannot trigger environments (no write access to add labels)
 - **🔒 Secure by design** - only trusted users can create expensive AWS resources
 
-### How GitHub Actions Work
+### GitHub Actions Integration
 
-The new system replaces complex GHA scripts with simple ones:
+Showtime is designed to be called by Superset's GitHub Actions workflows:
 
 ```yaml
-# .github/workflows/circus.yml (replaces current ephemeral-env.yml)
+# .github/workflows/showtime.yml - Integrates with Superset's existing build workflows
 on:
   pull_request_target:
     types: [labeled, unlabeled, synchronize]
 
 jobs:
-  circus-handler:
+  showtime-handler:
     if: contains(github.event.label.name, '🎪')
     steps:
       - name: Install Showtime from PyPI
@@ -251,66 +248,70 @@ jobs:
         run: python -m showtime handle-trigger ${{ github.event.pull_request.number }}
 ```
 
-**Security benefits:**
-- **Always runs trusted code** (from PyPI, not PR code)
-- **Simple workflow logic** (just install CLI and run)
-- **Same permission model** as current system
+**Integration approach:**
+- **Coordinates with Superset builds** - Uses existing container build workflows
+- **Runs trusted code** (from PyPI, not PR code)
+- **Simple orchestration logic** (install CLI and run commands)
+- **Leverages existing infrastructure** - Same AWS resources and permissions
 
 ## 🛠️ Installation & Setup
 
 ### For Contributors (GitHub Labels Only)
-No installation needed! Just use the GitHub label system.
+No installation needed! Just use GitHub labels to trigger environments.
 
-### For Maintainers (CLI Access)
+### For Maintainers (Manual CLI Operations)
 
-**Install CLI:**
+**Install CLI for debugging/testing:**
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_personal_access_token
 ```
 
-**Test CLI:**
+**Manual operations:**
 ```bash
-showtime list                    # See all active environments
-showtime status 1234            # Check specific environment
-showtime labels                 # Learn complete label system
+showtime list                    # Monitor all active environments
+showtime status 1234            # Debug specific environment
+showtime labels                 # Reference complete label system
 ```
 
-### For Repository Setup (One-Time)
+### For Repository Integration (GitHub Actions)
 
 **1. Install GitHub workflows:**
-Copy `.github/workflows/circus.yml` and `.github/workflows/circus-cleanup.yml` to your Superset repo.
+Copy `workflows-reference/showtime-trigger.yml` and `workflows-reference/showtime-cleanup.yml` to Superset's `.github/workflows/`.
+
+**2. Configure secrets (already exist in Superset):**
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `GITHUB_TOKEN`
 
-**2. Add repository secrets:**
-- `AWS_ACCESS_KEY_ID` (already exists)
-- `AWS_SECRET_ACCESS_KEY` (already exists)
-- `GITHUB_TOKEN` (already exists)
+**3. Dependencies:**
+Showtime coordinates with Superset's existing build infrastructure - no additional setup needed.
 
-**3. Replace old workflows:**
-Remove or disable the current `ephemeral-env.yml` and `ephemeral-env-pr-close.yml`.
+## 📊 CLI Reference (For Development/Debugging)
 
-## 📊 CLI Commands Reference
+> **Primary Interface**: Use GitHub labels in PR interface. CLI is mainly for maintainers debugging or developing Showtime itself.
 
-### Core Commands
+### Debugging Commands
 ```bash
-showtime start 1234             # Create environment (with dry-run options)
-showtime stop 1234              # Delete environment
-showtime status 1234            # Show environment status
-showtime list                   # List all environments across org
-showtime labels                 # Complete label reference guide
+showtime list                         # Monitor all environments
+showtime status 1234                  # Debug specific environment
+showtime labels                       # Complete label reference
+showtime test-lifecycle 1234          # Full workflow simulation
 ```
 
-### Testing & Development
+### Manual Operations (Advanced)
 ```bash
-showtime start 1234 --dry-run-aws          # Mock AWS, real GitHub labels
-showtime test-lifecycle 1234 --real-github # Full workflow simulation
-showtime handle-trigger 1234 --dry-run-aws # Simulate GitHub Actions
+showtime start 1234                    # Manually create environment
+showtime start 1234 --sha abc123f     # Create environment (specific SHA)
+showtime stop 1234                    # Manually delete environment
+showtime sync 1234                    # Force sync to desired state
+showtime cleanup --respect-ttl        # Manual cleanup
 ```
 
-### Advanced Operations
+### GitHub Actions Commands
 ```bash
-showtime cleanup --older-than 48h          # Clean up old environments
-showtime list --status running --user maxime  # Filter environments
+showtime handle-trigger 1234          # Process trigger labels (called by GHA)
+showtime cleanup --older-than 48h     # Scheduled cleanup (called by GHA)
 ```
 
 ## 🎪 Benefits for Superset
@@ -319,7 +320,7 @@ showtime list --status running --user maxime  # Filter environments
 - **🎯 Simple workflow** - Just add/remove GitHub labels
 - **👀 Visual feedback** - See environment status in PR labels
 - **⚡ Automatic updates** - New commits update environments automatically
-- **🔧 Live configuration** - Enable/disable feature flags without rebuilding
+- **🔧 Configuration testing** - Test config changes through code commits
 
 ### For Maintainers
 - **📊 Complete visibility** - `showtime list` shows all environments