magus-cli 7.4.1 → 7.5.1

package/src/services/profile-activate.ts

@@ -1,65 +1,118 @@
 /**
- * Finish a migration: put a profile on disk and make the project run it.
+ * Put a project on a profile: render it, write it, install its skills.
  *
- * Adoption used to end at `writeManifest`, which is the whole reason migrating
- * felt like it did nothing. "Active" is not a field anywhere — it is derived
- * from whether `.claude/settings.json` is a symlink into `_profiles/<id>/`
- * (see `activeProfile`). A manifest that nothing links to leaves the project in
- * exactly the state it was in, so the next command still asks which profile to
- * use, having just been told.
+ * "Active" is not a field in the manifest — it is the per-developer marker
+ * `.claude/profiles/active.json` that activation writes (see `activeProfile`).
+ * A manifest nothing has activated leaves the project exactly as it was.
  *
- * The three steps have to happen together and in this order, which is why they
- * live in one function rather than at each call site:
+ * Activation, in order:
  *
- *   1. materialize — write `_profiles/<id>/`, or activation throws
- *   2. gitignore   — before the links exist, or a symlink into generated state
- *                    lands in `git status` (`.claude/` is committed)
- *   3. activate    — point the four links at the profile
+ *   1. refuse, changing nothing, when a live file magus manages exists and
+ *      does not parse — magus never writes over a file it cannot read
+ *   2. convert an older layout's skills (`.claude/_profiles/`), restoring any
+ *      committed custom skills it displaced
+ *   3. refuse — before anything else changes — when the profile lists a skill
+ *      whose folder is already a custom skill
+ *   4. gitignore the generated files, before they exist, in magus's own block
+ *   5. write settings.json, .mcp.json and models.json from the manifest; only
+ *      at first adoption (no marker) is a hand-written file moved aside first
+ *   6. install/remove magus-installed skill folders; custom ones are untouched
+ *   7. record the marker, then move what is left of `.claude/_profiles/` into
+ *      `.claude/.magus-backups/<stamp>-layout/` — kept, never deleted
  *
- * No network and no installs: `resolveProfile` reads the manifest, and binary
- * resolution is skipped outright because nothing here materializes bins. That
- * matters — this runs inside a prompt the user answered, not inside `install`.
+ * Callers absorb the live files into the PREVIOUS profile before switching
+ * away (`profile-state.ts`) — including, for an older layout, what Claude
+ * Code wrote through its links — so what step 5 replaces is already in the
+ * manifest. No network except skill installs.
  */
 
+import { lstat } from "node:fs/promises";
 import path from "node:path";
