magus-cli 7.7.0 → 7.9.0

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

@@ -0,0 +1,96 @@
+import { expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+	makePlugin,
+	makeWorld,
+	removeWorld,
+	runDoctor,
+	writeExecutable,
+	writeJson,
+} from "./helpers";
+
+// Spec: AS-BUILT.md §5, doctor, doctor --json, and doctor --fix --yes
+// leave all five Claude Code files byte-identical even when a marketplace
+// lists a plugin whose source directory is missing.
+test("all doctor modes leave Claude Code marketplace state byte-identical", async () => {
+	const world = await makeWorld();
+	try {
+		const claude = join(world.home, ".claude");
+		const clone = join(claude, "plugins", "marketplaces", "test");
+		const plugin = await makePlugin(
+			world,
+			"present",
+			{
+				bin: [
+					{
+						check: ["present-tool", "--version"],
+						install: [{ formula: "present-tool", via: "brew" }],
+						name: "present-tool",
+					},
+				],
+				schema: 1,
+			},
+			join(clone, "plugins"),
+		);
+		const marketplace = join(clone, ".claude-plugin", "marketplace.json");
+		const pluginManifest = join(plugin, ".claude-plugin", "plugin.json");
+		const known = join(claude, "plugins", "known_marketplaces.json");
+		const installed = join(claude, "plugins", "installed_plugins.json");
+		const settings = join(claude, "settings.json");
+		await writeJson(marketplace, {
+			name: "test",
+			plugins: [
+				{ name: "present", source: "./plugins/present", version: "1.0.0" },
+				{ name: "missing", source: "./plugins/missing", version: "1.0.0" },
+			],
+		});
+		await writeJson(known, {
+			test: {
+				installLocation: clone,
+				lastUpdated: "2026-01-01T00:00:00.000Z",
+				source: { repo: "Example/test", source: "github" },
+			},
+		});
+		await writeJson(installed, {
+			plugins: {
+				"present@test": [
+					{
+						installPath: plugin,
+						installedAt: "2026-01-01T00:00:00.000Z",
+						lastUpdated: "2026-01-01T00:00:00.000Z",
+						scope: "user",
+						version: "1.0.0",
+					},
+				],
+			},
+			version: 2,
+		});
+		await writeJson(settings, { enabledPlugins: { "present@test": true } });
+		await writeExecutable(join(world.bin, "present-tool"), "exit 0");
+		const protectedFiles = [
+			marketplace,
+			pluginManifest,
+			known,
+			installed,
+			settings,
+		];
+		const before = await Promise.all(
+			protectedFiles.map((path) => readFile(path)),
+		);
+		for (const args of [[], ["--json"], ["--fix", "--yes"]]) {
+			const result = await runDoctor(world, args);
+			expect(result.timedOut).toBe(false);
+			expect(result.exitCode).not.toBeNull();
+			const after = await Promise.all(
+				protectedFiles.map((path) => readFile(path)),
+			);
+			for (const [index, bytes] of after.entries()) {
+				expect(bytes.equals(before[index])).toBe(true);
+			}
+		}
+	} finally {
+		await removeWorld(world);
+	}
+});

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

