onbuzz 4.6.4 → 4.7.0

package/src/services/authCacheStore.js

@@ -0,0 +1,140 @@
+/**
+ * Encrypted persistence for `webServer.lastAuthResult`.
+ *
+ * Purpose:
+ * - Survive local-server restarts without losing the OAuth JWT.
+ * - Without this, every restart wipes the in-memory auth cache, so
+ *   the FE polling fallback at `/api/auth/status` returns
+ *   `{ user: null, jwt: null }` and any frontend that didn't already
+ *   capture the JWT in its own localStorage (page reload after a
+ *   server bounce, fresh browser, incognito tab) gets 401s on every
+ *   marketplace publish/install/rate call.
+ *
+ * Why encrypted:
+ * - The cache row carries a raw JWT — a bearer credential. Storing it
+ *   in plaintext on disk would let any local process with file-read
+ *   access impersonate the user against the marketplace service.
+ *
+ * Storage: `<userDataDir>/settings/auth-cache.enc`. Cipher and key
+ * derivation are shared with `apiKeyManager` via
+ * `utilities/secretsCipher.js` — DRY by design.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getUserDataPaths, ensureUserDataDirs } from '../utilities/userDataDir.js';
+import {
+  getOrCreateEncryptionKey,
+  encrypt,
+  decrypt,
+} from '../utilities/secretsCipher.js';
+
+const FILE_NAME = 'auth-cache.enc';
+const SCHEMA_VERSION = 1;
+
+class AuthCacheStore {
+  constructor(logger) {
+    this.logger = logger;
+    this.persistenceFile = null;
+    this.encryptionKey = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Resolve the encrypted file path and derive (or load) the AES key.
+   * Idempotent. Failures are non-fatal — the store then behaves as a
+   * no-op (load returns null, save silently swallows), so a broken
+   * disk doesn't crash the server boot.
+   */
+  async initialize() {
+    if (this.initialized) return;
+    try {
+      await ensureUserDataDirs();
+      const paths = getUserDataPaths();
+      this.persistenceFile = path.join(paths.settings, FILE_NAME);
+      this.encryptionKey = await getOrCreateEncryptionKey(paths.settings, this.logger);
+      this.initialized = true;
+      this.logger?.info?.('[AuthCacheStore] Initialized');
+    } catch (error) {
+      this.logger?.warn?.('[AuthCacheStore] init failed, running in memory-only mode', {
+        error: error.message,
+      });
+    }
+  }
+
+  /**
+   * Load and decrypt the persisted cache row.
+   * Returns null when the file is missing, corrupted, schema-mismatched,
+   * or the store failed to initialize. Never throws.
+   *
+   * @returns {Promise<Object|null>} the `lastAuthResult`-shaped object
+   *   ({ user, hasApiKey, jwt, timestamp }) or null.
+   */
+  async load() {
+    if (!this.initialized) return null;
+    try {
+      const ciphertext = await fs.readFile(this.persistenceFile, 'utf8');
+      const decoded = decrypt(ciphertext, this.encryptionKey);
+      const data = JSON.parse(decoded);
+      if (data?.version !== SCHEMA_VERSION || !data.cache) {
+        this.logger?.warn?.('[AuthCacheStore] schema mismatch, ignoring on-disk cache', {
+          version: data?.version,
+        });
+        return null;
+      }
+      return data.cache;
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        this.logger?.warn?.('[AuthCacheStore] load failed', { error: error.message });
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Persist a cache row. Passing null clears the file (delegate to
+   * clear() for clarity; this is a convenience for the webServer
+   * call site that always wants "make disk match memory").
+   *
+   * @param {Object|null} cache
+   */
+  async save(cache) {
+    if (!this.initialized) return;
+    if (cache === null || cache === undefined) {
+      await this.clear();
+      return;
+    }
+    try {
+      const payload = {
+        version: SCHEMA_VERSION,
+        savedAt: new Date().toISOString(),
+        cache,
+      };
+      const ciphertext = encrypt(JSON.stringify(payload), this.encryptionKey);
+      await fs.writeFile(this.persistenceFile, ciphertext, { mode: 0o600 });
+      this.logger?.debug?.('[AuthCacheStore] saved', {
+        hasUser: !!cache.user,
+        hasJwt: !!cache.jwt,
+      });
+    } catch (error) {
+      this.logger?.warn?.('[AuthCacheStore] save failed', { error: error.message });
+    }
+  }
+
+  /**
+   * Delete the on-disk cache. No-op when the file is already absent.
+   */
+  async clear() {
+    if (!this.initialized) return;
+    try {
+      await fs.unlink(this.persistenceFile);
+      this.logger?.info?.('[AuthCacheStore] cleared');
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        this.logger?.warn?.('[AuthCacheStore] clear failed', { error: error.message });
+      }
+    }
+  }
+}
+
+export default AuthCacheStore;

