Skip to content

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

3.7 KB
Raw Blame
/**
 * Putting a directory at the FRONT of PATH for something the harness spawns.
 *
 * Two forms, because a command needs both. {@link prependPathEnv} writes the child's
 * environment, which is all a directly spawned process (a hook script) ever sees. A
 * command, though, runs through a LOGIN shell, and a login profile routinely prepends
 * `/opt/homebrew/bin` or `/usr/local/bin` to whatever PATH it inherited — so the
 * environment alone leaves the harness's directory behind whatever the profile put in
 * front of it. {@link pathPrependPrefix} is the statement that runs after the profile and
 * decides.
 *
 * Nothing here has an opinion about WHAT is prepended: the host supplies the directories
 * (see `EnvironmentConfig.pathPrepend`).
 */
import path from "node:path";

/**
 * `env` with `dirs` at the front of its PATH entry — a new object; the argument is not
 * touched. An empty list returns it unchanged.
 *
 * The existing entry's own spelling is reused rather than writing `PATH`: Windows resolves
 * environment names case-insensitively but stores the casing it was given, so an
 * environment carrying `Path` would end up with two entries differing only in case, and
 * which one the child reads is not ours to decide.
 */
export function prependPathEnv(env: NodeJS.ProcessEnv, dirs: readonly string[]): NodeJS.ProcessEnv {
  if (dirs.length === 0) return env;
  const key = Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH";
  const current = env[key];
  const prefix = dirs.join(path.delimiter);
  return {
    ...env,
    [key]:
      current === undefined || current === "" ? prefix : `${prefix}${path.delimiter}${current}`,
  };
}

/**
 * Shells that take a Bourne-style `export NAME=value`. Everything the POSIX resolver can
 * pick (see shell.ts) except `fish`, which spells the same thing `set -x` and would fail
 * the whole command on an `export`.
 */
const EXPORT_PATH_SHELLS = new Set(["bash", "sh", "zsh", "ksh", "ksh93", "mksh", "dash", "ash"]);

/** A string as one POSIX shell word: single-quoted, with each embedded quote spliced as `'\''`. */
function posixQuote(value: string): string {
  return `'${value.replaceAll("'", `'\\''`)}'`;
}

/** A string as a PowerShell single-quoted literal, where a quote is escaped by doubling it. */
function powerShellQuote(value: string): string {
  return `'${value.replaceAll("'", "''")}'`;
}

/**
 * The statement that puts `dirs` at the front of PATH for one command, written in the
 * syntax of the shell that will run it and ending in that shell's separator, so
 * `pathPrependPrefix(...) + cmd` is a command string with the original command still last
 * — untouched, and still the one whose exit status the shell reports.
 *
 * `""` for an empty list, and for any shell whose PATH syntax is not one of the three
 * below — `fish`, and whatever basename `ADELIE_SHELL` names. A prefix in the wrong
 * dialect would not misconfigure PATH, it would fail every command, so an unrecognized
 * shell keeps the child-environment prepend and nothing more.
 */
export function pathPrependPrefix(shellName: string, dirs: readonly string[]): string {
  if (dirs.length === 0) return "";
  if (shellName === "pwsh" || shellName === "powershell") {
    const prefix = dirs.map((dir) => `${powerShellQuote(dir)} + ';' + `).join("");
    return `$env:PATH = ${prefix}$env:PATH; `;
  }
  // cmd offers no quoting: a `%` in a directory would be read as a variable reference and
  // expanded here. What that costs is a prefix naming the wrong directory, not a mangled
  // PATH — the `;%PATH%` tail is unaffected.
  if (shellName === "cmd") return `set "PATH=${dirs.join(";")};%PATH%" && `;
  if (!EXPORT_PATH_SHELLS.has(shellName)) return "";
  return `export PATH=${dirs.map(posixQuote).join(":")}:"$PATH"; `;
}