magus-cli 7.4.0 → 7.5.0

package/src/services/profile-render.ts

@@ -0,0 +1,115 @@
+/**
+ * Render a profile's live config from the manifest, in memory.
+ *
+ * The output is what activation writes straight to `.claude/settings.json`,
+ * `.mcp.json` and `.claude/models.json`. Nothing is kept anywhere else: the
+ * manifest is the source, these are views of it. Skills are not rendered —
+ * they are installed (see `profile-skills.ts`).
+ *
+ * No installs and no global state, so it is testable with a temp dir.
+ */
+
+import type { ProfileManifest, ResolvedClosure } from "../types/index.js";
+import { type RenderedProfile, canonicalJson, sha256 } from "./profile-live.js";
+import { resolveAllProfiles, resolveProfile } from "./resolver.js";
+
+/**
+ * Build the settings.json contents for a profile: every resolved plugin
+ * enabled, merged with the profile's declared settings. The profile's settings
+ * win over the derived enabledPlugins only if it explicitly sets that key
+ * (it normally won't).
+ *
+ * `allPluginIds` is the manifest-wide union of plugins across every profile.
+ * Plugins in the union that this profile does NOT want are written as an
+ * explicit `false`, which is what makes `profile switch` exclusive rather than
+ * additive. Claude Code resolves enabledPlugins **per plugin id**, walking from
+ * the highest-precedence scope down and taking the first scope that mentions
+ * 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.
+ */
+export function buildProfileSettings(
+	closure: ResolvedClosure,
+	allPluginIds: readonly string[] = [],
+): Record<string, unknown> {
+	const enabledPlugins: Record<string, boolean> = {};
+	for (const pluginId of allPluginIds) {
+		enabledPlugins[pluginId] = false;
+	}
+	for (const pluginId of closure.disabledPlugins ?? []) {
+		enabledPlugins[pluginId] = false;
+	}
+	for (const pluginId of Object.keys(closure.plugins)) {
+		enabledPlugins[pluginId] = true;
+	}
+	return { enabledPlugins, ...closure.settings };
+}
+
+/** Build the .mcp.json contents for a profile. */
+export function buildProfileMcp(closure: ResolvedClosure): {
+	mcpServers: Record<string, unknown>;
+} {
+	return { mcpServers: { ...closure.mcpServers } };
+}
+
+/**
+ * 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.
+ */
+const noBins = async () => [];
+
+/**
+ * The hash of everything a profile's live config is rendered from.
+ *
+ * Not the entry alone. The resolved closure carries what the entry inherits
+ * through `extends` and the marketplaces its plugin ids imply, and the plugin
+ * ids of EVERY profile decide which `false` entries this one writes — so a
+ * 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.
+ */
+function renderDefinition(
+	closure: ResolvedClosure,
+	allPluginIds: readonly string[],
+): string {
+	return sha256(
+		canonicalJson({
+			marketplaces: closure.marketplaces,
+			plugins: closure.plugins,
+			disabledPlugins: [...(closure.disabledPlugins ?? [])].sort(),
+			settings: closure.settings,
+			mcpServers: closure.mcpServers,
+			models: closure.models ?? null,
+			skills: closure.skills,
+			allPluginIds: [...allPluginIds].sort(),
+		}),
+	);
+}
+
+/**
+ * The live settings.json, .mcp.json and models.json content of profile
+ * `name`, rendered from the manifest. The union of plugin ids across every
+ * profile is included so non-members are written as an explicit `false`.
+ */
+export async function renderProfile(
+	manifest: ProfileManifest,
+	name: 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 allPluginIds = Object.keys(union.plugins);
+	return {
+		settings: buildProfileSettings(closure, allPluginIds),
+		mcp: buildProfileMcp(closure),
+		models: closure.models
+			? (closure.models as unknown as Record<string, unknown>)
+			: null,
+		entry,
+		definition: renderDefinition(closure, allPluginIds),
+		allPluginIds: [...allPluginIds].sort(),
+	};
+}

