Skip to content

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

10.2 KB
Raw Blame
/**
 * Login-shell environment import for GUI launches (#351).
 *
 * A shell launched from the macOS Dock or a Linux desktop session inherits the session
 * manager's environment, not the user's login shell — exports from `.zshrc` / `.profile`
 * (model API keys picked up by core's env fallback, the PATH the agent shell needs for
 * user-installed tooling) never reach it. Without this import, the desktop app makes the
 * user re-enter keys that already work in their terminal, and agent commands run on the
 * bare system PATH.
 *
 * On macOS and Linux, when no terminal launched us (no TERM), the user's shell is run
 * once as an interactive login shell (`-i -l -c`, so both profile and rc files are read)
 * around a sentinel-framed `env -0` dump. NUL separation keeps values containing
 * newlines intact, and the sentinel frame cuts away whatever the rc files print around
 * it. The result is merged fill-missing-only into `process.env` before anything reads it:
 * an explicitly provided variable always wins, so a launch from a terminal — where the
 * import is skipped anyway — and a launch with variables set on the command line behave
 * exactly as before. The embedded server (and with it the agent shell) inherits
 * `process.env` at fork time, so the import reaches both without further plumbing.
 *
 * Everything but the probe spawn is pure and unit-tests without Electron; the probe is
 * best-effort with a hard timeout — any failure leaves the environment untouched.
 * `PENGUIN_NO_LOGIN_SHELL_ENV` (any non-empty value) skips the probe, the escape hatch
 * for a login shell that cannot run non-interactively within the timeout.
 */
import { spawn } from "node:child_process";

/** Frame marker around the probe's `env -0` output; rc-file noise falls outside the frame. */
const SENTINEL = "__PENGUIN_LOGIN_SHELL_ENV__";

/** The probe: static string, no interpolation, so no quoting hazards in any POSIX-ish shell. */
const PROBE_COMMAND = `printf '%s' '${SENTINEL}'; env -0; printf '%s' '${SENTINEL}'`;

/** Hard cap on the probe's lifetime; a hung interactive rc file must not stall app startup. */
export const PROBE_TIMEOUT_MS = 5_000;

/** Cap on collected probe output; an env dump is kilobytes, anything larger is runaway noise. */
const PROBE_OUTPUT_CAP = 4 * 1024 * 1024;

/**
 * Keys never imported: shell-position bookkeeping the probe shell wrote for itself
 * (`_`, `SHLVL`, `PWD`, `OLDPWD`), the probe's own terminal identity (`TERM`), and
 * `ELECTRON_RUN_AS_NODE` — importing that one would make every later relaunch of the
 * app run as plain Node instead of Electron.
 *
 * `PENGUIN_WEB_DIST` and `PENGUIN_CLI_ENTRY` join them because they select *code*: the
 * embedded server reads the first for the Web App it serves and the second for the entry it
 * self-updates through, and the fork does not override either. A profile line written for a
 * repo checkout would silently retarget an installed app that the user only double-clicked.
 * Data and settings variables are not excluded — `PENGUIN_HOME` chooses which data root the
 * app opens, which is a configuration choice a user can mean to make once for both the CLI
 * and the app.
 */
const EXCLUDED_KEYS = new Set([
  "_",
  "SHLVL",
  "PWD",
  "OLDPWD",
  "TERM",
  "ELECTRON_RUN_AS_NODE",
  "PENGUIN_WEB_DIST",
  "PENGUIN_CLI_ENTRY",
]);

/** Environment variable names as the POSIX shells define them; also drops `BASH_FUNC_f%%` exported functions. */
const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;

/**
 * Whether this launch should import the login shell environment: never on Windows (GUI
 * processes inherit the user environment there), never when a terminal launched us
 * (TERM set — the environment is already the shell's), and never when the escape hatch
 * `PENGUIN_NO_LOGIN_SHELL_ENV` is set.
 */
export function shouldImportLoginShellEnv(opts: {
  platform: NodeJS.Platform;
  env: NodeJS.ProcessEnv;
}): boolean {
  if (opts.platform === "win32") return false;
  if (opts.env.TERM !== undefined) return false;
  if (opts.env.PENGUIN_NO_LOGIN_SHELL_ENV) return false;
  return true;
}

/** The shell to probe: the user's `$SHELL` when absolute, else the platform default. */
export function probeShell(shell: string | undefined, platform: NodeJS.Platform): string {
  if (shell !== undefined && shell.startsWith("/")) return shell;
  return platform === "darwin" ? "/bin/zsh" : "/bin/bash";
}

/**
 * Extracts the environment record from the probe's stdout: the NUL-separated
 * `KEY=VALUE` entries between the first sentinel and the next one after it (a zsh
 * `zlogout` may print after the closing frame, so the close is the *next* occurrence,
 * not the last). Returns null when the frame is missing or holds no valid entry —
 * including when `env` does not support `-0` and printed nothing between the frames.
 */
