ubume 0.1.0

package/src/core/executables/codexExecutable.ts

@@ -0,0 +1,160 @@
+import { spawn } from "child_process";
+import { join } from "path";
+import { runCommand } from "../process/CommandRunner.js";
+import { buildSpawnSpec, resolveExecutable } from "./executableResolver.js";
+
+type CommandRunner = typeof runCommand;
+
+let cachedExecutable: string | null = null;
+let resolveInFlight: Promise<string> | null = null;
+
+interface SpawnOptions {
+  stdio: ["ignore" | "pipe", "pipe", "pipe"];
+}
+
+export interface CapturedProcessOutput {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export function resetCodexExecutableCacheForTests(): void {
+  cachedExecutable = null;
+}
+
+export async function resolveCodexExecutable(options?: {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+}): Promise<string> {
+  if (!options?.configuredPath && !options?.runCommandImpl && cachedExecutable !== null) {
+    return cachedExecutable;
+  }
+
+  if (!options?.configuredPath && !options?.runCommandImpl) {
+    if (resolveInFlight) return resolveInFlight;
+
+    resolveInFlight = (async () => {
+      const result = await doResolveCodexExecutable(options);
+      cachedExecutable = result;
+      return result;
+    })();
+
+    try {
+      return await resolveInFlight;
+    } finally {
+      resolveInFlight = null;
+    }
+  }
+
+  return doResolveCodexExecutable(options);
+}
+
+async function doResolveCodexExecutable(options?: {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+}): Promise<string> {
+  const knownFilePaths: string[] = [];
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) {
+    knownFilePaths.push(join(process.env.LOCALAPPDATA, "Microsoft", "WindowsApps", "codex.exe"));
+  }
+
+  return resolveExecutable({
+    runCommandImpl: options?.runCommandImpl,
+    cwd: options?.cwd,
+    configuredPath: options?.configuredPath,
+    envOverrides: ["CODEX_EXECUTABLE"],
+    commandNames: process.platform === "win32"
+      ? ["codex.cmd", "codex.exe", "codex"]
+      : ["codex"],
+    knownFilePaths,
+    label: "codex",
+  });
+}
+
+export function formatCodexLaunchError(err: NodeJS.ErrnoException): string {
+  const detail = err.message ? `\n\nDetails: ${err.message}` : "";
+
+  if (err.code === "ENOENT") {
+    return [
+      "Codex executable was not found in PATH.",
+      "Set CODEX_EXECUTABLE to your working command/path, then restart Ubume.",
+      "Alternative: install CLI with `npm install -g @openai/codex`.",
+    ].join("\n") + detail;
+  }
+
+  if (err.code === "EACCES" || err.code === "EPERM") {
+    return [
+      "Codex appears installed but this process cannot launch it (permission blocked).",
+      "Set CODEX_EXECUTABLE to a working CLI command/path and restart Ubume.",
+      "Windows note: Codex docs recommend WSL for the best CLI experience.",
+    ].join("\n") + detail;
+  }
+
+  return err.message;
+}
+
+export function spawnCodexProcess(
+  executable: string,
+  args: string[],
+  options: SpawnOptions,
+): ReturnType<typeof spawn> {
+  const spec = buildSpawnSpec(executable, args);
+  if (!spec.executable) throw new Error("Codex executable path is empty.");
+  return spawn(spec.executable, spec.args, { ...options, shell: false });
+}
+
+export function captureCodexProcessOutput(
+  executable: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<CapturedProcessOutput> {
+  return new Promise<CapturedProcessOutput>((resolve, reject) => {
+    let proc: ReturnType<typeof spawn>;
+    try {
+      proc = spawnCodexProcess(executable, args, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback();
+    };
+
+    const timer = setTimeout(() => {
+      proc.kill();
+      const error = new Error(`Timed out waiting for Codex command: ${args.join(" ")}`) as NodeJS.ErrnoException;
+      error.code = "ETIME";
+      finish(() => reject(error));
+    }, timeoutMs);
+
+    proc.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+
+    proc.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    proc.on("error", (error) => {
+      finish(() => reject(error));
+    });
+
+    proc.on("close", (exitCode) => {
+      finish(() => resolve({
+        exitCode,
+        stdout,
+        stderr,
+      }));
+    });
+  });
+}

package/src/core/executables/executableResolver.ts

@@ -0,0 +1,164 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { runCommand } from "../process/CommandRunner.js";
+import {
+  normalizeExecutableValue,
+  validateWindowsBatchArgumentForCmd,
+  validateWindowsBatchExecutableForCmd,
+} from "../process/processValidation.js";
+
+type CommandRunner = typeof runCommand;
+
+export interface ExecutableResolverOptions {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+  envOverrides?: string[];
+  commandNames: string[];
+  knownPathDirectories?: string[];
+  knownFilePaths?: string[];
+  label: string;
+  allowBareFallback?: boolean;
+  requireResolvedFile?: boolean;
+}
+
+function validateConfiguredExecutable(value: string, label: string, cwd: string): string {
+  return normalizeExecutableValue(value, {
+    label,
+    cwd,
+    requireExistingPath: /[\\/]/.test(value) || /^[\s"']*[A-Za-z]:/.test(value),
+    allowBareExecutable: true,
+  });
+}
+
+function validateResolvedExecutable(value: string, label: string, cwd: string): string {
+  return normalizeExecutableValue(value, {
+    label,
+    cwd,
+    requireExistingPath: false,
+    allowBareExecutable: true,
+  });
+}
+
+async function resolveWithWhere(
+  runCommandImpl: CommandRunner,
+  cwd: string,
+  query: string,
+  requireResolvedFile: boolean,
+): Promise<string | null> {
+  const whereRunner = runCommandImpl({
+    executable: "where.exe",
+    args: [query],
+    cwd,
+    timeoutMs: 5000,
+  });
+  const whereResult = await whereRunner.result;
+  if (whereResult.status !== "completed" || whereResult.exitCode !== 0) return null;
+  const lines = whereResult.stdout
+    .trim()
+    .split(/[\r\n]+/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    let candidate: string;
+    try {
+      candidate = validateResolvedExecutable(line, "where.exe result", cwd);
+    } catch {
+      continue;
+    }
+    if (!requireResolvedFile || existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Resolves an executable's location.
+ *
+ * Priority:
+ *   1. Configured path override
+ *   2. Environment variable overrides (in order)
+ *   3. Windows PATH lookup by explicit command names (using where.exe)
+ *   4. Windows known-path fallbacks (e.g. %APPDATA%\npm)
+ *   5. Explicit known file fallbacks
+ *   6. Bare name fallback, unless disabled
+ */
+export async function resolveExecutable(options: ExecutableResolverOptions): Promise<string> {
+  const runCommandImpl = options.runCommandImpl ?? runCommand;
+  const cwd = options.cwd ?? process.cwd();
+
+  // 1. Configured path override
+  if (options.configuredPath?.trim()) {
+    return validateConfiguredExecutable(options.configuredPath, `${options.label}CommandPath`, cwd);
+  }
+
+  // 2. Environment variable overrides
+  if (options.envOverrides) {
+    for (const envVar of options.envOverrides) {
+      const envOverride = process.env[envVar]?.trim();
+      if (envOverride) {
+        return validateConfiguredExecutable(envOverride, envVar, cwd);
+      }
+    }
+  }
+
+  // 3. Windows PATH lookup by explicit command names (where.exe returns null on non-Windows gracefully)
+  for (const candidate of options.commandNames) {
+    const resolved = await resolveWithWhere(runCommandImpl, cwd, candidate, options.requireResolvedFile === true);
+    if (resolved) return resolved;
+  }
+
+  // 4. Windows known-path fallbacks (existsSync returns false for non-existent paths on any platform)
+  if (options.knownPathDirectories) {
+    const knownCandidates: string[] = [];
+    for (const dir of options.knownPathDirectories) {
+      for (const candidate of options.commandNames) {
+        knownCandidates.push(join(dir, candidate));
+      }
+    }
+
+    for (const candidate of knownCandidates) {
+      const validated = validateResolvedExecutable(candidate, `${options.label} known executable`, cwd);
+      if (existsSync(validated)) return validated;
+    }
+  }
+
+  // 5. Explicit known file fallbacks
+  for (const candidate of options.knownFilePaths ?? []) {
+    const validated = validateResolvedExecutable(candidate, `${options.label} known executable`, cwd);
+    if (existsSync(validated)) return validated;
+  }
+
+  if (options.allowBareFallback === false) {
+    throw new Error(`${options.label} executable was not found.`);
+  }
+
+  // 6. Bare name fallback — prefer the name without an extension (works on Unix).
+  const bareName = options.commandNames.find((c) => !c.includes(".")) ?? options.commandNames[0];
+  return validateResolvedExecutable(bareName!, `${options.label} executable`, cwd);
+}
+
+/**
+ * Builds the spawn spec for a resolved executable.
+ * .cmd and .bat files must be invoked via `cmd.exe /d /s /c` on Windows.
+ *
+ * `platform` defaults to the host platform; it is injectable so the Windows
+ * wrapping branch can be unit-tested from any OS.
+ */
+export function buildSpawnSpec(
+  executable: string,
+  args: string[],
+  platform: NodeJS.Platform = process.platform,
+): { executable: string; args: string[] } {
+  const validatedExecutable = validateResolvedExecutable(executable, "Executable", process.cwd());
+  if (platform === "win32") {
+    const lower = validatedExecutable.toLowerCase();
+    if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+      validateWindowsBatchExecutableForCmd(validatedExecutable, "Windows batch executable");
+      for (const argument of args) {
+        validateWindowsBatchArgumentForCmd(argument, "Windows batch argument");
+      }
+      return { executable: "cmd.exe", args: ["/d", "/s", "/c", "call", validatedExecutable, ...args] };
+    }
+  }
+  return { executable: validatedExecutable, args };
+}

package/src/core/executables/geminiExecutable.ts

@@ -0,0 +1,78 @@
+import { join } from "path";
+import { runCommand } from "../process/CommandRunner.js";
+import { resolveExecutable } from "./executableResolver.js";
+
+type CommandRunner = typeof runCommand;
+
+let cachedExecutable: string | null = null;
+
+export function resetGeminiExecutableCacheForTests(): void {
+  cachedExecutable = null;
+}
+
+/**
+ * Returns the resolved Gemini CLI executable (full path or bare name).
+ *
+ * Priority:
+ *   1. Configured path override (geminiCommandPath)
+ *   2. GEMINI_EXECUTABLE or GEMINI_CLI_PATH env var
+ *   3. Windows PATH lookup for real files: gemini.exe, gemini.cmd, gemini.bat, gemini
+ *   4. Windows where.exe gemini fallback
+ *   5. Common npm/global locations on Windows
+ */
+export async function resolveGeminiExecutable(options?: {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+}): Promise<string> {
+  if (!options?.configuredPath && !options?.runCommandImpl && cachedExecutable !== null) {
+    return cachedExecutable;
+  }
+
+  const knownPathDirectories: string[] = [];
+  const userProfile = process.env.USERPROFILE;
+  const appData = process.env.APPDATA;
+  const localAppData = process.env.LOCALAPPDATA;
+
+  if (process.platform === "win32") {
+    if (appData) {
+      knownPathDirectories.push(join(appData, "npm"));
+    }
+    if (localAppData) {
+      knownPathDirectories.push(join(localAppData, "Programs", "nodejs"));
+    }
+  }
+
+  if (userProfile) {
+    knownPathDirectories.push(join(userProfile, ".local", "bin"));
+    knownPathDirectories.push(join(userProfile, "bin"));
+  }
+
+  const result = await resolveExecutable({
+    runCommandImpl: options?.runCommandImpl,
+    cwd: options?.cwd,
+    configuredPath: options?.configuredPath,
+    envOverrides: ["GEMINI_EXECUTABLE", "GEMINI_CLI_PATH"],
+    commandNames: ["gemini.exe", "gemini.cmd", "gemini.bat", "gemini"],
+    knownPathDirectories,
+    knownFilePaths: [],
+    label: "gemini",
+    allowBareFallback: process.platform !== "win32",
+    requireResolvedFile: true,
+  });
+
+  if (!options?.configuredPath && !options?.runCommandImpl) {
+    cachedExecutable = result;
+  }
+  return result;
+}
+
+/**
+ * Builds the spawn spec for a resolved Gemini executable.
+ */
+export function buildGeminiSpawnSpec(
+  executable: string,
+  args: string[],
+): { executable: string; args: string[]; shell?: boolean } {
+  return { executable, args };
+}

package/src/core/models/codexCapabilities.ts

@@ -0,0 +1,97 @@
+import { captureCodexProcessOutput } from "../executables/codexExecutable.js";
+import { stripAnsi, stripNonPrintableControls } from "../providers/codexTranscript.js";
+
+const HELP_TIMEOUT_MS = 5000;
+
+export interface CodexCliCapabilities {
+  askForApproval: boolean;
+  sandbox: boolean;
+  config: boolean;
+  fullAuto: boolean;
+  image?: boolean;
+}
+
+const capabilityCache = new Map<string, Promise<CodexCliCapabilities>>();
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizeHelpText(text: string): string {
+  return stripNonPrintableControls(stripAnsi(text))
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .toLowerCase();
+}
+
+// Uses a hand-rolled word-boundary pattern rather than \b so that flag names
+// containing hyphens (e.g. --ask-for-approval) are matched reliably.
+function hasCliToken(helpText: string, token: string): boolean {
+  const pattern = new RegExp(`(^|[^a-z0-9-])${escapeRegExp(token.toLowerCase())}(?=$|[^a-z0-9-])`, "m");
+  return pattern.test(helpText);
+}
+
+export function parseCodexCliCapabilities(
+  execHelpText: string,
+  _topLevelHelpText: string,
+): CodexCliCapabilities {
+  const execHelp = normalizeHelpText(execHelpText);
+
+  return {
+    askForApproval: hasCliToken(execHelp, "--ask-for-approval"),
+    sandbox: hasCliToken(execHelp, "--sandbox"),
+    config: hasCliToken(execHelp, "--config") || hasCliToken(execHelp, "-c"),
+    fullAuto: hasCliToken(execHelp, "--full-auto"),
+    image: hasCliToken(execHelp, "--image") || hasCliToken(execHelp, "-i"),
+  };
+}
+
+export async function getCodexCliCapabilities(executable: string): Promise<CodexCliCapabilities> {
+  const cached = capabilityCache.get(executable);
+  if (cached) {
+    return cached;
+  }
+
+  const inFlight = (async () => {
+    const [execHelp, topLevelHelp] = await Promise.allSettled([
+      captureCodexProcessOutput(executable, ["exec", "--help"], HELP_TIMEOUT_MS),
+      captureCodexProcessOutput(executable, ["--help"], HELP_TIMEOUT_MS),
+    ]);
+
+    const outputs: string[] = [];
+
+    if (execHelp.status === "fulfilled") {
+      outputs.push(execHelp.value.stdout, execHelp.value.stderr);
+    }
+
+    if (topLevelHelp.status === "fulfilled") {
+      outputs.push(topLevelHelp.value.stdout, topLevelHelp.value.stderr);
+    }
+
+    if (outputs.length === 0) {
+      if (execHelp.status === "rejected") {
+        throw execHelp.reason;
+      }
+
+      if (topLevelHelp.status === "rejected") {
+        throw topLevelHelp.reason;
+      }
+
+      throw new Error("Unable to determine Codex CLI capabilities from help output.");
+    }
+
+    return parseCodexCliCapabilities(
+      execHelp.status === "fulfilled" ? `${execHelp.value.stdout}\n${execHelp.value.stderr}` : "",
+      topLevelHelp.status === "fulfilled" ? `${topLevelHelp.value.stdout}\n${topLevelHelp.value.stderr}` : "",
+    );
+  })();
+
+  capabilityCache.set(executable, inFlight);
+
+  try {
+    return await inFlight;
+  } catch (error) {
+    capabilityCache.delete(executable);
+    throw error;
+  }
+}