From 19f69cf1442b77cbcd1b0bd36f6d4527f9bc5fbf Mon Sep 17 00:00:00 2001 From: Somansh Reddy Satish Date: Sat, 11 Jul 2026 03:05:33 +0000 Subject: [PATCH] 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 --- cmd/heygen/builder.go | 21 +-------------------- cmd/heygen/help_flatten.go | 6 +++--- cmd/heygen/hidden_commands_test.go | 6 +++--- internal/command/hidden.go | 25 +++++++++++++++++++++++++ 4 files changed, 32 insertions(+), 26 deletions(-) create mode 100644 internal/command/hidden.go diff --git a/cmd/heygen/builder.go b/cmd/heygen/builder.go index bc8675b..b586aeb 100644 --- a/cmd/heygen/builder.go +++ b/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 diff --git a/cmd/heygen/help_flatten.go b/cmd/heygen/help_flatten.go index 44092f4..90bae3d 100644 --- a/cmd/heygen/help_flatten.go +++ b/cmd/heygen/help_flatten.go @@ -178,7 +178,7 @@ 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. @@ -186,8 +186,8 @@ 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 diff --git a/cmd/heygen/hidden_commands_test.go b/cmd/heygen/hidden_commands_test.go index dfd897b..5c3e10c 100644 --- a/cmd/heygen/hidden_commands_test.go +++ b/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") } } diff --git a/internal/command/hidden.go b/internal/command/hidden.go new file mode 100644 index 0000000..4200b91 --- /dev/null +++ b/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] +}