magus-cli 7.2.0 → 7.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.2.0",
+  "version": "7.3.1",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.2.0",
-    "magus-cli-darwin-x64": "7.2.0",
-    "magus-cli-linux-x64": "7.2.0"
+    "magus-cli-darwin-arm64": "7.3.1",
+    "magus-cli-darwin-x64": "7.3.1",
+    "magus-cli-linux-x64": "7.3.1"
   }
 }

package/scripts/build-binaries.ts

@@ -10,8 +10,10 @@
  *     package.json   (os/cpu restricted, no `bin` — the launcher execs it)
  *     bin/magus   (the compiled binary)
  *
- * The main `magus` package lists these as optionalDependencies; npm installs
- * only the one matching the host os/cpu, and bin/magus.js execs it.
+ * The main `magus-cli` package lists these as optionalDependencies; npm
+ * installs only the one matching the host os/cpu, and bin/magus.js execs it.
+ * (`magus-cli` is the npm package; `magus` is the command it installs. The
+ * bare `magus` name on npm is an unrelated package.)
  *
  * Hard constraint: magus pins @opentui 0.1.x — 0.4.x breaks --compile.
  *

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

@@ -51,6 +51,7 @@ function item(over: Partial<PluginUpdateItem>): PluginUpdateItem {
 		pluginId: "x@magus",
 		pinned: "latest",
 		installed: "1.0.0",
+		loaded: "1.0.0",
 		available: "1.0.0",
 		target: null,
 		action: "current",
@@ -318,6 +319,7 @@ describe("countPluginStates", () => {
 			update: 2,
 			repair: 1,
 			current: 1,
+			"stale-load": 0,
 			unknown: 1,
 		});
 	});
@@ -328,6 +330,7 @@ describe("countPluginStates", () => {
 			update: 0,
 			repair: 0,
 			current: 0,
+			"stale-load": 0,
 			unknown: 0,
 		});
 	});

package/src/__tests__/doctor.test.ts

@@ -15,6 +15,7 @@ import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { doctorExitCode } from "../cli/doctor.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import type { DoctorResult } from "../services/doctor.js";
 
@@ -461,3 +462,33 @@ describe("doctor", () => {
 		});
 	});
 });
+
+/**
+ * `magus doctor`'s exit code, and the one thing `--fix` must not silence.
+ *
+ * Stale plugin loads are printed by doctor and repaired by nothing it runs — the
+ * section says so itself. They used to be added to the same counter as the
+ * fixable problems, and the code was `problems > 0 && !fix ? 1 : 0`, so
+ * `magus doctor --fix` printed its red lines and exited 0. A CI or pre-flight
+ * step reading that exit code went green over a plugin whose sessions load a
+ * version nobody installed.
+ */
+describe("doctorExitCode", () => {
+	it("exits 0 when nothing is wrong, with or without --fix", () => {
+		expect(doctorExitCode({ fixable: 0, unfixable: 0, fix: false })).toBe(0);
+		expect(doctorExitCode({ fixable: 0, unfixable: 0, fix: true })).toBe(0);
+	});
+
+	it("exits 1 for fixable problems only when --fix was NOT asked for", () => {
+		expect(doctorExitCode({ fixable: 3, unfixable: 0, fix: false })).toBe(1);
+		expect(doctorExitCode({ fixable: 3, unfixable: 0, fix: true })).toBe(0);
+	});
+
+	it("exits 1 for a stale plugin load EVEN WITH --fix", () => {
+		// The regression: --fix does not repair these, so suppressing the exit code
+		// reports success over output that says the opposite.
+		expect(doctorExitCode({ fixable: 0, unfixable: 1, fix: true })).toBe(1);
+		expect(doctorExitCode({ fixable: 0, unfixable: 1, fix: false })).toBe(1);
+		expect(doctorExitCode({ fixable: 2, unfixable: 1, fix: true })).toBe(1);
+	});
+});

