magus-cli 0.0.0-placeholder → 7.1.0

package/src/__tests__/version-unknown-state.test.ts

@@ -0,0 +1,403 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildScopeStatus,
+	compareVersions,
+	isBehind,
+	isInstalledInScope,
+	resolveScopeAction,
+} from "../services/plugin-manager.js";
+import type { PluginInfo } from "../services/plugin-manager.js";
+import { planPluginUpdates } from "../services/update-plan.js";
+
+/**
+ * REGRESSION: magus renders "I cannot tell" as "nothing there" in three
+ * separate places — Fixed in /dev:fix session dev-fix-20260910-magus.
+ *
+ * Measured before the fix, against the real function and real registry values:
+ *
+ *   compareVersions("517b2fcd1b60", "b819188d2eea") = 0   hasUpdate=false
+ *   compareVersions("7.2.0",        "517b2fcd1b60") = 1   hasUpdate=true
+ *
+ * Two different git commits compared EQUAL, so a sha-versioned plugin could
+ * never report an update; and a sha compared against a semver reported a
+ * spurious one. `feature-dev@claude-plugins-official` is 517b2fcd1b60 in one
+ * project and b819188d2eea in another on the reporter's machine.
+ *
+ * The rule this file pins: an unorderable pair is `null` (unknown), never 0
+ * (equal) and never a direction.
+ */
+
+const SHA_A = "517b2fcd1b60";
+const SHA_B = "b819188d2eea";
+
+describe("compareVersions — orderable pairs", () => {
+	test("semver ordering is unchanged", () => {
+		expect(compareVersions("7.2.0", "7.1.0")).toBe(1);
+		expect(compareVersions("7.1.0", "7.2.0")).toBe(-1);
+		expect(compareVersions("7.1.0", "7.1.0")).toBe(0);
+	});
+
+	test("a leading v is still stripped", () => {
+		expect(compareVersions("v2.0.0", "1.9.9")).toBe(1);
+	});
+
+	test("uneven part counts still compare", () => {
+		expect(compareVersions("1.2", "1.2.0")).toBe(0);
+		expect(compareVersions("1.2.1", "1.2")).toBe(1);
+	});
+});
+
+describe("compareVersions — unorderable pairs are null, not 0", () => {
+	test("two DIFFERENT commit shas are not equal", () => {
+		// The bug: this returned 0, so nothing downstream could see a difference.
+		expect(compareVersions(SHA_A, SHA_B)).toBeNull();
+		expect(compareVersions(SHA_B, SHA_A)).toBeNull();
+	});
+
+	test("the same commit sha is genuinely equal", () => {
+		expect(compareVersions(SHA_A, SHA_A)).toBe(0);
+	});
+
+	test("a sha against a semver is not orderable in either direction", () => {
+		// The bug: these returned 1 and -1, a fabricated ordering.
+		expect(compareVersions("7.2.0", SHA_A)).toBeNull();
+		expect(compareVersions(SHA_A, "7.2.0")).toBeNull();
+	});
+
+	test("a missing side is unknown, not equal", () => {
+		// The bug: `if (!a || !b) return 0` claimed two absent versions matched.
+		expect(compareVersions(undefined, "1.0.0")).toBeNull();
+		expect(compareVersions("1.0.0", null)).toBeNull();
+		expect(compareVersions(undefined, undefined)).toBeNull();
+	});
+
+	test("the 0.0.0 sentinel is comparable — official plugins record it", () => {
+		expect(compareVersions("0.0.0", "0.0.0")).toBe(0);
+		expect(compareVersions("1.0.0", "0.0.0")).toBe(1);
+	});
+});
+
+describe("isBehind — the question callers actually ask", () => {
+	test("semver behind, ahead, level", () => {
+		expect(isBehind("7.2.0", "7.1.0")).toBe(true);
+		expect(isBehind("7.1.0", "7.2.0")).toBe(false);
+		expect(isBehind("7.1.0", "7.1.0")).toBe(false);
+	});
+
+	test("a different published sha means the install is not current", () => {
+		// The catalog is authoritative for what is published NOW. An installed
+		// commit that differs from it is not current, even though the two shas
+		// carry no ordering between them.
+		expect(isBehind(SHA_B, SHA_A)).toBe(true);
+		expect(isBehind(SHA_A, SHA_A)).toBe(false);
+	});
+
+	test("a sha against a semver is unknown, never a silent false", () => {
+		expect(isBehind("7.2.0", SHA_A)).toBeNull();
+		expect(isBehind(SHA_A, "7.2.0")).toBeNull();
+	});
+
+	test("not installed is unknown, not up to date", () => {
+		// The bug: `installedVersion && compare(...)` yielded false, so a plugin
+		// that was not installed at all was excluded from the update count and
+		// read as up to date.
+		expect(isBehind("7.2.0", undefined)).toBeNull();
+		expect(isBehind("7.2.0", null)).toBeNull();
+	});
+});
+
+describe("buildScopeStatus — installation is a registry fact, not a settings key", () => {
+	test("an installed but NOT enabled plugin still reports its scope", () => {
+		// The bug: scope was `enabledPlugins[id] !== undefined ? {...} : undefined`,
+		// so a plugin with a real registry row but no settings key rendered
+		// identically to one that was never installed.
+		const scope = buildScopeStatus({}, { "dev@magus": "7.2.0" }, "dev@magus");
+		expect(scope).toBeDefined();
+		expect(scope?.version).toBe("7.2.0");
+		expect(scope?.enabled).toBe(false);
+		expect(isInstalledInScope(scope)).toBe(true);
+	});
+
+	test("enabled with no install is still reported, as a broken state", () => {
+		const scope = buildScopeStatus({ "dev@magus": true }, {}, "dev@magus");
+		expect(scope).toBeDefined();
+		expect(scope?.enabled).toBe(true);
+		expect(scope?.version).toBeUndefined();
+		expect(isInstalledInScope(scope)).toBe(false);
+	});
+
+	test("neither enabled nor installed has no scope at all", () => {
+		expect(buildScopeStatus({}, {}, "dev@magus")).toBeUndefined();
+	});
+});
+
+describe("isInstalledInScope — presence of files, not permission to load", () => {
+	test("installed and disabled is still installed", () => {
+		// The old rule was `!!scope?.enabled && !!scope.version`, which made
+		// disabling a plugin look like uninstalling it.
+		expect(isInstalledInScope({ enabled: false, version: "7.2.0" })).toBe(true);
+	});
+
+	test("the 0.0.0 sentinel counts as installed", () => {
+		expect(isInstalledInScope({ enabled: true, version: "0.0.0" })).toBe(true);
+	});
+
+	test("enabled with no version is not installed", () => {
+		expect(isInstalledInScope({ enabled: true, version: undefined })).toBe(
+			false,
+		);
+	});
+});
+
+const info = (over: Partial<PluginInfo>): PluginInfo =>
+	({
+		id: "x@magus",
+		name: "x",
+		version: "1.0.0",
+		description: "",
+		marketplace: "magus",
+		marketplaceDisplay: "Magus",
+		enabled: true,
+		...over,
+	}) as PluginInfo;
+
+/**
+ * A catalog that HAS been read for @magus — it lists other magus plugins. That
+ * distinction is load-bearing: an empty catalog means "this marketplace was
+ * never read", where absence proves nothing, and installing is what registers
+ * it. Only a catalog we demonstrably hold entries from can turn absence into
+ * the answer "that plugin is not published".
+ */
+const magusCatalog = (...extra: PluginInfo[]) =>
+	new Map(
+		[
+			info({ id: "dev@magus", version: "7.2.0" }),
+			info({ id: "terminal@magus", version: "5.0.1" }),
+			...extra,
+		].map((p) => [p.id, p]),
+	);
+
+describe("planPluginUpdates — a pin its own marketplace does not offer", () => {
+	test("declared, not installed, marketplace read, plugin absent → unknown", () => {
+		// The bug: the !installed branch ran before any catalog guard, so
+		// `agentdev@magus` (retired) and `seo@magus` (moved to magus-marketing)
+		// planned as `install` with the literal pin as target on every run,
+		// forever, and every apply failed. The installed path already answered
+		// this correctly further down; the two are now consistent.
+		const items = planPluginUpdates(
+			{ "agentdev@magus": "latest" },
+			magusCatalog(),
+		);
+		expect(items).toHaveLength(1);
+		expect(items[0]?.action).toBe("unknown");
+		expect(items[0]?.target).toBeNull();
+		expect(items[0]?.note).toContain(
+			"not offered by any configured marketplace",
+		);
+		expect(items[0]?.reason).toBe("not-offered");
+	});
+
+	test("an exact pin its marketplace does not offer is also unknown", () => {
+		const items = planPluginUpdates({ "gone@magus": "3.0.0" }, magusCatalog());
+		expect(items[0]?.action).toBe("unknown");
+		expect(items[0]?.target).toBeNull();
+		expect(items[0]?.reason).toBe("not-offered");
+	});
+
+	test("declared, not installed, and the catalog does offer it → install", () => {
+		const items = planPluginUpdates(
+			{ "kanban@magus": "latest" },
+			magusCatalog(info({ id: "kanban@magus", version: "1.6.2" })),
+		);
+		expect(items[0]?.action).toBe("install");
+		expect(items[0]?.target).toBe("1.6.2");
+		expect(items[0]?.reason).toBe("absent");
+	});
+
+	test("a marketplace we have NOT read still plans an install", () => {
+		// Not the dead-pin case: with no entries from @newmp we never read its
+		// catalog, so absence is not evidence — and installing is what registers
+		// the marketplace in the first place. Guarding on `available === null`
+		// alone broke exactly this, which the existing suite caught.
+		const items = planPluginUpdates(
+			{ "thing@newmp": "latest" },
+			magusCatalog(),
+		);
+		expect(items[0]?.action).toBe("install");
+		expect(items[0]?.reason).toBe("absent");
+	});
+});
+
+describe("REVIEW-B regressions — found by the patch-quality panel", () => {
+	test("a catalog entry with NO version is offered, not unknown", () => {
+		// Measured: 278 of the 292 plugins in claude-plugins-official declare no
+		// version at all, `feature-dev` among them. Keying "not offered" on
+		// `available === null` planned `unknown` for every one of them and never
+		// installed. Membership in the catalog is the real test.
+		const items = planPluginUpdates(
+			{ "feature-dev@official": "latest" },
+			new Map(
+				[
+					info({ id: "feature-dev@official", version: null }),
+					info({ id: "github@official", version: null }),
+				].map((p) => [p.id, p]),
+			),
+		);
+		expect(items[0]?.action).toBe("install");
+		expect(items[0]?.reason).toBe("absent");
+	});
+
+	// REVIEW-B's finding is accepted and its remedy REVERSED. 21 registry rows
+	// carry the literal string "unknown" as their version; against a semver
+	// catalog they are unorderable, so nothing is provably behind. REVIEW-B
+	// concluded that made `current` a false claim.
+	//
+	// The claim is now explicitly "nothing is KNOWN to be behind", and that is
+	// what `current` means here. Raising a warning instead put a permanent amber
+	// row in front of the user with no action that could ever clear it, which is
+	// a worse falsehood: it says "do something" when there is nothing to do.
+	test("an installed version that cannot be compared is assumed current", () => {
+		const items = planPluginUpdates(
+			{ "playground@official": "latest" },
+			new Map([
+				[
+					"playground@official",
+					info({
+						id: "playground@official",
+						version: "7.3.0",
+						projectScope: { enabled: true, version: "unknown" },
+					}),
+				],
+			]),
+		);
+		expect(items[0]?.action).toBe("current");
+		expect(items[0]?.reason).not.toBe("unorderable");
+		// The row stays silent: no note, and nothing planned against it.
+		expect(items[0]?.note).toBeUndefined();
+		expect(items[0]?.scopes).toEqual([]);
+	});
+
+	test("a genuinely current install is still current", () => {
+		const items = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			new Map([
+				[
+					"dev@magus",
+					info({
+						id: "dev@magus",
+						version: "7.3.0",
+						projectScope: { enabled: true, version: "7.3.0" },
+					}),
+				],
+			]),
+		);
+		expect(items[0]?.action).toBe("current");
+		expect(items[0]?.reason).toBe("up-to-date");
+	});
+});
+
+describe("resolveScopeAction — the scope key must never silently uninstall", () => {
+	test("installed but DISABLED resolves to install, not uninstall", () => {
+		// The hazard: the scope key runs cliUninstallPlugin with no confirmation.
+		// Relaxing isInstalledInScope made this combination fall through to
+		// "uninstall", so pressing the key on a plugin the user had merely
+		// switched off would delete it.
+		expect(
+			resolveScopeAction({ enabled: false, version: "3.0.2" }, false),
+		).toBe("install");
+	});
+
+	test("installed AND enabled at the latest version still offers uninstall", () => {
+		expect(resolveScopeAction({ enabled: true, version: "3.0.2" }, false)).toBe(
+			"uninstall",
+		);
+	});
+
+	test("installed, enabled, and behind still offers update", () => {
+		expect(resolveScopeAction({ enabled: true, version: "3.0.1" }, true)).toBe(
+			"update",
+		);
+	});
+
+	test("not installed at all resolves to install", () => {
+		expect(resolveScopeAction(undefined, false)).toBe("install");
+	});
+});
+
+describe("installed with no comparable catalog version — two different causes", () => {
+	test("in the catalog but declaring no version is NOT 'withdrawn'", () => {
+		// feature-dev@claude-plugins-official, measured live: installed, listed by
+		// its marketplace, and declaring no version. Reporting it as "not offered
+		// by any configured marketplace" told the user a working, currently
+		// published plugin had been withdrawn.
+		const items = planPluginUpdates(
+			{ "feature-dev@official": "latest" },
+			new Map([
+				[
+					"feature-dev@official",
+					info({
+						id: "feature-dev@official",
+						version: null,
+						projectScope: { enabled: true, version: "3ea32df27be7" },
+					}),
+				],
+			]),
+		);
+		// The distinction this test exists for is between the two REASONS, and it
+		// still holds. What changed is the verdict: declaring no version is not a
+		// problem, so the row is `current` and says nothing. Being withdrawn IS a
+		// problem, so the next test's row is `unknown` and says so.
+		expect(items[0]?.reason).toBe("no-published-version");
+		expect(items[0]?.reason).not.toBe("not-offered");
+		expect(items[0]?.action).toBe("current");
+		expect(items[0]?.note).toBeUndefined();
+	});
+
+	test("absent from the catalog entirely IS 'not offered'", () => {
+		const items = planPluginUpdates(
+			{ "gone@magus": "latest" },
+			new Map([
+				[
+					"other@magus",
+					info({
+						id: "other@magus",
+						version: "1.0.0",
+						projectScope: { enabled: true, version: "1.0.0" },
+					}),
+				],
+			]),
+		);
+		expect(items[0]?.action).toBe("unknown");
+		expect(items[0]?.note).toContain(
+			"not offered by any configured marketplace",
+		);
+		expect(items[0]?.reason).toBe("not-offered");
+	});
+});
+
+describe('the "0.0.0" registry value keeps its reason', () => {
+	test("installed at 0.0.0 with no published version is no-published-version", () => {
+		// Real: explanatory-output-style@claude-plugins-official is recorded as
+		// "0.0.0" in the registry for many project paths, and its marketplace
+		// publishes no version.
+		//
+		// "0.0.0" must never silently become a DIFFERENT reason — that is what
+		// this pins. The verdict is `current`: there is no published version to
+		// be behind, so there is nothing to report and nothing to do.
+		const items = planPluginUpdates(
+			{ "explanatory-output-style@official": "latest" },
+			new Map([
+				[
+					"explanatory-output-style@official",
+					info({
+						id: "explanatory-output-style@official",
+						version: null,
+						projectScope: { enabled: true, version: "0.0.0" },
+					}),
+				],
+			]),
+		);
+		expect(items[0]?.reason).toBe("no-published-version");
+		expect(items[0]?.action).toBe("current");
+	});
+});