package/src/tools/__tests__/webTool.e2e.test.js

@@ -12,7 +12,15 @@
  * Run with: npm run test:e2e
  */
 
-import { describe, test, expect, beforeAll, afterAll } from '@jest/globals';
+import { describe, test, expect, beforeAll, afterAll, jest } from '@jest/globals';
+
+// Real-network tests against example.com / iana.org are inherently
+// flaky on TCP / DNS / target-server hiccups. The contract under test
+// is "the WebTool chain machinery works", not "example.com is always
+// up", so we tolerate up to 2 retries before declaring failure.
+// If a test fails 3 times in a row, that's a real signal worth
+// investigating; transient flakes get absorbed silently.
+jest.retryTimes(2, { logErrorsBeforeRetry: true });
 import os from 'os';
 import fs from 'fs';
 

package/src/tools/webTool.js

@@ -1193,14 +1193,30 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
       const fetchStatus = fetchResponse ? fetchResponse.status() : null;
 
       if (fetchStatus && fetchStatus >= 400) {
+        // A page that returned 4xx/5xx did NOT give the agent what it
+        // asked for. We used to return `success: true` here on the
+        // theory that "the fetch itself executed"; downstream agents
+        // then ignored the warning and treated the error page as
+        // content. Switching to `success: false` matches the rest of
+        // the tool contract (operation either achieved its purpose
+        // or it didn't) AND surfaces the diagnostic via the standard
+        // `error` field that callers already inspect.
+        const reason =
+          fetchStatus >= 500 ? 'server error' :
+          fetchStatus === 404 ? 'page not found' :
+          fetchStatus === 403 ? 'access forbidden' :
+          fetchStatus === 401 ? 'authentication required' :
+          'client error';
         const errorResult = {
-          success: true,  // Fetch itself executed — page returned error status
+          success: false,
           url,
           httpStatus: fetchStatus,
-          diagnostic: `Page returned HTTP ${fetchStatus} (${fetchStatus >= 500 ? 'server error' : fetchStatus === 404 ? 'page not found' : fetchStatus === 403 ? 'access forbidden' : 'client error'})`,
-          warning: `HTTP ${fetchStatus} — the page loaded but returned an error status. Content may still be available.`
+          error: `HTTP ${fetchStatus}: ${reason}`,
+          diagnostic: `Page returned HTTP ${fetchStatus} (${reason})`,
+          warning: `HTTP ${fetchStatus} — the page loaded but returned an error status. Content may still be available.`,
         };
-        // Still try to get title for context
+        // Still try to get title for context — error pages often have
+        // useful titles like "404 - Not Found".
         try { errorResult.title = await page.title(); } catch {}
         // Don't close page here — finally block handles it
         return errorResult;

package/src/utilities/__tests__/secretsCipher.test.js

@@ -0,0 +1,97 @@
+/**
+ * Tests for the shared cipher primitives used by both
+ * `services/apiKeyManager.js` (api-keys.enc) and
+ * `services/authCacheStore.js` (auth-cache.enc).
+ *
+ * Covers:
+ *   - key derivation: persistence across calls, identity vs different salts
+ *   - round-trip: encrypt then decrypt returns the original
+ *   - constants stability: KEY_DERIVATION_DOMAIN is part of the on-disk
+ *     contract and must not change without a migration
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+import {
+  encrypt,
+  decrypt,
+  getOrCreateEncryptionKey,
+  KEY_DERIVATION_DOMAIN,
+  SALT_FILENAME,
+  SALT_LENGTH,
+  KEY_LENGTH,
+} from '../secretsCipher.js';
+
+const tmpDir = path.join(os.tmpdir(), 'secretsCipher-test-' + crypto.randomBytes(6).toString('hex'));
+
+beforeEach(async () => { await fs.mkdir(tmpDir, { recursive: true }); });
+afterEach(async () => { try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch { /* ok */ } });
+
+describe('secretsCipher', () => {
+  test('KEY_DERIVATION_DOMAIN is the documented value — changing this invalidates all stored credentials', () => {
+    // Tripwire: this constant is part of the on-disk contract.
+    // If you intentionally need to rotate it, also write a migration.
+    expect(KEY_DERIVATION_DOMAIN).toBe('loxia-api-key-encryption-v1');
+  });
+
+  test('getOrCreateEncryptionKey creates a salt file on first call', async () => {
+    await getOrCreateEncryptionKey(tmpDir, null);
+    const saltFile = path.join(tmpDir, SALT_FILENAME);
+    const buf = await fs.readFile(saltFile);
+    expect(buf.length).toBe(SALT_LENGTH);
+  });
+
+  test('getOrCreateEncryptionKey reuses the existing salt on subsequent calls', async () => {
+    const key1 = await getOrCreateEncryptionKey(tmpDir, null);
+    const key2 = await getOrCreateEncryptionKey(tmpDir, null);
+    expect(key1.equals(key2)).toBe(true);
+    expect(key1.length).toBe(KEY_LENGTH);
+  });
+
+  test('different salt directories yield different keys', async () => {
+    const dirA = path.join(tmpDir, 'a');
+    const dirB = path.join(tmpDir, 'b');
+    await fs.mkdir(dirA); await fs.mkdir(dirB);
+    const keyA = await getOrCreateEncryptionKey(dirA, null);
+    const keyB = await getOrCreateEncryptionKey(dirB, null);
+    expect(keyA.equals(keyB)).toBe(false);
+  });
+
+  test('encrypt then decrypt round-trips the plaintext', async () => {
+    const key = await getOrCreateEncryptionKey(tmpDir, null);
+    const plaintext = JSON.stringify({ jwt: 'eyJ.test.jwt', user: { id: 'u-1' } });
+    const ct = encrypt(plaintext, key);
+    expect(typeof ct).toBe('string');
+    expect(ct).not.toContain('eyJ');     // not plaintext
+    expect(decrypt(ct, key)).toBe(plaintext);
+  });
+
+  test('encrypt produces different ciphertext each call (random IV)', async () => {
+    const key = await getOrCreateEncryptionKey(tmpDir, null);
+    const ct1 = encrypt('same', key);
+    const ct2 = encrypt('same', key);
+    expect(ct1).not.toBe(ct2);
+  });
+
+  test('decrypt throws with a clear message when no key supplied', () => {
+    expect(() => decrypt('anything', null)).toThrow('Encryption key not initialized');
+  });
+
+  test('encrypt throws with a clear message when no key supplied', () => {
+    expect(() => encrypt('anything', null)).toThrow('Encryption key not initialized');
+  });
+
+  test('decrypt fails on tampered ciphertext (GCM authTag check)', async () => {
+    const key = await getOrCreateEncryptionKey(tmpDir, null);
+    const ct = encrypt('payload', key);
+    // Flip a byte in the middle of the buffer
+    const buf = Buffer.from(ct, 'base64');
+    buf[Math.floor(buf.length / 2)] ^= 0xff;
+    const tampered = buf.toString('base64');
+    expect(() => decrypt(tampered, key)).toThrow();
+  });
+});

