magus-cli 7.5.0 → 7.5.2

package/src/services/profile-live.ts

@@ -49,7 +49,7 @@ import { createHash } from "node:crypto";
 import type { Stats } from "node:fs";
 import path from "node:path";
 import fs from "fs-extra";
-import type { ProfileManifestEntry } from "../types/index.js";
+import type { DependencyReport, ProfileManifestEntry } from "../types/index.js";
 import { readManifest } from "./manifest.js";
 import { SettingsParseError } from "./settings-file.js";
 
@@ -174,6 +174,12 @@ export interface RenderedProfile {
 	 * profile does not enable was written as `false` by the render itself.
 	 */
 	allPluginIds: string[];
+	/**
+	 * What the profile's plugins depend on — derived ids (already enabled in
+	 * `settings`), unreadable plugin.json files, and dependencies the profile
+	 * turns off. Absent when there is nothing to say.
+	 */
+	dependencies?: DependencyReport;
 }
 
 /** The exact bytes magus writes for a rendered file. */
@@ -245,6 +251,20 @@ export interface ActiveMarker {
 	 * enabledPlugins as that bookkeeping rather than as the user's edits.
 	 */
 	cliBookkeeping?: true;
+	/**
+	 * The plugin ids the flagged run installs — only a `true` for one of these
+	 * can be the CLI's record. `magus update` installs the active profile's
+	 * plugins alone, so a plugin of another profile's that the user enabled
+	 * during the run is theirs. Absent (an older flag), every profile's
+	 * recorded ids (`allPluginIds`) stand in.
+	 */
+	cliInstallable?: string[];
+	/**
+	 * The dependencies the last render enabled (`true`) though no profile entry
+	 * names them. A live `false` for one of these is the user's own disable —
+	 * the render never wrote it. Absent in a marker an older release wrote.
+	 */
+	derived?: string[];
 	/** sha256 of each live file exactly as magus last wrote or absorbed it. */
 	files: Partial<Record<LiveFileKey, string>>;
 	/** Magus-installed skill folders under `.claude/skills/`, with content hash. */
@@ -276,6 +296,8 @@ function parseMarker(raw: unknown): ActiveMarker | null {
 		skills,
 		allPluginIds,
 		cliBookkeeping,
+		cliInstallable,
+		derived,
 	} = raw;
 	if (!isSegment(profile)) return null;
 	const hashes: ActiveMarker["files"] = {};
@@ -308,6 +330,15 @@ function parseMarker(raw: unknown): ActiveMarker | null {
 		marker.allPluginIds = allPluginIds as string[];
 	}
 	if (cliBookkeeping === true) marker.cliBookkeeping = true;
+	if (
+		Array.isArray(cliInstallable) &&
+		cliInstallable.every((id) => typeof id === "string")
+	) {
+		marker.cliInstallable = cliInstallable as string[];
+	}
+	if (Array.isArray(derived) && derived.every((id) => typeof id === "string")) {
+		marker.derived = derived as string[];
+	}
 	return marker;
 }
 