package/src/__tests__/npm-package-name-api.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The npm package name has one source of truth, and the self-upgrade builders
+ * read it.
+ *
+ * `MAGUS_NPM_PACKAGE` is `package.json` `name` (`magus-cli`). It is the npm
+ * package, NOT the command: the command is the `bin` key (`magus`), and the
+ * bare npm name belongs to an unrelated package. `selfUpgradeCommand` and
+ * `duplicateInstallRemoval` are the pure builders behind `magus upgrade`.
+ *
+ * Written black-box from the API contract. On the old tree this file fails at
+ * import, because none of these exports existed.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	type SelfUpgradeManager,
+	duplicateInstallRemoval,
+	selfUpgradeCommand,
+} from "../cli/upgrade.js";
+import { MAGUS_NPM_PACKAGE } from "../data/npm-package.js";
+
+// Read at test time: the single source of truth the requirements name.
+const PKG = JSON.parse(
+	readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8"),
+) as { name: string; version: string; bin: Record<string, string> };
+
+const COMMAND = "magus";
+const PACKAGE = "magus-cli";
+const MANAGERS: SelfUpgradeManager[] = ["bun", "npm"];
+
+describe("MAGUS_NPM_PACKAGE", () => {
+	test("is package.json `name`", () => {
+		expect(typeof MAGUS_NPM_PACKAGE).toBe("string");
+		expect(MAGUS_NPM_PACKAGE).toBe(PKG.name);
+		expect(MAGUS_NPM_PACKAGE).toBe(PACKAGE);
+	});
+
+	test("is not the command", () => {
+		const commands = Object.keys(PKG.bin);
+		expect(commands).toContain(COMMAND);
+		expect(commands).not.toContain(MAGUS_NPM_PACKAGE);
+		expect(MAGUS_NPM_PACKAGE).not.toBe(COMMAND);
+	});
+});
+
+describe("selfUpgradeCommand", () => {
+	test("bun installs `<package>@latest` globally", () => {
+		expect(selfUpgradeCommand("bun")).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", `${PACKAGE}@latest`],
+		});
+	});
+
+	test("npm installs `<package>@latest` globally", () => {
+		expect(selfUpgradeCommand("npm")).toEqual({
+			cmd: "npm",
+			args: ["install", "-g", `${PACKAGE}@latest`],
+		});
+	});
+
+	test("is pure: the answer does not depend on PATH", () => {
+		const expected = MANAGERS.map((m) => selfUpgradeCommand(m));
+		const emptyDir = mkdtempSync(join(tmpdir(), "magus-selfupgrade-path-"));
+		const savedPath = process.env.PATH;
+		try {
+			process.env.PATH = emptyDir;
+			const again = MANAGERS.map((m) => selfUpgradeCommand(m));
+			expect(again).toEqual(expected);
+		} finally {
+			process.env.PATH = savedPath;
+			rmSync(emptyDir, { recursive: true, force: true });
+		}
+		expect(MANAGERS.map((m) => selfUpgradeCommand(m))).toEqual(expected);
+	});
+
+	test("reads the package name from the single source", () => {
+		for (const m of MANAGERS) {
+			const { cmd, args } = selfUpgradeCommand(m);
+			expect(cmd).toBe(m);
+			expect(args[args.length - 1]).toBe(`${MAGUS_NPM_PACKAGE}@latest`);
+		}
+	});
+});
+
+describe("duplicateInstallRemoval", () => {
+	test("bun names the package", () => {
+		expect(duplicateInstallRemoval("bun")).toBe(`bun uninstall -g ${PACKAGE}`);
+	});
+
+	test("npm names the package", () => {
+		expect(duplicateInstallRemoval("npm")).toBe(`npm uninstall -g ${PACKAGE}`);
+	});
+
+	test("carries no leading indentation (the caller indents)", () => {
+		for (const m of MANAGERS) {
+			const hint = duplicateInstallRemoval(m);
+			expect(hint).toBe(hint.trimStart());
+		}
+	});
+
+	test("reads the package name from the single source", () => {
+		for (const m of MANAGERS) {
+			const tokens = duplicateInstallRemoval(m).split(" ");
+			expect(tokens[0]).toBe(m);
+			expect(tokens[tokens.indexOf("-g") + 1]).toBe(MAGUS_NPM_PACKAGE);
+		}
+	});
+});

package/src/__tests__/npm-package-name.test.ts

