superset-showtime 0.2.8__tar.gz → 0.2.9__tar.gz

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/.claude/settings.local.json

@@ -30,7 +30,11 @@
       "Bash(git grep:*)",
       "Bash(git push:*)",
       "Bash(make lint:*)",
-      "Bash(mypy:*)"
+      "Bash(mypy:*)",
+      "Bash(sed:*)",
+      "Bash(git pull:*)",
+      "Bash(git rebase:*)",
+      "Bash(git fetch:*)"
     ],
     "deny": [],
     "ask": []

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Superset Showtime is a Python CLI tool for managing Apache Superset ephemeral environments using **circus tent emoji labels** as a state management system on GitHub PRs. The system replaces complex GitHub Actions scripts with a simple CLI that uses GitHub labels for ACID-like state transactions.
+Superset Showtime is a Python CLI tool for managing Apache Superset ephemeral environments using **circus tent emoji labels** as a state management system on GitHub PRs. The system implements **ACID-style atomic transactions** using GitHub labels as a distributed coordination mechanism, with **compare-and-swap** patterns to prevent race conditions.
 
 ## Development Commands
 
@@ -22,11 +22,11 @@ python -m showtime labels               # Complete label reference
 python -m showtime list                 # List all environments (requires GITHUB_TOKEN)
 python -m showtime test-lifecycle 1234  # Full workflow simulation
 
-# Test with real GitHub PRs safely
+# Test new unified sync command
 export GITHUB_TOKEN=xxx
-showtime start 34809 --dry-run-aws --aws-sleep 5    # Mock AWS, real GitHub labels
-showtime status 34809                                # Check environment status
-showtime stop 34809 --force                         # Clean up test labels
+showtime sync 34809 --check-only                    # Analyze what's needed
+showtime sync 34809 --dry-run-aws --dry-run-docker # Test full flow safely
+showtime set-state building 34809                   # Manual state transitions
 ```
 
 ### Testing Single Components
@@ -39,10 +39,19 @@ python -c "from showtime.core.circus import Show; show = Show(pr_number=1234, sh
 ## Architecture Overview
 
 ### Core State Management Pattern
-The system uses **GitHub labels as a distributed state machine**:
-- **Trigger labels** (`🎪 trigger-start`) - Commands added by users, processed and removed by CLI
-- **State labels** (`🎪 🚦 abc123f running`) - Per-SHA status managed by CLI
+The system uses **GitHub labels as a distributed ACID-style database**:
+- **Trigger labels** (`🎪 ⚡ showtime-trigger-start`) - Commands added by users, atomically processed and removed
+- **State labels** (`🎪 abc123f 🚦 building`) - Per-SHA status managed with atomic compare-and-swap operations
 - **No external database** - All state reconstructed from GitHub labels
+- **Race condition prevention** - Atomic claim prevents double-processing of triggers
+
+### Enhanced State Lifecycle
+**Complete state progression**: `building → built → deploying → running/failed`
+- **building**: Docker image construction in progress
+- **built**: Docker build complete, ready for AWS deployment
+- **deploying**: AWS ECS deployment in progress
+- **running**: Environment live and accessible
+- **failed**: Build or deployment failed
 
 ### Key Classes and Responsibilities
 
@@ -96,8 +105,9 @@ Replicates current GitHub Actions AWS logic:
 - **Security model**: `pull_request_target` + PyPI install (no PR code execution)
 
 #### CLI Commands Called by GHA
-- `showtime handle-trigger {pr-number}` - Process trigger labels
-- `showtime handle-sync {pr-number}` - Handle new commits
+- `showtime sync {pr-number} --check-only` - Analyze state and determine build_needed
+- `showtime sync {pr-number} --sha {sha}` - Execute atomic claim + build + deploy
+- `showtime set-state {state} {pr-number}` - Manual state transitions
 - `showtime cleanup --older-than 48h` - Scheduled cleanup
 
 ## Important Implementation Details
@@ -114,15 +124,23 @@ The CLI has comprehensive dry-run support for safe testing:
 ```bash
 --dry-run-aws        # Skip AWS operations, use mock data
 --dry-run-github     # Skip GitHub operations, show what would happen
+--dry-run-docker     # Skip Docker build, use mock success
 --aws-sleep N        # Sleep N seconds to simulate AWS timing
 ```
 
-### AWS Resource Naming
-Must maintain compatibility with existing Superset infrastructure:
+### AWS Resource Naming & Docker Integration
+**Direct Docker build** (no supersetbot dependency):
+- **Docker Image**: `apache/superset:pr-{pr_number}-{sha}-ci` (single tag, built directly)
 - **ECS Service**: `pr-{pr_number}-{sha}` (e.g., `pr-1234-abc123f`)
-- **ECR Image**: `pr-{pr_number}-{sha}-ci`
 - **Network**: Same subnets/security groups as current production setup
 
+**Docker Build Command**:
+```bash
+docker buildx build --push --load --platform linux/amd64 --target ci \
+  --build-arg INCLUDE_CHROMIUM=false --build-arg LOAD_EXAMPLES_DUCKDB=true \
+  -t apache/superset:pr-{pr}-{sha}-ci .
+```
+
 ### State Recovery Pattern
 Since the CLI is stateless, it always reconstructs state from GitHub labels:
 ```python
@@ -133,15 +151,22 @@ show = pr.current_show                       # Finds active environment
 
 ## Critical Development Notes
 
