feat: waving flag while requests are in flight

Closes half of #52: a rippling Flagsmith flag on stderr for any request slow
enough that a user would otherwise wonder whether the CLI had hung.

It is gated on the CLI's own `loading_animation` flag, which means the CLI now
evaluates flags about itself, through the same SDK `flagsmith evaluate` uses.
Those flags live in Flagsmith's project, not the user's, so `internal/selfflags`
is deliberately separate from everything the user configures: a baked-in
client-side key (public by construction — every browser SDK ships one) always
evaluated against Edge, never `--sdk-api-url` or `flagsmith.json`.

It evaluates as an identity rather than taking the environment defaults, so a
feature can be aimed at some installations and not others. The targeting key is a
random id created on first use and kept in the config directory — not the cache,
which is disposable, and re-rolling it would move an installation to the other
side of every percentage rollout. Random rather than derived from the user or the
machine: it has to be stable, and nothing more. Traits carry what a segment could
usefully target — `cli.version`, `os`, `arch`, `is_saas`, and `organisation.id`
when the context named one by id. Never by name: resolving that costs a request,
and an organisation's name is its company's. The identity is stored rather than
transient, so it can also be targeted from the dashboard — which does mean one
identity per installation in the CLI's own project.

The read path never touches the network, because a spinner cannot wait on the
flag that decides whether to draw it. `Enabled` answers from a cache on disk and
`Refresh` fills it in the background for the next invocation — abandoned if the
process exits first, which only happens on commands too fast to have animated
anything. A cold cache is off, matching how the flag was created.

Nothing is evaluated when the answer cannot matter: no terminal on stderr (a
pipe or a CI log), `FLAGSMITH_DEBUG` (whose trace line would fight a repainting
one), or `FLAGSMITH_ANIMATION` set either way — an explicit local answer is also
the opt-out for anyone who would rather the CLI did not ask about itself.

The flag is drawn by wrapping the shared client's transport, so every request is
covered without touching call sites, refcounted so concurrent requests raise one
flag between them. It then *stands* between requests rather than being erased
after each, or a command making several in a row would flicker; the frame counter
is atomic and never reset, so the ripple resumes mid-wave. That needs an owner
for the line: `Guard` wraps cobra's writers so the command's own output takes it
back, prompts release it explicitly (huh in raw mode bypasses cobra), and Execute
releases once more for a command that prints nothing. The cursor is hidden while
a flag flies and restored by both of those paths and by a signal handler —
hiding it outlives the process, so an interrupt must not leave a terminal with no
cursor and no clue.

Braille gives four rows to ripple through per line of text. The cloth is five
cells of a gale — a wave six dots long against ten of flag — sampled at twenty
phases with the stalls stripped, since rounding to whole dot rows makes five of
them repeat their predecessor and a repeated frame reads as a hitch. No column
moves more than one dot row between frames, which is the difference between
rippling and flickering, and a test decodes the glyphs to hold the table to it.
Each cell is lit by how high the cloth flies there, so the crests carry the light
as the wave travels; colour is a function of the shape, not of the clock.

lipgloss and termenv move from indirect to direct requirements — both were
already in the module graph via huh, so go.sum is untouched.

beep boop

Author: khvn26

go.mod

