magus-cli 0.0.0-placeholder → 7.0.0

package/src/cli/update-view.ts

@@ -0,0 +1,526 @@
+/**
+ * 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 { 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 },
+	update: { glyph: "↑", label: "UPDATE", color: brand.warning },
+	upgrade: { glyph: "↑", label: "UPGRADE", color: brand.warning },
+	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, with a duration bar per step.
+ *
+ * The bar is each step's share of the SLOWEST step, not of the total — the
+ * question a reader has when an update felt slow is "which part was it?", and
+ * shares of a total flatten to a uniform smear once there are four of them.
+ * Colour ramps green to red with that share, so the offender is the red one.
+ */
+export function stepRecord(steps: Step[], now: number): string[] {
+	const times = steps.map((s) => stepDuration(s, now) ?? 0);
+	const slowest = Math.max(1, ...times);
+	return steps.map((step, i) => {
+		const share = (times[i] / slowest) * 100;
+		const bar = meter(share, BAR, ramps.severity);
+		const label = padEnd(step.label, STEP_LABEL_WIDTH);
+		const time = dim(padStart(elapsed(times[i]), 6));
+		return `${PAD}${stepMark(step, 0)}  ${label} ${bar} ${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 {
+	const note = item.note ? `  ${dim(`(${item.note})`)}` : "";
+	switch (item.action) {
+		case "install":
+			return `${item.target ?? "latest"}${note}`;
+		case "update":
+			return `${dim(item.installed ?? "—")} ${fg(
+				brand.warning,
+				"→",
+			)} ${fg(brand.warning, 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(brand.warning, "→")} ${fg(
+				brand.warning,
+				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.
+ */
+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 bar = stackedBar(
+		BAR,
+		[...counts].map(([action, value]) => ({
+			value,
+			color: ACTIONS[action].color,
+		})),
+	);
+	const legend = [...counts]
+		.map(([action, n]) =>
+			fg(ACTIONS[action].color, `${n} ${ACTIONS[action].label.toLowerCase()}`),
+		)
+		.join(dim(" · "));
+
+	return [
+		"",
+		`${PAD}${bold(padEnd(title, 9))} ${bar} ${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)),
+	);
+
+	return [
+		...section(
+			"Plugins",
+			plan.plugins.map((item) => ({
+				action: pluginAction(item),
+				name: item.pluginId,
+				detail: pluginDetail(item),
+			})),
+			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 plugins, under the plan. Never "up to date" — that is the point. */
+export function unknownPluginsNotice(count: number): string {
+	return warn(
+		`${bold(String(count))} plugin(s) could not be checked — not applied. They are NOT reported as up to date. Reasons are shown above.`,
+	);
+}
+
+/** 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.`,
+	);
+}