magus-cli 7.3.0 → 7.4.0

package/src/__tests__/uppercase-keybindings.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { parseKeypress } from "@opentui/core";
 import fs from "fs-extra";
+import type { KeyPress } from "../ui/input/key-dispatch.js";
+import { SCREEN_BINDINGS, matchBinding } from "../ui/keymap.js";
 
 /**
  * A shifted key never arrives as an uppercase `name`.
@@ -81,21 +83,32 @@ describe("no binding compares name to an uppercase letter", () => {
 		expect(offenders).toEqual([]);
 	});
 
-	test("an uppercase binding is reachable only via the shift flag", async () => {
+	test("an uppercase binding is reachable only via the shift flag", () => {
 		// The positive half: Shift+U must actually route to update. Asserting only
 		// the absence of `=== "U"` would also pass if someone deleted the binding.
-		const src = await fs.readFile(
-			path.join(UI_DIR, "screens", "PluginsScreen.tsx"),
-			"utf8",
+		// Keys are matched through the keymap now, so the check is on what a
+		// parsed keypress resolves to — and plain `u` must NOT resolve to update,
+		// which is the original bug the other way round.
+		const press = (raw: string): KeyPress => {
+			const k = parseKeypress(raw);
+			return {
+				name: k?.name ?? "",
+				sequence: k?.sequence ?? "",
+				ctrl: k?.ctrl === true,
+				meta: k?.meta === true,
+				shift: k?.shift === true,
+			};
+		};
+		expect(matchBinding(SCREEN_BINDINGS.plugins, press("U"))?.id).toBe(
+			"update",
 		);
-		const update = src.indexOf('event.name === "u" && event.shift');
-		const userScope = src.indexOf(
-			'event.name === "u") handleScopeToggle("user")',
+		expect(matchBinding(SCREEN_BINDINGS.plugins, press("u"))?.id).toBe("scope");
+		// The registry's refresh, the one that silently did nothing.
+		expect(matchBinding(SCREEN_BINDINGS["mcp-registry"], press("R"))?.id).toBe(
+			"reload",
 		);
-		expect(update).toBeGreaterThan(-1);
-		expect(userScope).toBeGreaterThan(-1);
-		// Order matters: the shifted branch has to be tested first, or the plain
-		// "u" branch swallows it again — which is exactly the original bug.
-		expect(update).toBeLessThan(userScope);
+		expect(
+			matchBinding(SCREEN_BINDINGS["mcp-registry"], press("r"))?.id,
+		).toBeUndefined();
 	});
 });

package/src/cli/ansi.ts

@@ -346,12 +346,12 @@ export function truncate(text: string, n: number): string {
 export const ramps = {
 	/**
 	 * Work in progress to done. Purple is magus's brand, green is "settled",
-	 * and the blue midtone is the chosen control point that stops a two-hue
+	 * and the teal midtone is the chosen control point that stops a two-hue
 	 * blend desaturating into grey at the halfway mark.
 	 */
 	progress: [
 		lighten(brand.accent, 0.15),
-		lighten(brand.link, 0.2),
+		lighten(brand.info, 0.2),
 		lighten(brand.success, 0.25),
 	],
 	/**

package/src/cli/bootstrap.ts

@@ -31,12 +31,28 @@ import {
 	needsNothing,
 	parseProfileChoice,
 } from "../services/profile-startup.js";
+import { SettingsParseError } from "../services/settings-file.js";
 import type { ProfileManifest } from "../types/index.js";
 import { dim } from "./ansi.js";
 import { confirm } from "./prompt.js";
 import { selectDialog } from "./tui-prompt.js";
 import { fail as failLine, note as noteLine } from "./update-view.js";
 
+/**
+ * Report a file that exists and cannot be used — it does not parse, or parses
+ * into the wrong shape — and that magus left it alone.
+ *
+ * One wording for every command that meets one — the message names the file
+ * and says what is wrong with it; the note says what the user has to do, since
+ * magus will not do it for them.
+ */
+export function reportUnparseable(error: SettingsParseError): void {
+	console.error(failLine(error.message));
+	console.error(
+		noteLine("Fix the JSON by hand; magus leaves the file as it is."),
+	);
+}
+
 /**
  * Write the adopted manifest, then put the project ON the profile it describes.
  *
@@ -147,13 +163,22 @@ export interface EnsureManifestOptions {
  * Return the project's manifest, creating one by adoption if it has none.
  *
  * Resolves to null when there is no manifest and none was created — the caller
- * should exit non-zero. Anything it prints has already explained why.
+ * should exit non-zero. Anything it prints has already explained why. A
+ * manifest that exists and does not parse is one of those: it is reported, and
+ * never read as "none" — adoption below would write a new one over it.
  */
 export async function ensureManifest(
 	projectPath: string,
 	opts: EnsureManifestOptions = {},
 ): Promise<ProfileManifest | null> {
-	const manifest = await readManifest(projectPath);
+	let manifest: ProfileManifest;
+	try {
+		manifest = await readManifest(projectPath);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable(error);
+		return null;
+	}
 	if (Object.keys(manifest.profiles).length > 0) return manifest;
 
 	const result = await adoptCurrentProject(projectPath);
@@ -226,6 +251,12 @@ export async function requireActiveProfile(
 	const need = await detectProfileStartupNeed(projectPath);
 	if (needsNothing(need)) return manifest;
 
+	// Nothing to ask: every option would read or write a file that does not parse.
+	if (need.parseError) {
+		reportUnparseable(need.parseError);
+		return null;
+	}
+
 	// The repo declares which profile it wants and there is nothing of the
 	// user's to replace — a fresh clone. Activate it and carry on, even under
 	// `--check` and with no TTY: this is the committed answer being applied, not

package/src/cli/doctor.ts

@@ -2,18 +2,27 @@
  * `magus doctor [--fix]`
  *
  * Diagnoses (and with --fix, repairs) project health:
+ *   0. Global settings — `~/.claude/settings.json` parses.
  *   1. Binary dependencies — every requires.bin / cliTools binary on PATH.
  *      This is the check that would have caught a dead `tmux-mcp`.
  *   2. Profile symlink integrity — the active profile's links resolve.
  *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
  *   4. Model routing — config validity, hook registration, and drift.
  *   5. Plugin loads — what Claude Code will load here vs what is installed.
+ *
+ * A file that exists and does not parse — the global settings, the project's
+ * `.claude/profiles.json` or its `.claude/settings.json` — is a finding in the
+ * section that meets it, never an abort: the rest of the report is still worth
+ * having. `--fix` repairs none of them, because magus never rewrites a file it
+ * cannot parse.
  */
 
 import path from "node:path";
 import fs from "fs-extra";
 import {
+	SettingsParseError,
 	getProjectInstalledPluginVersions,
+	readGlobalSettings,
 	readInstalledPluginsRegistry,
 	readSettings,
 } from "../services/claude-settings.js";
@@ -35,17 +44,35 @@ import {
 } from "../services/plugin-resolution.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
+import type { ClaudeSettings, ProfileManifest } from "../types/index.js";
 import { resolveExecutable } from "../utils/command-utils.js";
 
 export async function runDoctorCommand(args: string[]): Promise<number> {
 	const fix = args.includes("--fix");
 	const projectPath = process.cwd();
 	let problems = 0;
+	// Findings `--fix` does not repair, counted apart so it cannot silence
+	// them — see doctorExitCode.
+	let unfixable = 0;
+
+	// 0. Global settings. Its own check, first, because most of doctor never
+	// reads that file: a project without model routing reached it nowhere and
+	// reported "No problems found" over a damaged one, while the one section
+	// that did — hook registration under --fix — aborted the whole run on it.
+	const globalSettingsError = await checkGlobalSettings();
+	if (globalSettingsError) unfixable++;
 
-	// 1. Binary dependencies.
-	const manifest = await readManifest(projectPath);
+	// 1. Binary dependencies, which needs the manifest to know what to check.
+	let manifest: ProfileManifest | null = null;
+	try {
+		manifest = await readManifest(projectPath);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Profiles", error);
+		unfixable++;
+	}
 	let pluginIds: string[] = [];
-	if (Object.keys(manifest.profiles).length > 0) {
+	if (manifest && Object.keys(manifest.profiles).length > 0) {
 		const closure = await resolveAllProfiles(manifest);
 		pluginIds = Object.keys(closure.plugins);
 		if (closure.bins.length > 0) {
@@ -120,14 +147,43 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	}
 
 	// 4. Model routing.
-	problems += await checkModels(projectPath, fix);
+	const models = await checkModels(projectPath, fix, globalSettingsError);
+	problems += models.fixable;
+	unfixable += models.unfixable;
 
 	// 5. Stale plugin loads. Counted SEPARATELY, because `--fix` does not repair
 	// them — see doctorExitCode.
-	const staleLoads = await checkPluginLoads(projectPath);
+	unfixable += await checkPluginLoads(projectPath);
+
+	if (problems === 0 && unfixable === 0) console.log("\n✓ No problems found.");
+	return doctorExitCode({ fixable: problems, unfixable, fix });
+}
 
-	if (problems === 0 && staleLoads === 0) console.log("\n✓ No problems found.");
-	return doctorExitCode({ fixable: problems, unfixable: staleLoads, fix });
+/**
+ * A file that exists and does not parse, as a finding under `heading`.
+ *
+ * The same three lines wherever one turns up, so a damaged file reads the same
+ * whichever section met it.
+ */
+function reportUnparseable(heading: string, error: SettingsParseError): void {
+	console.log(`\n${heading}:`);
+	console.log(`  ✗ ${error.message}`);
+	console.log("    Fix the JSON by hand; magus leaves the file as it is.");
+}
+
+/**
+ * The global settings file, if it does not parse — reported, and returned so
+ * the hook check can say why it cannot answer instead of guessing.
+ */
+async function checkGlobalSettings(): Promise<SettingsParseError | null> {
+	try {
+		await readGlobalSettings();
+		return null;
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Global settings", error);
+		return error;
+	}
 }
 
 /**
@@ -177,7 +233,14 @@ export function doctorExitCode(args: {
  */
 async function checkPluginLoads(projectPath: string): Promise<number> {
 	const registry = await readInstalledPluginsRegistry();
-	const settings = await readSettings(projectPath);
+	let settings: ClaudeSettings;
+	try {
+		settings = await readSettings(projectPath);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Plugin loads", error);
+		return 1;
+	}
 	const installed = await getProjectInstalledPluginVersions(
 		settings.installedPluginVersions || {},
 		projectPath,
@@ -249,13 +312,24 @@ async function checkPluginLoads(projectPath: string): Promise<number> {
  * fixed from here (the values are a human's decision); an unregistered hook
  * routes nothing no matter how good the config is; drift only matters once
  * both of those are sound.
+ *
+ * `fixable` is what `--fix` can act on; `unfixable` is what it cannot, which
+ * is a hook whose settings file does not parse.
  */
-async function checkModels(projectPath: string, fix: boolean): Promise<number> {
+async function checkModels(
+	projectPath: string,
+	fix: boolean,
+	/** From `checkGlobalSettings`: the global settings file does not parse. */
+	globalSettingsError: SettingsParseError | null,
+): Promise<{ fixable: number; unfixable: number }> {
 	const { config, errors, path: file } = await readModelsConfig(projectPath);
-	if (config === null && errors.length === 0) return 0;
+	if (config === null && errors.length === 0) {
+		return { fixable: 0, unfixable: 0 };
+	}
 
 	console.log("\nModel routing:");
 	let problems = 0;
+	let unfixable = 0;
 
 	if (errors.length > 0) {
 		console.log(`  ✗ ${file} is invalid — nothing is routed:`);
@@ -268,15 +342,32 @@ async function checkModels(projectPath: string, fix: boolean): Promise<number> {
 		console.log("    re-run `magus models use <preset>`) and check again.");
 		// An invalid config is worth exactly one problem, not one per message —
 		// the count drives the exit code, not the severity.
-		return 1;
+		return { fixable: 1, unfixable: 0 };
 	}
 
 	// The hook is what applies the routing. Without it the config is inert.
 	if (await isAgentModelHookRegistered()) {
 		console.log("  ✓ agent-model hook registered at user scope.");
 	} else if (fix) {
-		await registerAgentModelHook();
-		console.log("  ✓ agent-model hook registered at user scope (fixed).");
+		try {
+			await registerAgentModelHook();
+			console.log("  ✓ agent-model hook registered at user scope (fixed).");
+		} catch (error) {
+			// Registering writes the settings file, and one that does not parse is
+			// never written. This used to escape and abort the whole run.
+			if (!(error instanceof SettingsParseError)) throw error;
+			console.log(
+				`  ✗ agent-model hook not registered: ${error.path} ${error.problem}, and magus does not write a file it cannot read.`,
+			);
+			unfixable++;
+		}
+	} else if (globalSettingsError) {
+		// `isAgentModelHookRegistered` reads an unparseable file as "not
+		// registered". Offering `--fix` for that would offer a write magus refuses.
+		console.log(
+			`  ✗ agent-model hook: cannot tell whether it is registered — the global settings file ${globalSettingsError.problem} (see above).`,
+		);
+		unfixable++;
 	} else {
 		console.log(
 			"  ✗ agent-model hook is not registered — the config is there, but nothing runs it.",
@@ -310,7 +401,7 @@ async function checkModels(projectPath: string, fix: boolean): Promise<number> {
 
 	for (const warning of status.warnings) console.log(`  ⚠ ${warning}`);
 
-	return problems;
+	return { fixable: problems, unfixable };
 }
 
 /** Which of the active profile's expected symlinks are missing or dangling. */

package/src/cli/install.ts

@@ -15,6 +15,7 @@
 import path from "node:path";
 import { installPlugin, isClaudeAvailable } from "../services/claude-cli.js";
 import {
+	getLocalSettingsPath,
 	readInstalledPluginsRegistry,
 	readLocalSettings,
 	writeLocalSettings,
@@ -31,6 +32,7 @@ import { reportDisplaced } from "../services/profile-activate.js";
 import { materializeProfile } from "../services/profile-materializer.js";
 import { detectProfileDrift } from "../services/profile-sync.js";
 import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
+import { writableMap } from "../services/settings-file.js";
 import { installSkill } from "../services/skills-manager.js";
 import {
 	PROFILE_GITIGNORE_ENTRIES,
@@ -229,10 +231,14 @@ async function collectEnv(
 	}
 
 	const local = await readLocalSettings(projectPath);
-	local.env = local.env ?? {};
+	// Checked before the first prompt, so a malformed `env` is refused before the
+	// user types anything, not after — and never replaced.
+	const env =
+		writableMap(local, "env", getLocalSettingsPath(projectPath)) ?? {};
+	local.env = env;
 	for (const name of status.missingRequired) {
 		const value = await promptValue(`  ${name} = `);
-		if (value) local.env[name] = value;
+		if (value) env[name] = value;
 	}
 	await writeLocalSettings(local, projectPath);
 	console.log("Saved to .claude/settings.local.json (personal, gitignored).");

package/src/cli/profile.ts

@@ -16,15 +16,32 @@ import { getManifestPath, readManifest } from "../services/manifest.js";
 import { reportDisplaced } from "../services/profile-activate.js";
 import { syncProfile } from "../services/profile-sync.js";
 import { resolveProfile } from "../services/resolver.js";
+import { SettingsParseError } from "../services/settings-file.js";
 import {
 	PROFILE_GITIGNORE_ENTRIES,
 	activateProfile,
 	activeProfile,
 	profileDir,
 } from "../services/symlink-manager.js";
-import { ensureManifest } from "./bootstrap.js";
+import { ensureManifest, reportUnparseable } from "./bootstrap.js";
 
+/**
+ * Every subcommand reads `.claude/profiles.json`, and one that does not parse
+ * is a report and exit 1 for all of them — named once here rather than guarded
+ * per subcommand. It never reads as "no profiles": `list` said exactly that,
+ * and `init` would then have written a new manifest over the file.
+ */
 export async function runProfileCommand(args: string[]): Promise<number> {
+	try {
+		return await dispatchProfileCommand(args);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable(error);
+		return 1;
+	}
+}
+
+async function dispatchProfileCommand(args: string[]): Promise<number> {
 	const [sub, ...rest] = args;
 	const projectPath = process.cwd();
 

package/src/cli/router.ts

@@ -7,8 +7,10 @@
  */
 
 import type { ThemeMode } from "@opentui/core";
+import { SettingsParseError } from "../services/settings-file.js";
 import { checkForUpdates } from "../services/version-check.js";
 import { type ThemeEnv, parseThemeWord } from "../ui/theme-resolve.js";
+import { reportUnparseable } from "./bootstrap.js";
 import { runDoctorCommand } from "./doctor.js";
 import { runInstallCommand } from "./install.js";
 import { runModelsCommand } from "./models.js";
@@ -171,24 +173,35 @@ export async function route(
 		setThemeMode(mode);
 	}
 
-	switch (command) {
-		case "update":
-			return HANDLED(await runUpdateCommand(rest));
-		case "upgrade":
-			return HANDLED(await runUpgradeCommand());
-		case "install":
-			return HANDLED(await runInstallCommand(rest));
-		case "profile":
-			return HANDLED(await runProfileCommand(rest));
-		case "models":
-			return HANDLED(await runModelsCommand(rest));
-		case "doctor":
-			return HANDLED(await runDoctorCommand(rest));
-		default:
-			// Bare `magus` or an unrecognized token → interactive TUI.
-			return themeFlag.theme === undefined
-				? LAUNCH_TUI
-				: { ...LAUNCH_TUI, theme: themeFlag.theme };
+	try {
+		switch (command) {
+			case "update":
+				return HANDLED(await runUpdateCommand(rest));
+			case "upgrade":
+				return HANDLED(await runUpgradeCommand());
+			case "install":
+				return HANDLED(await runInstallCommand(rest));
+			case "profile":
+				return HANDLED(await runProfileCommand(rest));
+			case "models":
+				return HANDLED(await runModelsCommand(rest));
+			case "doctor":
+				return HANDLED(await runDoctorCommand(rest));
+			default:
+				// Bare `magus` or an unrecognized token → interactive TUI.
+				return themeFlag.theme === undefined
+					? LAUNCH_TUI
+					: { ...LAUNCH_TUI, theme: themeFlag.theme };
+		}
+	} catch (error) {
+		// A settings or manifest file that does not parse is the user's to fix, not a
+		// crash. Every writer already refuses to touch it; this is the one place that
+		// turns the refusal into a message for commands with no handling of their own.
+		if (error instanceof SettingsParseError) {
+			reportUnparseable(error);
+			return HANDLED(1);
+		}
+		throw error;
 	}
 }
 

package/src/cli/update-view.ts

@@ -86,7 +86,7 @@ type ActionKey =
 
 const ACTIONS: Record<ActionKey, ActionStyle> = {
 	current: { glyph: "=", label: "CURRENT", color: brand.muted, chrome: true },
-	install: { glyph: "+", label: "INSTALL", color: brand.link },
+	install: { glyph: "+", label: "INSTALL", color: brand.info },
 	// Green, the tone magus uses for an update everywhere else. Amber stays
 	// on `unknown` below, so the two states remain distinguishable: green is
 	// "a newer version exists", amber is "we could not tell".

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.
@@ -28,6 +29,14 @@ export interface CliTool {
 	packageName: string;
 }
 
+/**
+ * Claude Code's npm package. Named once because two readers need it: the
+ * catalogue entry below, and the probe, which asks this package's `latest`
+ * dist-tag for a copy the native installer put on PATH — that copy has no
+ * package.json to say which package it is.
+ */
+export const CLAUDE_CODE_NPM_PACKAGE = "@anthropic-ai/claude-code";
+
 export const cliTools: CliTool[] = [
 	{
 		name: "magus",
@@ -38,7 +47,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",
@@ -69,7 +80,7 @@ export const cliTools: CliTool[] = [
 		website: "https://claude.ai/code",
 		category: "ai-coding",
 		packageManager: "npm",
-		packageName: "@anthropic-ai/claude-code",
+		packageName: CLAUDE_CODE_NPM_PACKAGE,
 	},
 	{
 		name: "codex",

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;