@golba98/codexa 1.0.3 → 1.0.5

package/src/core/terminal/frameLock.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isTerminalResizing } from "./terminalControl.js";
+
+export interface FrameLockOptions {
+  stdout: any;
+  env: Record<string, string | undefined>;
+}
+
+const resizeFrameCacheResetters = new WeakMap<object, () => void>();
+
+export function resetFrameLockForResize(stdout: object): void {
+  resizeFrameCacheResetters.get(stdout)?.();
+}
+
+/**
+ * Wraps the stdout stream to enforce frame-level deduplication, a flush lock,
+ * and width-safe row padding via ANSI clear-to-EOL (\x1b[K) injection.
+ */
+export function wrapStdoutWithFrameLock({
+  stdout,
+  env,
+}: FrameLockOptions) {
+  let lastFrame = "";
+  let isFlushing = false;
+  let debugLogStream: fs.WriteStream | null = null;
+
+  if (env.CODEXA_RENDER_DEBUG === "1") {
+    try {
+      const logPath = env.CODEXA_RENDER_DEBUG_FILE?.trim()
+        || path.join(process.cwd(), ".codexa", "debug", "render-status.log");
+      const logDir = path.dirname(logPath);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      debugLogStream = fs.createWriteStream(logPath, { flags: "a" });
+    } catch (e) {
+      // Gracefully fall back if logging fails (e.g. read-only filesystem)
+      void e;
+    }
+  }
+
+  const logDebug = (msg: string) => {
+    if (debugLogStream) {
+      debugLogStream.write(`${new Date().toISOString()} ${msg}\n`);
+    }
+  };
+
+  const originalWrite = stdout.write.bind(stdout);
+
+  // A terminal resize can make an otherwise identical Ink frame meaningful:
+  // rows reflow at a new width and height-driven spacer/layout changes must be
+  // written even when their source text did not change. src/index.tsx owns the
+  // single resize listener and invokes this reset through the exported helper.
+  resizeFrameCacheResetters.set(stdout, () => {
+    lastFrame = "";
+    logDebug("Frame cache reset: terminal resize");
+  });
+
+  stdout.write = (chunk: string | Uint8Array) => {
+    if (typeof chunk !== "string") {
+      return originalWrite(chunk);
+    }
+
+    // Task 7: Frame Lock
+    // Ensure only one render flush can write to stdout at a time.
+    if (isFlushing) {
+      logDebug("Frame dropped: lock active (concurrent flush)");
+      return true;
+    }
+
+    // Task 8: Full-frame Deduplication
+    // Skip if identical to last frame.
+    if (chunk === lastFrame) {
+      logDebug("Frame dropped: identical to last frame");
+      return true;
+    }
+
+    // Task 4: Width-Safe Injection
+    // Ensure every row clears to the end of the line. This fixes artifacts
+    // left behind when a shorter row replaces a longer row or when terminal
+    // wrapping occurs during resize.
+    //
+    // We inject \x1b[K before every newline and at the end of the frame.
+    // padding via \x1b[K injection.
+    // Only apply if the chunk is non-empty and doesn't look like a control-only 
+    // sequence (e.g. terminal title OSC).
+    let processed = chunk;
+    const isControlSequence = chunk.includes("\x1b]");
+    if (chunk.length > 0 && !isControlSequence) {
+      processed = chunk.replace(/\n/g, "\x1b[K\n");
+      if (!processed.endsWith("\x1b[K") && !processed.endsWith("\x1b[K\n")) {
+        processed += "\x1b[K";
+      }
+    }
+
+    isFlushing = true;
+    try {
+      lastFrame = chunk;
+      const resizing = isTerminalResizing();
+      logDebug(`Frame written: length=${processed.length} original=${chunk.length} resizing=${resizing}`);
+      return originalWrite(processed);
+    } finally {
+      isFlushing = false;
+    }
+  };
+
+  return stdout;
+}

package/src/core/terminal/inkRenderReset.ts

