magus-cli 7.3.0 → 7.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.3.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.3.0",
-    "magus-cli-darwin-x64": "7.3.0",
-    "magus-cli-linux-x64": "7.3.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__/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",
+		});
+	});
+});

package/src/__tests__/upgrade-spawn.test.ts

@@ -0,0 +1,355 @@
+/**
+ * `magus upgrade`, end to end, with node:child_process replaced.
+ *
+ * The upgrade must install the npm PACKAGE (`package.json` `name`,
+ * `magus-cli`) at `latest`, with whichever package manager owns the active
+ * `magus` binary. The bare npm name is an unrelated package: installing it
+ * leaves magus where it was. The duplicate-install hint must name the real
+ * package too. The probes that look for the COMMAND (`which magus`,
+ * `bun pm -g bin`, `npm prefix -g`) stay as they are.
+ *
+ * SAFETY. This is the one test that could run a real global install, so three
+ * independent layers stand between it and one:
+ *   1. identity guard: before every call, the imported `spawn` and `execSync`
+ *      must BE the fakes, or the test throws without calling anything;
+ *   2. PATH is an empty temp directory for the duration of the call, so even a
+ *      real `spawn("bun", ...)` finds nothing (bun 1.4.0's child_process.spawn
+ *      honours a runtime PATH change; `Bun.which` does not, so it is not used);
+ *   3. the module mock is restored in afterAll, the way cli-router.test.ts
+ *      restores its own, so no later file in the same process inherits it.
+ * Every other process launcher on the module is replaced by a fake that
+ * records and throws.
+ *
+ * Written black-box from the API contract.
+ */
+
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	mock,
+	test,
+} from "bun:test";
+import * as childProcessNamespace from "node:child_process";
+import { EventEmitter } from "node:events";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+
+// 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 };
+
+const COMMAND = "magus";
+const PACKAGE = "magus-cli";
+const EXPECTED_ARGS = ["install", "-g", `${PACKAGE}@latest`];
+
+// Snapshot the real module BEFORE mocking. mock.module is process-global and
+// updates live namespaces, so the snapshot is what gets put back.
+const realChildProcess: Record<string, unknown> = { ...childProcessNamespace };
+const realDefault = (realChildProcess.default ?? {}) as Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Fakes
+// ---------------------------------------------------------------------------
+
+interface SpawnCall {
+	cmd: string;
+	args: string[];
+	options: Record<string, unknown>;
+}
+
+interface Scenario {
+	/** What `which magus` answers: the active binary. */
+	which: string;
+	/** What `bun pm -g bin` answers. */
+	bunBin: string;
+	/** What `npm prefix -g` answers. */
+	npmPrefix: string;
+	/** The exit code the fake child reports. */
+	exitCode: number;
+}
+
+let scenario: Scenario = { which: "", bunBin: "", npmPrefix: "", exitCode: 0 };
+let spawnCalls: SpawnCall[] = [];
+let execCalls: string[] = [];
+
+function fakeExecSync(command: string, options?: { encoding?: string }) {
+	const text = String(command);
+	execCalls.push(text);
+	let answer: string | undefined;
+	if (text.includes("which magus")) answer = scenario.which;
+	else if (text.includes("bun pm -g bin")) answer = scenario.bunBin;
+	else if (text.includes("npm prefix -g")) answer = scenario.npmPrefix;
+	if (!answer) {
+		throw new Error(`fake execSync has no answer for: ${text}`);
+	}
+	// Mirror Node: a string when an encoding is asked for, a Buffer otherwise.
+	const out = `${answer}\n`;
+	const encoding = options?.encoding;
+	return encoding && encoding !== "buffer" ? out : Buffer.from(out);
+}
+
+function fakeSpawn(
+	cmd: string,
+	args?: readonly string[],
+	options?: Record<string, unknown>,
+) {
+	spawnCalls.push({
+		cmd: String(cmd),
+		args: [...(args ?? [])],
+		options: options ?? {},
+	});
+	const child = Object.assign(new EventEmitter(), {
+		pid: 424242,
+		stdin: null,
+		stdout: null,
+		stderr: null,
+		kill: () => true,
+	});
+	const code = scenario.exitCode;
+	setTimeout(() => {
+		child.emit("exit", code, null);
+		child.emit("close", code, null);
+	}, 0);
+	return child;
+}
+
+function refuse(name: string) {
+	return (...a: unknown[]) => {
+		throw new Error(
+			`upgrade-spawn test refused child_process.${name}(${String(a[0])}): no real process may run here`,
+		);
+	};
+}
+
+const fakes = {
+	spawn: fakeSpawn,
+	execSync: fakeExecSync,
+	spawnSync: refuse("spawnSync"),
+	exec: refuse("exec"),
+	execFile: refuse("execFile"),
+	execFileSync: refuse("execFileSync"),
+	fork: refuse("fork"),
+};
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+let runUpgradeCommand: () => Promise<number>;
+
+beforeAll(async () => {
+	mock.module("node:child_process", () => ({
+		...realChildProcess,
+		...fakes,
+		default: { ...realDefault, ...fakes },
+	}));
+	// Imported only AFTER the mock, so the module binds to the fakes.
+	({ runUpgradeCommand } = await import("../cli/upgrade.js"));
+});
+
+afterAll(() => {
+	mock.module("node:child_process", () => realChildProcess);
+});
+
+/** Layer 1: refuse to proceed unless the fakes are what callers will get. */
+async function assertChildProcessIsFake(): Promise<void> {
+	const cp = (await import("node:child_process")) as unknown as Record<
+		string,
+		unknown
+	>;
+	if (cp.spawn !== fakeSpawn || cp.execSync !== fakeExecSync) {
+		throw new Error(
+			"SAFETY: node:child_process is not mocked. Refusing to call runUpgradeCommand, which would run a real global install.",
+		);
+	}
+}
+
+let root: string;
+let logs: string[];
+let otherOutput: string[];
+const realLog = console.log;
+const realError = console.error;
+const realWarn = console.warn;
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+	// realpath: on macOS the temp dir sits behind a symlink.
+	root = realpathSync(mkdtempSync(join(tmpdir(), "magus-upgrade-spawn-")));
+	const bunBin = join(root, ".bun", "bin");
+	const npmPrefix = join(root, "npm");
+	mkdirSync(bunBin, { recursive: true });
+	mkdirSync(join(npmPrefix, "bin"), { recursive: true });
+	mkdirSync(join(root, "empty-path"));
+	// Two real installs of the command, one per manager (amendment M3).
+	writeFileSync(join(bunBin, COMMAND), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+	writeFileSync(join(npmPrefix, "bin", COMMAND), "#!/bin/sh\nexit 0\n", {
+		mode: 0o755,
+	});
+
+	scenario = { which: "", bunBin, npmPrefix, exitCode: 0 };
+	spawnCalls = [];
+	execCalls = [];
+	logs = [];
+	otherOutput = [];
+
+	console.log = (...a: unknown[]) => {
+		logs.push(a.map(String).join(" "));
+	};
+	console.error = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	console.warn = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	// No network, in case the upgrade consults the registry first.
+	globalThis.fetch = (async () =>
+		new Response(JSON.stringify({ version: "999.0.0" }), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		})) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+	console.log = realLog;
+	console.error = realError;
+	console.warn = realWarn;
+	globalThis.fetch = realFetch;
+	rmSync(root, { recursive: true, force: true });
+});
+
+const bunWhich = () => join(scenario.bunBin, COMMAND);
+const npmWhich = () => join(scenario.npmPrefix, "bin", COMMAND);
+
+async function runUpgrade(which: string, exitCode = 0): Promise<number> {
+	scenario.which = which;
+	scenario.exitCode = exitCode;
+	await assertChildProcessIsFake();
+	// Layer 2: nothing is reachable by name while the upgrade runs (M2).
+	const savedPath = process.env.PATH;
+	process.env.PATH = join(root, "empty-path");
+	try {
+		return await runUpgradeCommand();
+	} finally {
+		if (savedPath === undefined) Reflect.deleteProperty(process.env, "PATH");
+		else process.env.PATH = savedPath;
+	}
+}
+
+/** Captured console.log output, one entry per physical line, ANSI removed. */
+function logLines(): string[] {
+	return logs.flatMap((l) => stripVTControlCharacters(l).split("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("runUpgradeCommand installs the npm package with the owning manager", () => {
+	test("a bun-owned binary upgrades with `bun install -g <package>@latest`", async () => {
+		const code = await runUpgrade(bunWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("bun");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("an npm-owned binary upgrades with `npm install -g <package>@latest`", async () => {
+		// Precondition: nothing in this path may look bun-owned.
+		expect(npmWhich()).not.toContain(".bun");
+		expect(npmWhich()).not.toContain("bun/bin");
+
+		const code = await runUpgrade(npmWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("npm");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("a `bun/bin` path without `.bun` also counts as bun-owned", async () => {
+		const dir = join(root, "opt", "bun", "bin");
+		mkdirSync(dir, { recursive: true });
+		const which = join(dir, COMMAND);
+		writeFileSync(which, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+		expect(which).not.toContain(".bun");
+
+		await runUpgrade(which);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(spawnCalls[0]!.cmd).toBe("bun");
+		expect(spawnCalls[0]!.args).toEqual(EXPECTED_ARGS);
+	});
+
+	test("resolves with the child's exit code", async () => {
+		const code = await runUpgrade(npmWhich(), 3);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(code).toBe(3);
+	});
+});
+
+describe("the duplicate-install hint names the npm package", () => {
+	function expectBothHints() {
+		const out = logLines().join("\n");
+		expect(out).toContain(`bun uninstall -g ${PACKAGE}`);
+		expect(out).toContain(`npm uninstall -g ${PACKAGE}`);
+		// Every uninstall hint that was printed targets the package.
+		const hints = logLines().filter((l) => /\buninstall\b/.test(l));
+		expect(hints.length).toBeGreaterThanOrEqual(2);
+		for (const line of hints) {
+			const tokens = line.trim().split(/\s+/);
+			const i = tokens.indexOf("-g");
+			expect(i).toBeGreaterThanOrEqual(0);
+			expect(tokens[i + 1]).toBe(PKG.name);
+		}
+	}
+
+	test("both installs present, bun active: both hints name the package", async () => {
+		await runUpgrade(bunWhich());
+
+		expectBothHints();
+	});
+
+	test("both installs present, npm active: both hints name the package", async () => {
+		await runUpgrade(npmWhich());
+
+		expectBothHints();
+	});
+});
+
+describe("the probes still look for the command (R6)", () => {
+	test("`which magus`, `bun pm -g bin` and `npm prefix -g` are what gets asked", async () => {
+		await runUpgrade(bunWhich());
+
+		const probes = execCalls.join("\n");
+		expect(probes).toContain("bun pm -g bin");
+		expect(probes).toContain("npm prefix -g");
+		// `which` is asked about the COMMAND, not the package.
+		const whichProbe = execCalls
+			.map((c) => c.trim().split(/\s+/))
+			.find((tokens) => tokens.includes("which"));
+		expect(whichProbe).toBeDefined();
+		expect(whichProbe![whichProbe!.indexOf("which") + 1]).toBe(COMMAND);
+	});
+});

package/src/cli/upgrade.ts

@@ -6,19 +6,49 @@
  * and advancing the tool itself moved here.
  *
  * Detects magus installs across bun + npm global, warns on duplicates
- * (active vs shadowed), then re-installs `magus@latest` with whichever
- * package manager owns the active binary. Resolves with the child's exit code.
+ * (active vs shadowed), then re-installs the npm package (`MAGUS_NPM_PACKAGE`)
+ * at latest with whichever package manager owns the active binary. Resolves
+ * with the child's exit code.
+ *
+ * The npm package is not the command. The binary on disk and `which magus`
+ * stay `magus`; only what is handed to the package manager uses the package
+ * name, because bare `magus` on npm is an unrelated package.
  */
 
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
+import { MAGUS_NPM_PACKAGE } from "../data/npm-package.js";
+import type { Command } from "../utils/command-utils.js";
+
+/** The package managers `magus upgrade` detects and upgrades through. */
+export type SelfUpgradeManager = "bun" | "npm";
+
+/**
+ * The self-upgrade command for a package manager. Pure: no I/O, no PATH probe.
+ */
+export function selfUpgradeCommand(manager: SelfUpgradeManager): Command {
+	return {
+		cmd: manager,
+		args: ["install", "-g", `${MAGUS_NPM_PACKAGE}@latest`],
+	};
+}
+
+/**
+ * The command that removes a duplicate global install, for the hint printed
+ * when magus is installed through both package managers. No leading
+ * indentation — the caller indents.
+ */
+export function duplicateInstallRemoval(manager: SelfUpgradeManager): string {
+	return `${manager} uninstall -g ${MAGUS_NPM_PACKAGE}`;
+}
 
 export async function runUpgradeCommand(): Promise<number> {
 	const { execSync } = await import("node:child_process");
 	const { existsSync } = await import("node:fs");
 
 	// Detect all installations of magus across package managers
-	const installations: Array<{ manager: "bun" | "npm"; path: string }> = [];
+	const installations: Array<{ manager: SelfUpgradeManager; path: string }> =
+		[];
 
 	// Check bun global
 	try {
@@ -60,7 +90,7 @@ export async function runUpgradeCommand(): Promise<number> {
 		}
 		console.log("\nTo fix, keep one and remove the other:");
 		for (const inst of installations) {
-			console.log(`  ${inst.manager} uninstall -g magus`);
+			console.log(`  ${duplicateInstallRemoval(inst.manager)}`);
 		}
 		console.log();
 	}
@@ -76,13 +106,11 @@ export async function runUpgradeCommand(): Promise<number> {
 		// If which fails, default to npm
 	}
 
-	const pkgManager = usesBun ? "bun" : "npm";
-	console.log(`Updating magus using ${pkgManager}...`);
-
-	const installArgs = ["install", "-g", "magus@latest"];
+	const { cmd, args } = selfUpgradeCommand(usesBun ? "bun" : "npm");
+	console.log(`Updating magus using ${cmd}...`);
 
 	return new Promise<number>((resolve) => {
-		const proc = spawn(pkgManager, installArgs, {
+		const proc = spawn(cmd, args, {
 			stdio: "inherit",
 			shell: false, // Avoid shell for security (fixes DEP0190 warning)
 		});

package/src/data/cli-tools.ts

@@ -1,4 +1,5 @@
 import type { BinInstaller } from "../types/index.js";
+import { MAGUS_NPM_PACKAGE } from "./npm-package.js";
 
 /**
  * A CLI tool magus can install, check and update.
@@ -38,7 +39,9 @@ export const cliTools: CliTool[] = [
 		website: "https://github.com/MadAppGang/magus/tree/main/tools/magus",
 		category: "ai-coding",
 		packageManager: "bun",
-		packageName: "magus",
+		// The npm package (`magus-cli`), not the command above: bare `magus` on
+		// npm is an unrelated package.
+		packageName: MAGUS_NPM_PACKAGE,
 	},
 	{
 		name: "mnemex",

package/src/data/npm-package.ts

@@ -0,0 +1,15 @@
+import pkg from "../../package.json";
+
+/**
+ * The npm package magus is published as. It is NOT the command.
+ *
+ * The command users type is `magus` (package.json `bin`). The npm package is
+ * `magus-cli`, because the bare `magus` name on npm belongs to an unrelated
+ * 2015 package, and npm never transfers names. Anything that talks to npm —
+ * the registry check, the self-upgrade, the CLI Tools row — must use this, and
+ * `git grep MAGUS_NPM_PACKAGE` lists every such call site.
+ *
+ * Static import so it resolves inside a `bun build --compile` binary — a
+ * dynamic require("../../package.json") returns nothing usable there.
+ */
+export const MAGUS_NPM_PACKAGE: string = (pkg as { name: string }).name;

package/src/services/version-check.ts

@@ -1,5 +1,6 @@
 import semver from "semver";
 import pkg from "../../package.json";
+import { MAGUS_NPM_PACKAGE } from "../data/npm-package.js";
 
 // Cache the result for the session
 let cachedResult: VersionCheckResult | null = null;
@@ -29,15 +30,20 @@ async function fetchLatestVersion(): Promise<string | null> {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), 3000); // 3s timeout
 
-		const response = await fetch("https://registry.npmjs.org/magus/latest", {
-			signal: controller.signal,
-			headers: {
-				Accept: "application/json",
-				// Always revalidate — a CDN/HTTP-cached response serves a stale
-				// "latest" right after a release (the 4.25-vs-4.26 flicker).
-				"Cache-Control": "no-cache",
+		// The npm package, not the command: bare `magus` on npm is an unrelated
+		// package whose latest is 0.0.2, which hid every release from this check.
+		const response = await fetch(
+			`https://registry.npmjs.org/${MAGUS_NPM_PACKAGE}/latest`,
+			{
+				signal: controller.signal,
+				headers: {
+					Accept: "application/json",
+					// Always revalidate — a CDN/HTTP-cached response serves a stale
+					// "latest" right after a release (the 4.25-vs-4.26 flicker).
+					"Cache-Control": "no-cache",
+				},
 			},
-		});
+		);
 
 		clearTimeout(timeout);
 
@@ -117,11 +123,15 @@ export async function checkForUpdates(
 }
 
 /**
- * Format update message for display
+ * Format update message for display.
+ *
+ * Points at `magus upgrade`, which picks bun or npm from the active binary. A
+ * hard-coded `npm i -g …` would give every bun user a second, npm-owned copy —
+ * the duplicate state `magus upgrade` itself warns about.
  */
 export function formatUpdateMessage(result: VersionCheckResult): string {
 	if (!result.updateAvailable) return "";
 
 	const typeLabel = result.updateType ? ` (${result.updateType})` : "";
-	return `Update available: v${result.currentVersion} → v${result.latestVersion}${typeLabel}. Run: npm i -g magus-cli`;
+	return `Update available: v${result.currentVersion} → v${result.latestVersion}${typeLabel}. Run: magus upgrade`;
 }