Improved shell PATH hydration with candidate iteration, launchctl fallback, and PATH merging

Adapted from upstream t3code #1799. Adds listLoginShellCandidates, mergePathEntries,
and readPathFromLaunchctl to @bigcode/shared/shell. Updated fixPath() in os-jank to
iterate over shell candidates with per-shell error logging, merge shell PATH with
inherited PATH (shell entries first, deduped), and fall back to launchctl on macOS
when all shell reads fail.

Author: youpele52

apps/server/src/utils/os-jank.test.ts

@@ -36,4 +36,81 @@ describe("fixPath", () => {
     expect(readPath).not.toHaveBeenCalled();
     expect(env.PATH).toBe("C:\\Windows\\System32");
   });
+
+  it("merges shell PATH with env PATH, shell entries first", () => {
+    const env: NodeJS.ProcessEnv = {
+      SHELL: "/bin/zsh",
+      PATH: "/usr/bin:/usr/local/bin",
+    };
+    const readPath = vi.fn(() => "/opt/homebrew/bin:/usr/bin");
+
+    fixPath({
+      env,
+      platform: "darwin",
+      readPath,
+    });
+
+    expect(env.PATH).toBe("/opt/homebrew/bin:/usr/bin:/usr/local/bin");
+  });
+
+  it("tries multiple shell candidates before falling back to launchctl", () => {
+    const env: NodeJS.ProcessEnv = {
+      PATH: "/usr/bin",
+    };
+    const readPath = vi.fn(() => {
+      throw new Error("shell not found");
+    });
+    const readLaunchctlPath = vi.fn(() => "/usr/bin:/bin:/usr/sbin:/sbin");
+    const warnings: string[] = [];
+
+    fixPath({
+      env,
+      platform: "darwin",
+      readPath,
+      readLaunchctlPath,
+      logWarning: (msg) => warnings.push(msg),
+    });
+
+    expect(readLaunchctlPath).toHaveBeenCalled();
+    expect(warnings.length).toBeGreaterThan(0);
+  });
+
+  it("falls back to launchctl on macOS when all shell reads fail", () => {
+    const env: NodeJS.ProcessEnv = {
+      PATH: "/usr/bin",
+    };
+    const readPath = vi.fn(() => {
+      throw new Error("shell not found");
+    });
+    const readLaunchctlPath = vi.fn(() => "/usr/bin:/bin:/usr/sbin:/sbin");
+
+    fixPath({
+      env,
+      platform: "darwin",
+      readPath,
+      readLaunchctlPath,
+    });
+
+    expect(readLaunchctlPath).toHaveBeenCalled();
+    expect(env.PATH).toBe("/usr/bin:/bin:/usr/sbin:/sbin");
+  });
+
+  it("does not attempt launchctl on linux", () => {
+    const env: NodeJS.ProcessEnv = {
+      PATH: "/usr/bin",
+    };
+    const readPath = vi.fn(() => {
+      throw new Error("shell not found");
+    });
+    const readLaunchctlPath = vi.fn(() => "/launchctl/path");
+
+    fixPath({
+      env,
+      platform: "linux",
+      readPath,
+      readLaunchctlPath,
+    });
+
+    expect(readLaunchctlPath).not.toHaveBeenCalled();
+  });
 });

apps/server/src/utils/os-jank.ts

@@ -1,28 +1,53 @@
 import * as OS from "node:os";
 import { Effect, Path } from "effect";
-import { readPathFromLoginShell, resolveLoginShell } from "@bigcode/shared/shell";
+import {
+  listLoginShellCandidates,
+  mergePathEntries,
+  readPathFromLaunchctl,
+  readPathFromLoginShell,
+} from "@bigcode/shared/shell";
 
 export function fixPath(
   options: {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     readPath?: typeof readPathFromLoginShell;
+    readLaunchctlPath?: typeof readPathFromLaunchctl;
+    logWarning?: (message: string) => void;
   } = {},
 ): void {
   const platform = options.platform ?? process.platform;
   if (platform !== "darwin" && platform !== "linux") return;
 
   const env = options.env ?? process.env;
+  const warn = options.logWarning ?? (() => {});
+  const candidates = listLoginShellCandidates(platform, env.SHELL);
 
-  try {
-    const shell = resolveLoginShell(platform, env.SHELL);
-    if (!shell) return;
-    const result = (options.readPath ?? readPathFromLoginShell)(shell);
-    if (result) {
-      env.PATH = result;
+  for (const shell of candidates) {
+    try {
+      const shellPath = (options.readPath ?? readPathFromLoginShell)(shell);
+      if (shellPath) {
+        env.PATH = mergePathEntries(shellPath, env.PATH, platform);
+        return;
+      }
+    } catch (error) {
+      warn(
+        `Failed to read PATH from login shell '${shell}': ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const launchctlPath = (options.readLaunchctlPath ?? readPathFromLaunchctl)();
+      if (launchctlPath) {
+        env.PATH = mergePathEntries(launchctlPath, env.PATH, platform);
+      }
+    } catch (error) {
+      warn(
+        `Failed to read PATH from launchctl: ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
-  } catch {
-    // Silently ignore — keep default PATH
   }
 }
 

packages/shared/src/shell.test.ts

@@ -2,7 +2,10 @@ import { describe, expect, it, vi } from "vitest";
 
 import {
   extractPathFromShellOutput,
+  listLoginShellCandidates,
+  mergePathEntries,
   readEnvironmentFromLoginShell,
+  readPathFromLaunchctl,
   readPathFromLoginShell,
 } from "./shell";
 
@@ -126,3 +129,75 @@ describe("readEnvironmentFromLoginShell", () => {
     });
   });
 });
