magus-cli 7.4.0 → 7.5.0

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