magus-cli 0.0.0-placeholder → 7.1.0

package/src/cli/ansi.ts

@@ -0,0 +1,528 @@
+/**
+ * ansi.ts — colour, colour maths and one-row widgets for the printed commands.
+ *
+ * The interactive TUI draws through OpenTUI. `magus update`, `install` and
+ * `doctor` cannot: they print into the user's scrollback, interleave readline
+ * prompts, and hand the terminal to subprocesses that inherit stdio. Mounting a
+ * renderer around that fights all three. So the same visual language is rebuilt
+ * here on raw escape sequences — one blended colour per meter cell, badges with
+ * ink we own, dim chrome and saturated signal.
+ *
+ * PALETTE PARITY IS THE POINT. Every hue comes from `ui/theme.ts`'s `brand`, so
+ * a colour means one thing across the whole product: amber is "behind" in the
+ * TUI's plugin list and in an update plan alike. Nothing here invents a hue.
+ *
+ * The two `ramps` are the one place brand tokens are transformed, and they say
+ * why: `brand` is tuned to clear 3:1 as INK on both light and dark terminals,
+ * which makes it mid-dark. A solid block is a UI component, not text — WCAG's
+ * text ratio does not apply to it, and mid-dark blocks read as mud. So the fill
+ * ramps lighten those tokens. Ink colours are never lightened.
+ *
+ * No OpenTUI type crosses this boundary: hex in, escaped string out.
+ */
+
+import { barTrack } from "../ui/theme-mode.js";
+import { brand } from "../ui/theme.js";
+
+// -- colour capability -------------------------------------------------------
+
+/** Test seam. `null` restores environment detection. */
+let colorOverride: boolean | null = null;
+
+/** Force colour on or off; pass null to go back to detecting it. Tests only. */
+export function setColorEnabled(value: boolean | null): void {
+	colorOverride = value;
+}
+
+/**
+ * Whether to emit escape sequences at all.
+ *
+ * Order matters: NO_COLOR (any non-empty value, per no-color.org) beats
+ * FORCE_COLOR, which beats TTY detection. The other order would hand colour to
+ * a user who exported NO_COLOR in their shell profile the moment they ran under
+ * a CI that sets FORCE_COLOR.
+ */
+export function colorEnabled(): boolean {
+	if (colorOverride !== null) return colorOverride;
+	const no = process.env.NO_COLOR;
+	if (no !== undefined && no !== "") return false;
+	const force = process.env.FORCE_COLOR;
+	if (force !== undefined) return force !== "0" && force !== "false";
+	if (process.env.TERM === "dumb") return false;
+	return process.stdout.isTTY === true;
+}
+
+// -- hex and channels --------------------------------------------------------
+
+const clamp01 = (n: number): number =>
+	Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+
+/** `#rgb` and `#rrggbb`, hash optional. Anything else resolves to black. */
+function parseHex(hex: string): [number, number, number] {
+	let h = hex.trim().replace(/^#/, "");
+	if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+	if (!/^[0-9a-fA-F]{6}$/.test(h)) return [0, 0, 0];
+	return [
+		Number.parseInt(h.slice(0, 2), 16),
+		Number.parseInt(h.slice(2, 4), 16),
+		Number.parseInt(h.slice(4, 6), 16),
+	];
+}
+
+const toHex = (c: [number, number, number]): string =>
+	`#${c
+		.map((n) =>
+			Math.round(Math.min(255, Math.max(0, n)))
+				.toString(16)
+				.padStart(2, "0"),
+		)
+		.join("")}`;
+
+// -- colour maths ------------------------------------------------------------
+
+/**
+ * Linear interpolation in sRGB channel space, `t` clamped to 0..1.
+ *
+ * sRGB is a deliberate choice with a known cost: a two-stop blend between
+ * distant hues desaturates through the middle. Both ramps below therefore carry
+ * an explicit midtone stop rather than trusting the interpolator to find a good
+ * one — a chosen control point beats any colour space.
+ */
+export function mix(from: string, to: string, t: number): string {
+	const k = clamp01(t);
+	const a = parseHex(from);
+	const b = parseHex(to);
+	return toHex([
+		a[0] + (b[0] - a[0]) * k,
+		a[1] + (b[1] - a[1]) * k,
+		a[2] + (b[2] - a[2]) * k,
+	]);
+}
+
+/**
+ * `steps` colours from `from` to `to`, BOTH ENDPOINTS INCLUSIVE.
+ *
+ *   out.length === steps, out[0] === from, out[steps - 1] === to
+ *
+ * `steps === 1` takes the `from` end, so there is no division by zero. Zero,
+ * negative and non-integer all give `[]`. Call it with the widget's real width:
+ * one colour per cell is what reads as continuous.
+ */
+export function blend1D(steps: number, from: string, to: string): string[] {
+	if (!Number.isInteger(steps) || steps <= 0) return [];
+	if (steps === 1) return [toHex(parseHex(from))];
+	return Array.from({ length: steps }, (_, i) =>
+		mix(from, to, i / (steps - 1)),
+	);
+}
+
+/** Multi-stop ramp: `steps` colours spread evenly across every stop, in order. */
+export function blendStops(steps: number, ...stops: string[]): string[] {
+	if (!Number.isInteger(steps) || steps <= 0 || stops.length === 0) return [];
+	const first = stops[0];
+	const last = stops[stops.length - 1];
+	if (stops.length === 1 || steps === 1) return blend1D(steps, first, last);
+	const segs = stops.length - 1;
+	return Array.from({ length: steps }, (_, i) => {
+		const p = (i / (steps - 1)) * segs;
+		const s = Math.min(segs - 1, Math.floor(p));
+		return mix(stops[s], stops[s + 1], p - s);
+	});
+}
+
+/** Scale toward black by `amount` (0..1). */
+export function darken(hex: string, amount: number): string {
+	const k = 1 - clamp01(amount);
+	const [r, g, b] = parseHex(hex);
+	return toHex([r * k, g * k, b * k]);
+}
+
+/** Scale toward white by `amount` (0..1). */
+export function lighten(hex: string, amount: number): string {
+	const k = clamp01(amount);
+	const [r, g, b] = parseHex(hex);
+	return toHex([r + (255 - r) * k, g + (255 - g) * k, b + (255 - b) * k]);
+}
+
+/**
+ * Ink that stays readable on a filled block of `hex`.
+ *
+ * Perceived luminance, not the channel average: green contributes nearly six
+ * times what blue does, so an average puts white ink on amber and loses it.
+ */
+export function inkOn(hex: string): string {
+	const [r, g, b] = parseHex(hex);
+	return 0.299 * r + 0.587 * g + 0.114 * b > 140 ? "#101014" : brand.ink;
+}
+
+// -- styling -----------------------------------------------------------------
+
+const RESET = "\x1b[0m";
+
+/** Paint `text` in `hex` as foreground. Returns `text` unchanged when off. */
+export function fg(hex: string, text: string): string {
+	if (!colorEnabled()) return text;
+	const [r, g, b] = parseHex(hex);
+	return `\x1b[38;2;${r};${g};${b}m${text}${RESET}`;
+}
+
+/** Paint `text` on a `hex` background. Returns `text` unchanged when off. */
+export function bg(hex: string, text: string): string {
+	if (!colorEnabled()) return text;
+	const [r, g, b] = parseHex(hex);
+	return `\x1b[48;2;${r};${g};${b}m${text}${RESET}`;
+}
+
+/** Both in one sequence, so nothing nested can reset half a badge. */
+export function on(bgHex: string, fgHex: string, text: string): string {
+	if (!colorEnabled()) return text;
+	const [br, bgn, bb] = parseHex(bgHex);
+	const [fr, fgn, fb] = parseHex(fgHex);
+	return `\x1b[48;2;${br};${bgn};${bb};38;2;${fr};${fgn};${fb}m${text}${RESET}`;
+}
+
+export function bold(text: string): string {
+	return colorEnabled() ? `\x1b[1m${text}${RESET}` : text;
+}
+
+/** De-emphasis by colour, not by SGR 2 — faint is unreliable across terminals. */
+export function dim(text: string): string {
+	return fg(brand.muted, text);
+}
+
+// -- measuring ---------------------------------------------------------------
+
+/** Every CSI sequence, not only SGR — the live region emits cursor moves too. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ESC is the thing being matched.
+const CSI = /\x1b\[[0-9;?]*[\x20-\x2f]*[\x40-\x7e]/g;
+
+export function stripAnsi(text: string): string {
+	return text.replace(CSI, "");
+}
+
+/**
+ * Cells one codepoint occupies: 0, 1 or 2.
+ *
+ * UNDER-COUNTING IS THE DANGEROUS DIRECTION. A line measured narrower than it
+ * renders reaches the terminal's last column, auto-wraps into a second row, and
+ * then the live region's cursor-up erase — which counted it as one row — starts
+ * inside the block and smears it down the screen. Over-counting only clips a
+ * character early. So where a range is genuinely in doubt, widen.
+ *
+ * The ranges are East Asian Wide plus the emoji blocks that render double in
+ * every terminal worth supporting. EAW-AMBIGUOUS characters (most of the
+ * U+2500 box-drawing and arrow range, including `↑` and `→` used in the update
+ * report) are deliberately counted as 1: terminals genuinely disagree, and
+ * treating them as wide would misalign the common, correct case.
+ */
+function charWidth(cp: number): number {
+	// Combining marks, variation selectors, and the zero-width joiner take no
+	// cell. ZWJ matters: without it a three-person emoji family measures as
+	// three separate wide glyphs instead of one.
+	if (
+		(cp >= 0x0300 && cp <= 0x036f) ||
+		(cp >= 0xfe00 && cp <= 0xfe0f) ||
+		cp === 0x200d ||
+		cp === 0xfeff
+	)
+		return 0;
+	if (
+		(cp >= 0x1100 && cp <= 0x115f) ||
+		// Individually-Wide dingbats and symbols scattered through U+2000-27BF.
+		cp === 0x231a ||
+		cp === 0x231b ||
+		(cp >= 0x23e9 && cp <= 0x23ec) ||
+		cp === 0x23f0 ||
+		cp === 0x23f3 ||
+		(cp >= 0x25fd && cp <= 0x25fe) ||
+		(cp >= 0x2614 && cp <= 0x2615) ||
+		(cp >= 0x2648 && cp <= 0x2653) ||
+		cp === 0x267f ||
+		cp === 0x2693 ||
+		cp === 0x26a1 ||
+		(cp >= 0x26aa && cp <= 0x26ab) ||
+		(cp >= 0x26bd && cp <= 0x26be) ||
+		(cp >= 0x26c4 && cp <= 0x26c5) ||
+		cp === 0x26ce ||
+		cp === 0x26d4 ||
+		cp === 0x26ea ||
+		(cp >= 0x26f2 && cp <= 0x26f3) ||
+		cp === 0x26f5 ||
+		cp === 0x26fa ||
+		cp === 0x26fd ||
+		cp === 0x2705 ||
+		(cp >= 0x270a && cp <= 0x270b) ||
+		cp === 0x2728 ||
+		cp === 0x274c ||
+		cp === 0x274e ||
+		(cp >= 0x2753 && cp <= 0x2755) ||
+		cp === 0x2757 ||
+		(cp >= 0x2795 && cp <= 0x2797) ||
+		cp === 0x27b0 ||
+		cp === 0x27bf ||
+		(cp >= 0x2b1b && cp <= 0x2b1c) ||
+		cp === 0x2b50 ||
+		cp === 0x2b55 ||
+		(cp >= 0x2e80 && cp <= 0x303e) ||
+		(cp >= 0x3041 && cp <= 0x33ff) ||
+		(cp >= 0x3400 && cp <= 0x4dbf) ||
+		(cp >= 0x4e00 && cp <= 0x9fff) ||
+		(cp >= 0xa000 && cp <= 0xa4cf) ||
+		(cp >= 0xac00 && cp <= 0xd7a3) ||
+		(cp >= 0xf900 && cp <= 0xfaff) ||
+		(cp >= 0xfe30 && cp <= 0xfe6f) ||
+		(cp >= 0xff00 && cp <= 0xff60) ||
+		(cp >= 0xffe0 && cp <= 0xffe6) ||
+		// Emoji planes, contiguous rather than the three islands this used to
+		// carry — the gaps (transport at U+1F680, flags at U+1F1E6) all render
+		// wide, so excluding them was pure under-count.
+		(cp >= 0x1f000 && cp <= 0x1f9ff) ||
+		(cp >= 0x1fa70 && cp <= 0x1faff) ||
+		(cp >= 0x20000 && cp <= 0x3fffd)
+	)
+		return 2;
+	return 1;
+}
+
+/** Visible cell width, ignoring escape sequences. */
+export function width(text: string): number {
+	let w = 0;
+	for (const ch of stripAnsi(text)) w += charWidth(ch.codePointAt(0) ?? 0);
+	return w;
+}
+
+/** Pad on the right to `n` visible cells. Never truncates. */
+export function padEnd(text: string, n: number): string {
+	const w = width(text);
+	return w >= n ? text : text + " ".repeat(n - w);
+}
+
+/** Pad on the left to `n` visible cells — the only safe padding for numerals. */
+export function padStart(text: string, n: number): string {
+	const w = width(text);
+	return w >= n ? text : " ".repeat(n - w) + text;
+}
+
+/**
+ * Clip to `n` visible cells, stepping over escape sequences rather than
+ * counting them.
+ *
+ * The live region depends on this. A line one cell too wide occupies two
+ * terminal rows while the repainter still counts it as one, so the cursor-up
+ * arithmetic drifts by a row per frame and the block smears down the screen.
+ */
+export function truncate(text: string, n: number): string {
+	if (n <= 0) return "";
+	if (width(text) <= n) return text;
+	let out = "";
+	let w = 0;
+	let i = 0;
+	while (i < text.length) {
+		CSI.lastIndex = i;
+		const m = CSI.exec(text);
+		if (m && m.index === i) {
+			out += m[0];
+			i += m[0].length;
+			continue;
+		}
+		const cp = text.codePointAt(i);
+		if (cp === undefined) break;
+		const ch = String.fromCodePoint(cp);
+		const cw = charWidth(cp);
+		if (w + cw > n) break;
+		out += ch;
+		w += cw;
+		i += ch.length;
+	}
+	return out + (colorEnabled() ? RESET : "");
+}
+
+// -- palette derived for fills -----------------------------------------------
+
+/**
+ * Gradient stops for filled blocks. Lightened brand tokens — the file header
+ * says why ink hues and fill hues cannot be the same values.
+ */
+export const ramps = {
+	/**
+	 * Work in progress to done. Purple is magus's brand, green is "settled",
+	 * and the blue midtone is the chosen control point that stops a two-hue
+	 * blend desaturating into grey at the halfway mark.
+	 */
+	progress: [
+		lighten(brand.accent, 0.15),
+		lighten(brand.link, 0.2),
+		lighten(brand.success, 0.25),
+	],
+	/**
+	 * Severity: green through amber to red, for any magnitude that is bad news
+	 * as it grows — a step's share of the run's wall clock, a count of items
+	 * behind. Same three hues as the badges, so "amber means look at this" holds
+	 * whether it is a bar or a chip.
+	 */
+	severity: [
+		lighten(brand.success, 0.25),
+		lighten(brand.warning, 0.2),
+		lighten(brand.danger, 0.15),
+	],
+} as const;
+
+// -- widgets -----------------------------------------------------------------
+
+const FILL = "█";
+const TRACK = "░";
+
+/**
+ * The unfilled part of a bar, resolved per page.
+ *
+ * At full `brand.muted` a 20-cell `░` track reads as hatched texture rather
+ * than as emptiness, and competes with the fill — the opposite of "dim the
+ * chrome, saturate the signal". A track is chrome.
+ *
+ * Which grey is quiet depends on the page, so the two values and the numbers
+ * behind them live in `ui/theme-mode.ts`. Resolved per CALL, never hoisted into
+ * a const: the mode is set at startup by the router, after this module loads.
+ */
+const TRACK_COLOR = (): string => barTrack();
+
+/**
+ * Gradient meter: `cells` wide, one blended colour per filled cell.
+ *
+ * `pct` is 0..100, never 0..1 — the single most common way this widget goes
+ * silently wrong. The track glyph is the same width as the fill glyph, so the
+ * row cannot change length as it fills.
+ */
+export function meter(
+	pct: number,
+	cells: number,
+	stops: readonly string[] = ramps.progress,
+): string {
+	if (cells <= 0) return "";
+	const p = clamp01((Number.isFinite(pct) ? pct : 0) / 100);
+	const filled = Math.round(p * cells);
+	const cols = blendStops(
+		cells,
+		...(stops.length > 0 ? stops : ramps.progress),
+	);
+	let out = "";
+	for (let i = 0; i < cells; i++) {
+		out += i < filled ? fg(cols[i], FILL) : fg(TRACK_COLOR(), TRACK);
+	}
+	return out;
+}
+
+/** One share of a stacked bar, in one semantic colour. */
+export interface BarSegment {
+	value: number;
+	color: string;
+}
+
+/**
+ * Stacked bar for a category distribution — the counts ARE the shape.
+ *
+ * Exactly `cells` wide, always. Two rules fight for that width and the order
+ * between them is the whole design:
+ *
+ *  1. Every non-zero segment gets at least one cell, so one outlier in a large
+ *     set stays visible instead of rounding to nothing.
+ *  2. The row is never wider than `cells`.
+ *
+ * Rule 2 wins. When there are more non-zero segments than cells, rule 1 is
+ * impossible — the earlier version tried anyway: its shrink loop gave up once
+ * every segment was down to one cell and returned a row WIDER than asked for
+ * (measured: 5 cells for `cells = 3` with five segments), silently breaking the
+ * alignment every caller depends on. Now the largest segments keep their cell
+ * and the smallest are dropped, which is lossy but bounded and visible.
+ */
+export function stackedBar(cells: number, segments: BarSegment[]): string {
+	if (cells <= 0) return "";
+	let live = segments.filter((s) => s.value > 0);
+	if (live.length === 0) return fg(TRACK_COLOR(), TRACK.repeat(cells));
+	// More segments than cells: keep the biggest `cells` of them, in place.
+	if (live.length > cells) {
+		const cutoff = [...live]
+			.sort((a, b) => b.value - a.value)
+			.slice(0, cells)
+			.reduce((min, s) => Math.min(min, s.value), Number.POSITIVE_INFINITY);
+		const kept: BarSegment[] = [];
+		for (const s of live) {
+			if (s.value >= cutoff && kept.length < cells) kept.push(s);
+		}
+		live = kept;
+	}
+	const total = live.reduce((n, s) => n + s.value, 0);
+	const widths = live.map((s) =>
+		Math.max(1, Math.floor((s.value / total) * cells)),
+	);
+	let drift = cells - widths.reduce((n, w) => n + w, 0);
+	while (drift !== 0) {
+		const i = widths.indexOf(Math.max(...widths));
+		if (drift > 0) {
+			widths[i]++;
+			drift--;
+		} else if (widths[i] > 1) {
+			widths[i]--;
+			drift++;
+		} else break;
+	}
+	return live.map((s, i) => fg(s.color, FILL.repeat(widths[i]))).join("");
+}
+
+/**
+ * Indeterminate progress: a comet sweeping a dim track, `cells` wide.
+ *
+ * The honest widget for work with no denominator — a catalog read, a git fetch
+ * whose object count nobody exposes. A determinate meter would have to invent a
+ * percentage, and an invented percentage that sticks at 90% is worse than no
+ * bar at all. The head is full `hue`, the tail fades toward black over `band`
+ * cells, and the whole thing wraps every `cells + band` ticks.
+ */
+export function sweep(
+	cells: number,
+	tick: number,
+	hue: string,
+	band = 5,
+): string {
+	if (cells <= 0) return "";
+	const period = cells + band;
+	const head = ((Math.trunc(tick) % period) + period) % period;
+	let out = "";
+	for (let i = 0; i < cells; i++) {
+		const behind = head - i;
+		const heat = behind >= 0 && behind < band ? 1 - behind / band : 0;
+		out +=
+			heat <= 0
+				? fg(TRACK_COLOR(), TRACK)
+				: fg(mix(darken(hue, 0.75), hue, heat), FILL);
+	}
+	return out;
+}
+
+/** A discrete status, as dark-or-white ink on a saturated fill. */
+export function badge(label: string, hex: string, ink?: string): string {
+	// `inkOn` picks black or white by luminance, which is right for a saturated
+	// fill and blunt for a pale one: a soft ochre chip reads better with the deep
+	// member of its own family than with flat black. A caller carrying a measured
+	// pair passes it; everyone else keeps the automatic choice.
+	return on(hex, ink ?? inkOn(hex), ` ${label} `);
+}
+
+/**
+ * Braille spinner. Ten frames, so a 12 fps repaint cycles in under a second:
+ * fast enough to read as motion, slow enough not to strobe.
+ */
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export function spinner(tick: number): string {
+	return SPINNER[Math.abs(Math.trunc(tick)) % SPINNER.length];
+}
+
+/** Elapsed time sized to its magnitude: `340ms`, `1.4s`, `2m04s`. */
+export function elapsed(ms: number): string {
+	if (!Number.isFinite(ms) || ms < 0) return "--";
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+	const m = Math.floor(ms / 60_000);
+	const s = Math.round((ms - m * 60_000) / 1000);
+	return `${m}m${String(s).padStart(2, "0")}s`;
+}

package/src/cli/bootstrap.ts

@@ -0,0 +1,134 @@
+/**
+ * Manifest bootstrap — the "this repo has no profiles yet" path.
+ *
+ * `install` and `update` both require `.claude/profiles.json`. Rather than
+ * giving each a manifest-free fallback (two behaviours to keep in step, and a
+ * repo that never gets a committed manifest), a repo without one is offered
+ * adoption: magus writes the manifest that describes the project as it
+ * stands, then the original command proceeds against it normally.
+ */
+
+import {
+	getManifestPath,
+	readManifest,
+	writeManifest,
+} from "../services/manifest.js";
+import {
+	type AdoptResult,
+	adoptCurrentProject,
+} from "../services/profile-adopt.js";
+import type { ProfileManifest } from "../types/index.js";
+import { confirm } from "./prompt.js";
+
+/** Print what adoption would capture, so the user can judge it before writing. */
+function printAdoptionPlan(result: AdoptResult): void {
+	console.log(
+		"\nThis project has no .claude/profiles.json — magus can create one from its current setup.\n",
+	);
+	console.log(`  profile      ${result.profileId} (${result.entry.name})`);
+	console.log(
+		`  plugins      ${result.counts.plugins} enabled, adopted as "latest"`,
+	);
+	if (result.source === "user") {
+		// Never let this be invisible: the generated file is meant to be committed,
+		// and these came from ~/.claude/settings.json — this machine's personal
+		// global set, not anything this repo chose.
+		console.log(
+			"               ⚠ read from ~/.claude/settings.json (user scope) — this project",
+		);
+		console.log(
+			"                 enables none of its own. Review before committing.",
+		);
+	}
+	if (result.counts.mcpServers > 0) {
+		console.log(`  mcp servers  ${result.counts.mcpServers} from .mcp.json`);
+	}
+	if (result.counts.settingsKeys > 0) {
+		console.log(
+			`  settings     ${result.counts.settingsKeys} keys carried over`,
+		);
+	}
+	for (const id of result.skipped) {
+		console.log(
+			`  ⚠ skipped ${id} — no marketplace in its id, not reproducible`,
+		);
+	}
+	for (const hit of result.machinePaths) {
+		console.log(`  ⚠ machine path  ${hit}`);
+	}
+	if (result.machinePaths.length > 0) {
+		console.log(
+			"    Those name a directory on THIS machine and will not resolve on another.",
+		);
+	}
+	console.log(
+		"\nCommit the file to share this setup with the team; edit it to pin versions.",
+	);
+}
+
+export interface EnsureManifestOptions {
+	/** Read-only mode: never write, just report that adoption is needed. */
+	check?: boolean;
+	/**
+	 * Adopt without prompting. Set only by `magus profile init`, where
+	 * creating the manifest IS the command the user asked for.
+	 */
+	allowAdopt?: boolean;
+}
+
+/**
+ * Return the project's manifest, creating one by adoption if it has none.
+ *
+ * Resolves to null when there is no manifest and none was created — the caller
+ * should exit non-zero. Anything it prints has already explained why.
+ */
+export async function ensureManifest(
+	projectPath: string,
+	opts: EnsureManifestOptions = {},
+): Promise<ProfileManifest | null> {
+	const manifest = await readManifest(projectPath);
+	if (Object.keys(manifest.profiles).length > 0) return manifest;
+
+	const result = await adoptCurrentProject(projectPath);
+
+	if (result.counts.plugins === 0) {
+		console.error(
+			`No .claude/profiles.json in ${projectPath}, and no enabled plugins to adopt one from.`,
+		);
+		console.error(
+			"Open magus and select the plugins this project needs, then re-run.",
+		);
+		return null;
+	}
+
+	printAdoptionPlan(result);
+
+	if (opts.check) {
+		console.error(
+			"\n--check is read-only and will not create the manifest. Run `magus install` once to adopt.",
+		);
+		return null;
+	}
+
+	// `--yes` alone is NOT consent to author this file. It means "do not ask me
+	// about the thing I invoked", and someone running `magus update --yes` in
+	// CI invoked an update, not the creation of their team's committed contract —
+	// which this would otherwise write unreviewed, possibly from the machine's
+	// user-scope plugin set. Creating it needs either a human at the prompt or
+	// the command whose whole purpose is to create it.
+	if (opts.allowAdopt) {
+		// fall through to the write
+	} else if (!process.stdin.isTTY) {
+		console.error(
+			"\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?"))) {
+		console.log("Aborted — nothing written.");
+		return null;
+	}
+
+	await writeManifest(result.manifest, projectPath);
+	console.log(`✓ Wrote ${getManifestPath(projectPath)}\n`);
+	return result.manifest;
+}