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

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]
+}