package/src/utilities/__tests__/updateNotifier.test.js

@@ -0,0 +1,139 @@
+/**
+ * Tests for src/utilities/updateNotifier.js — the CLI banner wrapper.
+ *
+ * The helper has four kill-switch paths and two normal paths. We
+ * test each so a regression doesn't either spam users or silently
+ * stop checking.
+ */
+
+import { describe, test, expect, jest } from '@jest/globals';
+import {
+  runUpdateCheck,
+  isUpdateCheckDisabled,
+  loadPackageJson,
+} from '../updateNotifier.js';
+
+describe('isUpdateCheckDisabled', () => {
+  test('returns false on an empty env', () => {
+    expect(isUpdateCheckDisabled({})).toBe(false);
+  });
+
+  test('honors LOXIA_DISABLE_UPDATE_CHECK', () => {
+    expect(isUpdateCheckDisabled({ LOXIA_DISABLE_UPDATE_CHECK: '1' })).toBe(true);
+    expect(isUpdateCheckDisabled({ LOXIA_DISABLE_UPDATE_CHECK: 'true' })).toBe(true);
+  });
+
+  test('honors NO_UPDATE_NOTIFIER (package convention)', () => {
+    expect(isUpdateCheckDisabled({ NO_UPDATE_NOTIFIER: '1' })).toBe(true);
+  });
+
+  test('honors CI=true (avoids banner in pipelines)', () => {
+    expect(isUpdateCheckDisabled({ CI: 'true' })).toBe(true);
+  });
+
+  test('treats "0" and "false" as not-disabled (escape hatch for misuse)', () => {
+    expect(isUpdateCheckDisabled({ LOXIA_DISABLE_UPDATE_CHECK: '0' })).toBe(false);
+    expect(isUpdateCheckDisabled({ LOXIA_DISABLE_UPDATE_CHECK: 'false' })).toBe(false);
+  });
+});
+
+describe('loadPackageJson', () => {
+  test('finds the CLI package.json by walking up from a starting dir', () => {
+    // The helper looks for a pkg.json with `bin` OR `@loxia-labs/` name —
+    // both true of this repo's root pkg.json.
+    const pkg = loadPackageJson();
+    expect(pkg).not.toBeNull();
+    expect(pkg.name).toMatch(/loxia/i);
+    expect(typeof pkg.version).toBe('string');
+  });
+
+  test('returns null when no qualifying package.json exists in the chain', () => {
+    // Inject a stub that always returns ENOENT.
+    const fs = {
+      readFileSync: () => { throw Object.assign(new Error('nope'), { code: 'ENOENT' }); },
+    };
+    expect(loadPackageJson({ startDir: '/tmp', fs })).toBeNull();
+  });
+});
+
+describe('runUpdateCheck — kill-switches', () => {
+  test('returns null when disabled by env', async () => {
+    const importImpl = jest.fn();
+    const r = await runUpdateCheck({
+      env: { LOXIA_DISABLE_UPDATE_CHECK: '1' },
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+    });
+    expect(r).toBeNull();
+    expect(importImpl).not.toHaveBeenCalled();
+  });
+
+  test('returns null when pkg.json could not be loaded', async () => {
+    const importImpl = jest.fn();
+    const r = await runUpdateCheck({
+      env: {},
+      pkg: null,
+      importImpl,
+    });
+    expect(r).toBeNull();
+    expect(importImpl).not.toHaveBeenCalled();
+  });
+});
+
+describe('runUpdateCheck — dependency tolerance', () => {
+  test('returns null when update-notifier is not installed', async () => {
+    const importImpl = jest.fn().mockRejectedValue(new Error('Cannot find module'));
+    const r = await runUpdateCheck({
+      env: {},
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+    });
+    expect(r).toBeNull();
+  });
+
+  test('returns null when the module exists but has the wrong shape', async () => {
+    const importImpl = jest.fn().mockResolvedValue({ /* no default, no callable */ });
+    const r = await runUpdateCheck({
+      env: {},
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+    });
+    expect(r).toBeNull();
+  });
+});
+
+describe('runUpdateCheck — happy path', () => {
+  test('invokes update-notifier with the supplied pkg and calls notify()', async () => {
+    const notifyMock = jest.fn();
+    const updateNotifierFn = jest.fn().mockReturnValue({ notify: notifyMock });
+    const importImpl = jest.fn().mockResolvedValue({ default: updateNotifierFn });
+
+    const pkg = { name: '@loxia-labs/loxia-autopilot-one', version: '4.6.4' };
+    const result = await runUpdateCheck({ env: {}, pkg, importImpl });
+
+    expect(result).toEqual({ notify: notifyMock });
+    expect(updateNotifierFn).toHaveBeenCalledTimes(1);
+    const call = updateNotifierFn.mock.calls[0][0];
+    expect(call.pkg).toBe(pkg);
+    expect(typeof call.updateCheckInterval).toBe('number');
+    expect(notifyMock).toHaveBeenCalledTimes(1);
+
+    const notifyOpts = notifyMock.mock.calls[0][0];
+    expect(notifyOpts.isGlobal).toBe(true);
+    expect(notifyOpts.message).toContain('{packageName}');
+  });
+
+  test('a throwing notifier does not surface — returns null', async () => {
+    const updateNotifierFn = jest.fn().mockImplementation(() => { throw new Error('boom'); });
+    const importImpl = jest.fn().mockResolvedValue({ default: updateNotifierFn });
+    const logger = { debug: jest.fn() };
+    const r = await runUpdateCheck({
+      env: {},
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+      logger,
+    });
+    expect(r).toBeNull();
+    expect(logger.debug).toHaveBeenCalled();
+  });
+});

