# Build Dependencies

This document tracks all external dependencies used across the KubeOpenCode project's build pipeline, container images, CI workflows, and development tools.

## Container Base Images

All Dockerfiles pin base images to specific versions to avoid non-reproducible builds.

| Image | Pinned Version | Used In | Purpose |
|-------|---------------|---------|---------|
| `oven/bun` | `1.3.6-alpine` | `Dockerfile` (Stage 1) | Build OpenCode Web UI from source |
| `golang` | `1.26.2-alpine3.23` | `Dockerfile` (Stage 2) | Build kubeopencode Go binary |
| `alpine` | `3.23` | `Dockerfile` (Stage 3) | Runtime image for kubeopencode controller |
| `debian` | `bookworm-20260316-slim` | `agents/opencode/Dockerfile` | OpenCode CLI init container |
| `debian` | `bookworm-20260316-slim` | `agents/devbox/Dockerfile` | Universal development environment |
| `debian` | `bookworm-20260316-slim` | `agents/attach/Dockerfile` | Lightweight Server-mode attach Pod |
| `alpine` | `3.21` | `agents/echo/Dockerfile` | Minimal echo agent for testing |

### Updating Base Images

When updating base images:

1. **bun**: Must match the lockfile generated by the OpenCode project. Test with `bun install --frozen-lockfile` before updating. Mismatched versions cause integrity check failures (e.g., `@ibm/plex` tarball integrity failure with bun 1.3.11 vs lockfile generated by 1.3.6).
2. **golang**: Should match the Go version in `go.mod` (currently `go 1.25.0`). The image tag format is `<go-version>-alpine<alpine-version>`.
3. **debian**: Use dated tags (e.g., `bookworm-20260316-slim`) instead of `bookworm-slim`. Check [Docker Hub debian tags](https://hub.docker.com/_/debian/tags) for latest dated tags.
4. **alpine**: Pin to minor version (e.g., `3.23`). Patch updates within a minor are generally safe.

## OpenCode Versions

| Component | Version | Location | Purpose |
|-----------|---------|----------|---------|
| OpenCode CLI | `1.14.41` | `agents/opencode/Dockerfile` (`OPENCODE_VERSION` ARG) & `agents/Makefile` | AI agent binary |
| OpenCode Web UI | `v1.3.2` | `Makefile` (`OPENCODE_APP_VERSION`) | Self-hosted Web UI (built from source) |

## Go Toolchain

| Tool | Version | Location | Purpose |
|------|---------|----------|---------|
| Go | `1.25.0` | `go.mod` | Project Go version |
| Go (Dockerfile) | `1.26.2` | `Dockerfile` | Build image Go version |
| Go (devbox) | `1.25.5` | `agents/devbox/Dockerfile` (`GO_VERSION` ARG) | Agent runtime Go version |
| controller-gen | `v0.16.5` | `Makefile` | CRD and deepcopy code generation |
| golangci-lint | `v2.6.2` | `Makefile` | Go linter |
| envtest (K8s) | `1.35.0` | `Makefile` (`ENVTEST_K8S_VERSION`) | Integration test K8s API server |

## Frontend (UI)

| Dependency | Version Range | Location |
|------------|--------------|----------|
| React | `^18.2.0` | `ui/package.json` |
| React DOM | `^18.2.0` | `ui/package.json` |
| React Router DOM | `^6.22.0` | `ui/package.json` |
| TanStack React Query | `^5.17.0` | `ui/package.json` |
| TypeScript | `^5.3.3` | `ui/package.json` |
| Webpack | `^5.90.1` | `ui/package.json` |
| Tailwind CSS | `^3.4.1` | `ui/package.json` |
| Vitest | `^4.0.18` | `ui/package.json` |

The UI uses pnpm as package manager. Run `cd ui && pnpm install` to install dependencies.

## Devbox Agent — Unpinned Runtime Tools

The following tools in `agents/devbox/Dockerfile` are installed at their **latest version at build time** (not pinned). This is intentional as the devbox is a development environment where users generally want current tools:

| Tool | Install Method | Version Behavior |
|------|---------------|-----------------|
| kubectl | `curl` from dl.k8s.io/release/stable.txt | Latest stable |
| helm | `get-helm-3` install script | Latest v3 |
| yq | GitHub `latest` release | Latest |
| GitHub CLI (gh) | apt repository (`stable main`) | Latest stable |
| golangci-lint | Install script from `master` | Latest |
| Node.js | nodesource `setup_22.x` | Latest 22.x LTS |
| npm | `npm install -g npm@latest` | Latest |
| gopls | `go install gopls@latest` | Latest |
| typescript-language-server | `npm install -g` | Latest |
| python-lsp-server (pylsp) | `pip install` | Latest |
| Google Cloud CLI | apt repository | Latest |
| AWS CLI v2 | Official installer | Latest |
| Docker CLI | apt repository | Latest stable |

> **Note**: Since the devbox image is a development environment, unpinned tool versions are acceptable. The image is rebuilt periodically (weekly) and tested. If reproducibility is required, pin specific versions using build args.

## CI Workflow Dependencies

### GitHub Actions (`.github/workflows/push.yaml`)

| Action | Version | Purpose |
|--------|---------|---------|
| `actions/checkout` | `v6` | Code checkout |
| `actions/setup-go` | `v6` | Go setup (version: `1.25`) |
| `actions/setup-node` | `v6` | Node.js setup (version: `22`) |
| `dorny/paths-filter` | `v4` | Conditional builds based on changed files |
| `docker/setup-qemu-action` | `v4` | Multi-arch build support |
| `docker/setup-buildx-action` | `v4` | Docker Buildx setup |
| `docker/login-action` | `v4` | Container registry login |
| `docker/build-push-action` | `v7` | Build and push images |

> **Note**: GitHub Actions use major version tags (e.g., `@v6`) which float to the latest minor/patch within that major. This is standard practice for GitHub Actions.

