magus-cli 7.10.4 → 7.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.10.4",
+  "version": "7.11.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -65,8 +65,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.10.4",
-    "magus-cli-darwin-x64": "7.10.4",
-    "magus-cli-linux-x64": "7.10.4"
+    "magus-cli-darwin-arm64": "7.11.0",
+    "magus-cli-darwin-x64": "7.11.0",
+    "magus-cli-linux-x64": "7.11.0"
   }
 }

package/src/__tests__/blind/plugin-deps/doctor.test.ts

@@ -25,7 +25,7 @@ function requirement(
 }
 
 function requires(bin: Record<string, unknown>[]): Record<string, unknown> {
-	return { bin, schema: 1 };
+	return { bin, schema: 2 };
 }
 
 async function installPlugin(
@@ -157,7 +157,7 @@ describe("magus doctor black-box contract", () => {
 				magusOnPath: false,
 				pathAdvice: [],
 				plugins_needing_update: [],
-				schema: 1,
+				schema: 2,
 				unfixable: [],
 			});
 			expect(report.platform).toEqual({

package/src/__tests__/blind/plugin-deps/hook.test.ts

@@ -27,7 +27,7 @@ function requirement(
 }
 
 function requires(bin: Record<string, unknown>[]): Record<string, unknown> {
-	return { bin, schema: 1 };
+	return { bin, schema: 2 };
 }
 
 describe("registered SessionStart dependency hook", () => {
@@ -292,7 +292,7 @@ describe("registered SessionStart dependency hook", () => {
 			const plugin = await makeHookPlugin(world, "invalid", {
 				bin: [],
 				mystery: true,
-				schema: 1,
+				schema: 2,
 			});
 			await linkExecutable(world.bin, "bun", process.execPath);
 			const input = sessionInput("invalid-session");

package/src/__tests__/blind/plugin-deps/read-only.test.ts

@@ -30,7 +30,7 @@ test("all doctor modes leave Claude Code marketplace state byte-identical", asyn
 						name: "present-tool",
 					},
 				],
-				schema: 1,
+				schema: 2,
 			},
 			join(clone, "plugins"),
 		);

package/src/__tests__/blind/plugin-deps/schema.test.ts

@@ -13,7 +13,7 @@ function requirement(
 }
 
 function manifest(bin: Record<string, unknown>[]): Record<string, unknown> {
-	return { requires: { bin, schema: 1 } };
+	return { requires: { bin, schema: 2 } };
 }
 
 function invalidText(value: unknown): string {
@@ -26,7 +26,7 @@ function invalidText(value: unknown): string {
 	return result.errors.join("\n");
 }
 
-describe("requires schema 1", () => {
+describe("requires schema 2", () => {
 	// Spec: AS-BUILT.md §1, “brew takes EXACTLY ONE ...” through the
 	// renderInstall table define the seven manifest installer kinds.
 	test("accepts a complete declaration of every manifest via", () => {
@@ -78,7 +78,7 @@ describe("requires schema 1", () => {
 	// level, a requirement, an option) ... error naming the key.”
 	test("rejects and locates unknown keys at all three schema levels", () => {
 		const top = invalidText({
-			requires: { bin: [], mysteryTop: true, schema: 1 },
+			requires: { bin: [], mysteryTop: true, schema: 2 },
 		});
 		const req = invalidText(
 			manifest([
@@ -102,7 +102,7 @@ describe("requires schema 1", () => {
 		expect(option).toContain("mysteryOption");
 	});
 
-	// Spec: AS-BUILT.md §1, “schema greater than 1 ... smaller ...;
+	// Spec: AS-BUILT.md §1, “schema greater than 2 ... smaller ...;
 	// missing/non-number → invalid” and “no requires key ... empty.”
 	test("classifies schema versions and treats no requires as empty", () => {
 		expect(parseRequires({})).toEqual({ ok: true, requirements: [] });
@@ -112,11 +112,11 @@ describe("requires schema 1", () => {
 				ok: false,
 			});
 		}
-		expect(parseRequires({ requires: { bin: [], schema: 2 } })).toMatchObject({
+		expect(parseRequires({ requires: { bin: [], schema: 3 } })).toMatchObject({
 			kind: "newer-schema",
 			ok: false,
 		});
-		expect(parseRequires({ requires: { bin: [], schema: 0 } })).toMatchObject({
+		expect(parseRequires({ requires: { bin: [], schema: 1 } })).toMatchObject({
 			kind: "older-schema",
 			ok: false,
 		});

package/src/__tests__/blind/requires-min-version/TEST-PLAN.md

@@ -0,0 +1,54 @@
+# Test Plan: requires schema 2 — minVersion per dependency
+
+- **Spec**: docs/plans/2026-10-20-requires-min-version.md
+- **Contract**: ai-docs/plugin-deps-contract/contract/requires-probe.d.ts, contract/doctor-json.d.ts (schema 1; schema-2 additions taken from the spec)
+- **Stack**: bun   **Framework**: bun:test   **Scenarios**: 109 tests (parameterised)
+
+Fake executables are `#!/bin/sh` scripts in a temp dir that print a chosen version and exit
+with a chosen code. The hook tests link the test runner's own bun only to execute the hook's
+TypeScript, as the schema-1 blind suite does; no test reads the real claudish or bun version.
+
+## Scenarios (grouped)
+
+| Group | Type | Priority | Given / When / Then | REQ |
+|---|---|---|---|---|
+| parse.test.ts schema | unit | critical | REQUIRES_SCHEMA is 2; schema 1 → older-schema; 3 → newer-schema; no requires → empty | 1, 2 |
+| parse.test.ts field | unit | critical | minVersion X.Y.Z ok and kept on the requirement; v10.7.0, 10.7, 10.7.0-beta, 10.7.0.1, 10, "", " 10.7.0", 10.x.0, number → invalid; unknown key invalid and named | 3, 4, 5 |
+| parse.test.ts pins | unit | high | release tag (with/without v) below floor invalid, at/above valid; numeric; non-X.Y.Z tag invalid; vv invalid; no floor → not compared; exact bun version below floor invalid, at/above valid; ranges/tags/no version not compared | 6, 7 |
+| probe.test.ts × {presence, full} | integration | critical | >= floor present; < floor outdated {found,minVersion}; no version → unknown `no version in "tool --version" output`; stderr read; stdout wins; first match; suffix ignored; numeric; non-zero exit/absent → missing; slow → unknown; dependent of outdated is probed; order kept | 8–18 |
+| probe.test.ts no floor | integration | high | presence depth: unfloored self-named check is PATH-only (exit-1 fake present, not run); same fake with a floor runs → missing; full depth unchanged | 12 |
+| render.test.ts renderInstall | unit | critical | bun missing/outdated (@latest, @version), brew formula upgrade, brew cask upgrade --cask; other vias identical across reasons; describeStep of outdated bun | 19–22 |
+| render.test.ts renderFix | unit | high | outdated → banner with `outdated <name> <found> (needs <min>)` and the upgrade line; healthy → null | 23, 24 |
+| manifests.test.ts | unit | critical | every shipped plugin.json with requires is schema 2 and parses; claudish's claudish has minVersion 10.7.0; no other floors | 25, 26 |
+| surfaces.test.ts doctor | e2e (CLI) | high | --json schema 2, outdated dep with found/minVersion, fix text `bun add -g widget@latest`; text doctor exit non-zero; --fix leaving old binary → failed, remedy names found, floor, onPath | 27, 28, 29 |
+| surfaces.test.ts hook | e2e (hook) | high | outdated dep reported once per session with the head text; satisfied floor silent | 30 |
+
+## Coverage map
+
+| Requirement | Tests | Covered |
+|---|---|---|
+| REQ-1 REQUIRES_SCHEMA = 2 | parse | yes |
+| REQ-2 one schema only (1 → older, 3 → newer) | parse | yes |
+| REQ-3 minVersion shape | parse | yes |
+| REQ-4 optional field | parse, probe | yes |
+| REQ-5 allowed keys | parse | yes |
+| REQ-6 release tag vs floor | parse | yes |
+| REQ-7 exact bun version vs floor | parse | yes |
+| REQ-8..11, 13, 14 version reading and comparison | probe (both depths) | yes |
+| REQ-12 floored requirement always runs its check | probe | yes |
+| REQ-15, 16 non-zero/timeout as schema 1 | probe | yes |
+| REQ-17 blockedBy unchanged for outdated | probe | yes |
+| REQ-19..22 renderInstall reason | render | yes |
+| REQ-23, 24 renderFix | render | yes |
+| REQ-25, 26 shipped declarations | manifests | yes |
+| REQ-27 doctor --json schema 2 | surfaces | yes |
+| REQ-28 doctor text exit code | surfaces | yes |
+| REQ-29 executor: still outdated → failed + remedy | surfaces | yes |
+| REQ-30 hook ledger | surfaces | yes |
+
+## Known gaps
+
+- TUI (`cliToolsAdapter`, `depsAdapter`): no public contract was supplied for these surfaces.
+- Repo gate `scripts/check-plugin-requires.ts --self-test`: outside the contract given.
+- Hook-copy byte identity (`check:hook-copies`): a repo gate, not behaviour of the contract.
+- Rollout messages ("update magus-cli" / "update the plugin"): only the parse kinds are asserted, not doctor's wording.

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

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseRequires } from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import { REPO_ROOT } from "./support";
+
+const PLUGINS = join(REPO_ROOT, "plugins");
+
+function manifestPath(plugin: string): string {
+	return join(PLUGINS, plugin, ".claude-plugin", "plugin.json");
+}
+
+const declaring = readdirSync(PLUGINS)
+	.filter((name) => existsSync(manifestPath(name)))
+	.map((name) => ({
+		json: JSON.parse(readFileSync(manifestPath(name), "utf8")) as Record<
+			string,
+			unknown
+		>,
+		name,
+	}))
+	.filter(({ json }) => json.requires !== undefined);
+
+describe("shipped plugin manifests under schema 2", () => {
+	test("REQ-25 at least one shipped manifest declares requires (the scan is not empty)", () => {
+		expect(declaring.map(({ name }) => name)).toContain("claudish");
+	});
+
+	// REQ-25: "Every plugin.json with requires moves to schema: 2."
+	for (const { name, json } of declaring) {
+		test(`REQ-25 ${name}: requires declares schema 2 and parses ok`, () => {
+			expect((json.requires as Record<string, unknown>).schema).toBe(2);
+			const result = parseRequires(json);
+			if (!result.ok) {
+				throw new Error(`${name}: ${result.kind}: ${result.errors.join("; ")}`);
+			}
+			expect(result.ok).toBe(true);
+		});
+	}
+
+	// REQ-26: claudish gets minVersion 10.7.0; no other requirement gets a floor.
+	test("REQ-26 claudish's claudish requirement has minVersion 10.7.0", () => {
+		const claudish = declaring.find(({ name }) => name === "claudish");
+		if (!claudish) throw new Error("plugins/claudish declares no requires");
+		const result = parseRequires(claudish.json);
+		if (!result.ok)
+			throw new Error(`${result.kind}: ${result.errors.join("; ")}`);
+		const req = result.requirements.find((r) => r.name === "claudish") as
+			| (Record<string, unknown> & { name: string })
+			| undefined;
+		expect(req).toBeDefined();
+		expect(req?.minVersion).toBe("10.7.0");
+	});
+
+	test("REQ-26 no other shipped requirement declares a floor", () => {
+		const floored: string[] = [];
+		for (const { name, json } of declaring) {
+			const bin = ((json.requires as Record<string, unknown>).bin ??
+				[]) as Array<Record<string, unknown>>;
+			for (const r of bin) {
+				if (r.minVersion !== undefined)
+					floored.push(`${name}:${String(r.name)}`);
+			}
+		}
+		expect(floored).toEqual(["claudish:claudish"]);
+	});
+});

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

@@ -0,0 +1,266 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+	REQUIRES_SCHEMA,
+	parseRequires,
+} from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import { manifest, releaseOption, requirement } from "./support";
+
+const brew = [{ formula: "tool", via: "brew" }];
+// A via:bun option needs "bun" declared in the same plugin (schema-1 rule),
+// so every bun-option testdata carries this, and an invalid result can only
+// come from the floor comparison.
+const bunDecl = requirement("bun", [{ tool: "bun", via: "bootstrap" }]);
+
+function okRequirements(value: unknown) {
+	const result = parseRequires(value);
+	if (!result.ok) {
+		throw new Error(
+			`expected ok, got ${result.kind}: ${result.errors.join("; ")}`,
+		);
+	}
+	return result.requirements;
+}
+
+function expectInvalid(value: unknown): string {
+	const result = parseRequires(value);
+	expect(result.ok).toBe(false);
+	if (result.ok) throw new Error("testdata unexpectedly parsed");
+	expect(result.kind).toBe("invalid");
+	expect(result.errors.length).toBeGreaterThan(0);
+	return result.errors.join("\n");
+}
+
+describe("requires schema 2: version and schema number", () => {
+	// REQ-1: "any shape change bumps requires.schema, so this is schema 2"
+	test("REQ-1 REQUIRES_SCHEMA is 2", () => {
+		expect(REQUIRES_SCHEMA).toBe(2);
+	});
+
+	// REQ-2: "A reader reads exactly one schema: there is no schema-1 reading path"
+	test("REQ-2 a schema-1 requires block is older-schema, not parsed", () => {
+		expect(
+			parseRequires(manifest([requirement("tool", brew)], 1)),
+		).toMatchObject({ kind: "older-schema", ok: false });
+	});
+
+	test("REQ-2 a schema-3 requires block is newer-schema", () => {
+		expect(
+			parseRequires(manifest([requirement("tool", brew)], 3)),
+		).toMatchObject({ kind: "newer-schema", ok: false });
+	});
+
+	test("REQ-2 a manifest without requires still parses as empty", () => {
+		expect(parseRequires({ name: "p" })).toEqual({
+			ok: true,
+			requirements: [],
+		});
+	});
+});
+
+describe("requires schema 2: the minVersion field", () => {
+	// REQ-3: Shape ^\d+\.\d+\.\d+$
+	test("REQ-3 accepts minVersion X.Y.Z and keeps it on the requirement", () => {
+		const reqs = okRequirements(
+			manifest([requirement("tool", brew, { minVersion: "10.7.0" })]),
+		);
+		expect(reqs).toHaveLength(1);
+		expect(reqs[0]).toMatchObject({ minVersion: "10.7.0", name: "tool" });
+	});
+
+	// REQ-4: Optional — a requirement without it behaves as in schema 1.
+	test("REQ-4 a requirement without minVersion parses ok", () => {
+		const reqs = okRequirements(manifest([requirement("tool", brew)]));
+		expect(reqs).toHaveLength(1);
+		expect(reqs[0].name).toBe("tool");
+	});
+
+	// REQ-3: "three numeric parts, no v, no prerelease. Anything else is invalid."
+	for (const bad of [
+		"v10.7.0",
+		"10.7",
+		"10.7.0-beta",
+		"10.7.0.1",
+		"10",
+		"",
+		" 10.7.0",
+		"10.x.0",
+	]) {
+		test(`REQ-3 rejects minVersion ${JSON.stringify(bad)} as invalid`, () => {
+			expectInvalid(manifest([requirement("tool", brew, { minVersion: bad })]));
+		});
+	}
+
+	test("REQ-3 rejects a numeric (non-string) minVersion as invalid", () => {
+		expectInvalid(manifest([requirement("tool", brew, { minVersion: 10.7 })]));
+	});
+
+	// REQ-5: allowed keys are name, check, os, minVersion, install.
+	test("REQ-5 an unknown requirement key is still invalid and named", () => {
+		const errors = expectInvalid(
+			manifest([
+				requirement("tool", brew, {
+					minVersion: "1.0.0",
+					minimumVersion: "1.0.0",
+				}),
+			]),
+		);
+		expect(errors).toContain("minimumVersion");
+	});
+
+	test("REQ-5 os and minVersion together are allowed", () => {
+		const reqs = okRequirements(
+			manifest([
+				requirement(
+					"tool",
+					[{ formula: "tool", os: ["darwin"], via: "brew" }],
+					{
+						minVersion: "1.0.0",
+						os: ["darwin"],
+					},
+				),
+			]),
+		);
+		expect(reqs).toHaveLength(1);
+	});
+});
+
+describe("requires schema 2: pinned installs against the floor", () => {
+	// REQ-6: release tag, one leading v removed, must parse X.Y.Z and be >= minVersion.
+	test("REQ-6 a release tag below the floor is invalid", () => {
+		expectInvalid(
+			manifest([
+				requirement("tool", [releaseOption("v10.6.9")], {
+					minVersion: "10.7.0",
+				}),
+			]),
+		);
+	});
+
+	test("REQ-6 a release tag below the floor without a v is invalid", () => {
+		expectInvalid(
+			manifest([
+				requirement("tool", [releaseOption("10.6.9")], {
+					minVersion: "10.7.0",
+				}),
+			]),
+		);
+	});
+
+	for (const tag of ["v10.7.0", "10.7.0", "v10.7.1", "10.8.0", "v11.0.0"]) {
+		test(`REQ-6 a release tag ${tag} at or above floor 10.7.0 is valid`, () => {
+			expect(
+				okRequirements(
+					manifest([
+						requirement("tool", [releaseOption(tag)], { minVersion: "10.7.0" }),
+					]),
+				),
+			).toHaveLength(1);
+		});
+	}
+
+	test("REQ-6 tag comparison is numeric: v10.10.0 satisfies 10.9.0", () => {
+		expect(
+			okRequirements(
+				manifest([
+					requirement("tool", [releaseOption("v10.10.0")], {
+						minVersion: "10.9.0",
+					}),
+				]),
+			),
+		).toHaveLength(1);
+	});
+
+	test("REQ-6 tag comparison is numeric: v10.9.0 is below 10.10.0", () => {
+		expectInvalid(
+			manifest([
+				requirement("tool", [releaseOption("v10.9.0")], {
+					minVersion: "10.10.0",
+				}),
+			]),
+		);
+	});
+
+	test("REQ-6 a release tag that is not X.Y.Z is invalid when a floor is set", () => {
+		expectInvalid(
+			manifest([
+				requirement("tool", [releaseOption("v10")], { minVersion: "1.0.0" }),
+			]),
+		);
+	});
+
+	test("REQ-6 only one leading v is removed: vv10.7.0 is invalid", () => {
+		expectInvalid(
+			manifest([
+				requirement("tool", [releaseOption("vv10.7.0")], {
+					minVersion: "10.7.0",
+				}),
+			]),
+		);
+	});
+
+	test("REQ-4 without a floor a release tag is not compared (v1 stays valid)", () => {
+		expect(
+			okRequirements(manifest([requirement("tool", [releaseOption("v1")])])),
+		).toHaveLength(1);
+	});
+
+	// REQ-7: exact bun version must be >= minVersion; ranges and tags not compared.
+	test("REQ-7 an exact bun version below the floor is invalid", () => {
+		expectInvalid(
+			manifest([
+				bunDecl,
+				requirement(
+					"tool",
+					[{ package: "tool", version: "10.6.0", via: "bun" }],
+					{
+						minVersion: "10.7.0",
+					},
+				),
+			]),
+		);
+	});
+
+	for (const version of ["10.7.0", "10.12.3"]) {
+		test(`REQ-7 an exact bun version ${version} at or above the floor is valid`, () => {
+			expect(
+				okRequirements(
+					manifest([
+						bunDecl,
+						requirement("tool", [{ package: "tool", version, via: "bun" }], {
+							minVersion: "10.7.0",
+						}),
+					]),
+				),
+			).toHaveLength(2);
+		});
+	}
+
+	for (const version of ["^1.2.0", "latest", "~9.0.0"]) {
+		test(`REQ-7 a bun range or tag ${version} is not compared to the floor`, () => {
+			expect(
+				okRequirements(
+					manifest([
+						bunDecl,
+						requirement("tool", [{ package: "tool", version, via: "bun" }], {
+							minVersion: "10.7.0",
+						}),
+					]),
+				),
+			).toHaveLength(2);
+		});
+	}
+
+	test("REQ-7 a bun option with no version is valid under a floor", () => {
+		expect(
+			okRequirements(
+				manifest([
+					bunDecl,
+					requirement("tool", [{ package: "tool", via: "bun" }], {
+						minVersion: "10.7.0",
+					}),
+				]),
+			),
+		).toHaveLength(2);
+	});
+});