magus-cli 7.4.1 → 7.5.0

package/src/services/profile-materializer.ts

@@ -1,133 +0,0 @@
-/**
- * Materialize a resolved profile into `.claude/_profiles/<name>/`.
- *
- * Writes the shared config the symlink manager later points at:
- *   _profiles/<name>/settings.json  — enabledPlugins + the profile's settings
- *   _profiles/<name>/mcp.json       — the profile's MCP servers
- *   _profiles/<name>/models.json    — per-subagent model routing, when the
- *                                     profile declares any; REMOVED when it
- *                                     does not
- *   _profiles/<name>/skills/        — created empty; skills install into it
- *                                     (through the activated symlink)
- *
- * This is pure output derived from a ResolvedClosure — it performs no installs
- * and touches no global state, so it is fully testable with a temp dir.
- */
-
-import path from "node:path";
-import fs from "fs-extra";
-import type { ResolvedClosure } from "../types/index.js";
-import { profileDir } from "./symlink-manager.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. Since
- * `magus install` installs the union at user scope, every non-member would
- * otherwise inherit that user-scope `true` and stay enabled while a profile
- * that excludes it is active. Omitting the union (the default) preserves the
- * old additive behavior for callers that have no cross-profile view.
- */
-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 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 } };
-}
-
-/**
- * Seed a profile's skills/ dir from the project's pre-existing `.claude/skills/`.
- *
- * Activating a profile replaces `.claude/skills` with a symlink into the profile
- * dir, and replacing means `fs.remove` first. A project that committed its own
- * skills before adopting profiles would lose them at that moment. So the first
- * time a profile's skills/ dir is created, any real (non-symlink) project skills
- * are copied in — every profile inherits what the project already had, and the
- * link swap destroys nothing.
- *
- * Only runs when the profile's skills/ dir does not exist yet, so it never
- * fights a later `skills-manager` install or re-adds a skill the user removed.
- */
-async function seedSkillsFromProject(
-	skillsDir: string,
-	projectPath?: string,
-): Promise<void> {
-	if (await fs.pathExists(skillsDir)) return;
-
-	const projectSkills = path.join(
-		projectPath ?? process.cwd(),
-		".claude",
-		"skills",
-	);
-	try {
-		// lstat, not pathExists: an existing profile symlink is not a source.
-		const stat = await fs.lstat(projectSkills);
-		if (!stat.isDirectory() || stat.isSymbolicLink()) return;
-		if ((await fs.readdir(projectSkills)).length === 0) return;
-		await fs.copy(projectSkills, skillsDir, { dereference: true });
-	} catch {
-		// No project skills dir (or unreadable) — nothing to carry over.
-	}
-}
-
-/**
- * Write `_profiles/<name>/` from a resolved closure. Idempotent: overwrites
- * settings.json / mcp.json and ensures skills/ exists. Returns the dir path.
- */
-export async function materializeProfile(
-	name: string,
-	closure: ResolvedClosure,
-	projectPath?: string,
-	allPluginIds: readonly string[] = [],
-): Promise<string> {
-	const dir = profileDir(name, projectPath);
-	await fs.ensureDir(dir);
-	await fs.writeJson(
-		path.join(dir, "settings.json"),
-		buildProfileSettings(closure, allPluginIds),
-		{ spaces: 2 },
-	);
-	await fs.writeJson(path.join(dir, "mcp.json"), buildProfileMcp(closure), {
-		spaces: 2,
-	});
-
-	// models.json is the one artifact that is REMOVED when the closure lacks it.
-	// Every other file here is unconditional, so "overwrite" is enough; routing
-	// is optional, and a profile that dropped it would otherwise keep routing
-	// from a file nothing writes any more — `magus models off` could not turn
-	// routing off, because the hook walks up to the nearest models.json and this
-	// one would still be there (and still linked).
-	const modelsPath = path.join(dir, "models.json");
-	if (closure.models) {
-		await fs.writeJson(modelsPath, closure.models, { spaces: 2 });
-	} else {
-		await fs.remove(modelsPath);
-	}
-
-	const skillsDir = path.join(dir, "skills");
-	await seedSkillsFromProject(skillsDir, projectPath);
-	await fs.ensureDir(skillsDir);
-	return dir;
-}

