feat(update-check): show extension update notice on exit (#1236)

* feat(update-check): show extension update notice on exit

The CLI exit hook already prints "Update available" when a newer @jackwener/opencli is on npm. Extension updates were only surfaced inside `opencli doctor`, so users running normal browser commands had no signal that the Chrome extension was out of date.

Solution piggybacks on the existing 24h background fetch:
- Daemon writes the live extensionVersion + lastSeenAt into the shared cache on every hello handshake (rare event, one fs.writeFileSync).
- CLI exit hook reads the cache it already loads and prints an extra extension notice when a newer release is available and the cache is fresh (<7d).
- writeCache becomes a read-merge-write so the daemon's currentExtensionVersion and the CLI's npm latestVersion don't clobber each other.

Net cost on the CLI hot path: zero new I/O, zero new daemon contact. The notice formatter is split into a pure helper (buildUpdateNotices) so the staleness window, equality, and combined-notice cases are unit-tested without touching disk or stderr.

* fix(update-check): tolerate partial cache when daemon writes first

Self-review caught a TypeError path: if the daemon's hello handler runs `recordExtensionVersion` before the CLI's npm fetch ever populated the cache, the resulting cache file has only `currentExtensionVersion` + `extensionLastSeenAt` and no `latestVersion`. The next CLI run then fed `undefined` into `isNewer`, which calls `.replace(...)` on it.

- Mark `lastCheck` and `latestVersion` optional in the cache schema (the merge pattern means either side may write first).
- Guard the CLI notice on `cache.latestVersion` being defined before comparing.
- Guard `checkForUpdateBackground`'s 24h short-circuit on `lastCheck` being defined.
- Add a test for the daemon-only cache case.

Author: jackwener

src/daemon.ts

@@ -27,6 +27,7 @@ import { EXIT_CODES } from './errors.js';
 import { log } from './logger.js';
 import { PKG_VERSION } from './version.js';
 import { DEFAULT_CONTEXT_ID } from './browser/profile.js';
+import { recordExtensionVersion } from './update-check.js';
 
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 
@@ -390,6 +391,7 @@ wss.on('connection', (ws: WebSocket) => {
         connection.extensionVersion = typeof msg.version === 'string' ? msg.version : null;
         connection.extensionCompatRange = typeof msg.compatRange === 'string' ? msg.compatRange : null;
         connection.lastSeenAt = Date.now();
+        if (connection.extensionVersion) recordExtensionVersion(connection.extensionVersion);
         log.info(`[daemon] Extension profile connected: ${connection.contextId}`);
         return;
       }

src/update-check.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { _extractLatestExtensionVersionFromReleases as extractLatestExtensionVersionFromReleases } from './update-check.js';
+import {
+  _extractLatestExtensionVersionFromReleases as extractLatestExtensionVersionFromReleases,
+  _buildUpdateNotices as buildUpdateNotices,
+  _EXTENSION_STALE_MS as EXTENSION_STALE_MS,
+} from './update-check.js';
 
 describe('extractLatestExtensionVersionFromReleases', () => {
   it('reads the extension version from a versioned asset on a normal CLI release', () => {
@@ -38,3 +42,96 @@ describe('extractLatestExtensionVersionFromReleases', () => {
     ).toBeUndefined();
   });
 });
+
+describe('buildUpdateNotices', () => {
+  const now = 1_700_000_000_000;
+
+  it('returns nothing when cache is empty', () => {
+    expect(buildUpdateNotices({ cliVersion: '1.0.0', cache: null, now })).toEqual({});
+  });
+
+  it('emits a CLI notice when registry version is newer', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: { lastCheck: now, latestVersion: '1.0.1' },
+      now,
+    });
+    expect(lines.cli).toContain('v1.0.0 → v1.0.1');
+    expect(lines.extension).toBeUndefined();
+  });
+
+  it('emits an extension notice when current ext is older and cache is fresh', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: {
+        lastCheck: now,
+        latestVersion: '1.0.0',
+        latestExtensionVersion: '2.1.0',
+        currentExtensionVersion: '2.0.0',
+        extensionLastSeenAt: now - 60_000,
+      },
+      now,
+    });
+    expect(lines.cli).toBeUndefined();
+    expect(lines.extension).toContain('v2.0.0 → v2.1.0');
+  });
+
+  it('skips the extension notice when lastSeenAt is older than the stale window', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: {
+        lastCheck: now,
+        latestVersion: '1.0.0',
+        latestExtensionVersion: '2.1.0',
+        currentExtensionVersion: '2.0.0',
+        extensionLastSeenAt: now - EXTENSION_STALE_MS - 1,
+      },
+      now,
+    });
+    expect(lines.extension).toBeUndefined();
+  });
+
+  it('skips the extension notice when current and latest are equal', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: {
+        lastCheck: now,
+        latestVersion: '1.0.0',
+        latestExtensionVersion: '2.0.0',
+        currentExtensionVersion: '2.0.0',
+        extensionLastSeenAt: now,
+      },
+      now,
+    });
+    expect(lines.extension).toBeUndefined();
+  });
+
+  it('does not throw when cache has only daemon-written fields and no latestVersion', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: {
+        currentExtensionVersion: '2.0.0',
+        extensionLastSeenAt: now,
+      },
+      now,
+    });
+    expect(lines.cli).toBeUndefined();
+    expect(lines.extension).toBeUndefined();
+  });
+
+  it('emits both notices when both are out of date', () => {
+    const lines = buildUpdateNotices({
+      cliVersion: '1.0.0',
+      cache: {
+        lastCheck: now,
+        latestVersion: '1.1.0',
+        latestExtensionVersion: '2.1.0',
+        currentExtensionVersion: '2.0.0',
+        extensionLastSeenAt: now,
+      },
+      now,
+    });
+    expect(lines.cli).toContain('v1.0.0 → v1.1.0');
+    expect(lines.extension).toContain('v2.0.0 → v2.1.0');
+  });
+});

