feat(cli): add the ocf scaffolding CLI for custom-resource wrappers

[sourcehawk]

Description

Writing a custom-resource wrapper by hand is almost entirely mechanical: a builder with roughly eight fluent delegations, a resource with eleven to fifteen forwarding methods, a mutator, and the standard test cases. The declared-data migration stamped that pattern out 25 times inside this repo; external users writing wrappers for their own CRDs face the same boilerplate with no tooling, and hand-copied wrappers drift from the framework version they were copied from.

This adds ocf, a CLI shipped in the module at cmd/ocf and installed with go install github.com/sourcehawk/operator-component-framework/cmd/ocf@latest. ocf scaffold wrapper generates a complete wrapper package that compiles and whose generated tests pass immediately. Templates are embedded in the binary, so generated code always matches the framework version the CLI was built from.

Changes

• ocf scaffold wrapper generates mutator.go, builder.go, resource.go, and builder_test.go for any of the four resource categories (static, workload, task, integration), namespaced or cluster-scoped, with GoDoc on every exported symbol following the built-in primitives' wording.
• Variant-specific status handlers are generated as working defaults that report healthy, completed, or operational, each marked as a scaffolded default to replace. Nothing panics, and go test passes on a fresh scaffold.
• Flags only: ten flags, no interactive prompts and no loading of the target Go package. --type, --group, --version, --kind, --alias, and --package are validated, and version, alias, kind, and package name are derived when not given.
• The CLI never edits the user's go.mod. It prints a next-steps block with the go mod tidy hint instead, and refuses to write into a non-empty directory without --force.
• ocf version prints the framework version the binary was built from.
• New make target test-scaffold, wired into make all and CI: it scaffolds every variant against real Kubernetes types into a temp module with a replace directive pointing at the checkout, then runs go test ./... inside it. Template drift now fails CI instead of failing users.
• New docs page docs/cli.md in the mkdocs nav, a scaffolding section in the README, and a pointer from docs/custom-resource.md to the CLI that generates the pattern that page describes.

cobra is a new direct dependency of the module. Nothing outside cmd/ocf imports it, so go list -deps ./pkg/... pulls in zero cobra packages and library consumers are unaffected.

Challenges

The load-bearing risk is template drift: templates that render code against an API the framework has since changed would compile in CI here and fail in a user's module. make test-scaffold closes that by generating and running the real thing. Its first version only checked the go tool's exit code, which is not enough, because go test exits 0 both for a package with no test files and for a package whose test file declares no tests. It now consumes go test -json and asserts that each generated package actually ran a passing test.

The other sharp edge was flag values reaching generated source. --group, --version, and the --type import path are interpolated into Go string literals in the templates, so an unvalidated value could produce a silently wrong identity string or inject an extra import that still compiles. All three are validated in Options.Resolve, and the generated literals are quoted at the template boundary so no input can break out of them.

Related

• feat(plugin): ship the ocf Claude Code plugin for framework consumers #164 ships the ocf Claude Code plugin and is unrelated to this change, other than both being consumer-facing tooling.

Testing

make all passes: fmt, lint, the full test suite under envtest, the new scaffold gate, example tests, and example builds. mkdocs build --strict passes.

Unit coverage is 89.9% for internal/scaffold and 87.5% for cmd/ocf: table tests for every validation and derivation rule, golden tests pinning the full rendered output of all four variants plus a cluster-scoped case, writer tests for the --force and non-empty-directory semantics, and CLI tests for flag errors and the printed next-steps block.

The generated code itself is covered by make test-scaffold rather than by assertions on strings. Worth poking at yourself: install the binary, scaffold a wrapper for a CRD you actually manage, run go mod tidy and go test ./<package>/..., and check whether the generated defaults and their "replace me" wording tell you what to change. Deliberately breaking a template and running make test-scaffold is the quickest way to see the gate work.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds the ocf scaffolding CLI (under cmd/ocf) plus an internal/scaffold templating engine so framework consumers can generate custom-resource wrapper packages (builder/resource/mutator + tests) that match the framework version the CLI was built from, with CI enforcing template drift via a new scaffold gate.

Changes:

• Add ocf scaffold wrapper and ocf version, backed by embedded templates and validated option resolution.
• Add a scaffold CI gate (make test-scaffold) that generates wrappers into a temp module and runs go test -json, asserting tests actually ran per generated package.
• Document the CLI (new docs/cli.md) and link it from README, mkdocs nav, and the custom-resource wrapper docs.

Reviewed changes