-import type { ProfileManifest } from "../types/index.js";
-import { ensureGitignoreEntries } from "./conventions-manager.js";
-import { writeManifest } from "./manifest.js";
-import { adoptCurrentProject } from "./profile-adopt.js";
-import { materializeProfile } from "./profile-materializer.js";
-import { resolveAllProfiles, resolveProfile } from "./resolver.js";
+import type {
+	DependencyReport,
+	ProfileManifest,
+	ProfileSkillRef,
+} from "../types/index.js";
+import { updateManagedGitignoreBlock } from "./conventions-manager.js";
+import { readManifest } from "./manifest.js";
 import {
+	type ActiveMarker,
 	type DisplacedArtifact,
+	LIVE_FILE_KEYS,
+	OBSOLETE_GITIGNORE_ENTRIES,
+	PROFILE_GITIGNORE_COMMENT,
 	PROFILE_GITIGNORE_ENTRIES,
-	activateProfile,
-} from "./symlink-manager.js";
-
-/**
- * Bins are declared by plugins and read from the marketplace cache, one
- * `plugin.json` per plugin. Materialization writes settings, mcp, models and
- * skills — never bins — so resolving them here would be pure latency, and on a
- * machine with a cold cache it is latency inside a prompt.
- */
-const noBins = async () => [];
+	assertLiveFilesParse,
+	backupRoot,
+	backupStamp,
+	displace,
+	folderHash,
+	generatedPaths,
+	hasCurrentMarker,
+	liveKind,
+	livePath,
+	machineLocalSettings,
+	markerFor,
+	oldLayoutProfile,
+	readActiveMarker,
+	skillsRoot,
+	writeActiveMarker,
+	writeLiveFile,
+	writeRenderedFiles,
+} from "./profile-live.js";
+import { describeDependencies, renderProfile } from "./profile-render.js";
+import {
+	type LegacySkillConversion,
+	SkillClashError,
+	type SkillInstaller,
+	type SkillSyncResult,
+	archiveOlderLayout,
+	convertLegacySkills,
+	findSkillClashes,
+	installProfileSkill,
+	skillFolder,
+	syncSkills,
+	updateSkillIgnoreLines,
+} from "./profile-skills.js";
+import {
+	LiveFileRefusal,
+	TrackedLiveFileError,
+	trackedPaths,
+	untrackCommand,
+} from "./tracked-live-files.js";
+import type { ApplyReporter } from "./update-engine.js";
 
 export interface ActivationResult {
 	/** The profile now live. */
 	profileId: string;
-	/** Hand-written artifacts moved aside to make room for the symlinks. */
+	/** Hand-written files moved aside at first adoption. */
 	displaced: DisplacedArtifact[];
+	/** What happened to the profile's skill folders. */
+	skills: SkillSyncResult;
+	/** What converting an older layout did, if there was one. */
+	conversion: LegacySkillConversion;
+	/** Generated paths git still tracks (see {@link trackedGeneratedFiles}). */
+	tracked: string[];
+	/** Where `.claude/_profiles/` was kept, project-relative, or null. */
+	keptAt: string | null;
+	/** Unsaved changes added to a profile before activating, one line each. */
+	absorbed?: string[];
+	/** What the profile's plugins depend on — see `describeDependencies`. */
+	dependencies?: DependencyReport;
+	/** Listed skills whose folder the team committed: that copy is used. */
+	committedSkills?: string[];
+}
+
+export interface ActivateOptions {
+	/** Called as each hand-written file moves; defaults to printing it. */
+	onDisplace?: (artifact: DisplacedArtifact) => void;
+	/** Skill installer; the real one fetches from GitHub. */
+	installSkill?: SkillInstaller;
 }
 
 /**
- * Announce one displaced artifact, in project-relative terms.
- *
- * Shared by every command that activates, because a hand-written file moving is
- * the same event whichever command caused it, and the one that is easiest to
- * leave out: `activateProfile` returns the list, and a caller that discards the
- * return value still compiles. `magus install` and `magus profile switch` both
- * did exactly that.
- *
- * Paths are relative because absolute ones wrap over two terminal lines each,
- * and this is the notice a user must not skim.
+ * Announce one displaced artifact, in project-relative terms, the instant it
+ * moves — so a throw partway through still says where the first one went.
  */
 export function reportDisplaced(
 	projectPath: string,
@@ -70,78 +123,423 @@ export function reportDisplaced(
 }
 
 /**
- * Materialize `profileId` and make it the active profile.
+ * Generated paths that git tracks: the three live files, a committed
+ * `.claude/skills` SYMLINK (an older layout committed by mistake), and any of
+ * `skillFolders` — skill folders magus would install or remove. Committed
+ * custom skills under a real `.claude/skills/` directory are not generated
+ * state and are never reported. Empty outside a git repository.
+ */
+export async function trackedWriteTargets(
+	projectPath: string,
+	skillFolders: readonly string[] = [],
+): Promise<string[]> {
+	const rel = (abs: string) => path.relative(projectPath, abs);
+	const live = LIVE_FILE_KEYS.map((key) => rel(livePath(key, projectPath)));
+	const skills = rel(skillsRoot(projectPath));
+	const folders = skillFolders.map((folder) => path.join(skills, folder));
+	let skillsIsLink = false;
+	try {
+		skillsIsLink = (await lstat(skillsRoot(projectPath))).isSymbolicLink();
+	} catch {
+		// No .claude/skills at all.
+	}
+	const files = [...live, ...(skillsIsLink ? [skills] : [])];
+	const tracked = await trackedPaths(projectPath, files, folders);
+	return [...files, ...folders].filter((c) => tracked.has(c));
+}
+
+/**
+ * The folders of `skills` the team committed under `.claude/skills/`. Such a
+ * folder is the team's copy of the skill: magus neither installs over it nor
+ * manages it, so it never has cause to suggest untracking it.
+ */
+export async function committedSkillFolders(
+	projectPath: string,
+	skills: readonly ProfileSkillRef[],
+): Promise<Set<string>> {
+	const root = path.relative(projectPath, skillsRoot(projectPath));
+	const folders = skills.map((ref) => skillFolder(ref));
+	const tracked = await trackedPaths(
+		projectPath,
+		[],
+		folders.map((folder) => path.join(root, folder)),
+	);
+	return new Set(folders.filter((f) => tracked.has(path.join(root, f))));
+}
+
+/** {@link trackedWriteTargets} for the live files alone — what doctor reports. */
+export async function trackedGeneratedFiles(
+	projectPath: string,
+): Promise<string[]> {
+	return trackedWriteTargets(projectPath);
+}
+
+/**
+ * The skill folders activating a profile with `skills` could write: those
+ * magus manages now (kept or removed), and the profile's that are not on disk
+ * yet — unless the team committed them (see {@link committedSkillFolders}).
+ * An existing folder magus does not manage is a custom skill, which
+ * activation refuses as a clash rather than writing.
+ */
+export async function writableSkillFolders(
+	projectPath: string,
+	skills: readonly ProfileSkillRef[],
+	managed: Readonly<Record<string, string>> = {},
+): Promise<string[]> {
+	const out = new Set(Object.keys(managed));
+	const missing: ProfileSkillRef[] = [];
+	for (const ref of skills) {
+		const folder = skillFolder(ref);
+		if (out.has(folder)) continue;
+		try {
+			await lstat(path.join(skillsRoot(projectPath), folder));
+		} catch {
+			missing.push(ref);
+		}
+	}
+	const committed = await committedSkillFolders(projectPath, missing);
+	for (const ref of missing) {
+		if (!committed.has(skillFolder(ref))) out.add(skillFolder(ref));
+	}
+	return [...out];
+}
+
+/**
+ * The skill folders the ACTIVE profile's next render could write — see
+ * {@link writableSkillFolders}. For the checks made before a reconcile, which
+ * may re-render and so install or remove them.
+ */
+export async function activeWritableSkillFolders(
+	projectPath: string,
+	manifest: ProfileManifest,
+): Promise<string[]> {
+	const marker = await readActiveMarker(projectPath);
+	if (!marker) return [];
+	return writableSkillFolders(
+		projectPath,
+		manifest.profiles[marker.profile]?.skills ?? [],
+		marker.skills,
+	);
+}
+
+/**
+ * Why magus must not write here, or null: {@link assertNoTrackedWriteTargets}
+ * as a value, for callers that report a refusal instead of throwing it.
+ */
+export async function writeRefusal(
+	projectPath: string,
+	skillFolders: readonly string[] = [],
+): Promise<LiveFileRefusal | null> {
+	try {
+		await assertNoTrackedWriteTargets(projectPath, skillFolders);
+		return null;
+	} catch (error) {
+		if (error instanceof LiveFileRefusal) return error;
+		throw error;
+	}
+}
+
+/**
+ * Throw {@link TrackedLiveFileError} — before anything is written — when any
+ * of {@link trackedWriteTargets} is tracked, or `GitCheckError` when git
+ * cannot say.
+ */
+export async function assertNoTrackedWriteTargets(
+	projectPath: string,
+	skillFolders: readonly string[] = [],
+): Promise<void> {
+	const tracked = await trackedWriteTargets(projectPath, skillFolders);
+	if (tracked.length > 0) throw new TrackedLiveFileError(tracked);
+}
+
+/**
+ * Lines describing what activation did beyond the switch itself, phrased for
+ * both the terminal and the TUI's outcome modal.
+ */
+export function activationNotes(result: ActivationResult): string[] {
+	const lines: string[] = [
+		...(result.absorbed ?? []),
+		...describeDependencies(result.dependencies, result.profileId),
+	];
+	for (const folder of result.conversion.restored) {
+		lines.push(
+			`Restored custom skill .claude/skills/${folder} (the older profile layout had moved it)`,
+		);
+	}
+	for (const c of result.conversion.conflicts) {
+		lines.push(
+			`Skill "${c.folder}" exists in two versions; kept ${c.kept}, the other is at ${c.other}`,
+		);
+	}
+	for (const f of result.skills.failed) {
+		lines.push(`Skill "${f.skill}" could not be installed: ${f.reason}`);
+	}
+	for (const folder of result.committedSkills ?? []) {
+		lines.push(
+			`Skill .claude/skills/${folder} is committed to git — the team's copy is used; magus does not install or manage it`,
+		);
+	}
+	for (const rel of result.tracked) {
+		lines.push(
+			`${rel} is generated but tracked by git — run \`${untrackCommand(rel)}\`, then commit`,
+		);
+	}
+	if (result.keptAt) {
+		lines.push(
+			`The older layout's .claude/_profiles/ was kept at ${result.keptAt}/`,
+		);
+	}
+	return lines;
+}
+
+/**
+ * Render `profileId` from `manifest` and make it the active profile.
  *
- * The union of plugin ids across EVERY profile is passed to materialization, so
- * the profile writes an explicit `false` for plugins other profiles own. Without
- * it an omitted id falls through to user scope and stays enabled, which would
- * make the freshly adopted profile additive rather than a description of this
- * project — the exact drift adoption was run to end.
+ * Throws {@link TrackedLiveFileError}, having changed nothing, when a path it
+ * would write is tracked by git. Throws `SettingsParseError`, having changed
+ * nothing, when a live file of a managed project does not parse. Throws
+ * {@link SkillClashError} — having
+ * changed nothing but moving an older layout's skills into `.claude/skills/` —
+ * when a listed skill's folder is already a custom skill.
  */
-export async function materializeAndActivate(
+export async function activateProfile(
 	manifest: ProfileManifest,
 	profileId: string,
 	projectPath: string,
-	/** Called as each artifact moves; defaults to printing it. */
-	onDisplace: (artifact: DisplacedArtifact) => void = reportDisplaced(
-		projectPath,
-	),
+	opts: ActivateOptions = {},
 ): Promise<ActivationResult> {
-	const closure = await resolveProfile(manifest, profileId, {
-		binResolver: noBins,
-	});
-	const union = await resolveAllProfiles(manifest, { binResolver: noBins });
+	const onDisplace = opts.onDisplace ?? reportDisplaced(projectPath);
+	const rendered = await renderProfile(manifest, profileId, projectPath);
+	const skillRefs = rendered.entry.skills ?? [];
 
-	await materializeProfile(
-		profileId,
-		closure,
+	// Read before converting: the older marker lives in the directory the
+	// conversion moves away, and an older layout is recognised by its links.
+	const previous = await readActiveMarker(projectPath);
+	// Before anything else is touched — the conversion below writes too.
+	await assertNoTrackedWriteTargets(
 		projectPath,
-		Object.keys(union.plugins),
+		await writableSkillFolders(projectPath, skillRefs, previous?.skills),
 	);
+	const wasOldLayout = (await oldLayoutProfile(projectPath)) !== null;
+	// A managed project's live files are the profile's; one that does not
+	// parse is somebody mid-edit, and replacing it would lose their work. (At
+	// first adoption a hand-written file is moved to a backup, not replaced.)
+	if (previous !== null) await assertLiveFilesParse(projectPath);
+	const conversion = await convertLegacySkills(manifest, projectPath);
+	const managedBefore: Record<string, string> = {
+		...(previous?.skills ?? {}),
+		...conversion.managed,
+	};
 
-	await ensureGitignoreEntries(
+	// Listed skills the team committed and magus does not manage: that copy
+	// stands, and magus neither installs over it nor reports it as a clash.
+	const committedSkills = await committedSkillFolders(
+		projectPath,
+		skillRefs.filter((ref) => !(skillFolder(ref) in managedBefore)),
+	);
+	const clashes = await findSkillClashes(
+		skillRefs,
+		managedBefore,
+		projectPath,
+		committedSkills,
+	);
+	if (clashes.length > 0) throw new SkillClashError(profileId, clashes);
+
+	await updateManagedGitignoreBlock(
 		path.join(projectPath, ".gitignore"),
-		PROFILE_GITIGNORE_ENTRIES,
-		"# magus: generated profile build output + active-profile symlinks",
+		PROFILE_GITIGNORE_COMMENT,
+		{
+			add: PROFILE_GITIGNORE_ENTRIES,
+			// Only while converting an older layout, and only from magus's own
+			// block: the blanket `.claude/skills` line it wrote hid committed
+			// custom skills. The same line a person wrote elsewhere is theirs.
+			remove: conversion.converted ? OBSOLETE_GITIGNORE_ENTRIES : [],
+		},
 	);
 
-	const displaced = await activateProfile(profileId, projectPath, onDisplace);
-	return { profileId, displaced };
-}
+	const backupDir = path.join(backupRoot(projectPath), backupStamp());
+	const displaced: DisplacedArtifact[] = [];
+	const files: ActiveMarker["files"] = {};
+	// Read BEFORE a first adoption moves the file to a backup: this machine's
+	// `installedPluginVersions` must reach the new settings.json, and after the
+	// move there is nothing at the live path to read it from.
+	const carried = await machineLocalSettings(projectPath);
+	for (const key of LIVE_FILE_KEYS) {
+		// First adoption only: nothing marks this project as magus's and it is
+		// not an older magus layout, so a real file here is somebody's.
+		if (
+			previous === null &&
+			!wasOldLayout &&
+			(await liveKind(key, projectPath)) !== "missing"
+		) {
+			const moved = await displace(livePath(key, projectPath), backupDir);
+			if (moved) {
+				displaced.push(moved);
+				onDisplace(moved);
+			}
+		}
+		const hash = await writeLiveFile(key, rendered[key], projectPath, carried);
+		if (hash) files[key] = hash;
+		// Recorded after EACH file, so a throw on the next cannot leave a file
+		// magus just wrote looking like an edit to absorb.
+		await writeActiveMarker(
+			markerFor(profileId, rendered, files, managedBefore),
+			projectPath,
+		);
+	}
 
-/** The two ways a project can be put onto a profile. */
-export type ProfileChoice =
-	| { kind: "adopt"; id: string }
-	| { kind: "activate"; id: string };
+	const skills = await syncSkills(
+		skillRefs,
+		managedBefore,
+		projectPath,
+		opts.installSkill ?? installProfileSkill,
+		committedSkills,
+	);
+	await updateSkillIgnoreLines(
+		projectPath,
+		Object.keys(managedBefore),
+		Object.keys(skills.skills),
+	);
+	await writeActiveMarker(
+		markerFor(profileId, rendered, files, skills.skills),
+		projectPath,
+	);
+	// Last, so a failure above leaves the older layout readable.
+	await archiveOlderLayout(projectPath, conversion.keptAt);
+
+	return {
+		profileId,
+		displaced,
+		skills,
+		conversion,
+		tracked: await trackedGeneratedFiles(projectPath),
+		keptAt: conversion.keptAt
+			? path.relative(projectPath, conversion.keptAt)
+			: null,
+		...(rendered.dependencies ? { dependencies: rendered.dependencies } : {}),
+		...(committedSkills.size > 0
+			? { committedSkills: [...committedSkills].sort() }
+			: {}),
+	};
+}
 
 /**
- * Carry out the user's choice, whichever surface asked.
+ * Re-render the ACTIVE profile's settings.json, .mcp.json and models.json from
+ * the manifest and record them, leaving skills alone.
+ *
+ * For a command that has just changed the manifest (`models use`, a style) or
+ * let the Claude CLI write its own bookkeeping into settings.json (`magus
+ * install`, `magus update`). Anything Claude Code wrote was absorbed before the
+ * command acted, so replacing the files loses nothing.
  *
- * One implementation because "migrate" is two writes that must not come apart —
- * write the manifest, then link the project to it — and a second copy of that
- * pairing in the other surface is how one of them ends up writing the manifest
- * and stopping, which is the defect this whole area was fixed for.
+ * Returns false, writing nothing, when there is no current-format marker
+ * naming a defined profile. An older layout is NOT converted here: conversion
+ * must first record what Claude Code wrote through the old links, which is the
+ * entry-point gate's job (`prepareProfileState`). Throws `SettingsParseError`,
+ * writing nothing, when a live file does not parse.
  */
-export async function applyProfileChoice(
-	choice: ProfileChoice,
-	manifest: ProfileManifest,
+export async function regenerateLiveFiles(
 	projectPath: string,
-	onDisplace?: (artifact: DisplacedArtifact) => void,
-): Promise<ActivationResult> {
-	if (choice.kind === "activate") {
-		return materializeAndActivate(manifest, choice.id, projectPath, onDisplace);
-	}
-	const result = await adoptCurrentProject(
+): Promise<boolean> {
+	if (!(await hasCurrentMarker(projectPath))) return false;
+	const marker = await readActiveMarker(projectPath);
+	const manifest = await readManifest(projectPath);
+	if (!marker || !manifest.profiles[marker.profile]) return false;
+	await assertNoTrackedWriteTargets(projectPath);
+	await assertLiveFilesParse(projectPath);
+	const rendered = await renderProfile(manifest, marker.profile, projectPath);
+	const files = await writeRenderedFiles(rendered, projectPath);
+	await writeActiveMarker(
+		markerFor(marker.profile, rendered, files, marker.skills),
 		projectPath,
-		undefined,
-		manifest,
-		choice.id,
 	);
-	await writeManifest(result.manifest, projectPath);
-	return materializeAndActivate(
-		result.manifest,
-		choice.id,
+	return true;
+}
+
+/**
+ * The profile skills `magus update` may fetch into `.claude/skills/`: only for
+ * the ACTIVE profile (another profile's skills would land as folders nothing
+ * records, which read as custom skills), and only into a folder that is
+ * magus-installed or absent — never over a custom skill.
+ */
+export async function updatableSkills(
+	projectPath: string,
+	profileId: string,
+	refs: readonly ProfileSkillRef[],
+): Promise<ProfileSkillRef[]> {
+	const marker = await readActiveMarker(projectPath);
+	if (!marker || marker.profile !== profileId) return [];
+	const out: ProfileSkillRef[] = [];
+	for (const ref of refs) {
+		const folder = skillFolder(ref);
+		if (folder in marker.skills) {
+			out.push(ref);
+			continue;
+		}
+		try {
+			await lstat(path.join(skillsRoot(projectPath), folder));
+		} catch {
+			out.push(ref);
+		}
+	}
+	return out;
+}
+
+/**
+ * Which skill folders an apply actually fetched, read off its reporter: a
+ * skill counts once its item finishes successfully. Pass the returned
+ * `report` to the apply and `fetched()` to {@link recordRefetchedSkills} — a
+ * skill that was not fetched keeps its old hash, so an edit someone made to it
+ * during the run is still seen as an edit, not recorded as magus's own.
+ */
+export function trackFetchedSkills(
+	refs: readonly ProfileSkillRef[],
+	report: ApplyReporter,
+): { report: ApplyReporter; fetched: () => string[] } {
+	const folders = new Map(refs.map((ref) => [ref.name, skillFolder(ref)]));
+	const fetched = new Set<string>();
+	return {
+		report: {
+			begin: (name) => report.begin(name),
+			finish: (ok, name, detail, ms) => {
+				const folder = folders.get(name);
+				if (ok && folder) fetched.add(folder);
+				report.finish(ok, name, detail, ms);
+			},
+			detach: (work) => report.detach(work),
+		},
+		fetched: () => [...fetched],
+	};
+}
+
+/**
+ * After `magus update` re-fetched skills in place: record those folders as
+ * magus-installed with their new contents, so they do not read as edited.
+ * Only the folders it fetched (see {@link trackFetchedSkills}).
+ * Keeps every other part of the marker — including a `cliBookkeeping` flag,
+ * which the reconcile that follows (`withCliBookkeeping`) clears.
+ */
+export async function recordRefetchedSkills(
+	projectPath: string,
+	skillFolders: readonly string[],
+): Promise<void> {
+	if (!(await hasCurrentMarker(projectPath))) return;
+	const marker = await readActiveMarker(projectPath);
+	if (!marker) return;
+	const skills = { ...marker.skills };
+	for (const folder of skillFolders) {
+		const hash = await folderHash(path.join(skillsRoot(projectPath), folder));
+		if (hash) skills[folder] = hash;
+	}
+	await writeActiveMarker({ ...marker, skills }, projectPath);
+	await updateSkillIgnoreLines(
 		projectPath,
-		onDisplace,
+		Object.keys(marker.skills),
+		Object.keys(skills),
 	);
 }
+
+/** The two ways a project can be put onto a profile. */
+export type ProfileChoice =
+	| { kind: "adopt"; id: string }
+	| { kind: "activate"; id: string };