magus-cli 7.1.0 → 7.3.0

package/src/__tests__/useStaleLoadModal.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildStaleLoadModal,
+	staleLoadRepairSummary,
+} from "../ui/hooks/useStaleLoadModal";
+
+/**
+ * The startup popup for a broken plugin.
+ *
+ * Same shape as buildGitignoreModal beside it, with one difference that is the
+ * whole point of the popup: FIXING is the default. A plugin the loader resolves
+ * at the wrong version means every session in this directory runs code nobody
+ * installed, so Enter must repair it rather than dismiss.
+ */
+describe("buildStaleLoadModal", () => {
+	const args = (
+		over: Partial<Parameters<typeof buildStaleLoadModal>[0]> = {},
+	) => ({
+		brokenCount: 2,
+		onFix: () => {},
+		onOpenTab: () => {},
+		onDismiss: () => {},
+		...over,
+	});
+
+	it("offers fix, review and dismiss, with FIX first", () => {
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options.map((o) => o.value)).toEqual([
+			"fix",
+			"open-tab",
+			"dismiss",
+		]);
+	});
+
+	it("defaults to FIX explicitly, not by accident of ordering", () => {
+		// Stated in the data so a future reordering cannot quietly make "leave it
+		// broken" the thing Enter does.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.defaultIndex).toBe(0);
+		expect(modal.options[modal.defaultIndex ?? -1]?.value).toBe("fix");
+	});
+
+	it("blames the Claude Code bug, not magus's own state", () => {
+		// The title is the whole message for anyone who reads one line. It has to
+		// say what is wrong — a defect in Claude Code's loader — rather than
+		// report that two of magus's stores disagree, which is not actionable and
+		// reads as though the user misconfigured something.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.title).toContain("Claude Code");
+		expect(modal.message).toContain("stale cached version");
+		expect(modal.options[0].label).toBe("Fix it (3 plugins)");
+		expect(modal.message).toContain("3 plugins are on an older version");
+	});
+
+	it("says the reach is every worktree, not just this directory", () => {
+		// Relevance is decided by repository root, so every worktree and the main
+		// checkout resolve identically and break together. A reader told only
+		// about "this directory" would fix one worktree and expect the others to
+		// differ — they cannot.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain("every worktree");
+		expect(modal.message).toContain("main checkout");
+	});
+
+	it("states the effect plainly, without overstating it", () => {
+		// A draft claimed "your sessions run code you did not install". Nothing
+		// happens to the user's code; an old cached plugin version is used. The
+		// overstatement is pinned here so it cannot come back on the next edit.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).not.toContain("run code");
+		expect(modal.message).not.toContain("did not install");
+	});
+
+	it("reads correctly for a single plugin", () => {
+		const modal = buildStaleLoadModal(args({ brokenCount: 1 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options[0].label).toBe("Fix it (1 plugin)");
+		expect(modal.message).toContain("1 plugin is on an older version");
+	});
+
+	it("promises the backup and promises not to delete or downgrade", () => {
+		// The popup is asking permission to edit Claude Code-owned state. What it
+		// will and will not do has to be on the screen, not only in a code comment.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain(
+			"installed_plugins.json is backed up first",
+		);
+		// Case-insensitive: the promise has to be on screen, but whether it opens a
+		// sentence or trails one is a wording choice, and pinning the capital made
+		// an ordinary copy edit fail for nothing.
+		expect(modal.message.toLowerCase()).toContain(
+			"nothing is deleted or downgraded",
+		);
+	});
+
+	it("routes each choice to its callback, and cancel to dismiss", () => {
+		let fixed = 0;
+		let opened = 0;
+		let dismissed = 0;
+		const modal = buildStaleLoadModal(
+			args({
+				onFix: () => {
+					fixed++;
+				},
+				onOpenTab: () => {
+					opened++;
+				},
+				onDismiss: () => {
+					dismissed++;
+				},
+			}),
+		);
+		if (modal.type !== "select") throw new Error("type guard");
+
+		modal.onSelect("fix");
+		modal.onSelect("open-tab");
+		modal.onSelect("dismiss");
+		modal.onCancel();
+
+		expect({ fixed, opened, dismissed }).toEqual({
+			fixed: 1,
+			opened: 1,
+			dismissed: 2,
+		});
+	});
+});
+
+describe("staleLoadRepairSummary", () => {
+	it("says what loads NOW for each repaired plugin", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "madbench@magus", target: "0.5.0", ok: true },
+				{ pluginId: "dev@magus", target: "7.4.0", ok: true },
+			]),
+		).toBe("✓ madbench@magus now loads v0.5.0\n✓ dev@magus now loads v7.4.0");
+	});
+
+	it("reports a failed repair with its own reason, never as a success", () => {
+		expect(
+			staleLoadRepairSummary([
+				{
+					pluginId: "madbench@magus",
+					target: "0.5.0",
+					ok: false,
+					error: "the loader still resolves v0.3.0 here, not v0.5.0",
+				},
+			]),
+		).toBe(
+			"✗ madbench@magus — the loader still resolves v0.3.0 here, not v0.5.0",
+		);
+	});
+
+	it("falls back to a plain reason rather than an empty line", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "a@magus", target: "1.0.0", ok: false },
+			]),
+		).toBe("✗ a@magus — repair did not take effect");
+	});
+
+	it("says so when there was nothing to repair", () => {
+		expect(staleLoadRepairSummary([])).toBe("Nothing to repair.");
+	});
+});

