magus-cli 7.5.0 → 7.5.1

package/src/services/resolver.ts

@@ -5,7 +5,8 @@
  * marketplaces, plugins, MCP servers, binary deps, skills, settings, and env a
  * machine must have to match the profile. Binary deps are the union of the
  * profile's own `cliTools` and every enabled plugin's declared `requires.bin`,
- * deduped by executable name with the project's pin winning.
+ * deduped by executable name with the project's pin winning. Plugins include
+ * every plugin an enabled one declares as a dependency, transitively.
  */
 
 import semver from "semver";
@@ -14,12 +15,17 @@ import { getMarketplaceByName } from "../data/marketplaces.js";
 import { PREDEFINED_PROFILES } from "../data/predefined-profiles.js";
 import type {
 	BinRequirement,
+	DependencyReport,
 	ProfileManifest,
 	ProfileManifestEntry,
 	ResolvedBin,
 	ResolvedClosure,
 } from "../types/index.js";
 import { readManifest } from "./manifest.js";
+import {
+	type PluginDependencyReader,
+	readPluginDependencies,
+} from "./plugin-dependencies.js";
 import { resolvePluginBinRequirements } from "./plugin-requires.js";
 import { activeProfile } from "./profile-live.js";
 
@@ -29,6 +35,61 @@ export interface ResolveOptions {
 	 * tests; defaults to reading plugin.json from the marketplace cache.
 	 */
 	binResolver?: (pluginId: string) => Promise<BinRequirement[]>;
+	/**
+	 * Resolve a plugin id to the plugin ids its plugin.json declares as
+	 * dependencies, or null when it cannot be read. Defaults to reading the
+	 * plugin.json on this machine (`readPluginDependencies`).
+	 */
+	dependencyResolver?: PluginDependencyReader;
+}
+
+/**
+ * Every plugin the `enabled` plugins depend on, transitively, as their own
+ * plugin.json files declare it.
+ *
+ * Claude Code refuses to load a plugin whose dependency is not enabled, so a
+ * dependency is part of what a profile enables — derived, never written into
+ * profiles.json. A dependency the profile itself turns off (`off`) is left
+ * off and reported as `blocked`; nothing it depends on is followed. A plugin
+ * whose plugin.json cannot be read is reported as `unreadable` rather than
+ * guessed at.
+ */
+export async function resolveDependencies(
+	enabled: readonly string[],
+	off: ReadonlySet<string>,
+	read: PluginDependencyReader,
+): Promise<DependencyReport> {
+	const derived: string[] = [];
+	const unreadable: string[] = [];
+	const blocked: DependencyReport["blocked"] = [];
+	const queue = [...enabled];
+	const seen = new Set(enabled);
+	for (let id = queue.shift(); id !== undefined; id = queue.shift()) {
+		const dependencies = await read(id);
+		if (dependencies === null) {
+			unreadable.push(id);
+			continue;
+		}
+		for (const dependency of dependencies) {
+			if (off.has(dependency)) {
+				blocked.push({ plugin: id, dependency });
+				continue;
+			}
+			if (seen.has(dependency)) continue;
+			seen.add(dependency);
+			derived.push(dependency);
+			queue.push(dependency);
+		}
+	}
+	return { derived: derived.sort(), unreadable: unreadable.sort(), blocked };
+}
+
+function hasDependencies(report: DependencyReport): boolean {
+	return (
+		report.derived.length > 0 ||
+		report.unreadable.length > 0 ||
+		report.blocked.length > 0
+	);
 }
 
 /** Normalize a manifest plugins map to pluginId -> version ("latest" for true). */