package/src/utilities/secretsCipher.js

@@ -0,0 +1,116 @@
+/**
+ * Shared encryption primitives for at-rest credential storage.
+ *
+ * Used by:
+ *   - services/apiKeyManager.js   (api-keys.enc)
+ *   - services/authCacheStore.js  (auth-cache.enc)
+ *
+ * Both stores derive the same machine-specific AES-256-GCM key from a
+ * persistent salt at `<userDataDir>/.key-salt` plus os-derived data.
+ * Sharing the cipher primitives keeps the byte layout consistent and
+ * means a single review covers credential-at-rest for the whole app.
+ *
+ * On-disk format (per ciphertext, base64-encoded):
+ *   [ IV (16B) | authTag (16B) | ciphertext (variable) ]
+ *
+ * KEY_DERIVATION_DOMAIN must stay constant — changing it invalidates
+ * every existing `api-keys.enc` on every user's machine.
+ */
+
+import crypto from 'crypto';
+import os from 'os';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+export const ALGORITHM = 'aes-256-gcm';
+export const KEY_LENGTH = 32;        // 256 bits
+export const IV_LENGTH = 16;
+export const AUTH_TAG_LENGTH = 16;
+export const SALT_LENGTH = 32;
+export const PBKDF2_ITERATIONS = 100000;
+export const SALT_FILENAME = '.key-salt';
+
+/**
+ * Domain-separation string mixed into the key derivation input. Must
+ * not change without a migration — existing on-disk files would
+ * become undecryptable.
+ */
+export const KEY_DERIVATION_DOMAIN = 'loxia-api-key-encryption-v1';
+
+/**
+ * Read or create the per-machine salt and derive the AES key from it
+ * combined with stable machine identifiers.
+ *
+ * @param {string} settingsDir - directory holding `.key-salt`
+ * @param {Object} [logger]
+ * @returns {Promise<Buffer>} 32-byte AES key
+ */
+export async function getOrCreateEncryptionKey(settingsDir, logger) {
+  const saltFile = path.join(settingsDir, SALT_FILENAME);
+  let salt;
+  try {
+    salt = await fs.readFile(saltFile);
+  } catch {
+    salt = crypto.randomBytes(SALT_LENGTH);
+    await fs.writeFile(saltFile, salt, { mode: 0o600 });
+    logger?.info?.('[secretsCipher] Generated new encryption salt');
+  }
+
+  const machineData = [
+    os.hostname(),
+    os.homedir(),
+    os.userInfo().username,
+    process.platform,
+    KEY_DERIVATION_DOMAIN,
+  ].join(':');
+
+  return crypto.pbkdf2Sync(machineData, salt, PBKDF2_ITERATIONS, KEY_LENGTH, 'sha256');
+}
+
+/**
+ * Encrypt a UTF-8 plaintext to a base64 string carrying IV+authTag.
+ *
+ * @param {string} plaintext
+ * @param {Buffer} encryptionKey
+ * @returns {string} base64
+ */
+export function encrypt(plaintext, encryptionKey) {
+  if (!encryptionKey) throw new Error('Encryption key not initialized');
+
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, encryptionKey, iv);
+
+  let encrypted = cipher.update(plaintext, 'utf8', 'base64');
+  encrypted += cipher.final('base64');
+
+  const authTag = cipher.getAuthTag();
+  const combined = Buffer.concat([
+    iv,
+    authTag,
+    Buffer.from(encrypted, 'base64'),
+  ]);
+  return combined.toString('base64');
+}
+
+/**
+ * Decrypt a base64 IV+authTag+ciphertext blob back to UTF-8.
+ *
+ * @param {string} encryptedData base64
+ * @param {Buffer} encryptionKey
+ * @returns {string} plaintext
+ */
+export function decrypt(encryptedData, encryptionKey) {
+  if (!encryptionKey) throw new Error('Encryption key not initialized');
+
+  const combined = Buffer.from(encryptedData, 'base64');
+  const iv = combined.subarray(0, IV_LENGTH);
+  const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+  const encrypted = combined.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, encryptionKey, iv);
+  decipher.setAuthTag(authTag);
+
+  let decrypted = decipher.update(encrypted.toString('base64'), 'base64', 'utf8');
+  decrypted += decipher.final('utf8');
+  return decrypted;
+}

