superset-showtime 0.1.0__tar.gz

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

@@ -0,0 +1,24 @@
+{
+  "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:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

superset_showtime-0.1.0/.github/workflows/showtime-cleanup.yml

@@ -0,0 +1,40 @@
+name: 🎪 Showtime Cleanup
+
+# Scheduled cleanup of expired environments
+on:
+  schedule:
+    - cron: '0 */6 * * *'  # Every 6 hours
+
+  # Manual trigger for testing
+  workflow_dispatch:
+    inputs:
+      max_age_hours:
+        description: 'Maximum age in hours before cleanup'
+        required: false
+        default: '48'
+
+jobs:
+  cleanup-expired:
+    name: Clean up expired showtime environments
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Install Superset Showtime
+        run: |
+          pip install superset-showtime
+
+      - name: Cleanup expired environments
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ vars.AWS_REGION || 'us-west-2' }}
+          GITHUB_ORG: ${{ github.repository_owner }}
+          GITHUB_REPO: ${{ github.event.repository.name }}
+        run: |
+          MAX_AGE="${{ github.event.inputs.max_age_hours || '48' }}"
+          python -m showtime cleanup --older-than "${MAX_AGE}h"

superset_showtime-0.1.0/.github/workflows/showtime.yml

@@ -0,0 +1,185 @@
+name: 🎪 Superset Showtime Environment Manager
+
+# Trigger on circus tent labels
+on:
+  pull_request_target:
+    types: [labeled, unlabeled, synchronize, closed]
+
+jobs:
+  # Job 1: Check for showtime triggers and extract SHA
+  evaluate-triggers:
+    name: Evaluate showtime triggers
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    outputs:
+      should-build: ${{ steps.eval-triggers.outputs.should-build }}
+      should-cleanup: ${{ steps.eval-triggers.outputs.should-cleanup }}
+      sha: ${{ steps.get-sha.outputs.sha }}
+    env:
+      DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+    steps:
+      - name: Check for showtime trigger labels
+        id: eval-triggers
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request_target" && "${{ contains(github.event.label.name, '🎪 trigger-start') }}" == "true" ]]; then
+            echo "should-build=true" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event_name }}" == "synchronize" ]]; then
+            echo "should-build=true" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event.action }}" == "closed" ]]; then
+            echo "should-build=false" >> $GITHUB_OUTPUT
+            echo "should-cleanup=true" >> $GITHUB_OUTPUT
+          else
+            echo "should-build=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Get PR SHA
+        id: get-sha
+        if: steps.eval-triggers.outputs.should-build == 'true'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prSha = context.payload.pull_request.head.sha;
+            console.log(`PR SHA: ${prSha}`);
+            core.setOutput("sha", prSha);
+
+  # Job 2: Build Docker image (from original ephemeral-env.yml)
+  docker-build:
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}-build
+      cancel-in-progress: true
+    needs: evaluate-triggers
+    if: needs.evaluate-triggers.outputs.should-build == 'true'
+    name: Build ephemeral environment image
+    runs-on: ubuntu-24.04
+    env:
+      DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ needs.evaluate-triggers.outputs.sha }} )"
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.evaluate-triggers.outputs.sha }}
+          persist-credentials: false
+
+      - name: Setup Docker Environment
+        uses: ./.github/actions/setup-docker
+        with:
+          dockerhub-user: ${{ secrets.DOCKERHUB_USER }}
+          dockerhub-token: ${{ secrets.DOCKERHUB_TOKEN }}
+          build: "true"
+          install-docker-compose: "false"
+
+      - name: Setup supersetbot
+        uses: ./.github/actions/setup-supersetbot/
+
+      - name: Build ephemeral env image
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          supersetbot docker \
+            --push \
+            --load \
+            --preset ci \
+            --platform linux/amd64 \
+            --context-ref "${{ needs.evaluate-triggers.outputs.sha }}" \
+            --extra-flags "--build-arg INCLUDE_CHROMIUM=false"
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-west-2
+
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Tag and push image to ECR
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          ECR_REPOSITORY: superset-ci
+          IMAGE_TAG: apache/superset:${{ needs.evaluate-triggers.outputs.sha }}-ci
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          docker tag $IMAGE_TAG $ECR_REGISTRY/$ECR_REPOSITORY:pr-$PR_NUMBER-ci
+          docker push -a $ECR_REGISTRY/$ECR_REPOSITORY
+
+  # Job 3: Handle showtime operations (our new logic)
+  showtime-handler:
+    needs: [evaluate-triggers, docker-build]
+    if: needs.evaluate-triggers.outputs.should-build == 'true'
+
+    concurrency:
+      group: showtime-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: true
+
+    name: Process showtime operations
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Install Superset Showtime
+        run: |
+          pip install superset-showtime
+
+      - name: Process circus triggers
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: us-west-2
+          GITHUB_ORG: ${{ github.repository_owner }}
+          GITHUB_REPO: ${{ github.event.repository.name }}
+          GITHUB_ACTOR: ${{ github.actor }}
+        run: |
+          python -m showtime handle-trigger ${{ github.event.pull_request.number }}
+
+      - name: Handle synchronize events (new commits)
+        if: github.event_name == 'synchronize'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: us-west-2
+          GITHUB_ORG: ${{ github.repository_owner }}
+          GITHUB_REPO: ${{ github.event.repository.name }}
+          GITHUB_ACTOR: ${{ github.actor }}
+        run: |
+          python -m showtime handle-sync ${{ github.event.pull_request.number }}
+
+  # Job 4: Immediate cleanup when PR is closed/merged
+  pr-cleanup:
+    needs: evaluate-triggers
+    if: needs.evaluate-triggers.outputs.should-cleanup == 'true'
+    name: Clean up closed PR environment
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Install Superset Showtime
+        run: |
+          pip install superset-showtime
+
+      - name: Clean up closed PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: us-west-2
+          GITHUB_ORG: ${{ github.repository_owner }}
+          GITHUB_REPO: ${{ github.event.repository.name }}
+          GITHUB_ACTOR: ${{ github.actor }}
+        run: |
+          python -m showtime stop ${{ github.event.pull_request.number }} --force

