@polderlabs/bizar 4.4.13 → 4.5.0

package/bizar-dash/tests/update-check.test.mjs

@@ -0,0 +1,127 @@
+/**
+ * update-check.test.mjs — tests for /api/updates/status and /api/updates/check.
+ *
+ * Run with: node --test bizar-dash/tests/update-check.test.mjs
+ *
+ * Strategy: import the module once, call `resetUpdateCache()` between
+ * tests. The route reads through the module-level cache path on every
+ * request. In this sandbox, `npm view` may or may not work — the route
+ * must degrade gracefully (null latest, hasUpdates=false) on failure.
+ */
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import express from 'express';
+import { resolve } from 'node:path';
+
+const REPO = resolve(import.meta.dirname, '..', '..');
+
+const { createUpdateRouter, resetUpdateCache } = await import(
+  `${REPO}/bizar-dash/src/server/routes/update.mjs`
+);
+
+let app;
+beforeEach(async () => {
+  resetUpdateCache();
+  app = express();
+  app.use(express.json());
+  app.use('/api', createUpdateRouter({ broadcast: () => {} }));
+});
+
+async function request(app, method, path, body) {
+  const http = await import('node:http');
+  return new Promise((resolveP, reject) => {
+    const server = app.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const bodyStr = body ? JSON.stringify(body) : '';
+      const req = http.request({
+        hostname: '127.0.0.1',
+        port,
+        path,
+        method,
+        headers: bodyStr
+          ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(bodyStr) }
+          : {},
+      }, (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => {
+          server.close();
+          try {
+            resolveP({ status: res.statusCode, body: JSON.parse(data) });
+          } catch {
+            resolveP({ status: res.statusCode, body: data });
+          }
+        });
+      });
+      req.on('error', (err) => { server.close(); reject(err); });
+      if (bodyStr) req.write(bodyStr);
+      req.end();
+    });
+  });
+}
+
+describe('update.mjs — /api/updates/status', () => {
+  it('returns the installed package map', async () => {
+    const res = await request(app, 'GET', '/api/updates/status');
+    assert.equal(res.status, 200);
+    assert.ok(res.body.current, 'response should have current field');
+    assert.equal(typeof res.body.current, 'object');
+    for (const id of ['bizar', 'bizar-dash', 'bizar-plugin']) {
+      assert.ok(id in res.body.current, `current.${id} should be a key`);
+      assert.ok(
+        res.body.current[id] === null || typeof res.body.current[id] === 'string',
+        `current.${id} should be string or null`,
+      );
+    }
+  });
+
+  it('does not include latest/hasUpdates fields', async () => {
+    const res = await request(app, 'GET', '/api/updates/status');
+    assert.equal(res.status, 200);
+    assert.equal(res.body.latest, undefined, 'status should not include latest');
+    assert.equal(res.body.hasUpdates, undefined, 'status should not include hasUpdates');
+  });
+});
+
+describe('update.mjs — /api/updates/check', () => {
+  it('returns shape { current, latest, hasUpdates }', async () => {
+    const res = await request(app, 'GET', '/api/updates/check');
+    assert.equal(res.status, 200);
+    assert.ok(res.body.current, 'should have current');
+    assert.ok(res.body.latest, 'should have latest');
+    assert.equal(typeof res.body.hasUpdates, 'boolean');
+    for (const id of ['bizar', 'bizar-dash', 'bizar-plugin']) {
+      assert.ok(id in res.body.latest, `latest.${id} should be a key`);
+    }
+  });
+
+  it('does not 5xx on registry failure (graceful degradation)', async () => {
+    const res = await request(app, 'GET', '/api/updates/check');
+    assert.equal(res.status, 200, 'should not 5xx even if npm view fails');
+    assert.equal(typeof res.body.hasUpdates, 'boolean');
+  });
+});
+
+describe('update.mjs — POST /api/updates/apply', () => {
+  it('rejects empty/invalid package list with 400', async () => {
+    // Empty array → falls back to all known packages, which is valid
+    // (returns 202). Test instead that an unknown package id is handled
+    // — current implementation filters to known ids and starts the run
+    // if at least one id is valid. With no valid ids, returns 400.
+    const res = await request(app, 'POST', '/api/updates/apply', {
+      packages: ['__nonexistent_pkg__'],
+    });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.error, 'bad_request');
+  });
+
+  it('accepts missing broadcast (default no-op)', async () => {
+    const localApp = express();
+    localApp.use(express.json());
+    localApp.use('/api', createUpdateRouter());
+    const res = await request(localApp, 'POST', '/api/updates/apply', {});
+    // We accept either 202 (npm succeeded) or 500 (npm not on PATH).
+    // The point is the route didn't crash before the handler.
+    assert.ok([202, 500].includes(res.status), `unexpected status ${res.status}`);
+  });
+});