package/src/utilities/updateNotifier.js

@@ -0,0 +1,140 @@
+/**
+ * npm CLI update notifier — thin wrapper around `update-notifier`.
+ *
+ * Shows a non-blocking banner on CLI startup when a newer version of
+ * the published package is available on the npm registry. User stays
+ * in control: the CLI never auto-installs anything.
+ *
+ * Brand awareness:
+ *   The CLI ships under two brand-specific package names
+ *   (`@loxia-labs/loxia-autopilot-one`, `@loxia-labs/loxia-onbuzz`).
+ *   `update-notifier` reads the package name from the runtime
+ *   package.json so each brand's notifier checks the right registry
+ *   entry automatically.
+ *
+ * Kill-switch:
+ *   - LOXIA_DISABLE_UPDATE_CHECK=1   — our env var (preferred)
+ *   - NO_UPDATE_NOTIFIER=1           — package's own opt-out
+ *   - CI=true                        — most CIs set this; we honour it
+ *
+ * Dependency tolerance:
+ *   `update-notifier` is dynamically imported. If the package isn't
+ *   installed (e.g. dev tree without `npm install`), the function is
+ *   a silent no-op — the CLI MUST still boot.
+ *
+ * Network tolerance:
+ *   The check is a background fetch with cached result. We never await
+ *   the network — `update-notifier` schedules a child-process fetch
+ *   and writes the result to ~/.config/configstore for the NEXT run.
+ *   That means: the FIRST time a user is offline, no banner. Subsequent
+ *   runs use the cached version-comparison until the next check window.
+ */
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Env vars that disable the check. All are case-sensitive string
+ * comparisons against `'1'` / `'true'` to match common conventions.
+ */
+const DISABLE_ENVS = Object.freeze([
+  'LOXIA_DISABLE_UPDATE_CHECK',
+  'NO_UPDATE_NOTIFIER',
+  'CI',                       // standard CI marker
+]);
+
+/** How often update-notifier should re-check the npm registry. */
+const UPDATE_CHECK_INTERVAL_MS = 1000 * 60 * 60 * 24; // 24h
+
+/**
+ * @returns {boolean} true if any kill-switch env is set truthy.
+ */
+export function isUpdateCheckDisabled(env = process.env) {
+  for (const key of DISABLE_ENVS) {
+    const v = env[key];
+    if (v && v !== '0' && v.toLowerCase() !== 'false') return true;
+  }
+  return false;
+}
+
+/**
+ * Load the package.json this CLI is running from (the installed one,
+ * not the one in src/utilities of a dev tree). Returned object always
+ * has at least `name` and `version`.
+ *
+ * @returns {{ name: string, version: string } | null}
+ */
+export function loadPackageJson({
+  startDir = dirname(fileURLToPath(import.meta.url)),
+  fs = { readFileSync },
+} = {}) {
+  // Walk up from this file looking for package.json with a `bin`
+  // entry — that's the published CLI package, not a nested dep.
+  let dir = startDir;
+  const ROOT_LIMIT = 8;
+  for (let i = 0; i < ROOT_LIMIT; i++) {
+    try {
+      const raw = fs.readFileSync(join(dir, 'package.json'), 'utf8');
+      const pkg = JSON.parse(raw);
+      if (pkg.bin || pkg.name?.startsWith('@loxia-labs/')) {
+        return { name: pkg.name, version: pkg.version };
+      }
+    } catch { /* keep walking */ }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Run the update check and (if a newer version is on the registry)
+ * print a banner. Never throws. Never blocks. Safe to call exactly
+ * once at CLI entry.
+ *
+ * Returns the underlying notifier instance for tests, or null when
+ * disabled / package missing / pkg.json unreadable.
+ */
+export async function runUpdateCheck({
+  env = process.env,
+  pkg = loadPackageJson(),
+  importImpl = (specifier) => import(specifier),
+  logger = console,
+} = {}) {
+  if (isUpdateCheckDisabled(env)) return null;
+  if (!pkg) return null;
+
+  let mod;
+  try {
+    mod = await importImpl('update-notifier');
+  } catch {
+    // Package not installed in this tree. Silent no-op.
+    return null;
+  }
+
+  const updateNotifier = mod.default || mod;
+  if (typeof updateNotifier !== 'function') return null;
+
+  try {
+    const notifier = updateNotifier({
+      pkg,
+      updateCheckInterval: UPDATE_CHECK_INTERVAL_MS,
+      shouldNotifyInNpmScript: false,
+    });
+    // notify() is itself a no-op when there's no update; safe to call
+    // unconditionally.
+    notifier.notify?.({
+      defer: false,            // print before the CLI does its work
+      isGlobal: true,          // CLI ships as a global binary
+      message:
+        `Update available {currentVersion} → {latestVersion}\n` +
+        `Run \`npm i -g {packageName}\` to update.`,
+    });
+    return notifier;
+  } catch (err) {
+    // Any failure (network, configstore write, etc.) is non-fatal.
+    logger?.debug?.('[updateNotifier] check skipped:', err.message);
+    return null;
+  }
+}