magus-cli 0.0.0-placeholder → 7.1.0

package/src/cli/update-view.ts

@@ -0,0 +1,717 @@
+/**
+ * update-view.ts — every string `magus update` prints, and nothing else.
+ *
+ * Pure functions: plan in, lines out. No IO, no timers, no terminal. That is
+ * what makes the look testable — the old report was `console.log` calls braided
+ * through the control flow, so the only way to check a column lined up was to
+ * run the command against a real machine.
+ *
+ * ## The visual contract
+ *
+ * Three rules, applied mechanically rather than case by case:
+ *
+ *  1. **A discrete status is a badge**, not a coloured word: dark-or-white ink
+ *     on a saturated fill, so it reads as a chip at a glance.
+ *  2. **A bounded value is a bar**, not a numeral. A step's share of the run's
+ *     wall clock and the apply loop's completion are both bars; the number
+ *     labels the bar rather than replacing it.
+ *  3. **Dim the chrome, saturate the signal.** A plugin already at the right
+ *     version is chrome — grey, no chip. Everything that needs a decision or a
+ *     download is bright. Nine grey rows and three coloured ones is the whole
+ *     point: the eye lands on the three.
+ *
+ * Colour never carries meaning alone. Every action has its own glyph and its
+ * own word, so the report survives NO_COLOR, a pipe, and colour blindness.
+ */
+
+import { binCommandFor } from "../services/update-engine.js";
+import type {
+	BinUpdateItem,
+	PluginUpdateItem,
+	SkillUpdateItem,
+	UpdatePlan,
+} from "../services/update-plan.js";
+import { type ReportBadgeKind, reportBadge } from "../ui/theme-mode.js";
+import { brand } from "../ui/theme.js";
+import { formatCommand } from "../utils/command-utils.js";
+import {
+	badge,
+	bold,
+	dim,
+	elapsed,
+	fg,
+	meter,
+	padEnd,
+	padStart,
+	ramps,
+	spinner,
+	stackedBar,
+	sweep,
+	width,
+} from "./ansi.js";
+
+/** Two spaces of gutter on every line, so the report reads as one block. */
+const PAD = "  ";
+/** Bars are this wide everywhere; a bar that changes width cannot be compared. */
+const BAR = 18;
+
+// -- action vocabulary -------------------------------------------------------
+
+/**
+ * The single source of truth for what an action looks like.
+ *
+ * Glyph, word and hue together — defined once so a plugin `install` and a
+ * binary `install` cannot drift into two different blues with two different
+ * symbols, which is exactly what happened when each row built its own string.
+ */
+interface ActionStyle {
+	glyph: string;
+	label: string;
+	color: string;
+	/** Chrome rows are dimmed whole and carry no chip. */
+	chrome?: boolean;
+}
+
+/** Every action any of the three planners can produce, in one union. */
+type ActionKey =
+	| "current"
+	| "install"
+	| "update"
+	| "upgrade"
+	| "repair"
+	| "refresh"
+	| "unknown";
+
+const ACTIONS: Record<ActionKey, ActionStyle> = {
+	current: { glyph: "=", label: "CURRENT", color: brand.muted, chrome: true },
+	install: { glyph: "+", label: "INSTALL", color: brand.link },
+	// Green, the tone magus uses for an update everywhere else. Amber stays
+	// on `unknown` below, so the two states remain distinguishable: green is
+	// "a newer version exists", amber is "we could not tell".
+	update: { glyph: "↑", label: "UPDATE", color: brand.success },
+	upgrade: { glyph: "↑", label: "UPGRADE", color: brand.success },
+	repair: { glyph: "⟳", label: "REPAIR", color: brand.info },
+	refresh: { glyph: "⟳", label: "REFRESH", color: brand.info },
+	// Warning, not danger: "cannot tell" is not a failure, and red UNKNOWN read
+	// as "broken". The summary line and the TUI already use warning for it.
+	unknown: { glyph: "?", label: "UNKNOWN", color: brand.warning },
+};
+
+/** Widest label plus the badge's own two spaces of padding. */
+const CHIP_WIDTH =
+	Math.max(...Object.values(ACTIONS).map((a) => a.label.length)) + 2;
+
+/** A chip for an actionable row; flat dim text for a chrome one. */
+function chip(key: ActionKey): string {
+	const style = ACTIONS[key];
+	const text = style.chrome
+		? dim(padEnd(` ${style.label} `, CHIP_WIDTH))
+		: badge(style.label, style.color);
+	return padEnd(text, CHIP_WIDTH);
+}
+
+function glyph(key: ActionKey): string {
+	return fg(ACTIONS[key].color, ACTIONS[key].glyph);
+}
+
+/** Bright for a row that needs something, grey for a row that does not. */
+function rowText(key: ActionKey, text: string): string {
+	return ACTIONS[key].chrome ? dim(text) : text;
+}
+
+// -- header ------------------------------------------------------------------
+
+export function header(profileId: string): string[] {
+	return [
+		"",
+		`${PAD}${fg(brand.accent, "◆")} ${bold("magus update")}   ${dim(
+			"profile",
+		)} ${fg(brand.accent, profileId)}`,
+		"",
+	];
+}
+
+// -- phase checklist ---------------------------------------------------------
+
+export type StepState = "pending" | "running" | "done" | "warn" | "fail";
+
+export interface Step {
+	label: string;
+	state: StepState;
+	/** Right-hand summary. While running, say what it is blocked on. */
+	detail: string;
+	startedAt?: number;
+	endedAt?: number;
+	/**
+	 * Countable work, when the step has any.
+	 *
+	 * Present → a determinate meter. Absent → an indeterminate sweep, which is
+	 * the honest widget for a call with no denominator. Never fake a percentage
+	 * for one: a bar that creeps to 90% and stops is worse than no bar.
+	 */
+	progress?: { done: number; total: number };
+}
+
+const STEP_MARK: Record<Exclude<StepState, "running">, [string, string]> = {
+	pending: ["·", brand.muted],
+	done: ["✓", brand.success],
+	warn: ["⚠", brand.warning],
+	fail: ["✗", brand.danger],
+};
+
+function stepMark(step: Step, tick: number): string {
+	if (step.state === "running") return fg(brand.accent, spinner(tick));
+	const [mark, color] = STEP_MARK[step.state];
+	return fg(color, mark);
+}
+
+function stepDuration(step: Step, now: number): number | null {
+	if (step.startedAt === undefined) return null;
+	return (step.endedAt ?? now) - step.startedAt;
+}
+
+const STEP_LABEL_WIDTH = 14;
+
+/**
+ * The animated frame: one row per step, spinner on whichever is running.
+ *
+ * Deliberately shows the pending steps too. A single spinner says "busy"; a
+ * four-row checklist with one spinner says "busy, on step two of four, and here
+ * is what is left" — which is the difference between a hang and progress.
+ */
+export function stepFrame(steps: Step[], tick: number, now: number): string[] {
+	return steps.map((step) => {
+		const ms = stepDuration(step, now);
+		const time = ms === null ? "" : dim(padStart(elapsed(ms), 6));
+		const label =
+			step.state === "pending"
+				? dim(padEnd(step.label, STEP_LABEL_WIDTH))
+				: padEnd(step.label, STEP_LABEL_WIDTH);
+		// Only the running row carries a bar. A finished row's bar belongs in the
+		// record below, where every step is on one scale and comparable; drawing
+		// it here too would put two competing bar columns on the same screen.
+		const bar =
+			step.state !== "running"
+				? " ".repeat(BAR)
+				: step.progress && step.progress.total > 0
+					? meter((step.progress.done / step.progress.total) * 100, BAR)
+					: sweep(BAR, tick, brand.accent);
+		// The bar carries the shape; this labels it. Without the count a half-full
+		// meter says "some of it", which is not the same information as "2 of 4".
+		const count =
+			step.state === "running" && step.progress && step.progress.total > 0
+				? `${fg(brand.accent, `${step.progress.done}/${step.progress.total}`)} `
+				: "";
+		const detail =
+			step.state === "running"
+				? fg(brand.accent, step.detail)
+				: dim(step.detail);
+		return `${PAD}${stepMark(step, tick)}  ${label} ${bar} ${time}  ${count}${detail}`;
+	});
+}
+
+/**
+ * The permanent record: one row per step, its duration, and what it found.
+ *
+ * NO BAR. Each row carried an 18-cell meter of that step's share of the
+ * slowest step — which is precisely what the right-aligned millisecond column
+ * beside it already says, so the row stated one fact twice. A shape earns its
+ * width by making something readable that the number does not; a share of a
+ * five-row set, already sorted into a column, is not that.
+ *
+ * The LIVE frame keeps its bar (`stepFrame` above) and that is not the same
+ * widget: there the bar is a progress meter or an indeterminate sweep on the
+ * step running right now, and it answers "is this working or hung?" — a
+ * question no printed number can answer.
+ */
+export function stepRecord(steps: Step[], now: number): string[] {
+	return steps.map((step) => {
+		const label = padEnd(step.label, STEP_LABEL_WIDTH);
+		const time = dim(padStart(elapsed(stepDuration(step, now) ?? 0), 6));
+		return `${PAD}${stepMark(step, 0)}  ${label} ${time}  ${dim(step.detail)}`;
+	});
+}
+
+// -- the plan ----------------------------------------------------------------
+
+function pluginAction(item: PluginUpdateItem): ActionKey {
+	return item.action;
+}
+
+/** What the row says on its right: versions, never the action word again. */
+function pluginDetail(item: PluginUpdateItem): string {
+	// A note the row's own badge already states is noise, not information. The
+	// DEPRECATED chip and the heading above it both say "no configured
+	// marketplace offers this", so printing the sentence again put the longest
+	// string in the table on the least interesting rows.
+	//
+	// The note stays on the item. The TUI has no heading to lean on and renders
+	// it as that row's only explanation — this is a rendering decision about a
+	// table that carries the fact twice, not a change to what is known.
+	const note =
+		item.note && item.reason !== "not-offered"
+			? `  ${dim(`(${item.note})`)}`
+			: "";
+	switch (item.action) {
+		case "install":
+			return `${item.target ?? "latest"}${note}`;
+		case "update":
+			// The GROUP's page tone, not a literal and not ACTIONS: the arrow and
+			// the target sit in the same row as that group's glyph and chip, so
+			// they must resolve per page from the same place. A hardcoded tone
+			// here is how the row ended up half green and half amber.
+			return `${dim(item.installed ?? "—")} ${fg(
+				groupStyle("Update").text,
+				"→",
+			)} ${fg(groupStyle("Update").text, item.target ?? "?")}${note}`;
+		case "repair":
+		case "unknown":
+			return `${item.installed ?? "—"}${note}`;
+		case "current":
+			return `${item.installed ?? "—"}${note}`;
+	}
+}
+
+/**
+ * What a tool row says on its right.
+ *
+ * A `current` row used to print `pinned —` unconditionally, which was true only
+ * while "current" implied "pinned". An unpinned tool can be current now, so the
+ * pin is shown only when there is one.
+ */
+function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
+	const spec = plan.binSpecs.get(item.name);
+	// Rendered for the reader's eyes only — this row says what WILL run, while
+	// applyBins runs the argv itself. Same builder, so they cannot differ.
+	const cmd = spec ? binCommandFor(item, spec) : null;
+	const command = cmd ? dim(formatCommand(cmd)) : "";
+	switch (item.action) {
+		case "current":
+			return `${item.installed ?? "—"}${
+				item.version ? `  ${dim(`pinned ${item.version}`)}` : ""
+			}`;
+		case "upgrade":
+			return `${dim(item.installed ?? "—")} ${fg(
+				ACTIONS.upgrade.color,
+				"→",
+			)} ${fg(
+				ACTIONS.upgrade.color,
+				item.target ?? "?",
+			)}${command ? `  ${command}` : ""}${
+				// An upgrade that also changes the tool's owner says so here; a
+				// plain one reads identically to before.
+				item.adopted ? `  ${dim(`(${item.adopted})`)}` : ""
+			}`;
+		case "unknown":
+			return `${item.installed ?? "—"}${
+				item.note ? `  ${dim(`(${item.note})`)}` : ""
+			}`;
+		case "install":
+			return command;
+	}
+}
+
+/**
+ * A section: a stacked bar of the action mix, then one row per item.
+ *
+ * The bar is the section's whole story in one line — a reader who takes in
+ * nothing else knows whether this section is mostly settled or mostly work.
+ */
+/**
+ * Which heading a plugin row sits under.
+ *
+ * Read off the plan's machine codes — `action` and `reason` — never the human
+ * note. Five headings, and no more:
+ *
+ *   Update        something an apply would move forward
+ *   Deprecated    no configured marketplace offers it
+ *   Fix required  declared or enabled, with nothing on disk
+ *   Unverified    the check itself did not complete
+ *   Current       settled — the version was compared, or there was none to compare
+ *
+ * `Current` is last on purpose: it is the biggest group and the least
+ * interesting, and leading with it buries the few rows that need a decision.
+ *
+ * UNVERIFIED IS NOT CURRENT, and the two must not share a heading. A row whose
+ * catalog read failed used to land under `Current` carrying a `?` glyph and a
+ * note saying the catalog was unreachable — a row that contradicted the heading
+ * above it, while the closing notices insisted those rows are NOT reported as up
+ * to date. That is a different claim from "nothing could be compared, so we
+ * assume the install is the latest", which IS `current` and reaches it in the
+ * classifier, not here.
+ *
+ * "Unverified" is the word `summaryLine` already prints for this count; it is
+ * this report's existing vocabulary, not a new one.
+ */
+function pluginGroup(item: PluginUpdateItem): string {
+	if (item.action === "update" || item.action === "repair") return "Update";
+	if (item.action === "install") return "Fix required";
+	if (item.action === "unknown") {
+		return item.reason === "not-offered" ? "Deprecated" : "Unverified";
+	}
+	return "Current";
+}
+
+const GROUP_ORDER = [
+	"Update",
+	"Deprecated",
+	"Fix required",
+	"Unverified",
+	"Current",
+];
+
+/**
+ * Colour and emphasis per GROUP.
+ *
+ * "Dim the chrome, saturate the signal" is this file's own rule, stated at the
+ * top; the signal is the groups an apply would act on. Every colour comes from
+ * `brand`, which ui/theme.ts contrast-checks against BOTH a cream and a
+ * near-black terminal, so a light theme needs no second palette.
+ */
+const GROUP_KIND: Record<string, ReportBadgeKind> = {
+	Update: "update",
+	Deprecated: "deprecated",
+	"Fix required": "fix",
+};
+
+interface GroupStyle {
+	/** Heading and glyph, drawn on the page. */
+	text: string;
+	/** Badge fill and its ink. Absent on a chrome group, which carries no badge. */
+	fill?: string;
+	ink?: string;
+	chrome?: boolean;
+}
+
+/**
+ * A group's colours, for the page this run resolved.
+ *
+ * `reportBadge` answers per page — pale fill with deep ink on cream, saturated
+ * fill with pale ink on near-black — so this is the one place the report stops
+ * using a single set of hues for both. `brand` is still right for everything
+ * else here: those tokens are chosen to clear 3:1 as INK on either page, which
+ * is a different question from what a filled chip should look like.
+ */
+function groupStyle(group: string): GroupStyle {
+	const kind = GROUP_KIND[group];
+	if (!kind) return { text: brand.muted, chrome: true };
+	const ink = reportBadge(kind);
+	return { text: ink.text, fill: ink.fill, ink: ink.ink };
+}
+
+/** The badge's word: the heading, uppercased. Never a second vocabulary. */
+function groupBadge(group: string): string {
+	return group.toUpperCase();
+}
+
+/**
+ * Badge column width, from the labels THIS report shows — a run with nothing
+ * deprecated does not pay for the longest word. `width` ignores escape bytes,
+ * so measuring an already painted badge is safe.
+ */
+function badgeWidth(items: PluginUpdateItem[]): number {
+	return Math.max(
+		0,
+		...items
+			.filter((item) => !groupStyle(pluginGroup(item)).chrome)
+			.map((item) => {
+				const style = groupStyle(pluginGroup(item));
+				return (
+					width(
+						badge(
+							groupBadge(pluginGroup(item)),
+							style.fill ?? brand.muted,
+							style.ink,
+						),
+					) + 2
+				);
+			}),
+	);
+}
+
+function pluginRow(
+	item: PluginUpdateItem,
+	nameWidth: number,
+	chipWidth: number,
+): string {
+	const group = pluginGroup(item);
+	const style = groupStyle(group);
+	const name = padEnd(item.pluginId, nameWidth);
+	// Only an actionable row is badged; a chrome row gets the same width in
+	// spaces, so every version still starts in one column.
+	const chip = padEnd(
+		style.chrome
+			? ""
+			: badge(groupBadge(group), style.fill ?? brand.muted, style.ink),
+		chipWidth,
+	);
+	return `${PAD}${fg(style.text, ACTIONS[item.action].glyph)}  ${
+		style.chrome ? dim(name) : name
+	}  ${chip}${pluginDetail(item)}`;
+}
+
+/** The Plugins section: grouped by state, `Current` last. */
+function pluginSection(items: PluginUpdateItem[], nameWidth: number): string[] {
+	if (items.length === 0) return [];
+
+	const byGroup = new Map<string, PluginUpdateItem[]>();
+	for (const item of items) {
+		const group = pluginGroup(item);
+		const list = byGroup.get(group);
+		if (list) list.push(item);
+		else byGroup.set(group, [item]);
+	}
+
+	// GROUP_ORDER first, then anything it does not name. A report may never
+	// silently drop a row: driving the output purely from a fixed list would
+	// render an unexpected group as nothing at all while the header still
+	// counted it.
+	const ordered = [
+		...GROUP_ORDER.filter((g) => byGroup.has(g)),
+		...[...byGroup.keys()].filter((g) => !GROUP_ORDER.includes(g)),
+	];
+
+	const chipWidth = badgeWidth(items);
+	// No bar: it stacked the mix into one strip above groups that already print
+	// their own counts, in a form nobody can read a number off.
+	const lines: string[] = [
+		"",
+		`${PAD}${bold("Plugins")}  ${dim(String(items.length))}`,
+	];
+
+	for (const group of ordered) {
+		const rows = byGroup.get(group);
+		if (!rows || rows.length === 0) continue;
+		lines.push(
+			"",
+			`${PAD}${bold(fg(groupStyle(group).text, group))}  ${dim(
+				String(rows.length),
+			)}`,
+		);
+		for (const row of rows) lines.push(pluginRow(row, nameWidth, chipWidth));
+	}
+
+	return lines;
+}
+
+function section(
+	title: string,
+	rows: Array<{ action: ActionKey; name: string; detail: string }>,
+	nameWidth: number,
+): string[] {
+	if (rows.length === 0) return [];
+	const counts = new Map<ActionKey, number>();
+	for (const row of rows)
+		counts.set(row.action, (counts.get(row.action) ?? 0) + 1);
+	const legend = [...counts]
+		.map(([action, n]) =>
+			fg(ACTIONS[action].color, `${n} ${ACTIONS[action].label.toLowerCase()}`),
+		)
+		.join(dim(" · "));
+
+	return [
+		"",
+		`${PAD}${bold(padEnd(title, 9))} ${dim(
+			padStart(String(rows.length), 3),
+		)}  ${legend}`,
+		"",
+		...rows.map(
+			(row) =>
+				`${PAD}${glyph(row.action)}  ${rowText(
+					row.action,
+					padEnd(row.name, nameWidth),
+				)}  ${chip(row.action)}  ${row.detail}`,
+		),
+	];
+}
+
+export function planReport(plan: UpdatePlan): string[] {
+	const nameWidth = Math.max(
+		12,
+		...plan.plugins.map((p) => width(p.pluginId)),
+		...plan.bins.map((b) => width(b.name)),
+		...plan.skills.map((s) => width(s.name)),
+	);
+
+	// EVERY planned plugin gets a row. There is no filter here and there must
+	// not be one.
+	//
+	// A previous revision dropped `unknown` + `not-offered` + not-installed rows
+	// — a pin naming a plugin no marketplace offers — on the grounds that a
+	// notice named them instead. That notice did not exist: the function the
+	// comment cited was never written. The row appeared in no table and no
+	// notice, while the closing lines still counted it and said "Reasons are
+	// shown above", pointing at nothing.
+	//
+	// A report may never silently drop a row. That is the whole defect this
+	// file's grouping was written to end, and a filter here reintroduces it in a
+	// form that is harder to see, because the header count agrees with the rows
+	// and only the plan knows something is missing.
+	return [
+		...pluginSection(plan.plugins, nameWidth),
+		...section(
+			"CLI",
+			plan.bins.map((item: BinUpdateItem) => ({
+				action: item.action as ActionKey,
+				name: item.name,
+				detail: binDetail(item, plan),
+			})),
+			nameWidth,
+		),
+		...section(
+			"Skills",
+			plan.skills.map((item: SkillUpdateItem) => ({
+				action: item.action as ActionKey,
+				name: item.name,
+				detail: dim(`${item.ref.repo}/${item.ref.path}`),
+			})),
+			nameWidth,
+		),
+	];
+}
+
+// -- apply -------------------------------------------------------------------
+
+export interface ApplyState {
+	/** Items finished, of `total`. */
+	done: number;
+	total: number;
+	/** What is being worked on right now. */
+	current: string;
+	startedAt: number;
+}
+
+/**
+ * The animated apply frame: a gradient meter that turns green as it fills.
+ *
+ * The meter's ramp encodes POSITION along the fill, which is what a smooth
+ * gradient is for — the count beside it is the label, not the signal.
+ */
+export function applyFrame(
+	state: ApplyState,
+	tick: number,
+	now: number,
+): string[] {
+	const pct = state.total === 0 ? 100 : (state.done / state.total) * 100;
+	const count = `${state.done}/${state.total}`;
+	return [
+		"",
+		`${PAD}${fg(brand.accent, spinner(tick))}  ${meter(pct, BAR * 2)} ${padStart(
+			count,
+			7,
+		)}  ${fg(brand.accent, state.current)}  ${dim(
+			elapsed(now - state.startedAt),
+		)}`,
+	];
+}
+
+/** One finished item, written permanently above the meter. */
+export function applyRow(
+	ok: boolean,
+	name: string,
+	nameWidth: number,
+	detail: string,
+	ms: number,
+): string {
+	const mark = ok ? fg(brand.success, "✓") : fg(brand.danger, "✗");
+	return `${PAD}${mark}  ${padEnd(name, nameWidth)}  ${detail}  ${dim(
+		padStart(elapsed(ms), 7),
+	)}`;
+}
+
+/**
+ * Closing line: the run's shape as a bar, then the counts that label it.
+ *
+ * `unchanged` is its own count: an installer that exited 0 while read-back
+ * shows nothing moved. Folding it into `changed` is how every run printed
+ * "3 changed" while changing nothing; it is not a failure either.
+ */
+export function summaryLine(
+	changed: number,
+	current: number,
+	unknown: number,
+	failed: number,
+	ms: number,
+	unchanged = 0,
+): string[] {
+	const bar = stackedBar(BAR * 2, [
+		{ value: changed, color: brand.success },
+		{ value: current, color: brand.muted },
+		{ value: unchanged + unknown, color: brand.warning },
+		{ value: failed, color: brand.danger },
+	]);
+	const parts = [
+		changed > 0 ? fg(brand.success, `${changed} changed`) : "",
+		unchanged > 0 ? fg(brand.warning, `${unchanged} unchanged`) : "",
+		current > 0 ? dim(`${current} current`) : "",
+		unknown > 0 ? fg(brand.warning, `${unknown} unverified`) : "",
+		failed > 0 ? fg(brand.danger, `${failed} failed`) : "",
+	].filter(Boolean);
+	return [
+		"",
+		`${PAD}${bar}  ${parts.join(dim(" · "))}  ${dim(elapsed(ms))}`,
+		"",
+	];
+}
+
+// -- one-off notices ---------------------------------------------------------
+
+export function ok(text: string): string {
+	return `${PAD}${fg(brand.success, "✓")}  ${text}`;
+}
+
+export function warn(text: string): string {
+	return `${PAD}${fg(brand.warning, "⚠")}  ${text}`;
+}
+
+export function fail(text: string): string {
+	return `${PAD}${fg(brand.danger, "✗")}  ${text}`;
+}
+
+export function info(text: string): string {
+	return `${PAD}${fg(brand.info, "›")}  ${text}`;
+}
+
+export function note(text: string): string {
+	return `${PAD}   ${dim(text)}`;
+}
+
+// -- unverified items ----------------------------------------------------------
+//
+// A plugin is `unknown` for several distinct reasons — its marketplace publishes
+// no version, the two versions cannot be ordered, no marketplace offers it, its
+// marketplace was not read, or the catalog fetch failed — and every row above
+// already prints its own. These lines therefore claim only what holds for EVERY
+// reason. They once advised "re-run once the catalog is reachable", which is
+// false for a plugin whose marketplace publishes no version: re-running changes
+// nothing, and the reader went looking for a network fault that did not exist.
+
+/** Unverified tools, under the plan. */
+export function unknownToolsNotice(count: number, names: string[]): string {
+	return warn(
+		`${bold(String(count))} tool(s) could not be checked: ${names.join(", ")} — not applied. Reasons are shown above.`,
+	);
+}
+
+/**
+ * `--check` is about to exit 0 while N items went unchecked.
+ *
+ * The gate does not fail on an unknown — plugin or tool — because most unknowns
+ * are permanent (a marketplace that publishes no version, a tool another npm
+ * owns), and a gate that can never pass protects nothing. This line is what
+ * keeps the exit 0 honest: it is "nothing is KNOWN to be behind", not
+ * "everything was verified". It counts plugins and tools together because the
+ * two per-kind notices above already name which is which.
+ */
+export function uncheckedGateNotice(count: number): string {
+	return warn(
+		`${bold(String(count))} item(s) could not be checked — they do not fail this gate. They are NOT reported as up to date. Reasons are shown above.`,
+	);
+}
+
+/** The run ends with nothing to apply because every remaining plugin is unverified. */
+export function nothingToApplyNotice(unknownPlugins: number): string {
+	return warn(
+		`Nothing to apply. ${unknownPlugins} plugin(s) could not be checked. They are NOT reported as up to date. Reasons are shown above.`,
+	);
+}