@@ -0,0 +1,123 @@
+import * as renderDebug from "../perf/renderDebug.js";
+
+/**
+ * Typed subset of the internal Ink class instance we reach into.
+ *
+ * `unsubscribeResize` is used at startup to disable Ink's competing resize
+ * handler (see src/index.tsx). The remaining fields are Ink's per-frame render
+ * caches; we reset them on the explicit /clear boundary so the next frame is
+ * written authoritatively from a clean baseline — exactly like the first frame
+ * after a cold startup — rather than diffed against pre-clear output.
+ *
+ * All fields are optional so the type also describes the minimal capability
+ * needed by callers that only disable resize, and so resolution degrades
+ * gracefully across Ink versions / test mocks.
+ */
+export interface InkRenderInstance {
+  unsubscribeResize?: () => void;
+  renderInteractiveFrame?: (output: string, outputHeight: number, staticOutput: string) => void;
+  lastOutput?: string;
+  lastOutputToRender?: string;
+  lastOutputHeight?: number;
+  lastTerminalWidth?: number;
+  fullStaticOutput?: string;
+  log?: { reset?: () => void };
+  throttledOnRender?: { cancel?: () => void };
+  throttledLog?: { cancel?: () => void };
+}
+
+export interface AppStdoutLike {
+  columns?: number;
+  rows?: number;
+}
+
+/**
+ * Resolve the real Ink class instance via Ink's internal WeakMap<stdout, Ink>.
+ * Returns null if resolution fails (e.g. different Ink version, test mocks).
+ *
+ * Bun doesn't resolve bare subpath imports like "ink/build/instances.js" so we
+ * resolve ink's main entry first, then derive the sibling path.
+ */
+export function resolveInkRenderInstance(stdout: object): InkRenderInstance | null {
+  try {
+    const { createRequire } = require("node:module");
+    const req = createRequire(import.meta.url);
+    const inkMain = req.resolve("ink");
+    const instancesPath = inkMain.replace(/index\.js$/, "instances.js");
+    const instances = req(instancesPath);
+    const weakMap: WeakMap<object, InkRenderInstance> =
+      instances.default ?? instances;
+    return weakMap.get(stdout) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export interface ResetInkOutputOptions {
+  instance: InkRenderInstance | null;
+  /** Current terminal column count, used to reseat lastTerminalWidth. */
+  columns?: number;
+}
+
+/**
+ * Reset Ink's render-state caches to the fresh-startup baseline.
+ *
+ * Call this immediately AFTER the terminal has been physically cleared (e.g. by
+ * terminalControl.clearTranscript on /clear) and BEFORE the post-clear React
+ * render commits. It mirrors what a brand-new Ink instance looks like at cold
+ * startup: empty frame caches and zero previous height, so the next frame is
+ * authoritative and the subsequent resize math (Ink's renderInteractiveFrame /
+ * shouldClearTerminalForFrame) is evaluated against truthful state.
+ *
+ * This does NOT emit any clear/erase escape sequences itself — the terminal is
+ * already physically cleared, and Ink's log.reset() zeroes log-update's
+ * accounting without writing. Returns false (graceful no-op) if no live Ink
+ * instance is available.
+ */
+export function resetInkOutputForFreshFrame({ instance, columns }: ResetInkOutputOptions): boolean {
+  if (!instance) {
+    renderDebug.traceEvent("terminal", "clearRenderReset", { instanceResolved: false });
+    return false;
+  }
+
+  const before = {
+    lastOutputLength: instance.lastOutput?.length ?? 0,
+    lastOutputToRenderLength: instance.lastOutputToRender?.length ?? 0,
+    lastOutputHeight: instance.lastOutputHeight ?? 0,
+    fullStaticOutputLength: instance.fullStaticOutput?.length ?? 0,
+    lastTerminalWidth: instance.lastTerminalWidth,
+  };
+
+  // Drop any pending throttled render/log so a stale pre-clear frame can't be
+  // flushed after we reset the caches.
+  instance.throttledOnRender?.cancel?.();
+  instance.throttledLog?.cancel?.();
+
+  // Zero log-update's previousOutput/previousLineCount WITHOUT emitting escape
+  // sequences (the terminal was already physically cleared).
+  instance.log?.reset?.();
+
+  // Reset Ink's frame caches to the constructor/startup state.
+  instance.lastOutput = "";
+  instance.lastOutputToRender = "";
+  instance.lastOutputHeight = 0;
+  instance.fullStaticOutput = "";
+  if (typeof columns === "number" && Number.isFinite(columns)) {
+    instance.lastTerminalWidth = columns;
+  }
+
+  renderDebug.traceEvent("terminal", "clearRenderReset", {
+    instanceResolved: true,
+    columns,
+    before,
+    after: {
+      lastOutputLength: instance.lastOutput.length,
+      lastOutputToRenderLength: instance.lastOutputToRender.length,
+      lastOutputHeight: instance.lastOutputHeight,
+      fullStaticOutputLength: instance.fullStaticOutput.length,
+      lastTerminalWidth: instance.lastTerminalWidth,
+    },
+  });
+
+  return true;
+}

package/src/core/terminal/terminalControl.ts

@@ -14,11 +14,24 @@ export const TERMINAL_SEQUENCES = {
   mouseEnable: "\x1b[?1000h\x1b[?1006h",
   mouseDisable: "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l",
   title: `\x1b]0;${TERMINAL_TITLE}\x07\x1b]2;${TERMINAL_TITLE}\x07`,
+  alternateScreenEnable: "\x1b[?1049h",
+  alternateScreenDisable: "\x1b[?1049l",
 } as const;
 
 export type TerminalWrite = (chunk: string) => boolean | void;
 export type TerminalChannel = "stdout" | "stderr";
 
+// Tracks whether the terminal is currently in a live resize debounce.
+let terminalResizing = false;
+
+export function setTerminalResizing(resizing: boolean): void {
+  terminalResizing = resizing;
+}
+
+export function isTerminalResizing(): boolean {
+  return terminalResizing;
+}
+
 // Tracks current UI state kind for diagnostic assertions.
 let currentUIStateKind: string = "IDLE";
 
@@ -107,12 +120,14 @@ export interface TerminalModeController {
   clearViewport(source: string): void;
   setMouseReporting(enabled: boolean, source: string): void;
   setBracketedPaste(enabled: boolean, source: string): void;
+  setAlternateScreen(enabled: boolean, source: string): void;
   resetModes(): void;
 }
 
 export function createTerminalModeController(write: TerminalWrite): TerminalModeController {
   let mouseReporting: boolean | null = null;
   let bracketedPaste: boolean | null = null;
+  let alternateScreen: boolean | null = null;
 
   const writeStdout = (sequence: string, source: string) =>
     writeTerminalControl(write, "stdout", source, sequence);
@@ -135,13 +150,20 @@ export function createTerminalModeController(write: TerminalWrite): TerminalMode
       bracketedPaste = enabled;
       writeStdout(enabled ? TERMINAL_SEQUENCES.bracketedPasteEnable : TERMINAL_SEQUENCES.bracketedPasteDisable, source);
     },
+    setAlternateScreen(enabled, source) {
+      if (alternateScreen === enabled) return;
+      alternateScreen = enabled;
+      writeStdout(enabled ? TERMINAL_SEQUENCES.alternateScreenEnable : TERMINAL_SEQUENCES.alternateScreenDisable, source);
+    },
     resetModes() {
       renderDebug.traceEvent("terminal", "resetModes", {
         mouseReporting,
         bracketedPaste,
+        alternateScreen,
       });
       mouseReporting = null;
       bracketedPaste = null;
+      alternateScreen = null;
     },
   };
 }

