cmd: add CLI-surface description overrides overlay (API-488)

[somanshreddy]

Scope

Surfaces: CLI | Module: Output/Builder

Description

The CLI generates its command surface from HeyGen's OpenAPI spec. A handful of spec descriptions are written in raw HTTP terms — poll via GET /v3/videos/{id}, Pass to POST /v3/video-agents, Use GET /v3/video-translations/languages — which mislead a CLI user, who drives the API with commands and flags rather than raw HTTP calls. This PR adds a sparse, CLI-authored description overlay that reframes those few cases (e.g. "poll with heygen video get <video-id>, or pass --wait").

Runtime overlay, not a spec/codegen change. command.Spec is generated and immutable (AGENTS.md), so the overlay is resolved at command-build time in buildCobraCommand and never mutates the Spec. It mirrors the existing DefaultColumns curated-lookup pattern: hand-written data in internal/clidesc (an importable package so the builder and tooling share one source of truth), looked up by Spec and applied as the Cobra command/flag/schema text is built. Putting this in gen/ was a non-starter (regenerated and wiped by make generate); mutating the Spec at runtime is explicitly forbidden.

Keyed by (Endpoint, Method). That pair uniquely identifies a Spec, so a key survives a command rename in the generated surface. A test asserts every override key matches a real generated command, so a stale key fails loudly on the next resync.

Precedence: overlay wins; everything else falls through. Summary overrides Short, Description overrides Long, Flags[name] overrides a flag's usage, and Fields[json_name] overrides a schema property's description in --request-schema/--response-schema output (applied to a copy of the schema JSON at render time; the Spec's schema string is untouched). Any field left empty/absent falls through to the generated spec text unchanged. Most commands have no override.

An earlier spec-extension approach (x-cli-description, #167) was considered and closed: the API spec (EF) will not own CLI-surface descriptions, so this runtime overlay is the single mechanism. Default values (e.g. aspect_ratio) remain owned by the existing x-cli-default extension.

Override coverage

21 of the 22 reviewed overrides landed: 5 operation descriptions, 5 flag-help reframes, 11 schema-field reframes. One was dropped — ExternalCreateVideoAgentSessionResponse.video_id (the GET /v2/videos/{video_id} polling field): it does not exist anywhere in the generated surface (MCP-only /v2 model), as the draft anticipated. One draft item (GenerateVideoResponse.video_translation_id) was re-mapped: the CLI's video-translate create response actually returns video_translation_ids (plural array, no poll text); the singular video_translation_id poll field lives on video-translate proofreads generate, which is where the override was keyed. The look_id positional-arg reframe was not applied as a standalone entry because positional-arg help is never rendered in Cobra --help; the same guidance is already delivered via the AvatarLookItem.id response-schema field, which is overridden.

Flag-help overrides use plain quotes rather than backticks: Cobra/pflag treats the first backtick-delimited token in a flag's usage string as the value placeholder (it would render --style-id heygen video-agent styles list instead of --style-id string). Backticks are kept in Summary/Description and schema fields, where they render fine.

Testing

make build and make test pass. make lint is currently broken on clean main (golangci-lint built for go1.23 vs the go1.25 toolchain) — unrelated to this change; ran gofmt -l (clean) and go vet ./... (clean) as substitutes.

New tests in cmd/heygen/descriptions_test.go cover: operation Long override applied (and HTTP text gone); flag-usage override applied while a sibling flag falls through; response-schema field override applied while a sibling field is untouched; a fully non-overridden command keeping its generated Short/Long/flag text; the resolver helpers directly (override-wins and fall-through, including malformed/no-op schema); and a guard that every override key maps to a real generated command.