src/update-check.ts

@@ -7,6 +7,11 @@
  * - Check interval: 24 hours
  * - Notice appears AFTER command output, not before (same as npm/gh/yarn)
  * - Never delays or blocks the CLI command
+ *
+ * Cache is shared between the CLI process (writes latestVersion / latestExtensionVersion
+ * via background fetch) and the daemon process (writes currentExtensionVersion /
+ * extensionLastSeenAt via `recordExtensionVersion` on each hello). Writes use a
+ * read-merge-write pattern so neither side clobbers the other.
  */
 
 import * as fs from 'node:fs';
@@ -18,13 +23,19 @@ import { PKG_VERSION } from './version.js';
 const CACHE_DIR = path.join(os.homedir(), '.opencli');
 const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json');
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const EXTENSION_STALE_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@jackwener/opencli/latest';
 const GITHUB_RELEASES_URL = 'https://api.github.com/repos/jackwener/OpenCLI/releases?per_page=20';
 
 interface UpdateCache {
-  lastCheck: number;
-  latestVersion: string;
+  // CLI npm fetch fields — present once `checkForUpdateBackground` has succeeded.
+  // Optional because the daemon may write the cache first via `recordExtensionVersion`.
+  lastCheck?: number;
+  latestVersion?: string;
   latestExtensionVersion?: string;
+  // Daemon hello fields.
+  currentExtensionVersion?: string;
+  extensionLastSeenAt?: number;
 }
 
 interface GitHubReleaseAsset {
@@ -36,21 +47,23 @@ interface GitHubRelease {
   assets?: GitHubReleaseAsset[];
 }
 
-// Read cache once at module load — shared by both exported functions
-const _cache: UpdateCache | null = (() => {
+function readCacheSync(): UpdateCache | null {
   try {
     return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8')) as UpdateCache;
   } catch {
     return null;
   }
-})();
+}
+
+// Read cache once at module load — shared by both exported functions
+const _cache: UpdateCache | null = readCacheSync();
 
-function writeCache(latestVersion: string, latestExtensionVersion?: string): void {
+function writeCacheMerge(updates: Partial<UpdateCache>): void {
   try {
     fs.mkdirSync(CACHE_DIR, { recursive: true });
-    const data: UpdateCache = { lastCheck: Date.now(), latestVersion };
-    if (latestExtensionVersion) data.latestExtensionVersion = latestExtensionVersion;
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(data), 'utf-8');
+    const existing = readCacheSync() ?? {};
+    const merged = { ...existing, ...updates } as UpdateCache;
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(merged), 'utf-8');
   } catch {
     // Best-effort; never fail
   }
@@ -73,6 +86,41 @@ function isCI(): boolean {
   return !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION);
 }
 
