magus-cli 0.0.0-placeholder → 7.1.0

package/src/__tests__/blackbox-plugin-state.test.ts

@@ -0,0 +1,545 @@
+/**
+ * BLACK-BOX: R1 — one plugin classifier, and the TUI text contract (§8.1, §8.7).
+ * Written from requirements.md and architecture §8 only.
+ */
+import { describe, expect, test } from "bun:test";
+import type { PluginInfo } from "../services/plugin-manager.js";
+import {
+	type PluginUpdateItem,
+	type UpdatePlan,
+	classifyPlugin,
+	classifyPluginRows,
+	countPluginStates,
+	indexCatalog,
+	pinForRow,
+	planHasWork,
+	planIsBehind,
+	planPluginUpdates,
+	scopeIsBehind,
+} from "../services/update-plan.js";
+import type { PluginPluginItem } from "../ui/adapters/pluginsAdapter.js";
+import { pluginRowText } from "../ui/renderers/pluginRowText.js";
+import { pluginStatusText } from "../ui/renderers/pluginStatusText.js";
+
+function info(
+	id: string,
+	catalogVersion: string | null,
+	installed: string | null,
+	extra: Partial<PluginInfo> = {},
+): PluginInfo {
+	const at = id.indexOf("@");
+	return {
+		id,
+		name: at >= 0 ? id.slice(0, at) : id,
+		version: catalogVersion,
+		description: "",
+		marketplace: at >= 0 ? id.slice(at + 1) : "",
+		marketplaceDisplay: at >= 0 ? id.slice(at + 1) : "",
+		enabled: installed !== null,
+		...(installed !== null
+			? {
+					installedVersion: installed,
+					projectScope: { enabled: true, version: installed },
+				}
+			: {}),
+		...extra,
+	};
+}
+
+function item(over: Partial<PluginUpdateItem>): PluginUpdateItem {
+	return {
+		pluginId: "x@magus",
+		pinned: "latest",
+		installed: "1.0.0",
+		available: "1.0.0",
+		target: null,
+		action: "current",
+		reason: "up-to-date",
+		scopes: [],
+		beforeVersions: {},
+		...over,
+	};
+}
+
+describe("indexCatalog", () => {
+	const idx = indexCatalog([
+		info("dev@magus", "1.0.0", "1.0.0"),
+		info("old@magus", null, "0.1.0", { isOrphaned: true }),
+		info("solo@lonely", null, "0.1.0", { isOrphaned: true }),
+	]);
+
+	test("isListed is true only for a catalog row that is not an orphan", () => {
+		expect(idx.isListed("dev@magus")).toBe(true);
+		expect(idx.isListed("old@magus")).toBe(false);
+		expect(idx.isListed("missing@magus")).toBe(false);
+	});
+
+	test("marketplaceIsKnown is true when another listed id shares the marketplace suffix", () => {
+		expect(idx.marketplaceIsKnown("missing@magus")).toBe(true);
+		expect(idx.marketplaceIsKnown("solo@lonely")).toBe(false);
+		expect(idx.marketplaceIsKnown("no-at-sign")).toBe(false);
+	});
+
+	test("accepts a Map as well as an array", () => {
+		const fromMap = indexCatalog(
+			new Map([["dev@magus", info("dev@magus", "1.0.0", null)]]),
+		);
+		expect(fromMap.get("dev@magus")?.version).toBe("1.0.0");
+		expect(fromMap.isListed("dev@magus")).toBe(true);
+	});
+});
+
+describe("classifyPlugin — one state plus a human reason", () => {
+	test("declared, absent from the catalog, marketplace read: unknown / not-offered, no target", () => {
+		const idx = indexCatalog([info("dev@magus", "1.0.0", "1.0.0")]);
+
+		const got = classifyPlugin("gone@magus", "latest", idx);
+
+		expect({
+			action: got.action,
+			reason: got.reason,
+			target: got.target,
+		}).toEqual({
+			action: "unknown",
+			reason: "not-offered",
+			target: null,
+		});
+		expect(got.note).toBeTruthy();
+	});
+
+	test("installed orphan whose marketplace contributes no listed id: unknown / marketplace-unread", () => {
+		const idx = indexCatalog([
+			info("dev@magus", "1.0.0", "1.0.0"),
+			info("ghost@unread-mp", null, "0.3.0", { isOrphaned: true }),
+		]);
+
+		const got = classifyPlugin("ghost@unread-mp", "latest", idx);
+
+		expect({ action: got.action, reason: got.reason }).toEqual({
+			action: "unknown",
+			reason: "marketplace-unread",
+		});
+	});
+
+	test("declared latest, installed nowhere: install / absent, aiming at the catalog version", () => {
+		const idx = indexCatalog([info("bunjs@magus", "0.4.4", null)]);
+
+		const got = classifyPlugin("bunjs@magus", "latest", idx);
+
+		expect({
+			action: got.action,
+			reason: got.reason,
+			target: got.target,
+		}).toEqual({
+			action: "install",
+			reason: "absent",
+			target: "0.4.4",
+		});
+	});
+
+	test("installed behind the catalog: update / behind with the scope and its before-version", () => {
+		const idx = indexCatalog([info("designer@magus", "2.0.0", "1.5.0")]);
+
+		const got = classifyPlugin("designer@magus", "latest", idx);
+
+		expect({
+			action: got.action,
+			reason: got.reason,
+			target: got.target,
+			installed: got.installed,
+			available: got.available,
+		}).toEqual({
+			action: "update",
+			reason: "behind",
+			target: "2.0.0",
+			installed: "1.5.0",
+			available: "2.0.0",
+		});
+		expect(got.scopes).toContain("project");
+		expect(got.beforeVersions.project).toBe("1.5.0");
+	});
+
+	test("installed equal to the catalog: current / up-to-date", () => {
+		const idx = indexCatalog([info("dev@magus", "7.4.0", "7.4.0")]);
+
+		const got = classifyPlugin("dev@magus", "latest", idx);
+
+		expect({ action: got.action, reason: got.reason }).toEqual({
+			action: "current",
+			reason: "up-to-date",
+		});
+	});
+
+	// Report #1 asked for the opposite of this, and that decision was REVERSED:
+	// a catalog that publishes no version leaves the install `current`, because
+	// there is no newer version to be behind. The reason code still records WHY
+	// the verdict was reached, so the state is not lost — it just stops being
+	// reported as a problem the reader must act on.
+	test("unversioned catalog with a commit-sha install is current, with the reason kept", () => {
+		const idx = indexCatalog([
+			info("code-review@claude-plugins-official", null, "3ea32df27be7"),
+		]);
+
+		const got = classifyPlugin(
+			"code-review@claude-plugins-official",
+			"latest",
+			idx,
+		);
+
+		expect({ action: got.action, reason: got.reason }).toEqual({
+			action: "current",
+			reason: "no-published-version",
+		});
+		// No note: nothing here is actionable, so there is nothing to tell anyone.
+		expect(got.note).toBeUndefined();
+	});
+
+	test("a failed catalog check on a latest pin is unknown / catalog-unverified, never current", () => {
+		const idx = indexCatalog([
+			info("claudish@magus", "2.0.0", "2.0.0", { updateCheckFailed: true }),
+		]);
+
+		const got = classifyPlugin("claudish@magus", "latest", idx);
+
+		expect({ action: got.action, reason: got.reason }).toEqual({
+			action: "unknown",
+			reason: "catalog-unverified",
+		});
+	});
+
+	test("every unknown item carries a note and no target", () => {
+		const idx = indexCatalog([
+			info("a@magus", null, "abc123def456"),
+			info("b@magus", null, "1.0.0", { isOrphaned: true }),
+			info("c@magus", "1.0.0", "1.0.0", { updateCheckFailed: true }),
+			info("e@nowhere", null, "0.3.0", { isOrphaned: true }),
+		]);
+
+		// `a@magus` is deliberately NOT in this list: a catalog that publishes no
+		// version is `current` now, not unknown. It is the negative control
+		// below — without it this loop would pass even if every state collapsed
+		// into one.
+		for (const id of ["b@magus", "c@magus", "d@magus", "e@nowhere"]) {
+			const got = classifyPlugin(id, "latest", idx);
+			expect({ id, action: got.action }).toEqual({ id, action: "unknown" });
+			expect({ id, target: got.target, hasNote: Boolean(got.note) }).toEqual({
+				id,
+				target: null,
+				hasNote: true,
+			});
+		}
+
+		// The control: same catalog, same call, the opposite verdict — and
+		// crucially no note, because nothing about it is actionable.
+		const a = classifyPlugin("a@magus", "latest", idx);
+		expect(a.action).toBe("current");
+		expect(a.note).toBeUndefined();
+	});
+});
+
+describe("planPluginUpdates is classifyPlugin over every pin, sorted", () => {
+	test("output is sorted by pluginId and equals classifyPlugin item for item", () => {
+		const catalog = [
+			info("zeta@magus", "2.0.0", "1.0.0"),
+			info("alpha@magus", "1.0.0", "1.0.0"),
+			info("mid@magus", null, "abc123def456"),
+		];
+		const pins = {
+			"zeta@magus": "latest",
+			"alpha@magus": "latest",
+			"mid@magus": "latest",
+		};
+
+		const plan = planPluginUpdates(
+			pins,
+			new Map(catalog.map((c) => [c.id, c])),
+		);
+
+		expect(plan.map((p) => p.pluginId)).toEqual([
+			"alpha@magus",
+			"mid@magus",
+			"zeta@magus",
+		]);
+		const idx = indexCatalog(catalog);
+		for (const p of plan) {
+			expect(p).toEqual(
+				classifyPlugin(p.pluginId, pins[p.pluginId as keyof typeof pins], idx),
+			);
+		}
+	});
+});
+
+describe("pinForRow / classifyPluginRows", () => {
+	const declared = info("dev@magus", "1.0.0", "1.0.0");
+	const installedOnly = info("extra@magus", "1.0.0", "1.0.0");
+	const enabledOnly = info("en@magus", "1.0.0", null, {
+		enabled: true,
+		userScope: { enabled: true },
+	});
+	const browseOnly = info("browse@magus", "1.0.0", null);
+	const pins = { "dev@magus": "1.0.0" };
+
+	test("closure pin wins; installed or enabled rows are judged against latest; browse-only has no pin", () => {
+		expect(pinForRow(declared, pins)).toBe("1.0.0");
+		expect(pinForRow(installedOnly, pins)).toBe("latest");
+		expect(pinForRow(enabledOnly, pins)).toBe("latest");
+		expect(pinForRow(browseOnly, pins)).toBeNull();
+	});
+
+	test("classifyPluginRows has one status per pinned row and none for browse-only rows", () => {
+		const rows = classifyPluginRows(
+			[declared, installedOnly, enabledOnly, browseOnly],
+			pins,
+		);
+
+		expect([...rows.keys()].sort()).toEqual([
+			"dev@magus",
+			"en@magus",
+			"extra@magus",
+		]);
+		expect(rows.get("en@magus")?.action).toBe("install");
+		expect(rows.get("en@magus")?.reason).toBe("enabled-not-installed");
+	});
+});
+
+describe("countPluginStates", () => {
+	test("tallies each state exactly", () => {
+		const counts = countPluginStates([
+			item({ action: "install", reason: "absent" }),
+			item({ action: "update", reason: "behind" }),
+			item({ action: "update", reason: "behind" }),
+			item({ action: "repair", reason: "content-stale" }),
+			item({ action: "current" }),
+			item({ action: "unknown", reason: "no-published-version" }),
+		]);
+
+		expect(counts).toEqual({
+			install: 1,
+			update: 2,
+			repair: 1,
+			current: 1,
+			unknown: 1,
+		});
+	});
+
+	test("an empty input counts zero everywhere", () => {
+		expect(countPluginStates([])).toEqual({
+			install: 0,
+			update: 0,
+			repair: 0,
+			current: 0,
+			unknown: 0,
+		});
+	});
+});
+
+describe("planIsBehind — plugin actions at the --check gate", () => {
+	function planOf(plugins: PluginUpdateItem[]): UpdatePlan {
+		return {
+			profileId: "default",
+			plugins,
+			bins: [],
+			skills: [],
+			binSpecs: new Map(),
+		};
+	}
+
+	test("install, update and repair fail the gate; current and unknown do not", () => {
+		// The unknown row is the point: "could not be checked" is not evidence of
+		// drift, and for a marketplace that publishes no version it never will be,
+		// so the same rule as an unknown tool applies. It is still not APPLIED,
+		// which is planHasWork's business, not this gate's.
+		const table: Array<[PluginUpdateItem["action"], boolean]> = [
+			["install", true],
+			["update", true],
+			["repair", true],
+			["current", false],
+			["unknown", false],
+		];
+		for (const [action, behind] of table) {
+			const plan = planOf([item({ action })]);
+			expect({ action, behind: planIsBehind(plan) }).toEqual({
+				action,
+				behind,
+			});
+		}
+	});
+
+	test("one unknown among current rows does not fail the gate; one update does", () => {
+		const unknowns = planOf([
+			item({ action: "current" }),
+			item({ action: "unknown", reason: "no-published-version" }),
+		]);
+		expect(planIsBehind(unknowns)).toBe(false);
+		expect(planHasWork(unknowns)).toBe(true);
+
+		const withUpdate = planOf([
+			item({ action: "unknown", reason: "no-published-version" }),
+			item({ action: "update", reason: "behind" }),
+		]);
+		expect(planIsBehind(withUpdate)).toBe(true);
+	});
+});
+
+describe("scopeIsBehind", () => {
+	test("true only for an update whose scopes include that scope", () => {
+		const upd = item({
+			action: "update",
+			reason: "behind",
+			scopes: ["project"],
+		});
+
+		expect(scopeIsBehind(upd, "project")).toBe(true);
+		expect(scopeIsBehind(upd, "user")).toBe(false);
+		expect(
+			scopeIsBehind(
+				item({ action: "unknown", scopes: ["project"] }),
+				"project",
+			),
+		).toBe(false);
+		expect(scopeIsBehind(null, "project")).toBe(false);
+		expect(scopeIsBehind(undefined, "user")).toBe(false);
+	});
+});
+
+describe("pluginStatusText — the TUI suffix contract (§8.7)", () => {
+	test("null status: empty, muted", () => {
+		expect(pluginStatusText(null)).toEqual({ suffix: "", tone: "muted" });
+	});
+
+	test("unknown: ' ? <note>' with the note verbatim", () => {
+		const note =
+			"its marketplace publishes no version for this plugin, so there is nothing to compare";
+		expect(
+			pluginStatusText(
+				item({ action: "unknown", reason: "no-published-version", note }),
+			).suffix,
+		).toBe(` ? ${note}`);
+	});
+
+	test("update: ' → v<target> available', plus ' (<note>)' when a note is set", () => {
+		expect(
+			pluginStatusText(
+				item({ action: "update", reason: "behind", target: "2.0.0" }),
+			).suffix,
+		).toBe(" → v2.0.0 available");
+		expect(
+			pluginStatusText(
+				item({
+					action: "update",
+					reason: "pin-undeliverable",
+					target: "1.0.0",
+					note: "pin n",
+				}),
+			).suffix,
+		).toBe(" → v1.0.0 available (pin n)");
+	});
+
+	test("repair: ' stale — reinstall (<note>)'", () => {
+		expect(
+			pluginStatusText(
+				item({
+					action: "repair",
+					reason: "content-stale",
+					note: "files moved",
+				}),
+			).suffix,
+		).toBe(" stale — reinstall (files moved)");
+	});
+
+	test("install: absent claims the profile declares it; enabled-not-installed shows its note instead", () => {
+		expect(
+			pluginStatusText(
+				item({ action: "install", reason: "absent", installed: null }),
+			).suffix,
+		).toBe(" not installed — profile declares it");
+		const enabled = pluginStatusText(
+			item({
+				action: "install",
+				reason: "enabled-not-installed",
+				installed: null,
+				note: "enabled in user settings",
+			}),
+		).suffix;
+		expect(enabled).toBe(" not installed (enabled in user settings)");
+		expect(enabled).not.toContain("profile declares");
+	});
+
+	test("current: empty, or ' (<note>)' for pin-undeliverable", () => {
+		expect(pluginStatusText(item({ action: "current" })).suffix).toBe("");
+		expect(
+			pluginStatusText(
+				item({ action: "current", reason: "pin-undeliverable", note: "pin n" }),
+			).suffix,
+		).toBe(" (pin n)");
+	});
+});
+
+describe("pluginRowText", () => {
+	function rowItem(
+		plugin: PluginInfo,
+		status: PluginUpdateItem | null,
+	): PluginPluginItem {
+		return {
+			id: `plugin:${plugin.id}`,
+			kind: "plugin",
+			label: plugin.name,
+			plugin,
+			isExpandable: false,
+			isExpanded: false,
+			status,
+		};
+	}
+
+	// The gate this guards: every status clause used to be conditional on the
+	// installed version being displayable, so a plugin recorded as "0.0.0"
+	// printed nothing after its name and read as healthy.
+	//
+	// The fixture is an ORPHAN at 0.0.0, not a plain 0.0.0 install. A plain one
+	// is `current` with no note now, which would leave nothing for this test to
+	// find and let the gate come back unnoticed.
+	test("a note renders on a 0.0.0 install — no version gate", () => {
+		const plugin = info("zero-version@magus", null, "0.0.0", {
+			isOrphaned: true,
+		});
+		const sibling = info("dev@magus", "1.0.0", "1.0.0");
+		const status = classifyPlugin(
+			plugin.id,
+			"latest",
+			indexCatalog([plugin, sibling]),
+		);
+
+		const out = pluginRowText(rowItem(plugin, status));
+
+		expect(status.action).toBe("unknown");
+		expect(status.note).toBeTruthy();
+		expect(out.text).toContain(status.note ?? "<missing note>");
+		// The undisplayable version itself is still never printed.
+		expect(out.text).not.toContain("0.0.0");
+	});
+
+	test("text is exactly the segments joined, and contains the status suffix", () => {
+		const plugin = info("designer@magus", "2.0.0", "1.5.0");
+		const status = classifyPlugin(plugin.id, "latest", indexCatalog([plugin]));
+
+		const out = pluginRowText(rowItem(plugin, status));
+
+		expect(out.text).toBe(out.segments.map((s) => s.text).join(""));
+		expect(out.text).toContain(pluginStatusText(status).suffix);
+	});
+
+	test("an orphan row renders its note", () => {
+		const plugin = info("legacy@magus", null, "0.5.0", { isOrphaned: true });
+		const sibling = info("dev@magus", "1.0.0", "1.0.0");
+		const status = classifyPlugin(
+			plugin.id,
+			"latest",
+			indexCatalog([plugin, sibling]),
+		);
+
+		const out = pluginRowText(rowItem(plugin, status));
+
+		expect(status.action).toBe("unknown");
+		expect(out.text).toContain(status.note ?? "<missing note>");
+	});
+});