magus-cli 7.6.0 → 7.8.0

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,44 +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. */
-	lines(unchanged: readonly string[]): string;
+	/**
+	 * The popup for `failed` and then `unchanged`, in that order; null when
+	 * both are empty.
+	 */
+	report(
+		failed: readonly string[],
+		actions?: ReadonlyMap<string, PluginUpdateAction>,
+		unchanged?: readonly string[],
+	): FailureReport | null;
 } {
-	const why = new Map<string, string>();
+	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: (unchanged) =>
-			unchanged
-				.map((name) => {
-					const reason = why.get(name);
-					return reason ? `${name}: ${reason}` : name;
-				})
-				.join("\n"),
+		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,
+				})),
+			]),
 	};
 }
 
@@ -281,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) {
@@ -337,6 +605,7 @@ export function buildPluginBrowserItems({
 						expandedPlugins,
 						pluginContents,
 						statuses,
+						mcpSettingsNeeded,
 					);
 				}
 			}
@@ -375,6 +644,7 @@ export function buildPluginBrowserItems({
 							expandedPlugins,
 							pluginContents,
 							statuses,
+							mcpSettingsNeeded,
 						);
 					}
 				}
@@ -407,6 +677,7 @@ export function buildPluginBrowserItems({
 					expandedPlugins,
 					pluginContents,
 					statuses,
+					mcpSettingsNeeded,
 				);
 			}
 		}

package/src/ui/adapters/startupReports.ts