package/src/services/profile-skills.ts

@@ -0,0 +1,462 @@
+/**
+ * The active profile's skills in `.claude/skills/`.
+ *
+ * `.claude/skills/` is a real directory holding two kinds of folder:
+ *
+ *   magus-installed   a skill the active profile lists (`skills` in
+ *                     profiles.json). Installed by magus, recorded in the
+ *                     marker with a content hash, gitignored by its own line.
+ *   custom            every other folder. Owned by git and the team. magus
+ *                     never moves, copies, backs up or deletes one.
+ *
+ * Switching removes only the magus-installed folders the new profile does not
+ * list, and installs the ones it does. A profile listing a skill whose folder
+ * already exists as a custom skill is refused before anything changes.
+ *
+ * A magus-installed folder whose contents no longer match the marker has been
+ * edited by someone, and magus stops managing it: it becomes a custom skill
+ * (see `profile-absorb.ts`).
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import type {
+	ProfileManifest,
+	ProfileSkillRef,
+	SkillInfo,
+} from "../types/index.js";
+import { updateManagedGitignoreBlock } from "./conventions-manager.js";
+import {
+	PROFILE_GITIGNORE_COMMENT,
+	backupRoot,
+	backupStamp,
+	folderHash,
+	isSegment,
+	legacyProfileDirs,
+	legacyProfilesRoot,
+	profileLinkTarget,
+	skillsRoot,
+} from "./profile-live.js";
+import { installSkill, skillFolderName } from "./skills-manager.js";
+
+/** Installs one profile skill into `.claude/skills/<folder>/`. */
+export type SkillInstaller = (
+	ref: ProfileSkillRef,
+	projectPath: string,
+) => Promise<void>;
+
+/** Map a manifest skill ref to the SkillInfo shape installSkill expects. */
+export function toSkillInfo(ref: ProfileSkillRef): SkillInfo {
+	return {
+		id: `${ref.repo}/${ref.path}`,
+		name: ref.name,
+		source: {
+			label: ref.repo,
+			repo: ref.repo,
+			skillsPath: path.dirname(ref.path),
+		},
+		repoPath: ref.path,
+		gitBlobSha: "",
+		frontmatter: null,
+		installed: false,
+		installedScope: null,
+		hasUpdate: false,
+	};
+}
+
+/** The real installer: fetches the skill from GitHub into the project. */
+export const installProfileSkill: SkillInstaller = async (ref, projectPath) => {
+	await installSkill(toSkillInfo(ref), "project", projectPath);
+};
+
+/** The folder under `.claude/skills/` a profile skill installs into. */
+export function skillFolder(ref: ProfileSkillRef): string {
+	return skillFolderName(ref.name);
+}
+
+/** The gitignore line for one magus-installed skill folder. */
+export function skillIgnoreLine(folder: string): string {
+	return `.claude/skills/${folder}/`;
+}
+
+async function exists(p: string): Promise<boolean> {
+	try {
+		await fs.lstat(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ─── Clashes ─────────────────────────────────────────────────────────────────
+
+/** A profile skill whose folder is already taken by a custom skill. */
+export interface SkillClash {
+	skill: string;
+	folder: string;
+}
+
+/** Thrown before anything changes when a profile's skill would overwrite a custom one. */
+export class SkillClashError extends Error {
+	constructor(
+		readonly profile: string,
+		readonly clashes: SkillClash[],
+	) {
+		super(
+			[
+				`Cannot activate profile "${profile}": it lists ${clashes.length === 1 ? "a skill" : "skills"} whose folder is already a custom skill.`,
+				...clashes.map(
+					(c) =>
+						`  profile skill "${c.skill}"  vs  custom skill .claude/skills/${c.folder}/`,
+				),
+				"Rename or remove one of each pair, then try again. Nothing was changed.",
+			].join("\n"),
+		);
+		this.name = "SkillClashError";
+	}
+}
+
+/**
+ * The profile skills whose folder exists and is NOT magus-installed.
+ * `managed` is the marker's skills map.
+ */
+export async function findSkillClashes(
+	skills: readonly ProfileSkillRef[],
+	managed: Readonly<Record<string, string>>,
+	projectPath: string,
+): Promise<SkillClash[]> {
+	const clashes: SkillClash[] = [];
+	for (const ref of skills) {
+		const folder = skillFolder(ref);
+		if (folder in managed) continue;
+		if (await exists(path.join(skillsRoot(projectPath), folder))) {
+			clashes.push({ skill: ref.name, folder });
+		}
+	}
+	return clashes;
+}
+
+// ─── Sync ────────────────────────────────────────────────────────────────────
+
+export interface SkillSyncResult {
+	/** The magus-installed folders now present, with content hash. */
+	skills: Record<string, string>;
+	installed: string[];
+	removed: string[];
+	/** Profile skills that could not be installed, with the reason. */
+	failed: Array<{ skill: string; reason: string }>;
+}
+
+/**
+ * Make `.claude/skills/` hold exactly the profile's skills, alongside whatever
+ * custom skills are there.
+ *
+ * A previously installed folder the profile no longer lists is removed only if
+ * it is unchanged since magus installed it; an edited one is left as a custom
+ * skill. A listed skill already installed and unchanged is kept as is — no
+ * re-fetch. A failed install leaves no half-written folder behind, since a
+ * folder magus does not record would read as a custom skill.
+ */
+export async function syncSkills(
+	skills: readonly ProfileSkillRef[],
+	managed: Readonly<Record<string, string>>,
+	projectPath: string,
+	install: SkillInstaller = installProfileSkill,
+): Promise<SkillSyncResult> {
+	const root = skillsRoot(projectPath);
+	const wanted = new Map<string, ProfileSkillRef>();
+	for (const ref of skills) {
+		const folder = skillFolder(ref);
+		if (isSegment(folder)) wanted.set(folder, ref);
+	}
+
+	const result: SkillSyncResult = {
+		skills: {},
+		installed: [],
+		removed: [],
+		failed: [],
+	};
+
+	for (const [folder, hash] of Object.entries(managed)) {
+		if (wanted.has(folder)) continue;
+		const dir = path.join(root, folder);
+		if ((await folderHash(dir)) === hash) {
+			await fs.remove(dir);
+			result.removed.push(folder);
+		}
+	}
+
+	for (const [folder, ref] of wanted) {
+		const dir = path.join(root, folder);
+		const recorded = managed[folder];
+		const current = await folderHash(dir);
+		if (recorded !== undefined && current === recorded) {
+			result.skills[folder] = recorded;
+			continue;
+		}
+		// 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;
+		try {
+			await fs.ensureDir(root);
+			await install(ref, projectPath);
+			const hash = await folderHash(dir);
+			if (hash === null) {
+				throw new Error(`nothing was installed into .claude/skills/${folder}`);
+			}
+			result.skills[folder] = hash;
+			result.installed.push(folder);
+		} catch (error) {
+			await fs.remove(dir);
+			result.failed.push({
+				skill: ref.name,
+				reason: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+	return result;
+}
+
+/**
+ * Magus-installed folders whose contents no longer match the marker (edited),
+ * and ones that are gone (missing).
+ */
+export async function inspectManagedSkills(
+	managed: Readonly<Record<string, string>>,
+	projectPath: string,
+): Promise<{ edited: string[]; missing: string[] }> {
+	const edited: string[] = [];
+	const missing: string[] = [];
+	for (const [folder, hash] of Object.entries(managed)) {
+		const current = await folderHash(
+			path.join(skillsRoot(projectPath), folder),
+		);
+		if (current === null) missing.push(folder);
+		else if (current !== hash) edited.push(folder);
+	}
+	return { edited, missing };
+}
+
+// ─── Gitignore ───────────────────────────────────────────────────────────────
+
+/**
+ * Keep one ignore line per magus-installed skill folder in magus's own
+ * `.gitignore` block: `before` are the folders the marker listed, `after` the
+ * ones it lists now. Lines are taken out of magus's block only — the same
+ * pattern a person wrote elsewhere in the file stays.
+ */
+export async function updateSkillIgnoreLines(
+	projectPath: string,
+	before: readonly string[],
+	after: readonly string[],
+): Promise<void> {
+	const keep = new Set(after);
+	await updateManagedGitignoreBlock(
+		path.join(projectPath, ".gitignore"),
+		PROFILE_GITIGNORE_COMMENT,
+		{
+			add: [...keep].map(skillIgnoreLine),
+			remove: before.filter((f) => !keep.has(f)).map(skillIgnoreLine),
+		},
+	);
+}
+
+// ─── Converting an older layout ──────────────────────────────────────────────
+
+export interface LegacySkillConversion {
+	/** True when there was anything to convert. */
+	converted: boolean;
+	/** Magus-installed skills carried over into `.claude/skills/`, with hash. */
+	managed: Record<string, string>;
+	/** Custom skills put back into `.claude/skills/`. */
+	restored: string[];
+	/** A custom skill found in two places with different contents; both kept. */
+	conflicts: Array<{ folder: string; kept: string; other: string }>;
+	/**
+	 * Where `.claude/_profiles/` is kept once activation finishes — see
+	 * {@link archiveOlderLayout} — or null when there is none to keep.
+	 */
+	keptAt: string | null;
+}
+
+/** Backup directories that hold a `skills/` dir, newest first. */
+async function backupSkillDirs(projectPath: string): Promise<string[]> {
+	let stamps: string[];
+	try {
+		stamps = await fs.readdir(backupRoot(projectPath));
+	} catch {
+		return [];
+	}
+	const out: string[] = [];
+	for (const stamp of stamps.sort().reverse()) {
+		const dir = path.join(backupRoot(projectPath), stamp, "skills");
+		try {
+			if ((await fs.lstat(dir)).isDirectory()) out.push(dir);
+		} catch {
+			// This backup holds no skills.
+		}
+	}
+	return out;
+}
+
+async function subfolders(dir: string): Promise<string[]> {
+	try {
+		const names = await fs.readdir(dir);
+		const out: string[] = [];
+		for (const name of names.sort()) {
+			if (!isSegment(name)) continue;
+			if ((await fs.lstat(path.join(dir, name))).isDirectory()) out.push(name);
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+function manifestSkillFolders(
+	manifest: ProfileManifest,
+	profile: string,
+): Set<string> {
+	return new Set((manifest.profiles[profile]?.skills ?? []).map(skillFolder));
+}
+
+/**
+ * Convert an older layout's skills: `.claude/skills` as a symlink into
+ * `.claude/_profiles/<n>/skills`, the layout magus 7.4.1 and earlier wrote.
+ *
+ * The link is replaced by a real directory. The linked profile's own skills
+ * move into it as magus-installed. Every other skill folder found in the old
+ * profile directories or in `.claude/.magus-backups/*\/skills/` (newest first)
+ * that is not one of that profile's manifest skills goes back as a CUSTOM
+ * skill, byte for byte — those are the committed skills the old layout
+ * displaced when it seeded them into a profile, which is why git showed them as
+ * deleted. An existing folder is never overwritten; one that differs from a
+ * candidate is reported with both paths. Backups are copied from, never
+ * modified.
+ *
+ * Nothing is deleted. What remains of `.claude/_profiles/` — the settings,
+ * MCP and routing files Claude Code may have written through the old links,
+ * other profiles' skills, the older marker — is moved whole into
+ * `.claude/.magus-backups/<stamp>-layout/` by {@link archiveOlderLayout} once
+ * activation has written the new files. `keptAt` names that path.
+ */
+export async function convertLegacySkills(
+	manifest: ProfileManifest,
+	projectPath: string,
+): Promise<LegacySkillConversion> {
+	const result: LegacySkillConversion = {
+		converted: false,
+		managed: {},
+		restored: [],
+		conflicts: [],
+		keptAt: null,
+	};
+	const root = skillsRoot(projectPath);
+	const legacyRoot = legacyProfilesRoot(projectPath);
+	const oldDirs = await legacyProfileDirs(projectPath);
+	const linkedProfile = await profileLinkTarget(root, projectPath);
+	const hasLegacyRoot = await exists(legacyRoot);
+	if (linkedProfile === null && oldDirs.length === 0 && !hasLegacyRoot) {
+		return result;
+	}
+	result.converted = true;
+	if (hasLegacyRoot) {
+		result.keptAt = path.join(
+			backupRoot(projectPath),
+			`${backupStamp()}-layout`,
+		);
+	}
+
+	// Where the link pointed: the skills the project was actually running.
+	let linkedDir: string | null = null;
+	if (linkedProfile !== null) {
+		linkedDir = path.resolve(path.dirname(root), await fs.readlink(root));
+		await fs.remove(root);
+	}
+	const preexisting = new Set(await subfolders(root));
+	await fs.ensureDir(root);
+	const placed = new Map<string, string>();
+	/** Where `src`, inside `_profiles/`, will be once the layout is kept. */
+	const inKeptLayout = (src: string): string =>
+		result.keptAt && src.startsWith(legacyRoot + path.sep)
+			? path.join(result.keptAt, path.relative(legacyRoot, src))
+			: src;
+
+	const place = async (
+		from: string,
+		folder: string,
+		mode: "move" | "copy",
+		asManaged: boolean,
+	): Promise<void> => {
+		const src = path.join(from, folder);
+		const dest = path.join(root, folder);
+		if (!(await exists(dest))) {
+			if (mode === "move") await fs.move(src, dest);
+			else await fs.copy(src, dest, { preserveTimestamps: true });
+			placed.set(folder, src);
+			if (asManaged) {
+				const hash = await folderHash(dest);
+				if (hash) result.managed[folder] = hash;
+			} else {
+				result.restored.push(folder);
+			}
+			return;
+		}
+		// Already there, and identical: nothing to keep.
+		if ((await folderHash(dest)) === (await folderHash(src))) return;
+		// A backup is never modified, so an older backup copy losing to a newer
+		// one placed by this conversion loses nothing: newest wins, silently.
+		if (mode === "copy") {
+			if (placed.has(folder) && !preexisting.has(folder)) return;
+			result.conflicts.push({ folder, kept: dest, other: src });
+			return;
+		}
+		// A differing copy inside an old profile directory stays where it is,
+		// and goes into the kept layout with the rest of `_profiles/`.
+		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));
+		}
+	}
+	for (const dir of await backupSkillDirs(projectPath)) {
+		for (const folder of await subfolders(dir)) {
+			if (activeFolders.has(folder)) continue;
+			await place(dir, folder, "copy", false);
+		}
+	}
+	for (const { name, dir } of oldDirs) {
+		const skills = path.join(dir, "skills");
+		if (linkedDir !== null && path.resolve(skills) === linkedDir) continue;
+		const own = manifestSkillFolders(manifest, name);
+		for (const folder of await subfolders(skills)) {
+			if (own.has(folder)) continue;
+			await place(skills, folder, "move", false);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Move what remains of `.claude/_profiles/` to `keptAt`, whole. Never a
+ * delete: it may hold the only copy of an edit Claude Code wrote through an
+ * old link. Called by activation after the new live files are written, so a
+ * failure part-way leaves the old layout readable.
+ */
+export async function archiveOlderLayout(
+	projectPath: string,
+	keptAt: string | null,
+): Promise<void> {
+	const legacyRoot = legacyProfilesRoot(projectPath);
+	if (!keptAt || !(await exists(legacyRoot))) return;
+	await fs.ensureDir(path.dirname(keptAt));
+	await fs.move(legacyRoot, keptAt, { overwrite: false });
+}