@@ -234,16 +295,25 @@ export async function resolveProfile(
 	const binResolver = opts.binResolver ?? resolvePluginBinRequirements;
 
 	const plugins = normalizePlugins(entry.plugins);
-	const bins = await resolveBins(entry, Object.keys(plugins), binResolver);
-
 	const disabledPlugins = Object.entries(entry.plugins ?? {})
 		.filter(([, ver]) => ver === false)
 		.map(([id]) => id);
 
+	// The plugins the enabled ones need in order to load at all.
+	const dependencies = await resolveDependencies(
+		Object.keys(plugins),
+		new Set(disabledPlugins),
+		opts.dependencyResolver ?? readPluginDependencies,
+	);
+	for (const id of dependencies.derived) plugins[id] = "latest";
+
+	const bins = await resolveBins(entry, Object.keys(plugins), binResolver);
+
 	return {
 		marketplaces: withDerivedMarketplaces(entry.marketplaces, plugins),
 		plugins,
 		...(disabledPlugins.length > 0 ? { disabledPlugins } : {}),
+		...(hasDependencies(dependencies) ? { dependencies } : {}),
 		mcpServers: { ...(entry.mcpServers ?? {}) },
 		bins,
 		skills: [...(entry.skills ?? [])],
@@ -333,6 +403,9 @@ function mergeClosures(
 		}
 	}
 
+	// Dependency reports: union, for `install` and `doctor` to report.
+	const dependencies = mergeDependencyReports(a.dependencies, b.dependencies);
+
 	// Skills: union by repo+path.
 	const skillKey = (s: { repo: string; path: string }) => `${s.repo}#${s.path}`;
 	const skillMap = new Map(b.skills.map((s) => [skillKey(s), s]));
@@ -353,6 +426,26 @@ function mergeClosures(
 			optional: [...new Set([...a.env.optional, ...b.env.optional])],
 		},
 		...(conflicts.length > 0 ? { conflicts: [...new Set(conflicts)] } : {}),
+		...(dependencies ? { dependencies } : {}),
+	};
+}
+
+function mergeDependencyReports(
+	a: DependencyReport | undefined,
+	b: DependencyReport | undefined,
+): DependencyReport | undefined {
+	if (!a) return b;
+	if (!b) return a;
+	const blocked = new Map(
+		[...a.blocked, ...b.blocked].map((x) => [
+			`${x.plugin}\u0000${x.dependency}`,
+			x,
+		]),
+	);
+	return {
+		derived: [...new Set([...a.derived, ...b.derived])].sort(),
+		unreadable: [...new Set([...a.unreadable, ...b.unreadable])].sort(),
+		blocked: [...blocked.values()],
 	};
 }
 

package/src/services/tracked-live-files.ts

