magus-cli 7.4.0 → 7.5.0

package/src/services/claude-settings.ts

@@ -29,6 +29,10 @@ import {
 	repoRootForPath,
 } from "./plugin-resolution.js";
 import {
+	SettingsParseError,
+	SettingsShapeError,
+	describeJsonKind,
+	isJsonObject,
 	readSettingsFile,
 	writableList,
 	writableMap,
@@ -93,6 +97,30 @@ export async function ensureClaudeDir(projectPath?: string): Promise<string> {
  * file that was actually read.
  */
 
+/**
+ * THE FOUR WRITERS all start here: the file as it is NOW must still be one this
+ * module would read, or nothing is written.
+ *
+ * Every caller reads before it writes, but not necessarily just before —
+ * `magus install` reads the local settings, puts a prompt per missing variable
+ * on screen, and writes when the last one is answered. Claude Code writes that
+ * same file while those prompts are up (a permission rule, whenever someone
+ * answers "don't ask again"), and `writeJson` would replace it with a document
+ * built from the pre-prompt read.
+ *
+ * Checking at write time is what makes the refusal hold for every writer instead
+ * of only the ones that happened to re-read — the same rule `writeManifest`
+ * applies to `.claude/profiles.json`. The read is for the throw alone; the
+ * contents are about to be replaced.
+ *
+ * It closes the gap, it does not close the race: the check and the write are two
+ * syscalls. The window is microseconds rather than however long a human takes to
+ * answer a prompt.
+ */
+async function refuseUnwritableFile(filePath: string): Promise<void> {
+	await readSettingsFile(filePath);
+}
+
 /** <project>/.claude/settings.json */
 export function getSettingsPath(projectPath?: string): string {
 	return path.join(getClaudeDir(projectPath), SETTINGS_FILE);
@@ -120,6 +148,7 @@ export async function writeSettings(
 	settings: ClaudeSettings,
 	projectPath?: string,
 ): Promise<void> {
+	await refuseUnwritableFile(getSettingsPath(projectPath));
 	const claudeDir = await ensureClaudeDir(projectPath);
 	const settingsPath = path.join(claudeDir, SETTINGS_FILE);
 	await fs.writeJson(settingsPath, settings, { spaces: 2 });
@@ -137,6 +166,7 @@ export async function writeLocalSettings(
 	settings: ClaudeLocalSettings,
 	projectPath?: string,
 ): Promise<void> {
+	await refuseUnwritableFile(getLocalSettingsPath(projectPath));
 	const claudeDir = await ensureClaudeDir(projectPath);
 	const localPath = path.join(claudeDir, LOCAL_SETTINGS_FILE);
 	await fs.writeJson(localPath, settings, { spaces: 2 });
@@ -161,6 +191,7 @@ export async function writeMcpConfig(
 	projectPath?: string,
 ): Promise<void> {
 	const mcpPath = getMcpConfigPath(projectPath);
+	await refuseUnwritableFile(mcpPath);
 	await fs.writeJson(mcpPath, config, { spaces: 2 });
 }
 
@@ -171,6 +202,7 @@ export async function readGlobalSettings(): Promise<ClaudeSettings> {
 export async function writeGlobalSettings(
 	settings: ClaudeSettings,
 ): Promise<void> {
+	await refuseUnwritableFile(getGlobalSettingsPath());
 	await fs.ensureDir(getGlobalClaudeDir());
 	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
 	await fs.writeJson(settingsPath, settings, { spaces: 2 });
@@ -1130,13 +1162,13 @@ export async function migrateMarketplaceRename(
 	}
 
 	// 4. known_marketplaces.json — rename old keys + physical directory cleanup
-	const pluginsDir = path.join(
+	const marketplacesDir = path.join(
 		os.homedir(),
 		".claude",
 		"plugins",
 		"marketplaces",
 	);
-	const newDir = path.join(pluginsDir, NEW_MARKETPLACE_NAME);
+	const newDir = path.join(marketplacesDir, NEW_MARKETPLACE_NAME);
 
 	try {
 		const known = await readKnownMarketplaces();
@@ -1178,7 +1210,7 @@ export async function migrateMarketplaceRename(
 
 	// 4b. Rename/remove old physical directories (runs even if keys were already migrated)
 	for (const oldName of OLD_MARKETPLACE_NAMES) {
-		const oldDir = path.join(pluginsDir, oldName);
+		const oldDir = path.join(marketplacesDir, oldName);
 		try {
 			if (await fs.pathExists(oldDir)) {
 				if (!(await fs.pathExists(newDir))) {
@@ -1217,29 +1249,32 @@ export async function migrateMarketplaceRename(
 
 	// 5. installed_plugins.json — rename plugin ID keys
 	try {
-		const registry = await readInstalledPluginsRegistry();
 		let regCount = 0;
-		const newPlugins: typeof registry.plugins = {};
-		for (const [pluginId, entries] of Object.entries(registry.plugins)) {
-			const oldName = OLD_MARKETPLACE_NAMES.find((n) =>
-				pluginId.endsWith(`@${n}`),
-			);
-			if (oldName) {
-				const pluginName = pluginId.slice(0, pluginId.lastIndexOf("@"));
-				const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
-				if (!newPlugins[newKey]) {
-					newPlugins[newKey] = entries;
+		await updateRegistryFile((registry) => {
+			const newPlugins: typeof registry.plugins = {};
+			for (const [pluginId, entries] of Object.entries(registry.plugins)) {
+				const oldName = OLD_MARKETPLACE_NAMES.find((n) =>
+					pluginId.endsWith(`@${n}`),
+				);
+				if (oldName) {
+					const pluginName = pluginId.slice(0, pluginId.lastIndexOf("@"));
+					const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
+					if (!newPlugins[newKey]) {
+						newPlugins[newKey] = entries;
+					}
+					regCount++;
+				} else {
+					newPlugins[pluginId] = entries;
 				}
-				regCount++;
-			} else {
-				newPlugins[pluginId] = entries;
 			}
-		}
-		if (regCount > 0) {
+			if (regCount === 0) return false;
 			registry.plugins = newPlugins;
-			await writeInstalledPluginsRegistry(registry);
-			result.registryMigrated = regCount;
-		}
+			return true;
+		});
+		// After the write, never inside the mutation: a refused write (a corrupt
+		// file, or one another session changed) must not report a migration that
+		// did not land.
+		result.registryMigrated = regCount;
 	} catch {
 		/* skip if unreadable */
 	}
@@ -1494,7 +1529,17 @@ export async function resolveCacheProvenance(
 }
 
 /**
- * Read installed_plugins.json registry
+ * Read installed_plugins.json registry.
+ *
+ * Missing reads as an empty registry — nothing is lost by starting from one.
+ * A file that EXISTS and cannot be used throws, exactly as the settings readers
+ * do: this is the record of what every project on the machine has installed,
+ * and "unreadable" is not the same answer as "nothing installed".
+ *
+ * It used to answer an empty registry for both, and the registry writers below
+ * then wrote that empty copy back with one plugin in it — so a registry a
+ * Claude Code write had truncated came back holding a single row, and every
+ * other plugin on the machine read as uninstalled.
  *
  * @param root the plugins directory to read from — see {@link pluginsDir}
  */
@@ -1502,20 +1547,7 @@ export async function readInstalledPluginsRegistry(
 	root: string = pluginsDir(),
 ): Promise<InstalledPluginsRegistry> {
 	const file = installedPluginsFile(root);
-	const raw = await readRegistryBytes(file);
-	const parsed = parseRegistryBytes(raw);
-	if (parsed) return parsed;
-	if (raw !== null) {
-		// Corrupt rather than absent — keep a copy before any caller writes over it.
-		try {
-			const backup = await registryBackupPath(file, "corrupt");
-			await fs.copy(file, backup);
-			console.warn(`Corrupted registry backed up to: ${backup}`);
-		} catch {
-			// Ignore backup errors
-		}
-	}
-	return { version: 2, plugins: {} };
+	return requireRegistry(file, await readRegistryBytes(file));
 }
 
 /**
@@ -1535,18 +1567,104 @@ async function readRegistryBytes(file: string): Promise<string | null> {
 	}
 }
 
-/** Parse + structure check. Null means "not a registry", including absent. */
-function parseRegistryBytes(
+/** An empty, valid registry: what an absent file reads as. */
+function emptyRegistry(): InstalledPluginsRegistry {
+	return { version: 2, plugins: {} };
+}
+
+/**
+ * Refuse a registry document that cannot be read AT ALL — it does not parse, or
+ * its top level is not a JSON object — with the same refusal every settings file
+ * gets, naming the file. Absent or whitespace-only passes (and answers `null`).
+ *
+ * The weaker of the two checks, and deliberately so: it is what a WRITER asks
+ * before renaming over a file, where the question is only "is this a document
+ * anything could have read", not "does it match the shape this version of magus
+ * models". {@link requireRegistry} is the stronger one, asked by every reader.
+ */
+function refuseUnreadableRegistry(
+	file: string,
 	raw: string | null,
-): InstalledPluginsRegistry | null {
-	if (raw === null) return null;
+): Record<string, unknown> | null {
+	if (raw === null || raw.trim() === "") return null;
+
+	let parsed: unknown;
 	try {
-		const content = JSON.parse(raw);
-		if (!content?.version || !content?.plugins) return null;
-		return content as InstalledPluginsRegistry;
-	} catch {
-		return null;
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new SettingsParseError(file, error);
+	}
+	if (!isJsonObject(parsed)) {
+		throw new SettingsShapeError(
+			file,
+			"is not a JSON object",
+			`its top level is ${describeJsonKind(parsed)}`,
+		);
 	}
+	return parsed;
+}
+
+/**
+ * Parse + structure check, or throw.
+ *
+ * THE one place a registry document is judged for READING, so no two readers
+ * can disagree about whether the file on disk is usable. Absent or
+ * whitespace-only reads as an empty registry; anything else that is not
+ * `{version, plugins: {…}}` throws a {@link SettingsParseError} — a
+ * `SettingsShapeError` when it parsed but is the wrong shape — naming the file,
+ * so every read-modify-write refuses at the same point and nothing reaches a
+ * write.
+ */
+function requireRegistry(
+	file: string,
+	raw: string | null,
+): InstalledPluginsRegistry {
+	const parsed = refuseUnreadableRegistry(file, raw);
+	if (parsed === null) return emptyRegistry();
+
+	if (!parsed.version || !isJsonObject(parsed.plugins)) {
+		throw new SettingsShapeError(
+			file,
+			"is not a plugin registry",
+			`expected a "version" and a "plugins" object, got ${
+				parsed.plugins === undefined
+					? 'no "plugins" key'
+					: `"plugins" as ${describeJsonKind(parsed.plugins)}`
+			}`,
+		);
+	}
+	return parsed as unknown as InstalledPluginsRegistry;
+}
+
+/**
+ * Read the registry, change it, write it back — the ONE read-modify-write every
+ * registry writer goes through.
+ *
+ * Both halves of the safety live here rather than in each writer: the read
+ * refuses a document we cannot parse ({@link requireRegistry}), and the write
+ * carries the exact bytes that were read as a precondition, so a Claude Code
+ * install landing in between is refused instead of being silently dropped by our
+ * snapshot (see {@link writeInstalledPluginsRegistry}).
+ *
+ * `mutate` answers whether there is anything to write: `false` writes nothing
+ * and leaves the file untouched.
+ *
+ * {@link repairStaleLoad} is the one writer that does this by hand, because it
+ * takes an undo backup between the read and the write and reports its refusals
+ * as a result object instead of throwing. It reads and checks through the same
+ * {@link requireRegistry}.
+ */
+async function updateRegistryFile(
+	mutate: (registry: InstalledPluginsRegistry) => Promise<boolean> | boolean,
+	root: string = pluginsDir(),
+): Promise<void> {
+	const file = installedPluginsFile(root);
+	// The BYTES first, and the snapshot parsed from those same bytes: they have
+	// to describe one moment for the precondition to mean anything.
+	const before = await readRegistryBytes(file);
+	const registry = requireRegistry(file, before);
+	if (!(await mutate(registry))) return;
+	await writeInstalledPluginsRegistry(registry, root, before);
 }
 
 /** How many `installed_plugins.json.backup.*` files are kept. */
@@ -1625,10 +1743,23 @@ export class RegistryChangedError extends Error {
  *
  * ATOMIC — temp file in the same directory, then rename. This file is read by
  * every Claude Code session on the machine, so a write interrupted partway
- * leaves a truncated JSON document that `readInstalledPluginsRegistry` treats as
- * corrupt and replaces with an EMPTY registry: every plugin on the machine
- * reads as not installed. `rename(2)` within one directory cannot be observed
- * half-done, so a reader sees either the old file or the new one.
+ * leaves a truncated JSON document nothing can read: every plugin on the machine
+ * would read as not installed. `rename(2)` within one directory cannot be
+ * observed half-done, so a reader sees either the old file or the new one.
+ *
+ * TWO preconditions, both checked as the last act before the rename, and the
+ * second is not implied by the first:
+ *
+ *  1. the file is the one the caller read (`expectBytes`);
+ *  2. the file on disk is still a document we can read at all — it parses, and
+ *     into an object.
+ *
+ * Byte-equality does not cover (2). A caller holding the raw bytes of a corrupt
+ * file passes the compare exactly, and the rename then replaces a registry
+ * nobody could read with one holding only the plugin being written — every other
+ * project's installs gone. The strict read in {@link requireRegistry} is the
+ * first line and stops every read-modify-write; this is the second, and it holds
+ * for a direct caller too, including one that passes no `expectBytes`.
  *
  * ATOMICITY IS NOT ISOLATION, and conflating the two is how this silently lost
  * other sessions' work. A read-modify-write rewrites the WHOLE file from the
@@ -1664,10 +1795,12 @@ export async function writeInstalledPluginsRegistry(
 	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
 	try {
 		await fs.writeJson(tmp, registry, { spaces: 2 });
-		if (expectBytes !== undefined) {
-			const current = await readRegistryBytes(file);
-			if (current !== expectBytes) throw new RegistryChangedError(file);
+		// One read, both preconditions — they have to judge the same moment.
+		const current = await readRegistryBytes(file);
+		if (expectBytes !== undefined && current !== expectBytes) {
+			throw new RegistryChangedError(file);
 		}
+		refuseUnreadableRegistry(file, current);
 		await fs.rename(tmp, file);
 	} catch (error) {
 		await fs.remove(tmp).catch(() => {});
@@ -1703,65 +1836,73 @@ export async function updateInstalledPluginsRegistry(
 	projectPath?: string,
 ): Promise<void> {
 	try {
-		const registry = await readInstalledPluginsRegistry();
-
-		// Get marketplace from plugin ID
-		const parsed = parsePluginId(pluginId);
-		if (!parsed) {
-			console.warn(`Invalid plugin ID: ${pluginId}, skipping registry update`);
-			return;
-		}
-
-		const { marketplace } = parsed;
+		await updateRegistryFile(async (registry) => {
+			// Get marketplace from plugin ID
+			const parsed = parsePluginId(pluginId);
+			if (!parsed) {
+				console.warn(
+					`Invalid plugin ID: ${pluginId}, skipping registry update`,
+				);
+				return false;
+			}
 
-		// Copy plugin files from source to cache
-		// This ensures the cache has the latest plugin version
-		const copiedFrom = await copyPluginToCache(pluginId, version, marketplace);
+			const { marketplace } = parsed;
 
-		const installPath = getPluginCachePath(pluginId, version, marketplace);
-		const now = new Date().toISOString();
+			// Copy plugin files from source to cache
+			// This ensures the cache has the latest plugin version
+			const copiedFrom = await copyPluginToCache(
+				pluginId,
+				version,
+				marketplace,
+			);
 
-		// Initialize plugin array if it doesn't exist
-		if (!registry.plugins[pluginId]) {
-			registry.plugins[pluginId] = [];
-		}
+			const installPath = getPluginCachePath(pluginId, version, marketplace);
+			const now = new Date().toISOString();
 
-		// Find existing entry for this scope and project
-		const existingIndex = registry.plugins[pluginId].findIndex((entry) => {
-			if (entry.scope !== scope) return false;
-			if (scope === "user") return true;
-			return entry.projectPath === projectPath;
-		});
+			// Initialize plugin array if it doesn't exist
+			if (!registry.plugins[pluginId]) {
+				registry.plugins[pluginId] = [];
+			}
 
-		const entry: InstalledPluginEntry = {
-			scope,
-			projectPath,
-			installPath,
-			version,
-			installedAt:
-				existingIndex >= 0
-					? registry.plugins[pluginId][existingIndex].installedAt
-					: now,
-			lastUpdated: now,
-			gitCommitSha: await resolveCacheProvenance(
-				copiedFrom,
-				existingIndex >= 0
-					? registry.plugins[pluginId][existingIndex].gitCommitSha
-					: undefined,
-			),
-		};
+			// Find existing entry for this scope and project
+			const existingIndex = registry.plugins[pluginId].findIndex((entry) => {
+				if (entry.scope !== scope) return false;
+				if (scope === "user") return true;
+				return entry.projectPath === projectPath;
+			});
 
-		if (existingIndex >= 0) {
-			// Update existing entry
-			registry.plugins[pluginId][existingIndex] = entry;
-		} else {
-			// Add new entry
-			registry.plugins[pluginId].push(entry);
-		}
+			const entry: InstalledPluginEntry = {
+				scope,
+				projectPath,
+				installPath,
+				version,
+				installedAt:
+					existingIndex >= 0
+						? registry.plugins[pluginId][existingIndex].installedAt
+						: now,
+				lastUpdated: now,
+				gitCommitSha: await resolveCacheProvenance(
+					copiedFrom,
+					existingIndex >= 0
+						? registry.plugins[pluginId][existingIndex].gitCommitSha
+						: undefined,
+				),
+			};
 
-		await writeInstalledPluginsRegistry(registry);
+			if (existingIndex >= 0) {
+				// Update existing entry
+				registry.plugins[pluginId][existingIndex] = entry;
+			} else {
+				// Add new entry
+				registry.plugins[pluginId].push(entry);
+			}
+			return true;
+		});
 	} catch (error) {
-		// Log warning but don't block plugin operation
+		// Say what was refused and why, then let the plugin operation carry on:
+		// the install itself succeeded, and the registry is Claude Code's file to
+		// repair. What must not happen is writing over it, which is why the read
+		// throws rather than answering an empty registry.
 		console.warn(
 			`Failed to update registry for ${pluginId}:`,
 			error instanceof Error ? error.message : "Unknown error",
@@ -1778,23 +1919,24 @@ export async function removeFromInstalledPluginsRegistry(
 	projectPath?: string,
 ): Promise<void> {
 	try {
-		const registry = await readInstalledPluginsRegistry();
-
-		if (!registry.plugins[pluginId]) return;
+		await updateRegistryFile((registry) => {
+			if (!registry.plugins[pluginId]) return false;
+
+			// Remove entry matching scope and projectPath
+			registry.plugins[pluginId] = registry.plugins[pluginId].filter(
+				(entry) => {
+					if (entry.scope !== scope) return true;
+					if (scope === "user") return false;
+					return entry.projectPath !== projectPath;
+				},
+			);
 
-		// Remove entry matching scope and projectPath
-		registry.plugins[pluginId] = registry.plugins[pluginId].filter((entry) => {
-			if (entry.scope !== scope) return true;
-			if (scope === "user") return false;
-			return entry.projectPath !== projectPath;
+			// Remove plugin key if no entries remain
+			if (registry.plugins[pluginId].length === 0) {
+				delete registry.plugins[pluginId];
+			}
+			return true;
 		});
-
-		// Remove plugin key if no entries remain
-		if (registry.plugins[pluginId].length === 0) {
-			delete registry.plugins[pluginId];
-		}
-
-		await writeInstalledPluginsRegistry(registry);
 	} catch (error) {
 		// Log warning but don't block plugin operation
 		console.warn(
@@ -2128,12 +2270,17 @@ export async function repairStaleLoad(
 	// precondition the write is checked against, so they have to describe one
 	// moment — see `writeInstalledPluginsRegistry`.
 	const before = await readRegistryBytes(file);
-	const registry = parseRegistryBytes(before);
-	if (!registry) {
+	if (before === null) return fail(`${file} does not exist`);
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = requireRegistry(file, before);
+	} catch (error) {
+		// The same check every other reader makes; a repair reports it as a result
+		// rather than throwing, because it is one item in a plan of many.
 		return fail(
-			before === null
-				? `${file} does not exist`
-				: `${file} is not a readable registry — refusing to write over it`,
+			`${file} is not a readable registry — refusing to write over it: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
 		);
 	}
 	const rows = registry.plugins[pluginId];
@@ -2226,7 +2373,18 @@ export async function repairStaleLoad(
 
 	// Re-read from DISK, not from the object just mutated: the assertion has to
 	// judge the file the loader will read, which also proves the write landed.
-	const after = await readInstalledPluginsRegistry(root);
+	// A refusal here is reported like every other outcome — this function answers
+	// with a result, and a plan of repairs must not be ended by a throw from one.
+	let after: InstalledPluginsRegistry;
+	try {
+		after = await readInstalledPluginsRegistry(root);
+	} catch (error) {
+		return fail(
+			`could not re-read ${file} to confirm the repair: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+	}
 	const loaded =
 		pickLoadedEntry(after.plugins[pluginId], projectPath)?.version ?? null;
 	if (loaded === target) {

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

@@ -141,3 +141,33 @@ export function cliToolUninstall(
 			});
 	}
 }
+
+/**
+ * Why magus cannot remove an install made this way — or null when it can.
+ *
+ * Derived from {@link cliToolUninstall}, never from a second list of methods:
+ * "is there a command" and "why is there no command" have to answer about the
+ * same thing, or the conflict fix offers a removal it then skips. That is the
+ * defect this exists for — the fix used to list every install as removable,
+ * `continue` past the ones with no command, and report success.
+ *
+ * The text is a clause, to be read after "the <method> install stays:".
+ */
+export function uninstallBlocker(
+	tool: CliTool,
+	method: InstallMethod,
+	brewFormula?: string,
+): string | null {
+	if (cliToolUninstall(tool, method, brewFormula) !== null) return null;
+	switch (method) {
+		case "native":
+			// Claude Code's native installer. It updates itself and ships no
+			// uninstall command; inventing one would mean deleting another
+			// program's files by hand.
+			return "its own installer ships no uninstall command";
+		case "unknown":
+			return "magus could not tell which installer put it there";
+		default:
+			return `magus has no uninstall command for a ${method} install`;
+	}
+}

package/src/services/conventions-manager.ts

@@ -258,6 +258,94 @@ export async function removeGitignoreEntries(
 	});
 }
 
+/** A `.gitignore` comment that heads a block magus wrote. */
+const MAGUS_BLOCK_HEADER_RE = /^#\s*magus:/;
+
+/**
+ * Edit magus's own block in a `.gitignore`, and nothing else in the file.
+ *
+ * A block is a `# magus: …` comment line and the entry lines under it, up to
+ * the next blank line or comment. Every magus release wrote its profile lines
+ * that way, so that block is the only part of the file magus may take lines
+ * OUT of: the same pattern elsewhere is a person's, and they put it there on
+ * purpose.
+ *
+ * - `add`: entries not already present anywhere in the file are appended to
+ *   the block headed exactly by `header`, which is created at the end of the
+ *   file when there is none.
+ * - `remove`: entries are removed from every `# magus:` block. Lines outside
+ *   the blocks are never touched.
+ *
+ * Under the file lock, written atomically, a no-op when nothing changes.
+ */
+export async function updateManagedGitignoreBlock(
+	gitignorePath: string,
+	header: string,
+	edits: { add?: readonly string[]; remove?: readonly string[] },
+): Promise<{ added: string[]; removed: string[]; modified: boolean }> {
+	const add = (edits.add ?? []).map((e) => e.trim()).filter(Boolean);
+	const remove = new Set(
+		(edits.remove ?? []).map((e) => e.trim()).filter((e) => !add.includes(e)),
+	);
+	if (add.length === 0 && remove.size === 0) {
+		return { added: [], removed: [], modified: false };
+	}
+
+	return withFileLock(gitignorePath, async () => {
+		const content = await readFileOrEmpty(gitignorePath);
+		const lines = content.length > 0 ? content.split("\n") : [];
+		if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+
+		// Pass 1: drop `remove` entries inside magus blocks only.
+		const removed: string[] = [];
+		const kept: string[] = [];
+		let inBlock = false;
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (MAGUS_BLOCK_HEADER_RE.test(trimmed)) {
+				inBlock = true;
+				kept.push(line);
+				continue;
+			}
+			if (trimmed === "" || trimmed.startsWith("#")) inBlock = false;
+			if (inBlock && remove.has(trimmed)) {
+				removed.push(trimmed);
+				continue;
+			}
+			kept.push(line);
+		}
+
+		// Pass 2: add what the file lacks, at the end of the named block.
+		const present = new Set(
+			kept.map((l) => l.trim()).filter((l) => l && !l.startsWith("#")),
+		);
+		const toAdd = add.filter((e) => !present.has(e));
+		let out = kept;
+		if (toAdd.length > 0) {
+			const at = kept.findIndex((l) => l.trim() === header.trim());
+			if (at === -1) {
+				out = [...kept];
+				if (out.length > 0 && out[out.length - 1]?.trim() !== "") out.push("");
+				out.push(header, ...toAdd);
+			} else {
+				let end = at + 1;
+				while (end < kept.length) {
+					const t = kept[end]?.trim() ?? "";
+					if (t === "" || t.startsWith("#")) break;
+					end++;
+				}
+				out = [...kept.slice(0, end), ...toAdd, ...kept.slice(end)];
+			}
+		}
+
+		if (toAdd.length === 0 && removed.length === 0) {
+			return { added: [], removed: [], modified: false };
+		}
+		await atomicWrite(gitignorePath, `${out.join("\n")}\n`);
+		return { added: toAdd, removed, modified: true };
+	});
+}
+
 /**
  * Check which expected entries are missing from a .gitignore file.
  *