@golba98/codexa 1.0.1

package/src/core/process/processValidation.ts

@@ -0,0 +1,101 @@
+import { existsSync } from "fs";
+import { isAbsolute, resolve } from "path";
+
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const BARE_EXECUTABLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SHELL_METACHARACTER_PATTERN = /[;&|<>`$]/;
+const WINDOWS_BATCH_METACHARACTER_PATTERN = /[;&|<>`$^%!]/;
+
+export interface ExecutableValidationOptions {
+  label: string;
+  cwd?: string;
+  requireExistingPath?: boolean;
+  allowBareExecutable?: boolean;
+}
+
+function stripBalancedWrappingQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
+    return value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+function looksLikePath(value: string): boolean {
+  return /[\\/]/.test(value) || /^[A-Za-z]:/.test(value);
+}
+
+function hasWindowsBatchExtension(value: string): boolean {
+  return /\.(?:cmd|bat)$/i.test(value);
+}
+
+function validateCommonExecutableSyntax(value: string, label: string): void {
+  if (!value) {
+    throw new Error(`${label} is empty.`);
+  }
+  if (CONTROL_CHARACTER_PATTERN.test(value)) {
+    throw new Error(`${label} contains control characters and cannot be used as an executable.`);
+  }
+  if (value.includes(`"`) || value.includes(`'`)) {
+    throw new Error(`${label} must be a command/path only, without embedded quotes.`);
+  }
+  if (SHELL_METACHARACTER_PATTERN.test(value)) {
+    throw new Error(`${label} contains shell metacharacters and cannot be used as an executable.`);
+  }
+}
+
+export function normalizeExecutableValue(
+  rawValue: string,
+  options: ExecutableValidationOptions,
+): string {
+  const allowBareExecutable = options.allowBareExecutable ?? true;
+  const requireExistingPath = options.requireExistingPath ?? false;
+  const cwd = options.cwd ?? process.cwd();
+  const trimmed = stripBalancedWrappingQuotes(rawValue.trim());
+
+  validateCommonExecutableSyntax(trimmed, options.label);
+
+  if (!looksLikePath(trimmed)) {
+    if (!allowBareExecutable) {
+      throw new Error(`${options.label} must be an executable path.`);
+    }
+    if (!BARE_EXECUTABLE_PATTERN.test(trimmed)) {
+      throw new Error(`${options.label} must be a single executable name without arguments.`);
+    }
+    return trimmed;
+  }
+
+  const normalized = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd, trimmed);
+  validateCommonExecutableSyntax(normalized, options.label);
+
+  if (requireExistingPath && !existsSync(normalized)) {
+    throw new Error(
+      `${options.label} path does not exist: "${normalized}"\n` +
+      `Check the path is correct and the file is accessible, or unset ${options.label}.`,
+    );
+  }
+
+  return normalized;
+}
+
+export function validateExecutableForSpawn(
+  executable: string,
+  options: ExecutableValidationOptions,
+): string {
+  return normalizeExecutableValue(executable, {
+    ...options,
+    requireExistingPath: options.requireExistingPath ?? false,
+  });
+}
+
+export function validateWindowsBatchExecutableForCmd(
+  executable: string,
+  label: string,
+): void {
+  if (!hasWindowsBatchExtension(executable)) return;
+  if (WINDOWS_BATCH_METACHARACTER_PATTERN.test(executable)) {
+    throw new Error(`${label} contains characters that are unsafe for cmd.exe batch launch.`);
+  }
+}

