magus-cli 7.7.0 → 7.9.0

package/src/services/update-engine.ts

@@ -20,7 +20,7 @@
  * So the engine lives here, in `services/`, and both front ends drive it.
  * `cli/` and `ui/` are sibling presentation layers: they own how progress looks
  * and nothing else. Everything IO-shaped is injected — `PluginApplyDeps` for
- * the five Claude Code calls, `ApplyReporter` for progress, `runCommand` for
+ * the five Claude Code calls, `ApplyReporter` for progress, `runArgv` for
  * installers — so the same code drives an animated terminal meter, a TUI modal,
  * and a test that wants silence.
  *
@@ -32,18 +32,28 @@
 import path from "node:path";
 import type {
 	InstalledPluginEntry,
+	ManagedBin,
 	ProfileSkillRef,
-	ResolvedBin,
 	SkillInfo,
 } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import { formatCommand } from "../utils/command-utils.js";
-import { runCommand } from "../utils/run.js";
+import { runArgv, succeeded } from "../utils/run.js";
 import type { PluginScope } from "./claude-cli.js";
-import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
+import {
+	installPlugin,
+	repairPlugin,
+	uninstallPluginViaCli,
+	updatePlugin,
+} from "./claude-cli.js";
 import {
 	type StaleLoadRepairResult,
+	forgetInstalledPluginVersion,
+	getEnabledPlugins,
+	getGlobalEnabledPlugins,
+	getLocalEnabledPlugins,
 	loadedVersionHere,
+	notDownloadedReason,
 	readInstalledPluginsRegistry,
 	repairStaleLoad,
 	rowBelongsToRepository,
@@ -54,6 +64,7 @@ import {
 	readInstalledVersionForScope,
 	saveInstalledPluginVersionForScope,
 } from "./plugin-manager.js";
+import { removePluginFromProfile } from "./profile-state.js";
 import { installSkill } from "./skills-manager.js";
 import {
 	type ToolFacts,
@@ -95,6 +106,13 @@ export interface PinMismatch {
 
 export interface PluginApplyResult extends ApplyResult {
 	mismatches: PinMismatch[];
+	/**
+	 * Deprecated plugins removed — installed at no scope here afterwards, and no
+	 * longer listed by the profile. Also counted in `ok`; named separately so the
+	 * CLI can say "Removed …" ({@link describeRemoved}). The Plugins screen needs
+	 * no line: the rows are gone.
+	 */
+	removed: string[];
 }
 
 /** Everything one full apply produced, for whichever front end is reporting. */
@@ -121,19 +139,36 @@ export interface UpdateOutcome {
 export interface ApplyReporter {
 	/** An item is starting. Called before any of its work. */
 	begin(name: string): void;
-	/** An item finished. `detail` is already formatted for display. */
-	finish(ok: boolean, name: string, detail: string, ms: number): void;
+	/**
+	 * An item finished. `detail` is already formatted for display, in the user's
+	 * terms: a failure's detail is the REASON — the CLI prints it, and the
+	 * Plugins screen shows it on the plugin's row.
+	 *
+	 * `cause` is `"exception"` when the detail is instead an error thrown from
+	 * something the engine called — a Claude Code command's own output, a file
+	 * that would not parse — rather than a reason the engine worded itself.
+	 */
+	finish(
+		ok: boolean,
+		name: string,
+		detail: string,
+		ms: number,
+		cause?: FinishCause,
+	): void;
 	/**
 	 * Run `work` with the terminal released.
 	 *
-	 * A binary upgrade spawns `brew`/`uv` with inherited stdio: it writes and
-	 * moves the cursor itself, so any animated block must be erased first or the
-	 * two interleave into garbage. A TUI implementation suspends its renderer;
-	 * a silent one just awaits.
+	 * The installer's output is captured (`runArgv`), so nothing a child
+	 * prints reaches the terminal; an implementation pauses its animation for
+	 * the duration only so the meter does not tick over a step that has no
+	 * progress of its own to show. A silent one just awaits.
 	 */
 	detach<T>(work: () => Promise<T>): Promise<T>;
 }
 
+/** Where a finished item's detail came from — see {@link ApplyReporter.finish}. */
+export type FinishCause = "reason" | "exception";
+
 /** Reports nothing. The right default for a caller that renders its own state. */
 export const SILENT_REPORTER: ApplyReporter = {
 	begin: () => {},
@@ -211,8 +246,83 @@ export interface PluginApplyDeps {
 		row: InstalledPluginEntry,
 		projectPath: string,
 	) => boolean;
+	/**
+	 * What removing a deprecated plugin takes. Optional so the many doubles that
+	 * model only installs and updates need not grow three stubs each; a `remove`
+	 * item applied without it FAILS, saying so, rather than reporting a removal
+	 * that did not happen.
+	 */
+	remove?: PluginRemoveDeps;
+}
+
+/** The three calls a `remove` makes — see {@link applyRemove}. */
+export interface PluginRemoveDeps {
+	/**
+	 * `claude plugin uninstall <id> --scope <scope>`, and only that
+	 * (`uninstallPluginViaCli`, claude-cli.ts): it THROWS when the command
+	 * fails. The wrapper with a fallback (`uninstallPlugin`) edits the settings
+	 * files itself on failure, which is a direct write of Claude Code's files and
+	 * hides the command's error from the read-back. Measured on Claude Code
+	 * 2.1.284: the command uninstalls a plugin its marketplace no longer lists,
+	 * deleting the plugin from that scope's settings.
+	 */
+	uninstall: (
+		pluginId: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<void>;
+	/**
+	 * Installed at `scope` here, by the one definition the classifier uses: that
+	 * scope's settings turn the plugin on. The read-back after uninstalling.
+	 */
+	isInstalled: (
+		pluginId: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<boolean>;
+	/**
+	 * Stop `profile` listing the plugin; answers whether it no longer does.
+	 * `profile` undefined means the active one — see `removePluginFromProfile`.
+	 */
+	dropFromProfile: (
+		pluginId: string,
+		projectPath: string,
+		profile: string | null | undefined,
+	) => Promise<boolean>;
+	/**
+	 * Clear magus's OWN `installedPluginVersions` claim for the plugin at a
+	 * scope it was removed from (`forgetInstalledPluginVersion`). Claude Code
+	 * never writes that field, so its uninstall leaves the claim behind, and a
+	 * leftover claim is a plugin that still reads as installed. Optional so a
+	 * double that does not model it skips it; best-effort, because the removal
+	 * itself is judged by `isInstalled`, never by this field.
+	 */
+	forgetVersion?: (
+		pluginId: string,
+		scope: PluginScope,
+		projectPath: string,
+	) => Promise<void>;
+}
+
+/** The settings a scope's install lives in — the classifier's definition. */
+async function enabledAt(
+	scope: PluginScope,
+	projectPath: string,
+): Promise<Record<string, boolean>> {
+	if (scope === "user") return getGlobalEnabledPlugins();
+	if (scope === "local") return getLocalEnabledPlugins(projectPath);
+	return getEnabledPlugins(projectPath);
 }
 
+export const REAL_REMOVE_DEPS: PluginRemoveDeps = {
+	uninstall: uninstallPluginViaCli,
+	isInstalled: async (pluginId, scope, projectPath) =>
+		(await enabledAt(scope, projectPath))[pluginId] === true,
+	dropFromProfile: (pluginId, projectPath, profile) =>
+		removePluginFromProfile(projectPath, pluginId, profile),
+	forgetVersion: forgetInstalledPluginVersion,
+};
+
 export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
 	install: installPlugin,
 	update: updatePlugin,
@@ -225,6 +335,7 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
 		const rows = (await readInstalledPluginsRegistry()).plugins?.[pluginId];
 		return Array.isArray(rows) ? rows : [];
 	},
+	remove: REAL_REMOVE_DEPS,
 };
 
 /**
@@ -330,18 +441,23 @@ async function followMisdirectedUpdate(
 	return {
 		elsewhere,
 		version,
-		notFollowed: repair.ok
-			? null
-			: (repair.error ?? "the registry was not rewritten"),
+		notFollowed: repair.ok ? null : (repair.error ?? "nothing was changed"),
 	};
 }
 
-/** The words for a misdirected update, for an item's detail. */
+/**
+ * The words for a misdirected update, for an item's detail. In the user's
+ * terms: which OTHER folders were touched is counted, not listed — their paths
+ * are the mechanism, and the fact is that this folder was not the one updated.
+ */
 function describeMisdirected(m: MisdirectedUpdate): string {
-	const where = m.elsewhere.join(", ");
+	const where =
+		m.elsewhere.length === 1
+			? "another folder of this repository"
+			: `${m.elsewhere.length} other folders of this repository`;
 	return m.notFollowed === null
-		? `Claude Code updated ${where} instead of this project — moved this project's record to v${m.version} too`
-		: `Claude Code updated ${where} instead of this project, and this project's record could not follow: ${m.notFollowed}`;
+		? `Claude Code updated ${where} instead of this one — this folder now loads v${m.version} too`
+		: `Claude Code updated ${where} instead of this one, and this folder could not follow: ${m.notFollowed}`;
 }
 
 /**
@@ -377,9 +493,49 @@ export async function bringLoadForward(
 
 /** The words for a load brought forward, appended to an item's detail. */
 function describeLoadForward(outcome: StaleLoadRepairResult): string {
-	return `Claude Code now loads v${outcome.target} here (${outcome.rewritten} older record${
-		outcome.rewritten === 1 ? "" : "s"
-	} moved forward)`;
+	return `Claude Code now loads v${outcome.target} in this folder`;
+}
+
+/**
+ * The words for an install that landed but does not load — the failure detail
+ * `magus update`, the Plugins screen and `magus install` all print.
+ *
+ * When the repair's own check named the version still loading, that version IS
+ * the reason, and nothing is appended: the repair's message says the same thing
+ * a second time. When it refused before writing (`loaded` is then null), its
+ * message is the only reason there is, so it follows — except the refusal for
+ * a version with no download, which names the version again: "installed
+ * v1.3.0, but v1.3.0 is not downloaded" reads as a contradiction, so that one
+ * says the install did not download.
+ */
+export function describeLoadNotForward(forward: StaleLoadRepairResult): string {
+	// `target` is the version that landed: the repair was asked to make it load.
+	const installed = forward.target;
+	if (forward.loaded) {
+		return `installed v${installed}, but Claude Code still loads v${forward.loaded} in this folder`;
+	}
+	if (forward.error === notDownloadedReason(installed)) {
+		return `installed v${installed}, but it did not download — run magus install`;
+	}
+	return `installed v${installed}, but ${
+		forward.error ?? "Claude Code still loads an older version in this folder"
+	}`;
+}
+
+/**
+ * The line `magus update` prints for the deprecated plugins an apply removed,
+ * or null when it removed none. Plugin names, not ids: the line is
+ * about what the user knew them as.
+ */
+export function describeRemoved(removed: readonly string[]): string | null {
+	if (removed.length === 0) return null;
+	return `Removed ${removed.map(pluginName).join(", ")} — no longer published`;
+}
+
+/** A plugin id's name part: `kanban@magus` → `kanban`. */
+export function pluginName(pluginId: string): string {
+	const at = pluginId.indexOf("@");
+	return at > 0 ? pluginId.slice(0, at) : pluginId;
 }
 
 // -- selection ---------------------------------------------------------------
@@ -409,10 +565,15 @@ function scopesToApply(item: PluginUpdateItem): PluginScope[] {
 	// measured NOT to clear it — it writes another row for this project while the
 	// row the loader picks belongs to a different one — which is exactly why it
 	// must not come through here. {@link pluginNeedsWork} counts it separately.
+	//
+	// `remove` has its own branch too ({@link applyRemove}): its scopes are where
+	// to UNINSTALL, and a declared plugin installed nowhere still has work — the
+	// profile edit — with none at all.
 	if (
 		item.action === "current" ||
 		item.action === "unknown" ||
-		item.action === "stale-load"
+		item.action === "stale-load" ||
+		item.action === "remove"
 	)
 		return [];
 	return item.action === "install" && item.reason === "absent"
@@ -429,10 +590,16 @@ function scopesToApply(item: PluginUpdateItem): PluginScope[] {
  * looks exactly like a hang.
  *
  * `stale-load` is work without scopes — see {@link scopesToApply} — so it is
- * named here rather than counted through the scope list.
+ * named here rather than counted through the scope list. So is `remove`: a
+ * deprecated plugin the profile declares and nothing installed is still work,
+ * because the profile must stop declaring it.
  */
 export function pluginNeedsWork(item: PluginUpdateItem): boolean {
-	return item.action === "stale-load" || scopesToApply(item).length > 0;
+	return (
+		item.action === "stale-load" ||
+		item.action === "remove" ||
+		scopesToApply(item).length > 0
+	);
 }
 
 // -- plugins -----------------------------------------------------------------
@@ -555,7 +722,7 @@ async function applyStaleLoad(
 		report.finish(
 			false,
 			item.pluginId,
-			`no installed version to point ${item.pluginId}'s registry rows at`,
+			"no version is installed in this folder for Claude Code to load instead",
 			Date.now() - startedAt,
 		);
 		result.failed.push(item.pluginId);
@@ -571,9 +738,7 @@ async function applyStaleLoad(
 			report.finish(
 				true,
 				item.pluginId,
-				`registry → v${outcome.target} (${outcome.rewritten} row${
-					outcome.rewritten === 1 ? "" : "s"
-				} moved forward)`,
+				describeLoadForward(outcome),
 				Date.now() - startedAt,
 			);
 			result.ok++;
@@ -581,32 +746,159 @@ async function applyStaleLoad(
 			report.finish(
 				false,
 				item.pluginId,
-				outcome.error ?? `${item.pluginId} still does not load v${item.target}`,
+				outcome.error ??
+					`Claude Code still does not load v${item.target} in this folder`,
 				Date.now() - startedAt,
 			);
 			result.failed.push(item.pluginId);
 		}
 	} catch (error) {
 		const msg = error instanceof Error ? error.message : String(error);
-		report.finish(false, item.pluginId, msg, Date.now() - startedAt);
+		report.finish(
+			false,
+			item.pluginId,
+			msg,
+			Date.now() - startedAt,
+			"exception",
+		);
 		result.failed.push(item.pluginId);
 	}
 }
 
+/**
+ * Remove ONE deprecated plugin — the `remove` half of {@link applyPlugins}.
+ *
+ * Uninstalls it at every scope the plan found it installed at, through the
+ * Claude Code CLI wrapper, then stops the profile listing it. Both halves run
+ * even when the first fails part-way: a profile that keeps a plugin no
+ * marketplace publishes only ever asks for an install that cannot happen.
+ *
+ * Success is READ BACK, never "the calls returned": installed at no scope here
+ * afterwards — all three are checked, not just the planned ones — and the
+ * profile no longer lists it.
+ */
+async function applyRemove(
+	item: PluginUpdateItem,
+	projectPath: string,
+	deps: PluginApplyDeps,
+	report: ApplyReporter,
+	result: PluginApplyResult,
+	profile: string | null | undefined,
+): Promise<void> {
+	report.begin(item.pluginId);
+	const startedAt = Date.now();
+	const fail = (detail: string, cause?: FinishCause) => {
+		report.finish(false, item.pluginId, detail, Date.now() - startedAt, cause);
+		result.failed.push(item.pluginId);
+	};
+	const remove = deps.remove;
+	if (!remove) {
+		fail("magus cannot remove plugins from here");
+		return;
+	}
+	try {
+		let uninstallError: unknown = null;
+		for (const scope of item.scopes) {
+			try {
+				await remove.uninstall(item.pluginId, scope, projectPath);
+			} catch (error) {
+				uninstallError ??= error;
+			}
+		}
+		const unlisted = await remove.dropFromProfile(
+			item.pluginId,
+			projectPath,
+			profile,
+		);
+
+		const still: PluginScope[] = [];
+		for (const scope of REMOVE_SCOPES) {
+			if (await remove.isInstalled(item.pluginId, scope, projectPath)) {
+				still.push(scope);
+			}
+		}
+		// magus's own claim goes with the install, at each scope it was removed
+		// from. Best-effort: a claim left behind no longer counts as an install
+		// anywhere, so failing to clear it must not fail a removal that happened.
+		if (remove.forgetVersion) {
+			for (const scope of item.scopes) {
+				if (still.includes(scope)) continue;
+				await remove
+					.forgetVersion(item.pluginId, scope, projectPath)
+					.catch(() => {});
+			}
+		}
+		if (still.length > 0) {
+			// The CLI's own words when it said anything; ours otherwise.
+			if (uninstallError !== null) {
+				fail(
+					uninstallError instanceof Error
+						? uninstallError.message
+						: String(uninstallError),
+					"exception",
+				);
+			} else {
+				fail(
+					`still installed at ${still.map((s) => s.toUpperCase()).join(", ")} scope`,
+				);
+			}
+			return;
+		}
+		if (!unlisted) {
+			fail("the profile still lists it");
+			return;
+		}
+		report.finish(
+			true,
+			item.pluginId,
+			item.scopes.length > 0
+				? `removed at ${item.scopes.map((s) => s.toUpperCase()).join(", ")} · no longer published`
+				: "removed from the profile · no longer published",
+			Date.now() - startedAt,
+		);
+		result.ok++;
+		result.removed.push(item.pluginId);
+	} catch (error) {
+		fail(error instanceof Error ? error.message : String(error), "exception");
+	}
+}
+
+/** Every scope a removal must leave the plugin uninstalled at. */
+const REMOVE_SCOPES: readonly PluginScope[] = ["user", "project", "local"];
+
+/** Options for {@link applyPlugins}. */
+export interface ApplyPluginsOptions {
+	/**
+	 * The profile the plan was made from — the one a removed plugin is dropped
+	 * from. Undefined means the active profile; `magus update <name>` passes the
+	 * named one, which need not be active.
+	 */
+	profile?: string | null;
+}
+
 export async function applyPlugins(
 	items: PluginUpdateItem[],
 	projectPath: string,
 	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
 	report: ApplyReporter = SILENT_REPORTER,
+	opts: ApplyPluginsOptions = {},
 ): Promise<PluginApplyResult> {
 	const result: PluginApplyResult = {
 		ok: 0,
 		failed: [],
 		unchanged: [],
 		mismatches: [],
+		removed: [],
 	};
 
 	for (const item of items) {
+		// A deprecated plugin is uninstalled and dropped from the profile — no
+		// installer, no version to read back — so it too has its own branch.
+		if (item.action === "remove") {
+			await applyRemove(item, projectPath, deps, report, result, opts.profile);
+			continue;
+		}
+
 		// A stale load is repaired in the REGISTRY, not by any installer, so it
 		// leaves the scope loop entirely. Its own branch rather than a scope with a
 		// special case inside: everything below reads back a per-scope version and
@@ -695,9 +987,7 @@ export async function applyPlugins(
 				report.finish(
 					false,
 					item.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"}`,
+					describeLoadNotForward(forward),
 					Date.now() - startedAt,
 				);
 				result.failed.push(item.pluginId);
@@ -726,7 +1016,13 @@ export async function applyPlugins(
 			}
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			report.finish(false, item.pluginId, msg, Date.now() - startedAt);
+			report.finish(
+				false,
+				item.pluginId,
+				msg,
+				Date.now() - startedAt,
+				"exception",
+			);
 			result.failed.push(item.pluginId);
 		}
 	}
@@ -764,11 +1060,7 @@ async function applyOneInScope(
 	if (actual) {
 		const forward = await bringLoadForward(pluginId, actual, projectPath, deps);
 		if (forward && !forward.ok) {
-			throw new Error(
-				`installed v${actual}, but Claude Code still loads v${
-					forward.loaded ?? "an older version"
-				} here — ${forward.error ?? "the older records could not be moved forward"}`,
-			);
+			throw new Error(describeLoadNotForward(forward));
 		}
 	}
 	return actual;
@@ -836,7 +1128,7 @@ export async function updatePluginInScope(
  */
 export function binCommandFor(
 	item: BinUpdateItem,
-	spec: ResolvedBin,
+	spec: ManagedBin,
 ): Command | null {
 	if (!binNeedsWork(item)) return null;
 	if (item.action === "upgrade" && item.upgradeCommand)
@@ -893,7 +1185,14 @@ function binNoMove(item: BinUpdateItem, after: ToolFacts): string | null {
  * which R6 counts as changed — the safe answer, but never "no change — still
  * 3.7c", the one the user needs.
  */
-const REAL_READ_BACK = (spec: ResolvedBin): Promise<ToolFacts> =>
+/** How long one `magus update` installer may run before it is stopped. */
+const INSTALLER_TIMEOUT_MS = 15 * 60_000;
+
+/** The default installer runner: argv, output captured, true on success. */
+const runInstaller = async (command: Command): Promise<boolean> =>
+	succeeded(await runArgv(command, { timeoutMs: INSTALLER_TIMEOUT_MS }));
+
+const REAL_READ_BACK = (spec: ManagedBin): Promise<ToolFacts> =>
 	probeTool(spec, undefined, { allowCheckCommand: true });
 
 export async function applyBins(
@@ -903,9 +1202,9 @@ export async function applyBins(
 	// profile-supplied package name reach `/bin/sh`: a seam called "shell" reads
 	// as an invitation to hand it a string. It takes argv, and nothing here
 	// builds a shell line.
-	run: (command: Command) => Promise<boolean> = runCommand,
+	run: (command: Command) => Promise<boolean> = runInstaller,
 	/** Read-back seam: re-probe ONE tool after its installer ran. */
-	probe: (spec: ResolvedBin) => Promise<ToolFacts> = REAL_READ_BACK,
+	probe: (spec: ManagedBin) => Promise<ToolFacts> = REAL_READ_BACK,
 ): Promise<ApplyResult> {
 	const result: ApplyResult = { ok: 0, failed: [], unchanged: [] };
 	for (const item of plan.bins) {
@@ -930,8 +1229,6 @@ export async function applyBins(
 			result.failed.push(item.name);
 			continue;
 		}
-		// The installer owns the terminal for the duration: it streams its own
-		// output through inherited stdio.
 		const succeeded = await report.detach(() => run(cmd));
 		if (!succeeded) {
 			report.finish(
@@ -1023,7 +1320,7 @@ export interface ApplyPlanOptions {
 	/** Installer execution seam — see the note on {@link applyBins}. */
 	run?: (command: Command) => Promise<boolean>;
 	/** Read-back seam — see {@link applyBins}. Default: `probeTool(spec)`. */
-	probe?: (spec: ResolvedBin) => Promise<ToolFacts>;
+	probe?: (spec: ManagedBin) => Promise<ToolFacts>;
 }
 
 /**
@@ -1045,6 +1342,9 @@ export async function applyPlan(
 		projectPath,
 		opts.deps ?? REAL_PLUGIN_DEPS,
 		report,
+		// The profile planned is the one a removed plugin leaves — which, under
+		// `magus update <name>`, need not be the active one.
+		{ profile: plan.profileId },
 	);
 	const bins = await applyBins(plan, report, opts.run, opts.probe);
 	const skills = await applySkills(plan, projectPath, report);