package/src/cli/ansi.ts

@@ -513,6 +513,45 @@ export function badge(label: string, hex: string, ink?: string): string {
  */
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 
+/**
+ * A bordered dialog: title in the top rule, body inside, one blank row of
+ * breathing space top and bottom.
+ *
+ * Built on `padEnd`, which measures visible cells, so a body line carrying
+ * colour still aligns — padding a coloured string by `String.length` counts the
+ * escape bytes and shears the right border by however many bytes the colour
+ * cost.
+ *
+ * The border and the rule are dim and the body is not: a frame that competes
+ * with its own contents is why a boxed message can read as louder but say less.
+ */
+export function dialog(
+	title: string,
+	lines: string[],
+	opts: { width?: number; color?: string } = {},
+): string[] {
+	const inner = Math.max(
+		opts.width ?? 0,
+		...lines.map((l) => width(l)),
+		width(title) + 4,
+	);
+	const accent = opts.color;
+	const paint = (s: string) => (accent ? fg(accent, s) : s);
+
+	// Every row must be `inner + 4` cells: corner, space, body, space, corner.
+	// The head spends 2 on "╭─" and `width(title) + 2` on the titled gap, so the
+	// rule takes the rest. Getting this off by one is invisible in source and
+	// obvious on screen — the right border jags one column in at the title row.
+	const head = `${paint("╭─")}${paint(` ${title} `)}${dim(
+		"─".repeat(Math.max(0, inner - width(title) - 1)),
+	)}${dim("╮")}`;
+	const foot = dim(`╰${"─".repeat(inner + 2)}╯`);
+	const row = (text: string) =>
+		`${dim("│")} ${padEnd(text, inner)} ${dim("│")}`;
+
+	return [head, row(""), ...lines.map(row), row(""), foot];
+}
+
 export function spinner(tick: number): string {
 	return SPINNER[Math.abs(Math.trunc(tick)) % SPINNER.length];
 }

package/src/cli/bootstrap.ts

@@ -8,17 +8,74 @@
  * stands, then the original command proceeds against it normally.
  */
 
+import path from "node:path";
 import {
 	getManifestPath,
 	readManifest,
 	writeManifest,
 } from "../services/manifest.js";
+import {
+	applyProfileChoice,
+	materializeAndActivate,
+	reportDisplaced,
+} from "../services/profile-activate.js";
 import {
 	type AdoptResult,
 	adoptCurrentProject,
 } from "../services/profile-adopt.js";
+import {
+	buildProfileOptions,
+	defaultOptionIndex,
+	describeNeed,
+	detectProfileStartupNeed,
+	needsNothing,
+	parseProfileChoice,
+} from "../services/profile-startup.js";
 import type { ProfileManifest } from "../types/index.js";
+import { dim } from "./ansi.js";
 import { confirm } from "./prompt.js";
+import { selectDialog } from "./tui-prompt.js";
+import { fail as failLine, note as noteLine } from "./update-view.js";
+
+/**
+ * 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
+ * ask which profile to use.
+ *
+ * Activation is reported in full, including anything it moved aside, because it
+ * replaces files the user wrote by hand. A migration is allowed to change the
+ * working tree; it is not allowed to do it quietly.
+ */
+async function writeAndActivate(
+	result: AdoptResult,
+	projectPath: string,
+): Promise<void> {
+	// Relative to the project throughout. These are all project paths, and an
+	// absolute one wraps over two terminal lines — several wrapped lines in a row
+	// is where a reader stops reading, and this notice is the one that says where
+	// their hand-written files went.
+	const rel = (p: string) => path.relative(projectPath, p);
+
+	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(
+		result.manifest,
+		result.profileId,
+		projectPath,
+		reportDisplaced(projectPath),
+	);
+	console.log(`✓ Active profile: ${result.profileId}`);
+	console.log();
+}
 
 /** Print what adoption would capture, so the user can judge it before writing. */
 function printAdoptionPlan(result: AdoptResult): void {
@@ -64,6 +121,16 @@ function printAdoptionPlan(result: AdoptResult): void {
 	console.log(
 		"\nCommit the file to share this setup with the team; edit it to pin versions.",
 	);
+	// Said before the question, not after it: adopting also SWITCHES the project
+	// 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",
+	);
+	console.log(
+		".claude/skills become links into it, and your current copies are kept where",
+	);
+	console.log("the run reports.");
 }
 
 export interface EnsureManifestOptions {
@@ -123,12 +190,111 @@ export async function ensureManifest(
 			"\nRefusing to create .claude/profiles.json without a human: run `magus profile init` to create it deliberately.",
 		);
 		return null;
-	} else if (!(await confirm("\nCreate .claude/profiles.json?"))) {
+	} else if (!(await confirm("\nCreate it and switch to it?"))) {
 		console.log("Aborted — nothing written.");
 		return null;
 	}
 
-	await writeManifest(result.manifest, projectPath);
-	console.log(`✓ Wrote ${getManifestPath(projectPath)}\n`);
+	await writeAndActivate(result, projectPath);
 	return result.manifest;
 }
