magus-cli 7.1.0 → 7.2.0

package/src/services/symlink-manager.ts

@@ -21,6 +21,7 @@
  * would ship to every teammate.
  */
 
+import type { Stats } from "node:fs";
 import path from "node:path";
 import fs from "fs-extra";
 
@@ -32,6 +33,7 @@ import fs from "fs-extra";
  */
 export const PROFILE_GITIGNORE_ENTRIES = [
 	".claude/_profiles/",
+	".claude/.magus-backups/",
 	".claude/settings.json",
 	".claude/skills",
 	".claude/models.json",
@@ -52,6 +54,30 @@ export function profileDir(name: string, projectPath?: string): string {
 /** The artifacts an active profile links into place. */
 export type ProfileLinkKey = "settings" | "skills" | "mcp" | "models";
 
+/**
+ * Where each linked artifact lives, and what it is called inside a profile.
+ *
+ * One table, because the link paths do NOT depend on which profile is active
+ * and two places listing them is two places to forget one. `linkTargets` adds
+ * the profile dir; `linkPaths` needs no profile at all.
+ */
+const LINKED_ARTIFACTS: Array<{
+	key: ProfileLinkKey;
+	/** Path segments under the project root. */
+	at: string[];
+	/** File or directory name inside `_profiles/<name>/`. */
+	inProfile: string;
+}> = [
+	{
+		key: "settings",
+		at: [".claude", "settings.json"],
+		inProfile: "settings.json",
+	},
+	{ key: "skills", at: [".claude", "skills"], inProfile: "skills" },
+	{ key: "mcp", at: [".mcp.json"], inProfile: "mcp.json" },
+	{ key: "models", at: [".claude", "models.json"], inProfile: "models.json" },
+];
+
 /** The set of links an active profile owns, as [linkPath, targetPath] pairs. */
 export function linkTargets(
 	name: string,
@@ -59,28 +85,121 @@ export function linkTargets(
 ): Array<{ key: ProfileLinkKey; link: string; target: string }> {
 	const base = projectPath ?? process.cwd();
 	const dir = profileDir(name, projectPath);
-	return [
-		{
-			key: "settings",
-			link: path.join(base, ".claude", "settings.json"),
-			target: path.join(dir, "settings.json"),
-		},
-		{
-			key: "skills",
-			link: path.join(base, ".claude", "skills"),
-			target: path.join(dir, "skills"),
-		},
-		{
-			key: "mcp",
-			link: path.join(base, ".mcp.json"),
-			target: path.join(dir, "mcp.json"),
-		},
-		{
-			key: "models",
-			link: path.join(base, ".claude", "models.json"),
-			target: path.join(dir, "models.json"),
-		},
-	];
+	return LINKED_ARTIFACTS.map(({ key, at, inProfile }) => ({
+		key,
+		link: path.join(base, ...at),
+		target: path.join(dir, inProfile),
+	}));
+}
+
+/** The paths activation writes links at, whichever profile is chosen. */
+export function linkPaths(projectPath?: string): string[] {
+	const base = projectPath ?? process.cwd();
+	return LINKED_ARTIFACTS.map(({ at }) => path.join(base, ...at));
+}
+
+/**
+ * Real artifacts that activating ANY profile would have to move aside.
+ *
+ * Empty means activating is lossless — a fresh clone, where the only things at
+ * these paths are nothing at all or links magus wrote itself. That is what
+ * makes it safe to honour the manifest's declared default without asking: there
+ * is no work of the user's to replace, so there is no decision to put to them.
+ *
+ * Non-empty means a human put something there, and the choice is theirs.
+ */
+export async function displaceableArtifacts(
+	projectPath?: string,
+): Promise<string[]> {
+	const found: string[] = [];
+	for (const link of linkPaths(projectPath)) {
+		// A link we own is generated state the manifest reproduces on demand.
+		if (await isProfileLink(link, projectPath)) continue;
+		try {
+			await fs.lstat(link);
+			found.push(link);
+		} catch {
+			// Nothing there.
+		}
+	}
+	return found;
+}
+
+/**
+ * Where activation moves a real file it had to displace.
+ *
+ * Beside `_profiles/`, never inside it. `_profiles/` is generated and is
+ * documented as regenerable from the manifest, so it is the first thing a
+ * cleanup — a user's, or ours — deletes. A backup stored there is the only copy
+ * of a hand-written file sitting in the one directory everybody is told is safe
+ * to remove. Gitignored all the same: these are recovery copies, not something
+ * to commit.
+ */
+export function backupRoot(projectPath?: string): string {
+	const base = projectPath ?? process.cwd();
+	return path.join(base, ".claude", ".magus-backups");
+}
+
+/** One artifact activation moved aside to make room for its symlink. */
+export interface DisplacedArtifact {
+	/** The path that is now a profile symlink. */
+	link: string;
+	/** Where its previous contents were moved. */
+	savedTo: string;
+}
+
+/** A directory name that sorts chronologically and is legal on every platform. */
+function backupStamp(): string {
+	return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Move whatever sits at `link` into `backupDir`, unless it is generated state.
+ *
+ * Activation replaces four paths with symlinks, and replacing means removing
+ * what is there. Three of those paths are ordinary files a project writes by
+ * hand and commits. `fs.remove` on `.claude/settings.json` is unrecoverable, and
+ * it ran on every activation — which is why adoption deliberately stopped short
+ * of activating and left migrations half-done.
+ *
+ * A symlink magus itself wrote is skipped: it points into `_profiles/`, which
+ * the manifest regenerates on demand, so copying it would archive nothing and
+ * every `profile switch` would leave another directory behind. A symlink
+ * pointing ANYWHERE ELSE is somebody's deliberate wiring and is preserved like
+ * a real file — the link is moved, never its target.
+ */
+async function displace(
+	link: string,
+	backupDir: string,
+	projectPath?: string,
+): Promise<DisplacedArtifact | null> {
+	if (await isProfileLink(link, projectPath)) return null;
+	let stat: Stats;
+	try {
+		stat = await fs.lstat(link);
+	} catch {
+		return null; // Nothing there — the common case on a first activation.
+	}
+	// The four link paths have four distinct basenames, so one flat directory
+	// holds a whole activation without collisions.
+	const savedTo = path.join(backupDir, path.basename(link));
+	await fs.ensureDir(backupDir);
+
+	if (stat.isSymbolicLink()) {
+		// A symlink's target is resolved against the directory the LINK sits in,
+		// so moving the link two levels deeper silently repoints it: a relative
+		// `../shared/mcp.json` that worked becomes dangling, and the "preserved"
+		// copy preserves nothing. Rewrite it as absolute at its original meaning.
+		const target = await fs.readlink(link);
+		const absolute = path.resolve(path.dirname(link), target);
+		await fs.remove(savedTo);
+		await fs.symlink(absolute, savedTo);
+		await fs.remove(link);
+		return { link, savedTo };
+	}
+
+	await fs.move(link, savedTo, { overwrite: true });
+	return { link, savedTo };
 }
 
 /**
@@ -100,20 +219,44 @@ async function relink(link: string, target: string): Promise<void> {
  * Activate a profile: repoint every shared-config symlink into its
  * materialized directory. Only links whose target exists in the profile dir
  * are created (e.g. a profile with no skills/ dir gets no skills symlink).
+ *
+ * Returns whatever had to be moved aside to make room — empty for an ordinary
+ * `profile switch`, one entry per hand-written artifact the first time a
+ * project adopts profiles. Callers report it so the move is never silent.
  */
 export async function activateProfile(
 	name: string,
 	projectPath?: string,
-): Promise<void> {
+	/**
+	 * Called the instant an artifact is moved, before the next link is touched.
+	 *
+	 * The return value alone is not enough, and the difference is data the user
+	 * cannot otherwise find: activation moves up to four artifacts in sequence,
+	 * so a throw on the second discards the array describing the first — leaving
+	 * `.claude/settings.json` gone from where they put it and no message saying
+	 * where it went. Reporting as it happens is what makes a half-finished
+	 * activation recoverable by hand.
+	 */
+	onDisplace?: (artifact: DisplacedArtifact) => void,
+): Promise<DisplacedArtifact[]> {
 	const dir = profileDir(name, projectPath);
 	if (!(await fs.pathExists(dir))) {
 		throw new Error(
 			`Profile "${name}" is not materialized (${dir} missing). Run \`magus install ${name}\`.`,
 		);
 	}
+	// One stamped directory per activation, so the four artifacts that were live
+	// together stay together and can be restored as the set they were.
+	const backupDir = path.join(backupRoot(projectPath), backupStamp());
+	const displaced: DisplacedArtifact[] = [];
 	for (const { link, target } of linkTargets(name, projectPath)) {
-		await syncLink(link, target, projectPath);
+		const moved = await syncLink(link, target, projectPath, backupDir);
+		if (moved) {
+			displaced.push(moved);
+			onDisplace?.(moved);
+		}
 	}
+	return displaced;
 }
 
 /**
@@ -124,13 +267,20 @@ export async function activateProfile(
 async function syncLink(
 	link: string,
 	target: string,
-	projectPath?: string,
-): Promise<void> {
+	projectPath: string | undefined,
+	// Required, not optional. An optional backup directory keeps a
+	// replace-without-backup path expressible, and that path is the whole defect
+	// this function was changed to close — a future caller omitting the argument
+	// would reintroduce it silently, and type-check clean while doing so.
+	backupDir: string,
+): Promise<DisplacedArtifact | null> {
 	if (await fs.pathExists(target)) {
+		const moved = await displace(link, backupDir, projectPath);
 		await relink(link, target);
-		return;
+		return moved;
 	}
 	if (await isProfileLink(link, projectPath)) await fs.remove(link);
+	return null;
 }
 
 /**
@@ -145,10 +295,14 @@ export async function syncProfileLink(
 	name: string,
 	key: ProfileLinkKey,
 	projectPath?: string,
-): Promise<void> {
+): Promise<DisplacedArtifact | null> {
 	const entry = linkTargets(name, projectPath).find((t) => t.key === key);
-	if (!entry) return;
-	await syncLink(entry.link, entry.target, projectPath);
+	if (!entry) return null;
+	// Backed up for the same reason activation is: `magus models use` on a
+	// project with a hand-written `.claude/models.json` would otherwise delete it
+	// as a side effect of choosing a model.
+	const backupDir = path.join(backupRoot(projectPath), backupStamp());
+	return syncLink(entry.link, entry.target, projectPath, backupDir);
 }
 
 /** Is `link` a symlink pointing into `.claude/_profiles/`? */

package/src/types/index.ts

@@ -295,26 +295,33 @@ export interface ClaudeMdConventions {
 
 // ─── Plugin Profile Types ──────────────────────────────────────────────────────
 
-export interface Profile {
-	name: string;
-	plugins: Record<string, boolean>;
-	createdAt: string;
-	updatedAt: string;
-}
-
-export interface ProfilesFile {
-	version: number;
-	profiles: Record<string, Profile>;
-}
-
-/** A profile with its id and scope, as used in UI lists */
-export interface ProfileEntry {
+/**
+ * A profile with its id and scope, as used in UI lists.
+ *
+ * This IS a v2 manifest entry. There is no separate TUI profile shape: both
+ * surfaces read one `.claude/profiles.json`, so a second type describing the
+ * same file is a second answer to one question. The earlier `Profile` /
+ * `ProfilesFile` pair required `createdAt`/`updatedAt` and typed `plugins` as
+ * booleans, which is a v1 file — handed a v2 file written by `magus update`,
+ * the list sort dereferenced a missing `updatedAt` and threw, so the Profiles
+ * tab reported an error for anyone who had ever run the CLI.
+ */
+export interface ProfileEntry extends ProfileManifestEntry {
 	id: string;
-	name: string;
-	plugins: Record<string, boolean>;
-	createdAt: string;
-	updatedAt: string;
 	scope: "user" | "project";
+	/**
+	 * This profile is the one the project is actually running.
+	 *
+	 * Derived from the `.claude/settings.json` symlink, not stored — see
+	 * `activeProfile`. Carried on the entry because a list of profiles with no
+	 * mark on the live one cannot answer the first question anybody asks of it:
+	 * the Profiles tab showed two identical-looking rows straight after
+	 * activating one of them.
+	 *
+	 * Only ever true for a `project` profile; a user-scope profile is a template,
+	 * and nothing links to it.
+	 */
+	active?: boolean;
 }
 
 // NOTE: The built-in profile type lives with its data in
@@ -324,11 +331,11 @@ export interface ProfileEntry {
 
 // ─── Team Profile Manifest (v2, committed .claude/profiles.json) ────────────────
 //
-// The v1 `Profile`/`ProfilesFile` above are the TUI's saved presets (plugins
-// only). The v2 manifest below is the committed, team-shared source of truth:
-// a superset that also carries marketplaces, MCP servers, CLI tools, skills,
-// settings, and env requirements. A v1 profile is a structural subset of a v2
-// entry, so v1 files migrate forward by a version bump alone.
+// The ONE shape of `.claude/profiles.json`, read by the TUI and the CLI alike.
+// It carries marketplaces, MCP servers, CLI tools, skills, settings and env
+// requirements as well as plugins. A v1 file — the TUI's old plugins-only
+// preset — is a structural subset, so it is read as a v2 entry whose optional
+// fields are simply absent, and rewritten as v2 on the next save.
 
 /** A marketplace a profile depends on (registered before its plugins install). */
 export interface ProfileMarketplaceRef {
@@ -385,6 +392,20 @@ export interface ProfileManifest {
 	version: 2;
 	/** When true, `install --check` fails on any plugin version drift. */
 	strictVersions?: boolean;
+	/**
+	 * Which profile this project wants, by id. Committed with the manifest.
+	 *
+	 * Without it a manifest says which profiles exist and never which one to
+	 * use, so every teammate cloning the repo is asked to choose and has nothing
+	 * to choose by — the repo knows the answer and had no way to write it down.
+	 *
+	 * It is intent, not state: the profile that is ACTUALLY active is the symlink
+	 * (see `activeProfile`), which is per-developer and gitignored. This field is
+	 * what a fresh clone activates so nobody is asked at all.
+	 *
+	 * Must name a profile that exists; `validateManifest` rejects it otherwise.
+	 */
+	default?: string;
 	profiles: Record<string, ProfileManifestEntry>;
 }
 

package/src/ui/App.tsx

@@ -13,6 +13,11 @@ import {
 } from "../services/gitignore-service.js";
 import { repairAllMarketplaces } from "../services/local-marketplace.js";
 import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
+import {
+	type ProfileStartupNeed,
+	detectProfileStartupNeed,
+	needsNothing,
+} from "../services/profile-startup.js";
 import {
 	type VersionCheckResult,
 	checkForUpdates,
@@ -22,6 +27,7 @@ import { ProgressBar } from "./components/layout/ProgressBar.js";
 import { ModalContainer } from "./components/modals/index.js";
 import { useGitignoreModal } from "./hooks/useGitignoreModal.js";
 import { useKeyboardHandler } from "./hooks/useKeyboardHandler.js";
+import { useProfileStartupModal } from "./hooks/useProfileStartupModal.js";
 import {
 	AliasScreen,
 	CliToolsScreen,
@@ -128,6 +134,23 @@ function GlobalKeyHandler({
 			return;
 		}
 
+		// Ctrl+C quits from ANYWHERE, including from under an open modal, and is
+		// checked before the guard below rather than beside `q` further down.
+		//
+		// Every modal used to be dismissable, so Escape-then-Ctrl+C always worked
+		// and this ordering never mattered. The profile gate cannot be dismissed —
+		// by design, since there is nothing to carry on to — which left Ctrl+C
+		// swallowed by the guard and no interrupt at all. A terminal app that
+		// ignores Ctrl+C is indistinguishable from one that has hung.
+		//
+		// `q` deliberately does NOT get the same treatment: a modal may want it
+		// (the select list's own cancel), and it is a printable character an input
+		// modal has to receive.
+		if (key.ctrl && input === "c") {
+			onExit();
+			return;
+		}
+
 		// Don't handle keys when modal is open or searching
 		if (state.modal || state.isSearching) return;
 
@@ -364,7 +387,13 @@ function AppContent({ onExit }: AppContentProps) {
 		violationCount: number;
 		safeCount: number;
 	} | null>(null);
+	const [profileNeed, setProfileNeed] = useState<ProfileStartupNeed | null>(
+		null,
+	);
 	const gitignoreModal = useGitignoreModal();
+	// The profile modal cannot be dismissed, so it needs the app's own exit: its
+	// only non-action is to leave.
+	const profileModal = useProfileStartupModal(onExit);
 
 	// Check for updates on startup, then re-check periodically (force-bypassing
 	// the session cache) so the banner reflects a release that lands while
@@ -407,6 +436,37 @@ function AppContent({ onExit }: AppContentProps) {
 		setGitignoreData(null);
 	}, [gitignoreData, gitignoreModal, state.modal, state.projectPath]);
 
+	// Show the profile modal on the same terms as the gitignore one: only once
+	// the modal slot is free, so two startup checks that both found something do
+	// not stomp on each other. Gitignore is asked first simply because its
+	// effect is declared first; whichever the user dismisses, the other follows.
+	useEffect(() => {
+		if (!profileNeed) return;
+		if (state.modal) return;
+		profileModal.show(profileNeed);
+		setProfileNeed(null);
+	}, [profileNeed, profileModal, state.modal]);
+
+	// Is this project actually running a profile? Detection only — nothing is
+	// written until the user picks something in the modal. The Profiles tab could
+	// list two profiles while the project ran neither, and nothing anywhere said
+	// so.
+	//
+	// Its own effect, NOT part of the marketplace block below: that one returns
+	// early on `--no-refresh`, which is about network calls to marketplaces and
+	// has no bearing on whether this project is on a profile. Sharing the effect
+	// would let that flag silently disable this question.
+	useEffect(() => {
+		(async () => {
+			try {
+				const need = await detectProfileStartupNeed(process.cwd());
+				if (!needsNothing(need)) setProfileNeed(need);
+			} catch {
+				// non-fatal: the Profiles tab still works by hand
+			}
+		})();
+	}, []);
+
 	// Auto-refresh marketplaces on startup
 	useEffect(() => {
 		const noRefresh = process.argv.includes("--no-refresh");

package/src/ui/components/layout/FooterHints.tsx

@@ -1,4 +1,5 @@
 import type React from "react";
+import { hintChip } from "../../theme-mode.js";
 import { theme } from "../../theme.js";
 
 /** One footer hint: a key (or key group) and the action it performs. */
@@ -28,11 +29,12 @@ export function joinKeys(keys: string[]): string {
 // The shared chip palette, not a local one. This file used to define its own
 // (`theme.colors.dim` block + terminal-foreground ink), which is why the footer
 // stayed a low-contrast grey-on-grey strip after the palette was made vivid —
-// the new colours simply never reached it. Anything chip-shaped uses theme.hints.
-const KEY_BG = theme.hints.defaultBg;
-const KEY_FG = theme.hints.fg;
-const LABEL_FG = theme.colors.muted;
-const GAP = "   ";
+// the new colours simply never reached it. Anything chip-shaped uses the theme.
+//
+// `hintChip()` rather than `theme.hints`: the chip is two fills that must sit a
+// measured step apart, and "a step quieter" is only definable against a page.
+// The static palette cannot express it; `theme-mode` resolves it.
+const GAP = "  ";
 
 /**
  * Render a row of footer hints as key badges + labels:
@@ -45,25 +47,35 @@ const GAP = "   ";
 export function FooterHints({
 	hints,
 }: { hints: FooterHint[] }): React.ReactNode {
+	const ink = hintChip();
 	const nodes: React.ReactNode[] = [];
 	hints.forEach((hint, i) => {
 		// A hint is identified by its key chord plus label, not its position.
 		const id = `${joinKeys(hint.keys)}:${hint.label}`;
 		if (i > 0) {
 			nodes.push(
-				<span key={`gap-${id}`} fg={LABEL_FG}>
+				<span key={`gap-${id}`} fg={theme.colors.muted}>
 					{GAP}
 				</span>,
 			);
 		}
+		// The two halves butt together with no separator: the key's fill ends
+		// exactly where the label's begins, so the pair reads as one chip with a
+		// bright end rather than as a badge followed by a word.
+		//
+		// Both halves are padded on BOTH sides. The label used to carry a trailing
+		// space only, which left its first letter hard against the boundary between
+		// the two fills — the key's own trailing space sits on the bright fill, so
+		// there was no quiet gap on the label's side at all and `↑↓ select` read as
+		// one cramped word.
 		nodes.push(
-			<span key={`k-${id}`} bg={KEY_BG} fg={KEY_FG}>
+			<span key={`k-${id}`} bg={ink.keyBg} fg={ink.keyFg}>
 				{` ${joinKeys(hint.keys)} `}
 			</span>,
 		);
 		nodes.push(
-			<span key={`l-${id}`} fg={LABEL_FG}>
-				{` ${hint.label}`}
+			<span key={`l-${id}`} bg={ink.labelBg} fg={ink.labelFg}>
+				{` ${hint.label} `}
 			</span>,
 		);
 	});

package/src/ui/components/modals/ModalContainer.tsx

@@ -121,6 +121,7 @@ export function ModalContainer() {
 						defaultIndex={selectIndex}
 						onSelect={modal.onSelect}
 						onCancel={modal.onCancel}
+						cancellable={modal.cancellable}
 					/>
 				);