feat(gen): add /v3/audio/sounds CLI command (manual codegen resync)

[jrusso1020]

What

Manual codegen resync of gen/ from experiment-framework master after #38295 + #38296 merged (the new GET /v3/audio/sounds semantic background-music search endpoint).

• gen/audio.go — new heygen audio sounds list command (group audio).
• gen/registry.go — registers the audio group.
• codegen/examples/audio.yaml — usage examples (manual; clears the codegen "missing examples" warning).
• gen/video.go / gen/webhook.go — small backlog the auto-sync didn't pick up.

go build ./... passes.

Why manual

The sync-cli-codegen.yml workflow in EF cannot push to this repo: its bot commits are unsigned, and the org-wide "Enforce Signed Commits" ruleset rejects them (GH013: Commits must have verified signatures). It's been failing on every recent EF spec change for this reason, not just this one. This PR is created manually with a signed commit as an interim unblock.

Follow-up (separate): fix the codegen bot so its commits are signed (e.g., commit via the GitHub API / a signing App), or grant it a ruleset bypass — otherwise every future api-spec change needs a manual sync like this.

🤖 Generated with Claude Code

[somanshreddy]

@jrusso1020 thanks for the manual sync. I found a few issues that should be addressed before merging.

Findings

P2: --all is documented but not implemented

codegen/examples/audio.yaml:7 / gen/audio.go:20

The new help example documents:

heygen audio sounds list --query 'calm ambient piano' --all

But no --all flag exists. Running it returns:

{"error":{"code":"usage_error","message":"unknown flag: --all"}}

This also conflicts with the repo rule that pagination is manual via --token, not a generic --all mode. Please replace this example with a manual pagination example using --token <next_token> and regenerate.

P2: --min-score range is advertised but not enforced

gen/audio.go:60

--min-score advertises a 0-1 bound and generated metadata includes Min: intPtr(0) / Max: intPtr(1), but runtime validation only enforces min/max for int flags. Since this flag is float64, values like --min-score 2 are sent to the API instead of returning a local usage error with exit code 2.

This is a shared validator gap exposed by the new command. Please either fix float min/max validation or avoid generating unenforced bounds.

P3: New top-level audio group is missing from README command table

gen/registry.go:17 registers the new audio group, but README.md still omits it from the command table.

The repo instructions call out README updates for new command groups.

P3: New list command is missing human columns and E2E smoke coverage

gen/audio.go:16

This adds a new paginated list command, but cmd/heygen/columns.go has no curated audio/sounds list human columns, and .claude/skills/e2e-cli-test/SKILL.md has no Phase 2 smoke test for it.

Without curated columns, --human falls back to every response field, including long audio_url values. For the E2E skill, this should likely be added as a read-only list smoke command, e.g. with --query ... --limit 1.

Verification

I ran:

go test ./cmd/heygen ./internal/command ./codegen
go test ./...
go run ./cmd/heygen audio sounds list --query "calm ambient piano" --all

The tests passed. The documented --all example fails with unknown flag: --all.

[jrusso1020]

Thanks @somanshreddy — all four addressed in aa5c941:

P2 — --all example doesn't exist: Replaced with manual cursor pagination and regenerated:

heygen audio sounds list --query 'calm ambient piano' --token <next_token>

Matches the repo's manual-pagination rule (no generic --all).

P2 — --min-score float bounds not enforced: Fixed the shared validator gap — validateFlag now enforces min/max for float64 flags (it only handled int). --min-score 2 now returns a usage error (exit 2) instead of being sent to the API. Added TestBuildInvocation_FloatMinMaxValidation covering below-min / above-max / fractional-in-range.

P3 — README command table: Added the audio group row.

P3 — human columns + E2E smoke: Added curated audio/sounds list columns (id/name/duration/score, omitting the long audio_url) in cmd/heygen/columns.go, and a Phase 2 read-only smoke command (audio sounds list --query "calm ambient piano" --limit 1) in the e2e-cli-test skill.

Verified locally: go test ./... passes in a clean auth env, go vet clean, make generate STRICT=1 clean (no missing-examples warning).

Side note unrelated to this PR: the reason this is a manual sync is that sync-cli-codegen.yml's bot commits are unsigned and rejected by the org "Enforce Signed Commits" ruleset (GH013) — tracked separately so future spec syncs aren't manual.

[somanshreddy]

@jrusso1020 re-reviewed the latest commit. The issues from my previous review are addressed:

• The generated examples/help no longer document the nonexistent --all flag and now show manual --token pagination.
• --min-score now returns a local usage error for out-of-range values like 2.
• The new audio group is listed in the README command table.
• audio/sounds list has curated --human columns.
• The E2E skill includes a read-only smoke command for the new list endpoint.

I also reran:

go test ./cmd/heygen ./internal/command ./codegen
go test ./...
HEYGEN_NO_ANALYTICS=1 go run ./cmd/heygen audio sounds list --help

All passed / looked correct.

One non-blocking follow-up: the shared float validator still relies on integer Min/Max metadata, so it does not fully represent fractional bounds on existing float flags such as voice speech create --speed 0.5-2.0. That is broader than this PR and does not block the new audio command's 0-1 bound.