feat(setup): install bash completions as fallback for unsupported shells (#282)

## Problem

During `sentry setup`, if the user's shell isn't directly supported
(e.g. xonsh, nushell, tcsh), completions are silently skipped or a \"not
supported\" message is shown. Most systems have bash installed, and many
custom shells can load bash completions as a compatibility layer.

## Solution

When `handleCompletions` encounters an unsupported shell (not
bash/zsh/fish/sh/ash):
- If `bash` is found on `PATH` → install bash completions and inform the
user
- If `bash` is not found → keep the existing \"Not supported\" message

Example output for an xonsh user:
```
Completions: Your shell (unknown) is not directly supported
      Installed bash completions as a fallback: ~/.local/share/bash-completion/completions/sentry
```

`sh`/`ash` continue to silently skip completions (no message), as they
are minimal POSIX shells where completions aren't expected.

## Changes

- `src/lib/shell.ts` — `isBashAvailable()` using `Bun.which("bash")`
- `src/commands/cli/setup.ts` — `tryBashCompletionFallback()` helper;
updated `handleCompletions()`
- Tests updated/added for the fallback path, the sh silent-skip, and
`isBashAvailable`

Author: BYK

src/commands/cli/setup.ts

@@ -20,6 +20,7 @@ import {
   addToPath,
   detectShell,
   getPathCommand,
+  isBashAvailable,
   isInPath,
   type ShellInfo,
 } from "../../lib/shell.js";
@@ -117,31 +118,82 @@ async function handlePathModification(
   }
 }
 
