catherd-cli 0.2.1 → 1.0.0

package/src/domain/route.ts

@@ -0,0 +1,126 @@
+import type { Difficulty, Kind } from "./lane.ts";
+import type { Role } from "./roles.ts";
+
+export const CLIMB_REASONS = [
+  "check-failed-twice",
+  "blocker",
+  "same-defect",
+  "refused",
+  "blocked",
+  "unchanged",
+] as const;
+export type ClimbReason = (typeof CLIMB_REASONS)[number];
+
+/**
+ * Spec §5.4: where a lane's kind and difficulty came from. `jev-kind`: Jev was sure of the kind only, and the
+ * difficulty came from the lane's `Difficulty:` line, else from the role's default rung.
+ */
+export type RouteSource = "jev" | "jev-kind" | "lane" | "default";
+
+/** What Jev said about a lane, kept with its route for outcomes.jsonl (spec §5.6). */
+export interface RouteJev {
+  pKind: number | null;
+  pA: number | null;
+  pB: number | null;
+  nouls: Record<string, number>;
+}
+
+/** One row of routes.jsonl: a lane's route, or one climb of it. The last row of a lane is its current route. */
+export interface RouteRow {
+  at: string;
+  lane: string;
+  role: Role;
+  rung: string;
+  ladder: string[];
+  source: "route" | "climb";
+  decidedBy: RouteSource;
+  from: string | null;
+  reason: string | null;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+  /** route rows: the Jev question set asked (null when Jev was not asked) and its probabilities */
+  questionSet?: string | null;
+  jev?: RouteJev | null;
+  /** climb rows: the climb was caused by the environment, not the rung's capability (spec §5.6) */
+  env?: boolean;
+}
+
+export function nextRung(ladder: string[], current: string): string | null {
+  const i = ladder.indexOf(current);
+  return i >= 0 && i < ladder.length - 1 ? (ladder[i + 1] as string) : null;
+}
+
+export const currentRoute = (rows: RouteRow[], lane: string): RouteRow | null =>
+  rows.findLast((r) => r.lane === lane) ?? null;
+
+/**
+ * The lane's route in force at `at`: its last row stamped at or before that time; null when the lane
+ * had no row by then (or `at` is not a time). Rows without a parseable `at` are skipped.
+ */
+export function routeAt(rows: RouteRow[], lane: string, at: string): RouteRow | null {
+  const t = Date.parse(at);
+  if (Number.isNaN(t)) return null;
+  return rows.findLast((r) => r.lane === lane && Date.parse(r.at) <= t) ?? null;
+}
+
+/**
+ * One outcomes.jsonl row (spec §5.6): how a routed lane ended, for calibrating Jev's route rule.
+ * A lane can get several rows (a top-rung failure later landed, a milestone landed again):
+ * the last row per lane wins; read them through `latestOutcomes`.
+ */
+export interface OutcomeRow {
+  at: string;
+  lane: string;
+  questionSet: string | null;
+  jevProbs: RouteJev | null;
+  source: RouteSource;
+  startRung: string;
+  finalRung: string;
+  climbs: { from: string; to: string; reason: string; env: boolean }[];
+  /** true when the lane landed, false when it ended open (a climb past its top rung) */
+  landed: boolean;
+  /** landed with no climb the rung itself caused */
+  start_ok: boolean;
+  /** the ladder index it landed on; null when it ended open (censored) */
+  min_ok_index: number | null;
+  /** some climb was the environment's fault: calibration leaves this lane out */
+  envCaused: boolean;
+}
+
+/** The lane's outcome from its routes.jsonl rows since its last route; null when it was never routed. */
+export function laneOutcome(rows: RouteRow[], lane: string, landed: boolean, at: string): OutcomeRow | null {
+  const mine = rows.filter((r) => r.lane === lane);
+  const i = mine.findLastIndex((r) => r.source === "route");
+  const start = mine[i];
+  if (!start) return null;
+  // every climb row counts for start_ok and envCaused, including a no-op past the top rung (from === rung),
+  // which only drops out of the listed climbs
+  const allClimbs = mine
+    .slice(i + 1)
+    .filter((r) => r.source === "climb" && r.from !== null)
+    .map((r) => ({ from: r.from as string, to: r.rung, reason: r.reason ?? "", env: r.env === true }));
+  const climbs = allClimbs.filter((c) => c.from !== c.to);
+  const finalRung = mine.at(-1)?.rung ?? start.rung;
+  const idx = start.ladder.indexOf(finalRung);
+  return {
+    at,
+    lane,
+    questionSet: start.questionSet ?? null,
+    jevProbs: start.jev ?? null,
+    source: start.decidedBy,
+    startRung: start.rung,
+    finalRung,
+    climbs,
+    landed,
+    start_ok: landed && allClimbs.every((c) => c.env),
+    min_ok_index: landed && idx >= 0 ? idx : null,
+    envCaused: allClimbs.some((c) => c.env),
+  };
+}
+
+/** Spec §5.6: one row per lane, the last one written (last row per lane wins), in first-seen lane order. */
+export function latestOutcomes(rows: OutcomeRow[]): OutcomeRow[] {
+  const byLane = new Map<string, OutcomeRow>();
+  for (const r of rows) byLane.set(r.lane, r);
+  return [...byLane.values()];
+}

