Greptile Summary

This PR introduces comprehensive Docker-based local build and run capabilities to the Shuttle CLI, allowing developers to replicate the platform's build environment locally for debugging purposes. The changes add two major new experimental commands: shuttle build (with optional --docker flag) and enhanced shuttle run --docker functionality.

The implementation centers around a new shuttle-builder crate that uses Askama templates to generate Dockerfiles dynamically based on project configuration. The builder creates multi-stage Docker builds with cargo-chef for dependency caching, matching the platform's production pipeline. Key architectural changes include refactoring build argument handling through a new BuildArgsShared struct that unifies configuration between local and Docker builds, and streamlining cargo output by removing async channel communication in favor of direct stdout/stderr forwarding.

The PR also enhances user experience with cargo-style command aliases (shuttle b, shuttle r, etc.) and improved status messages that match cargo's formatting conventions. The Docker build system supports flexible configuration including custom tags, binary selection, feature flags, and asset copying through Shuttle.toml integration. All Docker-related functionality is currently hidden behind experimental flags with appropriate warnings, indicating this is an early-stage feature being gradually introduced.

Important Files Changed

Confidence score: 3/5

• This PR introduces significant new functionality that is experimental and affects core build/run workflows with potential Docker integration issues
• Score reflects the complexity of Docker build pipelines, template rendering, and the experimental nature of the features with limited testing mentioned
• Pay close attention to builder/src/lib.rs for hardcoded image names and unwrap calls, cargo-shuttle/src/lib.rs for Docker command construction, and the Dockerfile templates for proper multi-stage build configuration

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as "Shuttle CLI"
    participant Builder as "Builder Module"
    participant Docker
    participant CargoMetadata as "Cargo Metadata"
    participant FileSystem as "File System"
    participant DockerfileTemplate as "Dockerfile Template"

    User->>CLI: "shuttle build --docker"
    CLI->>CLI: "Load local config"
    CLI->>Builder: "async_cargo_metadata()"
    Builder->>CargoMetadata: "Get project metadata"
    CargoMetadata-->>Builder: "Project metadata"
    Builder->>Builder: "gather_rust_build_args()"
    Builder-->>CLI: "Build arguments"
    
    CLI->>CLI: "Create temp directory"
    CLI->>CLI: "gather_build_files()"
    CLI->>FileSystem: "Copy build files to temp dir"
    FileSystem-->>CLI: "Files copied"
    
    CLI->>DockerfileTemplate: "render_rust_dockerfile()"
    DockerfileTemplate-->>CLI: "Generated Dockerfile"
    CLI->>FileSystem: "Write Dockerfile to temp dir"
    
    CLI->>Docker: "docker buildx build --tag shuttle-build-{project}"
    Docker->>Docker: "Build image with cargo-chef and runtime setup"
    Docker-->>CLI: "Build complete"
    
    alt Run with Docker
        User->>CLI: "shuttle run --docker"
        CLI->>CLI: "local_docker_build()"
        CLI->>Docker: "docker run --network host shuttle-build-{project}"
        Docker->>Docker: "Start container with runtime"
        Docker-->>CLI: "Container running"
        CLI->>User: "Service available on port"
    end

    alt Native Build
        User->>CLI: "shuttle build"
        CLI->>Builder: "cargo_build()"
        Builder->>Builder: "Execute cargo build command"
        Builder-->>CLI: "Built executable path"
        CLI->>User: "Build complete"
    end

    alt Native Run
        User->>CLI: "shuttle run"
        CLI->>Builder: "local_build()"
        Builder->>Builder: "cargo_build()"
        Builder-->>CLI: "Built service"
        CLI->>CLI: "Start provisioner server"
        CLI->>CLI: "Spawn runtime process"
        CLI->>User: "Service running locally"
    end

_{15 files reviewed, 3 comments}

_{Edit Code Review Bot Settings | Greptile}