codegen: add golden tests and production overrides (PRINFRA-121)

[somanshreddy]

Description

Proves the codegen pipeline works and configures it for all 40 v3 endpoints.

Golden file tests — a mini OpenAPI spec with 6 endpoints (list with pagination, get by ID, create with body including complex fields, delete, nested action, multipart upload) runs through the full pipeline. Output is compared against checked-in golden files. Run `go test ./codegen/ -update` to refresh golden files after intentional changes.

Test coverage — golden file comparison, v1 endpoint skipping, pagination detection, complex field omission, multipart detection, nested action naming, skip pattern matching, missing examples validation.

Production overrides — overrides.yaml configures all 40 v3 endpoints with:

• Group renames ("Video Translate" → translate, "Video Agent" → video-agent)
• v1/v2 skip patterns
• Positional promotions (prompt, text, file)
• Usage examples for every command (mandatory — codegen fails without them)

After this PR, running `make generate SPEC=path/to/external-api.json` produces all 40 command definitions. Wiring them into the CLI is Stack 2.

Testing

8 golden file tests covering all codegen patterns. All tests are mocked — no external dependencies.

Files

• codegen/generate_test.go — 8 tests: golden files, v1 filtering, pagination, complex fields, multipart, naming, x-cli-visible, missing examples
• codegen/overrides.yaml — production overrides for all 40 v3 endpoints
• codegen/testdata/mini_spec.json — minimal 6-endpoint test spec
• codegen/testdata/golden/ — expected codegen output (widget.go, upload.go, registry.go)

[somanshreddy]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• codegen: add golden tests and production overrides (PRINFRA-121) #15 👈 (View in Graphite)
• codegen: add file generator, templates, and CLI entry point (PRINFRA-121) #14 : 1 other dependent PR (#16 )
• codegen: add endpoint grouper with agent-first naming (PRINFRA-121) #13
• codegen: add examples.yaml and simplify ArgSpec (PRINFRA-121) #11 : 1 other dependent PR (#12 )
• client: add multipart form-data support for file uploads (PRINFRA-121) #6 : 1 other dependent PR (#7 )
• cmd: add generic command builder (PRINFRA-121) #10
• client: refactor executor to use Spec + Invocation (PRINFRA-121) #9
• add command.Spec and command.Invocation types (PRINFRA-121) #5
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[linear]

PRINFRA-121 CLI M1: OpenAPI codegen pipeline

Build the code generation pipeline that reads openapi/external-api.json and produces CommandSpec structs.

Scope

• Go program in codegen/ using text/template
• Parse OpenAPI spec, filter to v3 endpoints only
• Generate CommandSpec data structs in gen/ (zero logic)
• overrides.yaml for:
  • Positional arg promotion (prompt, text, file)
  • Command group naming (video-translations → translate, webhooks/endpoints → webhook)
  • Help examples per command
• make generate SPEC=... target
• Nested path collapsing (e.g., /webhooks/endpoints/{id}/rotate-secret → webhook rotate-secret)
• Golden file tests for codegen output stability
• Generate all ~30 commands, wire into Cobra at startup

Mapping Rules

• OpenAPI tag → command group
• POST → create, GET (list) → list, GET (by id) → get, DELETE → delete, PATCH → update
• Path params → positional args, query params → flags, body fields → flags
• overrides.yaml exceptions for positional promotion and group naming

Acceptance Criteria

• make generate produces compilable CommandSpec files for all v3 endpoints
• Adding a new endpoint to spec + re-running codegen produces new command
• Generated help text includes descriptions and examples
• Golden file tests pass
• Override validation: make generate fails if overrides reference non-existent endpoints

[somanshreddy]

Merged into PR #14 (renderer + templates) during stack restructuring.