superset-showtime 0.3.3__tar.gz → 0.4.2__tar.gz

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/.claude/settings.local.json

@@ -35,7 +35,13 @@
       "Bash(git pull:*)",
       "Bash(git rebase:*)",
       "Bash(git fetch:*)",
-      "Read(//Users/max/.claudette/worktrees/showtime/**)"
+      "Read(//Users/max/.claudette/worktrees/showtime/**)",
+      "Bash(rg:*)",
+      "Bash(find:*)",
+      "Bash(make:*)",
+      "Bash(showtime status:*)",
+      "Bash(showtime sync:*)",
+      "Bash(AWS_PROFILE=\"\" showtime sync 34831 --dry-run-aws --dry-run-github)"
     ],
     "deny": [],
     "ask": []

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/.pre-commit-config.yaml

@@ -17,3 +17,11 @@ repos:
       - id: ruff
         args: [--fix]
       - id: ruff-format
+
+# TODO: Re-enable after fixing boto3-stubs type conflicts
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v1.8.0
+  #   hooks:
+  #     - id: mypy
+  #       files: ^showtime/
+  #       additional_dependencies: [types-requests, "boto3-stubs[ecs,ecr,ec2]"]

superset_showtime-0.4.2/CLAUDE.md

@@ -0,0 +1,160 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Superset Showtime is a CLI tool for managing Apache Superset ephemeral environments using "circus tent emoji labels" as a visual state management system on GitHub PRs. The tool integrates with GitHub Actions to provide automated environment provisioning on AWS ECS/ECR.
+
+## Development Commands
+
+**Package Management:**
+```bash
+# Install for development (preferred)
+uv pip install -e ".[dev]"
+
+# Traditional pip installation
+pip install -e ".[dev]"
+```
+
+**Code Quality:**
+```bash
+make lint           # Run ruff and mypy checks
+make format         # Auto-format with ruff
+make pre-commit     # Install pre-commit hooks
+make pre-commit-run # Run all pre-commit hooks
+```
+
+**Testing:**
+```bash
+make test          # Run pytest
+make test-cov      # Run tests with coverage report
+pytest tests/unit/test_circus.py  # Run specific test file
+```
+
+**Build and Distribution:**
+```bash
+make build         # Build package with uv
+make publish       # Publish to PyPI (use with caution)
+make clean         # Clean build artifacts
+```
+
+**Quick Testing:**
+```bash
+make circus        # Test circus emoji parsing logic
+```
+
+## Core Architecture
+
+### Main Components
+
+**CLI Layer (`showtime/cli.py`):**
+- Typer-based CLI with rich output formatting
+- Commands: `sync`, `start`, `stop`, `status`, `list`, `labels`, `cleanup`
+- Primary entry point for GitHub Actions and manual usage
+
+**Core Business Logic (`showtime/core/`):**
+
+1. **PullRequest (`pull_request.py`)** - Main orchestrator
+   - Manages PR-level state and atomic transactions
+   - Handles trigger processing and environment lifecycle
+   - Coordinates between GitHub labels and AWS resources
+   - Implements sync logic for automatic deployments
+
+2. **Show (`show.py`)** - Individual environment representation
+   - Represents a single ephemeral environment
+   - Manages Docker builds and AWS deployments
+   - Handles state transitions (building → running → failed)
+
+3. **GitHubInterface (`github.py`)** - GitHub API client
+   - Label management and PR data fetching
+   - Circus tent emoji label parsing and creation
+   - Token detection from environment or gh CLI
+
+4. **AWSInterface (`aws.py`)** - AWS operations
+   - ECS service deployment and management
+   - ECR image management
+   - Network configuration and service discovery
+
+### State Management Pattern
+
+The system uses GitHub labels as a distributed state machine:
+
+**Trigger Labels (User Actions):**
+- `🎪 ⚡ showtime-trigger-start` - Create environment
+- `🎪 🛑 showtime-trigger-stop` - Destroy environment
+- `🎪 🧊 showtime-freeze` - Prevent auto-sync
+
+**State Labels (System Managed):**
+- `🎪 {sha} 🚦 {status}` - Environment status
+- `🎪 🎯 {sha}` - Active environment pointer
+- `🎪 🏗️ {sha}` - Building environment pointer
+- `🎪 {sha} 🌐 {ip}` - Environment URL
+- `🎪 {sha} 📅 {timestamp}` - Creation timestamp
+
+### Atomic Transaction Model
+
+The `PullRequest.sync()` method implements an atomic claim pattern:
+1. **Claim**: Atomically remove trigger labels and set building state
+2. **Build**: Docker build with deterministic tags (`pr-{number}-{sha}-ci`)
+3. **Deploy**: AWS ECS service deployment with blue-green updates
+4. **Validate**: Health checks and state synchronization
+
+## Testing Approach
+
+**Unit Tests:** Focus on circus label parsing and business logic
+**Integration Tests:** Test with `--dry-run-aws --dry-run-docker` flags
+**Manual Testing:** Use CLI commands with dry-run modes
+
+## Key Design Principles
+
+1. **Deterministic Naming:** All AWS resources use `pr-{number}-{sha}` pattern
+2. **Idempotent Operations:** Safe to retry any operation
+3. **Visual State Management:** GitHub labels provide immediate status visibility
+4. **Zero-Downtime Updates:** Blue-green deployments with automatic traffic switching
+5. **Fail-Safe Defaults:** Conservative cleanup and error handling
+
+## Environment Variables
+
+**Required:**
+- `GITHUB_TOKEN` - GitHub API access
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` - AWS credentials
+
+**Optional:**
+- `AWS_REGION` - Default: us-west-2
+- `ECS_CLUSTER` - Default: superset-ci
+- `ECR_REPOSITORY` - Default: superset-ci
+- `GITHUB_ORG` - Default: apache
+- `GITHUB_REPO` - Default: superset
+
+## GitHub Actions Integration
+
+The tool is designed to be called from GitHub Actions workflows:
+```yaml
+- name: Install Superset Showtime
+  run: pip install superset-showtime
+
+- name: Sync PR state
+  run: showtime sync ${{ github.event.number }}
+```
+
+Primary workflow file: `workflows-reference/showtime-trigger.yml`
+
+## Common Development Patterns
+
+**Testing without AWS costs:**
+```bash
+showtime sync 1234 --dry-run-aws --dry-run-docker
+```
+
+**Debugging specific PR:**
+```bash
+showtime status 1234 --verbose
+showtime list --status running
+```
+
+**Manual environment management:**
+```bash
+showtime start 1234 --sha abc123f
+showtime stop 1234 --force
+```

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/Makefile

@@ -51,4 +51,4 @@ publish: ## Publish to PyPI (use with caution)
 	uvx twine upload dist/*
 
 circus: ## Quick test of circus emoji parsing
-	python -c "from showtime.core.circus import parse_circus_labels; print(parse_circus_labels(['🎪 🚦 running', '🎪 🎯 abc123f']))"
+	python -c "from showtime.core.show import Show; labels=['🎪 abc123f 🚦 running', '🎪 🎯 abc123f']; show=Show.from_circus_labels(1234, labels, 'abc123f'); print(f'Status: {show.status}, SHA: {show.sha}')"

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superset-showtime
-Version: 0.3.3
+Version: 0.4.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/
@@ -49,6 +49,7 @@ Provides-Extra: azure
 Requires-Dist: azure-mgmt-containerinstance>=10.0.0; extra == 'azure'
 Requires-Dist: azure-storage-blob>=12.0.0; extra == 'azure'
 Provides-Extra: dev
+Requires-Dist: boto3-stubs[ec2,ecr,ecs]>=1.40.0; extra == 'dev'
 Requires-Dist: build>=1.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
@@ -157,11 +158,11 @@ showtime labels                 # Complete label reference
 
 **Testing/development:**
 ```bash
