cli: share hidden-command list via command.Spec.IsHidden so docs honor it (#213)

cli: move hidden-command list to command package as shared source of truth

The hidden-command decision (pre-launch endpoints omitted from --help) lived in
cmd/heygen (package main), so it was unreachable to anything outside the CLI
binary. The EF docs generator, which imports gen and iterates raw specs, could
not honor it and would publish pre-launch commands (e.g. `asset search`) to the
public docs.

Move the list + predicate to internal/command as Spec.IsHidden() so both the
runtime builder (hides from --help) and the docs generator (omits from public
docs) share one source of truth. Behavior in the CLI is unchanged.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: somanshreddy

cmd/heygen/builder.go

@@ -21,25 +21,6 @@ import (
 	"golang.org/x/term"
 )
 
-// hiddenCommands lists generated commands that remain fully functional but are omitted from
-// `--help` listings (Cobra Hidden) — for endpoints that exist in the OpenAPI spec but aren't
-// announced yet (still under development). The spec is the source of truth for what exists; this
-// hard-coded list is the CLI-side decision of what's discoverable. A hidden command still runs if
-// invoked directly, and its own `--help` works. Keyed by "METHOD /path" so it survives command
-// renames (e.g. an x-cli-action verb change).
-// To surface a command in --help, remove its entry here. This list is transitional, for endpoints
-// under development pre-launch; for a permanent hidden-from-help posture, plumb an `x-cli-hidden`
-// extension from the OpenAPI spec instead of hard-coding it here, so the spec stays the source of
-// truth.
-var hiddenCommands = map[string]bool{
-	"GET /v3/assets/search": true, // asset search — pre-launch, not yet announced
-}
-
-// isHiddenCommand reports whether the command for this spec should be omitted from help listings.
-func isHiddenCommand(spec *command.Spec) bool {
-	return hiddenCommands[strings.ToUpper(spec.Method)+" "+spec.Endpoint]
-}
-
 // buildCobraCommand creates a Cobra command from a command.Spec.
 // It registers typed flags, sets up positional arg validation, and wires
 // RunE to build an Invocation and execute it through the HTTP client.
@@ -56,7 +37,7 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 		Short:   spec.Summary,
 		Long:    description,
 		Example: strings.Join(spec.Examples, "\n"),
-		Hidden:  isHiddenCommand(spec),
+		Hidden:  spec.IsHidden(),
 		Args: func(cmd *cobra.Command, args []string) error {
 			if isSchemaRequest(cmd) {
 				return nil

cmd/heygen/help_flatten.go

@@ -178,16 +178,16 @@ func isLeafCommand(cmd *cobra.Command) bool {
 }
 
 // hideEmptyGroups hides any group command left with no visible children — e.g. an intermediate
-// group whose only leaf is in hiddenCommands. Without this, such a group reads as a leaf to the
+// group whose only leaf is hidden (see command.Spec.IsHidden). Without this, such a group reads as a leaf to the
 // flattened help and renders as a phantom entry. Runs bottom-up so a group whose children all
 // become hidden is itself hidden. The underlying command stays reachable and runnable; only its
 // help listing is suppressed.
 func hideEmptyGroups(cmd *cobra.Command) {
 	for _, child := range cmd.Commands() {
 		hideEmptyGroups(child)
 	}
-	// A command with subcommands but no visible ones is an empty group (e.g. its only leaf is in
-	// hiddenCommands). Hide it. Leaves have no subcommands, so they're unaffected; intermediate
+	// A command with subcommands but no visible ones is an empty group (e.g. its only leaf is
+	// hidden). Hide it. Leaves have no subcommands, so they're unaffected; intermediate
 	// groups carry a help-showing RunE, so we must not gate on Runnable().
 	if cmd.HasSubCommands() && len(visibleChildren(cmd)) == 0 {
 		cmd.Hidden = true

cmd/heygen/hidden_commands_test.go

@@ -9,16 +9,16 @@ import (
 
 func TestIsHiddenCommand(t *testing.T) {
 	hidden := &command.Spec{Group: "asset", Name: "search", Method: "GET", Endpoint: "/v3/assets/search"}
-	if !isHiddenCommand(hidden) {
+	if !hidden.IsHidden() {
 		t.Error("GET /v3/assets/search should be hidden")
 	}
 	// Method match is case-insensitive (specs may carry a lowercased method).
 	lower := &command.Spec{Group: "asset", Name: "search", Method: "get", Endpoint: "/v3/assets/search"}
-	if !isHiddenCommand(lower) {
+	if !lower.IsHidden() {
 		t.Error("method match should be case-insensitive")
 	}
 	visible := &command.Spec{Group: "video", Name: "list", Method: "GET", Endpoint: "/v3/videos"}
-	if isHiddenCommand(visible) {
+	if visible.IsHidden() {
 		t.Error("GET /v3/videos should not be hidden")
 	}
 }

internal/command/hidden.go

@@ -0,0 +1,25 @@
+package command
+
+import "strings"
+
+// hiddenEndpoints lists commands that remain fully functional but are omitted from `--help`
+// listings (Cobra Hidden) and from generated docs — for endpoints that exist in the OpenAPI spec
+// but aren't announced yet (still under development). The spec is the source of truth for what
+// exists; this hand-maintained list is the CLI-side decision of what's discoverable. A hidden
+// command still runs if invoked directly, and its own `--help` works. Keyed by "METHOD /path" so
+// it survives command renames (e.g. an x-cli-action verb change).
+//
+// This list lives here (not in the builder) so every consumer of a Spec shares one source of
+// truth: the runtime builder hides it from `--help`, and the docs generator omits it from public
+// docs. To surface a command, remove its entry here. This list is transitional, for endpoints
+// under development pre-launch; for a permanent hidden posture, plumb an `x-cli-hidden` extension
+// from the OpenAPI spec so the spec stays the source of truth.
+var hiddenEndpoints = map[string]bool{
+	"GET /v3/assets/search": true, // asset search — pre-launch, not yet announced
+}
+
+// IsHidden reports whether the command for this spec should be omitted from help listings and
+// generated docs.
+func (s Spec) IsHidden() bool {
+	return hiddenEndpoints[strings.ToUpper(s.Method)+" "+s.Endpoint]
+}