@@ -0,0 +1,280 @@
+/**
+ * magus talks to npm by its PACKAGE name, never by its COMMAND name.
+ *
+ * The npm package is `package.json` `name` (`magus-cli`). The command users
+ * type is `magus`. The bare npm name belongs to an unrelated 2015 package
+ * whose latest release is 0.0.2, and npm never transfers names, so the split
+ * is permanent. Addressing npm by the command name made the update banner go
+ * silent and pointed the CLI Tools row at the wrong package.
+ *
+ * This file uses only exports that existed before the fix, so on the old tree
+ * it fails by VALUE (wrong URL, wrong packageName, wrong argv), not merely at
+ * import. Written black-box from the API contract.
+ *
+ * No network: every checkForUpdates call runs against a stubbed fetch, always
+ * with force = true, because the result is cached for the session.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cliTools } from "../data/cli-tools.js";
+import {
+	cliToolInstall,
+	cliToolUninstall,
+	cliToolUpdate,
+} from "../services/cli-tool-commands.js";
+import { cliToolToBin } from "../services/resolver.js";
+import { specForCatalogTool } from "../services/tool-probe.js";
+import {
+	checkForUpdates,
+	formatUpdateMessage,
+	getCurrentVersion,
+} from "../services/version-check.js";
+
+// Read at test time: the single source of truth the requirements name.
+const PKG = JSON.parse(
+	readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8"),
+) as { name: string; version: string; bin: Record<string, string> };
+
+/** The command users type. Also, unluckily, an unrelated npm package. */
+const COMMAND = "magus";
+/** The npm package, as the contract states it. */
+const PACKAGE = "magus-cli";
+const REGISTRY = "https://registry.npmjs.org";
+
+function magusEntry() {
+	const entry = cliTools.find((t) => t.name === COMMAND);
+	if (!entry) throw new Error("cliTools has no entry named magus");
+	return entry;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+function urlOf(input: unknown): string {
+	return input instanceof Request ? input.url : String(input);
+}
+
+describe("checkForUpdates asks npm about the package, not the command", () => {
+	const realFetch = globalThis.fetch;
+	let urls: string[];
+
+	beforeEach(() => {
+		urls = [];
+	});
+
+	afterEach(() => {
+		globalThis.fetch = realFetch;
+	});
+
+	function stubFetch(answer: (url: string) => Response | Promise<Response>) {
+		globalThis.fetch = (async (input: unknown) => {
+			const url = urlOf(input);
+			urls.push(url);
+			return answer(url);
+		}) as typeof fetch;
+	}
+
+	test("fetches the registry `latest` document of package.json `name`, once", async () => {
+		stubFetch(() => jsonResponse({ version: "999.0.0" }));
+
+		await checkForUpdates(true);
+
+		expect(urls).toHaveLength(1);
+		expect(urls[0]).toBe(`${REGISTRY}/${PKG.name}/latest`);
+		expect(urls[0]).toBe(`${REGISTRY}/${PACKAGE}/latest`);
+		// The first path segment is the package, never the command.
+		const segment = new URL(urls[0]!).pathname.split("/")[1];
+		expect(segment).toBe(PKG.name);
+		expect(segment).not.toBe(COMMAND);
+	});
+
+	test("with the registry as observed (bare name at 0.0.2, package ahead), an update is reported", async () => {
+		// A registry that answers per package, the way npm does: the unrelated
+		// package sits at 0.0.2, the real one is ahead of the running version.
+		const registry: Record<string, string> = {
+			magus: "0.0.2",
+			[PKG.name]: "999.0.0",
+		};
+		stubFetch((url) => {
+			const name = new URL(url).pathname.split("/")[1] ?? "";
+			const version = registry[name];
+			return version
+				? jsonResponse({ version })
+				: jsonResponse({ error: "Not found" }, 404);
+		});
+
+		const r = await checkForUpdates(true);
+
+		expect(r.currentVersion).toBe(PKG.version);
+		expect(r.latestVersion).toBe("999.0.0");
+		expect(r.updateAvailable).toBe(true);
+	});
+
+	test("a major release above the running version is a major update", async () => {
+		stubFetch(() => jsonResponse({ version: "999.0.0" }));
+
+		const r = await checkForUpdates(true);
+
+		expect(r.updateAvailable).toBe(true);
+		expect(r.updateType).toBe("major");
+		expect(r.latestVersion).toBe("999.0.0");
+	});
+
+	test("the unrelated package's 0.0.2 is not an update", async () => {
+		stubFetch(() => jsonResponse({ version: "0.0.2" }));
+
+		const r = await checkForUpdates(true);
+
+		expect(r.updateAvailable).toBe(false);
+	});
+
+	test("a non-ok registry response reports no update and keeps the running version", async () => {
+		stubFetch(() => jsonResponse({ error: "boom" }, 500));
+
+		const r = await checkForUpdates(true);
+
+		expect(r.latestVersion).toBe(r.currentVersion);
+		expect(r.updateAvailable).toBe(false);
+	});
+
+	test("a failed fetch reports no update and keeps the running version", async () => {
+		stubFetch(() => {
+			throw new Error("network down");
+		});
+
+		const r = await checkForUpdates(true);
+
+		expect(r.latestVersion).toBe(r.currentVersion);
+		expect(r.updateAvailable).toBe(false);
+	});
+
+	test("the running version is package.json `version`", () => {
+		expect(getCurrentVersion()).toBe(PKG.version);
+	});
+});
+
+describe("formatUpdateMessage", () => {
+	// Kept as a guard on the hint text; not V1 evidence (amendment L5).
+	test("names `magus upgrade` as the way to update", () => {
+		expect(
+			formatUpdateMessage({
+				currentVersion: "1.0.0",
+				latestVersion: "1.2.0",
+				updateAvailable: true,
+				updateType: "minor",
+			} as any),
+		).toBe("Update available: v1.0.0 → v1.2.0 (minor). Run: magus upgrade");
+	});
+
+	test("is empty when no update is available", () => {
+		expect(
+			formatUpdateMessage({
+				currentVersion: "1.0.0",
+				latestVersion: "1.0.0",
+				updateAvailable: false,
+			} as any),
+		).toBe("");
+	});
+});
+
+describe("the CLI Tools entry for magus", () => {
+	test("targets the npm package and keeps the command", () => {
+		const entry = magusEntry();
+
+		expect(entry.packageName).toBe(PKG.name);
+		expect(entry.packageName).toBe(PACKAGE);
+		// R6: everything that names the command is unchanged.
+		expect(entry.name).toBe(COMMAND);
+		expect(entry.displayName).toBe(COMMAND);
+		expect(entry.checkCommand).toBe("magus --version");
+		expect(entry.packageManager).toBe("bun");
+	});
+
+	test("install targets the package", () => {
+		expect(cliToolInstall(magusEntry())).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", PACKAGE],
+		});
+	});
+
+	test("update targets `<package>@latest` with bun and with npm", () => {
+		const entry = magusEntry();
+		expect(cliToolUpdate(entry, "bun")).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", `${PACKAGE}@latest`],
+		});
+		expect(cliToolUpdate(entry, "npm")).toEqual({
+			cmd: "npm",
+			args: ["install", "-g", `${PACKAGE}@latest`],
+		});
+	});
+
+	test("uninstall targets the package with bun and with npm", () => {
+		const entry = magusEntry();
+		expect(cliToolUninstall(entry, "bun")).toEqual({
+			cmd: "bun",
+			args: ["remove", "-g", PACKAGE],
+		});
+		expect(cliToolUninstall(entry, "npm")).toEqual({
+			cmd: "npm",
+			args: ["uninstall", "-g", PACKAGE],
+		});
+	});
+
+	test("no derived command addresses the bare command name on npm", () => {
+		const entry = magusEntry();
+		const commands = [
+			cliToolInstall(entry),
+			cliToolUpdate(entry, "bun"),
+			cliToolUpdate(entry, "npm"),
+			cliToolUninstall(entry, "bun"),
+			cliToolUninstall(entry, "npm"),
+		];
+		for (const c of commands) {
+			expect(c).not.toBeNull();
+			const args = c!.args as string[];
+			const target = args[args.indexOf("-g") + 1] ?? "";
+			// `<package>` or `<package>@<tag>`, never the command name.
+			expect(target.split("@")[0]).toBe(PKG.name);
+			expect(args).not.toContain(COMMAND);
+		}
+	});
+});
+
+describe("pins and probes resolve to the package", () => {
+	test("a pinned version installs `<package>@<version>` and checks the command", () => {
+		expect(cliToolToBin(COMMAND, PKG.version)).toMatchObject({
+			name: COMMAND,
+			via: "bun",
+			package: PACKAGE,
+			check: "magus --version",
+			version: PKG.version,
+		});
+	});
+
+	test("`latest` carries no version", () => {
+		const bin = cliToolToBin(COMMAND, "latest");
+		expect(bin).toMatchObject({
+			name: COMMAND,
+			via: "bun",
+			package: PACKAGE,
+			check: "magus --version",
+		});
+		expect(bin.version).toBeUndefined();
+	});
+
+	test("the catalogue spec (the dist-tags probe input) names the package", () => {
+		expect(specForCatalogTool(magusEntry(), null, undefined)).toMatchObject({
+			name: COMMAND,
+			via: "bun",
+			package: PACKAGE,
+			check: "magus --version",
+		});
+	});
+});