@@ -5,8 +5,10 @@ go 1.26
 require (
 	github.com/Flagsmith/flagsmith-go-client/v5 v5.1.0
 	github.com/charmbracelet/huh v1.0.0
+	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/fatih/color v1.19.0
 	github.com/itchyny/gojq v0.12.19
+	github.com/muesli/termenv v0.16.0
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.9
@@ -23,7 +25,6 @@ require (
 	github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 // indirect
 	github.com/charmbracelet/bubbletea v1.3.6 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.9.3 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
 	github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect
@@ -46,7 +47,6 @@ require (
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
-	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/ohler55/ojg v1.28.1 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect

internal/cmd/animation.go

@@ -0,0 +1,111 @@
+package cmd
+
+import (
+	"context"
+	"io"
+	"os"
+	"strconv"
+	"time"
+
+	"golang.org/x/term"
+
+	"github.com/Flagsmith/flagsmith-cli/v2/internal/selfflags"
+	"github.com/Flagsmith/flagsmith-cli/v2/internal/spinner"
+)
+
+// envAnimation answers loading_animation locally, in either direction.
+const envAnimation = "FLAGSMITH_ANIMATION"
+
+// selfFlagTimeout bounds the background evaluation. It is generous: nothing
+// waits on it, and the only cost of it running long is a goroutine the process
+// may exit out from under.
+const selfFlagTimeout = 10 * time.Second
+
+// stderrIsTTY reports whether there is a terminal to animate on; tests stub it.
+var stderrIsTTY = func() bool {
+	return term.IsTerminal(int(os.Stderr.Fd()))
+}
+
+// animation decides whether requests raise a waving flag, and whether asking
+// Flagsmith could change that answer next time.
+//
+// Both are false when the answer cannot matter: a pipe or a CI log has nothing
+// to animate, and FLAGSMITH_DEBUG puts a trace line on stderr for every request,
+// which a repainting flag would fight over. A local answer is also a final one —
+// setting FLAGSMITH_ANIMATION is how someone who would rather the CLI did not
+// ask about itself says so.
+func animation() (draw, ask bool) {
+	if !stderrIsTTY() || envBool("FLAGSMITH_DEBUG") {
+		return false, false
+	}
+	if os.Getenv(envAnimation) != "" {
+		return envBool(envAnimation), false
+	}
+	return selfflags.Enabled(selfflags.LoadingAnimation), true
+}
+
+// The flag for this invocation, and whether its value is worth refreshing. Both
+// are decided once, in Execute: the decision reads a file and installs a signal
+// handler, neither of which belongs in a code path a test may run in-process
+// hundreds of times.
+var (
+	activeFlag  *spinner.Spinner
+	refreshWant bool
+)
+
+// animationOut is where the flag is drawn: stderr, which is where progress
+// belongs. A var so tests can watch it.
+var animationOut io.Writer = os.Stderr
+
+// startAnimation gives the flag the terminal, when there is one and it is
+// wanted. cobra's writers are wrapped because the flag stands between requests
+// rather than being erased after each: the command's own output is what takes the
+// line back, whenever it has something to print.
+func startAnimation() {
+	draw, ask := animation()
+	refreshWant = ask
+	if !draw {
+		return
+	}
+	activeFlag = spinner.New(animationOut)
+	// Both writers, or a standing flag outlives whichever one the command happens
+	// to print through.
+	rootCmd.SetOut(activeFlag.Guard(os.Stdout))
+	rootCmd.SetErr(activeFlag.Guard(os.Stderr))
+}
+
+// releaseLine takes the line back from a standing flag. Called before anything
+// that writes to the terminal without going through cobra — an interactive
+// prompt — and once more before the process exits, for a command that printed
+// nothing at all.
+func releaseLine() {
+	if activeFlag != nil {
+		activeFlag.Release()
+	}
+}
+
+// refreshSelfFlags evaluates the CLI's own flags in the background, for the next
+// invocation to read. It builds its own client rather than sharing the command's,
+// so the request cannot raise a flag about itself, and is abandoned if the
+// process exits first — which only happens on commands too fast to have animated
+// anything.
+func refreshSelfFlags() {
+	aud := selfAudience
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), selfFlagTimeout)
+		defer cancel()
+		selfflags.Refresh(ctx, aud) //nolint:errcheck // best-effort, and nothing to report
+	}()
+}
+
+// selfAudience is what the resolved context contributes to the CLI's own
+// evaluation.
+var selfAudience selfflags.Audience
+
+func noteAudience(pc *projectContext) {
+	aud := selfflags.Audience{IsSaas: pc.apiURL() == defaultAPIURL}
+	if id, ok := pc.Organisation.Value.(int); ok {
+		aud.Organisation = strconv.Itoa(id)
+	}
+	selfAudience = aud
+}

internal/cmd/client.go

@@ -25,6 +25,15 @@ var (
 func sharedHTTPClient() *http.Client {
 	httpClientOnce.Do(func() {
 		httpClientMemo = httpx.New(userAgent())
+		if activeFlag != nil {
+			httpClientMemo.Transport = activeFlag.Wrap(httpClientMemo.Transport)
+		}
+		// Reaching for the client is the CLI committing to network I/O, which is
+		// the only time the flag's value is worth evaluating: a command that never
+		// leaves the machine does not ask about itself either.
+		if refreshWant {
+			refreshSelfFlags()
+		}
 	})
 	return httpClientMemo
 }

internal/cmd/cmd_test.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -7625,3 +7626,233 @@ func TestRefreshPersistsToKeychain(t *testing.T) {
 		t.Errorf("AccessToken = %q, want the refreshed token persisted", creds.AccessToken)
 	}
 }