-showtime start 1234 --dry-run-aws      # Test without AWS costs
-showtime test-lifecycle 1234           # Full workflow simulation
+showtime sync 1234 --dry-run-aws --dry-run-docker  # Test without costs
+showtime cleanup --dry-run --older-than 1h         # Test cleanup logic
 ```
 
-> **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.
+> **Architecture**: This CLI implements ACID-style atomic transactions with direct Docker integration. It handles complete environment lifecycle from Docker build to AWS deployment with race condition prevention.
 
 ## 🎪 Complete Label Reference
 
@@ -275,7 +276,14 @@ The CLI is primarily used by GitHub Actions, but available for debugging and adv
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_token
-showtime --help  # See all available commands
+
+# Core commands:
+showtime sync PR_NUMBER              # Sync to desired state (main command)
+showtime start PR_NUMBER             # Create new environment
+showtime stop PR_NUMBER              # Delete environment
+showtime status PR_NUMBER            # Show current state
+showtime list                        # List all environments
+showtime cleanup --older-than 48h    # Clean up expired environments
 ```
 
 
@@ -286,11 +294,11 @@ showtime --help  # See all available commands
 
 **Test with real PRs safely:**
 ```bash
-# Test label management without AWS costs:
-showtime start YOUR_PR_NUMBER --dry-run-aws --aws-sleep 10
+# Test full workflow without costs:
+showtime sync YOUR_PR_NUMBER --dry-run-aws --dry-run-docker
 
-# Test full lifecycle:
-showtime test-lifecycle YOUR_PR_NUMBER --real-github
+# Test cleanup logic:
+showtime cleanup --dry-run --older-than 24h
 ```
 
 ### Development Setup

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/README.md

