feat(update): detect install method to tailor or suppress update notices

.goreleaser.yaml

@@ -282,6 +282,14 @@ nfpms:
         dst: /etc/bash_completion.d/platform
       - src: completion/zsh/_platform
         dst: /usr/local/share/zsh/site-functions/_platform
+      # Marks the install as managed by a system package manager, so the CLI
+      # suppresses its update message. See internal/install.go. The dst must stay
+      # at <prefix>/share/<slug>/install-source, where <prefix> is the parent of
+      # the binary's dir (default bindir /usr/bin -> prefix /usr); changing the
+      # nfpm bindir would silently break suppression.
+      - src: packaging/install-source
+        dst: /usr/share/platformsh-cli/install-source
+        file_info: { mode: 0644 }
     apk:
       signature:
         key_file: "{{ with .Env.RSA_SIGNING_KEY_FILE }}{{ . }}{{ end }}"
@@ -309,6 +317,14 @@ nfpms:
         dst: /etc/bash_completion.d/upsun
       - src: completion/zsh/_upsun
         dst: /usr/local/share/zsh/site-functions/_upsun
+      # Marks the install as managed by a system package manager, so the CLI
+      # suppresses its update message. See internal/install.go. The dst must stay
+      # at <prefix>/share/<slug>/install-source, where <prefix> is the parent of
+      # the binary's dir (default bindir /usr/bin -> prefix /usr); changing the
+      # nfpm bindir would silently break suppression.
+      - src: packaging/install-source
+        dst: /usr/share/upsun/install-source
+        file_info: { mode: 0644 }
     apk:
       signature:
         key_file: "{{ with .Env.RSA_SIGNING_KEY_FILE }}{{ . }}{{ end }}"

CLAUDE.md

@@ -163,4 +163,12 @@ PHP version is still injected via ldflags:
 
 ### Update Checks
 
-The CLI checks for updates from GitHub releases (when Wrapper.GitHubRepo is set in config). This runs in a background goroutine and prints a message after command execution.
+The CLI checks for updates from GitHub releases (when Wrapper.GitHubRepo is set in config). The network check runs in a background goroutine and caches the latest known version in `state.json`; the notice is shown before the command on a later run (see `internal/update.go`).
+
+Install-method detection (`internal/install.go`) tailors or suppresses the notice:
+- System package managers (apt, yum/dnf, apk) are detected via a marker file installed by the nfpm packages (`packaging/install-source` → `/usr/share/<slug>/install-source`). Before printing a notice, older package installs without the marker are also detected by querying dpkg/rpm/apk. The notice is suppressed because the OS handles updates.
+- Homebrew, Scoop, npm, and the bash installer get a tailored upgrade command, built from config fields (`Wrapper.HomebrewTap`, `Wrapper.NpmPackage`, `Wrapper.InstallerURL`, `Application.Executable`).
+- The notice is throttled to once a week (`LastNotified` in state) and only shown in an interactive terminal.
+- `<PREFIX>INSTALL_METHOD` forces the method; `<PREFIX>UPDATES_CHECK=0` disables checks entirely.
+
+See `docs/design/update-message-install-detection.md` for the full design, including the planned Phase 2 (opt-in self-update).

README.md

