magus-cli 7.0.0 → 7.2.0

package/src/services/profile-startup.ts

@@ -0,0 +1,311 @@
+/**
+ * Is this project usable, and if not, what has to happen first.
+ *
+ * ## One source of truth, not two
+ *
+ * A profiled project's `.claude/settings.json` is a SYMLINK into
+ * `_profiles/<id>/`, and that file is generated from the manifest. So the
+ * manifest is the truth and `enabledPlugins` is its output.
+ *
+ * An earlier version of this file compared the two — the manifest against the
+ * plugins `enabledPlugins` lists — and offered to create a new profile when
+ * they disagreed. That is coherent only in the profileless world, where
+ * `settings.json` is a real file somebody wrote. Once a profile is active it
+ * compares the manifest against its own generated output, and "they disagree"
+ * cannot mean what the offer claimed: the honest answer is to re-materialize
+ * the profile, never to invent a third one describing the corrupted output.
+ *
+ * Worse, it meant magus behaved as though both worlds were live at once. So the
+ * comparison is gone. Nothing here reads `enabledPlugins`, and nothing compares
+ * a set of declared plugins to a set of installed ones — they are different
+ * kinds of thing and a comparison between them cannot be acted on.
+ *
+ * ## What is left is a three-state question
+ *
+ *   ok          a profile is active; the manifest is in effect; ask nothing
+ *   unmigrated  no manifest — the project is not using profiles at all
+ *   inactive    a manifest with profiles, none of them linked into place
+ *
+ * `unmigrated` and `inactive` are both unusable, not merely untidy: with no
+ * active profile there is no profile state to read and nothing to write updates
+ * into, so magus cannot do its job. The caller must not offer to continue.
+ *
+ * Detection only — nothing here writes. That is what makes it callable from the
+ * TUI's startup effect, and testable without a renderer.
+ */
+
+import type { ProfileManifest } from "../types/index.js";
+// Type-only, so it is erased: this module stays free of the UI and of React,
+// which is what lets `magus hook` and the CLI import it. The shape of a
+// selectable option is presentation-neutral data, and both surfaces render the
+// same list from these builders rather than each composing its own.
+import type { SelectOption } from "../ui/state/types.js";
+import { readManifest } from "./manifest.js";
+import type { ProfileChoice } from "./profile-activate.js";
+import { freeProfileId } from "./profile-adopt.js";
+import { activeProfile, displaceableArtifacts } from "./symlink-manager.js";
+
+/** Whether the project can be worked on, and if not, why not. */
+export type ProfileStartupState = "ok" | "unmigrated" | "inactive";
+
+/** A profile the user could activate. */
+export interface ActivatableProfile {
+	id: string;
+	name: string;
+	/**
+	 * How many plugins it declares.
+	 *
+	 * A property of the profile, read from the manifest — NOT a comparison
+	 * against what is installed. It is here to tell two rows apart, nothing more.
+	 */
+	pluginCount: number;
+}
+
+export interface ProfileStartupNeed {
+	state: ProfileStartupState;
+	/**
+	 * Id to create if the user wants what is turned on captured as a profile.
+	 * Null when a profile is already active. Never an id already in use.
+	 */
+	adopt: string | null;
+	/** Profiles that could be activated. Empty unless the state is `inactive`. */
+	activate: ActivatableProfile[];
+	/**
+	 * The profile this project declares it wants, if the manifest names one that
+	 * exists. Used to preselect the row so Enter does the intended thing.
+	 */
+	declaredDefault: string | null;
+	/**
+	 * Activate `declaredDefault` without asking.
+	 *
+	 * True only when the repo answered the question AND activating would replace
+	 * nothing a human put there — a fresh clone. Asking there is asking someone
+	 * to re-decide something their team already decided, with nothing at stake.
+	 *
+	 * False the moment there is anything to lose, however clear the declared
+	 * default is: replacing someone's working files is never automatic.
+	 */
+	autoActivate: boolean;
+	/** The manifest as read, so the caller does not read it a second time. */
+	manifest: ProfileManifest;
+}
+
+/** True when the project is usable and there is nothing to ask. */
+export function needsNothing(need: ProfileStartupNeed): boolean {
+	return need.state === "ok";
+}
+
+/** Inspect the project and decide what, if anything, must happen first. */
+export async function detectProfileStartupNeed(
+	projectPath: string,
+): Promise<ProfileStartupNeed> {
+	const manifest = await readManifest(projectPath);
+	const ids = Object.keys(manifest.profiles);
+
+	if (ids.length === 0) {
+		return {
+			state: "unmigrated",
+			adopt: freeProfileId(manifest),
+			activate: [],
+			declaredDefault: null,
+			autoActivate: false,
+			manifest,
+		};
+	}
+
+	// The ONE question that decides whether the manifest is in effect. Not a
+	// comparison, not a heuristic: either settings.json is a link into a
+	// profile or it is not.
+	if ((await activeProfile(projectPath)) !== null) {
+		return {
+			state: "ok",
+			adopt: null,
+			activate: [],
+			declaredDefault: null,
+			autoActivate: false,
+			manifest,
+		};
+	}
+
+	// Validated, not trusted: a `default` naming a profile that was renamed or
+	// removed must fall back to asking rather than throw somewhere downstream.
+	// `validateManifest` reports the typo; this keeps magus usable meanwhile.
+	const declaredDefault =
+		manifest.default !== undefined && ids.includes(manifest.default)
+			? manifest.default
+			: null;
+
+	return {
+		state: "inactive",
+		declaredDefault,
+		// Only when the repo answered AND there is nothing of the user's to
+		// replace. Both halves matter: without the first there is no answer to
+		// apply, and without the second applying it silently destroys work.
+		autoActivate:
+			declaredDefault !== null &&
+			(await displaceableArtifacts(projectPath)).length === 0,
+		// Still offered, because a manifest whose profiles all describe something
+		// this project no longer is would otherwise be a dead end — activating a
+		// wrong profile is the only way out. Offering it costs a row; NOT offering
+		// it rebuilds the trap. Which one to take is the user's call to make, and
+		// magus can no longer form an opinion on it without the comparison that
+		// used to be here.
+		adopt: freeProfileId(manifest),
+		activate: ids.map((id) => ({
+			id,
+			name: manifest.profiles[id]?.name ?? id,
+			pluginCount: Object.keys(manifest.profiles[id]?.plugins ?? {}).length,
+		})),
+		manifest,
+	};
+}
+
+// ─── What to offer, as data both surfaces render ─────────────────────────────
+
+/** Option values are parsed back, so they are data, not prose. */
+export const ADOPT_VALUE = "adopt";
+export const QUIT_VALUE = "quit";
+export const ACTIVATE_PREFIX = "activate:";
+
+/**
+ * Title and message for the state we are in.
+ *
+ * Written about what the user has, never about magus's internals. Two rewrites
+ * got here, and both failures are worth keeping in mind.
+ *
+ * First it explained the machinery: "the manifest is not in effect", "there is
+ * no profile state to read and nowhere to write updates". Accurate, and an
+ * answer to a question nobody standing in front of this modal is asking.
+ *
+ * Then it traded jargon for abstraction: "the setup you are running belongs to
+ * no profile". "Setup" names nothing the reader can point at, and "belongs to"
+ * describes a relationship rather than a consequence. So the copy now names the
+ * concrete things — the plugins and skills turned on for this project — and
+ * says what happens to them: they will be overwritten.
+ *
+ * That consequence is the whole reason the save option exists. A screen offering
+ * "save" and "switch" without saying they are alternatives asks the reader to
+ * guess which one keeps their work.
+ *
+ * The `unmigrated` copy must NOT carry that warning: adopting there captures
+ * what is already present, so the reassurance is the point.
+ *
+ * Neither mentions the backup, deliberately. A sentence promising "nothing is
+ * deleted — the old files are moved to a backup" raises a question the reader
+ * did not have (which files? what was at risk?) and implies data loss, when what
+ * changes is settings. Where the displaced files went belongs in the outcome
+ * modal AFTER the switch, where it is something to act on rather than a worry to
+ * plant beforehand.
+ *
+ * No file paths in these strings, deliberately. The TUI modal soft-wraps its
+ * message at whatever width the terminal gives it, and OpenTUI treats `.` as a
+ * break opportunity — MEASURED on screen, `.claude/settings.json` wrapped as
+ * `.` then `claude/settings.json` on the next line. A path split across a line
+ * break reads as two different paths, neither of them real.
+ */
+export function describeNeed(need: ProfileStartupNeed): {
+	title: string;
+	message: string;
+} {
+	if (need.state === "unmigrated") {
+		return {
+			title: "magus uses profiles",
+			message:
+				"A profile is a saved set of plugins, skills and MCP servers for one project. Commit it, and everyone on the team gets the same ones.\n\nThis project has no profile yet. Saving what it uses now makes the first one, and nothing about what you run changes.",
+		};
+	}
+
+	return {
+		title: "No profile selected",
+		message:
+			"A profile is a saved set of plugins, skills and MCP servers for one project.\n\nThe plugins and skills turned on here are not saved in any profile. Switch to one below and they will be overwritten.\n\nTo keep them, save them as a new profile first.",
+	};
+}
+
+/**
+ * The options for a need, in the order they should be offered.
+ *
+ * There is no "Not now". Without an active profile magus has no profile state
+ * to read and nowhere to write updates, so "carry on anyway" is not something
+ * it can offer — both surfaces used to have that escape, the TUI as a list row
+ * and the CLI as "using X for this run only", and both let the user into a
+ * magus that could not do its job.
+ *
+ * "Quit magus" is last instead. A question that cannot be answered with "no"
+ * still has to be answerable with "not in this app", and the way out has to be
+ * visible rather than a keystroke the user has to guess.
+ */
+export function buildProfileOptions(need: ProfileStartupNeed): SelectOption[] {
+	const options: SelectOption[] = [];
+
+	if (need.adopt !== null) {
+		options.push({
+			// Says what it PRESERVES, not what it creates. "Create <id> from this
+			// project" described the mechanism; the reason to pick this row is that
+			// it is the only one that keeps what is turned on right now.
+			//
+			// Kept short on purpose: this is the longest label in the list, and the
+			// meta column is measured against the longest one. "…and use it" made it
+			// 41 cells and pushed every plugin count onto a line of its own.
+			label: `Save what you have as "${need.adopt}"`,
+			value: ADOPT_VALUE,
+		});
+	}
+
+	for (const profile of need.activate) {
+		options.push({
+			label: `Activate ${profile.name}`,
+			value: `${ACTIVATE_PREFIX}${profile.id}`,
+			// The profile's own plugin count, to tell two rows apart. There used to
+			// be a "matches now" badge here, marking the profile that declared
+			// exactly what `enabledPlugins` had on. It is gone with the comparison
+			// that produced it: it asserted that the installed set was a legitimate
+			// thing to judge a profile against, which is the two-worlds confusion
+			// this change removes.
+			meta: `${profile.pluginCount} plugin${profile.pluginCount === 1 ? "" : "s"}`,
+		});
+	}
+
+	options.push({ label: "Quit magus", value: QUIT_VALUE });
+	return options;
+}
+
+/**
+ * Which row to start on.
+ *
+ * The profile the repo declares, when it names one — so a developer who does
+ * have local work to weigh still gets their team's answer under the cursor, and
+ * Enter does the intended thing. Falls back to the first row, which is the save
+ * option: the safe default when nobody has said otherwise, because it is the
+ * only one that keeps what is turned on.
+ */
+export function defaultOptionIndex(need: ProfileStartupNeed): number {
+	if (need.declaredDefault === null) return 0;
+	const at = buildProfileOptions(need).findIndex(
+		(o) => o.value === `${ACTIVATE_PREFIX}${need.declaredDefault}`,
+	);
+	return at === -1 ? 0 : at;
+}
+
+/**
+ * Turn a chosen option value into the action it means.
+ *
+ * Returns null for "quit" and for anything unrecognised — including `adopt`
+ * when there is nothing to adopt, so a stale value cannot reach the adopt path
+ * with no id.
+ */
+export function parseProfileChoice(
+	value: string,
+	need: ProfileStartupNeed,
+): ProfileChoice | null {
+	if (value === ADOPT_VALUE && need.adopt !== null) {
+		return { kind: "adopt", id: need.adopt };
+	}
+	if (value.startsWith(ACTIVATE_PREFIX)) {
+		const id = value.slice(ACTIVATE_PREFIX.length);
+		return need.activate.some((p) => p.id === id)
+			? { kind: "activate", id }
+			: null;
+	}
+	return null;
+}

