@golba98/codexa 1.0.1

package/src/core/executables/codexExecutable.test.ts

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { afterEach } from "node:test";
+import type { ChildProcess } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runCommand, type CommandResult } from "../process/CommandRunner.js";
+import {
+  resolveCodexExecutable,
+  resetCodexExecutableCacheForTests,
+  spawnCodexProcess,
+} from "./codexExecutable.js";
+
+function commandResult(overrides: Partial<CommandResult> = {}): CommandResult {
+  return {
+    status: "completed",
+    exitCode: 0,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    startedAt: 0,
+    endedAt: 0,
+    durationMs: 0,
+    userMessage: "Command completed.",
+    ...overrides,
+  };
+}
+
+function mockRunCommand(result: CommandResult, onCall?: (spec: Parameters<typeof runCommand>[0]) => void): typeof runCommand {
+  return ((spec) => {
+    onCall?.(spec);
+    return {
+      child: null as unknown as ChildProcess,
+      result: Promise.resolve(result),
+      cancel: () => undefined,
+    };
+  }) as typeof runCommand;
+}
+
+async function withEnv<T>(env: Partial<NodeJS.ProcessEnv>, callback: () => Promise<T>): Promise<T> {
+  const originalCodexExe = process.env.CODEX_EXECUTABLE;
+  try {
+    if ("CODEX_EXECUTABLE" in env) process.env.CODEX_EXECUTABLE = env.CODEX_EXECUTABLE;
+    else delete process.env.CODEX_EXECUTABLE;
+    resetCodexExecutableCacheForTests();
+    return await callback();
+  } finally {
+    if (originalCodexExe === undefined) delete process.env.CODEX_EXECUTABLE;
+    else process.env.CODEX_EXECUTABLE = originalCodexExe;
+    resetCodexExecutableCacheForTests();
+  }
+}
+
+afterEach(() => {
+  resetCodexExecutableCacheForTests();
+});
+
+test("Codex resolver: configuredPath wins and bypasses env and PATH", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "env-codex.cmd" }, async () => {
+    let whereCalled = false;
+    const resolved = await resolveCodexExecutable({
+      configuredPath: process.execPath,
+      runCommandImpl: mockRunCommand(commandResult(), () => { whereCalled = true; }),
+    });
+
+    assert.equal(resolved, process.execPath);
+    assert.equal(whereCalled, false, "where.exe should not be called when configuredPath is set");
+  });
+});
+
+test("Codex resolver: CODEX_EXECUTABLE env var used when no configuredPath", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "env-codex.cmd" }, async () => {
+    let whereCalled = false;
+    const resolved = await resolveCodexExecutable({
+      runCommandImpl: mockRunCommand(commandResult(), () => { whereCalled = true; }),
+    });
+
+    assert.equal(resolved, "env-codex.cmd");
+    assert.equal(whereCalled, false, "where.exe should not be called when CODEX_EXECUTABLE is set");
+  });
+});
+
+test("Codex resolver: rejects unsafe CODEX_EXECUTABLE values", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "codex.cmd & calc" }, async () => {
+    await assert.rejects(
+      () => resolveCodexExecutable({
+        runCommandImpl: mockRunCommand(commandResult()),
+      }),
+      /shell metacharacters|single executable name/i,
+    );
+  });
+});
+
+test("Codex resolver: accepts environment executable paths with spaces", async () => {
+  const tempRoot = join(tmpdir(), `codexa codex resolver ${Date.now()}`);
+  const codexPath = join(tempRoot, "codex cli.exe");
+  mkdirSync(tempRoot, { recursive: true });
+  writeFileSync(codexPath, "");
+  try {
+    await withEnv({ CODEX_EXECUTABLE: `"${codexPath}"` }, async () => {
+      const resolved = await resolveCodexExecutable({
+        runCommandImpl: mockRunCommand(commandResult()),
+      });
+      assert.equal(resolved, codexPath);
+    });
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test("Codex resolver: Windows where.exe PATH lookup used when no env or config", async () => {
+  if (process.platform !== "win32") return;
+
+  const resolvedPath = join(tmpdir(), "codex.cmd");
+  writeFileSync(resolvedPath, "");
+  await withEnv({}, async () => {
+    const calls: Array<Parameters<typeof runCommand>[0]> = [];
+    const resolved = await resolveCodexExecutable({
+      runCommandImpl: mockRunCommand(
+        commandResult({ stdout: `${resolvedPath}\n` }),
+        (spec) => calls.push(spec),
+      ),
+    });
+
+    assert.equal(resolved, resolvedPath);
+    const whereCall = calls.find((c) => c.executable === "where.exe");
+    assert.ok(whereCall, "where.exe should have been called");
+  });
+});
+
+test("Codex resolver: bare fallback returned when nothing found (non-Windows)", async () => {
+  if (process.platform === "win32") return;
+
+  await withEnv({}, async () => {
+    const resolved = await resolveCodexExecutable({
+      runCommandImpl: mockRunCommand(commandResult({ exitCode: 1, status: "failed" })),
+    });
+
+    assert.equal(resolved, "codex", "Should fall back to bare codex name");
+  });
+});
+
+test("Codex resolver: Windows bare fallback when where.exe fails", async () => {
+  if (process.platform !== "win32") return;
+
+  await withEnv({}, async () => {
+    const resolved = await resolveCodexExecutable({
+      runCommandImpl: mockRunCommand(commandResult({ exitCode: 1, status: "failed" })),
+    });
+
+    assert.ok(["codex.cmd", "codex.exe", "codex"].includes(resolved), `Unexpected fallback: ${resolved}`);
+  });
+});
+
+test("Codex resolver: cache is populated after first resolution", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "env-codex.cmd" }, async () => {
+    const first = await resolveCodexExecutable();
+    const second = await resolveCodexExecutable();
+
+    assert.equal(first, second);
+    assert.equal(first, "env-codex.cmd");
+  });
+});
+
+test("Codex resolver: configuredPath bypasses cache", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "env-codex.cmd" }, async () => {
+    const cached = await resolveCodexExecutable();
+    assert.equal(cached, "env-codex.cmd");
+
+    const withOverride = await resolveCodexExecutable({
+      configuredPath: process.execPath,
+    });
+    assert.equal(withOverride, process.execPath);
+
+    const afterOverride = await resolveCodexExecutable();
+    assert.equal(afterOverride, "env-codex.cmd", "Cache should not be polluted by configuredPath call");
+  });
+});
+
+test("Codex resolver: resetCodexExecutableCacheForTests clears state", async () => {
+  await withEnv({ CODEX_EXECUTABLE: "first.cmd" }, async () => {
+    const first = await resolveCodexExecutable();
+    assert.equal(first, "first.cmd");
+  });
+
+  resetCodexExecutableCacheForTests();
+
+  await withEnv({ CODEX_EXECUTABLE: "second.cmd" }, async () => {
+    const second = await resolveCodexExecutable();
+    assert.equal(second, "second.cmd");
+  });
+});
+
+test("spawnCodexProcess wraps .cmd in cmd.exe on Windows", () => {
+  if (process.platform !== "win32") return;
+
+  const codexPath = "C:\\Users\\Example\\AppData\\Roaming\\npm\\codex.cmd";
+  const proc = spawnCodexProcess(codexPath, ["exec", "--help"], { stdio: ["ignore", "pipe", "pipe"] });
+  proc.kill();
+
+  assert.ok(proc, "Process should have been spawned");
+});
+
+test("spawnCodexProcess uses executable directly on non-Windows", () => {
+  if (process.platform === "win32") return;
+
+  const proc = spawnCodexProcess("echo", ["hello"], { stdio: ["ignore", "pipe", "pipe"] });
+  proc.kill();
+
+  assert.ok(proc, "Process should have been spawned");
+});

