magus-cli 7.8.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");
+	});
+});

package/src/__tests__/blind-780-cli-tools.test.ts

@@ -17,10 +17,10 @@
  *   C5 stepFailureReport: settings file that does not parse, fallback fix → "C5"
  *   C6 no internal word or absolute binary path in headline/reason       → "C6"
  *
- * Errors are built in the shape Node's promisified `execFile` rejects with:
- * an Error whose message starts "Command failed: <cmd>", carrying `code`,
- * `killed`, `signal`, `stdout` and `stderr`; a missing executable is a
- * `spawn <cmd> ENOENT` with `code: "ENOENT"`. Nothing is spawned.
+ * Failures are built in the shape `runArgv` resolves with (`RunResult`):
+ * the exit code, whether the timeout killed it, the combined output tail, and
+ * for a missing executable a `spawn <cmd> ENOENT` spawn error. Nothing is
+ * spawned.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -40,6 +40,7 @@ import {
 } from "../ui/adapters/startupReports.js";
 import type { FailureReport } from "../ui/state/types.js";
 import type { Command } from "../utils/command-utils.js";
+import type { RunResult } from "../utils/run.js";
 
 /** The installer timeout the spec names: 60 seconds. */
 const TIMEOUT_MS = 60_000;
@@ -73,42 +74,43 @@ interface ExecErrorShape {
 	code?: number | string | null;
 	killed?: boolean;
 	signal?: string | null;
-	/** Extra lines appended to the "Command failed:" message. */
-	messageTail?: string;
 }
 
