magus-cli 7.4.1 → 7.5.1

package/src/services/profiles.ts

@@ -2,8 +2,8 @@ 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";
+import { readProfilesFile, writeJsonMinimal } from "./manifest.js";
+import { activeProfile } from "./profile-live.js";
 
 const PROFILES_FILE = "profiles.json";
 
@@ -64,10 +64,11 @@ async function writeProfiles(
 	projectPath?: string,
 ): Promise<void> {
 	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 });
+	// The refusal, and the file as read: only what the caller changed is
+	// written, every other byte kept. Diffed against the file's own `version`,
+	// so a v1 file is recorded as v2.
+	const current = await readProfilesFile(filePath);
+	await writeJsonMinimal(filePath, data, current);
 }
 
 // ─── CRUD ──────────────────────────────────────────────────────────────────────
@@ -150,38 +151,26 @@ export function toEnabledPlugins(
 }
 
 /**
- * Apply a profile: replaces enabledPlugins in the target settings scope.
- * targetScope is where the settings will be written, independent of where
- * the profile is stored.
+ * Apply a USER-scope profile — a template in `~/.claude/profiles.json` — to
+ * `~/.claude/settings.json`, replacing its enabledPlugins.
+ *
+ * User scope only, by construction. A project's live `.claude/settings.json`
+ * is rendered from its active profile in `.claude/profiles.json`; writing
+ * enabledPlugins into it directly is what made a TUI "apply" invisible to the
+ * profile and undone by the next render. A PROJECT profile is applied by
+ * switching to it (`switchToProfile` in `profile-state.ts`), the same path as
+ * `magus profile switch`.
  */
