magus-cli 7.3.0 → 7.4.0

package/src/services/claude-settings.ts

@@ -28,6 +28,18 @@ import {
 	pickLoadedEntry,
 	repoRootForPath,
 } from "./plugin-resolution.js";
+import {
+	readSettingsFile,
+	writableList,
+	writableMap,
+} from "./settings-file.js";
+
+/**
+ * What every reader below throws for a file that exists but does not parse.
+ * Defined beside `readSettingsFile`, which all four readers delegate to, and
+ * re-exported here because this is the module callers read settings through.
+ */
+export { SettingsParseError } from "./settings-file.js";
 
 const CLAUDE_DIR = ".claude";
 const SETTINGS_FILE = "settings.json";
@@ -44,8 +56,17 @@ export function getClaudeDir(projectPath?: string): string {
 	return path.join(base, CLAUDE_DIR);
 }
 
+/**
+ * `~/.claude`, resolved per call.
+ *
+ * `HOME` first, then `os.homedir()` — Node's own rule for `os.homedir()`, done
+ * by hand because Bun does not follow it: under Bun 1.4 `os.homedir()` answers
+ * the home the process started with and ignores a later `process.env.HOME`
+ * (measured; Node follows the change). Reading `HOME` at call time is what lets
+ * a caller — a test above all — point the global settings somewhere else.
+ */
 export function getGlobalClaudeDir(): string {
-	return path.join(os.homedir(), CLAUDE_DIR);
+	return path.join(process.env.HOME || os.homedir(), CLAUDE_DIR);
 }
 
 export async function ensureClaudeDir(projectPath?: string): Promise<string> {
@@ -54,18 +75,45 @@ export async function ensureClaudeDir(projectPath?: string): Promise<string> {
 	return claudeDir;
 }
 
+/*
+ * THE FOUR READERS: a missing file reads as `{}`; a file that exists but does
+ * not parse throws `SettingsParseError`, never `{}`.
+ *
+ * They used to swallow every error and answer `{}`. Each has a writer beside
+ * it, and every read-modify-write in magus is `read → change one key →
+ * write`, so a settings file a human was mid-edit in came back as `{}` plus
+ * one key — and was written over, taking the rest of the configuration with
+ * it. Throwing from the read is what makes every one of those callers refuse:
+ * nothing reaches the write, so the file stays byte-for-byte as it was.
+ */
+
+/*
+ * Each file's path has one getter, used by its reader AND by every writer that
+ * checks a map before writing into it (`writableMap`), so a refusal names the
+ * file that was actually read.
+ */
+
+/** <project>/.claude/settings.json */
+export function getSettingsPath(projectPath?: string): string {
+	return path.join(getClaudeDir(projectPath), SETTINGS_FILE);
+}
+
+/** <project>/.claude/settings.local.json */
+export function getLocalSettingsPath(projectPath?: string): string {
+	return path.join(getClaudeDir(projectPath), LOCAL_SETTINGS_FILE);
+}
+
+/** ~/.claude/settings.json */
+export function getGlobalSettingsPath(): string {
+	return path.join(getGlobalClaudeDir(), SETTINGS_FILE);
+}
+
 export async function readSettings(
 	projectPath?: string,
 ): Promise<ClaudeSettings> {
-	const settingsPath = path.join(getClaudeDir(projectPath), SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(settingsPath)) {
-			return await fs.readJson(settingsPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getSettingsPath(projectPath),
+	)) as ClaudeSettings;
 }
 
 export async function writeSettings(
@@ -80,15 +128,9 @@ export async function writeSettings(
 export async function readLocalSettings(
 	projectPath?: string,
 ): Promise<ClaudeLocalSettings> {
-	const localPath = path.join(getClaudeDir(projectPath), LOCAL_SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(localPath)) {
-			return await fs.readJson(localPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getLocalSettingsPath(projectPath),
+	)) as ClaudeLocalSettings;
 }
 
 export async function writeLocalSettings(
@@ -109,15 +151,9 @@ export function getMcpConfigPath(projectPath?: string): string {
 export async function readMcpConfig(
 	projectPath?: string,
 ): Promise<McpConfigFile> {
-	const mcpPath = getMcpConfigPath(projectPath);
-	try {
-		if (await fs.pathExists(mcpPath)) {
-			return await fs.readJson(mcpPath);
-		}
-	} catch {
-		// Return empty config on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getMcpConfigPath(projectPath),
+	)) as McpConfigFile;
 }
 
 export async function writeMcpConfig(
@@ -129,15 +165,7 @@ export async function writeMcpConfig(
 }
 
 export async function readGlobalSettings(): Promise<ClaudeSettings> {
-	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(settingsPath)) {
-			return await fs.readJson(settingsPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(getGlobalSettingsPath())) as ClaudeSettings;
 }
 
 export async function writeGlobalSettings(
@@ -160,15 +188,27 @@ export async function addMcpServer(
 	// biome-ignore lint/performance/noDelete: this object is serialised into .mcp.json; the env key must be absent, not present as undefined
 	delete configWithoutEnv.env;
 
-	// Add to .mcp.json (without env vars)
+	// Read BOTH files, and check every map written into, before writing either:
+	// if one does not parse or has the wrong shape, the whole operation refuses,
+	// rather than leaving .mcp.json changed and the local settings not.
 	const mcpConfig = await readMcpConfig(projectPath);
-	mcpConfig.mcpServers = mcpConfig.mcpServers || {};
-	mcpConfig.mcpServers[name] = configWithoutEnv;
+	const localSettings = await readLocalSettings(projectPath);
+	const localPath = getLocalSettingsPath(projectPath);
+	const mcpServers =
+		writableMap(mcpConfig, "mcpServers", getMcpConfigPath(projectPath)) ?? {};
+	const enabledServers =
+		writableList(localSettings, "enabledMcpjsonServers", localPath) ?? [];
+	const env =
+		Object.keys(envVars).length > 0
+			? (writableMap(localSettings, "env", localPath) ?? {})
+			: undefined;
+
+	// Add to .mcp.json (without env vars)
+	mcpConfig.mcpServers = mcpServers;
+	mcpServers[name] = configWithoutEnv;
 	await writeMcpConfig(mcpConfig, projectPath);
 
 	// Enable in settings.local.json and add env vars
-	const localSettings = await readLocalSettings(projectPath);
-	const enabledServers = localSettings.enabledMcpjsonServers || [];
 	if (!enabledServers.includes(name)) {
 		enabledServers.push(name);
 	}
@@ -176,12 +216,12 @@ export async function addMcpServer(
 	localSettings.enableAllProjectMcpServers = true;
 
 	// Add env vars to settings.local.json
-	if (Object.keys(envVars).length > 0) {
-		localSettings.env = localSettings.env || {};
+	if (env) {
+		localSettings.env = env;
 		for (const [key, value] of Object.entries(envVars)) {
 			// Only add non-reference values (references like ${VAR} don't need to be stored)
 			if (!value.startsWith("${") || !value.endsWith("}")) {
-				localSettings.env[key] = value;
+				env[key] = value;
 			}
 		}
 	}
@@ -193,18 +233,32 @@ export async function removeMcpServer(
 	name: string,
 	projectPath?: string,
 ): Promise<void> {
-	// Remove from .mcp.json
+	// Both reads and both shape checks first, for the same reason as in
+	// addMcpServer.
 	const mcpConfig = await readMcpConfig(projectPath);
-	if (mcpConfig.mcpServers) {
-		delete mcpConfig.mcpServers[name];
+	const localSettings = await readLocalSettings(projectPath);
+	const mcpServers = writableMap(
+		mcpConfig,
+		"mcpServers",
+		getMcpConfigPath(projectPath),
+	);
+	const enabledServers = writableList(
+		localSettings,
+		"enabledMcpjsonServers",
+		getLocalSettingsPath(projectPath),
+	);
+
+	// Remove from .mcp.json
+	if (mcpServers) {
+		delete mcpServers[name];
 	}
 	await writeMcpConfig(mcpConfig, projectPath);
 
 	// Remove from settings.local.json
-	const localSettings = await readLocalSettings(projectPath);
-	if (localSettings.enabledMcpjsonServers) {
-		localSettings.enabledMcpjsonServers =
-			localSettings.enabledMcpjsonServers.filter((s) => s !== name);
+	if (enabledServers) {
+		localSettings.enabledMcpjsonServers = enabledServers.filter(
+			(s) => s !== name,
+		);
 		await writeLocalSettings(localSettings, projectPath);
 	}
 }
@@ -242,12 +296,11 @@ export async function enablePlugin(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readSettings(projectPath);
-	settings.enabledPlugins = settings.enabledPlugins || {};
-	if (enabled) {
-		settings.enabledPlugins[pluginId] = true;
-	} else {
-		delete settings.enabledPlugins[pluginId];
-	}
+	settings.enabledPlugins =
+		writableMap(settings, "enabledPlugins", getSettingsPath(projectPath)) ?? {};
+	// `false`, never a deleted key: Claude Code resolves enabledPlugins per id with
+	// fall-through, so a missing project entry lets a user-scope `true` win.
+	settings.enabledPlugins[pluginId] = enabled;
 	await writeSettings(settings, projectPath);
 }
 
@@ -398,7 +451,12 @@ export async function enableLocalPlugin(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	settings.enabledPlugins = settings.enabledPlugins || {};
+	settings.enabledPlugins =
+		writableMap(
+			settings,
+			"enabledPlugins",
+			getLocalSettingsPath(projectPath),
+		) ?? {};
 	if (enabled) {
 		settings.enabledPlugins[pluginId] = true;
 	} else {
@@ -413,7 +471,12 @@ export async function saveLocalInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions =
+		writableMap(
+			settings,
+			"installedPluginVersions",
+			getLocalSettingsPath(projectPath),
+		) ?? {};
 	settings.installedPluginVersions[pluginId] = version;
 	await writeLocalSettings(settings, projectPath);
 
@@ -431,11 +494,14 @@ export async function removeLocalInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	if (settings.installedPluginVersions) {
-		delete settings.installedPluginVersions[pluginId];
+	const localPath = getLocalSettingsPath(projectPath);
+	const versions = writableMap(settings, "installedPluginVersions", localPath);
+	const enabled = writableMap(settings, "enabledPlugins", localPath);
+	if (versions) {
+		delete versions[pluginId];
 	}
-	if (settings.enabledPlugins) {
-		delete settings.enabledPlugins[pluginId];
+	if (enabled) {
+		delete enabled[pluginId];
 	}
 	await writeLocalSettings(settings, projectPath);
 
@@ -556,7 +622,8 @@ export async function setMcpEnvVar(
 	projectPath?: string,
 ): Promise<void> {
 	const localSettings = await readLocalSettings(projectPath);
-	localSettings.env = localSettings.env || {};
+	localSettings.env =
+		writableMap(localSettings, "env", getLocalSettingsPath(projectPath)) ?? {};
 	localSettings.env[name] = value;
 	await writeLocalSettings(localSettings, projectPath);
 }
@@ -567,8 +634,13 @@ export async function removeMcpEnvVar(
 	projectPath?: string,
 ): Promise<void> {
 	const localSettings = await readLocalSettings(projectPath);
-	if (localSettings.env) {
-		delete localSettings.env[name];
+	const env = writableMap(
+		localSettings,
+		"env",
+		getLocalSettingsPath(projectPath),
+	);
+	if (env) {
+		delete env[name];
 		await writeLocalSettings(localSettings, projectPath);
 	}
 }
@@ -652,7 +724,8 @@ export async function enableGlobalPlugin(
 	enabled: boolean,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	settings.enabledPlugins = settings.enabledPlugins || {};
+	settings.enabledPlugins =
+		writableMap(settings, "enabledPlugins", getGlobalSettingsPath()) ?? {};
 	if (enabled) {
 		settings.enabledPlugins[pluginId] = true;
 	} else {
@@ -683,7 +756,9 @@ export async function saveGlobalInstalledPluginVersion(
 	version: string,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions =
+		writableMap(settings, "installedPluginVersions", getGlobalSettingsPath()) ??
+		{};
 	settings.installedPluginVersions[pluginId] = version;
 	await writeGlobalSettings(settings);
 
@@ -695,11 +770,14 @@ export async function removeGlobalInstalledPluginVersion(
 	pluginId: string,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	if (settings.installedPluginVersions) {
-		delete settings.installedPluginVersions[pluginId];
+	const globalPath = getGlobalSettingsPath();
+	const versions = writableMap(settings, "installedPluginVersions", globalPath);
+	const enabled = writableMap(settings, "enabledPlugins", globalPath);
+	if (versions) {
+		delete versions[pluginId];
 	}
-	if (settings.enabledPlugins) {
-		delete settings.enabledPlugins[pluginId];
+	if (enabled) {
+		delete enabled[pluginId];
 	}
 	await writeGlobalSettings(settings);
 

package/src/services/cli-tool-commands.ts

@@ -37,8 +37,10 @@ import {
  * to follow what is actually on the machine, or it installs a second copy
  * beside the first and the screen then reports a conflict it created itself.
  *
- * `pnpm`, `yarn` and `unknown` have no `BinInstaller` counterpart, which is why
- * the two unions stay separate rather than one being widened into the other.
+ * `pnpm`, `yarn`, `native` and `unknown` have no `BinInstaller` counterpart,
+ * which is why the two unions stay separate rather than one being widened into
+ * the other. `native` is a tool's own installer — today Claude Code's, which
+ * keeps its releases under `~/.local/share/claude/versions/` and updates itself.
  */
 export type InstallMethod =
 	| "npm"
@@ -47,6 +49,7 @@ export type InstallMethod =
 	| "yarn"
 	| "brew"
 	| "pip"
+	| "native"
 	| "unknown";
 
 /**
@@ -75,6 +78,10 @@ export function cliToolInstall(tool: CliTool): Command {
  * the detector could not attribute the binary on PATH to any package manager,
  * and guessing there would install a second copy alongside the one already
  * there. Callers fall back to installing.
+ *
+ * `native` is null too: a tool's own updater is not derivable from the method
+ * name. The probe builds it (`ToolFacts.upgradeCommand`, e.g. `claude update`)
+ * and the row takes it from there, ahead of this function.
  */
 export function cliToolUpdate(
 	tool: CliTool,
@@ -82,12 +89,13 @@ export function cliToolUpdate(
 	brewFormula?: string,
 ): Command | null {
 	switch (method) {
-		// The three the resolver does not model. `pnpm`/`yarn` are not
+		// The ones the resolver does not model. `pnpm`/`yarn` are not
 		// BinInstallers because magus never chooses them — it only finds them.
 		case "pnpm":
 			return { cmd: "pnpm", args: ["install", "-g", tool.packageName] };
 		case "yarn":
 			return { cmd: "yarn", args: ["global", "add", tool.packageName] };
+		case "native":
 		case "unknown":
 			return null;
 		default:
@@ -107,8 +115,9 @@ export function cliToolUpdate(
 /**
  * Remove a tool, following the method it was actually installed with.
  *
- * Null means "no command to offer": `unknown` for the reason above, and `go`
- * because a `go install` binary has no uninstaller to call.
+ * Null means "no command to offer": `unknown` for the reason above, `native`
+ * because a self-installed tool ships no uninstall command, and `go` because a
+ * `go install` binary has no uninstaller to call.
  */
 export function cliToolUninstall(
 	tool: CliTool,
@@ -120,6 +129,7 @@ export function cliToolUninstall(
 			return { cmd: "pnpm", args: ["remove", "-g", tool.packageName] };
 		case "yarn":
 			return { cmd: "yarn", args: ["global", "remove", tool.packageName] };
+		case "native":
 		case "unknown":
 			return null;
 		default:

package/src/services/cli-tool-version.ts

@@ -0,0 +1,101 @@
+import { readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * The version of the npm/bun package a binary on PATH belongs to.
+ *
+ * A global install leaves `<prefix>/bin/<tool>` as a symlink into
+ * `<prefix>/lib/node_modules/<package>/…` (npm) or
+ * `~/.bun/install/global/node_modules/<package>/…` (bun). The package's own
+ * `package.json` is therefore the authority on what is installed, and reading
+ * it needs neither an installer record nor running the tool.
+ *
+ * The walk starts from the binary's REAL location — the symlink is resolved
+ * first, chain and all — because the directory the symlink sits in can belong
+ * to some unrelated project whose `package.json` would answer wrongly. The
+ * nearest `package.json` carrying both `name` and `version` wins; the partial
+ * ones a build leaves in `dist/` (`{"type":"module"}`) are skipped.
+ *
+ * Never throws: a missing binary, a dangling link, an unreadable or unparseable
+ * manifest, and "no package at all" are all `null`.
+ */
+export function readPackageVersionForBin(binPath: string): string | null {
+	let real: string;
+	try {
+		real = realpathSync(binPath);
+	} catch {
+		return null;
+	}
+
+	let dir = path.dirname(real);
+	for (;;) {
+		const version = qualifyingVersion(path.join(dir, "package.json"));
+		if (version !== undefined) return version;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** A bare release number, as a versioned install directory names its files. */
+const RELEASE = /^v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+/**
+ * The version a VERSIONED INSTALL names its binary by, or `null`.
+ *
+ * Some installers keep every release side by side and point PATH at one:
+ * Claude Code's native installer links `~/.local/bin/claude` to
+ * `~/.local/share/claude/versions/2.1.276`. There is no package.json there to
+ * read, but the file's own name IS the version — accepted only when the real
+ * path's parent directory is literally `versions` and the name is a bare
+ * release number, so an ordinary binary called `1.0.0` is not misread.
+ *
+ * Reads no file and runs nothing; never throws.
+ */
+export function readVersionDirForBin(binPath: string): string | null {
+	let real: string;
+	try {
+		real = realpathSync(binPath);
+	} catch {
+		return null;
+	}
+	return versionFromVersionedPath(real);
+}
+
+/**
+ * The same reading as {@link readVersionDirForBin}, from a path that is ALREADY
+ * real — pure string work, no filesystem. The probe resolves paths through its
+ * own IO seam and must not reach past it to the real disk.
+ */
+export function versionFromVersionedPath(realPath: string): string | null {
+	const name = path.basename(realPath);
+	if (path.basename(path.dirname(realPath)) !== "versions") return null;
+	return RELEASE.test(name) ? name.replace(/^v/, "") : null;
+}
+
+/**
+ * The manifest's version when it names both a package and a version.
+ *
+ * `undefined` means "not a package root, keep walking"; `null` means "this is
+ * the package root, and it cannot be read" — the walk stops there rather than
+ * letting an enclosing workspace answer for a package it does not own.
+ */
+function qualifyingVersion(file: string): string | null | undefined {
+	let text: string;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return undefined;
+	}
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (manifest === null || typeof manifest !== "object") return undefined;
+	const { name, version } = manifest as Record<string, unknown>;
+	if (typeof name !== "string" || name === "") return undefined;
+	if (typeof version !== "string" || version === "") return undefined;
+	return version;
+}

package/src/services/hook-registration.ts

@@ -18,16 +18,21 @@
  *     absolute path recorded today is a dead path after the next upgrade, and
  *     the failure is invisible (a hook that cannot start is a hook that
  *     silently does not route).
- *  3. **User scope, through `updateSettingsFile`.** NOT
- *     `readGlobalSettings`/`writeGlobalSettings`: those swallow a parse error
- *     and return `{}`, so a settings file a human is mid-edit in would be
- *     overwritten with one hook and nothing else. `updateSettingsFile` refuses
- *     a file it cannot parse.
+ *  3. **User scope, through `updateSettingsFile`.** It refuses a file it
+ *     cannot parse, so a settings file a human is mid-edit in is never
+ *     overwritten with one hook and nothing else. The path is the resolved
+ *     Claude config dir (`CLAUDE_CONFIG_DIR`), which
+ *     `readGlobalSettings`/`writeGlobalSettings` (always `~/.claude`) ignore.
  */
 
 import path from "node:path";
 import { claudeConfigDirOrNull } from "../utils/config-dir.js";
-import { readSettingsFile, updateSettingsFile } from "./settings-file.js";
+import {
+	readSettingsFile,
+	updateSettingsFile,
+	writableList,
+	writableMap,
+} from "./settings-file.js";
 
 /** The command Claude Code runs. Bare — see rule 2 above. */
 export const AGENT_MODEL_HOOK_COMMAND = "magus hook agent-model";
@@ -196,6 +201,18 @@ export async function registerAgentModelHook(
 	if (isHookRegistered(await readSettingsFile(settingsPath))) return "already";
 
 	await updateSettingsFile(settingsPath, (settings) => {
+		// The user's own hooks live in `hooks.PreToolUse`. A malformed one is
+		// refused here, never replaced: `ensureHookRegistered` alone swaps a
+		// non-object `hooks` or a non-array `PreToolUse` for an empty one, and this
+		// write would then drop everything that was in it.
+		const hooks = writableMap(settings, "hooks", settingsPath);
+		if (hooks) {
+			writableList(
+				hooks as Record<string, unknown>,
+				"PreToolUse",
+				settingsPath,
+			);
+		}
 		return ensureHookRegistered(settings).settings;
 	});
 	return "registered";