feat(ssh): pre-check the host CLI before starting the SSH tunnel (#2127)

## Changes

`databricks ssh connect` shells out to the host editor's shell command
(`code`/`cursor`) to open the remote window. When that command is off
PATH, the connect only failed deep inside the terminal after a long
wait. Fail fast instead: pre-check the command before touching auth,
compute, or a terminal, and surface an actionable prompt whose button
installs the shell command (falling back to the editor's download page
on hosts without the built-in installer).

Adds HostUtils.getHostCliCommand/isHostCliOnPath to resolve and probe
the command through a shell so PATH resolves as the terminal would.

## Tests


[hostUtils.ts](https://github.com/databricks/databricks-vscode/compare/fix/ssh-tunnel-host-cli-precheck?expand=1#diff-c1b4d8aeff4272f092f04f6ffbccb9c3d97f0f96c549d129b915dc1f9d2aba57)

Author: misha-db

packages/databricks-vscode/package.json

@@ -1900,6 +1900,7 @@
         "lodash": "^4.17.21",
         "markdown-it": "^14.2.0",
         "minimatch": "^10.0.1",
+        "shell-env": "^4.0.3",
         "shell-quote": "^1.8.4",
         "triple-beam": "^1.4.1",
         "winston": "^3.11.0",

packages/databricks-vscode/src/ssh/SshCommands.test.ts

@@ -0,0 +1,173 @@
+import assert from "assert";
+import {commands, Uri, window} from "vscode";
+import {instance, mock} from "ts-mockito";
+import {CliWrapper} from "../cli/CliWrapper";
+import {SshCommands} from "./SshCommands";
+import {HostUtils} from "../utils";
+
+/**
+ * Exercises the advisory host-CLI PATH warning in isolation. The prompt is
+ * fired-and-forgotten from startTunnelCommand, so tests reach the private
+ * warnIfHostCliMissing directly and flush the detached prompt chain it kicks
+ * off before asserting on the message and any follow-up command.
+ */
+describe(__filename, () => {
+    let originalIsHostCliOnPath: typeof HostUtils.isHostCliOnPath;
+    let originalGetHostCliCommand: typeof HostUtils.getHostCliCommand;
+    let originalIsCursor: typeof HostUtils.isCursor;
+    let originalShowWarningMessage: typeof window.showWarningMessage;
+    let originalExecuteCommand: typeof commands.executeCommand;
+    let originalPlatform: PropertyDescriptor | undefined;
+
+    // Messages shown and their offered actions, plus the executed commands, so
+    // each test can assert what the user was prompted with and what ran.
+    let shownWarnings: {message: string; items: string[]}[];
+    let executedCommands: {command: string; args: unknown[]}[];
+    // The action the stubbed warning resolves with (what the user "clicks").
+    let warningResponse: string | undefined;
+
+    function stubPlatform(value: NodeJS.Platform) {
+        Object.defineProperty(process, "platform", {
+            value,
+            configurable: true,
+        });
+    }
+
+    function newSshCommands(): SshCommands {
+        return new SshCommands(instance(mock(CliWrapper)));
+    }
+
+    // Runs the fire-and-forget warning, then drains the microtask queue so the
+    // detached prompt chain (warning → follow-up command) has fully settled.
+    async function warn(sshCommands: SshCommands) {
+        await (sshCommands as any).warnIfHostCliMissing();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+
+    beforeEach(() => {
+        shownWarnings = [];
+        executedCommands = [];
+        warningResponse = undefined;
+
+        originalIsHostCliOnPath = HostUtils.isHostCliOnPath;
+        originalGetHostCliCommand = HostUtils.getHostCliCommand;
+        originalIsCursor = HostUtils.isCursor;
+        originalShowWarningMessage = window.showWarningMessage;
+        originalExecuteCommand = commands.executeCommand;
+        originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+
+        (window as any).showWarningMessage = (
+            message: string,
+            ...items: string[]
+        ) => {
+            shownWarnings.push({message, items});
+            return Promise.resolve(warningResponse);
+        };
+        (commands as any).executeCommand = (
+            command: string,
+            ...args: unknown[]
+        ) => {
+            executedCommands.push({command, args});
+            return Promise.resolve();
+        };
+    });
+
+    afterEach(() => {
+        (HostUtils as any).isHostCliOnPath = originalIsHostCliOnPath;
+        (HostUtils as any).getHostCliCommand = originalGetHostCliCommand;
+        (HostUtils as any).isCursor = originalIsCursor;
+        (window as any).showWarningMessage = originalShowWarningMessage;
+        (commands as any).executeCommand = originalExecuteCommand;
+        if (originalPlatform) {
+            Object.defineProperty(process, "platform", originalPlatform);
+        }
+    });
+
+    it("shows no warning when the host CLI is on PATH", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => true;
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(shownWarnings.length, 0);
+        assert.strictEqual(executedCommands.length, 0);
+    });
+
+    it("offers the shell-command installer on macOS", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => false;
+        (HostUtils as any).getHostCliCommand = () => "code";
+        stubPlatform("darwin");
+        warningResponse = "Install shell command";
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(shownWarnings.length, 1);
+        assert.ok(shownWarnings[0].message.includes('"code"'));
+        assert.deepStrictEqual(shownWarnings[0].items, [
+            "Install shell command",
+        ]);
+        assert.deepStrictEqual(executedCommands, [
+            {command: "workbench.action.installCommandLine", args: []},
+        ]);
+    });
+
+    it("does not run the installer on macOS when the prompt is dismissed", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => false;
+        (HostUtils as any).getHostCliCommand = () => "code";
+        stubPlatform("darwin");
+        warningResponse = undefined;
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(shownWarnings.length, 1);
+        assert.strictEqual(executedCommands.length, 0);
+    });
+
+    it("points at the VS Code PATH docs off macOS", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => false;
+        (HostUtils as any).getHostCliCommand = () => "code";
+        (HostUtils as any).isCursor = () => false;
+        stubPlatform("linux");
+        warningResponse = "Setup instructions";
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(shownWarnings.length, 1);
+        assert.deepStrictEqual(shownWarnings[0].items, ["Setup instructions"]);
+        assert.strictEqual(executedCommands.length, 1);
+        assert.strictEqual(executedCommands[0].command, "vscode.open");
+        assert.strictEqual(
+            (executedCommands[0].args[0] as Uri).toString(),
+            Uri.parse(
+                "https://code.visualstudio.com/docs/setup/setup-overview"
+            ).toString()
+        );
+    });
+
+    it("points at the Cursor PATH docs off macOS in Cursor", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => false;
+        (HostUtils as any).getHostCliCommand = () => "cursor";
+        (HostUtils as any).isCursor = () => true;
+        stubPlatform("linux");
+        warningResponse = "Setup instructions";
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(
+            (executedCommands[0].args[0] as Uri).toString(),
+            Uri.parse("https://docs.cursor.com/en/cli/installation").toString()
+        );
+    });
+
+    it("does not open docs off macOS when the prompt is dismissed", async () => {
+        (HostUtils as any).isHostCliOnPath = async () => false;
+        (HostUtils as any).getHostCliCommand = () => "code";
+        (HostUtils as any).isCursor = () => false;
+        stubPlatform("linux");
+        warningResponse = undefined;
+
+        await warn(newSshCommands());
+
+        assert.strictEqual(shownWarnings.length, 1);
+        assert.strictEqual(executedCommands.length, 0);
+    });
+});

