claudeup 6.7.1 → 6.8.0

package/src/services/mate-catalog.ts

@@ -0,0 +1,265 @@
+/**
+ * The LIVE external-model catalogue, read from claudish.
+ *
+ * A slot is bound to a bare catalogue id (`grok-4.6`). This module answers one question about
+ * such an id — is it still in the catalogue — and does nothing else with the answer.
+ *
+ * ## Why there is no table of model ids in this repo
+ *
+ * There was one once, elsewhere, and it went four months stale and silently resolved dead
+ * ids. A committed snapshot of a catalogue that turns over weekly is not a cache, it is a
+ * liability with a plausible face: it keeps answering after it stops being right. So the ids
+ * come from the catalogue at call time or they do not come at all.
+ *
+ * ## Why `claudish --models` and nothing else
+ *
+ * It is a READ-ONLY DIAGNOSTIC. The rule in this project is that work goes through claudish's
+ * MCP tools, never its CLI — with exactly three exceptions, `--help`, `--version` and
+ * `--models`, none of which may run a task. This module uses one of the three and runs no
+ * task: it prints a table and we read it. claudeup is a TUI with no MCP client in it, so the
+ * MCP route is not available here at all; if it were, this would still be the right call,
+ * because listing a catalogue IS the diagnostic those three exist for.
+ *
+ * ## The contract this module holds to
+ *
+ * FAILS SILENT, ALWAYS. claudish absent, a non-zero exit, unparseable output, a timeout —
+ * every one of them returns an empty catalogue, which reads downstream as "unknown". Never
+ * throws, never blocks, never empties the Model column because a lookup failed. The screen
+ * with no catalogue is the screen showing every bound id exactly as written, unannotated,
+ * which is what it showed before this module existed.
+ *
+ * ADVISORY ONLY. It marks a bound id the catalogue does not list. It never rebinds a slot,
+ * never substitutes a model, never fails a validation. This is deliberately the same contract
+ * as the image-model staleness check in the repo's CLAUDE.md, and for the same reason: a
+ * check that can act on a catalogue it may have failed to read can act on nothing.
+ *
+ * ## Shape
+ *
+ * Mirrors `mate-availability.ts`: a pure decision, plus an injected seam for the thing that
+ * touches the machine. The PARSING and the DECISIONS are what is worth testing — a format
+ * change, a truncated table, an empty result — and none of them can be tested through a
+ * function that shells out. The default runner is the real one, so no caller needs to know
+ * the seam is there.
+ *
+ * This is NOT in `models-core.ts`. That module is pure — no fs, no process, no network —
+ * because Claude Code runs the hook that imports it on every single Agent call.
+ */
+
+import { spawn } from "node:child_process";
+
+/** One row of `claudish --models`, as printed. */
+export interface CatalogModel {
+	/** The bare catalogue id — the only field a binding stores. */
+	id: string;
+	provider: string;
+	/** As printed: `$4.00/1M`, or `FREE`. Kept as text; nothing here does arithmetic on it. */
+	pricing: string;
+	/** As printed: `1M`, `500K`, `N/A`. */
+	context: string;
+	/** As printed: `TRV`, `TR`, `·`. */
+	caps: string;
+	/** ISO date, or "" when the table printed an em dash for an unknown release. */
+	released: string;
+}
+
+/** How the catalogue is fetched. A seam — see the header. */
+export type CatalogFetcher = () => Promise<string | null>;
+
+/** Milliseconds before a wedged claudish is abandoned. It is drawing three rows, not a page. */
+export const CATALOG_TIMEOUT_MS = 8000;
+
+/**
+ * A table row: rank, id, provider, pricing, context, caps, released.
+ *
+ * Every field claudish prints is whitespace-free — providers are slugs (`thinking-machines`),
+ * pricing has no spaces (`$4.00/1M`, `FREE`), caps is a letter run or `·`, and an unknown
+ * release date is a single em dash. So a row is EXACTLY seven tokens with a number first, and
+ * that is the whole rule.
+ *
+ * Requiring exactly seven is the defensive choice, not a brittle one. If claudish adds a
+ * column, every row stops matching, the catalogue comes back empty, and empty means
+ * "unknown" — which suppresses the advisory note and changes nothing else on screen. The
+ * alternative, accepting `>= 7` and taking the first seven, would keep matching while
+ * silently reading the wrong field into `id` and marking live models as retired.
+ */
+const ROW = /^\s*\d+\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*$/;
+
+/**
+ * Strip SGR sequences.
+ *
+ * MEASURED: `claudish --models | cat` emits none, so on the path this module actually takes
+ * (a pipe, never a TTY) there is nothing to strip. Kept anyway, because claudish is free to
+ * start colouring a piped table, and an ESC left in the string would ride into an `id` and
+ * make a live model look retired — the exact false positive this module must never produce.
+ *
+ * The ESC is written as an escape rather than as the raw byte it first was: a literal control
+ * character in source survives no reformat and no copy-paste, and losing it silently turns
+ * this into a function that strips square brackets out of model ids.
+ */
+function stripAnsi(text: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: an SGR sequence starts with ESC
+	return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+/**
+ * Parse the table `claudish --models` prints. Never throws.
+ *
+ * Non-row lines fall out on their own rather than needing a section parser: the header starts
+ * with `#`, the rule is one long dash run, the `Caps:` legend and the local-provider block
+ * have the wrong token count, and the footer lines start with words. A section-aware parser
+ * would have to be taught each of those and would break when one moved.
+ */
+export function parseModelsTable(text: string): CatalogModel[] {
+	const out: CatalogModel[] = [];
+	const seen = new Set<string>();
+	for (const line of stripAnsi(text).split("\n")) {
+		const m = ROW.exec(line);
+		if (!m) continue;
+		const [, id, provider, pricing, context, caps, released] = m;
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		out.push({
+			id,
+			provider: provider ?? "",
+			pricing: pricing ?? "",
+			context: context ?? "",
+			caps: caps ?? "",
+			// An em dash means claudish does not know the date. "" says that; carrying the
+			// dash through would put a glyph in a field every reader treats as a date.
+			released: released === "—" ? "" : (released ?? ""),
+		});
+	}
+	return out;
+}
+
+/**
+ * Run `claudish --models` and hand back its stdout, or null.
+ *
+ * Null for every failure mode there is: no claudish on PATH (`error`), a non-zero exit, or a
+ * process still running after the timeout. The caller cannot tell them apart and does not
+ * need to — all three mean the catalogue is unknown, and unknown has exactly one behaviour.
+ */
+const runClaudishModels: CatalogFetcher = () =>
+	new Promise((resolve) => {
+		let settled = false;
+		const done = (value: string | null) => {
+			if (settled) return;
+			settled = true;
+			resolve(value);
+		};
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn("claudish", ["--models"], {
+				stdio: ["ignore", "pipe", "ignore"],
+			});
+		} catch {
+			// `spawn` throws rather than emitting `error` for some argv/permission failures.
+			done(null);
+			return;
+		}
+		let out = "";
+		child.stdout?.on("data", (chunk) => {
+			out += String(chunk);
+		});
+		child.on("error", () => done(null));
+		child.on("close", (code) => done(code === 0 ? out : null));
+		// Never let a wedged claudish hold the TUI. `unref` so a pending timer cannot keep
+		// the CLI's process alive after it has printed everything it means to print.
+		setTimeout(() => {
+			child.kill();
+			done(null);
+		}, CATALOG_TIMEOUT_MS).unref?.();
+	});
+
+/**
+ * Session cache, including the empty result.
+ *
+ * Caching a FAILURE is deliberate. The catalogue cannot change while claudeup is open, and a
+ * machine with no claudish would otherwise pay the spawn — and its timeout — once per screen
+ * that asks. One failed lookup answers for the session, which is the same reasoning
+ * `content-drift.ts` uses for its own session cache.
+ */
+let cached: CatalogModel[] | null = null;
+let inFlight: Promise<CatalogModel[]> | null = null;
+
+/** Drop the cached catalogue. For tests, and for an explicit reload. */
+export function clearMateCatalogCache(): void {
+	cached = null;
+	inFlight = null;
+}
+
+/**
+ * The live catalogue, or [] when it could not be read.
+ *
+ * [] is not distinguished from "claudish returned nothing", by design: both mean the same
+ * thing to every caller, and a tri-state would invite someone to branch on it and then have
+ * to decide what an error should do — which is the decision this module exists to refuse.
+ *
+ * Concurrent callers share one in-flight promise. Both screens on this tab ask at mount, and
+ * two spawns of the same read-only diagnostic is pure waste.
+ */
+export async function loadMateCatalog(
+	fetch: CatalogFetcher = runClaudishModels,
+): Promise<CatalogModel[]> {
+	if (cached !== null) return cached;
+	if (inFlight) return inFlight;
+	inFlight = (async () => {
+		let models: CatalogModel[] = [];
+		try {
+			const text = await fetch();
+			if (text) models = parseModelsTable(text);
+		} catch {
+			// A thrown fetcher is a failed lookup like any other. Nothing above this line is
+			// allowed to see an exception from a catalogue read.
+			models = [];
+		}
+		cached = models;
+		inFlight = null;
+		return models;
+	})();
+	return inFlight;
+}
+
+/** Every id the catalogue lists. The shape the staleness check and the UI actually want. */
+export function catalogIds(models: CatalogModel[]): Set<string> {
+	return new Set(models.map((model) => model.id));
+}
+
+/**
+ * Which of these bound ids the catalogue does not list.
+ *
+ * RETURNS NOTHING WHEN THE CATALOGUE IS EMPTY. That is the whole contract in one line: an
+ * unread catalogue lists nothing, so a naive "not in the set" test would mark every binding
+ * on the machine as retired the moment claudish was missing — an advisory that fires hardest
+ * exactly when it knows least. Same rule as the image-model staleness check: return nothing
+ * when you cannot reach the catalogue.
+ *
+ * Exact match only. A near-match would be the failure this is meant to catch, wearing a
+ * helpful face: `grok-4.5` is not a stand-in for a retired `grok-4.6`.
+ */
+export function unknownBindings(
+	ids: Iterable<string>,
+	catalog: CatalogModel[],
+): string[] {
+	if (catalog.length === 0) return [];
+	const known = catalogIds(catalog);
+	const out: string[] = [];
+	for (const id of ids) {
+		if (!known.has(id) && !out.includes(id)) out.push(id);
+	}
+	return out;
+}
+
+/**
+ * The advisory sentence, or null when there is nothing to say.
+ *
+ * Worded as an observation, never as an instruction: claudeup has not checked whether the
+ * model was renamed, retired, or simply sits outside the top 100 rows this diagnostic prints
+ * — and `--models` is a TOP-N view, so absence is genuinely weaker evidence than it looks.
+ * "may no longer exist" is the strongest claim the evidence supports.
+ */
+export function stalenessNote(unknown: string[]): string | null {
+	if (unknown.length === 0) return null;
+	const list = unknown.join(", ");
+	return `${list} ${unknown.length === 1 ? "is" : "are"} not in claudish's live catalogue — the id may have changed, or it may sit outside the models it lists. Check with \`claudish --models\`.`;
+}