@modelstatus/cli 0.1.1 → 0.1.26

package/src/telemetry.js

@@ -0,0 +1,66 @@
+/* Anonymous, opt-out usage analytics for the CLI/TUI (PostHog).
+ *
+ * Privacy: we send event NAMES + counts + version/OS only — never code, model
+ * strings, file paths, repo names, or your API key. The distinct id is a random
+ * per-machine UUID stored in the config (not tied to your account). Disable with
+ * any of MM_NO_ANALYTICS=1, DO_NOT_TRACK=1, or CI=1. The PostHog project token is
+ * a public ingest key (the same kind shipped in web bundles), baked at build via
+ * --define __POSTHOG_KEY__; with no key, every function here is a silent no-op. */
+import crypto from "node:crypto";
+import { loadConfig, setConfigValue } from "./config.js";
+import { BUILD_VERSION, UPDATE_CHANNEL } from "./version.js";
+
+// eslint-disable-next-line no-undef
+const POSTHOG_KEY = typeof __POSTHOG_KEY__ !== "undefined" ? __POSTHOG_KEY__ : (process.env.MM_POSTHOG_KEY || "");
+const POSTHOG_HOST = (process.env.MM_POSTHOG_HOST || "https://us.i.posthog.com").replace(/\/$/, "");
+
+const optedOut = () => !!(process.env.MM_NO_ANALYTICS || process.env.DO_NOT_TRACK || process.env.CI);
+const enabled = () => !!POSTHOG_KEY && !optedOut();
+
+let cachedId = null;
+function distinctId() {
+  if (cachedId) return cachedId;
+  const cfg = loadConfig();
+  cachedId = cfg.anonId || "cli_" + crypto.randomUUID();
+  if (!cfg.anonId) { try { setConfigValue("anonId", cachedId); } catch { /* best effort */ } }
+  return cachedId;
+}
+
+/** One-time, pre-TUI stderr disclosure. Honors opt-out + only shows once. */
+export function maybeAnalyticsNotice() {
+  if (!enabled()) return;
+  if (loadConfig().analyticsNoticeShown) return;
+  try { setConfigValue("analyticsNoticeShown", true); } catch { /* best effort */ }
+  process.stderr.write(
+    "ℹ llmstatus sends anonymous usage analytics (event names + counts only — never code, model names, or paths). Opt out: MM_NO_ANALYTICS=1\n",
+  );
+}
+
+/** Fire-and-forget capture. Never throws, never blocks the CLI meaningfully. */
+export function track(event, properties = {}) {
+  if (!enabled()) return;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 1500);
+    fetch(`${POSTHOG_HOST}/i/v0/e/`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        api_key: POSTHOG_KEY,
+        event,
+        distinct_id: distinctId(),
+        properties: {
+          $process_person_profile: false, // anonymous events, no person profiles
+          cli_version: BUILD_VERSION,
+          channel: UPDATE_CHANNEL,
+          os: process.platform,
+          arch: process.arch,
+          ...properties,
+        },
+        timestamp: new Date().toISOString(),
+      }),
+      signal: ctrl.signal,
+      keepalive: true,
+    }).catch(() => {}).finally(() => clearTimeout(timer));
+  } catch { /* analytics must never break the CLI */ }
+}

package/src/tui/app.js

@@ -1,139 +1,221 @@
 import React from "react";
-import { render, Box, Text, useInput, useApp } from "ink";
+import path from "node:path";
+import { render, Box, Text, useInput, useApp, useStdout } from "ink";
 import { createClient } from "../api.js";
