🤖 fix: wait for successful template builds before promotion (#70)

## Summary
Fix aggregated CoderTemplate update behavior so new template versions
are promoted to active only after the build succeeds, and export a
reusable aggregated template example for smoke/regression testing.

## Background
Template updates were creating new Coder template versions, but
promotion could race the provisioner build and fail with a "running
build" error. That left active version unchanged, which matched the
issue observed during testing.

## Implementation
- Added template build wait logic in aggregated template storage:
  - waits for template version job to reach "succeeded"
  - fails on "failed" / "canceled"
  - uses backoff polling with configurable env-based settings
- Added/expanded tests in internal/aggregated/storage/storage_test.go:
  - coverage for pending-build wait before promotion
  - env configuration default/validation coverage
  - mock API behavior for build-state gated promotion
- Added docs for tuning knobs in
docs/how-to/deploy-aggregated-apiserver.md
- Added reusable aggregated template example:
  - examples/aggregated/codertemplate-smoke-scratch.yaml
  - examples/aggregated/README.md
  - linked from root README.md

## Validation
- make verify-vendor
- make test
- make build
- make lint
- make docs-check
- kubectl apply --dry-run=client -f
examples/aggregated/codertemplate-smoke-scratch.yaml

## Risks
- Template update requests now block until build completes or timeout;
this increases latency for update calls by design.
- Misconfigured wait env vars now fail fast with explicit assertion
errors (intentional defensive behavior).

---

_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking:
`xhigh` • Cost: `$0.00`_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh
costs=0.00 -->

Author: ThomasK33

README.md

@@ -75,6 +75,8 @@ make docs-serve
 
 - [`examples/cloudnativepg/`](examples/cloudnativepg/) — Deploy a `CoderControlPlane` with a CloudNativePG-managed PostgreSQL backend.
 
+- [`examples/aggregated/`](examples/aggregated/) - Reusable `CoderTemplate` manifests for aggregated API testing.
+
 ## KIND development cluster (k9s demos)
 
 Bootstrap a KIND cluster and install CRDs/RBAC (**this switches current kubectl context**):

docs/how-to/deploy-aggregated-apiserver.md

@@ -90,6 +90,30 @@ kubectl get codertemplates.aggregation.coder.com -A
 kubectl logs -n coder-system deploy/coder-k8s
 ```
 
+## Template build wait tuning
+
+When updating `CoderTemplate.spec.files`, the aggregated API server now waits for
+Coder to finish building the new template version before promoting it active.
+
+The wait behavior is configurable via environment variables on the
+`coder-k8s` deployment:
+
+- `CODER_K8S_TEMPLATE_BUILD_WAIT_TIMEOUT` (default: `25m`)
+- `CODER_K8S_TEMPLATE_BUILD_BACKOFF_AFTER` (default: `2m`)
+- `CODER_K8S_TEMPLATE_BUILD_INITIAL_POLL_INTERVAL` (default: `2s`)
+- `CODER_K8S_TEMPLATE_BUILD_MAX_POLL_INTERVAL` (default: `10s`)
+
+- Aggregated API request timeout defaults to `30m`; keep it at or above the build wait timeout.
+
+- `CODER_K8S_TEMPLATE_BUILD_WAIT_TIMEOUT` values above `30m` are rejected, because they cannot exceed the API request timeout.
+
+Behavior:
+
+- Polls at the initial interval for the first 2 minutes.
+- After that, poll interval doubles up to the max poll interval.
+- Fails if the version build ends in `failed`/`canceled` or the total wait
+  timeout is exceeded.
+
 ## TLS note
 
 `deploy/apiserver-apiservice.yaml` uses `insecureSkipTLSVerify: true` for development convenience.

examples/aggregated/README.md

@@ -0,0 +1,19 @@
+# Aggregated API examples
+
+This directory contains example `CoderTemplate` resources for exercising the
+aggregated API server (`aggregation.coder.com/v1alpha1`).
+
+## Smoke template export
+
+- [`codertemplate-smoke-scratch.yaml`](./codertemplate-smoke-scratch.yaml)
+  is an exported template manifest captured from a live smoke-test cluster.
+- It is intended as a reusable baseline for template create/update API testing.
+
+Apply it with:
+
+```bash
+kubectl apply -f examples/aggregated/codertemplate-smoke-scratch.yaml
+```
+
+If you are updating an already-existing object with `kubectl replace`, include
+the latest `metadata.resourceVersion` from `kubectl get -o yaml`.

examples/aggregated/codertemplate-smoke-scratch.yaml

@@ -0,0 +1,91 @@
+apiVersion: aggregation.coder.com/v1alpha1
+kind: CoderTemplate
+metadata:
+  name: coder.smoke-scratch
+  namespace: coder
+spec:
+  organization: coder
+  # Leave blank for create-from-files workflows; the API creates a new template
+  # version and promotes it active after build succeeds.
+  versionID: ""
+  files:
+    README.md: |
+      ---
+      display_name: Scratch
+      description: A minimal starter template for Coder
+      icon: ../../../site/static/emojis/1f4e6.png
+      maintainer_github: coder
+      verified: true
+      tags: []
+      ---
+
+      # A minimal Scaffolding for a Coder Template
+
+      Use this starter template as a basis to create your own unique template from scratch.
+    main.tf: |
+      terraform {
+        required_providers {
+          coder = {
+            source = "coder/coder"
+          }
+        }
+      }
+
+      data "coder_provisioner" "me" {}
+
+      data "coder_workspace" "me" {}
+
+      resource "coder_agent" "main" {
+        arch = data.coder_provisioner.me.arch
+        os   = data.coder_provisioner.me.os
+
+        metadata {
+          display_name = "CPU Usage"
+          key          = "0_cpu_usage"
+          script       = "coder stat cpu"
+          interval     = 10
+          timeout      = 1
+        }
+
+        metadata {
+          display_name = "RAM Usage"
+          key          = "1_ram_usage"
+          script       = "coder stat mem"
+          interval     = 10
+          timeout      = 1
+        }
+      }
+
+      # Use this to set environment variables in your workspace
+      # details: https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env
+      resource "coder_env" "welcome_message" {
+        agent_id = coder_agent.main.id
+        name     = "WELCOME_MESSAGE"
+        value    = "Welcome to your Coder workspace!"
+      }
+
+      # Adds code-server
+      # See all available modules at https://registry.coder.com/modules
+      module "code-server" {
+        count  = data.coder_workspace.me.start_count
+        source = "registry.coder.com/coder/code-server/coder"
+
+        # This ensures that the latest non-breaking version of the module gets downloaded, you can also pin the module version to prevent breaking changes in production.
+        version = "~> 1.0"
+
+        agent_id = coder_agent.main.id
+      }
+
+      # Runs a script at workspace start/stop or on a cron schedule
+      # details: https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script
+      resource "coder_script" "startup_script" {
+        agent_id           = coder_agent.main.id
+        display_name       = "Startup Script"
+        script             = <<-EOF
+          #!/bin/sh
+          set -e
+          # Run programs at workspace startup
+        EOF
+        run_on_start       = true
+        start_blocks_login = true
+      }