magus-cli 0.0.0-placeholder → 7.0.0

package/src/__tests__/plugin-manager-fallback.test.ts

@@ -0,0 +1,320 @@
+import {
+	afterAll,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+} from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resetGitHubBudget } from "../services/github-budget";
+import type {
+	LocalMarketplace,
+	LocalMarketplacePlugin,
+} from "../services/local-marketplace";
+import {
+	clearMarketplaceCache,
+	fetchMarketplacePlugins,
+	getMarketplaceFetchFailures,
+	resolveMarketplacePlugins,
+} from "../services/marketplace-fetcher";
+
+/**
+ * Point the marketplace-clone lookup at an EMPTY temp directory.
+ *
+ * `resolveMarketplacePlugins` now consults a git remote ref before falling back
+ * to the checked-out clone. Without this, these tests found the operator's real
+ * `magus` clone, performed a live `git fetch`, and asserted against whatever
+ * happened to be published — 17 real plugins instead of the 2 in the fixture, and
+ * three seconds per test.
+ */
+let prevConfigDir: string | undefined;
+let emptyConfigDir: string;
+
+beforeAll(() => {
+	emptyConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "mp-fallback-"));
+	prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
+	process.env.CLAUDE_CONFIG_DIR = emptyConfigDir;
+});
+
+afterAll(() => {
+	// biome-ignore lint/performance/noDelete: assigning undefined to process.env stores the string "undefined"; only delete unsets the variable
+	if (prevConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+	else process.env.CLAUDE_CONFIG_DIR = prevConfigDir;
+	fs.rmSync(emptyConfigDir, { recursive: true, force: true });
+});
+
+/**
+ * Regression coverage for the "deprecated everything" bug.
+ *
+ * When `fetchMarketplacePlugins` returns an empty list (network down,
+ * repo moved, GitHub blocked, etc.), the orphan-detection loop in
+ * `getAvailablePlugins` would flag every installed plugin as
+ * `isOrphaned: true` and the UI rendered them all as "deprecated".
+ *
+ * `resolveMarketplacePlugins` adds the local-marketplace cache as a
+ * fallback so installed plugins keep rendering with their real metadata
+ * even when the machine is offline.
+ */
+
+function buildLocalMarketplace(
+	name: string,
+	plugins: LocalMarketplacePlugin[],
+): LocalMarketplace {
+	return { name, description: "", plugins };
+}
+
+describe("resolveMarketplacePlugins — offline fallback", () => {
+	beforeEach(() => {
+		// Session-level cache could otherwise carry over a previous test's
+		// successful fetch and short-circuit the fallback path.
+		clearMarketplaceCache();
+		// The per-host cooldown is deliberately NOT cleared by clearMarketplaceCache
+		// — it reflects GitHub's state, not ours — so a 429 in one test would
+		// otherwise gate every fetch in the next for the full backoff.
+		resetGitHubBudget();
+	});
+
+	it("falls back to the local cache when the remote fetch returns empty", async () => {
+		const local = new Map<string, LocalMarketplace>([
+			[
+				"magus",
+				buildLocalMarketplace("magus", [
+					{
+						name: "code-search",
+						version: "5.3.0",
+						description: "Codebase investigation tools",
+						category: "development",
+						author: { name: "Jack Rudenko" },
+					},
+					{
+						name: "dev",
+						version: "2.7.0",
+						description: "Dev workflow",
+					},
+				]),
+			],
+		]);
+
+		// An invalid repo string short-circuits `fetchMarketplacePlugins` to
+		// `[]` without any network call, simulating the offline case.
+		const resolved = await resolveMarketplacePlugins(
+			"magus",
+			"not a valid repo string",
+			local,
+		);
+
+		expect(resolved.plugins).toHaveLength(2);
+		expect(resolved.plugins.map((p) => p.name).sort()).toEqual([
+			"code-search",
+			"dev",
+		]);
+		const codeAnalysis = resolved.plugins.find((p) => p.name === "code-search");
+		expect(codeAnalysis?.version).toBe("5.3.0");
+		expect(codeAnalysis?.description).toBe("Codebase investigation tools");
+		expect(codeAnalysis?.category).toBe("development");
+		expect(codeAnalysis?.author?.name).toBe("Jack Rudenko");
+	});
+
+	it("labels the fallback answer as local-clone, not remote", async () => {
+		// The regression this guards: the fallback plugins were returned in the
+		// same shape as a successful remote fetch, so the caller compared installed
+		// versions against a clone nothing refreshes and reported "up to date".
+		// The source must travel with the data.
+		const local = new Map<string, LocalMarketplace>([
+			[
+				"magus",
+				buildLocalMarketplace("magus", [
+					{ name: "terminal", version: "4.1.4", description: "" },
+				]),
+			],
+		]);
+		const resolved = await resolveMarketplacePlugins(
+			"magus",
+			"not a valid repo string",
+			local,
+		);
+
+		expect(resolved.source).toBe("local-clone");
+		expect(resolved.failure).toBeDefined();
+		expect(resolved.failure?.kind).toBe("invalid-repo");
+		expect(resolved.failure?.marketplace).toBe("magus");
+	});
+
+	it("returns empty when both remote and cache are empty", async () => {
+		const local = new Map<string, LocalMarketplace>();
+		const resolved = await resolveMarketplacePlugins(
+			"magus",
+			"not a valid repo string",
+			local,
+		);
+		expect(resolved.plugins).toEqual([]);
+		expect(resolved.source).toBe("none");
+		expect(resolved.failure).toBeDefined();
+	});
+
+	it("returns empty when remote fails AND cache exists but has no plugins", async () => {
+		const local = new Map<string, LocalMarketplace>([
+			["magus", buildLocalMarketplace("magus", [])],
+		]);
+		const resolved = await resolveMarketplacePlugins(
+			"magus",
+			"not a valid repo string",
+			local,
+		);
+		expect(resolved.plugins).toEqual([]);
+		expect(resolved.source).toBe("none");
+	});
+
+	it("does not consult the cache when the remote returns plugins", async () => {
+		// We can't easily exercise the success branch without a live network,
+		// but we can verify that a cache entry for a DIFFERENT marketplace
+		// doesn't bleed into the requested one.
+		const local = new Map<string, LocalMarketplace>([
+			[
+				"other-marketplace",
+				buildLocalMarketplace("other-marketplace", [
+					{ name: "should-not-leak", version: "0.0.1", description: "" },
+				]),
+			],
+		]);
+		const resolved = await resolveMarketplacePlugins(
+			"magus",
+			"not a valid repo string",
+			local,
+		);
+		expect(resolved.plugins).toEqual([]);
+		expect(resolved.source).toBe("none");
+	});
+});
+
+/**
+ * The defect class these cover: a failed check that renders as a passed one.
+ *
+ * `fetchMarketplacePlugins` used to return `[]` for a rate limit, a timeout, a
+ * bad repo string and a genuinely empty marketplace alike. Every caller then had
+ * to guess, and all of them guessed "fine".
+ */
+describe("fetchMarketplacePlugins — failures are values", () => {
+	beforeEach(() => {
+		clearMarketplaceCache();
+		resetGitHubBudget();
+	});
+
+	it("classifies a rate limit distinctly from a network problem", async () => {
+		const original = globalThis.fetch;
+		globalThis.fetch = (async () =>
+			new Response("rate limited", {
+				status: 429,
+				statusText: "Too Many Requests",
+			})) as typeof globalThis.fetch;
+		try {
+			const result = await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+			expect(result.plugins).toEqual([]);
+			expect(result.failure?.kind).toBe("rate-limited");
+			expect(result.failure?.httpStatus).toBe(429);
+			expect(result.failure?.detail).toContain("rate limit");
+		} finally {
+			globalThis.fetch = original;
+		}
+	});
+
+	it("records the failure so the UI can report it without re-fetching", async () => {
+		const original = globalThis.fetch;
+		let calls = 0;
+		globalThis.fetch = (async () => {
+			calls++;
+			return new Response("nope", { status: 500, statusText: "Server Error" });
+		}) as typeof globalThis.fetch;
+		try {
+			await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+
+			const failures = getMarketplaceFetchFailures();
+			expect(failures.map((f) => f.marketplace)).toContain("magus");
+			expect(failures.find((f) => f.marketplace === "magus")?.kind).toBe(
+				"http",
+			);
+
+			// Second call must be served from the negative cache. Re-attempting on
+			// every screen mount is what cost 30-45s of "Loading..." per tab switch.
+			await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+			expect(calls).toBe(1);
+		} finally {
+			globalThis.fetch = original;
+		}
+	});
+
+	it("reports no failures when the fetch succeeds", async () => {
+		const original = globalThis.fetch;
+		globalThis.fetch = (async () =>
+			Response.json({
+				metadata: { version: "9.0.3" },
+				plugins: [{ name: "terminal", version: "4.1.6" }],
+			})) as typeof globalThis.fetch;
+		try {
+			const result = await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+			expect(result.failure).toBeUndefined();
+			expect(result.plugins).toHaveLength(1);
+			expect(getMarketplaceFetchFailures()).toEqual([]);
+		} finally {
+			globalThis.fetch = original;
+		}
+	});
+
+	it("does not send a request while the rate-limit window is still open", async () => {
+		// Deliberate: an explicit refresh clears OUR caches but not GitHub's limit.
+		// Retrying inside a known window cannot succeed, and on some endpoints a
+		// rejected request extends the penalty — so the screen waits and counts down
+		// instead. `clearMarketplaceCache()` must not be a way around that.
+		const original = globalThis.fetch;
+		let calls = 0;
+		globalThis.fetch = (async () => {
+			calls++;
+			return new Response("nope", { status: 429 });
+		}) as typeof globalThis.fetch;
+		try {
+			await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+			expect(calls).toBe(1);
+
+			clearMarketplaceCache();
+			const second = await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+
+			expect(calls).toBe(1); // no second request went out
+			expect(second.failure?.kind).toBe("rate-limited");
+			expect(second.failure?.retryAt).toBeGreaterThan(Date.now());
+		} finally {
+			globalThis.fetch = original;
+		}
+	});
+
+	it("clears the recorded failure once the window passes and the fetch succeeds", async () => {
+		const original = globalThis.fetch;
+		globalThis.fetch = (async () =>
+			new Response("nope", { status: 429 })) as typeof globalThis.fetch;
+		try {
+			await fetchMarketplacePlugins("magus", "MadAppGang/magus");
+			expect(getMarketplaceFetchFailures()).toHaveLength(1);
+
+			// The cooldown expiring is what unblocks the retry — this stands in for the
+			// clock reaching `retryAt`, which is when the screen refetches by itself.
+			resetGitHubBudget();
+			clearMarketplaceCache();
+			globalThis.fetch = (async () =>
+				Response.json({
+					plugins: [{ name: "terminal", version: "4.2.0" }],
+				})) as typeof globalThis.fetch;
+
+			const recovered = await fetchMarketplacePlugins(
+				"magus",
+				"MadAppGang/magus",
+			);
+			expect(recovered.failure).toBeUndefined();
+			expect(recovered.plugins).toHaveLength(1);
+			expect(getMarketplaceFetchFailures()).toEqual([]);
+		} finally {
+			globalThis.fetch = original;
+		}
+	});
+});

package/src/__tests__/plugin-releases.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import {
+	MAX_RELEASES,
+	normalizeReleases,
+} from "../services/plugin-releases.js";
+import type { PluginRelease } from "../types/index.js";
+
+/** Narrow to a populated result, failing the test rather than the assertion's type. */
+function expectEntries(input: unknown): PluginRelease[] {
+	const out = normalizeReleases(input);
+	if (!out) throw new Error("expected releases, got undefined");
+	return out;
+}
+
+describe("normalizeReleases", () => {
+	test("passes through a well-formed entry", () => {
+		expect(
+			normalizeReleases([
+				{
+					version: "3.3.0",
+					date: "2026-07-29",
+					kinds: ["Changed", "Fixed"],
+					summary: "Model resolution is now live",
+				},
+			]),
+		).toEqual([
+			{
+				version: "3.3.0",
+				date: "2026-07-29",
+				kinds: ["Changed", "Fixed"],
+				summary: "Model resolution is now live",
+			},
+		]);
+	});
+
+	test("omits optional fields rather than emitting undefined", () => {
+		const [entry] = expectEntries([
+			{ version: "1.0.0", summary: "First release" },
+		]);
+		expect(entry).toEqual({ version: "1.0.0", summary: "First release" });
+		expect("date" in entry).toBe(false);
+		expect("kinds" in entry).toBe(false);
+	});
+
+	test("returns undefined for anything that is not an array", () => {
+		for (const input of [undefined, null, "3.3.0", 7, {}, true]) {
+			expect(normalizeReleases(input)).toBeUndefined();
+		}
+	});
+
+	// The manifest is fetched over the network, so no field's type can be assumed.
+	test("drops entries missing or mistyping the required fields", () => {
+		expect(
+			normalizeReleases([
+				{ version: "1.0.0", summary: "kept" },
+				{ version: "1.0.1" }, // no summary
+				{ summary: "no version" },
+				{ version: 2, summary: "version is a number" },
+				{ version: "1.0.2", summary: 42 },
+				{ version: "  ", summary: "blank version" },
+				{ version: "1.0.3", summary: "   " },
+				null,
+				"not an object",
+			]),
+		).toEqual([{ version: "1.0.0", summary: "kept" }]);
+	});
+
+	test("returns undefined when every entry is unusable", () => {
+		expect(normalizeReleases([{ nope: true }, null])).toBeUndefined();
+		expect(normalizeReleases([])).toBeUndefined();
+	});
+
+	test("caps the list so one manifest cannot flood the panel", () => {
+		const many = Array.from({ length: 500 }, (_, i) => ({
+			version: `1.0.${i}`,
+			summary: `entry ${i}`,
+		}));
+		const out = expectEntries(many);
+		expect(out).toHaveLength(MAX_RELEASES);
+		// Newest-first ordering is preserved — the cap takes the head, not the tail.
+		expect(out[0].version).toBe("1.0.0");
+	});
+
+	test("keeps only string members of kinds", () => {
+		const [entry] = expectEntries([
+			{ version: "1.0.0", summary: "x", kinds: ["Added", 3, null, "Fixed"] },
+		]);
+		expect(entry.kinds).toEqual(["Added", "Fixed"]);
+	});
+
+	test("trims surrounding whitespace", () => {
+		expect(
+			normalizeReleases([
+				{ version: " 1.0.0 ", date: " 2026-07-29 ", summary: "  padded  " },
+			]),
+		).toEqual([{ version: "1.0.0", date: "2026-07-29", summary: "padded" }]);
+	});
+});

package/src/__tests__/plugin-requires.test.ts

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import {
+	parsePluginRequires,
+	readPluginRequires,
+} from "../services/plugin-requires.js";
+
+describe("parsePluginRequires", () => {
+	test("parses a valid requires.bin and fills defaults", () => {
+		const requires = parsePluginRequires({
+			name: "terminal",
+			requires: {
+				bin: [
+					{ name: "tmux", via: "brew", formula: "tmux", check: "tmux -V" },
+					{ name: "tmux-mcp", via: "bun", package: "tmux-mcp" },
+				],
+			},
+		});
+		expect(requires.bin).toHaveLength(2);
+		const tmux = requires.bin!.find((b) => b.name === "tmux")!;
+		expect(tmux.via).toBe("brew");
+		expect(tmux.check).toBe("tmux -V");
+		const mcp = requires.bin!.find((b) => b.name === "tmux-mcp")!;
+		// check defaulted from the name
+		expect(mcp.check).toBe("tmux-mcp --version");
+	});
+
+	test("drops entries with no name or an unknown installer", () => {
+		const requires = parsePluginRequires({
+			requires: {
+				bin: [
+					{ via: "bun" }, // no name
+					{ name: "x", via: "cargo" }, // unknown installer
+					{ name: "ok", via: "npm" },
+				],
+			},
+		});
+		expect(requires.bin).toHaveLength(1);
+		expect(requires.bin![0]!.name).toBe("ok");
+	});
+
+	test("no requires / non-array bin → empty object", () => {
+		expect(parsePluginRequires({ name: "x" })).toEqual({});
+		expect(parsePluginRequires({ requires: {} })).toEqual({});
+		expect(parsePluginRequires({ requires: { bin: "nope" } })).toEqual({});
+		expect(parsePluginRequires(null)).toEqual({});
+	});
+});
+
+describe("parsePluginRequires — setup block (the established convention)", () => {
+	test("terminal's setup: go module + required system tool", () => {
+		// The real plugins/terminal/plugin.json shape.
+		const r = parsePluginRequires({
+			name: "terminal",
+			setup: {
+				go: ["github.com/MadAppGang/tmux-mcp@latest"],
+				required: ["tmux"],
+			},
+		});
+		const mcp = r.bin!.find((b) => b.name === "tmux-mcp")!;
+		expect(mcp.via).toBe("go");
+		expect(mcp.module).toBe("github.com/MadAppGang/tmux-mcp");
+		expect(mcp.version).toBe("latest");
+		const tmux = r.bin!.find((b) => b.name === "tmux")!;
+		expect(tmux.via).toBe("brew");
+		expect(tmux.formula).toBe("tmux");
+	});
+
+	// Negative control for the /vN fix: basename(base) yields "v2" here, so
+	// without the go-module helper this test FAILS on `name`.
+	test("terminal's v2 pin: /v2 is the module's major version, not the binary", () => {
+		const r = parsePluginRequires({
+			name: "terminal",
+			setup: { go: ["github.com/MadAppGang/tmux-mcp/v2@v2.0.0"] },
+		});
+		expect(r.bin).toEqual([
+			{
+				name: "tmux-mcp",
+				via: "go",
+				module: "github.com/MadAppGang/tmux-mcp/v2",
+				version: "v2.0.0",
+				check: "tmux-mcp --version",
+			},
+		]);
+	});
+
+	// One manifest per spec: entries are keyed by binary name, so a v1 and a v2
+	// pin of the same module in ONE setup would (correctly) collapse to one.
+	test.each([
+		[
+			"github.com/MadAppGang/tmux-mcp@v1.7.1",
+			{
+				name: "tmux-mcp",
+				module: "github.com/MadAppGang/tmux-mcp",
+				version: "v1.7.1",
+			},
+		],
+		[
+			"github.com/MadAppGang/tmux-mcp/v2",
+			{
+				name: "tmux-mcp",
+				module: "github.com/MadAppGang/tmux-mcp/v2",
+				version: undefined,
+			},
+		],
+		[
+			"github.com/x/v2tool@v1.0.0",
+			{ name: "v2tool", module: "github.com/x/v2tool", version: "v1.0.0" },
+		],
+	])("go spec %s → name/module/version", (spec, expected) => {
+		const r = parsePluginRequires({ setup: { go: [spec] } });
+		expect(
+			r.bin!.map((b) => ({
+				name: b.name,
+				module: b.module,
+				version: b.version,
+			})),
+		).toEqual([expected]);
+	});
+
+	test("browser-use's setup: pip packages", () => {
+		const r = parsePluginRequires({
+			name: "browser-use",
+			setup: { pip: ["browser-use", "mcp"] },
+		});
+		expect(r.bin!.map((b) => b.name).sort()).toEqual(["browser-use", "mcp"]);
+		expect(r.bin!.every((b) => b.via === "pip")).toBe(true);
+	});
+
+	test("bun/npm specs split name@version", () => {
+		const r = parsePluginRequires({
+			setup: { bun: ["claudish@1.2.0"], npm: ["@scope/tool@3.0.0"] },
+		});
+		const claudish = r.bin!.find((b) => b.name === "claudish")!;
+		expect(claudish.version).toBe("1.2.0");
+		const scoped = r.bin!.find((b) => b.name === "tool")!;
+		expect(scoped.package).toBe("@scope/tool");
+		expect(scoped.version).toBe("3.0.0");
+	});
+
+	test("explicit requires.bin overrides a setup entry of the same name", () => {
+		const r = parsePluginRequires({
+			setup: { required: ["tmux"] }, // → brew
+			requires: {
+				bin: [{ name: "tmux", via: "go", module: "example.com/tmux" }],
+			},
+		});
+		const tmux = r.bin!.find((b) => b.name === "tmux")!;
+		expect(tmux.via).toBe("go"); // requires.bin won
+	});
+});
+
+describe("readPluginRequires", () => {
+	let dir: string;
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), "plugreq-"));
+	});
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	test("reads plugin.json at the plugin root", async () => {
+		await fs.writeJson(join(dir, "plugin.json"), {
+			name: "p",
+			requires: { bin: [{ name: "tmux", via: "brew" }] },
+		});
+		const r = await readPluginRequires(dir);
+		expect(r.bin?.[0]?.name).toBe("tmux");
+	});
+
+	test("falls back to .claude-plugin/plugin.json", async () => {
+		await fs.ensureDir(join(dir, ".claude-plugin"));
+		await fs.writeJson(join(dir, ".claude-plugin", "plugin.json"), {
+			name: "p",
+			requires: { bin: [{ name: "mnemex", via: "bun" }] },
+		});
+		const r = await readPluginRequires(dir);
+		expect(r.bin?.[0]?.name).toBe("mnemex");
+	});
+
+	test("missing manifest → empty", async () => {
+		expect(await readPluginRequires(dir)).toEqual({});
+	});
+});