-import { h, useAsync } from "./ui.js";
-import { InventoryView } from "./views/inventory.js";
-import { ScanView } from "./views/scan.js";
-import { WhatsNewView } from "./views/whatsnew.js";
-import { AddView } from "./views/add.js";
-import { AlertsView } from "./views/alerts.js";
-import { AccountView } from "./views/account.js";
+import { track } from "../telemetry.js";
+import { BUILD_VERSION } from "../version.js";
+import {
+  h, C, GLYPH, useAsync, Window, TrafficLights, TabStrip, StatusBar, legendSegments,
+  KeyBar, EmptyCard,
+} from "./ui.js";
+import { LocalView, meta as localMeta } from "./views/local.js";
+import { InventoryView, meta as inventoryMeta } from "./views/inventory.js";
+import { ScanView, meta as scanMeta } from "./views/scan.js";
+import { WhatsNewView, meta as whatsnewMeta } from "./views/whatsnew.js";
+import { AddView, meta as addMeta } from "./views/add.js";
+import { AlertsView, meta as alertsMeta } from "./views/alerts.js";
+import { AccountView, meta as accountMeta } from "./views/account.js";
+import { SignIn } from "./signin.js";
 
+// `needsAuth: true` views show a sign-in card when there's no apiKey; Local +
+// What's New are public (signed registry over HTTP, no account needed).
 const VIEWS = [
-  { key: "inventory", label: "Inventory", Comp: InventoryView },
-  { key: "scan", label: "Scan", Comp: ScanView },
-  { key: "whatsnew", label: "What's New", Comp: WhatsNewView },
-  { key: "add", label: "Add", Comp: AddView },
-  { key: "alerts", label: "Alerts", Comp: AlertsView },
-  { key: "account", label: "Account", Comp: AccountView },
+  { key: "local", label: "Here", title: "here", Comp: LocalView, meta: localMeta, needsAuth: false },
+  { key: "whatsnew", label: "What's New", title: "new", Comp: WhatsNewView, meta: whatsnewMeta, needsAuth: false },
+  { key: "inventory", label: "Inventory", title: "inventory", Comp: InventoryView, meta: inventoryMeta, needsAuth: true },
+  { key: "scan", label: "Scan", title: "scan", Comp: ScanView, meta: scanMeta, needsAuth: true },
+  { key: "add", label: "Add", title: "add", Comp: AddView, meta: addMeta, needsAuth: true },
+  { key: "alerts", label: "Alerts", title: "alerts", Comp: AlertsView, meta: alertsMeta, needsAuth: true },
+  { key: "account", label: "Account", title: "account", Comp: AccountView, meta: accountMeta, needsAuth: false },
 ];
 
