magus-cli 7.6.0 → 7.8.0

package/src/ui/adapters/cliToolsAdapter.ts

@@ -17,6 +17,7 @@
  * Pure: no IO, no React. The screen gathers facts; this only assembles.
  */
 
+import path from "node:path";
 import type { CliTool } from "../../data/cli-tools.js";
 import {
 	cliToolInstall,
@@ -31,8 +32,11 @@ import {
 } from "../../services/tool-probe.js";
 import { binCommandForState } from "../../services/toolchain.js";
 import type { BinRequirement, ResolvedBin } from "../../types/index.js";
-import type { Command } from "../../utils/command-utils.js";
+import { type Command, formatCommand } from "../../utils/command-utils.js";
 import type { StatusTone } from "../renderers/pluginStatusText.js";
+import type { FailureReport } from "../state/types.js";
+import { counted, failureReport, withoutBinaryPaths } from "./failureReport.js";
+import { CLAUDE_MISSING_REASON, exceptionReason } from "./pluginsAdapter.js";
 
 export interface CliToolRow {
 	tool: CliTool;
@@ -303,3 +307,201 @@ export function countToolRows(rows: readonly CliToolRow[]): {
 	}
 	return { installed, updates, unverified };
 }
+
+// ─── Failures ────────────────────────────────────────────────────────────────
+//
+// Every installer command that fails goes into the failure popup with why and
+// the command to run by hand. Update-all used to discard them: the reload
+// showed the tool still behind, with no reason anywhere.
+
+/**
+ * The verb for what an Enter action did not do — "installed", "updated",
+ * "reinstalled". The caller writes the headline around it:
+ * `${tool} was not ${cliToolNotDone(kind)}`.
+ */
+export function cliToolNotDone(kind: CliToolEnterAction["kind"]): string {
+	if (kind === "install") return "installed";
+	if (kind === "reinstall") return "reinstalled";
+	return "updated";
+}
+
+/** One installer command that did not succeed. */
+export interface CliToolCommandFailure {
+	/** The tool's display name. */
+	tool: string;
+	command: Command;
+	/** Why, in {@link commandFailureReason}'s words. */
+	reason: string;
+}
+
+/** The longest reason kept from an installer's own output. */
+const MAX_REASON = 160;
+
+/**
+ * npm's bookkeeping lines, which never say why: the error code and syscall
+ * fields, and where its log went.
+ */
+const INSTALLER_NOISE =
+	/^(?:code|errno|syscall|path|dest)\b|^(?:A complete log of this run|Log files were not written|You can rerun|For a full report see)\b/i;
+
+/**
+ * The name a user knows a command by: `/usr/local/bin/npm` → `npm`. Which
+ * copy of npm the machine found is mechanism, never part of a reason.
+ */
+function commandName(command: Command): string {
+	return path.basename(command.cmd) || command.cmd;
+}
+
+/** How a timeout reads, so its fix can be told apart from an ordinary failure. */
+const TIMED_OUT_REASON = /^did not finish within \d+ seconds$/;
+
+/**
+ * The fix for a timeout. Not "Run it yourself": the same command would take
+ * just as long. A slow download is the usual cause, so it names the network
+ * without claiming that is what happened.
+ */
+export const RETRY_TIMEOUT_FIX =
+	"Try again; if it keeps timing out, check your network connection";
+
+/**
+ * Why an installer command failed, as ONE line, from what `execFile` threw.
+ *
+ * The thrown message's first line is "Command failed: <the command>", which
+ * says nothing the fix line does not. The installer's own words are in its
+ * stderr: the text after an `error:` (npm, brew and cargo all say it that
+ * way), else its first line that is not bookkeeping. A missing installer and
+ * a timeout are said plainly — a missing `claude` in the words every other
+ * screen uses for it. No absolute binary path survives into the reason.
+ */
+export function commandFailureReason(
+	command: Command,
+	error: unknown,
+	timeoutMs: number,
+): string {
+	if (!(error instanceof Error)) {
+		return withoutBinaryPaths(String(error).split("\n")[0]?.trim() || "failed");
+	}
+	const e = error as Error & {
+		code?: unknown;
+		killed?: boolean;
+		signal?: unknown;
+		stderr?: unknown;
+	};
+	const name = commandName(command);
+	if (e.code === "ENOENT") {
+		return name === "claude"
+			? CLAUDE_MISSING_REASON
+			: `${name} is not installed on this machine`;
+	}
+	if (e.killed || e.signal === "SIGTERM") {
+		return `did not finish within ${Math.round(timeoutMs / 1000)} seconds`;
+	}
+	const lines = String(e.stderr ?? "")
+		.split("\n")
+		.map((line) => line.replace(/^npm (?:ERR!|error)\b/i, "").trim())
+		.filter((line) => line !== "" && !INSTALLER_NOISE.test(line));
+	const said = lines.find((line) => /\berror:\s*\S/i.test(line));
+	let reason = said
+		? said.slice(said.toLowerCase().lastIndexOf("error:") + 6).trim()
+		: (lines[0] ?? "");
+	if (!reason) {
+		reason =
+			typeof e.code === "number"
+				? `${name} exited with code ${e.code}`
+				: e.message
+						.split("\n")[0]
+						?.replace(/^Command failed: .*$/, "")
+						.trim() || `${name} failed`;
+	}
+	reason = withoutBinaryPaths(reason);
+	return reason.length > MAX_REASON
+		? `${reason.slice(0, MAX_REASON - 1)}…`
+		: reason;
+}
+
+/**
+ * The fix for one failed installer command.
+ *
+ * Usually the command itself, to run by hand. Not for the three causes that
+ * running the same command again would not cure: a timeout, no `claude` to
+ * run, and no network. Each keeps the fix that does help.
+ */
+export function commandFailureFix(command: Command, reason: string): string {
+	if (TIMED_OUT_REASON.test(reason)) return RETRY_TIMEOUT_FIX;
+	const known = exceptionReason(reason);
+	if (known.fix) return known.fix;
+	return `Run it yourself: ${formatCommand(command)}`;
+}
+
+/** The popup for failed installer commands, each with the fix that helps. */
+export function cliToolFailureReport(
+	headline: string,
+	failures: readonly CliToolCommandFailure[],
+): FailureReport | null {
+	return failureReport(
+		headline,
+		failures.map((f) => ({
+			subject: f.tool,
+			reason: f.reason,
+			fix: commandFailureFix(f.command, f.reason),
+		})),
+		{ group: false },
+	);
+}
+
+/** Update-all: the tools whose update command failed. */
+export function cliToolsNotUpdatedReport(
+	failures: readonly CliToolCommandFailure[],
+): FailureReport | null {
+	const n = failures.length;
+	return cliToolFailureReport(
+		`${counted(n, "tool")} ${n === 1 ? "was" : "were"} not updated`,
+		failures,
+	);
+}
+
+/**
+ * A conflict magus cannot resolve: the tool is installed more than one way
+ * and none of the installs can be removed from here.
+ */
+export function cliToolConflictStuckReport(
+	tool: string,
+	blockers: ReadonlyArray<{ method: string; reason: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${tool} is installed ${blockers.length} ways, and magus can remove none of them`,
+		blockers.map(({ method, reason }) => ({
+			subject: `${method} install`,
+			reason,
+			fix: "Remove one by hand, then press r",
+		})),
+		{ group: false },
+	);
+}
+
+/**
+ * A conflict resolved only in part: each removal that failed, with the
+ * command to run by hand, and each install magus could never remove.
+ */
+export function cliToolConflictPartialReport(
+	tool: string,
+	failed: ReadonlyArray<{ method: string; command: Command; reason: string }>,
+	leftBehind: ReadonlyArray<{ method: string; reason: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${tool} is still installed more than one way`,
+		[
+			...failed.map((f) => ({
+				subject: `${f.method} install`,
+				reason: `was not removed: ${f.reason}`,
+				fix: `Run it yourself: ${formatCommand(f.command)}`,
+			})),
+			...leftBehind.map(({ method, reason }) => ({
+				subject: `${method} install`,
+				reason: `stays: ${reason}`,
+				fix: "Remove it by hand if you want it gone",
+			})),
+		],
+		{ group: false },
+	);
+}

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}`;
+}