@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/src/cli/render.js

@@ -1,194 +1,194 @@
-// Human-readable renderers for each CLI subcommand. The CLI default switched
-// from JSON-to-stdout to these in v1.1; --json restores the old behavior
-// (still useful for piping to jq, MCP-like consumers, etc.).
-//
-// Conventions:
-//   - Render functions write to process.stdout (no trailing newline beyond
-//     what the formatted output naturally has).
-//   - They never throw on missing fields — the result objects come from
-//     core/ which already shape them.
-//   - Cores happen via src/core/ui.js (which already disables in NO_COLOR
-//     or when --no-tty etc.).
-
-import path from 'node:path';
-import { c, icons, summary } from '../core/ui.js';
-
-// --- generic helpers ---
-
-function table(rows, headers) {
-  if (rows.length === 0) {
-    return `${c.dim('(empty)')}\n`;
-  }
-  const cols = headers.length;
-  const widths = new Array(cols).fill(0);
-  for (let i = 0; i < cols; i++) widths[i] = Math.max(headers[i].length, ...rows.map(r => String(r[i] ?? '').length));
-  const out = [];
-  out.push(headers.map((h, i) => c.bold(h.padEnd(widths[i]))).join('  '));
-  out.push(headers.map((_, i) => c.dim('─'.repeat(widths[i]))).join('  '));
-  for (const r of rows) {
-    out.push(r.map((v, i) => String(v ?? '').padEnd(widths[i])).join('  '));
-  }
-  return out.join('\n') + '\n';
-}
-
-// --- kit ---
-
-export function renderKitList(items, kind) {
-  if (items.length === 0) {
-    return `${c.dim(`No ${kind}s in kit.`)}\n`;
-  }
-  const rows = items.map(x => [x.name, (x.description ?? '').slice(0, 80)]);
-  return table(rows, ['name', 'description']);
-}
-
-export function renderKitSearch(results) {
-  if (results.length === 0) {
-    return `${c.dim('No matches.')}\n`;
-  }
-  const rows = results.map(x => [x.kind, x.name, (x.description ?? '').slice(0, 70)]);
-  return table(rows, ['kind', 'name', 'description']);
-}
-
-// --- sync ---
-
-export function renderSyncTargets(targets) {
-  const rows = targets.map(t => [
-    t.id,
-    t.label,
-    Object.entries(t.capabilities).filter(([, v]) => v).map(([k]) => k).join(', '),
-  ]);
-  return table(rows, ['id', 'label', 'capabilities']);
-}
-
-export function renderSyncStatus(result) {
-  const rows = result.checks.map(c => [c.capability, c.path, c.exists ? '✓' : '—']);
-  return `${c.bold(`Status: ${result.target}`)}  ${c.dim(result.projectRoot)}\n` + table(rows, ['cap', 'path', 'present']);
-}
-
-export function renderSyncInstall(result) {
-  // Tally written paths by capability prefix
-  const counts = {};
-  for (const p of result.written) {
-    const rel = path.relative(result.projectRoot, p).replace(/\\/g, '/');
-    // Hide internal markers from the user-facing tally (they're a kit-mcp impl detail)
-    if (rel.endsWith('/.kit-mcp-managed')) continue;
-    let cap = 'rules';
-    if (rel.includes('.claude/agents/'))    cap = 'agents';
-    else if (rel.includes('.claude/commands/'))  cap = 'commands';
-    else if (rel.includes('.claude/skills/'))    cap = 'skills';
-    else if (rel.includes('.claude/framework/')) cap = 'framework';
-    else if (rel.includes('.claude/hooks/'))     cap = 'hooks';
-    counts[cap] = (counts[cap] ?? 0) + 1;
-  }
-  const rows = [];
-  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
-    if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
-  }
-  const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
-  // Phase 160 (v1.28): append diff tally row if cli attached one.
-  if (result._tally) {
-    const w = result._tally.written;
-    const s = result._tally.skipped;
-    rows.push(['new / updated', w]);
-    rows.push(['unchanged', s]);
-  }
-  return summary({
-    title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
-    rows,
-    total: visibleTotal,
-    hint: c.dim(result.projectRoot),
-  }) + '\n';
-}
-
-export function renderSyncRemove(result) {
-  return summary({
-    title: `Removed kit-mcp stubs from ${result.target}`,
-    rows: [['Files removed', result.removed.length]],
-    total: result.removed.length,
-    hint: c.dim(result.projectRoot),
-  }) + '\n';
-}
-
-// --- reverse-sync ---
-
-export function renderReverseDetect(result) {
-  if (result.candidates.length === 0) {
-    return `${c.green(icons.check)} No edits to bring back. Canonical kit and ${result.target} are in sync.\n`;
-  }
-  const rows = result.candidates.map(x => [x.kind, x.name, x.reason, x.diffSummary ?? '']);
-  return `${c.bold(`Candidates: ${result.candidates.length}`)}  ${c.dim(`(${result.target})`)}\n` +
-    table(rows, ['kind', 'name', 'reason', 'diff']);
-}
-
-export function renderReverseApply(result) {
-  const rows = result.results.map(x => [
-    x.kind,
-    x.name,
-    x.action.startsWith('overwrit') || x.action.startsWith('merge') || x.action.startsWith('renamed')
-      ? c.green(x.action)
-      : x.action.startsWith('skipped') ? c.dim(x.action) : c.yellow(x.action),
-  ]);
-  return `${c.bold(`Applied (strategy=${result.strategy})`)}\n` + table(rows, ['kind', 'name', 'action']);
-}
-
-// --- gates ---
-
-export function renderGatesList(items) {
-  const rows = items.map(g => [g.id, g.stage, g.blocking ? c.red('blocking') : c.dim('warn-only'), g.description]);
-  return table(rows, ['id', 'stage', 'mode', 'description']);
-}
-
-export function renderGateRun(result) {
-  const verdictColor = result.verdict === 'passed' ? c.green
-                     : result.verdict === 'block'  ? c.red
-                     : result.verdict === 'warn'   ? c.yellow
-                     : c.dim;
-  return `${c.bold(`Gate ${result.id}`)}: ${verdictColor(result.verdict)} ${result.exitCode !== undefined ? c.dim(`(exit ${result.exitCode})`) : ''}\n`;
-}
-
-// --- forensics ---
-
-export function renderForensicsCollect(items) {
-  if (items.length === 0) return `${c.dim('No failures collected.')}\n`;
-  const rows = items.map(x => [x.agent ?? '?', x.kind ?? '?', x.absPath ?? x.path ?? '']);
-  return table(rows, ['agent', 'kind', 'path']);
-}
-
-export function renderForensicsSummarize(byAgent) {
-  const entries = Object.entries(byAgent ?? {});
-  if (entries.length === 0) return `${c.dim('No failures.')}\n`;
-  const rows = entries.map(([agent, items]) => [agent, Array.isArray(items) ? items.length : '?']);
-  return table(rows, ['agent', 'failures']);
-}
-
-export function renderListReplays(items) {
-  if (!Array.isArray(items) || items.length === 0) return `${c.dim('No replays recorded.')}\n`;
-  const rows = items.map(r => [r.id ?? '?', r.agent ?? '?', r.timestamp ?? '?']);
-  return table(rows, ['id', 'agent', 'recorded']);
-}
-
-// --- install ---
-
-export function renderInstallTargets(targets) {
-  const rows = targets.map(t => [t.id, t.label, t.scopes?.join(', ') ?? '?']);
-  return table(rows, ['id', 'label', 'scopes']);
-}
-
-export function renderInstallResult(result) {
-  return summary({
-    title: result.dryRun ? `Install preview (${result.target}, scope=${result.scope})` : `Registered kit-mcp → ${result.target} (scope=${result.scope})`,
-    rows: [
-      ['Path',  result.path ?? '?'],
-      ['Name',  result.name ?? 'kit'],
-      ['Via',   result.via ?? '?'],
-    ].map(([k, v]) => [k, v ?? '—']),
-    hint: result.dryRun ? c.dim('No file written (dry-run)') : undefined,
-  }) + '\n';
-}
-
-// --- generic fallback ---
-
-export function renderFallback(value) {
-  // Used when we don't have a custom renderer yet.
-  return JSON.stringify(value, null, 2) + '\n';
-}
+// Human-readable renderers for each CLI subcommand. The CLI default switched
+// from JSON-to-stdout to these in v1.1; --json restores the old behavior
+// (still useful for piping to jq, MCP-like consumers, etc.).
+//
+// Conventions:
+//   - Render functions write to process.stdout (no trailing newline beyond
+//     what the formatted output naturally has).
+//   - They never throw on missing fields — the result objects come from
+//     core/ which already shape them.
+//   - Cores happen via src/core/ui.js (which already disables in NO_COLOR
+//     or when --no-tty etc.).
+
+import path from 'node:path';
+import { c, icons, summary } from '../core/ui.js';
+
+// --- generic helpers ---
+
+function table(rows, headers) {
+  if (rows.length === 0) {
+    return `${c.dim('(empty)')}\n`;
+  }
+  const cols = headers.length;
+  const widths = new Array(cols).fill(0);
+  for (let i = 0; i < cols; i++) widths[i] = Math.max(headers[i].length, ...rows.map(r => String(r[i] ?? '').length));
+  const out = [];
+  out.push(headers.map((h, i) => c.bold(h.padEnd(widths[i]))).join('  '));
+  out.push(headers.map((_, i) => c.dim('─'.repeat(widths[i]))).join('  '));
+  for (const r of rows) {
+    out.push(r.map((v, i) => String(v ?? '').padEnd(widths[i])).join('  '));
+  }
+  return out.join('\n') + '\n';
+}
+
+// --- kit ---
+
+export function renderKitList(items, kind) {
+  if (items.length === 0) {
+    return `${c.dim(`No ${kind}s in kit.`)}\n`;
+  }
+  const rows = items.map(x => [x.name, (x.description ?? '').slice(0, 80)]);
+  return table(rows, ['name', 'description']);
+}
+
+export function renderKitSearch(results) {
+  if (results.length === 0) {
+    return `${c.dim('No matches.')}\n`;
+  }
+  const rows = results.map(x => [x.kind, x.name, (x.description ?? '').slice(0, 70)]);
+  return table(rows, ['kind', 'name', 'description']);
+}
+
+// --- sync ---
+
+export function renderSyncTargets(targets) {
+  const rows = targets.map(t => [
+    t.id,
+    t.label,
+    Object.entries(t.capabilities).filter(([, v]) => v).map(([k]) => k).join(', '),
+  ]);
+  return table(rows, ['id', 'label', 'capabilities']);
+}
+
+export function renderSyncStatus(result) {
+  const rows = result.checks.map(c => [c.capability, c.path, c.exists ? '✓' : '—']);
+  return `${c.bold(`Status: ${result.target}`)}  ${c.dim(result.projectRoot)}\n` + table(rows, ['cap', 'path', 'present']);
+}
+
+export function renderSyncInstall(result) {
+  // Tally written paths by capability prefix
+  const counts = {};
+  for (const p of result.written) {
+    const rel = path.relative(result.projectRoot, p).replace(/\\/g, '/');
+    // Hide internal markers from the user-facing tally (they're a kit-mcp impl detail)
+    if (rel.endsWith('/.kit-mcp-managed')) continue;
+    let cap = 'rules';
+    if (rel.includes('.claude/agents/'))    cap = 'agents';
+    else if (rel.includes('.claude/commands/'))  cap = 'commands';
+    else if (rel.includes('.claude/skills/'))    cap = 'skills';
+    else if (rel.includes('.claude/framework/')) cap = 'framework';
+    else if (rel.includes('.claude/hooks/'))     cap = 'hooks';
+    counts[cap] = (counts[cap] ?? 0) + 1;
+  }
+  const rows = [];
+  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
+    if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
+  }
+  const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  // Phase 160 (v1.28): append diff tally row if cli attached one.
+  if (result._tally) {
+    const w = result._tally.written;
+    const s = result._tally.skipped;
+    rows.push(['new / updated', w]);
+    rows.push(['unchanged', s]);
+  }
+  return summary({
+    title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
+    rows,
+    total: visibleTotal,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+export function renderSyncRemove(result) {
+  return summary({
+    title: `Removed kit-mcp stubs from ${result.target}`,
+    rows: [['Files removed', result.removed.length]],
+    total: result.removed.length,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+// --- reverse-sync ---
+
+export function renderReverseDetect(result) {
+  if (result.candidates.length === 0) {
+    return `${c.green(icons.check)} No edits to bring back. Canonical kit and ${result.target} are in sync.\n`;
+  }
+  const rows = result.candidates.map(x => [x.kind, x.name, x.reason, x.diffSummary ?? '']);
+  return `${c.bold(`Candidates: ${result.candidates.length}`)}  ${c.dim(`(${result.target})`)}\n` +
+    table(rows, ['kind', 'name', 'reason', 'diff']);
+}
+
+export function renderReverseApply(result) {
+  const rows = result.results.map(x => [
+    x.kind,
+    x.name,
+    x.action.startsWith('overwrit') || x.action.startsWith('merge') || x.action.startsWith('renamed')
+      ? c.green(x.action)
+      : x.action.startsWith('skipped') ? c.dim(x.action) : c.yellow(x.action),
+  ]);
+  return `${c.bold(`Applied (strategy=${result.strategy})`)}\n` + table(rows, ['kind', 'name', 'action']);
+}
+
+// --- gates ---
+
+export function renderGatesList(items) {
+  const rows = items.map(g => [g.id, g.stage, g.blocking ? c.red('blocking') : c.dim('warn-only'), g.description]);
+  return table(rows, ['id', 'stage', 'mode', 'description']);
+}
+
+export function renderGateRun(result) {
+  const verdictColor = result.verdict === 'passed' ? c.green
+                     : result.verdict === 'block'  ? c.red
+                     : result.verdict === 'warn'   ? c.yellow
+                     : c.dim;
+  return `${c.bold(`Gate ${result.id}`)}: ${verdictColor(result.verdict)} ${result.exitCode !== undefined ? c.dim(`(exit ${result.exitCode})`) : ''}\n`;
+}
+
+// --- forensics ---
+
+export function renderForensicsCollect(items) {
+  if (items.length === 0) return `${c.dim('No failures collected.')}\n`;
+  const rows = items.map(x => [x.agent ?? '?', x.kind ?? '?', x.absPath ?? x.path ?? '']);
+  return table(rows, ['agent', 'kind', 'path']);
+}
+
+export function renderForensicsSummarize(byAgent) {
+  const entries = Object.entries(byAgent ?? {});
+  if (entries.length === 0) return `${c.dim('No failures.')}\n`;
+  const rows = entries.map(([agent, items]) => [agent, Array.isArray(items) ? items.length : '?']);
+  return table(rows, ['agent', 'failures']);
+}
+
+export function renderListReplays(items) {
+  if (!Array.isArray(items) || items.length === 0) return `${c.dim('No replays recorded.')}\n`;
+  const rows = items.map(r => [r.id ?? '?', r.agent ?? '?', r.timestamp ?? '?']);
+  return table(rows, ['id', 'agent', 'recorded']);
+}
+
+// --- install ---
+
+export function renderInstallTargets(targets) {
+  const rows = targets.map(t => [t.id, t.label, t.scopes?.join(', ') ?? '?']);
+  return table(rows, ['id', 'label', 'scopes']);
+}
+
+export function renderInstallResult(result) {
+  return summary({
+    title: result.dryRun ? `Install preview (${result.target}, scope=${result.scope})` : `Registered kit-mcp → ${result.target} (scope=${result.scope})`,
+    rows: [
+      ['Path',  result.path ?? '?'],
+      ['Name',  result.name ?? 'kit'],
+      ['Via',   result.via ?? '?'],
+    ].map(([k, v]) => [k, v ?? '—']),
+    hint: result.dryRun ? c.dim('No file written (dry-run)') : undefined,
+  }) + '\n';
+}
+
+// --- generic fallback ---
+
+export function renderFallback(value) {
+  // Used when we don't have a custom renderer yet.
+  return JSON.stringify(value, null, 2) + '\n';
+}

package/src/cli/upgrade-check.js

@@ -1,135 +1,135 @@
-// upgrade-check.js — non-blocking check for newer kit-mcp on npm.
-//
-// Both `kit doctor` (U1) and `kit ui start` (U4) call this. Result is cached
-// to ~/.kit-mcp/version-check.json for 24h so we don't hit the npm registry on
-// every boot. Falls back gracefully when offline or when the request fails.
-
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import https from 'node:https';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const PACKAGE_NAME = '@luanpdd/kit-mcp';
-const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24h
-const REQUEST_TIMEOUT_MS = 1500;
-
-function cacheFile() {
-  return path.join(os.homedir(), '.kit-mcp', 'version-check.json');
-}
-
-async function readCache() {
-  try {
-    const raw = await fs.readFile(cacheFile(), 'utf8');
-    const obj = JSON.parse(raw);
-    if (typeof obj.checkedAt !== 'number' || typeof obj.latest !== 'string') return null;
-    if (Date.now() - obj.checkedAt > CHECK_TTL_MS) return null;
-    return obj;
-  } catch {
-    return null;
-  }
-}
-
-async function writeCache(obj) {
-  try {
-    await fs.mkdir(path.dirname(cacheFile()), { recursive: true });
-    await fs.writeFile(cacheFile(), JSON.stringify(obj), 'utf8');
-  } catch {
-    /* cache failures are silent — not critical */
-  }
-}
-
-function fetchLatest() {
-  // Use the registry's package endpoint. Falls back to gracefully on any error.
-  return new Promise((resolve) => {
-    const req = https.request({
-      method: 'GET',
-      hostname: 'registry.npmjs.org',
-      path: `/${encodeURIComponent(PACKAGE_NAME)}/latest`,
-      headers: { 'accept': 'application/json' },
-      timeout: REQUEST_TIMEOUT_MS,
-    }, (res) => {
-      if (res.statusCode !== 200) { res.resume(); resolve(null); return; }
-      let body = '';
-      res.setEncoding('utf8');
-      res.on('data', (c) => { body += c; });
-      res.on('end', () => {
-        try {
-          const j = JSON.parse(body);
-          resolve(typeof j.version === 'string' ? j.version : null);
-        } catch {
-          resolve(null);
-        }
-      });
-    });
-    req.on('error', () => resolve(null));
-    req.on('timeout', () => { try { req.destroy(); } catch { /* noop */ } resolve(null); });
-    req.end();
-  });
-}
-
-export async function getLocalVersion() {
-  // Read package.json from the kit-mcp install root (parent of src/).
-  try {
-    const pkgPath = path.resolve(__dirname, '../../package.json');
-    const raw = await fs.readFile(pkgPath, 'utf8');
-    const j = JSON.parse(raw);
-    return typeof j.version === 'string' ? j.version : null;
-  } catch {
-    return null;
-  }
-}
-
-// Compare semver-like x.y.z lexically by component. Returns -1/0/1.
-// Missing components default to 0 ("1.5" === "1.5.0").
-function compareVersions(a, b) {
-  const parse = (v) => {
-    const parts = v.split('.').map((n) => Number.parseInt(n, 10) || 0);
-    while (parts.length < 3) parts.push(0);
-    return parts;
-  };
-  const [a1, a2, a3] = parse(a);
-  const [b1, b2, b3] = parse(b);
-  if (a1 !== b1) return a1 < b1 ? -1 : 1;
-  if (a2 !== b2) return a2 < b2 ? -1 : 1;
-  if (a3 !== b3) return a3 < b3 ? -1 : 1;
-  return 0;
-}
-
-// checkUpgrade({ force }): returns { local, latest, behind, source } or null on failure.
-//   force=true bypasses the 24h cache.
-export async function checkUpgrade({ force = false } = {}) {
-  const local = await getLocalVersion();
-  if (!local) return null;
-
-  if (!force) {
-    const cached = await readCache();
-    if (cached?.latest) {
-      return {
-        local,
-        latest: cached.latest,
-        behind: compareVersions(local, cached.latest) < 0,
-        source: 'cache',
-      };
-    }
-  }
-
-  const latest = await fetchLatest();
-  if (!latest) {
-    // Network failed; surface what we have.
-    return { local, latest: null, behind: false, source: 'offline' };
-  }
-
-  await writeCache({ checkedAt: Date.now(), latest });
-  return {
-    local,
-    latest,
-    behind: compareVersions(local, latest) < 0,
-    source: 'network',
-  };
-}
-
-export const __test = { compareVersions, PACKAGE_NAME, CHECK_TTL_MS };
+// upgrade-check.js — non-blocking check for newer kit-mcp on npm.
+//
+// Both `kit doctor` (U1) and `kit ui start` (U4) call this. Result is cached
+// to ~/.kit-mcp/version-check.json for 24h so we don't hit the npm registry on
+// every boot. Falls back gracefully when offline or when the request fails.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import https from 'node:https';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PACKAGE_NAME = '@luanpdd/kit-mcp';
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const REQUEST_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  return path.join(os.homedir(), '.kit-mcp', 'version-check.json');
+}
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(cacheFile(), 'utf8');
+    const obj = JSON.parse(raw);
+    if (typeof obj.checkedAt !== 'number' || typeof obj.latest !== 'string') return null;
+    if (Date.now() - obj.checkedAt > CHECK_TTL_MS) return null;
+    return obj;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(obj) {
+  try {
+    await fs.mkdir(path.dirname(cacheFile()), { recursive: true });
+    await fs.writeFile(cacheFile(), JSON.stringify(obj), 'utf8');
+  } catch {
+    /* cache failures are silent — not critical */
+  }
+}
+
+function fetchLatest() {
+  // Use the registry's package endpoint. Falls back to gracefully on any error.
+  return new Promise((resolve) => {
+    const req = https.request({
+      method: 'GET',
+      hostname: 'registry.npmjs.org',
+      path: `/${encodeURIComponent(PACKAGE_NAME)}/latest`,
+      headers: { 'accept': 'application/json' },
+      timeout: REQUEST_TIMEOUT_MS,
+    }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); resolve(null); return; }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          resolve(typeof j.version === 'string' ? j.version : null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { try { req.destroy(); } catch { /* noop */ } resolve(null); });
+    req.end();
+  });
+}
+
+export async function getLocalVersion() {
+  // Read package.json from the kit-mcp install root (parent of src/).
+  try {
+    const pkgPath = path.resolve(__dirname, '../../package.json');
+    const raw = await fs.readFile(pkgPath, 'utf8');
+    const j = JSON.parse(raw);
+    return typeof j.version === 'string' ? j.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// Compare semver-like x.y.z lexically by component. Returns -1/0/1.
+// Missing components default to 0 ("1.5" === "1.5.0").
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const parts = v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return parts;
+  };
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 < b1 ? -1 : 1;
+  if (a2 !== b2) return a2 < b2 ? -1 : 1;
+  if (a3 !== b3) return a3 < b3 ? -1 : 1;
+  return 0;
+}
+
+// checkUpgrade({ force }): returns { local, latest, behind, source } or null on failure.
+//   force=true bypasses the 24h cache.
+export async function checkUpgrade({ force = false } = {}) {
+  const local = await getLocalVersion();
+  if (!local) return null;
+
+  if (!force) {
+    const cached = await readCache();
+    if (cached?.latest) {
+      return {
+        local,
+        latest: cached.latest,
+        behind: compareVersions(local, cached.latest) < 0,
+        source: 'cache',
+      };
+    }
+  }
+
+  const latest = await fetchLatest();
+  if (!latest) {
+    // Network failed; surface what we have.
+    return { local, latest: null, behind: false, source: 'offline' };
+  }
+
+  await writeCache({ checkedAt: Date.now(), latest });
+  return {
+    local,
+    latest,
+    behind: compareVersions(local, latest) < 0,
+    source: 'network',
+  };
+}
+
+export const __test = { compareVersions, PACKAGE_NAME, CHECK_TTL_MS };