+
+/**
+ * Require an active profile, or stop the command.
+ *
+ * magus manages a project THROUGH its active profile: that is where plugin
+ * 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
+ * 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.
+ *
+ * So this asks whenever no profile is active, and the only answers are migrate,
+ * activate, or stop. Returns the manifest to carry on with, or null when the
+ * command must exit non-zero — by which point it has printed why.
+ *
+ * Nothing is compared. An earlier version weighed the manifest against
+ * `enabledPlugins`; see the header of `services/profile-startup.ts` for why
+ * that reads a profiled project's own generated output and cannot be acted on.
+ */
+export async function requireActiveProfile(
+	projectPath: string,
+	manifest: ProfileManifest,
+	opts: EnsureManifestOptions = {},
+): Promise<ProfileManifest | null> {
+	const need = await detectProfileStartupNeed(projectPath);
+	if (needsNothing(need)) return manifest;
+
+	// The repo declares which profile it wants and there is nothing of the
+	// user's to replace — a fresh clone. Activate it and carry on, even under
+	// `--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(
+			{ kind: "activate", id: need.declaredDefault },
+			need.manifest,
+			projectPath,
+			reportDisplaced(projectPath),
+		);
+		console.log(
+			`✓ Active profile: ${profileId} ${dim("(declared by this project)")}`,
+		);
+		console.log("");
+		return readManifest(projectPath);
+	}
+
+	const { title } = describeNeed(need);
+
+	// `--check` is a read-only CI gate, and "this project is not on a profile"
+	// is a legitimate thing for it to fail on rather than quietly repair.
+	if (opts.check) {
+		console.error(failLine(title));
+		console.error(noteLine("Run `magus update` at a terminal to resolve it."));
+		return null;
+	}
+
+	// CI has nobody to ask. Exiting beats hanging on an answer that cannot come.
+	if (!process.stdin.isTTY) {
+		console.error(failLine(title));
+		console.error(
+			noteLine(
+				need.state === "unmigrated"
+					? "Run `magus profile init` to create one deliberately."
+					: `Run \`magus profile switch <${need.activate
+							.map((p) => p.id)
+							.join("|")}>\` first.`,
+			),
+		);
+		return null;
+	}
+
+	console.log("");
+	const chosen = await selectDialog({
+		title,
+		message: describeNeed(need).message,
+		options: buildProfileOptions(need),
+		defaultIndex: defaultOptionIndex(need),
+	});
+
+	// Esc, Ctrl+C and the "Quit magus" row all land here, and there is no third
+	// outcome: the command stops rather than proceed without a profile.
+	const choice = chosen === null ? null : parseProfileChoice(chosen, need);
+	if (!choice) {
+		console.error(failLine("No active profile — stopping."));
+		return null;
+	}
+
+	const { profileId } = await applyProfileChoice(
+		choice,
+		need.manifest,
+		projectPath,
+		reportDisplaced(projectPath),
+	);
+	console.log(`✓ Active profile: ${profileId}`);
+	console.log("");
+
+	// Re-read rather than return `need.manifest`: adopting wrote a new profile
+	// into the file, and the caller resolves against whatever comes back.
+	return readManifest(projectPath);
+}

