magus-cli 7.3.1 → 7.4.1

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 });
 }

package/src/services/settings-file.ts

@@ -13,15 +13,168 @@
  *     mid-edit. Treating it as `{}` and writing our one key back is how a
  *     user's whole configuration disappears. We refuse and say so.
  *
+ * "Unparseable" includes a file that parses into something other than an
+ * object — `[]`, `null`, `5`, `"text"`. Every caller indexes the result as a
+ * map, so an array swallowed an enabled plugin as a property `JSON.stringify`
+ * never writes (the enable reported success and was gone), and `null` or a
+ * number crashed with a raw `TypeError`. Neither is a file we understand.
+ *
  * A MISSING file is different from an unparseable one: nothing is lost by
  * starting from `{}`, so that is what a missing (or empty) file reads as.
+ *
+ * Every Claude Code settings reader goes through `readSettingsFile` —
+ * `claude-settings.ts` delegates its four readers here, and the profiles
+ * readers in `manifest.ts` build on it — so there is one refusal, one wording
+ * and one error class for all of them.
  */
 
 import path from "node:path";
 import fs from "fs-extra";
 
 /**
- * Parse `settingsPath`. Missing or empty reads as `{}`; unparseable throws.
+ * A settings file that exists and cannot be used: it does not parse, or it
+ * parses into the wrong shape (see {@link SettingsShapeError}).
+ *
+ * Its own class so a caller can tell "this file is damaged" apart from every
+ * other failure and name the file to the user. The message is complete on its
+ * own — the path, what is wrong, and that magus refused — so a caller that
+ * prints `message` needs nothing else. `problem` and `detail` are its parts,
+ * for a caller that lays the file out on its own line instead.
+ */
+export class SettingsParseError extends Error {
+	readonly path: string;
+	/** What is wrong, as the rest of a sentence that starts with the file: "is not valid JSON". */
+	readonly problem: string;
+	/** The specifics: the parser's own words, or which part has the wrong shape. */
+	readonly detail: string;
+
+	constructor(
+		settingsPath: string,
+		cause: unknown,
+		problem = "is not valid JSON",
+	) {
+		const detail = cause instanceof Error ? cause.message : String(cause);
+		super(`${settingsPath} ${problem}, refusing to overwrite it: ${detail}`, {
+			cause,
+		});
+		this.name = "SettingsParseError";
+		this.path = settingsPath;
+		this.problem = problem;
+		this.detail = detail;
+	}
+}
+
+/**
+ * A settings or profiles file that is valid JSON, but not the shape the file
+ * must have — a top level that is not an object, or (for a profiles file) a
+ * `profiles` key that is not a map of objects.
+ *
+ * Refused exactly like a file that does not parse, and for the same reason:
+ * reading it as "empty" is what lets the next write replace it. A subclass so
+ * every existing `instanceof SettingsParseError` catch handles it unchanged.
+ */
+export class SettingsShapeError extends SettingsParseError {
+	constructor(settingsPath: string, problem: string, detail: string) {
+		super(settingsPath, detail, problem);
+		this.name = "SettingsShapeError";
+	}
+}
+
+/** True for a JSON object: not `null`, not an array, not a primitive. */
+export function isJsonObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A parsed JSON value's kind with its article, for a refusal: "an array", "null". */
+export function describeJsonKind(value: unknown): string {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "an object";
+	return `a ${typeof value}`;
+}
+
+/**
+ * The map at `settings[key]`, checked before the caller writes an entry into
+ * it: the map itself, or `undefined` when the key is absent. Present but not a
+ * JSON object THROWS {@link SettingsShapeError} naming the file and the key —
+ * so nothing reaches the write, and the file stays byte-for-byte as it was.
+ *
+ * The top-level check in {@link readSettingsFile} does not reach this far: the
+ * file IS an object, one of its maps is not. `settings.enabledPlugins || {}`
+ * kept an array, a plugin id set on an array is a property `JSON.stringify`
+ * never writes, and the enable reported success with nothing saved. On a
+ * string or a number the same assignment is a raw `TypeError`; on `null`,
+ * `|| {}` silently replaced the user's value.
+ *
+ * Every read-modify-write that writes into a map comes through here.
+ * `keyPath` names a nested key in the refusal ("permissions.allow"); it
+ * defaults to `key`.
+ */
+export function writableMap<S extends object, K extends keyof S & string>(
+	settings: S,
+	key: K,
+	settingsPath: string,
+	keyPath: string = key,
+): CheckedMap<S[K]> {
+	return checkedEntry(
+		settings,
+		key,
+		settingsPath,
+		keyPath,
+		"object",
+	) as CheckedMap<S[K]>;
+}
+
+/**
+ * A typed key keeps its type; an untyped one (`unknown`, from an open settings
+ * record) comes back as the object the check has just proved it is.
+ */
+type CheckedMap<V> = unknown extends V
+	? Record<string, unknown> | undefined
+	: V;
+
+/**
+ * {@link writableMap} for a list the caller pushes into or filters —
+ * `enabledMcpjsonServers`, a gitignore manifest's `ignore` and `track`. Present
+ * but not an array throws the same way.
+ */
+export function writableList<S extends object, K extends keyof S & string>(
+	settings: S,
+	key: K,
+	settingsPath: string,
+): CheckedList<S[K]> {
+	return checkedEntry(settings, key, settingsPath, key, "array") as CheckedList<
+		S[K]
+	>;
+}
+
+/** {@link CheckedMap} for a list: an untyped key comes back as the array it is. */
+type CheckedList<V> = unknown extends V ? unknown[] | undefined : V;
+
+function checkedEntry<S extends object, K extends keyof S & string>(
+	settings: S,
+	key: K,
+	settingsPath: string,
+	keyPath: string,
+	shape: "object" | "array",
+): S[K] {
+	const value = settings[key];
+	if (value === undefined) return value;
+	const fits = shape === "object" ? isJsonObject(value) : Array.isArray(value);
+	if (!fits) {
+		throw new SettingsShapeError(
+			settingsPath,
+			`has a malformed "${keyPath}"`,
+			`it is ${describeJsonKind(value)}, not a JSON ${shape}`,
+		);
+	}
+	return value;
+}
+
+/**
+ * Parse `settingsPath`. Missing or empty reads as `{}`; unparseable throws
+ * {@link SettingsParseError}, and a top level that is not an object throws
+ * {@link SettingsShapeError}.
  *
  * Exported for callers that only need the read half — the refusal wording is
  * the same either way, so nothing has to reimplement it.
@@ -34,13 +187,20 @@ export async function readSettingsFile(
 	const raw = (await fs.readFile(settingsPath, "utf8")).trim();
 	if (!raw) return {};
 
+	let parsed: unknown;
 	try {
-		return JSON.parse(raw) as Record<string, unknown>;
+		parsed = JSON.parse(raw);
 	} catch (error) {
-		throw new Error(
-			`${settingsPath} is not valid JSON, refusing to overwrite it: ${String(error)}`,
+		throw new SettingsParseError(settingsPath, error);
+	}
+	if (!isJsonObject(parsed)) {
+		throw new SettingsShapeError(
+			settingsPath,
+			"is not a JSON object",
+			`its top level is ${describeJsonKind(parsed)}`,
 		);
 	}
+	return parsed;
 }
 
 /**

package/src/services/settings-manager.ts

@@ -3,11 +3,14 @@ import * as path from "node:path";
 import type { SettingDefinition } from "../data/settings-catalog.js";
 import type { ClaudeSettings } from "../types/index.js";
 import {
+	getGlobalSettingsPath,
+	getSettingsPath,
 	readGlobalSettings,
 	readSettings,
 	writeGlobalSettings,
 	writeSettings,
 } from "./claude-settings.js";
+import { writableMap } from "./settings-file.js";
 
 export type SettingScope = "user" | "project";
 
@@ -103,6 +106,9 @@ export async function writeSettingValue(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await loadSettings(scope, projectPath);
+	// Named in the refusal when a map this writes into has the wrong shape.
+	const settingsPath =
+		scope === "user" ? getGlobalSettingsPath() : getSettingsPath(projectPath);
 
 	if (setting.storage.type === "attribution") {
 		// Boolean toggle: "false" -> write { commit: "", pr: "" }, "true"/undefined -> delete key
@@ -125,8 +131,10 @@ export async function writeSettingValue(
 			delete settings.attribution;
 		}
 	} else if (setting.storage.type === "env") {
-		// Write to the "env" block in settings.json
-		const env = isRecord(settings.env) ? settings.env : {};
+		// Write to the "env" block in settings.json. One that is present but not
+		// an object is refused, never replaced — replacing it deleted the user's
+		// value to make room for ours.
+		const env = writableMap(settings, "env", settingsPath) ?? {};
 		settings.env = env;
 		if (value === undefined || value === "" || value === setting.defaultValue) {
 			delete env[setting.storage.key];
@@ -149,11 +157,17 @@ export async function writeSettingValue(
 				settings[keys[0]] = parseSettingValue(value, setting.type);
 			}
 		} else {
-			// Nested key like "permissions.defaultMode"
+			// Nested key like "permissions.defaultMode". Each parent on the way is
+			// a map this writes into: absent is created, the wrong shape refused.
 			let obj: Record<string, unknown> = settings;
 			for (let i = 0; i < keys.length - 1; i++) {
-				const existing = obj[keys[i]];
-				const next = isRecord(existing) ? existing : {};
+				const next =
+					writableMap(
+						obj,
+						keys[i],
+						settingsPath,
+						keys.slice(0, i + 1).join("."),
+					) ?? {};
 				obj[keys[i]] = next;
 				obj = next;
 			}

package/src/services/skills-manager.ts

@@ -664,6 +664,26 @@ function parseYamlFrontmatter(content: string): Partial<SkillFrontmatter> {
 	if (!frontmatterMatch) return {};
 
 	const yaml = frontmatterMatch[1];
+
+	// Real YAML first: a description is routinely a block scalar (`description: >-`
+	// with the text on the lines below), which the line reading further down returns
+	// as the literal ">-". Many community SKILL.md files are not valid YAML, though —
+	// an unquoted ": " inside a description is common — so a parse failure falls
+	// back to the line reading those files have always had.
+	try {
+		// `Bun.YAML` ships in the runtime (1.2.21+) but not in the Bun types this
+		// package resolves. A runtime without it throws here and takes the fallback.
+		const { YAML } = Bun as unknown as {
+			YAML: { parse(text: string): unknown };
+		};
+		const parsed: unknown = YAML.parse(yaml);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Partial<SkillFrontmatter>;
+		}
+	} catch {
+		// Not valid YAML — read it line by line below.
+	}
+
 	const result: Record<string, unknown> = {};
 
 	for (const line of yaml.split("\n")) {
@@ -692,6 +712,32 @@ function parseYamlFrontmatter(content: string): Partial<SkillFrontmatter> {
 	return result as Partial<SkillFrontmatter>;
 }
 
+/**
+ * The frontmatter of an INSTALLED skill, read from its SKILL.md on disk.
+ *
+ * A local skill has no remote to fetch from, so this is the only place its
+ * description can come from. `name` falls back to the directory name and
+ * `description` to "" — the caller decides how to say "none". Never throws: an
+ * unreadable file answers `null`.
+ */
+export async function readLocalSkillFrontmatter(
+	skillMdPath: string,
+	fallbackName: string,
+): Promise<SkillFrontmatter | null> {
+	let content: string;
+	try {
+		content = await fs.readFile(skillMdPath, "utf8");
+	} catch {
+		return null;
+	}
+	const parsed = parseYamlFrontmatter(content);
+	return {
+		...parsed,
+		name: parsed.name || fallbackName,
+		description: parsed.description || "",
+	};
+}
+
 export async function fetchSkillFrontmatter(
 	skill: SkillInfo,
 ): Promise<SkillFrontmatter> {