|
| 1 | +You are an experienced, pragmatic software engineering AI agent. Do not over-engineer a solution when a simple one is possible. Keep edits minimal. If you want an exception to ANY rule, you MUST stop and get permission first. |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +`coder-k8s` is a Go-based Kubernetes operator scaffold for managing a custom resource named `CoderControlPlane` (`coder.com/v1alpha1`). The current codebase focuses on baseline wiring: CRD types, scheme registration, controller startup, and a placeholder reconciliation loop. |
| 6 | + |
| 7 | +**Tech stack** |
| 8 | +- Go `1.25.6` (`go.mod`) |
| 9 | +- Kubernetes libraries: `controller-runtime`, `client-go`, `apimachinery`, `code-generator` |
| 10 | +- Vendored dependencies committed under `vendor/` |
| 11 | +- Tooling: `make`, Bash scripts in `hack/`, GitHub Actions, GoReleaser, optional Nix dev shell (`flake.nix`) |
| 12 | + |
| 13 | +## Reference |
| 14 | + |
| 15 | +### Key files |
| 16 | +- `main.go`: manager bootstrap, scheme registration, health/readiness endpoints, controller wiring. |
| 17 | +- `main_test.go`: baseline tests for scheme registration and defensive nil-check behavior. |
| 18 | +- `api/v1alpha1/codercontrolplane_types.go`: CRD spec/status and list types. |
| 19 | +- `internal/controller/codercontrolplane_controller.go`: reconciler and `SetupWithManager` logic. |
| 20 | +- `hack/update-codegen.sh`: deepcopy codegen entrypoint. |
| 21 | +- `Makefile`: canonical build/test/vendor/codegen commands. |
| 22 | +- `.github/workflows/ci.yaml`: CI checks, workflow linting, and `:main` container publish. |
| 23 | + |
| 24 | +### Important directories |
| 25 | +- `api/v1alpha1/`: API group/version types and generated deepcopy code. |
| 26 | +- `internal/controller/`: reconciliation logic. |
| 27 | +- `internal/deps/`: blank imports to keep baseline Kubernetes tool deps in `go.mod`/`vendor`. |
| 28 | +- `hack/`: maintenance scripts. |
| 29 | +- `.github/workflows/`: CI and release automation. |
| 30 | +- `vendor/`: checked-in module dependencies (required by project workflow). |
| 31 | + |
| 32 | +### Architecture notes |
| 33 | +- `main` registers core Kubernetes + project schemes, constructs a controller-runtime manager, and starts it. |
| 34 | +- Reconciliation is intentionally minimal: fetch resource, validate identity assumptions, then no-op with TODO markers. |
| 35 | +- Defensive checks are intentional (`assertion failed: ...`) and used to fail fast during development. |
| 36 | + |
| 37 | +## Essential Commands |
| 38 | + |
| 39 | +Run from repository root. |
| 40 | + |
| 41 | +- **Build:** `make build` |
| 42 | +- **Format (apply):** `find . -type f -name '*.go' -not -path './vendor/*' -print0 | xargs -0 gofmt -w` |
| 43 | +- **Format (check):** `find . -type f -name '*.go' -not -path './vendor/*' -print0 | xargs -0 gofmt -l` |
| 44 | +- **Lint (workflows):** `go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.10` |
| 45 | +- **Test:** `make test` |
| 46 | +- **Clean:** `go clean -cache -testcache && rm -f ./coder-k8s && rm -rf ./dist` |
| 47 | +- **Development run:** `GOFLAGS=-mod=vendor go run .` (requires Kubernetes config via your env, e.g. `KUBECONFIG`) |
| 48 | +- **Vendor consistency:** `make verify-vendor` |
| 49 | +- **Code generation:** `make codegen` (or `bash ./hack/update-codegen.sh`) |
| 50 | +- **Shell scripts:** `find . -type f -name '*.sh' -not -path './vendor/*'` |
| 51 | + |
| 52 | +## Patterns |
| 53 | + |
| 54 | +- **Do** preserve fail-fast assertions for impossible states (nil manager/client/scheme, mismatched fetched objects). |
| 55 | + **Don’t** silently ignore these paths or convert them to soft failures. |
| 56 | +- **Do** keep vendoring in sync when dependencies change (`go mod tidy`, `go mod vendor`, then verify diff). |
| 57 | + **Don’t** submit dependency changes without updating `vendor/`. |
| 58 | +- **Do** regenerate deepcopy code after API type changes (`make codegen`). |
| 59 | + **Don’t** hand-edit `api/v1alpha1/zz_generated.deepcopy.go`. |
| 60 | +- **Do** keep controller and API changes paired with tests in `main_test.go` or focused package tests. |
| 61 | + **Don’t** add reconciliation behavior without coverage for critical assumptions. |
| 62 | + |
| 63 | +## Anti-patterns |
| 64 | + |
| 65 | +- Unpinned GitHub Action versions in workflow files (CI uses SHA-pinned actions). |
| 66 | +- Running CI-sensitive commands without vendoring mode when behavior differs from CI. |
| 67 | +- Removing assertion messages that start with `assertion failed:`; these are deliberate diagnostics. |
| 68 | + |
| 69 | +## Code Style |
| 70 | + |
| 71 | +- Follow idiomatic Go and keep code `gofmt`-formatted. |
| 72 | +- Keep comments concise and purposeful (package docs, exported type/function docs). |
| 73 | +- Match existing error style: contextual wrapping + explicit assertion messages for impossible conditions. |
| 74 | + |
| 75 | +## Commit and Pull Request Guidelines |
| 76 | + |
| 77 | +### Before committing |
| 78 | +1. Run `make test`. |
| 79 | +2. Run `make build`. |
| 80 | +3. Run `make verify-vendor`. |
| 81 | +4. If API types changed, run `make codegen` and include generated updates. |
| 82 | +5. If `.github/workflows/*` changed, run `go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.10`. |
| 83 | + |
| 84 | +### Commit messages |
| 85 | +- Match repository history style: short imperative summary, optionally prefixed by type (e.g., `chore: ...`). |
| 86 | +- Prefer `type: message` if unsure. |
| 87 | +- Include issue/PR reference when available (examples in history use `(#N)`). |
| 88 | + |
| 89 | +### Pull request descriptions |
| 90 | +- Include: what changed, why, validation commands run, and any follow-up work. |
| 91 | +- For public mux-generated PRs/commits in this environment, include footer: |
| 92 | + |
| 93 | +```md |
| 94 | +--- |
| 95 | +_Generated with [`mux`](https://github.com/coder/mux) • Model: `<modelString>` • Thinking: `<thinkingLevel>`_ |
| 96 | +``` |
0 commit comments