package/src/cli/doctor.ts

@@ -7,10 +7,16 @@
  *   2. Profile symlink integrity — the active profile's links resolve.
  *   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.
  */
 
 import path from "node:path";
 import fs from "fs-extra";
+import {
+	getProjectInstalledPluginVersions,
+	readInstalledPluginsRegistry,
+	readSettings,
+} from "../services/claude-settings.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import {
@@ -22,6 +28,11 @@ import {
 	readModelsConfig,
 	readModelsStatus,
 } from "../services/models-manager.js";
+import { isBehind } from "../services/plugin-manager.js";
+import {
+	type RepoRootCache,
+	pickLoadedEntry,
+} from "../services/plugin-resolution.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
 import { resolveExecutable } from "../utils/command-utils.js";
@@ -111,8 +122,123 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	// 4. Model routing.
 	problems += await checkModels(projectPath, fix);
 
-	if (problems === 0) console.log("\n✓ No problems found.");
-	return problems > 0 && !fix ? 1 : 0;
+	// 5. Stale plugin loads. Counted SEPARATELY, because `--fix` does not repair
+	// them — see doctorExitCode.
+	const staleLoads = await checkPluginLoads(projectPath);
+
+	if (problems === 0 && staleLoads === 0) console.log("\n✓ No problems found.");
+	return doctorExitCode({ fixable: problems, unfixable: staleLoads, fix });
+}
+
+/**
+ * Doctor's exit code.
+ *
+ * `--fix` suppresses the exit code for what it repaired — that is the point of
+ * the flag, and a caller that asked for repairs does not want a red exit over
+ * problems that are now gone. It must NOT suppress a class it never touches.
+ *
+ * Stale plugin loads are exactly that class: `checkPluginLoads` prints them and
+ * says so, and the repair lives in `repairStaleLoad`, reached by `magus update`
+ * and the Plugins screen. Folding them into the same counter meant `magus doctor
+ * --fix` printed red lines and exited 0 — so a CI or pre-flight step went green
+ * over a plugin whose sessions run a version nobody installed, which is the same
+ * deception the stale-load work exists to end.
+ *
+ * Pure and exported so the decision is pinned by a test rather than inferred from
+ * a command that needs a real `~/.claude` to run.
+ */
+export function doctorExitCode(args: {
+	/** Problems `--fix` can act on. */
+	fixable: number;
+	/** Problems it cannot — reported either way, and never silenced by `--fix`. */
+	unfixable: number;
+	fix: boolean;
+}): number {
+	if (args.unfixable > 0) return 1;
+	return args.fixable > 0 && !args.fix ? 1 : 0;
+}
+
+/**
+ * Plugins whose installed version is NOT the version that will load here.
+ *
+ * Reported, never repaired — `--fix` deliberately does nothing about it, and
+ * that is a division of labour rather than a dead end. A reinstall does not
+ * clear this (measured): it writes another `installed_plugins.json` row for THIS
+ * project, while the row the loader picks belongs to a different one — usually a
+ * worktree that has since been deleted, whose entry nothing prunes. Moving those
+ * rows forward is what fixes it, and that lives in `repairStaleLoad`, reached by
+ * `magus update` and by the Plugins screen's `a` key. Doctor's job is to name
+ * the winner, which is the one thing neither of those prints.
+ *
+ * Both halves come from the registry rather than the catalog, so this section
+ * makes no network call and holds even when GitHub is unreachable:
+ *   installed — magus's own resolution, `pickRegistryEntry` via settings overlay
+ *   loads     — the loader's, `pickLoadedEntry`
+ */
+async function checkPluginLoads(projectPath: string): Promise<number> {
+	const registry = await readInstalledPluginsRegistry();
+	const settings = await readSettings(projectPath);
+	const installed = await getProjectInstalledPluginVersions(
+		settings.installedPluginVersions || {},
+		projectPath,
+	);
+	const ids = Object.keys(installed);
+	if (ids.length === 0) return 0;
+
+	// One cache across every plugin: the same handful of project paths repeat in
+	// hundreds of rows, and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const stale: Array<{
+		pluginId: string;
+		loaded: string;
+		recorded: string;
+		winner: string;
+	}> = [];
+
+	for (const pluginId of ids.sort()) {
+		const recorded = installed[pluginId];
+		if (!recorded) continue;
+		const pick = pickLoadedEntry(
+			registry.plugins?.[pluginId],
+			projectPath,
+			cache,
+		);
+		if (!pick?.version) continue;
+		// The same predicate the classifier uses, so doctor and the plugin screen
+		// cannot disagree about which pairs count. Unorderable pairs answer null
+		// and are left alone — "cannot tell" is not a finding.
+		if (isBehind(recorded, pick.version) !== true) continue;
+		stale.push({
+			pluginId,
+			loaded: pick.version,
+			recorded,
+			winner:
+				pick.projectPath ??
+				(pick.scope === "user" ? "user scope (no project)" : "unknown project"),
+		});
+	}
+
+	console.log("\nPlugin loads:");
+	if (stale.length === 0) {
+		console.log(
+			`  ✓ All ${ids.length} installed plugins load at their installed version.`,
+		);
+		return 0;
+	}
+
+	for (const row of stale) {
+		console.log(
+			`  ✗ ${row.pluginId} — loads v${row.loaded}, installed v${row.recorded}`,
+		);
+		console.log(`      the entry that wins belongs to ${row.winner}`);
+	}
+	console.log(
+		"    Reinstalling does not fix this. Run `magus update` — it moves those",
+	);
+	console.log(
+		"    install records forward, backing up installed_plugins.json first.",
+	);
+	return stale.length;
 }
 
 /**

package/src/cli/install.ts

@@ -27,6 +27,7 @@ import {
 } from "../services/install-plan.js";
 import { 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";
@@ -355,7 +356,10 @@ export async function runInstallCommand(
 	const activeId =
 		flags.profile ?? (await pickActiveProfile(profileIds, flags.yes));
 	if (activeId) {
-		await activateProfile(activeId, projectPath);
+		// 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);

package/src/cli/profile.ts

@@ -13,6 +13,7 @@ import { ensureGitignoreEntries } from "../services/conventions-manager.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
 import { summarizeClosure } from "../services/install-plan.js";
 import { getManifestPath, readManifest } from "../services/manifest.js";
+import { reportDisplaced } from "../services/profile-activate.js";
 import { syncProfile } from "../services/profile-sync.js";
 import { resolveProfile } from "../services/resolver.js";
 import {
@@ -147,7 +148,10 @@ export async function switchProfile(
 		"# magus: generated profile build output + active-profile symlinks",
 	);
 
-	await activateProfile(name, projectPath);
+	// Switching between two already-active profiles displaces nothing — the paths
+	// are links magus owns. The FIRST switch in an unmanaged project displaces
+	// real files, and that is the run that must say so.
+	await activateProfile(name, projectPath, reportDisplaced(projectPath));
 	console.log(`✓ Switched to profile: ${name}`);
 
 	// Verify the profile's binary deps are actually usable — the switch itself