package/src/core/projectInstructions.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { loadProjectInstructions } from "./projectInstructions.js";
+
+function withTempWorkspace(run: (workspaceRoot: string) => void) {
+  const workspaceRoot = mkdtempSync(join(tmpdir(), "codexa-instructions-"));
+  try {
+    run(workspaceRoot);
+  } finally {
+    rmSync(workspaceRoot, { recursive: true, force: true });
+  }
+}
+
+test("loads AGENTS.md from the workspace root first", () => {
+  withTempWorkspace((workspaceRoot) => {
+    mkdirSync(join(workspaceRoot, ".codex"), { recursive: true });
+    writeFileSync(join(workspaceRoot, "AGENTS.md"), "root instructions\n", "utf8");
+    writeFileSync(join(workspaceRoot, ".codex", "AGENTS.md"), "nested instructions\n", "utf8");
+
+    const result = loadProjectInstructions(workspaceRoot);
+
+    assert.equal(result.status, "loaded");
+    if (result.status !== "loaded") return;
+    assert.equal(result.instructions.content, "root instructions");
+    assert.match(result.instructions.path, /AGENTS\.md$/);
+  });
+});
+
+test("falls back to .codex/AGENTS.md", () => {
+  withTempWorkspace((workspaceRoot) => {
+    mkdirSync(join(workspaceRoot, ".codex"), { recursive: true });
+    writeFileSync(join(workspaceRoot, ".codex", "AGENTS.md"), "project instructions\n", "utf8");
+
+    const result = loadProjectInstructions(workspaceRoot);
+
+    assert.equal(result.status, "loaded");
+    if (result.status !== "loaded") return;
+    assert.equal(result.instructions.content, "project instructions");
+    assert.match(result.instructions.path, /\.codex[\\/]AGENTS\.md$/);
+  });
+});
+
+test("treats missing instruction files as non-fatal", () => {
+  withTempWorkspace((workspaceRoot) => {
+    assert.deepEqual(loadProjectInstructions(workspaceRoot), { status: "missing" });
+  });
+});

