diff --git a/.nextchanges/cli/aitools-install-skills-fallback.md b/.nextchanges/cli/aitools-install-skills-fallback.md new file mode 100644 index 00000000000..ed776cd3574 --- /dev/null +++ b/.nextchanges/cli/aitools-install-skills-fallback.md @@ -0,0 +1 @@ +* `databricks aitools install` now installs skill files for a detected coding agent whose CLI is not on PATH (for example a Claude Code desktop or IDE install), unless it already has the plugin, says how to switch to the plugin later, and warns when the current project also has the plugin. `databricks aitools update` no longer tries to install the plugin for such an agent, and no longer writes skill files next to a plugin that such an agent already has. ([#7482](https://github.com/databricks/cli/pull/7482)) diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json b/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json new file mode 100644 index 00000000000..ee67a12e806 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/installed_plugins.json @@ -0,0 +1 @@ +{"plugins":{"databricks@claude-plugins-official":[{"scope":"user","version":"0.2.9"}]}} diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml b/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/output.txt b/acceptance/experimental/aitools/skills/install-non-interactive/output.txt new file mode 100644 index 00000000000..449731b1b16 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/output.txt @@ -0,0 +1,64 @@ + +=== no flags, no terminal: no prompts, global scope, every detected agent + +>>> [CLI] aitools install +Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'. +Installing Databricks skills for Claude Code, Cursor... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Claude Code has skill files + +=== a plugin installed with Claude Code itself is kept, without skill files next to it + +>>> [CLI] aitools install +Claude Code already has the databricks plugin; it was not refreshed because 'claude' is not on PATH. To refresh it, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'. +Installing Databricks skills for Cursor... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Claude Code has no skill files + +>>> [CLI] aitools update --force + updated test-stable v1.0.0 -> v1.0.0 +Updated 1 skill. +Claude Code has no skill files + +=== a named agent does not fall back: the failure says what to run + +>>> musterr [CLI] aitools install --agents=claude-code +Installing databricks plugin for Claude Code... +Skipped Claude Code: 'claude' is not on PATH + Install or update the Claude Code CLI so 'claude' is on PATH, then re-run 'databricks aitools install --scope=global --agents=claude-code'. Or install skill files instead: databricks aitools install --scope=global --agents=claude-code --skills-only +Error: Claude Code: 'claude' is not on PATH + +=== the suggested recovery command works + +>>> [CLI] aitools install --agents=claude-code --skills-only +Installing Databricks skills for Claude Code... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. + +=== project scope: a personal plugin does not replace the project's skill files + +>>> [CLI] aitools install --scope=project +Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=project --agents=claude-code'. +Installing Databricks skills for Claude Code... +Using skills version test-ref +Fetching skills manifest... +Installed 1 skill. +Skipped Cursor: does not support project-scoped skills + To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor + +>>> [CLI] aitools update --scope=project +Skipped Cursor: does not support project-scoped skills. +Already up to date. +The project has Claude Code skill files + +=== nothing can be set up: the run fails instead of exiting 0 + +>>> musterr [CLI] aitools install --scope=project +Skipped Cursor: does not support project-scoped skills + To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor +Error: nothing was installed; follow the steps above diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/script b/acceptance/experimental/aitools/skills/install-non-interactive/script new file mode 100644 index 00000000000..bb361d77522 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/script @@ -0,0 +1,87 @@ +# Isolate HOME so parallel aitools tests don't race on a shared ~/.databricks. +sethome home + +# Agent config dirs can also be moved by environment variables. Point them all +# at the fixture HOME, so the developer's own agents are not detected and +# nothing is written outside it. +unset CLAUDE_CONFIG_DIR PI_CODING_AGENT_DIR GEMINI_CLI_HOME GOOSE_PATH_ROOT +export XDG_CONFIG_HOME="${USERPROFILE:-$HOME}/.config" +export APPDATA="${USERPROFILE:-$HOME}/AppData/Roaming" + +# Agents are also detected by their CLI binary on PATH, so drop every PATH entry +# that holds one; otherwise the developer's own agents would join the run. That +# can drop /usr/bin (and /bin on a merged-/usr system), so resolve the commands +# the script runs first. Windows also finds a command under each PATHEXT +# extension (e.g. claude.cmd), so check those names too. +mkdir_bin=$(command -v mkdir) +rm_bin=$(command -v rm) +cp_bin=$(command -v cp) +exts="" +if [ -n "${PATHEXT:-}" ]; then exts=$(printf '%s' "$PATHEXT" | tr ';' ':'); fi +filtered_path="" +IFS=: +for dir in $PATH; do + keep=1 + for bin in claude cursor-agent codex opencode copilot pi gemini goose kiro; do + if [ -x "$dir/$bin" ]; then keep=; fi + for ext in $exts; do + if [ -f "$dir/$bin$ext" ]; then keep=; fi + done + done + if [ -n "$keep" ]; then filtered_path="$filtered_path:$dir"; fi +done +unset IFS +export PATH="${filtered_path#:}" + +# Claude Code's config dir exists but its CLI is not on PATH (desktop or IDE +# install). Cursor has no plugin and gets raw skill files. +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude" "${USERPROFILE:-$HOME}/.cursor" + +check_claude_skills() { + if [ -e "${USERPROFILE:-$HOME}/.claude/skills/test-stable" ]; then echo "Claude Code has skill files"; else echo "Claude Code has no skill files"; fi +} + +title "no flags, no terminal: no prompts, global scope, every detected agent" +# Stdin is not a TTY, so the scope select and agent picker are skipped. Cursor +# gets skills; Claude Code's plugin cannot be installed without its CLI, so it +# gets skill files too, with a note on how to switch to the plugin later. +trace $CLI aitools install +check_claude_skills + +title "a plugin installed with Claude Code itself is kept, without skill files next to it" +# Claude Code records its plugins in installed_plugins.json. The run keeps the +# plugin and removes the skill files the previous run gave Claude Code, and a +# later update does not write them back. +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins" +"$cp_bin" installed_plugins.json "${USERPROFILE:-$HOME}/.claude/plugins/" +trace $CLI aitools install +check_claude_skills +trace $CLI aitools update --force +check_claude_skills +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins" + +title "a named agent does not fall back: the failure says what to run" +trace musterr $CLI aitools install --agents=claude-code + +title "the suggested recovery command works" +trace $CLI aitools install --agents=claude-code --skills-only + +title "project scope: a personal plugin does not replace the project's skill files" +# Project skill files are shared through the repository, so a user-scope plugin +# installed with Claude Code itself later must not stop the update from +# refreshing them. Cursor only supports global skills and is skipped. +testdir=$(pwd) +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/project" +cd "${USERPROFILE:-$HOME}/project" +trace $CLI aitools install --scope=project +"$mkdir_bin" -p "${USERPROFILE:-$HOME}/.claude/plugins" +"$cp_bin" "$testdir/installed_plugins.json" "${USERPROFILE:-$HOME}/.claude/plugins/" +trace $CLI aitools update --scope=project +if [ -e .claude/skills/test-stable ]; then echo "The project has Claude Code skill files"; else echo "The project has no Claude Code skill files"; fi +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude/plugins" +cd "$testdir" + +title "nothing can be set up: the run fails instead of exiting 0" +# Cursor only supports global skills, so a project-scope run has nothing to do. +"$rm_bin" -rf "${USERPROFILE:-$HOME}/.claude" +trace musterr $CLI aitools install --scope=project diff --git a/acceptance/experimental/aitools/skills/install-non-interactive/test.toml b/acceptance/experimental/aitools/skills/install-non-interactive/test.toml new file mode 100644 index 00000000000..7afa69b4552 --- /dev/null +++ b/acceptance/experimental/aitools/skills/install-non-interactive/test.toml @@ -0,0 +1,33 @@ +# Mock server replaces raw.githubusercontent.com for manifest + skill 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": { + "test-stable": { + "version": "1.0.0", + "description": "Stable test skill", + "files": ["SKILL.md"], + "repo_dir": "skills" + } + } +} +''' + +[[Server]] +Pattern = "GET /test-ref/skills/test-stable/SKILL.md" +Response.Body = '''--- +name: test-stable +--- + +# Test stable skill +''' diff --git a/cmd/aitools/funnel.go b/cmd/aitools/funnel.go index d82c315c5a9..00f0eadef30 100644 --- a/cmd/aitools/funnel.go +++ b/cmd/aitools/funnel.go @@ -178,9 +178,29 @@ func deliverySteps(outcomes []agentOutcome) []protos.AitoolsCommandStep { return steps } -// anyInstalled reports whether at least one agent was set up. +// anyInstalled reports whether at least one agent was set up: installed, or +// left with the databricks plugin it already had. func anyInstalled(outcomes []agentOutcome) bool { - return slices.ContainsFunc(outcomes, func(o agentOutcome) bool { return o.status == outcomeInstalled }) + return slices.ContainsFunc(outcomes, func(o agentOutcome) bool { + return o.status == outcomeInstalled || o.status == outcomeKept + }) +} + +// onlyKeptPlugins reports whether a run installed nothing and failed for no +// agent, because each agent it set up kept the plugin it already had. The +// funnel records such a run as NOTHING_TO_DO rather than SUCCESS. +func onlyKeptPlugins(outcomes []agentOutcome) bool { + kept := false + for _, o := range outcomes { + switch o.status { + case outcomeInstalled, outcomeFailed: + return false + case outcomeKept: + kept = true + case outcomeSkipped: + } + } + return kept } // firstFailureCategory returns the category of the first agent that failed or diff --git a/cmd/aitools/funnel_test.go b/cmd/aitools/funnel_test.go index fe4be9dd4fc..dcbfe086135 100644 --- a/cmd/aitools/funnel_test.go +++ b/cmd/aitools/funnel_test.go @@ -570,30 +570,99 @@ func TestListFunnelFailure(t *testing.T) { } } -// A plugin failure for an auto-detected agent is only a warning, but when -// nothing got installed the run fails and the funnel must not report SUCCESS. -func TestInstallFunnelDetectedPluginFailureIsNotSuccess(t *testing.T) { - isolateAgents(t) - tmp := t.TempDir() - t.Setenv("HOME", tmp) - t.Setenv("USERPROFILE", tmp) - t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config")) - fakeBinsOnPath(t, "codex") - t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") - setupPluginMock(t) - forbidSkillsInstall(t) - installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { - return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} +// How the funnel finishes when a detected agent's plugin cannot be installed: +// its install failed, or its CLI is missing and it got skill files or kept the +// plugin it already had. +func TestInstallFunnelDetectedPluginAgents(t *testing.T) { + cases := []struct { + name string + claudeConfigDir bool // Claude Code detected by ~/.claude; its CLI is never on PATH + codexOnPath bool // Codex detected by its CLI, whose plugin install fails + pluginInstalled bool + wantErr error + wantShape []string + }{ + { + // A plugin failure for an auto-detected agent is only a warning, but + // when nothing got installed the run fails and the funnel takes the + // category from the agent's outcome. + name: "the only install failed", + codexOnPath: true, + wantErr: errNoAgentSetUp, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:FAILURE:PLUGIN_INSTALL_FAILED", + }, + }, + { + name: "CLI missing, skill files instead", + claudeConfigDir: true, + codexOnPath: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "SKILLS_INSTALLED", "FINISHED:SUCCESS:", + }, + }, + { + // The run installed nothing, but exits 0. + name: "CLI missing, plugin kept", + claudeConfigDir: true, + pluginInstalled: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:NOTHING_TO_DO:", + }, + }, + { + // A kept plugin counts like an installed one: the other agent's + // failed install is only a warning. + name: "CLI missing, plugin kept, another install failed", + claudeConfigDir: true, + codexOnPath: true, + pluginInstalled: true, + wantShape: []string{ + "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", + "FINISHED:SUCCESS:", + }, + }, } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + isolateAgents(t) + tmp := t.TempDir() + t.Setenv("HOME", tmp) + t.Setenv("USERPROFILE", tmp) + t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, ".config")) + if tc.claudeConfigDir { + require.NoError(t, os.MkdirAll(filepath.Join(tmp, ".claude"), 0o755)) + } + var wantPluginCalls []pluginCall + if tc.codexOnPath { + fakeBinsOnPath(t, "codex") + wantPluginCalls = []pluginCall{{agent: agents.NameCodex}} + } else { + fakeBinsOnPath(t) + } + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + stubLegacyCleanup(t) + setupInstallMock(t) + plugins := setupPluginMock(t) + installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { + *plugins = append(*plugins, pluginCall{agent: a.Name}) + return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} + } - // The run installed nothing, so it exits non-zero; the FINISHED event takes - // the category from the agent's outcome. - ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global") - require.ErrorIs(t, err, errNoAgentSetUp) - assert.Equal(t, []string{ - "STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "AGENTS_SELECTED", "PLAN_CONFIRMED", - "FINISHED:FAILURE:PLUGIN_INSTALL_FAILED", - }, funnelShape(funnelEvents(ctx))) + ctx, err := runInstall(t, cmdio.MockDiscard(t.Context()), "--scope", "global") + if tc.wantErr != nil { + require.ErrorIs(t, err, tc.wantErr) + } else { + require.NoError(t, err) + } + assert.Equal(t, wantPluginCalls, *plugins, "only an agent with its CLI on PATH gets a plugin install") + assert.Equal(t, tc.wantShape, funnelShape(funnelEvents(ctx))) + }) + } } func TestAnyInstalledAndFirstFailureCategory(t *testing.T) { @@ -608,6 +677,13 @@ func TestAnyInstalledAndFirstFailureCategory(t *testing.T) { assert.False(t, anyInstalled([]agentOutcome{failed, skipped})) assert.Equal(t, protos.AitoolsErrorCategoryPluginInstallFailed, firstFailureCategory([]agentOutcome{failed, skipped})) + kept := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeKept, errorCategory: protos.AitoolsErrorCategoryCLINotOnPath} + assert.True(t, anyInstalled([]agentOutcome{kept, skipped}), "a kept plugin is set up") + assert.True(t, onlyKeptPlugins([]agentOutcome{kept, skipped})) + assert.False(t, onlyKeptPlugins([]agentOutcome{kept, failed}), "a kept plugin counts like an installed one next to a failed install") + assert.False(t, onlyKeptPlugins([]agentOutcome{kept, installed})) + assert.False(t, onlyKeptPlugins([]agentOutcome{skipped})) + uncategorized := agentOutcome{agent: codex, delivery: deliveryPlugin, status: outcomeFailed} assert.Equal(t, protos.AitoolsErrorCategoryUnsupportedScope, firstFailureCategory([]agentOutcome{installed, uncategorized, skipped})) assert.Equal(t, protos.AitoolsErrorCategoryUncategorized, firstFailureCategory([]agentOutcome{installed, uncategorized})) @@ -820,6 +896,7 @@ func TestUpdateFunnelWhenPluginsFail(t *testing.T) { for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { isolateCommandEnv(t) + fakeBinsOnPath(t, "copilot") dir := saveGlobalState(t, tc.skills) if tc.noPlugins { require.NoError(t, installer.SaveState(dir, &installer.InstallState{SchemaVersion: 2, Release: "v0.2.6", Skills: tc.skills})) diff --git a/cmd/aitools/install.go b/cmd/aitools/install.go index 6a13be5f7b7..62e6f43e2b8 100644 --- a/cmd/aitools/install.go +++ b/cmd/aitools/install.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "os" "runtime" "strings" @@ -27,6 +28,7 @@ var ( installPluginForAgentFn = installer.InstallPluginForAgent recordPluginInstallsFn = installer.RecordPluginInstalls cleanupLegacyFn = installer.RemoveLegacyRawSkills + pluginAlreadyInstalledFn = pluginAlreadyInstalled ) // errNoAgentsSelected is returned when the picker is confirmed with nothing @@ -96,6 +98,15 @@ type agentPlanItem struct { reason string // why the agent is skipped (deliverySkip only) skipErrorCategory protos.AitoolsErrorCategory // error category for the skip (deliverySkip only) explicit bool // named via --agents (blocking it is an error) + // cliMissing marks a detected plugin agent whose CLI is not on PATH, so the + // plugin cannot be installed: it gets skill files instead (deliverySkills), + // or keeps the plugin it already has (deliveryPlugin, nothing is installed). + cliMissing bool + // projectPlugin marks a skills fallback in a directory where the agent + // already loads a databricks plugin that does not cover the install scope: + // a project or local plugin for a global install, or a personal (user or + // local) plugin for a project install. That directory sees both. + projectPlugin bool } // agentChoice is one row in the interactive agent picker. @@ -118,7 +129,13 @@ func NewInstallCmd() *cobra.Command { By default this installs the databricks plugin through each agent's own CLI (Claude Code, Codex, GitHub Copilot). Agents without a headless plugin install -(` + strings.Join(agents.SkillsOnlyNames(), ", ") + `) get raw skill files. +(` + strings.Join(agents.SkillsOnlyNames(), ", ") + `) get raw skill files, and so does a +detected plugin agent whose CLI is not on PATH (for example a desktop or IDE +install) and is not named with --agents, unless it already has the plugin. For +Claude Code that is read from its own plugin list; for Codex and GitHub Copilot +only a plugin installed by 'databricks aitools' is known, so one installed +another way shows every skill twice next to the skill files. A named agent +whose CLI is not on PATH fails; add --skills-only to give it skill files. Escape hatches: --skills-only Force raw skill files for every agent (no plugin). @@ -296,11 +313,12 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } } - plan := buildPlan(targetAgents, scope, skillsOnly, explicit) + plan := buildPlan(ctx, targetAgents, scope, skillsOnly, explicit) funnel.setAgents(plan) funnel.step(ctx, protos.AitoolsCommandStepAgentsSelected) // The picker selection confirms the plan; runs without the picker - // confirm it implicitly. + // confirm it implicitly. The picker labels show which agents get + // skill files instead of the plugin. funnel.step(ctx, protos.AitoolsCommandStepPlanConfirmed) if !explicit && interactive { printInstallScope(ctx, scope) @@ -328,7 +346,11 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } switch { case runErr == nil: - // The deferred funnel.finish records SUCCESS. + // The deferred funnel.finish records SUCCESS; a kept plugin counts + // like an installed one, unless nothing else was done. + if onlyKeptPlugins(outcomes) { + funnel.finishWith(ctx, protos.AitoolsCommandOutcomeNothingToDo, protos.AitoolsErrorCategoryUnspecified) + } case topLevelFailure(runErr) == nil: // Named agents failed, or no agent was set up. A skip has no error // type of its own, so take the category from the outcomes, not runErr. @@ -433,7 +455,7 @@ func agentChoices(ctx context.Context, scope string, skillsOnly bool) []agentCho cmdio.LogString(ctx, "Detecting coding agents...") var choices []agentChoice for _, a := range agents.Registry { - item := planItemFor(a, scope, skillsOnly, false) + item := planItemFor(ctx, a, scope, skillsOnly, false) label := agentChoiceLabel(ctx, a, item, skillsOnly) cmdio.LogString(ctx, fmt.Sprintf(" %-16s %s", a.DisplayName, label)) if item.delivery == deliverySkip { @@ -454,14 +476,21 @@ func agentChoices(ctx context.Context, scope string, skillsOnly bool) []agentCho // agentChoiceLabel is the picker label: the detection state, plus the skip // reason when the agent can't be acted on in the chosen scope. Under // --skills-only every found agent gets raw skills, so it is labeled "skills". +// An agent whose CLI is missing shows the skill files it gets instead of the +// plugin, or that it keeps the plugin it already has. func agentChoiceLabel(ctx context.Context, a *agents.Agent, item agentPlanItem, skillsOnly bool) string { state := a.DisplayState(ctx) label := agentStateLabel(state) if skillsOnly && state != agents.StateNotFound { label = deliverySkills.String() } - if item.delivery == deliverySkip { + switch { + case item.delivery == deliverySkip: return label + " · " + item.reason + case item.cliMissing && item.delivery == deliverySkills: + return "skills · CLI not found" + case item.cliMissing && item.delivery == deliveryPlugin: + return "plugin installed · CLI not found" } return label } @@ -512,10 +541,10 @@ func defaultPromptAgentSelection(_ context.Context, scope string, choices []agen // buildPlan resolves the per-agent delivery and scope. Plugin-first: an agent // with a headless plugin install gets the plugin; --skills-only forces skills // everywhere; agents with no plugin always get skills. -func buildPlan(targetAgents []*agents.Agent, scope string, skillsOnly, explicit bool) []agentPlanItem { +func buildPlan(ctx context.Context, targetAgents []*agents.Agent, scope string, skillsOnly, explicit bool) []agentPlanItem { plan := make([]agentPlanItem, 0, len(targetAgents)) for _, a := range targetAgents { - plan = append(plan, planItemFor(a, scope, skillsOnly, explicit)) + plan = append(plan, planItemFor(ctx, a, scope, skillsOnly, explicit)) } return plan } @@ -523,7 +552,7 @@ func buildPlan(targetAgents []*agents.Agent, scope string, skillsOnly, explicit // planItemFor resolves the delivery and scope for a single agent in the given // install scope. It is shared by buildPlan and the interactive picker so the // picker and the plan agree on what an agent will (or won't) do. -func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agentPlanItem { +func planItemFor(ctx context.Context, a *agents.Agent, scope string, skillsOnly, explicit bool) agentPlanItem { item := agentPlanItem{agent: a, explicit: explicit} switch { case skillsOnly || a.Plugin == nil: @@ -539,11 +568,31 @@ func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agent } default: nativeScope, ok, reason := mapAgentScope(a, scope) - if !ok { + switch { + case !ok: item.delivery = deliverySkip item.reason = reason item.skipErrorCategory = protos.AitoolsErrorCategoryUnsupportedScope - } else { + case !explicit && !a.HasBinary(ctx) && a.Detected(ctx): + // A desktop or IDE-only install has the config dir but no CLI to + // install the plugin with, so it gets the skill files it can use + // today. If it already has the plugin, skill files next to it would + // show every skill twice, so the plugin is kept. A named agent keeps + // failing with the commands to run: --agents never changes delivery. + item.cliMissing = true + item.delivery = deliverySkills + switch { + case pluginAlreadyInstalledFn(ctx, a, scope): + item.delivery = deliveryPlugin + item.scope = nativeScope + default: + // The skill files still serve every other project (global + // scope) or the project's teammates (project scope), but a + // plugin that does not cover this scope and applies here shows + // every skill twice in this directory. + item.projectPlugin = projectPluginActive(ctx, a) + } + default: item.delivery = deliveryPlugin item.scope = nativeScope } @@ -551,6 +600,55 @@ func planItemFor(a *agents.Agent, scope string, skillsOnly, explicit bool) agent return item } +// pluginAlreadyInstalled reports whether the agent already has the databricks +// plugin for this install scope. When the CLI can read the agent's own plugin +// manifest, the manifest decides, as in agents.DatabricksTooling: a plugin +// removed with the agent's own CLI leaves the CLI's record behind. Otherwise, +// or when the manifest exists but cannot be read, the CLI's install state for +// the scope does. +func pluginAlreadyInstalled(ctx context.Context, a *agents.Agent, scope string) bool { + if a.HasPluginManifestReader() { + active, err := manifestPluginActive(ctx, a, scope) + if err == nil { + return active + } + log.Debugf(ctx, "Could not read the plugin manifest of %s, using the install state: %v", a.DisplayName, err) + } + return installer.PluginRecorded(ctx, scope, a.Name) +} + +// manifestPluginActive reports whether the agent's own plugin manifest has a +// databricks plugin that serves this install scope. A global install serves +// every project, so only a machine-wide plugin covers it. A project install is +// shared through the repository, so only a project-scope plugin of this project +// covers it: a machine-wide or local plugin is personal, and teammates would +// get neither the plugin nor the skill files. +func manifestPluginActive(ctx context.Context, a *agents.Agent, scope string) (bool, error) { + if scope != installer.ScopeProject { + return a.DatabricksPluginActiveIn(ctx, "") + } + cwd, err := os.Getwd() + if err != nil { + return false, err + } + return a.DatabricksProjectPluginIn(ctx, cwd) +} + +// projectPluginActive reports whether the agent's own manifest has a databricks +// plugin record that applies in the current directory. Called after a global +// install found no machine-wide plugin, so a match is a project or local one: +// unlike manifestPluginActive for a project install, a local plugin counts, +// since its user sees both. An unreadable manifest or working directory +// reports false. +func projectPluginActive(ctx context.Context, a *agents.Agent) bool { + cwd, err := os.Getwd() + if err != nil { + return false + } + active, err := a.DatabricksPluginActiveIn(ctx, cwd) + return err == nil && active +} + // agentPickerTitle names the install scope, so it is visible before anything // is installed. func agentPickerTitle(scope string) string { @@ -584,6 +682,9 @@ const ( outcomeInstalled outcomeStatus = "installed" outcomeSkipped outcomeStatus = "skipped" outcomeFailed outcomeStatus = "failed" + // outcomeKept is an agent whose CLI is missing but which already has the + // plugin: it is set up, though nothing was installed. + outcomeKept outcomeStatus = "kept" ) // errNoAgentSetUp is returned when no agent was set up: none was detected, or @@ -601,6 +702,62 @@ type agentErrors struct{ err error } func (e *agentErrors) Error() string { return e.err.Error() } func (e *agentErrors) Unwrap() error { return e.err } +// cliMissingOutcome is the plugin outcome of an agent whose CLI is not on PATH: +// failed when it got skill files instead, kept when it already has the plugin. +func cliMissingOutcome(it agentPlanItem, status outcomeStatus) agentOutcome { + return agentOutcome{ + agent: it.agent, + delivery: deliveryPlugin, + status: status, + errorCategory: protos.AitoolsErrorCategoryCLINotOnPath, + message: cliMissingReason(it), + } +} + +// skillsBatchRerun reports the invocation that retries the skills batch when +// it included an agent whose CLI is missing and the run named its agents (the +// picker selection). Re-running with that agent named would try its plugin, +// since --agents never changes delivery, so it re-runs the skills agents with +// --skills-only instead. ok is false when rerun already retries the batch. +func skillsBatchRerun(rerun installInvocation, skillsAgents []*agents.Agent, fallbackItems []agentPlanItem) (installInvocation, bool) { + if rerun.agents == "" || len(fallbackItems) == 0 { + return rerun, false + } + rerun.agents = joinAgentNames(skillsAgents) + rerun.skillsOnly = true + return rerun, true +} + +// skillsBatchError attaches the skillsBatchRerun recovery step to a failed +// skills batch. When there is no such step, the error is returned as is, and +// the caller attaches the step for the whole run. +func skillsBatchError(ctx context.Context, rerun installInvocation, skillsAgents []*agents.Agent, fallbackItems []agentPlanItem, err error) error { + batchRerun, ok := skillsBatchRerun(rerun, skillsAgents, fallbackItems) + if !ok { + return err + } + return withRecovery(ctx, batchRerun, err) +} + +// forgetStalePluginRecords drops the CLI's plugin records of agents that just +// got skill files instead of the plugin. They have no plugin (see +// pluginAlreadyInstalled), so a record left by a removal with the agent's own +// CLI is stale, and list and update would keep treating them as plugin agents +// and never refresh their skill files. The skills are already installed, so a +// failure here is only a warning. +func forgetStalePluginRecords(ctx context.Context, scope string, items []agentPlanItem) { + if len(items) == 0 { + return + } + names := make([]string, len(items)) + for i, it := range items { + names[i] = it.agent.Name + } + if err := installer.ForgetPluginInstalls(ctx, scope, names); err != nil { + log.Warnf(ctx, "Could not drop stale plugin records for %s: %v", strings.Join(names, ", "), err) + } +} + // topLevelFailure returns the run error when it has no per-agent entry, or nil // when the failure is already reported per agent — so a per-agent failure is not // duplicated in the top-level error/errorCategory fields. @@ -612,22 +769,29 @@ func topLevelFailure(runErr error) error { } // executePlan carries out the plan and returns each agent's outcome. Skills -// installs go through the existing skills path. Plugin installs are reported but -// never silently fall back to skills: a blocked install is a warning, unless the -// agent was explicitly named via --agents, which is an error. A run that sets up -// no agent at all is an error too, so callers never mistake it for success. The -// per-agent recovery steps repeat rerun for the agent at hand. +// installs, including those of agents whose CLI is missing, go through the +// existing skills path as one group. A failed plugin install is a warning, +// unless the agent was explicitly named via --agents, which is an error. A run +// that sets up no agent at all is an error too, so callers never mistake it for +// success. The per-agent recovery steps repeat rerun for the agent at hand. func executePlan(ctx context.Context, src installer.ManifestSource, plan []agentPlanItem, opts installer.InstallOptions, rerun installInvocation, quiet bool) ([]agentOutcome, error) { var skillsAgents []*agents.Agent - var pluginItems, skipItems []agentPlanItem + var fallbackItems, keptItems, pluginItems, skipItems []agentPlanItem skillsExplicit := false for _, it := range plan { switch it.delivery { case deliverySkills: skillsAgents = append(skillsAgents, it.agent) skillsExplicit = skillsExplicit || it.explicit + if it.cliMissing { + fallbackItems = append(fallbackItems, it) + } case deliveryPlugin: - pluginItems = append(pluginItems, it) + if it.cliMissing { + keptItems = append(keptItems, it) + } else { + pluginItems = append(pluginItems, it) + } case deliverySkip: skipItems = append(skipItems, it) } @@ -636,6 +800,39 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent var outcomes []agentOutcome var explicitErrs []error + // The plugin could not be installed for these agents. Keep that in the + // outcomes so telemetry still sees it; the skills outcome records the + // fallback. + for _, it := range fallbackItems { + if !quiet { + cmdio.LogString(ctx, cmdio.Yellow(ctx, skillsFallbackText(rerun, it))) + if it.projectPlugin { + cmdio.LogString(ctx, cmdio.Yellow(ctx, projectPluginWarning(opts.Scope, it))) + } + } + outcomes = append(outcomes, cliMissingOutcome(it, outcomeFailed)) + } + + for _, it := range keptItems { + if !quiet { + cmdio.LogString(ctx, cmdio.Yellow(ctx, pluginKeptText(rerun, it))) + } + // Raw skills an earlier run gave this agent would show every skill + // twice next to the plugin, so remove them as a plugin install does. + // This runs before the skills batch: a newer release there replaces the + // recorded checksums, and older copies would then look user-modified + // and stay. Only the agent's own manifest is proof enough: for Codex and + // Copilot the CLI's record is the only evidence, and it outlives a + // removal with the agent's own CLI, so removing the skills then would + // leave the agent with neither. + if active, err := manifestPluginActive(ctx, it.agent, opts.Scope); err == nil && active { + if err := cleanupLegacyFn(ctx, it.agent, opts.Scope); err != nil { + log.Debugf(ctx, "Legacy skill cleanup for %s failed: %v", it.agent.DisplayName, err) + } + } + outcomes = append(outcomes, cliMissingOutcome(it, outcomeKept)) + } + // A skills install runs as a group; its failure is the command's top-level // error. Plugin agents don't depend on it, so they are still attempted. var skillsErr error @@ -648,6 +845,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent for _, a := range skillsAgents { outcomes = append(outcomes, agentOutcome{agent: a, delivery: deliverySkills, status: outcomeInstalled}) } + forgetStalePluginRecords(ctx, opts.Scope, fallbackItems) } } @@ -718,7 +916,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent if errors.Is(skillsErr, installer.ErrNoSkillsResolved) { return outcomes, err } - return outcomes, errors.Join(skillsErr, err) + return outcomes, errors.Join(skillsBatchError(ctx, rerun, skillsAgents, fallbackItems, skillsErr), err) } pluginsRecorded = true } @@ -752,12 +950,14 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent } // A release with no skill this CLI can install skips the skills agents when - // the plan had plugin agents, so the plugin outcomes decide the run. A - // --skills-only run with nothing else attempted keeps the error. So does a - // run whose installed plugins were not recorded (skills without install - // state are on disk): update and uninstall could not manage them. - if errors.Is(skillsErr, installer.ErrNoSkillsResolved) && len(pluginItems) > 0 && (pluginCount == 0 || pluginsRecorded) { - recovery := installRecovery(ctx, rerun, skillsErr) + // the plan had plugin agents, installed or kept, so the plugin outcomes + // decide the run. A --skills-only run with nothing else attempted keeps the + // error. So does a run whose installed plugins were not recorded (skills + // without install state are on disk): update and uninstall could not + // manage them. + if errors.Is(skillsErr, installer.ErrNoSkillsResolved) && (len(pluginItems) > 0 || len(keptItems) > 0) && (pluginCount == 0 || pluginsRecorded) { + batchRerun, _ := skillsBatchRerun(rerun, skillsAgents, fallbackItems) + recovery := installRecovery(ctx, batchRerun, skillsErr) names := make([]string, len(skillsAgents)) for i, a := range skillsAgents { names[i] = a.DisplayName @@ -776,7 +976,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent // The skills error has no per-agent entry, so it stays the top-level error; // explicit per-agent failures are already in their outcomes. if skillsErr != nil { - return outcomes, skillsErr + return outcomes, skillsBatchError(ctx, rerun, skillsAgents, fallbackItems, skillsErr) } if len(explicitErrs) > 0 { return outcomes, &agentErrors{err: errors.Join(explicitErrs...)} diff --git a/cmd/aitools/install_test.go b/cmd/aitools/install_test.go index 2b9ad9ea173..f98e0697e79 100644 --- a/cmd/aitools/install_test.go +++ b/cmd/aitools/install_test.go @@ -6,6 +6,7 @@ import ( "context" "encoding/json" "errors" + "fmt" "io" "io/fs" "net/http" @@ -99,6 +100,24 @@ func setupPluginMock(t *testing.T) *[]pluginCall { return &calls } +// stubPluginAlreadyInstalled pins whether an agent counts as already having the +// plugin; the real check reads the agent's manifest under the real HOME. +func stubPluginAlreadyInstalled(t *testing.T, installed bool) { + t.Helper() + orig := pluginAlreadyInstalledFn + t.Cleanup(func() { pluginAlreadyInstalledFn = orig }) + pluginAlreadyInstalledFn = func(context.Context, *agents.Agent, string) bool { return installed } +} + +// stubLegacyCleanup skips the raw-skill cleanup that follows a plugin install; +// the test agents have no config dir for it to inspect. +func stubLegacyCleanup(t *testing.T) { + t.Helper() + orig := cleanupLegacyFn + t.Cleanup(func() { cleanupLegacyFn = orig }) + cleanupLegacyFn = func(context.Context, *agents.Agent, string) error { return nil } +} + func setupScopeMock(t *testing.T, scope string) *bool { t.Helper() orig := promptScopeSelection @@ -142,6 +161,18 @@ func fakeBinsOnPath(t *testing.T, binaries ...string) { t.Setenv("PATH", dir) } +// writeClaudeManifest writes Claude Code's installed_plugins.json under home +// with one databricks plugin record of the given scope. +func writeClaudeManifest(t *testing.T, home, scope, projectPath string) { + t.Helper() + manifest, err := json.Marshal(map[string]any{"plugins": map[string]any{ + "databricks@claude-plugins-official": []map[string]string{{"scope": scope, "projectPath": projectPath, "version": "0.2.9"}}, + }}) + require.NoError(t, err) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), manifest, 0o600)) +} + func testPluginAgent(name, display, binary string) *agents.Agent { spec := &agents.PluginSpec{Marketplace: "databricks-agent-skills", ID: "databricks", Source: "databricks/databricks-agent-skills"} a := &agents.Agent{Name: name, DisplayName: display, Binary: binary, Plugin: spec} @@ -154,20 +185,21 @@ func testPluginAgent(name, display, binary string) *agents.Agent { // --- buildPlan / mapAgentScope / executePlan unit tests (no detection) --- func TestBuildPlanDeliveries(t *testing.T) { + fakeBinsOnPath(t, "claude") claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") // Cursor is a skills-only agent (no headless plugin install). cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor", Binary: "cursor-agent", SupportsProjectScope: true} opencode := &agents.Agent{Name: agents.NameOpenCode, DisplayName: "OpenCode", Binary: "opencode"} targets := []*agents.Agent{claude, cursor, opencode} - plan := buildPlan(targets, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), targets, installer.ScopeGlobal, false, false) assert.Equal(t, deliveryPlugin, plan[0].delivery) assert.Equal(t, agentScopeUser, plan[0].scope) assert.Equal(t, deliverySkills, plan[1].delivery) // Cursor -> skills assert.Equal(t, deliverySkills, plan[2].delivery) // --skills-only forces skills for every agent. - skillsPlan := buildPlan(targets, installer.ScopeGlobal, true, false) + skillsPlan := buildPlan(t.Context(), targets, installer.ScopeGlobal, true, false) for _, it := range skillsPlan { assert.Equal(t, deliverySkills, it.delivery) } @@ -253,10 +285,11 @@ func choicePreselected(t *testing.T, choices []agentChoice, name string) bool { } func TestBuildPlanProjectScopeSkipsUserOnlyAgent(t *testing.T) { + fakeBinsOnPath(t, "claude", "codex") claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") - plan := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeProject, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeProject, false, false) assert.Equal(t, deliveryPlugin, plan[0].delivery) assert.Equal(t, agentScopeProject, plan[0].scope) assert.Equal(t, deliverySkip, plan[1].delivery) @@ -269,17 +302,17 @@ func TestBuildPlanProjectScopeSkipsFilesOnlyAgent(t *testing.T) { opencode := &agents.Agent{Name: agents.NameOpenCode, DisplayName: "OpenCode", Binary: "opencode"} projectSkills := &agents.Agent{Name: "proj-skills", DisplayName: "Proj", Binary: "proj", SupportsProjectScope: true} - plan := buildPlan([]*agents.Agent{opencode, projectSkills}, installer.ScopeProject, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{opencode, projectSkills}, installer.ScopeProject, false, false) assert.Equal(t, deliverySkip, plan[0].delivery) assert.Contains(t, plan[0].reason, "project-scoped skills") assert.Equal(t, deliverySkills, plan[1].delivery) // --skills-only does not rescue a project-incompatible agent. - skillsOnly := buildPlan([]*agents.Agent{opencode}, installer.ScopeProject, true, false) + skillsOnly := buildPlan(t.Context(), []*agents.Agent{opencode}, installer.ScopeProject, true, false) assert.Equal(t, deliverySkip, skillsOnly[0].delivery) // Under global scope the same agent gets skills. - globalPlan := buildPlan([]*agents.Agent{opencode}, installer.ScopeGlobal, false, false) + globalPlan := buildPlan(t.Context(), []*agents.Agent{opencode}, installer.ScopeGlobal, false, false) assert.Equal(t, deliverySkills, globalPlan[0].delivery) } @@ -302,12 +335,13 @@ func TestMapAgentScope(t *testing.T) { func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude", "codex") orig := installPluginForAgentFn origRec := recordPluginInstallsFn t.Cleanup(func() { installPluginForAgentFn = orig; recordPluginInstallsFn = origRec }) installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { if a.Name == agents.NameClaudeCode { - return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonCLINotOnPath} + return installer.PluginRecord{}, &installer.BlockedError{Agent: a.Name, Reason: installer.ReasonInstallFailed} } return installer.PluginRecord{Version: "0.2.6"}, nil } @@ -322,17 +356,17 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { // Non-explicit blocked install is a warning, not an error, as long as another // agent was set up; the agent's failure is still recorded in its outcome. - plan := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.NoError(t, err) require.Len(t, outcomes, 2) assert.Equal(t, outcomeFailed, outcomes[0].status) - assert.Equal(t, protos.AitoolsErrorCategoryCLINotOnPath, outcomes[0].errorCategory) + assert.Equal(t, protos.AitoolsErrorCategoryPluginInstallFailed, outcomes[0].errorCategory) assert.Equal(t, outcomeInstalled, outcomes[1].status) // Explicit (--agents) blocked install is an error, even when another named // agent was set up. - planExplicit := buildPlan([]*agents.Agent{claude, codex}, installer.ScopeGlobal, false, true) + planExplicit := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, true) _, err = executePlan(ctx, nil, planExplicit, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.Error(t, err) assert.NotErrorIs(t, err, errNoAgentSetUp) @@ -340,6 +374,7 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { func TestExecutePlanNothingInstalledIsAnError(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") orig := installPluginForAgentFn t.Cleanup(func() { installPluginForAgentFn = orig }) installPluginForAgentFn = func(_ context.Context, a *agents.Agent, _, _ string) (installer.PluginRecord, error) { @@ -350,7 +385,7 @@ func TestExecutePlanNothingInstalledIsAnError(t *testing.T) { // used to exit 0 with only a warning, so an agent caller believed it worked. claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) - plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.ErrorIs(t, err, errNoAgentSetUp) @@ -397,7 +432,7 @@ func TestExecutePlanPluginWithUnresolvedSkillsRelease(t *testing.T) { } claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") - plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, true) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, true) outcomes, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.NoError(t, err) require.Len(t, outcomes, 1) @@ -410,6 +445,7 @@ func TestExecutePlanPluginWithUnresolvedSkillsRelease(t *testing.T) { func TestExecutePlanNoSkillsToInstall(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") plugins := setupPluginMock(t) origSkills := installSkillsForAgentsFn origCleanup := cleanupLegacyFn @@ -424,7 +460,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { // Only a skills agent: the run sets up nothing and fails, like an empty // --path dump. - plan := buildPlan([]*agents.Agent{cursor}, installer.ScopeGlobal, true, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor}, installer.ScopeGlobal, true, false) _, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.ErrorIs(t, err, installer.ErrNoSkillsResolved) assert.Error(t, topLevelFailure(err)) @@ -432,7 +468,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { // A plugin was installed too: the run succeeds and Cursor is skipped with // the step. ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) - plan = buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan = buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.NoError(t, err) require.Len(t, *plugins, 1) @@ -446,8 +482,23 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { assert.Contains(t, stderr.String(), "Skipped Cursor: no skills to install") assert.Contains(t, stderr.String(), " No skill in this release can be installed by this CLI.") + // A kept plugin counts like an installed one: the run succeeds too. + *plugins = nil + stubPluginAlreadyInstalled(t, true) + home := t.TempDir() + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude"), 0o755)) + desktopClaude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude-desktop") + desktopClaude.ConfigDir = func(context.Context) (string, error) { return filepath.Join(home, ".claude"), nil } + plan = buildPlan(t.Context(), []*agents.Agent{cursor, desktopClaude}, installer.ScopeGlobal, false, false) + outcomes, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) + require.NoError(t, err) + assert.Empty(t, *plugins) + require.Len(t, outcomes, 2) + assert.Equal(t, outcomeKept, outcomes[0].status) + assert.Equal(t, outcomeSkipped, outcomes[1].status) + // Named via --agents, the skipped skills agent is an error even so. - plan = buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, true) + plan = buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, true) _, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, inv, false) require.ErrorIs(t, err, installer.ErrNoSkillsResolved) assert.NoError(t, topLevelFailure(err)) @@ -455,6 +506,7 @@ func TestExecutePlanNoSkillsToInstall(t *testing.T) { func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") setupPluginMock(t) origSkills := installSkillsForAgentsFn t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) @@ -464,7 +516,7 @@ func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} inv := installInvocation{scope: installer.ScopeGlobal} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) // The plugin install failed: the run failed to set anything up, which is a // FAILURE with the plugin's category, not "nothing to do". @@ -491,9 +543,238 @@ func TestExecutePlanNoSkillsToInstallWithPluginFailures(t *testing.T) { assert.NotErrorIs(t, err, installer.ErrNoSkillsResolved) } +// A detected plugin agent whose CLI is not on PATH (a desktop or IDE install: +// ~/.claude exists, `claude` does not) gets skill files in the same skills +// batch as the other agents, or keeps the plugin it already has. This used to +// print "Skipped Claude Code" and leave the agent with nothing. +func TestExecutePlanWhenTheCLIIsMissing(t *testing.T) { + cases := []struct { + name string + pluginInstalled bool + wantBatches [][]string + wantOutcomes []string + projectPlugin bool + manifestPlugin bool // Claude Code's own manifest shows the plugin + wantCleanup []string + wantNotice string + }{ + { + name: "skill files instead of the plugin", + wantBatches: [][]string{{agents.NameCursor, agents.NameClaudeCode}}, + // The plugin failure stays visible to telemetry next to the skills + // success. + wantOutcomes: []string{"claude-code plugin failed CLI_NOT_ON_PATH", "cursor skills installed ", "claude-code skills installed "}, + wantNotice: "Skipped the plugin for Claude Code: 'claude' is not on PATH. Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.", + }, + { + name: "skill files instead, next to a project plugin", + projectPlugin: true, + wantBatches: [][]string{{agents.NameCursor, agents.NameClaudeCode}}, + wantOutcomes: []string{"claude-code plugin failed CLI_NOT_ON_PATH", "cursor skills installed ", "claude-code skills installed "}, + wantNotice: "Installing skill files instead; to switch to the plugin, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.\nClaude Code has the databricks plugin for this project, so this project will see both the plugin and the global skill files.\n", + }, + { + name: "plugin already installed is kept", + pluginInstalled: true, + manifestPlugin: true, + wantBatches: [][]string{{agents.NameCursor}}, + wantOutcomes: []string{"claude-code plugin kept CLI_NOT_ON_PATH", "cursor skills installed "}, + // Raw skills from an earlier fallback would duplicate the plugin's. + wantCleanup: []string{agents.NameClaudeCode}, + wantNotice: "Claude Code already has the databricks plugin; it was not refreshed because 'claude' is not on PATH. To refresh it, install the Claude Code CLI so 'claude' is on PATH and run 'databricks aitools install --scope=global --agents=claude-code'.", + }, + { + // Only the CLI's record says so (as for Codex and Copilot), and it + // outlives a removal with the agent's own CLI: the raw skills stay. + name: "plugin kept on the CLI's record alone", + pluginInstalled: true, + wantBatches: [][]string{{agents.NameCursor}}, + wantOutcomes: []string{"claude-code plugin kept CLI_NOT_ON_PATH", "cursor skills installed "}, + wantNotice: "Claude Code already has the databricks plugin", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + // First: it resets the environment set below. + isolateAgents(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t) + // The fallback rewrites the install state under HOME. + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + skills := setupInstallMock(t) + plugins := setupPluginMock(t) + var cleaned []string + orig := cleanupLegacyFn + t.Cleanup(func() { cleanupLegacyFn = orig }) + cleanupLegacyFn = func(_ context.Context, a *agents.Agent, _ string) error { + cleaned = append(cleaned, a.Name) + return nil + } + + // Detected by its config dir (a desktop or IDE install). + t.Chdir(t.TempDir()) + claude := agents.ByName(agents.NameClaudeCode) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + if tc.manifestPlugin { + writeClaudeManifest(t, home, "user", "") + } + cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + // planItemFor reads the project plugin from Claude Code's manifest + // (see TestPluginAlreadyInstalledRespectsTheScope); set it here. + plan[1].projectPlugin = tc.projectPlugin + outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) + + require.NoError(t, err) + assert.Empty(t, *plugins, "no plugin install without the CLI") + var batches [][]string + for _, c := range *skills { + batches = append(batches, c.agents) + } + assert.Equal(t, tc.wantBatches, batches) + var got []string + for _, o := range outcomes { + got = append(got, fmt.Sprintf("%s %s %s %s", o.agent.Name, o.delivery, o.status, o.errorCategory)) + } + assert.Equal(t, tc.wantOutcomes, got) + assert.Equal(t, tc.wantCleanup, cleaned) + assert.Contains(t, stderr.String(), tc.wantNotice) + }) + } +} + +// After a picker selection the recovery re-run names the agents, and a named +// agent never falls back, so a failed skills batch that included an agent +// whose CLI is missing is re-run with --skills-only. +func TestExecutePlanSkillsFailureWithAFallbackAgentSuggestsSkillsOnly(t *testing.T) { + isolateAgents(t) + home := setupTestAgents(t) // ~/.claude without `claude`: a desktop install + fakeBinsOnPath(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + t.Chdir(t.TempDir()) + stubPluginAlreadyInstalled(t, false) + origSkills := installSkillsForAgentsFn + t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) + fetchErr := &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: 503, Err: errors.New("failed to fetch manifest: HTTP 503")} + installSkillsForAgentsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.InstallOptions) error { + return fetchErr + } + require.DirExists(t, filepath.Join(home, ".claude")) + + claude := agents.ByName(agents.NameClaudeCode) + cursor := agents.ByName(agents.NameCursor) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + require.True(t, plan[1].cliMissing) + + picked := installInvocation{scope: installer.ScopeGlobal, agents: "cursor,claude-code"} + _, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, picked, true) + require.ErrorIs(t, err, fetchErr) + err = withRecovery(t.Context(), picked, err) + // The value's quoting depends on the shell, so check its parts. + assert.Contains(t, err.Error(), "cursor,claude-code") + assert.Contains(t, err.Error(), " --skills-only") + + // Without a picker selection the re-run detects the same agents, which + // fall back again, so it stays as it is. + _, err = executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, true) + err = withRecovery(t.Context(), installInvocation{scope: installer.ScopeGlobal}, err) + assert.NotContains(t, err.Error(), "--skills-only") +} + +// A release with no skill this CLI can install skips the skills agents when a +// plugin was installed. After a picker selection that named a fallback agent, +// the skip's step re-runs the skills agents with --skills-only, as a failed +// skills batch does: re-run by name, the agent would try its plugin. +func TestExecutePlanNoSkillsWithAFallbackAgentSuggestsSkillsOnly(t *testing.T) { + isolateAgents(t) + setupTestAgents(t) // ~/.claude without `claude`: a desktop install + fakeBinsOnPath(t, "codex") + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + t.Chdir(t.TempDir()) + stubPluginAlreadyInstalled(t, false) + stubLegacyCleanup(t) + plugins := setupPluginMock(t) + origSkills := installSkillsForAgentsFn + t.Cleanup(func() { installSkillsForAgentsFn = origSkills }) + installSkillsForAgentsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.InstallOptions) error { + return installer.ErrNoSkillsResolved + } + + claude := agents.ByName(agents.NameClaudeCode) + codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") + plan := buildPlan(t.Context(), []*agents.Agent{claude, codex}, installer.ScopeGlobal, false, false) + require.True(t, plan[0].cliMissing) + + picked := installInvocation{scope: installer.ScopeGlobal, agents: "claude-code,codex"} + outcomes, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, picked, true) + require.NoError(t, err) + require.Len(t, *plugins, 1) + var skipped *agentOutcome + for i := range outcomes { + if outcomes[i].delivery == deliverySkills { + skipped = &outcomes[i] + } + } + require.NotNil(t, skipped) + assert.Equal(t, agents.NameClaudeCode, skipped.agent.Name) + assert.Contains(t, skipped.recovery, "claude-code") + assert.Contains(t, skipped.recovery, " --skills-only") + assert.NotContains(t, skipped.recovery, "codex") +} + +// The plan decides the fallback, so the picker label, the plan summary and the +// outcomes agree on it. It applies only to a detected agent whose CLI is not on +// PATH: a named agent keeps failing with the commands to run. +func TestPlanItemForAgentWithoutCLI(t *testing.T) { + cases := []struct { + name string + agent string + scope string + onPath bool + explicit bool + pluginInstalled bool + wantDelivery delivery + wantCLIMissing bool + wantLabel string + }{ + {name: "CLI on PATH", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, onPath: true, wantDelivery: deliveryPlugin, wantLabel: "plugin"}, + {name: "CLI missing", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, wantDelivery: deliverySkills, wantCLIMissing: true, wantLabel: "skills · CLI not found"}, + {name: "CLI missing, plugin installed", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, pluginInstalled: true, wantDelivery: deliveryPlugin, wantCLIMissing: true, wantLabel: "plugin installed · CLI not found"}, + {name: "CLI missing, named via --agents", agent: agents.NameClaudeCode, scope: installer.ScopeGlobal, explicit: true, wantDelivery: deliveryPlugin, wantLabel: "plugin · CLI not found"}, + {name: "CLI missing, scope unsupported", agent: agents.NameCodex, scope: installer.ScopeProject, wantDelivery: deliverySkip, wantLabel: "plugin · CLI not found · Codex CLI is user-only; project scope is not supported"}, + // Neither its config dir nor its CLI exists: the picker still lists it, + // but picking it must not write skill files for an agent that is not + // installed. + {name: "not installed", agent: agents.NameCopilot, scope: installer.ScopeGlobal, wantDelivery: deliveryPlugin, wantLabel: "not found"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + home := setupTestAgents(t) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".codex"), 0o755)) + if tc.onPath { + fakeBinsOnPath(t, "claude", "codex") + } else { + fakeBinsOnPath(t) + } + stubPluginAlreadyInstalled(t, tc.pluginInstalled) + a := agents.ByName(tc.agent) + + item := planItemFor(t.Context(), a, tc.scope, false, tc.explicit) + assert.Equal(t, tc.wantDelivery, item.delivery) + assert.Equal(t, tc.wantCLIMissing, item.cliMissing) + assert.Equal(t, tc.wantLabel, agentChoiceLabel(t.Context(), a, item, false)) + }) + } +} + func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { setupTestAgents(t) // temp HOME for the real state file below t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") plugins := setupPluginMock(t) recordPluginInstallsFn = installer.RecordPluginInstalls origSkills := installSkillsForAgentsFn @@ -517,7 +798,7 @@ func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) // The skills failure is still the command's error, but it no longer stops @@ -538,6 +819,7 @@ func TestExecutePlanSkillsFailureStillInstallsPlugins(t *testing.T) { func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { setupTestAgents(t) + fakeBinsOnPath(t, "claude") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") plugins := setupPluginMock(t) recordPluginInstallsFn = installer.RecordPluginInstalls @@ -559,7 +841,7 @@ func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.ErrorIs(t, err, fetchErr) @@ -578,6 +860,7 @@ func TestExecutePlanSkillsFailureKeepsUntrackedSkillsVisible(t *testing.T) { func TestExecutePlanSkillsAndStateWriteFailuresAreJoined(t *testing.T) { setupTestAgents(t) // temp HOME: the skills failure path reads the global skills dir t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t, "claude") setupPluginMock(t) origSkills := installSkillsForAgentsFn origCleanup := cleanupLegacyFn @@ -595,7 +878,7 @@ func TestExecutePlanSkillsAndStateWriteFailuresAreJoined(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} ctx := cmdio.MockDiscard(t.Context()) - plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) + plan := buildPlan(t.Context(), []*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) _, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) // Both failures reach the user, the skills one first. @@ -1340,6 +1623,132 @@ func TestInstallPickerAbortSuggestsFlags(t *testing.T) { assert.Equal(t, "user aborted\nTo install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", err.Error()) } +// The skills fallback is skipped only when the plugin already serves the +// install's scope: a global install serves every project, so only a +// machine-wide plugin covers it, and a project or local plugin counts only for +// a project-scope install inside its own project. +func TestPluginAlreadyInstalledRespectsTheScope(t *testing.T) { + project, other := t.TempDir(), t.TempDir() + // A project install is shared through the repository, so only a + // project-scope plugin of this project covers it; a user or local plugin is + // personal. A fallback warns when this directory sees a plugin that does not + // cover the install next to the skill files: a project or local plugin for a + // global install, a user or local plugin for a project install. + cases := []struct { + name string + scope, projectPath string + wantGlobal, wantInProj bool + wantWarning bool + wantProjectWarning bool + }{ + {name: "user scope", scope: "user", wantGlobal: true, wantProjectWarning: true}, + {name: "project scope of this project", scope: "project", projectPath: project, wantInProj: true, wantWarning: true}, + {name: "local scope of this project", scope: "local", projectPath: project, wantWarning: true, wantProjectWarning: true}, + {name: "project scope of another project", scope: "project", projectPath: other}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + writeClaudeManifest(t, home, tc.scope, tc.projectPath) + t.Chdir(project) + + claude := agents.ByName(agents.NameClaudeCode) + assert.Equal(t, tc.wantGlobal, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal), "global install") + assert.Equal(t, tc.wantInProj, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeProject), "project install") + + // Without the CLI, a global install that falls back to skill files + // flags a project or local plugin of this project: it sees both. + fakeBinsOnPath(t) + item := planItemFor(t.Context(), claude, installer.ScopeGlobal, false, false) + assert.Equal(t, tc.wantWarning, item.projectPlugin, "project plugin next to a global fallback") + item = planItemFor(t.Context(), claude, installer.ScopeProject, false, false) + assert.Equal(t, tc.wantProjectWarning, item.projectPlugin, "personal plugin next to a project fallback") + }) + } +} + +// Removing the plugin with Claude Code's own CLI leaves the CLI's state record +// behind; Claude's manifest is authoritative, so the record must not keep the +// skills fallback from running. +func TestPluginAlreadyInstalledTrustsClaudesManifestOverTheState(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Chdir(t.TempDir()) + require.NoError(t, installer.RecordPluginInstalls(t.Context(), installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), []byte(`{"plugins":{}}`), 0o600)) + + claude := agents.ByName(agents.NameClaudeCode) + assert.False(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) + + // The fallback install drops the stale record, so list stops reporting the + // removed plugin and update reconciles Claude Code's skill files again. + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + fakeBinsOnPath(t) + setupInstallMock(t) + ctx := cmdio.MockDiscard(t.Context()) + plan := buildPlan(t.Context(), []*agents.Agent{claude}, installer.ScopeGlobal, false, false) + _, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, true) + require.NoError(t, err) + + dir, err := installer.GlobalSkillsDir(ctx) + require.NoError(t, err) + state, err := installer.LoadState(dir) + require.NoError(t, err) + assert.NotContains(t, state.Plugins, agents.NameClaudeCode) + fileAgents, _ := excludePluginAgents(ctx, installer.ScopeGlobal, []*agents.Agent{claude}, state) + assert.Equal(t, []*agents.Agent{claude}, fileAgents) + for _, e := range buildAgentEntries(ctx, map[string]*installer.InstallState{installer.ScopeGlobal: state}) { + if e.Name == agents.NameClaudeCode { + assert.NotEqual(t, deliveryPlugin.String(), e.Installed[installer.ScopeGlobal].Delivery) + } + } +} + +// A manifest that exists but cannot be parsed says nothing about the plugin, +// so the CLI's record decides instead of dropping it. +func TestPluginAlreadyInstalledUsesTheStateWhenTheManifestIsUnreadable(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Chdir(t.TempDir()) + require.NoError(t, os.MkdirAll(filepath.Join(home, ".claude", "plugins"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".claude", "plugins", "installed_plugins.json"), []byte(`{not json`), 0o600)) + + claude := agents.ByName(agents.NameClaudeCode) + assert.False(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) + require.NoError(t, installer.RecordPluginInstalls(t.Context(), installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + assert.True(t, pluginAlreadyInstalled(t.Context(), claude, installer.ScopeGlobal)) +} + +func TestPluginAlreadyInstalledReadsTheScopeState(t *testing.T) { + tmp := t.TempDir() + t.Setenv("HOME", tmp) + t.Setenv("USERPROFILE", tmp) + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + claude.ConfigDir = func(context.Context) (string, error) { return filepath.Join(tmp, ".claude"), nil } + ctx := t.Context() + assert.False(t, pluginAlreadyInstalled(ctx, claude, installer.ScopeGlobal)) + + dir, err := installer.GlobalSkillsDir(ctx) + require.NoError(t, err) + require.NoError(t, installer.RecordPluginInstalls(ctx, installer.ScopeGlobal, map[string]installer.PluginRecord{ + agents.NameClaudeCode: {Marketplace: "claude-plugins-official", Plugin: "databricks"}, + }, "v0.2.6")) + require.FileExists(t, filepath.Join(dir, ".state.json")) + assert.True(t, pluginAlreadyInstalled(ctx, claude, installer.ScopeGlobal)) +} + func TestInstallPathFailureHasRecoveryForThePathRun(t *testing.T) { setupTestAgents(t) t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") diff --git a/cmd/aitools/recovery.go b/cmd/aitools/recovery.go index b64988c78c0..ebb02260ca3 100644 --- a/cmd/aitools/recovery.go +++ b/cmd/aitools/recovery.go @@ -173,6 +173,10 @@ func withRecovery(ctx context.Context, inv installInvocation, err error) error { if err == nil { return nil } + // A step attached closer to the failure (see skillsBatchError) wins. + if _, ok := errors.AsType[*recoveryError](err); ok { + return err + } step := installRecovery(ctx, inv, err) if step == "" { return err @@ -453,7 +457,7 @@ func pluginFailureText(ctx context.Context, inv installInvocation, it agentPlanI return fmt.Sprintf("'%s plugin' is not available (%s)", a.Binary, blocked.Detail), fmt.Sprintf("Update the %s CLI to a version with the '%s plugin' command, then re-run %s. Or install skill files instead: %s", a.DisplayName, a.Binary, agentRerun(inv, it), skillsOnlyCommand(inv, it)) } - return fmt.Sprintf("'%s' is not on PATH", a.Binary), + return cliMissingReason(it), fmt.Sprintf("Install or update the %s CLI so '%s' is on PATH, then re-run %s. Or install skill files instead: %s", a.DisplayName, a.Binary, agentRerun(inv, it), skillsOnlyCommand(inv, it)) case blocked.Reason == installer.ReasonShimExitedWithError: // Detail carries the captured stderr and the commands that show the @@ -476,3 +480,37 @@ func skipRecovery(inv installInvocation, it agentPlanItem) string { inv.scope = installer.ScopeGlobal return "To set up " + it.agent.DisplayName + " in the global scope, run: " + installCommand(inv, it) } + +// cliMissingReason is why an agent whose CLI is not on PATH does not get the +// plugin. +func cliMissingReason(it agentPlanItem) string { + return fmt.Sprintf("'%s' is not on PATH", it.agent.Binary) +} + +// switchToPluginStep is how an agent whose CLI is missing gets the plugin later. +func switchToPluginStep(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("install the %s CLI so '%s' is on PATH and run %s", it.agent.DisplayName, it.agent.Binary, agentRerun(inv, it)) +} + +// skillsFallbackText is the notice printed when an agent gets skill files +// instead of the plugin because its CLI is missing. +func skillsFallbackText(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("Skipped the plugin for %s: %s. Installing skill files instead; to switch to the plugin, %s.", + it.agent.DisplayName, cliMissingReason(it), switchToPluginStep(inv, it)) +} + +// projectPluginWarning is printed when a skills fallback runs in a directory +// where the agent already loads a plugin that does not cover the install scope. +func projectPluginWarning(scope string, it agentPlanItem) string { + if scope == installer.ScopeProject { + return it.agent.DisplayName + " has a personal databricks plugin, so you will see both the plugin and this project's skill files here." + } + return it.agent.DisplayName + " has the databricks plugin for this project, so this project will see both the plugin and the global skill files." +} + +// pluginKeptText is the notice for an agent whose CLI is missing but which +// already has the plugin, so no skill files are added next to it. +func pluginKeptText(inv installInvocation, it agentPlanItem) string { + return fmt.Sprintf("%s already has the databricks plugin; it was not refreshed because %s. To refresh it, %s.", + it.agent.DisplayName, cliMissingReason(it), switchToPluginStep(inv, it)) +} diff --git a/cmd/aitools/recovery_test.go b/cmd/aitools/recovery_test.go index 430306abf9c..5c7852d865a 100644 --- a/cmd/aitools/recovery_test.go +++ b/cmd/aitools/recovery_test.go @@ -331,6 +331,8 @@ func TestRecoveryCommandsKeepTheProjectScope(t *testing.T) { notOnPath := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "not found"} _, recovery := pluginFailureText(t.Context(), inv, item, notOnPath) assert.Equal(t, "Install or update the Claude Code CLI so 'claude' is on PATH, then re-run '"+want+"'. Or install skill files instead: "+want+" --skills-only", recovery) + assert.Contains(t, skillsFallbackText(inv, item), "run '"+want+"'.") + assert.Contains(t, pluginKeptText(inv, item), "run '"+want+"'.") timedOut := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "timed out after 20s", TimedOut: true} _, recovery = pluginFailureText(t.Context(), inv, item, timedOut) diff --git a/cmd/aitools/update.go b/cmd/aitools/update.go index 0c23f6d02e5..bdddafbc56c 100644 --- a/cmd/aitools/update.go +++ b/cmd/aitools/update.go @@ -196,7 +196,30 @@ The command exits with code 1 when every update or check it attempts fails.`, targetAgents = mergeAgents(installed, agents.DetectProjectInstalled(cwd)) } - result, err := updateSkillsFn(ctx, src, excludePluginAgents(targetAgents, state), opts) + fileAgents, manifestPlugins := excludePluginAgents(ctx, scope, targetAgents, state) + // Raw skills an earlier install gave an agent that now has the + // plugin would show every skill twice, so remove them as + // install does when it keeps the plugin. + if !check { + for _, a := range manifestPlugins { + if err := updateCleanupLegacyFn(ctx, a, scope); err != nil { + log.Debugf(ctx, "Legacy skill cleanup for %s failed: %v", a.DisplayName, err) + } + } + } + // The plugin agents left no agent that can take file skills in + // this scope, so there is nothing to reconcile. Without this, a + // project whose only project-capable agent has the plugin would + // fail the update with "no agents support project-scoped skills". + // Without install state the reconcile still runs, for the + // "no skills or plugins installed" and legacy-install guidance. + if state != nil && len(manifestPlugins) > 0 && !slices.ContainsFunc(fileAgents, func(a *agents.Agent) bool { + return scope != installer.ScopeProject || a.SupportsProjectScope + }) { + continue + } + + result, err := updateSkillsFn(ctx, src, fileAgents, opts) if err != nil { return err } @@ -258,9 +281,13 @@ func pluginMigrationCandidatesForScope(ctx context.Context, scope string, state if !ok { continue } - // Match install's non-interactive behavior: a raw install for a plugin - // agent should attempt migration and report a skip if its CLI is missing, - // rather than silently staying on raw skills forever. + // Match install's behavior: an agent whose CLI is not on PATH keeps its + // raw skills, which update refreshes, until the CLI is there to install + // the plugin with. An agent with the CLI attempts migration and reports + // a skip if it fails, rather than silently staying on raw skills forever. + if !agent.HasBinary(ctx) { + continue + } hasRawSkills, err := hasManagedRawSkillsForAgentFn(ctx, agent, scope) if err != nil { return nil, err @@ -341,19 +368,31 @@ func mergeAgents(installed, project []*agents.Agent) []*agents.Agent { return merged } -// excludePluginAgents drops agents that are managed as plugins in this scope, so -// the file-skills reconcile never drops duplicate skill files onto a plugin agent. -func excludePluginAgents(installed []*agents.Agent, state *installer.InstallState) []*agents.Agent { - if state == nil || len(state.Plugins) == 0 { - return installed - } - out := make([]*agents.Agent, 0, len(installed)) +// excludePluginAgents splits off agents that have the plugin in this scope, so +// the file-skills reconcile never drops duplicate skill files onto a plugin +// agent. That is an agent the CLI recorded a plugin install for, or one whose +// own manifest shows a plugin serving the scope (see manifestPluginActive) while +// its CLI is missing: install keeps such a plugin, without recording it. With +// the CLI on PATH, raw skills next to the plugin are the user's choice (install +// --skills-only), so they are refreshed as before. manifestPlugins lists the +// agents excluded for their manifest. +func excludePluginAgents(ctx context.Context, scope string, installed []*agents.Agent, state *installer.InstallState) (fileAgents, manifestPlugins []*agents.Agent) { + fileAgents = make([]*agents.Agent, 0, len(installed)) for _, a := range installed { - if _, isPlugin := state.Plugins[a.Name]; !isPlugin { - out = append(out, a) + if state != nil { + if _, isPlugin := state.Plugins[a.Name]; isPlugin { + continue + } + } + if !a.HasBinary(ctx) { + if active, err := manifestPluginActive(ctx, a, scope); err == nil && active { + manifestPlugins = append(manifestPlugins, a) + continue + } } + fileAgents = append(fileAgents, a) } - return out + return fileAgents, manifestPlugins } // hasKnownPluginRecord reports whether state records a plugin for an agent this diff --git a/cmd/aitools/update_test.go b/cmd/aitools/update_test.go index 86c4aa0182e..74e869213ac 100644 --- a/cmd/aitools/update_test.go +++ b/cmd/aitools/update_test.go @@ -118,6 +118,7 @@ func testUpdateCheckPrintsPluginState(t *testing.T, version, want string) { func TestUpdateMigratesManagedRawSkillsToPlugins(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) @@ -193,6 +194,7 @@ func TestUpdateMigratesManagedRawSkillsToPlugins(t *testing.T) { func TestUpdateKeepsRawSkillsWhenPluginMigrationStateWriteFails(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) @@ -258,6 +260,7 @@ func TestUpdateKeepsRawSkillsWhenPluginMigrationStateWriteFails(t *testing.T) { func TestUpdateCheckPrintsPluginMigrationPlan(t *testing.T) { noTelemetryAuth(t) setupTestAgents(t) + fakeBinsOnPath(t, "claude", "codex", "copilot") t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") resetUpdatePluginSeams(t) setupUpdateMock(t) @@ -469,3 +472,147 @@ func TestHasKnownPluginRecord(t *testing.T) { assert.False(t, hasKnownPluginRecord(&installer.InstallState{Plugins: map[string]installer.PluginRecord{"aider": {}}})) assert.True(t, hasKnownPluginRecord(&installer.InstallState{Plugins: map[string]installer.PluginRecord{"aider": {}, agents.NameCodex: {}}})) } + +// A plugin agent whose CLI is not on PATH keeps the raw skills install gave it, +// so update does not try, and fail, to migrate it to the plugin on every run. +func TestPluginMigrationCandidatesNeedTheCLI(t *testing.T) { + setupTestAgents(t) + fakeBinsOnPath(t, "codex") + resetUpdatePluginSeams(t) + hasManagedRawSkillsForAgentFn = func(context.Context, *agents.Agent, string) (bool, error) { return true, nil } + + candidates, err := pluginMigrationCandidatesForScope(t.Context(), installer.ScopeGlobal, nil) + require.NoError(t, err) + var names []string + for _, c := range candidates { + names = append(names, c.agent.Name) + } + assert.Equal(t, []string{agents.NameCodex}, names) +} + +// Install keeps a plugin installed with Claude Code's own CLI without recording +// it, so update must not write the raw skills back next to it. A project's +// skill files are shared, so at project scope only a project-scope plugin of +// this project excludes the agent; a personal (user or local) plugin does not. +func TestExcludePluginAgentsReadsTheAgentsManifest(t *testing.T) { + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + project, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + t.Chdir(project) + claude := agents.ByName(agents.NameClaudeCode) + cursor := agents.ByName(agents.NameCursor) + all := []*agents.Agent{claude, cursor} + fileAgents, manifestPlugins := excludePluginAgents(t.Context(), installer.ScopeGlobal, all, nil) + assert.Equal(t, all, fileAgents) + assert.Empty(t, manifestPlugins) + + cases := []struct { + scope, projectPath string + wantGlobal bool + wantProject bool + }{ + {scope: "user", wantGlobal: true}, + {scope: "local", projectPath: project}, + {scope: "project", projectPath: project, wantProject: true}, + } + for _, tc := range cases { + writeClaudeManifest(t, home, tc.scope, tc.projectPath) + for _, c := range []struct { + cliScope string + want bool + }{{installer.ScopeGlobal, tc.wantGlobal}, {installer.ScopeProject, tc.wantProject}} { + fileAgents, manifestPlugins := excludePluginAgents(t.Context(), c.cliScope, all, nil) + if c.want { + assert.Equal(t, []*agents.Agent{cursor}, fileAgents, "%s plugin, %s update", tc.scope, c.cliScope) + assert.Equal(t, []*agents.Agent{claude}, manifestPlugins, "%s plugin, %s update", tc.scope, c.cliScope) + } else { + assert.Equal(t, all, fileAgents, "%s plugin, %s update", tc.scope, c.cliScope) + assert.Empty(t, manifestPlugins, "%s plugin, %s update", tc.scope, c.cliScope) + } + } + } + + // With the CLI on PATH, raw skills next to the plugin are the user's choice + // (install --skills-only), so they are refreshed and not removed. + writeClaudeManifest(t, home, "user", "") + fakeBinsOnPath(t, "claude") + fileAgents, manifestPlugins = excludePluginAgents(t.Context(), installer.ScopeGlobal, all, nil) + assert.Equal(t, all, fileAgents) + assert.Empty(t, manifestPlugins) + + // A recorded plugin is excluded too, without a manifest reader. + state := &installer.InstallState{Plugins: map[string]installer.PluginRecord{agents.NameCursor: {}}} + fileAgents, _ = excludePluginAgents(t.Context(), installer.ScopeGlobal, all, state) + assert.Equal(t, []*agents.Agent{claude}, fileAgents) +} + +// A project whose only project-capable agent has a project-scope plugin of its +// own has no agent to reconcile file skills for. The update used to fail with +// "no agents support project-scoped skills"; it now skips the reconcile and +// removes the raw skills an earlier install gave that agent. +func TestUpdateProjectScopeSkipsWhenOnlyPluginAgentsRemain(t *testing.T) { + noTelemetryAuth(t) + home := setupTestAgents(t) + fakeBinsOnPath(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + resetUpdatePluginSeams(t) + project, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + t.Chdir(project) + writeClaudeManifest(t, home, "project", project) + + origUpdateSkills := updateSkillsFn + t.Cleanup(func() { updateSkillsFn = origUpdateSkills }) + updateSkillsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.UpdateOptions) (*installer.UpdateResult, error) { + require.Fail(t, "no agent is left to reconcile file skills for") + return nil, nil + } + updatePluginsFn = func(context.Context, string, string) ([]installer.PluginUpdate, error) { return nil, nil } + var cleaned []string + updateCleanupLegacyFn = func(_ context.Context, a *agents.Agent, scope string) error { + cleaned = append(cleaned, a.Name+" "+scope) + return nil + } + + ctx := cmdio.MockDiscard(t.Context()) + dir, err := installer.ProjectSkillsDir(ctx) + require.NoError(t, err) + require.NoError(t, installer.SaveState(dir, &installer.InstallState{ + SchemaVersion: 2, + Release: "v0.2.5", + Skills: map[string]string{"databricks": "0.2.5"}, + })) + + cmd := NewUpdateCmd() + cmd.SetContext(ctx) + cmd.SetArgs([]string{"--scope", "project"}) + require.NoError(t, cmd.Execute()) + assert.Equal(t, []string{agents.NameClaudeCode + " project"}, cleaned) +} + +// Without install state the reconcile still runs when every detected agent has +// the plugin and no CLI, so update keeps telling the user to run install +// instead of exiting 0 having done nothing. +func TestUpdateWithoutStateKeepsTheInstallGuidance(t *testing.T) { + noTelemetryAuth(t) + isolateAgents(t) + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config")) + fakeBinsOnPath(t) + t.Chdir(t.TempDir()) + resetUpdatePluginSeams(t) + writeClaudeManifest(t, home, "user", "") + updateCleanupLegacyFn = func(context.Context, *agents.Agent, string) error { return nil } + + ctx := cmdio.MockDiscard(t.Context()) + cmd := NewUpdateCmd() + cmd.SetContext(ctx) + cmd.SetArgs(nil) + err := cmd.Execute() + require.ErrorIs(t, err, installer.ErrNothingInstalled) +} diff --git a/libs/aitools/agents/agents.go b/libs/aitools/agents/agents.go index a8f59f037b0..92b11077d14 100644 --- a/libs/aitools/agents/agents.go +++ b/libs/aitools/agents/agents.go @@ -61,8 +61,9 @@ type Agent struct { // set per agent (only for formats we have verified); when nil, // DatabricksPluginVersion reports no version and DatabricksTooling falls // back to the CLI install state. New agents extend support by providing - // their own reader here. - pluginInstalls func(ctx context.Context, a *Agent) ([]pluginInstall, bool) + // their own reader here. found is false when the manifest has no databricks + // entry or does not exist; an error means it exists but could not be read. + pluginInstalls func(ctx context.Context, a *Agent) (installs []pluginInstall, found bool, err error) } // Detected reports whether the agent is installed: its config directory exists, diff --git a/libs/aitools/agents/calling.go b/libs/aitools/agents/calling.go index 6e91d7fc9f1..6bb35c3e14b 100644 --- a/libs/aitools/agents/calling.go +++ b/libs/aitools/agents/calling.go @@ -72,7 +72,7 @@ func (a *Agent) DatabricksTooling(ctx context.Context, pluginRecorded func() boo } switch { case a.pluginInstalls != nil: - if a.databricksPluginActiveIn(ctx, cwd) { + if active, _ := a.DatabricksPluginActiveIn(ctx, cwd); active { return ToolingPlugin } case a.Plugin != nil: diff --git a/libs/aitools/agents/plugins.go b/libs/aitools/agents/plugins.go index 794d5c7f4d2..bbac9c443f4 100644 --- a/libs/aitools/agents/plugins.go +++ b/libs/aitools/agents/plugins.go @@ -3,6 +3,9 @@ package agents import ( "context" "encoding/json" + "errors" + "fmt" + "io/fs" "os" "path/filepath" "strings" @@ -15,6 +18,12 @@ import ( // entry as "@" (e.g. "databricks@claude-plugins-official"). const pluginManifestFile = "installed_plugins.json" +// Claude Code's install scopes that apply only inside one project. +const ( + claudeScopeProject = "project" + claudeScopeLocal = "local" +) + // pluginInstall is one install record in an agent's plugin manifest. A plugin // installed in more than one scope has several records. Claude Code documents // the record's scope and version and what each scope covers: @@ -38,7 +47,7 @@ type pluginInstall struct { // must be resolved (see resolvePath). func (p pluginInstall) appliesTo(cwd string) bool { switch p.Scope { - case "project", "local": + case claudeScopeProject, claudeScopeLocal: if p.ProjectPath == "" || cwd == "" { return false } @@ -101,8 +110,8 @@ func (a *Agent) DatabricksPluginVersion(ctx context.Context) (string, bool) { if a.pluginInstalls == nil { return "", false } - installs, ok := a.pluginInstalls(ctx, a) - if !ok { + installs, found, err := a.pluginInstalls(ctx, a) + if err != nil || !found { return "", false } best := "" @@ -115,40 +124,87 @@ func (a *Agent) DatabricksPluginVersion(ctx context.Context) (string, bool) { return best, true } -// databricksPluginActiveIn reports whether the agent's own manifest has a +// HasPluginManifestReader reports whether the CLI can read the agent's own +// plugin manifest (Claude Code), not whether the manifest file exists. For such +// agents the manifest is authoritative: a plugin removed with the agent's own +// CLI leaves the CLI's state record behind. +func (a *Agent) HasPluginManifestReader() bool { + return a.pluginInstalls != nil +} + +// DatabricksPluginActiveIn reports whether the agent's own manifest has a // databricks plugin record that applies in cwd (see pluginInstall.appliesTo). // A plugin disabled in the agent's settings still counts. -func (a *Agent) databricksPluginActiveIn(ctx context.Context, cwd string) bool { - installs, _ := a.pluginInstalls(ctx, a) +// With cwd "", only machine-wide records (not project or local ones) count. +// cwd is resolved here, so a working directory reached through a symlink is +// matched by the directory it points to. A missing manifest reports false; an +// error means the manifest exists but could not be read, so the answer is +// unknown. +func (a *Agent) DatabricksPluginActiveIn(ctx context.Context, cwd string) (bool, error) { + if a.pluginInstalls == nil { + return false, nil + } + if cwd != "" { + cwd = resolvePath(cwd) + } + installs, _, err := a.pluginInstalls(ctx, a) + if err != nil { + return false, err + } for _, install := range installs { if install.appliesTo(cwd) { - return true + return true, nil } } - return false + return false, nil +} + +// DatabricksProjectPluginIn reports whether the agent's own manifest has a +// project-scope databricks plugin record for the project that contains cwd: +// the plugin a project shares through its repository. Machine-wide and local +// records are personal and do not count. A missing manifest reports false; an +// error means the manifest exists but could not be read. +func (a *Agent) DatabricksProjectPluginIn(ctx context.Context, cwd string) (bool, error) { + if a.pluginInstalls == nil { + return false, nil + } + cwd = resolvePath(cwd) + installs, _, err := a.pluginInstalls(ctx, a) + if err != nil { + return false, err + } + for _, install := range installs { + if install.Scope == claudeScopeProject && install.appliesTo(cwd) { + return true, nil + } + } + return false, nil } // claudePluginInstalls reads the databricks plugin's records from Claude Code's // installed_plugins.json (/plugins/), which keys each entry as // "@" (e.g. "databricks@claude-plugins-official") with one // record per install scope. The plugin can be installed from more than one -// marketplace, so the records of every databricks entry are returned. Any -// read/parse failure reports (nil, false), so an unreadable manifest reads as -// "not installed". -func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool) { +// marketplace, so the records of every databricks entry are returned, and found +// reports whether there is any such entry. A missing manifest is not found; a +// manifest that cannot be read or parsed returns an error. +func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool, error) { configDir, err := a.ConfigDir(ctx) if err != nil { - return nil, false + return nil, false, err } data, err := os.ReadFile(filepath.Join(configDir, "plugins", pluginManifestFile)) + if errors.Is(err, fs.ErrNotExist) { + return nil, false, nil + } if err != nil { - return nil, false + return nil, false, err } var manifest struct { Plugins map[string][]pluginInstall `json:"plugins"` } if err := json.Unmarshal(data, &manifest); err != nil { - return nil, false + return nil, false, fmt.Errorf("parse %s: %w", pluginManifestFile, err) } var all []pluginInstall found := false @@ -159,5 +215,5 @@ func claudePluginInstalls(ctx context.Context, a *Agent) ([]pluginInstall, bool) found = true } } - return all, found + return all, found, nil } diff --git a/libs/aitools/agents/plugins_test.go b/libs/aitools/agents/plugins_test.go index 893449ccfba..cb4c10a7f63 100644 --- a/libs/aitools/agents/plugins_test.go +++ b/libs/aitools/agents/plugins_test.go @@ -63,7 +63,8 @@ func TestDatabricksPluginVersionAcrossMarketplaces(t *testing.T) { configDir := t.TempDir() writeManifest(t, configDir, `{"plugins":{"databricks@a":[{"scope":"user","version":"0.2.9"}],"databricks@b":[{"scope":"user","version":"0.3.0"}]}}`) a := agentWithConfigDir(configDir) - installs, ok := claudePluginInstalls(t.Context(), a) + installs, ok, err := claudePluginInstalls(t.Context(), a) + require.NoError(t, err) require.True(t, ok) assert.Len(t, installs, 2) version, ok := a.DatabricksPluginVersion(t.Context()) @@ -85,13 +86,51 @@ func projectFixture(t *testing.T) (project, sub string) { // Every record counts, not only the first one the reader returns. func TestDatabricksPluginActiveInChecksEveryRecord(t *testing.T) { project, _ := projectFixture(t) - a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool) { + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { return []pluginInstall{ {Scope: "project", ProjectPath: filepath.Join(filepath.Dir(project), "Other")}, {Scope: "user"}, - }, true + }, true, nil }} - assert.True(t, a.databricksPluginActiveIn(t.Context(), project)) + active, err := a.DatabricksPluginActiveIn(t.Context(), project) + require.NoError(t, err) + assert.True(t, active) +} + +// A working directory spelled through a symlink inside the project that points +// out of it is the directory it points to, which the project's plugin does not +// cover. +func TestDatabricksPluginActiveInResolvesTheWorkingDir(t *testing.T) { + project, _ := projectFixture(t) + outside := filepath.Join(filepath.Dir(project), "Other") + require.NoError(t, os.Mkdir(outside, 0o755)) + link := filepath.Join(project, "link") + if err := os.Symlink(outside, link); err != nil { + t.Skipf("cannot create a symlink: %v", err) + } + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { + return []pluginInstall{{Scope: "project", ProjectPath: project}}, true, nil + }} + active, err := a.DatabricksPluginActiveIn(t.Context(), link) + require.NoError(t, err) + assert.False(t, active) + active, err = a.DatabricksPluginActiveIn(t.Context(), project) + require.NoError(t, err) + assert.True(t, active) +} + +// A missing manifest means no plugin; one that exists but cannot be parsed +// leaves the answer unknown, so the caller can consult another source. +func TestDatabricksPluginActiveInTellsAMissingManifestFromAnUnreadableOne(t *testing.T) { + configDir := t.TempDir() + a := agentWithConfigDir(configDir) + active, err := a.DatabricksPluginActiveIn(t.Context(), "") + require.NoError(t, err) + assert.False(t, active) + + writeManifest(t, configDir, `{not json`) + _, err = a.DatabricksPluginActiveIn(t.Context(), "") + assert.Error(t, err) } func TestPluginInstallAppliesToProjectOutsideWorkingDir(t *testing.T) { @@ -142,3 +181,27 @@ func TestDatabricksPluginVersionWithoutReader(t *testing.T) { assert.False(t, ok) assert.Empty(t, version) } + +// Only a project-scope record for the project that contains cwd is the +// project's own plugin; user and local records are personal. +func TestDatabricksProjectPluginIn(t *testing.T) { + project, sub := projectFixture(t) + other := filepath.Join(filepath.Dir(project), "Other") + require.NoError(t, os.Mkdir(other, 0o755)) + for _, tc := range []struct { + install pluginInstall + want bool + }{ + {pluginInstall{Scope: "project", ProjectPath: project}, true}, + {pluginInstall{Scope: "project", ProjectPath: other}, false}, + {pluginInstall{Scope: "local", ProjectPath: project}, false}, + {pluginInstall{Scope: "user"}, false}, + } { + a := &Agent{pluginInstalls: func(context.Context, *Agent) ([]pluginInstall, bool, error) { + return []pluginInstall{tc.install}, true, nil + }} + got, err := a.DatabricksProjectPluginIn(t.Context(), sub) + require.NoError(t, err) + assert.Equal(t, tc.want, got, "%+v", tc.install) + } +} diff --git a/libs/aitools/agents/skills.go b/libs/aitools/agents/skills.go index 177f0fcfdf6..ac9acdafeb4 100644 --- a/libs/aitools/agents/skills.go +++ b/libs/aitools/agents/skills.go @@ -38,7 +38,11 @@ func HasDatabricksToolingInstalled(ctx context.Context) bool { cwd = resolvePath(wd) } for _, a := range installed { - if a.pluginInstalls == nil || !a.databricksPluginActiveIn(ctx, cwd) { + if a.pluginInstalls == nil { + return false + } + // An unreadable manifest counts as no plugin, as before. + if active, _ := a.DatabricksPluginActiveIn(ctx, cwd); !active { return false } } diff --git a/libs/aitools/installer/plugin.go b/libs/aitools/installer/plugin.go index e82d590e932..d623a75c496 100644 --- a/libs/aitools/installer/plugin.go +++ b/libs/aitools/installer/plugin.go @@ -38,7 +38,8 @@ const ( // BlockedError reports that a plugin operation could not be performed for an // agent. The command layer maps Reason to a user-facing message and decides // whether to skip-with-warning or hard-fail (per the non-TTY policy). It never -// causes a silent fall back to skills. +// causes a fall back to skills: install gives skill files to an agent whose +// CLI is not on PATH when it plans the run, before any plugin install. type BlockedError struct { Agent string Reason string @@ -528,6 +529,52 @@ func RecordPluginInstalls(ctx context.Context, cliScope string, records map[stri return SaveState(dir, state) } +// PluginRecorded reports whether the CLI install state for cliScope records a +// databricks plugin install for the agent. A scope without state, or a state +// that cannot be read, has no record. +func PluginRecorded(ctx context.Context, cliScope, agentName string) bool { + dir, err := skillsDir(ctx, cliScope) + if err != nil { + return false + } + state, err := LoadState(dir) + if err != nil { + log.Debugf(ctx, "Could not load AI tools install state in %s: %v", dir, err) + return false + } + if state == nil { + return false + } + _, ok := state.Plugins[agentName] + return ok +} + +// ForgetPluginInstalls removes the plugin install records of the named agents +// from the state file for the given CLI scope, for agents that no longer have +// the plugin. Agents without a record, or a scope without state, are left as +// they are. +func ForgetPluginInstalls(ctx context.Context, cliScope string, agentNames []string) error { + dir, err := skillsDir(ctx, cliScope) + if err != nil { + return err + } + state, err := LoadState(dir) + if err != nil || state == nil { + return err + } + changed := false + for _, name := range agentNames { + if _, ok := state.Plugins[name]; ok { + delete(state.Plugins, name) + changed = true + } + } + if !changed { + return nil + } + return SaveState(dir, state) +} + // ManualPluginInstallCommands returns the commands, in order, that install the // databricks plugin through the agent's own CLI. When the headless install // fails, running them by hand shows the agent's full output. Returns nil for an diff --git a/libs/aitools/installer/plugin_test.go b/libs/aitools/installer/plugin_test.go index 8bcfb0ded69..645dec6a853 100644 --- a/libs/aitools/installer/plugin_test.go +++ b/libs/aitools/installer/plugin_test.go @@ -857,6 +857,37 @@ func TestRunAgentCmdTimeoutKeepsPartialStderr(t *testing.T) { assert.Equal(t, "timed out after 1ms: Waiting for login...", blocked.Detail) } +func TestForgetPluginInstalls(t *testing.T) { + setupTestHome(t) + t.Chdir(t.TempDir()) + ctx := t.Context() + dir, err := GlobalSkillsDir(ctx) + require.NoError(t, err) + + // No state yet: nothing to forget, and no state file is created. + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameClaudeCode})) + st, err := LoadState(dir) + require.NoError(t, err) + assert.Nil(t, st) + assert.False(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) + + require.NoError(t, RecordPluginInstalls(ctx, ScopeGlobal, map[string]PluginRecord{ + agents.NameClaudeCode: {Marketplace: "databricks-agent-skills", Plugin: "databricks"}, + agents.NameCodex: {Marketplace: "databricks-agent-skills", Plugin: "databricks"}, + }, "v0.2.6")) + assert.True(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) + assert.False(t, PluginRecorded(ctx, ScopeProject, agents.NameClaudeCode), "the project scope has its own state") + + // An agent without a record is left alone; a recorded one is dropped. + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameCopilot})) + require.NoError(t, ForgetPluginInstalls(ctx, ScopeGlobal, []string{agents.NameClaudeCode})) + st, err = LoadState(dir) + require.NoError(t, err) + assert.NotContains(t, st.Plugins, agents.NameClaudeCode) + assert.Contains(t, st.Plugins, agents.NameCodex) + assert.False(t, PluginRecorded(ctx, ScopeGlobal, agents.NameClaudeCode)) +} + func TestRunAgentCmdReportsTimeout(t *testing.T) { // A slow agent CLI used to be reported as "not on PATH" with whatever the // killed process left on stderr. diff --git a/libs/aitools/installer/useragent.go b/libs/aitools/installer/useragent.go index 95a7cab6492..e34eb549038 100644 --- a/libs/aitools/installer/useragent.go +++ b/libs/aitools/installer/useragent.go @@ -4,7 +4,6 @@ import ( "context" "github.com/databricks/cli/libs/aitools/agents" - "github.com/databricks/cli/libs/log" "github.com/databricks/databricks-sdk-go/useragent" ) @@ -63,27 +62,9 @@ func WithCallingAgentToolingInUserAgent(ctx context.Context) context.Context { if a == nil { return ctx } - tooling := a.DatabricksTooling(ctx, func() bool { return globalPluginRecorded(ctx, a.Name) }) + // Only the global state is read: the CLI installs plugins in project scope + // only for agents with SupportsProjectScope (see mapAgentScope in + // cmd/aitools), and those have a manifest reader. + tooling := a.DatabricksTooling(ctx, func() bool { return PluginRecorded(ctx, ScopeGlobal, a.Name) }) return useragent.InContext(ctx, callingAgentToolingUserAgentKey, tooling.String()) } - -// globalPluginRecorded reports whether the global CLI install state records a -// databricks plugin install for the agent. Only the global state is read: the -// CLI installs plugins in project scope only for agents with SupportsProjectScope -// (see mapAgentScope in cmd/aitools), and those have a manifest reader. -func globalPluginRecorded(ctx context.Context, agentName string) bool { - dir, err := GlobalSkillsDir(ctx) - if err != nil { - return false - } - state, err := LoadState(dir) - if err != nil { - log.Debugf(ctx, "Could not load AI tools install state in %s: %v", dir, err) - return false - } - if state == nil { - return false - } - _, ok := state.Plugins[agentName] - return ok -}