@golba98/codexa 1.0.1 → 1.0.2

package/src/core/terminal/startupClear.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { performStartupClear } from "./startupClear.js";
+
+function makeCapture(): { written: string[]; write: (chunk: string) => boolean } {
+  const written: string[] = [];
+  return { written, write: (chunk) => { written.push(chunk); return true; } };
+}
+
+const TRANSCRIPT_CLEAR = "\x1b[2J\x1b[3J\x1b[H";
+
+test("emits full transcript clear in normal interactive mode", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: false, env: {} });
+  assert.deepEqual(cap.written, [TRANSCRIPT_CLEAR]);
+});
+
+test("skips clear when noClear flag is true (--no-clear)", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: true, env: {} });
+  assert.equal(cap.written.length, 0);
+});
+
+test("skips clear when CODEXA_NO_CLEAR=1 env var is set", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: false, env: { CODEXA_NO_CLEAR: "1" } });
+  assert.equal(cap.written.length, 0);
+});
+
+test("noClear flag takes precedence over unset env var", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: true, env: { CODEXA_NO_CLEAR: "0" } });
+  assert.equal(cap.written.length, 0);
+});
+
+test("emits clear when CODEXA_NO_CLEAR is not '1'", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: false, env: { CODEXA_NO_CLEAR: "0" } });
+  assert.deepEqual(cap.written, [TRANSCRIPT_CLEAR]);
+});
+
+test("emits clear when CODEXA_NO_CLEAR is undefined", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: false, env: { CODEXA_NO_CLEAR: undefined } });
+  assert.deepEqual(cap.written, [TRANSCRIPT_CLEAR]);
+});
+
+test("clear sequence includes viewport clear, scrollback clear, and cursor home", () => {
+  const cap = makeCapture();
+  performStartupClear({ write: cap.write, noClear: false, env: {} });
+  const seq = cap.written[0] ?? "";
+  assert.ok(seq.includes("\x1b[2J"), "must include viewport clear");
+  assert.ok(seq.includes("\x1b[3J"), "must include scrollback clear");
+  assert.ok(seq.includes("\x1b[H"), "must include cursor home");
+});

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");
+}

package/src/core/updateCheck.test.ts