@@ -381,16 +412,21 @@ export async function writeActiveMarker(
  */
 export function markerFor(
 	profile: string,
-	rendered: Pick<RenderedProfile, "entry" | "definition" | "allPluginIds">,
+	rendered: Pick<
+		RenderedProfile,
+		"entry" | "definition" | "allPluginIds" | "dependencies"
+	>,
 	files: ActiveMarker["files"],
 	skills: Record<string, string>,
 ): ActiveMarker {
+	const derived = rendered.dependencies?.derived ?? [];
 	return {
 		version: 1,
 		profile,
 		definition: rendered.definition,
 		base: rendered.entry,
 		allPluginIds: rendered.allPluginIds,
+		...(derived.length > 0 ? { derived } : {}),
 		files,
 		skills,
 	};
@@ -557,6 +593,13 @@ export async function writeLiveFile(
 	key: LiveFileKey,
 	content: Record<string, unknown> | null,
 	projectPath?: string,
+	/**
+	 * The machine-local settings keys to carry, when the caller read them
+	 * before the live file moved — first adoption displaces it to a backup
+	 * before this runs, and reading it here then would find nothing. Omitted,
+	 * they are read from the live file as it is now.
+	 */
+	carry?: Record<string, unknown>,
 ): Promise<string | null> {
 	const file = livePath(key, projectPath);
 	// Backstop for the callers' own checks: never replace a regular file that
@@ -571,12 +614,11 @@ export async function writeLiveFile(
 	}
 	let body = content;
 	if (key === "settings") {
-		// Through a link too: an older layout's settings.json carries them.
-		const live = (await readLiveThrough("settings", projectPath)).value;
-		if (live) {
+		const keep = carry ?? (await machineLocalSettings(projectPath));
+		if (Object.keys(keep).length > 0) {
 			body = { ...content };
-			for (const k of MACHINE_LOCAL_SETTINGS_KEYS) {
-				if (k in live && !(k in body)) body[k] = live[k];
+			for (const [k, value] of Object.entries(keep)) {
+				if (!(k in body)) body[k] = value;
 			}
 		}
 	}
@@ -585,6 +627,23 @@ export async function writeLiveFile(
 	return sha256(bytes);
 }
 
+/**
+ * The machine-local keys (see {@link MACHINE_LOCAL_SETTINGS_KEYS}) the live
+ * settings.json holds now — read through an older layout's link too. Empty
+ * when there is no readable file.
+ */
+export async function machineLocalSettings(
+	projectPath?: string,
+): Promise<Record<string, unknown>> {
+	const live = (await readLiveThrough("settings", projectPath)).value;
+	const out: Record<string, unknown> = {};
+	if (!live) return out;
+	for (const k of MACHINE_LOCAL_SETTINGS_KEYS) {
+		if (k in live) out[k] = live[k];
+	}
+	return out;
+}
+
 /** Write all three live files of `rendered`; returns their hashes. */
 export async function writeRenderedFiles(
 	rendered: RenderedProfile,

package/src/services/profile-render.ts

@@ -9,7 +9,15 @@
  * No installs and no global state, so it is testable with a temp dir.
  */
 
-import type { ProfileManifest, ResolvedClosure } from "../types/index.js";
+import type {
+	DependencyReport,
+	ProfileManifest,
+	ResolvedClosure,
+} from "../types/index.js";
+import {
+	type PluginDependencyReader,
+	readPluginDependencies,
+} from "./plugin-dependencies.js";
 import { type RenderedProfile, canonicalJson, sha256 } from "./profile-live.js";
 import { resolveAllProfiles, resolveProfile } from "./resolver.js";
 
@@ -27,6 +35,12 @@ import { resolveAllProfiles, resolveProfile } from "./resolver.js";
  * the id — an id a scope omits falls through to the next one, so a non-member
  * enabled at user scope would otherwise stay enabled here. A plugin the
  * profile itself declares `false` is written as `false` for the same reason.
+ *
+ * `closure.plugins` already holds every plugin an enabled one depends on, so
+ * a dependency is written `true` even when another profile lists it — Claude
+ * Code will not load a plugin whose dependency is disabled. The one exception
+ * is a dependency the profile itself turns off: its `false` stands, and
+ * {@link describeDependencies} says which plugin will not load.
  */
 export function buildProfileSettings(
 	closure: ResolvedClosure,
@@ -54,11 +68,53 @@ export function buildProfileMcp(closure: ResolvedClosure): {
 
 /**
  * Rendering needs no binary requirements — nothing it writes reads
- * `closure.bins` — and skipping the per-plugin `plugin.json` reads keeps it off
- * the marketplace cache entirely.
+ * `closure.bins` — so no plugin's `requires.bin` is read.
  */
 const noBins = async () => [];
 
+/**
+ * One read per plugin per render: the render resolves this profile and then
+ * every profile, and most plugins appear in both.
+ */
+function oncePerPlugin(read: PluginDependencyReader): PluginDependencyReader {
+	const seen = new Map<string, Promise<string[] | null>>();
+	return (pluginId) => {
+		let pending = seen.get(pluginId);
+		if (!pending) {
+			pending = read(pluginId);
+			seen.set(pluginId, pending);
+		}
+		return pending;
+	};
+}
+
+/**
+ * What a profile's dependencies mean for the person running it, one line
+ * each: a plugin that will not load because the profile turns off something
+ * it depends on, and plugins whose plugin.json could not be read here.
+ */
+export function describeDependencies(
+	report: DependencyReport | undefined,
+	profile: string,
+): string[] {
+	const lines: string[] = [];
+	for (const { plugin, dependency } of report?.blocked ?? []) {
+		lines.push(
+			`${plugin} will not load: it depends on ${dependency}, which profile "${profile}" turns off — remove "${dependency}": false from the profile to let it load`,
+		);
+	}
+	const unreadable = report?.unreadable ?? [];
+	if (unreadable.length > 0) {
+		const one = unreadable.length === 1;
+		lines.push(
+			`Could not read the plugin.json of ${unreadable.join(", ")} on this machine, so nothing ${
+				one ? "it depends" : "they depend"
+			} on was enabled — run \`magus install\` to fetch ${one ? "it" : "them"}`,
+		);
+	}
+	return lines;
+}
+
 /**
  * The hash of everything a profile's live config is rendered from.
  *
@@ -68,7 +124,9 @@ const noBins = async () => [];
  * teammate adding a plugin to another profile changes this profile's
  * settings.json. Hashing only the entry would leave that change unrendered
  * until the next switch. Install-only fields (`bins`, `env`, cross-profile
- * version conflicts) are left out: they change no live file.
+ * version conflicts) are left out: they change no live file. Dependencies are
+ * in: they are part of `closure.plugins`, so a plugin.json that starts or
+ * stops declaring one changes the definition and the live config regenerates.
  */
 function renderDefinition(
 	closure: ResolvedClosure,
@@ -96,11 +154,19 @@ function renderDefinition(
 export async function renderProfile(
 	manifest: ProfileManifest,
 	name: string,
+	/** Whose installed plugins' dependencies count (default: the current directory). */
+	projectPath?: string,
 ): Promise<RenderedProfile> {
 	const entry = manifest.profiles[name];
 	if (!entry) throw new Error(`Profile "${name}" not found in manifest`);
-	const closure = await resolveProfile(manifest, name, { binResolver: noBins });
-	const union = await resolveAllProfiles(manifest, { binResolver: noBins });
+	const opts = {
+		binResolver: noBins,
+		dependencyResolver: oncePerPlugin((id) =>
+			readPluginDependencies(id, projectPath),
+		),
+	};
+	const closure = await resolveProfile(manifest, name, opts);
+	const union = await resolveAllProfiles(manifest, opts);
 	const allPluginIds = Object.keys(union.plugins);
 	return {
 		settings: buildProfileSettings(closure, allPluginIds),
@@ -111,5 +177,6 @@ export async function renderProfile(
 		entry,
 		definition: renderDefinition(closure, allPluginIds),
 		allPluginIds: [...allPluginIds].sort(),
+		...(closure.dependencies ? { dependencies: closure.dependencies } : {}),
 	};
 }

package/src/services/profile-skills.ts

@@ -38,6 +38,7 @@ import {
 	skillsRoot,
 } from "./profile-live.js";
 import { installSkill, skillFolderName } from "./skills-manager.js";
+import { trackedPaths } from "./tracked-live-files.js";
 
 /** Installs one profile skill into `.claude/skills/<folder>/`. */
 export type SkillInstaller = (
@@ -124,11 +125,13 @@ export async function findSkillClashes(
 	skills: readonly ProfileSkillRef[],
 	managed: Readonly<Record<string, string>>,
 	projectPath: string,
+	/** Folders the team committed: the listed skill IS that copy, not a clash. */
+	committed: ReadonlySet<string> = new Set(),
 ): Promise<SkillClash[]> {
 	const clashes: SkillClash[] = [];
 	for (const ref of skills) {
 		const folder = skillFolder(ref);
-		if (folder in managed) continue;
+		if (folder in managed || committed.has(folder)) continue;
 		if (await exists(path.join(skillsRoot(projectPath), folder))) {
 			clashes.push({ skill: ref.name, folder });
 		}
@@ -162,6 +165,8 @@ export async function syncSkills(
 	managed: Readonly<Record<string, string>>,
 	projectPath: string,
 	install: SkillInstaller = installProfileSkill,
+	/** Folders the team committed: never installed into, even when missing. */
+	committed: ReadonlySet<string> = new Set(),
 ): Promise<SkillSyncResult> {
 	const root = skillsRoot(projectPath);
 	const wanted = new Map<string, ProfileSkillRef>();
@@ -197,6 +202,8 @@ export async function syncSkills(
 		// Present but not ours (or ours and since edited): never overwritten.
 		// Clashes are refused before this runs; this is the backstop.
 		if (await exists(dir)) continue;
+		// The team's committed copy, deleted in this checkout: git restores it.
+		if (recorded === undefined && committed.has(folder)) continue;
 		try {
 			await fs.ensureDir(root);
 			await install(ref, projectPath);
@@ -367,6 +374,24 @@ export async function convertLegacySkills(
 		);
 	}
 
+	const activeFolders =
+		linkedProfile !== null
+			? manifestSkillFolders(manifest, linkedProfile)
+			: new Set<string>();
+	// A folder the team committed under .claude/skills/ is the team's copy
+	// even when the profile lists it: it is restored as a custom skill, never
+	// recorded as magus-installed — which would make magus gitignore it, remove
+	// it on a switch, and tell the user to untrack a skill they committed.
+	// Asked before anything moves, so a git failure leaves the layout intact.
+	const skillsRel = path.relative(projectPath, root);
+	const committedDirs = await trackedPaths(
+		projectPath,
+		[],
+		[...activeFolders].map((folder) => path.join(skillsRel, folder)),
+	);
+	const committed = (folder: string) =>
+		committedDirs.has(path.join(skillsRel, folder));
+
 	// Where the link pointed: the skills the project was actually running.
 	let linkedDir: string | null = null;
 	if (linkedProfile !== null) {
@@ -416,14 +441,14 @@ export async function convertLegacySkills(
 		result.conflicts.push({ folder, kept: dest, other: inKeptLayout(src) });
 	};
 
-	const activeFolders =
-		linkedProfile !== null
-			? manifestSkillFolders(manifest, linkedProfile)
-			: new Set<string>();
-
 	if (linkedDir !== null) {
 		for (const folder of await subfolders(linkedDir)) {
-			await place(linkedDir, folder, "move", activeFolders.has(folder));
+			await place(
+				linkedDir,
+				folder,
+				"move",
+				activeFolders.has(folder) && !committed(folder),
+			);
 		}
 	}
 	for (const dir of await backupSkillDirs(projectPath)) {

package/src/services/profile-state.ts

@@ -41,6 +41,10 @@ import {
 	type ProfileChoice,
 	activateProfile,
 	activationNotes,
+	activeWritableSkillFolders,
+	assertNoTrackedWriteTargets,
+	writableSkillFolders,
+	writeRefusal,
 } from "./profile-activate.js";
 import { adoptCurrentProject } from "./profile-adopt.js";
 import {
@@ -69,6 +73,7 @@ import {
 	skillFolder,
 } from "./profile-skills.js";
 import type { SettingsParseError } from "./settings-file.js";
+import type { LiveFileRefusal } from "./tracked-live-files.js";
 
 export type ActiveProfileCheck =
 	| { state: "no-profiles" }
@@ -148,7 +153,7 @@ async function matchingProfiles(
 	const models = await readLiveJsonSafely("models", projectPath);
 	const matches: string[] = [];
 	for (const id of Object.keys(manifest.profiles)) {
-		const rendered = await renderProfile(manifest, id);
+		const rendered = await renderProfile(manifest, id, projectPath);
 		if (
 			jsonEqual(withoutMachineKeys(settings), rendered.settings) &&
 			jsonEqual(mcp, rendered.mcp) &&
@@ -184,7 +189,12 @@ async function restoreMarker(
 		if (hash) skills[folder] = hash;
 	}
 	await writeActiveMarker(
-		markerFor(profile, await renderProfile(manifest, profile), files, skills),
+		markerFor(
+			profile,
+			await renderProfile(manifest, profile, projectPath),
+			files,
+			skills,
+		),
 		projectPath,
 	);
 }
@@ -294,6 +304,11 @@ export interface ProfileStatePrep {
 	problems: string[];
 	/** The files behind `problems` that could not be parsed. */
 	unreadable: SettingsParseError[];
+	/**
+	 * Set when a file magus would write is tracked by git, or git could not
+	 * say: nothing ran, and `problems` holds its message.
+	 */
+	refusal?: LiveFileRefusal;
 }
 
 /**
@@ -307,6 +322,27 @@ export async function prepareProfileState(
 	projectPath: string,
 	opts: Pick<ActivateOptions, "installSkill"> = {},
 ): Promise<ProfileStatePrep> {
+	// A project with profiles whose live files — or the active profile's
+	// magus-installed skill folders — git tracks: every path below would write
+	// one of them (or the marker, or the manifest on the way), so nothing runs,
+	// not even the marker a unique match would restore.
+	const manifest = await readManifest(projectPath);
+	if (Object.keys(manifest.profiles).length > 0) {
+		const refusal = await writeRefusal(
+			projectPath,
+			await activeWritableSkillFolders(projectPath, manifest),
+		);
+		if (refusal) {
+			return {
+				check: await checkActiveProfile(projectPath, { restore: false }),
+				reconcile: null,
+				lines: [],
+				problems: [refusal.message],
+				unreadable: [],
+				refusal,
+			};
+		}
+	}
 	const check = await checkActiveProfile(projectPath);
 	const out: ProfileStatePrep = {
 		check,
@@ -415,7 +451,10 @@ export async function inspectProfileState(
 				);
 			}
 			const manifest = await readManifest(projectPath);
-			if ((await renderProfile(manifest, p)).definition !== marker.definition) {
+			if (
+				(await renderProfile(manifest, p, projectPath)).definition !==
+				marker.definition
+			) {
 				pending.push(
 					"profiles.json changed since the live config was generated — the next magus command regenerates it.",
 				);
@@ -478,12 +517,28 @@ export async function switchToProfile(
 	};
 
 	const before = await readManifest(projectPath);
-	if (!before.profiles[name]) {
+	const target = before.profiles[name];
+	if (!target) {
 		result.problems.push(
 			`Profile "${name}" not found. Available: ${Object.keys(before.profiles).join(", ")}`,
 		);
 		return result;
 	}
+	// Before the absorbs below write profiles.json: nothing at all is written
+	// when a live file this switch would write is tracked by git.
+	const marker = await readActiveMarker(projectPath);
+	const refusal = await writeRefusal(projectPath, [
+		...(await writableSkillFolders(
+			projectPath,
+			target.skills ?? [],
+			marker?.skills,
+		)),
+		...(await activeWritableSkillFolders(projectPath, before)),
+	]);
+	if (refusal) {
+		result.problems.push(refusal.message);
+		return result;
+	}
 
 	if (!take(await absorbBeforeConversion(projectPath, name))) return result;
 	const installSkill = { installSkill: opts.installSkill };
@@ -525,6 +580,20 @@ export async function applyProfileChoice(
 	projectPath: string,
 	opts: ActivateOptions = {},
 ): Promise<ActivationResult> {
+	// Nothing is written — not the adopted manifest, not an absorbed edit —
+	// when a live file this choice would write is tracked by git.
+	const skills =
+		choice.kind === "activate"
+			? (manifest.profiles[choice.id]?.skills ?? [])
+			: [];
+	await assertNoTrackedWriteTargets(
+		projectPath,
+		await writableSkillFolders(
+			projectPath,
+			skills,
+			(await readActiveMarker(projectPath))?.skills,
+		),
+	);
 	if (choice.kind === "activate") {
 		const absorbed: string[] = [];
 		let changed = false;
@@ -566,11 +635,19 @@ export async function prepareProfileWrite(
 	projectPath: string,
 ): Promise<ProfileStatePrep> {
 	const prep = await prepareProfileState(projectPath);
+	if (prep.refusal) throw prep.refusal;
 	refuseOnProblems(prep);
 	return prep;
 }
 
 export interface CliBookkeepingOptions {
+	/**
+	 * The plugin ids `work` installs. Only a `true` for one of these is taken
+	 * for the CLI's record; every other id in settings.json is the user's.
+	 * Recorded in the marker, so a killed run's next command applies the same
+	 * set. Omitted, every profile's plugins count.
+	 */
+	installable?: readonly string[];
 	/**
 	 * Runs after `work`, before the reconcile — for `magus update`, which must
 	 * record the skill folders it re-fetched before they are judged edited.
@@ -609,7 +686,14 @@ export async function withCliBookkeeping<T>(
 		? await readActiveMarker(projectPath)
 		: null;
 	if (!marker) return work();
-	await writeActiveMarker({ ...marker, cliBookkeeping: true }, projectPath);
+	await writeActiveMarker(
+		{
+			...marker,
+			cliBookkeeping: true,
+			...(opts.installable ? { cliInstallable: [...opts.installable] } : {}),
+		},
+		projectPath,
+	);
 	try {
 		return await work();
 	} finally {

package/src/services/profiles.ts

@@ -2,7 +2,7 @@ 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 { 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 ──────────────────────────────────────────────────────────────────────