Skip to content

Commit d0cb9df

Browse files
anton-107Isaac
andcommitted
aitools: report a Windows shim that printed help but exited non-zero under its own reason
On Windows, the `codex.cmd` and `copilot.bat` shims can print the full `plugin --help` and then exit 1. Because of that, `databricks aitools install` reported a CLI that is present as `cli-not-on-path`, which points the user at the wrong fix. The probe now reports that case as `shim-exited-with-error` and still stops before running any plugin command: ```diff probePluginCLI(agent) bin = lookPath(agent CLI) err = run `<bin> plugin --help` (20s timeout) - if err: block cli-not-on-path + if err and windowsShimPrintedHelp(bin, err): block shim-exited-with-error + ("printed its plugin help but exited with an error (<exit>)[: <stderr>]; + to see the error and exit code, run + `& "<bin>" plugin --help; $LASTEXITCODE` in PowerShell or + `"<bin>" plugin --help & echo %ERRORLEVEL%` in Command Prompt, and + re-run this command once it exits with 0") + if err: block cli-not-on-path +windowsShimPrintedHelp(bin, err) + bin ends in .cmd or .bat (LookPath returns these only on Windows) + and err is not a timeout + and stdout has a `Usage: <bin> plugin` line + and indented `install`/`add` and `marketplace` command lines ``` `blockedErrorCategory` maps the new reason to `PLUGIN_INSTALL_FAILED`, the closest existing category. Changelog fragment: `.nextchanges/cli/aitools-windows-shim-probe.md`. Co-authored-by: Isaac <no-reply@databricks.com>
1 parent 7f0dcdf commit d0cb9df

6 files changed