package/src/services/profile-sync.ts

@@ -1,158 +0,0 @@
-/**
- * `profile sync` — promote edits made to the active profile dir back into the
- * committed manifest.
- *
- * `.claude/_profiles/<name>/` is generated build output, so an edit to the
- * symlinked settings.json / mcp.json would be lost on the next `install`. Sync
- * reverse-materializes those files into `.claude/profiles.json` so the change
- * becomes a reviewable manifest diff instead of silent, throwaway drift.
- */
-
-import path from "node:path";
-import fs from "fs-extra";
-import type {
-	McpServerConfig,
-	ProfileManifest,
-	ProfileManifestEntry,
-} from "../types/index.js";
-import { readManifest, writeManifest } from "./manifest.js";
-import { profileDir } from "./symlink-manager.js";
-
-export interface SyncChange {
-	kind: "plugin-added" | "plugin-removed" | "settings-changed" | "mcp-changed";
-	detail: string;
-}
-
-/**
- * Merge a materialized profile's settings.json + mcp.json back into a manifest
- * entry. Pure: returns the updated entry and the list of changes.
- *
- * - enabledPlugins present but not in the entry -> added as "latest".
- * - entry plugins that are no longer enabled -> removed.
- * - an existing version PIN is preserved (enabled != downgrade-to-latest).
- * - non-enabledPlugins settings keys replace the entry's settings.
- * - mcpServers replace the entry's mcpServers when they differ.
- */
-export function computeSync(
-	entry: ProfileManifestEntry,
-	materializedSettings: Record<string, unknown>,
-	materializedMcp: { mcpServers?: Record<string, McpServerConfig> },
-	now: string = new Date().toISOString(),
-): { entry: ProfileManifestEntry; changes: SyncChange[] } {
-	const changes: SyncChange[] = [];
-	const next: ProfileManifestEntry = { ...entry };
-
-	const enabled = (materializedSettings.enabledPlugins ?? {}) as Record<
-		string,
-		boolean
-	>;
-	const currentPlugins = { ...(entry.plugins ?? {}) };
-
-	// Additions: enabled plugins the manifest doesn't list.
-	for (const [id, on] of Object.entries(enabled)) {
-		if (on && !(id in currentPlugins)) {
-			currentPlugins[id] = "latest";
-			changes.push({ kind: "plugin-added", detail: id });
-		}
-	}
-	// Removals: manifest plugins no longer enabled.
-	for (const id of Object.keys(entry.plugins ?? {})) {
-		if (!enabled[id]) {
-			delete currentPlugins[id];
-			changes.push({ kind: "plugin-removed", detail: id });
-		}
-	}
-	next.plugins = currentPlugins;
-
-	// Settings = everything in the materialized file except enabledPlugins.
-	const { enabledPlugins: _drop, ...settings } = materializedSettings;
-	if (JSON.stringify(settings) !== JSON.stringify(entry.settings ?? {})) {
-		if (Object.keys(settings).length > 0) next.settings = settings;
-		else {
-			// biome-ignore lint/performance/noDelete: the manifest entry is serialised to profiles.json and diffed with JSON.stringify/toStrictEqual; the key must be absent, not undefined
-			delete next.settings;
-		}
-		changes.push({ kind: "settings-changed", detail: "settings updated" });
-	}
-
-	// MCP servers.
-	const mcp = materializedMcp.mcpServers ?? {};
-	if (JSON.stringify(mcp) !== JSON.stringify(entry.mcpServers ?? {})) {
-		if (Object.keys(mcp).length > 0) next.mcpServers = mcp;
-		else {
-			// biome-ignore lint/performance/noDelete: the manifest entry is serialised to profiles.json and diffed with JSON.stringify/toStrictEqual; the key must be absent, not undefined
-			delete next.mcpServers;
-		}
-		changes.push({ kind: "mcp-changed", detail: "mcp servers updated" });
-	}
-
-	// Refresh the timestamp when anything changed. `now` is injectable so
-	// callers/tests control it (and computeSync stays pure).
-	if (changes.length > 0) next.updatedAt = now;
-
-	return { entry: next, changes };
-}
-
-/**
- * Detect drift between a materialized profile and the manifest WITHOUT writing.
- * Returns the changes `sync` would promote (empty = in sync). Returns [] if the
- * profile isn't materialized (nothing to lose).
- */
-export async function detectProfileDrift(
-	name: string,
-	projectPath?: string,
-): Promise<SyncChange[]> {
-	const manifest = await readManifest(projectPath);
-	const entry = manifest.profiles[name];
-	if (!entry) return [];
-
-	const dir = profileDir(name, projectPath);
-	const settingsPath = path.join(dir, "settings.json");
-	if (!(await fs.pathExists(settingsPath))) return [];
-
-	const mcpPath = path.join(dir, "mcp.json");
-	const materializedSettings = await fs.readJson(settingsPath);
-	const materializedMcp = (await fs.pathExists(mcpPath))
-		? await fs.readJson(mcpPath)
-		: { mcpServers: {} };
-
-	return computeSync(entry, materializedSettings, materializedMcp).changes;
-}
-
-/**
- * Read the materialized active profile, merge it into the manifest, and write
- * the manifest back if anything changed. Returns the applied changes.
- */
-export async function syncProfile(
-	name: string,
-	projectPath?: string,
-): Promise<{ changes: SyncChange[]; wrote: boolean }> {
-	const manifest: ProfileManifest = await readManifest(projectPath);
-	const entry = manifest.profiles[name];
-	if (!entry) throw new Error(`Profile "${name}" not found in manifest`);
-
-	const dir = profileDir(name, projectPath);
-	const settingsPath = path.join(dir, "settings.json");
-	const mcpPath = path.join(dir, "mcp.json");
-	if (!(await fs.pathExists(settingsPath))) {
-		throw new Error(
-			`Profile "${name}" isn't materialized (${settingsPath} missing).`,
-		);
-	}
-
-	const materializedSettings = await fs.readJson(settingsPath);
-	const materializedMcp = (await fs.pathExists(mcpPath))
-		? await fs.readJson(mcpPath)
-		: { mcpServers: {} };
-
-	const { entry: nextEntry, changes } = computeSync(
-		entry,
-		materializedSettings,
-		materializedMcp,
-	);
-	if (changes.length === 0) return { changes: [], wrote: false };
-
-	manifest.profiles[name] = nextEntry;
-	await writeManifest(manifest, projectPath);
-	return { changes, wrote: true };
-}