@@ -0,0 +1,390 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseRequires } from "../../../shared/plugin/hooks/lib/requires-probe.js";
+
+const digest = "a".repeat(64);
+
+function requirement(
+	name: string,
+	install: Record<string, unknown>[],
+	check = [name, "--version"],
+): Record<string, unknown> {
+	return { check, install, name };
+}
+
+function manifest(bin: Record<string, unknown>[]): Record<string, unknown> {
+	return { requires: { bin, schema: 1 } };
+}
+
+function invalidText(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");
+	return result.errors.join("\n");
+}
+
+describe("requires schema 1", () => {
+	// 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", () => {
+		const value = manifest([
+			requirement("bun", [{ tool: "bun", via: "bootstrap" }]),
+			requirement("uv", [{ tool: "uv", via: "bootstrap" }]),
+			requirement("bun-tool", [
+				{ package: "@scope/tool", version: "1.2.3", via: "bun" },
+			]),
+			requirement("formula-tool", [
+				{ formula: "owner/tap/tool@2", via: "brew" },
+			]),
+			requirement("cask-tool", [{ cask: "visual-tool", via: "brew" }]),
+			requirement("apt-tool", [
+				{ packages: ["libfoo2", "foo+bar"], via: "apt" },
+			]),
+			requirement("release-tool", [
+				{
+					arch: { amd64: "x64", arm64: "aarch64" },
+					asset: "tool-{os}-{arch}.tgz",
+					binary: "tool.bin",
+					repo: "Owner/repo.name",
+					sha256: { darwin_amd64: digest },
+					tag: "v1.2.3",
+					via: "release",
+				},
+			]),
+			requirement("uv-script-tool", [
+				{ args: ["--check"], script: "scripts/tool.py", via: "uv-script" },
+			]),
+			requirement("uv-module-tool", [
+				{
+					args: ["install", "thing"],
+					module: "package.module",
+					root: true,
+					script: "scripts/tool.py",
+					via: "uv-module",
+				},
+			]),
+		]);
+		const result = parseRequires(value);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.requirements).toHaveLength(9);
+		}
+	});
+
+	// Spec: AS-BUILT.md §1, “Unknown keys anywhere inside requires (top
+	// 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 },
+		});
+		const req = invalidText(
+			manifest([
+				{
+					...requirement("tool", [{ formula: "tool", via: "brew" }]),
+					mysteryRequirement: true,
+				},
+			]),
+		);
+		const option = invalidText(
+			manifest([
+				requirement("tool", [
+					{ formula: "tool", mysteryOption: true, via: "brew" },
+				]),
+			]),
+		);
+		expect(top).toContain("mysteryTop");
+		expect(req).toContain("requires.bin[0]");
+		expect(req).toContain("mysteryRequirement");
+		expect(option).toContain("requires.bin[0]");
+		expect(option).toContain("mysteryOption");
+	});
+
+	// Spec: AS-BUILT.md §1, “schema greater than 1 ... 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: [] });
+		for (const schema of [undefined, "1", null]) {
+			expect(parseRequires({ requires: { bin: [], schema } })).toMatchObject({
+				kind: "invalid",
+				ok: false,
+			});
+		}
+		expect(parseRequires({ requires: { bin: [], schema: 2 } })).toMatchObject({
+			kind: "newer-schema",
+			ok: false,
+		});
+		expect(parseRequires({ requires: { bin: [], schema: 0 } })).toMatchObject({
+			kind: "older-schema",
+			ok: false,
+		});
+	});
+
+	// Spec: arch-7.1-7.2-schema-probe-hook.md §7.1 Schema Rules,
+	// “name ... ^[a-z0-9][a-z0-9._-]*$” and check is non-empty argv.
+	test("enforces requirement name and check argv grammars", () => {
+		const good = parseRequires(
+			manifest([
+				requirement("a.good_name-2", [{ formula: "good", via: "brew" }]),
+			]),
+		);
+		expect(good.ok).toBe(true);
+		for (const name of ["Upper", "-leading", "has space", ""]) {
+			expect(invalidText(manifest([requirement(name, [])]))).toContain(
+				"requires.bin[0]",
+			);
+		}
+		for (const check of [[], ["tool", 7]]) {
+			expect(
+				invalidText(manifest([requirement("tool", [], check as string[])])),
+			).toContain("requires.bin[0]");
+		}
+	});
+
+	// Spec: AS-BUILT.md §1, “brew takes EXACTLY ONE of formula | cask.”
+	// Design §7.1 gives the formula grammar.
+	test("enforces brew formula grammar and formula XOR cask", () => {
+		for (const option of [
+			{ via: "brew" },
+			{ cask: "tool", formula: "tool", via: "brew" },
+			{ formula: "-tool", via: "brew" },
+		]) {
+			expect(invalidText(manifest([requirement("tool", [option])]))).toContain(
+				"requires.bin[0]",
+			);
+		}
+		for (const option of [
+			{ formula: "owner/tap/tool+v2@1", via: "brew" },
+			{ cask: "visual-tool", via: "brew" },
+		]) {
+			expect(parseRequires(manifest([requirement("tool", [option])])).ok).toBe(
+				true,
+			);
+		}
+	});
+
+	// Spec: arch-7.1-7.2-schema-probe-hook.md §7.1 Schema Rules,
+	// apt package names match ^[a-z0-9][a-z0-9+.-]+$ and cannot be options.
+	test("enforces apt package grammar and a non-empty package list", () => {
+		for (const packages of [[], ["-option"], ["UPPER"], ["x"]]) {
+			expect(
+				invalidText(
+					manifest([requirement("tool", [{ packages, via: "apt" }])]),
+				),
+			).toContain("requires.bin[0]");
+		}
+		expect(
+			parseRequires(
+				manifest([
+					requirement("tool", [
+						{ packages: ["libx2", "x+extra", "x.dev"], via: "apt" },
+					]),
+				]),
+			).ok,
+		).toBe(true);
+	});
+
+	// Spec: arch-7.1-7.2-schema-probe-hook.md §7.1 Schema Rules defines
+	// release repo, tag, and binary regexes and a fixed GitHub host.
+	test("enforces release repo, tag, and binary grammars", () => {
+		const base = {
+			asset: "tool-{os}-{arch}",
+			binary: "tool",
+			repo: "Owner/repo",
+			sha256: { linux_amd64: digest },
+			tag: "v1.0",
+			via: "release",
+		};
+		for (const patch of [
+			{ repo: "one-part" },
+			{ repo: "Owner/repo/extra" },
+			{ tag: "bad tag" },
+			{ tag: "-leading" },
+			{ binary: "bad/path" },
+			{ binary: "-leading" },
+		]) {
+			expect(
+				invalidText(manifest([requirement("tool", [{ ...base, ...patch }])])),
+			).toContain("requires.bin[0]");
+		}
+		expect(parseRequires(manifest([requirement("tool", [base])])).ok).toBe(
+			true,
+		);
+	});
+
+	// Spec: AS-BUILT.md §1 says only {os}/{arch} are asset substitutions,
+	// tar.gz/tgz are archives, and the listed other archive kinds are refused.
+	test("accepts bare and tar-gzip assets but refuses unsafe templates and archives", () => {
+		const option = {
+			binary: "tool",
+			repo: "Owner/repo",
+			sha256: { linux_amd64: digest },
+			tag: "v1",
+			via: "release",
+		};
+		for (const asset of [
+			"tool-{os}-{arch}",
+			"tool-{os}-{arch}.tar.gz",
+			"tool-{os}-{arch}.tgz",
+		]) {
+			expect(
+				parseRequires(manifest([requirement("tool", [{ ...option, asset }])]))
+					.ok,
+			).toBe(true);
+		}
+		for (const asset of [
+			"tool-{platform}",
+			"tool.zip",
+			"tool.tar",
+			"tool.tar.xz",
+			"tool.txz",
+			"tool.tar.bz2",
+			"tool.tbz",
+			"tool.tbz2",
+			"tool.gz",
+			"tool.xz",
+			"tool.bz2",
+			"tool.7z",
+		]) {
+			expect(
+				invalidText(manifest([requirement("tool", [{ ...option, asset }])])),
+			).toContain("requires.bin[0]");
+		}
+	});
+
+	// Spec: AS-BUILT.md §1 limits arch keys and sha256 platform keys, and
+	// requires each digest to be 64 lowercase hexadecimal characters.
+	test("validates release arch maps and pinned digests", () => {
+		const base = {
+			asset: "tool-{os}-{arch}",
+			binary: "tool",
+			repo: "Owner/repo",
+			tag: "v1",
+			via: "release",
+		};
+		expect(
+			parseRequires(
+				manifest([
+					requirement("tool", [
+						{
+							...base,
+							arch: { amd64: "x64", arm64: "aarch64" },
+							sha256: { darwin_arm64: digest },
+						},
+					]),
+				]),
+			).ok,
+		).toBe(true);
+		for (const option of [
+			{ ...base, arch: { riscv64: "riscv" }, sha256: {} },
+			{ ...base, sha256: { windows_amd64: digest } },
+			{ ...base, sha256: { linux_amd64: "A".repeat(64) } },
+			{ ...base, sha256: { linux_amd64: "a".repeat(63) } },
+		]) {
+			expect(invalidText(manifest([requirement("tool", [option])]))).toContain(
+				"requires.bin[0]",
+			);
+		}
+	});
+
+	// Spec: arch-7.1-7.2-schema-probe-hook.md §7.1 Schema Rules says uv
+	// scripts are relative and inside the root, and defines the module regex.
+	test("enforces uv script paths and module names", () => {
+		const uv = requirement("uv", [{ tool: "uv", via: "bootstrap" }]);
+		for (const option of [
+			{ args: [], script: "/abs/tool.py", via: "uv-script" },
+			{ args: [], script: "../tool.py", via: "uv-script" },
+			{
+				args: [],
+				module: "bad-module",
+				script: "scripts/tool.py",
+				via: "uv-module",
+			},
+			{
+				args: [],
+				module: "9module",
+				script: "scripts/tool.py",
+				via: "uv-module",
+			},
+		]) {
+			expect(
+				invalidText(manifest([uv, requirement("tool", [option])])),
+			).toContain("requires.bin[1]");
+		}
+		expect(
+			parseRequires(
+				manifest([
+					uv,
+					requirement("tool", [
+						{
+							args: ["--ok"],
+							module: "good_module.child2",
+							script: "scripts/tool.py",
+							via: "uv-module",
+						},
+					]),
+				]),
+			).ok,
+		).toBe(true);
+	});
+
+	// Spec: AS-BUILT.md §1, bun and both uv options need their toolchain
+	// declared beside them in the same manifest.
+	test("requires bun and uv toolchains to be declared beside consumers", () => {
+		for (const option of [
+			{ package: "pkg", via: "bun" },
+			{ args: [], script: "tool.py", via: "uv-script" },
+			{
+				args: [],
+				module: "tool",
+				script: "tool.py",
+				via: "uv-module",
+			},
+		]) {
+			const error = invalidText(manifest([requirement("consumer", [option])]));
+			expect(error).toMatch(/bun|uv/);
+		}
+	});
+
+	// Spec: AS-BUILT.md §1, “bootstrap.tool must be a key ... AND equal
+	// the requirement's name”; a URL is an unknown key.
+	test("restricts bootstrap to its self-named built-in tool", () => {
+		expect(
+			parseRequires(
+				manifest([requirement("bun", [{ tool: "bun", via: "bootstrap" }])]),
+			).ok,
+		).toBe(true);
+		for (const option of [
+			{ tool: "unknown", via: "bootstrap" },
+			{ tool: "uv", via: "bootstrap" },
+			{
+				tool: "bun",
+				url: "https://example.invalid/install",
+				via: "bootstrap",
+			},
+		]) {
+			expect(invalidText(manifest([requirement("bun", [option])]))).toContain(
+				"requires.bin[0]",
+			);
+		}
+	});
+
+	// Spec: AS-BUILT.md §1, profile-only npm, pip, and go are refused in
+	// plugin.json; arch-2-decisions.md D2 says the installer set is closed.
+	test("refuses every profile-only installer kind", () => {
+		for (const via of ["npm", "pip", "go"]) {
+			const error = invalidText(
+				manifest([requirement("tool", [{ package: "tool", via }])]),
+			);
+			expect(error).toContain(via);
+			expect(error).toContain("not allowed");
+		}
+		expect(
+			invalidText(
+				manifest([requirement("tool", [{ package: "tool", via: "cargo" }])]),
+			),
+		).toContain("cargo");
+	});
+});