@@ -0,0 +1,194 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  CODEXA_NPM_REGISTRY_URL,
+  CODEXA_UPDATE_COMMAND,
+  checkForUpdates,
+  compareSemver,
+  formatUpdateInstructions,
+  isNewerVersion,
+  type NpmRegistryMetadata,
+} from "./updateCheck.js";
+import { isCacheValid, type UpdateCheckCache } from "../config/updateCheckCache.js";
+
+function metadata(version: string): NpmRegistryMetadata {
+  return { "dist-tags": { latest: version } };
+}
+
+test("checkForUpdates returns update-available when installed version is lower than npm latest", async () => {
+  const result = await checkForUpdates(
+    {},
+    {
+      currentVersion: "1.0.1",
+      fetchNpmMetadataFn: async (url) => {
+        assert.equal(url, CODEXA_NPM_REGISTRY_URL);
+        return metadata("1.0.2");
+      },
+    },
+  );
+
+  assert.equal(result.status, "update-available");
+  assert.equal(result.currentVersion, "1.0.1");
+  assert.equal(result.latestVersion, "1.0.2");
+});
+
+test("checkForUpdates returns up-to-date when installed version equals npm latest", async () => {
+  const result = await checkForUpdates(
+    {},
+    {
+      currentVersion: "1.0.2",
+      fetchNpmMetadataFn: async () => metadata("1.0.2"),
+    },
+  );
+
+  assert.equal(result.status, "up-to-date");
+});
+
+test("checkForUpdates does not show update available when installed version is higher than npm latest", async () => {
+  const result = await checkForUpdates(
+    {},
+    {
+      currentVersion: "1.0.3",
+      fetchNpmMetadataFn: async () => metadata("1.0.2"),
+    },
+  );
+
+  assert.equal(result.status, "up-to-date");
+});
+
+test("checkForUpdates returns error status instead of throwing when npm request fails", async () => {
+  const result = await checkForUpdates(
+    {},
+    {
+      currentVersion: "1.0.1",
+      fetchNpmMetadataFn: async () => {
+        throw new Error("network unavailable");
+      },
+    },
+  );
+
+  assert.equal(result.status, "error");
+  assert.match(result.errorMessage ?? "", /network unavailable/);
+});
+
+test("checkForUpdates returns error when npm latest is missing", async () => {
+  const result = await checkForUpdates(
+    {},
+    {
+      currentVersion: "1.0.1",
+      fetchNpmMetadataFn: async () => ({ "dist-tags": {} }),
+    },
+  );
+
+  assert.equal(result.status, "error");
+  assert.match(result.errorMessage ?? "", /dist-tags\.latest/);
+});
+
+test("checkForUpdates returns unknown immediately when enabled=false", async () => {
+  let called = false;
+  const result = await checkForUpdates(
+    { enabled: false },
+    {
+      currentVersion: "1.0.1",
+      fetchNpmMetadataFn: async () => {
+        called = true;
+        return metadata("1.0.2");
+      },
+    },
+  );
+
+  assert.equal(result.status, "unknown");
+  assert.equal(called, false, "should not call npm when disabled");
+});
+
+test("semver comparison handles numeric and prerelease ordering", () => {
+  assert.equal(isNewerVersion("1.0.10", "1.0.2"), true);
+  assert.equal(isNewerVersion("1.0.2", "1.0.10"), false);
+  assert.equal(compareSemver("1.0.2", "1.0.2"), 0);
+  assert.equal(isNewerVersion("1.0.2", "1.0.2-beta.1"), true);
+  assert.equal(isNewerVersion("1.0.2-beta.1", "1.0.2"), false);
+});
+
+test("isCacheValid returns true when cache is within the interval", () => {
+  const cache: UpdateCheckCache = {
+    lastChecked: Date.now() - 1000 * 60 * 30,
+    currentVersion: "1.0.1",
+    latestVersion: "1.0.1",
+    updateAvailable: false,
+  };
+  assert.equal(isCacheValid(cache, 6), true);
+});
+
+test("isCacheValid returns false when cache is older than the interval", () => {
+  const cache: UpdateCheckCache = {
+    lastChecked: Date.now() - 1000 * 60 * 60 * 7,
+    currentVersion: "1.0.1",
+    latestVersion: "1.0.1",
+    updateAvailable: false,
+  };
+  assert.equal(isCacheValid(cache, 6), false);
+});
+
+test("formatUpdateInstructions formats update-available npm status", () => {
+  const result = formatUpdateInstructions({
+    status: "update-available",
+    currentVersion: "1.0.1",
+    latestVersion: "1.0.2",
+    checkedAt: Date.now(),
+  });
+
+  assert.match(result, /Current installed version: 1\.0\.1/);
+  assert.match(result, /npm latest version:\s+1\.0\.2/);
+  assert.match(result, /Update available: Codexa 1\.0\.2 is available\. You are using 1\.0\.1\./);
+  assert.match(result, new RegExp(`Run: ${CODEXA_UPDATE_COMMAND.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
+});
+
+test("formatUpdateInstructions formats up-to-date npm status", () => {
+  const result = formatUpdateInstructions({
+    status: "up-to-date",
+    currentVersion: "1.0.2",
+    latestVersion: "1.0.2",
+    checkedAt: Date.now(),
+  });
+
+  assert.match(result, /Already up to date/);
+  assert.match(result, /npm install -g @golba98\/codexa@latest/);
+});
+
+test("formatUpdateInstructions formats manual npm errors", () => {
+  const result = formatUpdateInstructions({
+    status: "error",
+    currentVersion: "1.0.1",
+    latestVersion: null,
+    errorMessage: "Connection timed out",
+    checkedAt: Date.now(),
+  });
+
+  assert.match(result, /Error checking npm update status: Connection timed out/);
+});
+
+test("/update check path bypasses cache by performing a fresh npm check", async () => {
+  const validCache: UpdateCheckCache = {
+    lastChecked: Date.now(),
+    currentVersion: "1.0.1",
+    latestVersion: "1.0.1",
+    updateAvailable: false,
+  };
+  assert.equal(isCacheValid(validCache, 6), true);
+
+  let calls = 0;
+  const result = await checkForUpdates(
+    { enabled: true },
+    {
+      currentVersion: validCache.currentVersion,
+      fetchNpmMetadataFn: async () => {
+        calls += 1;
+        return metadata("1.0.2");
+      },
+    },
+  );
+
+  assert.equal(calls, 1);
+  assert.equal(result.status, "update-available");
+  assert.equal(result.latestVersion, "1.0.2");
+});

package/src/core/updateCheck.ts

@@ -0,0 +1,172 @@
+import { APP_VERSION } from "../config/settings.js";
+
+export type UpdateStatus = "up-to-date" | "update-available" | "unknown" | "error";
+
+export interface UpdateCheckResult {
+  status: UpdateStatus;
+  currentVersion: string;
+  latestVersion: string | null;
+  errorMessage?: string;
+  checkedAt: number;
+}
+
+export interface NpmRegistryMetadata {
+  "dist-tags"?: {
+    latest?: unknown;
+  };
+}
+
+export interface UpdateCheckOverrides {
+  fetchNpmMetadataFn?: (url: string, init: RequestInit) => Promise<NpmRegistryMetadata>;
+  currentVersion?: string;
+  now?: () => number;
+}
+
+export const CODEXA_NPM_PACKAGE = "@golba98/codexa";
+export const CODEXA_NPM_REGISTRY_URL = "https://registry.npmjs.org/@golba98%2Fcodexa";
+export const CODEXA_UPDATE_COMMAND = "npm install -g @golba98/codexa@latest";
+
+const REMOTE_TIMEOUT_MS = 3000;
+
+interface ParsedSemver {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string[];
+}
+
+function parseSemver(version: string): ParsedSemver | null {
+  const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4]?.split(".") ?? [],
+  };
+}
+
+function comparePrerelease(left: string[], right: string[]): number {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+
+  const max = Math.max(left.length, right.length);
+  for (let index = 0; index < max; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined) return -1;
+    if (b === undefined) return 1;
+    if (a === b) continue;
+
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) return Number(a) > Number(b) ? 1 : -1;
+    if (aNumeric) return -1;
+    if (bNumeric) return 1;
+    return a > b ? 1 : -1;
+  }
+
+  return 0;
+}
+
+export function compareSemver(leftVersion: string, rightVersion: string): number {
+  const left = parseSemver(leftVersion);
+  const right = parseSemver(rightVersion);
+  if (!left || !right) {
+    throw new Error(`Invalid semver version: ${!left ? leftVersion : rightVersion}`);
+  }
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
+  }
+
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export function isNewerVersion(latestVersion: string, currentVersion: string): boolean {
+  return compareSemver(latestVersion, currentVersion) > 0;
+}
+
+async function fetchNpmMetadata(url: string, init: RequestInit): Promise<NpmRegistryMetadata> {
+  const res = await fetch(url, init);
+  if (!res.ok) {
+    throw new Error(`npm registry responded with HTTP ${res.status}`);
+  }
+  return await res.json() as NpmRegistryMetadata;
+}
+
+export async function getNpmLatestVersion(
+  fetchMetadata: (url: string, init: RequestInit) => Promise<NpmRegistryMetadata> = fetchNpmMetadata,
+): Promise<string> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REMOTE_TIMEOUT_MS);
+  try {
+    const data = await fetchMetadata(CODEXA_NPM_REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { "User-Agent": "Codexa-Update-Checker/1.0" },
+    });
+    const latest = data?.["dist-tags"]?.latest;
+    if (typeof latest !== "string" || !latest.trim()) {
+      throw new Error("npm registry response did not include dist-tags.latest");
+    }
+    return latest.trim();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function checkForUpdates(
+  opts?: { enabled?: boolean },
+  overrides?: UpdateCheckOverrides,
+): Promise<UpdateCheckResult> {
+  const now = overrides?.now ?? Date.now;
+  const currentVersion = overrides?.currentVersion ?? APP_VERSION;
+
+  if (opts?.enabled === false) {
+    return { status: "unknown", currentVersion, latestVersion: null, checkedAt: now() };
+  }
+
+  try {
+    const latestVersion = await getNpmLatestVersion(overrides?.fetchNpmMetadataFn);
+    return {
+      status: isNewerVersion(latestVersion, currentVersion) ? "update-available" : "up-to-date",
+      currentVersion,
+      latestVersion,
+      checkedAt: now(),
+    };
+  } catch (err) {
+    return {
+      status: "error",
+      currentVersion,
+      latestVersion: null,
+      errorMessage: err instanceof Error ? err.message : String(err),
+      checkedAt: now(),
+    };
+  }
+}
+
+export function formatUpdateInstructions(result: UpdateCheckResult | null): string {
+  const current = result?.currentVersion ?? APP_VERSION;
+  const latest = result?.latestVersion ?? "unknown";
+
+  let statusLine: string;
+  if (result?.status === "update-available" && result.latestVersion) {
+    statusLine = `Update available: Codexa ${result.latestVersion} is available. You are using ${current}.`;
+  } else if (result?.status === "up-to-date") {
+    statusLine = "Already up to date.";
+  } else if (result?.status === "error") {
+    statusLine = `Error checking npm update status: ${result.errorMessage || "unknown error"}`;
+  } else {
+    statusLine = "Status unknown - could not read npm latest version.";
+  }
+
+  return [
+    `Current installed version: ${current}`,
+    `npm latest version:       ${latest}`,
+    `Status:                   ${statusLine}`,
+    "",
+    `Run: ${CODEXA_UPDATE_COMMAND}`,
+  ].join("\n");
+}

package/src/headless/execArgs.ts

@@ -60,6 +60,7 @@ function buildLaunchArgs(params: {
     configOverrides: params.configOverrides,
     passthroughArgs: params.passthroughArgs,
     modelOverride: params.modelOverride,
+    noClear: false,
   };
 }
 

package/src/headless/execRunner.test.ts

@@ -21,6 +21,7 @@ function createLaunchArgs(): LaunchArgs {
     configOverrides: [],
     passthroughArgs: [],
     modelOverride: null,
+    noClear: false,
   };
 }
 
@@ -127,12 +128,13 @@ test("streams assistant deltas to stdout and progress/tool/error diagnostics to
     },
   );
 
-  assert.equal(result.exitCode, 0);
-  assert.equal(io.stdoutText(), "Hello world");
-  assert.match(io.stderrText(), /startup:/);
-  assert.match(io.stderrText(), /reasoning: thinking/);
-  assert.match(io.stderrText(), /tool: running: pwd/);
-});
+  assert.equal(result.exitCode, 0);
+  assert.equal(io.stdoutText(), "Hello world");
+  assert.doesNotMatch(`${io.stdoutText()}\n${io.stderrText()}`, /██████|Codexa v|Workspace:|Provider:|Context:/);
+  assert.match(io.stderrText(), /startup:/);
+  assert.match(io.stderrText(), /reasoning: thinking/);
+  assert.match(io.stderrText(), /tool: running: pwd/);
+});
 
 test("emits final_answer_observed timing before provider response settles", async () => {
   const io = createIo();