packages/databricks-vscode/src/ssh/SshCommands.ts

@@ -1,10 +1,12 @@
 import {
+    commands,
     Disposable,
     Event,
     EventEmitter,
     QuickPick,
     QuickPickItem,
     QuickPickItemKind,
+    Uri,
     window,
 } from "vscode";
 import {WorkspaceClient} from "@databricks/sdk-experimental";
@@ -24,6 +26,7 @@ import {AuthProvider} from "../configuration/auth/AuthProvider";
 import {LoginWizard} from "../configuration/LoginWizard";
 import {Cluster} from "../sdk-extensions";
 import {onError} from "../utils/onErrorDecorator";
+import {HostUtils} from "../utils";
 import {logging} from "@databricks/sdk-experimental";
 import {Loggers} from "../logger";
 
@@ -170,6 +173,15 @@ export class SshCommands implements Disposable {
 
     @onError({popup: {prefix: "Error starting SSH tunnel."}})
     async startTunnelCommand() {
+        // `databricks ssh connect` shells out to the host command (`code`/
+        // `cursor`) to open the remote window; when it is off PATH the connect
+        // only fails deep inside the terminal after a long wait. Surface an
+        // actionable in-editor hint up front when the command looks missing.
+        // This is advisory only — the probe runs a non-interactive shell whose
+        // PATH can differ from the terminal's, so we still proceed and let the
+        // terminal report the real error rather than blocking a tunnel that
+        // would have worked.
+        await this.warnIfHostCliMissing();
         const context = await this.resolveTunnelContext();
         if (context === undefined) {
             return;
@@ -412,6 +424,64 @@ export class SshCommands implements Disposable {
         return false;
     }
 
+    /**
+     * When the host editor's shell command (`code`/`cursor`) looks missing from
+     * PATH — which `databricks ssh connect` needs to open the remote window —
+     * shows a non-blocking hint. The probe is advisory (its PATH can differ from
+     * the terminal's), so this never gates the tunnel; the prompt is fired and
+     * forgotten while the caller proceeds.
+     *
+     * On macOS the prompt offers the built-in "Install shell command" installer.
+     * `workbench.action.installCommandLine` is registered only on macOS, so
+     * elsewhere we point at the editor's PATH-setup docs instead of telling the
+     * user to reinstall an editor they already have.
+     */
+    private async warnIfHostCliMissing(): Promise<void> {
+        if (await HostUtils.isHostCliOnPath()) {
+            return;
+        }
+        const cmd = HostUtils.getHostCliCommand();
+        const message =
+            `The "${cmd}" command may not be on your PATH, which the ` +
+            `Databricks SSH tunnel needs to open the remote window. If the ` +
+            `tunnel fails to open a window, add it to your PATH and try again.`;
+
+        const promptChain =
+            process.platform === "darwin"
+                ? this.promptInstallShellCommand(message)
+                : this.promptPathSetupDocs(message);
+        // The prompt outlives this call by design; make sure a rejection in the
+        // detached chain can't surface as an unhandled rejection.
+        promptChain.catch((e) => {
+            logging.NamedLogger.getOrCreate(Loggers.Extension).error(
+                "Failed to handle host CLI PATH prompt",
+                e
+            );
+        });
+    }
+
+    private async promptInstallShellCommand(message: string): Promise<void> {
+        const install = "Install shell command";
+        const choice = await window.showWarningMessage(message, install);
+        if (choice !== install) {
+            return;
+        }
+        // Built-in "Shell Command: Install '<cmd>' command in PATH" (macOS only).
+        await commands.executeCommand("workbench.action.installCommandLine");
+    }
+
+    private async promptPathSetupDocs(message: string): Promise<void> {
+        const setup = "Setup instructions";
+        const choice = await window.showWarningMessage(message, setup);
+        if (choice !== setup) {
+            return;
+        }
+        const url = HostUtils.isCursor()
+            ? "https://docs.cursor.com/en/cli/installation"
+            : "https://code.visualstudio.com/docs/setup/setup-overview";
+        await commands.executeCommand("vscode.open", Uri.parse(url));
+    }
+
     private async launchSshTunnel(
         authProvider: AuthProvider,
         compute: Compute

packages/databricks-vscode/src/utils/hostUtils.test.ts

@@ -1,6 +1,7 @@
 import {env} from "vscode";
 import assert from "assert";
-import {isCursor} from "./hostUtils";
+import {getHostCliCommand, isCursor, isHostCliOnPath} from "./hostUtils";
+import {cancellableExecFile} from "../cli/CliWrapper";
 
 describe(__filename, () => {
     let originalAppName: PropertyDescriptor | undefined;
@@ -31,4 +32,90 @@ describe(__filename, () => {
         stubUriScheme("vscode");
         assert.strictEqual(isCursor(), false);
     });
+
+    it("resolves the host CLI command to cursor in Cursor", () => {
+        stubUriScheme("cursor");
+        assert.strictEqual(getHostCliCommand(), "cursor");
+    });
+
+    it("resolves the host CLI command to code in VS Code", () => {
+        stubUriScheme("vscode");
+        assert.strictEqual(getHostCliCommand(), "code");
+    });
+
+    it("resolves the host CLI command to code in Insiders (the CLI has no Insiders descriptor)", () => {
+        stubUriScheme("vscode-insiders");
+        assert.strictEqual(getHostCliCommand(), "code");
+    });
+
+    describe("isHostCliOnPath", () => {
+        // A resolved profile env; the probe passes this to `execFile` as PATH.
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        const loadShellEnv = async () => async () => ({PATH: "/usr/bin"});
+
+        it("is true when the probe succeeds", async () => {
+            const exec = (async () => ({
+                stdout: "1.0.0",
+                stderr: "",
+            })) as unknown as typeof cancellableExecFile;
+            assert.strictEqual(await isHostCliOnPath(exec, loadShellEnv), true);
+        });
+
+        it("is false only when the command is definitively not found", async () => {
+            const notFound = Object.assign(new Error("spawn ENOENT"), {
+                code: "ENOENT",
+            });
+            const exec = (async () => {
+                throw notFound;
+            }) as unknown as typeof cancellableExecFile;
+            assert.strictEqual(
+                await isHostCliOnPath(exec, loadShellEnv),
+                false
+            );
+        });
+
+        it("is true (advisory) when the probe fails for another reason", async () => {
+            const exec = (async () => {
+                throw Object.assign(new Error("permission denied"), {
+                    code: "EACCES",
+                });
+            }) as unknown as typeof cancellableExecFile;
+            assert.strictEqual(await isHostCliOnPath(exec, loadShellEnv), true);
+        });
+
+        it("probes with the profile PATH on POSIX", async function () {
+            if (process.platform === "win32") {
+                this.skip();
+            }
+            let seenEnv: Record<string, string> | undefined;
+            const exec = (async (
+                _cmd: string,
+                _args: string[],
+                opts: {env?: Record<string, string>}
+            ) => {
+                seenEnv = opts.env;
+                return {stdout: "1.0.0", stderr: ""};
+            }) as unknown as typeof cancellableExecFile;
+            assert.strictEqual(await isHostCliOnPath(exec, loadShellEnv), true);
+            assert.strictEqual(seenEnv?.PATH, "/usr/bin");
+        });
+
+        it("is true (advisory) when the shell profile fails to resolve", async function () {
+            // Windows never loads shell-env, so this branch is POSIX-only.
+            if (process.platform === "win32") {
+                this.skip();
+            }
+            const exec = (async () => ({
+                stdout: "1.0.0",
+                stderr: "",
+            })) as unknown as typeof cancellableExecFile;
+            const failingShellEnv = async () => async () => {
+                throw new Error("profile blew up");
+            };
+            assert.strictEqual(
+                await isHostCliOnPath(exec, failingShellEnv),
+                true
+            );
+        });
+    });
 });