+
+describe("listLoginShellCandidates", () => {
+  it("returns envShell first, then userShell, then platform defaults (macOS)", () => {
+    const candidates = listLoginShellCandidates("darwin", "/opt/homebrew/bin/fish", "/bin/bash");
+    expect(candidates).toEqual(["/opt/homebrew/bin/fish", "/bin/bash", "/bin/zsh"]);
+  });
+
+  it("deduplicates entries", () => {
+    const candidates = listLoginShellCandidates("darwin", "/bin/zsh", "/bin/zsh");
+    expect(candidates).toEqual(["/bin/zsh", "/bin/bash"]);
+  });
+
+  it("returns platform defaults when no shells are specified (macOS)", () => {
+    const candidates = listLoginShellCandidates("darwin");
+    expect(candidates).toEqual(["/bin/zsh", "/bin/bash"]);
+  });
+
+  it("returns platform defaults when no shells are specified (linux)", () => {
+    const candidates = listLoginShellCandidates("linux");
+    expect(candidates).toEqual(["/bin/bash", "/bin/sh"]);
+  });
+
+  it("returns an empty array for unsupported platforms", () => {
+    const candidates = listLoginShellCandidates("win32");
+    expect(candidates).toEqual([]);
+  });
+});
+
+describe("mergePathEntries", () => {
+  it("places shell entries before env entries", () => {
+    expect(mergePathEntries("/a:/b", "/b:/c", "darwin")).toBe("/a:/b:/c");
+  });
+
+  it("deduplicates entries preserving first occurrence", () => {
+    expect(
+      mergePathEntries("/usr/bin:/opt/homebrew/bin", "/opt/homebrew/bin:/usr/local/bin", "darwin"),
+    ).toBe("/usr/bin:/opt/homebrew/bin:/usr/local/bin");
+  });
+
+  it("returns shell entries alone when envPath is undefined", () => {
+    expect(mergePathEntries("/usr/bin:/opt/homebrew/bin", undefined, "darwin")).toBe(
+      "/usr/bin:/opt/homebrew/bin",
+    );
+  });
+
+  it("filters empty segments", () => {
+    expect(mergePathEntries("/a::/b", "/c", "linux")).toBe("/a:/b:/c");
+  });
+});
+
+describe("readPathFromLaunchctl", () => {
+  it("returns the PATH value from launchctl on macOS", () => {
+    const execCommand = vi.fn(() => "/usr/bin:/bin:/usr/sbin:/sbin\n");
+    expect(readPathFromLaunchctl(execCommand as never)).toBe("/usr/bin:/bin:/usr/sbin:/sbin");
+    expect(execCommand).toHaveBeenCalledWith("launchctl getenv PATH", {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+  });
+
+  it("returns undefined when launchctl returns empty", () => {
+    const execCommand = vi.fn(() => "   \n");
+    expect(readPathFromLaunchctl(execCommand as never)).toBeUndefined();
+  });
+
+  it("returns undefined when launchctl throws", () => {
+    const execCommand = vi.fn(() => {
+      throw new Error("launchctl not available");
+    });
+    expect(readPathFromLaunchctl(execCommand as never)).toBeUndefined();
+  });
+});

packages/shared/src/shell.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 
 const PATH_CAPTURE_START = "__T3CODE_PATH_START__";
 const PATH_CAPTURE_END = "__T3CODE_PATH_END__";
@@ -10,6 +10,8 @@ type ExecFileSyncLike = (
   options: { encoding: "utf8"; timeout: number },
 ) => string;
 
+type ExecSyncLike = (command: string, options: { encoding: "utf8"; timeout: number }) => string;
+
 export function resolveLoginShell(
   platform: NodeJS.Platform,
   shell: string | undefined,
@@ -30,6 +32,67 @@ export function resolveLoginShell(
   return undefined;
 }
 
+export function listLoginShellCandidates(
+  platform: NodeJS.Platform,
+  envShell?: string | undefined,
+  userShell?: string | undefined,
+): ReadonlyArray<string> {
+  const candidates: string[] = [];
+
+  const add = (shell: string | undefined) => {
+    const trimmed = shell?.trim();
+    if (trimmed && !candidates.includes(trimmed)) {
+      candidates.push(trimmed);
+    }
+  };
+
+  add(envShell);
+  add(userShell);
+
+  if (platform === "darwin") {
+    add("/bin/zsh");
+    add("/bin/bash");
+  } else if (platform === "linux") {
+    add("/bin/bash");
+    add("/bin/sh");
+  }
+
+  return candidates;
+}
+
+export function mergePathEntries(
+  shellPath: string,
+  envPath: string | undefined,
+  _platform: NodeJS.Platform,
+): string {
+  const shellEntries = shellPath.split(":").filter((e) => e.length > 0);
+  const envEntries = envPath ? envPath.split(":").filter((e) => e.length > 0) : [];
+
+  const seen = new Set<string>();
+  const merged: string[] = [];
+
+  for (const entry of [...shellEntries, ...envEntries]) {
+    if (!seen.has(entry)) {
+      seen.add(entry);
+      merged.push(entry);
+    }
+  }
+
+  return merged.join(":");
+}
+
+export function readPathFromLaunchctl(execCommand: ExecSyncLike = execSync): string | undefined {
+  try {
+    const result = execCommand("launchctl getenv PATH", {
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
+    return result.length > 0 ? result : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function extractPathFromShellOutput(output: string): string | null {
   const startIndex = output.indexOf(PATH_CAPTURE_START);
   if (startIndex === -1) return null;