Copilot reviewed 48 out of 49 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Adds a scaffolding section and links to CLI docs.
mkdocs.yml	Adds CLI page to the Guides nav.
Makefile	Adds test-scaffold and wires it into make all.
internal/scaffold/variant.go	Defines wrapper variants and their generic-layer wiring.
internal/scaffold/templates/resource.go.tmpl	Template for generated Resource wrapper.
internal/scaffold/templates/mutator.go.tmpl	Template for generated Mutator with plan/apply semantics.
internal/scaffold/templates/builder.go.tmpl	Template for generated Builder and default handlers.
internal/scaffold/templates/builder_test.go.tmpl	Template for generated builder tests.
internal/scaffold/render.go	Renders embedded templates and gofmts output.
internal/scaffold/render_test.go	Golden tests + parsability tests for template rendering.
internal/scaffold/options.go	Validates/derives scaffold flags into TemplateData.
internal/scaffold/options_test.go	Table tests for validation and derivation rules.
internal/scaffold/data.go	TemplateData helpers (identity formatting, type names).
internal/scaffold/generate.go	Writes rendered files to disk with safe directory semantics.
internal/scaffold/generate_test.go	Tests write behavior, --force, and directory checks.
internal/scaffold/gate_test.go	Scaffold gate: generate into temp module, run go test -json, assert tests ran.
internal/scaffold/testdata/golden/static/builder.go.golden	Golden output for static builder.
internal/scaffold/testdata/golden/static/builder_test.go.golden	Golden output for static builder tests.
internal/scaffold/testdata/golden/static/mutator.go.golden	Golden output for static mutator.
internal/scaffold/testdata/golden/static/resource.go.golden	Golden output for static resource.
internal/scaffold/testdata/golden/workload/builder.go.golden	Golden output for workload builder.
internal/scaffold/testdata/golden/workload/builder_test.go.golden	Golden output for workload builder tests.
internal/scaffold/testdata/golden/workload/mutator.go.golden	Golden output for workload mutator.
internal/scaffold/testdata/golden/workload/resource.go.golden	Golden output for workload resource.
internal/scaffold/testdata/golden/task/builder.go.golden	Golden output for task builder.
internal/scaffold/testdata/golden/task/builder_test.go.golden	Golden output for task builder tests.
internal/scaffold/testdata/golden/task/mutator.go.golden	Golden output for task mutator.
internal/scaffold/testdata/golden/task/resource.go.golden	Golden output for task resource.
internal/scaffold/testdata/golden/integration/builder.go.golden	Golden output for integration builder.
internal/scaffold/testdata/golden/integration/builder_test.go.golden	Golden output for integration builder tests.
internal/scaffold/testdata/golden/integration/mutator.go.golden	Golden output for integration mutator.
internal/scaffold/testdata/golden/integration/resource.go.golden	Golden output for integration resource.
internal/scaffold/testdata/golden/static-cluster-scoped/builder.go.golden	Golden output for cluster-scoped static builder.
internal/scaffold/testdata/golden/static-cluster-scoped/builder_test.go.golden	Golden output for cluster-scoped static builder tests.
internal/scaffold/testdata/golden/static-cluster-scoped/mutator.go.golden	Golden output for cluster-scoped static mutator.
internal/scaffold/testdata/golden/static-cluster-scoped/resource.go.golden	Golden output for cluster-scoped static resource.
cmd/ocf/main.go	CLI entrypoint.
cmd/ocf/root.go	Root command wiring for ocf.
cmd/ocf/scaffold.go	Implements ocf scaffold wrapper flags + generation + summary.
cmd/ocf/version.go	Implements ocf version using build info.
cmd/ocf/cli_test.go	CLI behavior tests (generation, defaults, errors, version parsing).
docs/custom-resource.md	Adds a tip pointing users to generate wrappers via the CLI.
docs/cli.md	New CLI documentation page.
.github/workflows/test.yml	Runs make test-scaffold in CI.
.golangci.yml	Enables scaffold build tag for linting.
go.mod	Adds cobra dependency for the CLI.
go.sum	Updates sums for new/updated dependencies.
.github/copilot-instructions.md	Updates contributor guidance to include CLI + scaffold internals.
.ai/base.md	Mirrors instruction updates for the AI instruction set.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 49 changed files in this pull request and generated no new comments.

Suppressed comments (3)

internal/scaffold/gate_test.go:179

• runGoTestJSON relies on per-test {"Action":"pass","Test":...} events to prove each generated package actually ran tests, but the invoked command does not disable the Go test cache. If go test returns cached results, it may emit only package-level pass events (no Test field), which would make assertEachPackageRanTests fail on subsequent runs even when templates are correct.

Add -count=1 to force tests to run (and/or to ensure the JSON stream includes per-test events consistently).

	cmd := exec.CommandContext(t.Context(), "go", "test", "-json", "./...")

internal/scaffold/templates/builder.go.tmpl:18

• The status-handler GoDoc says to “inspect the fields your reports readiness through”. This is inaccurate for non-readiness variants (e.g. the Task variant reports completion, not readiness) and will be emitted into every scaffolded wrapper.

Prefer wording that refers to the variant’s state ({{$spec.StatusNoun}}) rather than “readiness”.

