codegen: add examples.yaml and simplify ArgSpec (PRINFRA-121)

[somanshreddy]

Description

Adds curated examples, simplifies the type system, and introduces dependencies for the codegen pipeline.

examples.yaml — hand-written CLI usage examples for every generated command. Mandatory — make generate fails if any endpoint is missing. Examples help both humans (copy-paste) and agents (pattern-matching working commands). This is the only CLI-side configuration file — naming and visibility are controlled in the OpenAPI spec.

ArgSpec simplified — positional arguments now only come from URL path parameters. Body fields and file paths are always named flags (--flag), never positional. This is an agent-first design: named flags are self-documenting.

FlagSpec extended — Source field gains a third value "file" (alongside "query" and "body"). Flags with Source: "file" route to inv.FilePath for multipart upload (e.g., --file ./video.mp4). BuildInvocation handles the routing.

command.Groups type — named type map[string][]*Spec with a SortedNames() helper. Used as the return type for the grouper and input to the renderer. Reads command.Groups instead of raw map type everywhere.

Libraries added:

• jinzhu/inflection — singularize group names from OpenAPI tags
• kin-openapi — parse OpenAPI specs (used by the grouper in a later PR)
• iancoleman/strcase — kebab-case and PascalCase conversion

Testing

Existing tests updated: ArgSpec Target field removed, body/file positional arg tests removed. All remaining tests pass.

Files

• internal/command/spec.go — ArgSpec simplified, FlagSpec Source:"file" added, Groups type added, BuildInvocation updated
• internal/command/spec_test.go — updated for simplified ArgSpec
• cmd/heygen/builder_test.go — updated for simplified ArgSpec
• codegen/examples.go — Examples type, YAML loading
• codegen/examples.yaml — curated examples for all v3 endpoints
• codegen/testdata/test_examples.yaml — test fixture
• go.mod / go.sum — dependencies added

[somanshreddy]

• codegen: add examples.yaml and simplify ArgSpec (PRINFRA-121) #11 : 2 dependent PRs (#12 , #13 ) 👈 (View in Graphite)
• 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]

I will work on proper examples once we have more of the CLI complete. This is just for basic functionality.

[jrusso1020]

instead of one massive examples.yaml can we split it by command/request or something? alongside the command code? basicaly a cleaner structure and will keep files smaller

[somanshreddy]

Right now, these are manual examples. Is this suggestion that we split these manual examples into a per-command file? Like

codegen/examples/video.yaml`` ``codegen/examples/avatar.yaml`` ``codegen/examples/voice.yaml

These don't sit beside the command code until the codegen pipeline (PR #14) runs.

We can also auto-generate them as well and place it in the command files directly but we need to come up with an algorithm to determine appropriate/representative examples. This seemed a bit too complex so I skipped it for now.

[somanshreddy]

Merge activity

• Apr 1, 7:16 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 1, 7:17 PM UTC: @somanshreddy merged this pull request with Graphite.