magus-cli 7.1.0 → 7.2.0

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/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

package/src/cli/prompt.ts

@@ -8,25 +8,57 @@
 
 import { createInterface } from "node:readline/promises";
 
-/** Y/n prompt. Empty input means yes. */
-export async function confirm(question: string): Promise<boolean> {
-	const rl = createInterface({ input: process.stdin, output: process.stdout });
-	try {
-		const answer = (await rl.question(`${question} [Y/n] `))
-			.trim()
-			.toLowerCase();
-		return answer === "" || answer === "y" || answer === "yes";
-	} finally {
-		rl.close();
+/**
+ * Ctrl+C at a prompt.
+ *
+ * `readline/promises` rejects `question()` with an `AbortError` carrying
+ * `code: "ABORT_ERR"`. That is a Node internal, and letting it escape printed
+ * nine frames of `internal:repl/node-errors` under "Error starting magus:" —
+ * a stack trace for the one input every terminal user knows how to give.
+ *
+ * It is converted here rather than at each call site so no future prompt can
+ * forget, and it stays a throw rather than a sentinel return so a caller that
+ * ignores it aborts instead of proceeding with a missing answer.
+ */
+export class PromptAborted extends Error {
+	constructor() {
+		super("Aborted with Ctrl+C");
+		this.name = "PromptAborted";
 	}
 }
 
-/** Free-text prompt, trimmed. */
-export async function promptValue(question: string): Promise<string> {
+/** True for a Ctrl+C at a prompt, ours or readline's own. */
+export function isPromptAborted(error: unknown): boolean {
+	if (error instanceof PromptAborted) return true;
+	// Belt and braces: an abort raised somewhere that does not route through
+	// `ask` still reads as a cancellation rather than a crash.
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		(error as { code?: unknown }).code === "ABORT_ERR"
+	);
+}
+
+/** One readline question, with Ctrl+C normalised. */
+async function ask(question: string): Promise<string> {
 	const rl = createInterface({ input: process.stdin, output: process.stdout });
 	try {
 		return (await rl.question(question)).trim();
+	} catch (error) {
+		if (isPromptAborted(error)) throw new PromptAborted();
+		throw error;
 	} finally {
 		rl.close();
 	}
 }
+
+/** Y/n prompt. Empty input means yes. */
+export async function confirm(question: string): Promise<boolean> {
+	const answer = (await ask(`${question} [Y/n] `)).toLowerCase();
+	return answer === "" || answer === "y" || answer === "yes";
+}
+
+/** Free-text prompt, trimmed. */
+export async function promptValue(question: string): Promise<string> {
+	return ask(question);
+}

package/src/cli/tui-prompt.tsx

@@ -0,0 +1,143 @@
+/**
+ * One OpenTUI dialog, for a command that is otherwise not a TUI.
+ *
+ * `magus update` prints a report and exits; it is not the interactive app. But
+ * a question it must ask deserves the same dialog the TUI asks with, so this
+ * mounts the REAL `SelectModal` — the component tab 5 and tab 0 use — for the
+ * length of one question, then tears the renderer down and lets the command
+ * carry on printing. Nothing here re-draws a list, a border or a highlight: the
+ * component and the theme own all of that, and a second implementation is how
+ * the two surfaces drift apart.
+ *
+ * Every import of `@opentui/*` and `ui/` is DYNAMIC. `main.tsx` splits the TUI
+ * out precisely so `magus hook …`, which Claude Code runs on every matching
+ * tool call, never pays to load the renderer — a static import here would undo
+ * that for every command that imports this module's file, whether or not it
+ * ever asks a question.
+ *
+ * `screenMode: "main-screen"` keeps the dialog in the scrollback beside the
+ * report. The alternate screen would take the terminal over and then hand back
+ * a screen with no trace the question was ever asked.
+ */
+
+import type { SelectOption } from "../ui/state/types.js";
+
+export interface SelectDialogInput {
+	title: string;
+	message: string;
+	options: SelectOption[];
+	/** Row to start on. Defaults to the first. */
+	defaultIndex?: number;
+}
+
+/**
+ * Ask the user to pick one option. Resolves to the chosen value, or null when
+ * they cancel with Esc or Ctrl+C — the caller decides whether that is fatal.
+ *
+ * Falls back to `null` when stdin or stdout is not a TTY. A renderer needs both:
+ * `magus update > file` has a TTY stdin and a pipe for stdout, and mounting
+ * there writes escape sequences into the file.
+ */
+export async function selectDialog(
+	input: SelectDialogInput,
+): Promise<string | null> {
+	if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+		return null;
+	}
+
+	const [{ createCliRenderer }, { createRoot }, React, modals, dimensions] =
+		await Promise.all([
+			import("@opentui/core"),
+			import("@opentui/react"),
+			import("react"),
+			import("../ui/components/modals/index.js"),
+			import("../ui/state/DimensionsContext.js"),
+		]);
+
+	const renderer = await createCliRenderer({
+		screenMode: "main-screen",
+		// BOTH, so the renderer registers no handler of its own and teardown
+		// below is the only path. With either left at its default, a Ctrl+C
+		// destroys the renderer underneath this promise and it never settles.
+		exitSignals: [],
+		exitOnCtrlC: false,
+	});
+
+	const root = createRoot(renderer);
+
+	return await new Promise<string | null>((resolve) => {
+		// Clamped, not trusted: a caller computing an index from a list it built
+		// separately could hand over one that is out of range, and a cursor
+		// pointing past the end makes Enter resolve to null.
+		let index = Math.min(
+			Math.max(0, input.defaultIndex ?? 0),
+			Math.max(0, input.options.length - 1),
+		);
+		let done = false;
+
+		const finish = (value: string | null): void => {
+			if (done) return;
+			done = true;
+			renderer.keyInput.off("keypress", onKey);
+			root.unmount();
+			renderer.destroy();
+			resolve(value);
+		};
+
+		function onKey(key: {
+			name?: string;
+			ctrl?: boolean;
+			sequence?: string;
+		}): void {
+			if ((key.ctrl && key.name === "c") || key.name === "escape") {
+				finish(null);
+				return;
+			}
+			if (key.name === "return" || key.name === "enter") {
+				finish(input.options[index]?.value ?? null);
+				return;
+			}
+			if (key.name === "up" || key.name === "k") {
+				index = (index - 1 + input.options.length) % input.options.length;
+				draw();
+				return;
+			}
+			if (key.name === "down" || key.name === "j") {
+				index = (index + 1) % input.options.length;
+				draw();
+				return;
+			}
+			// The numbers stay live: the list is short, and the plain-text prompt
+			// this replaced numbered it, so the habit already exists.
+			const digit = Number(key.sequence);
+			if (
+				Number.isInteger(digit) &&
+				digit >= 1 &&
+				digit <= input.options.length
+			) {
+				index = digit - 1;
+				finish(input.options[index]?.value ?? null);
+			}
+		}
+
+		const draw = (): void => {
+			root.render(
+				React.createElement(
+					dimensions.DimensionsProvider,
+					null,
+					React.createElement(modals.SelectModal, {
+						title: input.title,
+						message: input.message,
+						options: input.options,
+						defaultIndex: index,
+						onSelect: finish,
+						onCancel: () => finish(null),
+					}),
+				),
+			);
+		};
+
+		renderer.keyInput.on("keypress", onKey);
+		draw();
+	});
+}

package/src/cli/update-view.ts

@@ -37,6 +37,7 @@ import { formatCommand } from "../utils/command-utils.js";
 import {
 	badge,
 	bold,
+	dialog,
 	dim,
 	elapsed,
 	fg,

package/src/cli/update.ts

@@ -70,8 +70,9 @@ import {
 } from "../services/update-plan.js";
 import { brand } from "../ui/theme.js";
 import { bold, dim, fg, width } from "./ansi.js";
-import { ensureManifest } from "./bootstrap.js";
+import { ensureManifest, requireActiveProfile } from "./bootstrap.js";
 import { LiveRegion, withPaused } from "./live.js";
+import { selectDialog } from "./tui-prompt.js";
 import {
 	type ApplyState,
 	type Step,
@@ -190,8 +191,42 @@ export async function runUpdateCommand(
 		return 1;
 	}
 
-	const profileIds = Object.keys(manifest.profiles);
-	if (flags.profile && !manifest.profiles[flags.profile]) {
+	// No active profile, no update: that is where plugin state is read from and
+	// where changes are written. Asked before the profile is resolved, so what
+	// the user activates here is what this run uses.
+	//
+	// BOTH `--check` and `--dry-run` are read-only here. An earlier version let
+	// `--dry-run` activate, reasoning that a preview needs a real profile to
+	// report against — but activating writes symlinks and edits a TRACKED
+	// `.gitignore`, and `--dry-run` promises to write nothing and exit 0. A
+	// preview that mutates the repo is not a preview.
+	//
+	// So a read-only run refuses instead, and the two flags differ only in what
+	// that refusal MEANS: `--check` is a gate, so it fails; `--dry-run` is a
+	// preview, and "nothing to preview until a profile is active" is a legitimate
+	// preview result rather than an error.
+	//
+	// NAMING A PROFILE SKIPS THE GATE. `magus update lean` says which profile to
+	// update, and updating it needs the manifest, not the symlink — installs go
+	// to project scope either way. Gating it would refuse a question the user
+	// already answered on the command line, and would break `magus update lean`
+	// and `--check lean` in CI, both of which worked before this gate existed.
+	// ANY positional argument skips it, not just a valid one. A wrong name has to
+	// reach the "Profile not found. Available: …" check below, which says what
+	// the user got wrong; gating it first answers a different question — "no
+	// profile is selected" — which is true, unhelpful, and not the mistake.
+	const current =
+		flags.profile !== undefined
+			? manifest
+			: await requireActiveProfile(projectPath, manifest, {
+					check: flags.check || flags.dryRun,
+				});
+	// A refused dry run exits 0: it wrote nothing and previewed nothing, which is
+	// what it promised. A refused `--check` exits 1, because that is a gate.
+	if (!current) return flags.dryRun ? 0 : 1;
+
+	const profileIds = Object.keys(current.profiles);
+	if (flags.profile && !current.profiles[flags.profile]) {
 		console.error(
 			failLine(
 				`Profile "${flags.profile}" not found. Available: ${profileIds.join(", ")}`,
@@ -204,19 +239,27 @@ export async function runUpdateCommand(
 	// use. A single-profile manifest needs no activation to be unambiguous.
 	// Chosen through the same function the TUI uses, so both judge a plugin
 	// against the same pin.
-	const targetId = selectProfileId(
+	const resolvedId = selectProfileId(
 		profileIds,
 		flags.profile,
 		await activeProfile(projectPath),
 	);
-	if (!targetId) {
+
+	// `requireActiveProfile` above has already guaranteed one is active, so rule
+	// 2 of `selectProfileId` resolves and this is only unreachable-guard. There
+	// is deliberately no "pick one for this run" fallback any more: it used to
+	// ask here and then update a profile the project was not running, which is
+	// the two-worlds behaviour the gate exists to end. An explicit argument is
+	// still honoured — naming a profile is naming intent.
+	if (!resolvedId) {
 		console.error(
 			failLine(
-				`No active profile. Pass one: magus update <${profileIds.join("|")}>`,
+				`No active profile. Run \`magus profile switch <${profileIds.join("|")}>\`.`,
 			),
 		);
 		return 1;
 	}
+	const targetId = resolvedId;
 
 	for (const line of header(targetId)) console.log(line);
 
@@ -243,7 +286,7 @@ export async function runUpdateCommand(
 
 	const closure = await runStep(steps.profile, async (say) => {
 		say(`resolving "${targetId}"`);
-		const resolved = await resolveProfile(manifest, targetId);
+		const resolved = await resolveProfile(current, targetId);
 		steps.profile.detail = [
 			`${Object.keys(resolved.plugins).length} plugins`,
 			`${resolved.bins.length} tools`,

package/src/main.tsx

@@ -104,7 +104,16 @@ async function main(): Promise<void> {
 	});
 }
 
-main().catch((error) => {
+main().catch(async (error) => {
+	// Ctrl+C at a prompt is an answer — "stop" — not a failure. 130 is the
+	// shell's own convention for SIGINT (128 + 2), so `magus update && next`
+	// stops rather than running `next`. The newline lands the shell prompt on
+	// its own line instead of against the half-finished question.
+	const { isPromptAborted } = await import("./cli/prompt.js");
+	if (isPromptAborted(error)) {
+		process.stderr.write("\n");
+		process.exit(130);
+	}
 	console.error("Error starting magus:", error);
 	process.exit(1);
 });

package/src/services/manifest.ts

@@ -52,6 +52,12 @@ export function migrateToV2(raw: unknown): ProfileManifest {
 	// Only carry strictVersions when enabled, so a committed manifest that
 	// doesn't opt in stays minimal (no spurious `"strictVersions": false`).
 	if (obj.strictVersions === true) manifest.strictVersions = true;
+	// Carried through even when it names no existing profile: dropping it here
+	// would silently "fix" a typo that `validateManifest` is meant to report,
+	// and the commands that read it all check the id resolves first.
+	if (typeof obj.default === "string" && obj.default !== "") {
+		manifest.default = obj.default;
+	}
 	return manifest;
 }
 
@@ -110,6 +116,21 @@ export function validateManifest(
 		errors.push({ path: "profiles", message: "no profiles defined" });
 	}
 
+	// A `default` naming nothing is worse than none: a fresh clone would fall
+	// through to asking, with no sign that the repo tried to answer and got the
+	// id wrong. Reported here so it fails the same gate every other manifest
+	// mistake does, rather than being discovered as silence.
+	if (manifest.default !== undefined) {
+		if (typeof manifest.default !== "string") {
+			errors.push({ path: "default", message: "must be a profile id" });
+		} else if (!ids.includes(manifest.default)) {
+			errors.push({
+				path: "default",
+				message: `no profile "${manifest.default}" — declared: ${ids.join(", ")}`,
+			});
+		}
+	}
+
 	for (const [id, entry] of Object.entries(manifest.profiles ?? {})) {
 		const base = `profiles.${id}`;
 		if (!entry || typeof entry !== "object") {