package/src/domain/runtime.ts

@@ -0,0 +1,21 @@
+/** Spec §3.1 and D6: catherd runs on Bun 1.4.0 or newer. */
+export const MIN_BUN = "1.4.0";
+
+const parts = (v: string) => (/^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1) ?? ["0", "0", "0"]).map(Number);
+
+export function bunTooOld(version: string): boolean {
+  const a = parts(version);
+  const b = parts(MIN_BUN);
+  for (let i = 0; i < 3; i++)
+    if ((a[i] as number) !== (b[i] as number)) return (a[i] as number) < (b[i] as number);
+  return false;
+}
+
+/** The two lines to print, and exit 1 on, when this Bun is too old; null when it is new enough. */
+export function runtimeRefusal(version: string | undefined): string[] | null {
+  if (version !== undefined && !bunTooOld(version)) return null;
+  return [
+    `error E_RUNTIME_TOO_OLD: catherd needs Bun ${MIN_BUN} or newer; this is ${version ? `Bun ${version}` : "not Bun"}`,
+    "fix: bun upgrade (or install Bun: curl -fsSL https://bun.sh/install | bash)",
+  ];
+}

package/src/domain/sanitize.ts

@@ -0,0 +1,29 @@
+import { replaceSecrets, scrubKeyShapes } from "./secrets.ts";
+
+/** What to strip from a captured stream: exact secret values, and paths to replace with a stable name. */
+export interface Scrub {
+  secrets: string[];
+  paths: { from: string; to: string }[];
+}
+
+const EMAIL = /[\w.%+-]+@[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}/g;
+
+const longestFirst = <T>(xs: T[], len: (x: T) => number) => [...xs].sort((a, b) => len(b) - len(a));
+
+/**
+ * Spec §11.8: a capture keeps no secret and no home path. Secrets (8+ chars) and key-shaped strings
+ * (domain/secrets.ts) become `<redacted>`, emails `<email>`, and each path its stable name, longest
+ * path first so a repo inside the home directory reads `<repo>`, not `~/…`.
+ */
+export function sanitize(text: string, s: Scrub): string {
+  // a captured stream is JSONL: a secret with a quote, a backslash or a control character is escaped there
+  const forms = s.secrets.flatMap((x) => [x, JSON.stringify(x).slice(1, -1)]);
+  let out = scrubKeyShapes(replaceSecrets(text, forms, "<redacted>"), "<redacted>");
+  out = out.replace(EMAIL, "<email>");
+  for (const p of longestFirst(
+    s.paths.filter((x) => x.from.length > 1),
+    (x) => x.from.length,
+  ))
+    out = out.split(p.from).join(p.to);
+  return out;
+}

package/src/domain/secrets.ts