+/**
+ * Attempt to install bash completions as a fallback for unsupported shells.
+ *
+ * Many custom shells (xonsh, nushell, etc.) can load bash completions,
+ * so this is a useful fallback when the user's shell isn't directly supported.
+ *
+ * @param pathEnv - The PATH to search for bash, forwarded from the process env.
+ */
+async function tryBashCompletionFallback(
+  homeDir: string,
+  xdgDataHome: string | undefined,
+  pathEnv: string | undefined
+): Promise<string | null> {
+  if (!isBashAvailable(pathEnv)) {
+    return null;
+  }
+
+  const fallback = await installCompletions("bash", homeDir, xdgDataHome);
+  if (!fallback) {
+    // Defensive: installCompletions returns null only if the shell type has no
+    // completion script or path configured. "bash" is always supported, but
+    // we guard here in case that changes in future.
+    return null;
+  }
+  const action = fallback.created ? "Installed" : "Updated";
+  return `      ${action} bash completions as a fallback: ${fallback.path}`;
+}
+
 /**
  * Handle shell completion installation.
+ *
+ * For unsupported shells (xonsh, nushell, etc.), falls back to installing
+ * bash completions if bash is available on the system. Uses the provided
+ * PATH env to check for bash so the call is testable without side effects.
  */
 async function handleCompletions(
   shell: ShellInfo,
   homeDir: string,
   xdgDataHome: string | undefined,
-  log: Logger
-): Promise<void> {
+  pathEnv: string | undefined
+): Promise<string[]> {
   const location = await installCompletions(shell.type, homeDir, xdgDataHome);
 
   if (location) {
     const action = location.created ? "Installed to" : "Updated";
-    log(`Completions: ${action} ${location.path}`);
+    const lines = [`Completions: ${action} ${location.path}`];
 
     // Zsh may need fpath hint
     if (shell.type === "zsh") {
       const completionDir = dirname(location.path);
-      log(
+      lines.push(
         `      You may need to add to .zshrc: fpath=(${completionDir} $fpath)`
       );
     }
-  } else if (shell.type !== "sh" && shell.type !== "ash") {
-    log(`Completions: Not supported for ${shell.type} shell`);
+    return lines;
+  }
+
+  // sh/ash are minimal POSIX shells — completions aren't expected
+  if (shell.type === "sh" || shell.type === "ash") {
+    return [];
   }
+
+  const fallbackMsg = await tryBashCompletionFallback(
+    homeDir,
+    xdgDataHome,
+    pathEnv
+  );
+
+  if (fallbackMsg) {
+    return [
+      `Completions: Your shell (${shell.type}) is not directly supported`,
+      fallbackMsg,
+    ];
+  }
+
+  return [`Completions: Not supported for ${shell.type} shell`];
 }
 
 /**
@@ -284,7 +336,15 @@ export const setupCommand = buildCommand({
 
     // 3. Install shell completions
     if (!flags["no-completions"]) {
-      await handleCompletions(shell, homeDir, process.env.XDG_DATA_HOME, log);
+      const completionLines = await handleCompletions(
+        shell,
+        homeDir,
+        process.env.XDG_DATA_HOME,
+        process.env.PATH
+      );
+      for (const line of completionLines) {
+        log(line);
+      }
     }
 
     // 4. Install agent skills (auto-detected, silent when no agent found)

src/lib/shell.ts

@@ -266,3 +266,17 @@ export async function addToGitHubPath(
     return false;
   }
 }
+
+/**
+ * Check if bash is available on the system.
+ *
+ * Uses `Bun.which` to search PATH for a bash executable.
+ * Useful as a fallback for unsupported shells — many custom shells
+ * (xonsh, nushell, etc.) support bash completions.
+ *
+ * @param pathEnv - Override PATH for testing. Defaults to the process PATH.
+ */
+export function isBashAvailable(pathEnv?: string): boolean {
+  const opts = pathEnv !== undefined ? { PATH: pathEnv } : undefined;
+  return Bun.which("bash", opts) !== null;
+}

test/commands/cli/setup.test.ts

@@ -297,13 +297,65 @@ describe("sentry cli setup", () => {
     expect(combined).toContain("GITHUB_PATH");
   });
 
-  test("shows unsupported message for sh shell completions", async () => {
+  test("falls back to bash completions for unsupported shell when bash is available", async () => {
+    // Create a fake bash executable in testDir/bin so isBashAvailable() returns
+    // true with PATH pointing there — no dependency on the host system.
+    const binDir = join(testDir, "bin");
+    mkdirSync(binDir, { recursive: true });
+    const { chmodSync, writeFileSync: wf } = await import("node:fs");
+    const fakeBash = join(binDir, "bash");
+    wf(fakeBash, "#!/bin/sh\necho fake-bash");
+    chmodSync(fakeBash, 0o755);
+
+    const { context, output } = createMockContext({
+      homeDir: testDir,
+      execPath: join(testDir, "bin", "sentry"),
+      env: {
+        PATH: binDir,
+        SHELL: "/bin/xonsh",
+      },
+    });
+
+    await run(
+      app,
+      ["cli", "setup", "--no-modify-path", "--no-agent-skills"],
+      context
+    );
+
+    const combined = output.join("");
+    expect(combined).toContain("not directly supported");
+    expect(combined).toContain("bash completions as a fallback");
+    expect(combined).toContain("bash-completion");
+  });
+
+  test("shows unsupported message for unknown shell when bash is not in PATH", async () => {
+    const { context, output } = createMockContext({
+      homeDir: testDir,
+      execPath: join(testDir, "bin", "sentry"),
+      env: {
+        // Empty PATH so isBashAvailable() returns false
+        PATH: "",
+        SHELL: "/bin/xonsh",
+      },
+    });
+
+    await run(
+      app,
+      ["cli", "setup", "--no-modify-path", "--no-agent-skills"],
+      context
+    );
+
+    const combined = output.join("");
+    expect(combined).toContain("Not supported for unknown shell");
+  });
+
+  test("silently skips completions for sh shell", async () => {
     const { context, output } = createMockContext({
       homeDir: testDir,
       execPath: join(testDir, "bin", "sentry"),
       env: {
         PATH: `/usr/bin:${join(testDir, "bin")}:/bin`,
-        SHELL: "/bin/tcsh",
+        SHELL: "/bin/sh",
       },
     });
 
@@ -314,7 +366,8 @@ describe("sentry cli setup", () => {
     );
 
     const combined = output.join("");
-    expect(combined).toContain("Not supported for");
+    // sh/ash shells silently skip completions — no message at all
+    expect(combined).not.toContain("Completions:");
   });
 
   test("supports kebab-case flags", async () => {

test/lib/shell.test.ts

@@ -7,13 +7,14 @@
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import {
   addToGitHubPath,
   addToPath,
   detectShell,
   findExistingConfigFile,
   getConfigCandidates,
+  isBashAvailable,
 } from "../../src/lib/shell.js";
 
 describe("shell utilities", () => {
@@ -257,3 +258,23 @@ describe("shell utilities", () => {
     });
   });
 });
+
+describe("isBashAvailable", () => {
+  test("returns true when bash is in PATH", () => {
+    // Point PATH at the directory containing bash
+    const bashPath = Bun.which("bash");
+    if (!bashPath) {
+      // Skip if bash truly isn't on this system
+      return;
+    }
+    expect(isBashAvailable(dirname(bashPath))).toBe(true);
+  });
+
+  test("returns false when PATH has no bash", () => {
+    expect(isBashAvailable("/nonexistent")).toBe(false);
+  });
+
+  test("returns false when PATH is empty", () => {
+    expect(isBashAvailable("")).toBe(false);
+  });
+});