Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
6.9 KB
Raw Blame
// Which external commands capture may run without side effects on screen.
//
// macOS: /usr/bin/{git,python3,cc,clang,make,…} are Command Line Tools shims.
// When the tools are not installed, running one opens the "install the
// command line developer tools" dialog. `xcode-select -p` (which never opens
// it) is asked once per process; when it fails, a shim that resolves to
// /usr/bin is never executed and the caller records `xcode_clt_missing`
// instead. A Homebrew, pyenv or other binary outside /usr/bin is fine to run.

import { spawn } from "node:child_process";
import { statSync } from "node:fs";
import nodePath from "node:path";

export const XCODE_CLT_MISSING = "xcode_clt_missing";

/** /usr/bin commands that are Command Line Tools shims on macOS. */
export const CLT_SHIM_COMMANDS: ReadonlySet<string> = new Set([
  "git", "python3", "python", "pip3", "pip", "pydoc3", "cc", "c++", "gcc", "g++", "clang", "clang++", "cpp",
  "make", "gnumake", "ld", "as", "ar", "nm", "ranlib", "strip", "lipo", "otool", "libtool", "swift", "swiftc",
  "lldb", "gdb", "bison", "flex", "m4", "yacc", "lex", "svn", "dsymutil", "xcrun", "xcodebuild", "llvm-gcc",
  "llvm-g++", "gcov", "indent", "unifdef", "ctags", "mig", "rpcgen", "size", "strings", "c89", "c99",
]);

const XCODE_SELECT_TIMEOUT_MS = 2_000;

// --- command resolution ------------------------------------------------------

export type ResolveOptions = {
  platform?: NodeJS.Platform;
  pathEnv?: string;
  pathExt?: string;
  isFile?: (path: string) => boolean;
};

function isDirectory(path: string): boolean {
  if (!path) return false;
  try {
    return statSync(path).isDirectory();
  } catch {
    return false;
  }
}

function defaultIsFile(path: string): boolean {
  try {
    return statSync(path).isFile();
  } catch {
    return false;
  }
}

/**
 * The absolute path `command` runs from, searching PATH the way the shell
 * would (PATHEXT on Windows), or null when it is not installed. Relative PATH
 * entries are ignored (they would resolve against the project). On Windows an
 * App Execution Alias under `WindowsApps` is skipped: the Store's `python.exe`
 * stub opens the Store instead of printing a version.
 */
export function resolveCommand(command: string, options: ResolveOptions = {}): string | null {
  const platform = options.platform ?? process.platform;
  const path = platform === "win32" ? nodePath.win32 : nodePath.posix;
  const pathEnv = options.pathEnv ?? (platform === "win32" ? (process.env.Path ?? process.env.PATH) : process.env.PATH) ?? "";
  const isFile = options.isFile ?? defaultIsFile;
  const extensions = platform === "win32"
    ? (options.pathExt ?? process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((ext) => ext.trim().toLowerCase()).filter((ext) => ext === ".exe" || ext === ".cmd" || ext === ".bat" || ext === ".com")
    : [""];
  for (const raw of pathEnv.split(platform === "win32" ? ";" : ":")) {
    const dir = raw.trim().replace(/^"(.*)"$/, "$1");
    if (!dir || !path.isAbsolute(dir)) continue;
    if (platform === "win32" && /[\\/]WindowsApps(?:[\\/]|$)/i.test(dir)) continue;
    for (const ext of extensions) {
      const candidate = path.join(dir, command + ext);
      if (isFile(candidate)) return candidate;
    }
  }
  return null;
}

// --- the Command Line Tools guard --------------------------------------------

export type CltProbe = {
  platform?: NodeJS.Platform;
  /** Whether `xcode-select -p` succeeds; the real one runs /usr/bin/xcode-select. */
  xcodeSelect?: () => Promise<boolean>;
  /** The xcode-select binary the real check runs (/usr/bin/xcode-select). */
  xcodeSelectBin?: string;
  resolve?: (command: string) => string | null;
};

let probe: CltProbe = {};
let cltMissing: Promise<boolean> | null = null;
let gitReason: Promise<string | null> | null = null;

/** Test hook: replaces the platform, xcode-select and PATH lookup, and clears the per-process cache. */
export function configureCltProbe(next: CltProbe | null): void {
  probe = next ?? {};
  cltMissing = null;
  gitReason = null;
}

function runXcodeSelect(bin = "/usr/bin/xcode-select"): Promise<boolean> {
  return new Promise((resolvePromise) => {
    let settled = false;
    const finish = (installed: boolean) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolvePromise(installed);
    };
    let child: ReturnType<typeof spawn>;
    try {
      child = spawn(bin, ["-p"], { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
    } catch {
      resolvePromise(false);
      return;
    }
    const timer = setTimeout(() => {
      child.kill("SIGKILL");
      finish(false);
    }, XCODE_SELECT_TIMEOUT_MS);
    timer.unref?.();
    child.on("error", () => finish(false));
    let printed = "";
    child.stdout?.on("data", (chunk: Buffer) => {
      if (printed.length < 4096) printed += chunk.toString("utf8");
    });
    // Installed only when it succeeds AND the folder it prints exists (as the
    // engine's guard checks): a removed CLT or a stale DEVELOPER_DIR exits 0
    // with a path that is gone, and the /usr/bin shims then fail or prompt.
    child.on("close", (code) => finish(code === 0 && isDirectory(printed.trim())));
  });
}

/** Whether this is macOS without the Command Line Tools (asked once per process; false elsewhere). */
export function xcodeCltMissing(): Promise<boolean> {
  if ((probe.platform ?? process.platform) !== "darwin") return Promise.resolve(false);
  cltMissing ??= (probe.xcodeSelect ?? (() => runXcodeSelect(probe.xcodeSelectBin)))().then((installed) => !installed, () => true);
  return cltMissing;
}

/** Whether `resolvedPath` is a /usr/bin Command Line Tools shim for `command` (no check that the tools are missing). */
export function isCltShim(command: string, resolvedPath: string | null | undefined, platform: NodeJS.Platform = probe.platform ?? process.platform): boolean {
  if (platform !== "darwin" || !resolvedPath) return false;
  return resolvedPath.startsWith("/usr/bin/") && CLT_SHIM_COMMANDS.has(nodePath.posix.basename(command));
}

/**
 * `xcode_clt_missing` when running `command` (resolved on PATH unless
 * `resolvedPath` is given) would open the install dialog, else null.
 */
export async function cltSkipReason(command: string, resolvedPath?: string | null): Promise<string | null> {
  const platform = probe.platform ?? process.platform;
  if (platform !== "darwin") return null;
  const path = resolvedPath !== undefined ? resolvedPath : (probe.resolve ?? ((name: string) => resolveCommand(name, { platform })))(command);
  if (!isCltShim(command, path, platform)) return null;
  return (await xcodeCltMissing()) ? XCODE_CLT_MISSING : null;
}

/** Why capture must not run `git` here (`xcode_clt_missing`), or null; cached per process. */
export function gitSkipReason(): Promise<string | null> {
  if ((probe.platform ?? process.platform) !== "darwin") return Promise.resolve(null);
  gitReason ??= cltSkipReason("git").catch(() => XCODE_CLT_MISSING);
  return gitReason;
}