magus-cli 7.10.5 → 7.11.1

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

@@ -0,0 +1,359 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+	type Requirement,
+	probe,
+} from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import {
+	DEPTHS,
+	type World,
+	fakeTool,
+	makeWorld,
+	pluginDir,
+	probeEnv,
+	removeWorld,
+	writeExecutable,
+} from "./support";
+
+function req(
+	name: string,
+	minVersion?: string,
+	check: string[] = [name, "--version"],
+): Requirement {
+	const r: Record<string, unknown> = {
+		check,
+		install: [{ formula: name, via: "brew" }],
+		name,
+	};
+	if (minVersion !== undefined) r.minVersion = minVersion;
+	return r as unknown as Requirement;
+}
+
+async function withWorld(body: (world: World) => Promise<void>): Promise<void> {
+	const world = await makeWorld();
+	try {
+		await pluginDir(world);
+		await body(world);
+	} finally {
+		await removeWorld(world);
+	}
+}
+
+for (const depth of DEPTHS) {
+	describe(`probe with minVersion at depth "${depth}"`, () => {
+		// REQ-8: exit 0, found >= minVersion → present
+		test("REQ-8 version equal to the floor is present", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "tool 10.7.0" });
+				expect(
+					await probe([req("tool", "10.7.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "present" }]);
+			});
+		});
+
+		test("REQ-8 version above the floor is present", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "tool version 10.8.2" });
+				expect(
+					await probe([req("tool", "10.7.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "present" }]);
+			});
+		});
+
+		// REQ-9: exit 0, found < minVersion → outdated with found and minVersion.
+		// At presence depth this also proves the check runs (REQ-12): a PATH
+		// lookup alone cannot produce "outdated".
+		test("REQ-9 version below the floor is outdated with found and floor", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "tool 10.6.3" });
+				expect(
+					await probe([req("tool", "10.7.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "10.6.3",
+						minVersion: "10.7.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		// REQ-10: exit 0, no version in output → unknown with the stated reason.
+		test("REQ-10 no version in output is unknown with the argv in the reason", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", {
+					stderr: "nothing on stderr either",
+					stdout: "tool, unversioned build",
+				});
+				expect(
+					await probe([req("tool", "1.0.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						name: "tool",
+						reason: 'no version in "tool --version" output',
+						status: "unknown",
+					},
+				]);
+			});
+		});
+
+		// REQ-11: read stderr when stdout has no version.
+		test("REQ-11 a version only on stderr is read (outdated)", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stderr: "tool 2.0.1" });
+				expect(
+					await probe([req("tool", "3.0.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "2.0.1",
+						minVersion: "3.0.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		test("REQ-11 a version only on stderr is read (present)", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", {
+					stderr: "tool 3.1.0",
+					stdout: "no digits here",
+				});
+				expect(
+					await probe([req("tool", "3.0.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "present" }]);
+			});
+		});
+
+		test("REQ-11 stdout wins over stderr when stdout has a version", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stderr: "9.9.9", stdout: "1.0.0" });
+				expect(
+					await probe([req("tool", "2.0.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "1.0.0",
+						minVersion: "2.0.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		test("REQ-11 the first X.Y.Z match in stdout is the found version", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", {
+					stdout: "tool 1.2.3 (built with runtime 20.11.0)",
+				});
+				expect(
+					await probe([req("tool", "2.0.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "1.2.3",
+						minVersion: "2.0.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		// REQ-13: a suffix after the match is ignored.
+		test("REQ-13 10.7.0-beta.1 satisfies a 10.7.0 floor", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "10.7.0-beta.1" });
+				expect(
+					await probe([req("tool", "10.7.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "present" }]);
+			});
+		});
+
+		// REQ-14: comparison is numeric, part by part.
+		test("REQ-14 10.10.0 satisfies a 10.9.0 floor (numeric, not lexical)", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "10.10.0" });
+				expect(
+					await probe([req("tool", "10.9.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "present" }]);
+			});
+		});
+
+		test("REQ-14 10.9.0 is outdated against a 10.10.0 floor", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "10.9.0" });
+				expect(
+					await probe([req("tool", "10.10.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "10.9.0",
+						minVersion: "10.10.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		test("REQ-14 9.99.99 is outdated against a 10.0.0 floor", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { stdout: "9.99.99" });
+				expect(
+					await probe([req("tool", "10.0.0")], probeEnv(world, { depth })),
+				).toEqual([
+					{
+						found: "9.99.99",
+						minVersion: "10.0.0",
+						name: "tool",
+						status: "outdated",
+					},
+				]);
+			});
+		});
+
+		// REQ-15: non-zero exit → as schema 1, missing.
+		test("REQ-15 a non-zero exit is missing even when a high version prints", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "tool", { code: 1, stdout: "tool 99.0.0" });
+				expect(
+					await probe([req("tool", "1.0.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "missing" }]);
+			});
+		});
+
+		test("REQ-15 a tool absent from PATH is missing", async () => {
+			await withWorld(async (world) => {
+				expect(
+					await probe([req("tool", "1.0.0")], probeEnv(world, { depth })),
+				).toEqual([{ name: "tool", status: "missing" }]);
+			});
+		});
+
+		// REQ-16: timeout → as schema 1, unknown (slow).
+		test("REQ-16 a slow check under a floor is unknown (slow)", async () => {
+			await withWorld(async (world) => {
+				await writeExecutable(
+					join(world.bin, "tool"),
+					"/bin/sleep 3\necho 10.0.0",
+				);
+				const result = await probe(
+					[req("tool", "1.0.0")],
+					probeEnv(world, { capMs: 200, depth }),
+				);
+				expect(result).toEqual([
+					{
+						name: "tool",
+						reason: expect.stringMatching(/^slow: no answer within [0-9.]+s$/),
+						status: "unknown",
+					},
+				]);
+			});
+		});
+
+		// REQ-17: blockedBy ordering unchanged — a dependent of an outdated
+		// requirement is probed, since the tool exists and runs.
+		test("REQ-17 a dependent of an outdated requirement is probed, not blocked", async () => {
+			await withWorld(async (world) => {
+				await writeExecutable(
+					join(world.bin, "base"),
+					'if [ "$1" = "--version" ]; then echo "base 0.5.0"; exit 0; fi\nexit 0',
+				);
+				const result = await probe(
+					[
+						req("base", "1.0.0"),
+						req("child", undefined, ["base", "run", "child"]),
+					],
+					probeEnv(world, { depth }),
+				);
+				expect(result).toEqual([
+					{
+						found: "0.5.0",
+						minVersion: "1.0.0",
+						name: "base",
+						status: "outdated",
+					},
+					{ name: "child", status: "present" },
+				]);
+			});
+		});
+
+		// REQ-18: mixed list keeps requirement order.
+		test("REQ-18 results keep requirement order across floored and unfloored", async () => {
+			await withWorld(async (world) => {
+				await fakeTool(world, "old", { stdout: "1.0.0" });
+				await fakeTool(world, "new", { stdout: "5.0.0" });
+				await fakeTool(world, "plain", { stdout: "0.0.1" });
+				expect(
+					await probe(
+						[req("old", "2.0.0"), req("plain"), req("new", "5.0.0")],
+						probeEnv(world, { depth }),
+					),
+				).toEqual([
+					{
+						found: "1.0.0",
+						minVersion: "2.0.0",
+						name: "old",
+						status: "outdated",
+					},
+					{ name: "plain", status: "present" },
+					{ name: "new", status: "present" },
+				]);
+			});
+		});
+	});
+}
+
+describe("probe without minVersion keeps schema-1 depth behaviour", () => {
+	// REQ-12: "A requirement without it behaves as in schema 1" — presence depth
+	// decides a self-named check by PATH lookup alone.
+	test("REQ-12 presence depth: a fake that exits 1 still reads present and is not run", async () => {
+		await withWorld(async (world) => {
+			const marker = join(world.root, "plugin", "check-ran");
+			await writeExecutable(
+				join(world.bin, "tool"),
+				`: > "${marker}"\necho 1.0.0\nexit 1`,
+			);
+			expect(
+				await probe([req("tool")], probeEnv(world, { depth: "presence" })),
+			).toEqual([{ name: "tool", status: "present" }]);
+			expect(existsSync(marker)).toBe(false);
+		});
+	});
+
+	test("REQ-12 presence depth WITH a floor runs the check (same fake → missing)", async () => {
+		await withWorld(async (world) => {
+			const marker = join(world.root, "plugin", "check-ran");
+			await writeExecutable(
+				join(world.bin, "tool"),
+				`: > "${marker}"\necho 1.0.0\nexit 1`,
+			);
+			expect(
+				await probe(
+					[req("tool", "1.0.0")],
+					probeEnv(world, { depth: "presence" }),
+				),
+			).toEqual([{ name: "tool", status: "missing" }]);
+			expect(existsSync(marker)).toBe(true);
+		});
+	});
+
+	test("REQ-12 full depth without a floor: exit 1 is missing, unversioned exit 0 is present", async () => {
+		await withWorld(async (world) => {
+			await fakeTool(world, "bad", { code: 1, stdout: "1.0.0" });
+			await fakeTool(world, "quiet", { stdout: "no version at all" });
+			expect(
+				await probe(
+					[req("bad"), req("quiet")],
+					probeEnv(world, { depth: "full" }),
+				),
+			).toEqual([
+				{ name: "bad", status: "missing" },
+				{ name: "quiet", status: "present" },
+			]);
+		});
+	});
+});

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

@@ -0,0 +1,252 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+import {
+	type InstallOption,
+	type Presence,
+	type Requirement,
+	describeStep,
+	renderFix,
+	renderInstall,
+} from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import {
+	DIGEST,
+	makeWorld,
+	probeEnv,
+	removeWorld,
+	writeExecutable,
+} from "./support";
+
+type Reason = "missing" | "outdated";
+// The schema-2 renderInstall takes the reason as a fourth argument (spec:
+// "renderInstall takes the reason ("missing" | "outdated")").
+const render = renderInstall as unknown as (
+	r: Requirement,
+	o: InstallOption,
+	e: { os: "darwin" | "linux"; arch: "amd64" | "arm64"; pluginRoot: string },
+	reason: Reason,
+) => ReturnType<typeof renderInstall>;
+
+const e = {
+	arch: "arm64" as const,
+	os: "darwin" as const,
+	pluginRoot: "/tmp/plugin",
+};
+
+function req(
+	name: string,
+	minVersion?: string,
+	install: InstallOption[] = [],
+): Requirement {
+	const r: Record<string, unknown> = {
+		check: [name, "--version"],
+		install,
+		name,
+	};
+	if (minVersion !== undefined) r.minVersion = minVersion;
+	return r as unknown as Requirement;
+}
+
+function argvStep(name: string, argv: string[]) {
+	return { argv, escalation: "none", kind: "argv", name };
+}
+
+describe("renderInstall with a reason", () => {
+	const cases: Array<[string, InstallOption, Reason, string[]]> = [
+		// REQ-19: bun
+		[
+			"bun unpinned, missing",
+			{ package: "pkg", via: "bun" },
+			"missing",
+			["bun", "add", "-g", "pkg"],
+		],
+		[
+			"bun pinned, missing",
+			{ package: "pkg", version: "2.1.0", via: "bun" },
+			"missing",
+			["bun", "add", "-g", "pkg@2.1.0"],
+		],
+		[
+			"bun unpinned, outdated",
+			{ package: "pkg", via: "bun" },
+			"outdated",
+			["bun", "add", "-g", "pkg@latest"],
+		],
+		[
+			"bun pinned, outdated",
+			{ package: "pkg", version: "2.1.0", via: "bun" },
+			"outdated",
+			["bun", "add", "-g", "pkg@2.1.0"],
+		],
+		[
+			"bun scoped unpinned, outdated",
+			{ package: "@scope/pkg", via: "bun" },
+			"outdated",
+			["bun", "add", "-g", "@scope/pkg@latest"],
+		],
+		// REQ-20: brew formula
+		[
+			"brew formula, missing",
+			{ formula: "owner/tap/tool", via: "brew" },
+			"missing",
+			["brew", "install", "owner/tap/tool"],
+		],
+		[
+			"brew formula, outdated",
+			{ formula: "owner/tap/tool", via: "brew" },
+			"outdated",
+			["brew", "upgrade", "owner/tap/tool"],
+		],
+		// REQ-21: brew cask
+		[
+			"brew cask, missing",
+			{ cask: "visual", via: "brew" },
+			"missing",
+			["brew", "install", "--cask", "visual"],
+		],
+		[
+			"brew cask, outdated",
+			{ cask: "visual", via: "brew" },
+			"outdated",
+			["brew", "upgrade", "--cask", "visual"],
+		],
+	];
+	for (const [label, option, reason, argv] of cases) {
+		test(`REQ-19..21 ${label} → ${argv.join(" ")}`, () => {
+			expect(render(req("tool"), option, e, reason)).toEqual(
+				argvStep("tool", argv),
+			);
+		});
+	}
+
+	// REQ-22: every other via is unchanged between reasons.
+	const others: Array<[string, InstallOption]> = [
+		["apt", { packages: ["one"], via: "apt" }],
+		[
+			"release",
+			{
+				asset: "tool-{os}-{arch}",
+				binary: "tool",
+				repo: "Owner/tool",
+				sha256: { darwin_arm64: DIGEST },
+				tag: "v2.0.0",
+				via: "release",
+			},
+		],
+		["bootstrap", { tool: "uv", via: "bootstrap" }],
+		["uv-script", { args: ["--x"], script: "s.py", via: "uv-script" }],
+		["npm", { package: "pkg", via: "npm" }],
+	];
+	for (const [label, option] of others) {
+		test(`REQ-22 ${label}: outdated renders the same step as missing`, () => {
+			const r = req("tool");
+			expect(render(r, option, e, "outdated")).toEqual(
+				render(r, option, e, "missing"),
+			);
+		});
+	}
+
+	test("REQ-19 describeStep of an outdated bun step is the pasteable upgrade line", () => {
+		const step = render(
+			req("tool"),
+			{ package: "claudish", via: "bun" },
+			e,
+			"outdated",
+		);
+		expect(describeStep(step, "darwin")).toBe("bun add -g claudish@latest");
+	});
+});
+
+describe("renderFix with outdated presences", () => {
+	// REQ-23: banner head names found and floor; outdated gets a by-hand line.
+	test("REQ-23 an outdated dep produces a banner naming found and floor", async () => {
+		const world = await makeWorld();
+		try {
+			await writeExecutable(join(world.bin, "bun"), "echo 1.4.0");
+			const claudish = req("claudish", "10.7.0", [
+				{ package: "claudish", via: "bun" },
+			]);
+			const presences = [
+				{
+					found: "10.6.2",
+					minVersion: "10.7.0",
+					name: "claudish",
+					status: "outdated",
+				},
+			] as unknown as Presence[];
+			const banner = renderFix(
+				"claudish",
+				presences,
+				[claudish],
+				probeEnv(world),
+				true,
+			);
+			expect(banner).not.toBeNull();
+			if (banner === null) throw new Error("outdated must render a banner");
+			expect(banner).toContain("outdated claudish 10.6.2 (needs 10.7.0)");
+			expect(banner).toContain("bun add -g claudish@latest");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	test("REQ-23 an outdated brew dep's by-hand line upgrades rather than installs", async () => {
+		const world = await makeWorld();
+		try {
+			await writeExecutable(join(world.bin, "brew"), "exit 0");
+			const tool = req("tool", "2.0.0", [
+				{ formula: "owner/tap/tool", via: "brew" },
+			]);
+			const presences = [
+				{
+					found: "1.9.9",
+					minVersion: "2.0.0",
+					name: "tool",
+					status: "outdated",
+				},
+			] as unknown as Presence[];
+			const banner = renderFix(
+				"p",
+				presences,
+				[tool],
+				probeEnv(world, { os: "darwin", arch: "arm64" }),
+				true,
+			);
+			expect(banner).toContain("outdated tool 1.9.9 (needs 2.0.0)");
+			expect(banner).toContain("brew upgrade owner/tap/tool");
+			expect(banner).not.toContain("brew install owner/tap/tool");
+		} finally {
+			await removeWorld(world);
+		}
+	});
+
+	// REQ-24: "A healthy machine still prints nothing."
+	test("REQ-24 a healthy set with a floor returns null", async () => {
+		const world = await makeWorld();
+		try {
+			const claudish = req("claudish", "10.7.0", [
+				{ package: "claudish", via: "bun" },
+			]);
+			expect(
+				renderFix(
+					"claudish",
+					[{ name: "claudish", status: "present" }],
+					[claudish],
+					probeEnv(world),
+					true,
+				),
+			).toBeNull();
+			expect(
+				renderFix(
+					"claudish",
+					[{ name: "claudish", status: "present" }],
+					[claudish],
+					probeEnv(world),
+					false,
+				),
+			).toBeNull();
+		} finally {
+			await removeWorld(world);
+		}
+	});
+});

package/src/__tests__/blind/requires-min-version/support.ts

@@ -0,0 +1,83 @@
+// Shared testdata builders for the requires schema-2 (minVersion) blind suite.
+// World/process helpers are reused from the schema-1 blind suite.
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { ProbeEnv } from "../../../shared/plugin/hooks/lib/requires-probe.js";
+import { type World, writeExecutable } from "../plugin-deps/helpers";
+
+export * from "../plugin-deps/helpers";
+
+export const DIGEST = "c".repeat(64);
+
+export type Raw = Record<string, unknown>;
+
+export function requirement(
+	name: string,
+	install: Raw[],
+	extra: Raw = {},
+	check: string[] = [name, "--version"],
+): Raw {
+	return { check, install, name, ...extra };
+}
+
+export function requires(bin: Raw[], schema: unknown = 2): Raw {
+	return { bin, schema };
+}
+
+export function manifest(bin: Raw[], schema: unknown = 2): Raw {
+	return { requires: requires(bin, schema) };
+}
+
+export function releaseOption(tag: string): Raw {
+	return {
+		asset: "tool-{os}-{arch}",
+		binary: "tool",
+		repo: "Owner/tool",
+		sha256: { linux_amd64: DIGEST },
+		tag,
+		via: "release",
+	};
+}
+
+export function probeEnv(
+	world: World,
+	patch: Partial<ProbeEnv> = {},
+): ProbeEnv {
+	return {
+		arch: "amd64",
+		capMs: 5_000,
+		depth: "full",
+		home: world.home,
+		os: "linux",
+		path: world.bin,
+		pluginRoot: join(world.root, "plugin"),
+		userShell: "/bin/zsh",
+		...patch,
+	};
+}
+
+export async function pluginDir(world: World): Promise<void> {
+	await mkdir(join(world.root, "plugin"), { recursive: true });
+}
+
+/**
+ * A fake executable that prints `stdout` (and optionally `stderr`) and exits
+ * with `code`. Never the real tool.
+ */
+export async function fakeTool(
+	world: World,
+	name: string,
+	opts: { stdout?: string; stderr?: string; code?: number } = {},
+): Promise<string> {
+	const lines: string[] = [];
+	if (opts.stdout !== undefined) lines.push(`printf '%s\\n' '${opts.stdout}'`);
+	if (opts.stderr !== undefined)
+		lines.push(`printf '%s\\n' '${opts.stderr}' >&2`);
+	lines.push(`exit ${opts.code ?? 0}`);
+	const path = join(world.bin, name);
+	await writeExecutable(path, lines.join("\n"));
+	return path;
+}
+
+export const DEPTHS = ["presence", "full"] as const;