magus-cli 7.3.0 → 7.4.0

package/src/services/manifest.ts

@@ -11,13 +11,23 @@ import path from "node:path";
 import fs from "fs-extra";
 import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
 import { validateModelsConfig } from "./models-core.js";
+import {
+	SettingsShapeError,
+	describeJsonKind,
+	isJsonObject,
+	readSettingsFile,
+} from "./settings-file.js";
 
-const PROFILES_FILE = "profiles.json";
+/**
+ * The manifest's path relative to the project root, for messages that name the
+ * file without an absolute path — which wraps, and a wrapped path reads as two.
+ */
+export const MANIFEST_FILE = path.join(".claude", "profiles.json");
 
 /** Project-scoped manifest path: <projectPath|cwd>/.claude/profiles.json */
 export function getManifestPath(projectPath?: string): string {
 	const base = projectPath ?? process.cwd();
-	return path.join(base, ".claude", PROFILES_FILE);
+	return path.join(base, MANIFEST_FILE);
 }
 
 /** An empty, valid v2 manifest. */
@@ -26,65 +36,132 @@ export function emptyManifest(): ProfileManifest {
 }
 
 /**
- * Normalize any parsed profiles.json (v1 or v2) into a v2 manifest.
- * Unknown/missing shapes degrade to an empty manifest rather than throwing —
- * validation is the caller's job via {@link validateManifest}.
+ * A profiles file's contents once its shape has been checked: a JSON object
+ * whose `profiles` maps each id to an object. Only {@link readProfilesFile}
+ * produces one, so holding one means the check ran.
+ */
+export type ProfilesFile = Record<string, unknown> & {
+	profiles: Record<string, Record<string, unknown>>;
+};
+
+const NOT_A_PROFILES_FILE = "is not a valid profiles file";
+
+/**
+ * Read a profiles file — the project's `.claude/profiles.json` or the user's
+ * `~/.claude/profiles.json` — and check its shape.
+ *
+ * THE one shape check. `readManifest`, `readProfiles` and both writers all come
+ * through here, so the two views of the same file cannot disagree about
+ * whether it holds profiles. They used to: for `"profiles": 5` one read "none"
+ * and the other passed the 5 through.
+ *
+ * Missing, empty, `{}` and `{"version": 2}` read as no profiles. Everything
+ * else that is not a map of profile objects THROWS `SettingsShapeError` naming
+ * the file (a `SettingsParseError`, so every existing catch reports it):
+ *
+ *   - `profiles` present but not an object (`5`, `[]`, `null`);
+ *   - any entry under `profiles` that is not an object;
+ *   - `profiles` absent while the file holds any key besides `version`.
+ *
+ * The last is the one that bites. `{"version": 2, "profile": {…}}` — one
+ * letter off — read as "no profiles", which is the state in which magus offers
+ * to save what is turned on as the first profile, and saving writes this file.
+ * The real profile would have been replaced by a generated one.
  */
