magus-cli 7.7.0 → 7.8.0

package/src/services/update-plan.ts

@@ -39,6 +39,7 @@ import {
 	installedScopeVersions,
 	isBehind,
 	isInstalledAnywhere,
+	isInstalledInScope,
 	isRepairablyBehind,
 } from "./plugin-manager.js";
 import {
@@ -77,6 +78,17 @@ export type PluginUpdateAction =
 	 * every row, whichever scope or project each belongs to.
 	 */
 	| "stale-load"
+	/**
+	 * DEPRECATED: a marketplace we READ does not list it. Claude Code refuses to
+	 * load such a plugin ("Plugin X not found in marketplace Y" in its debug log,
+	 * measured on 2.1.284), so it is dead weight and removing it loses nothing.
+	 *
+	 * Applied by uninstalling at every scope in `scopes` and dropping it from the
+	 * profile, so the next activation does not add it back. `scopes` is empty for
+	 * a plugin the profile declares and nothing installed: the profile edit is
+	 * then the whole of the work.
+	 */
+	| "remove"
 	/** The catalog check failed; we cannot claim either way. */
 	| "unknown";
 
@@ -89,8 +101,19 @@ export type PluginReason =
 	| "absent"
 	/** install: installed at a scope, but no version resolves at any installed scope. */
 	| "files-missing"
-	/** unknown: a marketplace we READ does not list it. */
-	| "not-offered"
+	/** remove: a marketplace we READ does not list it — no longer published. */
+	| "deprecated"
+	/**
+	 * unknown: its marketplace no longer lists it, but another marketplace we
+	 * read lists the same name — it moved, and removing it would lose it.
+	 */
+	| "moved"
+	/**
+	 * unknown: no longer published, but it is in the plan only because another
+	 * plugin the profile turns on requires it. Removing it would not stick: the
+	 * next resolve derives it again.
+	 */
+	| "still-required"
 	/** unknown: installed, unlisted, and its marketplace contributed no listed ids. */
 	| "marketplace-unread"
 	/** unknown: the catalog fetch failed ("latest" pins only). */
@@ -243,6 +266,11 @@ export interface CatalogIndex {
 	isListed(pluginId: string): boolean;
 	/** Some OTHER listed id shares this id's "@marketplace" suffix. False for ids without "@". */
 	marketplaceIsKnown(pluginId: string): boolean;
+	/**
+	 * A LISTED plugin with the same name in a DIFFERENT marketplace, or
+	 * undefined. The first in catalog order when several do.
+	 */
+	listedElsewhere(pluginId: string): PluginInfo | undefined;
 }
 
 export function indexCatalog(
@@ -269,6 +297,16 @@ export function indexCatalog(
 		return !!info && !info.isOrphaned;
 	};
 
+	// Listed plugins by bare name, for "did it move?".
+	const listedByName = new Map<string, PluginInfo[]>();
+	for (const [id, info] of byId) {
+		if (info.isOrphaned) continue;
+		const name = bareName(id);
+		const same = listedByName.get(name);
+		if (same) same.push(info);
+		else listedByName.set(name, [info]);
+	}
+
 	return {
 		get: (id) => byId.get(id),
 		isListed,
@@ -279,23 +317,223 @@ export function indexCatalog(
 				(listedPerSuffix.get(suffix) ?? 0) - (isListed(id) ? 1 : 0);
 			return others > 0;
 		},
+		listedElsewhere: (id) => {
+			const suffix = marketplaceSuffix(id);
+			if (!suffix) return undefined;
+			return listedByName
+				.get(bareName(id))
+				?.find((info) => marketplaceSuffix(info.id) !== suffix);
+		},
+	};
+}
+
+/** An id's name part: `kanban@magus` → `kanban`. */
+function bareName(id: string): string {
+	const at = id.indexOf("@");
+	return at > 0 ? id.slice(0, at) : id;
+}
+
+const ALL_SCOPES: readonly PluginScope[] = ["user", "project", "local"];
+
+/**
+ * Every scope the plugin is installed at here — files missing included, since
+ * an install with no version is still an install Claude Code tries to load.
+ */
+function installedScopes(info: PluginInfo | undefined): PluginScope[] {
+	const byScope: Record<PluginScope, PluginInfo["userScope"]> = {
+		user: info?.userScope,
+		project: info?.projectScope,
+		local: info?.localScope,
+	};
+	return ALL_SCOPES.filter((scope) => isInstalledInScope(byScope[scope]));
+}
+
+/** The fields every classification carries, whatever its action. */
+type ItemBase = Omit<
+	PluginUpdateItem,
+	"target" | "action" | "reason" | "scopes" | "note"
+>;
+
+/**
+ * Plugin id → the plugin(s) whose plugin.json requires it — `DependencyReport
+ * .requiredBy` for the profile's plugins, merged with the same edges read from
+ * every installed plugin (`requirersHere`). Every edge counts, a plugin the
+ * profile also names included.
+ *
+ * A single id is one requirer; a list is every requirer known. The list is
+ * what lets {@link planPluginUpdates} remove a deprecated plugin whose only
+ * requirers are being removed too, and keep one that anything else needs.
+ */
+export type RequiredBy = Readonly<Record<string, string | readonly string[]>>;
+
+/** Every plugin `requiredBy` records as requiring `pluginId`, first first. */
+export function requirersOf(
+	requiredBy: RequiredBy,
+	pluginId: string,
+): string[] {
+	if (!Object.hasOwn(requiredBy, pluginId)) return [];
+	const value = requiredBy[pluginId];
+	if (value === undefined) return [];
+	return typeof value === "string" ? [value] : [...value];
+}
+
+/**
+ * Kept, not removed, although its marketplace no longer lists it: it MOVED to
+ * another marketplace, or another plugin STILL REQUIRES it. Both are facts,
+ * not a failed check — the CLI lists them under Deprecated as "kept" and never
+ * counts them as "could not be checked"; the TUI shows the note in a muted
+ * tone, not the amber "?" of a real unknown.
+ */
+export function isKeptDeprecated(item: PluginUpdateItem): boolean {
+	return (
+		item.action === "unknown" &&
+		(item.reason === "moved" || item.reason === "still-required")
+	);
+}
+
+/**
+ * No longer published: a marketplace we read does not list it. Removed at
+ * every scope it is installed at here, and from the profile — unless removing
+ * it would lose something or would not stick, which are both `unknown` and
+ * never applied:
+ *
+ *  - MOVED: another marketplace we read lists the same name. The plugin still
+ *    exists; uninstalling this copy is not the user's intent, and installing
+ *    the other one is not magus's guess to make.
+ *  - STILL REQUIRED: another plugin — one the profile turns on, or one
+ *    installed here — requires this one. Removing it breaks that plugin, and
+ *    when the profile never named it the next resolve derives it again, so
+ *    `--check` would never clear. That holds whether or not the profile also
+ *    names it.
+ *
+ * The notes are in the user's terms because they are the TUI's row text
+ * verbatim. Which marketplace stopped publishing it is the detail panel's to
+ * say, from the plugin's own display name.
+ */
+function notPublished(
+	base: ItemBase,
+	info: PluginInfo | undefined,
+	index: CatalogIndex,
+	requiredBy: RequiredBy,
+): PluginUpdateItem {
+	const unknown = (reason: PluginReason, note: string): PluginUpdateItem => ({
+		...base,
+		target: null,
+		action: "unknown",
+		reason,
+		scopes: [],
+		note,
+	});
+	const elsewhere = index.listedElsewhere(base.pluginId);
+	if (elsewhere) {
+		return unknown(
+			"moved",
+			`moved to ${elsewhere.marketplaceDisplay || elsewhere.marketplace}`,
+		);
+	}
+	const [requirer] = requirersOf(requiredBy, base.pluginId);
+	if (requirer) {
+		return unknown("still-required", stillRequiredNote(requirer));
+	}
+	return deprecatedRemove(base, info);
+}
+
+/** The kept row's words: which plugin still needs it. */
+function stillRequiredNote(requirer: string): string {
+	return `no longer published, but ${bareName(requirer)} still requires it`;
+}
+
+/** A deprecated plugin, removed at every scope it is installed at here. */
+function deprecatedRemove(
+	base: ItemBase,
+	info: PluginInfo | undefined,
+): PluginUpdateItem {
+	return {
+		...base,
+		target: null,
+		action: "remove",
+		reason: "deprecated",
+		scopes: installedScopes(info),
+		note: "no longer published",
 	};
 }
 
+/**
+ * Deprecated plugins that require EACH OTHER are removed together.
+ *
+ * {@link classifyPlugin} judges one plugin at a time, so any recorded
+ * requirer keeps a deprecated plugin. That is right when the requirer stays
+ * and wrong when it is being removed too: a chain A → B of retired plugins
+ * removed A and kept B "because A still requires it", and a cycle A ↔ B kept
+ * both forever. Either way `magus update --check` right after `magus update`
+ * still reported work.
+ *
+ * So the removal set is settled as a whole. Start from every no-longer-
+ * published plugin that was not moved, and take out each one something OUTSIDE
+ * the set requires, until nothing changes. What is left — nobody who stays
+ * needs any of it — is removed in one pass. What was taken out stays, and its
+ * note names a plugin that genuinely stays and needs it.
+ *
+ * `moved` is never in the set: the plugin still exists elsewhere, and a
+ * plugin that requires it is a reason to keep, not to remove.
+ */
+function settleDeprecated(
+	items: readonly PluginUpdateItem[],
+	index: CatalogIndex,
+	requiredBy: RequiredBy,
+): PluginUpdateItem[] {
+	const removable = new Set(
+		items
+			.filter((i) => i.reason === "deprecated" || i.reason === "still-required")
+			.map((i) => i.pluginId),
+	);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const id of removable) {
+			if (requirersOf(requiredBy, id).some((r) => !removable.has(r))) {
+				removable.delete(id);
+				changed = true;
+			}
+		}
+	}
+	return items.map((item) => {
+		if (item.reason !== "still-required") return item;
+		const {
+			target: _t,
+			action: _a,
+			reason: _r,
+			scopes: _s,
+			note: _n,
+			...base
+		} = item;
+		if (removable.has(item.pluginId)) {
+			return deprecatedRemove(base, index.get(item.pluginId));
+		}
+		const keeper = requirersOf(requiredBy, item.pluginId).find(
+			(r) => !removable.has(r),
+		);
+		return keeper ? { ...item, note: stillRequiredNote(keeper) } : item;
+	});
+}
+
 /**
  * THE plugin classifier. Pure.
  *
  * The rules are evaluated in order and the first match wins. Each branch below
  * returns, so reading top to bottom is reading the precedence.
  *
- * @param pluginId the plugin
- * @param pin      what it is judged against: an exact version, or "latest"
- * @param index    the catalog — see {@link indexCatalog}
+ * @param pluginId   the plugin
+ * @param pin        what it is judged against: an exact version, or "latest"
+ * @param index      the catalog — see {@link indexCatalog}
+ * @param requiredBy the plugins the profile has only as dependencies — see
+ *                   {@link RequiredBy}
  */
 export function classifyPlugin(
 	pluginId: string,
 	pin: string,
 	index: CatalogIndex,
+	requiredBy: RequiredBy = {},
 ): PluginUpdateItem {
 	const info = index.get(pluginId);
 	const listed = index.isListed(pluginId);
@@ -344,15 +582,13 @@ export function classifyPlugin(
 	// the marketplace. `marketplaceIsKnown` separates the two: holding other
 	// LISTED ids from that marketplace proves we genuinely read its catalog, so
 	// absence is an answer; holding none proves nothing.
+	//
+	// Such a pin is DEPRECATED, and removing it from the profile is the work:
+	// Claude Code will not load the plugin, so the pin only ever asks for an
+	// install that cannot happen. A plugin installed with its files missing lands
+	// here too (no installed scope has a version), and its scopes are uninstalled.
 	if (!listed && !installed && index.marketplaceIsKnown(pluginId)) {
-		return {
-			...base,
-			target: null,
-			action: "unknown",
-			reason: "not-offered",
-			scopes: [],
-			note: "not offered by any configured marketplace",
-		};
+		return notPublished(base, info, index, requiredBy);
 	}
 
 	// No installed scope has a version — the "checked but not installed" case.
@@ -390,25 +626,22 @@ export function classifyPlugin(
 	// text: it moved to a marketplace that does publish it; a marketplace we
 	// did read no longer lists it; or its marketplace contributed nothing we
 	// could read, so its absence proves nothing either way.
+	//
+	// A marketplace we read that does not list it is a fact, not a guess: the
+	// plugin is DEPRECATED and is removed. A marketplace that contributed nothing
+	// readable proves nothing, so that case stays `unknown` and nothing is done.
 	if (!listed) {
-		const orphan = {
-			...base,
-			target: null,
-			action: "unknown" as const,
-			scopes: [],
-		};
 		if (index.marketplaceIsKnown(pluginId)) {
-			return {
-				...orphan,
-				reason: "not-offered",
-				note: "not offered by any configured marketplace",
-			};
+			return notPublished(base, info, index, requiredBy);
 		}
 		const mp =
 			info?.marketplace || marketplaceSuffix(pluginId)?.slice(1) || pluginId;
 		return {
-			...orphan,
+			...base,
+			target: null,
+			action: "unknown",
 			reason: "marketplace-unread",
+			scopes: [],
 			note: `its marketplace ${mp} was not read, so whether it still offers this plugin is unknown`,
 		};
 	}
@@ -654,12 +887,15 @@ export function classifyPlugin(
  * `magus update`, which then reported everything up to date. The owner asked
  * for "absolutely the same code" on both sides; this is it.
  *
- * @param pinned  closure.plugins — pluginId -> exact version | "latest"
- * @param catalog getAvailablePlugins() output — keyed by id, or as a list
+ * @param pinned     closure.plugins — pluginId -> exact version | "latest"
+ * @param catalog    getAvailablePlugins() output — keyed by id, or as a list
+ * @param requiredBy closure.dependencies?.requiredBy — which plugin needs each
+ *                   dependency the profile does not name itself
  */
 export function planPluginUpdates(
 	pinned: Readonly<Record<string, string>>,
 	catalog: ReadonlyMap<string, PluginInfo> | readonly PluginInfo[],
+	requiredBy: RequiredBy = {},
 ): PluginUpdateItem[] {
 	const index = indexCatalog(catalog);
 	const plugins =
@@ -672,9 +908,13 @@ export function planPluginUpdates(
 		const pin = pinForRow(info, pinned);
 		if (pin !== null) pins.set(info.id, pin);
 	}
-	return [...pins]
-		.map(([pluginId, pin]) => classifyPlugin(pluginId, pin, index))
-		.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+	return settleDeprecated(
+		[...pins].map(([pluginId, pin]) =>
+			classifyPlugin(pluginId, pin, index, requiredBy),
+		),
+		index,
+		requiredBy,
+	).sort((a, b) => a.pluginId.localeCompare(b.pluginId));
 }
 
 /**
@@ -710,8 +950,11 @@ export function pinForRow(
 export function classifyPluginRows(
 	plugins: readonly PluginInfo[],
 	pins: Readonly<Record<string, string>>,
+	requiredBy: RequiredBy = {},
 ): Map<string, PluginUpdateItem> {
-	return new Map(planPluginUpdates(pins, plugins).map((i) => [i.pluginId, i]));
+	return new Map(
+		planPluginUpdates(pins, plugins, requiredBy).map((i) => [i.pluginId, i]),
+	);
 }
 
 export interface PluginStateCounts {
@@ -725,6 +968,8 @@ export interface PluginStateCounts {
 	 * header would report a clean bill of health for a session running old code.
 	 */
 	"stale-load": number;
+	/** Deprecated — no longer published, and removed by an apply. */
+	remove: number;
 	unknown: number;
 }
 
@@ -738,6 +983,7 @@ export function countPluginStates(
 		repair: 0,
 		current: 0,
 		"stale-load": 0,
+		remove: 0,
 		unknown: 0,
 	};
 	for (const item of items) counts[item.action]++;
@@ -953,6 +1199,11 @@ export function planHasWork(plan: UpdatePlan): boolean {
  * (`summarizePlan`'s `unknownPlugins`/`unknownTools`, rendered by
  * `cli/update-view.ts`), and every unknown row carries its own reason above.
  *
+ * A `remove` DOES count. It used to be an `unknown` ("not offered"), and the
+ * argument above kept it out while nothing could act on it. `magus update` now
+ * removes it, so the gate closes — and a deprecated plugin is not a guess: its
+ * marketplace was read and does not list it, and Claude Code refuses to load it.
+ *
  * Both unknowns are listed positively rather than as `!== "current"`, so a new
  * action has to be classified here deliberately instead of defaulting into the
  * gate.
@@ -964,7 +1215,8 @@ export function planIsBehind(plan: UpdatePlan): boolean {
 				p.action === "install" ||
 				p.action === "update" ||
 				p.action === "repair" ||
-				p.action === "stale-load",
+				p.action === "stale-load" ||
+				p.action === "remove",
 		) ||
 		plan.bins.some((b) => b.action === "install" || b.action === "upgrade") ||
 		plan.skills.some((s) => s.action === "install")
@@ -979,14 +1231,21 @@ export function summarizePlan(plan: UpdatePlan): {
 	current: number;
 	/** unknownPlugins + unknownTools. */
 	unknown: number;
+	/** Plugins that could not be checked — never a {@link isKeptDeprecated} one. */
 	unknownPlugins: number;
 	unknownTools: number;
+	/**
+	 * No longer published by their marketplace, and kept on purpose: moved, or
+	 * still required. A determined fact, so not part of `unknown`.
+	 */
+	kept: number;
 } {
 	const count = (a: PluginUpdateAction) =>
 		plan.plugins.filter((p) => p.action === a).length;
 	const bins = (a: BinUpdateAction) =>
 		plan.bins.filter((b) => b.action === a).length;
-	const unknownPlugins = count("unknown");
+	const kept = plan.plugins.filter(isKeptDeprecated).length;
+	const unknownPlugins = count("unknown") - kept;
 	const unknownTools = bins("unknown");
 	return {
 		installed: count("install") + bins("install"),
@@ -996,5 +1255,6 @@ export function summarizePlan(plan: UpdatePlan): {
 		unknown: unknownPlugins + unknownTools,
 		unknownPlugins,
 		unknownTools,
+		kept,
 	};
 }

package/src/types/index.ts

@@ -486,6 +486,13 @@ export interface ResolvedClosure {
 export interface DependencyReport {
 	/** Enabled only because an enabled plugin depends on them. Sorted. */
 	derived: string[];
+	/**
+	 * For every dependency an enabled plugin declares — derived ones and ones
+	 * the profile also names — the plugin whose plugin.json first asked for it,
+	 * so a report can say which plugin still needs it. Optional because a
+	 * hand-built report may carry no provenance.
+	 */
+	requiredBy?: Record<string, string>;
 	/** Enabled plugins whose plugin.json could not be read here. Sorted. */
 	unreadable: string[];
 	/** A dependency the profile itself turns off: `plugin` will not load. */