magus-cli 7.7.0 → 7.9.0

package/src/cli/deps-view.ts

@@ -0,0 +1,213 @@
+/**
+ * The terminal rendering of plugin dependencies: doctor's report section, the
+ * consent list, live progress, and the result of an apply. `magus doctor` and
+ * `magus install` both render through here; `--json` and the TUI render the
+ * same `ApplyOutcome[]` their own way.
+ */
+
+import {
+	type ApplyEvent,
+	type ApplyOutcome,
+	DepsLockBusy,
+	type DepsPlan,
+	type PathAdvice,
+	type PlanEnv,
+	applyDepsPlan,
+	defaultLockPath,
+	planLines,
+	requiredByOf,
+} from "../services/deps-plan.js";
+import type { DepsState } from "../services/deps-report.js";
+import { installText } from "../services/doctor-bins.js";
+import {
+	type Os,
+	type Presence,
+	doctorFixCommand,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import { askYesNo } from "./prompt.js";
+import { question } from "./update-view.js";
+
+function presenceLine(name: string, p: Presence, by: string): string | null {
+	switch (p.status) {
+		case "present":
+			return null;
+		case "missing":
+			return `  ✗ ${name} — missing${p.blockedBy ? ` (needs ${p.blockedBy} first)` : ""}  (${by})`;
+		case "off-path":
+			return `  ⚠ ${name} — installed in ${p.prefix}, which is not on the PATH Claude Code starts with  (${by})`;
+		case "unknown":
+			return `  ⚠ ${name} — could not tell: ${p.reason}  (${by})`;
+	}
+}
+
+/**
+ * doctor's "Plugin dependencies" section. Counts what `--fix` can and cannot
+ * act on. `projectDir` is `--project`'s directory, named in the fix line.
+ */
+export function depsSectionLines(
+	state: DepsState,
+	env: PlanEnv,
+	projectDir: string | null = null,
+): { lines: string[]; fixable: number; unfixable: number } {
+	const { collected, presences, plan } = state;
+	const lines: string[] = [];
+	let unfixable = 0;
+	collected.bins.forEach((bin, i) => {
+		const p = presences[i] as Presence;
+		const line = presenceLine(bin.name, p, requiredByOf(bin).join(", "));
+		if (!line) return;
+		lines.push(line);
+		if (p.status === "missing")
+			lines.push(`      fix: ${installText(bin, env)}`);
+		if (p.status === "off-path") unfixable++;
+	});
+	for (const problem of collected.problems) {
+		lines.push(
+			problem.kind === "invalid"
+				? `  ✗ ${problem.plugin} — its dependency declaration is invalid (${problem.errors.join("; ")}) — please report it to the plugin's author`
+				: `  ✗ ${problem.plugin} — ${problem.errors.join("; ")}`,
+		);
+		unfixable++;
+	}
+	for (const u of plan.unfixable) {
+		lines.push(`  ✗ ${u.name} — ${u.why}`);
+		unfixable++;
+	}
+	if (plan.steps.length > 0) {
+		lines.push(`    Fix: ${doctorFixCommand(projectDir)}`);
+	}
+	lines.push(...pathAdviceLines(plan.pathAdvice));
+	if (lines.length === 0 && collected.bins.length > 0) {
+		lines.push(`  ✓ All ${collected.bins.length} plugin dependencies present.`);
+	}
+	return {
+		lines: lines.length > 0 ? ["Plugin dependencies:", ...lines] : [],
+		fixable: plan.steps.length,
+		unfixable,
+	};
+}
+
+/** A box with a title, for the two blocks a person must act on. */
+function box(title: string, body: string[]): string[] {
+	return [`  ┌─ ${title}`, ...body.map((l) => `  │ ${l}`), "  └─"];
+}
+
+/** The PATH lines to add, ending with the restart. Empty when none. */
+export function pathAdviceLines(advice: readonly PathAdvice[]): string[] {
+	if (advice.length === 0) return [];
+	return box("DO THIS NEXT", [
+		...advice.map(
+			(a) =>
+				`${a.prefix} is not on your PATH: add  ${a.rcLine}  to ${a.rcFile}`,
+		),
+		"then restart Claude Code from a new terminal",
+	]);
+}
+
+const STATUS_TEXT: Record<ApplyOutcome["status"], string> = {
+	installed: "installed",
+	"off-path": "installed OFF the PATH Claude Code starts with",
+	failed: "failed",
+	"needs-password": "needs your sudo password",
+	"needs-root": "needs root",
+	blocked: "blocked",
+};
+
+/** The result of an apply: one row per step, then what needs the user. */
+export function renderApplyText(outcomes: readonly ApplyOutcome[]): string[] {
+	if (outcomes.length === 0) return [];
+	const width = Math.max(...outcomes.map((o) => o.name.length));
+	const mark = (o: ApplyOutcome) =>
+		o.status === "installed" ? "✓" : o.status === "off-path" ? "⚠" : "✗";
+	const lines = outcomes.map(
+		(o) =>
+			`  ${mark(o)} ${o.name.padEnd(width)}  ${STATUS_TEXT[o.status]}${o.dir ? ` (${o.dir})` : ""}${
+				o.durationMs > 0 ? `  ${(o.durationMs / 1000).toFixed(1)}s` : ""
+			}`,
+	);
+	const needs = outcomes.filter((o) => o.status !== "installed");
+	if (needs.length === 0) return lines;
+	const body: string[] = [];
+	for (const o of needs) {
+		body.push(
+			`${o.name}: ${STATUS_TEXT[o.status]}${o.dir ? ` — it is in ${o.dir}` : ""}`,
+		);
+		const last = o.outputTail.trim().split("\n").pop();
+		if (o.status === "failed" && last) body.push(`  ${last}`);
+		if (o.remedy) body.push(`  ${o.remedy}`);
+	}
+	return [...lines, ...box("NEEDS YOU", body)];
+}
+
+/** Live progress for a text apply, to stderr so stdout stays the report. */
+export function stderrProgress(e: ApplyEvent): void {
+	if (e.type === "step-start") {
+		process.stderr.write(`→ ${e.name}: ${e.describe}\n`);
+	} else if (e.type === "output") {
+		for (const line of e.chunk.split("\n")) {
+			if (line.trim()) process.stderr.write(`    ${line}\n`);
+		}
+	}
+}
+
+export interface FixDepsOptions {
+	yes: boolean;
+	/** Write progress and ask questions (text mode); false for `--json`. */
+	interactive: boolean;
+	/** For `--json` and tests: the lock path; defaults to the cache dir. */
+	lockPath?: string;
+	/** `--project`'s directory, named in a remedy's fix line. */
+	projectDir?: string | null;
+}
+
+export type FixDepsResult =
+	| { kind: "applied"; outcomes: ApplyOutcome[]; after: DepsState }
+	| { kind: "declined" }
+	| { kind: "busy"; message: string };
+
+/** The consent question's body: every step, once. */
+export function consentLines(plan: DepsPlan, os: Os): string[] {
+	return [
+		`Install ${plan.steps.length} plugin dependenc${plan.steps.length === 1 ? "y" : "ies"}:`,
+		...planLines(plan, os).map((l) => `  ${l}`),
+	];
+}
+
+/**
+ * The `--fix` flow, shared by doctor and install: list every step once, ask
+ * once (unless `yes`), apply, then re-assess from a fresh probe.
+ */
+export async function fixDeps(
+	state: DepsState,
+	env: PlanEnv,
+	opts: FixDepsOptions,
+	reassess: () => Promise<DepsState>,
+): Promise<FixDepsResult> {
+	try {
+		const outcomes = await applyDepsPlan(state.plan, {
+			yes: opts.yes,
+			env,
+			projectDir: opts.projectDir ?? null,
+			lockPath:
+				opts.lockPath ?? defaultLockPath(env.home, process.env.XDG_CACHE_HOME),
+			confirm: async (plan) => {
+				for (const line of consentLines(plan, env.os)) console.log(line);
+				return askYesNo(question("Install them now?"));
+			},
+			...(opts.interactive ? { onEvent: stderrProgress } : {}),
+		});
+		if (outcomes.length === 0 && state.plan.steps.length > 0) {
+			return { kind: "declined" };
+		}
+		return {
+			kind: "applied",
+			outcomes,
+			after: await reassess(),
+		};
+	} catch (error) {
+		if (error instanceof DepsLockBusy) {
+			return { kind: "busy", message: error.message };
+		}
+		throw error;
+	}
+}

package/src/cli/doctor.ts

@@ -1,10 +1,15 @@
 /**
- * `magus doctor [--fix]`
+ * `magus doctor [--json] [--fix] [--yes] [--project <dir>]`
  *
- * Diagnoses (and with --fix, repairs) project health:
+ * Diagnoses (and with --fix, repairs) the health of the project in the current
+ * directory, or in `--project`'s:
  *   0. Global settings — `~/.claude/settings.json` parses.
- *   1. Binary dependencies — every requires.bin / cliTools binary on PATH.
- *      This is the check that would have caught a dead `tmux-mcp`.
+ *   1. Plugin dependencies — what every plugin Claude Code loads here declares
+ *      in `requires` (plus the profiles' cliTools), probed with each
+ *      declaration's own check. `--fix` lists every install once, asks once
+ *      (`--yes` skips the question) and installs through the deps executor.
+ *      `--json` prints only this section, as one document on stdout, and
+ *      `--fix --json` repairs only this section: dependencies, nothing else.
  *   2. Profile state — which profile is active (strictly), what the next magus
  *      command would record or regenerate (with `--fix`, it does it now and
  *      says what it did), generated files git still tracks, and
@@ -21,6 +26,7 @@
  * them, because magus never rewrites a file it cannot parse.
  */
 
+import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import {
@@ -28,9 +34,16 @@ import {
 	getProjectInstalledPluginVersions,
 	readGlobalSettings,
 	readInstalledPluginsRegistry,
+	readLocalSettings,
 	readSettings,
 } from "../services/claude-settings.js";
-import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
+import type { PlanEnv } from "../services/deps-plan.js";
+import {
+	type DepsState,
+	assessDeps,
+	depsReportJson,
+} from "../services/deps-report.js";
+import { machineEnv } from "../services/doctor-bins.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import {
 	isAgentModelHookRegistered,
@@ -44,7 +57,9 @@ import {
 import { isBehind } from "../services/plugin-manager.js";
 import {
 	type RepoRootCache,
+	isRelevantInstallation,
 	pickLoadedEntry,
+	repoRootForPath,
 } from "../services/plugin-resolution.js";
 import { trackedGeneratedNotices } from "../services/profile-activate.js";
 import {
@@ -69,14 +84,59 @@ import {
 import { resolveAllProfiles } from "../services/resolver.js";
 import type {
 	ClaudeSettings,
+	InstalledPluginEntry,
 	InstalledPluginsRegistry,
 	ProfileManifest,
 } from "../types/index.js";
 import { resolveExecutable } from "../utils/command-utils.js";
+import { depsSectionLines, fixDeps, renderApplyText } from "./deps-view.js";
+
+/**
+ * `--project <dir>`: the directory to check, or null for the current one. A
+ * string `error` is a usage error to print.
+ */
+function projectOption(
+	args: string[],
+): { dir: string | null } | { error: string } {
+	const at = args.indexOf("--project");
+	if (at === -1) return { dir: null };
+	const value = args[at + 1];
+	if (value === undefined || value.startsWith("-")) {
+		return { error: "magus doctor --project needs a directory" };
+	}
+	const dir = path.resolve(value);
+	let isDir = false;
+	try {
+		isDir = fs.statSync(dir).isDirectory();
+	} catch {
+		// Absent: reported below like any other non-directory.
+	}
+	return isDir
+		? { dir }
+		: { error: `magus doctor --project: ${value} is not a directory` };
+}
 
 export async function runDoctorCommand(args: string[]): Promise<number> {
 	const fix = args.includes("--fix");
+	const yes = args.includes("--yes") || args.includes("-y");
+	const project = projectOption(args);
+	if ("error" in project) {
+		console.error(project.error);
+		return 2;
+	}
+	// Doctor checks the directory it runs in: the plugins enabled there, its
+	// profiles, and each check runs there as Claude Code runs a plugin's servers.
+	// `--project` moves it there, so every one of those reads the same directory.
+	if (project.dir !== null) process.chdir(project.dir);
 	const projectPath = process.cwd();
+	const env = machineEnv(
+		process.env.HOME || os.homedir(),
+		process.env.PATH ?? "",
+		process.env.SHELL ?? "",
+	);
+	if (args.includes("--json")) {
+		return runDepsJson(projectPath, env, { fix, yes, projectDir: project.dir });
+	}
 	let problems = 0;
 	// Findings `--fix` does not repair, counted apart so it cannot silence
 	// them — see doctorExitCode.
@@ -89,7 +149,17 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	const globalSettingsError = await checkGlobalSettings();
 	if (globalSettingsError) unfixable++;
 
-	// 1. Binary dependencies, which needs the manifest to know what to check.
+	// 1. Plugin dependencies.
+	if (env) {
+		const deps = await reportDeps(projectPath, env, {
+			fix,
+			yes,
+			projectDir: project.dir,
+		});
+		problems += deps.fixable;
+		unfixable += deps.unfixable;
+	}
+
 	let manifest: ProfileManifest | null = null;
 	try {
 		manifest = await readManifest(projectPath);
@@ -100,25 +170,11 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	}
 	let pluginIds: string[] = [];
 	if (manifest && Object.keys(manifest.profiles).length > 0) {
-		const closure = await resolveAllProfiles(manifest);
+		// Plugin ids only: the dependency section above read every requirement.
+		const closure = await resolveAllProfiles(manifest, {
+			binResolver: async () => [],
+		});
 		pluginIds = Object.keys(closure.plugins);
-		if (closure.bins.length > 0) {
-			const results = await checkBinaries(closure.bins);
-			const missing = missingBinaries(results);
-			if (missing.length > 0) {
-				console.log("Binary dependencies:");
-				for (const m of missing) {
-					console.log(
-						`  ✗ ${m.name} — run: ${m.installCommand}  (needed by ${m.sources.join(", ")})`,
-					);
-					problems++;
-				}
-			} else {
-				console.log(
-					`✓ All ${closure.bins.length} binary dependencies present.`,
-				);
-			}
-		}
 	}
 
 	// 2. Profile state.
@@ -179,6 +235,99 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	return doctorExitCode({ fixable: problems, unfixable, fix });
 }
 
+interface DoctorDepsFlags {
+	fix: boolean;
+	yes: boolean;
+	/** `--project`'s directory, named in every fix line doctor prints; else null. */
+	projectDir: string | null;
+}
+
+/**
+ * Section 1 in text: the report, and with `--fix` the install. After an
+ * install the report is printed again from a fresh probe, and whatever is
+ * still missing counts as a problem `--fix` could not solve.
+ */
+async function reportDeps(
+	projectPath: string,
+	env: PlanEnv,
+	flags: DoctorDepsFlags,
+): Promise<{ fixable: number; unfixable: number }> {
+	const state = await assessDeps(projectPath, env);
+	const before = depsSectionLines(state, env, flags.projectDir);
+	for (const line of before.lines) console.log(line);
+	if (!flags.fix || before.fixable === 0) return before;
+
+	console.log("");
+	const result = await fixDeps(
+		state,
+		env,
+		{ yes: flags.yes, interactive: true, projectDir: flags.projectDir },
+		() => assessDeps(projectPath, env),
+	);
+	if (result.kind === "busy") {
+		console.log(`  ✗ ${result.message}`);
+		return { fixable: 0, unfixable: before.fixable + before.unfixable };
+	}
+	if (result.kind === "declined") {
+		console.log("  Nothing installed.");
+		return { fixable: 0, unfixable: before.fixable + before.unfixable };
+	}
+	for (const line of renderApplyText(result.outcomes)) console.log(line);
+	const after = depsSectionLines(result.after, env, flags.projectDir);
+	console.log("");
+	for (const line of after.lines) console.log(line);
+	// Still missing after an install is not something a re-run of --fix fixes
+	// silently: it is a problem, counted so the exit code says so.
+	return { fixable: 0, unfixable: after.fixable + after.unfixable };
+}
+
+/**
+ * `--json`: only the dependency section, as one document on stdout and
+ * nothing else there. `--fix --json` needs `--yes`: with stdout carrying the
+ * document, there is nowhere to ask.
+ */
+async function runDepsJson(
+	projectPath: string,
+	env: PlanEnv | null,
+	flags: DoctorDepsFlags,
+): Promise<number> {
+	if (!env) {
+		console.error("magus doctor --json: this platform is not supported");
+		return 1;
+	}
+	if (flags.fix && !flags.yes) {
+		console.error(
+			"magus doctor --fix --json needs --yes: nothing can be asked while stdout carries the report",
+		);
+		return 2;
+	}
+	let state: DepsState = await assessDeps(projectPath, env);
+	let applied: ReturnType<typeof depsReportJson>["applied"];
+	if (flags.fix && state.plan.steps.length > 0) {
+		const result = await fixDeps(
+			state,
+			env,
+			{ yes: true, interactive: false, projectDir: flags.projectDir },
+			() => assessDeps(projectPath, env),
+		);
+		if (result.kind === "busy") {
+			console.error(result.message);
+			return 1;
+		}
+		if (result.kind === "applied") {
+			applied = result.outcomes;
+			state = result.after;
+		}
+	}
+	const report = depsReportJson(state, env, applied);
+	process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	const healthy =
+		report.deps.every((d) => d.status === "present") &&
+		report.invalid.length === 0 &&
+		report.plugins_needing_update.length === 0;
+	return healthy ? 0 : 1;
+}
+
 /**
  * A file that exists and does not parse, as a finding under `heading`.
  *
@@ -271,37 +420,140 @@ async function checkPluginLoads(projectPath: string): Promise<number> {
 		reportUnparseable("Plugin loads", error);
 		return 1;
 	}
+	let local: ClaudeSettings;
+	try {
+		local = await readLocalSettings(projectPath);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Plugin loads", error);
+		return 1;
+	}
+	// The global file's parse failure is section 0's finding, reported there;
+	// here it only means the user scope turns nothing on that we can see.
+	let global: ClaudeSettings = {};
+	try {
+		global = await readGlobalSettings();
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+	}
+	const enabled = enabledHere(global, settings, local);
 	const installed = await getProjectInstalledPluginVersions(
 		settings.installedPluginVersions || {},
 		projectPath,
 	);
-	const ids = Object.keys(installed);
+	// Counted as installed only when claimed HERE — the same rule
+	// `findPluginLoadProblems` applies to a plugin that loads nothing.
+	const cache: RepoRootCache = new Map();
+	const ids = Object.keys(installed).filter((id) =>
+		isClaimedHere(id, registry.plugins?.[id], projectPath, enabled, cache),
+	);
 	if (ids.length === 0) return 0;
 
-	// One cache across every plugin: the same handful of project paths repeat in
-	// hundreds of rows, and each miss walks the tree to the filesystem root.
-	const cache: RepoRootCache = new Map();
-	const stale: Array<{
+	const findings = findPluginLoadProblems(
+		installed,
+		registry.plugins,
+		projectPath,
+		enabled,
+	);
+	for (const line of pluginLoadLines(findings, ids.length)) console.log(line);
+	return findings.stale.length + findings.loadsNothing.length;
+}
+
+/** What `magus doctor`'s "Plugin loads" section found — see {@link findPluginLoadProblems}. */
+export interface PluginLoadFindings {
+	/** Installed here at one version, loading an older one. */
+	stale: Array<{
 		pluginId: string;
 		loaded: string;
 		recorded: string;
 		winner: string;
-	}> = [];
+	}>;
+	/**
+	 * Installed here, and Claude Code loads NO version of it in this folder.
+	 * Its own finding: counting it among the plugins that "load at their
+	 * installed version" reported a plugin that loads nothing as healthy.
+	 */
+	loadsNothing: string[];
+}
+
+/**
+ * `enabledPlugins` as it applies to this folder: user, then project, then
+ * local, a later scope overriding an earlier one — Claude Code's precedence.
+ */
+export function enabledHere(
+	...scopes: ReadonlyArray<Pick<ClaudeSettings, "enabledPlugins">>
+): Record<string, boolean> {
+	return Object.assign({}, ...scopes.map((s) => s.enabledPlugins ?? {}));
+}
+
+/**
+ * Does anything that APPLIES TO THIS FOLDER say the plugin is installed?
+ *
+ * Either a scope that applies here turns it on, or the registry holds a row
+ * the loader would consider here (`isRelevantInstallation` — the machine-wide
+ * scopes, this folder's own rows, and rows from the same repository). A row
+ * for some other project is not a claim about this folder: counting it made a
+ * stale `installedPluginVersions` entry plus an unrelated repo's install read
+ * as "installed here, loads nothing".
+ */
+export function isClaimedHere(
+	pluginId: string,
+	rows: readonly InstalledPluginEntry[] | undefined,
+	projectPath: string,
+	enabled: Readonly<Record<string, boolean>>,
+	cache: RepoRootCache = new Map(),
+): boolean {
+	if (enabled[pluginId] === true) return true;
+	if (!Array.isArray(rows) || rows.length === 0) return false;
+	const root = repoRootForPath(projectPath, cache);
+	return rows.some((row) =>
+		isRelevantInstallation(row, projectPath, root, cache),
+	);
+}
 
-	for (const pluginId of ids.sort()) {
+/**
+ * Compare what is installed here against what Claude Code will load here.
+ * Pure over its inputs, so the decision is pinned by a test rather than by a
+ * command that needs a real `~/.claude` to run.
+ *
+ * A plugin is only reported as loading nothing when something says it is
+ * INSTALLED HERE — see {@link isClaimedHere}: a scope that applies to this
+ * folder turns it on, or the registry holds a row relevant to this folder. A
+ * version in `installedPluginVersions` alone is not that — Claude Code never
+ * writes the field, so a claim with neither behind it is a leftover of
+ * magus's own, not an install that fails to load.
+ *
+ * @param installed      plugin id → the version recorded as installed here
+ * @param registryPlugins the registry's rows by plugin id
+ * @param enabled        `enabledPlugins` in the scopes that apply to this
+ *                       folder — see {@link enabledHere}
+ */
+export function findPluginLoadProblems(
+	installed: Readonly<Record<string, string>>,
+	registryPlugins: InstalledPluginsRegistry["plugins"] | undefined,
+	projectPath: string,
+	enabled: Readonly<Record<string, boolean>> = {},
+): PluginLoadFindings {
+	// One cache across every plugin: the same handful of project paths repeat in
+	// hundreds of rows, and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const findings: PluginLoadFindings = { stale: [], loadsNothing: [] };
+
+	for (const pluginId of Object.keys(installed).sort()) {
 		const recorded = installed[pluginId];
 		if (!recorded) continue;
-		const pick = pickLoadedEntry(
-			registry.plugins?.[pluginId],
-			projectPath,
-			cache,
-		);
-		if (!pick?.version) continue;
+		const rows = registryPlugins?.[pluginId];
+		const pick = pickLoadedEntry(rows, projectPath, cache);
+		if (!pick?.version) {
+			if (isClaimedHere(pluginId, rows, projectPath, enabled, cache))
+				findings.loadsNothing.push(pluginId);
+			continue;
+		}
 		// The same predicate the classifier uses, so doctor and the plugin screen
 		// cannot disagree about which pairs count. Unorderable pairs answer null
 		// and are left alone — "cannot tell" is not a finding.
 		if (isBehind(recorded, pick.version) !== true) continue;
-		stale.push({
+		findings.stale.push({
 			pluginId,
 			loaded: pick.version,
 			recorded,
@@ -310,28 +562,42 @@ async function checkPluginLoads(projectPath: string): Promise<number> {
 				(pick.scope === "user" ? "user scope (no project)" : "unknown project"),
 		});
 	}
+	return findings;
+}
 
-	console.log("\nPlugin loads:");
-	if (stale.length === 0) {
-		console.log(
-			`  ✓ All ${ids.length} installed plugins load at their installed version.`,
+/** The "Plugin loads" section's lines, for `total` plugins installed here. */
+export function pluginLoadLines(
+	findings: PluginLoadFindings,
+	total: number,
+): string[] {
+	const lines = ["", "Plugin loads:"];
+	if (findings.stale.length === 0 && findings.loadsNothing.length === 0) {
+		lines.push(
+			`  ✓ All ${total} installed plugins load at their installed version.`,
 		);
-		return 0;
+		return lines;
 	}
-
-	for (const row of stale) {
-		console.log(
+	for (const row of findings.stale) {
+		lines.push(
 			`  ✗ ${row.pluginId} — loads v${row.loaded}, installed v${row.recorded}`,
+			`      the entry that wins belongs to ${row.winner}`,
 		);
-		console.log(`      the entry that wins belongs to ${row.winner}`);
 	}
-	console.log(
-		"    Reinstalling does not fix this. Run `magus update` — it moves those",
-	);
-	console.log(
-		"    install records forward, backing up installed_plugins.json first.",
-	);
-	return stale.length;
+	if (findings.stale.length > 0) {
+		lines.push(
+			"    Reinstalling does not fix this. Run `magus update` — it moves those",
+			"    install records forward, backing up installed_plugins.json first.",
+		);
+	}
+	for (const pluginId of findings.loadsNothing) {
+		lines.push(
+			`  ✗ ${pluginId} is installed, but Claude Code loads no version of it in this folder`,
+		);
+	}
+	if (findings.loadsNothing.length > 0) {
+		lines.push("    Run `magus update` to fix it.");
+	}
+	return lines;
 }
 
 /**