rovecode 0.4.0-beta.3 → 0.4.0

package/src/market/types.ts

@@ -0,0 +1,236 @@
+/** One market, three kinds. `rovecode market …`, the sextant's /market and the site's market page all read
+ *  the SAME item type: an MCP server, a skill and a plugin differ in what installing them means, not in how
+ *  they are found, described or shown.
+ *
+ *  Design rules this file exists to hold:
+ *  - MCP is WRAPPED, never rewritten: `install.kind === "mcp"` carries the existing `MarketEntry`
+ *    (src/mcp/market.ts) untouched, so the curated shelf, the registry re-typing and the install planner
+ *    keep working exactly as they do today. A new kind is a new arm of `InstallSpec`, not a new pipeline.
+ *  - Everything a UI needs to draw a row is on the item itself (title, publisher, one line, tags, version,
+ *    source). Anything that needs the local filesystem — installed? update available? — is a separate
+ *    `InstalledState`, because it changes without the catalog changing.
+ *  - Catalog data is UNTRUSTED. These types describe what a validator PRODUCES (registry.ts), never what a
+ *    response happens to contain. The caps live here so every source is bounded the same way.
+ *  - Nothing here reads a file, spawns a process or touches the network: types + pure helpers only, so
+ *    importing this module costs nothing at boot (the lazy-import rule). */
+
+import type { MarketEntry } from "../mcp/market.ts";
+
+export type MarketKind = "mcp" | "skill" | "plugin";
+/** where the item was found. "curated" = built into rovecode, hand-checked; "registry" = a live remote
+ *  index (the MCP registry today); "catalog" = a rovecode-published catalog file for skills and plugins */
+export type MarketSource = "curated" | "registry" | "catalog";
+/** user = ~/.rovecode (every project sees it) · project = this repo (trust-gated, committed with the repo) */
+export type MarketScope = "user" | "project";
+
+/** Hard ceilings on anything a source contributes. A field past its cap is truncated (strings) or dropped
+ *  (list items) — never an error, because one bad row must not blank a whole catalog. */
+export const LIMITS = {
+  /** response body accepted from a remote catalog */
+  body: 2 * 1024 * 1024,
+  /** items accepted from one source */
+  items: 200,
+  /** any short string (id, title, publisher, version, url) */
+  str: 300,
+  /** the one-line description a row shows */
+  desc: 500,
+  /** tags per item, and files per skill */
+  list: 32,
+  /** environment variables one item may declare */
+  env: 24,
+  /** an item's documentation body: markdown, not a label. Nothing else here is remotely this big, which is
+   *  exactly why it needs its own cap — run a 24 KB body through `str()` and it comes back silently cut to
+   *  300 characters, still a valid string, and nobody notices. */
+  docs: 24 * 1024,
+} as const;
+
+/** An item's own documentation, fetched at BUILD time and carried in the catalog.
+ *
+ *  Never fetched at runtime. The market has to work offline and the site's page is static, and pulling
+ *  third-party text into a UI at display time is not something worth doing for a docs pane. The body is
+ *  carried as TEXT and nothing more: it is never executed, never evaluated, never parsed as HTML here —
+ *  each surface renders it safely on its own side.
+ *
+ *  Absent when upstream had no readable doc. A row without docs is a normal row, not a broken one. */
+export interface ItemDocs {
+  /** the exact URL it was read from, so a reader can go to the original */
+  source: string;
+  format: "markdown";
+  /** the body's length in bytes BEFORE truncation, so a UI can say how much is missing */
+  bytes: number;
+  truncated: boolean;
+  /** Markdown text, capped at LIMITS.docs. OPTIONAL on purpose: the search path does not carry bodies
+   *  (they are ~200 KB the search never reads), so a row from `searchMarket` has the metadata and
+   *  `body === undefined`. `undefined` means "not carried on this call" and is not the same as an empty
+   *  document — a UI must send the reader to `market docs <id>` rather than say there is nothing. */
+  body?: string;
+}
+
+/** An environment variable an item needs. Same shape the MCP side already uses (mcp/market.ts EnvSpec):
+ *  `secret: true` is asked masked on a shell and NEVER written into a project file — it is written as
+ *  `${NAME}` and read from the environment at launch. */
+export interface MarketEnv {
+  name: string;
+  description?: string;
+  required: boolean;
+  secret: boolean;
+  /** a value the catalog already knows (a default port, a public URL): not a question */
+  default?: string;
+}
+
+/** What installing this item actually does. One arm per kind — the arm carries whatever the kind's existing
+ *  installer needs, so `install.ts` can delegate without re-deriving anything. */
+export type InstallSpec =
+  /** the MCP entry as mcp/market.ts produced it; mcp/market-install.ts plans and writes it */
+  | { kind: "mcp"; entry: MarketEntry }
+  /** a plugin folder or git URL; src/plugins/install.ts addPlugin() clones and copies it.
+   *  `subfolder` is where the plugin.json lives inside that repo — real plugins live in a monorepo
+   *  (plugins/safety-net), so a repo root is the exception, not the rule. Same escape rules as a skill's. */
+  | { kind: "plugin"; source: string; /** true when `source` is a git URL rather than a local folder */ git: boolean; subfolder?: string }
+  /** a skill: a git repo (optionally a subfolder) or a set of files written verbatim.
+   *  `files` is the offline form — a curated skill ships its SKILL.md in the catalog itself. */
+  | { kind: "skill"; source?: { git: string; subfolder?: string }; files?: { path: string; text: string }[] };
+
+/** One row in the market, whatever its kind. */
+export interface MarketItem {
+  /** what `market install <id>` takes. Unique per kind, not across kinds: `mcp:git` and `skill:git` may
+   *  both exist, which is why resolve.ts accepts `kind:id` and lists candidates when a bare id is ambiguous. */
+  id: string;
+  kind: MarketKind;
+  /** display name; falls back to `id` when a source has none */
+  title: string;
+  /** who publishes it — a namespace, an org, or "unknown" */
+  publisher: string;
+  /** one line, already capped at LIMITS.desc */
+  description: string;
+  source: MarketSource;
+  version?: string;
+  repository?: string;
+  homepage?: string;
+  /** free-form, lowercase, capped; a UI may filter on these but must not depend on any particular tag */
+  tags: string[];
+  /** the source's own status when it is anything but normal ("deprecated", "experimental") */
+  status?: string;
+  /** the licence as the publisher states it ("Apache-2.0", "source-available, not open source", "none stated").
+   *  A field, not a note: a market that installs other people's work has to show this before the yes, and a
+   *  UI will want to filter on it. Free text — an SPDX id is common but not required. */
+  license?: string;
+  /** the variables this item needs before it can run. Empty for most skills and plugins. */
+  env: MarketEnv[];
+  install: InstallSpec;
+  /** the item's own documentation, carried in the catalog — see ItemDocs */
+  docs?: ItemDocs;
+  /** extra lines a catalog wants in the approval preview, in its own words ("copies one SKILL.md, runs
+   *  nothing"). install.ts writes the standard plan from `install`; these are appended verbatim, capped
+   *  like every other list. A catalog that has nothing special to say omits them. */
+  planNote?: string[];
+  /** what a plugin brings, as data rather than as a sentence: "commands", "skills", "agents", "hooks",
+   *  "mcpServers", "tools". The catalog has carried this since the generator was written, but only the
+   *  prose form ("contributes: commands, skills") ever reached a reader — so a caller wanting to filter
+   *  on it had to parse English. The prose stays for the approval preview, which is written for a
+   *  person; this is the same fact for anything that has to choose between two candidates. It describes
+   *  what the catalog CLAIMS, exactly like every other field here, and is no more verified than they are. */
+  contributes?: string[];
+}
+
+/** Local truth about one item, computed from disk (never from a catalog). Kept apart from `MarketItem`
+ *  because it changes when the user installs something, not when the catalog updates. Its PRESENCE on a
+ *  row means installed — `row.installed === undefined` is the not-installed case, so a UI draws the badge
+ *  from one check and never from a boolean that could disagree with the path. */
+export interface InstalledState {
+  /** where it landed: the mcp.json, the plugin folder, the skill folder */
+  path: string;
+  scope: MarketScope;
+  /** the version on disk when it is knowable (a plugin manifest, an mcp entry's recorded version) */
+  version?: string;
+  /** true when the catalog's version is a different string from the installed one. Not a semver compare:
+   *  a UI says "update available", the human reads both numbers. */
+  updateAvailable?: boolean;
+  /** project-scope items only: the trust gate's answer. `undefined` for user scope, which is never gated. */
+  trusted?: boolean;
+}
+
+/** A market row as a UI receives it: the catalog item plus what this machine knows about it.
+ *  `installed` present = on disk here; absent = not installed. */
+export interface MarketRow extends MarketItem {
+  installed?: InstalledState;
+}
+
+// ---------------------------------------------------------------- results, never exceptions
+
+/** Why a source produced nothing. A UI draws these differently, so they are distinguishable values and not
+ *  one error string: `offline` and `stale` still carry rows, `failed` carries the reason. */
+export type SourceStatus =
+  | { ok: true; from: "live" }
+  /** the network was not tried (--offline, no network): rows come from the cache or the curated shelf */
+  | { ok: true; from: "cache"; ageMs: number }
+  | { ok: true; from: "curated" }
+  /** the source was not consulted at all (an empty query never asks the registry): no rows, no failure */
+  | { ok: true; from: "skipped"; why: string }
+  /** the fetch failed and there was nothing cached: this source contributed no rows */
+  | { ok: false; reason: string };
+
+/** What every listing call returns. Never throws for a data problem — a caller that must distinguish
+ *  "nothing matched" from "the registry is down" reads `sources`. */
+export interface MarketResult {
+  items: MarketItem[];
+  /** one entry per source consulted, keyed by a stable name ("mcp:curated", "mcp:registry", "skills", "plugins") */
+  sources: Record<string, SourceStatus>;
+  /** human-readable notes worth showing once (a capped field, a dropped row, a stale cache) */
+  notes: string[];
+}
+
+/** The three-step visibility the MCP market established, generalised: a plan is built and SHOWN, the human
+ *  says yes, and only then is anything written. `preview` is the whole plan in the human's words. */
+export interface InstallPlanView {
+  item: MarketItem;
+  /** where the write lands (an mcp.json, a plugins folder, a skills folder) */
+  target: string;
+  scope: MarketScope;
+  /** the lines a CLI prints or a card shows — everything that must be seen before a yes */
+  preview: string[];
+  /** variables that will be asked (shell: masked for secrets) or written as `${NAME}` */
+  asks: MarketEnv[];
+  /** required values nobody can fill for the human (a directory to expose, a database URL) */
+  pending: string[];
+  /** true when this install replaces something already there */
+  replaces?: string;
+}
+
+export type InstallOutcome =
+  | { ok: true; item: MarketItem; target: string; scope: MarketScope;
+      /** variable names the written config now refers to; the human must export them before a restart */
+      envNames: string[];
+      /** project scope only: whether the write was recorded as trusted */
+      trusted?: boolean;
+      /** MCP only: `<…>` placeholders the written entry still carries because nobody answered for them; the
+       *  loader skips the server until a hand replaces them, so `next` says that instead of "restart" */
+      fillIn?: string[];
+      /** MCP install-once only (mcp/local-package.ts): the package npm put on disk, as recorded in
+       *  installed.json — `missing` names anything the record could not carry (an integrity hash the lockfile
+       *  did not supply), so a caller can say so rather than print a clean line over a hole */
+      package?: { name: string; version: string; prefix: string; bin: string; integrity?: string; missing?: string[] };
+      /** what the human must do for it to take effect ("restart rovecode — servers are read once per process") */
+      next?: string }
+  | { ok: false; error: string };
+
+// ---------------------------------------------------------------- pure helpers (no I/O)
+
+/** `mcp:filesystem` → {kind, id}; a bare word → {id} with no kind. Anything else → null. */
+export function parseQualifiedId(text: string): { kind?: MarketKind; id: string } | null {
+  const t = text.trim();
+  if (t.length === 0 || t.length > LIMITS.str) return null;
+  const m = /^(mcp|skill|plugin):(.+)$/.exec(t);
+  if (m) return { kind: m[1] as MarketKind, id: m[2]!.trim() };
+  return { id: t };
+}
+
+export const qualify = (item: Pick<MarketItem, "kind" | "id">): string => `${item.kind}:${item.id}`;
+
+/** The one-line row every surface shows. Kept here so the CLI, the TUI and the site cannot drift. */
+export function itemLine(item: MarketItem): string {
+  const bits = [item.kind.padEnd(6), item.title];
+  if (item.version) bits.push(item.version);
+  bits.push(`· ${item.publisher}`);
+  return `${bits.join(" ")} — ${item.description}`;
+}