@@ -0,0 +1,57 @@
+// Spec §10.4 and §11.8: the one rule for what is a secret. The log redactor (infra/log.ts), fixture
+// capture (domain/sanitize.ts) and Jev's lane state (domain/jev.ts) all scrub with it; each picks its mark.
+
+/** Env names whose values are credentials: the word may sit anywhere (OPENAI_API_KEY_2, GH_TOKEN_FILE). */
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i;
+/** A literal secret shorter than this is never scrubbed: it would blank ordinary words. */
+export const MIN_SECRET = 8;
+
+export const isSecretName = (name: string): boolean => SECRET_NAME.test(name);
+
+const longestFirst = (xs: string[]): string[] => [...new Set(xs)].sort((a, b) => b.length - a.length);
+
+/** The values of env vars whose names say they hold a credential: 8+ characters, once each, longest first. */
+export function secretEnvValues(env: Record<string, string | undefined>): string[] {
+  return longestFirst(
+    Object.entries(env)
+      .filter(([k, v]) => v !== undefined && v.length >= MIN_SECRET && isSecretName(k))
+      .map(([, v]) => v as string),
+  );
+}
+
+/** `text` with each literal secret of 8+ characters replaced by `mark`, the longest first. */
+export function replaceSecrets(text: string, secrets: string[], mark: string): string {
+  let out = text;
+  for (const s of longestFirst(secrets.filter((x) => x.length >= MIN_SECRET))) out = out.split(s).join(mark);
+  return out;
+}
+
+/** Strings shaped like a key wherever they appear, and the part kept before the mark ("Bearer ", a URL's user). */
+const KEY_SHAPES: [RegExp, string][] = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, ""],
+  [/sk-ant-[\w-]{10,}/g, ""],
+  [/\bsk-[\w-]{16,}/g, ""],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, ""],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, ""],
+  [/\bAKIA[0-9A-Z]{16}\b/g, ""],
+  [/\bxox[abpr]-[A-Za-z0-9-]{10,}/g, ""],
+  [/\b(Bearer\s+)[\w.~+/=-]{10,}/gi, "$1"],
+  [/(\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+(?=@)/g, "$1"],
+];
+
+/** `text` with every key-shaped string replaced by `mark` (which must not contain `$`). */
+export function scrubKeyShapes(text: string, mark: string): string {
+  let out = text;
+  for (const [re, keep] of KEY_SHAPES) out = out.replace(re, `${keep}${mark}`);
+  return out;
+}
+
+/**
+ * `api_key = value` and the like, keeping the name. Jev's state only: on a captured stream or a log row
+ * it would also blank counts such as `max_tokens: 100000`.
+ */
+const ASSIGNMENT =
+  /\b([A-Za-z0-9_]*(?:api[_-]?key|token|secret|password)[A-Za-z0-9_]*)\s*[:=]\s*["']?[^\s"']{6,}/gi;
+
+export const scrubSecretAssignments = (text: string, mark: string): string =>
+  text.replace(ASSIGNMENT, `$1=${mark}`);

package/src/domain/select.ts

@@ -0,0 +1,136 @@
+import {
+  type Catalog,
+  capableFor,
+  type Dim,
+  effortOffered,
+  type RungInfo,
+  rungInfo,
+  scoresOf,
+} from "./catalog.ts";
+import { type BillingMode, type Cost, compareCost, costOf, DEFAULT_BILLING } from "./cost.ts";
+import { CatherdError } from "./errors.ts";
+import { DIFFICULTIES, type Difficulty, type Kind } from "./lane.ts";
+import type { Role } from "./roles.ts";
+
+/** What routing reads from a profile for one role. */
+export interface RoutingProfile {
+  objective: "cost" | "speed";
+  billing: Partial<Record<string, BillingMode>>;
+  role: { enabled: boolean; rungs: string[]; defaultRung?: string };
+}
+
+export interface Candidate {
+  rung: string;
+  info: RungInfo;
+  scores: Partial<Record<Dim, number>>;
+  cost: Cost;
+  /** median seconds over the user's own runs (≥ 5 samples), else null */
+  secs: number | null;
+}
+
+export interface Pick {
+  rung: string;
+  ladder: string[];
+}
+
+const byNull = (a: number | null, b: number | null) =>
+  a === null || b === null ? (a === null ? 1 : 0) - (b === null ? 1 : 0) : a - b;
+
+function secsOf(c: Catalog, canonical: string, kind: Kind | null): number | null {
+  return c.secs[`${canonical}|${kind ?? "*"}`] ?? c.secs[`${canonical}|*`] ?? null;
+}
+
+/**
+ * The role's enabled rungs that the catalog can place: parseable, offered by their model, listed by
+ * the backend when it has a listing, capable for the role, and scored (their own or a treat-like).
+ * Ordered by cost (spec §5.3), or by measured speed with cost breaking ties; with fewer than 5
+ * samples a rung has no speed, and cost orders it, which within a model is effort order.
+ */
+export function candidates(c: Catalog, p: RoutingProfile, role: Role, kind: Kind | null = null): Candidate[] {
+  if (!p.role.enabled) return [];
+  const out: Candidate[] = [];
+  for (const rung of new Set(p.role.rungs)) {
+    let info: RungInfo;
+    try {
+      info = rungInfo(c, rung);
+    } catch {
+      continue;
+    }
+    if (!effortOffered(info) || info.listed === false || !capableFor(c, info, role)) continue;
+    const s = scoresOf(c, info.canonical);
+    if (!s) continue;
+    const mode = p.billing[info.key] ?? DEFAULT_BILLING[info.key];
+    out.push({
+      rung,
+      info,
+      scores: s.values,
+      cost: costOf(info.family, info.parsed.effort, mode),
+      secs: secsOf(c, info.canonical, kind),
+    });
+  }
+  const cost = (a: Candidate, b: Candidate) => compareCost(a.cost, b.cost) || byNull(a.secs, b.secs);
+  const speed = (a: Candidate, b: Candidate) => byNull(a.secs, b.secs) || compareCost(a.cost, b.cost);
+  return out.sort(p.objective === "speed" ? speed : cost);
+}
+
+export function clearsBar(c: Catalog, cand: Candidate, kind: Kind, difficulty: Difficulty): boolean {
+  return Object.entries(c.bars[kind][difficulty]).every(
+    ([dim, min]) => min === undefined || (cand.scores[dim as Dim] ?? Number.NEGATIVE_INFINITY) >= min,
+  );
+}
+
+function noRung(role: Role): CatherdError {
+  return new CatherdError("E_CONFIG_INVALID", `role "${role}" has no enabled, capable, scored rung`, {
+    fix: "run profile_validate, then enable a scored rung or map one with catherd catalog treat-like",
+  });
+}
+
+/**
+ * The role's default rung and every candidate above it (the whole list when it has no default), in cost
+ * order under either objective: speed order would put slower, not stronger, rungs above the default.
+ */
+export function defaultLadder(c: Catalog, p: RoutingProfile, role: Role): Pick {
+  const all = candidates(c, { ...p, objective: "cost" }, role).map((x) => x.rung);
+  if (all.length === 0) throw noRung(role);
+  const i = Math.max(0, all.indexOf(p.role.defaultRung ?? ""));
+  return { rung: all[i] as string, ladder: all.slice(i) };
+}
+
+/**
+ * The role's default difficulty for a kind: the hardest difficulty whose bar the role's default rung clears
+ * (`build` when it clears none, or is no candidate: never `copy`, whose start is the cheapest rung, below
+ * what the `default` source would pick). A route sure of the kind but not the difficulty starts there.
+ */
+export function defaultDifficulty(c: Catalog, p: RoutingProfile, role: Role, kind: Kind): Difficulty {
+  const start = defaultLadder(c, p, role).rung;
+  const cand = candidates(c, p, role, kind).find((x) => x.rung === start);
+  const cleared = cand ? DIFFICULTIES.filter((d) => clearsBar(c, cand, kind, d)) : [];
+  return cleared.at(-1) ?? "build";
+}
+
+/**
+ * Under `objective: "speed"` the objective picks only the start (the fastest bar-clearing rung); the
+ * ladder above it is the other bar-clearing rungs at least as strong on the kind's primary dimension,
+ * weakest first, cost breaking ties, so a lane never climbs onto a weaker rung. Ported from 0.x.
+ */
+function speedLadder(clearing: Candidate[], kind: Kind): Pick {
+  const start = clearing[0] as Candidate;
+  const dim: Dim = kind === "terminal" ? "terminal" : "repo_code";
+  const strength = (x: Candidate) => x.scores[dim] ?? Number.NEGATIVE_INFINITY;
+  const rest = clearing
+    .filter((x) => x !== start && strength(x) >= strength(start))
+    .sort((a, b) => strength(a) - strength(b) || compareCost(a.cost, b.cost));
+  return { rung: start.rung, ladder: [start, ...rest].map((x) => x.rung) };
+}
+
+/** Spec §5.4: the start rung and ladder for a lane of this kind and difficulty (0.x `select`). */
+export function select(c: Catalog, p: RoutingProfile, role: Role, kind: Kind, difficulty: Difficulty): Pick {
+  const all = candidates(c, p, role, kind);
+  if (all.length === 0) throw noRung(role);
+  if (all.length === 1) return { rung: all[0]?.rung as string, ladder: [all[0]?.rung as string] };
+  const clearing = all.filter((x) => clearsBar(c, x, kind, difficulty));
+  if (clearing.length === 0) return defaultLadder(c, p, role);
+  return p.objective === "speed"
+    ? speedLadder(clearing, kind)
+    : { rung: clearing[0]?.rung as string, ladder: clearing.map((x) => x.rung) };
+}

package/src/domain/state.ts

@@ -0,0 +1,33 @@
+export interface StateView {
+  title: string;
+  head: string;
+  dirty: { path: string; owner: string | null }[];
+  running: { name: string; rung: string; thread: string | null; since: string; brief: string }[];
+  lastCheck: string | null;
+  next: string;
+}
+
+/** state.md: enough for a fresh session to resume from alone; the next step is always the last line. */
+export function renderState(s: StateView): string {
+  const waiting = s.running.map((r) => r.name);
+  return [
+    `# ${s.title}`,
+    "",
+    `HEAD ${s.head}`,
+    "",
+    "Dirty:",
+    ...(s.dirty.length ? s.dirty.map((d) => `- ${d.path}${d.owner ? ` (${d.owner})` : ""}`) : ["- none"]),
+    "",
+    "Running:",
+    ...(s.running.length
+      ? s.running.map(
+          (r) => `- ${r.name} · ${r.rung} · thread ${r.thread ?? "new"} · since ${r.since} · ${r.brief}`,
+        )
+      : ["- none"]),
+    "",
+    `Last check: ${s.lastCheck ?? "none"}`,
+    "",
+    `Next: ${waiting.length ? `wait for ${waiting.join(", ")}; then ${s.next}` : s.next}`,
+    "",
+  ].join("\n");
+}

package/src/domain/util.ts

@@ -0,0 +1,18 @@
+/** Lower-case letters and digits, every other run of characters one `-`, no `-` at either end. */
+export const slug = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+/** The middle value, or the mean of the two middle values for an even count; null when there are none. */
+export function median(xs: readonly number[]): number | null {
+  if (xs.length === 0) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? (s[m] as number) : ((s[m - 1] as number) + (s[m] as number)) / 2;
+}
+
+/** A plain object: not null and not an array. */
+export const isPlain = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);

