magus-cli 7.7.0 → 7.8.0

package/src/ui/adapters/failureReport.ts

@@ -0,0 +1,137 @@
+/**
+ * THE failure popup's words, for every screen and every kind of subject.
+ *
+ * The TUI shows no status lines, notices or success messages: a screen reloads
+ * and shows state. What the user must KNOW because something failed — or must
+ * ACT on — goes into ONE popup (`modal.failures`, `FailureListModal`), and its
+ * shape is built here: a headline, one row per thing that failed (a plugin, a
+ * marketplace, a skill, a file, the profile), and the one fix when every row
+ * shares it. Pure, so the words are tested without a renderer.
+ *
+ * Each domain has a builder on top of {@link failureReport} —
+ * `pluginFailureReport` (pluginsAdapter.ts), `activationFailureReport` and the
+ * startup and Git State builders (startupReports.ts) — so they all read the
+ * same way.
+ */
+
+import type { FailureReport, FailureRow } from "../state/types.js";
+
+/**
+ * A fix a reason names at its end — "… — run magus install", "… — fix it by
+ * hand". Taken off the reason and carried as the row's fix, so it is said once
+ * (under the rows when every row shares it) rather than inside every reason.
+ */
+const FIX_CLAUSE =
+	/ — ((?:run|update it|ask them|fix it|remove|install|check|compare|commit)\b.*)$/;
+
+/** `run magus install` → `Run magus install`. */
+function sentence(text: string): string {
+	return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+
+/**
+ * An executable named by absolute path — `/usr/local/bin/npm`,
+ * `/Users/someone/.local/bin/claude` — is the mechanism: which copy the
+ * machine happened to find. The user knows it by its name.
+ */
+const BINARY_PATH = /(?:\/[^\s'"/:]+)+\/bin\/([\w.-]+)/g;
+
+/** Every absolute binary path in `text` replaced by the binary's name. */
+export function withoutBinaryPaths(text: string): string {
+	return text.replace(BINARY_PATH, "$1");
+}
+
+/**
+ * Split a reason into what went wrong and what to do about it, when the reason
+ * ends in a fix clause ({@link FIX_CLAUSE}). A row's own `fix` wins.
+ */
+export function splitFix(row: FailureRow): FailureRow {
+	if (row.fix) return row;
+	const match = FIX_CLAUSE.exec(row.reason);
+	if (!match?.[1]) return row;
+	return {
+		subject: row.subject,
+		reason: row.reason.slice(0, match.index).trim() || row.reason,
+		fix: sentence(match[1]),
+	};
+}
+
+export interface FailureReportOptions {
+	/**
+	 * Merge rows whose reason AND fix are identical into one row naming every
+	 * subject (default true). A caller with its own grouping rules — the plugin
+	 * builder keeps unexplained exceptions apart — passes false.
+	 */
+	group?: boolean;
+}
+
+/**
+ * The popup for `rows`, headed by `headline`; null when nothing failed — a
+ * success says nothing, because the reloaded screen shows it.
+ *
+ * Fixes: a fix clause at the end of a reason becomes the row's fix. When every
+ * row has the same fix, it is the report's `fix`, said once under the rows,
+ * and taken off each row; otherwise each row keeps its own (or none).
+ */
+export function failureReport(
+	headline: string,
+	rows: readonly FailureRow[],
+	opts: FailureReportOptions = {},
+): FailureReport | null {
+	if (rows.length === 0) return null;
+	let out = rows.map(splitFix);
+
+	if (opts.group !== false) {
+		const grouped: FailureRow[] = [];
+		const byKey = new Map<string, FailureRow>();
+		for (const row of out) {
+			const key = `${row.reason}\u0000${row.fix ?? ""}`;
+			const existing = byKey.get(key);
+			if (existing) {
+				existing.subject = `${existing.subject}, ${row.subject}`;
+				continue;
+			}
+			const copy = { ...row };
+			byKey.set(key, copy);
+			grouped.push(copy);
+		}
+		out = grouped;
+	}
+
+	const [first] = out;
+	const shared =
+		first?.fix && out.every((row) => row.fix === first.fix) ? first.fix : null;
+	if (shared) {
+		out = out.map(({ fix: _fix, ...row }) => row);
+	}
+	return { headline, rows: out, fix: shared };
+}
+
+/**
+ * Several reports about ONE event, as one popup under `headline` — so a user
+ * reads one list, not two popups in a row. A single report passes through
+ * with its own headline; none is null.
+ *
+ * Each report's shared fix goes back onto its own rows first, so no row loses
+ * its fix; the merged report then says a fix once again only when every row
+ * shares it.
+ */
+export function mergeFailureReports(
+	headline: string,
+	reports: ReadonlyArray<FailureReport | null | undefined>,
+): FailureReport | null {
+	const present = reports.filter((r): r is FailureReport => !!r);
+	const [only] = present;
+	if (present.length <= 1) return only ?? null;
+	const rows = present.flatMap((report) =>
+		report.rows.map((row) =>
+			row.fix || !report.fix ? row : { ...row, fix: report.fix },
+		),
+	);
+	return failureReport(headline, rows, { group: false });
+}
+
+/** `1 plugin`, `3 plugins`. */
+export function counted(n: number, noun: string, plural = `${noun}s`): string {
+	return `${n} ${n === 1 ? noun : plural}`;
+}

package/src/ui/adapters/pluginsAdapter.ts

@@ -1,10 +1,26 @@
 import type { PluginInfo } from "../../services/plugin-manager.js";
 import type { PluginComponent } from "../../services/skills-manager.js";
-import type { ApplyReporter } from "../../services/update-engine.js";
-import type { PluginUpdateItem } from "../../services/update-plan.js";
+import {
+	type ApplyReporter,
+	type FinishCause,
+	pluginName,
+} from "../../services/update-engine.js";
+import type {
+	PluginUpdateAction,
+	PluginUpdateItem,
+} from "../../services/update-plan.js";
 import type { Marketplace } from "../../types/index.js";
-import type { PluginContentsEntry } from "../state/types.js";
+import type {
+	FailureReport,
+	FailureRow,
+	PluginContentsEntry,
+} from "../state/types.js";
 import type { BadgeTone } from "../theme.js";
+import {
+	failureReport,
+	splitFix,
+	withoutBinaryPaths,
+} from "./failureReport.js";
 
 // Virtual marketplace name for the community sub-section of claude-plugins-official
 export const COMMUNITY_VIRTUAL_MARKETPLACE =
@@ -46,6 +62,12 @@ export interface PluginPluginItem {
 	 * declared by the profile nor installed): it has no state to claim.
 	 */
 	status: PluginUpdateItem | null;
+	/**
+	 * How many variables its MCP server references and nothing sets — from
+	 * current config (`missingPluginEnvVars`), so it is gone once they are set.
+	 * Absent means none, or not checked.
+	 */
+	mcpSettingsNeeded?: number;
 }
 
 /**
@@ -98,6 +120,8 @@ export interface BuildPluginBrowserItemsArgs {
 	pluginContents?: Map<string, PluginContentsEntry>;
 	/** `classifyPluginRows` output, by plugin id. A plugin absent from it gets no status. */
 	statuses?: ReadonlyMap<string, PluginUpdateItem>;
+	/** Plugin id → variables its MCP server still needs; see `mcpSettingsNeeded`. */
+	mcpSettingsNeeded?: ReadonlyMap<string, number>;
 }
 
 /**
@@ -123,10 +147,12 @@ function pushPluginItems(
 	expandedPlugins: Set<string>,
 	pluginContents: Map<string, PluginContentsEntry>,
 	statuses: ReadonlyMap<string, PluginUpdateItem>,
+	mcpSettingsNeeded: ReadonlyMap<string, number>,
 ): void {
 	const repo = pluginContentsRepo(plugin, marketplace);
 	const isExpandable = !plugin.isOrphaned && !!repo;
 	const isExpanded = isExpandable && expandedPlugins.has(plugin.id);
+	const needed = mcpSettingsNeeded.get(plugin.id) ?? 0;
 
 	items.push({
 		id: `pl:${plugin.id}`,
@@ -136,6 +162,7 @@ function pushPluginItems(
 		isExpandable,
 		isExpanded,
 		status: statuses.get(plugin.id) ?? null,
+		...(needed > 0 ? { mcpSettingsNeeded: needed } : {}),
 	});
 
 	if (!isExpanded) return;
@@ -229,63 +256,284 @@ function isMadAppGang(mp: Marketplace): boolean {
 	return (mp.source.repo ?? "").toLowerCase().startsWith("madappgang/");
 }
 
-// ─── "Ran, but nothing moved" ─────────────────────────────────────────────────
+// ─── "It failed, and here is why" ────────────────────────────────────────────
+
+/** A version token — `v2.0.3`, `8.1.3`, `1.0.0-beta.2`. */
+const VERSION = String.raw`v?\d+(?:\.\d+)+(?:[-+][0-9A-Za-z.-]+)?`;
+
+/**
+ * Where a version sat in a reason, and the noun that keeps the sentence true
+ * without it. Checked in order; the last is the fallback.
+ */
+const VERSION_NOUNS: ReadonlyArray<[RegExp, string]> = [
+	[
+		new RegExp(`^${VERSION} is not downloaded`),
+		"that version is not downloaded",
+	],
+	[new RegExp(`\\binstalled ${VERSION}`, "g"), "installed the new version"],
+	[
+		new RegExp(`\\bstill loads ${VERSION}`, "g"),
+		"still loads an older version",
+	],
+	[new RegExp(`\\bnow loads ${VERSION}`, "g"), "now loads the new version"],
+	[
+		new RegExp(`\\bdoes not load ${VERSION}`, "g"),
+		"does not load the installed version",
+	],
+	[new RegExp(`\\bis still ${VERSION}`, "g"), "is still on the same version"],
+	[new RegExp(`\\bwent to ${VERSION}`, "g"), "went to another version"],
+	[
+		new RegExp(`\\bnot the ${VERSION} this update asked for`, "g"),
+		"not the one this update asked for",
+	],
+	[new RegExp(VERSION, "g"), "another version"],
+];
+
+/**
+ * A reason with each version number replaced by a noun that keeps it true —
+ * the grouping key, and the shared line's words when the plugins in a group
+ * sit at different versions. "installed v2.0.6, but Claude Code still loads
+ * v2.0.3 in this folder" and the same at v1.4.0 are one reason, said as
+ * "installed the new version, but Claude Code still loads an older version in
+ * this folder". Deleting the versions instead produced "still loads in this
+ * folder", which is not a sentence about anything.
+ */
+export function reasonWithoutVersions(reason: string): string {
+	let out = reason;
+	for (const [pattern, noun] of VERSION_NOUNS) out = out.replace(pattern, noun);
+	return out.replace(/\s{2,}/g, " ").trim();
+}
+
+/**
+ * What a plugin failure did not do: the headline's verb. `repaired` is the
+ * startup "Repair plugins", which brings a stale load forward and installs
+ * nothing.
+ */
+export type FailureVerb = "installed" | "updated" | "removed" | "repaired";
+
+/** The verb for a plan action — an install, a removal, or anything that updates. */
+export function failureVerb(
+	action: PluginUpdateAction | undefined,
+): FailureVerb {
+	if (action === "install") return "installed";
+	if (action === "remove") return "removed";
+	return "updated";
+}
+
+/** One plugin that failed, as the engine reported it. */
+export interface PluginFailure {
+	pluginId: string;
+	verb: FailureVerb;
+	/** The engine's reason — the SAME string `magus update` prints for it. */
+	detail: string;
+	/** The detail is a thrown error's message, not a reason the engine worded. */
+	exception?: boolean;
+	/**
+	 * The command ran and exited cleanly, but nothing moved — the engine's
+	 * `unchanged`, detail "no change — …". Not an error, and not a change
+	 * either: the plugin was not updated, which is what the popup says.
+	 */
+	unchanged?: boolean;
+}
+
+/** The fix for a machine with no `claude` on PATH — said once, not per row. */
+export const INSTALL_CLAUDE_FIX =
+	"Install Claude Code: npm install -g @anthropic-ai/claude-code";
+/** The fix for a transient network failure. */
+export const RETRY_NETWORK_FIX = "Check your network connection and try again";
+
+/** A row's reason when there is no `claude` to run — one wording everywhere. */
+export const CLAUDE_MISSING_REASON = "claude CLI not found in PATH";
+
+/**
+ * No `claude` to run, in each shape it arrives: magus's own PATH lookup, and
+ * the spawn failing because the binary is gone — Node's `spawn <path> ENOENT`,
+ * Bun's `Executable not found in $PATH`.
+ */
+const CLAUDE_MISSING =
+	/^claude CLI not found in PATH|^spawn (?:\S*\/)?claude ENOENT\b|^Executable not found in \$PATH: "?claude"?$/i;
+const NETWORK =
+	/\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|network|Could not resolve host)\b/i;
+
+/**
+ * An unexpected exception, as a row: its first line only — no stack, no raw
+ * command output — and, for the kinds magus recognises, the fix. `known` is
+ * true for those kinds: a machine-wide cause (no `claude`, no network) is the
+ * same failure for every plugin it hits, so they may share a row; an
+ * exception magus cannot explain keeps a row of its own.
+ */
+export function exceptionReason(message: string): {
+	reason: string;
+	fix?: string;
+	known: boolean;
+} {
+	const first = withoutBinaryPaths(message.split("\n")[0]?.trim() || "failed");
+	if (CLAUDE_MISSING.test(first)) {
+		// The message carries its own install hint; the fix line says it, once.
+		return {
+			reason: CLAUDE_MISSING_REASON,
+			fix: INSTALL_CLAUDE_FIX,
+			known: true,
+		};
+	}
+	if (NETWORK.test(first)) {
+		return { reason: first, fix: RETRY_NETWORK_FIX, known: true };
+	}
+	return { reason: first, known: false };
+}
+
+/**
+ * The engine's "no change — …" detail for an item that ran and did not move,
+ * in the user's terms: the same fact `magus update` lists under "N item(s) ran
+ * but did not change", without "the installer exited 0".
+ */
+export function unchangedReason(detail: string): string {
+	let text = detail.replace(/^no change — /, "");
+	let note = "";
+	const paren = /\s\((.*)\)$/.exec(text);
+	if (paren) {
+		note = paren[1] ?? "";
+		text = text.slice(0, paren.index);
+	}
+	text = text
+		.replace(
+			/^the installer exited 0 but \S+ is still (\S+)$/,
+			(_, v: string) =>
+				`it ran, but it is still ${v.startsWith("v") ? v : `v${v}`}`,
+		)
+		.replace(
+			/^the installer exited 0 but no version of \S+ was recorded$/,
+			"it ran, but no installed version of it can be found afterwards",
+		);
+	return note ? `${text}; ${note}` : text;
+}
 
 /**
- * Collect the engine's no-move reasons so the screen can name them.
+ * THE plugin failure popup's words — for `a`, a single update, a scope key,
+ * a removal and a repair alike, so every apply path on the Plugins screen
+ * reports a failure the same way. Null when nothing failed: a success says
+ * nothing, because the reloaded rows show it.
  *
- * `ApplyResult.unchanged` is the whole point of the read-back: an item that
- * ran, exited 0, and left the machine exactly as it was. The CLI prints
- * `N item(s) ran but did not change:` with each cause; the TUI used to branch
- * on `failed.length` alone, show a success, and refetch a row that had not
- * moved — "press U, press U, forever", which is the experience the read-back
- * was added to remove.
+ * Each reason is the engine's, which is the string the CLI prints on that
+ * item's `✗` line, so the two front ends name the same cause in the same
+ * words. Plugins failing for the same reason share a row (versions replaced by
+ * nouns when they differ). An exception keeps only its first line; one magus
+ * recognises (no `claude`, no network) carries its fix and shares a row with
+ * the same message, one it cannot explain keeps a row of its own. An item that
+ * ran and changed nothing is "not updated", with the reason it did not move.
+ */
+export function pluginFailureReport(
+	failures: readonly PluginFailure[],
+): FailureReport | null {
+	if (failures.length === 0) return null;
+
+	interface Group {
+		names: string[];
+		reasons: string[];
+		fix?: string;
+	}
+	const rows: Group[] = [];
+	const groups = new Map<string, Group>();
+	const add = (
+		key: string | null,
+		name: string,
+		reason: string,
+		fix?: string,
+	) => {
+		const group = key === null ? undefined : groups.get(key);
+		if (group) {
+			group.names.push(name);
+			group.reasons.push(reason);
+			return;
+		}
+		const created: Group = { names: [name], reasons: [reason], fix };
+		if (key !== null) groups.set(key, created);
+		rows.push(created);
+	};
+
+	for (const f of failures) {
+		const name = pluginName(f.pluginId);
+		if (f.exception) {
+			const e = exceptionReason(f.detail);
+			add(e.known ? `exception:${e.reason}` : null, name, e.reason, e.fix);
+			continue;
+		}
+		const split = splitFix({
+			subject: name,
+			reason: f.unchanged ? unchangedReason(f.detail) : f.detail,
+		});
+		const key = `${reasonWithoutVersions(split.reason)}\u0000${split.fix ?? ""}`;
+		add(key, name, split.reason || "failed", split.fix);
+	}
+
+	const out: FailureRow[] = rows.map((group) => {
+		const [first = ""] = group.reasons;
+		const reason = group.reasons.every((r) => r === first)
+			? first
+			: reasonWithoutVersions(first);
+		return {
+			subject: group.names.join(", "),
+			reason: reason || "failed",
+			...(group.fix ? { fix: group.fix } : {}),
+		};
+	});
+
+	const verbs = [...new Set(failures.map((f) => f.verb))];
+	const [only] = failures;
+	const headline =
+		failures.length === 1 && only
+			? `${pluginName(only.pluginId)} was not ${only.verb}`
+			: `${failures.length} plugins were not ${verbs.join(" or ")}`;
+	return failureReport(headline, out, { group: false });
+}
+
+/**
+ * Collect why each plugin in one apply failed, for {@link pluginFailureReport}.
  *
- * The cause itself only ever reaches the reporter (`applyPlugins` formats it as
- * `no change — <why>`), so this captures it there, exactly as `cli/update.ts`
- * does with `finishedDetail`.
+ * `applyPlugins` passes each item's detail to `report.finish` — already in the
+ * user's terms, the same string the CLI prints. Only failures and items that
+ * ran without changing are reported: a success shows as the plugin's new
+ * state once the screen reloads.
  */