@@ -0,0 +1,125 @@
+/**
+ * magus never writes a generated file that git tracks.
+ *
+ * In a project with profiles, `.claude/settings.json`, `.mcp.json` and
+ * `.claude/models.json` are generated per developer from `.claude/profiles.json`.
+ * A committed copy is the team's hand-kept file: writing it leaves git
+ * tracking a file that now differs per developer, so every write shows as a
+ * modified tracked file and one developer's plugin set gets committed for
+ * everyone. `.gitignore` cannot fix that — it does not untrack a file already
+ * committed. So every writer refuses, having written nothing, and says how to
+ * stop tracking it; the user decides.
+ *
+ * Activation checks every path it would write up front (`profile-activate.ts`).
+ * This module holds the refusal itself, and the check for the writers outside
+ * activation: the TUI's direct settings edits, `.mcp.json` edits, and the
+ * Claude CLI's project-scope installs, which write `.claude/settings.json`.
+ */
+
+import path from "node:path";
+import { GitQueryError, trackedByGit } from "./git-worktree.js";
+import { getManifestPath, readProfilesFile } from "./manifest.js";
+
+/** magus refused to write a live file, and changed nothing. */
+export class LiveFileRefusal extends Error {}
+
+/** A live file magus would write is tracked by git. */
+export class TrackedLiveFileError extends LiveFileRefusal {
+	constructor(readonly paths: readonly string[]) {
+		const one = paths.length === 1;
+		super(
+			[
+				`magus will not write ${one ? "a file" : "files"} git tracks in this project — ${
+					one ? "it is" : "they are"
+				} generated from .claude/profiles.json and ${one ? "differs" : "differ"} per developer:`,
+				...paths.map((p) => `  ${p}`),
+				`Stop tracking ${one ? "it" : "them"}, commit, then run the command again:`,
+				...paths.map((p) => `  ${untrackCommand(p)}`),
+				'  git commit -m "Stop tracking generated Claude Code config"',
+				"Nothing was changed.",
+			].join("\n"),
+		);
+		this.name = "TrackedLiveFileError";
+	}
+}
+
+/**
+ * The project is a git work tree, but git could not say what it tracks — it
+ * timed out, is missing, or refused the repository (`detected dubious
+ * ownership`). Answering "nothing is tracked" would let magus write a tracked
+ * file, so it refuses instead and passes on git's own words.
+ */
+export class GitCheckError extends LiveFileRefusal {
+	constructor(readonly detail: string) {
+		super(
+			[
+				"magus could not check which files git tracks in this project, so it wrote nothing. git said:",
+				...detail
+					.trim()
+					.split("\n")
+					.map((line) => `  ${line}`),
+				"Fix that, then run the command again. Nothing was changed.",
+			].join("\n"),
+		);
+		this.name = "GitCheckError";
+	}
+}
+
+/** How to untrack one generated path — `-r` for a skill folder. */
+export function untrackCommand(rel: string): string {
+	const isDir =
+		rel.split(path.sep).length > 2 &&
+		rel.startsWith(path.join(".claude", "skills") + path.sep);
+	return isDir ? `git rm --cached -r ${rel}` : `git rm --cached ${rel}`;
+}
+
+/**
+ * Which of `files` (exact entries) and `dirs` (any file under them) git
+ * tracks, relative to `projectPath`. Empty outside a git work tree; throws
+ * {@link GitCheckError} when inside one and git cannot answer.
+ */
+export async function trackedPaths(
+	projectPath: string,
+	files: readonly string[],
+	dirs: readonly string[] = [],
+): Promise<Set<string>> {
+	try {
+		return await trackedByGit(projectPath, files, dirs);
+	} catch (error) {
+		if (error instanceof GitQueryError) throw new GitCheckError(error.detail);
+		throw error;
+	}
+}
+
+/**
+ * Does magus generate this project's live files — does its profiles.json
+ * define a profile? A profiles.json that cannot be read counts as yes: the
+ * check that follows only ever stops a write.
+ */
+async function hasProfiles(projectPath: string): Promise<boolean> {
+	try {
+		const file = await readProfilesFile(getManifestPath(projectPath));
+		return Object.keys(file.profiles).length > 0;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Throw {@link TrackedLiveFileError} — before anything is written — when
+ * `projectPath` has profiles and git tracks any of `files` (absolute, or
+ * relative to the project). A project without profiles owns its files by
+ * hand, and writing them is not magus's to refuse.
+ */
+export async function refuseTrackedLiveFiles(
+	projectPath: string,
+	files: readonly string[],
+): Promise<void> {
+	if (!(await hasProfiles(projectPath))) return;
+	const rel = files.map((f) =>
+		path.isAbsolute(f) ? path.relative(projectPath, f) : f,
+	);
+	const tracked = await trackedPaths(projectPath, rel);
+	const hit = rel.filter((r) => tracked.has(r));
+	if (hit.length > 0) throw new TrackedLiveFileError(hit);
+}

package/src/services/update-engine.ts

@@ -42,9 +42,11 @@ import type { PluginScope } from "./claude-cli.js";
 import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
 import {
 	type StaleLoadRepairResult,
+	loadedVersionHere,
 	repairStaleLoad,
 } from "./claude-settings.js";
 import {
+	isRepairablyBehind,
 	readInstalledVersionForScope,
 	saveInstalledPluginVersionForScope,
 } from "./plugin-manager.js";
@@ -181,6 +183,15 @@ export interface PluginApplyDeps {
 		target: string,
 		projectPath: string,
 	) => Promise<StaleLoadRepairResult>;
+	/**
+	 * The version Claude Code's loader resolves for a plugin in a project — the
+	 * question an install must ask afterwards (see {@link bringLoadForward}).
+	 * Optional so a test double that does not model the loader skips the check.
+	 */
+	loadedVersion?: (
+		pluginId: string,
+		projectPath: string,
+	) => Promise<string | null>;
 }
 
 export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
@@ -190,8 +201,47 @@ export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
 	readInstalled: readInstalledVersionForScope,
 	saveInstalled: saveInstalledPluginVersionForScope,
 	repairStaleLoad,
+	loadedVersion: loadedVersionHere,
 };
 
