magus-cli 7.1.0 → 7.3.0

package/src/services/symlink-manager.ts

@@ -21,6 +21,7 @@
  * would ship to every teammate.
  */
 
+import type { Stats } from "node:fs";
 import path from "node:path";
 import fs from "fs-extra";
 
@@ -32,6 +33,7 @@ import fs from "fs-extra";
  */
 export const PROFILE_GITIGNORE_ENTRIES = [
 	".claude/_profiles/",
+	".claude/.magus-backups/",
 	".claude/settings.json",
 	".claude/skills",
 	".claude/models.json",
@@ -52,6 +54,30 @@ export function profileDir(name: string, projectPath?: string): string {
 /** The artifacts an active profile links into place. */
 export type ProfileLinkKey = "settings" | "skills" | "mcp" | "models";
 
+/**
+ * Where each linked artifact lives, and what it is called inside a profile.
+ *
+ * One table, because the link paths do NOT depend on which profile is active
+ * and two places listing them is two places to forget one. `linkTargets` adds
+ * the profile dir; `linkPaths` needs no profile at all.
+ */
+const LINKED_ARTIFACTS: Array<{
+	key: ProfileLinkKey;
+	/** Path segments under the project root. */
+	at: string[];
+	/** File or directory name inside `_profiles/<name>/`. */
+	inProfile: string;
+}> = [
+	{
+		key: "settings",
+		at: [".claude", "settings.json"],
+		inProfile: "settings.json",
+	},
+	{ key: "skills", at: [".claude", "skills"], inProfile: "skills" },
+	{ key: "mcp", at: [".mcp.json"], inProfile: "mcp.json" },
+	{ key: "models", at: [".claude", "models.json"], inProfile: "models.json" },
+];
+
 /** The set of links an active profile owns, as [linkPath, targetPath] pairs. */
 export function linkTargets(
 	name: string,
@@ -59,28 +85,121 @@ export function linkTargets(
 ): Array<{ key: ProfileLinkKey; link: string; target: string }> {
 	const base = projectPath ?? process.cwd();
 	const dir = profileDir(name, projectPath);
-	return [
-		{
-			key: "settings",
-			link: path.join(base, ".claude", "settings.json"),
-			target: path.join(dir, "settings.json"),
-		},
-		{
-			key: "skills",
-			link: path.join(base, ".claude", "skills"),
-			target: path.join(dir, "skills"),
-		},
-		{
-			key: "mcp",
-			link: path.join(base, ".mcp.json"),
-			target: path.join(dir, "mcp.json"),
-		},
-		{
-			key: "models",
-			link: path.join(base, ".claude", "models.json"),
-			target: path.join(dir, "models.json"),
-		},
-	];
+	return LINKED_ARTIFACTS.map(({ key, at, inProfile }) => ({
+		key,
+		link: path.join(base, ...at),
+		target: path.join(dir, inProfile),
+	}));
+}
+
+/** The paths activation writes links at, whichever profile is chosen. */
+export function linkPaths(projectPath?: string): string[] {
+	const base = projectPath ?? process.cwd();
+	return LINKED_ARTIFACTS.map(({ at }) => path.join(base, ...at));
+}
+
+/**
+ * Real artifacts that activating ANY profile would have to move aside.
+ *
+ * Empty means activating is lossless — a fresh clone, where the only things at
+ * these paths are nothing at all or links magus wrote itself. That is what
+ * makes it safe to honour the manifest's declared default without asking: there
+ * is no work of the user's to replace, so there is no decision to put to them.
+ *
+ * Non-empty means a human put something there, and the choice is theirs.
+ */
+export async function displaceableArtifacts(
+	projectPath?: string,
+): Promise<string[]> {
+	const found: string[] = [];
+	for (const link of linkPaths(projectPath)) {
+		// A link we own is generated state the manifest reproduces on demand.
+		if (await isProfileLink(link, projectPath)) continue;
+		try {
+			await fs.lstat(link);
+			found.push(link);
+		} catch {
+			// Nothing there.
+		}
+	}
+	return found;
+}
+
+/**
+ * Where activation moves a real file it had to displace.
+ *
+ * Beside `_profiles/`, never inside it. `_profiles/` is generated and is
+ * documented as regenerable from the manifest, so it is the first thing a
+ * cleanup — a user's, or ours — deletes. A backup stored there is the only copy
+ * of a hand-written file sitting in the one directory everybody is told is safe
+ * to remove. Gitignored all the same: these are recovery copies, not something
+ * to commit.
+ */
+export function backupRoot(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", ".magus-backups");
+}
+
+/** One artifact activation moved aside to make room for its symlink. */
+export interface DisplacedArtifact {
+	/** The path that is now a profile symlink. */
+	link: string;
+	/** Where its previous contents were moved. */
+	savedTo: string;
+}
+
+/** A directory name that sorts chronologically and is legal on every platform. */
+function backupStamp(): string {
+	return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Move whatever sits at `link` into `backupDir`, unless it is generated state.
+ *
+ * Activation replaces four paths with symlinks, and replacing means removing
+ * what is there. Three of those paths are ordinary files a project writes by
+ * hand and commits. `fs.remove` on `.claude/settings.json` is unrecoverable, and
+ * it ran on every activation — which is why adoption deliberately stopped short
+ * of activating and left migrations half-done.
+ *
+ * A symlink magus itself wrote is skipped: it points into `_profiles/`, which
+ * the manifest regenerates on demand, so copying it would archive nothing and
+ * every `profile switch` would leave another directory behind. A symlink
+ * pointing ANYWHERE ELSE is somebody's deliberate wiring and is preserved like
+ * a real file — the link is moved, never its target.
+ */
+async function displace(
+	link: string,
+	backupDir: string,
+	projectPath?: string,
+): Promise<DisplacedArtifact | null> {
+	if (await isProfileLink(link, projectPath)) return null;
+	let stat: Stats;
+	try {
+		stat = await fs.lstat(link);
+	} catch {
+		return null; // Nothing there — the common case on a first activation.
+	}
+	// The four link paths have four distinct basenames, so one flat directory
+	// holds a whole activation without collisions.
+	const savedTo = path.join(backupDir, path.basename(link));
+	await fs.ensureDir(backupDir);
+
+	if (stat.isSymbolicLink()) {
+		// A symlink's target is resolved against the directory the LINK sits in,
+		// so moving the link two levels deeper silently repoints it: a relative
+		// `../shared/mcp.json` that worked becomes dangling, and the "preserved"
+		// copy preserves nothing. Rewrite it as absolute at its original meaning.
+		const target = await fs.readlink(link);
+		const absolute = path.resolve(path.dirname(link), target);
+		await fs.remove(savedTo);
+		await fs.symlink(absolute, savedTo);
+		await fs.remove(link);
+		return { link, savedTo };
+	}
+
+	await fs.move(link, savedTo, { overwrite: true });
+	return { link, savedTo };
 }
 
 /**
@@ -100,20 +219,44 @@ async function relink(link: string, target: string): Promise<void> {
  * Activate a profile: repoint every shared-config symlink into its
  * materialized directory. Only links whose target exists in the profile dir
  * are created (e.g. a profile with no skills/ dir gets no skills symlink).
+ *
+ * Returns whatever had to be moved aside to make room — empty for an ordinary
+ * `profile switch`, one entry per hand-written artifact the first time a
+ * project adopts profiles. Callers report it so the move is never silent.
  */
 export async function activateProfile(
 	name: string,
 	projectPath?: string,
-): Promise<void> {
+	/**
+	 * Called the instant an artifact is moved, before the next link is touched.
+	 *
+	 * The return value alone is not enough, and the difference is data the user
+	 * cannot otherwise find: activation moves up to four artifacts in sequence,
+	 * so a throw on the second discards the array describing the first — leaving
+	 * `.claude/settings.json` gone from where they put it and no message saying
+	 * where it went. Reporting as it happens is what makes a half-finished
+	 * activation recoverable by hand.
+	 */
+	onDisplace?: (artifact: DisplacedArtifact) => void,
+): Promise<DisplacedArtifact[]> {
 	const dir = profileDir(name, projectPath);
 	if (!(await fs.pathExists(dir))) {
 		throw new Error(
 			`Profile "${name}" is not materialized (${dir} missing). Run \`magus install ${name}\`.`,
 		);
 	}
+	// One stamped directory per activation, so the four artifacts that were live
+	// together stay together and can be restored as the set they were.
+	const backupDir = path.join(backupRoot(projectPath), backupStamp());
+	const displaced: DisplacedArtifact[] = [];
 	for (const { link, target } of linkTargets(name, projectPath)) {
-		await syncLink(link, target, projectPath);
+		const moved = await syncLink(link, target, projectPath, backupDir);
+		if (moved) {
+			displaced.push(moved);
+			onDisplace?.(moved);
+		}
 	}
+	return displaced;
 }
 
 /**
@@ -124,13 +267,20 @@ export async function activateProfile(
 async function syncLink(
 	link: string,
 	target: string,
-	projectPath?: string,
-): Promise<void> {
+	projectPath: string | undefined,
+	// Required, not optional. An optional backup directory keeps a
+	// replace-without-backup path expressible, and that path is the whole defect
+	// this function was changed to close — a future caller omitting the argument
+	// would reintroduce it silently, and type-check clean while doing so.
+	backupDir: string,
+): Promise<DisplacedArtifact | null> {
 	if (await fs.pathExists(target)) {
+		const moved = await displace(link, backupDir, projectPath);
 		await relink(link, target);
-		return;
+		return moved;
 	}
 	if (await isProfileLink(link, projectPath)) await fs.remove(link);
+	return null;
 }
 
 /**
@@ -145,10 +295,14 @@ export async function syncProfileLink(
 	name: string,
 	key: ProfileLinkKey,
 	projectPath?: string,
-): Promise<void> {
+): Promise<DisplacedArtifact | null> {
 	const entry = linkTargets(name, projectPath).find((t) => t.key === key);
-	if (!entry) return;
-	await syncLink(entry.link, entry.target, projectPath);
+	if (!entry) return null;
+	// Backed up for the same reason activation is: `magus models use` on a
+	// project with a hand-written `.claude/models.json` would otherwise delete it
+	// as a side effect of choosing a model.
+	const backupDir = path.join(backupRoot(projectPath), backupStamp());
+	return syncLink(entry.link, entry.target, projectPath, backupDir);
 }
 
 /** Is `link` a symlink pointing into `.claude/_profiles/`? */

package/src/services/update-engine.ts

@@ -40,6 +40,10 @@ import { formatCommand } from "../utils/command-utils.js";
 import { runCommand } from "../utils/run.js";
 import type { PluginScope } from "./claude-cli.js";
 import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
+import {
+	type StaleLoadRepairResult,
+	repairStaleLoad,
+} from "./claude-settings.js";
 import {
 	readInstalledVersionForScope,
 	saveInstalledPluginVersionForScope,
@@ -165,6 +169,18 @@ export interface PluginApplyDeps {
 		scope: PluginScope,
 		projectPath: string,
 	) => Promise<void>;
+	/**
+	 * The `stale-load` repair — NOT a Claude Code command, and the only dep here
+	 * that is not. No `claude plugin` invocation can reach the registry rows that
+	 * cause a stale load, so this one edits `installed_plugins.json` directly;
+	 * `repairStaleLoad`'s own doc comment carries the full reasoning and the
+	 * user's approval of the exception.
+	 */
+	repairStaleLoad: (
+		pluginId: string,
+		target: string,
+		projectPath: string,
+	) => Promise<StaleLoadRepairResult>;
 }
 
 export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
@@ -173,6 +189,7 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
 	repair: repairPlugin,
 	readInstalled: readInstalledVersionForScope,
 	saveInstalled: saveInstalledPluginVersionForScope,
+	repairStaleLoad,
 };
 
 // -- selection ---------------------------------------------------------------
@@ -189,7 +206,18 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
  * project row stays untouched, so the same drift reappears on the next run.
  */
 function scopesToApply(item: PluginUpdateItem): PluginScope[] {
-	if (item.action === "current" || item.action === "unknown") return [];
+	// `stale-load` has no scopes, and that is not "skipped": it is applied by
+	// `repairStaleLoad`, which rewrites registry rows rather than installing
+	// anything, so there is no per-scope work to enumerate. A reinstall is
+	// measured NOT to clear it — it writes another row for this project while the
+	// row the loader picks belongs to a different one — which is exactly why it
+	// must not come through here. {@link pluginNeedsWork} counts it separately.
+	if (
+		item.action === "current" ||
+		item.action === "unknown" ||
+		item.action === "stale-load"
+	)
+		return [];
 	return item.action === "install" ? ["project"] : item.scopes;
 }
 
@@ -200,9 +228,12 @@ function scopesToApply(item: PluginUpdateItem): PluginScope[] {
  * predicate the loop applies. Re-deriving it at the call site is how the two
  * drift, and a bar that stops short of full at the end of a successful run
  * looks exactly like a hang.
+ *
+ * `stale-load` is work without scopes — see {@link scopesToApply} — so it is
+ * named here rather than counted through the scope list.
  */
 export function pluginNeedsWork(item: PluginUpdateItem): boolean {
-	return scopesToApply(item).length > 0;
+	return item.action === "stale-load" || scopesToApply(item).length > 0;
 }
 
 // -- plugins -----------------------------------------------------------------
@@ -277,6 +308,67 @@ function pluginNoMove(
 	return null;
 }
 
+/**
+ * Repair ONE broken plugin — the `stale-load` half of {@link applyPlugins}.
+ *
+ * Success is the repair's own POST-WRITE assertion (`StaleLoadRepairResult.ok`),
+ * never "the call returned". The whole class of bug this state reports is a
+ * version that looks right and does not load, so a repair that rewrote rows
+ * without changing what the loader resolves is a FAILURE and says so.
+ */
+async function applyStaleLoad(
+	item: PluginUpdateItem,
+	projectPath: string,
+	deps: PluginApplyDeps,
+	report: ApplyReporter,
+	result: PluginApplyResult,
+): Promise<void> {
+	report.begin(item.pluginId);
+	const startedAt = Date.now();
+	// The classifier sets this to the version installed here; a null one means
+	// there is nothing on disk to point the rows at, so there is no repair to run.
+	if (!item.target) {
+		report.finish(
+			false,
+			item.pluginId,
+			`no installed version to point ${item.pluginId}'s registry rows at`,
+			Date.now() - startedAt,
+		);
+		result.failed.push(item.pluginId);
+		return;
+	}
+	try {
+		const outcome = await deps.repairStaleLoad(
+			item.pluginId,
+			item.target,
+			projectPath,
+		);
+		if (outcome.ok) {
+			report.finish(
+				true,
+				item.pluginId,
+				`registry → v${outcome.target} (${outcome.rewritten} row${
+					outcome.rewritten === 1 ? "" : "s"
+				} moved forward)`,
+				Date.now() - startedAt,
+			);
+			result.ok++;
+		} else {
+			report.finish(
+				false,
+				item.pluginId,
+				outcome.error ?? `${item.pluginId} still does not load v${item.target}`,
+				Date.now() - startedAt,
+			);
+			result.failed.push(item.pluginId);
+		}
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		report.finish(false, item.pluginId, msg, Date.now() - startedAt);
+		result.failed.push(item.pluginId);
+	}
+}
+
 export async function applyPlugins(
 	items: PluginUpdateItem[],
 	projectPath: string,
@@ -291,6 +383,16 @@ export async function applyPlugins(
 	};
 
 	for (const item of items) {
+		// A stale load is repaired in the REGISTRY, not by any installer, so it
+		// leaves the scope loop entirely. Its own branch rather than a scope with a
+		// special case inside: everything below reads back a per-scope version and
+		// compares it against the catalog, and none of those questions applies to a
+		// row rewrite.
+		if (item.action === "stale-load") {
+			await applyStaleLoad(item, projectPath, deps, report, result);
+			continue;
+		}
+
 		const scopes = scopesToApply(item);
 		if (scopes.length === 0) continue;