fix(update): suppress nag for pseudo-versions and add env-var escape hatch

CI integration test `TestRepoLifecycle` failed on PR #188:

  expected 'v1' in quiet tag list, got:
  💡 vers update available: v0.0.0-20260506213344-eb1e5d25fa7c -> v0.10.0 (run 'vers upgrade')

Two issues:

1. The integration test runner builds the CLI via `go build` against the
   PR merge commit, producing a Go module pseudo-version like
   `v0.0.0-<timestamp>-<commit>`. The previous `IsDevVersion` only
   matched `dev` / `dev-*` / `*-dirty`, so the pseudo-version sailed
   through, hit the live GitHub API, and printed the banner.

2. `testutil.RunVers` uses `cmd.CombinedOutput()`, so even though the
   banner correctly writes to stderr, it still ended up in the buffer
   that tests parse. Tests doing `strings.TrimSpace(out) != "v1"` are
   particularly fragile.

Fixes:

- IsDevVersion now also matches `v0.0.0-...` pseudo-versions. This
  protects `go install`, `go run`, and any module-graph build against
  an untagged commit — none of which represent a published release the
  user can "upgrade" to.
- New `VERS_NO_UPDATE_CHECK` env var (also accepts `NO_UPDATE_NOTIFIER`
  for cross-tool consistency with npm) silences the check entirely
  before any other logic runs. Truthy parsing follows convention:
  unset/empty/0/false/no/off mean "don't suppress", anything else
  suppresses.
- testutil.RunVers and RunVersInDir now set `VERS_NO_UPDATE_CHECK=1`
  unconditionally so future integration tests are immune to this class
  of contamination even if a real release ships during a CI run.

New tests cover pseudo-version detection, both env-var names, and
falsy-value rejection.

Author: AlephNotation

internal/update/update.go