package/src/entry/capture-fixtures-command.ts

@@ -0,0 +1,57 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import { assetPath } from "../infra/assets.ts";
+import { CAPTURE_BACKENDS, type Captured, captureFixtures } from "../services/capture.ts";
+import { exitCodeOf, mark, printError } from "./cli-kit.ts";
+
+/**
+ * Spec §11.8: fixtures go to the catherd checkout's test/fixtures/adapters, next to the contract fixtures
+ * they feed, wherever the command runs; null for an installed package, which has no tests to feed.
+ */
+export function defaultOut(): string | null {
+  const dir = assetPath("test/fixtures/adapters");
+  return existsSync(dir) ? dir : null;
+}
+
+export function formatCaptured(r: Captured): string {
+  return r.status === "captured"
+    ? `${mark("ok")} ${r.backend} ${r.cliVersion} ${r.name} → ${r.dir}/${r.name}.jsonl (exit ${r.exitCode})`
+    : `${mark("skip")} ${r.backend} ${r.name} skipped: ${r.reason}`;
+}
+
+export const captureFixturesCommand = defineCommand({
+  meta: {
+    name: "capture-fixtures",
+    description: "Record one cheap real run per ready backend as sanitized test fixtures",
+  },
+  args: {
+    backend: { type: "string", description: `only this backend (${CAPTURE_BACKENDS.join(", ")})` },
+    out: { type: "string", description: "fixture root (default: this checkout's test/fixtures/adapters)" },
+  },
+  async run({ args }) {
+    const refuse = (message: string, fix: string): void => {
+      const e = new CatherdError("E_INPUT_INVALID", message, { fix });
+      printError(e);
+      process.exitCode = exitCodeOf(e);
+    };
+    const out = args.out ? resolve(args.out) : defaultOut();
+    if (!out)
+      return refuse(
+        "no --out, and this catherd is not a source checkout",
+        "catherd capture-fixtures --out <dir>",
+      );
+    if (args.backend && !CAPTURE_BACKENDS.includes(args.backend))
+      return refuse(
+        `no capture cases for backend "${args.backend}"`,
+        `catherd capture-fixtures --backend ${CAPTURE_BACKENDS.join("|")}`,
+      );
+    const results = await captureFixtures({
+      outDir: out,
+      backends: args.backend ? [args.backend] : undefined,
+    });
+    for (const r of results) console.log(formatCaptured(r));
+    process.exitCode = results.some((r) => r.status === "captured") ? 0 : 1;
+  },
+});