package/src/core/executables/codexExecutable.ts

@@ -0,0 +1,159 @@
+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 Codexa.",
+      "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 Codexa.",
+      "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);
+  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.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ChildProcess } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCommand, type CommandResult } from "../process/CommandRunner.js";
+import { resolveExecutable, buildSpawnSpec } from "./executableResolver.js";
+
+function commandResult(overrides: Partial<CommandResult>): CommandResult {
+  return {
+    status: "completed",
+    exitCode: 0,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    startedAt: 0,
+    endedAt: 0,
+    durationMs: 0,
+    userMessage: "Command completed.",
+    ...overrides,
+  };
+}
+
+function mockRunCommand(result: CommandResult, onCall?: (spec: Parameters<typeof runCommand>[0]) => void): typeof runCommand {
+  return ((spec) => {
+    onCall?.(spec);
+    return {
+      child: null as unknown as ChildProcess,
+      result: Promise.resolve(result),
+      cancel: () => undefined,
+    };
+  }) as typeof runCommand;
+}
+
+test("resolver: uses configuredPath", async () => {
+  const resolved = await resolveExecutable({
+    commandNames: ["test"],
+    label: "test",
+    configuredPath: process.execPath,
+  });
+  assert.equal(resolved, process.execPath);
+});
+
+test("resolver: uses environment override", async () => {
+  const original = process.env.TEST_EXECUTABLE;
+  process.env.TEST_EXECUTABLE = "custom-test";
+  try {
+    const resolved = await resolveExecutable({
+      commandNames: ["test"],
+      label: "test",
+      envOverrides: ["TEST_EXECUTABLE"],
+    });
+    assert.equal(resolved, "custom-test");
+  } finally {
+    if (original === undefined) delete process.env.TEST_EXECUTABLE;
+    else process.env.TEST_EXECUTABLE = original;
+  }
+});
+
+test("resolver: rejects environment override with shell metacharacters", async () => {
+  const original = process.env.TEST_EXECUTABLE;
+  process.env.TEST_EXECUTABLE = "custom-test & calc";
+  try {
+    await assert.rejects(
+      () => resolveExecutable({
+        commandNames: ["test"],
+        label: "test",
+        envOverrides: ["TEST_EXECUTABLE"],
+      }),
+      /shell metacharacters|single executable name/i,
+    );
+  } finally {
+    if (original === undefined) delete process.env.TEST_EXECUTABLE;
+    else process.env.TEST_EXECUTABLE = original;
+  }
+});
+
+test("resolver: rejects configured executable values that include arguments", async () => {
+  await assert.rejects(
+    () => resolveExecutable({
+      commandNames: ["test"],
+      label: "test",
+      configuredPath: "test --version",
+    }),
+    /single executable name/i,
+  );
+});
+
+test("resolver: accepts quoted executable paths with spaces", async () => {
+  const tempRoot = join(tmpdir(), `codexa resolver ${Date.now()}`);
+  const executablePath = join(tempRoot, "tool with spaces.exe");
+  mkdirSync(tempRoot, { recursive: true });
+  writeFileSync(executablePath, "");
+  try {
+    const resolved = await resolveExecutable({
+      commandNames: ["test"],
+      label: "test",
+      configuredPath: `"${executablePath}"`,
+    });
+    assert.equal(resolved, executablePath);
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test("resolver: falls back to bare name if not found", async () => {
+  const mockImpl = mockRunCommand(commandResult({ status: "failed", exitCode: 1 }));
+  const resolved = await resolveExecutable({
+    runCommandImpl: mockImpl,
+    commandNames: ["mytest"],
+    label: "test",
+  });
+  assert.equal(resolved, "mytest");
+});
+
+test("buildSpawnSpec: wraps .cmd files in cmd.exe on Windows", async () => {
+  if (process.platform !== "win32") return;
+  const spec = buildSpawnSpec("test.cmd", ["arg1"]);
+  assert.equal(spec.executable, "cmd.exe");
+  assert.deepEqual(spec.args, ["/d", "/s", "/c", "call", "test.cmd", "arg1"]);
+});
+
+test("buildSpawnSpec: does not wrap .exe files", async () => {
+  if (process.platform !== "win32") return;
+  const spec = buildSpawnSpec("test.exe", ["arg1"]);
+  assert.equal(spec.executable, "test.exe");
+  assert.deepEqual(spec.args, ["arg1"]);
+});

package/src/core/executables/executableResolver.ts

@@ -0,0 +1,138 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { runCommand } from "../process/CommandRunner.js";
+import {
+  normalizeExecutableValue,
+  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,
+  });
+}
+
+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) {
+    if (!requireResolvedFile || existsSync(line)) return line;
+  }
+  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) {
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  // 5. Explicit known file fallbacks
+  for (const candidate of options.knownFilePaths ?? []) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  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 bareName!;
+}
+
+/**
+ * Builds the spawn spec for a resolved executable.
+ * .cmd and .bat files must be invoked via `cmd.exe /d /s /c` on Windows.
+ */
+export function buildSpawnSpec(
+  executable: string,
+  args: string[],
+): { executable: string; args: string[] } {
+  if (process.platform === "win32") {
+    const lower = executable.toLowerCase();
+    if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+      validateWindowsBatchExecutableForCmd(executable, "Windows batch executable");
+      return { executable: "cmd.exe", args: ["/d", "/s", "/c", "call", executable, ...args] };
+    }
+  }
+  return { executable, args };
+}