package/src/core/projectInstructions.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+export interface ProjectInstructions {
+  path: string;
+  content: string;
+}
+
+export type ProjectInstructionsLoadResult =
+  | { status: "loaded"; instructions: ProjectInstructions }
+  | { status: "missing" }
+  | { status: "error"; path: string; message: string };
+
+const PROJECT_INSTRUCTION_CANDIDATES = [
+  "AGENTS.md",
+  join(".codex", "AGENTS.md"),
+] as const;
+
+export function loadProjectInstructions(workspaceRoot: string): ProjectInstructionsLoadResult {
+  let firstError: Extract<ProjectInstructionsLoadResult, { status: "error" }> | null = null;
+
+  for (const relativePath of PROJECT_INSTRUCTION_CANDIDATES) {
+    const candidatePath = join(workspaceRoot, relativePath);
+    if (!existsSync(candidatePath)) {
+      continue;
+    }
+
+    try {
+      const content = readFileSync(candidatePath, "utf8").trim();
+      if (!content) {
+        continue;
+      }
+      return {
+        status: "loaded",
+        instructions: {
+          path: candidatePath,
+          content,
+        },
+      };
+    } catch (error) {
+      firstError ??= {
+        status: "error",
+        path: candidatePath,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  if (firstError) {
+    return firstError;
+  }
+
+  return { status: "missing" };
+}

package/src/core/providerLauncher/launcher.test.ts

@@ -0,0 +1,238 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "events";
+import test from "node:test";
+import { buildProviderLaunchSpec, launchProviderCli } from "./launcher.js";
+import type { ProviderConfig } from "./types.js";
+
+function makeProvider(overrides: Partial<ProviderConfig> = {}): ProviderConfig {
+  return {
+    id: "openai",
+    displayName: "OpenAI",
+    currentModel: "gpt-5.4",
+    backendType: "codex-cli-auth",
+    routeMode: "in-codexa",
+    enabled: true,
+    statusLabel: "Enabled",
+    launchCommand: { executable: "codex", args: [] },
+    isDefault: true,
+    isActiveRoute: true,
+    routeUnavailableReason: null,
+    ...overrides,
+  };
+}
+
+test("builds launch specs for enabled providers", () => {
+  const spec = buildProviderLaunchSpec(makeProvider({
+    launchCommand: { executable: "claude", args: ["--resume"] },
+  }), "C:\\Workspace");
+
+  assert.equal("status" in spec, false);
+  if ("status" in spec) return;
+  assert.equal(spec.executable, "claude");
+  assert.deepEqual(spec.args, ["--resume"]);
+  assert.equal(spec.cwd, "C:\\Workspace");
+});
+
+test("disabled providers fail before spawning", () => {
+  const result = buildProviderLaunchSpec(makeProvider({
+    id: "local",
+    displayName: "Local",
+    backendType: "local-openai-compatible",
+    enabled: false,
+    statusLabel: "Disabled",
+    launchCommand: null,
+    isDefault: false,
+  }), "C:\\Workspace");
+
+  assert.equal("status" in result, true);
+  assert.equal("status" in result ? result.status : "", "disabled");
+  assert.match("status" in result ? result.message : "", /Configure a command/i);
+});
+
+test("unsafe configured launch commands fail before spawning", () => {
+  const result = buildProviderLaunchSpec(makeProvider({
+    launchCommand: { executable: "codex & calc", args: [] },
+  }), "C:\\Workspace");
+
+  assert.equal("status" in result, true);
+  assert.equal("status" in result ? result.status : "", "spawn-error");
+  assert.match("status" in result ? result.message : "", /unsafe launch command/i);
+});
+
+test("missing command spawn errors become friendly launch results", async () => {
+  const child = new EventEmitter();
+  const spawnImpl = (() => {
+    queueMicrotask(() => {
+      const error = new Error("not found") as NodeJS.ErrnoException;
+      error.code = "ENOENT";
+      child.emit("error", error);
+    });
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace",
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "missing-command");
+  assert.match(result.message, /codex.*PATH/i);
+});
+
+test("missing command preflight fails before suspending raw mode", async () => {
+  const rawModes: boolean[] = [];
+  let didSpawn = false;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace",
+    stdin: {
+      isRaw: true,
+      setRawMode(enabled) {
+        rawModes.push(enabled);
+      },
+    },
+    commandExists: () => false,
+    spawnImpl: (() => {
+      didSpawn = true;
+      return new EventEmitter();
+    }) as unknown as typeof import("child_process").spawn,
+  });
+
+  assert.equal(result.status, "missing-command");
+  assert.equal(didSpawn, false);
+  assert.deepEqual(rawModes, []);
+});
+
+test("launch restores raw mode after child exits", async () => {
+  const child = new EventEmitter();
+  const rawModes: boolean[] = [];
+  const spawnImpl = (() => {
+    queueMicrotask(() => child.emit("close", 0, null));
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace",
+    stdin: {
+      isRaw: true,
+      setRawMode(enabled) {
+        rawModes.push(enabled);
+      },
+    },
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "completed");
+  assert.deepEqual(rawModes, [false, true]);
+});
+
+test("launch passes the workspace root as the child cwd", async () => {
+  const child = new EventEmitter();
+  let observedCwd = "";
+  let observedShell: boolean | undefined = undefined;
+  const spawnImpl = ((_executable: string, _args: string[], options: { cwd?: string; shell?: boolean }) => {
+    observedCwd = options.cwd ?? "";
+    observedShell = options.shell;
+    queueMicrotask(() => child.emit("close", 0, null));
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace\\Project",
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "completed");
+  assert.equal(observedCwd, "C:\\Workspace\\Project");
+  assert.equal(observedShell, false);
+});
+
+test("launch wraps Windows batch commands without enabling shell mode", async () => {
+  if (process.platform !== "win32") return;
+
+  const child = new EventEmitter();
+  let observedExecutable = "";
+  let observedArgs: string[] = [];
+  let observedShell: boolean | undefined = undefined;
+  const spawnImpl = ((executable: string, args: string[], options: { shell?: boolean }) => {
+    observedExecutable = executable;
+    observedArgs = args;
+    observedShell = options.shell;
+    queueMicrotask(() => child.emit("close", 0, null));
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider({
+    launchCommand: { executable: "codex.cmd", args: ["--resume"] },
+  }), {
+    cwd: "C:\\Workspace",
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "completed");
+  assert.equal(observedExecutable, "cmd.exe");
+  assert.deepEqual(observedArgs, ["/d", "/s", "/c", "call", "codex.cmd", "--resume"]);
+  assert.equal(observedShell, false);
+});
+
+test("launch runs suspend and resume hooks around raw mode changes", async () => {
+  const child = new EventEmitter();
+  const events: string[] = [];
+  const spawnImpl = (() => {
+    events.push("spawn");
+    queueMicrotask(() => child.emit("close", 0, null));
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace",
+    stdin: {
+      isRaw: true,
+      setRawMode(enabled) {
+        events.push(enabled ? "raw-on" : "raw-off");
+      },
+    },
+    beforeLaunch: () => events.push("before"),
+    afterLaunch: () => events.push("after"),
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "completed");
+  assert.deepEqual(events, ["before", "raw-off", "spawn", "raw-on", "after"]);
+});
+
+test("launch restores terminal state after child spawn error", async () => {
+  const child = new EventEmitter();
+  const events: string[] = [];
+  const spawnImpl = (() => {
+    events.push("spawn");
+    queueMicrotask(() => {
+      const error = new Error("blocked") as NodeJS.ErrnoException;
+      error.code = "EPERM";
+      child.emit("error", error);
+    });
+    return child;
+  }) as unknown as typeof import("child_process").spawn;
+
+  const result = await launchProviderCli(makeProvider(), {
+    cwd: "C:\\Workspace",
+    stdin: {
+      isRaw: true,
+      setRawMode(enabled) {
+        events.push(enabled ? "raw-on" : "raw-off");
+      },
+    },
+    beforeLaunch: () => events.push("before"),
+    afterLaunch: () => events.push("after"),
+    commandExists: () => true,
+    spawnImpl,
+  });
+
+  assert.equal(result.status, "spawn-error");
+  assert.deepEqual(events, ["before", "raw-off", "spawn", "raw-on", "after"]);
+});

package/src/core/providerLauncher/launcher.ts

@@ -0,0 +1,203 @@
+import { spawn, type ChildProcess } from "child_process";
+import { existsSync } from "fs";
+import { buildSpawnSpec } from "../executables/executableResolver.js";
+import { normalizeExecutableValue } from "../process/processValidation.js";
+import type { ProviderConfig, ProviderLaunchCommand } from "./types.js";
+
+export interface ProviderLaunchSpec {
+  executable: string;
+  args: string[];
+  cwd: string;
+}
+
+export type ProviderLaunchResult =
+  | { status: "completed"; exitCode: number | null; signal: NodeJS.Signals | null; message: string }
+  | { status: "disabled"; message: string }
+  | { status: "missing-command"; message: string }
+  | { status: "spawn-error"; message: string; errorCode?: string };
+
+interface RawModeStream {
+  isRaw?: boolean;
+  setRawMode?: (enabled: boolean) => unknown;
+}
+
+export interface LaunchProviderCliOptions {
+  cwd: string;
+  stdin?: RawModeStream | null;
+  beforeLaunch?: () => void;
+  afterLaunch?: () => void;
+  spawnImpl?: typeof spawn;
+  commandExists?: (executable: string) => Promise<boolean> | boolean;
+}
+
+function formatCommand(command: ProviderLaunchCommand): string {
+  return [command.executable, ...command.args].join(" ");
+}
+
+export function buildProviderLaunchSpec(provider: ProviderConfig, cwd: string): ProviderLaunchSpec | ProviderLaunchResult {
+  if (!provider.enabled) {
+    return {
+      status: "disabled",
+      message: `${provider.displayName} is disabled. Configure a command in .codexa/providers.json before launching it.`,
+    };
+  }
+
+  if (!provider.launchCommand?.executable.trim()) {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} does not have a launch command configured.`,
+    };
+  }
+
+  try {
+    return {
+      executable: normalizeExecutableValue(provider.launchCommand.executable, {
+        label: `${provider.displayName} launch command`,
+        cwd,
+      }),
+      args: provider.launchCommand.args,
+      cwd,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid launch command.";
+    return {
+      status: "spawn-error",
+      message: `${provider.displayName} has an unsafe launch command. ${message}`,
+    };
+  }
+}
+
+function setRawMode(stdin: RawModeStream | null | undefined, enabled: boolean): void {
+  try {
+    stdin?.setRawMode?.(enabled);
+  } catch {
+    // Some test streams and redirected terminals do not support raw-mode changes.
+  }
+}
+
+function executableLooksLikePath(executable: string): boolean {
+  return /[\\/]/.test(executable) || /^[A-Za-z]:/.test(executable);
+}
+
+// Probe-spawns the executable to check if it exits cleanly — used instead of `which`/`where`
+// because path-lookup alone doesn't verify the file is actually runnable.
+function captureProcessExit(executable: string, args: string[]): Promise<boolean> {
+  return new Promise((resolve) => {
+    let child: ChildProcess;
+    try {
+      child = spawn(executable, args, {
+        stdio: "ignore",
+        shell: false,
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+
+    child.once("error", () => resolve(false));
+    child.once("close", (exitCode) => resolve(exitCode === 0));
+  });
+}
+
+export async function commandExistsOnPath(executable: string): Promise<boolean> {
+  const trimmed = executable.trim();
+  if (!trimmed) return false;
+  if (executableLooksLikePath(trimmed)) {
+    return existsSync(trimmed);
+  }
+
+  if (process.platform === "win32") {
+    return captureProcessExit("where.exe", [trimmed]);
+  }
+
+  return captureProcessExit("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", trimmed]);
+}
+
+function formatSpawnError(provider: ProviderConfig, executable: string, error: NodeJS.ErrnoException): ProviderLaunchResult {
+  if (error.code === "ENOENT") {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} could not be launched because \`${executable}\` is not installed or not available on PATH.`,
+    };
+  }
+
+  if (error.code === "EACCES" || error.code === "EPERM") {
+    return {
+      status: "spawn-error",
+      errorCode: error.code,
+      message: `${provider.displayName} could not be launched because permission was denied for \`${executable}\`.`,
+    };
+  }
+
+  return {
+    status: "spawn-error",
+    errorCode: error.code,
+    message: `${provider.displayName} could not be launched. ${error.message}`,
+  };
+}
+
+export async function launchProviderCli(
+  provider: ProviderConfig,
+  options: LaunchProviderCliOptions,
+): Promise<ProviderLaunchResult> {
+  const spec = buildProviderLaunchSpec(provider, options.cwd);
+  if ("status" in spec) return spec;
+
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const commandExists = options.commandExists ?? commandExistsOnPath;
+  const available = await commandExists(spec.executable);
+  if (!available) {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} could not be launched because \`${spec.executable}\` is not installed or not available on PATH.`,
+    };
+  }
+
+  const wasRaw = Boolean(options.stdin?.isRaw);
+  options.beforeLaunch?.();
+  setRawMode(options.stdin, false);
+
+  try {
+    return await new Promise<ProviderLaunchResult>((resolve) => {
+      let child: ChildProcess;
+      try {
+        const spawnSpec = buildSpawnSpec(spec.executable, spec.args);
+        child = spawnImpl(spawnSpec.executable, spawnSpec.args, {
+          cwd: spec.cwd,
+          shell: false,
+          stdio: "inherit",
+        });
+      } catch (error) {
+        resolve(formatSpawnError(provider, spec.executable, error as NodeJS.ErrnoException));
+        return;
+      }
+
+      child.once("error", (error: NodeJS.ErrnoException) => {
+        resolve(formatSpawnError(provider, spec.executable, error));
+      });
+
+      child.once("close", (exitCode, signal) => {
+        resolve({
+          status: "completed",
+          exitCode,
+          signal,
+          message: `${provider.displayName} launch finished${exitCode === null ? "" : ` with exit code ${exitCode}`}.`,
+        });
+      });
+    });
+  } finally {
+    if (wasRaw) {
+      setRawMode(options.stdin, true);
+    }
+    options.afterLaunch?.();
+  }
+}
+
+export function describeProviderLaunch(provider: ProviderConfig): string {
+  if (!provider.enabled) {
+    return `${provider.displayName} is disabled.`;
+  }
+  return provider.launchCommand
+    ? `${provider.displayName}: ${formatCommand(provider.launchCommand)}`
+    : `${provider.displayName} has no launch command configured.`;
+}