codegen: resync gen/ from EF 6ced9812

[heygen-rui-bot]

Scope

Surfaces: API / CLI | Module: Brand (kits + glossaries), Video Translate

Stacked on #156 (deprecated command alias framework). Merge #156 first, or merge the stack together.

Summary

Codegen resync from experiment-framework 6ced9812. The automated run hit a fatal naming conflict and deleted gen/; this fixes the conflict, restores the generated commands, and keeps the previously shipped brand-kit list command working as a deprecated alias.

Root cause

In spec 6ced9812, brand kits (GET /v3/brand-kits) and the new brand glossaries (GET /v3/brand-glossaries) both carry the Brand tag. Both have no sub-path segments, so both derived the command name brand list, and codegen aborted with:

error: naming conflict in group "brand": two endpoints map to "list"

Fix

Added two nameOverrides in codegen/grouper.go so each generates as a distinct, nested list command:

• heygen brand kits list (GET /v3/brand-kits)
• heygen brand glossaries list (GET /v3/brand-glossaries)

Regenerated gen/, added curated --human columns for both, and refreshed the brand examples and the e2e test skill.

Because heygen brand-kit list shipped through v0.0.11, the Brand Kit → Brand retag would break it. Registered the old path as a hidden, deprecated alias (using the framework from #156) that delegates to the same handler. The deprecation notice prints to stderr, so stdout stays clean JSON for jq consumers.

What this release contains (vs main)

• New command: heygen brand glossaries list (brand glossaries / custom term translations).
• Group rename: brand-kit → brand; heygen brand-kit list becomes heygen brand kits list. The old path still works via a deprecated alias (removed in v0.1.0).
• Video translate: create/update gain a --brand-glossary-id flag to apply a glossary to a translation.
• Minor: video create aspect-ratio description tweak.

Testing

make test passes (all mocked). Verified on the built binary against the live API: heygen brand kits list and heygen brand glossaries list resolve and paginate; heygen brand-kit list returns data on stdout with the deprecation notice on stderr; brand-kit is hidden from help.

🤖 Generated with Claude Code

[jrusso1020]

APPROVE on merit. Read the alias registration, the brand-kit alias resolution test, and the regenerated gen/brand.go end-to-end. Trusting the rest of the regenerated gen/ files as codegen output.

Note on stamping policy: heygen-rui-bot authored, but this is a codegen-sync PR triggered by Somansh's framework work in #156 (the per-bot-on-explicit-request branch of CLAUDE.md applies — Somansh requested the resync that this PR implements, the hand-curated bits in aliases.go are Somansh's, and the bot-generated gen/ is mechanical output of codegen/grouper.go). Treating as a normal review.

Verified body claims against source

• Stack base: base.ref = "06-01-cli_add_deprecated_command_aliases" (#156's branch). Correctly stacked; merging #156 first or merging the stack together is what the body promises. ✓
• Naming conflict resolved: gen/brand.go exposes BOTH BrandKitsList (Group: "brand", Name: "kits list", Endpoint: /v3/brand-kits) AND BrandGlossariesList (Group: "brand", Name: "glossaries list", Endpoint: /v3/brand-glossaries). The collision the codegen aborted on is now resolved by name-nesting via codegen/grouper.go nameOverrides. ✓
• Alias registration: single entry for brand-kit list → gen.BrandKitsList with RemoveBy: "v0.1.0". ✓
• Alias coverage matches old surface: gen/brand-kit.go was deleted (-46 lines, single Spec worth). So only brand-kit list ever shipped — single alias is the right coverage, not a gap.

Audit per the brief's review angles

1. Backwards compat depth. Single alias for brand-kit list is the complete coverage — verified the prior gen/brand-kit.go only exported one Spec. No sibling brand-kit create / get / delete ever shipped, so there's nothing else to alias. ✓

2. Deprecation message content. Renders as: use "heygen brand kits list" instead; this alias will be removed in v0.1.0. Names both the new path AND the removal version. ✓ Migration is unambiguous.

3. Alias-resolves test (aliases_brandkit_test.go). The test:

• Mocks GET /v3/brand-kits returning a row with brand_kit_id: "bk_1"
• Invokes heygen brand-kit list (the deprecated path)
• Asserts ExitCode == 0 AND stdout contains "bk_1"

This confirms (a) the alias reaches the canonical handler and (c) data lands on stdout. ✓

4. Stderr-routing gap acknowledged in the test docstring. The test comment is explicit:

"The deprecation notice itself is verified in aliases_test.go (leaf.Deprecated is set). Cobra prints it via OutOrStderr, which is os.Stderr in production since main() does not call SetOut; the runCommand harness sets both writers, so notice routing is not asserted here."

That's the same gap I flagged in #156: the load-bearing "stdout clean for jq, notice on stderr" claim is verified by manual smoke-test on the binary (per the body), not by automated test. The chain reasoning is sound — cobra's Deprecated → OutOrStderr() → os.Stderr in production — but it's not pinned by CI. Worth a follow-up that adapts the runCommand harness or adds a separate test that distinguishes the writers and asserts the notice is on stderr only. Either PR is the right place for it.

5. Tab completion. Aliases are Hidden = true, and cobra's default genCompletion skips hidden commands — so heygen brand- will tab-complete to brand (the canonical), not brand-kit. This is the intended behavior, but worth noting it's an additional nudge toward migration: users who tab-completed before now learn the new path.

6. Documentation surface. CONTRIBUTING.md was updated in #156 with the pattern docs. The PR body here lists what's in the release (group rename, new --brand-glossary-id flag, alias removal target). No README update visible — assuming README is API-spec-driven and doesn't carry per-command examples.

Side observation on the spec rename surface

gen/brand.go:BrandGlossariesList.Description mentions the legacy alias brand_voice_id for the brand-glossary-id parameter: "Pass the returned brand_glossary_id (or the legacy alias brand_voice_id)..." That's a parameter-level alias, separate from the command-level alias this PR ships. Cross-checking: gen/video-translate.go should accept either form. If the spec already encodes brand_voice_id as a deprecated parameter alias, that's the EF side's job; nothing for this PR to do.

What works well

• The fix flow (spec rename → codegen abort → manual nameOverrides + alias framework + restored gen/) is the right shape — it preserves the codegen-pure invariant for the new commands while keeping the human migration story alive via the framework.
• The PR body's "What this release contains (vs main)" section is exactly the right artifact for a codegen-sync PR. Reviewer can see the wire surface delta at a glance.
• RemoveBy: "v0.1.0" is concrete — the deprecation notice tells users the removal version, not just "soon."
• Stack story is clean: #156 framework first, #153 consumes. CI green on both.

— Approving on merit. James gates the final stamp on heygen-cli per standing instruction.

— Rames Jusso (pr-review)