package/src/core/terminal/terminalTitle.ts

@@ -1,6 +1,7 @@
-import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
-import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import * as renderDebug from "../perf/renderDebug.js";
 
 export const DEFAULT_TERMINAL_TITLE = APP_NAME;
 
@@ -49,16 +50,17 @@ function findIncompleteOscTitleStart(text: string): number {
   return -1;
 }
 
-const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
-  || join(process.cwd(), ".codexa-debug", "terminal-title-debug.log");
+const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
+  || process.env["CODEXA_RENDER_DEBUG_FILE"]?.trim()
+  || join(process.cwd(), ".codexa", "debug", "render-status.log");
 
 let terminalTitleLifecycleState = "unknown";
 
-function debugLog(msg: string): void {
-  if (DEBUG_TERMINAL_TITLE) {
-    process.stderr.write(`[codexa:terminal-title] ${msg}\n`);
-  }
-}
+function debugLog(msg: string): void {
+  if (DEBUG_TERMINAL_TITLE) {
+    writeTerminalTitleDebugRecord({ event: "debug", message: msg });
+  }
+}
 
 function writeTerminalTitleDebugRecord(fields: Record<string, unknown>): void {
   if (!DEBUG_TERMINAL_TITLE) return;
@@ -144,8 +146,9 @@ export function writeCodexaTerminalTitle(title: string, options?: TerminalTitleO
 
   lastWrittenTerminalTitle = cleanTitle;
 
-  const sequence = buildTerminalTitleSequence(cleanTitle);
-  writeTerminalTitleDebugRecord({
+  const sequence = buildTerminalTitleSequence(cleanTitle);
+  renderDebug.traceTerminalWrite("stdout", `terminalTitle:${options?.reason ?? "unknown"}`, sequence);
+  writeTerminalTitleDebugRecord({
     event: "codexaTitleWrite",
     title: cleanTitle,
     reason: options?.reason ?? "unknown",
@@ -353,76 +356,7 @@ export function writeGuardedTerminalOutput(
   return write(safeText) !== false;
 }
 
-// ─── Startup guard ────────────────────────────────────────────────────────────
-
-/**
- * Schedules a sequence of title assertions to outlast Windows Terminal's
- * shell integration, which overwrites the process title at unpredictable
- * points during startup (shell prompt init, profile scripts, etc.).
- * The retries at 50/250/500/1000ms are intentional: no single delay is
- * reliable across all terminal configurations, so we assert multiple times.
- */
-export function beginColdStartSequence(title: string, options?: { write?: (chunk: string) => void }) {
-  setIntendedTerminalTitle(title, { force: true, write: options?.write, reason: "cold-start-immediate" });
-
-  const timers: ReturnType<typeof setTimeout>[] = [];
-  let cancelled = false;
-
-  const scheduleRetry = (delayMs: number) => {
-    const id = setTimeout(() => {
-      if (!cancelled) {
-        debugLog(`cold-start retry t=${delayMs}ms fired`);
-        reassertIntendedTerminalTitle({ write: options?.write, reason: `cold-start-retry-${delayMs}ms` });
-      }
-    }, delayMs);
-    timers.push(id);
-  };
-
-  scheduleRetry(50);
-  scheduleRetry(250);
-  scheduleRetry(500);
-  scheduleRetry(1000);
-
-  return () => {
-    cancelled = true;
-    timers.forEach(clearTimeout);
-    debugLog("cold-start sequence cancelled");
-  };
-}
-
-export function startTerminalTitleStartupGuard(options?: {
-  write?: (chunk: string) => void;
-  intervalMs?: number;
-  durationMs?: number;
-  reason?: string;
-}): () => void {
-  const intervalMs = options?.intervalMs ?? 150;
-  const durationMs = options?.durationMs ?? 3500;
-  const reason = options?.reason ?? "startup-guard";
-  let stopped = false;
-  const startedAt = Date.now();
-
-  reassertIntendedTerminalTitle({ write: options?.write, reason: `${reason}-start` });
-  const interval = setInterval(() => {
-    if (stopped) return;
-    if (Date.now() - startedAt >= durationMs) {
-      stopped = true;
-      clearInterval(interval);
-      reassertIntendedTerminalTitle({ write: options?.write, reason: `${reason}-end` });
-      return;
-    }
-    reassertIntendedTerminalTitle({ write: options?.write, reason });
-  }, intervalMs);
-  interval.unref?.();
-
-  return () => {
-    if (stopped) return;
-    stopped = true;
-    clearInterval(interval);
-  };
-}
-
-export function sanitizeTerminalTitle(title: string): string {
+export function sanitizeTerminalTitle(title: string): string {
   return title
     .replace(/[\u0000-\u001f\u007f]/g, " ")
     .replace(/\u001b/g, "")
@@ -461,23 +395,3 @@ export function reassertTerminalTitle(
   write(buildTerminalTitleSequence(title));
 }
 
-/**
- * Acquire a run-scoped title guard that immediately asserts the title,
- * reasserts it periodically while work is active, and emits one final
- * assertion when released.
- */
-export function acquireTerminalTitleGuard(
-  intervalMs = 250,
-  reassert: () => void = () => reassertTerminalTitle(),
-): () => void {
-  let released = false;
-  reassert();
-  const timer = setInterval(reassert, intervalMs);
-  timer.unref?.();
-  return () => {
-    if (released) return;
-    released = true;
-    clearInterval(timer);
-    reassert();
-  };
-}

package/src/core/{channel.ts → version/channel.ts}

@@ -1,4 +1,4 @@
-import { APP_VERSION } from "../config/settings.js";
+import { APP_VERSION } from "../../config/settings.js";
 
 export const CODEXA_CHANNEL_ENV = "CODEXA_CHANNEL";
 export const LOCAL_DEV_CHANNEL = "local-dev";

package/src/core/{updateCheck.ts → version/updateCheck.ts}

@@ -1,4 +1,4 @@
-import { APP_VERSION } from "../config/settings.js";
+import { APP_VERSION } from "../../config/settings.js";
 import { isLocalDevChannel } from "./channel.js";
 
 export const CODEXA_NPM_PACKAGE = "@golba98/codexa";
@@ -8,7 +8,7 @@ export const CODEXA_UPDATE_COMMAND = `npm install -g ${CODEXA_NPM_PACKAGE}@lates
 export type UpdateStatus = "up-to-date" | "update-available" | "unknown" | "error";
 
 export interface NpmRegistryMetadata {
-  "dist-tags": { latest?: string };
+  "dist-tags"?: { latest?: unknown };
 }
 
 export interface UpdateCheckResult {
@@ -27,6 +27,11 @@ export function normalizeVersion(v: string): string {
   return v.startsWith("v") ? v.slice(1) : v;
 }
 
+export function formatVersionLabel(version: string): string {
+  const normalized = normalizeVersion(version.trim());
+  return normalized ? `v${normalized}` : version;
+}
+
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
 
 /** Returns true for valid semver strings with or without a leading "v". */
@@ -111,7 +116,7 @@ export async function checkForUpdates(
     const metadata = await fetchFn(CODEXA_NPM_REGISTRY_URL);
     const rawLatest = metadata["dist-tags"]?.latest;
 
-    if (!rawLatest) {
+    if (typeof rawLatest !== "string" || !rawLatest.trim()) {
       return {
         status: "error",
         currentVersion,
@@ -122,7 +127,7 @@ export async function checkForUpdates(
       };
     }
 
-    const latestVersion = normalizeVersion(rawLatest);
+    const latestVersion = normalizeVersion(rawLatest.trim());
 
     if (!isValidSemver(latestVersion) || !isValidSemver(currentVersion)) {
       return {
@@ -163,7 +168,7 @@ export function formatUpdateInstructions(result: UpdateCheckResult | null): stri
 
   let statusLine: string;
   if (result?.status === "update-available" && result.latestVersion) {
-    statusLine = `Update available: Codexa ${result.latestVersion} is available. You are using ${current}.`;
+    statusLine = `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`;
   } else if (result?.status === "up-to-date") {
     statusLine = "Already up to date.";
   } else {

package/src/core/{launchContext.ts → workspace/launchContext.ts}

@@ -3,7 +3,7 @@ import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { resolveWorkspacePath } from "./workspaceGuard.js";
 import { normalizeWorkspaceRoot } from "./workspaceRoot.js";
-import { CODEXA_CHANNEL_ENV, LOCAL_DEV_CHANNEL, isLocalDevChannel } from "./channel.js";
+import { CODEXA_CHANNEL_ENV, LOCAL_DEV_CHANNEL, isLocalDevChannel } from "../version/channel.js";
 
 export type LaunchKind = "installed-bin" | "dev-run";
 
@@ -177,22 +177,15 @@ export function buildWorkspaceStatusMessage(launchContext: LaunchContext): strin
 }
 
 export function buildDevLaunchNotice(launchContext: LaunchContext): string | null {
-  if (launchContext.launchKind !== "dev-run") {
-    return null;
-  }
-
+  if (launchContext.launchKind !== "dev-run") {
+    return null;
+  }
+
   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");
-}
+    "Ready. Type a prompt, run !shell, or use /command.",
+    "Tip: /workspace relaunch <path>",
+  ].join("\n");
+}
 
 export function guardWorkspaceRelaunch(busy: boolean): { allowed: boolean; message?: string } {
   if (!busy) {

package/src/core/{planStorage.ts → workspace/planStorage.ts}

@@ -2,8 +2,8 @@ import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-import { isNoiseLine } from "./providers/codexTranscript.js";
-import { sanitizeTerminalOutput } from "./terminal/terminalSanitize.js";
+import { isNoiseLine } from "../providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
 
 type Platform = "win32" | "darwin" | "linux" | string;