+
+// fakeStderrTTY makes the animation think it has a terminal to draw on.
+func fakeStderrTTY(t *testing.T, on bool) {
+	t.Helper()
+	orig := stderrIsTTY
+	stderrIsTTY = func() bool { return on }
+	t.Cleanup(func() { stderrIsTTY = orig })
+}
+
+// cacheSelfFlag writes the CLI's own flag cache as selfflags reads it, standing
+// in for a refresh that already happened. The shape is pinned in that package.
+func cacheSelfFlag(t *testing.T, name string, enabled bool) {
+	t.Helper()
+	tmp := t.TempDir()
+	t.Setenv("HOME", tmp)
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(tmp, ".cache"))
+	t.Setenv("LocalAppData", tmp)
+	dir, err := os.UserCacheDir()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(dir, "flagsmith"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	body := fmt.Sprintf(`{"flags":{%q:%t},"fetchedAt":%q}`, name, enabled, time.Now().Format(time.RFC3339))
+	if err := os.WriteFile(filepath.Join(dir, "flagsmith", "selfflags.json"), []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnimationDecision(t *testing.T) {
+	t.Run("without a terminal there is nothing to draw and nothing to ask", func(t *testing.T) {
+		// Given
+		cacheSelfFlag(t, "loading_animation", true)
+		fakeStderrTTY(t, false)
+
+		// When
+		draw, ask := animation()
+
+		// Then a piped or CI run neither animates nor evaluates
+		if draw || ask {
+			t.Errorf("animation() = (%t, %t), want (false, false)", draw, ask)
+		}
+	})
+
+	t.Run("FLAGSMITH_DEBUG keeps stderr to itself", func(t *testing.T) {
+		// Given
+		cacheSelfFlag(t, "loading_animation", true)
+		fakeStderrTTY(t, true)
+		t.Setenv("FLAGSMITH_DEBUG", "1")
+
+		// When
+		draw, ask := animation()
+
+		// Then the trace is not fighting a repainting line
+		if draw || ask {
+			t.Errorf("animation() = (%t, %t), want (false, false)", draw, ask)
+		}
+	})
+
+	t.Run("FLAGSMITH_ANIMATION=1 draws without asking", func(t *testing.T) {
+		// Given no cached evaluation at all
+		cacheSelfFlag(t, "something_else", true)
+		fakeStderrTTY(t, true)
+		t.Setenv("FLAGSMITH_ANIMATION", "1")
+
+		// When
+		draw, ask := animation()
+
+		// Then the local answer stands on its own
+		if !draw || ask {
+			t.Errorf("animation() = (%t, %t), want (true, false)", draw, ask)
+		}
+	})
+
+	t.Run("FLAGSMITH_ANIMATION=0 is the opt-out", func(t *testing.T) {
+		// Given the flag is on for this CLI
+		cacheSelfFlag(t, "loading_animation", true)
+		fakeStderrTTY(t, true)
+		t.Setenv("FLAGSMITH_ANIMATION", "0")
+
+		// When
+		draw, ask := animation()
+
+		// Then it neither draws nor phones home again to check
+		if draw || ask {
+			t.Errorf("animation() = (%t, %t), want (false, false)", draw, ask)
+		}
+	})
+
+	t.Run("otherwise the CLI's own flag decides", func(t *testing.T) {
+		// Given loading_animation is on in the cached evaluation
+		cacheSelfFlag(t, "loading_animation", true)
+		fakeStderrTTY(t, true)
+
+		// When
+		draw, ask := animation()
+
+		// Then it draws, and keeps the evaluation current
+		if !draw || !ask {
+			t.Errorf("animation() = (%t, %t), want (true, true)", draw, ask)
+		}
+	})
+
+	t.Run("a cold cache draws nothing but asks", func(t *testing.T) {
+		// Given a machine that has never evaluated the flag
+		tmp := t.TempDir()
+		t.Setenv("HOME", tmp)
+		t.Setenv("XDG_CACHE_HOME", filepath.Join(tmp, ".cache"))
+		t.Setenv("LocalAppData", tmp)
+		fakeStderrTTY(t, true)
+
+		// When
+		draw, ask := animation()
+
+		// Then the first run is plain, and the next one need not be
+		if draw {
+			t.Error("animation() drew on a cold cache")
+		}
+		if !ask {
+			t.Error("animation() did not ask on a cold cache")
+		}
+	})
+}
+
+// TestAnimationOwnsTheTerminalLine covers the wiring rather than the animation:
+// the flag stands between requests, so something must take the line back before
+// the command prints. A build where startAnimation ran but its writers were not
+// installed left the flag stuck in front of the output.
+func TestAnimationOwnsTheTerminalLine(t *testing.T) {
+	// Given an invocation that animates
+	cacheSelfFlag(t, "loading_animation", true)
+	fakeStderrTTY(t, true)
+	drawn := &bytes.Buffer{}
+	restoreAnimation(t, drawn)
+
+	// When the animation is started
+	startAnimation()
+
+	// Then a flag exists to be raised
+	if activeFlag == nil {
+		t.Fatal("startAnimation drew no flag with the flag enabled and a terminal")
+	}
+	// And neither of the command's writers is the bare stream any more: a flag
+	// standing on the line would never be cleared if either were
+	if got := rootCmd.OutOrStdout(); got == os.Stdout {
+		t.Error("command output writes straight to stdout, past the flag")
+	}
+	if got := rootCmd.ErrOrStderr(); got == os.Stderr {
+		t.Error("command errors write straight to stderr, past the flag")
+	}
+	// And output written through them still arrives
+	if _, err := fmt.Fprint(rootCmd.OutOrStdout(), ""); err != nil {
+		t.Errorf("writing through the guarded writer: %v", err)
+	}
+}
+
+func TestAnimationLeavesWritersAloneWhenOff(t *testing.T) {
+	// Given a terminal but the flag turned off locally
+	cacheSelfFlag(t, "loading_animation", true)
+	fakeStderrTTY(t, true)
+	t.Setenv("FLAGSMITH_ANIMATION", "0")
+	drawn := &bytes.Buffer{}
+	restoreAnimation(t, drawn)
+
+	// When the animation is started
+	startAnimation()
+
+	// Then nothing was wrapped, and releasing the line is a no-op rather than a
+	// nil dereference
+	if activeFlag != nil {
+		t.Error("startAnimation drew a flag with the animation switched off")
+	}
+	releaseLine()
+	if got := drawn.String(); got != "" {
+		t.Errorf("wrote %q to the terminal with the animation off", got)
+	}
+}
+
+// restoreAnimation points the flag at w and puts the package's animation state —
+// and cobra's writers, which startAnimation replaces — back afterwards.
+func restoreAnimation(t *testing.T, w io.Writer) {
+	t.Helper()
+	origOut, origWant, origFlag := animationOut, refreshWant, activeFlag
+	animationOut = w
+	t.Cleanup(func() {
+		animationOut, refreshWant, activeFlag = origOut, origWant, origFlag
+		rootCmd.SetOut(nil)
+		rootCmd.SetErr(nil)
+	})
+}
+
+func TestNoteAudience(t *testing.T) {
+	restore := selfAudience
+	t.Cleanup(func() { selfAudience = restore })
+
+	t.Run("a self-hosted instance and an organisation id", func(t *testing.T) {
+		// Given a context pointed at someone's own instance
+		pc := &projectContext{
+			APIURL:       resolved{Value: "https://flagsmith.corp.example"},
+			Organisation: resolved{Value: 13},
+		}
+
+		// When it settles
+		noteAudience(pc)
+
+		// Then both facts are available to target: the organisation, and that this
+		// is not Flagsmith's own instance
+		if got := selfAudience; got.Organisation != "13" || got.IsSaas {
+			t.Errorf("selfAudience = %+v, want organisation 13 and not SaaS", got)
+		}
+	})
+
+	t.Run("an organisation named rather than numbered is not sent", func(t *testing.T) {
+		// Given a context naming its organisation
+		pc := &projectContext{
+			APIURL:       resolved{Value: defaultAPIURL},
+			Organisation: resolved{Value: "Acme Corp"},
+		}
+
+		// When it settles
+		noteAudience(pc)
+
+		// Then the name is left behind — resolving it costs a request, and it is
+		// the company's name. The default instance is Flagsmith's own.
+		if got := selfAudience; got.Organisation != "" || !got.IsSaas {
+			t.Errorf("selfAudience = %+v, want no organisation and SaaS", got)
+		}
+	})
+}