+/**
+ * After a plugin landed at `target` for `projectPath`: make sure that is the
+ * version Claude Code actually loads there, and bring the loader forward when
+ * it is not.
+ *
+ * The loader takes the FIRST registry row relevant to the repository, and rows
+ * from this repository's other checkouts — deleted worktrees included — often
+ * precede this project's own row. `claude plugin install|update` writes only
+ * this project's row, so a successful update could leave the plugin showing
+ * "updated" and loading the old version at once (measured: an update wrote
+ * 2.0.5 to this project's row while eight earlier rows held 2.0.4, and
+ * `--debug-file` showed 2.0.4 loading). So the update runs the stale-load
+ * repair as its own last step — the same `repairStaleLoad` the `stale-load`
+ * state uses, moving this repository's older rows forward to `target`.
+ *
+ * Null when nothing needed doing (the loader already resolves `target`, or the
+ * dep that asks it is absent); otherwise the repair's result, which the caller
+ * reports — `ok: false` means the plugin still does not load `target`.
+ */
+export async function bringLoadForward(
+	pluginId: string,
+	target: string,
+	projectPath: string,
+	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
+): Promise<StaleLoadRepairResult | null> {
+	if (!deps.loadedVersion) return null;
+	const loaded = await deps.loadedVersion(pluginId, projectPath);
+	if (!isRepairablyBehind(target, loaded)) return null;
+	return deps.repairStaleLoad(pluginId, target, projectPath);
+}
+
+/** The words for a load brought forward, appended to an item's detail. */
+function describeLoadForward(outcome: StaleLoadRepairResult): string {
+	return `Claude Code now loads v${outcome.target} here (${outcome.rewritten} older record${
+		outcome.rewritten === 1 ? "" : "s"
+	} moved forward)`;
+}
+
 // -- selection ---------------------------------------------------------------
 
 /**
@@ -448,7 +498,28 @@ export async function applyPlugins(
 				}
 			}
 			const noMove = pluginNoMove(item, landed);
-			if (noMove) {
+			// What landed here — the project row when there is one, since that is
+			// the row the loader must end up agreeing with.
+			const here =
+				landed.find(([scope]) => scope === "project")?.[1] ??
+				landed.find(([, actual]) => actual)?.[1] ??
+				null;
+			const forward = here
+				? await bringLoadForward(item.pluginId, here, projectPath, deps)
+				: null;
+			if (forward && !forward.ok) {
+				// Installed, but not what loads: that is not "updated". Reported as
+				// a failure with the repair's own reason, so nothing says current.
+				report.finish(
+					false,
+					item.pluginId,
+					`installed v${here}, but Claude Code still loads v${
+						forward.loaded ?? "an older version"
+					} here — ${forward.error ?? "the older records could not be moved forward"}`,
+					Date.now() - startedAt,
+				);
+				result.failed.push(item.pluginId);
+			} else if (noMove && !forward) {
 				report.finish(
 					true,
 					item.pluginId,
@@ -457,10 +528,11 @@ export async function applyPlugins(
 				);
 				result.unchanged.push(item.pluginId);
 			} else {
+				const moved = `${scopes.join(", ")}${item.target ? ` → ${item.target}` : ""}`;
 				report.finish(
 					true,
 					item.pluginId,
-					`${scopes.join(", ")}${item.target ? ` → ${item.target}` : ""}`,
+					forward ? `${moved} · ${describeLoadForward(forward)}` : moved,
 					Date.now() - startedAt,
 				);
 				result.ok++;
@@ -499,6 +571,19 @@ async function applyOneInScope(
 	await run(pluginId, scope);
 	const actual = await deps.readInstalled(pluginId, scope, projectPath);
 	if (actual) await deps.saveInstalled(pluginId, actual, scope, projectPath);
+	// The same last step as the apply loop, at every scope: installed must mean
+	// loaded here. `repairStaleLoad` itself refuses — and says why — when the
+	// winning record is not one this repository's rows can move.
+	if (actual) {
+		const forward = await bringLoadForward(pluginId, actual, projectPath, deps);
+		if (forward && !forward.ok) {
+			throw new Error(
+				`installed v${actual}, but Claude Code still loads v${
+					forward.loaded ?? "an older version"
+				} here — ${forward.error ?? "the older records could not be moved forward"}`,
+			);
+		}
+	}
 	return actual;
 }
 

package/src/types/index.ts

@@ -471,4 +471,23 @@ export interface ResolvedClosure {
 	env: { required: string[]; optional: string[] };
 	/** Cross-profile version conflicts detected while unioning profiles. */
 	conflicts?: string[];