package/src/entry/catalog-command.ts

@@ -0,0 +1,106 @@
+import { defineCommand } from "citty";
+import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { gitToplevel } from "../infra/git.ts";
+import {
+  type CatalogModel,
+  catalogQuery,
+  type Refreshed,
+  refreshDiscovery,
+  saveTreatLike,
+} from "../services/catalog-service.ts";
+import { exitCodeOf, JSON_ARG, mark, printError } from "./cli-kit.ts";
+
+/** One backend's refresh: its model count, else why it listed none, then its fix on a line of its own. */
+export function formatRefreshed(r: Refreshed, plain = false): string {
+  if (!r.error) return `${mark("ok", plain)} ${r.backend}: ${r.models} models`;
+  return [
+    `${mark("warn", plain)} ${r.backend}: ${r.error}${r.fetchedAt ? ` (last listed ${r.fetchedAt})` : ""}`,
+    ...(r.fix ? [`    fix: ${r.fix}`] : []),
+  ].join("\n");
+}
+
+export function formatModel(m: CatalogModel): string {
+  const scored = m.rungs.filter((r) => r.enabled).length;
+  const listed = m.listed === false ? "  not offered by this account" : "";
+  return `${m.backend}:${m.model}  ${scored}/${m.rungs.length} rungs scored  roles ${m.roles.join(",") || "none"}${listed}`;
+}
+
+/** The repository the command runs in, for per-repository listings; none outside one (global). */
+const hereRepo = async (): Promise<string | undefined> => (await gitToplevel(process.cwd())) ?? undefined;
+
+function fail(e: unknown): void {
+  if (!isCatherdError(e)) throw e;
+  printError(e);
+  process.exitCode = exitCodeOf(e);
+}
+
+const refresh = defineCommand({
+  meta: { name: "refresh", description: "List every backend's models now" },
+  args: JSON_ARG,
+  async run({ args }) {
+    const r = await refreshDiscovery({ repo: await hereRepo() });
+    if (args.json) console.log(JSON.stringify(r, null, 2));
+    else for (const x of r) console.log(formatRefreshed(x));
+    process.exitCode = r.some((x) => !x.error) ? 0 : 1;
+  },
+});
+
+const list = defineCommand({
+  meta: { name: "list", description: "The models catherd can place, with their scored rungs" },
+  args: {
+    backend: { type: "string", description: "only this backend or billing key" },
+    role: { type: "string", description: `only models for this role (${ROLES.join(", ")})` },
+    text: { type: "string", description: "only ids containing this" },
+    scored: { type: "boolean", description: "only models with a scored rung" },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    if (args.role && !(ROLES as readonly string[]).includes(args.role))
+      return fail(
+        new CatherdError("E_INPUT_INVALID", `no role "${args.role}"`, {
+          fix: `pass --role ${ROLES.join("|")}`,
+        }),
+      );
+    try {
+      const r = catalogQuery({
+        backend: args.backend,
+        role: args.role as Role | undefined,
+        text: args.text,
+        scoredOnly: args.scored === true,
+        limit: 10_000,
+        repo: await hereRepo(),
+      });
+      if (args.json) console.log(JSON.stringify(r, null, 2));
+      else for (const m of r.models) console.log(formatModel(m));
+    } catch (e) {
+      fail(e);
+    }
+  },
+});
+
+const treatLike = defineCommand({
+  meta: { name: "treat-like", description: "Score an unscored rung as a scored one" },
+  args: {
+    rung: {
+      type: "positional",
+      required: true,
+      description: "the unscored rung, backend:model#effort or model#effort",
+    },
+    like: { type: "positional", required: true, description: "the scored rung whose scores it borrows" },
+  },
+  async run({ args }) {
+    try {
+      const r = await saveTreatLike(args.rung, args.like);
+      console.log(`✓ ${r.rung} is treated like ${r.like}`);
+    } catch (e) {
+      fail(e);
+    }
+  },
+});
+
+/** Spec §8: `catherd catalog refresh|list|treat-like <rung> <like>`. */
+export const catalogCommand = defineCommand({
+  meta: { name: "catalog", description: "The model catalog" },
+  subCommands: { refresh, list, "treat-like": treatLike },
+});