+interface NoticeInputs {
+  cliVersion: string;
+  cache: UpdateCache | null;
+  now: number;
+}
+
+interface NoticeLines {
+  cli?: string;
+  extension?: string;
+}
+
+/** Pure function: derive notice text from cache state. Exported for tests. */
+function buildUpdateNotices({ cliVersion, cache, now }: NoticeInputs): NoticeLines {
+  if (!cache) return {};
+  const lines: NoticeLines = {};
+  if (cache.latestVersion && isNewer(cache.latestVersion, cliVersion)) {
+    lines.cli =
+      styleText('yellow', `\n  Update available: v${cliVersion} → v${cache.latestVersion}\n`) +
+      styleText('dim', `  Run: npm install -g @jackwener/opencli\n`);
+  }
+  const { currentExtensionVersion, latestExtensionVersion, extensionLastSeenAt } = cache;
+  if (
+    currentExtensionVersion &&
+    latestExtensionVersion &&
+    extensionLastSeenAt &&
+    now - extensionLastSeenAt < EXTENSION_STALE_MS &&
+    isNewer(latestExtensionVersion, currentExtensionVersion)
+  ) {
+    lines.extension =
+      styleText('yellow', `\n  Extension update available: v${currentExtensionVersion} → v${latestExtensionVersion}\n`) +
+      styleText('dim', `  Download: https://github.com/jackwener/opencli/releases\n`);
+  }
+  return lines;
+}
+
 /**
  * Register a process exit hook that prints an update notice if a newer
  * version was found on the last background check.
@@ -85,13 +133,14 @@ export function registerUpdateNoticeOnExit(): void {
 
   process.on('exit', (code) => {
     if (code !== 0) return; // Don't show update notice on error exit
-    if (!_cache) return;
-    if (!isNewer(_cache.latestVersion, PKG_VERSION)) return;
+    const { cli, extension } = buildUpdateNotices({
+      cliVersion: PKG_VERSION,
+      cache: _cache,
+      now: Date.now(),
+    });
+    if (!cli && !extension) return;
     try {
-      process.stderr.write(
-        styleText('yellow', `\n  Update available: v${PKG_VERSION} → v${_cache.latestVersion}\n`) +
-        styleText('dim', `  Run: npm install -g @jackwener/opencli\n\n`),
-      );
+      process.stderr.write(`${cli ?? ''}${extension ?? ''}\n`);
     } catch {
       // Ignore broken pipe (stderr closed before process exits)
     }
@@ -135,7 +184,7 @@ async function fetchLatestExtensionVersion(): Promise<string | undefined> {
  */
 export function checkForUpdateBackground(): void {
   if (isCI()) return;
-  if (_cache && Date.now() - _cache.lastCheck < CHECK_INTERVAL_MS) return;
+  if (_cache?.lastCheck && Date.now() - _cache.lastCheck < CHECK_INTERVAL_MS) return;
 
   void (async () => {
     try {
@@ -150,14 +199,29 @@ export function checkForUpdateBackground(): void {
       const data = await res.json() as { version?: string };
       if (typeof data.version === 'string') {
         const extVersion = await fetchLatestExtensionVersion();
-        writeCache(data.version, extVersion);
+        const updates: Partial<UpdateCache> = { lastCheck: Date.now(), latestVersion: data.version };
+        if (extVersion) updates.latestExtensionVersion = extVersion;
+        writeCacheMerge(updates);
       }
     } catch {
       // Network error: silently skip, try again next run
     }
   })();
 }
 
+/**
+ * Stash the current extension version into the shared cache. Called by the
+ * daemon on each hello handshake. Lets the next CLI process compare against
+ * the latest known release and print an exit notice without any extra I/O.
+ */
+export function recordExtensionVersion(version: string): void {
+  if (typeof version !== 'string' || !version.trim()) return;
+  writeCacheMerge({
+    currentExtensionVersion: version.trim(),
+    extensionLastSeenAt: Date.now(),
+  });
+}
+
 /**
  * Get the cached latest extension version (if available).
  * Used by `opencli doctor` to report extension updates.
@@ -168,4 +232,6 @@ export function getCachedLatestExtensionVersion(): string | undefined {
 
 export {
   extractLatestExtensionVersionFromReleases as _extractLatestExtensionVersionFromReleases,
+  buildUpdateNotices as _buildUpdateNotices,
+  EXTENSION_STALE_MS as _EXTENSION_STALE_MS,
 };