package/src/services/symlink-manager.ts

@@ -1,343 +0,0 @@
-/**
- * Profile symlink manager.
- *
- * Materialized profiles live at `.claude/_profiles/<name>/` (generated,
- * gitignored). The active profile is made "live" by symlinking the shared
- * config files into place:
- *
- *   .claude/settings.json  ->  .claude/_profiles/<name>/settings.json
- *   .claude/skills         ->  .claude/_profiles/<name>/skills
- *   .mcp.json              ->  .claude/_profiles/<name>/mcp.json
- *   .claude/models.json    ->  .claude/_profiles/<name>/models.json
- *
- * Switching profiles just repoints these links — no network, no reinstall.
- * settings.local.json is NEVER linked: it holds personal credentials and must
- * survive switches untouched.
- *
- * models.json is the one link whose target is OPTIONAL: a profile that declares
- * no routing has none, and the rule below (remove a link into _profiles/ whose
- * target is gone) is what keeps a dangling `.claude/models.json` out of the
- * repo. A dangling one would not be harmless — `.claude/` is committed, so it
- * would ship to every teammate.
- */
-
-import type { Stats } from "node:fs";
-import path from "node:path";
-import fs from "fs-extra";
-
-/**
- * Paths that must be gitignored once a project uses profiles: the generated
- * build output plus the active-profile symlinks. Only .claude/profiles.json is
- * the committed source of truth. settings.local.json is intentionally NOT here
- * (it's already gitignored elsewhere and holds personal credentials).
- */
-export const PROFILE_GITIGNORE_ENTRIES = [
-	".claude/_profiles/",
-	".claude/.magus-backups/",
-	".claude/settings.json",
-	".claude/skills",
-	".claude/models.json",
-	".mcp.json",
-];
-
-/** The generated, gitignored directory holding materialized profiles. */
-export function profilesRoot(projectPath?: string): string {
-	const base = projectPath ?? process.cwd();
-	return path.join(base, ".claude", "_profiles");
-}
-
-/** The materialized directory for one profile. */
-export function profileDir(name: string, projectPath?: string): string {
-	return path.join(profilesRoot(projectPath), name);
-}
-
-/** 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,
-	projectPath?: string,
-): Array<{ key: ProfileLinkKey; link: string; target: string }> {
-	const base = projectPath ?? process.cwd();
-	const dir = profileDir(name, projectPath);
-	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 };
-}
-
-/**
- * Point `link` at `target` with a relative symlink. Any existing file, dir, or
- * link at `link` is removed first. The target need not exist yet (dangling
- * links are tolerated so a profile can be activated before every artifact is
- * materialized), but its parent is created.
- */
-async function relink(link: string, target: string): Promise<void> {
-	await fs.ensureDir(path.dirname(link));
-	await fs.remove(link);
-	const rel = path.relative(path.dirname(link), target);
-	await fs.symlink(rel, link);
-}
-
-/**
- * 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,
-	/**
-	 * 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)) {
-		const moved = await syncLink(link, target, projectPath, backupDir);
-		if (moved) {
-			displaced.push(moved);
-			onDisplace?.(moved);
-		}
-	}
-	return displaced;
-}
-
-/**
- * Point one link at its target, or remove it when the profile has no such
- * artifact. A link is only removed when it points into `_profiles/` — a real
- * file the user put there is never clobbered.
- */
-async function syncLink(
-	link: string,
-	target: string,
-	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 moved;
-	}
-	if (await isProfileLink(link, projectPath)) await fs.remove(link);
-	return null;
-}
-
-/**
- * Sync ONE of the active profile's links, leaving the others alone.
- *
- * `activateProfile` repoints all four, which is right when switching profiles
- * and wrong when only one artifact changed: `magus models use` would replace
- * a project's real `.mcp.json` with a symlink as a side effect of choosing a
- * model. This is the narrow door for that case.
- */
-export async function syncProfileLink(
-	name: string,
-	key: ProfileLinkKey,
-	projectPath?: string,
-): Promise<DisplacedArtifact | null> {
-	const entry = linkTargets(name, projectPath).find((t) => t.key === key);
-	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/`? */
-async function isProfileLink(
-	link: string,
-	projectPath?: string,
-): Promise<boolean> {
-	try {
-		const stat = await fs.lstat(link);
-		if (!stat.isSymbolicLink()) return false;
-		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
-		return resolved.startsWith(profilesRoot(projectPath) + path.sep);
-	} catch {
-		return false;
-	}
-}
-
-/**
- * The name of the currently active profile, derived from where
- * .claude/settings.json points. Returns null if it isn't a profile symlink.
- */
-export async function activeProfile(
-	projectPath?: string,
-): Promise<string | null> {
-	const base = projectPath ?? process.cwd();
-	const link = path.join(base, ".claude", "settings.json");
-	try {
-		const stat = await fs.lstat(link);
-		if (!stat.isSymbolicLink()) return null;
-		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
-		const root = profilesRoot(projectPath) + path.sep;
-		if (!resolved.startsWith(root)) return null;
-		// resolved = <root>/<name>/settings.json → take the first segment.
-		return resolved.slice(root.length).split(path.sep)[0] ?? null;
-	} catch {
-		return null;
-	}
-}