feat(controls): manage controls from the CLI

[pbeckham]

What

Adds CLI parity with the released controls API so controls can be created, inspected, tagged and archived without the UI. Implements the command surface from the Definition of Ready in kosli-dev/server#5742.

Commands

Command	Endpoint
kosli create control <id> --name <name> [--description]	POST /api/v2/controls/{org}
kosli list controls [--search] [--tag] [--archived] [--page/--page-limit] [--output]	GET /api/v2/controls/{org}
kosli get control <id> [--output]	GET /api/v2/controls/{org}/{id}
kosli archive control <id>	POST /api/v2/controls/{org}/{id}/archive
kosli unarchive control <id> (new unarchive command group)	POST /api/v2/controls/{org}/{id}/unarchive
kosli tag control <id> --set/--unset	PATCH /api/v2/tags/{org}/control/{id}

Notable changes

• 409-retry fix (internal/requests): the shared client retries 409 (transient lock conflicts), which turned a duplicate-identifier 409 on control-create into a confusing "giving up after N attempts". Added a per-request DisableConflictRetry (threaded via request context) so control-create surfaces the real error immediately; lock-conflict retries are preserved everywhere else.
• kosli tag now accepts control/controls as a resource type (the server already supported it).
• Registry-driven OpenAPI contract test: fetches the live schema from the test server and asserts each CLI payload struct matches its schema component (every field it sends exists; every required property is sent). Seeded with control + environment; adding an entity is a one-line registry change. This is the "keep the CLI in sync with the schema" mechanism.

Testing

Every command has happy- and unhappy-path coverage: argument validation, required flags, duplicate-409, not-found, invalid-identifier (server validation surfaced verbatim), pagination bounds, filter correctness (search/tag/archived), and archived/active state verified via get. All green against the local server from a clean DB.

Out of scope (noted for follow-up)

• The generic : map[...] suffix on API error messages is the shared client's formatting for any message+errors response — cosmetic, repo-wide, not controls-specific.
• --link/links on create control and policies on environment are not exposed by the CLI yet; the contract test logs these as coverage gaps (not failures).

Refs kosli-dev/server#5742

🤖 Generated with Claude Code

[claude]

Claude finished @pbeckham's task in 3m 31s —— View job

---

Code review — feat(controls): manage controls from the CLI

• Static analysis (go build, go vet, go mod tidy)
• Review command code (create/list/get/archive/unarchive/tag)
• Review internal/requests 409-retry change
• Review tests + OpenAPI contract test
• Post review

Static analysis ✅

go build ./..., go vet ./... both clean. go mod tidy leaves go.mod/go.sum unchanged. No compile/vet/dependency issues.

Overall

This is a clean, well-structured PR. The command files follow the established new<Command>Cmd() factory + PreRunE/RunE pattern consistently, flag help lives in root.go with the rest, and every command has happy- and unhappy-path coverage. Nicely done.

Highlights worth calling out

• DisableConflictRetry (internal/requests) is the right fix, done well: a private contextKey type (no collision risk), the retry opt-out threaded through customCheckRetry, lock-conflict retries preserved everywhere else, and a dedicated test (/conflict/ with DisableConflictRetry: true) that pins the surfaced-immediately behavior. The earlier review's determinism fixes in getControl.go (sorted tags/links, != nil guards) are also in and look correct.
• Registry-driven OpenAPI contract test is a genuinely good mechanism for keeping CLI payloads in sync with the schema, and the "log-don't-fail" treatment of unexposed optional properties is a sensible default.

Suggestions (all minor / non-blocking)

1. Doc inconsistency in list controls example — flagged inline (listControls.go:41): the comment uses framework=finos-sdlc while the command and flag help use the colon form.

2. Contract test doesn't recurse into embedded structs — jsonFieldNames (openapiContract_test.go:113) iterates only top-level NumField(), so an anonymous/embedded payload struct (like the CommonAttestationPayload pattern used elsewhere) would silently contribute no field coverage. Both current cases (ControlPayload, CreateEnvironmentPayload) are flat so it's fine today — worth a one-line comment noting the limitation so a future registry addition doesn't get a false sense of coverage.

3. On the "isn't this a server-side test?" threads (@FayeSGW) — a fair point on the assertions that match the exact server-generated wording via goldenRegex (invalid-identifier, duplicate-409, not-found). The high-value CLI-side guarantee is that the command surfaces the error (non-zero exit + printed message) rather than swallowing/masking it — most importantly that create's DisableConflictRetry turns the duplicate 409 into a real error instead of "giving up after N attempts". Matching the server's literal phrasing ("A control with identifier ... already exists", "contains invalid characters") couples these CLI tests to server copy, so they'll break if the server rewords. If you want to keep them CLI-side, consider loosening those regexes to the CLI-owned part of the behavior; if the intent is purely to prove surfacing, a shorter anchor (e.g. just ^Error: plus already exists) is less brittle. Not blocking — just the trade-off behind Faye's question.

Nothing here blocks merge. 👍
· 5742-manage-controls