export function parseLoginShellEnvDump(stdout: string): Record<string, string> | null {
  const open = stdout.indexOf(SENTINEL);
  if (open === -1) return null;
  const close = stdout.indexOf(SENTINEL, open + SENTINEL.length);
  if (close === -1) return null;
  const dump = stdout.slice(open + SENTINEL.length, close);
  const out: Record<string, string> = {};
  for (const entry of dump.split("\0")) {
    if (entry.length === 0) continue;
    const eq = entry.indexOf("=");
    if (eq <= 0) continue;
    const key = entry.slice(0, eq);
    if (!KEY_PATTERN.test(key)) continue;
    out[key] = entry.slice(eq + 1);
  }
  return Object.keys(out).length > 0 ? out : null;
}

/**
 * The patch to apply to `current`: every imported variable `current` leaves unset,
 * minus `EXCLUDED_KEYS`. PATH is the one merged key — a GUI launch *has* a PATH (the
 * bare system one), so fill-missing alone would never improve it: the login shell's
 * entries come first (its ordering wins), current-only entries are appended, duplicates
 * and empties dropped.
 */
export function mergeLoginShellEnv(
  current: NodeJS.ProcessEnv,
  imported: Record<string, string>,
): Record<string, string> {
  const patch: Record<string, string> = {};
  for (const [key, value] of Object.entries(imported)) {
    if (key === "PATH" || EXCLUDED_KEYS.has(key)) continue;
    if (current[key] !== undefined) continue;
    patch[key] = value;
  }
  const importedPath = imported["PATH"];
  if (importedPath !== undefined) {
    const currentPath = current["PATH"];
    const merged =
      currentPath === undefined ? importedPath : mergePathValue(importedPath, currentPath);
    if (merged !== currentPath) patch["PATH"] = merged;
  }
  return patch;
}

/** Login-shell PATH entries first, then current-only ones; deduplicated, empties dropped. */
function mergePathValue(importedPath: string, currentPath: string): string {
  const out: string[] = [];
  const seen = new Set<string>();
  for (const entry of [...importedPath.split(":"), ...currentPath.split(":")]) {
    if (entry.length === 0 || seen.has(entry)) continue;
    seen.add(entry);
    out.push(entry);
  }
  return out.join(":");
}

/**
 * Runs the probe and returns the parsed environment, or null on any failure (spawn
 * error, timeout, output cap, unparseable output). The exit code is deliberately
 * ignored: login rc files exit non-zero for reasons of their own, and the
 * sentinel-framed dump is the actual signal.
 */
export function resolveLoginShellEnv(opts: {
  shell: string;
  env: NodeJS.ProcessEnv;
  timeoutMs?: number;
}): Promise<Record<string, string> | null> {
  return new Promise((resolve) => {
    let child: ReturnType<typeof spawn>;
    try {
      child = spawn(opts.shell, ["-i", "-l", "-c", PROBE_COMMAND], {
        env: opts.env,
        stdio: ["ignore", "pipe", "ignore"],
      });
    } catch {
      resolve(null);
      return;
    }
    let stdout = "";
    let settled = false;
    // Settle exactly once, and stop reading. On timeout or cap overrun the promise resolves
    // immediately after the kill instead of waiting for "close": a hung rc file's own
    // children inherit the stdout pipe and would hold "close" open for as long as they live
    // — and would keep feeding the buffer below, so the pipe is dropped here rather than
    // left collecting output nobody will read.
    const settle = (value: Record<string, string> | null): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      child.stdout?.destroy();
      resolve(value);
    };
    const timer = setTimeout(() => {
      child.kill("SIGKILL");
      settle(null);
    }, opts.timeoutMs ?? PROBE_TIMEOUT_MS);
    // Decode across chunk boundaries: the dump arrives in pipe-sized reads that cut wherever
    // they land, and a per-chunk Buffer -> string would turn every UTF-8 sequence straddling
    // a boundary into replacement characters (a value with any non-ASCII in it, in an
    // environment large enough to need a second read).
    child.stdout?.setEncoding("utf8");
    child.stdout?.on("data", (chunk: string) => {
      stdout += chunk;
      if (stdout.length > PROBE_OUTPUT_CAP) {
        child.kill("SIGKILL");
        settle(null);
      }
    });
    child.on("error", () => settle(null));
    child.on("close", () => settle(parseLoginShellEnvDump(stdout)));
  });
}

/**
 * Entry point for the shell's boot path: probes when `shouldImportLoginShellEnv` says
 * to, merges fill-missing into `opts.env` (normally `process.env`), and returns the
 * number of variables applied. Best-effort: every failure path logs one line and
 * returns 0 with the environment untouched.
 */
export async function applyLoginShellEnv(opts: {
  platform: NodeJS.Platform;
  env: NodeJS.ProcessEnv;
  shell: string | undefined;
  timeoutMs?: number;
  log: (line: string) => void;
}): Promise<number> {
  if (!shouldImportLoginShellEnv(opts)) return 0;
  const shell = probeShell(opts.shell, opts.platform);
  const resolved = await resolveLoginShellEnv({
    shell,
    env: opts.env,
    ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
  });
  if (resolved === null) {
    opts.log(`login shell environment unavailable (${shell}); continuing without it`);
    return 0;
  }
  const patch = mergeLoginShellEnv(opts.env, resolved);
  Object.assign(opts.env, patch);
  const count = Object.keys(patch).length;
  if (count > 0) {
    opts.log(`imported ${count} environment variable(s) from the login shell (${shell})`);
  }
  return count;
}