feat(monetizeapi): controller-gen as canonical CRD schema source

[bussyjd]

Why

CRD-vs-Go drift is a documented recurring bug class. PurchaseAutoRefill.MaxTotal existed in purchaserequest-crd.yaml for months while types.go didn't read it — fixed by hand in PR #513 with no enforcement to prevent the next instance. This commit also adds back the missing MaxTotal and MaxSpendPerDay fields to the Go struct so the next reconcile actually reads what the CRD declares.

Before

   internal/monetizeapi/types.go   (Go struct, hand-edited)
                  ↕  drift (no enforcement)
   *-crd.yaml                      (OpenAPI schema, hand-edited)

   Result: fields appear/disappear independently. Caught at runtime
   when apiserver rejects a CR with "unknown field" or controller
   reads zero from a field that was supposed to be populated.

After

   internal/monetizeapi/types.go
   (kubebuilder markers are the source of truth)
                  │
                  ▼  just generate
                  │
   *-crd.yaml + zz_generated.deepcopy.go
   (machine-generated; CI fails if not in sync with markers)

   Result: one editable source. Schema, validations, printer columns,
   subresources, DeepCopy methods all derive from Go markers.
   `git diff` after `just generate` MUST be empty — CI enforces.

What changed

• tools/tools.go — anchors controller-gen as a build dependency (v0.16.5, compatible with k8s.io/client-go v0.34.x)
• justfile — generate recipe runs controller-gen + renames obol.org_<plural>.yaml to existing <singular>-crd.yaml naming
• hack/boilerplate.go.txt — generated-file marker (force-added past the repo's *.txt gitignore)
• internal/monetizeapi/doc.go — package-level +groupName=obol.org / +versionName=v1alpha1 / +kubebuilder:object:generate=true
• internal/monetizeapi/types.go — kubebuilder markers on every CRD-backed type, plus the previously-missing MaxTotal / MaxSpendPerDay fields on PurchaseAutoRefill
• internal/monetizeapi/deepcopy_manual.go — hand-written DeepCopy for PreSignedAuth (its Payment map[string]interface{} is opaque to controller-gen)
• internal/monetizeapi/zz_generated.deepcopy.go — generated DeepCopy methods for the rest of the package
• internal/embed/infrastructure/base/templates/*-crd.yaml — regenerated (see diff section below)
• .github/workflows/lint-test.yaml — new generate-check job: runs just generate and fails if git status --porcelain is non-empty

CRD diff after generation

Bit-exact round-trip wasn't possible because controller-gen normalises layout. The unavoidable differences between hand-written and generated CRDs are:

1. Top-of-file comments dropped. controller-gen does not preserve the leading narrative comments (e.g. # ServiceOffer CRD\n# Defines a compute service...). All structural descriptions are preserved as description: fields on the matching property; the narrative comments are reproduced as Go doc comments on the corresponding types in types.go.
2. controller-gen.kubebuilder.io/version: v0.16.5 annotation added on every generated CRD — required for CI to detect drift via diff and lets future operators see which controller-gen version produced the YAML.
3. YAML key ordering and indentation changed. controller-gen alphabetises keys within objects (e.g. additionalPrinterColumns before name, singular after shortNames) and uses 2-space indentation throughout. The hand-written files used 4-space and a CRD-conventional ordering. The OpenAPI schemas are semantically identical; kubectl apply is order-insensitive.
4. apiVersion + kind + metadata properties appear in every CR's openAPIV3Schema. controller-gen always emits these to match what apiserver expects; they were elided in the hand-written files. No behaviour change.
5. PurchaseAutoRefill gained maxTotal (integer) and maxSpendPerDay (string) on the Go side. Both fields already existed in the prior hand-written CRD but were silently missing from types.go — this is the bug class the PR exists to close.
6. Top-of-file --- separator on the (previously-missing) purchaserequest-crd.yaml added by controller-gen; harmless.

No fields were dropped. No validations were loosened. The ^0x[0-9a-fA-F]{40}$ pattern on payTo, the eip3009;permit2 enum on transferMethod, the ^/[a-zA-Z0-9/_.-]*$ path pattern, the 1-65535 port range, the 1-2500 count range, the inference;fine-tuning;http;agent type enum, all printer columns, and all subresources.status declarations are preserved.

Test plan

• just generate (executed as the inlined shell script since just isn't installed locally) produces zero diff on a clean re-run
• go build ./... clean
• go test ./internal/embed/... green — the embed CRD parse + schema tests still pass against the regenerated YAML
• go test ./internal/monetizeapi/... ./internal/serviceoffercontroller/... ./internal/x402/... ./internal/x402/buyer/... green
• go vet ./... clean (only pre-existing internal/enclave/enclave_darwin.go unsafe-pointer warnings remain)
• internal/stack TestWarnIfNoChatModel_EmitsWarnWhenNoModels failure verified as pre-existing on origin/main (unrelated)

Future

Unblocks any future CRD changes (e.g. spec.paused + metav1.Condition) — those become "edit Go markers, run just generate, commit" instead of hand-editing CRDs twice and drifting.

[bussyjd]

Superseded by bundle PR #536 — closing in favor of the consolidated merge target. Original branch and history preserved.