codegen: add OpenAPI spec parser (PRINFRA-121)

[somanshreddy]

Description

Reads an OpenAPI 3.1 JSON spec and extracts the structured data needed for CLI command generation. This is the first stage of the codegen pipeline: raw spec → parsed endpoints.

Key parsing behaviors:

• $ref resolution — dereferences request body schema references (one level deep)
• Pydantic nullable handling — recognizes the `anyOf: [{type: T}, {type: null}]` pattern from HeyGen's Python-generated spec and extracts the real type
• Field classification — categorizes each request body field as simple (scalar or array-of-scalar → becomes a CLI flag) or complex (nested object, discriminated union → omitted from flags, users reach it via --json-body)
• Pagination detection — identifies list endpoints by looking for `has_more` boolean + a token field in the response schema
• Multipart detection — identifies file upload endpoints from `multipart/form-data` content type
• Type mapping — OpenAPI types to CLI flag types: string→string, integer→int, boolean→bool, number→float64, array of strings→string-slice

Output is a flat list of parsed endpoints. The grouper (next PR) organizes them into command groups.

Testing

Tested via golden file tests in a later PR. The parser is exercised by the full pipeline test with a mini OpenAPI spec covering all patterns.

Files

• codegen/parser.go — Parse(), $ref resolution, field classification, pagination/multipart detection, x-cli-visible filtering

[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 OpenAPI spec parser (PRINFRA-121) #12 👈 (View in Graphite)
• codegen: add examples.yaml and simplify ArgSpec (PRINFRA-121) #11 : 1 other dependent PR (#13 )
• 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]

Closed — parser merged into grouper. kin-openapi types used directly, no intermediate ParsedEndpoint.