-export function migrateToV2(raw: unknown): ProfileManifest {
-	if (!raw || typeof raw !== "object") return emptyManifest();
-	const obj = raw as Record<string, unknown>;
+export async function readProfilesFile(
+	filePath: string,
+): Promise<ProfilesFile> {
+	const raw = await readSettingsFile(filePath);
+	const refuse = (detail: string): never => {
+		throw new SettingsShapeError(filePath, NOT_A_PROFILES_FILE, detail);
+	};
 
-	const profilesRaw =
-		obj.profiles && typeof obj.profiles === "object"
-			? (obj.profiles as Record<string, unknown>)
-			: {};
+	if (!("profiles" in raw)) {
+		const others = Object.keys(raw).filter((key) => key !== "version");
+		if (others.length > 0) {
+			refuse(
+				`it has no "profiles" key, but has ${others.map((key) => `"${key}"`).join(", ")}`,
+			);
+		}
+		return { ...raw, profiles: {} };
+	}
 
-	const profiles: Record<string, ProfileManifestEntry> = {};
-	for (const [id, entry] of Object.entries(profilesRaw)) {
-		if (entry && typeof entry === "object") {
-			// v1 and v2 entries are both accepted as-is; v1's plugins map
-			// (Record<string, boolean>) is valid under v2's widened type.
-			profiles[id] = entry as ProfileManifestEntry;
+	const { profiles } = raw;
+	if (!isJsonObject(profiles)) {
+		return refuse(`"profiles" is ${describeJsonKind(profiles)}, not an object`);
+	}
+	for (const [id, entry] of Object.entries(profiles)) {
+		if (!isJsonObject(entry)) {
+			refuse(`profile "${id}" is ${describeJsonKind(entry)}, not an object`);
 		}
 	}
+	return raw as ProfilesFile;
+}
 
-	const manifest: ProfileManifest = { version: 2, profiles };
+/**
+ * Normalize a checked profiles file (v1 or v2) into a v2 manifest.
+ *
+ * Takes a {@link ProfilesFile}, never raw JSON: deciding that a wrong shape is
+ * "empty" is how a damaged file got overwritten, so there is no garbage branch
+ * here to decide it. The shape check refuses first.
+ */
+export function migrateToV2(file: ProfilesFile): ProfileManifest {
+	// v1 and v2 entries are both accepted as-is; v1's plugins map
+	// (Record<string, boolean>) is valid under v2's widened type. What an entry
+	// holds is `validateManifest`'s to report, not this function's to drop.
+	const manifest: ProfileManifest = {
+		version: 2,
+		profiles: file.profiles as unknown as Record<string, ProfileManifestEntry>,
+	};
 	// Only carry strictVersions when enabled, so a committed manifest that
 	// doesn't opt in stays minimal (no spurious `"strictVersions": false`).
-	if (obj.strictVersions === true) manifest.strictVersions = true;
+	if (file.strictVersions === true) manifest.strictVersions = true;
 	// Carried through even when it names no existing profile: dropping it here
 	// would silently "fix" a typo that `validateManifest` is meant to report,
 	// and the commands that read it all check the id resolves first.
-	if (typeof obj.default === "string" && obj.default !== "") {
-		manifest.default = obj.default;
+	if (typeof file.default === "string" && file.default !== "") {
+		manifest.default = file.default;
 	}
 	return manifest;
 }
 
 /**
- * Read and migrate the project manifest. Returns an empty v2 manifest if the
- * file is absent or unreadable.
+ * Read and migrate the project manifest.
+ *
+ * A missing (or empty) file is an empty v2 manifest: a repo with no profiles.
+ * A file that exists and does not parse, or has the wrong shape, THROWS
+ * `SettingsParseError` carrying its path — see {@link readProfilesFile}.
+ *
+ * It used to answer an empty manifest for both, and "no profiles" is not a
+ * harmless answer here. It is exactly the state in which magus offers to save
+ * what is turned on as a first profile, and saving WRITES this file — so a
+ * manifest someone was mid-edit in came back as one generated profile and
+ * nothing else. Throwing stops every caller before its write.
  */
 export async function readManifest(
 	projectPath?: string,
 ): Promise<ProfileManifest> {
-	const filePath = getManifestPath(projectPath);
-	try {
-		if (await fs.pathExists(filePath)) {
-			return migrateToV2(await fs.readJson(filePath));
-		}
-	} catch {
-		// Corrupt/unreadable — fall through to empty.
-	}
-	return emptyManifest();
+	return migrateToV2(await readProfilesFile(getManifestPath(projectPath)));
 }
 
-/** Write the manifest back to disk (used by `profile sync`, tests). */
+/**
+ * Write the manifest to disk.
+ *
+ * Refuses with `SettingsParseError`, leaving the file untouched, whenever the
+ * file already there would be refused by {@link readManifest} — unparseable or
+ * the wrong shape. Every caller read the manifest first, but not necessarily
+ * just before: the TUI's startup gate reads it at launch and writes when the
+ * user answers, which can be minutes later — long enough for someone to be
+ * mid-edit. Checking here makes the refusal hold for every writer, not only
+ * for the ones that happened to re-read.
+ */
 export async function writeManifest(
 	manifest: ProfileManifest,
 	projectPath?: string,
 ): Promise<void> {
 	const filePath = getManifestPath(projectPath);
+	// Read for the throw alone; the contents are about to be replaced.
+	await readProfilesFile(filePath);
 	await fs.ensureDir(path.dirname(filePath));
 	await fs.writeJson(filePath, manifest, { spaces: 2 });
 }
@@ -207,10 +284,10 @@ export function validateManifest(
  * manifest file, or no entry for that profile) — all three are normal states,
  * and `mutate` is not called.
  *
- * THROWS when the manifest exists and cannot be read as JSON. `readManifest`
- * degrades a corrupt file to an empty manifest, which here would mean silently
- * recording nothing and reporting success — the caller has just written a live
- * setting the next `magus install` will revert, and would never learn.
+ * THROWS `SettingsParseError` when the manifest exists and does not parse.
+ * Treating that as "no entry" would mean silently recording nothing and
+ * reporting success — the caller has just written a live setting the next
+ * `magus install` will revert, and would never learn.
  */
 export async function updateProfileEntry(
 	projectPath: string,
@@ -218,21 +295,9 @@ export async function updateProfileEntry(
 	mutate: (entry: ProfileManifestEntry) => void,
 ): Promise<boolean> {
 	if (!profile) return false;
-	const filePath = getManifestPath(projectPath);
-	if (!(await fs.pathExists(filePath))) return false;
-
-	// Read directly rather than through readManifest: its `catch` is exactly
-	// what turns a corrupt file into a silent no-op.
-	let raw: unknown;
-	try {
-		raw = await fs.readJson(filePath);
-	} catch (error) {
-		throw new Error(
-			`${filePath} is not valid JSON, refusing to write to it: ${String(error)}`,
-		);
-	}
+	if (!(await fs.pathExists(getManifestPath(projectPath)))) return false;
 
-	const manifest = migrateToV2(raw);
+	const manifest = await readManifest(projectPath);
 	const entry = manifest.profiles[profile];
 	if (!entry) return false;
 

package/src/services/plugin-manager.ts

@@ -16,6 +16,7 @@ import {
 	getLocalEnabledPlugins,
 	getLocalInstalledPluginVersions,
 	getProjectInstalledPluginVersions,
+	getSettingsPath,
 	pickRegistryEntry,
 	readInstalledPluginsRegistry,
 	readSettings,
@@ -46,6 +47,7 @@ import {
 	resolveMarketplacePlugins,
 } from "./marketplace-fetcher.js";
 import { resolveLoadedVersions } from "./plugin-resolution.js";
+import { writableMap } from "./settings-file.js";
 export {
 	fetchMarketplacePlugins,
 	getMarketplaceFetchFailures,
@@ -733,7 +735,12 @@ export async function saveInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readSettings(projectPath);
-	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions =
+		writableMap(
+			settings,
+			"installedPluginVersions",
+			getSettingsPath(projectPath),
+		) ?? {};
 	settings.installedPluginVersions[pluginId] = version;
 	await writeSettings(settings, projectPath);
 
@@ -799,11 +806,18 @@ export async function removeInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readSettings(projectPath);
-	if (settings.installedPluginVersions) {
-		delete settings.installedPluginVersions[pluginId];
+	const settingsPath = getSettingsPath(projectPath);
+	const versions = writableMap(
+		settings,
+		"installedPluginVersions",
+		settingsPath,
+	);
+	const enabled = writableMap(settings, "enabledPlugins", settingsPath);
+	if (versions) {
+		delete versions[pluginId];
 	}
-	if (settings.enabledPlugins) {
-		delete settings.enabledPlugins[pluginId];
+	if (enabled) {
+		delete enabled[pluginId];
 	}
 	await writeSettings(settings, projectPath);
 

package/src/services/profile-adopt.ts

@@ -165,11 +165,16 @@ export type AdoptSource = "project" | "user";
 export async function collectEnabledPlugins(
 	projectPath: string,
 ): Promise<{ plugins: Record<string, boolean>; source: AdoptSource }> {
-	const project = await getEnabledPlugins(projectPath).catch(() => ({}));
+	// No catch on either read. A project settings file that does not parse is
+	// not "no project plugins": falling through to user scope there would adopt
+	// one developer's global set as the team's contract, the exact thing the
+	// project-first order exists to prevent. The SettingsParseError names the
+	// file, and adoption stops.
+	const project = await getEnabledPlugins(projectPath);
 	if (Object.values(project).some(Boolean)) {
 		return { plugins: project, source: "project" };
 	}
-	const user = await getGlobalEnabledPlugins().catch(() => ({}));
+	const user = await getGlobalEnabledPlugins();
 	return { plugins: user, source: "user" };
 }
 

package/src/services/profile-startup.ts

@@ -20,16 +20,24 @@
  * a set of declared plugins to a set of installed ones — they are different
  * kinds of thing and a comparison between them cannot be acted on.
  *
- * ## What is left is a three-state question
+ * ## What is left is a three-state question, and one state with no question
  *
- *   ok          a profile is active; the manifest is in effect; ask nothing
- *   unmigrated  no manifest — the project is not using profiles at all
- *   inactive    a manifest with profiles, none of them linked into place
+ *   ok           a profile is active; the manifest is in effect; ask nothing
+ *   unmigrated   no manifest — the project is not using profiles at all
+ *   inactive     a manifest with profiles, none of them linked into place
+ *   unparseable  a manifest that exists and is not valid JSON, or is valid
+ *                JSON in the wrong shape (see `readProfilesFile`)
  *
  * `unmigrated` and `inactive` are both unusable, not merely untidy: with no
  * active profile there is no profile state to read and nothing to write updates
  * into, so magus cannot do its job. The caller must not offer to continue.
  *
+ * `unparseable` is unusable for a different reason: magus cannot tell which of
+ * the other three it is in. It must never read as `unmigrated` — that state
+ * offers to save what is turned on as a new profile, and saving writes the
+ * manifest over whatever the file held. So it offers nothing but the way out,
+ * and names the file to fix.
+ *
  * Detection only — nothing here writes. That is what makes it callable from the
  * TUI's startup effect, and testable without a renderer.
  */
@@ -40,13 +48,18 @@ import type { ProfileManifest } from "../types/index.js";
 // selectable option is presentation-neutral data, and both surfaces render the
 // same list from these builders rather than each composing its own.
 import type { SelectOption } from "../ui/state/types.js";
-import { readManifest } from "./manifest.js";
+import { MANIFEST_FILE, emptyManifest, readManifest } from "./manifest.js";
 import type { ProfileChoice } from "./profile-activate.js";
 import { freeProfileId } from "./profile-adopt.js";
+import { SettingsParseError } from "./settings-file.js";
 import { activeProfile, displaceableArtifacts } from "./symlink-manager.js";
 
 /** Whether the project can be worked on, and if not, why not. */
-export type ProfileStartupState = "ok" | "unmigrated" | "inactive";
+export type ProfileStartupState =
+	| "ok"
+	| "unmigrated"
+	| "inactive"
+	| "unparseable";
 
 /** A profile the user could activate. */
 export interface ActivatableProfile {
@@ -88,6 +101,11 @@ export interface ProfileStartupNeed {
 	autoActivate: boolean;
 	/** The manifest as read, so the caller does not read it a second time. */
 	manifest: ProfileManifest;
+	/**
+	 * Why the manifest could not be read. Set in the `unparseable` state only,
+	 * where `manifest` is empty because nothing was read.
+	 */
+	parseError?: SettingsParseError;
 }
 
 /** True when the project is usable and there is nothing to ask. */
@@ -95,11 +113,38 @@ export function needsNothing(need: ProfileStartupNeed): boolean {
 	return need.state === "ok";
 }
 
+/**
+ * The need for a manifest that does not parse: nothing to adopt, nothing to
+ * activate, so the only option built from it is the way out.
+ *
+ * Exported because detection is not the only place this is learned. The TUI
+ * gate reads at launch and writes when the user answers; a file that stops
+ * parsing in between surfaces as the write's refusal, and the gate has to turn
+ * into this rather than ask its stale question again.
+ */
+export function unparseableNeed(error: SettingsParseError): ProfileStartupNeed {
+	return {
+		state: "unparseable",
+		adopt: null,
+		activate: [],
+		declaredDefault: null,
+		autoActivate: false,
+		manifest: emptyManifest(),
+		parseError: error,
+	};
+}
+
 /** Inspect the project and decide what, if anything, must happen first. */
 export async function detectProfileStartupNeed(
 	projectPath: string,
 ): Promise<ProfileStartupNeed> {
-	const manifest = await readManifest(projectPath);
+	let manifest: ProfileManifest;
+	try {
+		manifest = await readManifest(projectPath);
+	} catch (error) {
+		if (!(error instanceof SettingsParseError)) throw error;
+		return unparseableNeed(error);
+	}
 	const ids = Object.keys(manifest.profiles);
 
 	if (ids.length === 0) {
@@ -202,11 +247,43 @@ export const ACTIVATE_PREFIX = "activate:";
  * break opportunity — MEASURED on screen, `.claude/settings.json` wrapped as
  * `.` then `claude/settings.json` on the next line. A path split across a line
  * break reads as two different paths, neither of them real.
+ *
+ * The `unparseable` state is the one exception, because the file IS the
+ * message: "fix it" is useless without saying which. So the path goes on a
+ * line of its own, project-relative, far shorter than the narrowest modal —
+ * nothing on that line ever needs to wrap.
  */
 export function describeNeed(need: ProfileStartupNeed): {
 	title: string;
 	message: string;
 } {
+	if (need.state === "unparseable") {
+		// The error's own parts, without the absolute path its message leads
+		// with: what is wrong ("is not valid JSON", "is not a valid profiles
+		// file") and the specifics — the parser's words, or the key with the
+		// wrong shape, which is how a one-letter typo gets found.
+		const error = need.parseError;
+		const lines = [
+			`This file ${error?.problem ?? "is not valid JSON"}:`,
+			"",
+			`  ${MANIFEST_FILE}`,
+		];
+		if (error?.detail) {
+			lines.push(
+				"",
+				error.detail.charAt(0).toUpperCase() + error.detail.slice(1),
+			);
+		}
+		lines.push(
+			"",
+			"magus leaves it exactly as it is. Fix the JSON by hand, then start magus again.",
+		);
+		return {
+			title: "Cannot read this project's profiles",
+			message: lines.join("\n"),
+		};
+	}
+
 	if (need.state === "unmigrated") {
 		return {
 			title: "magus uses profiles",
@@ -234,6 +311,9 @@ export function describeNeed(need: ProfileStartupNeed): {
  * "Quit magus" is last instead. A question that cannot be answered with "no"
  * still has to be answerable with "not in this app", and the way out has to be
  * visible rather than a keystroke the user has to guess.
+ *
+ * For an `unparseable` need it is the ONLY row: there is nothing to adopt into
+ * and nothing to activate from a file magus cannot read.
  */
 export function buildProfileOptions(need: ProfileStartupNeed): SelectOption[] {
 	const options: SelectOption[] = [];

package/src/services/profiles.ts

@@ -2,6 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import type { ProfileEntry, ProfileManifest } from "../types/index.js";
+import { readProfilesFile } from "./manifest.js";
 import { activeProfile } from "./symlink-manager.js";
 
 const PROFILES_FILE = "profiles.json";
@@ -19,40 +20,52 @@ export function getProjectProfilesPath(projectPath?: string): string {
 
 // ─── Low-level read/write ──────────────────────────────────────────────────────
 
+function profilesPath(scope: "user" | "project", projectPath?: string): string {
+	return scope === "user"
+		? getUserProfilesPath()
+		: getProjectProfilesPath(projectPath);
+}
+
+/**
+ * Read one scope's profiles file.
+ *
+ * Missing, empty, `{}` or `{"version": 2}` reads as no profiles. A file that
+ * does not parse, or parses into the wrong shape, throws `SettingsParseError`
+ * naming it — never "no profiles". Every writer below reads through here
+ * first, so an empty answer for a damaged file is how saving one profile used
+ * to write over all the others.
+ *
+ * The shape check is `readProfilesFile`'s, shared with `readManifest`: at
+ * project scope this is the same `.claude/profiles.json`, and the two readers
+ * must agree on what it holds.
+ */
 export async function readProfiles(
 	scope: "user" | "project",
 	projectPath?: string,
 ): Promise<ProfileManifest> {
-	const filePath =
-		scope === "user"
-			? getUserProfilesPath()
-			: getProjectProfilesPath(projectPath);
-	try {
-		if (await fs.pathExists(filePath)) {
-			const data = await fs.readJson(filePath);
-			// A v1 file differs only in what it omits, so it reads as a v2 entry
-			// with absent optional fields. Nothing here converts: `version: 2` is
-			// what the next write records, and every consumer already treats
-			// `createdAt`, `updatedAt` and a string plugin pin as optional.
-			if (data.version && data.profiles) {
-				return { ...data, version: 2 } as ProfileManifest;
-			}
-		}
-	} catch {
-		// fall through to default
-	}
-	return { version: 2, profiles: {} };
+	const data = await readProfilesFile(profilesPath(scope, projectPath));
+	// A v1 file differs only in what it omits, so it reads as a v2 entry
+	// with absent optional fields. Nothing here converts: `version: 2` is
+	// what the next write records, and every consumer already treats
+	// `createdAt`, `updatedAt` and a string plugin pin as optional. Keys this
+	// reader does not know are carried, so a write puts them back.
+	return { ...data, version: 2 } as unknown as ProfileManifest;
 }
 
+/**
+ * Write one scope's profiles file — refusing, and leaving it untouched, when
+ * the file already there would be refused by {@link readProfiles}. Every
+ * caller reads first, but this is the half that must never write over a file
+ * magus cannot read, so it checks for itself.
+ */
 async function writeProfiles(
 	scope: "user" | "project",
 	data: ProfileManifest,
 	projectPath?: string,
 ): Promise<void> {
-	const filePath =
-		scope === "user"
-			? getUserProfilesPath()
-			: getProjectProfilesPath(projectPath);
+	const filePath = profilesPath(scope, projectPath);
+	// Read for the throw alone; the contents are about to be replaced.
+	await readProfilesFile(filePath);
 	await fs.ensureDir(path.dirname(filePath));
 	await fs.writeJson(filePath, data, { spaces: 2 });
 }