Merge pull request #1703 from entireio/experimental-command-gating

feat: gate experimental commands behind build-time visibility flag

Author: gtrrz-victor

.goreleaser.yaml

@@ -26,6 +26,11 @@ builds:
       - -X github.com/entireio/cli/cmd/entire/cli/versioninfo.Commit={{.ShortCommit}}
       - -X github.com/entireio/cli/cmd/entire/cli/telemetry.PostHogAPIKey={{.Env.POSTHOG_API_KEY}}
       - -X github.com/entireio/cli/cmd/entire/cli/telemetry.PostHogEndpoint={{.Env.POSTHOG_ENDPOINT}}
+      # Experimental-command visibility: hide in stable releases, keep visible
+      # in nightly (prerelease) builds. .Prerelease is empty for a stable tag
+      # (vX.Y.Z) and non-empty for a nightly tag (vX.Y.Z-nightly.*). Local
+      # builds carry no stamp and use the package default ("true" = visible).
+      - -X github.com/entireio/cli/cmd/entire/cli/experimental.Visible={{ if .Prerelease }}true{{ else }}false{{ end }}
 
   # git-remote-entire is the git remote helper for entire:// URLs (see
   # cmd/git-remote-entire). A small, dedicated binary shipped alongside

CLAUDE.md

@@ -26,8 +26,18 @@ The visible CLI is organized around a set of noun groups plus a small set of
 top-level verbs. The groups are the canonical home for each verb; legacy
 top-level shortcuts remain functional but hidden, and emit a deprecation hint
 pointing at the canonical group form. Newer experimental command families are
-discoverable through `entire labs` and may remain hidden from root help while
-their canonical paths are still runnable.
+discoverable through `entire labs` and their canonical paths are always
+runnable.
+
+Experimental commands are gated by a build-time visibility flag (the
+`cmd/entire/cli/experimental` package): they are shown — grouped under an
+"Experimental commands:" help section — in developer and nightly builds, and
+hidden in stable release builds. Visibility is toggled by `experimental.Visible`
+(default `"true"`), which GoReleaser stamps `"false"` only on stable tags
+(`.Prerelease` empty); nightly (`vX.Y.Z-nightly.*`) and local builds leave it at
+the default. Register a command as experimental with `experimental.Register(parent,
+child)` instead of `parent.AddCommand(child)`. Gating only controls visibility —
+the commands are always runnable in every build.
 
 - `session` (alias: `sessions`): `list`, `info`, `tokens`, `stop`, `attach`, `adopt`, `resume`, `current`.
   `resume` with a branch arg switches to it and resumes its session; with no arg
@@ -66,9 +76,12 @@ their canonical paths are still runnable.
 - `grant`: manage access grants and org membership — `org`, `project`, and `repo`
   each support `add` / `list` / `remove`
 
-Experimental command families advertised through `entire labs`:
-
-- `tokens`: `profile` (hidden from root help while token diagnostics mature)
+Experimental commands (gated by the build-time visibility flag above — visible
+and grouped under "Experimental commands:" in developer/nightly builds, hidden
+in stable releases, always runnable): `tokens`, `import`, `review`,
+`investigate`, `blame`, `why`, the top-level `search` shortcut, `experts`,
+`runner`, and `checkpoint policy`. `tokens` is also advertised through `entire
+labs`. The canonical `checkpoint search` is not gated and stays visible.
 
 Top-level lifecycle and standalone commands: `enable`, `disable`, `status`,
 `login`, `logout`, `clean`, `version`, `dispatch`, `activity`, `help`,
@@ -91,7 +104,10 @@ one command's current flags; `--json` emits structured output. It is the single
 source of truth the first-turn context injection and the `--agent-help-skill`
 skill point agents at, instead of enumerating a surface that goes stale.
 Hidden commands opt into being advertised here by setting