@@ -0,0 +1,282 @@
+/**
+ * The failure popup's words for everything outside the Plugins screen's apply
+ * paths: the profile gate at startup, a profile activation, the startup
+ * repairs (stale plugin loads, marketplace refreshes, gitignore fixes) and the
+ * Git State screen. Each is a pure builder over what the service returned, on
+ * top of {@link failureReport}, so they read like every other failure.
+ *
+ * Each returns null when nothing failed: success says nothing, because the
+ * screen shows it.
+ */
+
+import type { StaleLoadRepairResult } from "../../services/claude-settings.js";
+import type { ActivationResult } from "../../services/profile-activate.js";
+import { SettingsParseError } from "../../services/settings-file.js";
+import { pluginName } from "../../services/update-engine.js";
+import { userFacingPath, withUserFacingPath } from "../../utils/user-path.js";
+import type { FailureReport, FailureRow } from "../state/types.js";
+import {
+	counted,
+	failureReport,
+	mergeFailureReports,
+} from "./failureReport.js";
+import { exceptionReason, pluginFailureReport } from "./pluginsAdapter.js";
+
+/** `run magus install` → `Run magus install`. */
+function sentence(text: string): string {
+	return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+
+/**
+ * One line the profile gate refused on, as a row. The gate words them
+ * "<file> cannot be read (<why>) — fix it by hand; magus left it as it is and
+ * did not switch": the file is the subject, the instruction the fix, and the
+ * rest the reason. A line of another shape is about the profile itself.
+ */
+export function profileProblemRow(problem: string): FailureRow {
+	const dash = problem.indexOf(" — ");
+	const head = dash >= 0 ? problem.slice(0, dash) : problem;
+	const tail = dash >= 0 ? problem.slice(dash + 3) : "";
+	const file = /^(\S+) (cannot be read\b.*)$/.exec(head);
+	const subject = file?.[1] ?? "profile";
+	let reason = file?.[2] ?? head;
+	let fix: string | undefined;
+	if (tail) {
+		const [instruction = "", ...rest] = tail.split("; ");
+		fix = sentence(instruction);
+		if (rest.length > 0) reason = `${reason} — ${rest.join("; ")}`;
+	}
+	return fix ? { subject, reason, fix } : { subject, reason };
+}
+
+/**
+ * H2: what the startup gate refused — `prepareProfileStartup(...).problems`.
+ * Shown before the profile question, which it does not replace: the question
+ * is still asked about whatever is left.
+ */
+export function profileProblemsReport(
+	problems: readonly string[],
+	headline = "This project's profile was not brought up to date",
+): FailureReport | null {
+	return failureReport(headline, problems.map(profileProblemRow));
+}
+
+/**
+ * H3: what a profile activation could not do, from its {@link
+ * ActivationResult}s — the startup re-render or format update, the startup
+ * choice, a Profiles-tab switch. ONE builder for all of them.
+ *
+ * Listed: plugins that will not load because the profile turns a dependency
+ * off; plugins whose dependencies could not be read because they are not
+ * downloaded; skills that did not install, with why; a skill that exists in
+ * two copies, saying which was kept and what to do. Everything else an
+ * activation reports is either done or shown as the screen's state.
+ */
+export function activationFailureReport(
+	results: ReadonlyArray<ActivationResult | null | undefined>,
+): FailureReport | null {
+	const rows: FailureRow[] = [];
+	const seen = new Set<string>();
+	const add = (row: FailureRow) => {
+		const key = `${row.subject}\u0000${row.reason}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		rows.push(row);
+	};
+	let profile: string | null = null;
+
+	for (const result of results) {
+		if (!result) continue;
+		profile ??= result.profileId;
+		for (const { plugin, dependency } of result.dependencies?.blocked ?? []) {
+			add({
+				subject: pluginName(plugin),
+				reason: `will not load: it depends on ${pluginName(dependency)}, which profile "${result.profileId}" turns off`,
+				fix: `Remove "${dependency}": false from the profile to let it load`,
+			});
+		}
+		for (const plugin of result.dependencies?.unreadable ?? []) {
+			add({
+				subject: pluginName(plugin),
+				reason:
+					"is not downloaded on this machine, so nothing it depends on was turned on",
+				fix: "Run magus install",
+			});
+		}
+		for (const f of result.skills.failed) {
+			add({
+				subject: `skill ${f.skill}`,
+				reason: `was not installed: ${exceptionReason(f.reason).reason}`,
+			});
+		}
+		for (const c of result.conversion.conflicts) {
+			add({
+				subject: `skill ${c.folder}`,
+				reason: `exists in two copies: ${c.kept} is the one in use, the other is at ${c.other}`,
+				fix: "Compare the two and delete the one you do not want",
+			});
+		}
+	}
+	if (rows.length === 0) return null;
+	return failureReport(
+		`Profile "${profile}" is active, but ${counted(rows.length, "thing")} did not work`,
+		rows,
+	);
+}
+
+/** The headline when the startup gate and the re-render both have something. */
+export const PROFILE_STARTUP_HEADLINE =
+	"This project's profile was not fully brought up to date";
+
+/**
+ * R8: everything the startup profile gate could not do, as ONE popup — what
+ * it refused ({@link profileProblemsReport}) and what its activation could not
+ * do ({@link activationFailureReport}). Both come from the same startup step,
+ * so they are one event: two popups in a row made the user dismiss twice for
+ * one thing. Either alone keeps its own headline.
+ */
+export function profileStartupReport(
+	problems: readonly string[],
+	activations: ReadonlyArray<ActivationResult | null | undefined>,
+): FailureReport | null {
+	return mergeFailureReports(PROFILE_STARTUP_HEADLINE, [
+		profileProblemsReport(problems),
+		activationFailureReport(activations),
+	]);
+}
+
+/**
+ * H4: the startup "Repair plugins" — each repair that did not bring the
+ * installed version forward, with its own reason.
+ */
+export function staleRepairReport(
+	results: readonly StaleLoadRepairResult[],
+): FailureReport | null {
+	return pluginFailureReport(
+		results
+			.filter((r) => !r.ok)
+			.map((r) => ({
+				pluginId: r.pluginId,
+				verb: "repaired" as const,
+				detail:
+					r.error ??
+					`Claude Code still does not load v${r.target} in this folder`,
+			})),
+	);
+}
+
+/** The fix for a settings file that does not parse: magus will not write over it. */
+export const FIX_BY_HAND = "Fix the file by hand, then try again";
+
+/**
+ * A thrown error from a whole step, as ONE row about `subject`.
+ *
+ * The reason is the error's first line. A cause magus recognises carries its
+ * own fix: no `claude` (a `spawn … claude ENOENT` included), no network, or a
+ * settings file that does not parse. That last one is about the FILE, so the
+ * file is the row's subject — named the way the user knows it
+ * (`.claude/settings.json`, `~/.claude/settings.json`), never by absolute path
+ * — because fixing it by hand is the only way on. `fallbackFix` is the fix for
+ * anything else: the command to run yourself, say. Without one, an
+ * unrecognised error has no fix line, because there is no real action to offer.
+ */
+export function stepFailureReport(
+	headline: string,
+	subject: string,
+	error: unknown,
+	fallbackFix?: string,
+): FailureReport {
+	if (error instanceof SettingsParseError) {
+		const detail = withUserFacingPath(
+			exceptionReason(error.detail).reason,
+			error.path,
+		);
+		return {
+			headline,
+			rows: [
+				{
+					subject: userFacingPath(error.path),
+					reason: `${error.problem} (${detail})`,
+				},
+			],
+			fix: FIX_BY_HAND,
+		};
+	}
+	const e = exceptionReason(
+		error instanceof Error ? error.message : String(error),
+	);
+	return {
+		headline,
+		rows: [{ subject, reason: e.reason }],
+		fix: e.fix ?? fallbackFix ?? null,
+	};
+}
+
+/**
+ * M8: marketplaces whose refresh failed after startup re-registered them.
+ * Until one refreshes, its plugins are read from a copy that may be old.
+ */
+export function marketplaceRefreshReport(
+	failures: ReadonlyArray<{ marketplace: string; error: unknown }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failures.length, "marketplace")} could not be refreshed`,
+		failures.map(({ marketplace, error }) => {
+			const e = exceptionReason(
+				error instanceof Error ? error.message : String(error),
+			);
+			return {
+				subject: marketplace,
+				reason: e.reason,
+				...(e.fix ? { fix: e.fix } : {}),
+			};
+		}),
+	);
+}
+
+/**
+ * M9: generated files the startup gitignore fix could not untrack, each with
+ * git's own reason.
+ */
+export function gitignoreStartupReport(
+	failed: ReadonlyArray<{ path: string; reason: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failed.length, "generated file")} ${failed.length === 1 ? "is" : "are"} still tracked by git`,
+		failed.map((f) => ({
+			subject: f.path,
+			reason: exceptionReason(f.reason).reason,
+		})),
+	);
+}
+
+/** Git State fixes that did not apply, each with its reason. */
+export function gitignoreFixReport(
+	failed: ReadonlyArray<{ path: string; message: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failed.length, "fix", "fixes")} did not apply`,
+		failed.map((f) => ({
+			subject: f.path,
+			reason: exceptionReason(f.message).reason,
+		})),
+	);
+}
+
+/**
+ * M9: template rules a merge skipped because they contradict a rule the
+ * manifest already has. They are not in the list, so this is the only place
+ * the user learns of them.
+ */
+export function gitignoreTemplateReport(
+	template: string,
+	conflicts: readonly string[],
+): FailureReport | null {
+	return failureReport(
+		`${counted(conflicts.length, "rule")} from "${template}" ${conflicts.length === 1 ? "was" : "were"} not added`,
+		conflicts.map((pattern) => ({
+			subject: pattern,
+			reason: "skipped: conflicts with existing rules",
+		})),
+	);
+}