magus-cli 7.4.0 → 7.5.0

package/src/__tests__/settings-file.test.ts

@@ -5,11 +5,9 @@
  * their configuration:
  *
  *  - an unparseable file must be REFUSED, and left byte-for-byte alone;
- *  - a symlinked settings.json must be written THROUGH the link, because that
- *    is the shape an active profile leaves behind (`.claude/settings.json` →
- *    `.claude/_profiles/<name>/settings.json`). Remove-then-create would
- *    replace the link with a plain file and detach the project from its
- *    profile, which nothing downstream would notice.
+ *  - a symlinked settings.json must be written THROUGH the link: a symlink a
+ *    person set up deliberately is theirs. Remove-then-create would replace
+ *    the link with a plain file, which nothing downstream would notice.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -154,7 +152,7 @@ describe("updateSettingsFile", () => {
 		expect(readFileSync(file, "utf8")).toBe(original);
 	});
 
-	test("S-6: a symlinked settings.json is written THROUGH the link — the profile case", async () => {
+	test("S-6: a symlinked settings.json is written THROUGH the link", async () => {
 		const dir = tempDir();
 		const target = path.join(dir, "profile-settings.json");
 		const link = path.join(dir, "settings.json");
@@ -168,7 +166,7 @@ describe("updateSettingsFile", () => {
 			settings.outputStyle = "composed";
 		});
 
-		// The profile's real file received the write …
+		// The link target received the write …
 		expect(JSON.parse(readFileSync(target, "utf8"))).toEqual({
 			enabledPlugins: { "dev@magus": true },
 			outputStyle: "composed",

package/src/__tests__/stale-load-repair.test.ts

@@ -344,10 +344,11 @@ describe("repairStaleLoad — refusals", () => {
 	});
 
 	test("an unreadable registry is refused rather than replaced", async () => {
-		// `readInstalledPluginsRegistry` answers an EMPTY registry for a corrupt
-		// file, and writing that back would erase every project's installs on the
-		// machine. The repair reads and parses the same bytes it will check before
-		// writing, so a document it cannot parse stops it here.
+		// Writing over a corrupt registry would erase every project's installs on
+		// the machine. The repair reads and parses the same bytes it will check
+		// before writing, so a document it cannot parse stops it here — and it
+		// reports that as a result rather than throwing, because one item in a
+		// plan of repairs must not end the plan.
 		await fs.outputFile(registryFile, "{ not json");
 
 		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);

package/src/__tests__/styles-manager.test.ts

@@ -4,6 +4,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import fs from "fs-extra";
 import { EMBEDDED_PRESETS } from "../data/styles/index.js";
+import { writeManifest } from "../services/manifest.js";
+import { activateProfile } from "../services/profile-activate.js";
+import {
+	liveHash,
+	readActiveMarker,
+	writeActiveMarker,
+} from "../services/profile-live.js";
 import {
 	INTEGRITY_BLOCK,
 	type ImportedStyle,
@@ -19,6 +26,7 @@ import {
 	splitFrontmatter,
 	validateSelection,
 } from "../services/styles-manager.js";
+import type { ProfileManifest } from "../types/index.js";
 import {
 	buildStyleBrowserItems,
 	firstSelectableIndex,
@@ -405,20 +413,26 @@ describe("applyStyles", () => {
 		).rejects.toThrow(/Nothing selected/);
 	});
 
-	test("writes THROUGH an active profile's settings symlink without breaking it", async () => {
-		// The regression this guards: removing-then-recreating settings.json
-		// silently detaches the project from its profile, and every later profile
-		// switch then writes to a file nothing reads.
-		const profileSettings = join(
+	const DEV: ProfileManifest = {
+		version: 2,
+		profiles: { dev: { name: "dev", plugins: {} } },
+	};
+
+	test("an older settings symlink is converted to a real file, not written through", async () => {
+		// Claude Code refuses to write through a symlink, so the style must not
+		// be applied by writing through one either: the file is rendered from
+		// the manifest in place of the link.
+		const oldSettings = join(
 			dir,
 			".claude",
 			"_profiles",
 			"dev",
 			"settings.json",
 		);
-		await fs.outputJson(profileSettings, { enabledPlugins: {} });
+		await fs.outputJson(oldSettings, { enabledPlugins: {} });
 		const link = join(dir, ".claude", "settings.json");
 		await symlink("_profiles/dev/settings.json", link);
+		await writeManifest(DEV, dir);
 
 		const result = await applyStyles({
 			projectPath: dir,
@@ -428,33 +442,13 @@ describe("applyStyles", () => {
 
 		expect(result.profile).toBe("dev");
 		expect(result.styleName).toBe("composed-dev");
-		expect((await fs.lstat(link)).isSymbolicLink()).toBe(true);
-		// The write landed in the profile, which is what "apply to the current
-		// profile" means.
-		expect((await fs.readJson(profileSettings)).outputStyle).toBe(
-			"composed-dev",
-		);
+		expect((await fs.lstat(link)).isSymbolicLink()).toBe(false);
+		expect((await fs.readJson(link)).outputStyle).toBe("composed-dev");
 	});
 
-	test("records the style in profiles.json so re-materializing cannot drop it", async () => {
-		// materializeProfile rewrites settings.json from the manifest, so a live
-		// write alone regresses on the next `magus install`.
-		const profileSettings = join(
-			dir,
-			".claude",
-			"_profiles",
-			"dev",
-			"settings.json",
-		);
-		await fs.outputJson(profileSettings, { enabledPlugins: {} });
-		await symlink(
-			"_profiles/dev/settings.json",
-			join(dir, ".claude", "settings.json"),
-		);
-		await fs.outputJson(join(dir, ".claude", "profiles.json"), {
-			version: 2,
-			profiles: { dev: { name: "dev", plugins: {} } },
-		});
+	test("with an activated profile, the live file stays real and is recorded", async () => {
+		await writeManifest(DEV, dir);
+		await activateProfile(DEV, "dev", dir, { onDisplace: () => {} });
 
 		const result = await applyStyles({
 			projectPath: dir,
@@ -462,67 +456,46 @@ describe("applyStyles", () => {
 			imports: [],
 		});
 
+		const live = join(dir, ".claude", "settings.json");
 		expect(result.recordedInManifest).toBe(true);
-		const manifest = await fs.readJson(join(dir, ".claude", "profiles.json"));
-		expect(manifest.profiles.dev.settings.outputStyle).toBe("composed-dev");
+		expect((await fs.lstat(live)).isFile()).toBe(true);
+		expect((await fs.readJson(live)).outputStyle).toBe("composed-dev");
+		// Rendered from the manifest and recorded, so it reads as unchanged.
+		expect((await readActiveMarker(dir))?.files.settings).toBe(
+			(await liveHash("settings", dir)) ?? "",
+		);
 	});
 
-	test("reports honestly when there is a profile but no manifest entry", async () => {
-		const profileSettings = join(
-			dir,
-			".claude",
-			"_profiles",
-			"dev",
-			"settings.json",
-		);
-		await fs.outputJson(profileSettings, {});
-		await symlink(
-			"_profiles/dev/settings.json",
-			join(dir, ".claude", "settings.json"),
-		);
+	test("records the style in profiles.json, where rendering reads it", async () => {
+		await writeManifest(DEV, dir);
+		await activateProfile(DEV, "dev", dir, { onDisplace: () => {} });
 
 		const result = await applyStyles({
 			projectPath: dir,
 			presets: [preset({ name: "direct" })],
 			imports: [],
 		});
-		expect(result.profile).toBe("dev");
-		expect(result.recordedInManifest).toBe(false);
-	});
-});
 
-describe("clearStyle", () => {
-	test("removes the key rather than setting it undefined", async () => {
-		await applyStyles({
-			projectPath: dir,
-			presets: [preset({ name: "direct" })],
-			imports: [],
-		});
-		await clearStyle(dir);
+		expect(result.recordedInManifest).toBe(true);
+		const manifest = await fs.readJson(join(dir, ".claude", "profiles.json"));
+		expect(manifest.profiles.dev.settings.outputStyle).toBe("composed-dev");
+	});
 
-		const raw = await fs.readFile(
-			join(dir, ".claude", "settings.json"),
-			"utf8",
+	test("a marker naming a profile profiles.json lacks is no active profile", async () => {
+		await writeManifest(DEV, dir);
+		await writeActiveMarker(
+			{ version: 1, profile: "gone", files: {}, skills: {} },
+			dir,
 		);
-		expect(raw).not.toContain("outputStyle");
-		expect(JSON.parse(raw)).toEqual({});
-	});
+		await fs.outputJson(join(dir, ".claude", "settings.json"), {});
 
-	test("leaves the generated file on disk so a re-apply is one keypress away", async () => {
 		const result = await applyStyles({
 			projectPath: dir,
 			presets: [preset({ name: "direct" })],
 			imports: [],
 		});
-		await clearStyle(dir);
-		expect(await fs.pathExists(result.stylePath)).toBe(true);
-	});
-
-	test("is a no-op on a project that never had a style", async () => {
-		await clearStyle(dir);
-		expect(await fs.pathExists(join(dir, ".claude", "settings.json"))).toBe(
-			false,
-		);
+		expect(result.profile).toBeNull();
+		expect(result.recordedInManifest).toBe(false);
 	});
 });
 

package/src/__tests__/styles-screen-state.test.ts

@@ -1,15 +1,18 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { parseKeypress } from "@opentui/core";
 import fs from "fs-extra";
+import { writeManifest } from "../services/manifest.js";
+import { activateProfile } from "../services/profile-activate.js";
 import {
 	applyStyles,
 	clearStyle,
 	communityCacheDirOrNull,
 	loadStyles,
 } from "../services/styles-manager.js";
+import type { ProfileManifest } from "../types/index.js";
 import type { KeyPress } from "../ui/input/key-dispatch.js";
 import { SCREEN_BINDINGS, matchBinding } from "../ui/keymap.js";
 import { appReducer, initialState } from "../ui/state/reducer.js";
@@ -291,16 +294,14 @@ describe("loadStyles reports what is actually in force", () => {
 	});
 
 	test("looks for the per-profile style when a profile is active", async () => {
-		await fs.outputJson(
-			join(dir, ".claude", "_profiles", "dev", "settings.json"),
-			{
-				outputStyle: "composed-dev",
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: {
+				dev: { name: "dev", settings: { outputStyle: "composed-dev" } },
 			},
-		);
-		await symlink(
-			"_profiles/dev/settings.json",
-			join(dir, ".claude", "settings.json"),
-		);
+		};
+		await writeManifest(manifest, dir);
+		await activateProfile(manifest, "dev", dir, { onDisplace: () => {} });
 		await fs.outputFile(
 			join(dir, ".claude", "output-styles", "composed-dev.md"),
 			"---\nname: composed-dev\nstyle-presets: terse\nstyle-imports: none\n---\n\nbody",

package/src/cli/bootstrap.ts

@@ -15,8 +15,9 @@ import {
 	writeManifest,
 } from "../services/manifest.js";
 import {
-	applyProfileChoice,
-	materializeAndActivate,
+	type ActivationResult,
+	activateProfile,
+	activationNotes,
 	reportDisplaced,
 } from "../services/profile-activate.js";
 import {
@@ -31,6 +32,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 +65,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
@@ -79,20 +87,73 @@ async function writeAndActivate(
 	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 +202,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 +291,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 +322,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 +353,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 +378,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