@modelstatus/cli 0.1.82 → 0.1.84

package/README.md

@@ -29,10 +29,20 @@ Or skip install entirely and one-shot it: `npx @modelstatus/cli status`.
 
 ## Quick start
 
-### Free: offline health check
+### Free: open the dashboard
 
 ```bash
-mm status [dir]                       # if installed
+mm [dir]                              # the full TUI — inventory · scan · what's new · alerts
+```
+
+Just run `mm` (optionally on a folder) for the interactive dashboard: it scans
+locally, shows every model in use with its health, and lets you fix the dying
+ones — no account needed.
+
+### Free: a one-shot health check (great for CI / pipes)
+
+```bash
+mm status [dir]                       # quick offline check, prints + exits
 npx @modelstatus/cli status [dir]     # zero install (needs Node)
 ```
 
@@ -138,6 +148,25 @@ Apple-notarized, every release manifest is Ed25519-signed and verified — again
 a public key embedded in the installer and the self-updater, not fetched from the
 CDN — and both refuse to proceed if any check fails.
 
+### Verify a download yourself
+
+The installer already checks everything, but you can verify any binary
+independently with [minisign](https://jedisct1.github.io/minisign/) (Ed25519).
+Each binary ships a detached `.minisig` next to it on the CDN:
+
+```sh
+# e.g. Linux x64 (use latest/ or a pinned cli/v0.1.83/)
+curl -fLO https://cdn.llmstatus.ai/cli/latest/modelstatus-cli-linux-x64
+curl -fLO https://cdn.llmstatus.ai/cli/latest/modelstatus-cli-linux-x64.minisig
+minisign -Vm modelstatus-cli-linux-x64 \
+  -P RWQlKGcm5lXiIiTvGv/cdc0joBn1sm9vOFr9WqR6CI15PXzoHNHVBY6S
+# → "Signature and comment signature verified"
+```
+
+The public key is also committed at `packages/cli/release-minisign.pub`. (On
+macOS you additionally get the Developer ID signature + Apple notarization; on
+Linux/Windows the minisign signature is the independent check.)
+
 ## Links
 
 - Website: [llmstatus.ai](https://llmstatus.ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelstatus/cli",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "description": "Track which AI models you use, where, and never get surprised by a retirement. Free offline model-health for any repo (mm status), browser sign-in for cloud inventory + alerts.",
   "keywords": [
     "llm",

package/src/changelog-data.js

@@ -1,6 +1,26 @@
 /* GENERATED by scripts/gen-changelog.mjs from apps/web/lib/changelog.json — do not edit.
  * Release notes baked into the binary (in-TUI + the on-load what's-new card). */
 export const CHANGELOG = [
+  {
+    "version": "0.1.84",
+    "date": "2026-06-14",
+    "title": "Clearer mm status, faster scans, safer CI",
+    "items": [
+      "`mm status` now leads with a one-line verdict, orders models by what dies first, and shows a `≈ suggestion?` for ids written without their provider prefix — so a model the registry knows isn't just labelled \"unrecognized\".",
+      "Scans are ~9x faster on large trees, with a live file counter while they run; random config keys and generated tokens no longer get mistaken for model ids.",
+      "`mm ci --diff` no longer silently passes on a symlinked checkout — it was dropping every finding, hiding retiring models in changed files behind a green check.",
+      "`mm scan --dry-run` always previews (it never launches the uploader), `mm scan --json` always emits JSON, and running the dashboard without an interactive terminal prints a clear message instead of crashing."
+    ]
+  },
+  {
+    "version": "0.1.83",
+    "date": "2026-06-14",
+    "title": "Live progress on mm status",
+    "items": [
+      "`mm status` and `mm fix` now show live progress while they pull the registry and scan your repo — a cold run no longer sits silent and looks frozen.",
+      "Docs and the post-install quick start now lead with `mm` (the full dashboard); `mm status` is the quick, scriptable, no-account check that drops into CI."
+    ]
+  },
   {
     "version": "0.1.82",
     "date": "2026-06-13",

package/src/detect/core.js

@@ -50,11 +50,31 @@ function matchesAtBoundary(haystack, term) {
   }
 }
 
+/** Reject a generic match that carries a long, high-entropy alnum run — a config
+ * key / generated id / random token (e.g. "claude-config-8f4k2m9x7p3q",
+ * "qwen1ah0aqumtapuychbwd2maghkvcltn") rather than a real model id. A model id —
+ * even a brand-new one not yet in the registry — has short, separated, mostly
+ * pronounceable segments; a generated key has one long mixed-case/digit blob.
+ * Only applied to GENERIC matches (exact registry strings bypass looksLikeModel),
+ * so it can never drop a known model. Pure-alpha segments (davinci) and pure-digit
+ * snapshot dates (20250514) are never flagged — only MIXED long segments are. */
+function hasRandomSegment(s) {
+  for (const seg of s.split(/[-._/:]+/)) {
+    if (seg.length < 12) continue;
+    if (!/[a-z]/i.test(seg) || !/[0-9]/.test(seg)) continue; // need mixed letters+digits
+    const distinct = new Set(seg).size;
+    const vowels = (seg.match(/[aeiou]/gi) || []).length;
+    if (distinct / seg.length > 0.6 || vowels / seg.length < 0.18) return true;
+  }
+  return false;
+}
+
 /** Family globs catch brand-NEW versioned models before they're in the
  * registry, so a real hit virtually always carries a version digit. Requiring
- * one (and rejecting filename/domain tails) kills the bulk of false positives. */
+ * one (and rejecting filename/domain tails + random-key blobs) kills the bulk of
+ * false positives. */
 function looksLikeModel(s) {
-  return s.length >= 5 && /[0-9]/.test(s) && !BANNED_TAIL.test(s);
+  return s.length >= 5 && /[0-9]/.test(s) && !BANNED_TAIL.test(s) && !hasRandomSegment(s);
 }
 
 // Detection strings that are ALSO everyday code/English words. Cohere's bare
@@ -78,8 +98,20 @@ export function compilePatterns(patterns) {
     // (The old >=4 floor silently dropped the entire OpenAI o-series.)
     if (ms.match && ms.match.length >= 2 && !STOPWORDS.has(ms.match.toLowerCase())) exact.push(ms.match.toLowerCase());
   }
+  // Bucket the exact strings by their first 2 chars. detectInLine then runs the
+  // boundary matcher ONLY on buckets whose 2-char head appears in the line (a
+  // cheap indexOf prefilter). With 1500+ registry strings this is ~9x faster on a
+  // large tree and byte-identical: a string always contains its own first 2 chars,
+  // so a present string's bucket is never skipped. (~47 distinct heads today.)
+  const exactByHead = new Map();
+  for (const s of exact) {
+    const head = s.slice(0, 2);
+    let bucket = exactByHead.get(head);
+    if (!bucket) exactByHead.set(head, (bucket = []));
+    bucket.push(s);
+  }
   const generic = (patterns.generic_model_regexes || []).map((r) => new RegExp(r, "gi"));
-  return { exact, generic };
+  return { exact, exactByHead, generic };
 }
 
 /** Find model strings on a single line. Returns a Set of lowercased strings. */
@@ -89,7 +121,16 @@ export function detectInLine(line, compiled) {
   // Exact registry strings must match at a token boundary, not as a raw substring
   // — otherwise a short alias ("gpt-4") resolves inside a longer id ("gpt-4o-mini")
   // to the wrong model. Matches the server PR scanner's boundary semantics.
-  for (const s of compiled.exact) if (matchesAtBoundary(lower, s)) found.add(s);
+  // Use the 2-char-head bucket index when available (only scan buckets whose head
+  // appears in the line); fall back to the flat list for any older compiled shape.
+  if (compiled.exactByHead) {
+    for (const [head, bucket] of compiled.exactByHead) {
+      if (lower.indexOf(head) < 0) continue;
+      for (const s of bucket) if (matchesAtBoundary(lower, s)) found.add(s);
+    }
+  } else {
+    for (const s of compiled.exact) if (matchesAtBoundary(lower, s)) found.add(s);
+  }
   for (const re of compiled.generic) {
     re.lastIndex = 0;
     let m;

package/src/index.js

@@ -14,7 +14,8 @@ import { redactValue } from "./redact.js";
 import { assignProjects, buildUsages } from "./upload.js";
 import { loginViaBrowser } from "./auth.js";
 import { maybeCheckForUpdate, forceUpdate } from "./updater.js";
-import { track, analyticsState } from "./telemetry.js";
+import { track, analyticsState, maybeFirstRun } from "./telemetry.js";
+import { startProgress } from "./spinner.js";
 import { BUILD_VERSION } from "./version.js";
 
 // TRUE BACKGROUND SCAN — hidden worker dispatch. MUST be the first executable
@@ -243,10 +244,18 @@ async function cmdPlay(positional, flags) {
 }
 
 async function launchTui(initialView, flags) {
-  // Pass apiKey straight through (may be null). The TUI's Bootstrap wrapper
-  // renders an interactive SignIn screen when there's no key, then swaps to
-  // the main App on success — no separate browser-login polling phase that the
-  // user has to wait through without seeing anything interactive.
+  // The Ink TUI needs raw-mode stdin. Without a TTY (piped, redirected, CI logs)
+  // Ink throws an unhandled "Raw mode is not supported" deep in a passive effect
+  // — it escapes main()'s try/catch and dumps a React/runtime stack. Guard like
+  // `mm play` does and point at the non-interactive command instead.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error("The mm dashboard needs an interactive terminal (a TTY).");
+    console.error("For a non-interactive check, run: mm status [dir]  (add --json for scripts)");
+    process.exit(1);
+  }
+  // Pass apiKey straight through (may be null). The TUI lands on the public
+  // "Here" tab (no account needed); sign-in is lazy — the Account tab (press 7)
+  // or any auth-gated tab prompts when you get there.
   const { apiBase, apiKey } = resolveAuth(flags);
   const dir = path.resolve(flags.dir || ".");
   const { runApp } = await import("./tui/app.js");
@@ -256,13 +265,15 @@ async function launchTui(initialView, flags) {
 }
 
 async function cmdScan(positional, flags) {
-  const dir = path.resolve(positional[1] || ".");
+  const dir = path.resolve(positional[1] || flags.dir || ".");
   const { apiBase, apiKey } = resolveAuth(flags);
   if (!apiKey) {
     console.error("No API key. Run `mm login` or pass --key.");
     process.exit(1);
   }
-  const interactive = !flags.yes && !flags.json && process.stdout.isTTY;
+  // --dry-run must NOT launch the interactive TUI (which can upload) — it's a
+  // no-upload preview, so force the non-interactive path even on a TTY.
+  const interactive = !flags.yes && !flags.json && !flags["dry-run"] && process.stdout.isTTY;
   if (interactive) {
     const { runApp } = await import("./tui/app.js");
     await runApp({ apiBase, apiKey, dir, initialView: "scan" });
@@ -289,7 +300,19 @@ async function cmdScan(positional, flags) {
   const patterns = await client.detectionPatterns();
   const candidates = await collectFrom(sources, opts, patterns, explicit);
   if (candidates.length === 0) {
-    console.log("No model usage found.");
+    // Respect --json/--ci even on the empty path, so `mm scan --ci | jq` never
+    // chokes on a bare text line. Mirror the shape of the matching non-empty path.
+    if (flags.json) {
+      const srcRows = avail.map((a) => ({ id: a.id, available: a.available }));
+      console.log(JSON.stringify(
+        flags["dry-run"]
+          ? { scanned: 0, would_upload: [], sources: avail }
+          : { scanned: 0, uploaded: 0, sources: srcRows, created: 0, updated: 0, failed: 0 },
+        null, 2,
+      ));
+    } else {
+      console.log("No model usage found.");
+    }
     return;
   }
 
@@ -435,8 +458,18 @@ async function postCiRun(dir, flags, res, failOn) {
  * annotations + a step summary under GITHUB_ACTIONS; exits non-zero per --fail-on
  * so it gates merges. Offline (public registry) by default; --report syncs (Pro). */
 async function cmdCi(positional, flags) {
-  const dir = path.resolve(positional[1] || flags.dir || ".");
+  // realpathSync so `dir` matches git's `--show-toplevel` (which resolves
+  // symlinks). Without this, on a symlinked checkout (macOS /tmp, symlinked CI
+  // workspaces) the --diff path math mismatches and ALL findings are dropped →
+  // a silent GREEN check while retired models in changed files slip through.
+  let dir = path.resolve(positional[1] || flags.dir || ".");
+  try { dir = fs.realpathSync(dir); } catch { /* keep resolved path if it doesn't exist */ }
+  const VALID_FAIL_ON = new Set(["none", "deprecating", "retiring", "retired"]);
   const failOn = String(flags["fail-on"] || "retired").toLowerCase();
+  if (flags["fail-on"] !== undefined && !VALID_FAIL_ON.has(failOn)) {
+    console.error(`Invalid --fail-on "${flags["fail-on"]}". One of: ${[...VALID_FAIL_ON].join(", ")}.`);
+    process.exit(1);
+  }
   const { evaluateCi, annotationLines, summaryMarkdown, filterToChangedFiles, getChangedFiles, HEALTH_RANK } = await import("./ci.js");
   const res = await evaluateCi({
     dir,
@@ -544,9 +577,15 @@ async function cmdFix(positional, flags) {
   const { getRegistry } = await import("./registry/fetch.js");
   const { resolveLocal, computeHealth } = await import("./registry/local.js");
   const { planFixes, applyFixes, terminalReplacement, recordFixes } = await import("./fix.js");
-  const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => process.stderr.write(`! ${m}\n`) });
-
-  const candidates = await collectFrom(["filesystem"], { root: dir }, snapshot.detection);
+  // Same cold-start silence as `mm status`: registry download + repo walk with
+  // no feedback. Spinner is stderr-only and auto-off under --json.
+  const prog = startProgress(!flags.json, "fetching the model registry…");
+  const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => prog.log(m) });
+
+  prog.update("scanning for model references…");
+  const onProgress = ({ filesScanned, candidates: c }) => prog.update(`scanning… ${filesScanned} files, ${c} reference(s)`);
+  const candidates = await collectFrom(["filesystem"], { root: dir }, snapshot.detection, new Set(), onProgress);
+  prog.stop();
   const resolved = resolveLocal(snapshot, [...new Set(candidates.map((c) => c.model_string))]);
   const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
   const today = new Date();
@@ -688,9 +727,19 @@ async function cmdStatus(positional, flags) {
   const dir = path.resolve(positional[1] || flags.dir || ".");
   const { getRegistry } = await import("./registry/fetch.js");
   const { resolveLocal, computeHealth, dropResolvedFragments } = await import("./registry/local.js");
-  const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => process.stderr.write(`! ${m}\n`) });
-
-  let candidates = await collectFrom(parseSources(flags), scanOpts(flags, dir), snapshot.detection, explicitSources(flags));
+  // A cold `mm status` downloads the ~225 kB registry snapshot then walks the
+  // repo with zero output — it reads as frozen. Show live stderr progress
+  // (auto-off for --json / pipes so machine output stays byte-identical).
+  // A cold `mm status` downloads the registry snapshot then walks the repo with
+  // zero output — it reads as frozen. Show live stderr progress with a MOVING
+  // file counter (auto-off for --json / pipes so machine output is byte-identical).
+  const prog = startProgress(!flags.json, "fetching the model registry…");
+  const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => prog.log(m) });
+
+  prog.update("scanning for model references…");
+  const onProgress = ({ filesScanned, candidates: c }) => prog.update(`scanning… ${filesScanned} files, ${c} reference(s)`);
+  let candidates = await collectFrom(parseSources(flags), scanOpts(flags, dir), snapshot.detection, explicitSources(flags), onProgress);
+  prog.stop();
   const resolved = resolveLocal(snapshot, [...new Set(candidates.map((c) => c.model_string))]);
   const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
   // Suppress detector fragments of resolved aliases (see dropResolvedFragments).
@@ -707,22 +756,36 @@ async function cmdStatus(positional, flags) {
       known.set(r.model_slug, e);
     } else custom.set(c.model_string, (custom.get(c.model_string) || 0) + 1);
   }
+  const fileCount = new Set(candidates.map((c) => c.source_path || c.location_label)).size;
 
   const today = new Date();
   const ICON = { ok: "🟢", deprecating: "🟡", retiring: "🟠", retired: "🔴", withdrawn: "⛔", custom: "⚪" };
-  const rank = { withdrawn: 0, retired: 0, retiring: 1, deprecating: 2, ok: 3 };
+  // Order by WHAT DIES FIRST: already-dead (retired/withdrawn) first, then aging
+  // by soonest retirement date regardless of bucket (a deprecating model that
+  // retires sooner outranks a retiring one that retires later), then ok last.
+  const tier = (h) => (h === "retired" || h === "withdrawn") ? 0 : h === "ok" ? 2 : 1;
   const rows = [...known.values()]
     .map(({ model, count }) => ({ model, count, health: computeHealth(model, 90, today) }))
-    .sort((a, b) => rank[a.health] - rank[b.health] || String(a.model.retires_date || "9999").localeCompare(String(b.model.retires_date || "9999")));
+    .sort((a, b) => tier(a.health) - tier(b.health) || String(a.model.retires_date || "9999").localeCompare(String(b.model.retires_date || "9999")));
   const attention = rows.filter((r) => r.health !== "ok");
+  const nBy = (h) => rows.filter((r) => r.health === h).length;
+  const nDead = nBy("retired") + nBy("withdrawn");
+  const nRetiring = nBy("retiring");
+  const nDeprecating = nBy("deprecating");
+
+  // Custom strings: surface the resolver's near-miss suggestion + sort by frequency.
+  const customList = [...custom.entries()]
+    .map(([name, places]) => ({ name, places, suggestion: byStr.get(name.toLowerCase())?.suggestion || null }))
+    .sort((a, b) => b.places - a.places || a.name.localeCompare(b.name));
 
   if (flags.json) {
     console.log(JSON.stringify({
       registry: { version: snapshot.version, generated_at: snapshot.generated_at, models: snapshot.models.length },
       scanned: dir,
       references: candidates.length,
+      files: fileCount,
       models: rows.map((r) => ({ slug: r.model.slug, display: r.model.display, health: r.health, retires_date: r.model.retires_date, replacement_slug: r.model.replacement_slug, places: r.count })),
-      custom: [...custom.entries()].map(([name, places]) => ({ name, places })),
+      custom: customList,
       needs_attention: attention.length,
     }, null, 2));
     return;
@@ -730,9 +793,21 @@ async function cmdStatus(positional, flags) {
 
   const ageDays = Math.round((today - new Date(snapshot.generated_at)) / 86_400_000);
   console.log(`LLM Status — registry ${snapshot.version} (${ageDays <= 0 ? "today" : ageDays + "d old"}), ${snapshot.models.length} models`);
-  console.log(`Scanned ${dir}: ${candidates.length} reference(s) → ${known.size} model(s), ${custom.size} custom\n`);
+  console.log(`Scanned ${dir}: ${candidates.length} reference(s) in ${fileCount} file(s) → ${known.size} model(s), ${custom.size} custom`);
+  // Lead with the verdict so the result reads at a glance.
+  if (attention.length) {
+    const parts = [];
+    if (nDead) parts.push(`${nDead} retired`);
+    if (nRetiring) parts.push(`${nRetiring} retiring soon`);
+    if (nDeprecating) parts.push(`${nDeprecating} deprecating`);
+    console.log(`${attention.length} of ${known.size} model(s) need attention: ${parts.join(" · ")}`);
+  } else if (rows.length) {
+    console.log(`All ${known.size} model(s) you use are current.`);
+  }
+  console.log("");
+
   if (!rows.length && !custom.size) {
-    console.log("No model usage found here. Try `mm status <dir>`, or `mm scan` to map a whole project.");
+    console.log("No model usage found here. Point `mm status` at a repo, or run `mm scan` to map a whole project.");
     return;
   }
   if (rows.length) {
@@ -743,15 +818,23 @@ async function cmdStatus(positional, flags) {
       console.log(`  ${ICON[r.health]} ${r.health.padEnd(11)} ${r.model.slug.padEnd(32)} ${tail.padEnd(20)}${repl}  (${r.count})`);
     }
   }
-  if (custom.size) {
+  if (customList.length) {
     console.log("\nCustom / unrecognized:");
-    for (const [name, places] of custom) console.log(`  ⚪ ${name}  (${places})`);
+    const CAP = 12;
+    for (const c of customList.slice(0, CAP)) {
+      const hint = c.suggestion ? `   ≈ ${c.suggestion}?` : "";
+      console.log(`  ⚪ ${c.name}  (${c.places})${hint}`);
+    }
+    if (customList.length > CAP) console.log(`  … +${customList.length - CAP} more  (mm status --json for the full list)`);
   }
+  // Functional next steps only (no marketing voice): `mm fix` when something's
+  // auto-rewritable; the alerts pointer only when not signed in.
   if (attention.length) {
-    console.log(`\n⚠ ${attention.length} model(s) need attention before they retire.`);
-    console.log("  Get alerted automatically (email/Slack/SMS): `mm login` then `mm upgrade` — scanning is free, alerting is the paid feature.");
-  } else if (rows.length) {
-    console.log("\n✓ Everything you use is current.");
+    const fixable = attention.filter((r) => r.model.replacement_slug).length;
+    const tips = [];
+    if (fixable) tips.push(`\`mm fix\` rewrites the ${fixable} with a known replacement`);
+    if (!loadConfig().apiKey) tips.push("`mm login` to get alerted before these dates (Pro)");
+    if (tips.length) console.log("\n" + tips.map((t) => "→ " + t).join("\n"));
   }
 }
 
@@ -767,14 +850,15 @@ Usage:
   mm scan [dir]            Scan for model usage; interactive TUI, or --ci/--json for pipelines
   mm fix [dir]             Rewrite dying model ids to their replacement, in place (--dry-run previews; --model <slug> limits; --yes skips the confirm)
   mm ci [dir]              CI gate: fail the build on deprecated/retiring models (GitHub annotations)
-                          (--diff <base> limits findings to files changed vs base; auto on PRs via GITHUB_BASE_REF)
+                          (--fail-on <none|deprecating|retiring|retired> sets the threshold, default retired;
+                           --json-out <file> writes findings JSON; --diff <base> limits to changed files, auto on PRs)
   mm sources               List detection sources and whether each can run here
   mm integrations          Manage live integrations (list | enable <id> | disable <id> | env <id> <tag>)
   mm clear                 Delete all tracked usages from your inventory (--all also wipes projects/rules; --yes to skip the prompt)
   mm update                Update to the latest version now and relaunch (or add --update to any command)
   mm upgrade               Open Stripe checkout and poll until Pro is active (the paid plan, not the binary)
   mm play [dir]            Play Donkey Kong while a background scan walks the dir (just for fun)
-  mm tui                   Force-launch the TUI (logs you in first if needed)
+  mm tui                   Force-launch the TUI (needs an interactive terminal)
 
 Scan sources (--sources; default = filesystem + enabled integrations; "all" for everything):
   filesystem  repo files          aws-secrets  AWS Secrets Manager + SSM
@@ -786,7 +870,8 @@ Scan sources (--sources; default = filesystem + enabled integrations; "all" for
   Secret sources shell out to your already-authenticated CLIs, run read-only,
   and only ever upload model ids — secret VALUES never leave your machine.
 
-Flags: --update · --api <url> · --key <key> · --project <id|name> · --yes · --json · --ci · --dry-run
+Flags: --update · --api <url> · --key <key> · --project <id|name> · --dir <path> · --yes · --json · --ci · --dry-run
+       --offline (use the cached registry) · --model <slug> (fix) · --fail-on <t> · --json-out <file> (ci) · --all · --force (clear)
        --sources <list> · --region <r> · --namespace <ns> · --kube-context <c> · --db <dsn> · --sql-table <t>
        --vercel-project <p> · --vercel-team <t> · --gh-repo <owner/name> · --supabase-ref <ref>
 
@@ -854,6 +939,7 @@ async function main() {
 
   // Anonymous, opt-out usage analytics (one-time disclosure, then a single
   // event per invocation). No-op without a baked key / when opted out.
+  maybeFirstRun(); // one-time cli_first_run per install (same opt-out as below)
   track("cli_command", { command: cmd || "tui" });
 
   // Explicit self-update: `mm update` (command) or `--update` (flag on any

package/src/registry/local.js

@@ -21,10 +21,22 @@ export function resolveLocal(snapshot, strings) {
       const model = bySlug.get(slug) || null;
       return { input: s, model_slug: slug, display: model?.display ?? s, model, confidence: 1, suggestion: null };
     }
-    // No exact hit — find the nearest known id (longest two-way substring overlap).
-    let near = null;
+    // No exact hit — find the nearest known id. Prefer (1) a key the input is a
+    // PREFIX of (input = base id, key = a versioned form, e.g. "gpt-3" →
+    // "gpt-3.5-turbo"), taking the SHORTEST such (closest minor version); else
+    // (2) the longest known id the input CONTAINS (input is a longer variant);
+    // else (3) the longest known id that contains the input. Tiering avoids
+    // latching onto a long dated/ARN variant (the old longest-overlap rule
+    // suggested e.g. an Amazon Bedrock ARN slug for a bare "claude-sonnet-4").
+    let near = null, bestScore = -1, bestTie = -Infinity;
     for (const k of keys) {
-      if (k.length >= 4 && (k.includes(n) || n.includes(k)) && (!near || k.length > near.length)) near = k;
+      if (k.length < 4) continue;
+      let score, tie;
+      if (k.startsWith(n)) { score = 3; tie = -k.length; }      // versioned form of the base — shortest wins
+      else if (n.includes(k)) { score = 2; tie = k.length; }    // input is a longer variant of a known id
+      else if (k.includes(n)) { score = 1; tie = -k.length; }   // input embedded in a longer id — weakest
+      else continue;
+      if (score > bestScore || (score === bestScore && tie > bestTie)) { near = k; bestScore = score; bestTie = tie; }
     }
     const suggestion = near ? exact.get(near) || null : null;
     return { input: s, model_slug: null, display: s, model: null, confidence: suggestion ? 0.6 : 0, suggestion };

package/src/sources/index.js

@@ -94,7 +94,7 @@ export async function availability(sourceIds, opts = {}, explicit = new Set()) {
  * the cheap path: uses available() (PATH check), never authState() (spawn).
  * `explicit` is the set of ids the caller named verbatim — naming a live
  * integration there overrides the enabled-gate. */
-export async function collectFrom(sourceIds, opts, patterns, explicit = new Set()) {
+export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(), onProgress = null) {
   const compiled = compilePatterns(patterns);
   const ids = sourceIds && sourceIds.length ? sourceIds : ["filesystem"];
   const seen = new Set();
@@ -108,7 +108,9 @@ export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(
     // Fold the per-source declared envTag into opts.env so the integration's env
     // overrides guessEnvFrom — but an explicit --env flag (opts.env) still wins,
     // and Vercel's authoritative deploy target still wins inside its own collect.
-    const srcOpts = src.integration ? { ...opts, env: opts.env || getEnvTag(id) } : opts;
+    // onProgress (optional) lets a caller render a live file counter — only the
+    // filesystem source emits progress; the rest ignore the extra opt.
+    const srcOpts = src.integration ? { ...opts, env: opts.env || getEnvTag(id), onProgress } : { ...opts, onProgress };
     for (const c of await src.collect(srcOpts, compiled)) {
       const key = `${c.model_string}|${c.location_label}`;
       if (seen.has(key)) continue;

package/src/spinner.js

@@ -0,0 +1,45 @@
+/* Minimal dependency-free progress spinner for stderr. A silent command that
+ * spends a few seconds downloading the registry / scanning a repo reads as
+ * frozen — this gives live feedback. No-op when stderr isn't a TTY (piped, CI,
+ * --json) so machine output is never polluted. */
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CLEAR = "\r\x1b[2K"; // carriage return + clear the whole line
+
+/** Start a spinner. `active` lets callers force it off (e.g. --json). Returns
+ * { update(text), log(line), stop() }. `log` prints a line ABOVE the spinner
+ * (clears, writes, resumes) so warnings from the work aren't clobbered. */
+export function startProgress(active, text) {
+  const isTTY = !!process.stderr.isTTY;
+  if (!active || !isTTY) {
+    return { update() {}, log: (m) => process.stderr.write(`! ${m}\n`), stop() {} };
+  }
+  let i = 0;
+  let msg = text;
+  let timer = null;
+  const frame = () => process.stderr.write(`${CLEAR}${FRAMES[i = (i + 1) % FRAMES.length]} ${msg}`);
+  const start = () => {
+    frame();
+    timer = setInterval(frame, 80);
+    if (timer.unref) timer.unref(); // don't keep the process alive
+  };
+  const clear = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    process.stderr.write(CLEAR);
+  };
+  start();
+  return {
+    update(m) {
+      msg = m;
+    },
+    log(m) {
+      clear();
+      process.stderr.write(`! ${m}\n`);
+      start();
+    },
+    stop() {
+      clear();
+    },
+  };
+}

package/src/telemetry.js

@@ -8,7 +8,8 @@
  * --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";
+import { BUILD_VERSION, UPDATE_CHANNEL, IS_SHELL_INSTALL } from "./version.js";
+import { isBrewManaged } from "./updater.js";
 
 // eslint-disable-next-line no-undef
 const POSTHOG_KEY = typeof __POSTHOG_KEY__ !== "undefined" ? __POSTHOG_KEY__ : (process.env.MM_POSTHOG_KEY || "");
@@ -20,6 +21,33 @@ const optedOut = () => {
 };
 const enabled = () => !!POSTHOG_KEY && !optedOut();
 
+/** How this CLI got onto the machine, for real-user-metrics segmentation.
+ *  - "homebrew": the binary lives under a brew prefix (shared with updater.js).
+ *  - "npm": running through Node from a node_modules tree (npm -g / npx).
+ *  - "binary": the curl|bash CDN binary (Bun-compiled, IS_SHELL_INSTALL=true) or
+ *    anything else we can't otherwise place.
+ *  Small + pure: takes its inputs so it's trivially testable. */
+export function installMethod(execPath = process.execPath, scriptPath = process.argv[1] || "") {
+  if (isBrewManaged(execPath)) return "homebrew";
+  // npm/npx run Node directly with our script under a node_modules tree; the
+  // compiled CDN binary is its own execPath and never lives under node_modules.
+  if (!IS_SHELL_INSTALL && (/node_modules/.test(scriptPath) || /node_modules/.test(execPath))) return "npm";
+  return "binary";
+}
+
+/** Properties stamped onto EVERY captured event — version/os/install method, plus
+ *  internal:true for our own dev machines (set MM_INTERNAL=1) so they can be
+ *  excluded from real-user metrics. Kept tiny + side-effect free. */
+function baseProps() {
+  const p = {
+    cli_version: BUILD_VERSION,
+    os: process.platform,
+    install_method: installMethod(),
+  };
+  if (process.env.MM_INTERNAL) p.internal = true;
+  return p;
+}
+
 let cachedId = null;
 function distinctId() {
   if (cachedId) return cachedId;
@@ -56,10 +84,9 @@ export function track(event, properties = {}) {
         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,
+          ...baseProps(), // cli_version, os, install_method, internal (every event)
           ...properties,
         },
         timestamp: new Date().toISOString(),
@@ -69,3 +96,24 @@ export function track(event, properties = {}) {
     }).catch(() => {}).finally(() => clearTimeout(timer));
   } catch { /* analytics must never break the CLI */ }
 }
+
+/** Emit a one-time `cli_first_run` event the first time the CLI runs per install.
+ *  "First run" is marked by a `firstRunAt` ISO timestamp persisted to the config
+ *  file — written on the first invocation that gets here and never re-emitted.
+ *  Honors the SAME opt-out as every other event (track() gates on enabled(): no
+ *  key, MM_NO_ANALYTICS / DO_NOT_TRACK / CI, or a persisted analyticsOptOut). The
+ *  marker is still written when opted-out so flipping analytics on later doesn't
+ *  retroactively fire a "first run". Never throws. */
+export function maybeFirstRun() {
+  try {
+    let cfg;
+    try { cfg = loadConfig(); } catch { cfg = {}; }
+    if (cfg.firstRunAt) return; // already seen this install
+    try { setConfigValue("firstRunAt", new Date().toISOString()); } catch { /* best effort */ }
+    track("cli_first_run", {
+      install_method: installMethod(),
+      cli_version: BUILD_VERSION,
+      os: process.platform,
+    });
+  } catch { /* analytics must never break the CLI */ }
+}

package/src/updater.js

@@ -127,9 +127,10 @@ function dirWritable(dir) {
 
 /** True when the running binary lives under a Homebrew prefix. Brew owns the
  * binary's lifecycle (`brew upgrade`), and silently swapping it out from under
- * brew would break its integrity tracking — so we never self-update there. */
-function isBrewManaged() {
-  const p = process.execPath;
+ * brew would break its integrity tracking — so we never self-update there.
+ * Exported so telemetry's install-method detection shares one definition. */
+export function isBrewManaged(execPath = process.execPath) {
+  const p = execPath;
   return p.includes("/Cellar/") || p.includes("/homebrew/") || p.includes("/linuxbrew/");
 }