-/** What promisified `execFile` rejects with when the command ran and failed. */
-function execError(o: ExecErrorShape): Error {
-	const cmdLine = line(o.command);
-	const err = new Error(
-		`Command failed: ${cmdLine}${o.messageTail ? `\n${o.messageTail}` : ""}`,
-	);
-	return Object.assign(err, {
-		cmd: cmdLine,
-		code: o.code === undefined ? 1 : o.code,
-		killed: o.killed ?? false,
+/** What `runArgv` resolves with when the command ran and failed. */
+function execError(o: ExecErrorShape): RunResult {
+	return {
+		exitCode:
+			typeof o.code === "number" ? o.code : o.code === undefined ? 1 : null,
 		signal: o.signal ?? null,
-		stdout: o.stdout ?? "",
-		stderr: o.stderr ?? "",
-	});
+		timedOut: o.killed ?? false,
+		outputTail: [o.stdout ?? "", o.stderr ?? ""].filter(Boolean).join("\n"),
+		durationMs: 0,
+	};
+}
+
+/** What `runArgv` resolves with when the executable does not exist. */
+function enoent(command: Command): RunResult {
+	return {
+		exitCode: null,
+		signal: null,
+		timedOut: false,
+		spawnError: `spawn ${command.cmd} ENOENT`,
+		outputTail: "",
+		durationMs: 0,
+	};
 }
 
-/** What `execFile` rejects with when the executable does not exist. */
-function enoent(command: Command): Error {
-	const err = new Error(`spawn ${command.cmd} ENOENT`);
-	return Object.assign(err, {
+/** What a spawn throws when the executable does not exist (a step's error). */
+function enoentError(command: Command): Error {
+	return Object.assign(new Error(`spawn ${command.cmd} ENOENT`), {
 		code: "ENOENT",
-		errno: -2,
 		syscall: `spawn ${command.cmd}`,
 		path: command.cmd,
-		spawnargs: [...command.args],
-		stdout: "",
-		stderr: "",
 	});
 }
 
-/** What `execFile` rejects with when its `timeout` killed the child. */
-function timedOut(command: Command, partialStderr = ""): Error {
+/** What `runArgv` resolves with when its timeout killed the child. */
+function timedOut(command: Command, partialStderr = ""): RunResult {
 	return execError({
 		command,
 		code: null,
@@ -241,13 +243,11 @@ describe("C1 commandFailureReason", () => {
 				command: BREW_UPGRADE,
 				stdout: "==> Fetching downloads for: tmux",
 				stderr: 'Error: No available formula with the name "tmux-nope".',
-				messageTail: "some other text from the message",
 			}),
 			TIMEOUT_MS,
 		);
 		expect(reason).toContain("No available formula");
 		expect(reason).not.toContain("Fetching downloads");
-		expect(reason).not.toContain("some other text from the message");
 	});
 
 	test("C1: is one line, even when stderr has many", () => {
@@ -319,25 +319,13 @@ describe("C1 commandFailureReason", () => {
 		expect(reason.trim().length).toBeGreaterThan(0);
 	});
 
-	test("C1: never returns 'Command failed:' when the cause is only in the message tail", () => {
+	test("C1: an installer that printed nothing still yields a non-empty reason", () => {
 		const reason = commandFailureReason(
 			NPM_INSTALL,
-			execError({
-				command: NPM_INSTALL,
-				messageTail:
-					"npm error 404 Not Found - GET https://npm.example.test/x - Not found",
-			}),
+			execError({ command: NPM_INSTALL }),
 			TIMEOUT_MS,
 		);
-		expect(reason).not.toContain("Command failed");
-		expect(reason.trim().length).toBeGreaterThan(0);
-	});
-
-	test("C1: something that is not an Error still yields a non-empty reason", () => {
-		const reason = commandFailureReason(NPM_INSTALL, "boom", TIMEOUT_MS);
-		expect(typeof reason).toBe("string");
-		expect(reason.trim().length).toBeGreaterThan(0);
-		expect(reason).not.toContain("Command failed");
+		expect(reason).toBe("npm exited with code 1");
 	});
 });
 
@@ -664,7 +652,7 @@ describe("C5 stepFailureReport", () => {
 		const report = stepFailureReport(
 			"Plugins were not refreshed",
 			"magus",
-			enoent({ cmd: "claude", args: ["plugin", "marketplace", "update"] }),
+			enoentError({ cmd: "claude", args: ["plugin", "marketplace", "update"] }),
 			"Run it yourself: claude plugin marketplace update magus",
 		);
 		const fixes = fixesOf(report);
@@ -791,7 +779,7 @@ describe("C6 no internal word in any headline or reason", () => {
 			stepFailureReport(
 				"Plugins were not refreshed",
 				"magus",
-				enoent(ABS_CLAUDE),
+				enoentError(ABS_CLAUDE),
 			),
 		],
 	];

package/src/__tests__/blind-780-review2.test.ts

@@ -58,7 +58,6 @@ import {
 } from "../ui/adapters/pluginsAdapter.js";
 import {
 	activationFailureReport,
-	marketplaceRefreshReport,
 	profileProblemRow,
 	profileProblemsReport,
 	staleRepairReport,
@@ -449,30 +448,6 @@ describe("U4 failed stale-load repairs", () => {
 	});
 });
 
-// ---------------------------------------------------------------------------
-// U5
-// ---------------------------------------------------------------------------
-
-describe("U5 a failed marketplace refresh", () => {
-	test("U5 the row's subject is the marketplace name", () => {
-		const r = marketplaceRefreshReport([
-			{
-				marketplace: "magus-marketing",
-				error: new Error("fatal: unable to access remote"),
-			},
-		]);
-		expect(r).not.toBeNull();
-		const report = r as FailureReport;
-		expect(report.rows).toHaveLength(1);
-		expect((report.rows[0] as FailureRow).subject).toBe("magus-marketing");
-	});
-
-	test("U5 nothing failed → no report", () => {
-		const r = marketplaceRefreshReport([]);
-		expect(r === null || r.rows.length === 0).toBe(true);
-	});
-});
-
 // ---------------------------------------------------------------------------
 // U6
 // ---------------------------------------------------------------------------