Add databricks version --check to check for available CLI updates (#5469)

## Why

`databricks version` (and `databricks --version`) only prints the
version you're on. There's no way to tell whether you're behind, and
even once you know, the command to upgrade depends on how you installed
the CLI (Homebrew, WinGet, Chocolatey, or the install script). A version
check also shouldn't be fragile: if GitHub is slow or unreachable it
must not hang or fail the command.

## Changes

Before: `databricks version` prints the current version and nothing
else.

Now: `databricks version --check` fetches the latest release from
GitHub, compares it with the running build, and prints the upgrade
command for your install method:

```
Databricks CLI v0.240.0
A new version is available: 0.245.0
To upgrade, run:
  brew upgrade databricks
```

Per review feedback this is the only way to run the check (the `version
check` subcommand from an earlier revision is gone). Bare `databricks
version` and `databricks --version` stay lightweight and identical to
today: no network call, no output change.

Details:

- New `libs/versioncheck` package fetches
`api.github.com/repos/databricks/cli/releases/latest`, semver-compares,
and infers the install method from the executable path (resolving
symlinks so a Homebrew shim classifies as Homebrew, not the install
script).
- The lookup is capped at 2s. If GitHub is unreachable, times out, or
rate-limits, the check fails gently: it prints that it couldn't reach
GitHub and links to the releases page, and still exits 0 instead of
erroring.
- Development and snapshot builds short-circuit without a network call.
- `databricks version --check --output json` returns the structured
result (including `check_failed`) for scripting.

First PR in a two-PR stack; the follow-up (#5470) adds a passive
once-per-day notice.

## Test plan

- [x] Unit tests: install-method detection across OSes, semver
comparison, and the full check against a mock server (update available,
up to date, dev build, server error fails gently, unreachable fails
gently).
- [x] White-box render tests asserting exact output for all states,
including the "couldn't reach GitHub" message.
- [x] Acceptance test (`acceptance/cmd/version`) covering lightweight
`version`, `version --check`, and `version --check --output json`.
- [x] Full local acceptance suite (`go test ./acceptance`), including
the `help` output test.
- [x] `./task fmt`, lint on changed packages, and `./task checks` clean.

This pull request and its description were written by Isaac.

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -7,11 +7,13 @@
 
 ### CLI
 * Added the `databricks quickstart` command, a short introduction to the CLI that prints a human-friendly guide interactively and an agent-oriented version when run non-interactively ([#5464](https://github.com/databricks/cli/pull/5464)).
+* Add `databricks version --check` to report whether a newer CLI version is available and print the upgrade command for the detected install method ([#5469](https://github.com/databricks/cli/pull/5469)).
 * `databricks auth describe` now verifies credentials against both the workspace and account endpoints before reporting a failure, fixing false "Unable to authenticate" errors for account console profiles ([#5479](https://github.com/databricks/cli/issues/5479)).
 * `databricks auth login` no longer prompts for workspace selection when logging in to an account console host (`https://accounts.*`). Pass `--workspace-id` explicitly to store a workspace ID on such a profile ([#5504](https://github.com/databricks/cli/pull/5504)).
 * `databricks auth profiles --skip-validate` no longer makes any network calls; the host metadata fetch is skipped along with validation ([#5530](https://github.com/databricks/cli/pull/5530)).
 
 
+
 ### Bundles
 * Set the default `data_security_mode` to `DATA_SECURITY_MODE_AUTO` in bundle templates ([#5452](https://github.com/databricks/cli/pull/5452)).
 * Mark vector search index index_subtype as backend_default to prevent drift after deployment ([#5454](https://github.com/databricks/cli/pull/5454)).

acceptance/cmd/version/out.test.toml

@@ -0,0 +1,20 @@
+
+=== version stays lightweight
+
+>>> [CLI] version
+Databricks CLI v[DEV_VERSION]
+
+=== version --check
+
+>>> [CLI] version --check
+Databricks CLI v[DEV_VERSION]
+This is a development build; skipping the update check.
+
+=== version --check --output json
+
+>>> [CLI] version --check --output json
+{
+  "current_version": "[DEV_VERSION]",
+  "update_available": false,
+  "development_build": true
+}

acceptance/cmd/version/output.txt

@@ -0,0 +1,10 @@
+title "version stays lightweight\n"
+trace $CLI version
+
+# The acceptance binary is a development build, so the check short-circuits
+# without contacting GitHub. This exercises command wiring and output rendering.
+title "version --check\n"
+trace $CLI version --check
+
+title "version --check --output json\n"
+trace $CLI version --check --output json

acceptance/cmd/version/script

@@ -0,0 +1,3 @@
+# The update check is not bundle-aware; run it once instead of per-engine.
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = []

acceptance/cmd/version/test.toml

@@ -6,9 +6,30 @@ import (
 	"github.com/databricks/cli/cmd/root"
 	"github.com/databricks/cli/internal/build"
 	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/versioncheck"
 	"github.com/spf13/cobra"
 )
 
+// updateCheckTemplate renders an update check in text mode. JSON output is
+// rendered directly from the versioncheck.Result struct by cmdio.
+const updateCheckTemplate = `Databricks CLI v{{.CurrentVersion}}
+{{if .DevelopmentBuild -}}
+This is a development build; skipping the update check.
+{{- else if .CheckFailed -}}
+Could not reach GitHub to check for a newer version. See https://github.com/databricks/cli/releases for the latest release.
+{{- else if .UpdateAvailable -}}
+{{yellow "A new version is available"}}: {{.LatestVersion}}
+{{if .UpgradeCommand -}}
+To upgrade, run:
+  {{.UpgradeCommand}}
+{{- else -}}
+Download the latest release: https://github.com/databricks/cli/releases
+{{- end}}
+{{- else -}}
+{{green "You're on the latest version."}}
+{{- end}}
+`
+
 func New() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "version",
@@ -19,8 +40,15 @@ func New() *cobra.Command {
 		},
 	}
 
+	var check bool
+	cmd.Flags().BoolVar(&check, "check", false, "Check whether a newer version of the CLI is available")
+
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
-		return cmdio.Render(cmd.Context(), build.GetInfo())
+		ctx := cmd.Context()
+		if check {
+			return cmdio.RenderWithTemplate(ctx, versioncheck.Check(ctx), "", updateCheckTemplate)
+		}
+		return cmdio.Render(ctx, build.GetInfo())
 	}
 
 	return cmd

cmd/version/version.go

@@ -0,0 +1,87 @@
+package version
+
+import (
+	"testing"
+
+	"github.com/databricks/cli/libs/cmdio"
+	"github.com/databricks/cli/libs/versioncheck"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUpdateCheckTemplate(t *testing.T) {
+	tests := []struct {
+		name   string
+		result versioncheck.Result
+		want   string
+	}{
+		{
+			name: "update available with upgrade command",
+			result: versioncheck.Result{
+				CurrentVersion:  "0.240.0",
+				LatestVersion:   "0.245.0",
+				UpdateAvailable: true,
+				InstallMethod:   versioncheck.InstallHomebrew,
+				UpgradeCommand:  "brew upgrade databricks",
+			},
+			want: `Databricks CLI v0.240.0
+A new version is available: 0.245.0
+To upgrade, run:
+  brew upgrade databricks
+`,
+		},
+		{
+			name: "update available without known install method",
+			result: versioncheck.Result{
+				CurrentVersion:  "0.240.0",
+				LatestVersion:   "0.245.0",
+				UpdateAvailable: true,
+				InstallMethod:   versioncheck.InstallUnknown,
+			},
+			want: `Databricks CLI v0.240.0
+A new version is available: 0.245.0
+Download the latest release: https://github.com/databricks/cli/releases
+`,
+		},
+		{
+			name: "up to date",
+			result: versioncheck.Result{
+				CurrentVersion:  "0.245.0",
+				LatestVersion:   "0.245.0",
+				UpdateAvailable: false,
+			},
+			want: `Databricks CLI v0.245.0
+You're on the latest version.
+`,
+		},
+		{
+			name: "development build",
+			result: versioncheck.Result{
+				CurrentVersion:   "0.0.0-dev+abc123",
+				DevelopmentBuild: true,
+			},
+			want: `Databricks CLI v0.0.0-dev+abc123
+This is a development build; skipping the update check.
+`,
+		},
+		{
+			name: "check failed",
+			result: versioncheck.Result{
+				CurrentVersion: "0.240.0",
+				CheckFailed:    true,
+			},
+			want: `Databricks CLI v0.240.0
+Could not reach GitHub to check for a newer version. See https://github.com/databricks/cli/releases for the latest release.
+`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx, out := cmdio.NewTestContextWithStdout(t.Context())
+			err := cmdio.RenderWithTemplate(ctx, tt.result, "", updateCheckTemplate)
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, out.String())
+		})
+	}
+}