-export async function applyProfile(
-	profileId: string,
-	profileScope: "user" | "project",
-	targetScope: "user" | "project" | "local",
-	projectPath?: string,
-): Promise<void> {
-	const data = await readProfiles(profileScope, projectPath);
-	const profile = data.profiles[profileId];
-	if (!profile) throw new Error(`Profile "${profileId}" not found`);
-
-	// Import settings functions dynamically to avoid circular deps
-	const {
-		readSettings,
-		writeSettings,
-		readGlobalSettings,
-		writeGlobalSettings,
-	} = await import("./claude-settings.js");
-
-	if (targetScope === "user") {
-		const settings = await readGlobalSettings();
-		settings.enabledPlugins = toEnabledPlugins(profile.plugins);
-		await writeGlobalSettings(settings);
-	} else {
-		// project or local both write to project settings.json
-		const settings = await readSettings(projectPath);
-		settings.enabledPlugins = toEnabledPlugins(profile.plugins);
-		await writeSettings(settings, projectPath);
-	}
+export async function applyUserProfile(profile: {
+	plugins?: Record<string, string | boolean>;
+}): Promise<void> {
+	// Dynamic import: claude-settings reaches back into this module's callers.
+	const { readGlobalSettings, writeGlobalSettings } = await import(
+		"./claude-settings.js"
+	);
+	const settings = await readGlobalSettings();
+	settings.enabledPlugins = toEnabledPlugins(profile.plugins);
+	await writeGlobalSettings(settings);
 }
 
 /** Rename a profile in-place (preserves id, createdAt) */

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,14 +15,19 @@ 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 "./symlink-manager.js";
+import { activeProfile } from "./profile-live.js";
 
 export interface ResolveOptions {
 	/**
@@ -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,11 +295,25 @@ export async function resolveProfile(
 	const binResolver = opts.binResolver ?? resolvePluginBinRequirements;
 
 	const plugins = normalizePlugins(entry.plugins);
+	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 ?? [])],
@@ -328,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]));
@@ -348,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/settings-file.ts

@@ -3,11 +3,11 @@
  *
  * Two rules, and both exist because of damage they prevent:
  *
- *  1. **Write IN PLACE, never remove-and-recreate.** `.claude/settings.json` is
- *     a SYMLINK into `.claude/_profiles/<name>/` whenever a profile is active,
- *     and `writeFile` follows it — which is what we want. Unlinking the file
- *     first would break the link and silently detach the project from its
- *     profile, leaving the next read looking at a fresh, empty file.
+ *  1. **Write IN PLACE, never remove-and-recreate.** A settings file may be a
+ *     symlink somebody set up deliberately, and `writeFile` follows it — which
+ *     is what we want. Unlinking the file first would break the link and leave
+ *     the next read looking at a fresh, empty file. (magus's own profile files
+ *     are real files; `profile-live.ts` replaces them via a rename.)
  *  2. **Unparseable is an ERROR, not an empty object.** A settings file that
  *     fails to parse is a file we do not understand, usually because a human is
  *     mid-edit. Treating it as `{}` and writing our one key back is how a

package/src/services/skills-manager.ts

@@ -40,6 +40,18 @@ export function getProjectSkillsDir(projectPath?: string): string {
 	return path.join(projectPath ?? process.cwd(), ".claude", "skills");
 }
 
+/**
+ * The folder a skill installs into: a slug of its display name, since display
+ * names can carry slashes and spaces. One definition, because the profile code
+ * must predict exactly where `installSkill` will write.
+ */
+export function skillFolderName(name: string): string {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
 // ─── GitHub Tree API ──────────────────────────────────────────────────────────
 
 async function fetchGitTree(repo: string): Promise<GitTreeResponse> {
@@ -1003,10 +1015,7 @@ export async function installSkill(
 	}
 
 	// Use slug for directory name — display names can have slashes/spaces
-	const dirName = skill.name
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-|-$/g, "");
+	const dirName = skillFolderName(skill.name);
 
 	const installDir =
 		scope === "user"
@@ -1090,10 +1099,7 @@ export async function uninstallSkill(
 	scope: "user" | "project",
 	projectPath?: string,
 ): Promise<void> {
-	const dirName = skillName
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-|-$/g, "");
+	const dirName = skillFolderName(skillName);
 
 	const installDir =
 		scope === "user"

package/src/services/styles-manager.ts

@@ -19,12 +19,11 @@
  *
  * ## Profile awareness
  *
- * `.claude/settings.json` is a symlink into `.claude/_profiles/<name>/` when a
- * profile is active, so writing `outputStyle` through it lands in that
- * profile. But `materializeProfile` REWRITES that file from the manifest on
- * every `magus install`, so the live write alone silently regresses. The
- * selection is therefore also recorded in `.claude/profiles.json` under
- * `profiles.<name>.settings.outputStyle`, which is the durable source.
+ * `.claude/settings.json` is rendered from the active profile when there is
+ * one, so the selection is recorded in `.claude/profiles.json` under
+ * `profiles.<name>.settings.outputStyle` — the durable source — and the live
+ * file is rendered again from it. Without a profile the live file is edited in
+ * place.
  *
  * The generated style file is named per-profile (`composed-<name>`) so two
  * profiles can hold different styles without clobbering each other's file
@@ -43,8 +42,10 @@ import {
 	readManifest,
 	writeManifest,
 } from "./manifest.js";
+import { regenerateLiveFiles } from "./profile-activate.js";
+import { activeProfile } from "./profile-live.js";
+import { prepareProfileWrite } from "./profile-state.js";
 import { updateSettingsFile } from "./settings-file.js";
-import { activeProfile } from "./symlink-manager.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -188,7 +189,7 @@ export interface StylesSnapshot {
 	settingsPath: string;
 	/** Name of the generated style, e.g. "composed" or "composed-dev". */
 	styleName: string;
-	/** Active profile name, when .claude/settings.json is a profile symlink. */
+	/** Active profile name, when a profile is active (see `activeProfile`). */
 	profile: string | null;
 	/** The value currently in settings.json, whatever set it. */
 	currentOutputStyle: string | null;
@@ -1112,6 +1113,10 @@ export async function applyStyles({
 		throw new Error("Nothing selected. Pick at least one style.");
 	}
 
+	// The gate before anything is written: whatever Claude Code wrote to the
+	// live config goes into the profile, so the render below replaces nothing
+	// unrecorded — and a live file that does not parse stops everything.
+	await prepareProfileWrite(projectPath);
 	const profile = await activeProfile(projectPath);
 	const styleName = generatedStyleName(profile);
 	const stylePath = stylePathFor(projectPath, styleName);
@@ -1122,7 +1127,19 @@ export async function applyStyles({
 
 	await fs.ensureDir(path.dirname(stylePath));
 	await fs.writeFile(stylePath, contents, "utf8");
-	await setOutputStyle(settingsPath, styleName);
+
+	// With a profile active, the manifest is where the selection lives and the
+	// live file is rendered from it.
+	let recordedInManifest = false;
+	if (profile !== null) {
+		recordedInManifest = await recordInManifest(
+			projectPath,
+			profile,
+			styleName,
+		);
+	}
+	if (recordedInManifest) await regenerateLiveFiles(projectPath);
+	else await setOutputStyle(settingsPath, styleName);
 
 	// Verify by re-reading, not by trusting the write.
 	const verify = splitFrontmatter(await fs.readFile(stylePath, "utf8"));
@@ -1144,12 +1161,6 @@ export async function applyStyles({
 		throw new Error(`Verification failed — ${problems.join("; ")}`);
 	}
 
-	const recordedInManifest = await recordInManifest(
-		projectPath,
-		profile,
-		styleName,
-	);
-
 	// Write the declaration LAST, once the artifact is verified. It is the thing
 	// that gets committed and that teammates are told to match, so it must never
 	// claim a composition that failed to produce a valid file.
@@ -1268,6 +1279,25 @@ export async function createTeamStyle(
  */
 export async function clearStyle(projectPath: string): Promise<void> {
 	const settingsPath = settingsPathFor(projectPath);
+	// The gate first; a live file that does not parse stops everything.
+	await prepareProfileWrite(projectPath);
+	const profile = await activeProfile(projectPath);
+
+	if (profile !== null && (await fs.pathExists(getManifestPath(projectPath)))) {
+		const manifest = await readManifest(projectPath);
+		const entry = manifest.profiles[profile];
+		if (entry?.settings && "outputStyle" in entry.settings) {
+			// The guard above uses `in`, so assigning undefined would make a second
+			// call a no-op that still leaves the key serialized into profiles.json.
+			// biome-ignore lint/performance/noDelete: removal is the intent, not a shortcut
+			delete entry.settings.outputStyle;
+			entry.updatedAt = new Date().toISOString();
+			await writeManifest(manifest, projectPath);
+		}
+		await regenerateLiveFiles(projectPath);
+		return;
+	}
+
 	// The guard stays: a project that never had a style must not gain a
 	// settings.json just because the style was cleared.
 	if (await fs.pathExists(settingsPath)) {
@@ -1278,17 +1308,4 @@ export async function clearStyle(projectPath: string): Promise<void> {
 			delete settings.outputStyle;
 		});
 	}
-
-	const profile = await activeProfile(projectPath);
-	if (!profile) return;
-	if (!(await fs.pathExists(getManifestPath(projectPath)))) return;
-	const manifest = await readManifest(projectPath);
-	const entry = manifest.profiles[profile];
-	if (!entry?.settings || !("outputStyle" in entry.settings)) return;
-	// The guard above uses `in`, so assigning undefined would make a second call
-	// a no-op that still leaves the key serialized into profiles.json.
-	// biome-ignore lint/performance/noDelete: removal is the intent, not a shortcut
-	delete entry.settings.outputStyle;
-	entry.updatedAt = new Date().toISOString();
-	await writeManifest(manifest, projectPath);
 }

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