feat: flash build --preview in local docker for smoke-testing deployments

docs/Flash_Deploy_Guide.md

@@ -1102,26 +1102,32 @@ On mothership boot:
 
 ## Testing & Debugging
 
-### flash test-mothership
+### flash build --preview
 
-Local testing of mothership provisioning without deploying to RunPod.
+Local testing of your distributed system without deploying to RunPod.
 
 ```bash
-flash test-mothership
+flash build --preview
 ```
 
 **What it does**:
-1. Loads flash_manifest.json from current directory
-2. Creates temporary resource configs (prefixed with `tmp-`)
-3. Simulates mothership provisioning locally
-4. Displays resource creation output
-5. Auto-cleanup on exit
+1. Builds your project (creates archive, manifest)
+2. Creates a Docker network for inter-container communication
+3. Starts one Docker container per resource config:
+   - Mothership container (orchestrator)
+   - All worker containers (GPU, CPU, etc.)
+4. Exposes mothership on `localhost:8000`
+5. All containers communicate via Docker DNS
+6. Auto-cleanup on exit (Ctrl+C)
 
 **Use Cases**:
 - Validate manifest structure before deployment
 - Test resource provisioning logic
+- Debug distributed function calls
+- Test endpoint auto-discovery
+- Verify container networking
 
-**Code Reference**: `src/tetra_rp/cli/commands/test_mothership.py`
+**Code Reference**: `src/tetra_rp/cli/commands/preview.py`
 
 ### Local Docker Testing
 

scripts/verify-manifest-constants.sh

@@ -27,7 +27,8 @@ BLUE='\033[0;34m'
 NC='\033[0m'
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-EXAMPLES_DIR="/Users/deanquinanola/Github/python/flash-examples/01_getting_started/01_hello_world"
+: "${FLASH_EXAMPLES_DIR:="$REPO_ROOT/../flash-examples/01_getting_started/01_hello_world"}"
+EXAMPLES_DIR="$FLASH_EXAMPLES_DIR"
 TEST_RESULTS=()
 
 echo -e "${BLUE}============================================================${NC}"

src/tetra_rp/cli/commands/build.py

@@ -203,6 +203,11 @@ def build_command(
         "--use-local-tetra",
         help="Bundle local tetra_rp source instead of PyPI version (for development/testing)",
     ),
+    preview: bool = typer.Option(
+        False,
+        "--preview",
+        help="Launch local test environment after successful build",
+    ),
 ):
     """
     Build Flash application for deployment.
@@ -214,6 +219,7 @@ def build_command(
       flash build                              # Build with all dependencies
       flash build --no-deps                    # Skip transitive dependencies
       flash build --keep-build                 # Keep temporary build directory
+      flash build --preview                    # Build and launch local test environment
       flash build -o my-app.tar.gz             # Custom archive name
       flash build --exclude torch,torchvision  # Exclude large packages (assume in base image)
     """
@@ -226,6 +232,11 @@ def build_command(
             console.print("Run [bold]flash init[/bold] to create a Flash project")
             raise typer.Exit(1)
 
+        # Auto-enable keep_build if preview requested (preview needs build directory)
+        if preview:
+            keep_build = True
+            logger.debug("Preview mode: automatically enabling keep_build")
+
         # Create build directory first to ensure clean state before collecting files
         build_dir = create_build_directory(project_dir, app_name)
 
@@ -478,6 +489,30 @@ def build_command(
         # Success summary
         _display_build_summary(archive_path, app_name, len(files), len(requirements))
 
+        # Launch preview environment if requested
+        if preview:
+            console.print(
+                "\n[bold cyan]Launching multi-container preview...[/bold cyan]"
+            )
+            console.print("[dim]Starting all endpoints locally in Docker...[/dim]\n")
+
+            try:
+                from .preview import launch_preview
+
+                # Manifest is in .flash/flash_manifest.json
+                manifest_path = project_dir / ".flash" / "flash_manifest.json"
+
+                launch_preview(
+                    build_dir=build_dir,
+                    manifest_path=manifest_path,
+                )
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Preview stopped by user[/yellow]")
+            except Exception as e:
+                console.print(f"[red]Preview error:[/red] {e}")
+                logger.exception("Preview launch failed")
+                raise typer.Exit(1)
+
     except KeyboardInterrupt:
         console.print("\n[yellow]Build cancelled by user[/yellow]")
         raise typer.Exit(1)