-### Label Operations Must Be Atomic
-GitHub label operations are the "database transactions" - handle carefully:
+### ACID-Style Atomic Transactions
+GitHub label operations implement compare-and-swap pattern for race condition prevention:
 ```python
-# Remove trigger immediately after processing
-github.remove_label(pr_number, trigger_label)
-# Update state labels atomically
-github.remove_circus_labels(pr_number)
-for label in new_labels:
-    github.add_label(pr_number, label)
+# Atomic claim pattern in _atomic_claim_environment():
+# 1. CHECK: Validate current state allows new work
+# 2. COMPARE: Ensure triggers exist and state is valid
+# 3. SWAP: Remove triggers + Set building state atomically
+# 4. COMMIT: Environment successfully claimed
+
+# Example atomic transaction:
+if not _validate_non_active_state(pr):
+    return False  # Another job already active
+github.remove_label(pr_number, trigger_label)  # Remove trigger
+github.remove_circus_labels(pr_number)         # Clear stale state
+for label in building_show.to_circus_labels():
+    github.add_label(pr_number, label)         # Set building state
 ```
 
 ### Per-SHA Format Required
@@ -166,16 +191,14 @@ showtime stop 34809 --force
 
 ## Current Implementation Status
 
-### ✅ 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
+### ✅ Current Architecture (Production Ready)
+- **ACID-style transactions**: Atomic compare-and-swap prevents race conditions
+- **Direct Docker integration**: No supersetbot dependency, single tag builds
+- **Streamlined GitHub Actions**: 3-step workflow (check → setup → sync)
+- **Enhanced state machine**: building→built→deploying→running/failed lifecycle
+- **Unified sync command**: Handles atomic claim + build + deploy in one command
+- **Smart conditionals**: Skip Docker setup when build_needed=false
+- **Race condition safe**: Multiple jobs can't double-process triggers
 
 ### 🎯 Label System (Streamlined)
 - **Trigger labels**: `🎪 ⚡ showtime-trigger-start` (namespaced, searchable)
@@ -183,8 +206,16 @@ showtime stop 34809 --force
 - **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
+### 📦 Key Commands for Development
+```bash
+# Core sync command (replaces handle-trigger, handle-sync):
+showtime sync PR_NUMBER --check-only        # Returns build_needed + target_sha
+showtime sync PR_NUMBER --sha SHA           # Atomic claim + build + deploy
+
+# Manual state management:
+showtime set-state building PR_NUMBER       # Set specific state
+showtime set-state failed PR_NUMBER --error-msg "Build failed"
+
+# Development testing:
+showtime sync PR_NUMBER --dry-run-aws --dry-run-docker --dry-run-github
+```

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superset-showtime
-Version: 0.2.8
+Version: 0.2.9
 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/
@@ -113,9 +113,34 @@ Superset Showtime is a CLI tool designed primarily for **GitHub Actions** to man
 🎪 abc123f 🌐 52-1-2-3      # Available at http://52.1.2.3:8080
 ```
 
-## 📊 For Maintainers (CLI Operations)
+### 🔄 Showtime Workflow
+
+```mermaid
+flowchart TD
+    A[User adds 🎪 ⚡ trigger-start] --> B[GitHub Actions: sync]
+    B --> C{Current state?}
+
+    C -->|No environment| D[🔒 Claim: Remove trigger + Set building]
+    C -->|Running + new SHA| E[🔒 Claim: Remove trigger + Set building]
+    C -->|Already building| F[❌ Exit: Another job active]
+    C -->|No triggers| G[❌ Exit: Nothing to do]
+
+    D --> H[📋 State: building]
+    E --> H
+    H --> I[🐳 Docker build]
+    I -->|Success| J[📋 State: built]
+    I -->|Fail| K[📋 State: failed]
+
+    J --> L[📋 State: deploying]
+    L --> M[☁️ AWS Deploy]
+    M -->|Success| N[📋 State: running]
+    M -->|Fail| O[📋 State: failed]
+
+    N --> P[🎪 Environment ready!]
+
+    Q[User adds 🎪 🛑 trigger-stop] --> R[🧹 Cleanup AWS + Remove labels]
+```
 
-> **Note**: CLI is mainly for debugging or developing Showtime itself. Primary interface is GitHub labels above.
 
 **Install CLI for debugging:**
 ```bash
@@ -229,129 +254,31 @@ You'll see:
 
 ### GitHub Actions Integration
 