-function Header({ idx, accountName, plan }) {
-  return h(
-    Box,
-    { flexDirection: "column" },
-    h(
-      Box,
-      { justifyContent: "space-between" },
-      h(Text, { color: "cyan", bold: true }, " LLM Status "),
-      h(
-        Text,
-        { color: "gray" },
-        `${accountName ?? "…"}${plan ? `  ·  ${plan}` : ""} `,
-      ),
-    ),
-    h(
-      Box,
-      {},
-      ...VIEWS.map((v, i) =>
-        h(
-          Text,
-          { key: v.key, color: i === idx ? "black" : "gray", backgroundColor: i === idx ? "cyan" : undefined },
-          ` ${i + 1} ${v.label} `,
-        ),
-      ),
-    ),
-  );
+const GATE_KEYS = [{ k: "1-7", label: "switch" }, { k: "7", label: "sign in" }];
+
+// Lines of chrome around the body (topRule, lights, tabs, blank, prompt, blank,
+// toast, status, keybar, bottomRule) — the body fills whatever rows remain.
+const CHROME_ROWS = 10;
+
+/** Full terminal dims, resize-aware. Fills the screen edge-to-edge.
+ * MM_TUI_WIDTH / MM_TUI_HEIGHT force exact dims (reproducible screenshots). */
+function useTermDims() {
+  const { stdout } = useStdout();
+  const [dims, setDims] = React.useState({ cols: (stdout && stdout.columns) || 80, rows: (stdout && stdout.rows) || 24 });
+  React.useEffect(() => {
+    if (!stdout) return undefined;
+    const on = () => setDims({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+    stdout.on("resize", on);
+    return () => stdout.off("resize", on);
+  }, [stdout]);
+  const fw = Number(process.env.MM_TUI_WIDTH);
+  const fh = Number(process.env.MM_TUI_HEIGHT);
+  const cols = Number.isFinite(fw) && fw > 0 ? fw : dims.cols;
+  const rows = Number.isFinite(fh) && fh > 0 ? fh : dims.rows;
+  // Never exceed the real terminal width (a wider frame soft-wraps every chrome
+  // line and shatters the window). Fill the FULL terminal height: when the frame
+  // height ≥ the terminal rows, ink redraws with a full clear each frame; render
+  // shorter than the screen (the old 80-row cap did this on tall external
+  // monitors) and ink falls back to cursor-up diffing, which drifts/scrolls.
+  return { outer: Math.min(cols || 80, 220), termRows: Math.max(8, Math.min(rows || 24, 200)) };
 }
 
-function PromptBar({ prompt }) {
-  if (!prompt) return null;
+function PromptRow({ prompt }) {
+  if (!prompt) return h(Text, {}, "");
   return h(
-    Box,
-    { borderStyle: "round", borderColor: "yellow", paddingX: 1 },
-    h(Text, { color: "yellow" }, `${prompt.label}: `),
-    h(Text, {}, prompt.value),
-    h(Text, { color: "gray" }, "▏"),
+    Text,
+    {},
+    h(Text, { color: C.ACCENT, bold: true }, ` ${prompt.label} `),
+    h(Text, { color: C.FG }, prompt.value || ""),
+    h(Text, { color: C.ACCENT }, "▏"),
   );
 }
 
-export function App({ apiBase, apiKey, dir, initialView }) {
+export function App({ apiBase, apiKey, dir, initialView, onSignedIn, fresh }) {
   const { exit } = useApp();
+  const { stdout } = useStdout();
   const client = React.useMemo(() => createClient({ apiBase, apiKey }), [apiBase, apiKey]);
-  const startIdx = Math.max(0, VIEWS.findIndex((v) => v.key === initialView));
+  const fallbackKey = apiKey ? "inventory" : "local";
+  const startIdx = Math.max(0, VIEWS.findIndex((v) => v.key === (initialView || fallbackKey)));
   const [idx, setIdx] = React.useState(startIdx);
+  const [redraw, setRedraw] = React.useState(0); // bumped by ctrl-L to force a clean repaint
   const [toast, setToast] = React.useState(null);
   const [prompt, setPrompt] = React.useState(null);
-  const me = useAsync(() => client.me(), []);
+  const [capturing, setCapturing] = React.useState(false); // a view is capturing text (e.g. / search)
+  const [status, setStatus] = React.useState(null); // { forKey, counts, context }
+  const me = useAsync(async () => (apiKey ? client.me() : null), [apiKey]);
+
+  const { outer, termRows } = useTermDims();
+  const W = outer - 4; // content width: 2 border rails + 2 paddingX
+  const bodyRows = Math.max(3, termRows - CHROME_ROWS);
 
-  const showToast = React.useCallback((msg, color = "green") => {
+  const current = VIEWS[idx];
+  const curKeyRef = React.useRef(current.key);
+  curKeyRef.current = current.key;
+  // Anonymous: which tab is being viewed (no content, just the view name).
+  React.useEffect(() => { track("tui_view", { view: current.key }); }, [current.key]);
+
+  const showToast = React.useCallback((msg, color = "#16a34a") => {
     setToast({ msg, color });
     setTimeout(() => setToast(null), 2500);
   }, []);
-
   const askPrompt = React.useCallback(
-    (label, { initial = "", onSubmit, onCancel } = {}) =>
-      setPrompt({ label, value: initial, onSubmit, onCancel }),
+    (label, { initial = "", onSubmit, onCancel } = {}) => setPrompt({ label, value: initial, onSubmit, onCancel }),
     [],
   );
+  // Views push their live legend counts + context up here (data-keyed, not tick).
+  const reportStatus = React.useCallback((next) => {
+    setStatus((prev) => {
+      const stamped = { ...next, forKey: curKeyRef.current };
+      if (prev && JSON.stringify(prev) === JSON.stringify(stamped)) return prev;
+      return stamped;
+    });
+  }, []);
+  // A view sets this true when it handles "back" itself (drilled into a detail,
+  // an active filter, …). Backspace then defers to the view; otherwise backspace
+  // walks back a tab (mirrors Shift-Tab). Keeps backspace a single coherent
+  // "back" without the app + view both firing on the same key.
+  const handlesBackRef = React.useRef(false);
+  const setHandlesBack = React.useCallback((v) => { handlesBackRef.current = !!v; }, []);
 
-  // Global keys — paused while a prompt is capturing text.
   useInput(
     (input, key) => {
       if (key.ctrl && input === "c") return exit();
-      if (/[1-6]/.test(input)) return setIdx(Number(input) - 1);
+      // Ctrl-L: hard redraw. Clears screen + scrollback, then bumps `redraw` so
+      // the frame string changes (ink skips writing identical output) and ink
+      // repaints from a clean top. Fixes a display knocked askew by a resize /
+      // monitor change without restarting.
+      if (key.ctrl && input === "l") {
+        if (stdout) stdout.write("\x1b[2J\x1b[3J\x1b[H");
+        return setRedraw((r) => r + 1);
+      }
+      const n = Number(input);
+      if (n >= 1 && n <= VIEWS.length) return setIdx(n - 1);
+      if (key.tab && key.shift) return setIdx((i) => (i - 1 + VIEWS.length) % VIEWS.length);
       if (key.tab) return setIdx((i) => (i + 1) % VIEWS.length);
+      // Backspace = go back: let the active view back out of a drill-in/filter
+      // first; with nothing to back out of, step to the previous tab.
+      if (key.backspace || key.delete) {
+        if (handlesBackRef.current) return undefined;
+        return setIdx((i) => (i - 1 + VIEWS.length) % VIEWS.length);
+      }
       if (input === "q") return exit();
     },
-    { isActive: !prompt },
+    { isActive: !prompt && !capturing },
   );
-
-  // Prompt capture.
   useInput(
     (input, key) => {
-      if (key.escape) {
-        const cb = prompt.onCancel;
-        setPrompt(null);
-        cb?.();
-        return;
-      }
-      if (key.return) {
-        const { onSubmit, value } = prompt;
-        setPrompt(null);
-        onSubmit?.(value);
-        return;
-      }
+      if (key.escape) { const cb = prompt.onCancel; setPrompt(null); cb && cb(); return; }
+      if (key.return) { const { onSubmit, value } = prompt; setPrompt(null); onSubmit && onSubmit(value); return; }
       if (key.backspace || key.delete) return setPrompt((p) => ({ ...p, value: p.value.slice(0, -1) }));
-      if (input && !key.ctrl && !key.meta) setPrompt((p) => ({ ...p, value: p.value + input }));
+      if (input && !key.ctrl && !key.meta) return setPrompt((p) => ({ ...p, value: p.value + input }));
     },
     { isActive: !!prompt },
   );
 
-  const ui = { showToast, askPrompt, switchTo: (key) => setIdx(VIEWS.findIndex((v) => v.key === key)) };
-  const View = VIEWS[idx].Comp;
+  const ui = { showToast, askPrompt, reportStatus, setCapturing, setHandlesBack, switchTo: (k) => setIdx(VIEWS.findIndex((v) => v.key === k)) };
+  const current2 = current;
+  const View = current2.Comp;
   const account = me.data?.account ?? null;
+  const plan = account?.plan ?? (apiKey ? null : undefined);
+  const workspace = account?.name || path.basename(path.resolve(dir));
+  // Trailing toggle so a ctrl-L redraw changes the frame string (ink won't
+  // re-emit byte-identical output); invisible (just rebalances a title dash).
+  const title = `llmstatus ${current2.title} — ${workspace}${redraw % 2 ? " " : ""}`;
+
+  const showSignInOnAccount = current2.key === "account" && !apiKey;
+  const showSignInGate = current2.needsAuth && !apiKey;
+
+  let body, keys;
+  if (showSignInOnAccount) {
+    body = h(SignIn, { apiBase, onSuccess: onSignedIn || (() => {}) });
+    keys = GATE_KEYS;
+  } else if (showSignInGate) {
+    body = h(EmptyCard, {
+      icon: GLYPH.spark,
+      title: `${current2.label} needs a sign-in`,
+      lines: ["Press 7 for Account to sign in with your browser.", "Tabs 1-2 (Here, What's New) work without an account."],
+      width: W,
+    });
+    keys = GATE_KEYS;
+  } else {
+    body = h(View, { client, me: account, refreshMe: me.reload, dir, apiBase, ui, width: W, height: bodyRows, active: !prompt, fresh });
+    keys = (current2.meta && current2.meta.keys) || [];
+  }
+
+  // Status bar segments.
+  const live = status && status.forKey === current2.key ? status : null;
+  const segsLeft = [
+    { text: "workspace ", color: C.FG_FAINT },
+    { text: workspace, color: C.ACCENT, bold: true },
+  ];
+  const segsRight = [];
+  if (live && live.counts) segsRight.push(...legendSegments(live.counts));
+  if (live && live.context) {
+    if (segsRight.length) segsRight.push({ text: "     ", color: C.FG_FAINT });
+    segsRight.push({ text: live.context, color: C.FG_DIM });
+  }
 
   return h(
-    Box,
-    { flexDirection: "column", paddingX: 1 },
-    h(Header, { idx, accountName: account?.name, plan: account?.plan }),
-    h(
-      Box,
-      { flexDirection: "column", marginTop: 1, minHeight: 14 },
-      h(View, { client, me: account, refreshMe: me.reload, dir, apiBase, ui, active: !prompt }),
-    ),
-    h(PromptBar, { prompt }),
-    h(
-      Box,
-      { marginTop: 0 },
-      toast
-        ? h(Text, { color: toast.color }, ` ${toast.msg}`)
-        : h(Text, { color: "gray" }, " 1-6/Tab switch · q quit · keys per view shown above"),
-    ),
+    Window,
+    { title, width: outer },
+    h(TrafficLights, null),
+    h(TabStrip, { idx, tabs: VIEWS, account: apiKey ? null : "(local)", plan, version: BUILD_VERSION }),
+    h(Text, {}, ""),
+    h(Box, { flexDirection: "column", width: W, minHeight: bodyRows }, body),
+    h(PromptRow, { prompt }),
+    h(Text, {}, ""),
+    toast ? h(Text, { color: toast.color }, ` ${toast.msg}`) : h(Text, {}, ""),
+    h(StatusBar, { segsLeft, segsRight, width: W }),
+    h(KeyBar, { keys, width: W }),
   );
 }
 
+/** Top-level TUI entry — always renders App; auth unlocks tabs in-place. */
+function Bootstrap(props) {
+  const [apiKey, setApiKey] = React.useState(props.apiKey);
+  return h(App, { ...props, apiKey, onSignedIn: (k) => { track("signed_in"); setApiKey(k); } });
+}
+
 export function runApp(opts) {
-  const app = render(h(App, opts));
+  const app = render(h(Bootstrap, opts));
   return app.waitUntilExit();
 }

package/src/tui/scan-stream.js

@@ -0,0 +1,234 @@
+/* Streaming filesystem scan, factored out of local.js so both the free Local
+ * view and (potentially) other views share one cooperative-scan engine. Fetches
+ * the signed registry, then streams the filesystem scan, batching progress into
+ * React state on a ~120ms cadence (per-file updates would thrash the renderer).
+ * Yields live { phase, counts, rows, custom } as models are discovered.
+ *
+ * A module-level dir-keyed cache means returning to the Here tab reuses the
+ * completed scan instead of restarting it; `reload()` busts the cache + rescans. */
+import React from "react";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getRegistry } from "../registry/fetch.js";
+import { resolveLocal, computeHealth } from "../registry/local.js";
+import { scanFilesystemStreaming } from "../sources/filesystem.js";
+import { compilePatterns } from "../detect/core.js";
+
+export const HEALTH_RANK = { retired: 0, retiring: 1, deprecating: 2, ok: 3 };
+
+// dir → { snapshot, candidates, ... } for the last completed scan THIS session.
+const SCAN_CACHE = new Map();
+
+// Cross-run persistence: the last scan's candidates per dir, so opening the TUI
+// loads instantly instead of re-walking the tree every launch. Override for tests.
+const scanDiskPath = () => process.env.LLMSTATUS_SCAN_CACHE || path.join(os.homedir(), ".config", "llmstatus", "scans.json");
+const trimCandidate = (c) => ({ model_string: c.model_string, source_path: c.source_path, source_line: c.source_line, location_label: c.location_label, environment: c.environment });
+
+/** The persisted scan for `dir`, or null. Version-gated so a schema bump (or a
+ * malformed/hand-edited file) invalidates old entries instead of feeding stale
+ * shapes into summarize(). */
+export function readDiskScan(dir) {
+  try {
+    const j = JSON.parse(fs.readFileSync(scanDiskPath(), "utf8"));
+    if (!j || j.version !== 1 || !j.scans || typeof j.scans !== "object" || Array.isArray(j.scans)) return null;
+    return j.scans[dir] || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist `dir`'s candidates (atomic, pruned to the 20 most-recent dirs).
+ * Concurrent mm instances scanning different dirs may drop each other's
+ * just-added entry (read-modify-write, no lock) — benign for a best-effort cache:
+ * the lost dir simply re-walks (and re-persists) on its next launch. */
+export function writeDiskScan(dir, candidates) {
+  try {
+    const file = scanDiskPath();
+    let j = { version: 1, scans: {} };
+    // Reuse only a well-formed v1 file; anything else (wrong version, scans not a
+    // plain object) is discarded and overwritten fresh, self-healing corruption
+    // instead of throwing on `j.scans[dir] = …` and wedging persistence forever.
+    try { const p = JSON.parse(fs.readFileSync(file, "utf8")); if (p && p.version === 1 && p.scans && typeof p.scans === "object" && !Array.isArray(p.scans)) j = p; } catch { /* fresh */ }
+    j.scans[dir] = { scannedAt: Date.now(), candidates: candidates.map(trimCandidate) };
+    j.scans = Object.fromEntries(Object.entries(j.scans).sort((a, b) => (b[1].scannedAt || 0) - (a[1].scannedAt || 0)).slice(0, 20));
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(j));
+    fs.renameSync(tmp, file);
+  } catch { /* best effort */ }
+}
+
+/** Fetch the signed registry. Honors LLMSTATUS_REGISTRY_OFFLINE=1 +
+ * LLMSTATUS_REGISTRY_CACHE=<file> so tests (and offline power-users) can pin a
+ * deterministic snapshot without network. */
+export function loadRegistry(log = () => {}) {
+  return getRegistry({
+    log,
+    offline: process.env.LLMSTATUS_REGISTRY_OFFLINE === "1",
+    cacheFile: process.env.LLMSTATUS_REGISTRY_CACHE || undefined,
+  });
+}
+
+/** Roll candidates up into health-sorted known rows + a custom map, against the
+ * snapshot. Also returns the per-model + per-custom reference lists (for the
+ * detail pane) so a highlighted row can show exactly where it's used. */
+export function summarize(snapshot, candidates) {
+  const resolved = resolveLocal(snapshot, [...new Set(candidates.map((c) => c.model_string))]);
+  const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
+  const known = new Map(); // slug → { model, count }
+  const custom = new Map(); // string → count
+  const refsBySlug = new Map(); // slug → [candidate]
+  const customRefs = new Map(); // string → [candidate]
+  // Dedupe by location per target so the list "(count)" matches the detail
+  // panel's "used in N places" (two aliases of one slug on the same line = 1 use).
+  const seenLoc = new Set();
+  for (const c of candidates) {
+    const r = byStr.get(c.model_string.toLowerCase());
+    const loc = (c.source_path || c.location_label || "") + (c.source_line ? ":" + c.source_line : "");
+    if (r?.model_slug && r.model) {
+      if (seenLoc.has(r.model_slug + "|" + loc)) continue;
+      seenLoc.add(r.model_slug + "|" + loc);
+      const e = known.get(r.model_slug) || { model: r.model, count: 0 };
+      e.count++;
+      known.set(r.model_slug, e);
+      if (!refsBySlug.has(r.model_slug)) refsBySlug.set(r.model_slug, []);
+      refsBySlug.get(r.model_slug).push(c);
+    } else {
+      if (seenLoc.has("custom:" + c.model_string + "|" + loc)) continue;
+      seenLoc.add("custom:" + c.model_string + "|" + loc);
+      custom.set(c.model_string, (custom.get(c.model_string) || 0) + 1);
+      if (!customRefs.has(c.model_string)) customRefs.set(c.model_string, []);
+      customRefs.get(c.model_string).push(c);
+    }
+  }
+  const today = new Date();
+  const rows = [...known.values()]
+    .map(({ model, count }) => ({ model, count, health: computeHealth(model, 90, today) }))
+    .sort(
+      (a, b) =>
+        HEALTH_RANK[a.health] - HEALTH_RANK[b.health] ||
+        String(a.model.retires_date || "9999-99-99").localeCompare(
+          String(b.model.retires_date || "9999-99-99"),
+        ),
+    );
+  return { rows, custom, refsBySlug, customRefs };
+}
+
+/** Health distribution for the status-bar legend. */
+export function countHealth(rows) {
+  const counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0, custom: 0 };
+  for (const r of rows) counts[r.health] = (counts[r.health] || 0) + 1;
+  return counts;
+}
+
+const baseState = (extra = {}) => ({
+  phase: "registry", // registry | scanning | done | error
+  error: null,
+  snapshot: null,
+  candidates: [],
+  filesScanned: 0,
+  dirsSeen: 0,
+  catalogsSkipped: 0,
+  currentDir: "",
+  rows: [],
+  custom: new Map(),
+  refsBySlug: new Map(),
+  customRefs: new Map(),
+  candidateCount: 0,
+  scannedAt: null,
+  fromCache: false,
+  ...extra,
+});
+
+const doneFromCache = (dir) => {
+  const e = SCAN_CACHE.get(dir);
+  return baseState({ phase: "done", snapshot: e.snapshot, candidates: e.candidates, filesScanned: e.filesScanned, dirsSeen: e.dirsSeen, catalogsSkipped: e.catalogsSkipped, scannedAt: e.scannedAt, fromCache: e.fromCache, candidateCount: e.candidates.length, ...summarize(e.snapshot, e.candidates) });
+};
+
+/** Streaming scan controller. On open, reuses this session's cache, else loads
+ * the last persisted scan from disk (skipping the fs walk) unless `opts.fresh`;
+ * `reload()` always re-walks. Aborts on unmount. */
+export function useStreamingScan(dir, opts = {}) {
+  const [nonce, setNonce] = React.useState(0);
+  const [state, setState] = React.useState(() => (SCAN_CACHE.has(dir) ? doneFromCache(dir) : baseState()));
+  const [paused, setPaused] = React.useState(false);
+  const pausedRef = React.useRef(false);
+  const togglePause = React.useCallback(() => {
+    pausedRef.current = !pausedRef.current;
+    setPaused(pausedRef.current);
+  }, []);
+
+  React.useEffect(() => {
+    // Initial visit (nonce 0) with a same-session cache → the useState
+    // initializer already seeded it; nothing to do.
+    if (nonce === 0 && SCAN_CACHE.has(dir)) return undefined;
+    pausedRef.current = false;
+    setPaused(false);
+    const ac = new AbortController();
+    let cancelled = false;
+    const acc = { snapshot: null, candidates: [], filesScanned: 0, dirsSeen: 0, catalogsSkipped: 0, currentDir: "", dirty: false };
+    setState(baseState());
+
+    const flush = () => {
+      if (cancelled || !acc.dirty) return;
+      acc.dirty = false;
+      const sum = acc.snapshot ? summarize(acc.snapshot, acc.candidates) : { rows: [], custom: new Map(), refsBySlug: new Map(), customRefs: new Map() };
+      setState((s) => ({ ...s, filesScanned: acc.filesScanned, dirsSeen: acc.dirsSeen, catalogsSkipped: acc.catalogsSkipped, currentDir: acc.currentDir, candidateCount: acc.candidates.length, candidates: acc.candidates, ...sum }));
+    };
+    let flushTimer = null;
+
+    (async () => {
+      try {
+        const snapshot = await loadRegistry();
+        if (cancelled) return;
+        acc.snapshot = snapshot;
+
+        // Fast path: load the last persisted scan (skip the fs walk) on a fresh
+        // open, unless the caller forced --scan or this is a g-triggered reload.
+        const forced = opts.fresh || nonce > 0;
+        const disk = forced ? null : readDiskScan(dir);
+        // Drop malformed candidates (null / non-string model_string) so a corrupt
+        // entry can't throw in summarize() and surface phase:"error" on every
+        // launch; if nothing usable survives, fall through to a fresh walk.
+        const clean = disk && Array.isArray(disk.candidates)
+          ? disk.candidates.filter((c) => c && typeof c.model_string === "string")
+          : null;
+        if (clean && clean.length) {
+          try {
+            const sum = summarize(snapshot, clean);
+            SCAN_CACHE.set(dir, { snapshot, candidates: clean, filesScanned: 0, dirsSeen: 0, catalogsSkipped: 0, scannedAt: disk.scannedAt || null, fromCache: true });
+            setState(baseState({ phase: "done", snapshot, candidates: clean, scannedAt: disk.scannedAt || null, fromCache: true, candidateCount: clean.length, ...sum }));
+            return;
+          } catch { /* corrupt cache → fall through to a fresh walk (which re-persists) */ }
+        }
+
+        setState((s) => ({ ...s, phase: "scanning", snapshot }));
+        flushTimer = setInterval(flush, 120);
+        const compiled = compilePatterns(snapshot.detection);
+        await scanFilesystemStreaming({ root: dir, signal: ac.signal, isPaused: () => pausedRef.current }, compiled, (ev) => {
+          if (ev.type === "dir") { acc.dirsSeen = ev.dirsSeen; acc.currentDir = ev.path; }
+          else if (ev.type === "candidate") acc.candidates.push(ev.candidate);
+          else if (ev.type === "skip") acc.catalogsSkipped = ev.catalogsSkipped;
+          else if (ev.type === "progress") { acc.filesScanned = ev.filesScanned; acc.dirsSeen = ev.dirsSeen; acc.catalogsSkipped = ev.catalogsSkipped; }
+          acc.dirty = true;
+        });
+        if (cancelled) return;
+        clearInterval(flushTimer);
+        const now = Date.now();
+        SCAN_CACHE.set(dir, { snapshot, candidates: acc.candidates, filesScanned: acc.filesScanned, dirsSeen: acc.dirsSeen, catalogsSkipped: acc.catalogsSkipped, scannedAt: now, fromCache: false });
+        writeDiskScan(dir, acc.candidates);
+        setState((s) => ({ ...s, phase: "done", filesScanned: acc.filesScanned, dirsSeen: acc.dirsSeen, catalogsSkipped: acc.catalogsSkipped, currentDir: "", scannedAt: now, fromCache: false, candidateCount: acc.candidates.length, candidates: acc.candidates, ...summarize(snapshot, acc.candidates) }));
+      } catch (e) {
+        if (cancelled) return;
+        if (flushTimer) clearInterval(flushTimer);
+        setState((s) => ({ ...s, phase: "error", error: e?.message || String(e) }));
+      }
+    })();
+
+    return () => { cancelled = true; ac.abort(); clearInterval(flushTimer); };
+  }, [dir, nonce]);
+
+  const reload = React.useCallback(() => { SCAN_CACHE.delete(dir); setNonce((n) => n + 1); }, [dir]);
+  return { ...state, paused, reload, togglePause };
+}