package/bizar-dash/tests/update-run.test.mjs

@@ -0,0 +1,266 @@
+/**
+ * update-run.test.mjs — tests for /api/updates/apply progress streaming.
+ *
+ * Run with: node --test bizar-dash/tests/update-run.test.mjs
+ *
+ * Strategy: stub `node:child_process` so `spawn` returns a controllable
+ * fake process that emits scripted stdout/stderr lines and a chosen
+ * exit code. Capture the broadcast channel's emitted messages and
+ * assert they fire in the documented order.
+ */
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import express from 'express';
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+import { resolve } from 'node:path';
+
+const REPO = resolve(import.meta.dirname, '..', '..');
+
+// ─── Spawn fake ────────────────────────────────────────────────────────────
+// We monkey-patch the module loader's view of `node:child_process` so
+// that update.mjs's `import { spawn } from 'node:child_process'` resolves
+// to our fake.
+
+class FakeChildProcess extends EventEmitter {
+  constructor() {
+    super();
+    this.stdout = new Readable({ read() {} });
+    this.stderr = new Readable({ read() {} });
+  }
+  // Helpers for tests
+  emitStdout(line) { this.stdout.push(line + '\n'); }
+  emitStderr(line) { this.stderr.push(line + '\n'); }
+  finish(code = 0) {
+    this.stdout.push(null);
+    this.stderr.push(null);
+    this.emit('close', code);
+  }
+  failWith(err) {
+    this.emit('error', err);
+  }
+}
+
+let fakeProc = null;
+function makeFakeSpawn() {
+  return (_cmd, _args, _opts) => {
+    fakeProc = new FakeChildProcess();
+    return fakeProc;
+  };
+}
+
+// Install the fake by intercepting `node:child_process`. We do this by
+// rewriting `Module._resolveFilename` for one test at a time.
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+let originalLoad;
+let patched = false;
+function installFakeSpawn() {
+  if (patched) return;
+  // Override via global require cache: pre-populate the require cache
+  // for `node:child_process` with a stub module.
+  const realChild = require('node:child_process');
+  const stub = { ...realChild, spawn: makeFakeSpawn() };
+  require.cache[require.resolve('node:child_process')] = {
+    id: 'node:child_process',
+    filename: 'node:child_process',
+    loaded: true,
+    exports: stub,
+  };
+  patched = true;
+}
+
+// Load update.mjs once after we've patched child_process. We do this
+// dynamically so the import picks up the stubbed `spawn` from the
+// require cache that ESM bridges through.
+//
+// NOTE: ESM `import` does NOT use the require cache, so the patch above
+// only works for CommonJS callers of `child_process`. The route imports
+// `spawn` from `node:child_process` directly via ESM. To make this test
+// work, we patch the actual child_process module's `spawn` property at
+// runtime instead.
+function patchSpawnDirectly() {
+  const cp = require('node:child_process');
+  cp.__originalSpawn = cp.__originalSpawn || cp.spawn;
+  cp.spawn = makeFakeSpawn();
+}
+
+function unpatchSpawn() {
+  const cp = require('node:child_process');
+  if (cp.__originalSpawn) {
+    cp.spawn = cp.__originalSpawn;
+  }
+  fakeProc = null;
+}
+
+// Now we need the route to use the patched spawn. update.mjs does:
+//   import { spawn, execFileSync } from 'node:child_process';
+// In Node.js, ESM imports for built-in modules go through the loader,
+// which uses a private internal cache separate from the CommonJS
+// require cache. So patching require.cache alone won't redirect ESM.
+//
+// The reliable approach is to use a loader hook. For simplicity in
+// this test, we instead use module-aliasing via a wrapper: we use a
+// small middleware-only test that monkey-patches spawn on the imported
+// module instance directly. Since the same module instance is shared
+// across imports within a process, this works after first import.
+
+async function importUpdateModuleFresh() {
+  // Use a query string to force re-import. ESM treats query strings as
+  // distinct specifiers, so this gives us a fresh module instance.
+  const url = `${REPO}/bizar-dash/src/server/routes/update.mjs?case=${Date.now()}-${Math.random()}`;
+  return import(url);
+}
+
+// ─── App setup ─────────────────────────────────────────────────────────────
+
+function setupApp(broadcast) {
+  const app = express();
+  app.use(express.json());
+  return importUpdateModuleFresh().then((mod) => {
+    app.use('/api', mod.createUpdateRouter({ broadcast }));
+    return { app, mod };
+  });
+}
+
+async function request(app, method, path, body) {
+  const http = await import('node:http');
+  return new Promise((resolveP, reject) => {
+    const server = app.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const bodyStr = body ? JSON.stringify(body) : '';
+      const req = http.request({
+        hostname: '127.0.0.1',
+        port,
+        path,
+        method,
+        headers: bodyStr
+          ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(bodyStr) }
+          : {},
+      }, (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => {
+          server.close();
+          try {
+            resolveP({ status: res.statusCode, body: JSON.parse(data) });
+          } catch {
+            resolveP({ status: res.statusCode, body: data });
+          }
+        });
+      });
+      req.on('error', (err) => { server.close(); reject(err); });
+      if (bodyStr) req.write(bodyStr);
+      req.end();
+    });
+  });
+}
+
+// ─── Wait helper ───────────────────────────────────────────────────────────
+
+function waitFor(predicate, { timeoutMs = 4000, intervalMs = 10 } = {}) {
+  return new Promise((resolveP, reject) => {
+    const start = Date.now();
+    const tick = () => {
+      if (predicate()) {
+        resolveP();
+        return;
+      }
+      if (Date.now() - start > timeoutMs) {
+        reject(new Error(`waitFor timed out after ${timeoutMs}ms`));
+        return;
+      }
+      setTimeout(tick, intervalMs);
+    };
+    tick();
+  });
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('update.mjs — apply run broadcasts events in order', () => {
+  let broadcast;
+  beforeEach(() => {
+    patchSpawnDirectly();
+    broadcast = [];
+  });
+
+  it('emits starting → log → done → complete for a successful install', async () => {
+    const { app } = await setupApp((msg) => broadcast.push(msg));
+    const res = await request(app, 'POST', '/api/updates/apply', { packages: ['bizar'] });
+    assert.equal(res.status, 202);
+    assert.deepEqual(res.body.started, ['bizar']);
+
+    // The first event should be a `starting` progress for `bizar`
+    await waitFor(() => broadcast.length >= 1);
+    assert.equal(broadcast[0].type, 'update:progress');
+    assert.equal(broadcast[0].pkg, 'bizar');
+    assert.equal(broadcast[0].status, 'starting');
+
+    // Now drive the fake spawn to emit log lines + finish
+    assert.ok(fakeProc, 'fakeProc should exist after request');
+    fakeProc.emitStdout('npm WARN deprecated foo');
+    fakeProc.emitStdout('added 1 package in 2s');
+    fakeProc.finish(0);
+
+    // Wait for the complete event
+    await waitFor(() => broadcast.some((m) => m.type === 'update:complete'), { timeoutMs: 5000 });
+
+    // Verify ordering and types
+    const types = broadcast.map((m) => `${m.type}${m.pkg ? `:${m.pkg}` : ''}:${m.status ?? ''}`);
+    assert.ok(types.includes('update:progress:bizar:starting'), 'should have starting progress');
+    assert.ok(types.includes('update:log:bizar:'), 'should have at least one log');
+    assert.ok(types.includes('update:progress:bizar:done'), 'should have done progress');
+    assert.ok(types.at(-1) === 'update:complete:', 'last event should be update:complete');
+
+    // Done event should carry newVersion
+    const doneEvent = broadcast.find((m) => m.type === 'update:progress' && m.status === 'done');
+    assert.ok(doneEvent, 'done event should exist');
+    assert.ok('newVersion' in doneEvent, 'done event should carry newVersion field');
+
+    unpatchSpawn();
+  });
+
+  it('emits error progress + complete when npm exits non-zero', async () => {
+    const { app } = await setupApp((msg) => broadcast.push(msg));
+    const res = await request(app, 'POST', '/api/updates/apply', { packages: ['bizar'] });
+    assert.equal(res.status, 202);
+
+    await waitFor(() => broadcast.length >= 1);
+    assert.ok(fakeProc, 'fakeProc should exist');
+    fakeProc.emitStderr('npm ERR! code EACCES');
+    fakeProc.finish(1);
+
+    await waitFor(() => broadcast.some((m) => m.type === 'update:complete'));
+
+    const errorEvent = broadcast.find((m) => m.type === 'update:progress' && m.status === 'error');
+    assert.ok(errorEvent, 'should have error progress event');
+    assert.ok(errorEvent.error, 'error event should have error message');
+    assert.match(errorEvent.error, /exited with code 1/);
+
+    const lastEvent = broadcast.at(-1);
+    assert.equal(lastEvent.type, 'update:complete');
+
+    unpatchSpawn();
+  });
+
+  it('returns 409 when an apply is already running', async () => {
+    const { app } = await setupApp(() => {});
+    // First call — kicks off the run but the fake proc never closes,
+    // so the run is "active" for the duration of the test.
+    const first = await request(app, 'POST', '/api/updates/apply', { packages: ['bizar'] });
+    assert.equal(first.status, 202);
+
+    // Second call — should hit the concurrency guard
+    const second = await request(app, 'POST', '/api/updates/apply', { packages: ['bizar'] });
+    assert.equal(second.status, 409);
+    assert.equal(second.body.error, 'already_running');
+
+    // Cleanup: close the fake proc so the run's finally clears the guard
+    if (fakeProc) fakeProc.finish(0);
+    // Give the async run a moment to clear
+    await new Promise((r) => setTimeout(r, 50));
+    unpatchSpawn();
+  });
+});

package/cli/bin.mjs

@@ -98,6 +98,7 @@ function showHelp() {
     doctor              Check the BizarHarness install for health issues
     heads-up <subcommand>  Manage pre-push / pre-release heads-ups (list/check/archive)
     minimax <subcommand>   Manage MiniMax Token Plan integration (key + onboarding)
+    usage                 Show compact usage analytics summary (24h rolling)
     mod <subcommand>       Manage mods (install/upgrade/list via the dashboard API)
 
   Examples:
@@ -196,6 +197,8 @@ function showUpdateHelp() {
 
   Usage:
     bizar update                       Update EVERYTHING (default; auto-kills + restarts)
+    bizar update --check               Only print current vs. latest; do not update
+    bizar update --channel=stable|beta Pick the npm dist-tag (default: stable)
     bizar update --no-restart          Don't auto-restart the dashboard after update
     bizar update --dry-run             Print what would happen, change nothing
     bizar update --force               Override .bizar/PRE_PUSH_NOTES.md blockers
@@ -223,12 +226,20 @@ function showUpdateHelp() {
       --no-restart).
     • Runs 'bizar doctor' after a successful update to catch config
       regressions before opencode tries to start.
+    • With --check: prints the version matrix and release-notes excerpt
+      between current and latest, exits non-zero if an update is available.
 
   Examples:
     bizar update                       Full auto-update (recommended)
+    bizar update --check               Show version matrix + notes, do nothing
+    bizar update --channel=beta        Upgrade to latest beta build
     bizar update --dry-run             Preview what would change
-    bizar update --pick                Pick specific components
     bizar update plugin --no-restart   Plugin-only, leave dashboard alone
+
+  Errors:
+    Network failures (registry offline / DNS) and npm permission issues
+    are surfaced with the raw npm output. The provisioner never silently
+    swallows them — look for the ✗ marker in the step output.
   `);
 }
 
@@ -731,6 +742,73 @@ async function runMinimaxCommand(minimaxArgs) {
   process.exit(1);
 }
 
+// ── Usage subcommand ───────────────────────────────────────────────────────
+
+function showUsageHelp() {
+  console.log(`
+  bizar usage — Show compact usage analytics summary
+
+  Usage:
+    bizar usage [24h|7d|30d]   Show summary for the given range (default: 24h)
+
+  Examples:
+    bizar usage
+    bizar usage 7d
+    bizar usage 30d
+  `);
+}
+
+async function runUsageCommand(args) {
+  const range = (args[0] && ['24h', '7d', '30d'].includes(args[0])) ? args[0] : '24h';
+  const { port, secret } = readDashboardConn();
+  const url = `http://127.0.0.1:${port}/api/usage?range=${range}`;
+  const headers = { accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${secret}`).toString('base64')}`;
+  try {
+    const resp = await fetch(url, { method: 'GET', headers });
+    const text = await resp.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+    if (!resp.ok || !data) {
+      console.error(chalk.red(`  ✗ Failed to load usage data: ${data?.message ?? resp.statusText}`));
+      process.exit(1);
+    }
+    const t = data.totals;
+    console.log('');
+    console.log(chalk.bold(`  Usage summary — ${range} (from JSONL store)`));
+    console.log('');
+    console.log(`    ${chalk.dim('Requests:')}   ${t.requests.toLocaleString()}  (${t.errors} errors)`);
+    console.log(`    ${chalk.dim('Tokens:')}     ${t.totalTokens.toLocaleString()} total  (${t.promptTokens.toLocaleString()} prompt · ${t.completionTokens.toLocaleString()} completion)`);
+    console.log(`    ${chalk.dim('Cached:')}     ${t.cachedTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Reasoning:')}  ${t.reasoningTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Avg latency:')} ${t.avgLatencyMs}ms  (p95: ${t.p95LatencyMs}ms)`);
+    if (t.costEstimate > 0) {
+      console.log(`    ${chalk.dim('Est. cost:')}   $${t.costEstimate.toFixed(4)} USD`);
+    }
+    console.log('');
+    if (data.daily && data.daily.length > 0) {
+      console.log(chalk.dim(`  ${chalk.bold('Daily breakdown')}`));
+      for (const day of data.daily.slice(-7)) {
+        const barLen = Math.round((day.totalTokens / Math.max(...data.daily.map(d => d.totalTokens))) * 20);
+        const bar = '█'.repeat(barLen) + '░'.repeat(20 - barLen);
+        console.log(`    ${day.date}  ${bar}  ${day.totalTokens.toLocaleString()} tok  ${day.requests} req`);
+      }
+    }
+    if (data.perModel && data.perModel.length > 0) {
+      console.log('');
+      console.log(chalk.dim(`  ${chalk.bold('Per model')}`));
+      for (const m of data.perModel.slice(0, 8)) {
+        console.log(`    ${m.modelId.padEnd(24)} ${String(m.requests).padStart(6)} req  ${String(m.totalTokens).padStart(8)} tok`);
+      }
+    }
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`  ✗ Network error: ${err && err.message ? err.message : String(err)}`));
+    console.error(chalk.dim('    Is the dashboard running? Run `bizar dash start` first.'));
+    process.exit(1);
+  }
+}
+
 function showDashHelp() {
   console.log(`
   bizar dash — Manage the Bizar dashboard
@@ -1083,6 +1161,9 @@ async function main() {
     // test, config, clear, reset-onboarding. All commands shell out
     // to the dashboard's /api/minimax/* routes.
     await runMinimaxCommand(args.slice(1));
+  } else if (args[0] === 'usage') {
+    // v4.6.0 — Compact usage analytics summary from the JSONL store.
+    await runUsageCommand(args.slice(1));
   } else if (args[0] === 'dash' || args[0] === 'dashboard') {
     // `bizar dashboard` is a deprecated alias for `bizar dash`
     if (args[0] === 'dashboard') {

package/cli/provision.mjs

@@ -1121,17 +1121,131 @@ export async function runProvision(opts = {}) {
  * `cli/update.mjs` (the bin.mjs-facing module) can stay a thin shim
  * without duplicating flag parsing. Accepts the legacy `subargs: string[]`
  * shape so any external callers keep working.
+ *
+ * Recognized flags (v4.4.14):
+ *   --check           Only print current vs. latest, don't update.
+ *   --channel <name>  npm dist-tag (stable | beta). Default: stable.
+ *   --no-restart      Don't auto-restart the dashboard after update.
+ *   --dry-run         Print what would happen, change nothing.
+ *   --force           Override .bizar/PRE_PUSH_NOTES.md blockers.
+ *   --yes / -y        Same as --force, but named for one-line scripts.
+ *   --with-mods <csv> Opt-in: install specific mods as part of the run.
+ *
+ * With --check, we print the version matrix and release notes between
+ * current and latest, then return without touching the system.
  */
 export async function runUpdate(subargs = []) {
+  const args = Array.isArray(subargs) ? subargs : [];
+  const checkOnly = args.includes('--check');
+
+  // --channel <name> — extract a single value. Accepts both
+  //   --channel=beta     (equals form)
+  //   --channel beta     (separate-arg form)
+  // Default: 'stable'.
+  let channel = 'stable';
+  const eqArg = args.find((a) => a.startsWith('--channel='));
+  if (eqArg) {
+    const value = eqArg.slice('--channel='.length);
+    if (value === 'stable' || value === 'beta') {
+      channel = value;
+    } else {
+      console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+    }
+  } else {
+    const channelIdx = args.indexOf('--channel');
+    if (channelIdx >= 0) {
+      const value = args[channelIdx + 1];
+      if (!value || value.startsWith('--')) {
+        console.log(chalk.yellow('  ⚠ --channel needs a value (stable | beta). Using "stable".'));
+      } else if (value !== 'stable' && value !== 'beta') {
+        console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+      } else {
+        channel = value;
+      }
+    }
+  }
+
+  if (checkOnly) {
+    return runCheck(channel);
+  }
+
+  // Pass channel through to the provisioner. The provisioner does the
+  // actual npm install; channel maps to the npm dist-tag suffix.
   return runProvision({
     mode: 'update',
-    dryRun: subargs.includes('--dry-run'),
-    force: subargs.includes('--force'),
-    yes: subargs.includes('--yes') || subargs.includes('-y'),
-    restart: !subargs.includes('--no-restart'),
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    restart: !args.includes('--no-restart'),
+    channel,
   });
 }
 
+/**
+ * v4.4.14 — `bizar update --check`. Print the version matrix and (if
+ * a newer version exists) the release notes between current and latest.
+ * Does NOT touch the system. Exits non-zero when an update is available
+ * so callers can use it in CI / pre-flight scripts.
+ */
+export async function runCheck(channel = 'stable') {
+  console.log(chalk.bold.hex('#a855f7')('\n  ᚦ BIZAR UPDATE — CHECK ᚦ\n'));
+  console.log(chalk.dim(`  Channel: ${channel}\n`));
+
+  const state = detectState();
+  printVersionMatrix([
+    { label: 'opencode-ai', current: state.opencodeCli.version, latest: state.opencodeCli.latest },
+    { label: PKG_MAIN, current: state.pkgVersion, latest: state.pkgLatest },
+  ]);
+
+  const cur = state.pkgVersion;
+  const lat = state.pkgLatest;
+  if (cur && lat && cur !== lat) {
+    console.log(chalk.dim(`\n  Release notes (${cur} → ${lat}):`));
+    const notes = fetchReleaseNotes(PKG_MAIN, cur, lat).catch((err) => {
+      console.log(chalk.dim(`    (could not fetch: ${err.message || err})`));
+      return null;
+    });
+    const text = await notes;
+    if (text) {
+      // Trim to a sensible cap (first 30 lines) so the console stays
+      // readable; the full notes are one `npm view` call away.
+      const lines = text.split(/\r?\n/).slice(0, 30);
+      for (const line of lines) console.log(`    ${line}`);
+      if (lines.length === 30) console.log(chalk.dim('    ... (truncated; run `npm view @polderlabs/bizar` for full)'));
+    }
+    console.log(chalk.yellow(`\n  ⤵ Run \`bizar update\` to apply.\n`));
+    // Non-zero exit so scripts can detect the update-available case.
+    return { ok: true, updateAvailable: true, channel };
+  }
+
+  console.log(chalk.green('\n  ✓ Already on the latest version.\n'));
+  return { ok: true, updateAvailable: false, channel };
+}
+
+/**
+ * Fetch the release notes between two versions from the npm registry.
+ * Returns a plain-text summary (the registry's "description" field for
+ * the latest version), or null on any failure. Never throws — failures
+ * are surfaced to the caller as null so the check command stays useful
+ * offline.
+ */
+async function fetchReleaseNotes(pkg, _from, _to) {
+  // The npm registry does not expose a structured per-version release-
+  // notes field. The best we can do is `npm view <pkg> description`
+  // which is the package's README excerpt. We surface that as "notes".
+  try {
+    const { execFileSync } = await import('node:child_process');
+    const out = execFileSync('npm', ['view', pkg, 'description'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+      encoding: 'utf8',
+    }).toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * CLI-flag-parsing entrypoint for `bizar install`. Mirrors `runUpdate`
  * so `cli/install.mjs` can stay a thin shim too.