-`Annotations[agentHelpAnnotation] = "true"` (e.g. `trail`).
+`Annotations[agentHelpAnnotation] = "true"` (e.g. `trail`). Because `agent-help`
+renders live and lists non-hidden commands, the experimental commands appear in
+`agent-help` in developer/nightly builds and are absent in stable releases — the
+advertised surface is build-dependent, matching what `entire help` shows.
 No-channel agents (Cursor, Copilot CLI, Factory Droid, MCP hosts — no
 context-injection channel and no agent-help skill template) reach it without an
 active push. All of them can discover it passively: it is visible in `entire
@@ -107,7 +123,9 @@ Hidden top-level shortcuts (functional, emit a one-line deprecation hint):
 `resume` → `session resume`, `attach` → `session attach`, `explain` →
 `checkpoint explain`, `trace` → `doctor trace`.
 Cobra-native aliases (no hint): `sessions` → `session`, `cp`/`checkpoints` →
-`checkpoint`. The `search` top-level remains hidden without a hint.
+`checkpoint`. The `search` top-level is experimental (see the visibility gate
+above), so it follows the build-dependent visibility rather than being
+unconditionally hidden.
 
 Deprecated top-level commands (functional, print a cobra deprecation message):
 `reset` → `clean`, and `rewind` (no replacement, announces removal — same

cmd/entire/cli/checkpoint_group.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"errors"
 
+	"github.com/entireio/cli/cmd/entire/cli/experimental"
 	"github.com/entireio/cli/cmd/entire/cli/paths"
 	"github.com/spf13/cobra"
 )
@@ -39,7 +40,7 @@ Examples:
 	cmd.AddCommand(newCheckpointResumeCmd())
 	cmd.AddCommand(newExplainCmd())
 	cmd.AddCommand(newCheckpointTokensCmd())
-	cmd.AddCommand(newCheckpointPolicyCmd())
+	experimental.Register(cmd, newCheckpointPolicyCmd()) // 'checkpoint policy' (experimental)
 	cmd.AddCommand(newRewindCmd())
 	cmd.AddCommand(newCheckpointSearchCmd())
 

cmd/entire/cli/experimental/experimental.go

@@ -0,0 +1,50 @@
+// Package experimental gates the visibility of experimental CLI commands.
+//
+// Experimental commands stay fully runnable in every build; this package only
+// controls whether they appear in `entire help`. Developer builds (go build,
+// go run, mise) show them, grouped under an "Experimental commands:" help
+// section. Release builds (GoReleaser) hide them.
+package experimental
+
+import "github.com/spf13/cobra"
+
+// Visible controls whether experimental commands are shown in help. It is
+// stamped by GoReleaser via ldflags
+// (-X github.com/entireio/cli/cmd/entire/cli/experimental.Visible=false)
+// to hide them in shipped binaries. It defaults to "true", so every
+// non-release build (go build, go run, mise) shows them. The commands remain
+// experimental and fully runnable regardless of this flag — it only toggles
+// visibility.
+var Visible = "true"
+
+// IsVisible reports whether experimental commands are shown in help.
+func IsVisible() bool { return Visible != "false" }
+
+// GroupID is the cobra group experimental commands are filed under.
+const GroupID = "experimental"
+
+const groupTitle = "Experimental commands:"
+
+// Register adds child under parent as an experimental command.
+//
+// When experimental commands are visible, child is filed under parent's
+// "Experimental commands:" help group (registering the group on parent once).
+// When hidden, child is marked Hidden and left ungrouped — so release help
+// never carries an empty group header, and cobra never references a group ID
+// that was not registered.
+//
+// Register overrides any Hidden value the child's constructor set, so callers
+// do not need to touch the constructors (including ones in other packages).
+func Register(parent, child *cobra.Command) {
+	if IsVisible() {
+		if !parent.ContainsGroup(GroupID) {
+			parent.AddGroup(&cobra.Group{ID: GroupID, Title: groupTitle})
+		}
+		child.Hidden = false
+		child.GroupID = GroupID
+	} else {
+		child.Hidden = true
+		child.GroupID = ""
+	}
+	parent.AddCommand(child)
+}

cmd/entire/cli/experimental/experimental_test.go

@@ -0,0 +1,100 @@
+package experimental
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// setVisible sets the package-global Visible for the duration of the test and
+// restores it afterward. Mutating a global means these tests cannot run in
+// parallel.
+func setVisible(t *testing.T, v string) {
+	t.Helper()
+	prev := Visible
+	Visible = v
+	t.Cleanup(func() { Visible = prev })
+}
+
+func TestIsVisible(t *testing.T) {
+	tests := []struct {
+		value string
+		want  bool
+	}{
+		{"true", true},
+		{"false", false},
+		{"", true},         // only the literal "false" hides
+		{"anything", true}, // any non-"false" stamp is treated as visible
+	}
+	for _, tt := range tests {
+		t.Run(tt.value, func(t *testing.T) {
+			setVisible(t, tt.value)
+			if got := IsVisible(); got != tt.want {
+				t.Fatalf("IsVisible() with Visible=%q = %v, want %v", tt.value, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRegister_Visible(t *testing.T) {
+	setVisible(t, "true")
+
+	parent := &cobra.Command{Use: "parent"}
+	child := &cobra.Command{Use: "child", Hidden: true} // constructor-set Hidden must be overridden
+	Register(parent, child)
+
+	if child.Hidden {
+		t.Error("child should be visible when experimental commands are visible")
+	}
+	if child.GroupID != GroupID {
+		t.Errorf("child.GroupID = %q, want %q", child.GroupID, GroupID)
+	}
+	if !parent.ContainsGroup(GroupID) {
+		t.Error("parent should have the experimental group registered")
+	}
+	if len(parent.Commands()) != 1 || parent.Commands()[0] != child {
+		t.Error("child should be added to parent")
+	}
+}
+
+func TestRegister_Hidden(t *testing.T) {
+	setVisible(t, "false")
+
+	parent := &cobra.Command{Use: "parent"}
+	child := &cobra.Command{Use: "child"}
+	Register(parent, child)
+
+	if !child.Hidden {
+		t.Error("child should be hidden when experimental commands are hidden")
+	}
+	if child.GroupID != "" {
+		t.Errorf("child.GroupID = %q, want empty (no group referenced in release)", child.GroupID)
+	}
+	if parent.ContainsGroup(GroupID) {
+		t.Error("parent should not register the experimental group in release builds")
+	}
+	if len(parent.Commands()) != 1 || parent.Commands()[0] != child {
+		t.Error("child should still be added to parent")
+	}
+}
+
+// TestRegister_MultipleShareOneGroup verifies the group is registered once even
+// when several experimental commands are registered under the same parent.
+func TestRegister_MultipleShareOneGroup(t *testing.T) {
+	setVisible(t, "true")
+
+	parent := &cobra.Command{Use: "parent"}
+	Register(parent, &cobra.Command{Use: "a"})
+	Register(parent, &cobra.Command{Use: "b"})
+
+	groups := parent.Groups()
+	count := 0
+	for _, g := range groups {
+		if g.ID == GroupID {
+			count++
+		}
+	}
+	if count != 1 {
+		t.Errorf("experimental group registered %d times, want 1", count)
+	}
+}

cmd/entire/cli/experimental_wiring_test.go

@@ -0,0 +1,117 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/entireio/cli/cmd/entire/cli/experimental"
+	"github.com/spf13/cobra"
+)
+
+// experimentalRootCommands are the top-level commands gated behind the
+// experimental visibility flag. Names match cobra's Command.Name() (the first
+// token of Use).
+var experimentalRootCommands = []string{
+	"tokens", "import", "review", "investigate",
+	"blame", "why", "search", "experts", "runner",
+}
+
+// withVisible sets the experimental visibility flag for the test and restores
+// it afterward. Because it mutates a package global, callers must not run in
+// parallel.
+func withVisible(t *testing.T, v string) {
+	t.Helper()
+	prev := experimental.Visible
+	experimental.Visible = v
+	t.Cleanup(func() { experimental.Visible = prev })
+}
+
+func findCommand(parent *cobra.Command, name string) *cobra.Command {
+	for _, c := range parent.Commands() {
+		if c.Name() == name {
+			return c
+		}
+	}
+	return nil
+}
+
+// checkpointPolicy returns the `checkpoint policy` command.
+func checkpointPolicy(t *testing.T, root *cobra.Command) *cobra.Command {
+	t.Helper()
+	cp := findCommand(root, "checkpoint")
+	if cp == nil {
+		t.Fatal("checkpoint command not found on root")
+	}
+	return findCommand(cp, "policy")
+}
+
+// TestExperimental_VisibleInDevBuild verifies that, in a developer build
+// (Visible defaults to "true"), the experimental commands are shown and filed
+// under the experimental group. Cannot use t.Parallel — mutates a global.
+func TestExperimental_VisibleInDevBuild(t *testing.T) {
+	withVisible(t, "true")
+
+	root := NewRootCmd()
+
+	if !root.ContainsGroup(experimental.GroupID) {
+		t.Fatal("root should register the experimental group in a dev build")
+	}
+	for _, name := range experimentalRootCommands {
+		cmd := findCommand(root, name)
+		if cmd == nil {
+			t.Errorf("%q not found on root", name)
+			continue
+		}
+		if cmd.Hidden {
+			t.Errorf("%q should be visible in a dev build", name)
+		}
+		if cmd.GroupID != experimental.GroupID {
+			t.Errorf("%q GroupID = %q, want %q", name, cmd.GroupID, experimental.GroupID)
+		}
+	}
+
+	policy := checkpointPolicy(t, root)
+	if policy == nil {
+		t.Fatal("checkpoint policy not found")
+	}
+	if policy.Hidden {
+		t.Error("checkpoint policy should be visible in a dev build")
+	}
+	if policy.GroupID != experimental.GroupID {
+		t.Errorf("checkpoint policy GroupID = %q, want %q", policy.GroupID, experimental.GroupID)
+	}
+}
+
+// TestExperimental_HiddenInReleaseBuild verifies that, when GoReleaser stamps
+// Visible=false, the experimental commands are hidden, carry no group, and the
+// empty experimental group is never registered (so release help is unchanged).
+// Cannot use t.Parallel — mutates a global.
+func TestExperimental_HiddenInReleaseBuild(t *testing.T) {
+	withVisible(t, "false")
+
+	root := NewRootCmd()
+
+	if root.ContainsGroup(experimental.GroupID) {
+		t.Error("root should not register the experimental group in a release build")
+	}
+	for _, name := range experimentalRootCommands {
+		cmd := findCommand(root, name)
+		if cmd == nil {
+			t.Errorf("%q not found on root", name)
+			continue
+		}
+		if !cmd.Hidden {
+			t.Errorf("%q should be hidden in a release build", name)
+		}
+		if cmd.GroupID != "" {
+			t.Errorf("%q GroupID = %q, want empty in a release build", name, cmd.GroupID)
+		}
+	}
+
+	policy := checkpointPolicy(t, root)
+	if policy == nil {
+		t.Fatal("checkpoint policy not found")
+	}
+	if !policy.Hidden {
+		t.Error("checkpoint policy should be hidden in a release build")
+	}
+}

cmd/entire/cli/experts_test.go

@@ -12,6 +12,8 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/entireio/cli/cmd/entire/cli/experimental"
+
 	"charm.land/lipgloss/v2"
 	"github.com/entireio/cli/cmd/entire/cli/palette"
 	"github.com/entireio/cli/cmd/entire/cli/paths"
@@ -116,7 +118,7 @@ func expertsSuccessBody() string {
 }`
 }
 
-func TestExpertsCommandIsHiddenAndListedInLabs(t *testing.T) {
+func TestExpertsCommandIsExperimentalAndListedInLabs(t *testing.T) {
 	root := NewRootCmd()
 	cmd, _, err := root.Find([]string{"experts"})
 	if err != nil {
@@ -125,8 +127,10 @@ func TestExpertsCommandIsHiddenAndListedInLabs(t *testing.T) {
 	if cmd.Name() != "experts" {
 		t.Fatalf("found command %q, want experts", cmd.Name())
 	}
-	if !cmd.Hidden {
-		t.Fatal("experts command should be hidden while in labs")
+	// Gated as experimental: visible and grouped in developer builds
+	// (the default test build), hidden in shipped releases.
+	if cmd.GroupID != experimental.GroupID {
+		t.Fatalf("experts GroupID = %q, want %q (experimental)", cmd.GroupID, experimental.GroupID)
 	}
 	if !strings.Contains(labsOverview(), "entire experts") {
 		t.Fatalf("labs overview missing experts:\n%s", labsOverview())