+	/**
+	 * What the enabled plugins' own plugin.json files require — present when
+	 * anything was derived or could not be read. The derived ids are already
+	 * in `plugins`.
+	 */
+	dependencies?: DependencyReport;
+}
+
+/**
+ * The dependencies a profile's enabled plugins declare, resolved transitively.
+ * Derived, never recorded: profiles.json names none of them.
+ */
+export interface DependencyReport {
+	/** Enabled only because an enabled plugin depends on them. Sorted. */
+	derived: string[];
+	/** Enabled plugins whose plugin.json could not be read here. Sorted. */
+	unreadable: string[];
+	/** A dependency the profile itself turns off: `plugin` will not load. */
+	blocked: Array<{ plugin: string; dependency: string }>;
 }

package/src/ui/screens/PluginsScreen.tsx

@@ -44,6 +44,7 @@ import {
 	fetchPluginContents,
 	fetchPluginSkillDetail,
 } from "../../services/skills-manager.js";
+import { LiveFileRefusal } from "../../services/tracked-live-files.js";
 // The one update implementation, shared with `magus update`. See the header
 // of update-engine.ts for what drifted while the TUI had its own loop.
 import {
@@ -982,7 +983,11 @@ export function PluginsScreen() {
 				fetchData();
 			} catch (error) {
 				modal.hideModal();
-				await modal.message("Error", `Failed: ${error}`, "error");
+				await modal.message(
+					"Error",
+					error instanceof LiveFileRefusal ? error.message : `Failed: ${error}`,
+					"error",
+				);
 			}
 		}
 	};
@@ -1202,7 +1207,11 @@ export function PluginsScreen() {
 			fetchData();
 		} catch (error) {
 			modal.hideModal();
-			await modal.message("Error", `Failed: ${error}`, "error");
+			await modal.message(
+				"Error",
+				error instanceof LiveFileRefusal ? error.message : `Failed: ${error}`,
+				"error",
+			);
 		}
 	};
 

package/src/ui/screens/ProfilesScreen.tsx

@@ -26,6 +26,7 @@ import {
 	renameProfile,
 } from "../../services/profiles.js";
 import { writableMap } from "../../services/settings-file.js";
+import { LiveFileRefusal } from "../../services/tracked-live-files.js";
 import {
 	ClipboardUnavailableError,
 	readClipboard,
@@ -177,7 +178,9 @@ export function ProfilesScreen() {
 			modal.hideModal();
 			await modal.message(
 				"Error",
-				`Failed to apply profile: ${error}`,
+				error instanceof LiveFileRefusal
+					? error.message
+					: `Failed to apply profile: ${error}`,
 				"error",
 			);
 		}
@@ -242,7 +245,9 @@ export function ProfilesScreen() {
 				modal.hideModal();
 				await modal.message(
 					"Error",
-					`Failed to switch profile: ${error}`,
+					error instanceof LiveFileRefusal
+						? error.message
+						: `Failed to switch profile: ${error}`,
 					"error",
 				);
 			}
@@ -275,7 +280,9 @@ export function ProfilesScreen() {
 			modal.hideModal();
 			await modal.message(
 				"Error",
-				`Failed to apply profile: ${error}`,
+				error instanceof LiveFileRefusal
+					? error.message
+					: `Failed to apply profile: ${error}`,
 				"error",
 			);
 		}