@@ -92,11 +92,11 @@ showtime labels                 # Complete label reference
 
 **Testing/development:**
 ```bash
-showtime start 1234 --dry-run-aws      # Test without AWS costs
-showtime test-lifecycle 1234           # Full workflow simulation
+showtime sync 1234 --dry-run-aws --dry-run-docker  # Test without costs
+showtime cleanup --dry-run --older-than 1h         # Test cleanup logic
 ```
 
-> **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.
+> **Architecture**: This CLI implements ACID-style atomic transactions with direct Docker integration. It handles complete environment lifecycle from Docker build to AWS deployment with race condition prevention.
 
 ## 🎪 Complete Label Reference
 
@@ -210,7 +210,14 @@ The CLI is primarily used by GitHub Actions, but available for debugging and adv
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_token
-showtime --help  # See all available commands
+
+# Core commands:
+showtime sync PR_NUMBER              # Sync to desired state (main command)
+showtime start PR_NUMBER             # Create new environment
+showtime stop PR_NUMBER              # Delete environment
+showtime status PR_NUMBER            # Show current state
+showtime list                        # List all environments
+showtime cleanup --older-than 48h    # Clean up expired environments
 ```
 
 
@@ -221,11 +228,11 @@ showtime --help  # See all available commands
 
 **Test with real PRs safely:**
 ```bash
-# Test label management without AWS costs:
-showtime start YOUR_PR_NUMBER --dry-run-aws --aws-sleep 10
+# Test full workflow without costs:
+showtime sync YOUR_PR_NUMBER --dry-run-aws --dry-run-docker
 
-# Test full lifecycle:
-showtime test-lifecycle YOUR_PR_NUMBER --real-github
+# Test cleanup logic:
+showtime cleanup --dry-run --older-than 24h
 ```
 
 ### Development Setup

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/pyproject.toml

@@ -77,6 +77,7 @@ dev = [
     "pre-commit>=3.0.0",
     "build>=1.0.0",
     "twine>=4.0.0",
+    "boto3-stubs[ecs,ecr,ec2]>=1.40.0",
 ]
 
 [project.urls]
@@ -120,7 +121,7 @@ ignore = [
 "__init__.py" = ["F401"]
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/requirements-dev.txt

@@ -8,11 +8,15 @@ backports-tarfile==1.2.0
     # via jaraco-context
 boto3==1.40.16
     # via superset-showtime (pyproject.toml)
+boto3-stubs==1.40.16
+    # via superset-showtime (pyproject.toml)
 botocore==1.40.16
     # via
     #   superset-showtime (pyproject.toml)
     #   boto3
     #   s3transfer
+botocore-stubs==1.38.46
+    # via boto3-stubs
 build==1.3.0
     # via superset-showtime (pyproject.toml)
 certifi==2025.8.3
@@ -79,6 +83,12 @@ more-itertools==10.7.0
     #   jaraco-functools
 mypy==1.17.1
     # via superset-showtime (pyproject.toml)
+mypy-boto3-ec2==1.40.13
+    # via boto3-stubs
+mypy-boto3-ecr==1.40.0
+    # via boto3-stubs
+mypy-boto3-ecs==1.40.15
+    # via boto3-stubs
 mypy-extensions==1.1.0
     # via mypy
 nh3==0.3.0
@@ -157,10 +167,18 @@ twine==6.1.0
     # via superset-showtime (pyproject.toml)
 typer==0.16.1
     # via superset-showtime (pyproject.toml)
+types-awscrt==0.27.6
+    # via botocore-stubs
+types-s3transfer==0.13.0
+    # via boto3-stubs
 typing-extensions==4.14.1
     # via
     #   anyio
+    #   boto3-stubs
     #   mypy
+    #   mypy-boto3-ec2
+    #   mypy-boto3-ecr
+    #   mypy-boto3-ecs
     #   pydantic
     #   pydantic-core
     #   typer

{superset_showtime-0.3.3 → superset_showtime-0.4.2}/showtime/__init__.py

@@ -4,12 +4,13 @@
 Circus tent emoji state tracking for Apache Superset ephemeral environments.
 """
 
-__version__ = "0.3.3"
+__version__ = "0.4.2"
 __author__ = "Maxime Beauchemin"
 __email__ = "maximebeauchemin@gmail.com"
 
-from .core.circus import PullRequest, Show
 from .core.github import GitHubInterface
+from .core.pull_request import PullRequest
+from .core.show import Show
 
 __all__ = [
     "__version__",