Lines changed: 181 additions & 1 deletion

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* `databricks aitools install` and `databricks aitools update` now report a coding agent CLI shim (`.cmd` or `.bat`) on Windows that prints its plugin help and then exits with an error as `shim-exited-with-error`, with the command to run to see the error, instead of reporting the CLI as not on PATH. ([#7476](https://github.com/databricks/cli/pull/7476))

‎cmd/aitools/categorize.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,9 @@ func blockedErrorCategory(e *installer.BlockedError) protos.AitoolsErrorCategory
191191
switch e.Reason {
192192
case installer.ReasonCLINotOnPath:
193193
return protos.AitoolsErrorCategoryCLINotOnPath
194-
case installer.ReasonInstallFailed:
194+
// A shim that exited with an error is a present CLI whose plugin command
195+
// failed, which is closest to a failed plugin install.
196+
case installer.ReasonInstallFailed, installer.ReasonShimExitedWithError:
195197
return protos.AitoolsErrorCategoryPluginInstallFailed
196198
default:
197199
return protos.AitoolsErrorCategoryUncategorized

‎cmd/aitools/categorize_test.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,11 @@ func TestClassifyInstallError(t *testing.T) {
4747
err: &installer.BlockedError{Agent: "codex", Reason: installer.ReasonInstallFailed},
4848
want: protos.AitoolsErrorCategoryPluginInstallFailed,
4949
},
50+
{
51+
name: "blocked shim exited with error",
52+
err: &installer.BlockedError{Agent: "copilot", Reason: installer.ReasonShimExitedWithError},
53+
want: protos.AitoolsErrorCategoryPluginInstallFailed,
54+
},
5055
{
5156
name: "blocked timeout wins over its reason",
5257
err: &installer.BlockedError{Agent: "claude-code", Reason: installer.ReasonCLINotOnPath, TimedOut: true},

‎libs/aitools/installer/plugin.go‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ import (
66
"fmt"
77
"maps"
88
"os/exec"
9+
"path/filepath"
10+
"regexp"
911
"strings"
12+
"sync"
1013
"time"
1114

1215
"github.com/databricks/cli/libs/aitools/agents"
@@ -52,6 +55,10 @@ const (
5255
// ReasonCLINotOnPath: the agent's CLI binary is not on PATH, or its CLI does
5356
// not expose a working `plugin` subcommand.
5457
ReasonCLINotOnPath = "cli-not-on-path"
58+
// ReasonShimExitedWithError: the agent's Windows .cmd/.bat shim printed its
59+
// `plugin --help` but exited with an error. The install stops here rather
60+
// than run plugin commands through a shim that may fail part way.
61+
ReasonShimExitedWithError = "shim-exited-with-error"
5562
// ReasonInstallFailed: the agent's plugin CLI ran but returned an error.
5663
ReasonInstallFailed = "install-failed"
5764
// ReasonNoPlugin: the agent has no installable plugin. Callers filter these
@@ -300,11 +307,67 @@ func probePluginCLI(ctx context.Context, agent *agents.Agent) (string, error) {
300307
return "", &BlockedError{Agent: agent.Name, Reason: ReasonCLINotOnPath, Detail: err.Error()}
301308
}
302309
if _, err := runAgentCmd(ctx, pluginProbeTimeout, []string{bin, "plugin", "--help"}); err != nil {
310+
if perr, ok := windowsShimPrintedHelp(bin, err); ok {
311+
return "", &BlockedError{Agent: agent.Name, Reason: ReasonShimExitedWithError, Detail: shimExitedDetail(bin, perr)}
312+
}
303313
return "", newBlockedError(agent, ReasonCLINotOnPath, err)
304314
}
305315
return bin, nil
306316
}
307317

318+
// shimExitedDetail explains a shim that printed its plugin help but exited with
319+
// an error. It keeps the shim's stderr, since a re-run may show only the help,
320+
// and names how to read the exit code, which neither Windows shell prints. The
321+
// path stays absolute and keeps its backslashes so it can be pasted into
322+
// Command Prompt or PowerShell as is, and it is quoted because a profile path
323+
// can contain spaces. PowerShell needs the & call operator before a quoted path.
324+
func shimExitedDetail(bin string, perr *process.ProcessError) string {
325+
detail := fmt.Sprintf("printed its plugin help but exited with an error (%s)", perr.Err)
326+
if stderr := strings.TrimSpace(perr.Stderr); stderr != "" {
327+
detail += ": " + stderr
328+
}
329+
return detail + fmt.Sprintf("; to see the error and exit code, run `& \"%[1]s\" plugin --help; $LASTEXITCODE` in PowerShell or `\"%[1]s\" plugin --help & echo %%ERRORLEVEL%%` in Command Prompt, and re-run this command once it exits with 0", bin)
330+
}
331+
332+
// pluginHelpUsage, pluginHelpInstall and pluginHelpMarket match the help that
333+
// `<agent> plugin --help` prints: a "Usage: <bin> plugin" line and an indented
334+
// command list that includes install (add for Codex) and marketplace. An error
335+
// message that merely mentions those words has neither shape.
336+
var (
337+
pluginHelpUsage = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`(?im)^usage:[ \t]+\S+[ \t]+plugin\b`) })
338+
pluginHelpInstall = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`(?m)^[ \t]+(install|add)\b`) })
339+
pluginHelpMarket = sync.OnceValue(func() *regexp.Regexp { return regexp.MustCompile(`(?m)^[ \t]+marketplace\b`) })
340+
)
341+
342+
// windowsShimPrintedHelp reports whether a failed probe is a Windows shim that
343+
// printed the full `plugin --help` and then exited with an error, and returns
344+
// the failed process. Such a CLI is present, so reporting it as not on PATH
345+
// would point the user at the wrong fix. Agent binaries are bare names, so
346+
// LookPath returns a .cmd or .bat path only on Windows. Only stdout is matched:
347+
// the agent CLIs print --help to stdout, and help on stderr usually means the
348+
// CLI rejected its arguments.
349+
//
350+
// No public upstream report documents this exit code, so there is no link to
351+
// cite; TestProbeRealCmdShimPrintedHelp runs a real .cmd that prints the help
352+
// and exits 1 to check that this path sees it.
353+
func windowsShimPrintedHelp(bin string, err error) (*process.ProcessError, bool) {
354+
if ext := strings.ToLower(filepath.Ext(bin)); ext != ".cmd" && ext != ".bat" {
355+
return nil, false
356+
}
357+
if _, ok := errors.AsType[*agentCmdTimeoutError](err); ok {
358+
return nil, false
359+
}
360+
perr, ok := errors.AsType[*process.ProcessError](err)
361+
if !ok {
362+
return nil, false
363+
}
364+
out := perr.Stdout
365+
if !pluginHelpUsage().MatchString(out) || !pluginHelpInstall().MatchString(out) || !pluginHelpMarket().MatchString(out) {
366+
return nil, false
367+
}
368+
return perr, true
369+
}
370+
308371
// InstallPluginForAgent registers the databricks marketplace and installs the
309372
// plugin through the agent's own CLI, returning the record to persist in state.
310373
// It never falls back to skills: a blocked install returns a *BlockedError.

