magus-cli 7.7.0 → 7.8.0

package/src/ui/adapters/startupReports.ts

@@ -0,0 +1,282 @@
+/**
+ * The failure popup's words for everything outside the Plugins screen's apply
+ * paths: the profile gate at startup, a profile activation, the startup
+ * repairs (stale plugin loads, marketplace refreshes, gitignore fixes) and the
+ * Git State screen. Each is a pure builder over what the service returned, on
+ * top of {@link failureReport}, so they read like every other failure.
+ *
+ * Each returns null when nothing failed: success says nothing, because the
+ * screen shows it.
+ */
+
+import type { StaleLoadRepairResult } from "../../services/claude-settings.js";
+import type { ActivationResult } from "../../services/profile-activate.js";
+import { SettingsParseError } from "../../services/settings-file.js";
+import { pluginName } from "../../services/update-engine.js";
+import { userFacingPath, withUserFacingPath } from "../../utils/user-path.js";
+import type { FailureReport, FailureRow } from "../state/types.js";
+import {
+	counted,
+	failureReport,
+	mergeFailureReports,
+} from "./failureReport.js";
+import { exceptionReason, pluginFailureReport } from "./pluginsAdapter.js";
+
+/** `run magus install` → `Run magus install`. */
+function sentence(text: string): string {
+	return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+
+/**
+ * One line the profile gate refused on, as a row. The gate words them
+ * "<file> cannot be read (<why>) — fix it by hand; magus left it as it is and
+ * did not switch": the file is the subject, the instruction the fix, and the
+ * rest the reason. A line of another shape is about the profile itself.
+ */
+export function profileProblemRow(problem: string): FailureRow {
+	const dash = problem.indexOf(" — ");
+	const head = dash >= 0 ? problem.slice(0, dash) : problem;
+	const tail = dash >= 0 ? problem.slice(dash + 3) : "";
+	const file = /^(\S+) (cannot be read\b.*)$/.exec(head);
+	const subject = file?.[1] ?? "profile";
+	let reason = file?.[2] ?? head;
+	let fix: string | undefined;
+	if (tail) {
+		const [instruction = "", ...rest] = tail.split("; ");
+		fix = sentence(instruction);
+		if (rest.length > 0) reason = `${reason} — ${rest.join("; ")}`;
+	}
+	return fix ? { subject, reason, fix } : { subject, reason };
+}
+
+/**
+ * H2: what the startup gate refused — `prepareProfileStartup(...).problems`.
+ * Shown before the profile question, which it does not replace: the question
+ * is still asked about whatever is left.
+ */
+export function profileProblemsReport(
+	problems: readonly string[],
+	headline = "This project's profile was not brought up to date",
+): FailureReport | null {
+	return failureReport(headline, problems.map(profileProblemRow));
+}
+
+/**
+ * H3: what a profile activation could not do, from its {@link
+ * ActivationResult}s — the startup re-render or format update, the startup
+ * choice, a Profiles-tab switch. ONE builder for all of them.
+ *
+ * Listed: plugins that will not load because the profile turns a dependency
+ * off; plugins whose dependencies could not be read because they are not
+ * downloaded; skills that did not install, with why; a skill that exists in
+ * two copies, saying which was kept and what to do. Everything else an
+ * activation reports is either done or shown as the screen's state.
+ */
+export function activationFailureReport(
+	results: ReadonlyArray<ActivationResult | null | undefined>,
+): FailureReport | null {
+	const rows: FailureRow[] = [];
+	const seen = new Set<string>();
+	const add = (row: FailureRow) => {
+		const key = `${row.subject}\u0000${row.reason}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		rows.push(row);
+	};
+	let profile: string | null = null;
+
+	for (const result of results) {
+		if (!result) continue;
+		profile ??= result.profileId;
+		for (const { plugin, dependency } of result.dependencies?.blocked ?? []) {
+			add({
+				subject: pluginName(plugin),
+				reason: `will not load: it depends on ${pluginName(dependency)}, which profile "${result.profileId}" turns off`,
+				fix: `Remove "${dependency}": false from the profile to let it load`,
+			});
+		}
+		for (const plugin of result.dependencies?.unreadable ?? []) {
+			add({
+				subject: pluginName(plugin),
+				reason:
+					"is not downloaded on this machine, so nothing it depends on was turned on",
+				fix: "Run magus install",
+			});
+		}
+		for (const f of result.skills.failed) {
+			add({
+				subject: `skill ${f.skill}`,
+				reason: `was not installed: ${exceptionReason(f.reason).reason}`,
+			});
+		}
+		for (const c of result.conversion.conflicts) {
+			add({
+				subject: `skill ${c.folder}`,
+				reason: `exists in two copies: ${c.kept} is the one in use, the other is at ${c.other}`,
+				fix: "Compare the two and delete the one you do not want",
+			});
+		}
+	}
+	if (rows.length === 0) return null;
+	return failureReport(
+		`Profile "${profile}" is active, but ${counted(rows.length, "thing")} did not work`,
+		rows,
+	);
+}
+
+/** The headline when the startup gate and the re-render both have something. */
+export const PROFILE_STARTUP_HEADLINE =
+	"This project's profile was not fully brought up to date";
+
+/**
+ * R8: everything the startup profile gate could not do, as ONE popup — what
+ * it refused ({@link profileProblemsReport}) and what its activation could not
+ * do ({@link activationFailureReport}). Both come from the same startup step,
+ * so they are one event: two popups in a row made the user dismiss twice for
+ * one thing. Either alone keeps its own headline.
+ */
+export function profileStartupReport(
+	problems: readonly string[],
+	activations: ReadonlyArray<ActivationResult | null | undefined>,
+): FailureReport | null {
+	return mergeFailureReports(PROFILE_STARTUP_HEADLINE, [
+		profileProblemsReport(problems),
+		activationFailureReport(activations),
+	]);
+}
+
+/**
+ * H4: the startup "Repair plugins" — each repair that did not bring the
+ * installed version forward, with its own reason.
+ */
+export function staleRepairReport(
+	results: readonly StaleLoadRepairResult[],
+): FailureReport | null {
+	return pluginFailureReport(
+		results
+			.filter((r) => !r.ok)
+			.map((r) => ({
+				pluginId: r.pluginId,
+				verb: "repaired" as const,
+				detail:
+					r.error ??
+					`Claude Code still does not load v${r.target} in this folder`,
+			})),
+	);
+}
+
+/** The fix for a settings file that does not parse: magus will not write over it. */
+export const FIX_BY_HAND = "Fix the file by hand, then try again";
+
+/**
+ * A thrown error from a whole step, as ONE row about `subject`.
+ *
+ * The reason is the error's first line. A cause magus recognises carries its
+ * own fix: no `claude` (a `spawn … claude ENOENT` included), no network, or a
+ * settings file that does not parse. That last one is about the FILE, so the
+ * file is the row's subject — named the way the user knows it
+ * (`.claude/settings.json`, `~/.claude/settings.json`), never by absolute path
+ * — because fixing it by hand is the only way on. `fallbackFix` is the fix for
+ * anything else: the command to run yourself, say. Without one, an
+ * unrecognised error has no fix line, because there is no real action to offer.
+ */
+export function stepFailureReport(
+	headline: string,
+	subject: string,
+	error: unknown,
+	fallbackFix?: string,
+): FailureReport {
+	if (error instanceof SettingsParseError) {
+		const detail = withUserFacingPath(
+			exceptionReason(error.detail).reason,
+			error.path,
+		);
+		return {
+			headline,
+			rows: [
+				{
+					subject: userFacingPath(error.path),
+					reason: `${error.problem} (${detail})`,
+				},
+			],
+			fix: FIX_BY_HAND,
+		};
+	}
+	const e = exceptionReason(
+		error instanceof Error ? error.message : String(error),
+	);
+	return {
+		headline,
+		rows: [{ subject, reason: e.reason }],
+		fix: e.fix ?? fallbackFix ?? null,
+	};
+}
+
+/**
+ * M8: marketplaces whose refresh failed after startup re-registered them.
+ * Until one refreshes, its plugins are read from a copy that may be old.
+ */
+export function marketplaceRefreshReport(
+	failures: ReadonlyArray<{ marketplace: string; error: unknown }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failures.length, "marketplace")} could not be refreshed`,
+		failures.map(({ marketplace, error }) => {
+			const e = exceptionReason(
+				error instanceof Error ? error.message : String(error),
+			);
+			return {
+				subject: marketplace,
+				reason: e.reason,
+				...(e.fix ? { fix: e.fix } : {}),
+			};
+		}),
+	);
+}
+
+/**
+ * M9: generated files the startup gitignore fix could not untrack, each with
+ * git's own reason.
+ */
+export function gitignoreStartupReport(
+	failed: ReadonlyArray<{ path: string; reason: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failed.length, "generated file")} ${failed.length === 1 ? "is" : "are"} still tracked by git`,
+		failed.map((f) => ({
+			subject: f.path,
+			reason: exceptionReason(f.reason).reason,
+		})),
+	);
+}
+
+/** Git State fixes that did not apply, each with its reason. */
+export function gitignoreFixReport(
+	failed: ReadonlyArray<{ path: string; message: string }>,
+): FailureReport | null {
+	return failureReport(
+		`${counted(failed.length, "fix", "fixes")} did not apply`,
+		failed.map((f) => ({
+			subject: f.path,
+			reason: exceptionReason(f.message).reason,
+		})),
+	);
+}
+
+/**
+ * M9: template rules a merge skipped because they contradict a rule the
+ * manifest already has. They are not in the list, so this is the only place
+ * the user learns of them.
+ */
+export function gitignoreTemplateReport(
+	template: string,
+	conflicts: readonly string[],
+): FailureReport | null {
+	return failureReport(
+		`${counted(conflicts.length, "rule")} from "${template}" ${conflicts.length === 1 ? "was" : "were"} not added`,
+		conflicts.map((pattern) => ({
+			subject: pattern,
+			reason: "skipped: conflicts with existing rules",
+		})),
+	);
+}

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

@@ -0,0 +1,231 @@
+import type { FailureReport, FailureRow } from "../../state/types.js";
+import { theme } from "../../theme.js";
+
+/** Border (2) and horizontal padding (3 + 3). */
+const CHROME = 8;
+const MAX_WIDTH = 88;
+const MIN_WIDTH = 40;
+/** "✗ " before each row's subject. */
+const MARK = "✗ ";
+/**
+ * Rows of the popup that are not failure rows: border (2), padding (2), the
+ * headline and its gap (2), the footer and its gap (2), and a row of air
+ * between the popup and the terminal's edge (2).
+ */
+const FIXED_ROWS = 10;
+
+/**
+ * The popup's width for a terminal `terminalWidth` columns wide: as wide as the
+ * rows need, never wider than the terminal leaves room for.
+ */
+export function failureListWidth(terminalWidth: number): number {
+	return Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, terminalWidth - 4));
+}
+
+/**
+ * Whether a row's reason goes on its own line under the subject. The subject
+ * never wraps — it is what the user scans for — so a long one (several plugins
+ * sharing a reason) takes the line to itself and the reason goes beneath it,
+ * rather than being squeezed into a sliver beside it.
+ */
+export function reasonBelow(subject: string, innerWidth: number): boolean {
+	return MARK.length + subject.length + 2 > innerWidth / 2;
+}
+
+/** Lines `text` takes when word-wrapped at `width` columns. */
+function wrappedLines(text: string, width: number): number {
+	if (width <= 0) return text.length;
+	let lines = 1;
+	let used = 0;
+	for (const word of text.split(/\s+/).filter(Boolean)) {
+		const len = word.length;
+		if (used === 0) {
+			used = len;
+		} else if (used + 1 + len <= width) {
+			used += 1 + len;
+		} else {
+			lines++;
+			used = len;
+		}
+		while (used > width) {
+			lines++;
+			used -= width;
+		}
+	}
+	return lines;
+}
+
+/** Terminal rows one failure row takes at an inner width of `inner`. */
+function rowHeight(row: FailureRow, inner: number): number {
+	if (reasonBelow(row.subject, inner)) {
+		const column = inner - MARK.length;
+		return (
+			1 +
+			wrappedLines(row.reason, column) +
+			(row.fix ? wrappedLines(row.fix, column) : 0)
+		);
+	}
+	const column = inner - (MARK.length + row.subject.length + 2);
+	return (
+		wrappedLines(row.reason, column) +
+		(row.fix ? wrappedLines(row.fix, column) : 0)
+	);
+}
+
+/**
+ * The rows that fit a terminal `terminalHeight` rows tall, and how many did
+ * not. Without a height every row is drawn. A popup taller than the terminal
+ * would push its own headline and footer off screen, so it stops early and
+ * says `+N more` instead — and always shows at least one row.
+ */
+export function visibleFailureRows(
+	report: FailureReport,
+	terminalWidth: number,
+	terminalHeight?: number,
+): { rows: FailureRow[]; hidden: number } {
+	if (terminalHeight === undefined) return { rows: report.rows, hidden: 0 };
+	const inner = failureListWidth(terminalWidth) - CHROME;
+	const fixRows = report.fix ? 1 + wrappedLines(report.fix, inner) : 0;
+	const budget = terminalHeight - FIXED_ROWS - fixRows;
+	const total = report.rows.reduce(
+		(sum, row) => sum + rowHeight(row, inner),
+		0,
+	);
+	if (total <= budget) return { rows: report.rows, hidden: 0 };
+
+	// One row is kept back for the "+N more" line.
+	const rows: FailureRow[] = [];
+	let used = 0;
+	for (const row of report.rows) {
+		const height = rowHeight(row, inner);
+		if (rows.length > 0 && used + height > budget - 1) break;
+		rows.push(row);
+		used += height;
+	}
+	return { rows, hidden: report.rows.length - rows.length };
+}
+
+/**
+ * A row's reason and, when it has its own, its fix beneath it. A plain call,
+ * not a component, so the whole popup is one element tree.
+ */
+function reasonColumn(row: FailureRow) {
+	return (
+		<box flexDirection="column" flexGrow={1} flexShrink={1}>
+			<text fg={theme.colors.muted} wrapMode="word">
+				{row.reason}
+			</text>
+			{row.fix ? (
+				<text fg={theme.colors.text} wrapMode="word">
+					{row.fix}
+				</text>
+			) : null}
+		</box>
+	);
+}
+
+/**
+ * THE failure popup: what did not happen, counted; each thing that failed with
+ * why; and the one fix, when there is one. The shape is {@link FailureReport},
+ * built by a pure function per screen, so every failure reads the same way.
+ *
+ * Theme tokens only: the ✗ in danger, the subject in the text colour, the
+ * reason muted — the reason is the detail, the subject is what the user scans.
+ * A fix is in the text colour, under its row when only that row has it, or
+ * once under all of them. Reasons wrap; subjects do not. Given the terminal's
+ * height, it draws only the rows that fit and ends with `+N more`. Any key
+ * dismisses it (ModalContainer).
+ */
+export function FailureListModal({
+	report,
+	terminalWidth,
+	terminalHeight,
+}: {
+	report: FailureReport;
+	terminalWidth: number;
+	/** Cap the rows to this many terminal rows; every row is drawn without it. */
+	terminalHeight?: number;
+}) {
+	const width = failureListWidth(terminalWidth);
+	const inner = width - CHROME;
+	const { rows, hidden } = visibleFailureRows(
+		report,
+		terminalWidth,
+		terminalHeight,
+	);
+
+	return (
+		<box
+			flexDirection="column"
+			border
+			borderStyle="rounded"
+			borderColor={theme.colors.dim}
+			backgroundColor={theme.surface.bg}
+			paddingLeft={3}
+			paddingRight={3}
+			paddingTop={1}
+			paddingBottom={1}
+			width={width}
+		>
+			<box marginBottom={1}>
+				<text fg={theme.colors.text}>
+					<span fg={theme.colors.danger}>{MARK}</span>
+					<strong>{report.headline}</strong>
+				</text>
+			</box>
+
+			{/*
+			 * The index is part of the key: a report built with `group: false`
+			 * keeps rows apart even when subject and reason match, and a repeated
+			 * key makes React drop or reuse one of them.
+			 */}
+			{rows.map((row, index) =>
+				reasonBelow(row.subject, inner) ? (
+					<box
+						key={`${row.subject}:${row.reason}:${index}`}
+						flexDirection="column"
+					>
+						<text fg={theme.colors.text}>
+							<span fg={theme.colors.danger}>{MARK}</span>
+							<span fg={theme.colors.text}>{row.subject}</span>
+						</text>
+						<box paddingLeft={MARK.length}>{reasonColumn(row)}</box>
+					</box>
+				) : (
+					<box
+						key={`${row.subject}:${row.reason}:${index}`}
+						flexDirection="row"
+					>
+						<box flexShrink={0}>
+							<text fg={theme.colors.text}>
+								<span fg={theme.colors.danger}>{MARK}</span>
+								<span fg={theme.colors.text}>{`${row.subject}  `}</span>
+							</text>
+						</box>
+						{reasonColumn(row)}
+					</box>
+				),
+			)}
+
+			{hidden > 0 ? (
+				<box paddingLeft={MARK.length}>
+					<text fg={theme.colors.muted}>{`+${hidden} more`}</text>
+				</box>
+			) : null}
+
+			{report.fix ? (
+				<box marginTop={1}>
+					<text fg={theme.colors.text} wrapMode="word">
+						{report.fix}
+					</text>
+				</box>
+			) : null}
+
+			<box marginTop={1}>
+				<text fg={theme.colors.muted}>Press any key to continue</text>
+			</box>
+		</box>
+	);
+}
+
+export default FailureListModal;

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

@@ -6,19 +6,14 @@ interface MessageModalProps {
 	title: string;
 	/** Modal message */
 	message: string;
-	/** Message variant */
-	variant: "info" | "error";
 }
 
-const variantConfig = {
-	info: { icon: "ℹ", color: theme.colors.info },
-	error: { icon: "✗", color: theme.colors.danger },
-} as const;
-
-/** Draws the message. Any key dismisses it — ModalContainer handles that. */
-export function MessageModal({ title, message, variant }: MessageModalProps) {
-	const config = variantConfig[variant];
-
+/**
+ * Draws information to read: help text, a command to run. Never a failure —
+ * those go in `FailureListModal`. Any key dismisses it — ModalContainer
+ * handles that.
+ */
+export function MessageModal({ title, message }: MessageModalProps) {
 	return (
 		<box
 			flexDirection="column"
@@ -33,7 +28,7 @@ export function MessageModal({ title, message, variant }: MessageModalProps) {
 			width={60}
 		>
 			<box marginBottom={1}>
-				<text fg={config.color}>{config.icon} </text>
+				<text fg={theme.colors.info}>ℹ </text>
 				<text fg={theme.colors.text}>
 					<strong>{title}</strong>
 				</text>

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

@@ -5,6 +5,7 @@ import { type KeyPress, isScrollKey } from "../../input/key-dispatch.js";
 import { useApp, useModal } from "../../state/AppContext.js";
 import { useDimensions } from "../../state/DimensionsContext.js";
 import { ConfirmModal } from "./ConfirmModal.js";
+import { FailureListModal } from "./FailureListModal.js";
 import { HelpOverlay, helpOverlaySize } from "./HelpOverlay.js";
 import { InputModal } from "./InputModal.js";
 import { LoadingModal } from "./LoadingModal.js";
@@ -37,7 +38,7 @@ const isPlain = (key: KeyPress) => !key.ctrl && !key.meta;
  *            Only an <input> that was ALREADY focused when the key arrived:
  *            the Enter that opens an input modal from a select never reaches
  *            it (KeyRouter's `dispatchThenGuardFocus`).
- * - message: any key dismisses.
+ * - message, failures: any key dismisses.
  * - loading: keys are swallowed until the work finishes.
  * - help:    ↑↓ / PgUp / PgDn / Ctrl+U / Ctrl+D scroll; Esc or `?` close.
  */
@@ -102,6 +103,7 @@ export function ModalContainer() {
 				break;
 
 			case "message":
+			case "failures":
 				modal.onDismiss();
 				break;
 
@@ -174,11 +176,14 @@ export function ModalContainer() {
 				);
 
 			case "message":
+				return <MessageModal title={modal.title} message={modal.message} />;
+
+			case "failures":
 				return (
-					<MessageModal
-						title={modal.title}
-						message={modal.message}
-						variant={modal.variant}
+					<FailureListModal
+						report={modal.report}
+						terminalWidth={dimensions.terminalWidth}
+						terminalHeight={dimensions.terminalHeight}
 					/>
 				);
 

package/src/ui/components/modals/index.ts

@@ -2,5 +2,6 @@ export { ConfirmModal } from "./ConfirmModal.js";
 export { InputModal } from "./InputModal.js";
 export { SelectModal } from "./SelectModal.js";
 export { MessageModal } from "./MessageModal.js";
+export { FailureListModal } from "./FailureListModal.js";
 export { LoadingModal } from "./LoadingModal.js";
 export { ModalContainer } from "./ModalContainer.js";

package/src/ui/hooks/startupQueue.ts

@@ -0,0 +1,56 @@
+/**
+ * What the app shows next at startup, when the modal slot is free — the ONE
+ * order every startup popup and question is asked in. Pure, so the order is
+ * tested without mounting the app; `App.tsx`'s startup effect acts on it.
+ *
+ * The order:
+ *
+ *  1. Failure reports, oldest first. A failure is something that already
+ *     happened, and the question after it may be answered differently once
+ *     it is known — so the profile gate's refusals, queued in the same tick as
+ *     the profile question, are read BEFORE it and never replace it.
+ *  2. The gitignore question, once no newer check is pending.
+ *  3. The broken-plugins question.
+ *  4. The profile question — last, and asked again whenever the slot is free
+ *     and it has not been answered (it cannot be dismissed).
+ *
+ * Nothing is shown while any modal is open: two needs arriving in one commit
+ * would otherwise both see an empty slot, and the later would replace the
+ * earlier after its need was cleared.
+ */
+
+import type { FailureReport } from "../state/types.js";
+
+export interface StartupQueueState<ProfileNeed> {
+	/** A modal (any modal) is on screen. */
+	modalOpen: boolean;
+	/** Failure reports not yet shown, oldest first. */
+	reports: readonly FailureReport[];
+	/** A gitignore answer is waiting and no newer check is running. */
+	gitignoreReady: boolean;
+	/** Plugins found loading an older version than installed, or null. */
+	brokenCount: number | null;
+	/** The unanswered profile question, or null. */
+	profileNeed: ProfileNeed | null;
+}
+
+export type StartupStep<ProfileNeed> =
+	| { kind: "report"; report: FailureReport; rest: FailureReport[] }
+	| { kind: "gitignore" }
+	| { kind: "stale-load"; brokenCount: number }
+	| { kind: "profile"; need: ProfileNeed }
+	| null;
+
+export function nextStartupStep<ProfileNeed>(
+	s: StartupQueueState<ProfileNeed>,
+): StartupStep<ProfileNeed> {
+	if (s.modalOpen) return null;
+	const [report, ...rest] = s.reports;
+	if (report) return { kind: "report", report, rest };
+	if (s.gitignoreReady) return { kind: "gitignore" };
+	if (s.brokenCount !== null) {
+		return { kind: "stale-load", brokenCount: s.brokenCount };
+	}
+	if (s.profileNeed !== null) return { kind: "profile", need: s.profileNeed };
+	return null;
+}