superset-showtime 0.6.4__tar.gz → 0.6.7__tar.gz

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/.claude/settings.local.json

@@ -46,7 +46,15 @@
       "Bash(showtime list:*)",
       "Bash(showtime git-check)",
       "Read(//^def aws_cleanup/,/**)",
-      "WebFetch(domain:github.com)"
+      "WebFetch(domain:github.com)",
+      "Bash(showtime labels:*)",
+      "Read(//Users/max/**)",
+      "Bash(showtime cleanup:*)",
+      "Bash(gh pr view:*)",
+      "Bash(for pr in 34842 35033 35152)",
+      "Bash(do echo \"PR $pr:\")",
+      "Bash(done)",
+      "Bash(cat:*)"
     ],
     "deny": [],
     "ask": [],

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superset-showtime
-Version: 0.6.4
+Version: 0.6.7
 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/

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/showtime/__init__.py

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

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/showtime/cli.py

@@ -8,9 +8,9 @@ from typing import Dict, Optional
 
 import typer
 from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.table import Table
 
-from .core.emojis import STATUS_DISPLAY
 from .core.github import GitHubError, GitHubInterface
 from .core.github_messages import (
     get_aws_console_urls,
@@ -73,10 +73,10 @@ def _get_github_workflow_url() -> str:
 
 
 def _get_github_actor() -> str:
-    """Get current GitHub actor with fallback"""
-    import os
+    """Get current GitHub actor with fallback (DEPRECATED: Use GitHubInterface.get_current_actor())"""
+    from .core.github import GitHubInterface
 
-    return os.getenv("GITHUB_ACTOR", DEFAULT_GITHUB_ACTOR)
+    return GitHubInterface.get_current_actor()
 
 
 def _get_showtime_footer() -> str:
@@ -96,7 +96,7 @@ def version() -> None:
 def start(
     pr_number: int = typer.Argument(..., help="PR number to create environment for"),
     sha: Optional[str] = typer.Option(None, "--sha", help="Specific commit SHA (default: latest)"),
-    ttl: Optional[str] = typer.Option("24h", help="Time to live (24h, 48h, 1w, close)"),
+    ttl: Optional[str] = typer.Option("48h", help="Time to live (24h, 48h, 1w, close)"),
     size: Optional[str] = typer.Option("standard", help="Environment size (standard, large)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be done"),
     dry_run_aws: bool = typer.Option(
@@ -173,7 +173,15 @@ def status(
 ) -> None:
     """Show environment status for PR"""
     try:
-        pr = PullRequest.from_id(pr_number)
+        # Show spinner while fetching PR status
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=Console(),
+            transient=True,
+        ) as progress:
+            progress.add_task(description=f"🎪 Fetching status for PR #{pr_number}...", total=None)
+            pr = PullRequest.from_id(pr_number)
 
         # Use PullRequest method for data
         status_data = pr.get_status()
@@ -184,20 +192,22 @@ def status(
 
         show_data = status_data["show"]
 
-        # Create status table
-        table = Table(title=f"🎪 Environment Status - PR #{pr_number}")
+        # Create status table with clickable PR link
+        pr_url = f"https://github.com/apache/superset/pull/{pr_number}"
+        table = Table(title=f"🎪 Environment Status - [link={pr_url}]PR #{pr_number}[/link]")
         table.add_column("Property", style="cyan")
         table.add_column("Value", style="white")
 
-        status_emoji = STATUS_DISPLAY
-        table.add_row(
-            "Status", f"{status_emoji.get(show_data['status'], '❓')} {show_data['status'].title()}"
-        )
+        from .core.emojis import STATUS_DISPLAY
+
+        status_display = STATUS_DISPLAY.get(show_data["status"], "❓")
+        table.add_row("Status", f"{status_display} {show_data['status'].title()}")
         table.add_row("Environment", f"`{show_data['sha']}`")
-        table.add_row("AWS Service", f"`{show_data['aws_service_name']}`")
+        table.add_row("Service Name", f"`{show_data['aws_service_name']}`")
 
         if show_data["ip"]:
-            table.add_row("URL", f"http://{show_data['ip']}:8080")
+            superset_url = f"http://{show_data['ip']}:8080"
+            table.add_row("Superset URL", f"[link={superset_url}]{superset_url}[/link]")
         if show_data["created_at"]:
             table.add_row("Created", show_data["created_at"])
 
@@ -206,6 +216,13 @@ def status(
         if show_data["requested_by"]:
             table.add_row("Requested by", f"@{show_data['requested_by']}")
 
+        # Add AWS Console URLs - clickable
+        from .core.github_messages import get_aws_console_urls
+
+        aws_urls = get_aws_console_urls(show_data["aws_service_name"])
+        table.add_row("AWS Logs", f"[link={aws_urls['logs']}]View Logs ↗[/link]")
+        table.add_row("AWS Service", f"[link={aws_urls['service']}]View Service ↗[/link]")
+
         # Show active triggers
         trigger_labels = [label for label in pr.labels if "showtime-trigger-" in label]
         if trigger_labels:
@@ -290,8 +307,16 @@ def list(
 ) -> None:
     """List all environments"""
     try:
-        # Use PullRequest method for data collection
-        all_environments = PullRequest.list_all_environments()
+        # Show spinner while fetching environments
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=Console(),
+            transient=True,
+        ) as progress:
+            progress.add_task(description="🎪 Fetching environments...", total=None)
+            # Use PullRequest method for data collection
+            all_environments = PullRequest.list_all_environments()
 
         if not all_environments:
             p("🎪 No environments currently running")
@@ -319,19 +344,19 @@ def list(
         # Create table with full terminal width
         table = Table(title="🎪 Environment List", expand=True)
         table.add_column("PR", style="cyan", min_width=6)
-        table.add_column("Type", style="white", min_width=8)
-        table.add_column("Status", style="white", min_width=12)
+        table.add_column("Service Name", style="white", min_width=20)
+        table.add_column("", style="white", min_width=2)  # Emoji type column
+        table.add_column("🟢", style="white", min_width=2)
         table.add_column("SHA", style="green", min_width=11)
-        table.add_column("Created", style="dim white", min_width=12)
+        table.add_column("Age", style="dim white", min_width=12)
         table.add_column("Superset URL", style="blue", min_width=25)
-        table.add_column("AWS Logs", style="dim blue", min_width=15)
+        table.add_column("Logs", style="dim blue", min_width=10)
         table.add_column("TTL", style="yellow", min_width=6)
         table.add_column("User", style="magenta", min_width=10)
 
-        status_emoji = STATUS_DISPLAY
-
-        # Sort by PR number, then by show type (active first, then building, then orphaned)
-        type_priority = {"active": 1, "building": 2, "orphaned": 3}
+        # Sort by PR number, then by show type (active first, then building, then orphaned, legacy last)
+        # TODO: Remove after legacy cleanup - legacy type priority
+        type_priority = {"active": 1, "building": 2, "orphaned": 3, "legacy": 4}
         sorted_envs = sorted(
             filtered_envs,
             key=lambda e: (
@@ -344,14 +369,16 @@ def list(
             show_data = env["show"]
             pr_number = env["pr_number"]
 
-            # Show type with appropriate styling (using single-width chars for alignment)
+            # Show type with emoji indicators
             show_type = show_data.get("show_type", "orphaned")
             if show_type == "active":
-                type_display = "* active"
+                type_display = "🎯"  # Active environment (has pointer)
             elif show_type == "building":
-                type_display = "# building"
+                type_display = "🔨"  # Building environment (hammer is single-width)
+            elif show_type == "legacy":  # TODO: Remove after legacy cleanup
+                type_display = "⚠️"  # Legacy environment (no SHA in service name)
             else:
-                type_display = "! orphaned"
+                type_display = "👻"  # Orphaned environment (no pointer)
 
             # Make Superset URL clickable and show full URL
             if show_data["ip"]:
@@ -370,26 +397,32 @@ def list(
             pr_url = f"https://github.com/apache/superset/pull/{pr_number}"
             clickable_pr = f"[link={pr_url}]{pr_number}[/link]"
 
-            # Format creation time for display
-            created_display = show_data.get("created_at", "-")
-            if created_display and created_display != "-":
-                # Convert 2025-08-25T05-18 to more readable format
-                try:
-                    parts = created_display.replace("T", " ").replace("-", ":")
-                    created_display = parts[-8:]  # Show just HH:MM:SS
-                except Exception:
-                    pass  # Keep original if parsing fails
+            # Get age display from show
+            age_display = show_data.get("age", "-")
+
+            # Simple status display - just emoji
+            status_display = "🟢" if show_data["status"] == "running" else "❌"
+
+            # TODO: Remove after legacy cleanup - handle missing legacy fields
+            sha_display = show_data["sha"] if show_data["sha"] != "-" else "-"
+            ttl_display = show_data["ttl"] if show_data["ttl"] else "-"
+            user_display = (
+                f"@{show_data['requested_by']}"
+                if show_data["requested_by"] and show_data["requested_by"] != "-"
+                else "-"
+            )
 
             table.add_row(
                 clickable_pr,
+                f"{show_data['aws_service_name']}-service",
                 type_display,
-                f"{status_emoji.get(show_data['status'], '❓')} {show_data['status']}",
-                show_data["sha"],
-                created_display,
+                status_display,
+                sha_display,
+                age_display,
                 superset_url,
                 aws_logs_link,
-                show_data["ttl"],
-                f"@{show_data['requested_by']}" if show_data["requested_by"] else "-",
+                ttl_display,
+                user_display,
             )
 
         p(table)
@@ -537,11 +570,8 @@ def sync(
 
         if check_only:
             # Analysis mode - just return what's needed
-            analysis_result = pr.analyze(target_sha, pr_state)
-            p(f"build_needed={str(analysis_result.build_needed).lower()}")
-            p(f"sync_needed={str(analysis_result.sync_needed).lower()}")
-            p(f"pr_number={pr_number}")
-            p(f"target_sha={target_sha}")
+            sync_state = pr.analyze(target_sha, pr_state)
+            p(sync_state.to_gha_stdout(pr_number))
             return
 
         # Execution mode - do the sync
@@ -679,13 +709,23 @@ def cleanup(
             return
 
         cleaned_count = 0
+        orphan_cleaned_count = 0
+
         for pr_number in pr_numbers:
             pr = PullRequest.from_id(pr_number)
+
+            # Clean expired environments with pointers
             if pr.stop_if_expired(max_age_hours, dry_run):
                 cleaned_count += 1
 
-        if cleaned_count > 0:
-            p(f"🎪 ✅ Cleaned up {cleaned_count} expired environments")
+            # Clean orphaned environments without pointers
+            orphan_cleaned_count += pr.cleanup_orphaned_shows(max_age_hours, dry_run)
+
+        if cleaned_count > 0 or orphan_cleaned_count > 0:
+            if cleaned_count > 0:
+                p(f"🎪 ✅ Cleaned up {cleaned_count} expired environments")
+            if orphan_cleaned_count > 0:
+                p(f"🎪 ✅ Cleaned up {orphan_cleaned_count} orphaned environments")
         else:
             p("🎪 No expired environments found")
 
@@ -718,20 +758,33 @@ def cleanup(
                     if len(aws_orphans) > 3:
                         p(f"  ... and {len(aws_orphans) - 3} more")
 
-                    if not force and not dry_run:
-                        if typer.confirm(f"Delete {len(aws_orphans)} orphaned AWS resources?"):
-                            # Clean up AWS orphans
-                            for orphan in aws_orphans:
-                                if not dry_run:
-                                    aws.delete_service(orphan["service_name"])
-                                aws_cleaned_count += 1
-                        else:
-                            p("❌ Skipping AWS orphan cleanup")
-                    elif force or dry_run:
+                    # Determine if we should proceed with cleanup
+                    should_cleanup = False
+                    if dry_run:
+                        should_cleanup = True
                         aws_cleaned_count = len(aws_orphans)
-                        if not dry_run:
-                            for orphan in aws_orphans:
-                                aws.delete_service(orphan["service_name"])
+                    elif force:
+                        should_cleanup = True
+                    elif typer.confirm(f"Delete {len(aws_orphans)} orphaned AWS resources?"):
+                        should_cleanup = True
+                    else:
+                        p("❌ Skipping AWS orphan cleanup")
+
+                    # Perform cleanup if approved
+                    if should_cleanup and not dry_run:
+                        from .core.service_name import ServiceName
+
+                        for orphan in aws_orphans:
+                            service_name_str = orphan["service_name"]
+                            try:
+                                # Parse service name to get PR number
+                                svc = ServiceName.from_service_name(service_name_str)
+                                # Pass base name (without -service) to delete_environment
+                                aws.delete_environment(svc.base_name, svc.pr_number)
+                                aws_cleaned_count += 1
+                            except ValueError as e:
+                                p(f"⚠️ Skipping invalid service name {service_name_str}: {e}")
+                                continue
 
                 if aws_cleaned_count > 0:
                     p(f"☁️ ✅ Cleaned up {aws_cleaned_count} orphaned AWS resources")

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/showtime/core/aws.py

@@ -74,16 +74,16 @@ class AWSInterface:
         4. Deploy and wait for stability
         5. Health check and return IP
         """
-        from datetime import datetime
 
+        # Create Show object for consistent AWS naming
+        from .date_utils import format_utc_now
         from .show import Show
 
-        # Create Show object for consistent AWS naming
         show = Show(
             pr_number=pr_number,
             sha=sha[:7],  # Truncate to 7 chars like GitHub
             status="building",
-            created_at=datetime.utcnow().strftime("%Y-%m-%dT%H-%M"),
+            created_at=format_utc_now(),
             requested_by=github_user,
         )
 
@@ -173,67 +173,46 @@ class AWSInterface:
         except Exception as e:
             return EnvironmentResult(success=False, error=str(e))
 
-    def delete_environment(self, service_name: str, pr_number: int) -> bool:
+    def delete_environment(self, base_name: str, pr_number: int) -> bool:
         """
-        Delete ephemeral environment with proper verification
+        Delete ephemeral environment
 
-        Steps:
-        1. Check if ECS service exists 
-        2. Delete ECS service with force and wait for completion
-        3. Delete ECR image tag
-        4. Verify deletion completed
+        Args:
+            base_name: Base service name WITHOUT -service suffix (e.g., "pr-34868-abc123f")
+            pr_number: PR number for this environment
         """
         try:
-            ecs_service_name = f"{service_name}-service" if not service_name.endswith("-service") else service_name
+            # Simple: always add -service suffix
+            ecs_service_name = f"{base_name}-service"
             print(f"🗑️ Deleting ECS service: {ecs_service_name}")
-            
-            # Step 1: Check if service exists
-            if not self._service_exists(ecs_service_name):
-                print(f"✅ Service {ecs_service_name} already deleted")
-                return True
-
-            # Step 2: Delete ECS service (force delete) and wait
-            print(f"☁️ Initiating ECS service deletion...")
-            delete_response = self.ecs_client.delete_service(
-                cluster=self.cluster, 
-                service=ecs_service_name, 
-                force=True
-            )
-            print(f"🔄 Delete initiated: {delete_response.get('service', {}).get('status', 'unknown')}")
-
-            # Step 3: Wait for deletion to complete (crucial!)
-            print(f"⏳ Waiting for service deletion to complete...")
-            deletion_success = self._wait_for_service_deletion(ecs_service_name, timeout_minutes=10)
-            
-            if not deletion_success:
-                print(f"⚠️ Service deletion timeout - service may still exist")
-                return False
 
-            # Step 4: Delete ECR image tag
-            print(f"🐳 Cleaning up Docker image...")
-            # Fix SHA extraction: pr-34831-ac533ec-service → ac533ec
-            # Remove "pr-" prefix and "-service" suffix, then get SHA (last part)
-            base_name = service_name.replace("pr-", "").replace("-service", "")
-            parts = base_name.split("-")
-            sha = parts[-1] if len(parts) > 1 else base_name  # Last part is SHA
-            image_tag = f"pr-{pr_number}-{sha}-ci"
+            # Delete ECS service with force flag (AWS will handle cleanup)
+            try:
+                self.ecs_client.delete_service(
+                    cluster=self.cluster, service=ecs_service_name, force=True
+                )
+                print(f"✅ ECS service deletion initiated: {ecs_service_name}")
+            except self.ecs_client.exceptions.ServiceNotFoundException:
+                print(f"ℹ️ Service {ecs_service_name} already deleted")
+            except Exception as e:
+                print(f"❌ AWS deletion failed: {e}")
+                return False
 
+            # Try to clean up ECR image - for showtime services, tag is base_name + "-ci"
             try:
+                image_tag = f"{base_name}-ci"
                 self.ecr_client.batch_delete_image(
                     repositoryName=self.repository, imageIds=[{"imageTag": image_tag}]
                 )
                 print(f"✅ Deleted ECR image: {image_tag}")
-            except self.ecr_client.exceptions.ImageNotFoundException:
-                print(f"ℹ️ ECR image {image_tag} already deleted")
+            except Exception:
+                pass  # Image cleanup is optional
 
-            print(f"✅ Environment {service_name} fully deleted")
             return True
 
         except Exception as e:
-            print(f"❌ AWS deletion failed: {e}")
-            raise AWSError(
-                message=str(e), operation="delete_environment", resource=service_name
-            ) from e
+            print(f"❌ Unexpected error: {e}")
+            return False
 
     def get_environment_ip(self, service_name: str) -> Optional[str]:
         """
@@ -701,19 +680,19 @@ class AWSInterface:
         try:
             # List all services in cluster
             response = self.ecs_client.list_services(cluster=self.cluster)
-            
+
             if not response.get("serviceArns"):
                 return []
-            
+
             # Extract service names and filter for showtime pattern
             showtime_services = []
             for service_arn in response["serviceArns"]:
                 service_name = service_arn.split("/")[-1]  # Extract name from ARN
                 if service_name.startswith("pr-") and "-service" in service_name:
                     showtime_services.append(service_name)
-            
+
             return sorted(showtime_services)
-            
+
         except Exception as e:
             print(f"❌ Failed to find showtime services: {e}")
             return []
@@ -845,10 +824,15 @@ class AWSInterface:
             for attempt in range(max_attempts):
                 # Check if service still exists
                 if not self._service_exists(service_name):
-                    print(f"✅ Service {service_name} fully deleted after {attempt * 5}s")
+                    if attempt == 0:
+                        print(
+                            f"✅ Service {service_name} deletion confirmed (was already draining)"
+                        )
+                    else:
+                        print(f"✅ Service {service_name} fully deleted after {attempt * 5}s")
                     return True
 
-                if attempt % 6 == 0:  # Every 30s
+                if attempt % 6 == 0 and attempt > 0:  # Every 30s after first check
                     print(f"⏳ Waiting for service deletion... ({attempt * 5}s elapsed)")
 
                 time.sleep(5)  # Check every 5 seconds

superset_showtime-0.6.7/showtime/core/constants.py

@@ -0,0 +1,10 @@
+"""Constants used throughout the showtime codebase."""
+
+# Default time-to-live for new environments
+DEFAULT_TTL = "48h"
+
+# TTL options for environments
+TTL_OPTIONS = ["24h", "48h", "72h", "1w", "close"]
+
+# Maximum age for considering environments stale/orphaned
+DEFAULT_CLEANUP_AGE = "48h"

superset_showtime-0.6.7/showtime/core/date_utils.py

@@ -0,0 +1,80 @@
+"""Date and time utilities for consistent timestamp handling."""
+
+from datetime import datetime
+from typing import Optional
+
+# Custom timestamp format used in circus labels
+# Format: YYYY-MM-DDTHH-MM (using dashes instead of colons for GitHub label compatibility)
+CIRCUS_TIME_FORMAT = "%Y-%m-%dT%H-%M"
+
+
+def format_utc_now() -> str:
+    """Get current UTC time formatted for circus labels."""
+    return datetime.utcnow().strftime(CIRCUS_TIME_FORMAT)
+
+
+def parse_circus_time(timestamp: str) -> Optional[datetime]:
+    """Parse a circus timestamp string into a datetime object.
+
+    Args:
+        timestamp: String in format "YYYY-MM-DDTHH-MM"
+
+    Returns:
+        datetime object or None if parsing fails
+    """
+    if not timestamp:
+        return None
+
+    try:
+        return datetime.strptime(timestamp, CIRCUS_TIME_FORMAT)
+    except (ValueError, AttributeError):
+        return None
+
+
+def age_display(created_at: str) -> str:
+    """Convert a circus timestamp to human-readable age.
+
+    Args:
+        created_at: Timestamp string in circus format
+
+    Returns:
+        Human-readable age like "2d 5h" or "45m"
+    """
+    created_dt = parse_circus_time(created_at)
+    if not created_dt:
+        return "-"
+
+    # Compare UTC to UTC for accurate age
+    age = datetime.utcnow() - created_dt
+
+    # Format age nicely
+    days = age.days
+    hours = age.seconds // 3600
+    minutes = (age.seconds % 3600) // 60
+
+    if days > 0:
+        return f"{days}d {hours}h"
+    elif hours > 0:
+        return f"{hours}h {minutes}m"
+    else:
+        return f"{minutes}m"
+
+
+def is_expired(created_at: str, max_age_hours: int) -> bool:
+    """Check if a timestamp is older than the specified hours.
+
+    Args:
+        created_at: Timestamp string in circus format
+        max_age_hours: Maximum age in hours
+
+    Returns:
+        True if timestamp is older than max_age_hours
+    """
+    created_dt = parse_circus_time(created_at)
+    if not created_dt:
+        return False
+
+    from datetime import timedelta
+
+    expiry_time = created_dt + timedelta(hours=max_age_hours)
+    return datetime.utcnow() > expiry_time

{superset_showtime-0.6.4 → superset_showtime-0.6.7}/showtime/core/git_validation.py

@@ -5,14 +5,17 @@ Validates that the current Git repository contains required commit SHA to preven
 usage with outdated releases.
 """
 
-from typing import Optional, Tuple
+from typing import TYPE_CHECKING, Optional, Tuple
 
-try:
+if TYPE_CHECKING:
     from git import InvalidGitRepositoryError, Repo
-except ImportError:
-    # Fallback if GitPython is not available
-    Repo = None
-    InvalidGitRepositoryError = Exception
+else:
+    try:
+        from git import InvalidGitRepositoryError, Repo
+    except ImportError:
+        # Fallback if GitPython is not available
+        Repo = None
+        InvalidGitRepositoryError = Exception
 
 
 # Hard-coded required SHA - update this when needed
@@ -36,7 +39,9 @@ def is_git_repository(path: str = ".") -> bool:
     Returns:
         True if it's a Git repository, False otherwise
     """
-    if Repo is None:
+    try:
+        from git import InvalidGitRepositoryError, Repo
+    except ImportError:
         # GitPython not available, assume not a git repo
         return False
 
@@ -69,9 +74,12 @@ def validate_required_sha(required_sha: Optional[str] = None) -> Tuple[bool, Opt
         return _validate_sha_via_github_api(sha_to_check)
     except Exception as e:
         print(f"⚠️ GitHub API validation failed: {e}")
+        # Fall through to Git validation
 
     # Fallback to Git validation for non-GitHub origins
-    if Repo is None:
+    try:
+        from git import Repo
+    except ImportError:
         print("⚠️ GitPython not available, skipping SHA validation")
         return True, None
 
@@ -84,9 +92,6 @@ def validate_required_sha(required_sha: Optional[str] = None) -> Tuple[bool, Opt
             print(f"⚠️ Git validation failed: {error}")
             return True, None  # Allow operation to continue
 
-    except InvalidGitRepositoryError:
-        print("⚠️ Not a Git repository, skipping SHA validation")
-        return True, None
     except Exception as e:
         print(f"⚠️ Git validation error: {e}")
         return True, None
@@ -181,13 +186,17 @@ def get_validation_error_message(required_sha: Optional[str] = None) -> str:
 
 This branch requires commit {sha_to_check} to be present in your Git history.
 
+[bold yellow]Why this commit is required:[/bold yellow]
+Showtime depends on Docker build infrastructure (LOAD_EXAMPLES_DUCKDB) and DuckDB
+examples support that was introduced in this commit. Without it, Docker builds will fail.
+
 [bold yellow]To resolve this:[/bold yellow]
 1. Ensure you're on the correct branch (usually main)
 2. Pull the latest changes: [cyan]git pull origin main[/cyan]
 3. Verify the commit exists: [cyan]git log --oneline | grep {sha_to_check[:7]}[/cyan]
 4. If needed, switch to main branch: [cyan]git checkout main[/cyan]
 
-[dim]This check prevents Showtime from running on outdated releases.[/dim]
+[dim]This prevents Docker build failures on PRs missing required infrastructure.[/dim]
 """.strip()