@@ -162,6 +162,24 @@ sudo apt-get update && sudo apt-get upgrade upsun-cli
 sudo dnf upgrade -y upsun-cli
 ```
 
+### Update notifications
+
+When a newer release is available, the CLI prints a short notice with the
+upgrade command for the tool you installed it with. It detects the install
+method automatically and, for system package managers (apt, yum/dnf, apk), stays
+silent because those update the CLI through the OS.
+
+The notice is shown at most once a week and only in an interactive terminal. To
+control it:
+
+- `UPSUN_CLI_UPDATES_CHECK=0` disables update checks and notices entirely.
+- `UPSUN_CLI_INSTALL_METHOD=<method>` forces the detected install method, where
+  `<method>` is one of `homebrew`, `scoop`, `npm`, `package`, or `script`. Use
+  `package` to silence the notice when the OS manages updates.
+
+(For the `platform` command, the prefix is `PLATFORMSH_CLI_` instead of
+`UPSUN_CLI_`.)
+
 ## Building
 
 Build a single binary:

commands/root.go

@@ -40,10 +40,7 @@ func Execute(cnf *config.Config) error {
 }
 
 func newRootCommand(cnf *config.Config, assets *vendorization.VendorAssets) *cobra.Command {
-	var (
-		updateMessageChan = make(chan *internal.ReleaseInfo, 1)
-		versionCommand    = newVersionCommand(cnf)
-	)
+	versionCommand := newVersionCommand(cnf)
 	cmd := &cobra.Command{
 		Use:                cnf.Application.Executable,
 		Short:              cnf.Application.Name,
@@ -57,7 +54,8 @@ func newRootCommand(cnf *config.Config, assets *vendorization.VendorAssets) *cob
 				// Completions must be fast and quiet.
 				return
 			}
-			if viper.GetBool("quiet") && !viper.GetBool("debug") && !viper.GetBool("verbose") {
+			quiet := viper.GetBool("quiet") && !viper.GetBool("debug") && !viper.GetBool("verbose")
+			if quiet {
 				viper.Set("no-interaction", true)
 				cmd.SetErr(io.Discard)
 			} else {
@@ -77,9 +75,20 @@ func newRootCommand(cnf *config.Config, assets *vendorization.VendorAssets) *cob
 				os.Exit(0)
 			}
 			if cnf.Wrapper.GitHubRepo != "" {
+				// Show any update found by a previous run, before the command's
+				// output. The check itself runs in the background (below) and
+				// caches its result for the next invocation. In quiet mode the
+				// notice would be discarded, so it is left for a later run.
+				if rel := internal.PendingNotification(cnf, config.Version); rel != nil && !quiet {
+					// Full detection can find package installs that lack the marker.
+					if !internal.DetectInstallMethod(cnf).AutoUpdating() {
+						printUpdateMessage(cmd.ErrOrStderr(), rel, cnf)
+					}
+					internal.MarkNotified(cnf)
+				}
 				go func() {
-					rel, _ := internal.CheckForUpdate(cnf, config.Version)
-					updateMessageChan <- rel
+					//nolint:errcheck // a failed update check should not affect the command
+					internal.CheckForUpdate(cnf, config.Version)
 				}()
 			}
 			if alt.ShouldUpdate(cnf) {
@@ -101,11 +110,6 @@ func newRootCommand(cnf *config.Config, assets *vendorization.VendorAssets) *cob
 				return
 			}
 			checkShellConfigLeftovers(cmd.ErrOrStderr(), cnf)
-			select {
-			case rel := <-updateMessageChan:
-				printUpdateMessage(cmd.ErrOrStderr(), rel, cnf)
-			default:
-			}
 		},
 	}
 
@@ -212,19 +216,14 @@ func printUpdateMessage(w io.Writer, newRelease *internal.ReleaseInfo, cnf *conf
 		return
 	}
 
-	fmt.Fprintf(w, "\n\n%s %s → %s\n",
+	fmt.Fprintf(w, "%s %s → %s\n",
 		color.YellowString(fmt.Sprintf("A new release of the %s is available:", cnf.Application.Name)),
 		color.CyanString(config.Version),
 		color.CyanString(newRelease.Version),
 	)
 
-	executable, err := os.Executable()
-	if err == nil && cnf.Wrapper.HomebrewTap != "" && isUnderHomebrew(executable) {
-		fmt.Fprintf(
-			w,
-			"To upgrade, run: brew update && brew upgrade %s\n",
-			color.YellowString(cnf.Wrapper.HomebrewTap),
-		)
+	if cmd := upgradeCommand(cnf); cmd != "" {
+		fmt.Fprintf(w, "To upgrade, run: %s\n", color.YellowString(cmd))
 	} else if cnf.Wrapper.GitHubRepo != "" {
 		fmt.Fprintf(
 			w,
@@ -236,19 +235,45 @@ func printUpdateMessage(w io.Writer, newRelease *internal.ReleaseInfo, cnf *conf
 	fmt.Fprintf(w, "%s\n\n", color.YellowString(newRelease.URL))
 }
 
-func isUnderHomebrew(binary string) bool {
-	brewExe, err := exec.LookPath("brew")
-	if err != nil {
-		return false
-	}
+// upgradeCommand returns the upgrade command for the detected install method, or
+// an empty string when there is no tailored command (the caller then falls back
+// to a generic link).
+func upgradeCommand(cnf *config.Config) string {
+	exe, _ := os.Executable()
+	return upgradeCommandFor(cnf, internal.DetectInstallMethod(cnf), exe)
+}
 
-	brewPrefixBytes, err := exec.Command(brewExe, "--prefix").Output()
-	if err != nil {
-		return false
+func upgradeCommandFor(cnf *config.Config, method internal.InstallMethod, exe string) string {
+	switch method {
+	case internal.InstallHomebrew:
+		if cnf.Wrapper.HomebrewTap != "" {
+			return "brew update && brew upgrade " + cnf.Wrapper.HomebrewTap
+		}
+	case internal.InstallScoop:
+		return "scoop update " + cnf.Application.Executable
+	case internal.InstallNpm:
+		if cnf.Wrapper.NpmPackage != "" {
+			return "npm install -g " + cnf.Wrapper.NpmPackage + "@latest"
+		}
+	case internal.InstallScript:
+		// The raw method replaces the binary in INSTALL_DIR; without it, the
+		// installer may choose a package manager instead (e.g. apt on Debian).
+		if cnf.Wrapper.InstallerURL != "" && exe != "" {
+			return "curl -fsSL " + cnf.Wrapper.InstallerURL +
+				" | INSTALL_METHOD=raw INSTALL_DIR=" + shellQuote(filepath.Dir(exe)) + " sh"
+		}
 	}
+	return ""
+}
 
-	brewBinPrefix := filepath.Join(strings.TrimSpace(string(brewPrefixBytes)), "bin") + string(filepath.Separator)
-	return strings.HasPrefix(binary, brewBinPrefix)
+var shellSafe = regexp.MustCompile(`^[A-Za-z0-9_./-]+$`)
+
+// shellQuote quotes s for a POSIX shell, if needed.
+func shellQuote(s string) string {
+	if shellSafe.MatchString(s) {
+		return s
+	}
+	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
 }
 
 func debugLogf(format string, v ...any) {

commands/root_test.go

@@ -0,0 +1,54 @@
+package commands
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/upsun/cli/internal"
+)
+
+func TestUpgradeCommandFor(t *testing.T) {
+	cnf := testConfig()
+	cnf.Wrapper.HomebrewTap = "upsun/tap/upsun-cli"
+	cnf.Wrapper.NpmPackage = "upsun"
+	cnf.Wrapper.InstallerURL = "https://x.test/i.sh"
+	cnf.Application.Executable = "upsun"
+
+	cases := []struct {
+		method internal.InstallMethod
+		want   string
+	}{
+		{internal.InstallHomebrew, "brew update && brew upgrade upsun/tap/upsun-cli"},
+		{internal.InstallScoop, "scoop update upsun"},
+		{internal.InstallNpm, "npm install -g upsun@latest"},
+		{internal.InstallScript, "curl -fsSL https://x.test/i.sh | INSTALL_METHOD=raw INSTALL_DIR=/usr/local/bin sh"},
+		{internal.InstallPackage, ""}, // suppressed; no tailored command
+		{internal.InstallUnknown, ""}, // falls back to the generic link
+	}
+	for _, c := range cases {
+		t.Run(string(c.method), func(t *testing.T) {
+			assert.Equal(t, c.want, upgradeCommandFor(cnf, c.method, "/usr/local/bin/upsun"))
+		})
+	}
+}
+
+func TestUpgradeCommandForMissingConfigFallsBack(t *testing.T) {
+	cnf := testConfig() // no Wrapper.* fields set
+	// Homebrew/npm/script require their config field; without it, fall back (empty).
+	assert.Empty(t, upgradeCommandFor(cnf, internal.InstallHomebrew, "/usr/local/bin/upsun"))
+	assert.Empty(t, upgradeCommandFor(cnf, internal.InstallNpm, "/usr/local/bin/upsun"))
+	assert.Empty(t, upgradeCommandFor(cnf, internal.InstallScript, "/usr/local/bin/upsun"))
+}
+
+func TestShellQuote(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"/usr/local/bin", "/usr/local/bin"},
+		{"/home/Jane Doe/.local/bin", "'/home/Jane Doe/.local/bin'"},
+		{"/tmp/it's", `'/tmp/it'\''s'`},
+		{"/tmp/$(id)", "'/tmp/$(id)'"},
+	}
+	for _, c := range cases {
+		assert.Equal(t, c.want, shellQuote(c.in))
+	}
+}