ADR-039: Distribution and Packaging Strategy

Status

Proposed

Context

SEA-Forge™ is a distributed system with multiple components (CLI tools, backend services, generators, DSL compilers). Users currently need to manually install numerous dependencies (Node.js, Rust, Python, Docker, mise, devbox, just, sops, age) before they can start developing.

This friction:

• Increases time-to-first-value for new developers
• Creates inconsistencies between development environments
• Makes onboarding error-prone

Constraints:

• SEA-Forge™ is NOT a desktop application—it’s a development toolkit
• Backend services require Docker (Oxigraph, NATS, PostgreSQL)
• Existing just recipes already orchestrate common workflows
• The project uses Rust, TypeScript, and Python

Decision

Adopt a multi-layer distribution strategy:

1. DevContainer (Primary): Zero-config development via .devcontainer/
2. Rust CLI (sea-forge): Orchestration binary wrapping just recipes
3. Package Managers: Homebrew and Cargo for CLI distribution

Layer 1: DevContainer

1
Developer → Opens in VS Code/Codespaces → Everything works

• Contains all dependencies pre-installed
• postCreateCommand runs just setup
• Works in GitHub Codespaces, VS Code, JetBrains Fleet

Layer 2: Rust CLI (sea-forge)

1
2
3
4
sea-forge doctor    # Check system prerequisites
sea-forge init      # Bootstrap project
sea-forge up        # Start all services
sea-forge validate  # Run spec-guard

• Single binary (~5-10MB)
• Embeds recipe logic for portability (no just dependency at runtime)
• Provides better error messages and progress indicators
• Published to Cargo (primary), then Homebrew

IDE Support

| IDE | Setup Method | Status | |—–|————–|——–| | Zed IDE | just ui-setup / sea-forge setup | ✅ Primary | | VS Code | DevContainer | ✅ Alternative | | Codespaces | DevContainer | ✅ Alternative | | Other | just setup / sea-forge init | ✅ Supported |

Layer 3: Package Managers

1
2
3
cargo install sea-forge
# or
brew install sprime01/tap/sea-forge

Constraints

• MUST embed recipe logic for portability (no runtime just dependency)
• MUST support Linux, macOS, and WSL2
• MUST preserve Docker-based service architecture
• MUST NOT require Tauri/GUI frameworks

Consequences

Positive

• One-command installation via Cargo/Homebrew
• Zero-config development via DevContainer
• Consistent environments across team
• Better onboarding experience

Negative

• Maintenance of three distribution channels
• Rust CLI adds build complexity
• DevContainer requires Docker

Risks

• CLI/just recipe drift → Mitigation: CLI calls just directly, no duplication
• DevContainer build time → Mitigation: Use devcontainer features, not custom Dockerfile

Alternatives Considered

Related

• ADR-026: Cognitive Supply Chain (developer experience principles)
• SDS-048: Platform UI Integration (LibreChat/Zed setup)
• PRD-019: Developer Experience Requirements