@golba98/codexa 1.0.1

package/src/core/workspaceGuard.ts

@@ -0,0 +1,288 @@
+import { posix, win32 } from "path";
+import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+
+type PathStyle = "windows" | "posix";
+
+export interface WorkspacePathViolation {
+  rawPath: string;
+  normalizedPath: string;
+}
+
+const QUOTED_ABSOLUTE_PATH_PATTERN =
+  /(["'`])((?:[A-Za-z]:[\\/]|\\\\[^\\/\r\n]+[\\/][^\\/\r\n]+[\\/]|\/)[^"'`\r\n]+?)\1/g;
+const QUOTED_RELATIVE_PATH_PATTERN = /(["'`])((?:\.\.?[\\/])[^"'`\r\n]+?)\1/g;
+const WINDOWS_DRIVE_PATH_PATTERN = /(?:^|[\s([{\],;=])([A-Za-z]:[\\/][^\s"'`<>|]+)/g;
+const WINDOWS_UNC_PATH_PATTERN =
+  /(?:^|[\s([{\],;=])(\\\\[^\\/\s"'`<>|]+[\\/][^\\/\s"'`<>|]+(?:[\\/][^\s"'`<>|]+)*)/g;
+const POSIX_ABSOLUTE_PATH_PATTERN = /(?:^|[\s([{\],;=])(\/(?:[^\/\s"'`<>|]+\/)+[^\s"'`<>|]+)/g;
+const RELATIVE_PATH_PATTERN = /(?:^|[\s([{\],;=])((?:\.\.?[\\/])(?:[^\s"'`<>|]+(?:[\\/][^\s"'`<>|]+)*))/g;
+const TRAILING_PUNCTUATION_PATTERN = /[),.;:\]}]+$/;
+const DIRECTORY_NAVIGATION_PATTERN = /(?:^|[;&\n]|&&|\|\|)\s*(cd|pushd|set-location)\b/i;
+
+function detectPathStyle(pathValue: string): PathStyle | null {
+  if (/^[A-Za-z]:[\\/]/.test(pathValue) || /^\\\\[^\\\/]+[\\\/][^\\\/]+/.test(pathValue)) {
+    return "windows";
+  }
+
+  if (pathValue.startsWith("/")) {
+    return "posix";
+  }
+
+  return null;
+}
+
+function getPathApi(style: PathStyle) {
+  return style === "windows" ? win32 : posix;
+}
+
+function stripWrappingQuotes(text: string): string {
+  return text.replace(/^["'`]|["'`]$/g, "");
+}
+
+function stripTrailingPunctuation(text: string): string {
+  return text.replace(TRAILING_PUNCTUATION_PATTERN, "");
+}
+
+function isExplicitRelativePath(pathValue: string): boolean {
+  return /^(?:\.\.?[\\/])/.test(pathValue);
+}
+
+function normalizeAbsolutePath(pathValue: string, style: PathStyle): string {
+  const pathApi = getPathApi(style);
+  const resolved = pathApi.normalize(pathApi.resolve(pathValue));
+  const { root } = pathApi.parse(resolved);
+
+  let normalized = resolved;
+  while (normalized.length > root.length && /[\\/]+$/.test(normalized)) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+function normalizeComparisonPath(pathValue: string, style: PathStyle): string {
+  const normalized = normalizeAbsolutePath(pathValue, style);
+  return style === "windows" ? normalized.toLowerCase() : normalized;
+}
+
+function normalizeAllowedRoots(workspaceRoot: string, allowedRoots: readonly string[] = []): string[] {
+  const normalizedWorkspace = normalizeWorkspaceRoot(workspaceRoot);
+  const roots = [normalizedWorkspace, ...allowedRoots];
+  const seen = new Set<string>();
+  const normalizedRoots: string[] = [];
+
+  for (const root of roots) {
+    const style = detectPathStyle(root);
+    if (!style) continue;
+    const normalizedRoot = normalizeAbsolutePath(root, style);
+    const comparisonKey = normalizeComparisonPath(normalizedRoot, style);
+    if (seen.has(comparisonKey)) continue;
+    seen.add(comparisonKey);
+    normalizedRoots.push(normalizedRoot);
+  }
+
+  return normalizedRoots;
+}
+
+export function resolveWorkspacePath(pathValue: string, workspaceRoot: string): string {
+  const trimmed = stripWrappingQuotes(pathValue.trim());
+  const workspaceStyle = detectPathStyle(workspaceRoot) ?? "windows";
+  const explicitStyle = detectPathStyle(trimmed);
+
+  if (explicitStyle) {
+    return normalizeAbsolutePath(trimmed, explicitStyle);
+  }
+
+  const pathApi = getPathApi(workspaceStyle);
+  // Normalize separators in relative paths to match the workspace style so
+  // that Windows-style backslashes work correctly on POSIX systems and vice versa.
+  const separatorNormalized = workspaceStyle === "windows"
+    ? trimmed.replace(/\//g, "\\")
+    : trimmed.replace(/\\/g, "/");
+  return normalizeAbsolutePath(pathApi.resolve(workspaceRoot, separatorNormalized), workspaceStyle);
+}
+
+export function isPathInsideWorkspace(pathValue: string, workspaceRoot: string): boolean {
+  const normalizedWorkspace = normalizeWorkspaceRoot(workspaceRoot);
+  return isPathInsideAllowedRoots(pathValue, normalizedWorkspace);
+}
+
+export function isPathInsideAllowedRoots(
+  pathValue: string,
+  workspaceRoot: string,
+  allowedRoots: readonly string[] = [],
+): boolean {
+  const normalizedWorkspace = normalizeWorkspaceRoot(workspaceRoot);
+  const normalizedRoots = normalizeAllowedRoots(normalizedWorkspace, allowedRoots);
+  const resolvedTarget = resolveWorkspacePath(pathValue, normalizedWorkspace);
+  const targetStyle = detectPathStyle(resolvedTarget);
+
+  if (!targetStyle) {
+    return false;
+  }
+
+  for (const root of normalizedRoots) {
+    const rootStyle = detectPathStyle(root);
+    if (!rootStyle || rootStyle !== targetStyle) {
+      continue;
+    }
+
+    const pathApi = getPathApi(rootStyle);
+    const rootForComparison = normalizeComparisonPath(root, rootStyle);
+    const targetForComparison = normalizeComparisonPath(resolvedTarget, rootStyle);
+    const relativePath = pathApi.relative(rootForComparison, targetForComparison);
+
+    if (
+      relativePath === "" ||
+      (!relativePath.startsWith("..") && !pathApi.isAbsolute(relativePath))
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function extractExplicitPathReferences(text: string): string[] {
+  const matches: string[] = [];
+  const seen = new Set<string>();
+
+  const addMatch = (candidate: string) => {
+    const cleaned = stripTrailingPunctuation(stripWrappingQuotes(candidate.trim()));
+    if (!cleaned || (!detectPathStyle(cleaned) && !isExplicitRelativePath(cleaned))) {
+      return;
+    }
+
+    const comparisonKey = detectPathStyle(cleaned) === "posix" ? cleaned : cleaned.toLowerCase();
+    if (seen.has(comparisonKey)) {
+      return;
+    }
+
+    seen.add(comparisonKey);
+    matches.push(cleaned);
+  };
+
+  for (const pattern of [
+    QUOTED_ABSOLUTE_PATH_PATTERN,
+    QUOTED_RELATIVE_PATH_PATTERN,
+    WINDOWS_DRIVE_PATH_PATTERN,
+    WINDOWS_UNC_PATH_PATTERN,
+    POSIX_ABSOLUTE_PATH_PATTERN,
+    RELATIVE_PATH_PATTERN,
+  ]) {
+    pattern.lastIndex = 0;
+    let match = pattern.exec(text);
+    while (match) {
+      addMatch(match[2] ?? match[1] ?? "");
+      match = pattern.exec(text);
+    }
+  }
+
+  return matches;
+}
+
+export function findOutsideWorkspacePaths(
+  text: string,
+  workspaceRoot: string,
+  allowedRoots: readonly string[] = [],
+): WorkspacePathViolation[] {
+  const violations: WorkspacePathViolation[] = [];
+  const seen = new Set<string>();
+  const workspaceStyle = detectPathStyle(workspaceRoot) ?? "windows";
+
+  for (const rawPath of extractExplicitPathReferences(text)) {
+    if (isPathInsideAllowedRoots(rawPath, workspaceRoot, allowedRoots)) {
+      continue;
+    }
+
+    const explicitStyle = detectPathStyle(rawPath) ?? workspaceStyle;
+    const normalizedPath = detectPathStyle(rawPath)
+      ? normalizeAbsolutePath(rawPath, explicitStyle)
+      : resolveWorkspacePath(rawPath, workspaceRoot);
+    const comparisonKey = explicitStyle === "windows" ? normalizedPath.toLowerCase() : normalizedPath;
+
+    if (seen.has(comparisonKey)) {
+      continue;
+    }
+
+    seen.add(comparisonKey);
+    violations.push({ rawPath, normalizedPath });
+  }
+
+  return violations;
+}
+
+export function containsDirectoryNavigationCommand(command: string): boolean {
+  return DIRECTORY_NAVIGATION_PATTERN.test(command);
+}
+
+function formatOutsidePathBlockMessage(
+  heading: string,
+  workspaceRoot: string,
+  violations: WorkspacePathViolation[],
+  allowedRoots: readonly string[] = [],
+): string {
+  const normalizedWorkspace = normalizeWorkspaceRoot(workspaceRoot);
+  const normalizedAllowedRoots = normalizeAllowedRoots(normalizedWorkspace, allowedRoots)
+    .filter((root) => normalizeComparisonPath(root, detectPathStyle(root) ?? "windows") !== normalizeComparisonPath(normalizedWorkspace, detectPathStyle(normalizedWorkspace) ?? "windows"));
+  const paths = violations.map((item) => `  - ${item.normalizedPath}`).join("\n");
+  const extraRootsBlock = normalizedAllowedRoots.length > 0
+    ? [
+      "Allowed writable roots:",
+      ...normalizedAllowedRoots.map((root) => `  - ${root}`),
+    ].join("\n")
+    : null;
+
+  return [
+    heading,
+    `Locked workspace: ${normalizedWorkspace}`,
+    extraRootsBlock,
+    "Outside path references:",
+    paths,
+    "Use relative paths inside this workspace, or relaunch the CLI from the folder you want to edit.",
+  ].filter(Boolean).join("\n");
+}
+
+export function getPromptWorkspaceGuardMessage(
+  prompt: string,
+  workspaceRoot: string,
+  allowedRoots: readonly string[] = [],
+): string | null {
+  const violations = findOutsideWorkspacePaths(prompt, workspaceRoot, allowedRoots);
+  if (violations.length === 0) {
+    return null;
+  }
+
+  return formatOutsidePathBlockMessage(
+    "Run blocked: this session can only work inside the locked workspace.",
+    workspaceRoot,
+    violations,
+    allowedRoots,
+  );
+}
+
+export function getShellWorkspaceGuardMessage(
+  command: string,
+  workspaceRoot: string,
+  allowedRoots: readonly string[] = [],
+): string | null {
+  if (containsDirectoryNavigationCommand(command)) {
+    return [
+      "Shell command blocked: this session is locked to the launch folder.",
+      `Locked workspace: ${normalizeWorkspaceRoot(workspaceRoot)}`,
+      "Directory-changing commands like cd, Set-Location, and pushd are disabled here.",
+    ].join("\n");
+  }
+
+  const violations = findOutsideWorkspacePaths(command, workspaceRoot, allowedRoots);
+  if (violations.length === 0) {
+    return null;
+  }
+
+  return formatOutsidePathBlockMessage(
+    "Shell command blocked: it references paths outside the locked workspace.",
+    workspaceRoot,
+    violations,
+    allowedRoots,
+  );
+}

package/src/core/workspaceRoot.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { normalizeWorkspaceRoot, resolveWorkspaceRoot } from "./workspaceRoot.js";
+
+test("prefers CODEX_WORKSPACE_ROOT when provided", () => {
+  const originalWorkspace = process.env.CODEX_WORKSPACE_ROOT;
+  try {
+    process.env.CODEX_WORKSPACE_ROOT = "D:/project/";
+    assert.equal(resolveWorkspaceRoot(), normalizeWorkspaceRoot("D:/project/"));
+  } finally {
+    process.env.CODEX_WORKSPACE_ROOT = originalWorkspace;
+  }
+});
+
+test("falls back to process.cwd when no workspace override exists", () => {
+  const originalWorkspace = process.env.CODEX_WORKSPACE_ROOT;
+  try {
+    delete process.env.CODEX_WORKSPACE_ROOT;
+    assert.equal(resolveWorkspaceRoot(), normalizeWorkspaceRoot(process.cwd()));
+  } finally {
+    process.env.CODEX_WORKSPACE_ROOT = originalWorkspace;
+  }
+});

package/src/core/workspaceRoot.ts

@@ -0,0 +1,47 @@
+import { parse, resolve, win32 } from "path";
+
+function isWindowsStylePath(p: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+
+export function normalizeWorkspaceRoot(pathValue: string): string {
+  let candidate = pathValue.trim();
+  // Guard against obviously unsafe values that could break command-line parsing.
+  if (candidate.includes("\n") || candidate.includes("\r") || candidate.includes("\0")) {
+    candidate = process.cwd();
+  }
+
+  if (isWindowsStylePath(candidate)) {
+    const resolved = win32.normalize(candidate);
+    const { root } = win32.parse(resolved);
+    let normalized = resolved;
+    while (normalized.length > root.length && /[\\/]+$/.test(normalized)) {
+      normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+  }
+
+  const resolved = resolve(candidate);
+  const { root } = parse(resolved);
+
+  let normalized = resolved;
+  while (normalized.length > root.length && /[\\/]+$/.test(normalized)) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+export function resolveWorkspaceRoot(): string {
+  const candidates = [
+    process.env.CODEX_WORKSPACE_ROOT,
+    process.cwd(),
+  ];
+
+  for (const candidate of candidates) {
+    const value = candidate?.trim();
+    if (value) return normalizeWorkspaceRoot(value);
+  }
+
+  return normalizeWorkspaceRoot(process.cwd());
+}

package/src/exec.test.ts

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+test("codexa exec entrypoint does not import interactive UI modules", () => {
+  const source = readFileSync(fileURLToPath(new URL("./exec.ts", import.meta.url)), "utf8");
+
+  assert.doesNotMatch(source, /from\s+["']\.\/index(?:\.js)?["']/);
+  assert.doesNotMatch(source, /from\s+["']\.\/app(?:\.js)?["']/);
+  assert.doesNotMatch(source, /from\s+["']ink["']/);
+  assert.doesNotMatch(source, /from\s+["']react["']/);
+});

package/src/exec.ts

@@ -0,0 +1,72 @@
+import { parseHeadlessExecArgs } from "./headless/execArgs.js";
+import {
+  createHeadlessExecTiming,
+  HEADLESS_EXEC_PARSE_ERROR,
+  runHeadlessExec,
+} from "./headless/execRunner.js";
+
+export function printExecHelp(): void {
+  console.log(`Usage:
+  codexa exec "prompt"
+  codexa exec --prompt "prompt"
+  codexa exec [--profile <name>] [-c key=value] "prompt"
+  codexa exec --model gpt-5.4-mini --reasoning medium "Reply with exactly: CODEXA_READY"
+
+Options:
+      --prompt <text>     Prompt to submit in headless mode.
+      --reasoning <effort>
+                          Reasoning effort: none, minimal, low, medium, high, xhigh.
+      --benchmark-diagnostics
+                          Alias for --timing.
+      --timing            Print optional codexa exec phase timing to stderr.
+      --codexa-prompt-policy <raw|wrapped>
+                          Prompt policy for exec mode. Defaults to raw.
+      --skip-git-repo-check
+                          Forward --skip-git-repo-check to codex exec.
+      --profile <name>    Load a Codex profile from config.
+  -m, --model <name>      Select the Codex model for this launch.
+  -c, --config <key=val>  Override a runtime config value.
+  -h, --help              Show this help text and exit.
+`);
+}
+
+const isMainModule = Boolean((import.meta as ImportMeta & { main?: boolean }).main);
+
+if (isMainModule) {
+  const argv = process.argv.slice(2);
+  const timing = createHeadlessExecTiming({
+    enabled: process.env.CODEXA_EXEC_TIMING === "1"
+      || argv.includes("--timing")
+      || argv.includes("--benchmark-diagnostics"),
+    stderr: process.stderr,
+    startTimeMs: Number(process.env.CODEXA_EXEC_TIMING_EPOCH_MS) || undefined,
+  });
+  timing.mark("codexa_exec_process_start", { pid: process.pid });
+
+  const parsed = parseHeadlessExecArgs(argv);
+  if (!parsed.ok) {
+    console.error(`[codexa exec] parse: ${parsed.error}`);
+    timing.mark("codexa_exec_process_exit", { exit_code: HEADLESS_EXEC_PARSE_ERROR });
+    process.exit(HEADLESS_EXEC_PARSE_ERROR);
+  }
+
+  timing.mark("args_parsed", {
+    prompt_character_count: parsed.value.prompt.length,
+    prompt_policy: parsed.value.promptPolicy,
+  });
+
+  if (parsed.value.help) {
+    printExecHelp();
+    timing.mark("codexa_exec_process_exit", { exit_code: 0 });
+    process.exit(0);
+  }
+
+  const result = await runHeadlessExec({
+    prompt: parsed.value.prompt,
+    launchArgs: parsed.value.launchArgs,
+    promptPolicy: parsed.value.promptPolicy,
+    benchmarkDiagnostics: (parsed.value.timing || process.env.CODEXA_EXEC_TIMING === "1") ? timing : undefined,
+  });
+  timing.mark("codexa_exec_process_exit", { exit_code: result.exitCode });
+  process.exit(result.exitCode);
+}

package/src/headless/execArgs.test.ts

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseHeadlessExecArgs } from "./execArgs.js";
+
+test("parses codexa exec positional prompt", () => {
+  const parsed = parseHeadlessExecArgs(["Print", "the", "directory"]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Print the directory");
+  assert.equal(parsed.value.promptPolicy, "raw");
+  assert.equal(parsed.value.launchArgs.initialPrompt, "Print the directory");
+});
+
+test("parses codexa exec --prompt value", () => {
+  const parsed = parseHeadlessExecArgs(["--prompt", "Print the directory"]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Print the directory");
+});
+
+test("parses codexa exec --prompt=value", () => {
+  const parsed = parseHeadlessExecArgs(["--prompt=Print the directory"]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Print the directory");
+});
+
+test("rejects missing and empty prompts", () => {
+  const missing = parseHeadlessExecArgs([]);
+  assert.equal(missing.ok, false);
+  if (!missing.ok) {
+    assert.match(missing.error, /missing prompt/i);
+  }
+
+  const empty = parseHeadlessExecArgs(["--prompt", "   "]);
+  assert.equal(empty.ok, false);
+  if (!empty.ok) {
+    assert.match(empty.error, /--prompt/i);
+  }
+});
+
+test("parses codexa exec --reasoning value", () => {
+  const parsed = parseHeadlessExecArgs(["--reasoning", "medium", "Print files"]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Print files");
+  assert.deepEqual(parsed.value.launchArgs.configOverrides, ["model_reasoning_effort=medium"]);
+  assert.deepEqual(parsed.value.launchArgs.passthroughArgs, ["--reasoning", "medium"]);
+});
+
+test("parses codexa exec --reasoning=value", () => {
+  const parsed = parseHeadlessExecArgs(["--reasoning=high", "Print files"]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Print files");
+  assert.deepEqual(parsed.value.launchArgs.configOverrides, ["model_reasoning_effort=high"]);
+  assert.deepEqual(parsed.value.launchArgs.passthroughArgs, ["--reasoning=high"]);
+});
+
+test("parses timing and prompt policy flags without forwarding them to Codex", () => {
+  const parsed = parseHeadlessExecArgs([
+    "--timing",
+    "--codexa-prompt-policy",
+    "wrapped",
+    "Print files",
+  ]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.timing, true);
+  assert.equal(parsed.value.promptPolicy, "wrapped");
+  assert.equal(parsed.value.prompt, "Print files");
+  assert.deepEqual(parsed.value.launchArgs.passthroughArgs, []);
+});
+
+test("rejects invalid prompt policy values", () => {
+  const parsed = parseHeadlessExecArgs(["--codexa-prompt-policy", "verbose", "Prompt"]);
+
+  assert.equal(parsed.ok, false);
+  if (!parsed.ok) {
+    assert.match(parsed.error, /codexa-prompt-policy/i);
+  }
+});
+
+test("parses codexa exec --model and --reasoning together", () => {
+  const parsed = parseHeadlessExecArgs([
+    "--model", "gpt-5.4-mini",
+    "--reasoning", "medium",
+    "Reply with exactly: CODEXA_READY",
+  ]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.prompt, "Reply with exactly: CODEXA_READY");
+  assert.deepEqual(parsed.value.launchArgs.configOverrides, [
+    "model=\"gpt-5.4-mini\"",
+    "model_reasoning_effort=medium",
+  ]);
+});
+
+test("preserves profile and repeated config overrides", () => {
+  const parsed = parseHeadlessExecArgs([
+    "--benchmark-diagnostics",
+    "--skip-git-repo-check",
+    "--profile",
+    "bench",
+    "--model",
+    "gpt-5.4-mini",
+    "-c",
+    "model_reasoning_effort=medium",
+    "--config",
+    "sandbox_mode=\"workspace-write\"",
+    "--config=approval_policy=\"never\"",
+    "Print",
+    "files",
+  ]);
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) return;
+  assert.equal(parsed.value.benchmarkDiagnostics, true);
+  assert.equal(parsed.value.timing, true);
+  assert.equal(parsed.value.prompt, "Print files");
+  assert.equal(parsed.value.launchArgs.profile, "bench");
+  assert.deepEqual(parsed.value.launchArgs.configOverrides, [
+    "model=\"gpt-5.4-mini\"",
+    "model_reasoning_effort=medium",
+    "sandbox_mode=\"workspace-write\"",
+    "approval_policy=\"never\"",
+  ]);
+  assert.deepEqual(parsed.value.launchArgs.passthroughArgs, [
+    "--skip-git-repo-check",
+    "--profile",
+    "bench",
+    "--model",
+    "gpt-5.4-mini",
+    "-c",
+    "model_reasoning_effort=medium",
+    "--config",
+    "sandbox_mode=\"workspace-write\"",
+    "--config=approval_policy=\"never\"",
+  ]);
+});