‎libs/aitools/installer/plugin_test.go‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import (
77
"log/slog"
88
"os/exec"
99
"path/filepath"
10+
"strings"
1011
"testing"
1112
"time"
1213

@@ -847,3 +848,77 @@ func TestRunAgentCmdReportsTimeout(t *testing.T) {
847848
assert.Equal(t, ReasonCLINotOnPath, blocked.Reason)
848849
assert.Equal(t, "timed out after 1ms", blocked.Detail)
849850
}
851+
852+
// copilotPluginHelp is the commander-style shape of `copilot plugin --help`.
853+
const copilotPluginHelp = "Usage: copilot plugin [options] [command]\n\nManage plugins\n\nCommands:\n install <plugin> Install a plugin\n uninstall <plugin> Uninstall a plugin\n marketplace Manage marketplaces\n"
854+
855+
// codexPluginHelp is the clap-style shape of `codex plugin --help`, which
856+
// lists add rather than install.
857+
const codexPluginHelp = "Manage plugins\n\nUsage: codex plugin [OPTIONS] <COMMAND>\n\nCommands:\n add Install a plugin\n marketplace Manage plugin marketplaces\n help Print this message or the help of the given subcommand(s)\n\nOptions:\n -h, --help Print help\n"
858+
859+
func TestProbeWindowsShimPrintedHelp(t *testing.T) {
860+
copilot := pluginAgent(agents.NameCopilot, "GitHub Copilot", "copilot")
861+
tests := []struct {
862+
name string
863+
agent *agents.Agent
864+
bin string
865+
stdout string
866+
stderr string
867+
shim bool
868+
}{
869+
{name: "windows .bat shim printed help and exited 1", agent: copilot, bin: `C:\npm\copilot.bat`, stdout: copilotPluginHelp, shim: true},
870+
{name: "windows .cmd shim printed help and exited 1", agent: copilot, bin: `C:\npm\copilot.cmd`, stdout: copilotPluginHelp, shim: true},
871+
{name: "windows shim under a path with a space", agent: copilot, bin: `C:\Users\Jane Doe\AppData\Roaming\npm\copilot.cmd`, stdout: copilotPluginHelp, shim: true},
872+
{name: "windows shim that printed an error on stderr", agent: copilot, bin: `C:\npm\copilot.cmd`, stdout: copilotPluginHelp, stderr: " node: bad option\n", shim: true},
873+
{name: "help on stderr is not a shim that printed help", agent: copilot, bin: `C:\npm\copilot.cmd`, stderr: copilotPluginHelp},
874+
{name: "windows codex .cmd shim printed clap help and exited 1", agent: codexAgent(), bin: `C:\npm\codex.cmd`, stdout: codexPluginHelp, shim: true},
875+
{name: "windows shim without a plugin command", agent: codexAgent(), bin: `C:\npm\codex.cmd`, stdout: "error: unknown command 'plugin'\n"},
876+
{name: "unix binary is not a shim", agent: copilot, bin: "/usr/bin/copilot", stdout: copilotPluginHelp},
877+
{name: "windows .exe is not a shim", agent: copilot, bin: `C:\bin\copilot.exe`, stdout: copilotPluginHelp},
878+
{name: "error that mentions both words", agent: copilot, bin: `C:\npm\copilot.bat`, stdout: "Error: cannot install plugins: marketplace disabled by policy\n"},
879+
{name: "usage line without a command list", agent: copilot, bin: `C:\npm\copilot.bat`, stdout: "Usage: copilot plugin\nerror: install and marketplace are not available\n"},
880+
{name: "unindented words after blank lines", agent: copilot, bin: `C:\npm\copilot.bat`, stdout: "Usage: copilot plugin [options]\n\nmarketplace: disabled by policy\n\ninstall is not permitted\n"},
881+
}
882+
for _, tc := range tests {
883+
t.Run(tc.name, func(t *testing.T) {
884+
origLook := lookPath
885+
t.Cleanup(func() { lookPath = origLook })
886+
lookPath = func(string) (string, error) { return tc.bin, nil }
887+
888+
ctx, stub := process.WithStub(t.Context())
889+
stub.WithCallback(func(*exec.Cmd) error { return nil })
890+
stub.WithStdoutFor("plugin --help", tc.stdout)
891+
stub.WithStderrFor("plugin --help", tc.stderr)
892+
stub.WithFailureFor("plugin --help", errors.New("exit status 1"))
893+
894+
_, err := InstallPluginForAgent(ctx, tc.agent, "", "v0.2.6")
895+
var be *BlockedError
896+
require.ErrorAs(t, err, &be)
897+
if tc.shim {
898+
assert.Equal(t, ReasonShimExitedWithError, be.Reason)
899+
assert.False(t, be.TimedOut)
900+
wantDetail := "printed its plugin help but exited with an error (exit status 1)"
901+
if tc.stderr != "" {
902+
wantDetail += ": " + strings.TrimSpace(tc.stderr)
903+
}
904+
wantDetail += "; to see the error and exit code, run `& \"" + tc.bin + "\" plugin --help; $LASTEXITCODE` in PowerShell or `\"" + tc.bin + "\" plugin --help & echo %ERRORLEVEL%` in Command Prompt, and re-run this command once it exits with 0"
905+
assert.Equal(t, wantDetail, be.Detail)
906+
} else {
907+
assert.Equal(t, ReasonCLINotOnPath, be.Reason)
908+
}
909+
assert.Len(t, stub.Commands(), 1, "nothing runs after a failed probe")
910+
})
911+
}
912+
}
913+
914+
func TestWindowsShimPrintedHelpRejectsTimeout(t *testing.T) {
915+
// A shim that printed the help and then hung until its deadline reports the
916+
// timeout, even though the same output without the timeout is a shim error.
917+
perr := &process.ProcessError{Command: "copilot.bat plugin --help", Err: errors.New("exit status 1"), Stdout: copilotPluginHelp}
918+
bin := `C:\npm\copilot.bat`
919+
got, ok := windowsShimPrintedHelp(bin, perr)
920+
assert.True(t, ok)
921+
assert.Same(t, perr, got)
922+
_, ok = windowsShimPrintedHelp(bin, &agentCmdTimeoutError{timeout: time.Second, err: perr})
923+
assert.False(t, ok)
924+
}
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
//go:build windows
2+
3+
package installer
4+
5+
import (
6+
"os"
7+
"path/filepath"
8+
"strings"
9+
"testing"
10+
11+
"github.com/databricks/cli/libs/aitools/agents"
12+
"github.com/stretchr/testify/assert"
13+
"github.com/stretchr/testify/require"
14+
)
15+
16+
// TestProbeRealCmdShimPrintedHelp runs a real .cmd shim that prints the plugin
17+
// help and exits 1, so the probe sees the exit code and stdout that cmd.exe
18+
// actually reports rather than a stub.
19+
func TestProbeRealCmdShimPrintedHelp(t *testing.T) {
20+
dir := t.TempDir()
21+
require.NoError(t, os.WriteFile(filepath.Join(dir, "help.txt"), []byte(copilotPluginHelp), 0o644))
22+
shim := filepath.Join(dir, "copilot.cmd")
23+
require.NoError(t, os.WriteFile(shim, []byte("@type \"%~dp0help.txt\"\r\n@exit /b 1\r\n"), 0o755))
24+
25+
origLook := lookPath
26+
t.Cleanup(func() { lookPath = origLook })
27+
lookPath = func(string) (string, error) { return shim, nil }
28+
29+
_, err := InstallPluginForAgent(t.Context(), pluginAgent(agents.NameCopilot, "GitHub Copilot", "copilot"), "", "v0.2.6")
30+
var be *BlockedError
31+
require.ErrorAs(t, err, &be)
32+
assert.Equal(t, ReasonShimExitedWithError, be.Reason)
33+
assert.True(t, strings.HasPrefix(be.Detail, "printed its plugin help but exited with an error (exit status 1)"), be.Detail)
34+
}

0 commit comments

Comments
 (0)