magus-cli 7.10.5 → 7.11.1

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/__tests__/scope-action-deprecated.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+	type ScopeStatus,
+	isInstalledInScope,
+	resolveScopeAction,
+} from "../services/plugin-manager.js";
+
+/**
+ * MTL-70: a deprecated plugin (no longer in any marketplace,
+ * `PluginInfo.isOrphaned === true`) can only be removed from a scope key.
+ * Installed in the scope → "uninstall"; not installed → "none". `behind` never
+ * matters for a deprecated plugin. Written blind from the spec.
+ */
+
+const installedScopes: Array<[string, ScopeStatus]> = [
+	["installed with a registry version", { installed: true, version: "3.0.2" }],
+	["installed with no version (files missing)", { installed: true }],
+	['installed at "0.0.0"', { installed: true, version: "0.0.0" }],
+	[
+		"installed with an unorderable sha",
+		{ installed: true, version: "3ea32df27be7" },
+	],
+];
+
+const notInstalledScopes: Array<[string, ScopeStatus | undefined]> = [
+	["an absent scope", undefined],
+	["installed: false", { installed: false }],
+	[
+		"installed: false with a registry version",
+		{ installed: false, version: "3.0.2" },
+	],
+];
+
+describe("resolveScopeAction — deprecated plugin installed in the scope (REQ-1)", () => {
+	for (const [label, scope] of installedScopes) {
+		test(`${label} is installed per isInstalledInScope (precondition)`, () => {
+			expect(isInstalledInScope(scope)).toBe(true);
+		});
+
+		for (const behind of [false, true]) {
+			test(`REQ-1: ${label}, behind=${behind} resolves to uninstall`, () => {
+				expect(resolveScopeAction(scope, behind, true)).toBe("uninstall");
+			});
+		}
+	}
+});
+
+describe("resolveScopeAction — deprecated plugin NOT installed in the scope (REQ-2)", () => {
+	for (const [label, scope] of notInstalledScopes) {
+		test(`${label} is not installed per isInstalledInScope (precondition)`, () => {
+			expect(isInstalledInScope(scope)).toBe(false);
+		});
+
+		for (const behind of [false, true]) {
+			test(`REQ-2: ${label}, behind=${behind} resolves to none — no install, no update`, () => {
+				const action = resolveScopeAction(scope, behind, true);
+				expect(action).toBe("none");
+				expect(action).not.toBe("install");
+				expect(action).not.toBe("update");
+			});
+		}
+	}
+});
+
+describe("resolveScopeAction — orphaned false or omitted is unchanged (REQ-3)", () => {
+	const cases: Array<[string, ScopeStatus | undefined, boolean, string]> = [
+		["files missing", { installed: true }, false, "install"],
+		["files missing, behind", { installed: true }, true, "install"],
+		["never installed (absent)", undefined, false, "install"],
+		["never installed (flag off)", { installed: false }, false, "install"],
+		[
+			"healthy at latest",
+			{ installed: true, version: "3.0.2" },
+			false,
+			"uninstall",
+		],
+		[
+			"healthy and behind",
+			{ installed: true, version: "2.9.0" },
+			true,
+			"update",
+		],
+	];
+
+	for (const [label, scope, behind, expected] of cases) {
+		test(`REQ-3: ${label} with orphaned omitted resolves to ${expected}`, () => {
+			expect(resolveScopeAction(scope, behind)).toBe(expected as never);
+		});
+		test(`REQ-3: ${label} with orphaned=false resolves to ${expected}`, () => {
+			expect(resolveScopeAction(scope, behind, false)).toBe(expected as never);
+		});
+	}
+
+	test("REQ-3: a non-deprecated plugin never resolves to none", () => {
+		const all: Array<ScopeStatus | undefined> = [
+			...installedScopes.map(([, s]) => s),
+			...notInstalledScopes.map(([, s]) => s),
+		];
+		for (const scope of all) {
+			for (const behind of [false, true]) {
+				expect(resolveScopeAction(scope, behind, false)).not.toBe("none");
+			}
+		}
+	});
+});

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/cli/router.ts

@@ -103,7 +103,12 @@ const SUBCOMMANDS = new Set([
 	"doctor",
 ]);
 
-/** Subcommands that read or write profile state, and so pass the gate first. */
+/**
+ * Subcommands that read or write profile state, and so pass the gate first.
+ * code-search setup runs `magus profile list` to regenerate settings.json after it
+ * edits profiles.json, so `profile` must keep running the gate
+ * (ai-docs/code-search-setup-profiles.md).
+ */
 const PROFILE_GATED = new Set(["install", "update", "profile", "models"]);
 
 export async function route(