package/src/market/validate.ts

@@ -0,0 +1,227 @@
+/** Check a catalog before anyone is asked to trust it.
+ *
+ *  `--check` in CI answers "did OUR generator produce this?", which is the wrong question for someone
+ *  else's file. A person writing a private catalog for their team, or preparing one to send us, needs the
+ *  question answered the other way round: *given this file, what would rovecode do with it, and which of my
+ *  fields would not survive?* That is what this reports, field by field.
+ *
+ *  THE INVARIANT THAT MATTERS: this must never call a row valid that `registry.ts` would drop. A validator
+ *  that disagrees with the loader is worse than none — it hands out a clean bill for a catalog that shows
+ *  up empty. So every row is also run through `itemFromCatalog`, the real reader, and a row it refuses
+ *  while we found nothing to say produces an error anyway. The checks below exist to explain the refusal in
+ *  the author's terms, not to be the authority on it.
+ *
+ *  Errors and warnings are genuinely different and are not collapsed:
+ *    error   — the row (or the file) is dropped. The market will not show it.
+ *    warning — the row loads, but not as written: a field was truncated, a list item past the cap was
+ *              dropped, a key was not recognised. Silent in production, and exactly what an author wants
+ *              to hear before they publish.
+ */
+
+import { itemFromCatalog } from "./registry.ts";
+import { LIMITS } from "./types.ts";
+
+export type Severity = "error" | "warning";
+
+export interface Finding {
+  /** where it is, in the author's terms: `items[3].description` */
+  path: string;
+  message: string;
+  severity: Severity;
+}
+
+export interface ValidationReport {
+  ok: boolean;
+  kind: "skill" | "plugin";
+  /** rows that would load */
+  accepted: number;
+  /** rows the market would drop */
+  dropped: number;
+  findings: Finding[];
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** The keys each kind's rows may carry. An unrecognised key is a warning, not an error, because a catalog
+ *  may legitimately carry more than we read — but `descriptoin` is a typo that would otherwise cost the
+ *  author a silent empty description, and that is worth a line. */
+const KNOWN_KEYS: Record<"skill" | "plugin", ReadonlySet<string>> = {
+  skill: new Set(["id", "name", "title", "publisher", "description", "version", "license", "tags", "repository",
+                  "homepage", "source", "files", "bytes", "docs", "env", "status", "planNote"]),
+  plugin: new Set(["id", "name", "title", "publisher", "description", "version", "apiVersion", "license", "tags",
+                   "repository", "homepage", "install", "contributes", "docs", "env", "status", "planNote"]),
+};
+
+/** a subfolder that climbs out of its clone, by the same rules the installers apply */
+function escapes(sub: unknown): boolean {
+  if (typeof sub !== "string" || sub === "") return false;
+  const s = sub.split("\\").join("/");
+  return s.startsWith("/") || /^[A-Za-z]:/.test(s) || s.split("/").includes("..");
+}
+
+export interface ValidateOptions {
+  /** `skill` or `plugin`; when absent it is read from the document's own `kind`, else inferred from a name */
+  kind?: "skill" | "plugin";
+  /** the file name, used only to infer the kind when nothing else says */
+  filename?: string;
+}
+
+export function inferKind(doc: unknown, opts: ValidateOptions = {}): "skill" | "plugin" | undefined {
+  if (opts.kind !== undefined) return opts.kind;
+  if (isRecord(doc) && (doc.kind === "skill" || doc.kind === "plugin")) return doc.kind;
+  const n = (opts.filename ?? "").toLowerCase();
+  if (n.includes("skill")) return "skill";
+  if (n.includes("plugin")) return "plugin";
+  return undefined;
+}
+
+/** Validate one catalog document. `text` is the raw file — parsing is part of what is being checked. */
+export function validateCatalog(text: string, opts: ValidateOptions = {}): ValidationReport {
+  const findings: Finding[] = [];
+  const add = (path: string, message: string, severity: Severity = "error") => findings.push({ path, message, severity });
+
+  if (text.length > LIMITS.body) {
+    return { ok: false, kind: opts.kind ?? "skill", accepted: 0, dropped: 0,
+             findings: [{ path: "", message: `the file is ${Math.round(text.length / 1024)} KB; rovecode reads at most ${LIMITS.body / 1024} KB`, severity: "error" }] };
+  }
+
+  let doc: unknown;
+  try { doc = JSON.parse(text); }
+  catch (e) { return { ok: false, kind: opts.kind ?? "skill", accepted: 0, dropped: 0,
+                       findings: [{ path: "", message: `not valid JSON: ${e instanceof Error ? e.message : String(e)}`, severity: "error" }] }; }
+
+  const kind = inferKind(doc, opts);
+  if (kind === undefined) {
+    return { ok: false, kind: "skill", accepted: 0, dropped: 0,
+             findings: [{ path: "", message: `cannot tell whether this is a skill or a plugin catalog — pass --kind skill|plugin, or give the document a "kind" field`, severity: "error" }] };
+  }
+
+  if (!isRecord(doc)) {
+    return { ok: false, kind, accepted: 0, dropped: 0, findings: [{ path: "", message: "the top level must be an object", severity: "error" }] };
+  }
+  if (doc.version === undefined) add("version", "missing; rovecode assumes 1", "warning");
+  else if (doc.version !== 1) add("version", `is ${JSON.stringify(doc.version)}; this rovecode reads version 1`);
+  if (!Array.isArray(doc.items)) {
+    add("items", "missing or not an array — a catalog is { version, items: [...] }");
+    return { ok: false, kind, accepted: 0, dropped: 0, findings };
+  }
+
+  const rows = doc.items;
+  if (rows.length === 0) add("items", "no rows: this catalog would show nothing", "warning");
+  if (rows.length > LIMITS.items) add("items", `${rows.length} rows; rovecode reads the first ${LIMITS.items} and ignores the rest`, "warning");
+
+  const seen = new Map<string, number>();
+  let accepted = 0, dropped = 0;
+
+  rows.forEach((raw: unknown, i: number) => {
+    const at = `items[${i}]`;
+    const before = findings.length;
+
+    if (!isRecord(raw)) { add(at, "not an object"); dropped++; return; }
+
+    const id = typeof raw.id === "string" ? raw.id : typeof raw.name === "string" ? raw.name : undefined;
+    if (id === undefined) add(`${at}.id`, "missing (a row needs an id, or a name to use as one)");
+    else if (!ID.test(id)) add(`${at}.id`, `"${id}" is not a bare slug — lowercase letters, digits, dot, dash, underscore, at most 64`);
+    else {
+      const first = seen.get(id);
+      if (first !== undefined) add(`${at}.id`, `"${id}" is already used by items[${first}]; ids are unique within a kind`);
+      else seen.set(id, i);
+    }
+
+    if (typeof raw.description !== "string" || raw.description.trim() === "") add(`${at}.description`, "missing (a row needs one line describing it)");
+    else if (raw.description.length > LIMITS.desc) add(`${at}.description`, `${raw.description.length} characters; will be cut to ${LIMITS.desc}`, "warning");
+
+    for (const k of ["title", "publisher", "version", "license", "repository", "homepage"] as const) {
+      const v = raw[k];
+      if (v !== undefined && typeof v !== "string") add(`${at}.${k}`, `must be a string, not ${Array.isArray(v) ? "an array" : typeof v}`, "warning");
+      else if (typeof v === "string" && v.length > LIMITS.str) add(`${at}.${k}`, `${v.length} characters; will be cut to ${LIMITS.str}`, "warning");
+    }
+    if (raw.publisher === undefined) add(`${at}.publisher`, 'missing; the row will say "unknown"', "warning");
+
+    if (raw.tags !== undefined) {
+      if (!Array.isArray(raw.tags)) add(`${at}.tags`, "must be an array of strings", "warning");
+      else if (raw.tags.length > LIMITS.list) add(`${at}.tags`, `${raw.tags.length} tags; only the first ${LIMITS.list} are read`, "warning");
+    }
+
+    validateInstall(kind, raw, at, add);
+    validateDocs(raw.docs, `${at}.docs`, add);
+
+    for (const key of Object.keys(raw)) {
+      if (!KNOWN_KEYS[kind].has(key)) add(`${at}.${key}`, "not a field rovecode reads — a typo, or something it will ignore", "warning");
+    }
+
+    // The authority, not us: whatever we found or missed, the real reader decides whether this row loads.
+    const notes: string[] = [];
+    const item = itemFromCatalog(kind, raw, notes);
+    const errorsHere = findings.slice(before).some((f) => f.severity === "error");
+    if (item === null) {
+      dropped++;
+      if (!errorsHere) add(at, `rovecode drops this row${notes.length ? `: ${notes[notes.length - 1]}` : ""} — the checks above did not explain why, which is a gap in this validator`);
+    } else {
+      if (errorsHere) add(at, "the row loads despite the errors above; treat them as the more careful reading", "warning");
+      accepted++;
+    }
+  });
+
+  return { ok: findings.every((f) => f.severity !== "error"), kind, accepted, dropped, findings };
+}
+
+function validateInstall(kind: "skill" | "plugin", raw: Record<string, unknown>, at: string,
+                         add: (p: string, m: string, s?: Severity) => void): void {
+  if (kind === "skill") {
+    const source = isRecord(raw.source) ? raw.source : undefined;
+    const files = Array.isArray(raw.files) ? raw.files : undefined;
+    if (source === undefined && files === undefined) {
+      add(`${at}.source`, "missing: a skill needs either source.git (a repository) or files (the text itself)");
+      return;
+    }
+    if (source !== undefined) {
+      if (typeof source.git !== "string" || !/^https?:\/\//.test(source.git)) add(`${at}.source.git`, "must be an http(s) repository URL");
+      if (escapes(source.subfolder)) add(`${at}.source.subfolder`, `"${String(source.subfolder)}" climbs out of the clone`);
+    }
+    files?.forEach((f: unknown, j: number) => {
+      const p = isRecord(f) ? f.path : undefined;
+      if (typeof p !== "string" || p === "") add(`${at}.files[${j}].path`, "missing");
+      else if (escapes(p)) add(`${at}.files[${j}].path`, `"${p}" writes outside the skill's folder`);
+      if (isRecord(f) && typeof f.text !== "string") add(`${at}.files[${j}].text`, "missing (the file's contents)");
+    });
+    if (files !== undefined && files.length > LIMITS.list) add(`${at}.files`, `${files.length} files; only the first ${LIMITS.list} are read`, "warning");
+    return;
+  }
+
+  const install = isRecord(raw.install) ? raw.install : undefined;
+  if (install === undefined) { add(`${at}.install`, "missing: a plugin needs install.source (a repository URL or a folder)"); return; }
+  if (typeof install.source !== "string" || install.source === "") { add(`${at}.install.source`, "missing"); return; }
+  if (install.git === true && !/^https?:\/\//.test(install.source)) add(`${at}.install.source`, `"${install.source}" is marked git: true but is not an http(s) URL`);
+  if (escapes(install.subfolder)) add(`${at}.install.subfolder`, `"${String(install.subfolder)}" climbs out of the clone`);
+  // Not an error, and said plainly: rovecode's own three plugins all live in a subfolder, so a row without
+  // one is claiming the manifest sits at the repository root — right sometimes, a mistake more often.
+  if (install.subfolder === undefined) add(`${at}.install.subfolder`, "absent: the plugin.json must then be at the repository root", "warning");
+}
+
+function validateDocs(docs: unknown, at: string, add: (p: string, m: string, s?: Severity) => void): void {
+  if (docs === undefined) return;                       // a row without documentation is a normal row
+  if (!isRecord(docs)) { add(at, "must be an object", "warning"); return; }
+  if (typeof docs.source !== "string" || !/^https?:\/\//.test(docs.source)) add(`${at}.source`, "must be the http(s) URL the document was read from — the docs are dropped without it", "warning");
+  if (docs.format !== "markdown") add(`${at}.format`, `must be "markdown"; the docs are dropped otherwise`, "warning");
+  if (typeof docs.body !== "string" || docs.body.trim() === "") add(`${at}.body`, "empty: the docs are dropped and the row keeps no documentation", "warning");
+  else if (Buffer.byteLength(docs.body, "utf8") > LIMITS.docs) add(`${at}.body`, `${Math.round(Buffer.byteLength(docs.body, "utf8") / 1024)} KB; will be cut to ${LIMITS.docs / 1024} KB`, "warning");
+  if (docs.truncated === true && typeof docs.bytes === "number" && typeof docs.body === "string"
+      && docs.bytes <= Buffer.byteLength(docs.body, "utf8")) {
+    add(`${at}.bytes`, "marked truncated, but bytes is not larger than the body — bytes should be the size BEFORE truncation", "warning");
+  }
+}
+
+/** The report as lines, for a terminal. Errors first: an author fixes those, warnings are a second pass. */
+export function reportLines(r: ValidationReport, where: string): string[] {
+  const errors = r.findings.filter((f) => f.severity === "error");
+  const warnings = r.findings.filter((f) => f.severity === "warning");
+  const lines = [`${where}: ${r.kind} catalog — ${r.ok ? "valid" : "INVALID"}`];
+  lines.push(`  ${r.accepted} row${r.accepted === 1 ? "" : "s"} would load, ${r.dropped} dropped, ${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
+  for (const f of [...errors, ...warnings]) {
+    lines.push(`  ${f.severity === "error" ? "error  " : "warning"}  ${f.path === "" ? "(file)" : f.path}: ${f.message}`);
+  }
+  if (r.ok && warnings.length > 0) lines.push("  warnings do not stop a catalog loading; they are fields that will not survive as written");
+  return lines;
+}