package/src/entry/cli-kit.ts

@@ -0,0 +1,36 @@
+import { type CatherdError, isCatherdError } from "../domain/errors.ts";
+import { RUN_NOT_FOUND_FIX } from "../services/run-store.ts";
+import { glyph, type State } from "./glyphs.ts";
+
+/** Spec §8: 0 ok, 1 error, 2 usage, 3 not ready (doctor), 130 interrupted. */
+export const EXIT = { ok: 0, error: 1, usage: 2, notReady: 3, interrupted: 130 } as const;
+
+// oxlint-disable-next-line no-control-regex -- citty colours its messages; the one-line error must not
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/** `text` without colour codes: for output that is piped, or under NO_COLOR. */
+export const stripAnsi = (text: string): string => text.replace(ANSI, "");
+
+/** A service's fix worded for the MCP tools, as the CLI says it. */
+const CLI_FIX: Record<string, string> = { [RUN_NOT_FOUND_FIX]: "catherd runs list" };
+
+/** Spec §8: one line `error E_CODE: message`, then `fix: …` when there is one. */
+export function printError(e: Pick<CatherdError, "code" | "message" | "fix">): void {
+  console.error(`error ${e.code}: ${stripAnsi(e.message).split("\n").join(" ")}`);
+  if (e.fix) console.error(`fix: ${CLI_FIX[e.fix] ?? e.fix}`);
+}
+
+/** Bad input from the command line is a usage error; any other catherd error is an error. */
+export const exitCodeOf = (e: unknown): number =>
+  isCatherdError(e) && e.code === "E_INPUT_INVALID" ? EXIT.usage : EXIT.error;
+
+export const printJson = (v: unknown): void => console.log(JSON.stringify(v, null, 2));
+
+/** The `--json` flag every read command takes. */
+export const JSON_ARG = { json: { type: "boolean", description: "print JSON" } } as const;
+
+/**
+ * The glyph for a state, as in `✓ ready`: the dashboard's own (spec §9.3), ASCII with `--plain` only;
+ * NO_COLOR drops colour, never glyphs. The caller adds the word.
+ */
+export const mark = (state: State, plain = false): string => glyph(state, plain);

package/src/entry/deps.ts

@@ -0,0 +1,16 @@
+import { VERSION } from "../infra/version.ts";
+import type { Deps } from "../services/ports.ts";
+import { profileService } from "../services/profile-service.ts";
+import { routingService } from "../services/routing-service.ts";
+
+/** The services every entry point (MCP server, CLI commands) runs on. */
+export function defaultDeps(): Deps {
+  return {
+    profiles: profileService(),
+    routing: routingService(),
+    version: VERSION,
+    pollMs: 250,
+    tickMs: Number(process.env.CATHERD_TICK_MS) || 30_000,
+    now: Date.now,
+  };
+}