magus-cli 7.3.1 → 7.4.0

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/data/cli-tools.ts

@@ -29,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",
@@ -72,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",