@@ -29,9 +29,31 @@ type GitHubRelease struct {
 
 // IsDevVersion reports whether a version string represents a local/dev build
 // for which we should skip update checks entirely.
+//
+// This catches:
+//   - the literal sentinels "dev" / "unknown" / "" set when ldflags weren't applied
+//   - "dev-<sha>" / "*-dirty" produced by our init() fallback against `git describe`
+//   - Go module *pseudo-versions* of the form "v0.0.0-<timestamp>-<commit>",
+//     which are what `go install` and `go run` produce against an untagged
+//     commit. Without this, integration test runs that build via the module
+//     graph end up with a perfectly valid-looking semver and try to "upgrade"
+//     to whatever real release is currently latest, contaminating test output.
 func IsDevVersion(v string) bool {
-	v = strings.TrimPrefix(v, "v")
-	return v == "" || v == "dev" || v == "unknown" || strings.HasPrefix(v, "dev-") || strings.Contains(v, "-dirty")
+	stripped := strings.TrimPrefix(v, "v")
+	if stripped == "" || stripped == "dev" || stripped == "unknown" {
+		return true
+	}
+	if strings.HasPrefix(stripped, "dev-") || strings.Contains(stripped, "-dirty") {
+		return true
+	}
+	// Go pseudo-versions all start with "0.0.0-" (untagged repo) or
+	// "X.Y.Z-0.<timestamp>-<commit>" (post-tag). The first form is the
+	// only one we hit in practice (the release pipeline sets a real
+	// version via ldflags), so checking that prefix is sufficient.
+	if strings.HasPrefix(stripped, "0.0.0-") {
+		return true
+	}
+	return false
 }
 
 // CheckForUpdates checks if there's a new version available.
@@ -227,7 +249,19 @@ func isNewerSemver(current, latest string) bool {
 // Errors are intentionally swallowed — the update check must never break a
 // real command. When verbose is true, debug output is written to stderr.
 func MaybeNotifyUpdate(ctx context.Context, current, repository string, timeout time.Duration, verbose bool) {
+	// Escape hatches for CI / scripted use. Either of these silences the
+	// nag and skips all network I/O. Mirrors NO_UPDATE_NOTIFIER (npm) and
+	// HOMEBREW_NO_AUTO_UPDATE (brew), which are well-known patterns.
+	if envFlagSet("VERS_NO_UPDATE_CHECK") || envFlagSet("NO_UPDATE_NOTIFIER") {
+		if verbose {
+			fmt.Fprintf(os.Stderr, "[DEBUG] update: skipped (VERS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER set)\n")
+		}
+		return
+	}
 	if IsDevVersion(current) {
+		if verbose {
+			fmt.Fprintf(os.Stderr, "[DEBUG] update: skipped (dev/pseudo version %q)\n", current)
+		}
 		return
 	}
 
@@ -284,3 +318,20 @@ func MaybeNotifyUpdate(ctx context.Context, current, repository string, timeout
 func printUpdateBanner(current, latest string) {
 	fmt.Fprintf(os.Stderr, "💡 vers update available: %s -> %s (run 'vers upgrade')\n\n", current, latest)
 }
+
+// envFlagSet returns true if the env var is set to a "truthy" value.
+// Treats unset, empty string, "0", "false", "no", "off" (case-insensitive)
+// as false and anything else as true. This matches the convention used by
+// most CLI tools and avoids surprises like VERS_NO_UPDATE_CHECK=0 being
+// interpreted as "yes, suppress".
+func envFlagSet(name string) bool {
+	v := strings.TrimSpace(os.Getenv(name))
+	if v == "" {
+		return false
+	}
+	switch strings.ToLower(v) {
+	case "0", "false", "no", "off":
+		return false
+	}
+	return true
+}

internal/update/update_test.go

@@ -44,7 +44,14 @@ func TestIsNewerSemver(t *testing.T) {
 }
 
 func TestIsDevVersion(t *testing.T) {
-	dev := []string{"dev", "unknown", "dev-abc1234", "dev-abc1234-dirty", "v0.10.0-dirty", ""}
+	dev := []string{
+		"dev", "unknown", "dev-abc1234", "dev-abc1234-dirty",
+		"v0.10.0-dirty", "",
+		// Go module pseudo-versions, as produced by `go install` /
+		// `go run` against an untagged commit.
+		"v0.0.0-20260506213344-eb1e5d25fa7c",
+		"v0.0.0-20260101000000-000000000000",
+	}
 	notDev := []string{"v0.10.0", "0.10.0", "v1.2.3", "v0.10.0-rc1"}
 	for _, v := range dev {
 		if !IsDevVersion(v) {
@@ -58,6 +65,66 @@ func TestIsDevVersion(t *testing.T) {
 	}
 }
 
+func TestMaybeNotifyUpdate_EnvVarSilencesCheck(t *testing.T) {
+	withTempHome(t)
+
+	// Server that fails the test if hit.
+	hits := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hits++
+		http.Error(w, "should not be called", 500)
+	}))
+	defer srv.Close()
+	withRewrittenHTTP(t, strings.TrimPrefix(srv.URL, "http://"))
+
+	for _, varName := range []string{"VERS_NO_UPDATE_CHECK", "NO_UPDATE_NOTIFIER"} {
+		t.Run(varName, func(t *testing.T) {
+			t.Setenv(varName, "1")
+			out := captureStderr(t, func() {
+				MaybeNotifyUpdate(context.Background(), "v0.9.0", "https://github.com/hdresearch/vers-cli", 500*time.Millisecond, false)
+			})
+			if hits != 0 {
+				t.Errorf("expected zero network calls when %s=1, got %d", varName, hits)
+			}
+			if out != "" {
+				t.Errorf("expected silent output when %s=1, got %q", varName, out)
+			}
+		})
+	}
+}
+
+func TestMaybeNotifyUpdate_EnvVarFalsyValuesDoNotSilence(t *testing.T) {
+	// "0", "false", "no", "off" should NOT silence the nag — only positive
+	// truthy values do. This mirrors common CLI conventions.
+	for _, val := range []string{"0", "false", "FALSE", "no", "off", ""} {
+		t.Run("VERS_NO_UPDATE_CHECK="+val, func(t *testing.T) {
+			withTempHome(t)
+			t.Setenv("VERS_NO_UPDATE_CHECK", val)
+			t.Setenv("NO_UPDATE_NOTIFIER", "")
+
+			cfg := &config.CLIConfig{
+				UpdateCheck: config.UpdateCheckConfig{
+					NextCheck:     time.Now().Add(-1 * time.Hour),
+					CheckInterval: 3600,
+				},
+			}
+			_ = config.SaveCLIConfig(cfg)
+
+			hits := 0
+			srv := fakeReleasesServer(t, "v0.10.0", &hits)
+			defer srv.Close()
+			withRewrittenHTTP(t, strings.TrimPrefix(srv.URL, "http://"))
+
+			out := captureStderr(t, func() {
+				MaybeNotifyUpdate(context.Background(), "v0.9.0", "https://github.com/hdresearch/vers-cli", 1*time.Second, false)
+			})
+			if !strings.Contains(out, "v0.9.0 -> v0.10.0") {
+				t.Errorf("expected banner with VERS_NO_UPDATE_CHECK=%q, got %q", val, out)
+			}
+		})
+	}
+}
+
 // withTempHome redirects $HOME to a temporary directory for the duration of
 // the test so config.LoadCLIConfig / SaveCLIConfig don't touch the user's
 // real ~/.vers/config.json. Returns the path to the temp config file.

test/testutil/helpers.go

@@ -85,8 +85,10 @@ func RunVers(t TLike, timeout time.Duration, args ...string) (string, error) {
 	defer cancel()
 
 	cmd := exec.CommandContext(ctx, BinPath, args...)
-	// Inherit env so VERS_URL and VERS_API_KEY are visible
-	cmd.Env = os.Environ()
+	// Inherit env so VERS_URL and VERS_API_KEY are visible, but force
+	// the update-check off so the "💡 vers update available" banner
+	// can't contaminate command output that tests parse.
+	cmd.Env = append(os.Environ(), "VERS_NO_UPDATE_CHECK=1")
 	out, err := cmd.CombinedOutput()
 	if ctx.Err() == context.DeadlineExceeded {
 		return string(out), fmt.Errorf("command timed out: vers %s", strings.Join(args, " "))
@@ -107,7 +109,7 @@ func RunVersInDir(t TLike, dir string, timeout time.Duration, args ...string) (s
 
 	cmd := exec.CommandContext(ctx, absBin, args...)
 	cmd.Dir = dir
-	cmd.Env = os.Environ()
+	cmd.Env = append(os.Environ(), "VERS_NO_UPDATE_CHECK=1")
 	out, err := cmd.CombinedOutput()
 	if ctx.Err() == context.DeadlineExceeded {
 		return string(out), fmt.Errorf("command timed out: vers %s", strings.Join(args, " "))