From c9931c1045a827c13d51c31e604911ff26138620 Mon Sep 17 00:00:00 2001 From: Anton Nekipelov <226657+anton-107@users.noreply.github.com> Date: Wed, 11 Nov 2026 13:53:13 +0000 Subject: [PATCH] aitools: print a recovery step for every install failure A failed `databricks aitools install` now ends with a step the user (or an agent calling the CLI) can take, in the text output and in a new `recovery` field of `--output json` (top level and per agent). ```text install RunE rerun := the run's flags (scope, agents, skills, --path, --skills-only, --experimental, --output json) ... install ... on error: withRecovery(ctx, rerun, err) # cmd/aitools/recovery.go per-agent errors -> no extra step (each agent printed its own) empty picker selection -> name --scope and --agents to skip prompts switch classifyInstallError(err) # the telemetry category USER_ABORTED, PROMPT_FAILED -> name --scope and --agents to skip prompts NETWORK, TIMEOUT (fetch with no response), RELEASE_LOOKUP_FAILED, RATE_LIMITED, MANIFEST_NOT_FOUND, MANIFEST_INVALID, SKILLS_FETCH_FAILED -> per host / HTTP status / missing release STATE_INVALID -> move the state file aside, re-run (global scope: without --skills) SKILL_NOT_FOUND, VERSION_INCOMPATIBLE -> 'databricks aitools list', or upgrade the CLI EXPERIMENTAL_SKILL -> no extra step (the message names --experimental) PERMISSION_DENIED -> check ownership (e.g. an earlier sudo run) FILESYSTEM -> check the path is writable and has free space otherwise -> RefusedError (downgrade, legacy guard): no extra step; else re-run with --debug, report at github.com/databricks/cli/issues per-agent plugin failure / skip -> exact agent CLI commands (installer.ManualPluginInstallCommands) or the run's command narrowed to that agent ``` - The recovery step is chosen from the category `classifyInstallError` returns, so the advice and the telemetry category cannot disagree. - Every re-run command, including the per-agent ones, repeats this run's choices (scope, `--skills-only`, `--skills`, `--experimental`, `--output json`), so a copied command never widens to every agent or the global scope. Agents chosen by flag or in the picker are named; auto-detected agents are not (the retry detects them again). A skipped agent gets the command for just that agent in the global scope. - `--path`, `--agents` and `--skills` values are quoted for the user's shell: POSIX quoting, or the new `shellquote.WindowsArg` for cmd.exe/PowerShell. If no quoting keeps a value literal (`$`, `` ` ``, `%`, `!`, `"`, control characters on Windows; control characters on POSIX), the step says "your original install command" instead of printing a command that could expand or run something. On Windows, `--path` is printed with forward slashes, so it pastes the same into cmd.exe, PowerShell and Git Bash. A command that contains a single quote is delimited with backticks instead of single quotes. - The installer's downgrade refusal and legacy-install guard return the new `installer.RefusedError`; their messages already name the fix, so no generic step is added when the refusal is the failure. The legacy-install message now names `--scope=global --skills-only`, the install that rebuilds skills state now that plugins are the default. - The step appended to an error drops its final period (error strings must not end with punctuation). The error still unwraps to the original, so the telemetry category does not change. - "No supported coding agents found" now also says how to name an agent that was not detected. - Changelog fragment: `.nextchanges/cli/aitools-install-recovery.md`. Co-authored-by: Isaac --- .nextchanges/cli/aitools-install-recovery.md | 1 + .../telemetry/install-failure/output.txt | 4 + .../output.txt | 3 +- .../output.txt | 6 +- .../install-output-json-error/output.txt | 3 +- cmd/aitools/funnel_test.go | 2 +- cmd/aitools/install.go | 74 ++- cmd/aitools/install_test.go | 96 +++- cmd/aitools/recovery.go | 471 ++++++++++++++++++ cmd/aitools/recovery_test.go | 470 +++++++++++++++++ cmd/root/stale_version.go | 4 +- cmd/root/stale_version_test.go | 2 +- libs/aitools/installer/errors.go | 11 + libs/aitools/installer/installer.go | 4 +- libs/aitools/installer/installer_test.go | 35 ++ libs/aitools/installer/plugin.go | 20 + libs/aitools/installer/plugin_test.go | 13 + libs/shellquote/quote.go | 40 ++ libs/shellquote/quote_test.go | 71 +++ 19 files changed, 1299 insertions(+), 31 deletions(-) create mode 100644 .nextchanges/cli/aitools-install-recovery.md create mode 100644 cmd/aitools/recovery.go create mode 100644 cmd/aitools/recovery_test.go diff --git a/.nextchanges/cli/aitools-install-recovery.md b/.nextchanges/cli/aitools-install-recovery.md new file mode 100644 index 00000000000..50cb46dcf8f --- /dev/null +++ b/.nextchanges/cli/aitools-install-recovery.md @@ -0,0 +1 @@ +* `databricks aitools install` now ends a failed install with a step to recover, in the text output and in a new `recovery` field of `--output json`. ([#7480](https://github.com/databricks/cli/pull/7480)) diff --git a/acceptance/cmd/aitools/telemetry/install-failure/output.txt b/acceptance/cmd/aitools/telemetry/install-failure/output.txt index 380eea4597c..70aa956837d 100644 --- a/acceptance/cmd/aitools/telemetry/install-failure/output.txt +++ b/acceptance/cmd/aitools/telemetry/install-failure/output.txt @@ -6,6 +6,7 @@ Installing Databricks skills for Cursor... Using skills version test-ref Fetching skills manifest... Error: skill "nonexistent" not found +Run 'databricks aitools list' to see the available skills >>> print_telemetry {"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}} @@ -23,6 +24,7 @@ Installing Databricks skills for Cursor... Using skills version missing-ref Fetching skills manifest... Error: skills manifest at databricks-agent-skills@missing-ref: not found +No skills release exists at the version DATABRICKS_SKILLS_REF names. Unset it, or set it to a release tag from https://github.com/databricks/databricks-agent-skills/releases, then re-run 'databricks aitools install --scope=global --agents=cursor --skills-only' >>> print_telemetry {"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}} @@ -40,6 +42,7 @@ Installing Databricks skills for Cursor... Using skills version broken-ref Fetching skills manifest... Error: failed to fetch manifest: HTTP 500 +[DATABRICKS_HOST] returned HTTP 500, a server-side error. Wait a few minutes and re-run 'databricks aitools install --scope=global --agents=cursor --skills-only' >>> print_telemetry {"command":"aitools_install","exit_code":1,"aitools_command_event":{"command":"INSTALL","stage":"STARTED","interactive":false,"install_mode":"SKILLS_ONLY"}} @@ -54,6 +57,7 @@ Error: failed to fetch manifest: HTTP 500 >>> [CLI] aitools install --skills-only --scope=project --agents=cursor Skipped Cursor: does not support project-scoped skills + To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only Error: Cursor: does not support project-scoped skills >>> print_telemetry diff --git a/acceptance/experimental/aitools/skills/install-output-json-agent-error/output.txt b/acceptance/experimental/aitools/skills/install-output-json-agent-error/output.txt index cf2f618437d..b047db890c4 100644 --- a/acceptance/experimental/aitools/skills/install-output-json-agent-error/output.txt +++ b/acceptance/experimental/aitools/skills/install-output-json-agent-error/output.txt @@ -15,7 +15,8 @@ "delivery": "skip", "status": "skipped", "error_category": "UNSUPPORTED_SCOPE", - "message": "does not support project-scoped skills" + "message": "does not support project-scoped skills", + "recovery": "To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only --output json" } ] } diff --git a/acceptance/experimental/aitools/skills/install-output-json-agents-skipped/output.txt b/acceptance/experimental/aitools/skills/install-output-json-agents-skipped/output.txt index 2b5f8d403a8..5bffc78c9d7 100644 --- a/acceptance/experimental/aitools/skills/install-output-json-agents-skipped/output.txt +++ b/acceptance/experimental/aitools/skills/install-output-json-agents-skipped/output.txt @@ -10,14 +10,16 @@ "delivery": "skip", "status": "skipped", "error_category": "UNSUPPORTED_SCOPE", - "message": "does not support project-scoped skills" + "message": "does not support project-scoped skills", + "recovery": "To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only --output json" }, { "name": "codex", "delivery": "skip", "status": "skipped", "error_category": "UNSUPPORTED_SCOPE", - "message": "does not support project-scoped skills" + "message": "does not support project-scoped skills", + "recovery": "To set up Codex CLI in the global scope, run: databricks aitools install --scope=global --agents=codex --skills-only --output json" } ] } diff --git a/acceptance/experimental/aitools/skills/install-output-json-error/output.txt b/acceptance/experimental/aitools/skills/install-output-json-error/output.txt index 84ee93c8897..bf216304f87 100644 --- a/acceptance/experimental/aitools/skills/install-output-json-error/output.txt +++ b/acceptance/experimental/aitools/skills/install-output-json-error/output.txt @@ -6,7 +6,8 @@ "scope": "global", "agents": [], "error": "skill \"nonexistent\" not found", - "error_category": "SKILL_NOT_FOUND" + "error_category": "SKILL_NOT_FOUND", + "recovery": "Run 'databricks aitools list' to see the available skills." } Exit code: 1 diff --git a/cmd/aitools/funnel_test.go b/cmd/aitools/funnel_test.go index 07efa2e7c9e..b4a09f1aab2 100644 --- a/cmd/aitools/funnel_test.go +++ b/cmd/aitools/funnel_test.go @@ -378,7 +378,7 @@ func TestInstallFunnelEmptyPickerSelectionIsCancelled(t *testing.T) { cmd.SetContext(ctx) err := cmd.RunE(cmd, nil) require.ErrorIs(t, err, errNoAgentsSelected) - assert.Equal(t, "at least one agent must be selected", err.Error()) + assert.Equal(t, "at least one agent must be selected\nTo install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", err.Error()) assert.Equal(t, []string{"STARTED", "FLAGS_VALIDATED", "SCOPE_RESOLVED", "FINISHED:CANCELLED:"}, funnelShape(funnelEvents(ctx))) } diff --git a/cmd/aitools/install.go b/cmd/aitools/install.go index bb9ffe5ab8f..6e84d59ed54 100644 --- a/cmd/aitools/install.go +++ b/cmd/aitools/install.go @@ -4,6 +4,7 @@ import ( "context" "errors" "fmt" + "runtime" "strings" "github.com/charmbracelet/huh" @@ -183,7 +184,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), funnel.step(ctx, protos.AitoolsCommandStepFlagsValidated) written, err := installer.DumpSkillsToPath(ctx, src, pathFlag, opts) if err != nil { - return err + return withRecovery(ctx, installInvocation{path: pathFlag, skills: skillsFlag, experimental: includeExperimental}, err) } if written == 0 { // Every skill was filtered out (e.g. all experimental without @@ -226,6 +227,18 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } } + // Recovery steps repeat this run with the choices made so far, so a + // copied command never widens to every agent or the global scope. + // Agents chosen by flag or in the picker are named; without a + // choice the re-run detects the same agents again. + rerun := installInvocation{ + scope: scope, + skills: skillsFlag, + skillsOnly: skillsOnly, + experimental: includeExperimental, + jsonOutput: jsonMode, + } + // Validate --agents with the other flags, before the scope prompt. var targetAgents []*agents.Agent explicit := agentsFlag != "" @@ -235,6 +248,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), return err } funnel.setTargets(targetAgents) + rerun.agents = joinAgentNames(targetAgents) } funnel.step(ctx, protos.AitoolsCommandStepFlagsValidated) @@ -257,8 +271,9 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), if scope == "" { scope, err = resolveScopeWithPrompt(ctx, interactive) if err != nil { - return err + return withRecovery(ctx, rerun, err) } + rerun.scope = scope } opts.Scope = scope funnel.setScope(scope) @@ -267,13 +282,16 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), if !explicit { targetAgents, err = selectAgents(ctx, scope, skillsOnly, interactive) if err != nil { - return err + return withRecovery(ctx, rerun, err) } if len(targetAgents) == 0 { - printNoAgentsMessage(ctx) + printNoAgentsMessage(ctx, rerun) funnel.finishWith(ctx, protos.AitoolsCommandOutcomeNothingToDo, protos.AitoolsErrorCategoryUnspecified) return nil } + if interactive { + rerun.agents = joinAgentNames(targetAgents) + } } plan := buildPlan(targetAgents, scope, skillsOnly, explicit) @@ -302,7 +320,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), }, classifyInstallError(topLevelFailure(runErr)), outcomes) }() - outcomes, runErr = executePlan(ctx, src, plan, opts, jsonMode) + outcomes, runErr = executePlan(ctx, src, plan, opts, rerun, jsonMode) for _, s := range deliverySteps(outcomes) { funnel.step(ctx, s) } @@ -322,7 +340,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } if jsonMode { - if jerr := renderJSON(cmd.OutOrStdout(), buildInstallOutput(opts.Scope, outcomes, runErr)); jerr != nil { + if jerr := renderJSON(cmd.OutOrStdout(), buildInstallOutput(ctx, rerun, opts.Scope, outcomes, runErr)); jerr != nil { // Rendering failed, so the JSON the caller parses is broken. // Report the render error unless the run already failed for // another reason. @@ -341,7 +359,7 @@ Supported agents: ` + strings.Join(agents.SupportedNames(), ", "), } return nil } - return runErr + return withRecovery(ctx, rerun, runErr) }, } @@ -557,6 +575,7 @@ type agentOutcome struct { status outcomeStatus errorCategory protos.AitoolsErrorCategory // Unspecified when status == outcomeInstalled message string // set when skipped or failed + recovery string // next step for the user, when skipped or failed } type outcomeStatus string @@ -589,8 +608,9 @@ 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 (exit 0), -// unless the agent was explicitly named via --agents, which is an error. -func executePlan(ctx context.Context, src installer.ManifestSource, plan []agentPlanItem, opts installer.InstallOptions, quiet bool) ([]agentOutcome, error) { +// unless the agent was explicitly named via --agents, which is an error. 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 for _, it := range plan { @@ -638,8 +658,10 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent } rec, err := installPluginForAgentFn(ctx, it.agent, it.scope, ref) if err != nil { + reason, recovery := pluginFailureText(ctx, rerun, it, err) if !quiet { - cmdio.LogString(ctx, cmdio.Yellow(ctx, fmt.Sprintf("Skipped %s: %v", it.agent.DisplayName, err))) + cmdio.LogString(ctx, cmdio.Yellow(ctx, fmt.Sprintf("Skipped %s: %s", it.agent.DisplayName, reason))) + cmdio.LogString(ctx, " "+recovery) } outcomes = append(outcomes, agentOutcome{ agent: it.agent, @@ -647,9 +669,10 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent status: outcomeFailed, errorCategory: classifyInstallError(err), message: err.Error(), + recovery: recovery, }) if it.explicit { - explicitErrs = append(explicitErrs, err) + explicitErrs = append(explicitErrs, &displayError{msg: it.agent.DisplayName + ": " + reason, err: err}) } continue } @@ -686,8 +709,10 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent } for _, it := range skipItems { + recovery := skipRecovery(rerun, it) if !quiet { cmdio.LogString(ctx, cmdio.Yellow(ctx, "Skipped "+it.agent.DisplayName+": "+it.reason)) + cmdio.LogString(ctx, " "+recovery) } outcomes = append(outcomes, agentOutcome{ agent: it.agent, @@ -695,6 +720,7 @@ func executePlan(ctx context.Context, src installer.ManifestSource, plan []agent status: outcomeSkipped, errorCategory: it.skipErrorCategory, message: it.reason, + recovery: recovery, }) if it.explicit { explicitErrs = append(explicitErrs, fmt.Errorf("%s: %s", it.agent.DisplayName, it.reason)) @@ -730,6 +756,8 @@ type installOutput struct { // also records. Error string `json:"error,omitempty"` ErrorCategory string `json:"error_category,omitempty"` + // Recovery is the next step for the top-level failure, local-only like Error. + Recovery string `json:"recovery,omitempty"` } type agentResultJSON struct { @@ -738,9 +766,12 @@ type agentResultJSON struct { Status string `json:"status"` ErrorCategory string `json:"error_category,omitempty"` Message string `json:"message,omitempty"` + Recovery string `json:"recovery,omitempty"` } -func buildInstallOutput(scope string, outcomes []agentOutcome, runErr error) installOutput { +// buildInstallOutput builds the --output json result; the recovery steps +// repeat rerun. +func buildInstallOutput(ctx context.Context, rerun installInvocation, scope string, outcomes []agentOutcome, runErr error) installOutput { out := installOutput{Scope: scope, Agents: make([]agentResultJSON, 0, len(outcomes))} for _, o := range outcomes { entry := agentResultJSON{ @@ -748,6 +779,7 @@ func buildInstallOutput(scope string, outcomes []agentOutcome, runErr error) ins Delivery: o.delivery.String(), Status: string(o.status), Message: o.message, + Recovery: o.recovery, } // Only non-successful outcomes carry a category, keyed on status to match // agentResultsField in telemetry.go so the JSON and telemetry views of the @@ -765,10 +797,20 @@ func buildInstallOutput(scope string, outcomes []agentOutcome, runErr error) ins if e := topLevelFailure(runErr); e != nil { out.Error = e.Error() out.ErrorCategory = string(classifyInstallError(e)) + out.Recovery = installRecovery(ctx, rerun, e) } return out } +// joinAgentNames is the --agents value that names targetAgents. +func joinAgentNames(targetAgents []*agents.Agent) string { + names := make([]string, len(targetAgents)) + for i, a := range targetAgents { + names[i] = a.Name + } + return strings.Join(names, ",") +} + // resolveAgentNames parses a comma-separated list of agent names and validates // them against the registry. Returns an error for unrecognized names. func resolveAgentNames(_ context.Context, names string) ([]*agents.Agent, error) { @@ -800,10 +842,12 @@ func resolveAgentNames(_ context.Context, names string) ([]*agents.Agent, error) return result, nil } -// printNoAgentsMessage prints the "no agents detected" message. -func printNoAgentsMessage(ctx context.Context) { +// printNoAgentsMessage prints the "no agents detected" message. Its commands +// repeat rerun, so a named agent is set up in the scope and mode this run used. +func printNoAgentsMessage(ctx context.Context, rerun installInvocation) { cmdio.LogString(ctx, cmdio.Yellow(ctx, "No supported coding agents found on PATH.")) cmdio.LogString(ctx, "") cmdio.LogString(ctx, "Supported: "+strings.Join(agents.SupportedNames(), ", ")+".") - cmdio.LogString(ctx, "Install one, then re-run 'databricks aitools install'.") + named, _ := commandText(runtime.GOOS, rerun, nil, "--agents=") + cmdio.LogString(ctx, "Install one, then re-run "+rerunPhrase(runtime.GOOS, rerun)+". To set up an agent that was not detected, name it: "+named) } diff --git a/cmd/aitools/install_test.go b/cmd/aitools/install_test.go index abd9a491537..6ef4bc51a4e 100644 --- a/cmd/aitools/install_test.go +++ b/cmd/aitools/install_test.go @@ -14,6 +14,7 @@ import ( "runtime" "testing" + "github.com/charmbracelet/huh" "github.com/databricks/cli/cmd/root" "github.com/databricks/cli/libs/aitools/agents" "github.com/databricks/cli/libs/aitools/installer" @@ -314,7 +315,7 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { // Non-explicit blocked install is a warning, not an error, but the agent's // failure is still recorded in its outcome. plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, false) - outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, 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, 1) assert.Equal(t, outcomeFailed, outcomes[0].status) @@ -322,7 +323,7 @@ func TestExecutePlanSkipBlockedPluginExit0(t *testing.T) { // Explicit (--agents) blocked install is an error. planExplicit := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, true) - _, err = executePlan(ctx, nil, planExplicit, installer.InstallOptions{Scope: installer.ScopeGlobal}, false) + _, err = executePlan(ctx, nil, planExplicit, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.Error(t, err) } @@ -362,7 +363,7 @@ func TestExecutePlanPluginWithUnresolvedSkillsRelease(t *testing.T) { claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") plan := buildPlan([]*agents.Agent{claude}, installer.ScopeGlobal, false, true) - outcomes, err := executePlan(cmdio.MockDiscard(t.Context()), nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, false) + 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) assert.Equal(t, outcomeInstalled, outcomes[0].status) @@ -399,7 +400,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) - outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, 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 // Claude Code's plugin install. @@ -441,7 +442,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) - outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, false) + outcomes, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, installInvocation{scope: installer.ScopeGlobal}, false) require.ErrorIs(t, err, fetchErr) require.Len(t, *plugins, 1) @@ -477,7 +478,7 @@ func TestExecutePlanSkillsAndStateWriteFailuresAreJoined(t *testing.T) { cursor := &agents.Agent{Name: agents.NameCursor, DisplayName: "Cursor"} ctx := cmdio.MockDiscard(t.Context()) plan := buildPlan([]*agents.Agent{cursor, claude}, installer.ScopeGlobal, false, false) - _, err := executePlan(ctx, nil, plan, installer.InstallOptions{Scope: installer.ScopeGlobal}, 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. require.ErrorIs(t, err, skillsErr) @@ -1194,3 +1195,86 @@ func TestInstallAgentCallerNoteSilent(t *testing.T) { }) } } + +func TestInstallPickerAbortSuggestsFlags(t *testing.T) { + isolateAgents(t) + setupTestAgents(t) + setupScopeMock(t, installer.ScopeGlobal) + origPrompt := promptAgentSelection + t.Cleanup(func() { promptAgentSelection = origPrompt }) + promptAgentSelection = func(context.Context, string, []agentChoice) ([]*agents.Agent, error) { + return nil, huh.ErrUserAborted + } + + ctx, test := cmdio.SetupTest(t.Context(), cmdio.TestOptions{PromptSupported: true}) + defer test.Done() + go drainReader(test.Stdout) + go drainReader(test.Stderr) + cmd := newTestInstallCmd() + cmd.SetContext(ctx) + + err := cmd.RunE(cmd, nil) + require.ErrorIs(t, err, huh.ErrUserAborted) + assert.Equal(t, "user aborted\nTo install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", err.Error()) +} + +func TestInstallPathFailureHasRecoveryForThePathRun(t *testing.T) { + setupTestAgents(t) + t.Setenv("DATABRICKS_SKILLS_REF", "v0.2.6") + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "http://127.0.0.1:1") + // A relative destination keeps the printed command independent of how the + // host spells its temp dir; the space makes it need quoting in every shell. + t.Chdir(t.TempDir()) + const out = "my skills" + + ctx := telemetry.WithNewLogger(cmdio.MockDiscard(t.Context())) + cmd := newTestInstallCmd() + cmd.SetContext(ctx) + cmd.SetArgs([]string{"--path", out}) + err := cmd.Execute() + + require.Error(t, err) + assert.Contains(t, err.Error(), "\nCould not download Databricks skills from 127.0.0.1:1.") + // The POSIX-quoted command contains single quotes, so backticks delimit it. + want := "`databricks aitools install --path='my skills'`" + if runtime.GOOS == "windows" { + want = `'databricks aitools install --path="my skills"'` + } + assert.Contains(t, err.Error(), "then re-run "+want) +} + +func TestInstallFailureAfterPickerNamesTheSelectedAgents(t *testing.T) { + isolateAgents(t) + setupTestAgents(t) + setupScopeMock(t, installer.ScopeGlobal) + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "") + origPicker := promptAgentSelection + t.Cleanup(func() { promptAgentSelection = origPicker }) + // Claude Code and Cursor are detected; the user picks only Cursor. + promptAgentSelection = func(context.Context, string, []agentChoice) ([]*agents.Agent, error) { + return []*agents.Agent{agents.ByName(agents.NameCursor)}, nil + } + origInstall := installSkillsForAgentsFn + t.Cleanup(func() { installSkillsForAgentsFn = origInstall }) + installSkillsForAgentsFn = func(context.Context, installer.ManifestSource, []*agents.Agent, installer.InstallOptions) error { + return &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusBadGateway, Err: errors.New("failed to fetch manifest: HTTP 502")} + } + + ioCtx, test := cmdio.SetupTest(t.Context(), cmdio.TestOptions{PromptSupported: true}) + defer test.Done() + go drainReader(test.Stdout) + go drainReader(test.Stderr) + cmd := newTestInstallCmd() + cmd.SetContext(telemetry.WithNewLogger(ioCtx)) + require.NoError(t, cmd.Flags().Set("skills-only", "true")) + + err := cmd.RunE(cmd, nil) + require.Error(t, err) + assert.Contains(t, err.Error(), "re-run 'databricks aitools install --scope=global --agents=cursor --skills-only'") +} + +func TestNoAgentsMessageKeepsTheRunsScopeAndMode(t *testing.T) { + ctx, stderr := cmdio.NewTestContextWithStderr(t.Context()) + printNoAgentsMessage(ctx, installInvocation{scope: installer.ScopeProject, skillsOnly: true}) + assert.Contains(t, stderr.String(), "Install one, then re-run 'databricks aitools install --scope=project --skills-only'. To set up an agent that was not detected, name it: databricks aitools install --scope=project --skills-only --agents=") +} diff --git a/cmd/aitools/recovery.go b/cmd/aitools/recovery.go new file mode 100644 index 00000000000..f8002d5761f --- /dev/null +++ b/cmd/aitools/recovery.go @@ -0,0 +1,471 @@ +package aitools + +import ( + "context" + "errors" + "fmt" + "io/fs" + "net/http" + "net/url" + "os" + "path/filepath" + "runtime" + "slices" + "strconv" + "strings" + "unicode" + + "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/aitools/installer" + "github.com/databricks/cli/libs/env" + "github.com/databricks/cli/libs/shellquote" + "github.com/databricks/cli/libs/telemetry/protos" + "github.com/databricks/cli/libs/versioncheck" +) + +const ( + skillsReleasesURL = "https://github.com/databricks/databricks-agent-skills/releases" + cliIssuesURL = "https://github.com/databricks/cli/issues" + // debugFlag is added to a re-run command whose output should explain a + // failure the step cannot. + debugFlag = "--debug" +) + +// installInvocation is the subset of install flags a re-run must repeat: this +// run's own choices, so a copied command does the same thing and never widens +// to every agent or the global scope. Values are quoted for the user's shell +// when the command is rendered. +type installInvocation struct { + path, scope, agents, skills string + skillsOnly, experimental, jsonOutput bool +} + +// renderInstallCommand renders inv as a command line for the shell a user on +// goos pastes it into. It reports false when a value cannot be quoted so that +// the shell passes it on unchanged. +func renderInstallCommand(goos string, inv installInvocation) (string, bool) { + args := []string{"databricks aitools install"} + if inv.path != "" { + path := inv.path + if goos == "windows" { + // Windows accepts forward slashes, and so the command pastes the + // same into cmd.exe, PowerShell and Git Bash, which would drop + // the backslashes. filepath.ToSlash follows the host OS, not goos. + path = strings.ReplaceAll(path, `\`, "/") + } + path, ok := quoteArg(goos, path) + if !ok { + return "", false + } + args = append(args, "--path="+path) + } + if inv.scope != "" { + args = append(args, "--scope="+inv.scope) + } + if inv.agents != "" { + // Quoted like --skills: PowerShell reads a bare comma as the array + // operator and would split the list into two arguments. + names, ok := quoteArg(goos, inv.agents) + if !ok { + return "", false + } + args = append(args, "--agents="+names) + } + if inv.skillsOnly { + args = append(args, "--skills-only") + } + if inv.skills != "" { + // Normalized as install parses it, so "a, b" pastes as one value. + skills, ok := quoteArg(goos, strings.Join(splitAndTrim(inv.skills), ",")) + if !ok { + return "", false + } + args = append(args, "--skills="+skills) + } + if inv.experimental { + args = append(args, "--experimental") + } + if inv.jsonOutput { + args = append(args, "--output json") + } + return strings.Join(args, " "), true +} + +// quoteArg quotes a flag value for the shell a user on goos pastes the printed +// command into, only when it needs it, so the common case stays readable: +// cmd.exe or PowerShell on Windows, a POSIX shell elsewhere. It reports false +// for a value no quoting keeps literal there, and for any value with a control +// character: a line break in a pasted command runs what follows it. +func quoteArg(goos, value string) (string, bool) { + if goos == "windows" { + return shellquote.WindowsArg(value) + } + if strings.ContainsFunc(value, unicode.IsControl) { + return "", false + } + return shellquote.BashArg(value), true +} + +// commandText renders inv followed by extra flags, for printing after a colon. +// When a value cannot be printed so that it pastes literally, it returns false +// and a phrase asking for the user's own command with the flags in changed +// (those this command sets differently) and extra. +func commandText(goos string, inv installInvocation, changed []string, extra ...string) (string, bool) { + cmd, ok := renderInstallCommand(goos, inv) + if !ok { + phrase := "your original install command" + if flags := slices.Concat(changed, extra); len(flags) > 0 { + phrase += " with " + strings.Join(flags, " ") + } + return phrase, false + } + return strings.Join(append([]string{cmd}, extra...), " "), true +} + +// inSentence delimits a command printed inside a sentence. Single quotes are +// the convention for commands in CLI messages; a command that contains one (a +// value quoted for a POSIX shell) is delimited with backticks instead, so the +// reader can tell where it ends. A phrase that is not a command stays as is. +func inSentence(text string, isCommand bool) string { + switch { + case !isCommand: + return text + case strings.Contains(text, "'"): + return "`" + text + "`" + default: + return "'" + text + "'" + } +} + +// rerunPhrase names the command that repeats inv plus extra flags, for use +// inside a sentence. +func rerunPhrase(goos string, inv installInvocation, extra ...string) string { + return inSentence(commandText(goos, inv, nil, extra...)) +} + +// recoveryError appends a recovery step to an install failure. It unwraps to the +// original error so telemetry classification is unchanged. +type recoveryError struct { + err error + recovery string +} + +// Error appends the recovery step without its final period: an error string +// must not end with punctuation. +func (e *recoveryError) Error() string { + return e.err.Error() + "\n" + strings.TrimSuffix(e.recovery, ".") +} +func (e *recoveryError) Unwrap() error { return e.err } + +// displayError replaces the message of an error that is already explained by +// lines printed above it, keeping the cause for classification. +type displayError struct { + msg string + err error +} + +func (e *displayError) Error() string { return e.msg } +func (e *displayError) Unwrap() error { return e.err } + +// withRecovery attaches the recovery step for err. The install command returns +// its run error through it, which is nil when the run succeeded. +func withRecovery(ctx context.Context, inv installInvocation, err error) error { + if err == nil { + return nil + } + step := installRecovery(ctx, inv, err) + if step == "" { + return err + } + return &recoveryError{err: err, recovery: step} +} + +// installRecovery returns the next step a user can take after a failed install. +// It is keyed on the category classifyInstallError reports, so the advice and +// the telemetry category cannot disagree. It returns "" when the error already +// says what to do. +func installRecovery(ctx context.Context, inv installInvocation, err error) string { + if _, ok := errors.AsType[*agentErrors](err); ok { + // Each agent's failure was printed with its own step. + return "" + } + // An empty picker selection has no category of its own: the funnel + // reports it as CANCELLED. + if errors.Is(err, errNoAgentsSelected) { + return promptRecovery(inv) + } + rerun := rerunPhrase(runtime.GOOS, inv) + // classifyInstallError reports RATE_LIMITED and SKILLS_FETCH_FAILED only for + // a FetchError, and STATE_INVALID only for a StateError. + ferr, _ := errors.AsType[*installer.FetchError](err) + switch classifyInstallError(err) { + case protos.AitoolsErrorCategoryCommandInterrupted: + // The user stopped the command; nothing failed that needs a fix. + return "" + case protos.AitoolsErrorCategoryUserAborted, protos.AitoolsErrorCategoryPromptFailed: + return promptRecovery(inv) + case protos.AitoolsErrorCategoryNetwork, protos.AitoolsErrorCategoryTimeout: + // A fetch that got no response; other network errors get the generic step. + if ferr == nil { + return genericRecovery(inv) + } + if ferr.Stage == installer.FetchStageRelease { + return releaseLookupRecovery(ctx, rerun) + } + return unreachableRecovery(ctx, rerun) + case protos.AitoolsErrorCategoryReleaseLookupFailed: + return releaseLookupRecovery(ctx, rerun) + case protos.AitoolsErrorCategoryRateLimited: + if ferr.Stage == installer.FetchStageRelease { + return releaseHost(ctx) + " rate-limited the lookup of the latest Databricks skills release. " + releaseLookupStep(rerun) + } + return skillsHost(ctx) + " rate-limited the download (HTTP " + strconv.Itoa(ferr.StatusCode) + "). Wait a few minutes and re-run " + rerun + "." + case protos.AitoolsErrorCategoryManifestNotFound: + if env.Get(ctx, "DATABRICKS_SKILLS_REF") != "" { + return "No skills release exists at the version DATABRICKS_SKILLS_REF names. Unset it, or set it to a release tag from " + skillsReleasesURL + ", then re-run " + rerun + "." + } + return "The skills release this CLI selected is missing. Set DATABRICKS_SKILLS_REF to a release tag from " + skillsReleasesURL + " and re-run " + rerun + ", and report it at " + cliIssuesURL + "." + case protos.AitoolsErrorCategoryManifestInvalid: + host := skillsHost(ctx) + return host + " answered with something that is not a skills manifest (a proxy or captive portal page, or a broken mirror). Check what this machine gets from " + host + ", then re-run " + rerun + "." + case protos.AitoolsErrorCategorySkillsFetchFailed: + return downloadRecovery(ctx, inv, ferr) + case protos.AitoolsErrorCategoryStateInvalid: + serr, _ := errors.AsType[*installer.StateError](err) + return stateRecovery(inv, serr) + case protos.AitoolsErrorCategorySkillNotFound: + return "Run 'databricks aitools list' to see the available skills." + case protos.AitoolsErrorCategoryVersionIncompatible: + if _, cmd := versioncheck.DetectInstallMethod(ctx); cmd != "" { + return "Upgrade the Databricks CLI with '" + cmd + "', then re-run the install." + } + return "Upgrade the Databricks CLI (see " + root.InstallDocsURL + "), then re-run the install." + case protos.AitoolsErrorCategoryExperimentalSkill: + // The message already names --experimental. + return "" + case protos.AitoolsErrorCategoryPermissionDenied: + return permissionRecovery(inv, err) + case protos.AitoolsErrorCategoryFilesystem: + return filesystemRecovery(inv, err) + default: + // A refusal is UNCATEGORIZED and its message names the fix. Checked + // here, not before the switch, so a failure joined to a refusal still + // gets the step for its own category. + if _, ok := errors.AsType[*installer.RefusedError](err); ok { + return "" + } + return genericRecovery(inv) + } +} + +// genericRecovery is the step for a failure no other step explains: re-run +// with debug output, and report it if it persists. +func genericRecovery(inv installInvocation) string { + return "Re-run " + rerunPhrase(runtime.GOOS, inv, debugFlag) + " to see details. If it keeps failing, report it at " + cliIssuesURL + "." +} + +// unreachableRecovery is the step for a skills download that got no response, +// or whose response broke off. +func unreachableRecovery(ctx context.Context, rerun string) string { + return "Could not download Databricks skills from " + skillsHost(ctx) + ". Check that this machine can reach it (set HTTPS_PROXY if you use a proxy), then re-run " + rerun + "." +} + +// promptRecovery is the step for a prompt that was aborted or could not be +// shown: name every choice by flag, so the re-run prompts for nothing. +func promptRecovery(inv installInvocation) string { + if inv.scope == "" { + inv.scope = installer.ScopeGlobal + } + var extra []string + if inv.agents == "" { + extra = append(extra, "--agents=") + } + cmd, _ := commandText(runtime.GOOS, inv, []string{"--scope=" + inv.scope}, extra...) + return "To install without prompts, name the scope and agents, for example: " + cmd +} + +// releaseLookupRecovery is the step for a lookup of the latest skills release +// that failed for any reason but a rate limit. +func releaseLookupRecovery(ctx context.Context, rerun string) string { + return "Could not look up the latest Databricks skills release on " + releaseHost(ctx) + ". " + releaseLookupStep(rerun) +} + +// releaseLookupStep is what to do after a failed lookup of the latest skills +// release: wait and retry, or pin a release so no lookup is needed. +func releaseLookupStep(rerun string) string { + return "Wait a few minutes and re-run " + rerun + ", or skip the lookup by setting DATABRICKS_SKILLS_REF to a release tag from " + skillsReleasesURL + "." +} + +// releaseHost is the host the latest skills release is looked up on. +func releaseHost(ctx context.Context) string { + return hostOf(versioncheck.GitHubAPIURL(ctx)) +} + +// skillsHost is the host the skills manifest and files are downloaded from. +func skillsHost(ctx context.Context) string { + return hostOf(installer.GetSkillsBaseURL(ctx)) +} + +// hostOf returns the host of rawURL. An environment override without a scheme +// has no host to name, so it is returned as it was set: that is what the CLI +// tried to fetch. +func hostOf(rawURL string) string { + if u, err := url.Parse(rawURL); err == nil && u.Host != "" { + return u.Host + } + return rawURL +} + +// downloadRecovery is the step for a manifest or skill file download that got +// a response. A status below 400 means the body could not be read (a dropped +// connection), which is a network failure too. +func downloadRecovery(ctx context.Context, inv installInvocation, ferr *installer.FetchError) string { + host := skillsHost(ctx) + rerun := rerunPhrase(runtime.GOOS, inv) + status := strconv.Itoa(ferr.StatusCode) + switch { + case ferr.StatusCode >= 500: + return host + " returned HTTP " + status + ", a server-side error. Wait a few minutes and re-run " + rerun + "." + case ferr.StatusCode == http.StatusForbidden || ferr.StatusCode == http.StatusProxyAuthRequired: + return host + " refused the download (HTTP " + status + "). A proxy or access policy may block it; ask your network admin to allow " + host + ", then re-run " + rerun + "." + case ferr.StatusCode >= 400: + return host + " returned HTTP " + status + ". Re-run " + rerunPhrase(runtime.GOOS, inv, debugFlag) + " to see details, and report it at " + cliIssuesURL + "." + default: + return unreachableRecovery(ctx, rerun) + } +} + +// stateRecovery is the step for a state file that cannot be parsed. Without +// state, an install of named skills in the global scope is refused while other +// skills are on disk (they would stay untracked), so the global re-run installs +// all skills; a project-scope install of named skills is not refused, so it +// keeps --skills, and the step adds that the project's other skills need a +// re-run too, or the new state file leaves them untracked. The state file +// also records the plugins and skills of other +// agents in the scope, which a re-run limited to some agents, or to skill +// files, does not record again. +func stateRecovery(inv installInvocation, serr *installer.StateError) string { + step := fmt.Sprintf("Move the install state file %s aside (for example, rename it to %s.bak), then re-run ", filepath.ToSlash(serr.Path), filepath.Base(serr.Path)) + named := inv.skills != "" && inv.scope == installer.ScopeGlobal + if named { + inv.skills = "" + } + step += rerunPhrase(runtime.GOOS, inv) + if named { + step += " to reinstall all skills (without the state file, an install of named skills in the global scope is refused)" + } + step += "." + if inv.skills != "" { + all := inv + all.skills = "" + step += " The new state file records only the named skills, so the project's other skills stay untracked by update and uninstall; reinstall them too with " + rerunPhrase(runtime.GOOS, all) + "." + } + if inv.agents != "" || inv.skillsOnly { + step += " The state file also tracked the other agents set up in this scope; re-run their install too, for example " + rerunPhrase(runtime.GOOS, installInvocation{scope: inv.scope}) + "." + } + return step +} + +// failedPath returns the path an OS error names, with forward slashes; a +// rename names its destination. It returns "" when the error names no path. +func failedPath(err error) string { + if perr, ok := errors.AsType[*fs.PathError](err); ok { + return filepath.ToSlash(perr.Path) + } + if lerr, ok := errors.AsType[*os.LinkError](err); ok { + return filepath.ToSlash(lerr.New) + } + return "" +} + +// permissionRecovery is the step for a file the install may not write. +func permissionRecovery(inv installInvocation, err error) string { + rerun := rerunPhrase(runtime.GOOS, inv) + path := failedPath(err) + if path == "" { + return "Check that you own the directories the install writes to and can write to them (an earlier run with sudo can leave them owned by root), then re-run " + rerun + "." + } + return fmt.Sprintf("Check that you own %s and can write to it (an earlier run with sudo can leave it owned by root), then re-run %s.", path, rerun) +} + +// filesystemRecovery is the step for any other failure to write the install's +// files, such as a full disk or a read-only filesystem: neither is a CLI bug. +func filesystemRecovery(inv installInvocation, err error) string { + rerun := rerunPhrase(runtime.GOOS, inv) + path := failedPath(err) + if path == "" { + return "Check that the directories the install writes to are writable and that the disk has free space, then re-run " + rerun + "." + } + return fmt.Sprintf("Check that %s is on a writable filesystem with free space, then re-run %s.", path, rerun) +} + +// agentCommandText renders the command that repeats this run for one agent, +// followed by extra flags. The scope is always spelled out: without it a +// non-interactive run defaults to global, which is not what a project-scoped +// run asked for. +func agentCommandText(inv installInvocation, it agentPlanItem, extra ...string) (string, bool) { + changed := []string{"--scope=" + inv.scope, "--agents=" + it.agent.Name} + inv.agents = it.agent.Name + return commandText(runtime.GOOS, inv, changed, extra...) +} + +// installCommand is agentCommandText for printing after a colon. +func installCommand(inv installInvocation, it agentPlanItem, extra ...string) string { + cmd, _ := agentCommandText(inv, it, extra...) + return cmd +} + +// agentRerun is agentCommandText delimited for use inside a sentence. +func agentRerun(inv installInvocation, it agentPlanItem, extra ...string) string { + return inSentence(agentCommandText(inv, it, extra...)) +} + +// skillsOnlyCommand is the raw-skills install for one agent, the escape hatch +// when its plugin cannot be installed. +func skillsOnlyCommand(inv installInvocation, it agentPlanItem) string { + inv.skillsOnly = true + return installCommand(inv, it) +} + +// pluginFailureText returns the one-line reason and the recovery step for a +// plugin agent that could not be set up. +func pluginFailureText(ctx context.Context, inv installInvocation, it agentPlanItem, err error) (reason, recovery string) { + a := it.agent + blocked, ok := errors.AsType[*installer.BlockedError](err) + if !ok { + return err.Error(), "Re-run " + agentRerun(inv, it, debugFlag) + " to see details, or install skill files instead: " + skillsOnlyCommand(inv, it) + } + switch { + case blocked.TimedOut: + return fmt.Sprintf("'%s plugin' %s", a.Binary, blocked.Detail), + "Re-run " + agentRerun(inv, it) + " (an agent CLI's first start can be slow), or install skill files instead: " + skillsOnlyCommand(inv, it) + case blocked.Reason == installer.ReasonCLINotOnPath: + if a.HasBinary(ctx) { + // The CLI is on PATH but has no working plugin command, e.g. a + // version from before plugins. + 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), + 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 + // exit code; a plain re-run of the help may print only the help. + return fmt.Sprintf("'%s plugin --help' %s", a.Binary, blocked.Detail), + fmt.Sprintf("Once it exits with 0, re-run %s. Or install skill files instead: %s", agentRerun(inv, it), skillsOnlyCommand(inv, it)) + case blocked.Reason == installer.ReasonInstallFailed: + manual := installer.ManualPluginInstallCommands(a, it.scope) + return fmt.Sprintf("'%s plugin' failed: %s", a.Binary, blocked.Detail), + "Run '" + strings.Join(manual, "', then '") + "' to see the full error. Once they succeed, re-run " + agentRerun(inv, it) + " so the CLI records the plugin. Or install skill files instead: " + skillsOnlyCommand(inv, it) + default: + return err.Error(), "Install skill files instead: " + skillsOnlyCommand(inv, it) + } +} + +// skipRecovery returns the recovery step for an agent the plan skipped. Every +// skip is an agent without support for the project scope, so the step is the +// command that sets up just this agent in the global scope. +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) +} diff --git a/cmd/aitools/recovery_test.go b/cmd/aitools/recovery_test.go new file mode 100644 index 00000000000..2bdd5aa933e --- /dev/null +++ b/cmd/aitools/recovery_test.go @@ -0,0 +1,470 @@ +package aitools + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "net" + "net/http" + "net/url" + "os" + "path/filepath" + "syscall" + "testing" + + "github.com/charmbracelet/huh" + "github.com/databricks/cli/libs/aitools/agents" + "github.com/databricks/cli/libs/aitools/installer" + "github.com/databricks/cli/libs/clicompat" + "github.com/databricks/cli/libs/cmdio" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// dnsError is what a fetch that got no response wraps. +var dnsError = &net.OpError{Op: "dial", Net: "tcp", Err: &net.DNSError{Err: "no such host", Name: "raw.githubusercontent.com", IsNotFound: true}} + +func TestInstallRecovery(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "") + t.Setenv("DATABRICKS_SKILLS_REF", "") + tests := []struct { + name string + err error + want string + }{ + { + name: "release lookup rate limited", + err: fmt.Errorf("resolve latest skills release: %w", &installer.FetchError{Stage: installer.FetchStageRelease, StatusCode: http.StatusForbidden, RateLimited: true, Err: errors.New("HTTP 403 fetching latest skills release")}), + want: "api.github.com rate-limited the lookup of the latest Databricks skills release. Wait a few minutes and re-run 'databricks aitools install', or skip the lookup by setting DATABRICKS_SKILLS_REF to a release tag from https://github.com/databricks/databricks-agent-skills/releases.", + }, + { + name: "release lookup denied without rate-limit evidence", + err: &installer.FetchError{Stage: installer.FetchStageRelease, StatusCode: http.StatusForbidden, Err: errors.New("HTTP 403 fetching latest skills release")}, + want: "Could not look up the latest Databricks skills release on api.github.com. Wait a few minutes and re-run 'databricks aitools install', or skip the lookup by setting DATABRICKS_SKILLS_REF to a release tag from https://github.com/databricks/databricks-agent-skills/releases.", + }, + { + name: "release lookup network error", + err: &installer.FetchError{Stage: installer.FetchStageRelease, Err: dnsError}, + want: "Could not look up the latest Databricks skills release on api.github.com. Wait a few minutes and re-run 'databricks aitools install', or skip the lookup by setting DATABRICKS_SKILLS_REF to a release tag from https://github.com/databricks/databricks-agent-skills/releases.", + }, + { + name: "manifest fetch server error", + err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusServiceUnavailable, Err: errors.New("failed to fetch manifest: HTTP 503")}, + want: "raw.githubusercontent.com returned HTTP 503, a server-side error. Wait a few minutes and re-run 'databricks aitools install'.", + }, + { + name: "manifest fetch refused without rate-limit evidence", + err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusForbidden, Err: errors.New("failed to fetch manifest: HTTP 403")}, + want: "raw.githubusercontent.com refused the download (HTTP 403). A proxy or access policy may block it; ask your network admin to allow raw.githubusercontent.com, then re-run 'databricks aitools install'.", + }, + { + name: "manifest fetch rate limited", + err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusTooManyRequests, RateLimited: true, Err: errors.New("failed to fetch manifest: HTTP 429")}, + want: "raw.githubusercontent.com rate-limited the download (HTTP 429). Wait a few minutes and re-run 'databricks aitools install'.", + }, + { + name: "manifest is not JSON", + err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusOK, Err: fmt.Errorf("failed to parse manifest: %w", &json.SyntaxError{})}, + want: "raw.githubusercontent.com answered with something that is not a skills manifest (a proxy or captive portal page, or a broken mirror). Check what this machine gets from raw.githubusercontent.com, then re-run 'databricks aitools install'.", + }, + { + name: "manifest fetch without a response", + err: &installer.FetchError{Stage: installer.FetchStageManifest, Err: fmt.Errorf("failed to fetch manifest: %w", dnsError)}, + want: "Could not download Databricks skills from raw.githubusercontent.com. Check that this machine can reach it (set HTTPS_PROXY if you use a proxy), then re-run 'databricks aitools install'.", + }, + { + name: "body read failure after HTTP 200 is a network failure", + err: &installer.FetchError{Stage: installer.FetchStageFile, StatusCode: http.StatusOK, Err: fmt.Errorf("failed to read response: %w", io.ErrUnexpectedEOF)}, + want: "Could not download Databricks skills from raw.githubusercontent.com. Check that this machine can reach it (set HTTPS_PROXY if you use a proxy), then re-run 'databricks aitools install'.", + }, + { + name: "manifest missing at the cli-compat pin", + err: &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusNotFound, Err: fmt.Errorf("skills manifest at databricks-agent-skills@v9: %w", clicompat.ErrNotFound)}, + want: "The skills release this CLI selected is missing. Set DATABRICKS_SKILLS_REF to a release tag from https://github.com/databricks/databricks-agent-skills/releases and re-run 'databricks aitools install', and report it at https://github.com/databricks/cli/issues.", + }, + { + name: "skill file fetch", + err: fmt.Errorf("failed to fetch skills/x/SKILL.md at v1: %w", &installer.FetchError{Stage: installer.FetchStageFile, StatusCode: http.StatusNotFound, Err: errors.New("HTTP 404")}), + want: "raw.githubusercontent.com returned HTTP 404. Re-run 'databricks aitools install --debug' to see details, and report it at https://github.com/databricks/cli/issues.", + }, + { + name: "corrupt state file", + err: fmt.Errorf("failed to load install state: %w", &installer.StateError{Path: filepath.FromSlash("/home/u/.databricks/aitools/skills/.state.json"), Err: errors.New("failed to parse state file")}), + want: "Move the install state file /home/u/.databricks/aitools/skills/.state.json aside (for example, rename it to .state.json.bak), then re-run 'databricks aitools install'.", + }, + { + name: "unreadable state file keeps the permission step", + err: fmt.Errorf("failed to load install state: %w", fmt.Errorf("failed to read state file: %w", &fs.PathError{Op: "open", Path: filepath.FromSlash("/home/u/.databricks/aitools/skills/.state.json"), Err: fs.ErrPermission})), + want: "Check that you own /home/u/.databricks/aitools/skills/.state.json and can write to it (an earlier run with sudo can leave it owned by root), then re-run 'databricks aitools install'.", + }, + { + name: "permission denied", + err: fmt.Errorf("failed to create skills directory: %w", &fs.PathError{Op: "mkdir", Path: filepath.FromSlash("/home/u/.databricks/aitools"), Err: fs.ErrPermission}), + want: "Check that you own /home/u/.databricks/aitools and can write to it (an earlier run with sudo can leave it owned by root), then re-run 'databricks aitools install'.", + }, + { + name: "permission denied on a rename names its destination", + err: fmt.Errorf("failed to move skill into place: %w", &os.LinkError{Op: "rename", Old: filepath.FromSlash("/home/u/.tmp/x"), New: filepath.FromSlash("/home/u/.databricks/aitools/skills/x"), Err: fs.ErrPermission}), + want: "Check that you own /home/u/.databricks/aitools/skills/x and can write to it (an earlier run with sudo can leave it owned by root), then re-run 'databricks aitools install'.", + }, + { + name: "permission denied without a path", + err: os.NewSyscallError("open", syscall.EACCES), + want: "Check that you own the directories the install writes to and can write to them (an earlier run with sudo can leave them owned by root), then re-run 'databricks aitools install'.", + }, + { + name: "prompt aborted", + err: promptError(huh.ErrUserAborted), + want: "To install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", + }, + { + name: "nothing selected in picker", + err: errNoAgentsSelected, + want: "To install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", + }, + { + name: "terminal that cannot be opened is a prompt failure, not a permission problem", + err: promptError(&fs.PathError{Op: "open", Path: "/dev/tty", Err: fs.ErrPermission}), + want: "To install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=", + }, + { + name: "skill not found", + err: &installer.SkillError{Skill: "x", Reason: installer.ReasonSkillNotFound, Detail: "not found"}, + want: "Run 'databricks aitools list' to see the available skills.", + }, + { + name: "experimental skill already names the flag", + err: &installer.SkillError{Skill: "x", Reason: installer.ReasonExperimentalSkill, Detail: "is experimental; use --experimental to install"}, + want: "", + }, + { + name: "interrupted command gets no step", + err: &installer.FetchError{Stage: installer.FetchStageManifest, Err: fmt.Errorf("failed to fetch manifest: %w", context.Canceled)}, + want: "", + }, + { + name: "refused downgrade already says what to do", + err: &installer.RefusedError{Err: errors.New("refusing to downgrade skills from 0.3.0 to 0.2.0; ... set DATABRICKS_SKILLS_REF=v0.2.0 to select this version explicitly")}, + want: "", + }, + { + name: "legacy install guard already says what to do", + err: &installer.RefusedError{Err: errors.New("legacy install detected without state tracking; run 'databricks aitools install' (without a skill name) first to rebuild state")}, + want: "", + }, + { + name: "per-agent failures carry their own steps", + err: &agentErrors{err: errors.New("Cursor: does not support project-scoped skills")}, + want: "", + }, + { + name: "unknown error", + err: errors.New("boom"), + want: "Re-run 'databricks aitools install --debug' to see details. If it keeps failing, report it at https://github.com/databricks/cli/issues.", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, tc.want, installRecovery(t.Context(), installInvocation{}, tc.err)) + }) + } +} + +func TestWithRecoveryKeepsCauseAndAppendsStep(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "") + cause := &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusBadGateway, Err: errors.New("failed to fetch manifest: HTTP 502")} + err := withRecovery(t.Context(), installInvocation{}, cause) + + assert.Equal(t, "failed to fetch manifest: HTTP 502\nraw.githubusercontent.com returned HTTP 502, a server-side error. Wait a few minutes and re-run 'databricks aitools install'", err.Error()) + _, ok := errors.AsType[*installer.FetchError](err) + assert.True(t, ok, "classification must still see the cause") + assert.NoError(t, withRecovery(t.Context(), installInvocation{}, nil)) +} + +func TestFetchRecoveryNamesOverriddenHost(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "https://mirror.example.test/skills") + got := installRecovery(t.Context(), installInvocation{}, &installer.FetchError{Stage: installer.FetchStageManifest, Err: dnsError}) + assert.Contains(t, got, "Could not download Databricks skills from mirror.example.test.") +} + +func TestReleaseLookupRecoveryNamesOverriddenHost(t *testing.T) { + t.Setenv("DATABRICKS_CLI_GITHUB_API_URL", "https://ghe.example.test/api/v3") + got := installRecovery(t.Context(), installInvocation{}, &installer.FetchError{Stage: installer.FetchStageRelease, Err: dnsError}) + assert.Contains(t, got, "Could not look up the latest Databricks skills release on ghe.example.test.") +} + +func TestPluginFailureText(t *testing.T) { + t.Setenv("PATH", t.TempDir()) + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + claude.Plugin.Source = "anthropics/claude-plugins-official" + claude.Plugin.Marketplace = "claude-plugins-official" + item := agentPlanItem{agent: claude, delivery: deliveryPlugin, scope: agentScopeUser} + inv := installInvocation{scope: installer.ScopeGlobal, agents: agents.NameClaudeCode} + const rerun = "databricks aitools install --scope=global --agents=claude-code" + + tests := []struct { + name string + err error + wantReason string + wantRecovery string + }{ + { + name: "cli not on path", + err: &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: `could not resolve claude on PATH: exec: "claude": executable file not found in $PATH`}, + wantReason: "'claude' is not on PATH", + wantRecovery: "Install or update the Claude Code CLI so 'claude' is on PATH, then re-run '" + rerun + "'. Or install skill files instead: " + rerun + " --skills-only", + }, + { + name: "install failed", + err: &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonInstallFailed, Detail: "fatal: unable to access github.com"}, + wantReason: "'claude plugin' failed: fatal: unable to access github.com", + wantRecovery: "Run 'claude plugin marketplace add anthropics/claude-plugins-official', then 'claude plugin marketplace update claude-plugins-official', then 'claude plugin install databricks@claude-plugins-official --scope user' to see the full error. Once they succeed, re-run '" + rerun + "' so the CLI records the plugin. Or install skill files instead: " + rerun + " --skills-only", + }, + { + name: "timed out", + err: &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "timed out after 20s", TimedOut: true}, + wantReason: "'claude plugin' timed out after 20s", + wantRecovery: "Re-run '" + rerun + "' (an agent CLI's first start can be slow), or install skill files instead: " + rerun + " --skills-only", + }, + { + name: "windows shim exited with an error", + err: &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonShimExitedWithError, Detail: "printed its plugin help but exited with an error (exit status 1): node: bad option; to see the error and exit code, run ..."}, + wantReason: "'claude plugin --help' printed its plugin help but exited with an error (exit status 1): node: bad option; to see the error and exit code, run ...", + wantRecovery: "Once it exits with 0, re-run '" + rerun + "'. Or install skill files instead: " + rerun + " --skills-only", + }, + { + name: "untyped error", + err: errors.New("boom"), + wantReason: "boom", + wantRecovery: "Re-run '" + rerun + " --debug' to see details, or install skill files instead: " + rerun + " --skills-only", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + reason, recovery := pluginFailureText(t.Context(), inv, item, tc.err) + assert.Equal(t, tc.wantReason, reason) + assert.Equal(t, tc.wantRecovery, recovery) + }) + } +} + +func TestPluginFailureTextKeepsTheRunsFlags(t *testing.T) { + // The fallback after a plugin failure must not drop --experimental or + // --output json, and must name only the failed agent. + t.Setenv("PATH", t.TempDir()) + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + item := agentPlanItem{agent: claude, delivery: deliveryPlugin, scope: agentScopeUser} + inv := installInvocation{scope: installer.ScopeGlobal, agents: "claude-code,codex", experimental: true, jsonOutput: true} + + _, recovery := pluginFailureText(t.Context(), inv, item, &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "not found"}) + assert.Equal(t, "Install or update the Claude Code CLI so 'claude' is on PATH, then re-run 'databricks aitools install --scope=global --agents=claude-code --experimental --output json'. Or install skill files instead: databricks aitools install --scope=global --agents=claude-code --skills-only --experimental --output json", recovery) +} + +func TestSkipRecoveryNamesOnlyTheAgentInTheGlobalScope(t *testing.T) { + cursor := agents.ByName(agents.NameCursor) + inv := installInvocation{scope: installer.ScopeProject, agents: "claude-code,cursor", skillsOnly: true, experimental: true} + assert.Equal(t, "To set up Cursor in the global scope, run: databricks aitools install --scope=global --agents=cursor --skills-only --experimental", skipRecovery(inv, agentPlanItem{agent: cursor, delivery: deliverySkip})) + + inv = installInvocation{scope: installer.ScopeProject, agents: "codex", jsonOutput: true} + codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") + assert.Equal(t, "To set up Codex CLI in the global scope, run: databricks aitools install --scope=global --agents=codex --output json", skipRecovery(inv, agentPlanItem{agent: codex, delivery: deliverySkip})) +} + +func TestBuildInstallOutputIncludesRecovery(t *testing.T) { + codex := testPluginAgent(agents.NameCodex, "Codex CLI", "codex") + ctx := cmdio.MockDiscard(t.Context()) + inv := installInvocation{scope: installer.ScopeGlobal, agents: agents.NameCodex, jsonOutput: true} + out := buildInstallOutput(ctx, inv, installer.ScopeGlobal, []agentOutcome{{ + agent: codex, + delivery: deliveryPlugin, + status: outcomeFailed, + message: "codex: cli-not-on-path", + recovery: "Install the Codex CLI", + }}, &installer.StateError{Path: filepath.FromSlash("/s/.state.json"), Err: errors.New("failed to parse state file")}) + + require.Len(t, out.Agents, 1) + assert.Equal(t, "Install the Codex CLI", out.Agents[0].Recovery) + assert.Equal(t, "failed to parse state file", out.Error, "the message stays the raw cause") + assert.Contains(t, out.Recovery, "/s/.state.json") + assert.Contains(t, out.Recovery, "re-run 'databricks aitools install --scope=global --agents=codex --output json'", "a JSON run is told to re-run in JSON") +} + +func TestPluginFailureTextCLIWithoutPluginCommand(t *testing.T) { + fakeBinsOnPath(t, "claude") + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + err := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "unknown command 'plugin'"} + + reason, recovery := pluginFailureText(t.Context(), installInvocation{scope: installer.ScopeGlobal}, agentPlanItem{agent: claude}, err) + assert.Equal(t, "'claude plugin' is not available (unknown command 'plugin')", reason) + // The CLI is already on PATH, so the step asks for a version with plugins. + assert.Equal(t, "Update the Claude Code CLI to a version with the 'claude plugin' command, 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", recovery) +} + +func TestRecoveryCommandsKeepTheProjectScope(t *testing.T) { + // A project-scoped run must not be told to run a command that defaults to + // the global scope or to every detected agent. + t.Setenv("PATH", t.TempDir()) + claude := testPluginAgent(agents.NameClaudeCode, "Claude Code", "claude") + item := agentPlanItem{agent: claude, delivery: deliveryPlugin, scope: agentScopeProject} + inv := installInvocation{scope: installer.ScopeProject} + const want = "databricks aitools install --scope=project --agents=claude-code" + + 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) + + timedOut := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonCLINotOnPath, Detail: "timed out after 20s", TimedOut: true} + _, recovery = pluginFailureText(t.Context(), inv, item, timedOut) + assert.Equal(t, "Re-run '"+want+"' (an agent CLI's first start can be slow), or install skill files instead: "+want+" --skills-only", recovery) + + failed := &installer.BlockedError{Agent: claude.Name, Reason: installer.ReasonInstallFailed, Detail: "boom"} + _, recovery = pluginFailureText(t.Context(), inv, item, failed) + assert.Contains(t, recovery, "'claude plugin install databricks@databricks-agent-skills --scope project'") + assert.Contains(t, recovery, want+" --skills-only") +} + +func TestRecoveryRepeatsTheRunsFlags(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "") + inv := installInvocation{scope: installer.ScopeProject, agents: "cursor", skillsOnly: true, skills: "a", experimental: true} + got := installRecovery(t.Context(), inv, &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusBadGateway, Err: errors.New("HTTP 502")}) + assert.Contains(t, got, "re-run 'databricks aitools install --scope=project --agents=cursor --skills-only --skills=a --experimental'.") +} + +func TestPromptRecoveryBuildsOnTheChoicesMade(t *testing.T) { + // The scope was chosen at the prompt; the agent picker failed. + inv := installInvocation{scope: installer.ScopeProject, skillsOnly: true} + assert.Equal(t, "To install without prompts, name the scope and agents, for example: databricks aitools install --scope=project --skills-only --agents=", installRecovery(t.Context(), inv, errNoAgentsSelected)) + + // The scope prompt failed; the agents were named by flag. + inv = installInvocation{agents: agents.NameCursor} + assert.Equal(t, "To install without prompts, name the scope and agents, for example: databricks aitools install --scope=global --agents=cursor", installRecovery(t.Context(), inv, huh.ErrUserAborted)) +} + +func TestRenderInstallCommandQuotesUserInput(t *testing.T) { + tests := []struct { + goos string + inv installInvocation + want string + }{ + {"linux", installInvocation{path: "/tmp/out"}, "databricks aitools install --path=/tmp/out"}, + {"darwin", installInvocation{path: "/tmp/my dir"}, "databricks aitools install --path='/tmp/my dir'"}, + {"linux", installInvocation{path: "/tmp/it's"}, `databricks aitools install --path='/tmp/it'\''s'`}, + // Single quotes keep every POSIX shell character literal. + {"linux", installInvocation{path: "/tmp/$(id)"}, "databricks aitools install --path='/tmp/$(id)'"}, + {"linux", installInvocation{path: "/tmp/a`id`!%\"b"}, "databricks aitools install --path='/tmp/a`id`!%\"b'"}, + // A Windows path is printed with forward slashes: Windows accepts them, + // and Git Bash would drop backslashes. A trailing one needs no doubling. + {"windows", installInvocation{path: `C:\Users\me\out`}, `databricks aitools install --path=C:/Users/me/out`}, + {"windows", installInvocation{path: `C:\Users\me\my out`}, `databricks aitools install --path="C:/Users/me/my out"`}, + {"windows", installInvocation{path: `C:\Users\me\my out\`}, `databricks aitools install --path="C:/Users/me/my out/"`}, + + // A skill name with a space stays one argument; normalized as install + // parses the list, so "a, b" is one value too. + {"linux", installInvocation{skillsOnly: true, skills: "databricks-jobs"}, "databricks aitools install --skills-only --skills=databricks-jobs"}, + {"linux", installInvocation{skillsOnly: true, skills: "data science, b"}, "databricks aitools install --skills-only --skills='data science,b'"}, + {"linux", installInvocation{skillsOnly: true, skills: "$(id)"}, "databricks aitools install --skills-only --skills='$(id)'"}, + {"windows", installInvocation{skillsOnly: true, skills: "data science, b"}, `databricks aitools install --skills-only --skills="data science,b"`}, + + // A list of agents is one argument too: PowerShell splits at a bare comma. + {"windows", installInvocation{scope: installer.ScopeGlobal, agents: "claude-code,cursor", skillsOnly: true, skills: "a,b"}, `databricks aitools install --scope=global --agents="claude-code,cursor" --skills-only --skills="a,b"`}, + {"linux", installInvocation{scope: installer.ScopeGlobal, agents: "claude-code,cursor"}, "databricks aitools install --scope=global --agents='claude-code,cursor'"}, + {"windows", installInvocation{scope: installer.ScopeGlobal, agents: "cursor"}, "databricks aitools install --scope=global --agents=cursor"}, + + {"linux", installInvocation{scope: installer.ScopeGlobal, agents: "cursor", jsonOutput: true}, "databricks aitools install --scope=global --agents=cursor --output json"}, + } + for _, tc := range tests { + t.Run(tc.goos+" "+tc.want, func(t *testing.T) { + got, ok := renderInstallCommand(tc.goos, tc.inv) + assert.True(t, ok) + assert.Equal(t, tc.want, got) + }) + } +} + +func TestRerunPhraseDelimitsACommandThatContainsAQuote(t *testing.T) { + assert.Equal(t, "'databricks aitools install --path=/tmp/out'", rerunPhrase("linux", installInvocation{path: "/tmp/out"})) + assert.Equal(t, "`databricks aitools install --path='my skills'`", rerunPhrase("linux", installInvocation{path: "my skills"})) + assert.Equal(t, `'databricks aitools install --path="my skills"'`, rerunPhrase("windows", installInvocation{path: "my skills"})) +} + +func TestRenderInstallCommandRejectsValuesThatDoNotPasteLiterally(t *testing.T) { + tests := []struct { + goos string + inv installInvocation + }{ + // A line break ends the pasted command and runs what follows, in any shell. + {"linux", installInvocation{skillsOnly: true, skills: "a\nrm -rf ~"}}, + {"darwin", installInvocation{path: "/tmp/a\r\nb"}}, + {"windows", installInvocation{skillsOnly: true, skills: "a\r\ndel *"}}, + // PowerShell expands $ and ` inside double quotes, cmd.exe %VAR% and + // !VAR!, and a double quote ends the string. + {"windows", installInvocation{path: `C:\$cache\skills`}}, + {"windows", installInvocation{skillsOnly: true, skills: "$(id)"}}, + {"windows", installInvocation{path: "C:\\a`b"}}, + {"windows", installInvocation{path: `C:\%TEMP%\skills`}}, + {"windows", installInvocation{path: `C:\!TEMP!\skills`}}, + {"windows", installInvocation{path: `C:\a"b`}}, + } + for _, tc := range tests { + t.Run(tc.goos+" "+tc.inv.path+tc.inv.skills, func(t *testing.T) { + _, ok := renderInstallCommand(tc.goos, tc.inv) + assert.False(t, ok) + assert.Equal(t, "your original install command with --debug", rerunPhrase(tc.goos, tc.inv, "--debug")) + }) + } +} + +func TestRecoveryAsksToRepeatTheCommandForAValueThatCannotBePrinted(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "") + inv := installInvocation{scope: installer.ScopeGlobal, skillsOnly: true, skills: "a\nb"} + err := &installer.FetchError{Stage: installer.FetchStageManifest, Err: dnsError} + assert.Equal(t, "Could not download Databricks skills from raw.githubusercontent.com. Check that this machine can reach it (set HTTPS_PROXY if you use a proxy), then re-run your original install command.", installRecovery(t.Context(), inv, err)) + assert.Equal(t, "Re-run your original install command with --debug to see details. If it keeps failing, report it at https://github.com/databricks/cli/issues.", installRecovery(t.Context(), inv, errors.New("boom"))) + + cursor := agents.ByName(agents.NameCursor) + assert.Equal(t, "To set up Cursor in the global scope, run: your original install command with --scope=global --agents=cursor", skipRecovery(inv, agentPlanItem{agent: cursor, delivery: deliverySkip})) +} + +func TestStateRecoveryDropsNamedSkills(t *testing.T) { + serr := &installer.StateError{Path: filepath.FromSlash("/home/u/.databricks/aitools/skills/.state.json"), Err: errors.New("failed to parse state file")} + inv := installInvocation{scope: installer.ScopeGlobal, agents: "cursor", skillsOnly: true, skills: "databricks-jobs"} + assert.Equal(t, "Move the install state file /home/u/.databricks/aitools/skills/.state.json aside (for example, rename it to .state.json.bak), then re-run 'databricks aitools install --scope=global --agents=cursor --skills-only' to reinstall all skills (without the state file, an install of named skills in the global scope is refused). The state file also tracked the other agents set up in this scope; re-run their install too, for example 'databricks aitools install --scope=global'.", installRecovery(t.Context(), inv, serr)) +} + +func TestStateRecoveryKeepsNamedSkillsInTheProjectScope(t *testing.T) { + // The installer refuses a targeted install without state only in the + // global scope, so a project-scope re-run keeps --skills. + serr := &installer.StateError{Path: filepath.FromSlash("/repo/.databricks/aitools/skills/.state.json"), Err: errors.New("failed to parse state file")} + inv := installInvocation{scope: installer.ScopeProject, agents: "cursor", skillsOnly: true, skills: "databricks-jobs"} + assert.Equal(t, "Move the install state file /repo/.databricks/aitools/skills/.state.json aside (for example, rename it to .state.json.bak), then re-run 'databricks aitools install --scope=project --agents=cursor --skills-only --skills=databricks-jobs'. The new state file records only the named skills, so the project's other skills stay untracked by update and uninstall; reinstall them too with 'databricks aitools install --scope=project --agents=cursor --skills-only'. The state file also tracked the other agents set up in this scope; re-run their install too, for example 'databricks aitools install --scope=project'.", installRecovery(t.Context(), inv, serr)) +} + +func TestRecoveryNamesAnOverrideWithoutAScheme(t *testing.T) { + // The CLI fetched what the variable says; there is no other host to name. + t.Setenv("DATABRICKS_SKILLS_BASE_URL", "mirror.internal/skills") + got := installRecovery(t.Context(), installInvocation{}, &installer.FetchError{Stage: installer.FetchStageManifest, Err: &url.Error{Op: "Get", URL: "mirror.internal/skills/v1/manifest.json", Err: dnsError}}) + assert.Contains(t, got, "Could not download Databricks skills from mirror.internal/skills.") +} + +func TestRefusalDoesNotHideAJoinedFailure(t *testing.T) { + // A refused skills install joined to a permission error on the state file: + // the category is PERMISSION_DENIED, so the ownership step is printed. + refused := &installer.RefusedError{Err: errors.New("refusing to downgrade skills from 0.3.0 to 0.2.0")} + denied := fmt.Errorf("failed to save state: %w", &fs.PathError{Op: "open", Path: filepath.FromSlash("/home/u/.databricks/aitools/skills/.state.json"), Err: fs.ErrPermission}) + got := installRecovery(t.Context(), installInvocation{}, errors.Join(refused, denied)) + assert.Equal(t, "Check that you own /home/u/.databricks/aitools/skills/.state.json and can write to it (an earlier run with sudo can leave it owned by root), then re-run 'databricks aitools install'.", got) +} + +func TestFilesystemRecoveryIsNotABugReport(t *testing.T) { + full := fmt.Errorf("failed to write skill: %w", &fs.PathError{Op: "write", Path: filepath.FromSlash("/home/u/.claude/skills/x/SKILL.md"), Err: syscall.ENOSPC}) + assert.Equal(t, "Check that /home/u/.claude/skills/x/SKILL.md is on a writable filesystem with free space, then re-run 'databricks aitools install'.", installRecovery(t.Context(), installInvocation{}, full)) +} + +func TestPinnedRefRecoveryMentionsTheVariableOnlyWhenSet(t *testing.T) { + t.Setenv("DATABRICKS_SKILLS_REF", "v9.9.9") + err := &installer.FetchError{Stage: installer.FetchStageManifest, StatusCode: http.StatusNotFound, Err: fmt.Errorf("skills manifest at x@v9.9.9: %w", clicompat.ErrNotFound)} + assert.Equal(t, "No skills release exists at the version DATABRICKS_SKILLS_REF names. Unset it, or set it to a release tag from https://github.com/databricks/databricks-agent-skills/releases, then re-run 'databricks aitools install'.", installRecovery(t.Context(), installInvocation{}, err)) +} diff --git a/cmd/root/stale_version.go b/cmd/root/stale_version.go index 4732b1cd22d..b33c0b98fbc 100644 --- a/cmd/root/stale_version.go +++ b/cmd/root/stale_version.go @@ -13,7 +13,7 @@ import ( const ( staleVersionThreshold = 6 * 30 * 24 * time.Hour - installDocsURL = "https://docs.databricks.com/dev-tools/cli/install.html" + InstallDocsURL = "https://docs.databricks.com/dev-tools/cli/install.html" ) // staleVersionWarning returns the warning for a build older than the threshold, or "" otherwise. @@ -28,7 +28,7 @@ func staleVersionWarning(buildTime, now time.Time, upgradeCommand string) string if upgradeCommand != "" { return msg + "To upgrade, run: " + upgradeCommand + "\n" } - return msg + "See " + installDocsURL + " to upgrade.\n" + return msg + "See " + InstallDocsURL + " to upgrade.\n" } func skipStaleVersionWarning(ctx context.Context, info build.Info) bool { diff --git a/cmd/root/stale_version_test.go b/cmd/root/stale_version_test.go index 8eeea38fbca..a7bcb8f4da6 100644 --- a/cmd/root/stale_version_test.go +++ b/cmd/root/stale_version_test.go @@ -33,7 +33,7 @@ func TestStaleVersionWarning(t *testing.T) { { name: "stale with unknown install method", buildTime: stale, - want: header + "See " + installDocsURL + " to upgrade.\n", + want: header + "See " + InstallDocsURL + " to upgrade.\n", }, } for _, tc := range tests { diff --git a/libs/aitools/installer/errors.go b/libs/aitools/installer/errors.go index b75a007821d..da28aa9906e 100644 --- a/libs/aitools/installer/errors.go +++ b/libs/aitools/installer/errors.go @@ -129,3 +129,14 @@ type StateError struct { func (e *StateError) Error() string { return e.Err.Error() } func (e *StateError) Unwrap() error { return e.Err } + +// RefusedError reports an install the installer declines to run in the +// current state, such as a downgrade or a targeted install over untracked +// skills. Its message already names what to do instead, so the command layer +// adds no generic retry step to it. +type RefusedError struct { + Err error +} + +func (e *RefusedError) Error() string { return e.Err.Error() } +func (e *RefusedError) Unwrap() error { return e.Err } diff --git a/libs/aitools/installer/installer.go b/libs/aitools/installer/installer.go index 2699fd4a38a..fa23a222c80 100644 --- a/libs/aitools/installer/installer.go +++ b/libs/aitools/installer/installer.go @@ -318,7 +318,7 @@ func installedSkillsRelease(state *InstallState) (ref string, allowFallback bool func checkSkillsDowngrade(installedRef, ref string, explicit bool) error { if !explicit && semver.Compare(ref, installedRef) < 0 { - return fmt.Errorf("refusing to downgrade skills from %s to %s; retry when the latest release is available or set DATABRICKS_SKILLS_REF=%s to select this version explicitly", DisplaySkillsVersion(installedRef), DisplaySkillsVersion(ref), ref) + return &RefusedError{Err: fmt.Errorf("refusing to downgrade skills from %s to %s; retry when the latest release is available or set DATABRICKS_SKILLS_REF=%s to select this version explicitly", DisplaySkillsVersion(installedRef), DisplaySkillsVersion(ref), ref)} } return nil } @@ -366,7 +366,7 @@ func InstallSkillsForAgents(ctx context.Context, src ManifestSource, targetAgent // hasLegacyInstall lives in update.go (shared with the update/uninstall paths). legacyInstall := state == nil && scope == ScopeGlobal && hasLegacyInstall(ctx, baseDir) if legacyInstall && len(opts.SpecificSkills) > 0 { - return errors.New("legacy install detected without state tracking; run 'databricks aitools install' (without a skill name) first to rebuild state") + return &RefusedError{Err: errors.New("legacy install detected without state tracking; run 'databricks aitools install --scope=global --skills-only' (without --skills) first to rebuild state")} } installedRef, allowFallback := installedSkillsRelease(state) diff --git a/libs/aitools/installer/installer_test.go b/libs/aitools/installer/installer_test.go index baf02bc3e57..389a13bec64 100644 --- a/libs/aitools/installer/installer_test.go +++ b/libs/aitools/installer/installer_test.go @@ -670,6 +670,8 @@ func TestCheckSkillsDowngrade(t *testing.T) { err := checkSkillsDowngrade(tc.installedRef, tc.ref, false) if tc.wantErr { require.ErrorContains(t, err, "refusing to downgrade skills") + // The message names the fix; callers add no generic step to it. + assert.ErrorAs(t, err, new(*RefusedError)) } else { require.NoError(t, err) } @@ -1015,6 +1017,7 @@ func TestLegacyTargetedInstallBlockedFromLegacyDir(t *testing.T) { }) require.Error(t, err) assert.Contains(t, err.Error(), "legacy install detected") + assert.ErrorAs(t, err, new(*RefusedError)) } func TestIdempotentInstallReinstallsForNewAgent(t *testing.T) { @@ -1109,6 +1112,38 @@ func TestLegacyFullInstallAllowed(t *testing.T) { assert.Len(t, state.Skills, 2) } +// The recovery step for a corrupt state file is to move it aside and install +// all skills: with skills on disk and no state, a targeted install is refused. +func TestCorruptStateRecoveryNeedsFullInstall(t *testing.T) { + tmp := setupTestHome(t) + ctx := cmdio.MockDiscard(t.Context()) + setupFetchMock(t) + t.Setenv("DATABRICKS_SKILLS_REF", testSkillsRef) + + globalDir := filepath.Join(tmp, ".databricks", "aitools", "skills") + require.NoError(t, os.MkdirAll(filepath.Join(globalDir, "databricks-sql"), 0o755)) + statePath := filepath.Join(globalDir, ".state.json") + require.NoError(t, os.WriteFile(statePath, []byte("{not json"), 0o644)) + + src := &mockManifestSource{manifest: testManifest()} + agent := testAgent(tmp) + targeted := InstallOptions{SpecificSkills: []string{"databricks-sql"}} + + err := InstallSkillsForAgents(ctx, src, []*agents.Agent{agent}, targeted) + _, ok := errors.AsType[*StateError](err) + require.True(t, ok, "want *StateError, got %v", err) + + require.NoError(t, os.Rename(statePath, statePath+".bak")) + err = InstallSkillsForAgents(ctx, src, []*agents.Agent{agent}, targeted) + require.ErrorContains(t, err, "legacy install detected") + + require.NoError(t, InstallSkillsForAgents(ctx, src, []*agents.Agent{agent}, InstallOptions{})) + state, err := LoadState(globalDir) + require.NoError(t, err) + require.NotNil(t, state) + assert.Len(t, state.Skills, 2) +} + func TestInstallAllSkillsSignaturePreserved(t *testing.T) { // Compile-time check that InstallAllSkills satisfies func(context.Context) error. callback := func(fn func(context.Context) error) { _ = fn } diff --git a/libs/aitools/installer/plugin.go b/libs/aitools/installer/plugin.go index 5801cbc95d5..e82d590e932 100644 --- a/libs/aitools/installer/plugin.go +++ b/libs/aitools/installer/plugin.go @@ -528,6 +528,26 @@ func RecordPluginInstalls(ctx context.Context, cliScope string, records map[stri 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 +// agent without a plugin or CLI binary. +func ManualPluginInstallCommands(agent *agents.Agent, nativeScope string) []string { + if agent.Plugin == nil || agent.Binary == "" { + return nil + } + var cmds []string + if agent.Plugin.Source != "" { + cmds = append(cmds, strings.Join(prepend(agent.Binary, marketplaceAddArgs(agent.Plugin)), " ")) + } + // The same refresh the headless install runs; a stale local marketplace + // reports the plugin as missing. + if args := marketplaceUpdateArgs(agent, agent.Plugin.Marketplace); args != nil { + cmds = append(cmds, strings.Join(prepend(agent.Binary, args), " ")) + } + return append(cmds, strings.Join(prepend(agent.Binary, pluginInstallArgs(agent, nativeScope)), " ")) +} + // prepend returns a fresh argv with bin as argv[0] followed by args. func prepend(bin string, args []string) []string { argv := make([]string, 0, len(args)+1) diff --git a/libs/aitools/installer/plugin_test.go b/libs/aitools/installer/plugin_test.go index acf52b8ceec..35836220150 100644 --- a/libs/aitools/installer/plugin_test.go +++ b/libs/aitools/installer/plugin_test.go @@ -874,6 +874,19 @@ func TestRunAgentCmdReportsTimeout(t *testing.T) { assert.Equal(t, "timed out after 1ms", blocked.Detail) } +func TestManualPluginInstallCommands(t *testing.T) { + assert.Equal(t, []string{ + "claude plugin marketplace add databricks/databricks-agent-skills", + "claude plugin marketplace update databricks-agent-skills", + "claude plugin install databricks@databricks-agent-skills --scope user", + }, ManualPluginInstallCommands(claudeAgent(), "user")) + assert.Equal(t, []string{ + "codex plugin marketplace add databricks/databricks-agent-skills", + "codex plugin add databricks@databricks-agent-skills", + }, ManualPluginInstallCommands(codexAgent(), "")) + assert.Nil(t, ManualPluginInstallCommands(noPluginAgent(), "")) +} + // copilotPluginHelp is the commander-style shape of `copilot plugin --help`. const copilotPluginHelp = "Usage: copilot plugin [options] [command]\n\nManage plugins\n\nCommands:\n install Install a plugin\n uninstall Uninstall a plugin\n marketplace Manage marketplaces\n" diff --git a/libs/shellquote/quote.go b/libs/shellquote/quote.go index e7be6753846..fdc4a8bd5ef 100644 --- a/libs/shellquote/quote.go +++ b/libs/shellquote/quote.go @@ -2,6 +2,7 @@ package shellquote import ( "strings" + "unicode" ) // BashArg quotes a string for safe use as a bash command argument. @@ -37,3 +38,42 @@ func isSafeChar(c rune) bool { (c >= '0' && c <= '9') || c == '-' || c == '_' || c == '/' || c == '.' || c == ':' } + +// WindowsArg quotes a string for use as a command argument that cmd.exe and +// PowerShell pass to the program as one argument, without expanding anything +// in it. It returns the argument unquoted unless it contains whitespace (any +// Unicode space: PowerShell splits arguments at a no-break space too), a +// cmd.exe command separator, or a character PowerShell treats specially outside +// quotes (a single quote starts a string, braces a script block, @ and # +// splatting and comments); backslashes are path separators there, not escapes. +// Quoted arguments get their trailing backslashes doubled, so the closing +// quote is not escaped when the program parses its command line from cmd.exe. +// PowerShell 7.3 and later quote arguments themselves and treat a backslash as +// a literal, so there a doubled trailing backslash reaches the program as two +// backslashes; for a path that is harmless. +// +// Parsing rules encoded here: +// - Program command lines: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments +// - cmd.exe: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd +// - PowerShell quoting: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules +// - PowerShell native argument passing: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing +// +// The second result is false when no quoting keeps s literal in both shells: +// inside double quotes PowerShell still expands $ and ` (a $(...) runs a +// command), cmd.exe still expands %VAR% and, with delayed expansion, !VAR!, a +// double quote ends the string, and a control character such as a line break +// ends the command when pasted. Callers must not print such a string as part +// of a command. +func WindowsArg(s string) (string, bool) { + if strings.ContainsAny(s, "$`%!\"“”„") || strings.ContainsFunc(s, unicode.IsControl) { + return "", false + } + if s == "" { + return `""`, true + } + if !strings.ContainsAny(s, "&^()<>|,;='{}@#‘’‚‛") && !strings.ContainsFunc(s, unicode.IsSpace) { + return s, true + } + trailing := len(s) - len(strings.TrimRight(s, `\`)) + return `"` + s + strings.Repeat(`\`, trailing) + `"`, true +} diff --git a/libs/shellquote/quote_test.go b/libs/shellquote/quote_test.go index e1f67b90e69..4ed53d3f508 100644 --- a/libs/shellquote/quote_test.go +++ b/libs/shellquote/quote_test.go @@ -61,3 +61,74 @@ func TestBashArg(t *testing.T) { }) } } + +func TestWindowsArg(t *testing.T) { + tests := []struct { + input string + expected string + }{ + // Backslashes and 8.3 short names are not special to cmd.exe or PowerShell. + {`C:\Users\me\skills`, `C:\Users\me\skills`}, + {`C:\Users\RUNNER~1\AppData\Local\Temp\out`, `C:\Users\RUNNER~1\AppData\Local\Temp\out`}, + {`.\out`, `.\out`}, + + // cmd.exe splits at spaces and command separators. + {`C:\my skills`, `"C:\my skills"`}, + {`C:\Program Files (x86)\out`, `"C:\Program Files (x86)\out"`}, + // PowerShell also splits at Unicode spaces such as a no-break space. + {"C:\\my\u00a0skills", "\"C:\\my\u00a0skills\""}, + {"C:\\my\u3000skills", "\"C:\\my\u3000skills\""}, + {`C:\a&b`, `"C:\a&b"`}, + {`C:\a;b`, `"C:\a;b"`}, + // PowerShell starts a string at a bare single quote, a script block at a + // brace, and splats or comments at @ and #. + {`C:\it's`, `"C:\it's"`}, + {"C:\\it\u2019s", "\"C:\\it\u2019s\""}, + {`C:\a{b}`, `"C:\a{b}"`}, + {`@out`, `"@out"`}, + {`C:\#out`, `"C:\#out"`}, + {`data science,databricks-jobs`, `"data science,databricks-jobs"`}, + + // A trailing backslash would escape the closing quote. + {`C:\my skills\`, `"C:\my skills\\"`}, + {`C:\my skills\\`, `"C:\my skills\\\\"`}, + + {"", `""`}, + } + + for _, tt := range tests { + t.Run(tt.input, func(t *testing.T) { + got, ok := WindowsArg(tt.input) + assert.True(t, ok) + assert.Equal(t, tt.expected, got) + }) + } +} + +func TestWindowsArgRejectsWhatNoQuotingKeepsLiteral(t *testing.T) { + for _, input := range []string{ + // PowerShell expands variables and runs subexpressions inside double quotes. + `C:\$cache\skills`, + `$(Remove-Item -Recurse ~)`, + "C:\\a`b", + // cmd.exe expands %VAR% inside double quotes, and !VAR! with delayed + // expansion. + `C:\%TEMP%\skills`, + `C:\!TEMP!\skills`, + `C:\a!b`, + // A double quote, or a typographic one PowerShell reads as one, ends the string. + `C:\a"b`, + "C:\\a\u201cb", + // A line break ends the pasted command; other control characters do not + // paste as typed. + "C:\\a\nb", + "C:\\a\r\ndel *", + "C:\\a\rb", + "C:\\a\tb", + } { + t.Run(input, func(t *testing.T) { + _, ok := WindowsArg(input) + assert.False(t, ok) + }) + } +}