homebrew: handle situation when local tap version is not refreshed yet during update (#57)

Author: roblaszczak

internal/selfupdate.go

@@ -2,6 +2,7 @@ package internal
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"os"
 	"os/exec"
@@ -160,6 +161,68 @@ func repoSlug() selfupdate.RepositorySlug {
 	return selfupdate.NewRepositorySlug(repoOwner, repoName)
 }
 
+func parseBrewFormulaVersion(data []byte) (string, error) {
+	var result struct {
+		Formulae []struct {
+			Versions struct {
+				Stable string `json:"stable"`
+			} `json:"versions"`
+		} `json:"formulae"`
+	}
+	if err := json.Unmarshal(data, &result); err != nil {
+		return "", err
+	}
+	if len(result.Formulae) == 0 || result.Formulae[0].Versions.Stable == "" {
+		return "", fmt.Errorf("no version found in brew info output")
+	}
+	return result.Formulae[0].Versions.Stable, nil
+}
+
+// brewFormulaVersion returns the version from the local Homebrew tap formula.
+//
+// Homebrew caches third-party tap formulae as local git clones and only
+// refreshes them when auto-update fires. Auto-update is triggered by
+// commands like `brew install` or `brew upgrade`, but has a 24h debounce
+// (HOMEBREW_AUTO_UPDATE_SECS, default 86400s) — if any brew command ran
+// within that window, the refresh is skipped. There is no background
+// process; taps stay stale until the next brew command after the debounce
+// expires, or until the user runs `brew update` manually.
+//
+// Unlike `go install @vX.Y.Z`, there is no way to tell brew to install a
+// specific version of a tap formula. The `@version` syntax (e.g.
+// `python@3.11`) only works when a separate versioned formula file exists
+// in the tap, which we don't publish.
+//
+// This function lets us detect when the local formula is behind the latest
+// GitHub release, so we can suppress misleading update prompts rather than
+// pointing the user at an upgrade that would silently no-op.
+func brewFormulaVersion(ctx context.Context) (string, error) {
+	cmd := exec.CommandContext(ctx, "brew", "info", "--json=v2", "threedotslabs/tap/tdl")
+	out, err := cmd.Output()
+	if err != nil {
+		return "", fmt.Errorf("brew info failed: %w", err)
+	}
+	return parseBrewFormulaVersion(out)
+}
+
+// isVersionAvailableForInstallMethod checks whether the given version
+// is available through the user's install method. Currently only
+// Homebrew is checked — see brewFormulaVersion for why.
+// Returns true for all other methods or on any error (graceful fallback).
+func isVersionAvailableForInstallMethod(version string) bool {
+	method := DetectInstallMethod()
+	if method != InstallMethodHomebrew {
+		return true
+	}
+	formulaVer, err := brewFormulaVersion(context.Background())
+	if err != nil {
+		logrus.WithError(err).Debug("Could not check brew formula version")
+		return true
+	}
+	target := strings.TrimPrefix(version, "v")
+	return !isNewerVersion(target, formulaVer)
+}
+
 // RunUpdate checks for updates and applies them based on the installation method.
 func RunUpdate(ctx context.Context, currentVersion string, opts UpdateOptions) error {
 	if os.Getenv("TDL_NO_UPDATE_CHECK") != "" {
@@ -243,6 +306,22 @@ func RunUpdate(ctx context.Context, currentVersion string, opts UpdateOptions) e
 	// Branch on install method
 	switch method {
 	case InstallMethodHomebrew:
+		// Homebrew's local tap may still point to an older formula version
+		// (24h auto-update debounce). Bail out early instead of running a
+		// doomed `brew upgrade` that would print "already installed".
+		formulaVer, err := brewFormulaVersion(ctx)
+		if err == nil {
+			target := strings.TrimPrefix(targetVersion, "v")
+			if isNewerVersion(target, formulaVer) {
+				fmt.Println(color.YellowString(
+					"Version %s is not yet available via Homebrew (formula has %s).",
+					targetVersion, formulaVer,
+				))
+				fmt.Println("Homebrew updates its formula cache periodically. To refresh manually, run:")
+				fmt.Printf("  %s\n\n", SprintCommand("brew update && brew upgrade tdl"))
+				return nil
+			}
+		}
 		return updateViaCommand(ctx, "brew", opts, currentVersion, targetVersion,
 			[]string{"upgrade", "tdl"})
 

internal/selfupdate_test.go

@@ -212,3 +212,54 @@ func TestFormatReleaseNotes(t *testing.T) {
 		assert.Contains(t, result, "Second line")
 	})
 }
+
+func TestParseBrewFormulaVersion(t *testing.T) {
+	tests := []struct {
+		name    string
+		json    string
+		want    string
+		wantErr bool
+	}{
+		{
+			name: "valid response",
+			json: `{"formulae":[{"versions":{"stable":"0.1.78"}}],"casks":[]}`,
+			want: "0.1.78",
+		},
+		{
+			name: "version with multiple formulae",
+			json: `{"formulae":[{"versions":{"stable":"1.2.3"}},{"versions":{"stable":"4.5.6"}}],"casks":[]}`,
+			want: "1.2.3",
+		},
+		{
+			name:    "empty formulae array",
+			json:    `{"formulae":[],"casks":[]}`,
+			wantErr: true,
+		},
+		{
+			name:    "missing stable version",
+			json:    `{"formulae":[{"versions":{"head":"HEAD"}}],"casks":[]}`,
+			wantErr: true,
+		},
+		{
+			name:    "invalid json",
+			json:    `{broken`,
+			wantErr: true,
+		},
+		{
+			name:    "empty input",
+			json:    ``,
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseBrewFormulaVersion([]byte(tt.json))
+			if tt.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+				assert.Equal(t, tt.want, got)
+			}
+		})
+	}
+}

