# Build executor (Milestone 2): Containers + Queue + R2

Status 2026-10-22: code complete and tested locally; **not provisioned** (see Blocked).

## Flow
1. `POST /api/projects/import` (or `POST /api/projects/:id/builds`) → `startContainerBuild`: daily cap check, commit pinned from the branch, `build_jobs` row (`executor = cf-container`), `deployments` row (`target = devstack-sites`), message on `BUILD_QUEUE`.
2. Queue consumer (`custom-worker.ts` `queue()`) → `runContainerJob`: `claimWithCap` (max 2 running, conditional UPDATE) → container `build-<jobId>` `POST /build` → NDJSON phases (`installing` → `building` → `uploading`) and log chunks → `createLogStream` (line-buffered, redacted) → `build_events` + `logs/<jobId>.txt` in R2.
3. `GET /artifact` (tar of the output dir) → `artifacts/<jobId>.tar` → files → `SITES` bucket `sites/<deploymentId>/…` → hostname aliases `hosts/<label>.json`.
4. Production builds also move `<slug>.devstack.bid` (promote). Previews get `<slug>-<shortid>.devstack.bid`.
5. Cancel: `requestCancel` → heartbeat watchdog (10 s) → container `/cancel` (SIGTERM, then SIGKILL). 15-minute hard limit → `timed_out`. Cron sweeper unchanged.

## Caps
`MAX_CONCURRENT_BUILDS = 2`, `BUILD_TIMEOUT_MS = 15 min`, `DAILY_BUILDS_PER_USER = 10` (`src/lib/build/caps.ts`), container `max_instances: 2`, queue `max_concurrency: 2`.

## Security
- Container image (`container/Dockerfile`): pinned digests, non-root `node` user, tini, no secrets/ARGs.
- GitHub token: only in the `/build` request body → git `http.extraheader` via `GIT_CONFIG_*` env (never argv, never the build env, never logged). Public repos build without a token. The user OAuth token is used (no GitHub App yet), so it is not short-lived or repo-scoped: see Next.
- Commands run without a shell (argv split, metacharacters rejected). Dangerous env keys (`PATH`, `NODE_OPTIONS`, `LD_PRELOAD`, …) are dropped.
- Egress allowlist on the container: GitHub + npm/yarn/bun registries + nodejs.org.
- Logs: `sanitizeLog` everywhere (verbatim, URL-encoded and base64 forms, longest first, GitHub token patterns); warning when a secret is shorter than 6 chars.
- User sites are served by a separate Worker (`sites-worker/`) with no D1 and no platform secrets; static files only; `nosniff`; no cookies. A hostname belongs to the first project that claims it.
- Recommendation: move user sites to a dedicated registrable domain (for example `devstack.app`) so user JavaScript is not same-site with `devstack.bid`.

## Blocked (needs the owner / infrastructure)
- **Container image**: built and verified locally (see Verified). Pushing it happens only as part of `npm run deploy:release`, which needs a GO.
- **Queue / R2 buckets** not created yet: `wrangler queues create devstack-build-jobs`, `wrangler r2 bucket create devstack-build-artifacts`, `wrangler r2 bucket create devstack-sites`.
- **Wildcard DNS + route** (the API token has no Zone DNS permission):
  - DNS: `AAAA  *  100::  proxied` in zone `devstack.bid` (apex, `www` and all other records unchanged).
  - Worker route: `*.devstack.bid/*` → Worker `devstack-sites` (deploy with `wrangler deploy -c sites-worker/wrangler.jsonc`). The zone already has a route `*.devstack.bid` with no Worker; it must be replaced by (or narrowed to) the route above.
  - Then set `SITES_DNS_READY=1`.

## Deploy configs (hotfix vs full release)
- `wrangler.jsonc` (base, **hotfix**): no Containers, Durable Object, Queue or build R2. `npm run deploy:hotfix` (same as `npm run deploy`) never needs Docker. The executor reports the missing bindings (`missingInfra`) and builds stay queued/blocked.
- `release/build-bindings.jsonc`: the build-executor bindings only. `npm run cf:release-config` merges them over the base into `wrangler.release.jsonc` (generated, committed; `tests/release-config.test.ts` fails if it is stale).
- `npm run deploy:release` = regenerate + `opennextjs-cloudflare deploy -c wrangler.release.jsonc`. Needs Docker plus the Queue and buckets above.
- After the first release deploy (DO migration `v1-build-container` applied), prefer `deploy:release` for later deploys. A hotfix deploy keeps `BuildContainer` exported, so it does not delete the class, but it removes the bindings until the next release deploy.

## Verified
- Docker 26.1.5 on the box (dockerd started by hand, no systemd). `docker build --network host -t devstack-builder:local container/` (the box sandbox only gives apt network on the host network). The real container (runs as `node`, uid 1000) built `sveltejs/template@5b3da65` through `POST /build` → `{"t":"result","ok":true}`, and `GET /artifact` returned a tar with `index.html`, `global.css`, `favicon.png` and `build/bundle.{js,css}`.
- Dry runs: `wrangler deploy --dry-run` passes with no Docker (base); `wrangler deploy -c wrangler.release.jsonc --dry-run` builds the image and lists BUILD_CONTAINER, BUILD_QUEUE, BUILD_ARTIFACTS and SITES.
- Unit tests: `tests/build-executor.test.ts`, `tests/hosting.test.ts`, `tests/security-review.test.ts`.
- Real end-to-end without Docker: `E2E_BUILD=1 npx vitest run tests/build-executor.test.ts` runs `container/build-server.mjs` locally, clones `sveltejs/template@5b3da65`, `npm install`, `npm run build`, and the executor publishes `public/` and serves it by hostname.