@golba98/codexa 1.0.1

package/src/core/inputDebug.ts

@@ -0,0 +1,51 @@
+import { appendFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+type DebugDetails = Record<string, unknown>;
+
+let sequence = 0;
+
+export function isInputDebugEnabled(): boolean {
+  return process.env.CODEXA_DEBUG_INPUT === "1";
+}
+
+export function getInputDebugLogPath(): string {
+  return process.env.CODEXA_DEBUG_INPUT_LOG || join(homedir(), ".codexa-input-debug.log");
+}
+
+export function getStdinDebugState(stdin: unknown): DebugDetails {
+  const input = stdin as {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    readable?: boolean;
+    destroyed?: boolean;
+    isPaused?: () => boolean;
+  } | null | undefined;
+
+  return {
+    isTTY: input?.isTTY ?? null,
+    isRaw: input?.isRaw ?? null,
+    readable: input?.readable ?? null,
+    destroyed: input?.destroyed ?? null,
+    paused: typeof input?.isPaused === "function" ? input.isPaused() : null,
+  };
+}
+
+export function traceInputDebug(event: string, details: DebugDetails = {}): void {
+  if (!isInputDebugEnabled()) {
+    return;
+  }
+
+  try {
+    const entry = {
+      ts: new Date().toISOString(),
+      seq: ++sequence,
+      event,
+      ...details,
+    };
+    appendFileSync(getInputDebugLogPath(), `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Debug tracing must never affect interactive input.
+  }
+}

package/src/core/launchContext.test.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import test from "node:test";
+import {
+  buildWorkspaceStatusMessage,
+  createWorkspaceRelaunchPlan,
+  guardWorkspaceRelaunch,
+  resolveLaunchContext,
+} from "./launchContext.js";
+import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+
+function createTempWorkspace(): string {
+  return mkdtempSync(join(tmpdir(), "codexa-launch-context-"));
+}
+
+test("uses installed launcher metadata when available", () => {
+  const context = resolveLaunchContext({
+    workspaceRoot: "C:/target",
+    packageRoot: "C:/repo",
+    execPath: "C:/Program Files/nodejs/node.exe",
+    env: {
+      CODEXA_LAUNCH_KIND: "installed-bin",
+      CODEXA_PACKAGE_ROOT: "C:/repo",
+      CODEXA_LAUNCHER_SCRIPT: "C:/repo/bin/codexa.js",
+      CODEXA_RELAUNCH_EXECUTABLE: "C:/Program Files/nodejs/node.exe",
+      CODEXA_RELAUNCH_ARGS: JSON.stringify(["C:/repo/bin/codexa.js", "--profile", "review"]),
+    },
+  });
+
+  assert.equal(context.launchKind, "installed-bin");
+  assert.equal(context.packageRoot, "C:\\repo");
+  assert.equal(context.launcherScriptPath, "C:/repo/bin/codexa.js");
+  assert.equal(context.relaunchExecutable, "C:/Program Files/nodejs/node.exe");
+  assert.deepEqual(context.relaunchArgs, ["C:/repo/bin/codexa.js", "--profile", "review"]);
+});
+
+test("falls back to bun repo launch metadata when no installed launcher env exists", () => {
+  const context = resolveLaunchContext({
+    workspaceRoot: "C:/repo",
+    packageRoot: "C:/repo",
+    execPath: "C:/tools/bun.exe",
+    hasBunRuntime: true,
+    forwardArgs: ["--profile", "review", "--config", "model=\"gpt-5.4\""],
+    env: {},
+  });
+
+  assert.equal(context.launchKind, "dev-run");
+  assert.equal(context.relaunchExecutable, "C:/tools/bun.exe");
+  assert.deepEqual(context.relaunchArgs, [
+    "run",
+    "--silent",
+    join("C:\\repo", "src", "index.tsx"),
+    "--",
+    "--profile",
+    "review",
+    "--config",
+    "model=\"gpt-5.4\"",
+  ]);
+});
+
+test("creates an installed-bin relaunch plan with normalized target cwd and env", () => {
+  const root = createTempWorkspace();
+  try {
+    const nextWorkspace = join(root, "next");
+    mkdirSync(nextWorkspace);
+
+    const context = resolveLaunchContext({
+      workspaceRoot: root,
+      packageRoot: "C:/repo",
+      execPath: "C:/Program Files/nodejs/node.exe",
+      env: {
+        CODEXA_LAUNCH_KIND: "installed-bin",
+        CODEXA_PACKAGE_ROOT: "C:/repo",
+        CODEXA_LAUNCHER_SCRIPT: "C:/repo/bin/codexa.js",
+        CODEXA_RELAUNCH_EXECUTABLE: "C:/Program Files/nodejs/node.exe",
+        CODEXA_RELAUNCH_ARGS: JSON.stringify(["C:/repo/bin/codexa.js", "--profile", "review"]),
+      },
+    });
+
+    const result = createWorkspaceRelaunchPlan(".\\next", context, {});
+    assert.equal(result.ok, true);
+    if (!result.ok) return;
+
+    assert.equal(result.plan.executable, "C:/Program Files/nodejs/node.exe");
+    assert.deepEqual(result.plan.args, ["C:/repo/bin/codexa.js", "--profile", "review"]);
+    assert.equal(result.plan.cwd, normalizeWorkspaceRoot(nextWorkspace));
+    assert.equal(result.plan.env.CODEX_WORKSPACE_ROOT, normalizeWorkspaceRoot(nextWorkspace));
+    assert.equal(result.plan.env.CODEXA_LAUNCH_KIND, "installed-bin");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects relaunch targets that do not exist", () => {
+  const root = createTempWorkspace();
+  try {
+    const context = resolveLaunchContext({
+      workspaceRoot: root,
+      packageRoot: root,
+      execPath: "C:/tools/bun.exe",
+      hasBunRuntime: true,
+      env: {},
+    });
+
+    const result = createWorkspaceRelaunchPlan(".\\missing", context, {});
+    assert.equal(result.ok, false);
+    if (result.ok) return;
+    assert.match(result.message, /does not exist/i);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects relaunch targets that are files instead of directories", () => {
+  const root = createTempWorkspace();
+  try {
+    const fileTarget = join(root, "notes.txt");
+    writeFileSync(fileTarget, "hello", "utf8");
+    const context = resolveLaunchContext({
+      workspaceRoot: root,
+      packageRoot: root,
+      execPath: "C:/tools/bun.exe",
+      hasBunRuntime: true,
+      env: {},
+    });
+
+    const result = createWorkspaceRelaunchPlan(".\\notes.txt", context, {});
+    assert.equal(result.ok, false);
+    if (result.ok) return;
+    assert.match(result.message, /not a directory/i);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("blocks workspace relaunch while busy", () => {
+  assert.deepEqual(guardWorkspaceRelaunch(false), { allowed: true });
+  assert.equal(guardWorkspaceRelaunch(true).allowed, false);
+  assert.match(guardWorkspaceRelaunch(true).message ?? "", /finish the current run/i);
+});
+
+test("describes dev launch mode with install guidance", () => {
+  const message = buildWorkspaceStatusMessage(resolveLaunchContext({
+    workspaceRoot: "C:/repo",
+    packageRoot: "C:/repo",
+    execPath: "C:/tools/bun.exe",
+    hasBunRuntime: true,
+    env: {},
+  }));
+
+  assert.match(message, /Launch mode: dev\/repo launch/i);
+  assert.match(message, /npm link/i);
+  assert.match(message, /where codexa/i);
+  assert.match(message, /\/workspace relaunch <path>/i);
+});

package/src/core/launchContext.ts

@@ -0,0 +1,266 @@
+import { statSync } from "fs";
+import { basename, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { resolveWorkspacePath } from "./workspaceGuard.js";
+import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+
+export type LaunchKind = "installed-bin" | "dev-run";
+
+export interface LaunchContext {
+  workspaceRoot: string;
+  packageRoot: string;
+  launchKind: LaunchKind;
+  launcherScriptPath?: string;
+  relaunchExecutable: string;
+  relaunchArgs: string[];
+}
+
+export interface ResolveLaunchContextOptions {
+  env?: NodeJS.ProcessEnv;
+  workspaceRoot?: string;
+  packageRoot?: string;
+  execPath?: string;
+  hasBunRuntime?: boolean;
+  forwardArgs?: string[];
+}
+
+export interface WorkspaceCommandContext {
+  root: string;
+  summaryMessage: string;
+}
+
+export interface WorkspaceRelaunchPlan {
+  executable: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  targetWorkspaceRoot: string;
+}
+
+export type WorkspaceRelaunchPlanResult =
+  | { ok: true; plan: WorkspaceRelaunchPlan }
+  | { ok: false; message: string };
+
+const ENV_KEYS = {
+  workspaceRoot: "CODEX_WORKSPACE_ROOT",
+  launchKind: "CODEXA_LAUNCH_KIND",
+  packageRoot: "CODEXA_PACKAGE_ROOT",
+  launcherScript: "CODEXA_LAUNCHER_SCRIPT",
+  relaunchExecutable: "CODEXA_RELAUNCH_EXECUTABLE",
+  relaunchArgs: "CODEXA_RELAUNCH_ARGS",
+} as const;
+
+function getDefaultPackageRoot(): string {
+  return normalizeWorkspaceRoot(resolve(fileURLToPath(new URL(".", import.meta.url)), "..", ".."));
+}
+
+function parseRelaunchArgs(raw: string | undefined): string[] | null {
+  const value = raw?.trim();
+  if (!value) return null;
+
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
+      return null;
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function isBunExecutable(execPath: string): boolean {
+  return basename(execPath).toLowerCase().startsWith("bun");
+}
+
+function getDevRelaunchExecutable(execPath: string, hasBunRuntime: boolean): string {
+  if (hasBunRuntime || isBunExecutable(execPath)) {
+    return execPath;
+  }
+
+  return "bun";
+}
+
+function buildInstalledRelaunchArgs(launcherScriptPath: string, forwardArgs: readonly string[]): string[] {
+  return [launcherScriptPath, ...forwardArgs];
+}
+
+function buildDevRelaunchArgs(packageRoot: string, forwardArgs: readonly string[]): string[] {
+  const args = ["run", "--silent", join(packageRoot, "src", "index.tsx")];
+  if (forwardArgs.length > 0) {
+    args.push("--", ...forwardArgs);
+  }
+  return args;
+}
+
+export function resolveLaunchContext(options: ResolveLaunchContextOptions = {}): LaunchContext {
+  const env = options.env ?? process.env;
+  const workspaceRoot = normalizeWorkspaceRoot(
+    options.workspaceRoot ?? env[ENV_KEYS.workspaceRoot] ?? process.cwd(),
+  );
+  const packageRoot = normalizeWorkspaceRoot(
+    env[ENV_KEYS.packageRoot] ?? options.packageRoot ?? getDefaultPackageRoot(),
+  );
+  const launchKind = env[ENV_KEYS.launchKind] === "installed-bin" ? "installed-bin" : "dev-run";
+  const launcherScriptPath = env[ENV_KEYS.launcherScript]?.trim() || undefined;
+  const envRelaunchExecutable = env[ENV_KEYS.relaunchExecutable]?.trim();
+  const envRelaunchArgs = parseRelaunchArgs(env[ENV_KEYS.relaunchArgs]);
+  const execPath = options.execPath ?? process.execPath;
+  const hasBunRuntime = options.hasBunRuntime ?? Boolean(process.versions.bun);
+  const forwardArgs = options.forwardArgs ?? process.argv.slice(2);
+
+  if (launchKind === "installed-bin") {
+    const resolvedLauncherScript = launcherScriptPath ?? join(packageRoot, "bin", "codexa.js");
+
+    return {
+      workspaceRoot,
+      packageRoot,
+      launchKind,
+      launcherScriptPath: resolvedLauncherScript,
+      relaunchExecutable: envRelaunchExecutable || execPath,
+      relaunchArgs: envRelaunchArgs && envRelaunchArgs.length > 0
+        ? envRelaunchArgs
+        : buildInstalledRelaunchArgs(resolvedLauncherScript, forwardArgs),
+    };
+  }
+
+  return {
+    workspaceRoot,
+    packageRoot,
+    launchKind: "dev-run",
+    launcherScriptPath,
+    relaunchExecutable: envRelaunchExecutable || getDevRelaunchExecutable(execPath, hasBunRuntime),
+    relaunchArgs: envRelaunchArgs && envRelaunchArgs.length > 0
+      ? envRelaunchArgs
+      : buildDevRelaunchArgs(packageRoot, forwardArgs),
+  };
+}
+
+export function buildWorkspaceCommandContext(launchContext: LaunchContext): WorkspaceCommandContext {
+  return {
+    root: launchContext.workspaceRoot,
+    summaryMessage: buildWorkspaceStatusMessage(launchContext),
+  };
+}
+
+export function buildWorkspaceStatusMessage(launchContext: LaunchContext): string {
+  const lines = [
+    "Active workspace:",
+    `  ${launchContext.workspaceRoot}`,
+    "",
+    `Launch mode: ${launchContext.launchKind === "installed-bin" ? "installed codexa" : "dev/repo launch"}`,
+    "",
+  ];
+
+  if (launchContext.launchKind === "dev-run") {
+    lines.push(
+      "This session was started from a repo/dev launch, so the locked workspace follows that launch directory.",
+      "Recommended Windows setup:",
+      `  cd ${launchContext.packageRoot}`,
+      "  npm link",
+      "  where codexa",
+      "  cd <target-folder>",
+      "  codexa",
+      "",
+      "Quick recovery from here:",
+      "  /workspace relaunch <path>",
+    );
+  } else {
+    lines.push(
+      "This session is locked to the folder where you launched codexa.",
+      "Use /workspace relaunch <path> to restart into another folder from inside this UI.",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function buildDevLaunchNotice(launchContext: LaunchContext): string | null {
+  if (launchContext.launchKind !== "dev-run") {
+    return null;
+  }
+
+  return [
+    "This session was started from a repo/dev launch, so the locked workspace follows that launch directory.",
+    "Normal Windows flow:",
+    `  cd ${launchContext.packageRoot}`,
+    "  npm link",
+    "  where codexa",
+    "  cd <target-folder>",
+    "  codexa",
+    "",
+    "Recovery from this session:",
+    "  /workspace relaunch <path>",
+  ].join("\n");
+}
+
+export function guardWorkspaceRelaunch(busy: boolean): { allowed: boolean; message?: string } {
+  if (!busy) {
+    return { allowed: true };
+  }
+
+  return {
+    allowed: false,
+    message: "Finish the current run before relaunching into another workspace.",
+  };
+}
+
+function buildRelaunchEnv(
+  launchContext: LaunchContext,
+  targetWorkspaceRoot: string,
+  baseEnv: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  return {
+    ...baseEnv,
+    [ENV_KEYS.workspaceRoot]: targetWorkspaceRoot,
+    [ENV_KEYS.launchKind]: launchContext.launchKind,
+    [ENV_KEYS.packageRoot]: launchContext.packageRoot,
+    [ENV_KEYS.launcherScript]: launchContext.launcherScriptPath ?? "",
+    [ENV_KEYS.relaunchExecutable]: launchContext.relaunchExecutable,
+    [ENV_KEYS.relaunchArgs]: JSON.stringify(launchContext.relaunchArgs),
+  };
+}
+
+export function createWorkspaceRelaunchPlan(
+  targetInput: string,
+  launchContext: LaunchContext,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): WorkspaceRelaunchPlanResult {
+  const trimmedTarget = targetInput.trim();
+  if (!trimmedTarget) {
+    return { ok: false, message: "Usage: /workspace relaunch <path>" };
+  }
+
+  const targetWorkspaceRoot = normalizeWorkspaceRoot(
+    resolveWorkspacePath(trimmedTarget, launchContext.workspaceRoot),
+  );
+
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(targetWorkspaceRoot);
+  } catch {
+    return {
+      ok: false,
+      message: `Workspace relaunch failed: ${targetWorkspaceRoot} does not exist.`,
+    };
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      ok: false,
+      message: `Workspace relaunch failed: ${targetWorkspaceRoot} is not a directory.`,
+    };
+  }
+
+  return {
+    ok: true,
+    plan: {
+      executable: launchContext.relaunchExecutable,
+      args: launchContext.relaunchArgs,
+      cwd: targetWorkspaceRoot,
+      env: buildRelaunchEnv(launchContext, targetWorkspaceRoot, baseEnv),
+      targetWorkspaceRoot,
+    },
+  };
+}

package/src/core/models/codexCapabilities.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseCodexCliCapabilities } from "./codexCapabilities.js";
+
+test("detects exec help flags and strips ANSI noise", () => {
+  const capabilities = parseCodexCliCapabilities(
+    "\u001B[32mOptions:\u001B[0m\n  --ask-for-approval <policy>\n  --sandbox <mode>\n  -c, --config <key=value>\n",
+    "Global options:\n  --ask-for-approval <policy>\n",
+  );
+
+  assert.deepEqual(capabilities, {
+    askForApproval: true,
+    sandbox: true,
+    config: true,
+    fullAuto: false,
+  });
+});
+
+test("does not promote top-level approval flags into exec capabilities", () => {
+  const capabilities = parseCodexCliCapabilities(
+    "Usage: codex exec [OPTIONS]\n  --sandbox <mode>\n  --full-auto\n",
+    "Global options:\n  --ask-for-approval <policy>\n  --sandbox <mode>\n  --full-auto\n",
+  );
+
+  assert.deepEqual(capabilities, {
+    askForApproval: false,
+    sandbox: true,
+    config: false,
+    fullAuto: true,
+  });
+});
+
+test("requires exact option tokens instead of prose guesses", () => {
+  const capabilities = parseCodexCliCapabilities(
+    "This build documents ask-for-approval compatibility in prose only.\nIt also mentions sandbox_mode in config docs.\n",
+    "Use full auto mode for trusted environments.\n",
+  );
+
+  assert.deepEqual(capabilities, {
+    askForApproval: false,
+    sandbox: false,
+    config: false,
+    fullAuto: false,
+  });
+});

package/src/core/models/codexCapabilities.ts

@@ -0,0 +1,95 @@
+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;
+}
+
+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"),
+  };
+}
+
+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;
+  }
+}