From c5eef9cc3d7d9e3c04ed3082a38b34f5f1821dd3 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:22:06 +0000 Subject: [PATCH 1/2] aitools: store the auto-install state and opt-out, gate it in cli-compat First of three changes that install Databricks AI tools automatically on the first run of a new CLI version. This one stores the state and the opt-out and adds the remote gate; nothing installs yet. - ~/.databricks/aitools/auto-install.json holds last_version, attempts and opted_out. It is a dedicated file, not a libs/cache entry, so an opt-out survives upgrades and `databricks cache clear`. - `databricks aitools auto-install disable|enable` toggles the opt-out; enable warns when DATABRICKS_AITOOLS_AUTO_INSTALL=false is set. - A global-scope `databricks aitools uninstall` (including --skills and --agents) opts out. - cli-compat.json entries get an optional auto_install field, resolved by clicompat.ResolveAutoInstall. No entry sets it, and TestManifestLeavesAutoInstallOff keeps it off. Co-authored-by: Isaac --- .agents/skills/bump-cli-compat/SKILL.md | 2 +- .../cli/aitools-auto-install-opt-out.md | 1 + .../auto-install/enable-disable/out.test.toml | 1 + .../auto-install/enable-disable/output.txt | 57 ++++++++++ .../auto-install/enable-disable/script | 35 ++++++ .../cmd/aitools/auto-install/script.prepare | 5 + acceptance/cmd/aitools/auto-install/test.toml | 35 ++++++ cmd/aitools/aitools.go | 1 + cmd/aitools/autoinstall.go | 65 +++++++++++ cmd/aitools/uninstall.go | 14 +++ libs/aitools/autoinstall/state.go | 101 ++++++++++++++++++ libs/clicompat/clicompat.go | 17 +++ libs/clicompat/clicompat_test.go | 39 +++++++ 13 files changed, 372 insertions(+), 1 deletion(-) create mode 100644 .nextchanges/cli/aitools-auto-install-opt-out.md create mode 100644 acceptance/cmd/aitools/auto-install/enable-disable/out.test.toml create mode 100644 acceptance/cmd/aitools/auto-install/enable-disable/output.txt create mode 100644 acceptance/cmd/aitools/auto-install/enable-disable/script create mode 100644 acceptance/cmd/aitools/auto-install/script.prepare create mode 100644 acceptance/cmd/aitools/auto-install/test.toml create mode 100644 cmd/aitools/autoinstall.go create mode 100644 libs/aitools/autoinstall/state.go diff --git a/.agents/skills/bump-cli-compat/SKILL.md b/.agents/skills/bump-cli-compat/SKILL.md index 454c93e14a9..a5808c4ea8b 100644 --- a/.agents/skills/bump-cli-compat/SKILL.md +++ b/.agents/skills/bump-cli-compat/SKILL.md @@ -89,7 +89,7 @@ Write the updated `internal/build/cli-compat.json` and `internal/build/clicompat Ask the user for the **minimum CLI version** that supports the new features. -Add a new entry keyed to that CLI version with the new `appkit` and `"skills": "latest"`. Update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go` to the tested skills version. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries. +Add a new entry keyed to that CLI version with the new `appkit` and `"skills": "latest"`. If the previous highest entry has `"auto_install": true`, copy it to the new entry: it turns on the automatic installation of AI tools for its range, so a new entry without it turns the feature off for every newer CLI. Update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go` to the tested skills version. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries. Write the updated `internal/build/cli-compat.json` and `internal/build/clicompat.go`. diff --git a/.nextchanges/cli/aitools-auto-install-opt-out.md b/.nextchanges/cli/aitools-auto-install-opt-out.md new file mode 100644 index 00000000000..cd24a1a300d --- /dev/null +++ b/.nextchanges/cli/aitools-auto-install-opt-out.md @@ -0,0 +1 @@ +* Add `databricks aitools auto-install disable` and `enable` to turn off (or back on) the automatic installation of Databricks AI tools on CLI upgrades. A global-scope `databricks aitools uninstall` also turns it off. ([#7701](https://github.com/databricks/cli/pull/7701)) diff --git a/acceptance/cmd/aitools/auto-install/enable-disable/out.test.toml b/acceptance/cmd/aitools/auto-install/enable-disable/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/aitools/auto-install/enable-disable/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/aitools/auto-install/enable-disable/output.txt b/acceptance/cmd/aitools/auto-install/enable-disable/output.txt new file mode 100644 index 00000000000..c5b3db00b1f --- /dev/null +++ b/acceptance/cmd/aitools/auto-install/enable-disable/output.txt @@ -0,0 +1,57 @@ + +=== nothing stored yet + +>>> auto_install_state +(no auto-install state) + +=== disable stores the opt-out + +>>> [CLI] aitools auto-install disable +Automatic installation of Databricks AI tools is disabled. + +>>> auto_install_state +{ + "opted_out": true +} + +=== enable clears it + +>>> [CLI] aitools auto-install enable +Automatic installation of Databricks AI tools is enabled. + +>>> auto_install_state +{} + +=== enable says when the environment still turns it off + +>>> DATABRICKS_AITOOLS_AUTO_INSTALL=false [CLI] aitools auto-install enable +Automatic installation of Databricks AI tools is enabled. +DATABRICKS_AITOOLS_AUTO_INSTALL still disables it in this environment; unset it to let it run. + +=== disable replaces a state file it cannot read + +>>> [CLI] aitools auto-install disable +Automatic installation of Databricks AI tools is disabled. + +>>> auto_install_state +{ + "opted_out": true +} + +=== a global uninstall turns it off + +>>> [CLI] aitools uninstall --scope=global +Uninstalled 1 skill. + +>>> auto_install_state +{ + "opted_out": true +} + +=== a project uninstall leaves it on + +>>> [CLI] aitools uninstall --scope=project +Uninstalled 1 skill. + +>>> auto_install_state +{} diff --git a/acceptance/cmd/aitools/auto-install/enable-disable/script b/acceptance/cmd/aitools/auto-install/enable-disable/script new file mode 100644 index 00000000000..7b802bfb85a --- /dev/null +++ b/acceptance/cmd/aitools/auto-install/enable-disable/script @@ -0,0 +1,35 @@ +sethome home +mkdir -p "${USERPROFILE:-$HOME}/.cursor" + +title "nothing stored yet" +trace auto_install_state + +title "disable stores the opt-out" +trace $CLI aitools auto-install disable +trace auto_install_state + +title "enable clears it" +trace $CLI aitools auto-install enable +trace auto_install_state + +title "enable says when the environment still turns it off" +trace DATABRICKS_AITOOLS_AUTO_INSTALL=false $CLI aitools auto-install enable + +title "disable replaces a state file it cannot read" +echo "not json" > "${USERPROFILE:-$HOME}/.databricks/aitools/auto-install.json" +trace $CLI aitools auto-install disable +trace auto_install_state +$CLI aitools auto-install enable > /dev/null 2>&1 + +title "a global uninstall turns it off" +$CLI aitools install --skills-only --scope=global --agents=cursor &> LOG.install-global +trace $CLI aitools uninstall --scope=global +trace auto_install_state +$CLI aitools auto-install enable > /dev/null 2>&1 + +title "a project uninstall leaves it on" +mkdir -p "${USERPROFILE:-$HOME}/project" +cd "${USERPROFILE:-$HOME}/project" +$CLI aitools install --skills-only --scope=project --agents=claude-code &> LOG.install-project +trace $CLI aitools uninstall --scope=project +trace auto_install_state diff --git a/acceptance/cmd/aitools/auto-install/script.prepare b/acceptance/cmd/aitools/auto-install/script.prepare new file mode 100644 index 00000000000..8f64b39a860 --- /dev/null +++ b/acceptance/cmd/aitools/auto-install/script.prepare @@ -0,0 +1,5 @@ +# auto_install_state prints the persisted auto-install state. +auto_install_state() { + local path="${USERPROFILE:-$HOME}/.databricks/aitools/auto-install.json" + if [ -f "$path" ]; then cat "$path"; else echo "(no auto-install state)"; fi +} diff --git a/acceptance/cmd/aitools/auto-install/test.toml b/acceptance/cmd/aitools/auto-install/test.toml new file mode 100644 index 00000000000..9fef185795b --- /dev/null +++ b/acceptance/cmd/aitools/auto-install/test.toml @@ -0,0 +1,35 @@ +# Automatic installation of Databricks AI tools on the first run of a new CLI +# version. The mock server replaces raw.githubusercontent.com (skills manifest +# and files). +Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST" +Env.DATABRICKS_SKILLS_REF = "test-ref" + +Ignore = [ + "home", +] + +[[Server]] +Pattern = "GET /test-ref/manifest.json" +Response.Body = ''' +{ + "version": "2", + "updated_at": "2026-01-01T00:00:00Z", + "skills": { + "databricks-test": { + "version": "1.0.0", + "description": "Test skill", + "files": ["SKILL.md"], + "repo_dir": "skills" + } + } +} +''' + +[[Server]] +Pattern = "GET /test-ref/skills/databricks-test/SKILL.md" +Response.Body = '''--- +name: databricks-test +--- + +# Test skill +''' diff --git a/cmd/aitools/aitools.go b/cmd/aitools/aitools.go index 503bfc634ec..2805d891ef5 100644 --- a/cmd/aitools/aitools.go +++ b/cmd/aitools/aitools.go @@ -31,4 +31,5 @@ https://github.com/databricks/databricks-agent-skills` cmd.AddCommand(NewUninstallCmd()) cmd.AddCommand(NewListCmd()) cmd.AddCommand(NewVersionCmd()) + cmd.AddCommand(newAutoInstallCmd()) } diff --git a/cmd/aitools/autoinstall.go b/cmd/aitools/autoinstall.go new file mode 100644 index 00000000000..7dd77896490 --- /dev/null +++ b/cmd/aitools/autoinstall.go @@ -0,0 +1,65 @@ +package aitools + +import ( + "context" + "fmt" + + "github.com/databricks/cli/libs/aitools/autoinstall" + "github.com/databricks/cli/libs/cmdio" + "github.com/spf13/cobra" +) + +func newAutoInstallCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "auto-install", + Short: "Turn the automatic installation of Databricks AI tools on or off", + Long: `Turn the automatic installation of Databricks AI tools on or off. + +On the first run of a new CLI version, the CLI can install the Databricks AI +tools (skills and plugins) for the coding agents already on this machine, as +'databricks aitools install --scope=global' does, or update an existing +installation, as 'databricks aitools update' does. It never runs in CI and only +touches the global scope. + +It stays off after 'databricks aitools auto-install disable' or a global-scope +'databricks aitools uninstall', until 'databricks aitools auto-install enable'. +Setting ` + autoinstall.EnvVar + `=false turns it off in that environment.`, + } + cmd.AddCommand(newAutoInstallToggleCmd(true)) + cmd.AddCommand(newAutoInstallToggleCmd(false)) + return cmd +} + +// newAutoInstallToggleCmd returns `auto-install enable` or `auto-install disable`. +func newAutoInstallToggleCmd(enable bool) *cobra.Command { + use, short := "disable", "Turn off the automatic installation of Databricks AI tools" + if enable { + use, short = "enable", "Turn the automatic installation of Databricks AI tools back on" + } + return &cobra.Command{ + Use: use, + Short: short, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + ctx := cmd.Context() + if err := autoinstall.SetOptedOut(ctx, !enable); err != nil { + return fmt.Errorf("failed to save the auto-install setting: %w", err) + } + printAutoInstallSetting(ctx, enable) + return nil + }, + } +} + +// printAutoInstallSetting confirms the stored setting. An enable that the +// environment still overrides says so, rather than looking like it worked. +func printAutoInstallSetting(ctx context.Context, enabled bool) { + if !enabled { + cmdio.LogString(ctx, "Automatic installation of Databricks AI tools is disabled.") + return + } + cmdio.LogString(ctx, "Automatic installation of Databricks AI tools is enabled.") + if autoinstall.EnvOptedOut(ctx) { + cmdio.LogString(ctx, cmdio.Yellow(ctx, autoinstall.EnvVar+" still disables it in this environment; unset it to let it run.")) + } +} diff --git a/cmd/aitools/uninstall.go b/cmd/aitools/uninstall.go index 787156ff519..5a12d73a8d9 100644 --- a/cmd/aitools/uninstall.go +++ b/cmd/aitools/uninstall.go @@ -7,8 +7,10 @@ import ( "slices" "strings" + "github.com/databricks/cli/libs/aitools/autoinstall" "github.com/databricks/cli/libs/aitools/installer" "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/cli/libs/log" "github.com/databricks/cli/libs/telemetry/protos" "github.com/spf13/cobra" ) @@ -27,6 +29,10 @@ func NewUninstallCmd() *cobra.Command { By default, removes all skills. Use --skills to remove specific skills only. +A global-scope uninstall also turns off the automatic installation of +Databricks AI tools on CLI upgrades; 'databricks aitools auto-install enable' +turns it back on. + The command exits with code 1 when every removal it attempts fails.`, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { @@ -103,6 +109,14 @@ The command exits with code 1 when every removal it attempts fails.`, if state != nil && skillsInstalled(state, opts.Skills) { waitForTelemetryAuth(ctx) } + // Auto-install only ever installs in global scope, so only a global + // uninstall could be undone by it on the next CLI upgrade. A partial + // one counts too: the update it runs re-adds removed skills. + if scope == installer.ScopeGlobal { + if err := autoinstall.SetOptedOut(ctx, true); err != nil { + log.Warnf(ctx, "Could not turn off the automatic installation of Databricks AI tools: %v", err) + } + } result, err := uninstallSkillsFn(ctx, opts) if err != nil { return err diff --git a/libs/aitools/autoinstall/state.go b/libs/aitools/autoinstall/state.go new file mode 100644 index 00000000000..5227b14ef53 --- /dev/null +++ b/libs/aitools/autoinstall/state.go @@ -0,0 +1,101 @@ +// Package autoinstall holds what the CLI remembers about installing Databricks +// AI tools automatically on the first run of a new CLI version. +package autoinstall + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + + "github.com/databricks/cli/libs/atomicfile" + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/log" +) + +// stateFileName is the state file under ~/.databricks/aitools. It is not a +// libs/cache entry: cache entries are namespaced by CLI version and expire, +// and this state must outlive upgrades and `databricks cache clear`. +const stateFileName = "auto-install.json" + +// State is what auto-install remembers across CLI versions. +type State struct { + // LastVersion is the CLI version auto-install last ran for. + LastVersion string `json:"last_version,omitempty"` + + // Attempts counts the failed attempts for LastVersion. It is 0 once a run + // for LastVersion succeeded or was skipped for good. + Attempts int `json:"attempts,omitempty"` + + // OptedOut turns auto-install off for every later version. It is set by + // `databricks aitools auto-install disable` and by a global-scope + // `databricks aitools uninstall`. + OptedOut bool `json:"opted_out,omitempty"` +} + +// statePath returns ~/.databricks/aitools/auto-install.json. +func statePath(ctx context.Context) (string, error) { + home, err := env.UserHomeDir(ctx) + if err != nil { + return "", err + } + return filepath.Join(home, ".databricks", "aitools", stateFileName), nil +} + +// Load reads the state. A missing file is the zero State. +func Load(ctx context.Context) (State, error) { + path, err := statePath(ctx) + if err != nil { + return State{}, err + } + data, err := os.ReadFile(path) + if errors.Is(err, fs.ErrNotExist) { + return State{}, nil + } + if err != nil { + return State{}, err + } + var s State + if err := json.Unmarshal(data, &s); err != nil { + return State{}, fmt.Errorf("parse %s: %w", filepath.ToSlash(path), err) + } + return s, nil +} + +// Save writes the state atomically. +func Save(ctx context.Context, s State) error { + path, err := statePath(ctx) + if err != nil { + return err + } + data, err := json.MarshalIndent(s, "", " ") + if err != nil { + return err + } + return atomicfile.Write(path, append(data, '\n'), 0o600, atomicfile.MkDir(0o755)) +} + +// SetOptedOut turns auto-install off (true) or back on (false), keeping the +// rest of the state. A state file that cannot be read is replaced: the user's +// explicit choice matters more than a broken record. +func SetOptedOut(ctx context.Context, optedOut bool) error { + s, err := Load(ctx) + if err != nil { + log.Debugf(ctx, "Replacing unreadable auto-install state: %v", err) + s = State{} + } + s.OptedOut = optedOut + return Save(ctx, s) +} + +// EnvVar turns auto-install off when set to false (or 0, no, off). +const EnvVar = "DATABRICKS_AITOOLS_AUTO_INSTALL" + +// EnvOptedOut reports whether EnvVar turns auto-install off. +func EnvOptedOut(ctx context.Context) bool { + enabled, ok := env.GetBool(ctx, EnvVar) + return ok && !enabled +} diff --git a/libs/clicompat/clicompat.go b/libs/clicompat/clicompat.go index 446c8e4755c..7d9f6f746fa 100644 --- a/libs/clicompat/clicompat.go +++ b/libs/clicompat/clicompat.go @@ -56,6 +56,13 @@ const ( type Entry struct { AppKit string `json:"appkit"` AgentSkills string `json:"skills"` + + // AutoInstall turns on the automatic installation of Databricks AI tools + // on the first run of a new CLI version in this range. Off when absent, so + // the feature ships off and can be turned on (or off again) remotely; a + // change reaches a machine on its first run of a version after the change. + // CLIs that predate the field ignore it. + AutoInstall bool `json:"auto_install,omitempty"` } // Manifest is the compatibility manifest: a map of CLI version strings to entries. @@ -287,6 +294,16 @@ func ResolveAgentSkillsVersion(ctx context.Context) (string, error) { return entry.AgentSkills, nil } +// ResolveAutoInstall reports whether the manifest entry for cliVersion turns on +// the automatic installation of Databricks AI tools. +func ResolveAutoInstall(ctx context.Context, cliVersion string) (bool, error) { + entry, err := resolveEntry(ctx, cliVersion) + if err != nil { + return false, err + } + return entry.AutoInstall, nil +} + // --- Local manifest cache --- // manifestLocalPath returns the path to the locally cached manifest file. diff --git a/libs/clicompat/clicompat_test.go b/libs/clicompat/clicompat_test.go index 644df86efdf..1fda6a53979 100644 --- a/libs/clicompat/clicompat_test.go +++ b/libs/clicompat/clicompat_test.go @@ -324,6 +324,45 @@ func TestResolveAgentSkillsVersion(t *testing.T) { } } +func TestResolveAutoInstall(t *testing.T) { + manifest := `{ + "1.20.0": {"appkit": "0.84.0", "skills": "0.2.30"}, + "1.30.0": {"appkit": "0.84.0", "skills": "0.2.30", "auto_install": true} + }` + tests := []struct { + cliVersion string + want bool + }{ + {cliVersion: "1.25.0", want: false}, + {cliVersion: "1.30.0", want: true}, + {cliVersion: "1.31.2", want: true}, + } + for _, tc := range tests { + t.Run(tc.cliVersion, func(t *testing.T) { + ctx := testContext(t) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + _, _ = w.Write([]byte(manifest)) + })) + defer srv.Close() + redirectToServer(t, srv) + + got, err := ResolveAutoInstall(ctx, tc.cliVersion) + require.NoError(t, err) + assert.Equal(t, tc.want, got) + }) + } +} + +// The remote manifest is this same file on main, so turning auto_install on +// anywhere is a launch decision: change this test in the PR that makes it. +func TestManifestLeavesAutoInstallOff(t *testing.T) { + m, err := parseManifest(build.CLICompatManifestJSON) + require.NoError(t, err) + for version, entry := range m { + assert.False(t, entry.AutoInstall, "auto_install is on for %s", version) + } +} + // --- ResolveEmbeddedAppKitVersion --- func TestResolveEmbeddedAppKitVersion(t *testing.T) { From 8926e091f13a5bf6b6388f614c8435256c129003 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Tue, 17 Nov 2026 14:26:39 +0000 Subject: [PATCH 2/2] aitools: address review on the auto-install opt-out - A global uninstall opts out only when it removed something, so a mistyped --skills or an empty scope no longer turns auto-install off. - `aitools auto-install ` now fails instead of printing help and exiting 0. - Document auto_install in internal/build/README.md (format, the copy-forward step for new entries, the trust model). - Say that any non-true DATABRICKS_AITOOLS_AUTO_INSTALL value opts out, and move EnvVar next to the other constant. - Add unit tests for the state file; pin the env var in the acceptance test and log the reset steps instead of discarding them. Co-authored-by: Isaac --- .../auto-install/enable-disable/output.txt | 20 +++++ .../auto-install/enable-disable/script | 14 +++- acceptance/cmd/aitools/auto-install/test.toml | 2 + cmd/aitools/autoinstall.go | 5 +- cmd/aitools/uninstall.go | 17 ++-- internal/build/README.md | 6 +- libs/aitools/autoinstall/state.go | 7 +- libs/aitools/autoinstall/state_test.go | 80 +++++++++++++++++++ libs/clicompat/clicompat_test.go | 5 +- 9 files changed, 137 insertions(+), 19 deletions(-) create mode 100644 libs/aitools/autoinstall/state_test.go diff --git a/acceptance/cmd/aitools/auto-install/enable-disable/output.txt b/acceptance/cmd/aitools/auto-install/enable-disable/output.txt index c5b3db00b1f..d651e45cd40 100644 --- a/acceptance/cmd/aitools/auto-install/enable-disable/output.txt +++ b/acceptance/cmd/aitools/auto-install/enable-disable/output.txt @@ -38,6 +38,26 @@ Automatic installation of Databricks AI tools is disabled. "opted_out": true } +=== a global uninstall that removes nothing leaves it on + +>>> [CLI] aitools uninstall --scope=global +Error: no skills or plugins installed + +Exit code: 1 + +>>> auto_install_state +{} + +=== a global uninstall of a mistyped skill leaves it on + +>>> [CLI] aitools uninstall --scope=global --skills databricks-tset +Error: skill "databricks-tset" is not installed + +Exit code: 1 + +>>> auto_install_state +{} + === a global uninstall turns it off >>> [CLI] aitools uninstall --scope=global diff --git a/acceptance/cmd/aitools/auto-install/enable-disable/script b/acceptance/cmd/aitools/auto-install/enable-disable/script index 7b802bfb85a..6bf99ed965d 100644 --- a/acceptance/cmd/aitools/auto-install/enable-disable/script +++ b/acceptance/cmd/aitools/auto-install/enable-disable/script @@ -19,13 +19,21 @@ title "disable replaces a state file it cannot read" echo "not json" > "${USERPROFILE:-$HOME}/.databricks/aitools/auto-install.json" trace $CLI aitools auto-install disable trace auto_install_state -$CLI aitools auto-install enable > /dev/null 2>&1 +$CLI aitools auto-install enable &> LOG.enable-reset-1 -title "a global uninstall turns it off" +title "a global uninstall that removes nothing leaves it on" +errcode trace $CLI aitools uninstall --scope=global +trace auto_install_state + +title "a global uninstall of a mistyped skill leaves it on" $CLI aitools install --skills-only --scope=global --agents=cursor &> LOG.install-global +errcode trace $CLI aitools uninstall --scope=global --skills databricks-tset +trace auto_install_state + +title "a global uninstall turns it off" trace $CLI aitools uninstall --scope=global trace auto_install_state -$CLI aitools auto-install enable > /dev/null 2>&1 +$CLI aitools auto-install enable &> LOG.enable-reset-2 title "a project uninstall leaves it on" mkdir -p "${USERPROFILE:-$HOME}/project" diff --git a/acceptance/cmd/aitools/auto-install/test.toml b/acceptance/cmd/aitools/auto-install/test.toml index 9fef185795b..da6d94db55c 100644 --- a/acceptance/cmd/aitools/auto-install/test.toml +++ b/acceptance/cmd/aitools/auto-install/test.toml @@ -3,6 +3,8 @@ # and files). Env.DATABRICKS_SKILLS_BASE_URL = "$DATABRICKS_HOST" Env.DATABRICKS_SKILLS_REF = "test-ref" +# Pin it so an opt-out exported in the developer's shell does not change the output. +Env.DATABRICKS_AITOOLS_AUTO_INSTALL = "true" Ignore = [ "home", diff --git a/cmd/aitools/autoinstall.go b/cmd/aitools/autoinstall.go index 7dd77896490..9cafbf4d5cf 100644 --- a/cmd/aitools/autoinstall.go +++ b/cmd/aitools/autoinstall.go @@ -4,6 +4,7 @@ import ( "context" "fmt" + "github.com/databricks/cli/cmd/root" "github.com/databricks/cli/libs/aitools/autoinstall" "github.com/databricks/cli/libs/cmdio" "github.com/spf13/cobra" @@ -23,7 +24,9 @@ touches the global scope. It stays off after 'databricks aitools auto-install disable' or a global-scope 'databricks aitools uninstall', until 'databricks aitools auto-install enable'. -Setting ` + autoinstall.EnvVar + `=false turns it off in that environment.`, +Setting ` + autoinstall.EnvVar + ` to anything but a true value (true, 1, yes, +on) turns it off in that environment.`, + RunE: root.ReportUnknownSubcommand, } cmd.AddCommand(newAutoInstallToggleCmd(true)) cmd.AddCommand(newAutoInstallToggleCmd(false)) diff --git a/cmd/aitools/uninstall.go b/cmd/aitools/uninstall.go index 5a12d73a8d9..88af82e36a6 100644 --- a/cmd/aitools/uninstall.go +++ b/cmd/aitools/uninstall.go @@ -29,8 +29,8 @@ func NewUninstallCmd() *cobra.Command { By default, removes all skills. Use --skills to remove specific skills only. -A global-scope uninstall also turns off the automatic installation of -Databricks AI tools on CLI upgrades; 'databricks aitools auto-install enable' +A global-scope uninstall that removes anything also turns off the automatic +installation of Databricks AI tools on CLI upgrades; 'databricks aitools auto-install enable' turns it back on. The command exits with code 1 when every removal it attempts fails.`, @@ -109,18 +109,19 @@ The command exits with code 1 when every removal it attempts fails.`, if state != nil && skillsInstalled(state, opts.Skills) { waitForTelemetryAuth(ctx) } + result, err := uninstallSkillsFn(ctx, opts) + if err != nil { + return err + } // Auto-install only ever installs in global scope, so only a global // uninstall could be undone by it on the next CLI upgrade. A partial - // one counts too: the update it runs re-adds removed skills. - if scope == installer.ScopeGlobal { + // one counts too: the update it runs re-adds removed skills. A run + // that removed nothing (a mistyped skill, nothing installed) does not. + if scope == installer.ScopeGlobal && (result.PluginsRemoved > 0 || result.SkillsChanged > 0) { if err := autoinstall.SetOptedOut(ctx, true); err != nil { log.Warnf(ctx, "Could not turn off the automatic installation of Databricks AI tools: %v", err) } } - result, err := uninstallSkillsFn(ctx, opts) - if err != nil { - return err - } // A plugin or skill that could not be removed is only a warning, unless // no copy of any skill and no plugin was removed at all. A plugin record // for an agent this CLI does not know is not an attempt: no command can diff --git a/internal/build/README.md b/internal/build/README.md index 0adf8c77a22..d82afac3751 100644 --- a/internal/build/README.md +++ b/internal/build/README.md @@ -19,6 +19,8 @@ Each key is a CLI version in semver format. Each entry defines a **range floor** `skills` is an exact pin for its CLI range or `"latest"` to install the skills repository's latest published GitHub release. When the latest-release lookup fails or the selected skills manifest is missing, ranges tracking latest use `AgentSkillsFallbackVersion` from `internal/build/clicompat.go`. Pinned ranges use their embedded manifest's skills version as the fallback. Changing either fallback takes effect in the next CLI build. Released binaries keep the fallback they shipped with. +An entry can also set `"auto_install": true` to turn on the automatic installation of Databricks AI tools on the first run of a new CLI version in its range (`aitools auto-install`). It is off when absent. A change reaches a machine on its first run of a CLI version after the change; machines that resolve to a cached or embedded manifest keep the value they have. + This skills fallback only applies to raw-file delivery. Version checks omit update availability when latest is unknown, and plugin operations don't substitute the fallback version. Raw-skills updates and reinstalls reject automatic downgrades, including with `--force`: the fallback must be at least as new as the installed release. Existing installs without a comparable release require a successful latest-release fetch. Explicit `DATABRICKS_SKILLS_REF` overrides and compatibility pins can still select an older release. @@ -62,7 +64,7 @@ When updating AppKit or recording a tested skills fallback: 1. **Run evals** on the new AppKit version. If there is no regression, proceed. 2. **Open a PR** to update `cli-compat.json`. The change depends on the type of release: - **No breaking changes**: update the highest entry's `appkit` in-place, keeping `"skills": "latest"`. To record a tested skills fallback, update `AgentSkillsFallbackVersion` in `internal/build/clicompat.go`. Do NOT add a new versioned key. - - **Breaking changes** (the new AppKit templates require specific `apps init` features, or the new skills version requires CLI commands that older CLIs lack): add a new entry keyed to the **minimum CLI version** that supports the new features. Set `"skills": "latest"` on the new entry and update the compiled skills fallback to a tested release. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries. + - **Breaking changes** (the new AppKit templates require specific `apps init` features, or the new skills version requires CLI commands that older CLIs lack): add a new entry keyed to the **minimum CLI version** that supports the new features. Set `"skills": "latest"` on the new entry and update the compiled skills fallback to a tested release. If skills compatibility changed, replace `"latest"` in the affected older ranges with the last compatible release. Preserve unrelated AppKit and skills compatibility boundaries. If the previous highest entry sets `"auto_install": true`, copy it to the new entry: a new entry without it turns auto-install off for every newer CLI. This process is manual for now but can be automated as part of the release workflow in the future. Use the `/bump-cli-compat` Claude Code skill to automate the update and PR creation. @@ -82,4 +84,4 @@ Entries MUST NOT be removed from the manifest. Older CLI binaries use the lowest ## Trust model -The live manifest is fetched over HTTPS from GitHub (`raw.githubusercontent.com`). The trust boundary is: TLS certificate validation + GitHub's access controls + write access to the `main` branch of `databricks/cli`. A compromised manifest can only steer clients to existing published tags (AppKit or skills); it cannot inject arbitrary code. The CLI binary always ships an embedded fallback manifest that limits exposure to cache-TTL windows (1 hour). The local cache (`~/.cache/databricks/compat-manifest.json`) is trust-on-disk: an attacker with user-level write access to the cache directory could swap in a malicious manifest pointing to different tags. +The live manifest is fetched over HTTPS from GitHub (`raw.githubusercontent.com`). The trust boundary is: TLS certificate validation + GitHub's access controls + write access to the `main` branch of `databricks/cli`. A compromised manifest can steer clients to existing published tags (AppKit or skills), and through `auto_install` make them install those published skills and plugins without a command from the user; it cannot inject arbitrary code. The CLI binary always ships an embedded fallback manifest that limits exposure to cache-TTL windows (1 hour). The local cache (`~/.cache/databricks/compat-manifest.json`) is trust-on-disk: an attacker with user-level write access to the cache directory could swap in a malicious manifest pointing to different tags. diff --git a/libs/aitools/autoinstall/state.go b/libs/aitools/autoinstall/state.go index 5227b14ef53..313b429434e 100644 --- a/libs/aitools/autoinstall/state.go +++ b/libs/aitools/autoinstall/state.go @@ -21,6 +21,10 @@ import ( // and this state must outlive upgrades and `databricks cache clear`. const stateFileName = "auto-install.json" +// EnvVar turns auto-install off when set to anything but a true value (true, +// 1, yes, on), including an empty or unparseable value. +const EnvVar = "DATABRICKS_AITOOLS_AUTO_INSTALL" + // State is what auto-install remembers across CLI versions. type State struct { // LastVersion is the CLI version auto-install last ran for. @@ -91,9 +95,6 @@ func SetOptedOut(ctx context.Context, optedOut bool) error { return Save(ctx, s) } -// EnvVar turns auto-install off when set to false (or 0, no, off). -const EnvVar = "DATABRICKS_AITOOLS_AUTO_INSTALL" - // EnvOptedOut reports whether EnvVar turns auto-install off. func EnvOptedOut(ctx context.Context) bool { enabled, ok := env.GetBool(ctx, EnvVar) diff --git a/libs/aitools/autoinstall/state_test.go b/libs/aitools/autoinstall/state_test.go new file mode 100644 index 00000000000..ea4e5c8476c --- /dev/null +++ b/libs/aitools/autoinstall/state_test.go @@ -0,0 +1,80 @@ +package autoinstall + +import ( + "os" + "path/filepath" + "testing" + + "github.com/databricks/cli/libs/env" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestLoadMissingFileIsZeroState(t *testing.T) { + ctx := env.WithUserHomeDir(t.Context(), t.TempDir()) + + s, err := Load(ctx) + require.NoError(t, err) + assert.Equal(t, State{}, s) +} + +func TestLoadCorruptFileFails(t *testing.T) { + home := t.TempDir() + ctx := env.WithUserHomeDir(t.Context(), home) + path := filepath.Join(home, ".databricks", "aitools", stateFileName) + require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o755)) + require.NoError(t, os.WriteFile(path, []byte("not json"), 0o600)) + + _, err := Load(ctx) + assert.ErrorContains(t, err, "parse ") +} + +func TestSetOptedOutKeepsOtherFields(t *testing.T) { + ctx := env.WithUserHomeDir(t.Context(), t.TempDir()) + require.NoError(t, Save(ctx, State{LastVersion: "1.2.3", Attempts: 2})) + + require.NoError(t, SetOptedOut(ctx, true)) + s, err := Load(ctx) + require.NoError(t, err) + assert.Equal(t, State{LastVersion: "1.2.3", Attempts: 2, OptedOut: true}, s) + + require.NoError(t, SetOptedOut(ctx, false)) + s, err = Load(ctx) + require.NoError(t, err) + assert.Equal(t, State{LastVersion: "1.2.3", Attempts: 2}, s) +} + +func TestSetOptedOutReplacesCorruptFile(t *testing.T) { + home := t.TempDir() + ctx := env.WithUserHomeDir(t.Context(), home) + path := filepath.Join(home, ".databricks", "aitools", stateFileName) + require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o755)) + require.NoError(t, os.WriteFile(path, []byte("not json"), 0o600)) + + require.NoError(t, SetOptedOut(ctx, true)) + s, err := Load(ctx) + require.NoError(t, err) + assert.Equal(t, State{OptedOut: true}, s) +} + +func TestEnvOptedOut(t *testing.T) { + ctx := t.Context() + assert.False(t, EnvOptedOut(ctx), "unset") + + for value, want := range map[string]bool{ + "true": false, + "1": false, + "yes": false, + "on": false, + "false": true, + "0": true, + "no": true, + "off": true, + "": true, + "enabled": true, + } { + t.Run(value, func(t *testing.T) { + assert.Equal(t, want, EnvOptedOut(env.Set(ctx, EnvVar, value))) + }) + } +} diff --git a/libs/clicompat/clicompat_test.go b/libs/clicompat/clicompat_test.go index 1fda6a53979..f4ce7613f71 100644 --- a/libs/clicompat/clicompat_test.go +++ b/libs/clicompat/clicompat_test.go @@ -353,8 +353,9 @@ func TestResolveAutoInstall(t *testing.T) { } } -// The remote manifest is this same file on main, so turning auto_install on -// anywhere is a launch decision: change this test in the PR that makes it. +// TestManifestLeavesAutoInstallOff checks that no entry turns auto_install on. +// The remote manifest is this same file on main, so turning it on anywhere is a +// launch decision: change this test in the PR that makes it. func TestManifestLeavesAutoInstallOff(t *testing.T) { m, err := parseManifest(build.CLICompatManifestJSON) require.NoError(t, err)