cli: share hidden-command list via command.Spec.IsHidden so docs honor it

[somanshreddy]

Scope

Surfaces: CLI + docs pipeline | Module: Codegen / command surface

Summary

Pre-launch commands the CLI deliberately hides from --help (currently asset search) were about to leak into the public /commands docs, because the docs generator had no way to see the CLI's hidden set. This moves that set to a shared source of truth both the CLI runtime and the docs generator honor.

Root cause

The hidden-command list and its predicate lived in cmd/heygen (package main). Anything outside the CLI binary, including the EF docs generator that imports the gen package and iterates raw specs, could not reach it, so it treated every generated command as public.

Fix

Moved the list + predicate to internal/command as a value-receiver method Spec.IsHidden(). The builder now sets Cobra Hidden via spec.IsHidden(). A value receiver is deliberate: it lands in the method set of both Spec and *Spec, so a package that imports only gen can call s.IsHidden() on the *command.Spec values gen exposes without importing internal/command. CLI behavior is unchanged — the same map, the same case-insensitive METHOD /path keying.

The companion EF change (docs generator skipping hidden specs) depends on this method existing on the default branch, so this merges first.

Testing

go build, make lint (0 issues), go test ./cmd/heygen ./internal/command (all pass). Runtime-verified: asset search is absent from asset --help, still runnable via asset search --help, and empty-group hiding still works. Also ran the patched EF dumper against this branch to confirm /v3/assets/search is excluded while the real asset commands remain.

[jrusso1020]

Reviewed at 19f69cf1. Small, well-scoped extraction — moves the CLI's hidden-command predicate from the private cmd/heygen binary into internal/command so both the runtime and the docs generator share one source of truth.

Verified

• Move, not duplicate: the old hiddenCommands map + isHiddenCommand function are FULLY REMOVED from cmd/heygen/builder.go (grep-clean — no dead code). The new home in internal/command/hidden.go carries the same fixture (GET /v3/assets/search) and the same strings.ToUpper(Method) + " " + Endpoint case-insensitive keying. Runtime behavior byte-identical.
• Value-receiver method (s Spec) IsHidden() bool — as the body claims, this lands in the method set of both Spec and *Spec per Go method-set rules, so a package that imports only gen (e.g. EF's cli_docs_dump/main.go) can call s.IsHidden() on a *command.Spec value without needing to import internal/command. That's the key architectural decision this PR makes correctly.
• Cobra builder wiring: Hidden: spec.IsHidden() at builder.go:40 — was isHiddenCommand(spec), semantically equivalent.
• Empty-group hiding preserved: help_flatten.go changes are comment-only (hiddenCommands variable → command.Spec.IsHidden). The hideEmptyGroups walk still runs bottom-up and hides any group whose only leaf is hidden.
• Test coverage preserved + updated: hidden_commands_test.go renames 3 assertions from isHiddenCommand(x) to x.IsHidden(). Still exercises (a) uppercase METHOD (hidden), (b) lowercase METHOD (verify case-insensitive), (c) visible endpoint (not hidden). Discipline preserved.

CI

govulncheck red — pre-existing on main (same failure signature at 2026-07-11T00:07:40Z on main/HEAD), not introduced by this PR. All the checks touched by this diff (build, lint, unit tests) are green.

Non-blocking notes

• Hidden set is transitional: Somansh's inline docstring names this correctly — the long-term move is x-cli-hidden in the OpenAPI spec so the spec stays the source of truth. Fine to keep the hand-maintained list for now; low-cost future change.
• Merge ordering: the companion EF#41881 correctly notes this must merge first (the dumper compiles against heygen-cli's default branch during the sync job, so s.IsHidden() must exist on main first, else the docs-sync workflow would fail at compile time).

Verdict

Clean refactor with the right architectural choice (value-receiver → cross-package callable). Ready to merge, holding stamp per protocol until you explicitly ask.

— Rames Jusso