magus-cli 7.7.0 → 7.9.0

package/src/ui/adapters/cliToolsAdapter.ts

@@ -17,7 +17,8 @@
  * Pure: no IO, no React. The screen gathers facts; this only assembles.
  */
 
-import type { CliTool } from "../../data/cli-tools.js";
+import path from "node:path";
+import type { CliTool, OwnedCatalogueEntry } from "../../data/cli-tools.js";
 import {
 	cliToolInstall,
 	cliToolUpdate,
@@ -30,14 +31,23 @@ import {
 	classifyTool,
 } 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 { Presence } from "../../shared/plugin/hooks/lib/requires-probe.js";
+import type {
+	ManagedBin,
+	ManagedTool,
+	ResolvedBin,
+} from "../../types/index.js";
+import { type Command, formatCommand } from "../../utils/command-utils.js";
+import type { RunResult } from "../../utils/run.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;
 	/** The requirement the tool was probed through (closure → detected → catalogue). */
-	spec: BinRequirement;
+	spec: ManagedTool;
 	/** True until facts arrive. */
 	checking: boolean;
 	/** Null while checking. */
@@ -52,25 +62,65 @@ export interface CliToolRow {
 	updateCommand?: Command;
 	/** What Enter runs for a tool that is not installed. */
 	installCommand: Command;
+	/**
+	 * For a tool a plugin owns: that plugin's requirement. Enter on a missing
+	 * one installs it through the deps executor, like `magus doctor --fix`.
+	 */
+	owned?: ResolvedBin;
+}
+
+/**
+ * A catalogue tool its plugin installs with an option magus does not version
+ * (a release, a Homebrew cask, apt): read-only. No Enter action, no update,
+ * no conflict fix — the row says which plugin manages it and whether it is
+ * here, from the same probe `magus doctor` runs.
+ */
+export interface PluginManagedRow {
+	/** The plugin that installs it: `<plugin>@<marketplace>`. */
+	managedBy: string;
+	entry: OwnedCatalogueEntry;
+	owned: ResolvedBin;
+	/** Null while checking. */
+	presence: Presence | null;
+	/** The plugin's install line, for display; `magus doctor --fix` runs it. */
+	installText: string;
+}
+
+/** A CLI Tools list row. */
+export type CliToolsRow = CliToolRow | PluginManagedRow;
+
+export const isPluginManagedRow = (row: CliToolsRow): row is PluginManagedRow =>
+	"managedBy" in row;
+
+/** The tool's catalogue name, whichever kind of row. */
+export function rowName(row: CliToolsRow): string {
+	return isPluginManagedRow(row) ? row.entry.name : row.tool.name;
+}
+
+/** On PATH or in a user prefix, as far as the row knows. */
+function rowInstalled(row: CliToolsRow): boolean {
+	if (!isPluginManagedRow(row)) return isInstalled(row.status);
+	const status = row.presence?.status;
+	return status === "present" || status === "off-path";
 }
 
 /**
  * Did this spec come from the resolver's closure — i.e. does the active profile
  * declare this tool?
  *
- * `ResolvedBin` is `BinRequirement` plus `sources`, and only the resolver adds
+ * `ManagedBin` is `ManagedTool` plus `sources`, and only the resolver adds
  * them, so the provenance travels with the spec itself rather than being
  * re-derived here (which would be a second copy of `specForCatalogTool`'s
  * branch 1, free to disagree with it).
  */
-function declaredSpec(spec: BinRequirement): ResolvedBin | null {
-	const candidate = spec as ResolvedBin;
+function declaredSpec(spec: ManagedTool): ManagedBin | null {
+	const candidate = spec as ManagedBin;
 	return Array.isArray(candidate.sources) ? candidate : null;
 }
 
 export function buildToolRow(
 	tool: CliTool,
-	spec: BinRequirement,
+	spec: ManagedTool,
 	facts: ToolFacts | undefined,
 	install?: InstallInfo,
 ): CliToolRow {
@@ -118,7 +168,7 @@ export function buildToolRow(
  */
 function updateCommandFor(
 	tool: CliTool,
-	declared: ResolvedBin | null,
+	declared: ManagedBin | null,
 	status: ToolStatus,
 	facts: ToolFacts,
 	install: InstallInfo | undefined,
@@ -233,7 +283,7 @@ export interface CliToolStatusText {
  * within 24. Keyed by reason alone — plus the spec's installer, which is a
  * word, never a path.
  */
-function unknownLabel(reason: ToolReason, via: BinRequirement["via"]): string {
+function unknownLabel(reason: ToolReason, via: ManagedTool["via"]): string {
 	switch (reason) {
 		case "not-managed":
 			return `not managed by ${via}`;
@@ -288,7 +338,7 @@ export function cliToolStatusText(row: CliToolRow): CliToolStatusText {
 }
 
 /** Header counts, from the rows' states. */
-export function countToolRows(rows: readonly CliToolRow[]): {
+export function countToolRows(rows: readonly CliToolsRow[]): {
 	installed: number;
 	updates: number;
 	unverified: number;
@@ -297,9 +347,199 @@ export function countToolRows(rows: readonly CliToolRow[]): {
 	let updates = 0;
 	let unverified = 0;
 	for (const row of rows) {
-		if (isInstalled(row.status)) installed++;
+		if (rowInstalled(row)) installed++;
+		if (isPluginManagedRow(row)) {
+			if (row.presence?.status === "unknown") unverified++;
+			continue;
+		}
 		if (row.status?.state === "upgrade") updates++;
 		if (row.status?.state === "unknown") unverified++;
 	}
 	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 its {@link RunResult}.
+ *
+ * The installer's own words are in its output: 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,
+	result: RunResult,
+	timeoutMs: number,
+): string {
+	const name = commandName(command);
+	if (result.spawnError?.includes("ENOENT")) {
+		return name === "claude"
+			? CLAUDE_MISSING_REASON
+			: `${name} is not installed on this machine`;
+	}
+	if (result.timedOut) {
+		return `did not finish within ${Math.round(timeoutMs / 1000)} seconds`;
+	}
+	const lines = result.outputTail
+		.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 =
+			result.spawnError ??
+			(result.exitCode !== null
+				? `${name} exited with code ${result.exitCode}`
+				: `${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/depsAdapter.ts

@@ -0,0 +1,129 @@
+/**
+ * Plugin dependencies in the TUI: the same plan and the same `ApplyOutcome[]`
+ * `magus doctor --fix` renders as text, rendered as a confirm modal and a
+ * failure popup.
+ *
+ * `installBinsInTui` is the one flow the Plugins screen (a plugin just
+ * installed) and the CLI Tools screen (a tool a plugin owns) both run:
+ * probe → `planDeps` → confirm listing every step → `applyDepsPlan` → popup.
+ */
+
+import { homedir } from "node:os";
+import {
+	type ApplyOutcome,
+	type DepsPlan,
+	applyDepsPlan,
+	defaultLockPath,
+	planLines,
+} from "../../services/deps-plan.js";
+import { assessBins } from "../../services/deps-report.js";
+import { machineEnv } from "../../services/doctor-bins.js";
+import type { ResolvedBin } from "../../types/index.js";
+import type { FailureReport, FailureRow } from "../state/types.js";
+import { counted, failureReport } from "./failureReport.js";
+
+const STATUS_REASON: Record<ApplyOutcome["status"], string> = {
+	installed: "installed",
+	"off-path": "installed, but not on the PATH Claude Code starts with",
+	failed: "the installer failed",
+	"needs-password": "needs your sudo password",
+	"needs-root": "needs root, and sudo is not available",
+	blocked: "what it needs was not installed",
+};
+
+/**
+ * What did not install, each with why and the exact command; then what can
+ * never be installed here; then the PATH lines. Null when there is nothing to
+ * say. The headline counts what needs the user.
+ */
+export function depsFailureReport(
+	subject: string,
+	outcomes: readonly ApplyOutcome[],
+	plan: Pick<DepsPlan, "unfixable" | "pathAdvice">,
+): FailureReport | null {
+	const rows: FailureRow[] = [];
+	for (const o of outcomes) {
+		if (o.status === "installed") continue;
+		const last = o.outputTail.trim().split("\n").pop()?.trim();
+		rows.push({
+			subject: o.name,
+			reason:
+				o.status === "failed" && last
+					? `${STATUS_REASON[o.status]}: ${last}`
+					: o.dir
+						? `${STATUS_REASON[o.status]}: it is in ${o.dir}`
+						: STATUS_REASON[o.status],
+			...(o.remedy ? { fix: o.remedy } : {}),
+		});
+	}
+	for (const u of plan.unfixable) {
+		rows.push({
+			subject: u.name,
+			reason: u.why,
+		});
+	}
+	for (const a of plan.pathAdvice) {
+		rows.push({
+			subject: a.prefix,
+			reason: "not on the PATH Claude Code starts with",
+			fix: `add ${a.rcLine} to ${a.rcFile}, then restart Claude Code from a new terminal`,
+		});
+	}
+	return failureReport(
+		`${counted(rows.length, "dependency of", "dependencies of")} ${subject} ${
+			rows.length === 1 ? "needs" : "need"
+		} you`,
+		rows,
+		{ group: false },
+	);
+}
+
+/** The part of the modal API the flow uses. */
+export interface DepsModal {
+	confirm(title: string, message: string): Promise<boolean>;
+	loading(message: string): void;
+	hideModal(): void;
+	failures(report: FailureReport): Promise<void>;
+}
+
+/** Probe, plan, ask once, install, and report — for `bins` of `subject`. */
+export async function installBinsInTui(
+	subject: string,
+	bins: ResolvedBin[],
+	modal: DepsModal,
+): Promise<void> {
+	const env = machineEnv(
+		process.env.HOME || homedir(),
+		process.env.PATH ?? "",
+		process.env.SHELL ?? "",
+	);
+	if (!env || bins.length === 0) return;
+	const { plan } = await assessBins(
+		{ plugins: [subject], bins, problems: [] },
+		env,
+	);
+	let outcomes: ApplyOutcome[] = [];
+	if (plan.steps.length > 0) {
+		const ok = await modal.confirm(
+			"Install Dependencies?",
+			`${subject} needs:\n\n${planLines(plan, env.os).join("\n")}\n\nInstall now?`,
+		);
+		if (!ok) return;
+		modal.loading("Installing dependencies...");
+		try {
+			outcomes = await applyDepsPlan(plan, {
+				yes: true,
+				confirm: async () => true,
+				env,
+				lockPath: defaultLockPath(env.home, process.env.XDG_CACHE_HOME),
+				onEvent: (e) => {
+					if (e.type === "step-start") modal.loading(`Installing ${e.name}...`);
+				},
+			});
+		} finally {
+			modal.hideModal();
+		}
+	}
+	const report = depsFailureReport(subject, outcomes, plan);
+	if (report) await modal.failures(report);
+}

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