@iislee/opencodex 2.11.0

package/src/update/notify.ts

@@ -0,0 +1,257 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { atomicWriteFile, getConfigDir } from "../config";
+import { hasStarPromptRun } from "../cli/star-prompt";
+import {
+  type Channel,
+  currentVersion,
+  detectInstall,
+  latestVersion,
+  runUpdate,
+  updateCommandStr,
+  updateTag,
+} from "./index";
+
+const VERSION_FILENAME = "version.json";
+const REFRESH_INTERVAL_MS = 20 * 60 * 60 * 1000; // 20h, matching codex-rs
+const RELEASE_NOTES_URL = "https://github.com/lidge-jun/opencodex/releases/latest";
+
+export interface VersionCache {
+  latest_version: string;
+  /** ISO-8601 (RFC3339) timestamp of the last successful registry check. */
+  last_checked_at: string;
+  dismissed_version?: string;
+  tag: Channel;
+}
+
+function versionFilePath(): string {
+  return join(getConfigDir(), VERSION_FILENAME);
+}
+
+/**
+ * Read the cached version info. Returns null on any error or when the cached
+ * channel differs from the current one (so a stable<->preview switch re-fetches
+ * instead of comparing across channels).
+ */
+export function readVersionCache(channel: Channel): VersionCache | null {
+  try {
+    const raw = readFileSync(versionFilePath(), "utf8");
+    const parsed = JSON.parse(raw) as Partial<VersionCache>;
+    if (typeof parsed.latest_version !== "string" || typeof parsed.last_checked_at !== "string") return null;
+    if (parsed.tag !== channel) return null;
+    return {
+      latest_version: parsed.latest_version,
+      last_checked_at: parsed.last_checked_at,
+      dismissed_version: typeof parsed.dismissed_version === "string" ? parsed.dismissed_version : undefined,
+      tag: parsed.tag,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeVersionCache(cache: VersionCache): void {
+  try {
+    atomicWriteFile(versionFilePath(), `${JSON.stringify(cache)}\n`);
+  } catch {
+    /* best-effort; never block startup */
+  }
+}
+
+function parseStable(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function parsePreview(v: string): [number, number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)-preview\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+}
+
+function gt(a: number[], b: number[]): boolean {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av !== bv) return av > bv;
+  }
+  return false;
+}
+
+/**
+ * Channel-aware "is latest newer than current?".
+ * - latest channel: compare maj.min.pat only; prereleases are never "newer"
+ *   (parity with codex-rs), so stable users are not pushed onto previews.
+ * - preview channel: preview-vs-preview compares the trailing -preview.N; a
+ *   stable release with a strictly higher base counts as newer (O3), while a
+ *   stable release with the same base as the current preview does not.
+ */
+export function isNewer(latest: string, current: string, channel: Channel): boolean {
+  if (channel === "latest") {
+    const l = parseStable(latest);
+    const c = parseStable(current);
+    if (!l || !c) return false;
+    return gt(l, c);
+  }
+  // preview channel
+  const lPre = parsePreview(latest);
+  const cPre = parsePreview(current);
+  if (lPre && cPre) return gt(lPre, cPre);
+
+  const lStable = parseStable(latest);
+  if (lStable && cPre) {
+    // Stable release vs current preview: newer only if the base is strictly
+    // higher than the preview's base (equal base would be a downgrade nag).
+    return gt(lStable, [cPre[0], cPre[1], cPre[2]]);
+  }
+  const cStable = parseStable(current);
+  if (lStable && cStable) return gt(lStable, cStable);
+  return false;
+}
+
+export function isSourceBuildVersion(v: string): boolean {
+  return v.trim() === "0.0.0";
+}
+
+/** The interactive/TTY + install-method gate shared with the star prompt. */
+function interactiveGuardOk(): boolean {
+  return !(process.env.OCX_SERVICE || !process.stdin.isTTY || !process.stdout.isTTY);
+}
+
+/**
+ * Decide whether this run should even consider showing the prompt. Returns the
+ * channel + current version when eligible, else null. Eligibility requires a
+ * real global install, a non-source version, the interactive guard, and that
+ * the one-time star prompt has already run (first-run yield, O1).
+ */
+export function shouldConsider(): { channel: Channel; current: string } | null {
+  if (detectInstall() === "source") return null;
+  const current = currentVersion();
+  if (current === "?" || isSourceBuildVersion(current)) return null;
+  if (!interactiveGuardOk()) return null;
+  if (!hasStarPromptRun()) return null; // yield on the very first run
+  return { channel: updateTag(current), current };
+}
+
+/** The cached upgrade version to surface, honoring the user's dismissal. */
+export function getUpgradeVersionForPopup(
+  cache: VersionCache | null,
+  current: string,
+  channel: Channel,
+): string | null {
+  if (!cache) return null;
+  if (!isNewer(cache.latest_version, current, channel)) return null;
+  if (cache.dismissed_version === cache.latest_version) return null;
+  return cache.latest_version;
+}
+
+function cacheIsStale(cache: VersionCache | null): boolean {
+  if (!cache) return true;
+  const checked = Date.parse(cache.last_checked_at);
+  if (!Number.isFinite(checked)) return true;
+  return Date.now() - checked > REFRESH_INTERVAL_MS;
+}
+
+/**
+ * If the cache is missing or older than 20h, kick off a detached helper to
+ * refresh it without blocking this (soon-to-be daemon) process. Fire-and-forget.
+ */
+export function triggerBackgroundRefreshIfStale(channel: Channel, cache: VersionCache | null): void {
+  if (!cacheIsStale(cache)) return;
+  try {
+    const entry = process.argv[1];
+    if (!entry || !existsSync(entry)) return;
+    const child = spawn(process.execPath, [entry, "__refresh-version", channel], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: { ...process.env, OCX_SERVICE: "1" }, // never let the helper prompt
+    });
+    child.unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Body of the hidden `__refresh-version` subcommand: fetch the latest version
+ * for the channel and persist it. Only advances `last_checked_at` on success so
+ * a failed fetch retries on the next start.
+ */
+export async function refreshVersionCache(channel: Channel): Promise<void> {
+  const latest = latestVersion(channel);
+  if (!latest) return; // do not dirty the cache or advance the timestamp
+  const prev = readVersionCache(channel);
+  writeVersionCache({
+    latest_version: latest,
+    last_checked_at: new Date().toISOString(),
+    dismissed_version: prev?.dismissed_version,
+    tag: channel,
+  });
+}
+
+/** Persist a dismissal so this exact version stops prompting. */
+function dismissVersion(channel: Channel, version: string): void {
+  const cache = readVersionCache(channel);
+  if (!cache) return;
+  writeVersionCache({ ...cache, dismissed_version: version });
+}
+
+function renderPrompt(current: string, latest: string, channel: Channel): string {
+  const command = updateCommandStr(detectInstall(), channel);
+  return [
+    "",
+    `  \x1b[38;5;141m✨ Update available!\x1b[0m  \x1b[2m${current} -> ${latest}\x1b[0m`,
+    "",
+    `  \x1b[2mRelease notes:\x1b[0m ${RELEASE_NOTES_URL}`,
+    "",
+    `  1) Update now (runs \`${command}\`)`,
+    "  2) Skip",
+    "  3) Skip until next version",
+    "",
+    "  [1/2/3] (default 1): ",
+  ].join("\n");
+}
+
+/**
+ * Interactive-only update prompt for `ocx start`. Must be called BEFORE the
+ * server binds a port / writes a PID, because "Update now" installs globally
+ * and exits. No-op for service/daemon/non-TTY runs and source checkouts.
+ * Never throws.
+ */
+export async function maybeShowUpdatePrompt(): Promise<void> {
+  try {
+    const eligible = shouldConsider();
+    if (!eligible) return;
+    const { channel, current } = eligible;
+
+    const cache = readVersionCache(channel);
+    triggerBackgroundRefreshIfStale(channel, cache);
+
+    const latest = getUpgradeVersionForPopup(cache, current, channel);
+    if (!latest) return;
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answer = "";
+    try {
+      answer = (await rl.question(renderPrompt(current, latest, channel))).trim();
+    } finally {
+      rl.close();
+    }
+
+    const choice = answer === "" ? "1" : answer;
+    if (choice === "1") {
+      await runUpdate();
+      console.log("\nRestart the proxy:  ocx start");
+      process.exit(0);
+    } else if (choice === "3") {
+      dismissVersion(channel, latest);
+    }
+    // "2" (or anything else) -> Skip: continue this run unchanged.
+  } catch {
+    /* never let the update prompt disrupt startup */
+  }
+}

package/src/update/npm-invocation.d.mts

@@ -0,0 +1,23 @@
+export interface NpmInvocationDeps {
+  cwd?: string;
+  exists?: (path: string) => boolean;
+}
+
+export interface NpmInvocation {
+  file: string;
+  args: string[];
+  options: { windowsVerbatimArguments?: boolean };
+}
+
+export declare function resolveNpmCommand(
+  platform?: NodeJS.Platform,
+  env?: Record<string, string | undefined>,
+  deps?: NpmInvocationDeps,
+): string | null;
+
+export declare function npmInvocation(
+  args: readonly string[],
+  platform?: NodeJS.Platform,
+  env?: Record<string, string | undefined>,
+  deps?: NpmInvocationDeps,
+): NpmInvocation | null;

package/src/update/npm-invocation.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+
+const CMD_META = /([()%!^"`<>&|;, *?])/g;
+
+function escapeCmdArg(arg) {
+  let out = String(arg).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  return `"${out}"`.replace(CMD_META, "^$1");
+}
+
+function escapeCmdCommand(command) {
+  return command.replace(CMD_META, "^$1");
+}
+
+/**
+ * Whether a PATH entry *is* the current directory. The hijack this guards against is
+ * cmd.exe resolving a bare `npm` out of the directory opencodex was launched from, so
+ * only that exact directory has to be skipped — every candidate we hand to spawn is an
+ * absolute path, which is what actually defeats the implicit cwd-first search.
+ *
+ * Deliberately not a subtree test: npm's default Windows global prefix is
+ * `%AppData%\npm` (`C:\Users\x\AppData\Roaming\npm`), so excluding everything under the
+ * cwd would fail closed for anyone whose shell sits in their home directory — a normal
+ * setup, not the untrusted-project case this hardening is for.
+ */
+function isCurrentDirectory(cwd, entry) {
+  const left = win32.resolve(entry);
+  const right = win32.resolve(cwd);
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+function cleanPathEntry(entry) {
+  const trimmed = entry.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed.slice(1, -1);
+  return trimmed;
+}
+
+export function resolveNpmCommand(
+  platform = process.platform,
+  env = process.env,
+  deps = {},
+) {
+  if (platform !== "win32") return "npm";
+  const exists = deps.exists ?? existsSync;
+  const cwd = deps.cwd ?? process.cwd();
+  const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .filter(Boolean);
+  const pathEntries = (env.PATH ?? env.Path ?? "")
+    .split(win32.delimiter)
+    .map(cleanPathEntry)
+    .filter(Boolean);
+
+  for (const entry of pathEntries) {
+    if (!win32.isAbsolute(entry)) continue;
+    if (isCurrentDirectory(cwd, entry)) continue;
+    for (const extension of extensions) {
+      const candidate = win32.join(entry, `npm${extension.toLowerCase()}`);
+      if (exists(candidate)) return win32.resolve(candidate);
+    }
+  }
+  return null;
+}
+
+function systemCommandProcessor(env) {
+  const systemRoot = env.SystemRoot ?? env.windir;
+  if (systemRoot && win32.isAbsolute(systemRoot)) {
+    return win32.join(systemRoot, "System32", "cmd.exe");
+  }
+  const comSpec = env.ComSpec;
+  return comSpec && win32.isAbsolute(comSpec) ? win32.resolve(comSpec) : null;
+}
+
+export function npmInvocation(
+  args,
+  platform = process.platform,
+  env = process.env,
+  deps = {},
+) {
+  const npm = resolveNpmCommand(platform, env, deps);
+  if (!npm) return null;
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(npm)) {
+    return { file: npm, args: [...args], options: {} };
+  }
+
+  const commandProcessor = systemCommandProcessor(env);
+  if (!commandProcessor) return null;
+  const line = [escapeCmdCommand(npm), ...args.map(escapeCmdArg)].join(" ");
+  return {
+    file: commandProcessor,
+    args: ["/d", "/s", "/c", `"${line}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}

package/src/update/tray-update-plan.d.mts

@@ -0,0 +1,18 @@
+export interface WindowsTrayUpdatePlan {
+  installed: boolean;
+  running: boolean;
+  stopBeforeReplacement: boolean;
+  restoreOnFailure: boolean;
+  refreshAfterReplacement: boolean;
+  installArgs: string[];
+}
+
+export declare function planWindowsTrayUpdate(status: { installed?: boolean; running?: boolean }): WindowsTrayUpdatePlan;
+export declare function windowsTrayStopConfirmed(exitStatus: number | null, stillRunning: boolean): boolean;
+export declare function handoffWindowsTrayForUpdate(
+  status: { installed?: boolean; running?: boolean },
+  io: {
+    stop: () => { exitStatus: number | null; running: boolean };
+    start: () => unknown;
+  },
+): WindowsTrayUpdatePlan;

package/src/update/tray-update-plan.mjs

@@ -0,0 +1,38 @@
+/**
+ * Shared, side-effect-free contract for preserving the Windows tray across all
+ * updater entry points (npm launcher, CLI updater, and GUI worker).
+ */
+export function planWindowsTrayUpdate(status) {
+  const installed = status?.installed === true;
+  const running = status?.running === true;
+  return {
+    installed,
+    running,
+    stopBeforeReplacement: running,
+    restoreOnFailure: running,
+    refreshAfterReplacement: installed,
+    installArgs: ["tray", "install", ...(!running ? ["--no-start"] : [])],
+  };
+}
+
+export function windowsTrayStopConfirmed(exitStatus, stillRunning) {
+  return exitStatus === 0 && !stillRunning;
+}
+
+/** Stop before replacement and restore best-effort when the handoff cannot be confirmed. */
+export function handoffWindowsTrayForUpdate(status, io) {
+  const plan = planWindowsTrayUpdate(status);
+  if (!plan.stopBeforeReplacement) return plan;
+  try {
+    const stopped = io.stop();
+    if (!windowsTrayStopConfirmed(stopped.exitStatus, stopped.running)) {
+      throw new Error("the tray still reports running after shutdown");
+    }
+    return plan;
+  } catch (error) {
+    if (plan.restoreOnFailure) {
+      try { io.start(); } catch { /* preserve the handoff failure */ }
+    }
+    throw error;
+  }
+}

package/src/usage/debug.ts

@@ -0,0 +1,97 @@
+/** Usage-shape diagnostic JSONL. Enable with `ocx debug usage on` or OPENCODEX_USAGE_DEBUG=1. */
+
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { DEBUG_ENV } from "../lib/debug-settings";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import type { DebugLogEntry } from "../lib/debug-log-buffer";
+import { redactSecretString, redactSecrets } from "../lib/redact";
+import type { OcxUsage } from "../types";
+
+export const USAGE_DEBUG_ENV = DEBUG_ENV.usage;
+export { isUsageDebugEnabled } from "../lib/debug-settings";
+export const USAGE_DEBUG_BODY_SAMPLE_BYTES = 2048;
+export const USAGE_DEBUG_MAX_LINES = 200;
+export const USAGE_DEBUG_KEEP_LINES = 100;
+
+export type UsageDebugBodyKind = "sse" | "json" | "other" | "none";
+
+export interface UsageDebugRecord {
+  ts: number;
+  requestId: string;
+  provider: string;
+  model: string;
+  upstreamContentType: string | null;
+  upstreamStatus: number;
+  bodyKind: UsageDebugBodyKind;
+  bodySample: string;
+  extractedUsage: OcxUsage | null;
+}
+
+export function usageDebugPath(): string {
+  return join(getConfigDir(), "usage-debug.jsonl");
+}
+
+export function truncateForDebug(text: string, max = USAGE_DEBUG_BODY_SAMPLE_BYTES): string {
+  const redacted = redactSecretString(text);
+  if (redacted.length <= max) return redacted;
+  const cut = redacted.slice(0, max);
+  const remaining = redacted.length - max;
+  return `${cut}... [+${remaining} more]`;
+}
+
+function ensureUsageDebugDir(): void {
+  const dir = getConfigDir();
+  recordOwnedConfigPath(dir, usageDebugPath());
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+}
+
+function trimRollingFile(path: string): void {
+  const text = readFileSync(path, "utf-8");
+  const lines = text.split(/\r?\n/).filter(line => line.length > 0);
+  if (lines.length <= USAGE_DEBUG_MAX_LINES) return;
+  const kept = lines.slice(-USAGE_DEBUG_KEEP_LINES).join("\n") + "\n";
+  writeFileSync(path, kept, { encoding: "utf-8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+}
+
+export function appendUsageDebug(record: UsageDebugRecord): void {
+  try {
+    ensureUsageDebugDir();
+    const path = usageDebugPath();
+    const safeRecord = redactSecrets(record) as UsageDebugRecord;
+    appendFileSync(path, `${JSON.stringify(safeRecord)}\n`, { encoding: "utf-8", mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (existsSync(path)) trimRollingFile(path);
+  } catch {
+    /* debug capture must never break the proxy */
+  }
+}
+
+/** Tail usage-debug.jsonl for GUI / management API (same shape as provider debug buffer). */
+export function getUsageDebugLogEntries(options?: { after?: number; limit?: number }): DebugLogEntry[] {
+  const after = options?.after ?? 0;
+  const limit = options?.limit ?? 500;
+  try {
+    const content = readFileSync(usageDebugPath(), "utf8");
+    const entries: DebugLogEntry[] = [];
+    let seq = 0;
+    for (const line of content.split(/\r?\n/).filter(Boolean)) {
+      seq += 1;
+      if (after > 0 && seq <= after) continue;
+      try {
+        const record = JSON.parse(line) as UsageDebugRecord;
+        const at = typeof record.ts === "number" ? record.ts : 0;
+        entries.push({ seq, at, line });
+      } catch {
+        entries.push({ seq, at: 0, line });
+      }
+    }
+    if (entries.length <= limit) return entries;
+    return entries.slice(-limit);
+  } catch {
+    return [];
+  }
+}