internal/update.go

@@ -66,6 +66,16 @@ func CheckForUpdate(currentVersion string, commandName string, forcePrompt bool)
 	isDifferent := release.Version != "" && release.Version != currentVersion
 
 	if isNewer || (forcePrompt && isDifferent) {
+		// Don't advertise updates that aren't installable yet — e.g. the
+		// Homebrew tap formula may still point to the old version (24h
+		// auto-update debounce). The notice will appear once the tap refreshes.
+		if !forcePrompt && !isVersionAvailableForInstallMethod(release.Version) {
+			logrus.Debug("Version not yet available via install method, skipping notice")
+			updateInfo.LastChecked = time.Now()
+			_ = storeUpdateInfo(updateInfo)
+			return
+		}
+
 		updateInfo.CurrentVersion = currentVersion
 		updateInfo.AvailableVersion = release.Version
 		updateInfo.UpdateAvailable = true
@@ -122,10 +132,15 @@ func CheckUpdateAvailable(currentVersion string, forcePrompt bool) (available bo
 			isNewer := release.Version != "" && isNewerVersion(release.Version, currentVersion)
 			isDifferent := release.Version != "" && release.Version != currentVersion
 			if isNewer || (forcePrompt && isDifferent) {
-				updateInfo.CurrentVersion = currentVersion
-				updateInfo.AvailableVersion = release.Version
-				updateInfo.UpdateAvailable = true
-				updateInfo.ReleaseNotes = release.ReleaseNotes
+				// Same install-method gate as in CheckForUpdate — see comment there.
+				if forcePrompt || isVersionAvailableForInstallMethod(release.Version) {
+					updateInfo.CurrentVersion = currentVersion
+					updateInfo.AvailableVersion = release.Version
+					updateInfo.UpdateAvailable = true
+					updateInfo.ReleaseNotes = release.ReleaseNotes
+				} else {
+					logrus.Debug("Version not yet available via install method, skipping")
+				}
 			} else {
 				updateInfo.CurrentVersion = currentVersion
 				updateInfo.AvailableVersion = ""