magus-cli 7.3.0 → 7.4.0

package/src/services/settings-file.ts

@@ -13,15 +13,162 @@
  *     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`. 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,
+): S[K] {
+	return checkedEntry(settings, key, settingsPath, key, "array");
+}
+
+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 +181,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> {