// This is a scaffolded default: it reports {{$spec.StatusValue}} unconditionally, without
// reading the {{.Kind}}'s status. Replace it with logic that inspects the fields
// your {{.Kind}} reports readiness through.

internal/scaffold/templates/builder.go.tmpl:51

• The suspension-mutation GoDoc says “Replace it with the change that stops your workload”, but this handler is also generated for the integration variant (e.g. Service/Ingress) where “workload” is misleading.

Adjust the wording to be kind-neutral so generated wrappers don’t suggest workload-specific actions for non-workload objects.

// This is a scaffolded default: it records no mutation, so the {{.Kind}} is left
// untouched while suspended. Replace it with the change that stops your workload,
// for example scaling to zero or setting a suspended field.

[sourcehawk]

Addressed the three suppressed comments from the latest review in 6cfd4f0. They arrived as suppressed comments rather than threads, so the resolutions are recorded here.

gate_test.go: no -count=1 on the inner go test. Applied, though not for the stated reason. I checked the claim that a cached run emits only package-level pass events: on Go 1.26.1 a cached go test -json replays the per-test events, so assertEachPackageRanTests would not have started failing on repeat runs. The change is still right on its own merits, since a gate whose job is to prove the generated packages actually build and pass should execute them rather than replay a previous result. The inner invocation now passes -count=1, with a comment saying why.

builder.go.tmpl: status handler GoDoc says "readiness". Correct, and it shipped into every scaffolded wrapper. The line now names the variant's own state via {{$spec.StatusNoun}}: a Deployment wrapper reads "reports its converged state through", a Job wrapper "its completed state", an Ingress wrapper "its operational state".

builder.go.tmpl: suspension handler GoDoc says "stops your workload". Correct for the same reason, since the handler is generated for the integration variant too. It now reads "the change that takes the <Kind> out of service, for example scaling to zero or setting a suspended field", which fits a Service or Ingress as well as a Deployment.

Goldens regenerated for the workload, task, and integration variants. make test-scaffold, go test ./internal/scaffold/... ./cmd/ocf/..., golangci-lint run ./... and golangci-lint run --build-tags scaffold ./internal/scaffold/... are all clean.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 49 changed files in this pull request and generated no new comments.

Suppressed comments (2)

internal/scaffold/gate_test.go:184

• Like runGo, runGoTestJSON appends a new GOFLAGS entry without removing any existing GOFLAGS from the environment. If GOFLAGS is already set, the intended -mod=mod may be ignored, making the scaffold gate sensitive to the runner's ambient environment.

	cmd := exec.CommandContext(t.Context(), "go", "test", "-count=1", "-json", "./...")
	cmd.Dir = dir
	cmd.Env = append(os.Environ(), "GOFLAGS=-mod=mod")

internal/scaffold/gate_test.go:153

• cmd.Env = append(os.Environ(), "GOFLAGS=-mod=mod") can result in duplicate GOFLAGS entries when the parent environment already has GOFLAGS set. On many systems the first occurrence wins, so this test may not actually force -mod=mod, leading to non-reproducible gate behavior depending on the runner environment.

This issue also appears on line 181 of the same file.

	cmd := exec.CommandContext(t.Context(), "go", args...)
	cmd.Dir = dir
	cmd.Env = append(os.Environ(), "GOFLAGS=-mod=mod")

[sourcehawk]

The latest review's two suppressed comments both rest on the same premise, and I checked it rather than acting on it. No code change.

Claim: cmd.Env = append(os.Environ(), "GOFLAGS=-mod=mod") can leave a duplicate GOFLAGS in which the parent's value wins, so the gate may not actually force -mod=mod.

That is not how Go resolves it. os/exec deduplicates Cmd.Env before starting the process and keeps the last occurrence of each key, so an appended entry always overrides the inherited one. Verified on this toolchain (Go 1.26.1) with a parent environment that sets a conflicting value:

parent GOFLAGS="-mod=vendor" child sees: -mod=mod

Both call sites (runGo and runGoTestJSON) use exactly that append form, so the gate does force -mod=mod regardless of the runner's ambient GOFLAGS, which is the isolation the comment asks for. Rewriting the env slice to strip a pre-existing entry first would add code that changes no behavior.

Worth noting what the gate deliberately does not isolate: an ambient GOFLAGS hostile to the repo itself (for example -mod=vendor, when there is no vendor directory) breaks the outer go test that runs the gate, exactly as it would break any other go invocation in this repo. That is a property of the runner's environment, not of this gate.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 53 changed files in this pull request and generated no new comments.

Suppressed comments (1)

plugin/commands/new-wrapper.md:22

• The placeholder --variant <category> is ambiguous/inaccurate: the CLI only accepts a fixed set of variant values. Using the explicit allowed set here avoids users thinking arbitrary category names are valid.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 54 changed files in this pull request and generated no new comments.