package/src/__tests__/worktree-registry-resolution.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { pickRegistryEntry } from "../services/claude-settings.js";
+import type { InstalledPluginEntry } from "../types/index.js";
+
+/**
+ * Regression cover for "a fresh git worktree reports every plugin as not installed".
+ *
+ * `installed_plugins.json` keys one entry per `projectPath`, and a new worktree is
+ * a project path nobody has ever installed into — measured on a real machine:
+ * 750 project-scope rows, zero of them for the worktree, and zero user-scope rows
+ * for any magus plugin. So `pickRegistryEntry` found nothing, `overlayRegistryVersions`
+ * deleted the version as an unbacked claim, and `isInstalledInScope` reported the
+ * plugin missing.
+ *
+ * Claude Code disagreed: it loaded all of them. Its loader is not gated on the
+ * current project — a worktree with no rows resolves `installPath` from another
+ * project's row and loads from cache (measured, `ai-docs/plugin-system-state-model.md`).
+ * So magus was offering to install plugins that were already working.
+ *
+ * A linked worktree is the same project as its main working tree, so the main
+ * tree's row is the honest answer for it.
+ */
+
+const entry = (
+	scope: InstalledPluginEntry["scope"],
+	version: string,
+	projectPath?: string,
+): InstalledPluginEntry => ({
+	scope,
+	version,
+	projectPath,
+	installPath: `/cache/${version}`,
+	installedAt: "2026-01-01T00:00:00.000Z",
+	lastUpdated: "2026-01-01T00:00:00.000Z",
+});
+
+const MAIN = "/repo";
+const TREE = "/repo/.claude/worktrees/feature";
+
+describe("pickRegistryEntry — worktree fallback", () => {
+	test("a worktree with no rows of its own resolves to the main working tree's row", () => {
+		const entries = [entry("project", "3.3.0", MAIN)];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"3.3.0",
+		);
+	});
+
+	test("the worktree's own row still wins over the main tree's row", () => {
+		const entries = [
+			entry("project", "3.3.0", MAIN),
+			entry("project", "4.0.0", TREE),
+		];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"4.0.0",
+		);
+	});
+
+	test("a local-scope row on the main tree satisfies a worktree project lookup", () => {
+		const entries = [entry("local", "5.0.0", MAIN)];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"5.0.0",
+		);
+	});
+
+	test("the main-tree row outranks a user-scope entry", () => {
+		// Same project beats "installed globally somewhere". The user entry is the
+		// looser fallback and stays available when the main tree has no row.
+		const entries = [entry("user", "1.0.0"), entry("project", "3.3.0", MAIN)];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"3.3.0",
+		);
+	});
+
+	test("the user-scope entry still applies when the main tree has no row either", () => {
+		const entries = [
+			entry("user", "2.1.2"),
+			entry("project", "9.9.9", "/elsewhere"),
+		];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"2.1.2",
+		);
+	});
+
+	test("an unrelated project's row is never inherited", () => {
+		// The loader may well resolve one of these, but magus must not claim a
+		// version it cannot attribute to this project.
+		const entries = [entry("project", "9.9.9", "/some/other/project")];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])).toBeUndefined();
+	});
+
+	test("fallback paths are compared resolved, not as raw strings", () => {
+		const entries = [entry("project", "4.2.0", "/repo/./sub/..")];
+		expect(pickRegistryEntry(entries, "project", TREE, [MAIN])?.version).toBe(
+			"4.2.0",
+		);
+	});
+
+	test("fallback paths are ignored for a user-scope lookup", () => {
+		const entries = [entry("project", "3.3.0", MAIN)];
+		expect(pickRegistryEntry(entries, "user", TREE, [MAIN])).toBeUndefined();
+	});
+
+	test("omitting fallback paths preserves the previous behaviour", () => {
+		const entries = [entry("project", "3.3.0", MAIN)];
+		expect(pickRegistryEntry(entries, "project", TREE)).toBeUndefined();
+	});
+});