@modelstatus/cli 0.1.86 → 0.1.88

package/src/index.js

@@ -6,6 +6,7 @@ import { spawnSync } from "node:child_process";
 import { resolveAuth, loadConfig, saveConfig, clearAuth, configFilePath } from "./config.js";
 import { createClient } from "./api.js";
 import { collectFrom, availability, ALL_SOURCE_IDS, getSource } from "./sources/index.js";
+import * as SourcesMod from "./sources/index.js";
 import {
   INTEGRATION_IDS, INTEGRATION_META, readIntegrations, enabledIds,
   getEnvTag, setEnabled, setEnvTag,
@@ -14,7 +15,7 @@ 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, maybeFirstRun } from "./telemetry.js";
+import { track, analyticsState, maybeFirstRun, telemetryCommand } from "./telemetry.js";
 import { startProgress } from "./spinner.js";
 import { BUILD_VERSION } from "./version.js";
 
@@ -85,21 +86,55 @@ if (process.argv[2] === "__bench_frames") {
   process.exit(0);
 }
 
+// The ONE table of every flag the CLI accepts (keep HELP/COMMAND_HELP in sync).
+// VALUE_FLAGS take an argument (space or GNU `--flag=value` form); BOOL_FLAGS
+// don't. Anything else is an invocation error — a typo'd flag must fail loudly,
+// never silently change behavior (`--fail-on=none` used to parse as an unknown
+// boolean and silently run the CI gate at the default threshold).
+const VALUE_FLAGS = new Set([
+  "api", "key", "project", "dir", "fail-on", "diff", "json-out", "model",
+  "sources", "region", "namespace", "kube-context", "db", "sql-table", "env",
+  // Per-integration scope flags (non-secret): consumed by the 4 live sources.
+  "vercel-project", "vercel-team", "gh-repo", "supabase-ref",
+]);
+const BOOL_FLAGS = new Set([
+  "help", "h", "version", "v", "ci", "yes", "json", "dry-run", "update",
+  "offline", "all", "force", "report", "lifetime", "scan", "rescan", "fresh",
+]);
+
+function argError(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
-  const valueFlags = new Set([
-    "api", "key", "project", "dir", "fail-on", "diff", "json-out", "model",
-    "sources", "region", "namespace", "kube-context", "db", "sql-table", "env",
-    // Per-integration scope flags (non-secret): consumed by the 4 live sources.
-    "vercel-project", "vercel-team", "gh-repo", "supabase-ref",
-  ]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a.startsWith("--")) {
-      const name = a.slice(2);
-      if (valueFlags.has(name)) flags[name] = argv[++i];
-      else flags[name] = true;
+      let name = a.slice(2);
+      let inline = null; // GNU `--name=value` form: split on the FIRST '='
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        inline = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      if (VALUE_FLAGS.has(name)) {
+        const v = inline !== null ? inline : argv[++i];
+        // A missing value — or the NEXT flag where the value should be — must
+        // error, not swallow the flag (`mm status --dir --json` used to scan a
+        // dir literally named "--json" and lose --json).
+        if (v === undefined || v === "" || (inline === null && v.startsWith("--"))) {
+          argError(`--${name} requires a value`);
+        }
+        flags[name] = v;
+      } else if (BOOL_FLAGS.has(name)) {
+        if (inline !== null) argError(`--${name} does not take a value`);
+        flags[name] = true;
+      } else {
+        argError(`unknown flag: --${name} (run \`mm --help\` for the list)`);
+      }
     } else if (a === "-h") flags.help = true;
     else if (a === "-v") flags.version = true;
     else positional.push(a);
@@ -156,6 +191,34 @@ function scanOpts(flags, dir) {
   };
 }
 
