cmd: add generic command builder (PRINFRA-121)

[somanshreddy]

Description

Adds the generic command builder — the bridge between generated Specs (pure data) and the Cobra command tree.

The problem: Codegen produces command.Spec structs — endpoint, method, flags, args. Cobra needs *cobra.Command objects with RunE functions, registered flags, and arg validators. Something needs to convert one to the other. That's what buildCobraCommand does.

What it does for every generated command:

1. Creates a Cobra command with Use, Short, Long, Example derived from the Spec
2. Registers typed flags — dispatches by FlagSpec.Type: --limit becomes IntVar, --title becomes StringVar, --draft becomes BoolVar, --events becomes StringSliceVar. Defaults, required flags, and enum help text all handled automatically.
3. Adds -d/--data flag for commands with BodyEncoding: "json" — the escape hatch for complex request bodies (discriminated unions, nested objects). Accepts inline JSON, a file path, or - for stdin. Named to match curl and Stripe CLI conventions.
4. Sets positional arg validation — cobra.ExactArgs(len(spec.Args)) ensures the right number of positional args
5. Wires RunE — when the user runs the command:
   • Parses -d input if provided (inline JSON, file, or stdin via readData)
   • Calls spec.BuildInvocation() to resolve flags + args into an Invocation (with merge order: -d base → positional args → flags overlay)
   • Calls client.Execute(spec, inv) to send the HTTP request
   • Calls formatter.Data(result) to write JSON to stdout

Why this matters: This is what makes "generated commands are data, not logic" work. All 40 generated commands go through this same function. No per-command code. Add a new endpoint to the OpenAPI spec, run make generate, and it works — because the builder handles everything generically.

Also in this PR: newRootCmdWithSpecs — a test helper that builds a full Cobra tree from Specs instead of hand-written commands. This enables integration tests that prove the builder produces identical behavior to the M0 hand-written video list command.

Testing

6 integration tests using httptest mocks:

• Video list via Spec (verifies parity with hand-written command)
• Query flag forwarding (limit, folder-id, token)
• POST with body flags (webhook create with url + entity-id)
• Path param substitution (video get with video-id)
• Bodyless POST sends no request body (avatar create)
• Enum validation returns exit code 2 (voice list with invalid --type)

Files

• cmd/heygen/builder.go — buildCobraCommand, registerFlag, readData, buildUseLine
• cmd/heygen/builder_test.go — 6 integration tests with httptest
• cmd/heygen/root.go — added newRootCmdWithSpecs for test support

[somanshreddy]

• client: add multipart form-data support for file uploads (PRINFRA-121) #6 : 2 dependent PRs (#7 , #11 )
• cmd: add generic command builder (PRINFRA-121) #10 👈 (View in Graphite)
• 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]

Merge activity

• Mar 31, 10:38 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 31, 10:42 PM UTC: Graphite rebased this pull request as part of a merge.
• Mar 31, 10:44 PM UTC: @somanshreddy merged this pull request with Graphite.