Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Launcher catalog warm step.
*
* Owns the decision tree that runs once at CLI startup, before the proxy
* server boots:
*
* 1. Decide whether the catalog needs warming at all (`shouldWarmCatalog`).
* 2. Classify the on-disk cache state (`classifyCatalogState`).
* 3. Drive the FR-4 hybrid-fallback state machine (`warmCatalogIfNeeded`).
*
* Architecture: ai-docs/sessions/dev-feature-catalog-warm-hardcoded-cleanup-XXX/architecture.md sections 2-5
*
* The launcher gate is "belt + suspenders" alongside the proxy-server's
* background warm at `proxy-server.ts:535` (see Appendix B). The bg warm
* is harmless if the launcher already populated the cache.
*/
import { type DiskCacheV3, readAllModelsCache } from "../providers/all-models-cache.js";
import { type RefreshOutcome, refreshCatalog } from "../providers/catalog-client.js";
import type { ClaudishConfig } from "../types.js";
import { VERSION } from "../version.js";
/**
* Result returned by `warmCatalogIfNeeded`. The launcher reacts to this:
* - "ok" → proceed to createProxyServer
* - "warned" → proceed (warning already printed to stderr)
* - "skipped" → proceed silently (local model or --models-skip-update)
* - "hard_fail" → exit 1 (error already printed to stderr)
*/
export type WarmOutcome = "ok" | "warned" | "skipped" | "hard_fail";
/**
* Verbatim hard-fail copy from FR-4. Printed when the catalog is missing AND
* the network refresh failed — claudish cannot route cloud models without it.
*
* "No cached copy found" is a claim about the disk, so this must never be the
* message for a contract mismatch: there a copy exists and is merely unreadable,
* the network is fine, and every line below sends the user to debug the wrong
* thing. `warmCatalogIfNeeded` checks the sentinel before it can reach here for
* exactly that reason — see the guard above `reportFetchFailure`.
*
* Trailing newline included so the message reads as one paragraph terminated
* cleanly when written to stderr.
*/
const HARD_FAIL_MESSAGE =
"Error: cannot reach model catalog and no cached copy found.\n" +
"\n" +
"To proceed:\n" +
" - Check network connection\n" +
" - Use a local model: claudish --model [email protected] 'task'\n" +
" - Skip catalog (advanced): claudish --models-skip-update 'task'\n" +
"\n" +
"Claudish will not launch without catalog data when using cloud models.\n";
/**
* Local-only model prefixes. When the user asks for one of these, the launcher
* skips the catalog warm entirely (NFR-2): Ollama, LM Studio, and explicit
* localhost URLs talk to in-process daemons that don't need the slim catalog.
*
* All comparisons are lower-case (the model spec is `toLowerCase()`'d before
* the loop). The `http(s)://localhost` and `http(s)://127.0.0.1` prefixes are
* deliberately limited to those two host literals — `ws://`, IPv6 `[::1]`,
* and arbitrary local LAN IPs are not supported claudish model specs.
*/
const LOCAL_MODEL_PREFIXES = [
"ollama@",
"lmstudio@",
"http://localhost",
"http://127.0.0.1",
"https://localhost",
"https://127.0.0.1",
] as const;
/**
* Pure trigger function. No I/O, no side effects.
*
* Returns `false` (skip warm) when:
* - The user passed `--models-skip-update` (hard skip, regardless of model).
* - The user passed a local-only model prefix (case-insensitive).
*
* Returns `true` (warm) when:
* - No model is specified (auto-route path needs the catalog to pick).
* - The model is an aggregator/native prefix (`or@`, `g@`, ...) or bare ID.
*
* New aggregator/native prefixes added in the future automatically warm —
* the default branch is the safer one.
*/
export function shouldWarmCatalog(args: {
model?: string;
skipModelsUpdate?: boolean;
}): boolean {
if (args.skipModelsUpdate) return false;
if (args.model === undefined) return true;
const m = args.model.toLowerCase();
for (const prefix of LOCAL_MODEL_PREFIXES) {
if (m.startsWith(prefix)) return false;
}
return true;
}
/**
* Pure classifier. No I/O — caller passes the cache and `now` explicitly so
* tests can drive the time axis deterministically.
*
* "missing" semantics cover three on-disk failure modes:
* 1. The file doesn't exist (or readAllModelsCache returned null because
* the JSON was unparseable — both bubble up here as null).
* 2. The file is parseable but contains zero entries AND zero models
* (defense against an empty-but-valid blob).
* 3. `lastUpdated` is malformed (Date.parse → NaN) so we can't compute age.
*
* Otherwise, freshness is `ageMs < ttlMs` (strict <). At exactly the TTL
* boundary we report "stale" — a refresh is preferable to letting cache age
* silently drift past the policy.
*/
export function classifyCatalogState(
cache: DiskCacheV3 | null,
ttlHours: number,
now: Date
): "fresh" | "stale" | "missing" {
if (cache === null) return "missing";
if (cache.entries.length === 0 && cache.models.length === 0) return "missing";
const lastUpdatedMs = Date.parse(cache.lastUpdated);
if (Number.isNaN(lastUpdatedMs)) return "missing";
const ageMs = now.getTime() - lastUpdatedMs;
const ttlMs = ttlHours * 3_600_000;
return ageMs < ttlMs ? "fresh" : "stale";
}
/**
* Format an age in milliseconds as a coarse human string ("5 minutes",
* "3 hours", "2 days"). Bucketed at 60-minute and 24-hour boundaries.
*
* F11 mitigation: the minute-bucket uses `Math.max(1, ...)` so very young
* ages (e.g. 12s after a clock skew) never render as "0 minutes".
*
* Pluralization: when the bucket value is exactly 1 we render the singular
* ("1 minute" / "1 hour" / "1 day") so the WARNING line reads naturally at
* the boundary.
*/
function humanizeAge(ageMs: number): string {
const minutes = Math.max(1, Math.floor(ageMs / 60_000));
if (minutes < 60) return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
const hours = Math.floor(ageMs / 3_600_000);
if (hours < 24) return `${hours} ${hours === 1 ? "hour" : "hours"}`;
const days = Math.floor(ageMs / 86_400_000);
return `${days} ${days === 1 ? "day" : "days"}`;
}
/**
* Minimal stderr spinner. Animates only when `process.stderr.isTTY` is true
* (R6 in architecture.md — non-TTY contexts get one initial line, no `\r`
* frames). Update interval capped at 250ms per FR-2.
*
* `quiet` short-circuits to a no-op stopper so the spinner respects the
* documented `--quiet` semantic (Q2 in architecture.md §10) — no stderr
* frames are emitted at all in quiet mode.
*
* Returns a `stop()` to clear the active frame and silence further updates.
*/
interface Spinner {
stop(): void;
}
function startSpinner(label: string, quiet = false): Spinner {
if (quiet) {
// --quiet suppresses spinner frames entirely. The dispatcher already
// skips the "preparing..." header in quiet mode; the spinner is the
// last source of stderr noise during a successful refresh.
return { stop: () => {} };
}
const isTty = Boolean(process.stderr.isTTY);
if (!isTty) {
// Non-TTY: print one line and return a no-op stopper. The caller has
// already printed the "preparing model catalog..." header line above us;
// we only want to add an extra line if we have something distinct to say.
return { stop: () => {} };
}
const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
let i = 0;
let stopped = false;
const render = (): void => {
if (stopped) return;
process.stderr.write(`\r ${frames[i]} ${label}`);
i = (i + 1) % frames.length;
};
render();
const handle = setInterval(render, 250);
return {
stop(): void {
if (stopped) return;
stopped = true;
clearInterval(handle);
// Erase the spinner line: write CR + spaces wide enough to cover the
// longest frame + label, then CR back to column 0.
const wipe = " ".repeat(Math.max(0, label.length + 6));
process.stderr.write(`\r${wipe}\r`);
},
};
}
/**
* Launcher catalog warm dispatcher.
*
* Drives the FR-4 state machine end-to-end:
*
* 1. Trigger gate — if local model or `--models-skip-update`, return "skipped".
* 2. Print the "preparing model catalog..." header (suppressed by `--quiet`).
* 3. Classify on-disk cache state.
* 4. Decide:
* - fresh && !forceUpdate → "ok" without fetching (lazy disk load happens
* later via _getEntries when the proxy first calls resolveSync).
* - else (stale, missing, or forceUpdate=true on fresh) → call
* `OpenRouterCatalogResolver.refreshCatalog(8000)`:
* - refreshed → print indexed-count line, return "ok".
* - incompatible → contract-mismatch message + return "warned".
* - fetch_failed:
* - a sentinel is already recorded → contract-mismatch message +
* return "warned" (the cache state is not what it looks like;
* see the guard at the call to `reportFetchFailure`).
* - prior state was "stale" → WARN + return "warned".
* - prior state was "missing" → hard-fail message + return "hard_fail".
* - prior state was "fresh" → treat as "warned" (we still have
* the fresh cache; the user explicitly asked to refresh it).
*
* Only ONE branch here ever returns "hard_fail", and it means one thing: there
* is no catalog data on this machine at all and none can be fetched. An
* unreadable catalog is a different failure with a different remedy, and it
* never exits — routing decides that one per model name, where the explicit
* `provider@model` carve-out lives.
*
* `--quiet` suppresses the preparing/indexed lines but never WARNINGs or
* the hard-fail error (Q2 in architecture.md §10).
*/
export async function warmCatalogIfNeeded(
config: ClaudishConfig,
opts?: { now?: Date; ttlHours?: number }
): Promise<WarmOutcome> {
if (
!shouldWarmCatalog({
model: config.model,
skipModelsUpdate: config.skipModelsUpdate,
})
) {
return "skipped";
}
if (!config.quiet) {
process.stderr.write(`claudish v${VERSION} — preparing model catalog...\n`);
}
const ttlHoursRaw =
opts?.ttlHours ?? Number.parseFloat(process.env.CLAUDISH_CATALOG_TTL_HOURS ?? "24");
const ttlHours = Number.isFinite(ttlHoursRaw) && ttlHoursRaw > 0 ? ttlHoursRaw : 24;
const now = opts?.now ?? new Date();
const cache = readAllModelsCache();
const state = classifyCatalogState(cache, ttlHours, now);
// Fresh && !forceUpdate: don't fetch. _memCache lazy-loads on first
// resolveSync call via _getEntries (see openrouter.ts). Do NOT call
// ensureReady(0) here — timeout=0 races against fetch start before the
// disk-backed entries populate.
if (state === "fresh" && !config.forceUpdate) {
return "ok";
}
const spinner = startSpinner("Fetching model catalog from Firebase...", config.quiet);
let outcome: RefreshOutcome;
try {
outcome = await refreshCatalog(8000);
} finally {
spinner.stop();
}
if (outcome.kind === "refreshed") {
if (!config.quiet) {
process.stderr.write(
` Indexed ${outcome.modelCount} models, ${outcome.modelCount} entries.\n`
);
}
return "ok";
}
return reportUnusableCatalog(outcome, state, cache, now, config.quiet === true);
}
/**
* The refresh came back with no usable catalog. Decide which failure it was.
*
* Extracted from `warmCatalogIfNeeded` purely to hold that function at its
* pre-existing complexity budget; the branch ORDER is the argument, and it is
* "unreadable before unreachable" throughout — an unreadable catalog is the
* finding that survives on disk, so it outranks whatever this one refresh did or
* did not manage to fetch.
*/
function reportUnusableCatalog(
outcome: Exclude<RefreshOutcome, { kind: "refreshed" }>,
state: ReturnType<typeof classifyCatalogState>,
cache: DiskCacheV3 | null,
now: Date,
quiet: boolean
): WarmOutcome {
if (outcome.kind === "incompatible") {
process.stderr.write(
`Model catalog contract v${outcome.serverContractVersion ?? "unknown"} is not supported by this build.\n`
);
return cache === null ? "hard_fail" : "warned";
}
// `disabled` is not a failure and must never reach the branches below. Nobody
// attempted a fetch, so the cache state is irrelevant: with no cache at all
// the `missing` branch would print HARD_FAIL_MESSAGE — "cannot reach model
// catalog… Check network connection" — and `index.ts` turns `hard_fail` into
// `process.exit(1)`. That sends a reader to debug a working connection over a
// condition their own harness created, which is the entire reason this reason
// exists as a distinct value rather than reusing `network`.
//
// It reaches here through `CLAUDISH_DISABLE_CATALOG_WARM=1`, which
// `scripts/guard-real-config.ts` sets on the whole test run — and the e2e
// suites spawn `src/index.ts` as a child, which inherits it. So on a machine
// with no `~/.claudish/cloud-models-catalog-v3.json`, the untreated path fails those tests
// with a network diagnosis.
//
// "skipped" is the accurate answer, and it is the same one
// `--models-skip-update` already produces: a refresh nobody attempted.
if (outcome.reason === "disabled") {
if (!quiet) {
process.stderr.write(" Catalog refresh disabled (CLAUDISH_DISABLE_CATALOG_WARM=1).\n");
}
return "skipped";
}
return reportFetchFailure(state, cache, now);
}
function reportFetchFailure(
state: ReturnType<typeof classifyCatalogState>,
cache: DiskCacheV3 | null,
now: Date
): WarmOutcome {
if (state === "stale") {
const ageMs = now.getTime() - Date.parse(cache!.lastUpdated);
const ageStr = humanizeAge(ageMs);
process.stderr.write(
`WARNING: Catalog stale (${ageStr}). Using cached version. Run \`claudish --models-refresh\` to retry.\n`
);
return "warned";
}
if (state === "fresh") {
// forceUpdate path: refresh requested but failed. The fresh cache is
// still usable — warn but proceed. Use the same human-readable copy as
// the stale branch so the user sees a single, consistent error format.
const ageMs = now.getTime() - Date.parse(cache!.lastUpdated);
const ageStr = humanizeAge(ageMs);
process.stderr.write(
`WARNING: Catalog refresh failed (cache age ${ageStr}). Using cached version.\n`
);
return "warned";
}
// state === "missing" + fetch failed → hard fail.
process.stderr.write(HARD_FAIL_MESSAGE);
return "hard_fail";
}