superset_showtime-0.1.0/.gitignore

@@ -0,0 +1,149 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Showtime specific
+.showtime/
+config.yml

superset_showtime-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

superset_showtime-0.1.0/CLAUDE.md

@@ -0,0 +1,185 @@
+# 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 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.
+
+## Development Commands
+
+### Essential Commands
+```bash
+# Development setup
+uv pip install -e ".[dev]"     # Install with dev dependencies
+make pre-commit                 # Setup pre-commit hooks
+make test                       # Run tests
+make lint                       # Run ruff + mypy
+
+# Testing circus tent functionality
+python -m showtime --help               # Shows complete workflow tutorial
+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
+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
+```
+
+### Testing Single Components
+```bash
+pytest tests/unit/test_circus.py                    # Test label parsing
+pytest tests/unit/test_circus.py::test_show_properties -v   # Single test
+python -c "from showtime.core.circus import Show; show = Show(pr_number=1234, sha='abc123f', status='running'); print(show.to_circus_labels())"   # Quick circus label test
+```
+
+## 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
+- **No external database** - All state reconstructed from GitHub labels
+
+### Key Classes and Responsibilities
+
+#### `Show` (showtime/core/circus.py:16)
+Represents a single ephemeral environment with per-SHA state:
+- **Properties**: `aws_service_name`, `aws_image_tag` for deterministic AWS naming
+- **Methods**: `to_circus_labels()` creates per-SHA format labels
+- **Parsing**: `from_circus_labels()` reconstructs from GitHub labels
+
+#### `PullRequest` (showtime/core/circus.py:121)
+Container parsing all shows from a PR's labels:
+- **Properties**: `current_show`, `building_show`, `circus_labels`
+- **State reconstruction**: Parses all environments from labels
+- **Factory method**: `from_id()` loads real GitHub data
+
+#### `GitHubInterface` (showtime/core/github.py:23)
+GitHub API operations with emoji label support:
+- **Authentication**: Auto-detects `GITHUB_TOKEN` or `gh auth token`
+- **Label operations**: Handles emoji encoding for GitHub API
+- **Discovery**: `find_prs_with_shows()` searches for circus tent labels
+
+#### `AWSInterface` (showtime/core/aws.py:35)
+Replicates current GitHub Actions AWS logic:
+- **Naming**: Uses same deterministic patterns as current GHA
+- **Operations**: `create_environment()`, `delete_environment()` mirror existing workflows
+- **Network config**: Same subnets/security groups as production
+
+### Label Format Design
+
+#### Per-SHA State Labels
+```bash
+🎪 🚦 {sha} {status}        # 🎪 🚦 abc123f running
+🎪 🌐 {sha} {ip-dashes}     # 🎪 🌐 abc123f 52-1-2-3
+🎪 📅 {sha} {timestamp}     # 🎪 📅 abc123f 2024-01-15T14-30
+🎪 ⌛ {sha} {ttl}           # 🎪 ⌛ abc123f 24h
+🎪 🤡 {sha} {username}      # 🎪 🤡 abc123f maxime
+🎪 ⚙️ {sha} {config}        # 🎪 ⚙️ abc123f alerts,debug
+```
+
+#### Pointer Labels (No Value)
+```bash
+🎪 🎯 {sha}                 # Active environment pointer
+🎪 🏗️ {sha}                 # Building environment pointer
+```
+
+### GitHub Actions Integration
+
+#### Current Integration Points
+- **`.github/workflows/circus.yml`** - Main workflow replacing `ephemeral-env.yml`
+- **`.github/workflows/circus-cleanup.yml`** - Scheduled cleanup replacing manual processes
+- **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 cleanup --older-than 48h` - Scheduled cleanup
+
+## Important Implementation Details
+
+### Authentication Pattern
+```python
+# Priority order for credentials:
+github = GitHubInterface()  # Auto-detects GITHUB_TOKEN or gh CLI
+# No config files - environment variables only
+```
+
+### Dry-Run Testing Strategy
+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
+--aws-sleep N        # Sleep N seconds to simulate AWS timing
+```
+
+### AWS Resource Naming
+Must maintain compatibility with existing Superset infrastructure:
+- **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
+
+### State Recovery Pattern
+Since the CLI is stateless, it always reconstructs state from GitHub labels:
+```python
+pr = PullRequest.from_id(pr_number, github)  # Reads all labels
+show = pr.current_show                       # Finds active environment
+# All state comes from parsing circus tent emoji labels
+```
+
+## Critical Development Notes
+
+### Label Operations Must Be Atomic
+GitHub label operations are the "database transactions" - handle carefully:
+```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)
+```
+
+### Per-SHA Format Required
+All new state labels must include SHA for multi-environment support:
+```python
+# Correct: Per-SHA format
+f"🎪 🚦 {sha} running"      # Status per environment
+f"🎪 🌐 {sha} {ip}"         # IP per environment
+
+# Incorrect: Global format (legacy)
+"🎪 🚦 running"             # Which environment??
+```
+
+### Testing Against Real PRs
+The CLI can safely test against real Superset PRs:
+```bash
+# Test label management without AWS costs
+showtime start 34809 --dry-run-aws
+# Removes test labels when done
+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

superset_showtime-0.1.0/Makefile

@@ -0,0 +1,54 @@
+.PHONY: help install install-dev test test-cov lint format clean pre-commit
+
+help: ## Show this help message
+	@echo 'Usage: make <target>'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-15s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install package dependencies
+	uv pip install -e .
+
+install-dev: ## Install package with development dependencies
+	uv pip install -e ".[dev]"
+
+test: ## Run tests
+	pytest
+
+test-cov: ## Run tests with coverage
+	pytest --cov=showtime --cov-report=term-missing --cov-report=html
+
+lint: ## Run linting
+	ruff check .
+	mypy showtime
+
+format: ## Format code
+	ruff format .
+	ruff check --fix .
+
+clean: ## Clean up build artifacts
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	rm -rf htmlcov/
+	rm -rf .coverage
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+pre-commit: ## Install pre-commit hooks
+	pre-commit install
+
+pre-commit-run: ## Run pre-commit hooks on all files
+	pre-commit run --all-files
+
+build: ## Build package
+	uv build
+
+publish: ## Publish to PyPI (use with caution)
+	uv build
+	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']))"