magus-cli 7.4.0 → 7.5.0

package/src/cli/doctor.ts

@@ -5,16 +5,20 @@
  *   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.
  *
  * A file that exists and does not parse — the global settings, the project's
- * `.claude/profiles.json` or its `.claude/settings.json` — is a finding in the
- * section that meets it, never an abort: the rest of the report is still worth
- * having. `--fix` repairs none of them, because magus never rewrites a file it
- * cannot parse.
+ * `.claude/profiles.json` or its `.claude/settings.json`, Claude Code's
+ * `installed_plugins.json` — is a finding in the section that meets it, never an
+ * abort: the rest of the report is still worth having. `--fix` repairs none of
+ * them, because magus never rewrites a file it cannot parse.
  */
 
 import path from "node:path";
@@ -42,9 +46,31 @@ import {
 	type RepoRootCache,
 	pickLoadedEntry,
 } from "../services/plugin-resolution.js";
+import {
+	trackedGeneratedFiles,
+	untrackCommand,
+} from "../services/profile-activate.js";
+import {
+	LIVE_FILE_KEYS,
+	liveKind,
+	livePath,
+	readActiveMarker,
+} from "../services/profile-live.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 type { ClaudeSettings, ProfileManifest } from "../types/index.js";
+import type {
+	ClaudeSettings,
+	InstalledPluginsRegistry,
+	ProfileManifest,
+} from "../types/index.js";
 import { resolveExecutable } from "../utils/command-utils.js";
 
 export async function runDoctorCommand(args: string[]): Promise<number> {
@@ -94,18 +120,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
@@ -232,7 +251,17 @@ export function doctorExitCode(args: {
  *   loads     — the loader's, `pickLoadedEntry`
  */
 async function checkPluginLoads(projectPath: string): Promise<number> {
-	const registry = await readInstalledPluginsRegistry();
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = await readInstalledPluginsRegistry();
+	} catch (error) {
+		// A registry nothing can read is a finding, not an abort: doctor is the
+		// command someone runs BECAUSE something is wrong, and it has to reach its
+		// remaining sections and its exit code.
+		if (!(error instanceof SettingsParseError)) throw error;
+		reportUnparseable("Plugin loads", error);
+		return 1;
+	}
 	let settings: ClaudeSettings;
 	try {
 		settings = await readSettings(projectPath);
@@ -404,32 +433,111 @@ 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.`);
 		}
 	}
-	return broken;
+
+	// A .gitignore entry does not untrack a file committed before it. Report
+	// only: magus never runs git rm.
+	for (const tracked of await trackedGeneratedFiles(projectPath)) {
+		console.log(
+			`✗ ${tracked} is generated from profiles.json but tracked by git. Fix: \`${untrackCommand(tracked)}\`, then commit.`,
+		);
+		unfixable++;
+	}
+	return { fixable, unfixable };
 }

package/src/cli/install.ts

@@ -1,18 +1,18 @@
 /**
  * `magus install [profile] [--check] [--yes]`
  *
- * Materialize a committed team profile from .claude/profiles.json onto this
- * machine: register marketplaces, install pinned plugins, install the binaries
- * plugins declare (requires.bin) plus the profile's cliTools, install skills,
- * collect required env, then activate the profile via symlinks.
+ * Put a committed team profile from .claude/profiles.json onto this machine:
+ * register marketplaces, activate the profile (render its settings.json,
+ * .mcp.json and models.json, install its skills), install its pinned plugins
+ * and the binaries plugins declare (requires.bin) plus the profile's cliTools,
+ * then collect required env.
  *
- * With no argument it installs the union of every profile's deps and
- * materializes them all (so `profile switch` needs no reinstall), then
- * activates one. `--check` is a read-only drift gate for CI. `--yes` skips
+ * With no argument it installs the union of every profile's deps (so `profile
+ * switch` needs no reinstall) and keeps the active profile active, asking only
+ * when none is. `--check` is a read-only version gate for CI. `--yes` skips
  * the confirmation prompt.
  */
 
-import path from "node:path";
 import { installPlugin, isClaudeAvailable } from "../services/claude-cli.js";
 import {
 	getLocalSettingsPath,
@@ -20,45 +20,36 @@ import {
 	readLocalSettings,
 	writeLocalSettings,
 } from "../services/claude-settings.js";
-import { ensureGitignoreEntries } from "../services/conventions-manager.js";
 import {
 	computeEnvStatus,
 	computeVersionDrift,
 	summarizeClosure,
 } from "../services/install-plan.js";
-import { validateManifest } from "../services/manifest.js";
+import { readManifest, validateManifest } from "../services/manifest.js";
 import { registerClosureMarketplaces } from "../services/marketplace-sync.js";
 import { reportDisplaced } from "../services/profile-activate.js";
-import { materializeProfile } from "../services/profile-materializer.js";
-import { detectProfileDrift } from "../services/profile-sync.js";
-import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
-import { writableMap } from "../services/settings-file.js";
-import { installSkill } from "../services/skills-manager.js";
+import { activeProfile } from "../services/profile-live.js";
 import {
-	PROFILE_GITIGNORE_ENTRIES,
-	activateProfile,
-	activeProfile,
-} from "../services/symlink-manager.js";
+	switchToProfile,
+	withCliBookkeeping,
+} from "../services/profile-state.js";
+import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
+import { SettingsParseError, writableMap } from "../services/settings-file.js";
 import {
 	TOOLCHAIN_BOOTSTRAP,
 	binInstallCommand,
 	detectToolchains,
 } from "../services/toolchain.js";
-import type {
-	ProfileSkillRef,
-	ResolvedBin,
-	ResolvedClosure,
-	SkillInfo,
-} from "../types/index.js";
+import type { ResolvedBin, ResolvedClosure } from "../types/index.js";
 import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
 import { runCommand, runShellScript } from "../utils/run.js";
-import { ensureManifest } from "./bootstrap.js";
+import { ensureManifest, printActivationNotes } from "./bootstrap.js";
 import { confirm, promptValue } from "./prompt.js";
+import { note as noteLine } from "./update-view.js";
 
 interface InstallFlags {
 	check: boolean;
 	yes: boolean;
-	force: boolean;
 	profile?: string;
 }
 
@@ -66,12 +57,11 @@ function parseArgs(args: string[]): InstallFlags {
 	return {
 		check: args.includes("--check"),
 		yes: args.includes("--yes") || args.includes("-y"),
-		force: args.includes("--force"),
 		profile: args.find((a) => !a.startsWith("-")),
 	};
 }
 
-// ── --check: read-only drift gate ───────────────────────────────────────────
+// ── --check: read-only version gate ─────────────────────────────────────────
 
 async function runCheck(
 	closure: ResolvedClosure,
@@ -149,9 +139,10 @@ async function ensureToolchains(
  * Project scope keeps the blast radius to this repo. The plugin *cache* is
  * global either way, so `profile switch` stays offline.
  *
- * Whatever the CLI writes into .claude/settings.json here is transient:
- * materialization rewrites that file from the manifest, and activation replaces
- * it with a symlink. The manifest stays authoritative.
+ * The CLI records each install in the live `.claude/settings.json`. That is
+ * its bookkeeping, not a change to the profile — with no argument this installs
+ * EVERY profile's plugins — so the caller runs this inside
+ * `withCliBookkeeping`, which renders the live files over it afterwards.
  */
 async function installPlugins(closure: ResolvedClosure): Promise<void> {
 	for (const pluginId of Object.keys(closure.plugins)) {
@@ -179,39 +170,6 @@ async function installBins(bins: ResolvedBin[]): Promise<void> {
 	}
 }
 
-/** Map a manifest skill ref to the SkillInfo shape installSkill expects. */
-function toSkillInfo(ref: ProfileSkillRef): SkillInfo {
-	return {
-		id: `${ref.repo}/${ref.path}`,
-		name: ref.name,
-		source: {
-			label: ref.repo,
-			repo: ref.repo,
-			skillsPath: path.dirname(ref.path),
-		},
-		repoPath: ref.path,
-		gitBlobSha: "",
-		frontmatter: null,
-		installed: false,
-		installedScope: null,
-		hasUpdate: false,
-	};
-}
-
-async function installSkills(
-	skills: ProfileSkillRef[],
-	projectPath: string,
-): Promise<void> {
-	for (const ref of skills) {
-		try {
-			console.log(`+ skill ${ref.name}`);
-			await installSkill(toSkillInfo(ref), "project", projectPath);
-		} catch (e) {
-			console.warn(`⚠ skill ${ref.name}: ${(e as Error).message}`);
-		}
-	}
-}
-
 async function collectEnv(
 	closure: ResolvedClosure,
 	projectPath: string,
@@ -230,17 +188,42 @@ async function collectEnv(
 		return;
 	}
 
-	const local = await readLocalSettings(projectPath);
-	// Checked before the first prompt, so a malformed `env` is refused before the
-	// user types anything, not after — and never replaced.
-	const env =
-		writableMap(local, "env", getLocalSettingsPath(projectPath)) ?? {};
-	local.env = env;
+	// EVERY answer first, then one read-modify-write.
+	//
+	// The read has to happen AFTER the last prompt. Claude Code writes
+	// settings.local.json while these prompts are on screen — it is where a
+	// "don't ask again" permission rule lands — and this used to read the file
+	// before the first question and write that copy back at the end, so every
+	// rule the user granted in between was erased. The prompts are the slow part,
+	// and a read from before them describes a file that no longer exists.
+	const answers: Array<[string, string]> = [];
 	for (const name of status.missingRequired) {
 		const value = await promptValue(`  ${name} = `);
-		if (value) env[name] = value;
+		if (value) answers.push([name, value]);
+	}
+
+	const localPath = getLocalSettingsPath(projectPath);
+	try {
+		// Refuses a file that stopped parsing while the prompts were up, and a
+		// malformed `env` map, before anything is written. Either way the file is
+		// left exactly as it is.
+		const local = await readLocalSettings(projectPath);
+		const env = writableMap(local, "env", localPath) ?? {};
+		local.env = env;
+		for (const [name, value] of answers) env[name] = value;
+		await writeLocalSettings(local, projectPath);
+	} catch (error) {
+		// Which variables went unsaved, by NAME — never the values. They are
+		// tokens, and a refusal is not a reason to print one to a terminal.
+		if (error instanceof SettingsParseError && answers.length > 0) {
+			console.error(
+				`Not saved: ${answers
+					.map(([name]) => name)
+					.join(", ")} — set them again once the file is fixed.`,
+			);
+		}
+		throw error;
 	}
-	await writeLocalSettings(local, projectPath);
 	console.log("Saved to .claude/settings.local.json (personal, gitignored).");
 }
 
@@ -287,26 +270,6 @@ export async function runInstallCommand(
 		return runCheck(closure, manifest.strictVersions === true);
 	}
 
-	// Drift guard: refuse to clobber unsynced local edits to the active profile
-	// (materialize would overwrite them) unless --force is given.
-	if (!flags.force) {
-		const active = await activeProfile(projectPath);
-		if (active && (flags.profile === undefined || flags.profile === active)) {
-			const drift = await detectProfileDrift(active, projectPath);
-			if (drift.length > 0) {
-				console.error(
-					`Active profile "${active}" has unsynced local edits that install would overwrite:`,
-				);
-				for (const c of drift) console.error(`  ${c.kind}: ${c.detail}`);
-				console.error(
-					"\nRun `magus profile sync` to promote them into .claude/profiles.json,\n" +
-						"or re-run with --force to discard them.",
-				);
-				return 1;
-			}
-		}
-	}
-
 	// Plan
 	console.log(`\nPlan for ${flags.profile ?? "all profiles"}:`);
 	for (const line of summarizeClosure(closure)) console.log(`  ${line}`);
@@ -332,45 +295,47 @@ export async function runInstallCommand(
 
 	await ensureToolchains(closure, flags.yes);
 	await registerClosureMarketplaces(closure.marketplaces);
-	await installPlugins(closure);
-	await installBins(closure.bins);
 
-	// Materialize every profile (so `profile switch` needs no reinstall), then
-	// activate the target (or the sole/first profile).
-	//
-	// Every profile is materialized even when one was named: a profile arg scopes
-	// what gets *installed* and which becomes active, not which settings files
-	// exist. It also keeps the union below consistent across all of them — a
-	// profile left holding an older union would stop disabling plugins added
-	// since, silently making `switch` additive again.
-	const unionPluginIds = Object.keys(
-		(flags.profile ? await resolveAllProfiles(manifest) : closure).plugins,
-	);
-	for (const id of profileIds) {
-		const profileClosure = await resolveProfile(manifest, id);
-		await materializeProfile(id, profileClosure, projectPath, unionPluginIds);
+	const current = await activeProfile(projectPath);
+	const activeId =
+		flags.profile ??
+		current ??
+		(await pickActiveProfile(profileIds, flags.yes));
+	if (activeId) {
+		// The one switch path: what Claude Code wrote into the live config — or
+		// through an older layout's links — goes into the profile it was written
+		// under (or, if profiles.json no longer defines that one, into this one)
+		// before anything is rendered over it. The displacement reporter is not
+		// optional: a first `install` over a hand-written settings.json moves it
+		// aside, and the move must never be silent.
+		const switched = await switchToProfile(projectPath, activeId, {
+			onDisplace: reportDisplaced(projectPath),
+		});
+		for (const line of switched.lines) console.log(noteLine(line));
+		if (!switched.activation) {
+			for (const problem of switched.problems) console.error(problem);
+			return 1;
+		}
+		console.log(`\n✓ Active profile: ${activeId}`);
+		printActivationNotes(switched.activation);
 	}
 
-	// Keep the generated dir + active-profile symlinks out of git before
-	// activating (source of truth is .claude/profiles.json).
-	await ensureGitignoreEntries(
-		path.join(projectPath, ".gitignore"),
-		PROFILE_GITIGNORE_ENTRIES,
-		"# magus: generated profile build output + active-profile symlinks",
-	);
+	// The CLI's installs write enabledPlugins for every plugin installed — all
+	// profiles' when no profile was named. `withCliBookkeeping` flags the marker
+	// while they run and reconciles in `finally`: what the user changed in the
+	// meantime is kept, only the install's own records are discarded, and a
+	// Ctrl-C leaves the flag for the next command to do the same.
+	await withCliBookkeeping(projectPath, () => installPlugins(closure), {
+		report: (line) => console.log(noteLine(line)),
+	});
+	await installBins(closure.bins);
 
-	const activeId =
-		flags.profile ?? (await pickActiveProfile(profileIds, flags.yes));
 	if (activeId) {
-		// The reporter is not optional here. The first `install` in a project that
-		// had a hand-written .claude/settings.json moves it aside, and without
-		// this the move is invisible — the file is simply not where it was.
-		await activateProfile(activeId, projectPath, reportDisplaced(projectPath));
-		console.log(`\n✓ Active profile: ${activeId}`);
-		// Skills route through the now-active .claude/skills symlink.
-		const activeClosure = await resolveProfile(manifest, activeId);
-		await installSkills(activeClosure.skills, projectPath);
-		await collectEnv(activeClosure, projectPath, flags.yes);
+		await collectEnv(
+			await resolveProfile(await readManifest(projectPath), activeId),
+			projectPath,
+			flags.yes,
+		);
 	}
 
 	console.log("\nDone.");

package/src/cli/models.ts

@@ -18,6 +18,7 @@ import {
 	presetLabel,
 	presetNames,
 } from "../data/models-presets.js";
+import { readManifest } from "../services/manifest.js";
 import {
 	loadMateCatalog,
 	stalenessNote,
@@ -40,7 +41,23 @@ import {
 	readModelsConfig,
 	readModelsStatus,
 } from "../services/models-manager.js";
-import { ensureManifest } from "./bootstrap.js";
+import { activeProfile } from "../services/profile-live.js";
+import { ensureManifest, requireActiveProfile } from "./bootstrap.js";
+
+/**
+ * A project with profiles must be ON one before routing is written: the
+ * routing is a property of the active profile. With none active this asks at a
+ * terminal and stops with the instruction anywhere else, rather than writing a
+ * plain models.json the next activation would replace.
+ */
+async function requireProfileWhenManaged(
+	projectPath: string,
+): Promise<boolean> {
+	const manifest = await readManifest(projectPath);
+	if (Object.keys(manifest.profiles).length === 0) return true;
+	if ((await activeProfile(projectPath)) !== null) return true;
+	return (await requireActiveProfile(projectPath, manifest)) !== null;
+}
 
 const HEADLINE: Record<ModelsState, string> = {
 	off: "off — no .claude/models.json, subagents inherit the session model",
@@ -206,6 +223,8 @@ async function runUse(projectPath: string, name?: string): Promise<number> {
 		return 1;
 	}
 
+	if (!(await requireProfileWhenManaged(projectPath))) return 1;
+
 	let result: Awaited<ReturnType<typeof applyModelPreset>>;
 	try {
 		result = await applyModelPreset({
@@ -247,6 +266,7 @@ async function runUse(projectPath: string, name?: string): Promise<number> {
 }
 
 async function runOff(projectPath: string): Promise<number> {
+	if (!(await requireProfileWhenManaged(projectPath))) return 1;
 	await clearModels(projectPath);
 	console.log(
 		"\n✓ Model tiers off. Subagents inherit the session model again.",