fix: compare versions by semver, not string equality (#48)

The update nag treated any version difference as "newer", so a fresh
throttle cache holding a tag that was latest when written but is now
OLDER than the installed binary nagged backward. This happens in normal
operation: release vX, self-upgrade within the 24h cache window, and the
cached older tag triggers a "1.1.0 → v1.0.0" notice. Meanwhile
`praxis update` (live fetch) correctly reported "already latest", so the
two disagreed.

Replace the string-equality compare with a small semver comparator
(compareSemver) that only nags when the latest tag is strictly newer.
`praxis update` now uses the same comparator (<= 0 → already latest),
so it never offers a downgrade and can't disagree with the nag. No new
dependency — the comparator handles v-prefix, missing components, build
metadata, and release-outranks-prerelease.

Regression tests cover the exact backward-nag scenario (fresh cache
older than installed) plus the comparator's edge cases.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anujhydrabadi

cmd/update.go

@@ -56,7 +56,11 @@ Homebrew users: prefer 'brew upgrade praxis' so brew tracks the version.`,
 
 		latest := strings.TrimPrefix(rel.TagName, "v")
 		current := strings.TrimPrefix(version, "v")
-		if latest == current {
+		// Treat "not strictly newer" as already-latest: an equal version, or a
+		// release that is older than the installed build (so we never offer a
+		// downgrade). Uses the same comparator as the background update nag
+		// (cmd/update_check.go) so the two can't disagree.
+		if compareSemver(rel.TagName, version) <= 0 {
 			if asJSON {
 				return render.JSON(out, map[string]any{
 					"updated": false,

cmd/update_check.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 	"unicode"
@@ -57,11 +58,10 @@ func checkForUpdate() string {
 	if isDevBuild(version) {
 		return ""
 	}
-	currentClean := strings.TrimPrefix(version, "v")
 
 	// Serve from cache while fresh.
 	if cached, err := readUpdateCache(); err == nil && time.Since(cached.CheckedAt) < updateCheckInterval {
-		return newerThan(currentClean, cached.LatestVersion)
+		return newerThan(version, cached.LatestVersion)
 	}
 
 	// Live fetch with one silent retry on any error.
@@ -80,7 +80,7 @@ func checkForUpdate() string {
 		LatestVersion: rel.TagName,
 	})
 
-	return newerThan(currentClean, rel.TagName)
+	return newerThan(version, rel.TagName)
 }
 
 // gitDescribeAhead matches the "-<n>-g<sha>" suffix git describe appends when
@@ -99,17 +99,76 @@ func isDevBuild(v string) bool {
 	return gitDescribeAhead.MatchString(v)
 }
 
-// newerThan reports latestTag (e.g. "v1.2.3") as the result when it differs
-// from the current version, else "". Comparison is string equality after
-// stripping the "v" prefix — matching praxis update (cmd/update.go) and raptor.
-func newerThan(currentClean, latestTag string) string {
-	latestClean := strings.TrimPrefix(latestTag, "v")
-	if latestClean != "" && latestClean != currentClean {
+// newerThan reports latestTag (e.g. "v1.2.3") as the result only when it is
+// strictly semver-newer than current, else "". A plain string-inequality test
+// is wrong here: the throttle cache can hold a tag that was latest when written
+// but is now OLDER than the installed binary (e.g. the user released vX and
+// self-upgraded within the 24h window), which would otherwise nag backward.
+func newerThan(current, latestTag string) string {
+	if latestTag == "" {
+		return ""
+	}
+	if compareSemver(latestTag, current) > 0 {
 		return latestTag
 	}
 	return ""
 }
 
+// compareSemver compares two dotted versions, ignoring a leading "v" and any
+// build metadata. Returns -1 if a<b, 0 if equal, 1 if a>b. The numeric core
+// (major.minor.patch) is compared numerically; a release outranks a prerelease
+// of the same core (1.0.0 > 1.0.0-rc1); two prereleases fall back to a string
+// compare. This is sufficient for goreleaser's clean release tags; "dev"/
+// "ahead"/"dirty" builds never reach here (filtered by isDevBuild).
+func compareSemver(a, b string) int {
+	ac, ap := splitVersion(a)
+	bc, bp := splitVersion(b)
+	for i := 0; i < 3; i++ {
+		if ac[i] != bc[i] {
+			if ac[i] < bc[i] {
+				return -1
+			}
+			return 1
+		}
+	}
+	switch {
+	case ap == bp:
+		return 0
+	case ap == "": // a is a release, b a prerelease of the same core → a newer
+		return 1
+	case bp == "":
+		return -1
+	case ap < bp:
+		return -1
+	default:
+		return 1
+	}
+}
+
+// splitVersion parses "v1.2.3-rc1+build" into its numeric core [1,2,3] and
+// prerelease ("rc1"). Missing core components default to 0; non-numeric ones
+// are treated as 0.
+func splitVersion(v string) ([3]int, string) {
+	v = strings.TrimPrefix(v, "v")
+	core, pre := v, ""
+	if i := strings.IndexByte(v, '-'); i >= 0 {
+		core, pre = v[:i], v[i+1:]
+	}
+	// Drop any build metadata (from the core if there was no prerelease, or
+	// from the tail of the prerelease).
+	if j := strings.IndexByte(core, '+'); j >= 0 {
+		core = core[:j]
+	}
+	if j := strings.IndexByte(pre, '+'); j >= 0 {
+		pre = pre[:j]
+	}
+	var nums [3]int
+	for i, p := range strings.SplitN(core, ".", 3) {
+		nums[i], _ = strconv.Atoi(p)
+	}
+	return nums, pre
+}
+
 // fetchLatestReleaseWithRetry calls the fetchLatestRelease seam up to twice,
 // pausing briefly between attempts. Returns nil if both attempts fail.
 func fetchLatestReleaseWithRetry() *selfupdate.Release {

cmd/update_check_test.go

@@ -63,6 +63,12 @@ func TestCheckForUpdate(t *testing.T) {
 			rel:     &selfupdate.Release{TagName: "v1.2.0"},
 			want:    "v1.2.0",
 		},
+		{
+			name:    "newer patch returns latest tag",
+			version: "1.0.0",
+			rel:     &selfupdate.Release{TagName: "v1.0.1"},
+			want:    "v1.0.1",
+		},
 		{
 			name:    "equal returns empty",
 			version: "1.2.0",
@@ -75,6 +81,14 @@ func TestCheckForUpdate(t *testing.T) {
 			rel:     &selfupdate.Release{TagName: "1.2.0"},
 			want:    "",
 		},
+		{
+			// Regression: installed binary is NEWER than the live "latest".
+			// String-equality would nag backward; semver must stay silent.
+			name:    "installed newer than latest stays silent",
+			version: "1.2.0",
+			rel:     &selfupdate.Release{TagName: "v1.0.0"},
+			want:    "",
+		},
 		{
 			name:    "dev build skipped",
 			version: "dev",
@@ -124,6 +138,18 @@ func TestCheckForUpdate(t *testing.T) {
 			failFetch: true,
 			want:      "",
 		},
+		{
+			// Exact production bug: a fresh cache holds the tag that was latest
+			// when written (v1.0.0), but the user has since self-upgraded to
+			// 1.1.0 within the 24h window. Must NOT nag backward.
+			name:    "fresh cache older than installed stays silent",
+			version: "1.1.0",
+			seedCache: func(t *testing.T) {
+				writeCache(t, time.Hour, "v1.0.0")
+			},
+			failFetch: true,
+			want:      "",
+		},
 		{
 			name:    "stale cache triggers fetch",
 			version: "1.0.0",
@@ -251,6 +277,47 @@ func TestCheckForUpdate_ThrottlesFailures(t *testing.T) {
 	}
 }
 
+func TestCompareSemver(t *testing.T) {
+	tests := []struct {
+		a, b string
+		want int
+	}{
+		{"1.0.0", "1.0.0", 0},
+		{"v1.0.0", "1.0.0", 0}, // v-prefix ignored
+		{"1.1.0", "1.0.0", 1},
+		{"1.0.0", "1.1.0", -1},
+		{"1.0.1", "1.0.0", 1},
+		{"2.0.0", "1.9.9", 1},
+		{"1.10.0", "1.9.0", 1},        // numeric, not lexical
+		{"1.0", "1.0.0", 0},           // missing patch defaults to 0
+		{"1.0.0", "1.0.0-rc1", 1},     // release outranks prerelease
+		{"1.0.0-rc1", "1.0.0", -1},    // and vice versa
+		{"1.0.0-rc2", "1.0.0-rc1", 1}, // prerelease string compare
+		{"1.2.3+build", "1.2.3", 0},   // build metadata ignored
+	}
+	for _, tt := range tests {
+		if got := compareSemver(tt.a, tt.b); got != tt.want {
+			t.Errorf("compareSemver(%q, %q) = %d, want %d", tt.a, tt.b, got, tt.want)
+		}
+	}
+}
+
+func TestNewerThan(t *testing.T) {
+	tests := []struct {
+		current, latestTag, want string
+	}{
+		{"1.0.0", "v1.1.0", "v1.1.0"}, // newer → returns the tag verbatim
+		{"1.0.0", "v1.0.0", ""},       // equal
+		{"1.1.0", "v1.0.0", ""},       // older → silent (the bug)
+		{"1.0.0", "", ""},             // empty (failed-fetch marker)
+	}
+	for _, tt := range tests {
+		if got := newerThan(tt.current, tt.latestTag); got != tt.want {
+			t.Errorf("newerThan(%q, %q) = %q, want %q", tt.current, tt.latestTag, got, tt.want)
+		}
+	}
+}
+
 func TestPrintUpdateNotification(t *testing.T) {
 	withVersion(t, "1.0.0")
 	var buf bytes.Buffer