-Showtime is designed to be called by Superset's GitHub Actions workflows:
-
-```yaml
-# .github/workflows/showtime.yml - Integrates with Superset's existing build workflows
-on:
-  pull_request_target:
-    types: [labeled, unlabeled, synchronize]
-
-jobs:
-  showtime-handler:
-    if: contains(github.event.label.name, '🎪')
-    steps:
-      - name: Install Showtime from PyPI
-        run: pip install superset-showtime
-
-      - name: Process circus triggers
-        run: python -m showtime handle-trigger ${{ github.event.pull_request.number }}
-```
-
-**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 GitHub labels to trigger environments.
-
-### For Maintainers (Manual CLI Operations)
+**🎯 Live Workflow**: [showtime-trigger.yml](https://github.com/apache/superset/actions/workflows/showtime-trigger.yml)
 
-**Install CLI for debugging/testing:**
-```bash
-pip install superset-showtime
-export GITHUB_TOKEN=your_personal_access_token
-```
+**How it works:**
+- Triggers on PR label changes, commits, and closures
+- Installs `superset-showtime` from PyPI (trusted code, not PR code)
+- Runs `showtime sync` to handle trigger processing and deployments
+- Supports manual testing via `workflow_dispatch` with specific SHA override
 
-**Manual operations:**
+**Commands used:**
 ```bash
-showtime list                    # Monitor all active environments
-showtime status 1234            # Debug specific environment
-showtime labels                 # Reference complete label system
+showtime sync PR_NUMBER --check-only    # Determine build_needed + target_sha
+showtime sync PR_NUMBER --sha SHA       # Execute atomic claim + build + deploy
 ```
 
-### For Repository Integration (GitHub Actions)
-
-**1. Install GitHub workflows:**
-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`
-
-**3. Dependencies:**
-Showtime coordinates with Superset's existing build infrastructure - no additional setup needed.
-
-## 📊 CLI Reference (For Development/Debugging)
+## 🛠️ CLI Usage
 
-> **Primary Interface**: Use GitHub labels in PR interface. CLI is mainly for maintainers debugging or developing Showtime itself.
+The CLI is primarily used by GitHub Actions, but available for debugging and advanced users:
 
-### Debugging Commands
 ```bash
-showtime list                         # Monitor all environments
-showtime status 1234                  # Debug specific environment
-showtime labels                       # Complete label reference
-showtime test-lifecycle 1234          # Full workflow simulation
-```
-
-### Manual Operations (Advanced)
-```bash
-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
+pip install superset-showtime
+export GITHUB_TOKEN=your_token
+showtime --help  # See all available commands
 ```
 
-### GitHub Actions Commands
-```bash
-showtime handle-trigger 1234          # Process trigger labels (called by GHA)
-showtime cleanup --older-than 48h     # Scheduled cleanup (called by GHA)
-```
 
-## 🎪 Benefits for Superset
-
-### For Contributors
-- **🎯 Simple workflow** - Just add/remove GitHub labels
-- **👀 Visual feedback** - See environment status in PR labels
-- **⚡ Automatic updates** - New commits update environments automatically
-- **🔧 Configuration testing** - Test config changes through code commits
-
-### For Maintainers
-- **📊 Complete visibility** - `showtime list` shows all environments
-- **🧹 Easy cleanup** - Automatic expired environment cleanup
-- **🔍 Better debugging** - Clear state in labels, comprehensive CLI
-- **💰 Cost savings** - No duplicate environments, proper cleanup
-
-### For Operations
-- **📝 Simpler workflows** - Replace complex GHA scripts with simple CLI calls
-- **🔒 Same security model** - No new permissions needed
-- **🎯 Deterministic** - Predictable AWS resource naming
-- **🚨 Monitoring ready** - 48h maximum lifetime, scheduled cleanup
-
-## 🏗️ Architecture
-
-### State Management
-All state lives in **GitHub labels** - no external databases needed:
-- **Trigger labels** (`🎪 trigger-*`) - Commands that get processed and removed
-- **State labels** (`🎪 🚦 *`) - Current environment status, managed by CLI
-
-### AWS Resources
-Deterministic naming enables reliable cleanup:
-- **ECS Service:** `pr-{pr_number}-{sha}` (e.g., `pr-1234-abc123f`)
-- **ECR Image:** `pr-{pr_number}-{sha}-ci` (e.g., `pr-1234-abc123f-ci`)
-
-### Rolling Updates
-Zero-downtime updates by running multiple environments:
-1. Keep old environment serving traffic
-2. Build new environment in parallel
-3. Switch traffic when new environment is healthy
-4. Clean up old environment
 
 ## 🤝 Contributing
 

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/README.md

@@ -48,9 +48,34 @@ Superset Showtime is a CLI tool designed primarily for **GitHub Actions** to man
 🎪 abc123f 🌐 52-1-2-3      # Available at http://52.1.2.3:8080
 ```
 
-## 📊 For Maintainers (CLI Operations)
+### 🔄 Showtime Workflow
+
+```mermaid
+flowchart TD
+    A[User adds 🎪 ⚡ trigger-start] --> B[GitHub Actions: sync]
+    B --> C{Current state?}
+
+    C -->|No environment| D[🔒 Claim: Remove trigger + Set building]
+    C -->|Running + new SHA| E[🔒 Claim: Remove trigger + Set building]
+    C -->|Already building| F[❌ Exit: Another job active]
+    C -->|No triggers| G[❌ Exit: Nothing to do]
+
+    D --> H[📋 State: building]
+    E --> H
+    H --> I[🐳 Docker build]
+    I -->|Success| J[📋 State: built]
+    I -->|Fail| K[📋 State: failed]
+
+    J --> L[📋 State: deploying]
+    L --> M[☁️ AWS Deploy]
+    M -->|Success| N[📋 State: running]
+    M -->|Fail| O[📋 State: failed]
+
+    N --> P[🎪 Environment ready!]
+
+    Q[User adds 🎪 🛑 trigger-stop] --> R[🧹 Cleanup AWS + Remove labels]
+```
 
-> **Note**: CLI is mainly for debugging or developing Showtime itself. Primary interface is GitHub labels above.
 
 **Install CLI for debugging:**
 ```bash
@@ -164,129 +189,31 @@ You'll see:
 
 ### GitHub Actions Integration
 
-Showtime is designed to be called by Superset's GitHub Actions workflows:
-
-```yaml
-# .github/workflows/showtime.yml - Integrates with Superset's existing build workflows
-on:
-  pull_request_target:
-    types: [labeled, unlabeled, synchronize]
-
-jobs:
-  showtime-handler:
-    if: contains(github.event.label.name, '🎪')
-    steps:
-      - name: Install Showtime from PyPI
-        run: pip install superset-showtime
-
-      - name: Process circus triggers
-        run: python -m showtime handle-trigger ${{ github.event.pull_request.number }}
-```
-
-**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 GitHub labels to trigger environments.
-
-### For Maintainers (Manual CLI Operations)
+**🎯 Live Workflow**: [showtime-trigger.yml](https://github.com/apache/superset/actions/workflows/showtime-trigger.yml)
 
-**Install CLI for debugging/testing:**
-```bash
-pip install superset-showtime
-export GITHUB_TOKEN=your_personal_access_token
-```
+**How it works:**
+- Triggers on PR label changes, commits, and closures
+- Installs `superset-showtime` from PyPI (trusted code, not PR code)
+- Runs `showtime sync` to handle trigger processing and deployments
+- Supports manual testing via `workflow_dispatch` with specific SHA override
 
-**Manual operations:**
+**Commands used:**
 ```bash
-showtime list                    # Monitor all active environments
-showtime status 1234            # Debug specific environment
-showtime labels                 # Reference complete label system
+showtime sync PR_NUMBER --check-only    # Determine build_needed + target_sha
+showtime sync PR_NUMBER --sha SHA       # Execute atomic claim + build + deploy
 ```
 
-### For Repository Integration (GitHub Actions)
-
-**1. Install GitHub workflows:**
-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`
-
-**3. Dependencies:**
-Showtime coordinates with Superset's existing build infrastructure - no additional setup needed.
-
-## 📊 CLI Reference (For Development/Debugging)
+## 🛠️ CLI Usage
 
-> **Primary Interface**: Use GitHub labels in PR interface. CLI is mainly for maintainers debugging or developing Showtime itself.
+The CLI is primarily used by GitHub Actions, but available for debugging and advanced users:
 
-### Debugging Commands
 ```bash
-showtime list                         # Monitor all environments
-showtime status 1234                  # Debug specific environment
-showtime labels                       # Complete label reference
-showtime test-lifecycle 1234          # Full workflow simulation
-```
-
-### Manual Operations (Advanced)
-```bash
-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
+pip install superset-showtime
+export GITHUB_TOKEN=your_token
+showtime --help  # See all available commands
 ```
 
-### GitHub Actions Commands
-```bash
-showtime handle-trigger 1234          # Process trigger labels (called by GHA)
-showtime cleanup --older-than 48h     # Scheduled cleanup (called by GHA)
-```
 
-## 🎪 Benefits for Superset
-
-### For Contributors
-- **🎯 Simple workflow** - Just add/remove GitHub labels
-- **👀 Visual feedback** - See environment status in PR labels
-- **⚡ Automatic updates** - New commits update environments automatically
-- **🔧 Configuration testing** - Test config changes through code commits
-
-### For Maintainers
-- **📊 Complete visibility** - `showtime list` shows all environments
-- **🧹 Easy cleanup** - Automatic expired environment cleanup
-- **🔍 Better debugging** - Clear state in labels, comprehensive CLI
-- **💰 Cost savings** - No duplicate environments, proper cleanup
-
-### For Operations
-- **📝 Simpler workflows** - Replace complex GHA scripts with simple CLI calls
-- **🔒 Same security model** - No new permissions needed
-- **🎯 Deterministic** - Predictable AWS resource naming
-- **🚨 Monitoring ready** - 48h maximum lifetime, scheduled cleanup
-
-## 🏗️ Architecture
-
-### State Management
-All state lives in **GitHub labels** - no external databases needed:
-- **Trigger labels** (`🎪 trigger-*`) - Commands that get processed and removed
-- **State labels** (`🎪 🚦 *`) - Current environment status, managed by CLI
-
-### AWS Resources
-Deterministic naming enables reliable cleanup:
-- **ECS Service:** `pr-{pr_number}-{sha}` (e.g., `pr-1234-abc123f`)
-- **ECR Image:** `pr-{pr_number}-{sha}-ci` (e.g., `pr-1234-abc123f-ci`)
-
-### Rolling Updates
-Zero-downtime updates by running multiple environments:
-1. Keep old environment serving traffic
-2. Build new environment in parallel
-3. Switch traffic when new environment is healthy
-4. Clean up old environment
 
 ## 🤝 Contributing
 

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/showtime/__init__.py

@@ -4,7 +4,7 @@
 Circus tent emoji state tracking for Apache Superset ephemeral environments.
 """
 
-__version__ = "0.2.8"
+__version__ = "0.2.9"
 __author__ = "Maxime Beauchemin"
 __email__ = "maximebeauchemin@gmail.com"
 

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/showtime/cli.py

@@ -4,6 +4,7 @@
 Main command-line interface for Apache Superset circus tent environment management.
 """
 
+import subprocess
 from typing import Optional
 
 import typer
@@ -14,6 +15,8 @@ from .core.circus import PullRequest, Show, short_sha
 from .core.emojis import STATUS_DISPLAY
 from .core.github import GitHubError, GitHubInterface
 from .core.github_messages import (
+    building_comment,
+    failure_comment,
     get_aws_console_urls,
     rolling_failure_comment,
     rolling_start_comment,
@@ -176,6 +179,232 @@ def _get_showtime_footer() -> str:
     return "{_get_showtime_footer()}"
 
 
+def _validate_non_active_state(pr: PullRequest) -> bool:
+    """Check if PR is in a state where new work can begin
+
+    Args:
+        pr: PullRequest object with current state
+
+    Returns:
+        True if safe to start new work, False if another job is already active
+    """
+    if pr.current_show:
+        active_states = ["building", "built", "deploying", "running", "updating"]
+        if pr.current_show.status in active_states:
+            return False  # Already active
+    return True  # Safe to proceed
+
+
+def _atomic_claim_environment(
+    pr_number: int, target_sha: str, github: GitHubInterface, dry_run: bool = False
+) -> bool:
+    """Atomically claim environment for this job using compare-and-swap pattern
+
+    Args:
+        pr_number: PR number to claim
+        target_sha: Target commit SHA
+        github: GitHub interface for label operations
+        dry_run: If True, simulate operations
+
+    Returns:
+        True if successfully claimed, False if another job already active or no triggers
+    """
+    from datetime import datetime
+
+    try:
+        # 1. CHECK: Load current PR state
+        pr = PullRequest.from_id(pr_number, github)
+
+        # 2. VALIDATE: Ensure non-active state (compare part of compare-and-swap)
+        if not _validate_non_active_state(pr):
+            current_state = pr.current_show.status if pr.current_show else "unknown"
+            console.print(
+                f"🎪 Environment already active (state: {current_state}) - another job is running"
+            )
+            return False
+
+        # 3. FIND TRIGGERS: Must have triggers to claim
+        trigger_labels = [label for label in pr.labels if "showtime-trigger-" in label]
+        if not trigger_labels:
+            console.print("🎪 No trigger labels found - nothing to claim")
+            return False
+
+        # 4. VALIDATE TRIGGER-SPECIFIC STATE REQUIREMENTS
+        for trigger_label in trigger_labels:
+            if "showtime-trigger-start" in trigger_label:
+                # Start trigger: should NOT already be building/running
+                if pr.current_show and pr.current_show.status in [
+                    "building",
+                    "built",
+                    "deploying",
+                    "running",
+                ]:
+                    console.print(
+                        f"🎪 Start trigger invalid - environment already {pr.current_show.status}"
+                    )
+                    return False
+            elif "showtime-trigger-stop" in trigger_label:
+                # Stop trigger: should HAVE an active environment
+                if not pr.current_show or pr.current_show.status in ["failed"]:
+                    console.print("🎪 Stop trigger invalid - no active environment to stop")
+                    return False
+
+        console.print(f"🎪 Claiming environment for PR #{pr_number} SHA {target_sha[:7]}")
+        console.print(f"🎪 Found {len(trigger_labels)} valid trigger(s) to process")
+
+        if dry_run:
+            console.print(
+                "🎪 [bold yellow]DRY-RUN[/bold yellow] - Would atomically claim environment"
+            )
+            return True
+
+        # 4. ATOMIC SWAP: Remove triggers + Set building state (swap part)
+        console.print("🎪 Executing atomic claim (remove triggers + set building)...")
+
+        # Remove all trigger labels first
+        for trigger_label in trigger_labels:
+            console.print(f"  🗑️ Removing trigger: {trigger_label}")
+            github.remove_label(pr_number, trigger_label)
+
+        # Immediately set building state to claim the environment
+        building_show = Show(
+            pr_number=pr_number,
+            sha=short_sha(target_sha),
+            status="building",
+            created_at=datetime.utcnow().strftime("%Y-%m-%dT%H-%M"),
+            ttl="24h",
+            requested_by=_get_github_actor(),
+        )
+
+        # Clear any stale state and set building labels atomically
+        github.remove_circus_labels(pr_number)
+        for label in building_show.to_circus_labels():
+            github.add_label(pr_number, label)
+
+        console.print("🎪 ✅ Environment claimed successfully")
+        return True
+
+    except Exception as e:
+        console.print(f"🎪 ❌ Failed to claim environment: {e}")
+        return False
+
+
+def _build_docker_image(pr_number: int, sha: str, dry_run: bool = False) -> bool:
+    """Build Docker image directly without supersetbot dependency
+
+    Args:
+        pr_number: PR number for tagging
+        sha: Full commit SHA
+        dry_run: If True, print command but don't execute
+
+    Returns:
+        True if build succeeded, False if failed
+    """
+    tag = f"apache/superset:pr-{pr_number}-{short_sha(sha)}-ci"
+
+    cmd = [
+        "docker",
+        "buildx",
+        "build",
+        "--push",
+        "--load",
+        "--platform",
+        "linux/amd64",
+        "--target",
+        "ci",
+        "--build-arg",
+        "PY_VER=3.10-slim-bookworm",
+        "--build-arg",
+        "INCLUDE_CHROMIUM=false",
+        "--build-arg",
+        "LOAD_EXAMPLES_DUCKDB=true",
+        "-t",
+        tag,
+        ".",
+    ]
+
+    console.print(f"🐳 Building Docker image: {tag}")
+    if dry_run:
+        console.print(f"🎪 [bold yellow]DRY-RUN[/bold yellow] - Would run: {' '.join(cmd)}")
+        return True
+
+    try:
+        console.print(f"🎪 Running: {' '.join(cmd)}")
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)  # 30 min timeout
+
+        if result.returncode == 0:
+            console.print(f"🎪 ✅ Docker build succeeded: {tag}")
+            return True
+        else:
+            console.print("🎪 ❌ Docker build failed:")
+            console.print(f"Exit code: {result.returncode}")
+            console.print(f"STDOUT: {result.stdout}")
+            console.print(f"STDERR: {result.stderr}")
+            return False
+
+    except subprocess.TimeoutExpired:
+        console.print("🎪 ❌ Docker build timed out after 30 minutes")
+        return False
+    except Exception as e:
+        console.print(f"🎪 ❌ Docker build error: {e}")
+        return False
+
+
+def _set_state_internal(
+    state: str,
+    pr_number: int,
+    show: Show,
+    github: GitHubInterface,
+    dry_run_github: bool = False,
+    error_msg: Optional[str] = None,
+) -> None:
+    """Internal helper to set state and handle comments/labels
+
+    Used by sync and other commands to set final state transitions
+    """
+    console.print(f"🎪 Setting state to '{state}' for PR #{pr_number} SHA {show.sha}")
+
+    # Update show state
+    show.status = state
+
+    # Handle state-specific logic
+    comment_text = None
+
+    if state == "building":
+        comment_text = building_comment(show)
+        console.print("🎪 Posting building comment...")
+
+    elif state == "running":
+        comment_text = success_comment(show)
+        console.print("🎪 Posting success comment...")
+
+    elif state == "failed":
+        error_message = error_msg or "Build or deployment failed"
+        comment_text = failure_comment(show, error_message)
+        console.print("🎪 Posting failure comment...")
+
+    elif state in ["built", "deploying"]:
+        console.print(f"🎪 Silent state change to '{state}' - no comment posted")
+
+    # Post comment if needed
+    if comment_text and not dry_run_github:
+        github.post_comment(pr_number, comment_text)
+        console.print("🎪 ✅ Comment posted!")
+    elif comment_text:
+        console.print("🎪 [bold yellow]DRY-RUN-GITHUB[/bold yellow] - Would post comment")
+
+    # Set state labels
+    state_labels = show.to_circus_labels()
+
+    if not dry_run_github:
+        github.remove_circus_labels(pr_number)
+        for label in state_labels:
+            github.add_label(pr_number, label)
+        console.print("🎪 ✅ Labels updated!")
+    else:
+        console.print("🎪 [bold yellow]DRY-RUN-GITHUB[/bold yellow] - Would update labels")
+
+
 @app.command()
 def version():
     """Show version information"""
@@ -184,6 +413,74 @@ def version():
     console.print(f"🎪 Superset Showtime v{__version__}")
 
 
+@app.command()
+def set_state(
+    state: str = typer.Argument(
+        ..., help="State to set (building, built, deploying, running, failed)"
+    ),
+    pr_number: int = typer.Argument(..., help="PR number to update"),
+    sha: Optional[str] = typer.Option(None, "--sha", help="Specific commit SHA (default: latest)"),
+    error_msg: Optional[str] = typer.Option(
+        None, "--error-msg", help="Error message for failed state"
+    ),
+    dry_run_github: bool = typer.Option(
+        False, "--dry-run-github", help="Skip GitHub operations, show what would happen"
+    ),
+):
+    """🎪 Set environment state (generic state transition command)
+
+    States:
+    • building - Docker image is being built (posts comment)
+    • built - Docker build complete, ready for deployment (silent)
+    • deploying - AWS deployment in progress (silent)
+    • running - Environment is live and ready (posts success comment)
+    • failed - Build or deployment failed (posts error comment)
+    """
+    from datetime import datetime
+
+    try:
+        github = GitHubInterface()
+
+        # Get SHA - use provided SHA or default to latest
+        if sha:
+            target_sha = sha
+            console.print(f"🎪 Using specified SHA: {target_sha[:7]}")
+        else:
+            target_sha = github.get_latest_commit_sha(pr_number)
+            console.print(f"🎪 Using latest SHA: {target_sha[:7]}")
+
+        # Validate state
+        valid_states = ["building", "built", "deploying", "running", "failed"]
+        if state not in valid_states:
+            console.print(f"❌ Invalid state: {state}. Must be one of: {', '.join(valid_states)}")
+            raise typer.Exit(1)
+
+        # Get GitHub actor
+        github_actor = _get_github_actor()
+
+        # Create or update show object
+        show = Show(
+            pr_number=pr_number,
+            sha=short_sha(target_sha),
+            status=state,
+            created_at=datetime.utcnow().strftime("%Y-%m-%dT%H-%M"),
+            ttl="24h",
+            requested_by=github_actor,
+        )
+
+        # Use internal helper to set state
+        _set_state_internal(state, pr_number, show, github, dry_run_github, error_msg)
+
+        console.print(f"🎪 [bold green]State successfully set to '{state}'[/bold green]")
+
+    except GitHubError as e:
+        console.print(f"❌ GitHub error: {e}")
+        raise typer.Exit(1) from e
+    except Exception as e:
+        console.print(f"❌ Error: {e}")
+        raise typer.Exit(1) from e
+
+
 @app.command()
 def start(
     pr_number: int = typer.Argument(..., help="PR number to create environment for"),
@@ -648,15 +945,15 @@ def sync(
     check_only: bool = typer.Option(
         False, "--check-only", help="Check what actions are needed without executing"
     ),
-    deploy: bool = typer.Option(
-        False, "--deploy", help="Execute deployment actions (assumes build is complete)"
-    ),
     dry_run_aws: bool = typer.Option(
         False, "--dry-run-aws", help="Skip AWS operations, use mock data"
     ),
     dry_run_github: bool = typer.Option(
         False, "--dry-run-github", help="Skip GitHub label operations"
     ),
+    dry_run_docker: bool = typer.Option(
+        False, "--dry-run-docker", help="Skip Docker build, use mock success"
+    ),
     aws_sleep: int = typer.Option(
         0, "--aws-sleep", help="Seconds to sleep during AWS operations (for testing)"
     ),
@@ -685,18 +982,99 @@ def sync(
         action_needed = _determine_sync_action(pr, pr_state, target_sha)
 
         if check_only:
-            # Output structured results for GitHub Actions
-            console.print(f"action_needed={action_needed}")
-
-            # Build needed for new environments and updates (SHA changes)
+            # Output simple results for GitHub Actions
             build_needed = action_needed in ["create_environment", "rolling_update", "auto_sync"]
-            console.print(f"build_needed={str(build_needed).lower()}")
+            sync_needed = action_needed != "no_action"
 
-            # Deploy needed for everything except no_action
-            deploy_needed = action_needed != "no_action"
-            console.print(f"deploy_needed={str(deploy_needed).lower()}")
+            console.print(f"build_needed={str(build_needed).lower()}")
+            console.print(f"sync_needed={str(sync_needed).lower()}")
+            console.print(f"pr_number={pr_number}")
+            console.print(f"target_sha={target_sha}")
             return
 
+        # Default behavior: execute the sync (directive command)
+        # Use --check-only to override this and do read-only analysis
+        if not check_only:
+            console.print(
+                f"🎪 [bold blue]Syncing PR #{pr_number}[/bold blue] (SHA: {target_sha[:7]})"
+            )
+            console.print(f"🎪 Action needed: {action_needed}")
+
+            # For trigger-based actions, use atomic claim to prevent race conditions
+            if action_needed in ["create_environment", "rolling_update", "destroy_environment"]:
+                if not _atomic_claim_environment(pr_number, target_sha, github, dry_run_github):
+                    console.print("🎪 Unable to claim environment - exiting")
+                    return
+                console.print("🎪 ✅ Environment claimed - proceeding with work")
+
+            # Execute based on determined action
+            if action_needed == "cleanup":
+                console.print("🎪 PR is closed - cleaning up environment")
+                if pr.current_show:
+                    _handle_stop_trigger(pr_number, github, dry_run_aws, dry_run_github)
+                else:
+                    console.print("🎪 No environment to clean up")
+                return
+
+            elif action_needed in ["create_environment", "rolling_update"]:
+                # These require Docker build + deployment
+                console.print(f"🎪 Starting {action_needed} workflow")
+
+                # Post building comment (atomic claim already set building state)
+                if action_needed == "create_environment":
+                    console.print("🎪 Posting building comment...")
+                elif action_needed == "rolling_update":
+                    console.print("🎪 Posting rolling update comment...")
+
+                # Build Docker image
+                build_success = _build_docker_image(pr_number, target_sha, dry_run_docker)
+                if not build_success:
+                    _set_state_internal(
+                        "failed",
+                        pr_number,
+                        Show(
+                            pr_number=pr_number,
+                            sha=short_sha(target_sha),
+                            status="failed",
+                            requested_by=_get_github_actor(),
+                        ),
+                        github,
+                        dry_run_github,
+                        "Docker build failed",
+                    )
+                    return
+
+                # Continue with AWS deployment (reuse existing logic)
+                _handle_start_trigger(
+                    pr_number,
+                    github,
+                    dry_run_aws,
+                    dry_run_github,
+                    aws_sleep,
+                    docker_tag,
+                    force=True,
+                )
+                return
+
+            elif action_needed == "destroy_environment":
+                console.print("🎪 Destroying environment")
+                _handle_stop_trigger(pr_number, github, dry_run_aws, dry_run_github)
+                return
+
+            elif action_needed == "auto_sync":
+                console.print("🎪 Auto-sync on new commit")
+                # This also requires build + deployment
+                build_success = _build_docker_image(pr_number, target_sha, dry_run_docker)
+                if build_success:
+                    _handle_sync_trigger(pr_number, github, dry_run_aws, dry_run_github, aws_sleep)
+                else:
+                    console.print("🎪 ❌ Auto-sync failed due to build failure")
+                return
+
+            else:
+                console.print(f"🎪 No action needed ({action_needed})")
+                return
+
         console.print(
             f"🎪 [bold blue]Syncing PR #{pr_number}[/bold blue] (state: {pr_state}, SHA: {target_sha[:7]})"
         )
@@ -1238,57 +1616,18 @@ def _handle_start_trigger(
                         )
                         _schedule_blue_cleanup(pr_number, blue_services)
 
-                # Update to running state with new SHA
-                show.status = "running"
+                # Update show with deployment result
                 show.ip = result.ip
 
-                # Traffic switching happens here - update GitHub labels atomically
-                running_labels = show.to_circus_labels()
-                console.print("\n🎪 Setting running state labels (traffic switch):")
-                for label in running_labels:
-                    console.print(f"  + {label}")
-
-                if not dry_run_github:
-                    console.print("🎪 Executing traffic switch via GitHub labels...")
-                    # Remove existing circus labels first
-                    github.remove_circus_labels(pr_number)
-                    # Add new running labels - this switches traffic atomically
-                    for label in running_labels:
-                        github.add_label(pr_number, label)
-                    console.print("🎪 ✅ Labels updated to running state!")
-
-                    # Post success comment with real IP
-                    # Update show with real IP for comment
-                    show.ip = result.ip
-                    show.status = "running"
-                    success_comment_text = success_comment(show, feature_count=len(feature_flags))
-
-                    github.post_comment(pr_number, success_comment_text)
+                # Use internal helper to set running state (posts success comment)
+                console.print("\n🎪 Traffic switching to running state:")
+                _set_state_internal("running", pr_number, show, github, dry_run_github)
 
             else:
                 console.print(f"🎪 [bold red]❌ AWS deployment failed:[/bold red] {result.error}")
 
-                # Update to failed state
-                show.status = "failed"
-                failed_labels = show.to_circus_labels()
-
-                if not dry_run_github:
-                    console.print("🎪 Setting failed state labels...")
-                    github.remove_circus_labels(pr_number)
-                    for label in failed_labels:
-                        github.add_label(pr_number, label)
-
-                    # Post failure comment
-                    failure_comment = f"""🎪 @{github_actor} Environment creation failed.
-
-**Error:** {result.error}
-**Environment:** `{show.sha}`
-
-Please check the logs and try again.
-
-{_get_showtime_footer()}"""
-
-                    github.post_comment(pr_number, failure_comment)
+                # Use internal helper to set failed state (posts failure comment)
+                _set_state_internal("failed", pr_number, show, github, dry_run_github, result.error)
 
     except Exception as e:
         console.print(f"🎪 [bold red]Start trigger failed:[/bold red] {e}")

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/showtime/core/circus.py

@@ -18,7 +18,7 @@ class Show:
 
     pr_number: int
     sha: str  # 7-char commit SHA
-    status: str  # building, running, updating, failed
+    status: str  # building, built, deploying, running, updating, failed
     ip: Optional[str] = None  # Environment IP address
     created_at: Optional[str] = None  # ISO timestamp
     ttl: str = "24h"  # 24h, 48h, close, etc.
@@ -54,6 +54,16 @@ class Show:
         """Check if environment is currently building"""
         return self.status == "building"
 
+    @property
+    def is_built(self) -> bool:
+        """Check if environment is built (Docker complete, ready for deploy)"""
+        return self.status == "built"
+
+    @property
+    def is_deploying(self) -> bool:
+        """Check if environment is currently deploying to AWS"""
+        return self.status == "deploying"
+
     @property
     def is_updating(self) -> bool:
         """Check if environment is currently updating"""

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/showtime/core/github_messages.py

@@ -96,8 +96,18 @@ def get_aws_console_urls(service_name: str) -> Dict[str, str]:
 # Typed comment functions with clear parameter requirements
 
 
+def building_comment(show: Show) -> str:
+    """Create building start comment
+
+    Args:
+        show: Show object with SHA and other metadata
+    """
+    links = _create_header_links(show.sha)
+    return f"🎪 {links['showtime_link']} is building environment on {links['gha_link']} for {links['commit_link']}"
+
+
 def start_comment(show: Show) -> str:
-    """Create environment start comment
+    """Create environment start comment (DEPRECATED - use building_comment)
 
     Args:
         show: Show object with SHA and other metadata

{superset_showtime-0.2.8 → superset_showtime-0.2.9}/workflows-reference/showtime-trigger.yml

@@ -3,7 +3,7 @@ name: 🎪 Superset Showtime
 # Ultra-simple: just sync on any PR state change
 on:
   pull_request_target:
-    types: [labeled, unlabeled, synchronize, closed]
+    types: [labeled, synchronize, closed]
 
   # Manual testing
   workflow_dispatch:
@@ -57,20 +57,27 @@ jobs:
           fi
 
           echo "Using PR number: $PR_NUM"
-          OUTPUT=$(python -m showtime sync $PR_NUM --check-only)
+
+          # Run sync check-only with optional SHA override
+          if [[ -n "${{ github.event.inputs.sha }}" ]]; then
+            OUTPUT=$(python -m showtime sync $PR_NUM --check-only --sha "${{ github.event.inputs.sha }}")
+          else
+            OUTPUT=$(python -m showtime sync $PR_NUM --check-only)
+          fi
           echo "$OUTPUT"
 
-          # Extract outputs for conditional steps
-          ACTION=$(echo "$OUTPUT" | grep "action_needed=" | cut -d'=' -f2)
+          # Extract the outputs we need for conditional steps
           BUILD=$(echo "$OUTPUT" | grep "build_needed=" | cut -d'=' -f2)
-          DEPLOY=$(echo "$OUTPUT" | grep "deploy_needed=" | cut -d'=' -f2)
+          SYNC=$(echo "$OUTPUT" | grep "sync_needed=" | cut -d'=' -f2)
+          PR_NUM_OUT=$(echo "$OUTPUT" | grep "pr_number=" | cut -d'=' -f2)
+          TARGET_SHA=$(echo "$OUTPUT" | grep "target_sha=" | cut -d'=' -f2)
 
-          echo "action_needed=$ACTION" >> $GITHUB_OUTPUT
           echo "build_needed=$BUILD" >> $GITHUB_OUTPUT
-          echo "deploy_needed=$DEPLOY" >> $GITHUB_OUTPUT
-          echo "pr_number=$PR_NUM" >> $GITHUB_OUTPUT
+          echo "sync_needed=$SYNC" >> $GITHUB_OUTPUT
+          echo "pr_number=$PR_NUM_OUT" >> $GITHUB_OUTPUT
+          echo "target_sha=$TARGET_SHA" >> $GITHUB_OUTPUT
 
-      - name: Setup Docker Environment
+      - name: Setup Docker Environment (only if build needed)
         if: steps.check.outputs.build_needed == 'true'
         uses: ./.github/actions/setup-docker
         with:
@@ -78,58 +85,20 @@ jobs:
           dockerhub-token: ${{ env.DOCKERHUB_TOKEN }}
           build: "true"
 
-      - name: Setup supersetbot
-        if: steps.check.outputs.build_needed == 'true'
-        uses: ./.github/actions/setup-supersetbot/
-
-      - name: Get PR SHA for build
-        id: sha
-        if: steps.check.outputs.build_needed == 'true'
-        run: |
-          # Simple SHA handling - use input or default to PR head
-          if [[ -n "${{ github.event.inputs.sha }}" ]]; then
-            SHA="${{ github.event.inputs.sha }}"
-            echo "Using override SHA: $SHA"
-          elif [[ -n "${{ github.event.pull_request.head.sha }}" ]]; then
-            SHA="${{ github.event.pull_request.head.sha }}"
-            echo "Using PR head SHA: $SHA"
-          else
-            echo "❌ No SHA available from PR head or inputs"
-            exit 1
-          fi
-
-          # Validate SHA format (40-char hex)
-          if [[ ! "$SHA" =~ ^[a-f0-9]{40}$ ]]; then
-            echo "❌ Invalid SHA format: $SHA"
-            exit 1
-          fi
-
-          echo "build_sha=$SHA" >> $GITHUB_OUTPUT
-
-      - name: Checkout PR code
+      - name: Checkout PR code (only if build needed)
         if: steps.check.outputs.build_needed == 'true'
         uses: actions/checkout@v4
         with:
-          ref: ${{ steps.sha.outputs.build_sha }}
+          ref: ${{ steps.check.outputs.target_sha }}
           persist-credentials: false
 
-      - name: Build Docker image
-        if: steps.check.outputs.build_needed == 'true'
-        run: |
-          supersetbot docker \
-            --push \
-            --load \
-            --preset ci \
-            --platform linux/amd64 \
-            --context-ref "${{ steps.sha.outputs.build_sha }}" \
-            --extra-flags "--build-arg INCLUDE_CHROMIUM=false --build-arg LOAD_EXAMPLES_DUCKDB=true"
-
-      - name: Execute sync deployment
-        if: steps.check.outputs.deploy_needed == 'true'
+      - name: Execute sync (handles everything)
+        if: steps.check.outputs.sync_needed == 'true'
         run: |
           PR_NUM="${{ steps.check.outputs.pr_number }}"
-          if [[ -n "${{ github.event.inputs.sha }}" ]]; then
-            python -m showtime sync $PR_NUM --deploy --sha "${{ github.event.inputs.sha }}"
+          TARGET_SHA="${{ steps.check.outputs.target_sha }}"
+          if [[ -n "$TARGET_SHA" ]]; then
+            python -m showtime sync $PR_NUM --sha "$TARGET_SHA"
           else
-            python -m showtime sync $PR_NUM --deploy
+            python -m showtime sync $PR_NUM
           fi