magus-cli 7.4.0 → 7.5.0

package/src/services/profile-live.ts

@@ -0,0 +1,825 @@
+/**
+ * The active profile's live config: where it is, what magus last wrote there,
+ * and the marker that records it.
+ *
+ * `.claude/profiles.json` is the ONE source of truth. Everything Claude Code
+ * reads is generated from the active profile's entry and written as real files
+ * — there are no symlinks:
+ *
+ *   .claude/settings.json      rendered from the entry (plugins + settings)
+ *   .mcp.json                  rendered from the entry (mcpServers)
+ *   .claude/models.json        rendered from the entry (models); absent when
+ *                              the profile routes no models
+ *   .claude/skills/<name>/     one folder per skill the entry lists, installed
+ *                              by magus. Any OTHER folder in .claude/skills is a
+ *                              custom skill, owned by git and the team; magus
+ *                              never moves, copies, backs up or deletes one.
+ *
+ * `.claude/profiles/` holds only the marker, `.claude/profiles/active.json`:
+ *
+ *   { "version": 1, "profile": "<name>",
+ *     "definition": "<sha256 of everything the live files are rendered from>",
+ *     "base": { ...that entry... },
+ *     "allPluginIds": [ ...every profile's plugin ids, as rendered... ],
+ *     "files": { "settings": "<sha256>", "mcp": "<sha256>", "models": "<sha256>" },
+ *     "skills": { "<folder>": "<sha256 of its contents>" } }
+ *
+ * A live file whose hash differs was changed since magus wrote it — by Claude
+ * Code or a person — and in a magus project that IS a change to the active
+ * profile: `profile-absorb.ts` writes it into profiles.json. An entry whose
+ * hash differs was changed in profiles.json — usually a teammate's commit
+ * arriving by `git pull` — and the live files are regenerated. Edits are
+ * absorbed first and merged against `base`, so neither side is lost. Once a
+ * marker exists, nothing live is ever backed up.
+ *
+ * The one thing that IS backed up is a genuine pre-magus, hand-written
+ * settings.json, .mcp.json or models.json met at first adoption (no marker, no
+ * older layout). It is not magus's, so it goes to `.claude/.magus-backups/`.
+ *
+ * Why real files: Claude Code writes settings.json and .mcp.json itself, and
+ * its atomic writer refuses to write through a symlink
+ * (`SymlinkWriteRefusedError`). Every write here goes through a temp file and a
+ * rename, so a symlink left by an older layout is REPLACED, never written
+ * through.
+ *
+ * settings.local.json is NEVER touched: it holds personal credentials.
+ */
+
+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 { readManifest } from "./manifest.js";
+import { SettingsParseError } from "./settings-file.js";
+
+/**
+ * Paths that must be gitignored once a project uses profiles: the marker
+ * directory, backups and the generated live files. Only .claude/profiles.json
+ * is committed. `.claude/skills` is deliberately NOT here — custom skills in it
+ * are committed; each magus-installed skill folder gets its own line instead
+ * (see `profile-skills.ts`).
+ */
+export const PROFILE_GITIGNORE_ENTRIES = [
+	".claude/profiles/",
+	".claude/.magus-backups/",
+	".claude/settings.json",
+	".claude/models.json",
+	".mcp.json",
+];
+
+/** The comment heading magus's lines in a project's .gitignore. */
+export const PROFILE_GITIGNORE_COMMENT =
+	"# magus: generated profile config (source of truth: .claude/profiles.json)";
+
+/**
+ * Lines older releases wrote into magus's managed `.gitignore` block that must
+ * go when an older layout is converted: the blanket skills ignore hid committed
+ * custom skills, and `_profiles/` no longer exists. Removed from magus's own
+ * block only, and only during that conversion — the same line written by a
+ * person elsewhere in the file is theirs.
+ */
+export const OBSOLETE_GITIGNORE_ENTRIES = [
+	".claude/skills",
+	".claude/skills/",
+	".claude/_profiles/",
+];
+
+/**
+ * Settings keys that describe THIS MACHINE rather than the profile.
+ *
+ * magus records `installedPluginVersions` in the project settings file. It is
+ * never absorbed into profiles.json (that would commit one developer's install
+ * state as the team's contract), and it is carried across every re-render so
+ * writing the live file does not erase it.
+ */
+export const MACHINE_LOCAL_SETTINGS_KEYS: readonly string[] = [
+	"installedPluginVersions",
+];
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+/** `.claude/profiles/` — holds only the marker. */
+export function profilesRoot(projectPath?: string): string {
+	return path.join(projectPath ?? process.cwd(), ".claude", "profiles");
+}
+
+/** The directory an earlier release materialized profiles into. */
+export function legacyProfilesRoot(projectPath?: string): string {
+	return path.join(projectPath ?? process.cwd(), ".claude", "_profiles");
+}
+
+/** Where the active-profile marker lives. */
+export function activeMarkerPath(projectPath?: string): string {
+	return path.join(profilesRoot(projectPath), "active.json");
+}
+
+function legacyMarkerPath(projectPath?: string): string {
+	return path.join(legacyProfilesRoot(projectPath), ".active");
+}
+
+/** `.claude/skills/` — a real directory of skill folders. */
+export function skillsRoot(projectPath?: string): string {
+	return path.join(projectPath ?? process.cwd(), ".claude", "skills");
+}
+
+/** The live files rendered from the manifest and tracked by hash. */
+export type LiveFileKey = "settings" | "mcp" | "models";
+
+export const LIVE_FILE_KEYS: readonly LiveFileKey[] = [
+	"settings",
+	"mcp",
+	"models",
+];
+
+const LIVE_FILES: Record<LiveFileKey, string[]> = {
+	settings: [".claude", "settings.json"],
+	mcp: [".mcp.json"],
+	models: [".claude", "models.json"],
+};
+
+/** The live path of a rendered file. */
+export function livePath(key: LiveFileKey, projectPath?: string): string {
+	return path.join(projectPath ?? process.cwd(), ...LIVE_FILES[key]);
+}
+
+/** Every generated path, for the git-tracked check and doctor. */
+export function generatedPaths(projectPath?: string): string[] {
+	return [
+		livePath("settings", projectPath),
+		livePath("mcp", projectPath),
+		livePath("models", projectPath),
+		skillsRoot(projectPath),
+	];
+}
+
+// ─── Content helpers ─────────────────────────────────────────────────────────
+
+/** The live content of a profile, rendered in memory from the manifest. */
+export interface RenderedProfile {
+	settings: Record<string, unknown>;
+	mcp: Record<string, unknown>;
+	/** The routing file's content, or null when the profile routes nothing. */
+	models: Record<string, unknown> | null;
+	/** The manifest entry they were rendered from, as written in profiles.json. */
+	entry: ProfileManifestEntry;
+	/**
+	 * sha256 of everything the rendering read — see `renderProfile`. What the
+	 * marker's `definition` records, so a change anywhere in profiles.json that
+	 * alters this profile's output is noticed, including in another profile.
+	 */
+	definition: string;
+	/**
+	 * Every profile's plugin ids at render time, sorted. Any of them this
+	 * profile does not enable was written as `false` by the render itself.
+	 */
+	allPluginIds: string[];
+}
+
+/** The exact bytes magus writes for a rendered file. */
+export function serializeLive(content: Record<string, unknown>): string {
+	return `${JSON.stringify(content, null, 2)}\n`;
+}
+
+export function sha256(bytes: Buffer | string): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function sortKeys(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortKeys);
+	if (typeof value === "object" && value !== null) {
+		const out: Record<string, unknown> = {};
+		for (const key of Object.keys(value).sort()) {
+			out[key] = sortKeys((value as Record<string, unknown>)[key]);
+		}
+		return out;
+	}
+	return value;
+}
+
+/** JSON with object keys sorted at every level — equal meaning, equal text. */
+export function canonicalJson(value: unknown): string {
+	return JSON.stringify(sortKeys(value));
+}
+
+/** Semantic JSON equality: key order does not matter, everything else does. */
+export function jsonEqual(a: unknown, b: unknown): boolean {
+	return canonicalJson(a) === canonicalJson(b);
+}
+
+export function isJsonRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ─── The marker ──────────────────────────────────────────────────────────────
+
+/** The contents of the active-profile marker. */
+export interface ActiveMarker {
+	version: 1;
+	/** The active profile's id. */
+	profile: string;
+	/**
+	 * sha256 of the whole render input of the live files (`renderProfile`):
+	 * this profile's resolved closure and the plugin ids of every profile.
+	 */
+	definition?: string;
+	/**
+	 * That entry itself: the common ancestor when Claude Code edited the live
+	 * files AND profiles.json changed underneath them, so both can be merged.
+	 */
+	base?: ProfileManifestEntry;
+	/**
+	 * Every profile's plugin ids when the live files were rendered. A `false`
+	 * in the live settings for one of these that `base` does not enable is the
+	 * render's own output, not an edit — even after a teammate removes the
+	 * plugin from every profile and the current manifest no longer names it.
+	 */
+	allPluginIds?: string[];
+	/**
+	 * Set while magus runs the Claude CLI's plugin installs (`magus install`,
+	 * `magus update`). Each `claude plugin install --scope project` enables its
+	 * plugin in the live settings.json — for every profile's plugins, not only
+	 * the active one's. That is the CLI's bookkeeping, and it is rendered over
+	 * when the installs end. If the run dies first (Ctrl-C, a crash), the flag
+	 * is still here, and the next reconcile treats settings.json's
+	 * enabledPlugins as that bookkeeping rather than as the user's edits.
+	 */
+	cliBookkeeping?: true;
+	/** 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. */
+	skills: Record<string, string>;
+}
+
+/**
+ * A profile id or skill folder is one path segment. Anything else in the
+ * marker is not a name magus wrote, and following it could escape the tree.
+ */
+export function isSegment(name: unknown): name is string {
+	return (
+		typeof name === "string" &&
+		name.length > 0 &&
+		name !== "." &&
+		name !== ".." &&
+		!name.includes("/") &&
+		!name.includes("\\")
+	);
+}
+
+function parseMarker(raw: unknown): ActiveMarker | null {
+	if (!isJsonRecord(raw)) return null;
+	const {
+		profile,
+		files,
+		definition,
+		base,
+		skills,
+		allPluginIds,
+		cliBookkeeping,
+	} = raw;
+	if (!isSegment(profile)) return null;
+	const hashes: ActiveMarker["files"] = {};
+	if (isJsonRecord(files)) {
+		for (const key of LIVE_FILE_KEYS) {
+			const value = files[key];
+			if (typeof value === "string") hashes[key] = value;
+		}
+	}
+	const skillHashes: Record<string, string> = {};
+	if (isJsonRecord(skills)) {
+		for (const [folder, hash] of Object.entries(skills)) {
+			if (isSegment(folder) && typeof hash === "string") {
+				skillHashes[folder] = hash;
+			}
+		}
+	}
+	const marker: ActiveMarker = {
+		version: 1,
+		profile,
+		files: hashes,
+		skills: skillHashes,
+	};
+	if (typeof definition === "string") marker.definition = definition;
+	if (isJsonRecord(base)) marker.base = base as unknown as ProfileManifestEntry;
+	if (
+		Array.isArray(allPluginIds) &&
+		allPluginIds.every((id) => typeof id === "string")
+	) {
+		marker.allPluginIds = allPluginIds as string[];
+	}
+	if (cliBookkeeping === true) marker.cliBookkeeping = true;
+	return marker;
+}
+
+/**
+ * Read the marker. Absent, unparseable or wrongly shaped all answer null: the
+ * marker is magus's own bookkeeping, and a damaged one degrades to "no marker"
+ * — which the active-profile check then resolves — never to a throw.
+ *
+ * Reading and writing the marker go through this pair and nothing else, so
+ * where it lives is decided in one place. A marker an earlier release left at
+ * `.claude/_profiles/.active` is read too, while no current one exists.
+ */
+export async function readActiveMarker(
+	projectPath?: string,
+): Promise<ActiveMarker | null> {
+	for (const file of [
+		activeMarkerPath(projectPath),
+		legacyMarkerPath(projectPath),
+	]) {
+		try {
+			return parseMarker(await fs.readJson(file));
+		} catch {
+			// Try the next location.
+		}
+	}
+	return null;
+}
+
+/**
+ * Is there a marker in the current format at `.claude/profiles/active.json`?
+ * False for none, and for one an earlier release left at `_profiles/.active`,
+ * which belongs to an older layout and is converted with it.
+ */
+export async function hasCurrentMarker(projectPath?: string): Promise<boolean> {
+	return fs.pathExists(activeMarkerPath(projectPath));
+}
+
+/**
+ * The hashes an earlier release recorded at `_profiles/.active`, or null. Used
+ * only to tell an unedited live file of that layout from an edited one.
+ */
+export async function readLegacyMarkerHashes(
+	projectPath?: string,
+): Promise<ActiveMarker["files"] | null> {
+	try {
+		return (
+			parseMarker(await fs.readJson(legacyMarkerPath(projectPath)))?.files ??
+			null
+		);
+	} catch {
+		return null;
+	}
+}
+
+/** Write the marker. The other half of {@link readActiveMarker}. */
+export async function writeActiveMarker(
+	marker: ActiveMarker,
+	projectPath?: string,
+): Promise<void> {
+	// The older marker at `_profiles/.active` is left where it is: the current
+	// one takes precedence, and conversion keeps `_profiles/` whole in a backup.
+	await writeRealFile(
+		activeMarkerPath(projectPath),
+		`${JSON.stringify(marker, null, 2)}\n`,
+	);
+}
+
+/**
+ * A marker for `profile`, recording what `rendered` was rendered from. Never
+ * carries `cliBookkeeping`: writing a fresh marker is what clears it.
+ */
+export function markerFor(
+	profile: string,
+	rendered: Pick<RenderedProfile, "entry" | "definition" | "allPluginIds">,
+	files: ActiveMarker["files"],
+	skills: Record<string, string>,
+): ActiveMarker {
+	return {
+		version: 1,
+		profile,
+		definition: rendered.definition,
+		base: rendered.entry,
+		allPluginIds: rendered.allPluginIds,
+		files,
+		skills,
+	};
+}
+
+// ─── Live files ──────────────────────────────────────────────────────────────
+
+/** What sits at a live path. */
+export type LiveKind = "file" | "missing" | "symlink" | "other";
+
+export async function liveKind(
+	key: LiveFileKey,
+	projectPath?: string,
+): Promise<LiveKind> {
+	try {
+		const stat = await fs.lstat(livePath(key, projectPath));
+		if (stat.isSymbolicLink()) return "symlink";
+		return stat.isFile() ? "file" : "other";
+	} catch {
+		return "missing";
+	}
+}
+
+/** The hash of a live file, or null when it is not a regular file. */
+export async function liveHash(
+	key: LiveFileKey,
+	projectPath?: string,
+): Promise<string | null> {
+	if ((await liveKind(key, projectPath)) !== "file") return null;
+	return sha256(await fs.readFile(livePath(key, projectPath)));
+}
+
+/**
+ * The live file parsed as a JSON object. `null` when absent or not a regular
+ * file; throws `SyntaxError` when it exists and is not a JSON object.
+ */
+export async function readLiveJson(
+	key: LiveFileKey,
+	projectPath?: string,
+): Promise<Record<string, unknown> | null> {
+	if ((await liveKind(key, projectPath)) !== "file") return null;
+	const parsed: unknown = JSON.parse(
+		await fs.readFile(livePath(key, projectPath), "utf8"),
+	);
+	if (!isJsonRecord(parsed)) throw new SyntaxError("not a JSON object");
+	return parsed;
+}
+
+/** {@link readLiveJson} that answers null instead of throwing. */
+export async function readLiveJsonSafely(
+	key: LiveFileKey,
+	projectPath?: string,
+): Promise<Record<string, unknown> | null> {
+	try {
+		return await readLiveJson(key, projectPath);
+	} catch {
+		return null;
+	}
+}
+
+/** What a live path holds, read THROUGH a symlink if it is one. */
+export interface LiveRead {
+	/** Nothing there, or a link whose target is gone. */
+	missing: boolean;
+	/** The path is a symlink (an older layout's). */
+	isLink: boolean;
+	/** The parsed object, when it parsed. */
+	value: Record<string, unknown> | null;
+	/** sha256 of the bytes, when there were any. */
+	hash: string | null;
+	/** Why it could not be used, when it could not. */
+	error: SettingsParseError | null;
+}
+
+/**
+ * Read a live file following a symlink — an older layout linked settings.json,
+ * .mcp.json and models.json into `.claude/_profiles/<name>/`, and Claude Code
+ * before 2.1.280 wrote its edits through those links. Never throws.
+ */
+export async function readLiveThrough(
+	key: LiveFileKey,
+	projectPath?: string,
+): Promise<LiveRead> {
+	const file = livePath(key, projectPath);
+	const out: LiveRead = {
+		missing: true,
+		isLink: false,
+		value: null,
+		hash: null,
+		error: null,
+	};
+	try {
+		out.isLink = (await fs.lstat(file)).isSymbolicLink();
+	} catch {
+		return out;
+	}
+	let bytes: Buffer;
+	try {
+		bytes = await fs.readFile(file);
+	} catch {
+		return out; // A dangling link: nothing to read.
+	}
+	out.missing = false;
+	out.hash = sha256(bytes);
+	try {
+		const parsed: unknown = JSON.parse(bytes.toString("utf8"));
+		if (!isJsonRecord(parsed)) throw new SyntaxError("not a JSON object");
+		out.value = parsed;
+	} catch (error) {
+		out.error = new SettingsParseError(file, error);
+	}
+	return out;
+}
+
+/**
+ * Live files that exist as regular files and do not parse as a JSON object.
+ *
+ * magus never writes over a file it cannot parse — the same rule every
+ * settings writer follows — so every path that writes the live files checks
+ * this first and refuses, leaving the file byte for byte as it is.
+ */
+export async function unreadableLiveFiles(
+	projectPath?: string,
+): Promise<SettingsParseError[]> {
+	const out: SettingsParseError[] = [];
+	for (const key of LIVE_FILE_KEYS) {
+		if ((await liveKind(key, projectPath)) !== "file") continue;
+		const read = await readLiveThrough(key, projectPath);
+		if (read.error) out.push(read.error);
+	}
+	return out;
+}
+
+/** Throw the first of {@link unreadableLiveFiles}, if there is one. */
+export async function assertLiveFilesParse(
+	projectPath?: string,
+): Promise<void> {
+	const [first] = await unreadableLiveFiles(projectPath);
+	if (first) throw first;
+}
+
+/**
+ * Write `bytes` at `file` as a real file, replacing whatever entry is there.
+ *
+ * Via a temp file and a rename, so Claude Code never reads half a file, and so
+ * a symlink at `file` is REPLACED rather than written through.
+ */
+async function writeRealFile(file: string, bytes: string): Promise<void> {
+	await fs.ensureDir(path.dirname(file));
+	const tmp = `${file}.magus-tmp-${process.pid}`;
+	await fs.writeFile(tmp, bytes);
+	await fs.rename(tmp, file);
+}
+
+/**
+ * Write one rendered live file (or remove it, for `null` content) and return
+ * the hash of what was written, or null when nothing is there now. Does NOT
+ * touch the marker — callers record the hash with the rest of their state.
+ *
+ * Machine-local settings keys in the current live file are carried into the
+ * new one (see {@link MACHINE_LOCAL_SETTINGS_KEYS}).
+ */
+export async function writeLiveFile(
+	key: LiveFileKey,
+	content: Record<string, unknown> | null,
+	projectPath?: string,
+): Promise<string | null> {
+	const file = livePath(key, projectPath);
+	// Backstop for the callers' own checks: never replace a regular file that
+	// does not parse. A symlink (an older layout) is replaced by the rename.
+	if ((await liveKind(key, projectPath)) === "file") {
+		const current = await readLiveThrough(key, projectPath);
+		if (current.error) throw current.error;
+	}
+	if (content === null) {
+		await fs.remove(file);
+		return null;
+	}
+	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) {
+			body = { ...content };
+			for (const k of MACHINE_LOCAL_SETTINGS_KEYS) {
+				if (k in live && !(k in body)) body[k] = live[k];
+			}
+		}
+	}
+	const bytes = serializeLive(body);
+	await writeRealFile(file, bytes);
+	return sha256(bytes);
+}
+
+/** Write all three live files of `rendered`; returns their hashes. */
+export async function writeRenderedFiles(
+	rendered: RenderedProfile,
+	projectPath?: string,
+): Promise<ActiveMarker["files"]> {
+	const files: ActiveMarker["files"] = {};
+	for (const key of LIVE_FILE_KEYS) {
+		const hash = await writeLiveFile(key, rendered[key], projectPath);
+		if (hash) files[key] = hash;
+	}
+	return files;
+}
+
+// ─── Skill folders ───────────────────────────────────────────────────────────
+
+/**
+ * A content hash of a skill folder: every file's path relative to the folder
+ * and its bytes, in sorted order. A symlink inside contributes its target text.
+ * Null when the folder does not exist.
+ */
+export async function folderHash(dir: string): Promise<string | null> {
+	try {
+		if (!(await fs.lstat(dir)).isDirectory()) return null;
+	} catch {
+		return null;
+	}
+	const hash = createHash("sha256");
+	const walk = async (rel: string): Promise<void> => {
+		const entries = (await fs.readdir(path.join(dir, rel))).sort();
+		for (const name of entries) {
+			const childRel = rel ? `${rel}/${name}` : name;
+			const abs = path.join(dir, childRel);
+			const stat = await fs.lstat(abs);
+			if (stat.isDirectory()) {
+				await walk(childRel);
+			} else if (stat.isSymbolicLink()) {
+				hash.update(`L\0${childRel}\0${await fs.readlink(abs)}\0`);
+			} else if (stat.isFile()) {
+				hash.update(`F\0${childRel}\0`);
+				hash.update(await fs.readFile(abs));
+				hash.update("\0");
+			}
+		}
+	};
+	await walk("");
+	return hash.digest("hex");
+}
+
+// ─── Older layouts ───────────────────────────────────────────────────────────
+
+/**
+ * If `link` is a symlink into `.claude/_profiles/<n>/…` — the layout magus
+ * 7.4.1 and earlier wrote — the profile it points into. No release linked into
+ * `.claude/profiles/`, so a link there is somebody's own and is left alone.
+ */
+export async function profileLinkTarget(
+	link: string,
+	projectPath?: string,
+): Promise<string | null> {
+	try {
+		if (!(await fs.lstat(link)).isSymbolicLink()) return null;
+		const resolved = path.resolve(path.dirname(link), await fs.readlink(link));
+		const prefix = legacyProfilesRoot(projectPath) + path.sep;
+		if (!resolved.startsWith(prefix)) return null;
+		const name = resolved.slice(prefix.length).split(path.sep)[0];
+		return isSegment(name) ? name : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The profile an older symlink layout names, or null. Any of the generated
+ * paths being a symlink into a profiles directory counts — the skills link
+ * outlived the settings link by one release.
+ */
+export async function oldLayoutProfile(
+	projectPath?: string,
+): Promise<string | null> {
+	for (const p of generatedPaths(projectPath)) {
+		const name = await profileLinkTarget(p, projectPath);
+		if (name) return name;
+	}
+	return null;
+}
+
+/**
+ * The per-profile directories older releases left: `.claude/_profiles/<n>/`,
+ * written by magus 7.4.1 and earlier and by the release after it. Conversion
+ * takes the skills out and keeps the rest in `.claude/.magus-backups/`.
+ *
+ * `.claude/profiles/` is never scanned: no release wrote per-profile
+ * directories there, so anything in it besides `active.json` is somebody's.
+ */
+export async function legacyProfileDirs(
+	projectPath?: string,
+): Promise<Array<{ name: string; dir: string }>> {
+	const out: Array<{ name: string; dir: string }> = [];
+	const root = legacyProfilesRoot(projectPath);
+	let names: string[];
+	try {
+		names = await fs.readdir(root);
+	} catch {
+		return out;
+	}
+	for (const name of names) {
+		if (!isSegment(name) || name.startsWith(".")) continue;
+		const dir = path.join(root, name);
+		try {
+			if ((await fs.lstat(dir)).isDirectory()) out.push({ name, dir });
+		} catch {
+			// Vanished between listing and stat.
+		}
+	}
+	return out;
+}
+
+/**
+ * Does anything of an older layout remain — a generated path that is a
+ * symlink into `.claude/_profiles/`, the `_profiles/` directory itself, or the
+ * older marker? Activation converts all of it.
+ */
+export async function hasOlderLayout(projectPath?: string): Promise<boolean> {
+	if ((await oldLayoutProfile(projectPath)) !== null) return true;
+	return fs.pathExists(legacyProfilesRoot(projectPath));
+}
+
+// ─── Backups ─────────────────────────────────────────────────────────────────
+
+/**
+ * Where first adoption moves a hand-written file it had to displace. Never
+ * inside `.claude/profiles/`, which is documented as regenerable.
+ */
+export function backupRoot(projectPath?: string): string {
+	return path.join(projectPath ?? process.cwd(), ".claude", ".magus-backups");
+}
+
+/** One artifact first adoption moved aside to make room for the profile's. */
+export interface DisplacedArtifact {
+	/** The live path the profile's artifact now occupies. */
+	link: string;
+	/** Where its previous contents were moved. */
+	savedTo: string;
+}
+
+/** A directory name that sorts chronologically and is legal on every platform. */
+export function backupStamp(): string {
+	return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Move whatever sits at `file` into `backupDir`. A symlink is moved as a link,
+ * rewritten as absolute so its meaning survives the move.
+ */
+export async function displace(
+	file: string,
+	backupDir: string,
+): Promise<DisplacedArtifact | null> {
+	let stat: Stats;
+	try {
+		stat = await fs.lstat(file);
+	} catch {
+		return null;
+	}
+	const savedTo = path.join(backupDir, path.basename(file));
+	await fs.ensureDir(backupDir);
+	if (stat.isSymbolicLink()) {
+		const absolute = path.resolve(path.dirname(file), await fs.readlink(file));
+		await fs.remove(savedTo);
+		await fs.symlink(absolute, savedTo);
+		await fs.remove(file);
+		return { link: file, savedTo };
+	}
+	await fs.move(file, savedTo, { overwrite: true });
+	return { link: file, savedTo };
+}
+
+/**
+ * Hand-written files that activating ANY profile would have to move aside.
+ *
+ * Empty means activating is lossless — a fresh clone, a project magus already
+ * manages (a marker exists: its live files are absorbed, never displaced), or
+ * an older layout magus converts. That is what makes it safe to honour the
+ * manifest's declared default without asking.
+ */
+export async function displaceableArtifacts(
+	projectPath?: string,
+): Promise<string[]> {
+	if ((await readActiveMarker(projectPath)) !== null) return [];
+	if ((await oldLayoutProfile(projectPath)) !== null) return [];
+	const found: string[] = [];
+	for (const key of LIVE_FILE_KEYS) {
+		if ((await liveKind(key, projectPath)) !== "missing") {
+			found.push(livePath(key, projectPath));
+		}
+	}
+	return found;
+}
+
+// ─── Which profile is active ─────────────────────────────────────────────────
+
+/**
+ * The profile the marker (or an older symlink layout) NAMES, whether or not
+ * the manifest still defines it. For the strict check in `profile-state.ts`;
+ * everyone else wants {@link activeProfile}.
+ */
+export async function namedActiveProfile(
+	projectPath?: string,
+): Promise<{ profile: string; source: "marker" | "old-layout" } | null> {
+	const marker = await readActiveMarker(projectPath);
+	if (marker) return { profile: marker.profile, source: "marker" };
+	const old = await oldLayoutProfile(projectPath);
+	return old ? { profile: old, source: "old-layout" } : null;
+}
+
+/**
+ * The name of the currently active profile, or null when none is.
+ *
+ * Strict: the marker (or an older layout) must name a profile that
+ * `.claude/profiles.json` defines. A marker naming a profile the manifest no
+ * longer has describes nothing magus can act on, so it answers null here and
+ * the entry-point check (`checkActiveProfile`) reports it with the fix.
+ */
+export async function activeProfile(
+	projectPath?: string,
+): Promise<string | null> {
+	const named = await namedActiveProfile(projectPath);
+	if (!named) return null;
+	try {
+		const manifest = await readManifest(projectPath);
+		return Object.hasOwn(manifest.profiles, named.profile)
+			? named.profile
+			: null;
+	} catch {
+		// An unreadable manifest: the commands that read it properly report why.
+		return null;
+	}
+}