@modelstatus/cli 0.1.0 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelstatus/cli",
-  "version": "0.1.0",
+  "version": "0.1.25",
   "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/api.js

@@ -64,6 +64,9 @@ export function createClient({ apiBase, apiKey }) {
     linkUsage: (id, modelId) => req("POST", `/usages/${id}/link`, { model_id: modelId }),
     bulkUpload: (projectId, usages) => req("POST", "/usages/bulk", { project_id: projectId, usages }),
 
+    // ci runs (Pro) — record a CI evaluation for the dashboard + alerts
+    ciRun: (body) => req("POST", "/ci/runs", body),
+
     // notification rules
     listRules: () => req("GET", "/notification-rules"),
     createRule: (body) => req("POST", "/notification-rules", body),

package/src/ci.js

@@ -0,0 +1,143 @@
+/* CI evaluation engine: scan a repo, resolve against the signed registry, and
+ * report any deprecated/retiring/retired AI-model usage with file:line. Pure
+ * (no process.exit / no direct GitHub I/O) so it's testable; the `mm ci` command
+ * in index.js turns the result into GitHub annotations + a step summary + an
+ * exit code. Offline-capable — uses the public signed registry, no account. */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { getRegistry } from "./registry/fetch.js";
+import { resolveLocal, computeHealth } from "./registry/local.js";
+import { collectFrom } from "./sources/index.js";
+
+export const HEALTH_RANK = { ok: 0, deprecating: 1, retiring: 2, retired: 3 };
+// `--fail-on` threshold → the minimum health rank that fails the build.
+export const FAIL_THRESHOLD = { none: 99, deprecating: 1, retiring: 2, retired: 3 };
+const BADGE = { ok: "🟢", deprecating: "🟡", retiring: "🟠", retired: "🔴" };
+
+/** Evaluate `dir` and return { findings, failing, threshold, failOn, counts, snapshot }.
+ * `findings` are per-(model, location) entries with health worse than ok. */
+export async function evaluateCi({ dir, sources = ["filesystem"], scanOpts = {}, failOn = "retired", offline = false, log = () => {} }) {
+  // Online by default so CI checks against the LATEST registry; --offline (or the
+  // env) falls back to the cached snapshot. cacheFile env keeps tests hermetic.
+  const snapshot = await getRegistry({
+    offline: offline || process.env.LLMSTATUS_REGISTRY_OFFLINE === "1",
+    cacheFile: process.env.LLMSTATUS_REGISTRY_CACHE || undefined,
+    log: (m) => log(`${m}\n`),
+  });
+  const candidates = await collectFrom(sources, { root: dir, ...scanOpts }, snapshot.detection);
+  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();
+  const threshold = FAIL_THRESHOLD[failOn] ?? FAIL_THRESHOLD.retired;
+
+  const seen = new Set();
+  const findings = [];
+  for (const c of candidates) {
+    const r = byStr.get(c.model_string.toLowerCase());
+    if (!r?.model || !r.model_slug) continue; // only registry-known models can be scored
+    const health = computeHealth(r.model, 90, today);
+    if (health === "ok") continue;
+    const loc = `${c.source_path || c.location_label || ""}:${c.source_line || ""}`;
+    const key = r.model_slug + "|" + loc;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push({
+      slug: r.model_slug,
+      health,
+      retires: r.model.retires_date || null,
+      replacement: r.model.replacement_slug || null,
+      path: c.source_path || null,
+      line: c.source_line || null,
+      location: c.location_label || c.source_path || c.model_string,
+      env: c.environment || null,
+    });
+  }
+  findings.sort((a, b) => HEALTH_RANK[b.health] - HEALTH_RANK[a.health] || String(a.retires || "9999").localeCompare(String(b.retires || "9999")));
+
+  const counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0 };
+  for (const f of findings) counts[f.health]++;
+  const failing = findings.filter((f) => HEALTH_RANK[f.health] >= threshold);
+  return { snapshot, candidates, findings, failing, threshold, failOn, counts };
+}
+
+/**
+ * Pure filter: keep only findings whose `path` is in `changedPaths`. `changedPaths`
+ * is a Set of dir-relative posix paths (the same shape as `finding.path`). A `null`
+ * (or undefined) set means "couldn't determine the diff" → return findings unchanged
+ * (no filtering). Findings without a `path` are always dropped in diff mode, since we
+ * can't prove they belong to a changed file. No git / no I/O — trivially testable.
+ */
+export function filterToChangedFiles(findings, changedPaths) {
+  if (!changedPaths) return findings; // null/undefined → no diff info → don't filter
+  const norm = (p) => String(p || "").replace(/\\/g, "/").replace(/^\.\//, "");
+  const want = new Set([...changedPaths].map(norm));
+  return findings.filter((f) => f.path && want.has(norm(f.path)));
+}
+
+/**
+ * Run `git diff --name-only <base>...HEAD` in `dir` and return a Set of paths made
+ * RELATIVE TO `dir` (so they match `finding.path`, which is dir-relative). git reports
+ * repo-root-relative paths, so each is resolved against the repo root then re-based on
+ * `dir`. Returns `null` (caller falls back to the full finding set) when git is missing,
+ * `dir` is not a repo, or `base` is unknown — i.e. on ANY git failure. Optional `log`
+ * receives a human note on fallback. Synchronous + offline (pure local git).
+ */
+export function getChangedFiles(dir, base, { log = () => {}, git = "git" } = {}) {
+  if (!base) return null;
+  const run = (args) => execFileSync(git, args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  let repoRoot;
+  try {
+    repoRoot = run(["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    log(`--diff: not a git repo (or git not installed) — scanning all files.\n`);
+    return null;
+  }
+  let out;
+  try {
+    out = run(["diff", "--name-only", `${base}...HEAD`]);
+  } catch {
+    log(`--diff: couldn't diff against "${base}" (unknown ref?) — scanning all files.\n`);
+    return null;
+  }
+  const set = new Set();
+  for (const line of out.split(/\r?\n/)) {
+    const rel = line.trim();
+    if (!rel) continue;
+    // git path is repo-root-relative → make it dir-relative to match finding.path.
+    const relToDir = path.relative(dir, path.resolve(repoRoot, rel)).replace(/\\/g, "/");
+    set.add(relToDir);
+  }
+  return set;
+}
+
+const ann = (s) => String(s).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+
+/** GitHub Actions workflow-command annotations (one per finding). Inline on the PR. */
+export function annotationLines(findings, threshold) {
+  return findings.map((f) => {
+    const sev = HEALTH_RANK[f.health] >= threshold ? "error" : "warning";
+    const where = f.path ? `file=${ann(f.path)},line=${f.line || 1},` : "";
+    const msg = `${f.slug} is ${f.health}${f.retires ? ` (retires ${f.retires})` : ""}${f.replacement ? ` — switch to ${f.replacement}` : ""}`;
+    return `::${sev} ${where}title=AI model ${f.health}::${ann(msg)}`;
+  });
+}
+
+/** Markdown for $GITHUB_STEP_SUMMARY (and a decent human report). */
+export function summaryMarkdown(findings, { failing, failOn } = {}) {
+  const lines = ["## LLM Status — model lifecycle check", ""];
+  if (!findings.length) {
+    lines.push("✅ No deprecated, retiring, or retired AI models found.");
+    return lines.join("\n") + "\n";
+  }
+  const fc = failing ? failing.length : 0;
+  lines.push(fc ? `🔴 **${fc}** usage(s) at or past the \`${failOn}\` threshold — this check fails.` : `Found ${findings.length} aging model usage(s) (below the \`${failOn}\` fail threshold).`, "");
+  lines.push("| | Model | Where | Retires | Replacement |", "|---|---|---|---|---|");
+  for (const f of findings.slice(0, 100)) {
+    lines.push(`| ${BADGE[f.health]} ${f.health} | \`${f.slug}\` | \`${f.location || ""}\` | ${f.retires || "—"} | ${f.replacement ? `\`${f.replacement}\`` : "—"} |`);
+  }
+  if (findings.length > 100) lines.push(`\n…and ${findings.length - 100} more.`);
+  lines.push("", "_Powered by [LLM Status](https://llmstatus.ai)._");
+  return lines.join("\n") + "\n";
+}
+
+export { BADGE };

package/src/detect/core.js

@@ -12,6 +12,28 @@ function cleanGeneric(s) {
   return s.replace(/^[.\-_]+/, "").replace(/[.\-_]+$/, "");
 }
 
+/** A char is part of a model token if it's alnum or one of - _ . / : (slug-ish).
+ * Mirrors the server PR scanner (apps/web/lib/github/scan-pr.ts) so the CLI and
+ * the GitHub check agree on what counts as a boundary. */
+function isTokenChar(ch) {
+  return /[A-Za-z0-9._/:-]/.test(ch);
+}
+
+/** True when `term` occurs in `haystack` at a word-ish boundary (not embedded
+ * inside a longer identifier). Both are already lower-cased. This is what stops
+ * the alias "gpt-4" from matching inside "gpt-4o-mini" (→ wrong, older model). */
+function matchesAtBoundary(haystack, term) {
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(term, from);
+    if (at < 0) return false;
+    const before = at > 0 ? haystack[at - 1] : "";
+    const after = at + term.length < haystack.length ? haystack[at + term.length] : "";
+    if ((before === "" || !isTokenChar(before)) && (after === "" || !isTokenChar(after))) return true;
+    from = at + 1; // a later occurrence may be bounded
+  }
+}
+
 /** 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. */
@@ -33,7 +55,10 @@ export function compilePatterns(patterns) {
 export function detectInLine(line, compiled) {
   const lower = line.toLowerCase();
   const found = new Set();
-  for (const s of compiled.exact) if (lower.includes(s)) found.add(s);
+  // 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);
   for (const re of compiled.generic) {
     re.lastIndex = 0;
     let m;

package/src/index.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import path from "node:path";
 import { resolveAuth, loadConfig, saveConfig, clearAuth, configFilePath } from "./config.js";
 import { createClient } from "./api.js";
 import { collectFrom, availability, ALL_SOURCE_IDS } from "./sources/index.js";
 import { loginViaBrowser } from "./auth.js";
+import { maybeCheckForUpdate } from "./updater.js";
+import { track, maybeAnalyticsNotice } from "./telemetry.js";
+import { BUILD_VERSION } from "./version.js";
 
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
   const valueFlags = new Set([
-    "api", "key", "project", "dir",
+    "api", "key", "project", "dir", "fail-on", "diff", "json-out",
     "sources", "region", "namespace", "kube-context", "db", "sql-table", "env",
   ]);
   for (let i = 0; i < argv.length; i++) {
@@ -29,6 +33,12 @@ function parseArgs(argv) {
 
 const uuidish = (s) => /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(s || "");
 
+/** The "owner/name" repo slug for source deep-links. In GitHub Actions
+ * GITHUB_REPOSITORY is exactly that and the checkout is repo-root-relative (so
+ * our source_path lines up). Outside CI we return "" (omit it) rather than guess
+ * from a git remote, since a local scan root may not be the repo root. */
+const ghRepoSlug = () => (process.env.GITHUB_REPOSITORY || "").trim();
+
 /** Resolve the requested sources: default filesystem, "all", or a comma list. */
 function parseSources(flags) {
   const raw = (flags.sources || "").trim();
@@ -95,14 +105,16 @@ async function cmdUpgrade(_positional, flags) {
 }
 
 async function launchTui(initialView, flags) {
-  let { apiBase, apiKey } = resolveAuth(flags);
-  if (!apiKey) {
-    console.error("Not signed in — starting browser login…");
-    ({ apiKey } = await loginViaBrowser({ apiBase }));
-  }
+  // 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.
+  const { apiBase, apiKey } = resolveAuth(flags);
   const dir = path.resolve(flags.dir || ".");
   const { runApp } = await import("./tui/app.js");
-  await runApp({ apiBase, apiKey, dir, initialView });
+  // --scan / --rescan / --fresh force a fresh filesystem walk instead of loading
+  // the last persisted scan.
+  await runApp({ apiBase, apiKey, dir, initialView, fresh: !!(flags.scan || flags.rescan || flags.fresh) });
 }
 
 async function cmdScan(positional, flags) {
@@ -161,6 +173,7 @@ async function cmdScan(positional, flags) {
     custom_model_name: r.model_id ? undefined : r.model_string,
     environment: r.environment,
     location_label: r.location_label,
+    source_repo: ghRepoSlug() || undefined,
     source_path: r.source_path,
     source_line: r.source_line ?? undefined,
   }));
@@ -190,6 +203,7 @@ async function cmdScan(positional, flags) {
   }
 
   const res = await client.bulkUpload(projectId, usages);
+  track("usages_uploaded", { count: usages.length, created: res.created, updated: res.updated, source: "cli" });
   if (flags.json) {
     console.log(
       JSON.stringify(
@@ -205,6 +219,144 @@ async function cmdScan(positional, flags) {
   }
 }
 
+/** Pro cloud sync for `mm ci --report`: push this run's usages to the account so
+ * the dashboard tracks per-commit drift + alerts can fire. Plan-gated server-side
+ * (402 → skipped, the local check still ran). Best-effort: never fails the build. */
+async function ciReport(dir, flags, res) {
+  const { apiBase, apiKey } = resolveAuth(flags);
+  if (!apiKey) {
+    process.stderr.write("! --report needs an API key (set LLMSTATUS_API_KEY) — skipping cloud sync.\n");
+    return null;
+  }
+  const client = createClient({ apiBase, apiKey });
+  const uniq = [...new Set(res.candidates.map((c) => c.model_string))];
+  const resolved = uniq.length ? (await client.resolve(uniq)).data || [] : [];
+  const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
+  const seen = new Set();
+  const usages = [];
+  for (const c of res.candidates) {
+    const r = byStr.get(c.model_string.toLowerCase());
+    const k = `${r?.model_id ?? "custom:" + c.model_string}|${c.location_label}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    usages.push({
+      model_id: r?.model_id ?? undefined,
+      custom_model_name: r?.model_id ? undefined : c.model_string,
+      environment: c.environment,
+      location_label: c.location_label,
+      source_path: c.source_path,
+      source_line: c.source_line ?? undefined,
+    });
+  }
+  try {
+    const projectName = flags.project || (process.env.GITHUB_REPOSITORY || "").split("/").pop() || path.basename(dir);
+    const projects = (await client.listProjects()).data || [];
+    const projectId = projects.find((p) => p.name === projectName)?.id || (await client.createProject(projectName)).id;
+    const r = await client.bulkUpload(projectId, usages);
+    process.stderr.write(`✓ Reported ${usages.length} usage(s) to LLM Status (project "${projectName}").\n`);
+    return { project: projectName, ...r };
+  } catch (e) {
+    if (e.status === 402) process.stderr.write("! Cloud CI reporting is a Pro feature — the local check still ran. Upgrade with: mm upgrade\n");
+    else process.stderr.write(`! Cloud report skipped: ${e.message}\n`);
+    return null;
+  }
+}
+
+/** Record this run's summary to /ci/runs (the dashboard's source). Pulls commit/
+ * branch/repo from the GitHub Actions env (sensible local fallbacks). Best-effort,
+ * Pro-gated server-side (402 → skipped). Never throws into the CI gate. */
+async function postCiRun(dir, flags, res, failOn) {
+  const { apiBase, apiKey } = resolveAuth(flags);
+  if (!apiKey) return null;
+  const env = process.env;
+  const client = createClient({ apiBase, apiKey });
+  try {
+    await client.ciRun({
+      commit_sha: env.GITHUB_SHA || "local",
+      branch: env.GITHUB_REF_NAME || "",
+      ref: env.GITHUB_REF || "",
+      repo: env.GITHUB_REPOSITORY || path.basename(path.resolve(dir)),
+      counts: res.counts,
+      fail_on: failOn,
+      failing_count: res.failing.length,
+      findings: res.findings.slice(0, 200),
+    });
+    return true;
+  } catch (e) {
+    if (e.status === 402) process.stderr.write("! CI run recording is a Pro feature — the local check still ran. Upgrade: mm upgrade\n");
+    return null;
+  }
+}
+
+/** `mm ci [dir]` — evaluate the repo for deprecated/retiring models. Emits GitHub
+ * 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 || ".");
+  const failOn = String(flags["fail-on"] || "retired").toLowerCase();
+  const { evaluateCi, annotationLines, summaryMarkdown, filterToChangedFiles, getChangedFiles, HEALTH_RANK } = await import("./ci.js");
+  const res = await evaluateCi({
+    dir,
+    sources: parseSources(flags),
+    scanOpts: scanOpts(flags, dir),
+    failOn,
+    offline: !!flags.offline,
+    log: (m) => process.stderr.write(`! ${m}`),
+  });
+  let { findings, failing, threshold, counts } = res;
+
+  // --diff <base> (or a GitHub PR: GITHUB_BASE_REF as base, HEAD as head) restricts
+  // findings to files CHANGED vs base — we still scan the whole repo, then drop findings
+  // whose source_path isn't in the changed set. getChangedFiles returns null on any git
+  // failure (missing git / not a repo / bad base), and filterToChangedFiles treats null
+  // as "don't filter", so we transparently fall back to the full set with a stderr note.
+  const diffBase = flags.diff && flags.diff !== true ? flags.diff : process.env.GITHUB_BASE_REF || null;
+  if (diffBase) {
+    const changed = getChangedFiles(dir, diffBase, { log: (m) => process.stderr.write(`! ${m}`) });
+    if (changed) {
+      findings = filterToChangedFiles(findings, changed);
+      failing = findings.filter((f) => HEALTH_RANK[f.health] >= threshold);
+      counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0 };
+      for (const f of findings) counts[f.health]++;
+      process.stderr.write(`! --diff ${diffBase}: ${findings.length} finding(s) in ${changed.size} changed file(s).\n`);
+    }
+  }
+
+  if (process.env.GITHUB_ACTIONS) {
+    for (const a of annotationLines(findings, threshold)) console.log(a);
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summaryMarkdown(findings, { failing, failOn })); } catch { /* best effort */ }
+    }
+  }
+
+  // Record the run to the account (Pro): inventory drift (bulkUpload) + a CI-run
+  // row for the dashboard. Best-effort, plan-gated server-side, never fails CI.
+  const reported = flags.report ? await ciReport(dir, flags, res).catch(() => null) : null;
+  if (flags.report) await postCiRun(dir, flags, res, failOn).catch(() => null);
+
+  const report = { scanned: dir, fail_on: failOn, counts, findings, failing: failing.length, reported };
+  // --json-out writes CLEAN JSON to a file (annotations still go to stdout for
+  // GitHub) so a CI step can parse it without stdout pollution.
+  if (flags["json-out"]) { try { fs.writeFileSync(flags["json-out"], JSON.stringify(report, null, 2)); } catch { /* best effort */ } }
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    const ICON = { ok: "🟢", deprecating: "🟡", retiring: "🟠", retired: "🔴" };
+    console.log(`LLM Status CI — scanned ${dir}  (fail-on: ${failOn})`);
+    if (!findings.length) {
+      console.log("✓ No deprecated, retiring, or retired AI models found.");
+    } else {
+      for (const f of findings) {
+        console.log(`  ${ICON[f.health]} ${f.health.padEnd(11)} ${f.slug.padEnd(30)} ${String(f.location || "").padEnd(28)}${f.retires ? ` retires ${f.retires}` : ""}${f.replacement ? ` → ${f.replacement}` : ""}`);
+      }
+      console.log("");
+      console.log(failing.length ? `✗ ${failing.length} usage(s) at or past "${failOn}" — failing the build.` : `✓ ${findings.length} aging usage(s), none past "${failOn}".`);
+    }
+  }
+  if (failing.length) process.exit(1);
+}
+
 /** List detection sources and whether each can run right now. */
 async function cmdSources(_positional, flags) {
   const dir = path.resolve(flags.dir || ".");
@@ -292,15 +444,17 @@ async function cmdStatus(positional, flags) {
 const HELP = `LLM Status CLI
 
 Usage:
-  mm                       Launch the TUI (inventory, scan, what's-new, alerts, account)
+  mm                       Launch the TUI (signs you in via in-TUI device flow if needed)
   mm status [dir]          Offline model-health check for a dir — no account needed
   mm login [api_key]       Browser sign-in with polling (or paste a key)
   mm signup                Create an account in the browser, then poll
   mm logout                Forget the saved API key
   mm scan [dir]            Scan for model usage; interactive TUI, or --ci/--json for pipelines
+  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)
   mm sources               List detection sources and whether each can run here
   mm upgrade               Open Stripe checkout and poll until Pro is active
-  mm tui                   Same as bare \`mm\`
+  mm tui                   Force-launch the TUI (logs you in first if needed)
 
 Scan sources (--sources, default filesystem; "all" for everything):
   filesystem  repo files          aws-secrets  AWS Secrets Manager + SSM
@@ -314,24 +468,60 @@ Flags: --api <url> · --key <key> · --project <id|name> · --yes · --json · -
 
 Get started: \`mm login\` (opens your browser).`;
 
+/** Awaits the updater promise; prints a one-liner if an update completed. Never throws. */
+async function maybePrintUpdate(promise) {
+  try {
+    const r = await promise;
+    if (!r) return;
+    if (r.manual) {
+      // Can't auto-update in place (root-owned dir like /usr/local/bin) — would
+      // be unsafe. Point the user at a one-line reinstall to a user-owned dir.
+      process.stderr.write(`\n✦ mm ${r.to} is available (you're on ${r.from}). Auto-update can't write ${process.execPath} — reinstall:\n  curl -fsSL https://llmstatus.ai/install.sh | bash\n`);
+    } else {
+      process.stderr.write(`\n✓ Updated mm ${r.from} → ${r.to} — your next run uses the new version.\n`);
+    }
+  } catch {
+    /* swallow */
+  }
+}
+
 async function main() {
   const { positional, flags } = parseArgs(process.argv.slice(2));
   const cmd = positional[0];
+
+  // --version / -v: print + exit (skip dispatch + updater).
+  if (cmd === "version" || flags.version || flags.v) {
+    console.log(BUILD_VERSION);
+    return;
+  }
+
+  // Anonymous, opt-out usage analytics (one-time disclosure, then a single
+  // event per invocation). No-op without a baked key / when opted out.
+  maybeAnalyticsNotice();
+  track("cli_command", { command: cmd || "tui" });
+
+  // Kick off the background self-update check — runs in parallel with the
+  // user's command, capped at 1/24h, only for shell-installed binaries.
+  const updatePromise = maybeCheckForUpdate(flags);
+
   try {
     if (cmd === "login") await cmdLogin(positional, flags);
     else if (cmd === "signup") await cmdSignup(positional, flags);
     else if (cmd === "logout") cmdLogout();
     else if (cmd === "scan") await cmdScan(positional, flags);
+    else if (cmd === "ci") await cmdCi(positional, flags);
     else if (cmd === "status") await cmdStatus(positional, flags);
     else if (cmd === "sources") await cmdSources(positional, flags);
     else if (cmd === "upgrade") await cmdUpgrade(positional, flags);
-    else if (cmd === "tui" || !cmd) await launchTui(positional[1] || "inventory", flags);
+    else if (cmd === "tui" || !cmd) await launchTui(positional[1], flags);
     else if (cmd === "help" || flags.help) console.log(HELP);
     else console.log(HELP);
   } catch (e) {
     console.error(`Error: ${e?.message ?? e}`);
+    await maybePrintUpdate(updatePromise);
     process.exit(1);
   }
+  await maybePrintUpdate(updatePromise);
 }
 
 main();

package/src/openUrl.js

@@ -1,4 +1,46 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+
+function hasCmd(c) {
+  try {
+    return spawnSync(process.platform === "win32" ? "where" : "which", [c], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Open a source location in the user's editor. Prefers a line-aware editor
+ * ($MM_EDITOR template, then `code -g`/`cursor -g`); falls back to the OS opener
+ * (no line jump). Non-blocking, best-effort, never throws. Test-gated by
+ * LLMSTATUS_NO_OPEN. Returns true if something was launched. */
+export function openLocation(absPath, line) {
+  if (process.env.LLMSTATUS_NO_OPEN) return false;
+  const target = line ? `${absPath}:${line}` : absPath;
+  const editorEnv = (process.env.MM_EDITOR || "").trim();
+  let cmd, args;
+  if (editorEnv) {
+    const parts = editorEnv.split(/\s+/);
+    cmd = parts[0];
+    args = [...parts.slice(1), target];
+  } else if (hasCmd("code")) {
+    cmd = "code"; args = ["-g", target];
+  } else if (hasCmd("cursor")) {
+    cmd = "cursor"; args = ["-g", target];
+  } else if (process.platform === "darwin") {
+    cmd = "open"; args = [absPath];
+  } else if (process.platform === "win32") {
+    cmd = "cmd"; args = ["/c", "start", "", absPath];
+  } else {
+    cmd = "xdg-open"; args = [absPath];
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 /** Open a URL in the user's default browser, cross-platform. Best-effort: if it
  * fails we still printed the URL, so the user can open it manually. */

package/src/registry/local.js

@@ -1,14 +1,33 @@
 /* Offline resolution + health from a verified snapshot — mirrors the server's
  * computeHealth (apps/web/lib/serialize.ts) so an offline run matches online. */
 
-/** Resolve model strings against the snapshot's detection table (exact match). */
+/** Resolve model strings against the snapshot's detection table.
+ *
+ * Exact match stays AUTHORITATIVE: only an exact hit sets `model` (and thus
+ * lifecycle/health), so a custom id never inherits a real model's retirement
+ * date by accident. For misses we attach a non-authoritative `suggestion` — the
+ * nearest known id by two-way substring containment (mirrors the server's 0.6
+ * fuzzy in apps/web/lib/services/registry.ts) — so callers can hint "≈ gpt-4?"
+ * on a typo without treating it as a confirmed match. `confidence`: 1 exact,
+ * 0.6 suggestion, 0 unknown. */
 export function resolveLocal(snapshot, strings) {
   const exact = new Map((snapshot.detection?.model_strings || []).map((s) => [s.match.toLowerCase(), s.model_slug]));
   const bySlug = new Map((snapshot.models || []).map((m) => [m.slug, m]));
+  const keys = [...exact.keys()];
   return strings.map((s) => {
-    const slug = exact.get(String(s).toLowerCase()) || null;
-    const model = slug ? bySlug.get(slug) || null : null;
-    return { input: s, model_slug: slug, display: model?.display ?? s, model };
+    const n = String(s).toLowerCase();
+    const slug = exact.get(n) || null;
+    if (slug) {
+      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;
+    for (const k of keys) {
+      if (k.length >= 4 && (k.includes(n) || n.includes(k)) && (!near || k.length > near.length)) near = k;
+    }
+    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/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 */ }
+}