Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.7 KB
Raw Blame
/**
 * Shell selection for command sessions.
 *
 * Commands run via `bash -lc <cmd>` wherever a bash exists. Neither platform guarantees one
 * — Windows has none by default, and a POSIX box can be launched with a PATH that has none —
 * so the resolver picks the best available shell once per process:
 *
 * 1. `ADELIE_SHELL` (explicit executable name or path) always wins, on every platform;
 *    the argument shape is inferred from its basename (see below).
 * 2. Otherwise, non-Windows uses `bash -lc` — but only after confirming a `bash` exists.
 *    A GUI-launched app inherits the desktop session's PATH, not a login shell's, and a
 *    trimmed session PATH (or a distribution that simply does not install bash) leaves
 *    `spawn("bash")` dying with ENOENT before the command runs at all. So: `bash` on
 *    PATH, then the usual absolute locations, then `$SHELL` when it is some other POSIX
 *    shell, then `sh`. The probe is a PATH walk, not a subprocess.
 * 3. On Windows, probe PATH for `bash` (a full Git for Windows install — best compatibility
 *    with the skill/prompt ecosystem, which is written for a POSIX shell). A `bash` that
 *    resolves into the Windows system directory is ignored: that is the WSL launcher, which
 *    runs commands inside a Linux distro with a different filesystem view (and fails outright
 *    when no distro is configured).
 * 4. Then `ADELIE_BUNDLED_SHELL` (the pre-rename `PENGUIN_BUNDLED_SHELL` is still read — the
 *    launcher shim that sets it ships with the installers, so its writer is outside this
 *    repository) — the MinGit bash the Windows package ships (see the
 *    release workflow), advertised by the launcher shims as an absolute path. It comes
 *    *after* the PATH probe on purpose: a user's own Git for Windows carries the full MSYS
 *    userland (curl, tar, less, perl …), while MinGit carries ~60 core tools, so when both
 *    exist theirs is the better shell. This step is what makes the shell deterministic —
 *    without it, the same Agent and the same Skill behave differently on two Windows
 *    machines depending on what happens to be installed.
 * 5. Only then `pwsh` (PowerShell 7+), and finally `powershell` (Windows PowerShell 5.1,
 *    always present). These remain reachable for npm installs, which ship no bundle.
 *
 * Argument shapes by basename (also applied to `ADELIE_SHELL` values):
 * - `pwsh` / `powershell` -> `-NoLogo -NoProfile -Command <cmd>`
 * - `cmd`                 -> `/d /s /c <cmd>`
 * - anything else         -> `-lc <cmd>` (bash/zsh/sh-style login shell)
 *
 * `-lc` matters for the bundled shell: as a login shell it sources MinGit's `etc/profile`,
 * which defaults to `MSYS2_PATH_TYPE=inherit` and yields
 * `/mingw64/bin:/usr/local/bin:/usr/bin:/bin:<inherited Windows PATH>` — the bundled coreutils
 * and git first, the inherited Windows PATH still behind them, so System32's `curl.exe` and
 * `tar.exe` (which MinGit does not carry) keep resolving. Nothing has to plumb PATH by hand.
 *
 * The resolved shell's name is surfaced to the model via the session environment (the
 * `Shell:` line in the system prompt), so it knows which syntax the exec tool speaks.
 */
import { spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import path from "node:path";
import { boundaryEnv } from "../../../state/boundary-env.js";

/** A resolved shell invocation: `spawn(command, [...args, cmd])` runs `cmd` in that shell. */
export interface ShellInvocation {
  /** Executable name or absolute path handed to spawn(). */
  command: string;
  /** Fixed argument prefix placed before the command string. */
  args: string[];
  /** Short lowercase name (basename without extension), shown to the model (e.g. "bash", "pwsh"). */
  name: string;
}

/** Injection points for unit tests; production callers use the defaults. */
export interface ResolveShellOptions {
  platform?: NodeJS.Platform;
  env?: NodeJS.ProcessEnv;
  /** Returns the PATH resolutions of an executable name, best match first ([] when not found). */
  whichAll?: (cmd: string) => string[];
  /** The Windows system root (to recognize the WSL bash launcher); default `env.SystemRoot` or C:\Windows. */
  systemRoot?: string;
  /** Existence probe for the bundled shell path (injected in tests); default `fs.existsSync`. */
  exists?: (filePath: string) => boolean;
}

/** Basename without a trailing .exe/.cmd/.bat/.ps1 extension, lowercased ("C:\...\pwsh.EXE" -> "pwsh"). */
function shellBasename(command: string): string {
  // path.win32 handles both separators, so ADELIE_SHELL=/usr/bin/zsh still yields "zsh".
  return path.win32
    .basename(command)
    .replace(/\.(exe|cmd|bat|ps1)$/i, "")
    .toLowerCase();
}

/**
 * Absolute POSIX locations to try when no `bash` is on PATH. A GUI launch can inherit a
 * PATH that omits the directory bash actually lives in, while the binary is right there.
 */
const POSIX_BASH_PATHS = [
  "/bin/bash",
  "/usr/bin/bash",
  "/usr/local/bin/bash",
  "/opt/homebrew/bin/bash",
];

/** POSIX shells worth falling back to, in the order they are tried, once bash is ruled out. */
const POSIX_FALLBACK_SHELLS = ["sh", "/bin/sh", "/usr/bin/sh"];

/**
 * Basenames `$SHELL` is allowed to name. It carries the login shell of whatever account the
 * server runs as, and on a service account that field is routinely `/usr/sbin/nologin` or
 * `/bin/false` — both exist, neither runs a command, and `-lc` would turn every command into
 * a silent non-zero exit. Membership here means "accepts `-lc <cmd>`"; anything else falls
 * through to `sh`, which does.
 */
const POSIX_LOGIN_SHELLS = new Set([
  "bash",
  "zsh",
  "fish",
  "ksh",
  "ksh93",
  "mksh",
  "dash",
  "ash",
  "sh",
]);

/** Argument prefix for a shell, chosen by its basename (PowerShell-style vs cmd vs POSIX-style). */
function argsForShell(name: string): string[] {
  if (name === "pwsh" || name === "powershell") return ["-NoLogo", "-NoProfile", "-Command"];
  if (name === "cmd") return ["/d", "/s", "/c"];
  return ["-lc"];
}

/**
 * Is `name` reachable as a bare command on this PATH? A plain directory walk — the POSIX
 * branch resolves at every process start and must not pay for a subprocess to do it.
 */
function onPath(name: string, env: NodeJS.ProcessEnv, exists: (p: string) => boolean): boolean {
  const raw = env.PATH ?? "";
  for (const dir of raw.split(path.posix.delimiter)) {
    // An empty entry means the working directory. Skipped deliberately: the Workspace is
    // model-writable, and picking a shell out of it would be an execution primitive.
    if (dir === "") continue;
    if (exists(path.posix.join(dir, name))) return true;
  }
  return false;
}

/**
 * The POSIX shell, in preference order. `bash` stays first and stays a *bare* name when
 * PATH has it, so the overwhelmingly common case is byte-identical to what shipped
 * before: the Skill and prompt ecosystem is written for bash, and the child resolves the
 * name against its own PATH. Everything after it exists so a box without bash degrades to
 * a working shell instead of an ENOENT on every single command.
 */
function resolvePosixShell(
  env: NodeJS.ProcessEnv,
  exists: (filePath: string) => boolean,
): ShellInvocation {
  if (onPath("bash", env, exists)) return { command: "bash", args: ["-lc"], name: "bash" };
  for (const candidate of POSIX_BASH_PATHS) {
    if (exists(candidate)) return { command: candidate, args: ["-lc"], name: "bash" };
  }
  // The user's own login shell, when it is one of the shells POSIX_LOGIN_SHELLS names (zsh,
  // fish, ksh …). It is named honestly to the model: `-lc` is what every one of them speaks,
  // but the syntax the model should write is that shell's, not bash's.
  const login = env.SHELL?.trim();
  if (login !== undefined && login.startsWith("/") && exists(login)) {
    const name = shellBasename(login);
    if (POSIX_LOGIN_SHELLS.has(name)) return { command: login, args: argsForShell(name), name };
  }
  for (const candidate of POSIX_FALLBACK_SHELLS) {
    if (candidate.startsWith("/") ? exists(candidate) : onPath(candidate, env, exists)) {
      return { command: candidate, args: ["-lc"], name: "sh" };
    }
  }
  // Nothing answered. Keep the historical invocation so the failure is the familiar one.
  return { command: "bash", args: ["-lc"], name: "bash" };
}

/** Default PATH probe: `where` lists every match line by line, in PATH order (win32 only). */
function defaultWhichAll(cmd: string): string[] {
  try {
    const res = spawnSync("where", [cmd], {
      stdio: ["ignore", "pipe", "ignore"],
      windowsHide: true,
    });
    if (res.status !== 0 || !res.stdout) return [];
    return res.stdout
      .toString("utf8")
      .split(/\r?\n/)
      .map((line) => line.trim())
      .filter((line) => line.length > 0);
  } catch {
    return [];
  }
}

/**
 * Resolves the shell for command sessions (pure given its options; see the module comment
 * for the order). Exported for unit tests; runtime code uses the cached `sessionShell()`.
 */
export function resolveShell(opts: ResolveShellOptions = {}): ShellInvocation {
  const platform = opts.platform ?? process.platform;
  const env = opts.env ?? process.env;

  const explicit = env.ADELIE_SHELL?.trim();
  if (explicit) {
    const name = shellBasename(explicit);
    return { command: explicit, args: argsForShell(name), name };
  }

  const exists = opts.exists ?? existsSync;
  if (platform !== "win32") {
    return resolvePosixShell(env, exists);
  }

  const whichAll = opts.whichAll ?? defaultWhichAll;
  const systemRoot = opts.systemRoot ?? env.SystemRoot ?? "C:\\Windows";
  // The WSL launcher lives in <SystemRoot>\System32 (or Sysnative under WOW64); a Git for
  // Windows bash lives under the Git install dir. Only the first PATH match counts — that
  // is the one spawn("bash") would run.
  const bash = whichAll("bash")[0];
  if (bash && !bash.toLowerCase().startsWith(systemRoot.toLowerCase() + path.win32.sep)) {
    return { command: "bash", args: ["-lc"], name: "bash" };
  }
  // The bundled MinGit bash (installed-package layout only; absent for npm installs). Reported
  // to the model as "bash" rather than its filename: MinGit installs GNU bash under the name
  // `sh`, and the Skill ecosystem targets bash, so "sh" would understate what it can run.
  const bundled = boundaryEnv(env, "bundledShell")?.trim();
  if (bundled && exists(bundled)) {
    return { command: bundled, args: ["-lc"], name: "bash" };
  }
  if (whichAll("pwsh").length > 0) {
    return { command: "pwsh", args: argsForShell("pwsh"), name: "pwsh" };
  }
  return { command: "powershell", args: argsForShell("powershell"), name: "powershell" };
}

let cached: ShellInvocation | null = null;

/** The process-wide shell for command sessions; resolved once (probing PATH costs a subprocess on Windows). */
export function sessionShell(): ShellInvocation {
  if (!cached) cached = resolveShell();
  return cached;
}