+/** Loud path guard for scan-shaped commands: a missing path (or a file where a
+ * directory is expected) is an INVOCATION error, exit 1 — never a clean
+ * "0 references" scan. A typo'd dir in a CI workflow used to gate green forever. */
+function requireDirectory(dir) {
+  let st = null;
+  try { st = fs.statSync(dir); } catch { /* missing */ }
+  if (!st) {
+    console.error(`path does not exist: ${dir}`);
+    process.exit(1);
+  }
+  if (!st.isDirectory()) {
+    console.error(`expected a directory: ${dir}`);
+    process.exit(1);
+  }
+}
+
+/** Unknown --sources ids are an invocation error (exit 1), never a silent
+ * empty scan (`--sources filesysten` used to report a clean result). Prefers
+ * sources/index.js's unknownSourceIds; falls back to a getSource filter. */
+function assertKnownSources(ids) {
+  const unknownOf = SourcesMod.unknownSourceIds ?? ((xs) => xs.filter((id) => !getSource(id)));
+  const unknown = unknownOf(ids);
+  if (unknown.length) {
+    console.error(`unknown source: ${unknown.join(", ")} (known: ${ALL_SOURCE_IDS.join(", ")})`);
+    process.exit(1);
+  }
+}
+
 async function cmdLogin(positional, flags) {
   const key = positional[1] || flags.key;
   const { apiBase } = resolveAuth(flags);
@@ -203,7 +266,8 @@ async function cmdUpgrade(_positional, flags) {
   const checkoutPlan = flags.lifetime ? "lifetime" : undefined;
   const plan = await upgradeViaBrowser({ client, plan: checkoutPlan });
   if (!plan) {
-    console.error("Upgrade not detected (timed out). Run `mm upgrade` again if you completed checkout.");
+    // Never claim success here — the target plan was not confirmed.
+    console.error("Purchase not confirmed yet — check your plan at llmstatus.ai/app, or re-run `mm upgrade` after completing checkout.");
     process.exit(1);
   }
 }
@@ -274,23 +338,28 @@ async function launchTui(initialView, flags) {
 
 async function cmdScan(positional, flags) {
   const dir = path.resolve(positional[1] || flags.dir || ".");
+  requireDirectory(dir);
+  const dryRun = !!flags["dry-run"];
   const { apiBase, apiKey } = resolveAuth(flags);
-  if (!apiKey) {
+  // --dry-run is a fully LOCAL preview — no account, ZERO calls to the API.
+  // (The signed registry CDN fetch is its only network, same as `mm status`.)
+  if (!apiKey && !dryRun) {
     console.error("No API key. Run `mm login` or pass --key.");
     process.exit(1);
   }
   // --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;
+  const interactive = !flags.yes && !flags.json && !dryRun && process.stdout.isTTY;
   if (interactive) {
     const { runApp } = await import("./tui/app.js");
     await runApp({ apiBase, apiKey, dir, initialView: "scan" });
     return;
   }
 
-  // Non-interactive (CI / --json / --yes): scan + bulk upload, no TUI.
-  const client = createClient({ apiBase, apiKey });
+  // Non-interactive (CI / --json / --yes): scan (+ bulk upload unless --dry-run).
+  const client = dryRun ? null : createClient({ apiBase, apiKey });
   const sources = parseSources(flags);
+  assertKnownSources(sources);
   const explicit = explicitSources(flags);
   const opts = scanOpts(flags, dir);
 
@@ -305,7 +374,22 @@ async function cmdScan(positional, flags) {
   const active = avail.filter((a) => a.available).map((a) => a.id);
   process.stderr.write(`Scanning [${active.join(", ") || "none"}] …\n`);
 
-  const patterns = await client.detectionPatterns();
+  // Detection patterns: the upload path asks the API (needs the key anyway); the
+  // dry-run path uses the SIGNED PUBLIC SNAPSHOT so the preview never touches
+  // the API — it works logged-out and offline (--offline / cached registry).
+  let snapshot = null;
+  let patterns;
+  if (dryRun) {
+    const { getRegistry } = await import("./registry/fetch.js");
+    snapshot = await getRegistry({
+      offline: !!flags.offline || process.env.LLMSTATUS_REGISTRY_OFFLINE === "1",
+      cacheFile: process.env.LLMSTATUS_REGISTRY_CACHE || undefined,
+      log: (m) => process.stderr.write(`! ${m}\n`),
+    });
+    patterns = snapshot.detection;
+  } else {
+    patterns = await client.detectionPatterns();
+  }
   const candidates = await collectFrom(sources, opts, patterns, explicit);
   if (candidates.length === 0) {
     // Respect --json/--ci even on the empty path, so `mm scan --ci | jq` never
@@ -313,7 +397,7 @@ async function cmdScan(positional, flags) {
     if (flags.json) {
       const srcRows = avail.map((a) => ({ id: a.id, available: a.available }));
       console.log(JSON.stringify(
-        flags["dry-run"]
+        dryRun
           ? { scanned: 0, would_upload: [], sources: avail }
           : { scanned: 0, uploaded: 0, sources: srcRows, created: 0, updated: 0, failed: 0 },
         null, 2,
@@ -324,31 +408,45 @@ async function cmdScan(positional, flags) {
     return;
   }
 
+  // Resolution: dry-run resolves against the local snapshot (no POST of the
+  // detected model inventory); the real upload path resolves server-side.
   const uniq = [...new Set(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]));
+  let byStr;
+  if (dryRun) {
+    const { resolveLocal } = await import("./registry/local.js");
+    byStr = new Map(resolveLocal(snapshot, uniq).map((r) => [r.input.toLowerCase(), r]));
+  } else {
+    const resolved = uniq.length ? (await client.resolve(uniq)).data : [];
+    byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
+  }
   const seenRows = new Set();
   const rows = candidates
     .map((c) => {
       const r = byStr.get(c.model_string.toLowerCase());
-      return { ...c, model_id: r?.model_id ?? null, display: r?.model_id ? r.display : c.model_string };
+      const hit = r?.model_id ?? r?.model_slug ?? null;
+      return { ...c, model_id: r?.model_id ?? null, model_slug: r?.model_slug ?? null, display: hit ? r.display : c.model_string };
     })
     .filter((r) => {
-      const k = `${r.model_id ?? "custom:" + r.model_string}|${r.location_label}`;
+      const k = `${r.model_id ?? r.model_slug ?? "custom:" + r.model_string}|${r.location_label}`;
       if (seenRows.has(k)) return false;
       seenRows.add(k);
       return true;
     });
 
-  // Build the upload payload via the SHARED helper so the command, the TUI Scan
-  // tab, and the Here push produce byte-identical usages (model resolution +
-  // redaction + the location_label scheme prefix that carries provenance). Parity-
-  // only: buildUsages reads the same fields the inline map did and falls back to
-  // GITHUB_REPOSITORY for source_repo. No new data is uploaded.
-  const usages = await buildUsages(client, rows);
-
-  // --dry-run: show exactly what WOULD upload (secret-source safety check).
-  if (flags["dry-run"]) {
+  // --dry-run: show exactly what WOULD upload (secret-source safety check),
+  // built entirely locally — model_slug instead of the server's model_id, the
+  // same redaction as the real payload, and nothing sent anywhere.
+  if (dryRun) {
+    const ghRepo = (process.env.GITHUB_REPOSITORY || "").trim();
+    const usages = rows.map((r) => ({
+      model_slug: r.model_slug ?? undefined,
+      custom_model_name: r.model_slug ? undefined : redactValue(r.model_string).slice(0, 120),
+      environment: r.environment,
+      location_label: r.location_label,
+      source_repo: r.source_repo || ghRepo || undefined,
+      source_path: r.source_path,
+      source_line: r.source_line ?? undefined,
+    }));
     if (flags.json) {
       console.log(JSON.stringify({ scanned: rows.length, would_upload: usages, sources: avail }, null, 2));
     } else {
@@ -356,10 +454,20 @@ async function cmdScan(positional, flags) {
       console.log(`Dry run — ${rows.length} usage(s) found across [${types}]. Nothing uploaded:`);
       for (const r of rows.slice(0, 60)) console.log(`  ${(r.display || r.model_string).padEnd(28)} ${r.location_label}  (${r.environment})`);
       if (rows.length > 60) console.log(`  …and ${rows.length - 60} more`);
+      console.log(apiKey
+        ? "\n(dry run — nothing uploaded. Re-run without --dry-run to upload.)"
+        : "\n(dry run — nothing uploaded. Uploading needs an account: run `mm login` first.)");
     }
     return;
   }
 
+  // Build the upload payload via the SHARED helper so the command, the TUI Scan
+  // tab, and the Here push produce byte-identical usages (model resolution +
+  // redaction + the location_label scheme prefix that carries provenance). Parity-
+  // only: buildUsages reads the same fields the inline map did and falls back to
+  // GITHUB_REPOSITORY for source_repo. No new data is uploaded.
+  const usages = await buildUsages(client, rows);
+
   // --project routes everything to one project; otherwise assignProjects derives a
   // real per-file project (git-root README › repo › path chunk). Shared with the
   // TUI so the command + tabs assign identically.
@@ -471,18 +579,28 @@ async function cmdCi(positional, flags) {
   // 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 */ }
+  try { dir = fs.realpathSync(dir); } catch { /* keep resolved path; requireDirectory errors next */ }
+  // A CI gate must NEVER read a bad invocation as a clean pass: a missing/renamed
+  // dir or a typo'd source id is exit 1, not a green "no models found".
+  requireDirectory(dir);
+  const sources = parseSources(flags);
+  assertKnownSources(sources);
+  const explicit = explicitSources(flags);
   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);
   }
+  // Surface skipped-but-requested sources on stderr (annotations stay on stdout).
+  for (const a of await availability(sources, scanOpts(flags, dir), explicit)) {
+    if (!a.available) process.stderr.write(`! ${a.id} unavailable (tool, creds, or flags missing) — skipped\n`);
+  }
   const { evaluateCi, annotationLines, summaryMarkdown, filterToChangedFiles, getChangedFiles, HEALTH_RANK } = await import("./ci.js");
   const res = await evaluateCi({
     dir,
-    sources: parseSources(flags),
-    explicit: explicitSources(flags),
+    sources,
+    explicit,
     scanOpts: scanOpts(flags, dir),
     failOn,
     offline: !!flags.offline,
@@ -501,7 +619,7 @@ async function cmdCi(positional, flags) {
     if (changed) {
       findings = filterToChangedFiles(findings, changed);
       failing = findings.filter((f) => HEALTH_RANK[f.health] >= threshold);
-      counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0 };
+      counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0, withdrawn: 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`);
     }
@@ -530,7 +648,7 @@ async function cmdCi(positional, flags) {
     const ICON = { ok: "🟢", deprecating: "🟡", retiring: "🟠", retired: "🔴", withdrawn: "⛔" };
     console.log(`LLM Status CI — scanned ${dir}  (fail-on: ${failOn})`);
     if (!findings.length) {
-      console.log("✓ No deprecated, retiring, or retired AI models found.");
+      console.log("✓ No deprecated, retiring, retired, or withdrawn 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}` : ""}`);
@@ -586,6 +704,7 @@ async function cmdClear(_positional, flags) {
  * rewritable (vercel:// etc. are skipped). */
 async function cmdFix(positional, flags) {
   const dir = path.resolve(positional[1] || flags.dir || ".");
+  requireDirectory(dir);
   const { getRegistry } = await import("./registry/fetch.js");
   const { resolveLocal, computeHealth } = await import("./registry/local.js");
   const { planFixes, applyFixes, terminalReplacement, recordFixes } = await import("./fix.js");
@@ -655,9 +774,79 @@ async function cmdFix(positional, flags) {
   console.log(`\n✓ rewrote ${res.applied.length} reference(s) in ${new Set(res.applied.map((p) => p.file)).size} file(s).`);
   for (const s of res.stale) console.log(`  ! skipped ${s.file}:${s.line} — ${s.error}`);
   for (const f of res.failed) console.log(`  × failed ${f.file}:${f.line} — ${f.error}`);
+  if (res.stale.some((s) => /pinned variant/.test(s.error || ""))) {
+    console.log("\n→ pinned ids need a human (or an agent): `mm prompt` prints a fix-it prompt for your AI coding agent.");
+  }
   if (res.applied.length) console.log("\nRe-run your tests, then `mm status` to confirm everything reads current.");
 }
 
+/** `mm prompt [dir]` — print a copy-paste prompt for an AI coding agent to fix
+ * dying model refs. Where `mm fix` mechanically rewrites what it can prove safe,
+ * the prompt hands EVERYTHING to an agent — including version-pinned ids, models
+ * with no registry replacement yet, and the config/parameter follow-ups a string
+ * swap can't do. stdout is the prompt and nothing else (pipe it: `mm prompt |
+ * pbcopy`); progress + the summary line go to stderr. */
+async function cmdPrompt(positional, flags) {
+  const dir = path.resolve(positional[1] || flags.dir || ".");
+  requireDirectory(dir);
+  const { getRegistry } = await import("./registry/fetch.js");
+  const { resolveLocal, computeHealth, dropResolvedFragments } = await import("./registry/local.js");
+  const { terminalReplacement } = await import("./fix.js");
+  const { buildFixPrompt } = await import("./fix-prompt.js");
+  const prog = startProgress(true, "fetching the model registry…");
+  const snapshot = await getRegistry({
+    offline: !!flags.offline || process.env.LLMSTATUS_REGISTRY_OFFLINE === "1",
+    cacheFile: process.env.LLMSTATUS_REGISTRY_CACHE || undefined,
+    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(["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]));
+  candidates = dropResolvedFragments(candidates, (c) => !!byStr.get(c.model_string.toLowerCase())?.model_slug);
+  const today = new Date();
+
+  // Group EVERY dying model's refs — unlike cmdFix, keep models with no
+  // replacement (the agent picks a successor) and pinned refs (it re-pins).
+  const byModel = new Map(); // slug -> { model, health, refs }
+  for (const c of candidates) {
+    const r = byStr.get(c.model_string.toLowerCase());
+    if (!r?.model_slug || !r.model) continue;
+    const health = computeHealth(r.model, 90, today);
+    if (health === "ok") continue;
+    if (flags.model && r.model_slug !== flags.model) continue;
+    const e = byModel.get(r.model_slug) || { model: r.model, health, refs: [] };
+    e.refs.push(c);
+    byModel.set(r.model_slug, e);
+  }
+
+  const bySlug = new Map(snapshot.models.map((m) => [m.slug, m]));
+  const isCurrent = (m) => computeHealth(m, 90, today) === "ok";
+  const findings = [...byModel.values()].map(({ model, health, refs }) => ({
+    slug: model.slug,
+    display: model.display,
+    health,
+    retires_date: model.retires_date,
+    replacement: model.replacement_slug
+      ? terminalReplacement(model.replacement_slug, (slug) => bySlug.get(slug) ?? null, isCurrent)
+      : null,
+    refs: refs.map((c) => ({ file: c.source_path || c.location_label, line: c.source_line, matched: c.model_string })),
+  }));
+
+  const text = buildFixPrompt(findings, { date: today });
+  if (!text) {
+    process.stderr.write("Nothing to fix — every recognized model here is current. No prompt to generate.\n");
+    return;
+  }
+  console.log(text);
+  const nRefs = findings.reduce((n, f) => n + f.refs.length, 0);
+  const copyTool = process.platform === "darwin" ? "pbcopy" : process.platform === "win32" ? "clip" : "xclip -selection clipboard";
+  process.stderr.write(`\n(${findings.length} model(s), ${nRefs} reference(s). Copy it straight to your clipboard: mm prompt | ${copyTool})\n`);
+}
+
 /** List detection sources and whether each can run right now. Live integrations
  * also show their on/off toggle (the `int` column) so toggled state is visible
  * here too. */
@@ -737,6 +926,15 @@ function cmdIntegrations(positional, flags) {
  * here, resolve + score health entirely on-device. The free tier's core value. */
 async function cmdStatus(positional, flags) {
   const dir = path.resolve(positional[1] || flags.dir || ".");
+  // Loud invocation errors BEFORE scanning: a missing path, a file argument, or
+  // a typo'd --sources id must never read as a clean "0 references" result.
+  requireDirectory(dir);
+  const sources = parseSources(flags);
+  assertKnownSources(sources);
+  const explicit = explicitSources(flags);
+  for (const a of await availability(sources, scanOpts(flags, dir), explicit)) {
+    if (!a.available) process.stderr.write(`! ${a.id} unavailable (tool, creds, or flags missing) — skipped\n`);
+  }
   const { getRegistry } = await import("./registry/fetch.js");
   const { resolveLocal, computeHealth, dropResolvedFragments } = await import("./registry/local.js");
   // A cold `mm status` downloads the ~225 kB registry snapshot then walks the
@@ -750,7 +948,7 @@ async function cmdStatus(positional, flags) {
 
   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);
+  let candidates = await collectFrom(sources, scanOpts(flags, dir), snapshot.detection, explicit, 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]));
@@ -845,6 +1043,7 @@ async function cmdStatus(positional, flags) {
     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`);
+    tips.push("`mm prompt` prints a fix-it prompt for your AI coding agent (Claude Code, Cursor, …)");
     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"));
   }
@@ -861,6 +1060,7 @@ Usage:
   mm config                View or change settings (analytics, …)
   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 prompt [dir]          Print a fix-it prompt for your AI coding agent — paste it into Claude Code, Cursor, … and let it do the rewrites (mm prompt | pbcopy)
   mm ci [dir]              CI gate: fail the build on deprecated/retiring models (GitHub annotations)
                           (--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)
@@ -914,6 +1114,19 @@ const COMMAND_HELP = {
   --yes             skip the confirmation prompt
   --model <slug>    only fix this one model (full provider/slug)
   --offline         use the cached registry only`,
+  prompt: `mm prompt [dir]   Print a copy-paste prompt for an AI coding agent to fix dying model refs.
+
+  Scans like \`mm status\`, then prints one self-contained prompt to stdout: every
+  retired/retiring model reference (file:line + the exact string in code), the
+  chain-resolved replacement, and the rewrite rules. Paste it into Claude Code,
+  Cursor, or any coding agent. Unlike \`mm fix\` (a mechanical in-place rewrite),
+  an agent can also re-pin dated ids, follow config indirection, and adjust
+  parameters the new model needs. stdout is ONLY the prompt — pipe it:
+  mm prompt | pbcopy
+
+  --model <slug>    only include this one model (full provider/slug)
+  --offline         use the cached registry only
+  --dir <path>      directory to scan (alternative to the positional arg)`,
   ci: `mm ci [dir]   CI gate: fail the build on deprecated/retiring models.
 
   Exits non-zero when a finding is at/above --fail-on. Emits GitHub annotations +
@@ -930,7 +1143,7 @@ const COMMAND_HELP = {
   On a TTY with no flags it opens the interactive Scan tab. --ci/--json/--yes run
   non-interactively.
 
-  --dry-run         show exactly what WOULD upload, upload nothing
+  --dry-run         show exactly what WOULD upload, upload nothing (fully local — no login needed)
   --json / --ci     machine output (--ci implies --yes + --json)
   --yes             upload without the interactive TUI
   --project <id|name>  route everything to one project (created if the name is new)
@@ -1028,8 +1241,14 @@ 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.
+  // telemetryCommand sends the vetted command WORD only — `mm ~/some/repo`
+  // reports "dir", a typo reports "unknown"; a path never leaves the machine.
   maybeFirstRun(); // one-time cli_first_run per install (same opt-out as below)
-  track("cli_command", { command: cmd || "tui" });
+  track("cli_command", {
+    command: telemetryCommand(cmd, (p) => {
+      try { return fs.statSync(p).isDirectory(); } catch { return false; }
+    }),
+  });
 
   // Explicit self-update: `mm update` (command) or `--update` (flag on any
   // command). Apply the update in place and RE-EXEC the fresh binary so this one
@@ -1083,6 +1302,7 @@ async function main() {
     }
     else if (cmd === "scan") await cmdScan(positional, flags);
     else if (cmd === "fix") await cmdFix(positional, flags);
+    else if (cmd === "prompt") await cmdPrompt(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);

package/src/integrations.js

@@ -51,13 +51,28 @@ export const INTEGRATION_META = {
 
 const ENV_TAGS = new Set(["prod", "staging", "dev", "unknown"]);
 
-/** Parsed integrations.json, or {} (missing/corrupt file → {}, like loadConfig). */
+/** Parsed integrations.json, or {} (missing file → {}, like loadConfig). A file
+ * that parses to a NON-OBJECT (e.g. the literal `null`, an array, a number) or
+ * doesn't parse at all also yields {} — every downstream reader does
+ * `cur[id]?.enabled`, so returning null once crashed EVERY command with an
+ * opaque TypeError. Invalid content warns ONCE per process, naming the file. */
+let warnedInvalidIntegrations = false;
 export function readIntegrations() {
+  const file = integrationsFilePath();
+  let raw;
   try {
-    return JSON.parse(fs.readFileSync(integrationsFilePath(), "utf8"));
+    raw = fs.readFileSync(file, "utf8");
   } catch {
-    return {};
+    return {}; // missing file is the normal first-run state — stay quiet
+  }
+  let parsed = null;
+  try { parsed = JSON.parse(raw); } catch { /* falls through to the warning */ }
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  if (!warnedInvalidIntegrations) {
+    warnedInvalidIntegrations = true;
+    process.stderr.write(`! ignoring invalid integrations file (${file}) — expected a JSON object. Fix or delete it; using defaults.\n`);
   }
+  return {};
 }
 
 /** Write the whole map. Owner-only (0600), mirroring config.js's saveConfig

package/src/registry/fetch.js

@@ -12,9 +12,24 @@ const DEFAULT_BASE = process.env.LLMSTATUS_REGISTRY_URL || "https://cdn.llmstatu
 const DEFAULT_CACHE = path.join(os.homedir(), ".config", "llmstatus", "registry-cache.json");
 const STALE_DAYS = 30;
 
+// Cap each snapshot fetch. Without it, a CDN edge that accepts the connection
+// but never responds holds every registry-touching command (status/fix/ci/TUI)
+// for undici's ~5-minute default before the cache fallback can kick in — a
+// timeout throws into getRegistry's existing catch, which falls back to the
+// cached copy with one stderr note. Overridable for tests / hostile networks.
+const fetchTimeoutMs = () => Number(process.env.MM_REGISTRY_TIMEOUT_MS) || 10_000;
+const isTimeout = (e) => e?.name === "TimeoutError" || e?.name === "AbortError" || e?.code === "ABORT_ERR" || e?.cause?.name === "TimeoutError";
+
 async function readUrl(u) {
   if (u.startsWith("file://")) return fs.readFileSync(fileURLToPath(u));
-  const res = await fetch(u, { redirect: "follow" });
+  const ms = fetchTimeoutMs();
+  let res;
+  try {
+    res = await fetch(u, { redirect: "follow", signal: AbortSignal.timeout(ms) });
+  } catch (e) {
+    if (isTimeout(e)) throw new Error(`GET ${u} timed out after ${Math.max(1, Math.round(ms / 1000))}s`);
+    throw e;
+  }
   if (!res.ok) throw new Error(`GET ${u} -> ${res.status}`);
   return Buffer.from(await res.arrayBuffer());
 }

package/src/sources/aws-lambda.js

@@ -1,4 +1,4 @@
-import { hasCmd, run } from "./shell.js";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { scanConfigEntries, entriesFromKV } from "./configscan.js";
 
 /* Pure parsers (unit-tested) — keep all JSON shape knowledge here, like aws.js.
@@ -63,14 +63,20 @@ export const awsLambdaSource = {
   async collect(opts, compiled) {
     const region = opts?.region ? ["--region", opts.region] : [];
     const tag = opts?.region || "default";
+    // Expired SSO / dead creds must be LOUD, never a silent "no functions".
+    const fail = makeCliFailureReporter("aws-lambda", "aws", opts);
     const out = [];
 
     // (a) Lambda functions → per-function env vars (Bedrock model ids show up here).
     const list = await run("aws", ["lambda", "list-functions", "--output", "json", ...region]);
+    if (!list.ok) fail(list);
     if (list.ok) {
       for (const fn of parseFunctionList(list.stdout)) {
         const cfg = await run("aws", ["lambda", "get-function-configuration", "--function-name", fn, "--output", "json", ...region]);
-        if (!cfg.ok) continue;
+        if (!cfg.ok) {
+          fail(cfg); // per-item failures collapse to one line per failure mode
+          continue;
+        }
         for (const [k, v] of Object.entries(parseFunctionEnv(cfg.stdout))) {
           const entries = entriesFromKV(k, v, `aws-lambda://${tag}/${fn}#${k}`, fn);
           out.push(...scanConfigEntries(entries, compiled, { sourceType: "aws-lambda", env: opts?.env }));
@@ -83,6 +89,7 @@ export const awsLambdaSource = {
     // on; opts.awsBedrock === false skips the extra call.
     if (opts?.awsBedrock !== false) {
       const bm = await run("aws", ["bedrock", "list-foundation-models", "--output", "json", ...region]);
+      if (!bm.ok) fail(bm);
       if (bm.ok) {
         for (const modelId of parseBedrockModels(bm.stdout)) {
           const entries = entriesFromKV("bedrock-model", modelId, `aws-bedrock://${tag}/foundation-models#${modelId}`, opts?.region);

package/src/sources/aws.js

@@ -1,4 +1,4 @@
-import { hasCmd, run } from "./shell.js";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { scanConfigEntries, entriesFromKV } from "./configscan.js";
 
 /* Pure parsers (unit-tested) — keep all JSON shape knowledge here. */
@@ -36,12 +36,17 @@ export const awsSecretsSource = {
   async collect(opts, compiled) {
     const region = opts?.region ? ["--region", opts.region] : [];
     const tag = opts?.region || "default";
+    // Expired SSO / missing creds / a timeout kill must be LOUD — a failed aws
+    // call reading as "no secrets" is a false-clean for a deprecation scanner.
+    const fail = makeCliFailureReporter("aws-secrets", "aws", opts);
     const out = [];
 
     const list = await run("aws", ["secretsmanager", "list-secrets", "--output", "json", ...region]);
+    if (!list.ok) fail(list);
     if (list.ok) {
       for (const name of parseSecretList(list.stdout)) {
         const v = await run("aws", ["secretsmanager", "get-secret-value", "--secret-id", name, "--output", "json", ...region]);
+        if (!v.ok) fail(v); // per-item failures collapse to one line per failure mode
         const val = v.ok ? parseSecretValue(v.stdout) : null;
         if (val == null) continue;
         const entries = entriesFromKV(name.split("/").pop(), val, `aws-secrets://${tag}/${name}`, name);
@@ -52,6 +57,7 @@ export const awsSecretsSource = {
     const ssm = await run("aws", [
       "ssm", "get-parameters-by-path", "--path", "/", "--recursive", "--with-decryption", "--output", "json", ...region,
     ]);
+    if (!ssm.ok) fail(ssm);
     if (ssm.ok) {
       for (const p of parseSsm(ssm.stdout)) {
         const entries = entriesFromKV(p.name.split("/").pop(), p.value, `aws-ssm://${tag}${p.name}`, p.name);