fix(setup): auto-configure zsh fpath for shell completions (#509)

## Summary

Zsh completions installed by `sentry cli setup` don't work out of the
box because `~/.local/share/zsh/site-functions` isn't in zsh's default
`fpath`. The setup previously only printed a hint asking users to
manually edit `.zshrc`, while PATH was auto-configured — inconsistent
and easy to miss.

Now setup automatically appends `fpath=("dir" $fpath)` to `.zshrc`,
mirroring how `addToPath()` already works. Also runs on upgrades so
existing users get their fpath fixed on the next `sentry cli setup`.

## Changes

- Add `addToFpath()` and `getFpathCommand()` to `shell.ts` (mirrors
`addToPath`/`getPathCommand`)
- Extract `handleZshFpath()` in `setup.ts` to keep complexity in check
- Replace passive fpath hint with active `.zshrc` modification
- Run fpath check even on completion file updates (one-time migration
for existing installs)

## Test Plan

- [x] `bun test test/lib/shell.test.ts` — 23 tests pass (5 new for
`addToFpath`)
- [x] `bun test test/commands/cli/setup.test.ts` — 29 tests pass
(updated zsh test + new idempotency test)
- [x] `bun run typecheck` — clean
- [x] `bun run lint` — clean (only pre-existing warning in markdown.ts)
- Manual: run `sentry cli setup` on zsh, verify `.zshrc` gets fpath
line, restart shell, confirm tab completion works

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: betegon

src/commands/cli/setup.ts

@@ -30,9 +30,11 @@ import {
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { logger } from "../../lib/logger.js";
 import {
+  addToFpath,
   addToGitHubPath,
   addToPath,
   detectShell,
+  getFpathCommand,
   getPathCommand,
   isBashAvailable,
   isInPath,
@@ -180,6 +182,37 @@ async function tryBashCompletionFallback(
   return await installCompletions("bash", homeDir, xdgDataHome);
 }
 
+/**
+ * Ensure the zsh completion directory is in fpath.
+ *
+ * Runs even on updates so existing installs get fpath configured (one-time migration).
+ * Returns status messages for the user.
+ */
+async function handleZshFpath(
+  shell: ShellInfo,
+  completionDir: string,
+  isNewInstall: boolean
+): Promise<string[]> {
+  const lines: string[] = [];
+
+  if (shell.configFile) {
+    const result = await addToFpath(shell.configFile, completionDir);
+    if (result.modified) {
+      lines.push(`Completions: ${result.message}`);
+      lines.push(`      Restart your shell or run: source ${shell.configFile}`);
+    } else if (result.manualCommand) {
+      lines.push(`Completions: ${result.message}`);
+      lines.push(
+        `      Add manually to ${shell.configFile}: ${result.manualCommand}`
+      );
+    }
+  } else if (isNewInstall) {
+    lines.push(`      Add to your .zshrc: ${getFpathCommand(completionDir)}`);
+  }
+
+  return lines;
+}
+
 /**
  * Handle shell completion installation.
  *
@@ -200,20 +233,19 @@ async function handleCompletions(
   const location = await installCompletions(shell.type, homeDir, xdgDataHome);
 
   if (location) {
-    // Silently updated — no need to tell the user on every upgrade
-    if (!location.created) {
-      return [];
-    }
-
-    const lines = [`Completions: Installed to ${location.path}`];
+    const lines: string[] = [];
 
-    // Zsh may need fpath hint
     if (shell.type === "zsh") {
       const completionDir = dirname(location.path);
       lines.push(
-        `      You may need to add to .zshrc: fpath=(${completionDir} $fpath)`
+        ...(await handleZshFpath(shell, completionDir, location.created))
       );
     }
+
+    if (location.created) {
+      lines.unshift(`Completions: Installed to ${location.path}`);
+    }
+
     return lines;
   }
 

src/lib/shell.ts

@@ -171,79 +171,115 @@ export function isInPath(
 }
 
 /**
- * Add a directory to PATH in a shell config file.
+ * Append a shell config line to a config file with idempotency.
  *
- * @param configFile - Path to the config file
- * @param directory - Directory to add to PATH
- * @param shellType - The shell type (for correct syntax)
- * @returns Result of the modification attempt
+ * Shared implementation for `addToPath` and `addToFpath`. Handles file
+ * creation, duplicate detection, newline-aware appending, and error fallback.
+ *
+ * @param configFile - Path to the shell config file
+ * @param directory - Directory being configured (used for duplicate check)
+ * @param command - The full shell command to append (e.g. `export PATH="..."`)
+ * @param label - Human-readable label for messages (e.g. "PATH", "fpath")
  */
-export async function addToPath(
+async function addToShellConfig(
   configFile: string,
   directory: string,
-  shellType: ShellType
+  command: string,
+  label: string
 ): Promise<PathModificationResult> {
-  const pathCommand = getPathCommand(shellType, directory);
-
-  // Read current content
   const file = Bun.file(configFile);
   const exists = await file.exists();
 
   if (!exists) {
-    // Create the file with the PATH command
     try {
-      await Bun.write(configFile, `# sentry\n${pathCommand}\n`);
+      await Bun.write(configFile, `# sentry\n${command}\n`);
       return {
         modified: true,
         configFile,
-        message: `Created ${configFile} with PATH configuration`,
+        message: `Created ${configFile} with ${label} configuration`,
         manualCommand: null,
       };
     } catch {
       return {
         modified: false,
         configFile: null,
         message: `Could not create ${configFile}`,
-        manualCommand: pathCommand,
+        manualCommand: command,
       };
     }
   }
 
   const content = await file.text();
 
-  // Check if already configured
-  if (content.includes(pathCommand) || content.includes(`"${directory}"`)) {
+  if (content.includes(command) || content.includes(`"${directory}"`)) {
     return {
       modified: false,
       configFile,
-      message: `PATH already configured in ${configFile}`,
+      message: `${label} already configured in ${configFile}`,
       manualCommand: null,
     };
   }
 
-  // Append to file
   try {
     const newContent = content.endsWith("\n")
-      ? `${content}\n# sentry\n${pathCommand}\n`
-      : `${content}\n\n# sentry\n${pathCommand}\n`;
+      ? `${content}\n# sentry\n${command}\n`
+      : `${content}\n\n# sentry\n${command}\n`;
 
     await Bun.write(configFile, newContent);
     return {
       modified: true,
       configFile,
-      message: `Added sentry to PATH in ${configFile}`,
+      message: `Added sentry ${label} in ${configFile}`,
       manualCommand: null,
     };
   } catch {
     return {
       modified: false,
       configFile: null,
       message: `Could not write to ${configFile}`,
-      manualCommand: pathCommand,
+      manualCommand: command,
     };
   }
 }
 
+export function addToPath(
+  configFile: string,
+  directory: string,
+  shellType: ShellType
+): Promise<PathModificationResult> {
+  return addToShellConfig(
+    configFile,
+    directory,
+    getPathCommand(shellType, directory),
+    "PATH"
+  );
+}
+
+/**
+ * Generate the fpath command for zsh completion directory.
+ */
+export function getFpathCommand(directory: string): string {
+  return `fpath=("${directory}" $fpath)`;
+}
+
+/**
+ * Add a directory to zsh's fpath in a shell config file.
+ *
+ * @param configFile - Path to the zsh config file (e.g. ~/.zshrc)
+ * @param directory - Directory to add to fpath
+ */
+export function addToFpath(
+  configFile: string,
+  directory: string
+): Promise<PathModificationResult> {
+  return addToShellConfig(
+    configFile,
+    directory,
+    getFpathCommand(directory),
+    "fpath"
+  );
+}
+
 /**
  * Add to GitHub Actions PATH if running in CI.
  */

test/commands/cli/setup.test.ts

@@ -291,7 +291,46 @@ describe("sentry cli setup", () => {
     expect(getOutput()).toContain("Completions:");
   });
 
-  test("shows zsh fpath hint for zsh completions", async () => {
+  test("adds fpath to .zshrc for zsh completions", async () => {
+    const zshrc = join(testDir, ".zshrc");
+    writeFileSync(zshrc, "# existing zshrc\n");
+
+    const { context, getOutput, restore } = createMockContext({
+      homeDir: testDir,
+      execPath: join(testDir, "bin", "sentry"),
+      env: {
+        PATH: `/usr/bin:${join(testDir, "bin")}:/bin`,
+        SHELL: "/bin/zsh",
+      },
+    });
+    restoreStderr = restore;
+
+    await run(
+      app,
+      ["cli", "setup", "--no-modify-path", "--no-agent-skills"],
+      context
+    );
+
+    expect(getOutput()).toContain("fpath");
+    expect(getOutput()).toContain("Completions:");
+
+    // Verify .zshrc was actually modified
+    const content = await Bun.file(zshrc).text();
+    expect(content).toContain("fpath=");
+    expect(content).toContain("site-functions");
+  });
+
+  test("skips fpath modification when already configured in .zshrc", async () => {
+    const zshrc = join(testDir, ".zshrc");
+    const completionDir = join(
+      testDir,
+      ".local",
+      "share",
+      "zsh",
+      "site-functions"
+    );
+    writeFileSync(zshrc, `# existing\nfpath=("${completionDir}" $fpath)\n`);
+
     const { context, getOutput, restore } = createMockContext({
       homeDir: testDir,
       execPath: join(testDir, "bin", "sentry"),
@@ -308,7 +347,10 @@ describe("sentry cli setup", () => {
       context
     );
 
-    expect(getOutput()).toContain("fpath=");
+    // Should still show "Installed to" but not "Added ... to fpath"
+    const output = getOutput();
+    expect(output).toContain("Completions: Installed to");
+    expect(output).not.toContain("Added sentry fpath in");
   });
 
   test("handles GitHub Actions PATH when GITHUB_ACTIONS is set", async () => {

test/lib/shell.test.ts

@@ -9,6 +9,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import {
+  addToFpath,
   addToGitHubPath,
   addToPath,
   detectShell,
@@ -193,6 +194,103 @@ describe("shell utilities", () => {
     });
   });
 
+  describe("addToFpath", () => {
+    let testDir: string;
+
+    beforeEach(() => {
+      testDir = join(
+        "/tmp",
+        `shell-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+      );
+      mkdirSync(testDir, { recursive: true });
+    });
+
+    afterEach(() => {
+      rmSync(testDir, { recursive: true, force: true });
+    });
+
+    test("creates config file if it doesn't exist", async () => {
+      const configFile = join(testDir, ".zshrc");
+      const result = await addToFpath(
+        configFile,
+        "/home/user/.local/share/zsh/site-functions"
+      );
+
+      expect(result.modified).toBe(true);
+      expect(result.configFile).toBe(configFile);
+
+      const content = await Bun.file(configFile).text();
+      expect(content).toContain(
+        'fpath=("/home/user/.local/share/zsh/site-functions" $fpath)'
+      );
+    });
+
+    test("appends to existing config file", async () => {
+      const configFile = join(testDir, ".zshrc");
+      writeFileSync(configFile, "# existing content\n");
+
+      const result = await addToFpath(
+        configFile,
+        "/home/user/.local/share/zsh/site-functions"
+      );
+
+      expect(result.modified).toBe(true);
+
+      const content = await Bun.file(configFile).text();
+      expect(content).toContain("# existing content");
+      expect(content).toContain("# sentry");
+      expect(content).toContain(
+        'fpath=("/home/user/.local/share/zsh/site-functions" $fpath)'
+      );
+    });
+
+    test("skips if already configured", async () => {
+      const configFile = join(testDir, ".zshrc");
+      writeFileSync(
+        configFile,
+        '# sentry\nfpath=("/home/user/.local/share/zsh/site-functions" $fpath)\n'
+      );
+
+      const result = await addToFpath(
+        configFile,
+        "/home/user/.local/share/zsh/site-functions"
+      );
+
+      expect(result.modified).toBe(false);
+      expect(result.message).toContain("already configured");
+    });
+
+    test("appends newline separator when file doesn't end with newline", async () => {
+      const configFile = join(testDir, ".zshrc");
+      writeFileSync(configFile, "# existing content without newline");
+
+      const result = await addToFpath(
+        configFile,
+        "/home/user/.local/share/zsh/site-functions"
+      );
+
+      expect(result.modified).toBe(true);
+
+      const content = await Bun.file(configFile).text();
+      expect(content).toContain(
+        "# existing content without newline\n\n# sentry\n"
+      );
+    });
+
+    test("returns manualCommand when config file cannot be created", async () => {
+      const configFile = "/dev/null/impossible/path/.zshrc";
+      const result = await addToFpath(
+        configFile,
+        "/home/user/.local/share/zsh/site-functions"
+      );
+
+      expect(result.modified).toBe(false);
+      expect(result.manualCommand).toBe(
+        'fpath=("/home/user/.local/share/zsh/site-functions" $fpath)'
+      );
+    });
+  });
+
   describe("addToGitHubPath", () => {
     let testDir: string;