magus-cli 7.4.1 → 7.5.1

package/src/cli/bootstrap.ts

@@ -15,8 +15,10 @@ import {
 	writeManifest,
 } from "../services/manifest.js";
 import {
-	applyProfileChoice,
-	materializeAndActivate,
+	type ActivationResult,
+	activateProfile,
+	activationNotes,
+	assertNoTrackedWriteTargets,
 	reportDisplaced,
 } from "../services/profile-activate.js";
 import {
@@ -31,6 +33,13 @@ import {
 	needsNothing,
 	parseProfileChoice,
 } from "../services/profile-startup.js";
+import {
+	applyProfileChoice,
+	describeUnknownProfile,
+	prepareProfileState,
+	suggestedProfile,
+	switchHint,
+} from "../services/profile-state.js";
 import { SettingsParseError } from "../services/settings-file.js";
 import type { ProfileManifest } from "../types/index.js";
 import { dim } from "./ansi.js";
@@ -57,8 +66,8 @@ export function reportUnparseable(error: SettingsParseError): void {
  * Write the adopted manifest, then put the project ON the profile it describes.
  *
  * Both halves or neither. Writing alone is what made migrating feel like a
- * no-op: `activeProfile()` is derived from the symlink, so a manifest nothing
- * links to changes no behaviour, and the run that just migrated still has to
+ * no-op: `activeProfile()` reads the marker activation writes, so a manifest
+ * nothing activated changes no behaviour, and the run that just migrated still has to
  * ask which profile to use.
  *
  * Activation is reported in full, including anything it moved aside, because it
@@ -75,24 +84,80 @@ async function writeAndActivate(
 	// their hand-written files went.
 	const rel = (p: string) => path.relative(projectPath, p);
 
+	// Before the manifest is written: adopting activates, and activating a
+	// project whose settings.json git tracks would take that file over.
+	await assertNoTrackedWriteTargets(projectPath);
 	await writeManifest(result.manifest, projectPath);
 	console.log(`✓ Wrote ${rel(getManifestPath(projectPath))}`);
 
 	// Each move is printed as it happens, not from the returned list afterwards.
-	// Activation touches up to four artifacts in sequence, so a throw on the
-	// third would discard the record of the first two — and the first of those
-	// is the user's `.claude/settings.json`, now absent from where they left it.
-	// Printing first means a failed activation still says where everything went.
-	await materializeAndActivate(
+	// Activation writes three files in sequence, so a throw on the third would
+	// discard the record of the first two — and the first of those is the
+	// user's `.claude/settings.json`, now absent from where they left it.
+	const activation = await activateProfile(
 		result.manifest,
 		result.profileId,
 		projectPath,
-		reportDisplaced(projectPath),
+		{ onDisplace: reportDisplaced(projectPath) },
 	);
 	console.log(`✓ Active profile: ${result.profileId}`);
+	printActivationNotes(activation);
 	console.log();
 }
 
+/** Print what activation did beyond the switch itself, one line each. */
+export function printActivationNotes(result: ActivationResult): void {
+	for (const line of activationNotes(result)) console.log(noteLine(line));
+}
+
+export interface ProfileGateOptions {
+	/**
+	 * Carry on when the marker names a profile profiles.json does not define.
+	 * Only for commands that fix exactly that by activating a profile that
+	 * exists — `profile switch`, `install`.
+	 */
+	allowUnknown?: boolean;
+}
+
+/**
+ * The gate every CLI command that reads or writes profile state passes first.
+ *
+ * Restores a lost marker when the live config matches exactly one profile,
+ * converts an older layout, absorbs what Claude Code wrote to the live config
+ * into the active profile, and regenerates the live config when profiles.json
+ * changed — printing one line for each. Returns false, having said why, when
+ * the command must not act: a marker naming a profile that does not exist, or
+ * a live file that cannot be read (it would be overwritten).
+ */
+export async function profileGate(
+	projectPath: string,
+	opts: ProfileGateOptions = {},
+): Promise<boolean> {
+	let prep: Awaited<ReturnType<typeof prepareProfileState>>;
+	try {
+		prep = await prepareProfileState(projectPath);
+	} catch (error) {
+		if (error instanceof SettingsParseError) {
+			reportUnparseable(error);
+			return false;
+		}
+		console.error(
+			failLine(error instanceof Error ? error.message : String(error)),
+		);
+		return false;
+	}
+	for (const line of prep.lines) console.log(noteLine(line));
+	if (prep.problems.length > 0) {
+		for (const problem of prep.problems) console.error(failLine(problem));
+		return false;
+	}
+	if (prep.check.state === "unknown" && !opts.allowUnknown) {
+		console.error(failLine(describeUnknownProfile(prep.check)));
+		return false;
+	}
+	return true;
+}
+
 /** Print what adoption would capture, so the user can judge it before writing. */
 function printAdoptionPlan(result: AdoptResult): void {
 	console.log(
@@ -141,12 +206,11 @@ function printAdoptionPlan(result: AdoptResult): void {
 	// onto the profile, which replaces two files that are in the working tree
 	// right now. The prompt below is the only place to decline.
 	console.log(
-		"The project then runs this profile: .claude/settings.json, .mcp.json and",
+		"The project then runs this profile: .claude/settings.json and .mcp.json are",
 	);
 	console.log(
-		".claude/skills become links into it, and your current copies are kept where",
+		"generated from it, and your current copies are kept where the run reports.",
 	);
-	console.log("the run reports.");
 }
 
 export interface EnsureManifestOptions {
@@ -231,7 +295,7 @@ export async function ensureManifest(
  * state is read from and where updates are written. With none there is nothing
  * to read and nowhere to write, so there is no useful work to do — and the
  * previous version of this offered exactly that anyway. It asked only when the
- * manifest had drifted, let the user decline, and `update` then carried on with
+ * manifest disagreed with `enabledPlugins`, let the user decline, and `update` then carried on with
  * a profile "for this run only", resolving against a manifest the project was
  * not running. Two worlds live at once, which is the confusion being removed.
  *
@@ -262,15 +326,16 @@ export async function requireActiveProfile(
 	// `--check` and with no TTY: this is the committed answer being applied, not
 	// a decision being made, and it is exactly the case CI hits.
 	if (need.autoActivate && need.declaredDefault !== null && !opts.check) {
-		const { profileId } = await applyProfileChoice(
+		const result = await applyProfileChoice(
 			{ kind: "activate", id: need.declaredDefault },
 			need.manifest,
 			projectPath,
-			reportDisplaced(projectPath),
+			{ onDisplace: reportDisplaced(projectPath) },
 		);
 		console.log(
-			`✓ Active profile: ${profileId} ${dim("(declared by this project)")}`,
+			`✓ Active profile: ${result.profileId} ${dim("(declared by this project)")}`,
 		);
+		printActivationNotes(result);
 		console.log("");
 		return readManifest(projectPath);
 	}
@@ -292,9 +357,10 @@ export async function requireActiveProfile(
 			noteLine(
 				need.state === "unmigrated"
 					? "Run `magus profile init` to create one deliberately."
-					: `Run \`magus profile switch <${need.activate
-							.map((p) => p.id)
-							.join("|")}>\` first.`,
+					: `Run ${switchHint(
+							need.activate.map((p) => p.id),
+							need.declaredDefault ?? suggestedProfile(need.manifest),
+						)} first.`,
 			),
 		);
 		return null;
@@ -316,13 +382,11 @@ export async function requireActiveProfile(
 		return null;
 	}
 
-	const { profileId } = await applyProfileChoice(
-		choice,
-		need.manifest,
-		projectPath,
-		reportDisplaced(projectPath),
-	);
-	console.log(`✓ Active profile: ${profileId}`);
+	const result = await applyProfileChoice(choice, need.manifest, projectPath, {
+		onDisplace: reportDisplaced(projectPath),
+	});
+	console.log(`✓ Active profile: ${result.profileId}`);
+	printActivationNotes(result);
 	console.log("");
 
 	// Re-read rather than return `need.manifest`: adopting wrote a new profile

package/src/cli/doctor.ts

@@ -5,7 +5,11 @@
  *   0. Global settings — `~/.claude/settings.json` parses.
  *   1. Binary dependencies — every requires.bin / cliTools binary on PATH.
  *      This is the check that would have caught a dead `tmux-mcp`.
- *   2. Profile symlink integrity — the active profile's links resolve.
+ *   2. Profile state — which profile is active (strictly), what the next magus
+ *      command would record or regenerate (with `--fix`, it does it now and
+ *      says what it did), generated files git still tracks, and
+ *      magus-installed skills that are missing. Without `--fix` this section
+ *      writes nothing: no absorbing, no converting an older layout.
  *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
  *   4. Model routing — config validity, hook registration, and drift.
  *   5. Plugin loads — what Claude Code will load here vs what is installed.
@@ -42,8 +46,31 @@ import {
 	type RepoRootCache,
 	pickLoadedEntry,
 } from "../services/plugin-resolution.js";
+import { trackedGeneratedFiles } from "../services/profile-activate.js";
+import {
+	LIVE_FILE_KEYS,
+	liveKind,
+	livePath,
+	readActiveMarker,
+} from "../services/profile-live.js";
+import {
+	describeDependencies,
+	renderProfile,
+} from "../services/profile-render.js";
+import { inspectManagedSkills } from "../services/profile-skills.js";
+import {
+	type ActiveProfileCheck,
+	describeUnknownProfile,
+	describeUnmarked,
+	inspectProfileState,
+	prepareProfileState,
+	switchHint,
+} from "../services/profile-state.js";
 import { resolveAllProfiles } from "../services/resolver.js";
-import { activeProfile, profileDir } from "../services/symlink-manager.js";
+import {
+	GitCheckError,
+	untrackCommand,
+} from "../services/tracked-live-files.js";
 import type {
 	ClaudeSettings,
 	InstalledPluginsRegistry,
@@ -98,18 +125,11 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 		}
 	}
 
-	// 2. Profile symlink integrity.
-	const active = await activeProfile(projectPath);
-	if (active) {
-		const dangling = await danglingLinks(active, projectPath);
-		if (dangling.length > 0) {
-			console.log(`Profile "${active}" has broken symlinks:`);
-			for (const l of dangling) console.log(`  ✗ ${l}`);
-			console.log(`  Fix: magus install ${active}`);
-			problems += dangling.length;
-		} else {
-			console.log(`✓ Active profile "${active}" symlinks resolve.`);
-		}
+	// 2. Profile state.
+	if (manifest) {
+		const profile = await reportProfileState(projectPath, fix);
+		problems += profile.fixable;
+		unfixable += profile.unfixable;
 	}
 
 	// 3. Convention compliance — scoped to THIS project only (the ported engine
@@ -418,32 +438,139 @@ async function checkModels(
 	return { fixable: problems, unfixable };
 }
 
-/** Which of the active profile's expected symlinks are missing or dangling. */
-async function danglingLinks(
-	name: string,
+/**
+ * Section 2: which profile is active, and whether its live config is whole.
+ *
+ * Runs the same gate as every other command first — restoring a lost marker,
+ * converting an older layout, absorbing what Claude Code wrote into the live
+ * config and regenerating from a changed profiles.json — and reports what it
+ * did. What is left is reported plainly, each with its fix.
+ */
+export async function reportProfileState(
 	projectPath: string,
-): Promise<string[]> {
-	const dir = profileDir(name, projectPath);
-	const checks: Array<{ link: string; target: string }> = [
-		{
-			link: path.join(projectPath, ".claude", "settings.json"),
-			target: path.join(dir, "settings.json"),
-		},
-		{
-			link: path.join(projectPath, ".mcp.json"),
-			target: path.join(dir, "mcp.json"),
-		},
-	];
-	const broken: string[] = [];
-	for (const { link, target } of checks) {
-		try {
-			const stat = await fs.lstat(link);
-			if (stat.isSymbolicLink() && !(await fs.pathExists(target))) {
-				broken.push(path.relative(projectPath, link));
+	fix: boolean,
+): Promise<{ fixable: number; unfixable: number }> {
+	const rel = (p: string) => path.relative(projectPath, p);
+	let fixable = 0;
+	let unfixable = 0;
+	let check: ActiveProfileCheck;
+	try {
+		if (fix) {
+			// `--fix`: the same gate every other command runs, reported.
+			const prep = await prepareProfileState(projectPath);
+			check = prep.check;
+			if (check.state === "no-profiles") return { fixable, unfixable };
+			for (const line of prep.lines) console.log(`• ${line}`);
+			for (const problem of prep.problems) {
+				console.log(`✗ ${problem}`);
+				unfixable++;
 			}
-		} catch {
-			// link absent — not "broken", the profile may not provide it.
+		} else {
+			// Report only. Nothing here writes — not an absorb, not a marker, not
+			// a conversion: a diagnostic that changes the project is not one.
+			const report = await inspectProfileState(projectPath);
+			check = report.check;
+			if (check.state === "no-profiles") return { fixable, unfixable };
+			for (const error of report.unreadable) {
+				console.log(`✗ ${error.message}`);
+				console.log(
+					"    Fix the JSON by hand; magus leaves the file as it is.",
+				);
+				unfixable++;
+			}
+			// What the next magus command will do on its own — record an edit,
+			// regenerate, convert, restore a lost marker — is information, not
+			// a fault: none of it makes doctor exit non-zero.
+			for (const line of report.pending) console.log(`• ${line}`);
+		}
+	} catch (error) {
+		console.log("\nProfile:");
+		console.log(
+			`  ✗ ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return { fixable: 0, unfixable: 1 };
+	}
+
+	if (check.state === "unknown") {
+		console.log(`✗ ${describeUnknownProfile(check)}`);
+		unfixable++;
+	} else if (check.state === "unmarked" && check.match !== null) {
+		// The live config matches exactly one profile: the pending line above
+		// already says the next command restores the marker. Not a fault.
+	} else if (check.state === "unmarked") {
+		console.log(
+			check.liveFiles
+				? `✗ ${describeUnmarked(check)}`
+				: `✗ No profile is active yet. Run \`magus install\` or ${switchHint(check.available, check.suggested)}.`,
+		);
+		unfixable++;
+	} else if (check.state === "active" || check.state === "old-layout") {
+		const broken: string[] = [];
+		for (const key of LIVE_FILE_KEYS) {
+			const kind = await liveKind(key, projectPath);
+			// An older layout's links are reported as pending conversion above.
+			if (
+				kind === "other" ||
+				(kind === "symlink" && check.state === "active")
+			) {
+				broken.push(`${rel(livePath(key, projectPath))} is not a regular file`);
+			}
+		}
+		const marker = await readActiveMarker(projectPath);
+		if (marker) {
+			const { missing } = await inspectManagedSkills(
+				marker.skills,
+				projectPath,
+			);
+			for (const folder of missing) {
+				broken.push(`skill .claude/skills/${folder} is missing`);
+			}
+		}
+		if (broken.length > 0) {
+			console.log(`Profile "${check.profile}" is not fully in place:`);
+			for (const line of broken) console.log(`  ✗ ${line}`);
+			console.log(`  Fix: magus profile switch ${check.profile}`);
+			fixable += broken.length;
+		} else if (check.state === "active") {
+			console.log(`✓ Active profile "${check.profile}" is in place.`);
 		}
+		// Plugin dependencies: a dependency the profile turns off stops a plugin
+		// loading; a plugin.json that cannot be read leaves its dependencies
+		// unknown, and they were not enabled.
+		const manifest = await readManifest(projectPath);
+		const { dependencies } = manifest.profiles[check.profile]
+			? await renderProfile(manifest, check.profile, projectPath)
+			: { dependencies: undefined };
+		for (const line of describeDependencies(
+			dependencies && { ...dependencies, unreadable: [] },
+			check.profile,
+		)) {
+			console.log(`✗ ${line}`);
+			unfixable++;
+		}
+		for (const line of describeDependencies(
+			dependencies && { ...dependencies, blocked: [] },
+			check.profile,
+		)) {
+			console.log(`⚠ ${line}`);
+		}
+	}
+
+	// A .gitignore entry does not untrack a file committed before it. Report
+	// only: magus never runs git rm.
+	let tracked: string[] = [];
+	try {
+		tracked = await trackedGeneratedFiles(projectPath);
+	} catch (error) {
+		if (!(error instanceof GitCheckError)) throw error;
+		console.log(`✗ ${error.message}`);
+		unfixable++;
+	}
+	for (const rel of tracked) {
+		console.log(
+			`✗ ${rel} is generated from profiles.json but tracked by git. Fix: \`${untrackCommand(rel)}\`, then commit.`,
+		);
+		unfixable++;
 	}
-	return broken;
+	return { fixable, unfixable };
 }