magus-cli 7.7.0 → 7.8.0

package/src/cli/doctor.ts

@@ -28,6 +28,7 @@ import {
 	getProjectInstalledPluginVersions,
 	readGlobalSettings,
 	readInstalledPluginsRegistry,
+	readLocalSettings,
 	readSettings,
 } from "../services/claude-settings.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
@@ -44,7 +45,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,6 +72,7 @@ import {
 import { resolveAllProfiles } from "../services/resolver.js";
 import type {
 	ClaudeSettings,
+	InstalledPluginEntry,
 	InstalledPluginsRegistry,
 	ProfileManifest,
 } from "../types/index.js";
@@ -271,37 +275,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[];
+}
 
-	for (const pluginId of ids.sort()) {
+/**
+ * `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),
+	);
+}
+
+/**
+ * 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 +417,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;
 }
 
 /**

package/src/cli/install.ts

@@ -44,7 +44,10 @@ import {
 	binInstallCommand,
 	detectToolchains,
 } from "../services/toolchain.js";
-import { bringLoadForward } from "../services/update-engine.js";
+import {
+	bringLoadForward,
+	describeLoadNotForward,
+} from "../services/update-engine.js";
 import type { ResolvedBin, ResolvedClosure } from "../types/index.js";
 import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
 import { runCommand, runShellScript } from "../utils/run.js";
@@ -210,11 +213,7 @@ async function bringLoadsForward(
 				} moved forward)`,
 			);
 		} else {
-			console.warn(
-				`⚠ ${pluginId}: installed v${here}, but Claude Code still loads v${
-					forward.loaded ?? "an older version"
-				} here — ${forward.error ?? "the older records could not be moved forward"}`,
-			);
+			console.warn(`⚠ ${pluginId}: ${describeLoadNotForward(forward)}`);
 		}
 	}
 }

package/src/cli/update-view.ts

@@ -27,11 +27,12 @@
  */
 
 import { binCommandFor } from "../services/update-engine.js";
-import type {
-	BinUpdateItem,
-	PluginUpdateItem,
-	SkillUpdateItem,
-	UpdatePlan,
+import {
+	type BinUpdateItem,
+	type PluginUpdateItem,
+	type SkillUpdateItem,
+	type UpdatePlan,
+	isKeptDeprecated,
 } from "../services/update-plan.js";
 import { type ReportBadgeKind, reportBadge } from "../ui/theme-mode.js";
 import { brand } from "../ui/theme.js";
@@ -84,6 +85,7 @@ type ActionKey =
 	| "repair"
 	| "refresh"
 	| "stale-load"
+	| "remove"
 	| "unknown";
 
 const ACTIONS: Record<ActionKey, ActionStyle> = {
@@ -101,6 +103,10 @@ const ACTIONS: Record<ActionKey, ActionStyle> = {
 	// a mild version of `repair`, and this is not that. Six characters, one under
 	// UNKNOWN, so CHIP_WIDTH is unchanged and no other section pays for it.
 	"stale-load": { glyph: "✗", label: "BROKEN", color: brand.danger },
+	// No longer published, and removed by the apply. ✗ in danger: the plugin is
+	// dead weight Claude Code refuses to load, and the row is work, not a shrug.
+	// The plugin table shows the group's DEPRECATED chip, not this label.
+	remove: { glyph: "✗", label: "REMOVE", color: brand.danger },
 	// Warning, not danger: "cannot tell" is not a failure, and red UNKNOWN read
 	// as "broken". The summary line and the TUI already use warning for it.
 	unknown: { glyph: "?", label: "UNKNOWN", color: brand.warning },
@@ -373,10 +379,15 @@ function pluginDetail(item: PluginUpdateItem): string {
 	// "loads v0.3.0, installed v0.5.0" and the two columns beside it already do.
 	const note =
 		item.note &&
-		item.reason !== "not-offered" &&
+		item.reason !== "deprecated" &&
 		item.reason !== "older-version-loads"
 			? `  ${dim(`(${item.note})`)}`
 			: "";
+	// Kept on purpose — moved, or still required. Under Deprecated, and the
+	// word says nothing will happen to it; the note says why.
+	if (isKeptDeprecated(item)) {
+		return `${item.installed ?? "—"}  ${dim(`kept — ${item.note ?? "no longer published"}`)}`;
+	}
 	switch (item.action) {
 		case "install":
 			return `${item.target ?? "latest"}${note}`;
@@ -391,6 +402,7 @@ function pluginDetail(item: PluginUpdateItem): string {
 			)} ${fg(groupStyle("Update").text, item.target ?? "?")}${note}`;
 		case "repair":
 		case "unknown":
+		case "remove":
 			return `${item.installed ?? "—"}${note}`;
 		case "stale-load":
 			// Both versions, in the order the reader needs them: what runs, then
@@ -459,7 +471,7 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
  * note. Five headings, and no more:
  *
  *   Update        something an apply would move forward
- *   Deprecated    no configured marketplace offers it
+ *   Deprecated    no longer published — an apply removes it
  *   Fix required  declared or installed, with its files missing
  *   Unverified    the check itself did not complete
  *   Current       settled — the version was compared, or there was none to compare
@@ -485,9 +497,11 @@ function pluginGroup(item: PluginUpdateItem): string {
 	// state deceptive, and a row that reads as up to date under a CURRENT
 	// heading is the defect this state was added to end.
 	if (item.action === "stale-load") return "Broken";
-	if (item.action === "unknown") {
-		return item.reason === "not-offered" ? "Deprecated" : "Unverified";
-	}
+	if (item.action === "remove") return "Deprecated";
+	// Moved or still required: no longer published here, and KEPT. That is a
+	// determined fact, not a check that failed, so never "Unverified".
+	if (isKeptDeprecated(item)) return "Deprecated";
+	if (item.action === "unknown") return "Unverified";
 	return "Current";
 }
 
@@ -590,9 +604,12 @@ function pluginRow(
 			: badge(groupBadge(group), style.fill ?? brand.muted, style.ink),
 		chipWidth,
 	);
-	return `${PAD}${fg(style.text, ACTIONS[item.action].glyph)}  ${
-		style.chrome ? dim(name) : name
-	}  ${chip}${pluginDetail(item)}`;
+	// A kept row is not work: the ✗ of a removal would say it is, and the "?"
+	// of an unknown that nobody knows. It gets the settled row's muted glyph.
+	const mark = isKeptDeprecated(item)
+		? fg(brand.muted, ACTIONS.current.glyph)
+		: fg(style.text, ACTIONS[item.action].glyph);
+	return `${PAD}${mark}  ${style.chrome ? dim(name) : name}  ${chip}${pluginDetail(item)}`;
 }
 
 /** The Plugins section: grouped by state, `Current` last. */
@@ -681,7 +698,7 @@ export function planReport(plan: UpdatePlan): string[] {
 	// EVERY planned plugin gets a row. There is no filter here and there must
 	// not be one.
 	//
-	// A previous revision dropped `unknown` + `not-offered` + not-installed rows
+	// A previous revision dropped unlisted, not-installed rows
 	// — a pin naming a plugin no marketplace offers — on the grounds that a
 	// notice named them instead. That notice did not exist: the function the
 	// comment cited was never written. The row appeared in no table and no
@@ -778,10 +795,11 @@ export function summaryLine(
 	failed: number,
 	ms: number,
 	unchanged = 0,
+	kept = 0,
 ): string[] {
 	const bar = stackedBar(BAR * 2, [
 		{ value: changed, color: brand.success },
-		{ value: current, color: brand.muted },
+		{ value: current + kept, color: brand.muted },
 		{ value: unchanged + unknown, color: brand.warning },
 		{ value: failed, color: brand.danger },
 	]);
@@ -789,6 +807,9 @@ export function summaryLine(
 		changed > 0 ? fg(brand.success, `${changed} changed`) : "",
 		unchanged > 0 ? fg(brand.warning, `${unchanged} unchanged`) : "",
 		current > 0 ? dim(`${current} current`) : "",
+		// Deprecated but kept on purpose (moved, still required): settled, so
+		// grey beside `current`, and never folded into "unverified".
+		kept > 0 ? dim(`${kept} kept`) : "",
 		unknown > 0 ? fg(brand.warning, `${unknown} unverified`) : "",
 		failed > 0 ? fg(brand.danger, `${failed} failed`) : "",
 	].filter(Boolean);
@@ -860,3 +881,25 @@ export function nothingToApplyNotice(unknownPlugins: number): string {
 		`Nothing to apply. ${unknownPlugins} plugin(s) could not be checked. They are NOT reported as up to date. Reasons are shown above.`,
 	);
 }
+
+/**
+ * The words `--check` fails with, chosen by what is pending. "Updates
+ * available" over a plan whose only work is removing plugins that are no
+ * longer published claims an update nobody can find in the table above.
+ */
+export function pendingHeadline(plan: UpdatePlan): string {
+	const pendingPlugins = plan.plugins.filter(
+		(p) =>
+			p.action === "install" ||
+			p.action === "update" ||
+			p.action === "repair" ||
+			p.action === "stale-load" ||
+			p.action === "remove",
+	);
+	const onlyRemovals =
+		pendingPlugins.length > 0 &&
+		pendingPlugins.every((p) => p.action === "remove") &&
+		!plan.bins.some((b) => b.action === "install" || b.action === "upgrade") &&
+		!plan.skills.some((s) => s.action === "install");
+	return onlyRemovals ? "Changes pending" : "Updates available";
+}

package/src/cli/update.ts

@@ -47,6 +47,7 @@ import {
 	type PluginInfo,
 	clearMarketplaceCache,
 	getAvailablePlugins,
+	isInstalledAnywhere,
 } from "../services/plugin-manager.js";
 import {
 	recordRefetchedSkills,
@@ -61,7 +62,7 @@ import {
 	switchHint,
 	withCliBookkeeping,
 } from "../services/profile-state.js";
-import { resolveProfile } from "../services/resolver.js";
+import { requirersHere, resolveProfile } from "../services/resolver.js";
 import { getInstalledSkillNames } from "../services/skills-manager.js";
 import { REAL_TOOL_PROBE_IO, probeTools } from "../services/tool-probe.js";
 // The apply half lives in services/ so the TUI runs the SAME code — see the
@@ -69,6 +70,7 @@ import { REAL_TOOL_PROBE_IO, probeTools } from "../services/tool-probe.js";
 import {
 	type ApplyReporter,
 	applyPlan,
+	describeRemoved,
 	planWorkItems,
 } from "../services/update-engine.js";
 import {
@@ -95,6 +97,7 @@ import {
 	note as noteLine,
 	nothingToApplyNotice,
 	ok as okLine,
+	pendingHeadline,
 	planReport,
 	stepFrame,
 	stepRecord,
@@ -441,9 +444,17 @@ export async function runUpdateCommand(
 		targetId,
 		closure.skills,
 	);
+	// Every installed plugin's dependencies count, not only the profile's: a
+	// plugin still required by one that stays is never planned for removal, and
+	// retired plugins that only require each other are removed together.
+	const requiredBy = await requirersHere(
+		closure.dependencies?.requiredBy,
+		[...catalog.values()].filter(isInstalledAnywhere).map((p) => p.id),
+		projectPath,
+	);
 	const plan: UpdatePlan = {
 		profileId: targetId,
-		plugins: planPluginUpdates(closure.plugins, catalog),
+		plugins: planPluginUpdates(closure.plugins, catalog, requiredBy),
 		bins: planBinUpdates(closure.bins, toolFacts),
 		skills: planSkillUpdates(skillRefs, installedSkills),
 		binSpecs: new Map(closure.bins.map((b) => [b.name, b])),
@@ -489,7 +500,9 @@ export async function runUpdateCommand(
 			return 0;
 		}
 		console.error(
-			failLine(`Updates available. Run ${bold("magus update")} to apply.`),
+			failLine(
+				`${pendingHeadline(plan)}. Run ${bold("magus update")} to apply.`,
+			),
 		);
 		return 1;
 	}
@@ -506,6 +519,8 @@ export async function runUpdateCommand(
 			counts.unknown,
 			0,
 			Date.now() - startedAt,
+			0,
+			counts.kept,
 		))
 			console.log(line);
 		// `planHasWork` counts an `unknown` plugin as work, because from the
@@ -539,8 +554,10 @@ export async function runUpdateCommand(
 
 	// No confirmation. `update` moves the machine toward what the profile
 	// declares and can only go FORWARD: `claude plugin install` takes no version
-	// and installs the newest published one, so there is no downgrade and no
-	// delete for a prompt to protect against. The plan is printed above, so the
+	// and installs the newest published one, so there is no downgrade for a
+	// prompt to protect against. The one delete it makes is a DEPRECATED plugin:
+	// its marketplace no longer publishes it and Claude Code refuses to load it
+	// (measured, 2.1.284), so removing it loses nothing. The plan is printed above, so the
 	// run is still legible after the fact — and `--dry-run` shows it beforehand.
 	//
 	// Note this also runs a profile's CLI-tool installers unattended (`brew
@@ -637,9 +654,14 @@ export async function runUpdateCommand(
 		failed.length,
 		Date.now() - startedAt,
 		outcome.unchanged.length,
+		counts.kept,
 	))
 		console.log(line);
 
+	// Only the CLI says it: on the Plugins screen the removed rows are simply gone.
+	const removed = describeRemoved(outcome.plugins.removed);
+	if (removed) console.log(okLine(removed));
+
 	// Exited 0, read back unmoved. Reported, never fatal — the same precedent
 	// as the pin mismatches below: this is a standing property of the machine
 	// (a stale tap, a shadowing PATH entry), not something this run did wrong,

package/src/services/catalog-cache-store.ts

@@ -35,12 +35,14 @@ import type { MarketplacePlugin } from "./marketplace-catalog.js";
 /**
  * How long a cached catalog is served before we ask again.
  *
- * This is the ONLY refresh rhythm magus has, and it is why the TUI and
- * `magus update` can disagree about the same plugin for up to an hour:
- * `update` fast-forwards the clones and clears this cache before planning,
- * while the TUI serves whatever is here. That is not a bug in either path, but
- * anything that reports "no update" off a cached catalog has to say the answer
- * is up to an hour old.
+ * This is the ONLY refresh rhythm magus has, and it applies to both surfaces:
+ * `magus update` and the TUI read a catalog written here within the hour
+ * before they go to the network. `update` pulls the marketplace clones and
+ * drops its in-process memo before planning, but it does NOT clear this file,
+ * so a release published inside the TTL is not seen by `update` either. Only
+ * an explicit refresh (`r` in the TUI) clears it. Anything that reports "no
+ * update" — or decides a plugin is no longer published — off a cached catalog
+ * is working from an answer up to an hour old, by design.
  */
 export const CATALOG_TTL_MS = 60 * 60 * 1000;