magus-cli 7.10.5 → 7.11.0

package/src/__tests__/blind/requires-min-version/surfaces.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	type Raw,
+	type World,
+	configureClaude,
+	linkExecutable,
+	makeHookPlugin,
+	makePlugin,
+	makeWorld,
+	removeWorld,
+	requirement,
+	requires,
+	runDoctor,
+	runHook,
+	sessionInput,
+	writeExecutable,
+} from "./support";
+
+// Fake bun: answers --version, does nothing for `add` (so an "upgrade" leaves
+// the old binary in place). Never the real bun.
+async function fakeBun(world: World): Promise<void> {
+	await writeExecutable(
+		join(world.bin, "bun"),
+		'if [ "$1" = "--version" ]; then echo 1.4.0; exit 0; fi\nexit 0',
+	);
+}
+
+function bunAndWidget(minVersion: string): Raw {
+	return requires([
+		requirement("bun", [{ tool: "bun", via: "bootstrap" }]),
+		requirement("widget", [{ package: "widget", via: "bun" }], { minVersion }),
+	]);
+}
+
+async function installPlugin(
+	world: World,
+	name: string,
+	value: Raw,
+): Promise<string> {
+	const root = await makePlugin(world, name, value);
+	await configureClaude(world, [{ key: `${name}@test`, root, scope: "user" }]);
+	return root;
+}
+
+function parseReport<T>(result: {
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+}): T {
+	try {
+		return JSON.parse(result.stdout) as T;
+	} catch {
+		throw new Error(
+			`doctor printed no JSON (exit ${result.exitCode}); stderr: ${result.stderr.slice(0, 400)}`,
+		);
+	}
+}
+
+interface Dep {
+	name: string;
+	status: string;
+	found?: string;
+	minVersion?: string;
+	fix?: { text: string };
+}
+
+describe("magus doctor with an outdated dependency", () => {
+	// REQ-27: DEPS_REPORT_SCHEMA 2; status "outdated"; found/minVersion only then.
+	test("REQ-27 --json reports schema 2 and an outdated dep with found and floor", async () => {
+		const world = await makeWorld();
+		try {
+			await fakeBun(world);
+			await writeExecutable(join(world.bin, "widget"), "echo widget 1.2.0");
+			await installPlugin(world, "testdata", bunAndWidget("2.0.0"));
+			const result = await runDoctor(world, ["--json"]);
+			expect(result.timedOut).toBe(false);
+			const report = parseReport<{ schema: number; deps: Dep[] }>(result);
+			expect(report.schema).toBe(2);
+			const widget = report.deps.find((d) => d.name === "widget");
+			expect(widget).toMatchObject({
+				found: "1.2.0",
+				minVersion: "2.0.0",
+				status: "outdated",
+			});
+			expect(widget?.fix?.text).toBe("bun add -g widget@latest");
+			const bun = report.deps.find((d) => d.name === "bun");
+			expect(bun?.status).toBe("present");
+			expect(bun).not.toHaveProperty("found");
+			expect(bun).not.toHaveProperty("minVersion");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// REQ-28: "magus doctor text: Outdated rows are failures and count toward the exit code."
+	test("REQ-28 text doctor exits non-zero for an outdated dep, zero once satisfied", async () => {
+		const world = await makeWorld();
+		try {
+			await fakeBun(world);
+			await writeExecutable(join(world.bin, "widget"), "echo widget 1.2.0");
+			await installPlugin(world, "testdata", bunAndWidget("2.0.0"));
+			const outdated = await runDoctor(world, []);
+			expect(outdated.timedOut).toBe(false);
+			expect(outdated.exitCode).not.toBe(0);
+			expect(outdated.stdout + outdated.stderr).toContain("1.2.0");
+
+			await writeExecutable(join(world.bin, "widget"), "echo widget 2.0.0");
+			const healthy = await runDoctor(world, []);
+			expect(healthy.exitCode).toBe(0);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// REQ-29: after install, still outdated → failed; remedy names found, floor, onPath.
+	test("REQ-29 --fix that leaves the old binary first on PATH reports failed with a remedy", async () => {
+		const world = await makeWorld();
+		try {
+			await fakeBun(world);
+			await writeExecutable(join(world.bin, "widget"), "echo widget 1.2.0");
+			await installPlugin(world, "testdata", bunAndWidget("2.0.0"));
+			const result = await runDoctor(world, ["--fix", "--yes", "--json"]);
+			expect(result.timedOut).toBe(false);
+			expect(result.exitCode).not.toBe(0);
+			const report = parseReport<{
+				applied?: Array<{
+					name: string;
+					status: string;
+					remedy?: string;
+					argv?: string[];
+				}>;
+			}>(result);
+			expect(report.applied).toBeDefined();
+			const applied = (report.applied ?? []).find((a) => a.name === "widget");
+			expect(applied?.status).toBe("failed");
+			// The executor may resolve argv[0] to an absolute path ("exactly what
+			// ran"); the spec fixes the rendered step, not how bun is located.
+			expect(applied?.argv?.[0]?.split("/").pop()).toBe("bun");
+			expect(applied?.argv?.slice(1)).toEqual(["add", "-g", "widget@latest"]);
+			expect(applied?.remedy).toContain("1.2.0");
+			expect(applied?.remedy).toContain("2.0.0");
+			expect(applied?.remedy).toContain(join(world.bin, "widget"));
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});
+
+describe("SessionStart hook with an outdated dependency", () => {
+	// REQ-30: "An outdated dep is claimed and reported once per session, like a missing one."
+	test("REQ-30 reports an outdated dep once per session", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(
+				world,
+				"outdated",
+				requires([
+					requirement("widget", [{ formula: "widget", via: "brew" }], {
+						minVersion: "2.0.0",
+					}),
+				]),
+			);
+			// The hook itself needs a bun to execute TypeScript, as in the schema-1 suite.
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "brew"), "exit 0");
+			await writeExecutable(join(world.bin, "widget"), "echo widget 1.5.0");
+			const input = sessionInput("outdated-session");
+			const first = await runHook(
+				world,
+				plugin,
+				"outdated",
+				[world.bin],
+				input,
+			);
+			expect(first.timedOut).toBe(false);
+			expect(first.exitCode).toBe(0);
+			const banner = JSON.parse(first.stdout) as { systemMessage: string };
+			expect(banner.systemMessage).toContain("magus-deps");
+			expect(banner.systemMessage).toContain(
+				"outdated widget 1.5.0 (needs 2.0.0)",
+			);
+			const second = await runHook(
+				world,
+				plugin,
+				"outdated",
+				[world.bin],
+				input,
+			);
+			expect(second.exitCode).toBe(0);
+			expect(second.stdout).toBe("");
+			expect(
+				await readdir(
+					join(world.tmp, "magus-deps-outdated-session", "claimed"),
+				),
+			).toHaveLength(1);
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	test("REQ-30 a satisfied floor keeps the hook silent", async () => {
+		const world = await makeWorld();
+		try {
+			const plugin = await makeHookPlugin(
+				world,
+				"fresh",
+				requires([
+					requirement("widget", [{ formula: "widget", via: "brew" }], {
+						minVersion: "2.0.0",
+					}),
+				]),
+			);
+			await linkExecutable(world.bin, "bun", process.execPath);
+			await writeExecutable(join(world.bin, "widget"), "echo widget 2.3.0");
+			const result = await runHook(
+				world,
+				plugin,
+				"fresh",
+				[world.bin],
+				sessionInput("fresh-session"),
+			);
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout).toBe("");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});

package/src/__tests__/blind/review-followups/bun-install-path.test.ts

@@ -18,7 +18,7 @@ test("a Bun under BUN_INSTALL is reported as installed but absent from Claude Co
 	try {
 		const plugin = await makeHookPlugin(world, "bun-install", {
 			bin: [],
-			schema: 1,
+			schema: 2,
 		});
 		const shellPath = await makeShellPath(world);
 		const bunInstall = join(world.root, "bun-install");

package/src/__tests__/blind/review-followups/ledger-permissions.test.ts

@@ -43,7 +43,7 @@ test("the TypeScript hook and shell fallback create ledger directories private t
 	const world = await makeWorld();
 	try {
 		const plugin = await makeHookPlugin(world, "private-ledger", {
-			schema: 1,
+			schema: 2,
 			bin: [],
 		});
 		const shellPath = await makeShellPath(world);

package/src/__tests__/blind/review-followups/ledger-pruning.test.ts

@@ -26,7 +26,7 @@ test("each stale ledger is pruned even when another stale ledger cannot be remov
 	let blocked = "";
 	try {
 		const plugin = await makeHookPlugin(world, "ledger-pruning", {
-			schema: 1,
+			schema: 2,
 			bin: [],
 		});
 		const shellPath = await makeShellPath(world);

package/src/__tests__/blind/review-followups/path-advice.test.ts

@@ -17,7 +17,7 @@ test("doctor does not advise adding a PATH line already present in the shell rc
 		const rcLine = 'export PATH="$HOME/.bun/bin:$PATH"';
 		await writeFile(join(world.home, ".zshrc"), `${rcLine}\n`);
 		const plugin = await makePlugin(world, "path-advice", {
-			schema: 1,
+			schema: 2,
 			bin: [
 				{
 					name: "bun",

package/src/__tests__/deps-check-hook.test.ts

@@ -105,14 +105,14 @@ const ledger = (sessionId = "s-1") => join(tmp, `magus-deps-${sessionId}`);
 describe("deps-check hook", () => {
 	test("healthy: prints nothing, and the ledger proves it ran", () => {
 		tool("jq");
-		const dir = plugin("dev", { schema: 1, bin: [JQ] });
+		const dir = plugin("dev", { schema: 2, bin: [JQ] });
 		const r = runHook("dev", dir);
 		expect(r).toEqual({ stdout: "", exitCode: 0 });
 		expect(readFileSync(join(ledger(), "seen", "dev"), "utf8")).toBe("ts");
 	});
 
 	test("missing: one systemMessage with the marker, the dep and its fix", () => {
-		const dir = plugin("dev", { schema: 1, bin: [JQ] });
+		const dir = plugin("dev", { schema: 2, bin: [JQ] });
 		const r = runHook("dev", dir);
 		expect(r.exitCode).toBe(0);
 		const out = JSON.parse(r.stdout) as {
@@ -134,7 +134,7 @@ describe("deps-check hook", () => {
 
 	test("magus on PATH: the fix names magus alone", () => {
 		tool("magus");
-		const dir = plugin("dev", { schema: 1, bin: [JQ] });
+		const dir = plugin("dev", { schema: 2, bin: [JQ] });
 		const out = JSON.parse(runHook("dev", dir).stdout) as {
 			systemMessage: string;
 		};
@@ -149,7 +149,7 @@ describe("deps-check hook", () => {
 				JSON.parse(
 					runHook(
 						"dev",
-						plugin("dev", { schema: 1, bin: [JQ] }),
+						plugin("dev", { schema: 2, bin: [JQ] }),
 						session,
 						input,
 					).stdout,
@@ -174,10 +174,10 @@ describe("deps-check hook", () => {
 	});
 
 	test("one identical declaration in two plugins is reported once per session", () => {
-		const first = runHook("dev", plugin("dev", { schema: 1, bin: [JQ] }));
+		const first = runHook("dev", plugin("dev", { schema: 2, bin: [JQ] }));
 		const second = runHook(
 			"code-search",
-			plugin("code-search", { schema: 1, bin: [JQ] }),
+			plugin("code-search", { schema: 2, bin: [JQ] }),
 		);
 		expect(first.stdout).toContain("magus-deps · dev: missing jq");
 		expect(second.stdout).toBe("");
@@ -188,14 +188,14 @@ describe("deps-check hook", () => {
 	});
 
 	test("no readable session id: no ledger, and the banner still prints", () => {
-		const dir = plugin("dev", { schema: 1, bin: [JQ] });
+		const dir = plugin("dev", { schema: 2, bin: [JQ] });
 		const r = runHook("dev", dir, null);
 		expect(r.stdout).toContain("magus-deps · dev: missing jq");
 		expect(existsSync(tmp) && readdirSync(tmp)).toEqual([]);
 	});
 
 	test("an invalid declaration is reported, not swallowed", () => {
-		const dir = plugin("dev", { schema: 1, bin: [{ name: "jq" }] });
+		const dir = plugin("dev", { schema: 2, bin: [{ name: "jq" }] });
 		const out = JSON.parse(runHook("dev", dir).stdout) as {
 			systemMessage: string;
 		};
@@ -213,7 +213,7 @@ describe("deps-check hook", () => {
 		const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000);
 		require("node:fs").utimesSync(old, twoDaysAgo, twoDaysAgo);
 		tool("jq");
-		runHook("dev", plugin("dev", { schema: 1, bin: [JQ] }));
+		runHook("dev", plugin("dev", { schema: 2, bin: [JQ] }));
 		expect(existsSync(old)).toBe(false);
 		expect(existsSync(fresh)).toBe(true);
 	});

package/src/__tests__/deps-plan.test.ts

@@ -262,7 +262,7 @@ describe("planDeps", () => {
 		for (const via of ["npm", "pip", "go"]) {
 			const parsed = parseRequires({
 				requires: {
-					schema: 1,
+					schema: 2,
 					bin: [{ name: "x", check: ["x"], install: [{ via, package: "x" }] }],
 				},
 			});

package/src/__tests__/deps-report.test.ts

@@ -66,7 +66,7 @@ const TMUX_MCP = {
 	],
 };
 
-const manifest = (bin: unknown[], schema = 1) => ({
+const manifest = (bin: unknown[], schema = 2) => ({
 	requires: { schema, bin },
 });
 
@@ -117,9 +117,9 @@ describe("collectDeps", () => {
 		const collected = await collectDeps(
 			root,
 			sources({
-				"new@x": manifest([BUN], 2),
-				"old@x": manifest([BUN], 0),
-				"bad@x": { requires: { schema: 1, bin: [{ name: "x" }] } },
+				"new@x": manifest([BUN], 3),
+				"old@x": manifest([BUN], 1),
+				"bad@x": { requires: { schema: 2, bin: [{ name: "x" }] } },
 			}),
 		);
 		expect(collected.problems.map((p) => [p.plugin, p.kind])).toEqual([
@@ -132,7 +132,7 @@ describe("collectDeps", () => {
 });
 
 describe("depsReportJson", () => {
-	test("names tmux-mcp missing with its release install, in the schema-1 shape", async () => {
+	test("names tmux-mcp missing with its release install, in the schema-2 shape", async () => {
 		const state = await assessDeps(
 			root,
 			env,

package/src/__tests__/doctor-json.test.ts

@@ -36,7 +36,7 @@ beforeEach(() => {
 		JSON.stringify({
 			name: "fake",
 			requires: {
-				schema: 1,
+				schema: 2,
 				bin: [
 					{
 						name: "faketool",
@@ -117,7 +117,7 @@ describe("magus doctor --json", () => {
 		const r = doctor("--json");
 		expect(r.code).toBe(1);
 		const doc = JSON.parse(r.out);
-		expect(doc.schema).toBe(1);
+		expect(doc.schema).toBe(2);
 		expect(doc.plugins).toEqual(["fake@magus"]);
 		expect(doc.deps).toEqual([
 			{

package/src/__tests__/marketplace-refresh.test.ts

@@ -60,7 +60,7 @@ function writePluginJson(dir: string, version: string, pin: string) {
 		JSON.stringify({
 			version,
 			requires: {
-				schema: 1,
+				schema: 2,
 				bin: [{ name: "x", install: [{ via: "release", tag: pin }] }],
 			},
 		}),

package/src/__tests__/plugin-requires.test.ts

@@ -23,7 +23,7 @@ const BUN: Requirement = {
 };
 const declares = (bin: Requirement[]) => ({
 	name: "p",
-	requires: { schema: 1, bin },
+	requires: { schema: 2, bin },
 });
 
 let dir: string;
@@ -60,7 +60,7 @@ describe("readPluginRequires", () => {
 	test("an invalid declaration is reported, never dropped to empty", async () => {
 		await fs.outputJson(join(dir, ".claude-plugin", "plugin.json"), {
 			name: "p",
-			requires: { schema: 1, bin: [{ name: "x", via: "brew" }] },
+			requires: { schema: 2, bin: [{ name: "x", via: "brew" }] },
 		});
 		const r = await readPluginRequires(dir);
 		expect(r?.ok).toBe(false);

package/src/__tests__/requires-probe.test.ts

@@ -156,10 +156,10 @@ describe("parseRequires", () => {
 	});
 
 	test("schema: newer asks for a newer magus-cli, older for a newer plugin", () => {
-		const newer = parseRequires({ requires: { schema: 2, bin: [] } });
+		const newer = parseRequires({ requires: { schema: 3, bin: [] } });
 		expect(newer.ok ? null : newer.kind).toBe("newer-schema");
 		expect(newer.ok ? "" : newer.errors[0]).toContain("update magus-cli");
-		const older = parseRequires({ requires: { schema: 0, bin: [] } });
+		const older = parseRequires({ requires: { schema: 1, bin: [] } });
 		expect(older.ok ? null : older.kind).toBe("older-schema");
 		expect(older.ok ? "" : older.errors[0]).toContain("update the plugin");
 		const none = parseRequires({ requires: { bin: [] } });

package/src/cli/deps-view.ts

@@ -18,7 +18,7 @@ import {
 	requiredByOf,
 } from "../services/deps-plan.js";
 import type { DepsState } from "../services/deps-report.js";
-import { installText } from "../services/doctor-bins.js";
+import { installReason, installText } from "../services/doctor-bins.js";
 import {
 	type Os,
 	type Presence,
@@ -33,6 +33,8 @@ function presenceLine(name: string, p: Presence, by: string): string | null {
 			return null;
 		case "missing":
 			return `  ✗ ${name} — missing${p.blockedBy ? ` (needs ${p.blockedBy} first)` : ""}  (${by})`;
+		case "outdated":
+			return `  ✗ ${name} — outdated: ${p.found}, needs ${p.minVersion} or later  (${by})`;
 		case "off-path":
 			return `  ⚠ ${name} — installed in ${p.prefix}, which is not on the PATH Claude Code starts with  (${by})`;
 		case "unknown":
@@ -57,8 +59,8 @@ export function depsSectionLines(
 		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 === "missing" || p.status === "outdated")
+			lines.push(`      fix: ${installText(bin, env, installReason(p))}`);
 		if (p.status === "off-path") unfixable++;
 	});
 	for (const problem of collected.problems) {

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,