magus-cli 7.10.5 → 7.11.1

package/src/services/deps-plan.ts

@@ -1,7 +1,8 @@
 /**
  * The one installer executor: plan what is missing, then install it.
  *
- * `planDeps` turns the requirements a probe found missing into ordered steps,
+ * `planDeps` turns the requirements a probe found missing or outdated into
+ * ordered steps,
  * each rendered by requires-probe's `renderInstall` (the only renderer).
  * `applyDepsPlan` runs them through `runArgv` and returns one `ApplyOutcome`
  * per step. Nothing here prints: `magus doctor` (text and `--json`),
@@ -42,6 +43,7 @@ import {
 	BUN_PREFIX,
 	type Bootstrap,
 	type BootstrapTool,
+	type InstallReason,
 	type InstallStep,
 	LOCAL_PREFIX,
 	type Os,
@@ -240,10 +242,11 @@ function fromMagusMarketplace(bin: ResolvedBin): boolean {
 }
 
 /**
- * The steps that install every `missing` requirement, in the order they must
- * run. `presence[i]` is the probe's answer for `bins[i]`. An `off-path`
- * requirement is not reinstalled: it needs a PATH line, which `pathAdvice`
- * carries. An `unknown` one (a check too slow to answer) is left alone.
+ * The steps that install every `missing` requirement and replace every
+ * `outdated` one, in the order they must run. `presence[i]` is the probe's
+ * answer for `bins[i]`. An `off-path` requirement is not reinstalled: it needs
+ * a PATH line, which `pathAdvice` carries. An `unknown` one (a check too slow
+ * to answer, or one that printed no version) is left alone.
  */
 export function planDeps(
 	bins: ResolvedBin[],
@@ -253,10 +256,11 @@ export function planDeps(
 	const unfixable: DepsPlan["unfixable"] = [];
 	/** The prefixes off the PATH, in the order they came up. */
 	const offPathPrefixes = new Set<UserPrefix>();
-	const missing: ResolvedBin[] = [];
+	const missing: { bin: ResolvedBin; reason: InstallReason }[] = [];
 	bins.forEach((bin, i) => {
 		const p = presence[i];
-		if (p?.status === "missing") missing.push(bin);
+		if (p?.status === "missing") missing.push({ bin, reason: "missing" });
+		if (p?.status === "outdated") missing.push({ bin, reason: "outdated" });
 		if (p?.status === "off-path") offPathPrefixes.add(p.prefix);
 	});
 
@@ -285,7 +289,7 @@ export function planDeps(
 		pluginRoot: bin.root ?? "",
 	});
 
-	for (const bin of missing) {
+	for (const { bin, reason } of missing) {
 		const option = bin.chosen;
 		if (!option) {
 			unfixable.push({
@@ -294,11 +298,12 @@ export function planDeps(
 			});
 			continue;
 		}
-		const step = renderInstall(bin, option, {
-			os: env.os,
-			arch: env.arch,
-			pluginRoot: bin.root ?? "",
-		});
+		const step = renderInstall(
+			bin,
+			option,
+			{ os: env.os, arch: env.arch, pluginRoot: bin.root ?? "" },
+			reason,
+		);
 		if (
 			step.kind === "uv-module" &&
 			step.escalation === "sudo" &&
@@ -895,7 +900,9 @@ async function landingDir(
  * After a step's installer exited 0, re-probe everything it installs with the
  * same probe doctor runs. Installed only when the probe now finds each one.
  * Found in a directory off the PATH Claude Code starts with: off-path, naming
- * the directory and the rc line. Not found at all: failed.
+ * the directory and the rc line. Not found at all: failed. Still below its
+ * `minVersion`: failed, naming the version found, the floor and the file the
+ * PATH resolves to — usually an older copy ahead of the one just installed.
  */
 async function verifyInstalled(
 	p: PlannedStep,
@@ -904,6 +911,7 @@ async function verifyInstalled(
 	const { env } = ctx;
 	const offPath: Verified[] = [];
 	const missing: string[] = [];
+	const outdated: string[] = [];
 	for (const target of p.installs) {
 		const presence = await ctx.io.verify(target, env);
 		if (presence.status === "present") continue;
@@ -911,6 +919,18 @@ async function verifyInstalled(
 			offPath.push({ status: "off-path", dir: presence.prefix });
 			continue;
 		}
+		if (presence.status === "outdated") {
+			const tool = target.requirement.check[0] ?? target.requirement.name;
+			const resolved = onPath(tool, env.path);
+			outdated.push(
+				`${target.requirement.name} is still ${presence.found}, below the ${presence.minVersion} it needs: ${
+					resolved
+						? `the PATH Claude Code starts with runs ${resolved}`
+						: `${tool} is not on the PATH Claude Code starts with`
+				} — remove that older copy or put the new one ahead of it, then restart Claude Code from a new terminal`,
+			);
+			continue;
+		}
 		const tool = target.requirement.check[0] ?? target.requirement.name;
 		const landed = await landingDir(p.step, ctx);
 		if (landed && onPath(tool, landed)) {
@@ -924,6 +944,10 @@ async function verifyInstalled(
 	if (missing.length > 0) {
 		return { status: "failed", why: missing.join("\n") };
 	}
+	if (outdated.length > 0) {
+		const why = outdated.join("\n");
+		return { status: "failed", why, remedy: why };
+	}
 	const first = offPath[0];
 	if (first?.dir) {
 		return {

package/src/services/deps-report.ts

@@ -33,13 +33,20 @@ import {
 	prefixOnPath,
 	requiredByOf,
 } from "./deps-plan.js";
-import { DOCTOR_CHECK_CAP_MS, probeBins } from "./doctor-bins.js";
+import {
+	DOCTOR_CHECK_CAP_MS,
+	installReason,
+	probeBins,
+} from "./doctor-bins.js";
 import { readManifest } from "./manifest.js";
 import { resolvePluginRequires, selectBins } from "./plugin-requires.js";
 import { binKey, cliToolBins, mergeBins } from "./resolver.js";
 
-/** The `--json` document's shape version. */
-export const DEPS_REPORT_SCHEMA = 1;
+/**
+ * The `--json` document's shape version. 2 added the `outdated` status and a
+ * dep's `found` and `minVersion`.
+ */
+export const DEPS_REPORT_SCHEMA = 2;
 
 export interface PluginParseProblem {
 	plugin: string;
@@ -187,6 +194,10 @@ export interface DepJson {
 	blockedBy?: string;
 	prefix?: string;
 	reason?: string;
+	/** Only when `status` is "outdated": the version the check reported. */
+	found?: string;
+	/** Only when `status` is "outdated": the lowest version that will do. */
+	minVersion?: string;
 	fix?: {
 		via: string;
 		escalation: "none" | "sudo";
@@ -227,11 +238,17 @@ export function depsReportJson(
 		if (p.status === "missing" && p.blockedBy) entry.blockedBy = p.blockedBy;
 		if (p.status === "off-path") entry.prefix = p.prefix;
 		if (p.status === "unknown") entry.reason = p.reason;
+		if (p.status === "outdated") {
+			entry.found = p.found;
+			entry.minVersion = p.minVersion;
+		}
 		if (p.status !== "present" && bin.chosen) {
-			const step = renderInstall(bin, bin.chosen, {
-				...env,
-				pluginRoot: bin.root ?? "",
-			});
+			const step = renderInstall(
+				bin,
+				bin.chosen,
+				{ ...env, pluginRoot: bin.root ?? "" },
+				installReason(p),
+			);
 			const prefix = prefixOf(step);
 			entry.fix = {
 				via: bin.chosen.via,

package/src/services/doctor-bins.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+	type InstallReason,
 	type Presence,
 	type ProbeDepth,
 	type Requirement,
@@ -68,6 +69,7 @@ export async function probeBins(
 		const reqs: Requirement[] = batch.map(({ bin }) => ({
 			name: bin.name,
 			check: expandCheck(bin, bin.root ?? ""),
+			...(bin.minVersion !== undefined ? { minVersion: bin.minVersion } : {}),
 			install: bin.install,
 		}));
 		const answers = await probe(reqs, {
@@ -93,13 +95,25 @@ export async function probeBins(
 	return out;
 }
 
-/** The line a person runs to install `bin` here, or why nothing can. */
-export function installText(bin: ResolvedBin, env: PlanEnv): string {
+/**
+ * The line a person runs to install `bin` here — or, `outdated`, to replace
+ * the copy that is too old — or why nothing can.
+ */
+export function installText(
+	bin: ResolvedBin,
+	env: PlanEnv,
+	reason: InstallReason = "missing",
+): string {
 	if (!bin.chosen) {
 		return whyUnselectable(bin, env, (t) => onPath(t, env.path) !== null);
 	}
 	return describeStep(
-		renderInstall(bin, bin.chosen, { ...env, pluginRoot: bin.root ?? "" }),
+		renderInstall(
+			bin,
+			bin.chosen,
+			{ ...env, pluginRoot: bin.root ?? "" },
+			reason,
+		),
 		env.os,
 	);
 }
@@ -107,7 +121,10 @@ export function installText(bin: ResolvedBin, env: PlanEnv): string {
 export interface BinCheckResult {
 	name: string;
 	presence: Presence;
-	/** Advisory text after "run:" for a human to copy. Never executed. */
+	/**
+	 * Advisory text after "run:" for a human to copy, an upgrade when the
+	 * presence is `outdated`. Never executed.
+	 */
 	installCommand: string;
 	/** Where the requirement came from (profile cliTools / plugin ids). */
 	sources: string[];
@@ -119,17 +136,28 @@ export async function checkBinaries(
 	opts: ProbeBinsOptions,
 ): Promise<BinCheckResult[]> {
 	const presences = await probeBins(bins, opts);
-	return bins.map((bin, i) => ({
-		name: bin.name,
-		presence: presences[i] as Presence,
-		installCommand: installText(bin, opts.env),
-		sources: bin.sources,
-	}));
+	return bins.map((bin, i) => {
+		const presence = presences[i] as Presence;
+		return {
+			name: bin.name,
+			presence,
+			installCommand: installText(bin, opts.env, installReason(presence)),
+			sources: bin.sources,
+		};
+	});
+}
+
+/** Why a requirement with this presence would be installed. */
+export function installReason(presence: Presence): InstallReason {
+	return presence.status === "outdated" ? "outdated" : "missing";
 }
 
-/** The actionable subset: missing, or installed but not on PATH. */
+/** The actionable subset: missing, outdated, or installed but not on PATH. */
 export function missingBinaries(results: BinCheckResult[]): BinCheckResult[] {
 	return results.filter(
-		(r) => r.presence.status === "missing" || r.presence.status === "off-path",
+		(r) =>
+			r.presence.status === "missing" ||
+			r.presence.status === "outdated" ||
+			r.presence.status === "off-path",
 	);
 }

package/src/services/plugin-manager.ts

@@ -371,7 +371,11 @@ export function buildScopeStatus(
 export function resolveScopeAction(
 	scope: ScopeStatus | undefined,
 	behind: boolean,
-): "install" | "update" | "uninstall" {
+	orphaned = false,
+): "install" | "update" | "uninstall" | "none" {
+	// A deprecated plugin is no longer in any marketplace, so install and update
+	// can only fail with a raw CLI error. Removing it is the one action left.
+	if (orphaned) return isInstalledInScope(scope) ? "uninstall" : "none";
 	if (!isInstalledInScope(scope) || scopeFilesMissing(scope)) return "install";
 	return behind ? "update" : "uninstall";
 }

package/src/services/resolver.ts

@@ -314,6 +314,7 @@ export function requirementOf(bin: Requirement): Requirement {
 		name: bin.name,
 		check: bin.check,
 		...(bin.os ? { os: bin.os } : {}),
+		...(bin.minVersion !== undefined ? { minVersion: bin.minVersion } : {}),
 		install: bin.install,
 	};
 }

package/src/shared/plugin/hooks/deps-check.ts

@@ -6,8 +6,9 @@
  * Reads the plugin's own `.claude-plugin/plugin.json` through
  * lib/requires-probe.ts, probes each requirement at presence depth (a PATH
  * lookup for a check that runs the requirement's own binary, the declared check
- * for every other), and prints a `systemMessage` carrying the `magus-deps` marker when something is
- * missing or off PATH. Prints nothing when healthy. Its "Fix all" line runs
+ * for every other, and for any requirement with a `minVersion`), and prints a
+ * `systemMessage` carrying the `magus-deps` marker when something is missing,
+ * outdated or off PATH. Prints nothing when healthy. Its "Fix all" line runs
  * doctor with `--project <cwd>`, the session's directory from the hook input:
  * doctor reads the plugins enabled in the project it checks, and the banner is
  * read in a terminal that may be anywhere.
@@ -200,8 +201,11 @@ async function main(): Promise<void> {
 		userShell: process.env.SHELL ?? "",
 	};
 	const presences = await probe(reqs, env);
+	// Outdated is a finding like missing: claimed once, reported once.
 	const reportable = (p: Presence) =>
-		p.status === "missing" || p.status === "off-path";
+		p.status === "missing" ||
+		p.status === "outdated" ||
+		p.status === "off-path";
 	if (!presences.some(reportable)) return;
 
 	const byName = new Map(reqs.map((r) => [r.name, r]));