package/src/services/profiles.ts

@@ -1,7 +1,8 @@
 import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
-import type { Profile, ProfileEntry, ProfilesFile } from "../types/index.js";
+import type { ProfileEntry, ProfileManifest } from "../types/index.js";
+import { activeProfile } from "./symlink-manager.js";
 
 const PROFILES_FILE = "profiles.json";
 
@@ -21,7 +22,7 @@ export function getProjectProfilesPath(projectPath?: string): string {
 export async function readProfiles(
 	scope: "user" | "project",
 	projectPath?: string,
-): Promise<ProfilesFile> {
+): Promise<ProfileManifest> {
 	const filePath =
 		scope === "user"
 			? getUserProfilesPath()
@@ -29,17 +30,23 @@ export async function readProfiles(
 	try {
 		if (await fs.pathExists(filePath)) {
 			const data = await fs.readJson(filePath);
-			if (data.version && data.profiles) return data as ProfilesFile;
+			// A v1 file differs only in what it omits, so it reads as a v2 entry
+			// with absent optional fields. Nothing here converts: `version: 2` is
+			// what the next write records, and every consumer already treats
+			// `createdAt`, `updatedAt` and a string plugin pin as optional.
+			if (data.version && data.profiles) {
+				return { ...data, version: 2 } as ProfileManifest;
+			}
 		}
 	} catch {
 		// fall through to default
 	}
-	return { version: 1, profiles: {} };
+	return { version: 2, profiles: {} };
 }
 
 async function writeProfiles(
 	scope: "user" | "project",
-	data: ProfilesFile,
+	data: ProfileManifest,
 	projectPath?: string,
 ): Promise<void> {
 	const filePath =
@@ -56,21 +63,33 @@ async function writeProfiles(
 export async function listProfiles(
 	projectPath?: string,
 ): Promise<ProfileEntry[]> {
-	const [user, project] = await Promise.all([
+	// The active profile is read alongside the files rather than by the caller:
+	// every surface that lists profiles wants to mark the live one, and a flag
+	// each of them derives itself is a flag some of them forget.
+	const [user, project, active] = await Promise.all([
 		readProfiles("user"),
 		readProfiles("project", projectPath),
+		activeProfile(projectPath),
 	]);
 	const entries: ProfileEntry[] = [];
 	for (const [id, p] of Object.entries(user.profiles)) {
 		entries.push({ id, scope: "user", ...p });
 	}
 	for (const [id, p] of Object.entries(project.profiles)) {
-		entries.push({ id, scope: "project", ...p });
+		entries.push({ id, scope: "project", ...p, active: id === active });
 	}
-	// Sort: user profiles first, then project, each by updatedAt desc
+	// Sort: user profiles first, then project, each by updatedAt desc.
+	//
+	// `updatedAt` is optional — a hand-written or CLI-authored profile carries
+	// no timestamp, and dereferencing it here is what made this function throw
+	// on every v2 file. An undated profile sorts last within its scope, then by
+	// id so the order is stable rather than dependent on key order.
 	entries.sort((a, b) => {
 		if (a.scope !== b.scope) return a.scope === "user" ? -1 : 1;
-		return b.updatedAt.localeCompare(a.updatedAt);
+		const at = a.updatedAt ?? "";
+		const bt = b.updatedAt ?? "";
+		if (at !== bt) return bt.localeCompare(at);
+		return a.id.localeCompare(b.id);
 	});
 	return entries;
 }
@@ -98,6 +117,25 @@ export async function saveProfile(
 	return id;
 }
 
+/**
+ * A profile's plugin map as Claude Code's `enabledPlugins` needs it.
+ *
+ * A profile pins a plugin to a version ("1.2.0"), to "latest", or to `true`.
+ * Claude Code's `enabledPlugins` takes booleans and nothing else, so spreading
+ * a profile straight in writes `"latest"` where `true` belongs and the plugin
+ * silently stops loading. Only an explicit `false` means disabled; every pin
+ * names a plugin the profile wants on.
+ */
+export function toEnabledPlugins(
+	plugins: Record<string, string | boolean> | undefined,
+): Record<string, boolean> {
+	const out: Record<string, boolean> = {};
+	for (const [id, pin] of Object.entries(plugins ?? {})) {
+		out[id] = pin !== false;
+	}
+	return out;
+}
+
 /**
  * Apply a profile: replaces enabledPlugins in the target settings scope.
  * targetScope is where the settings will be written, independent of where
@@ -123,12 +161,12 @@ export async function applyProfile(
 
 	if (targetScope === "user") {
 		const settings = await readGlobalSettings();
-		settings.enabledPlugins = { ...profile.plugins };
+		settings.enabledPlugins = toEnabledPlugins(profile.plugins);
 		await writeGlobalSettings(settings);
 	} else {
 		// project or local both write to project settings.json
 		const settings = await readSettings(projectPath);
-		settings.enabledPlugins = { ...profile.plugins };
+		settings.enabledPlugins = toEnabledPlugins(profile.plugins);
 		await writeSettings(settings, projectPath);
 	}
 }

package/src/services/resolver.ts

@@ -19,7 +19,9 @@ import type {
 	ResolvedBin,
 	ResolvedClosure,
 } from "../types/index.js";
+import { readManifest } from "./manifest.js";
 import { resolvePluginBinRequirements } from "./plugin-requires.js";
+import { activeProfile } from "./symlink-manager.js";
 
 export interface ResolveOptions {
 	/**
@@ -190,6 +192,37 @@ export function withDerivedMarketplaces(
 	return out;
 }
 
+/**
+ * The active profile's plugin pins, or null when there is nothing to read.
+ *
+ * A convenience for callers that want the manifest's opinion but must never be
+ * blocked by it — the TUI above all. Every failure path answers null: no
+ * manifest file, no profiles in it, no active profile and more than one to
+ * choose from, an unresolvable profile. A project without a manifest is the
+ * normal case, not an error, and a broken one must not stop the plugin list
+ * from rendering.
+ *
+ * `magus update` deliberately does NOT use this: it needs to fail loudly
+ * when the profile is ambiguous, and to name the profile it resolved.
+ */
+export async function activeProfilePins(
+	projectPath?: string,
+): Promise<Record<string, string> | null> {
+	try {
+		const manifest = await readManifest(projectPath);
+		const ids = Object.keys(manifest.profiles);
+		if (ids.length === 0) return null;
+		const id =
+			(await activeProfile(projectPath)) ??
+			(ids.length === 1 ? ids[0] : undefined);
+		if (!id) return null;
+		const closure = await resolveProfile(manifest, id);
+		return closure.plugins;
+	} catch {
+		return null;
+	}
+}
+
 export async function resolveProfile(
 	manifest: ProfileManifest,
 	profileId: string,