@golba98/codexa 1.0.1 → 1.0.3

package/src/config/updateCheckCache.ts

@@ -0,0 +1,63 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+export interface UpdateCheckCache {
+  lastChecked: number;
+  currentVersion: string;
+  latestVersion: string | null;
+  updateAvailable: boolean;
+}
+
+const CACHE_FILE = join(homedir(), ".codexa-update-check.json");
+
+export function loadUpdateCheckCache(): UpdateCheckCache | null {
+  try {
+    const text = readFileSync(CACHE_FILE, "utf-8");
+    const data = JSON.parse(text) as Record<string, unknown>;
+    if (typeof data.lastChecked !== "number") return null;
+    if (typeof data.currentVersion !== "string") return null;
+    return {
+      lastChecked: data.lastChecked,
+      currentVersion: data.currentVersion,
+      latestVersion: typeof data.latestVersion === "string" ? data.latestVersion : null,
+      updateAvailable: data.updateAvailable === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveUpdateCheckCache(cache: UpdateCheckCache): void {
+  try {
+    mkdirSync(dirname(CACHE_FILE), { recursive: true });
+    const tmp = `${CACHE_FILE}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache, null, 2), "utf-8");
+    renameSync(tmp, CACHE_FILE);
+  } catch {
+    // Best-effort — never crash on cache write failure.
+  }
+}
+
+function stripV(v: string): string {
+  return v.startsWith("v") ? v.slice(1) : v;
+}
+
+/**
+ * Returns true only when the cache is still usable:
+ * - `runningVersion` matches the version the cache was written for (version-mismatch = stale)
+ * - The cache was written within `intervalHours`
+ */
+export function isCacheValid(
+  cache: UpdateCheckCache,
+  intervalHours: number,
+  runningVersion?: string,
+): boolean {
+  if (runningVersion !== undefined) {
+    if (stripV(cache.currentVersion) !== stripV(runningVersion)) {
+      return false;
+    }
+  }
+  const maxAgeMs = intervalHours * 60 * 60 * 1000;
+  return Date.now() - cache.lastChecked < maxAgeMs;
+}

package/src/core/channel.ts

@@ -0,0 +1,23 @@
+import { APP_VERSION } from "../config/settings.js";
+
+export const CODEXA_CHANNEL_ENV = "CODEXA_CHANNEL";
+export const LOCAL_DEV_CHANNEL = "local-dev";
+
+export function getCodexaChannel(env: NodeJS.ProcessEnv = process.env): string {
+  return env[CODEXA_CHANNEL_ENV]?.trim() || "published";
+}
+
+export function isLocalDevChannel(env: NodeJS.ProcessEnv = process.env): boolean {
+  return getCodexaChannel(env) === LOCAL_DEV_CHANNEL;
+}
+
+export function formatCodexaVersionLabel(
+  version: string = APP_VERSION,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return isLocalDevChannel(env) ? `${version}-dev local` : version;
+}
+
+export function formatCodexaBrandLabel(env: NodeJS.ProcessEnv = process.env): string {
+  return `Codexa v${formatCodexaVersionLabel(APP_VERSION, env)}`;
+}

package/src/core/executables/codexExecutable.ts

@@ -101,6 +101,7 @@ export function spawnCodexProcess(
   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 });
 }
 

package/src/core/executables/executableResolver.ts

@@ -21,18 +21,27 @@ export interface ExecutableResolverOptions {
   requireResolvedFile?: boolean;
 }
 
-function validateConfiguredExecutable(value: string, label: string, cwd: string): string {
-  return normalizeExecutableValue(value, {
+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,
+  });
+}
+
+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> {
@@ -47,13 +56,19 @@ async function resolveWithWhere(
   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;
-}
+    .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.
@@ -98,41 +113,44 @@ export async function resolveExecutable(options: ExecutableResolverOptions): Pro
       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;
-  }
+    }
+
+    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 bareName!;
-}
+  // 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.
  */
-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 };
-}
+export function buildSpawnSpec(
+  executable: string,
+  args: string[],
+): { executable: string; args: string[] } {
+  const validatedExecutable = validateResolvedExecutable(executable, "Executable", process.cwd());
+  if (process.platform === "win32") {
+    const lower = validatedExecutable.toLowerCase();
+    if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+      validateWindowsBatchExecutableForCmd(validatedExecutable, "Windows batch executable");
+      return { executable: "cmd.exe", args: ["/d", "/s", "/c", "call", validatedExecutable, ...args] };
+    }
+  }
+  return { executable: validatedExecutable, args };
+}

package/src/core/launchContext.ts

@@ -1,8 +1,9 @@
 import { statSync } from "fs";
 import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { resolveWorkspacePath } from "./workspaceGuard.js";
-import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+import { resolveWorkspacePath } from "./workspaceGuard.js";
+import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
+import { CODEXA_CHANNEL_ENV, LOCAL_DEV_CHANNEL, isLocalDevChannel } from "./channel.js";
 
 export type LaunchKind = "installed-bin" | "dev-run";
 
@@ -46,9 +47,9 @@ const ENV_KEYS = {
   launchKind: "CODEXA_LAUNCH_KIND",
   packageRoot: "CODEXA_PACKAGE_ROOT",
   launcherScript: "CODEXA_LAUNCHER_SCRIPT",
-  relaunchExecutable: "CODEXA_RELAUNCH_EXECUTABLE",
-  relaunchArgs: "CODEXA_RELAUNCH_ARGS",
-} as const;
+  relaunchExecutable: "CODEXA_RELAUNCH_EXECUTABLE",
+  relaunchArgs: "CODEXA_RELAUNCH_ARGS",
+} as const;
 
 function getDefaultPackageRoot(): string {
   return normalizeWorkspaceRoot(resolve(fileURLToPath(new URL(".", import.meta.url)), "..", ".."));
@@ -153,18 +154,17 @@ export function buildWorkspaceStatusMessage(launchContext: LaunchContext): strin
     "",
   ];
 
-  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>",
+  if (launchContext.launchKind === "dev-run") {
+    lines.push(
+      "This session was started from a local dev launch.",
+      "Recommended setup:",
+      "  npm run install:dev-bin",
+      "  which codexa-dev",
+      "  cd <target-folder>",
+      "  codexa-dev",
+      "",
+      "Quick recovery from here:",
+      "  /workspace relaunch <path>",
     );
   } else {
     lines.push(
@@ -181,17 +181,16 @@ export function buildDevLaunchNotice(launchContext: LaunchContext): string | nul
     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>",
+  return [
+    "This session was started from local-dev Codexa.",
+    "Normal flow:",
+    "  npm run install:dev-bin",
+    "  which codexa-dev",
+    "  cd <target-folder>",
+    "  codexa-dev",
+    "",
+    "Recovery from this session:",
+    "  /workspace relaunch <path>",
   ].join("\n");
 }
 
@@ -216,11 +215,12 @@ function buildRelaunchEnv(
     [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),
-  };
-}
+    [ENV_KEYS.launcherScript]: launchContext.launcherScriptPath ?? "",
+    [ENV_KEYS.relaunchExecutable]: launchContext.relaunchExecutable,
+    [ENV_KEYS.relaunchArgs]: JSON.stringify(launchContext.relaunchArgs),
+    [CODEXA_CHANNEL_ENV]: isLocalDevChannel(baseEnv) ? LOCAL_DEV_CHANNEL : baseEnv[CODEXA_CHANNEL_ENV],
+  };
+}
 
 export function createWorkspaceRelaunchPlan(
   targetInput: string,

package/src/core/process/processValidation.ts

@@ -23,10 +23,14 @@ function stripBalancedWrappingQuotes(value: string): string {
   return value;
 }
 
-function looksLikePath(value: string): boolean {
-  return /[\\/]/.test(value) || /^[A-Za-z]:/.test(value);
-}
-
+function looksLikePath(value: string): boolean {
+  return /[\\/]/.test(value) || /^[A-Za-z]:/.test(value);
+}
+
+function isWindowsAbsolutePath(value: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(value);
+}
+
 function hasWindowsBatchExtension(value: string): boolean {
   return /\.(?:cmd|bat)$/i.test(value);
 }
@@ -67,7 +71,7 @@ export function normalizeExecutableValue(
     return trimmed;
   }
 
-  const normalized = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd, trimmed);
+  const normalized = isAbsolute(trimmed) || isWindowsAbsolutePath(trimmed) ? trimmed : resolve(cwd, trimmed);
   validateCommonExecutableSyntax(normalized, options.label);
 
   if (requireExistingPath && !existsSync(normalized)) {

package/src/core/providerLauncher/launcher.ts

@@ -1,8 +1,9 @@
-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";
+import { spawn, type ChildProcess } from "child_process";
+import { accessSync, constants, existsSync } from "fs";
+import { delimiter, join } from "path";
+import { buildSpawnSpec } from "../executables/executableResolver.js";
+import { normalizeExecutableValue } from "../process/processValidation.js";
+import type { ProviderConfig, ProviderLaunchCommand } from "./types.js";
 
 export interface ProviderLaunchSpec {
   executable: string;
@@ -75,43 +76,55 @@ function setRawMode(stdin: RawModeStream | null | undefined, enabled: boolean):
   }
 }
 
-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 executableLooksLikePath(executable: string): boolean {
+  return /[\\/]/.test(executable) || /^[A-Za-z]:/.test(executable);
+}
+
+function canAccessExecutable(path: string): boolean {
+  try {
+    if (process.platform === "win32") {
+      return existsSync(path);
+    }
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPathExecutableCandidates(executable: string): string[] {
+  if (process.platform !== "win32" || /\.[A-Za-z0-9_-]+$/.test(executable)) {
+    return [executable];
+  }
+
+  const pathExt = process.env.PATHEXT?.split(";").filter(Boolean) ?? [".COM", ".EXE", ".BAT", ".CMD"];
+  return [executable, ...pathExt.map((ext) => `${executable}${ext.toLowerCase()}`)];
+}
+
+export async function commandExistsOnPath(executable: string): Promise<boolean> {
+  let candidate: string;
+  try {
+    candidate = normalizeExecutableValue(executable, {
+      label: "Provider launch command",
+      allowBareExecutable: true,
+    });
+  } catch {
+    return false;
+  }
+
+  const trimmed = candidate.trim();
+  if (executableLooksLikePath(trimmed)) {
+    return canAccessExecutable(trimmed);
+  }
+
+  const pathEntries = process.env.PATH?.split(delimiter).filter(Boolean) ?? [];
+  for (const dir of pathEntries) {
+    for (const name of getPathExecutableCandidates(trimmed)) {
+      if (canAccessExecutable(join(dir, name))) return true;
+    }
+  }
+  return false;
+}
 
 function formatSpawnError(provider: ProviderConfig, executable: string, error: NodeJS.ErrnoException): ProviderLaunchResult {
   if (error.code === "ENOENT") {
@@ -162,6 +175,10 @@ export async function launchProviderCli(
       let child: ChildProcess;
       try {
         const spawnSpec = buildSpawnSpec(spec.executable, spec.args);
+        if (!spawnSpec.executable) {
+          resolve({ status: "spawn-error", message: "Executable path is empty after resolution." });
+          return;
+        }
         child = spawnImpl(spawnSpec.executable, spawnSpec.args, {
           cwd: spec.cwd,
           shell: false,

package/src/core/terminal/startupClear.ts

@@ -0,0 +1,20 @@
+export interface StartupClearOptions {
+  write: (chunk: string) => boolean | void;
+  /** True when --no-clear was passed on the CLI. */
+  noClear: boolean;
+  env: Record<string, string | undefined>;
+}
+
+/**
+ * Writes a full terminal clear (viewport + scrollback + cursor home) to stdout
+ * before the first Ink render. Skipped when --no-clear or CODEXA_NO_CLEAR=1.
+ *
+ * Only call this from startApp() in TTY mode — never inside render loops.
+ */
+export function performStartupClear(options: StartupClearOptions): void {
+  if (options.noClear || options.env["CODEXA_NO_CLEAR"] === "1") return;
+  // \x1b[2J: clear visible viewport
+  // \x1b[3J: clear scrollback buffer
+  // \x1b[H:  move cursor to top-left
+  options.write("\x1b[2J\x1b[3J\x1b[H");
+}