-export function noMoveReasons(): {
+export function failureReasons(): {
 	reporter: ApplyReporter;
 	/**
-	 * One line per unchanged item, with its cause when one was reported, so one
-	 * plugin's reason never runs into the next. The screen posts
-	 * {@link notice} instead; this is the per-item form it is built from.
+	 * The popup for `failed` and then `unchanged`, in that order; null when
+	 * both are empty.
 	 */
-	lines(unchanged: readonly string[]): string[];
-	/**
-	 * The same, as ONE notice line, or null when nothing was unchanged. "Update
-	 * all" can leave many plugins where they were, and a line each would fill
-	 * the banner and push out whatever else it had to say. So several become
-	 * `3 plugins unchanged — a, b, c`, with the cause only when they all share
-	 * it; one keeps its own cause.
-	 */
-	notice(unchanged: readonly string[]): string | null;
+	report(
+		failed: readonly string[],
+		actions?: ReadonlyMap<string, PluginUpdateAction>,
+		unchanged?: readonly string[],
+	): FailureReport | null;
 } {
-	const why = new Map<string, string>();
-	const lines = (unchanged: readonly string[]): string[] =>
-		unchanged.map((name) => {
-			const reason = why.get(name);
-			return reason ? `${name}: ${reason}` : name;
-		});
+	const why = new Map<string, { detail: string; cause?: FinishCause }>();
 	return {
 		reporter: {
 			begin: () => {},
-			finish: (_ok, name, detail) => {
-				const reason = detail.replace(/^no change — /, "");
-				if (reason !== detail) why.set(name, reason);
+			finish: (_ok, name, detail, _ms, cause) => {
+				why.set(name, { detail, cause });
 			},
 			detach: (work) => work(),
 		},
-		lines,
-		notice: (unchanged) => {
-			if (unchanged.length === 0) return null;
-			if (unchanged.length === 1) return `No change: ${lines(unchanged)[0]}`;
-			const reasons = new Set(unchanged.map((name) => why.get(name)));
-			const [shared] = reasons;
-			const cause = reasons.size === 1 && shared ? `: ${shared}` : "";
-			return `${unchanged.length} plugins unchanged — ${unchanged.join(", ")}${cause}`;
-		},
+		report: (failed, actions, unchanged = []) =>
+			pluginFailureReport([
+				...failed.map((pluginId) => {
+					const captured = why.get(pluginId);
+					return {
+						pluginId,
+						verb: failureVerb(actions?.get(pluginId)),
+						detail: captured?.detail ?? "",
+						exception: captured?.cause === "exception",
+					};
+				}),
+				...unchanged.map((pluginId) => ({
+					pluginId,
+					verb: failureVerb(actions?.get(pluginId)),
+					detail: why.get(pluginId)?.detail ?? "",
+					unchanged: true,
+				})),
+			]),
 	};
 }
 
@@ -300,6 +548,7 @@ export function buildPluginBrowserItems({
 	expandedPlugins = new Set(),
 	pluginContents = new Map(),
 	statuses = new Map(),
+	mcpSettingsNeeded = new Map(),
 }: BuildPluginBrowserItemsArgs): PluginBrowserItem[] {
 	const pluginsByMarketplace = new Map<string, PluginInfo[]>();
 	for (const plugin of plugins) {
@@ -356,6 +605,7 @@ export function buildPluginBrowserItems({
 						expandedPlugins,
 						pluginContents,
 						statuses,
+						mcpSettingsNeeded,
 					);
 				}
 			}
@@ -394,6 +644,7 @@ export function buildPluginBrowserItems({
 							expandedPlugins,
 							pluginContents,
 							statuses,
+							mcpSettingsNeeded,
 						);
 					}
 				}
@@ -426,6 +677,7 @@ export function buildPluginBrowserItems({
 					expandedPlugins,
 					pluginContents,
 					statuses,
+					mcpSettingsNeeded,
 				);
 			}
 		}