magus-cli 7.3.0 → 7.4.0

package/src/ui/components/primitives/ErrorNotice.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { theme } from "../../theme.js";
+
+interface ErrorNoticeProps {
+	/** What could not be done, in words: "Could not read the MCP configuration." */
+	title: string;
+	/**
+	 * The error's own message. Shown verbatim, because for a settings file that
+	 * does not parse it is the message that names the file — a summary here
+	 * would drop the one fact the reader needs to fix it.
+	 */
+	detail: string;
+	/** Optional next step, e.g. "Fix the file, then press r." */
+	hint?: string;
+}
+
+/**
+ * A failure shown in place of content that could not be loaded.
+ *
+ * It exists so a failed read never renders as an empty list: an empty list
+ * says "nothing is configured", which for a settings file that merely failed
+ * to parse is false and invites the user to configure it again.
+ */
+export function ErrorNotice({ title, detail, hint }: ErrorNoticeProps) {
+	return (
+		<box flexDirection="column" paddingLeft={2} paddingRight={2}>
+			<text fg={theme.colors.danger}>{title}</text>
+			<box marginTop={1}>
+				<text fg={theme.colors.muted}>{detail}</text>
+			</box>
+			{hint && (
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>{hint}</text>
+				</box>
+			)}
+		</box>
+	);
+}

package/src/ui/components/primitives/ListCategoryRow.tsx

@@ -1,13 +1,14 @@
 import React from "react";
-import { theme } from "../../theme.js";
-import { SelectableRow } from "./SelectableRow.js";
+import { type BadgeTone, theme } from "../../theme.js";
+import { SelectableRow, rowLead } from "./SelectableRow.js";
 
 interface ListCategoryRowProps {
 	title: string;
 	expanded?: boolean;
 	count?: number;
 	badge?: string;
-	tone?: keyof typeof theme.category;
+	/** What the group is. `neutral` unless its name is a state — see `theme.badge`. */
+	tone?: BadgeTone;
 	selected: boolean;
 	/**
 	 * Whether the row can be opened and closed. Default true, which is what
@@ -23,22 +24,32 @@ export function ListCategoryRow({
 	expanded = false,
 	count,
 	badge,
-	tone = "gray",
+	tone = "neutral",
 	selected,
 	expandable = true,
 }: ListCategoryRowProps) {
-	const colors = theme.category[tone];
+	const colors = theme.badge[tone];
 	const marker = expandable ? (expanded ? "▼ " : "▶ ") : "";
 	const label = `${marker}${title}${count !== undefined ? ` (${count})` : ""}`;
 
+	// Both forms start with the row's lead cell — a blank inside the chip, the
+	// selection mark on the cursor — so the title never moves as it is selected.
 	return (
 		<SelectableRow selected={selected}>
 			{!selected && (
 				<span bg={colors.bg} fg={colors.fg}>
-					<strong> {label} </strong>
+					<strong>
+						{rowLead(false)}
+						{label}{" "}
+					</strong>
 				</span>
 			)}
-			{selected && <strong> {label} </strong>}
+			{selected && (
+				<strong>
+					{rowLead(true)}
+					{label}{" "}
+				</strong>
+			)}
 			{!selected && badge ? <span fg={colors.badgeFg}> {badge}</span> : null}
 		</SelectableRow>
 	);

package/src/ui/components/primitives/MetaText.tsx

@@ -3,7 +3,7 @@ import { theme } from "../../theme.js";
 
 interface MetaTextProps {
 	text: string;
-	tone?: "muted" | "warning" | "success" | "danger";
+	tone?: keyof typeof theme.meta;
 	/**
 	 * True when this sits inside a SELECTED row. Not cosmetic.
 	 *

package/src/ui/components/primitives/ScopeDetail.tsx

@@ -19,49 +19,54 @@ interface ScopeDetailProps {
 }
 
 /**
- * The u/p/l badges used in detail panels.
- * Renders each scope as: [bg=color] key [/bg] ● or ○ Label path
+ * The u/p/l lines used in detail panels:
+ * `[key] ● Label path` — the key chip, installed or not, the scope's name.
+ *
+ * The key chip is neutral: it names a key to press, which is chrome. The scopes
+ * no longer own a hue each (see theme.ts), so the dot carries the state — `●`
+ * in `success` when installed, `○` in `muted` when not — and the words carry
+ * which scope it is.
  */
 export function ScopeDetail({ scopes, paths }: ScopeDetailProps) {
 	const items = [
-		{
-			key: "u",
-			label: "User",
-			color: theme.scopes.user,
-			active: scopes.user,
-			path: paths?.user,
-		},
+		{ key: "u", label: "User", active: scopes.user, path: paths?.user },
 		{
 			key: "p",
 			label: "Project",
-			color: theme.scopes.project,
 			active: scopes.project,
 			path: paths?.project,
 		},
-		{
-			key: "l",
-			label: "Local",
-			color: theme.scopes.local,
-			active: scopes.local,
-			path: paths?.local,
-		},
+		{ key: "l", label: "Local", active: scopes.local, path: paths?.local },
 	].filter((i) => i.path !== undefined || i.active !== undefined);
 
 	return (
 		<box flexDirection="column">
 			{items.map((item) => (
-				<text key={item.key}>
-					<span bg={item.color} fg={theme.hints.fg}>
-						{" "}
-						{item.key}{" "}
-					</span>
-					<span fg={item.active ? item.color : theme.colors.muted}>
-						{item.active ? " ● " : " ○ "}
-					</span>
-					<span fg={item.color}>{item.label}</span>
+				<text key={item.key} fg={theme.colors.text}>
+					<ScopeKeyChip scopeKey={item.key} />
+					<ScopeDot installed={!!item.active} />
+					<span fg={theme.colors.text}>{item.label}</span>
 					{item.path && <span fg={theme.colors.muted}> {item.path}</span>}
 				</text>
 			))}
 		</box>
 	);
 }
+
+/** ` u ` — the key that toggles a scope, as a neutral chip. Inside a `<text>`. */
+export function ScopeKeyChip({ scopeKey }: { scopeKey: string }) {
+	return (
+		<span bg={theme.colors.dim} fg={theme.hints.fg}>
+			{` ${scopeKey} `}
+		</span>
+	);
+}
+
+/** ` ● ` installed, ` ○ ` not. Inside a `<text>`. */
+export function ScopeDot({ installed }: { installed: boolean }) {
+	return (
+		<span fg={installed ? theme.colors.success : theme.colors.muted}>
+			{installed ? " ● " : " ○ "}
+		</span>
+	);
+}

package/src/ui/components/primitives/ScopeSquares.tsx

@@ -1,5 +1,4 @@
 import type React from "react";
-import { scopeOffFill } from "../../theme-mode.js";
 import { theme } from "../../theme.js";
 
 interface ScopeSquaresProps {
@@ -9,22 +8,26 @@ interface ScopeSquaresProps {
 	selected?: boolean;
 }
 
-/** Every segment is a filled block; only the fill colour says lit or unlit. */
-const SEGMENT = "■";
+/** Installed at that scope. */
+export const SCOPE_ON = "■";
+/** Not installed at that scope. */
+export const SCOPE_OFF = "□";
 
 /**
- * Scope bar: three positional segments, user / project / local.
+ * Scope bar: three positional squares, user / project / local.
  *
- * Reads as a segmented indicator — each segment lit in its scope colour, or
- * unlit in a fill that recedes toward the page. Position identifies the scope;
- * the first segment is always user, the second project, the third local.
+ * POSITION names the scope — the first square is always user, the second
+ * project, the third local — and SHAPE says the state: `■` installed, `□` not.
+ * That reads with no colour at all, which the bar never used to: every square
+ * was the same filled block, lit in a scope hue or unlit in a fill near the
+ * page, so on a monochrome terminal, to a colour-blind reader, or on a theme
+ * that drew two hues alike, all three states were one shape.
  *
- * The unlit fill used to be `theme.colors.muted` (#6B7280), the same mid-dark
- * grey as de-emphasised body text. Against a light page that reads as a *dark*
- * block, giving an unlit segment the same visual weight as a lit one — "non
- * installed state is dark as well - confusing". The unlit fill now comes from
- * `scopeOffFill()`, which steps toward the page the resolved mode names; see
- * theme-mode.ts for why that one value cannot be fixed.
+ * Colour now only repeats what the shape says. A filled square wears `success`
+ * (installed is what it means, on every screen); a hollow one wears `muted`,
+ * which a thin outline needs to stay visible — the shape, not a pale fill, is
+ * what makes it recede. On a selected row the selection owns the colour
+ * channel: filled squares take its ink, hollow ones its dim ink.
  */
 export function ScopeSquares({
 	user,
@@ -32,25 +35,17 @@ export function ScopeSquares({
 	local,
 	selected = false,
 }: ScopeSquaresProps) {
-	// On a selected row the background is our own accent, so an unlit segment
-	// recedes toward that block rather than toward the page.
-	const off = selected ? theme.selection.bg : scopeOffFill();
-	const lit = (on: boolean, color: string) =>
-		on ? (selected ? theme.selection.fg : color) : off;
-
-	const segments = [
-		lit(user, theme.scopes.user),
-		lit(project, theme.scopes.project),
-		...(local !== undefined ? [lit(local, theme.scopes.local)] : []),
-	];
+	const on = selected ? theme.selection.fg : theme.colors.success;
+	const off = selected ? theme.selection.dim : theme.colors.muted;
+	const states = [user, project, ...(local !== undefined ? [local] : [])];
 
 	// Fragments of <span> — safe to embed inside a coloured <text> parent.
 	return (
 		<>
-			{segments.map((fg, i) => (
-				// biome-ignore lint/suspicious/noArrayIndexKey: fixed positional segments
-				<span key={i} fg={fg}>
-					{SEGMENT}
+			{states.map((installed, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: fixed positional squares
+				<span key={i} fg={installed ? on : off}>
+					{installed ? SCOPE_ON : SCOPE_OFF}
 				</span>
 			))}
 		</>

package/src/ui/components/primitives/SelectableRow.tsx

@@ -1,8 +1,29 @@
 import type React from "react";
 import { theme } from "../../theme.js";
 
+/**
+ * The glyph a selected row starts with.
+ *
+ * The selection used to be a background fill and nothing else, so it vanished
+ * wherever colour does — a monochrome terminal, a screenshot pasted as text, a
+ * reader who cannot tell the fill from the page. A left-edge bar is the cursor
+ * in shape as well as in colour, and it takes the row's first cell, which every
+ * list row already leaves blank, so no name moves as the cursor passes.
+ */
+export const SELECTED_MARK = "▌";
+
+/** A list row's first cell: the selection mark, or the blank it replaces. */
+export function rowLead(selected: boolean): string {
+	return selected ? SELECTED_MARK : " ";
+}
+
 interface SelectableRowProps {
 	selected: boolean;
+	/**
+	 * Leading cells before the children. The first of them is the lead cell,
+	 * which carries `SELECTED_MARK` on the selected row. At 0 the children own
+	 * their first cell and must draw `rowLead` themselves.
+	 */
 	indent?: number;
 	children: React.ReactNode;
 }
@@ -12,6 +33,8 @@ export function SelectableRow({
 	indent = 0,
 	children,
 }: SelectableRowProps) {
+	const lead =
+		indent > 0 ? `${rowLead(selected)}${" ".repeat(indent - 1)}` : "";
 	return (
 		<text
 			// Unselected: no background, so the row sits on the terminal's own page.
@@ -23,7 +46,7 @@ export function SelectableRow({
 			// reached by omission rather than by a wrong literal.
 			fg={selected ? theme.selection.fg : theme.colors.text}
 		>
-			{" ".repeat(indent)}
+			{lead}
 			{children}
 		</text>
 	);

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

@@ -1,9 +1,10 @@
-export { SelectableRow } from "./SelectableRow.js";
+export { SELECTED_MARK, SelectableRow, rowLead } from "./SelectableRow.js";
 export { ListCategoryRow } from "./ListCategoryRow.js";
-export { ScopeSquares } from "./ScopeSquares.js";
-export { ScopeDetail } from "./ScopeDetail.js";
+export { SCOPE_OFF, SCOPE_ON, ScopeSquares } from "./ScopeSquares.js";
+export { ScopeDetail, ScopeDot, ScopeKeyChip } from "./ScopeDetail.js";
 export { ActionHints } from "./ActionHints.js";
 export type { Hint } from "./ActionHints.js";
 export { MetaText } from "./MetaText.js";
 export { KeyValueLine } from "./KeyValueLine.js";
 export { DetailSection } from "./DetailSection.js";
+export { ErrorNotice } from "./ErrorNotice.js";

package/src/ui/hooks/useProfileStartupModal.ts

@@ -16,6 +16,7 @@
  */
 
 import { useCallback } from "react";
+import { getManifestPath } from "../../services/manifest.js";
 import {
 	type ProfileChoice,
 	applyProfileChoice,
@@ -26,7 +27,9 @@ import {
 	defaultOptionIndex,
 	describeNeed,
 	parseProfileChoice,
+	unparseableNeed,
 } from "../../services/profile-startup.js";
+import { SettingsParseError } from "../../services/settings-file.js";
 import type { DisplacedArtifact } from "../../services/symlink-manager.js";
 import { useApp, useNavigation } from "../state/AppContext.js";
 import type { ModalState } from "../state/types.js";
@@ -207,6 +210,15 @@ export function useProfileStartupModal(onQuit: () => void) {
 						});
 					})
 					.catch((error: unknown) => {
+						// The manifest stopped parsing between launch and this answer —
+						// someone is mid-edit — and saving refused to write over it.
+						// Asking the same question again would offer that save again, so
+						// the question becomes the one for a file that does not parse.
+						const next =
+							error instanceof SettingsParseError &&
+							error.path === getManifestPath(projectPath)
+								? unparseableNeed(error)
+								: need;
 						dispatch({
 							type: "SHOW_MODAL",
 							modal: {
@@ -226,17 +238,17 @@ export function useProfileStartupModal(onQuit: () => void) {
 								// dismissing returns to the question — including when the
 								// attempt was automatic, which is the one case where there
 								// was no question on screen yet.
-								onDismiss: ask,
+								onDismiss: () => ask(next),
 							},
 						});
 					});
 			};
 
-			function ask(): void {
+			function ask(current: ProfileStartupNeed = need): void {
 				dispatch({
 					type: "SHOW_MODAL",
 					modal: buildProfileStartupModal({
-						need,
+						need: current,
 						onChoose: (choice) => apply(choice, false),
 						onQuit,
 					}),

package/src/ui/input/KeyRouter.tsx

@@ -0,0 +1,180 @@
+/**
+ * The one keyboard subscriber in the React tree.
+ *
+ * Components do not call `useKeyboard`. They register a LAYER — modal, input,
+ * screen, scroll or global — and this router offers each key to the live layers
+ * through `dispatchKey`, top first, so exactly one of them acts on it. The
+ * system layer (Ctrl+C) is not here: `src/tui.tsx` takes that key on the
+ * renderer before this subscriber runs and stops it there.
+ *
+ * Each key is dispatched inside `flushSync`, so everything a key changes is
+ * committed — and every layer's `active` flag and handler refreshed — before the
+ * next key is looked at. A paste or a fast typist delivers several keys in one
+ * stdin read; without this, `/abc` would open the search box and then send `a`,
+ * `b` and `c` to the screen underneath, whose handlers still believed the box
+ * was closed.
+ */
+
+import { appendFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { KeyEvent } from "@opentui/core";
+import { flushSync, useKeyboard } from "@opentui/react";
+import {
+	type ReactNode,
+	createContext,
+	useContext,
+	useLayoutEffect,
+	useState,
+} from "react";
+import {
+	SCREEN_BINDINGS,
+	type ScreenHandlers,
+	runBindings,
+} from "../keymap.js";
+import type { Screen } from "../state/types.js";
+import {
+	type KeyLayer,
+	type KeyLayerId,
+	type KeyPress,
+	dispatchKey,
+	inputLayerConsumes,
+	typedCharacter,
+} from "./key-dispatch.js";
+
+const LayersContext = createContext<Set<KeyLayer> | null>(null);
+
+/** OpenTUI's key event, reduced to the fields the dispatcher reads. */
+export function toKeyPress(event: KeyEvent): KeyPress {
+	return {
+		name: event.name ?? "",
+		sequence: event.sequence ?? "",
+		ctrl: event.ctrl === true,
+		meta: event.meta === true,
+		shift: event.shift === true,
+	};
+}
+
+/**
+ * `MAGUS_DEBUG_KEYS=1` appends every key and the layer that took it to
+ * `magus-keys.log` in the temp directory — the first thing to look at when a
+ * key "does nothing".
+ */
+function logKey(key: KeyPress, consumer: KeyLayerId | null): void {
+	if (process.env.MAGUS_DEBUG_KEYS !== "1") return;
+	try {
+		appendFileSync(
+			path.join(os.tmpdir(), "magus-keys.log"),
+			`${new Date().toISOString()} name=${JSON.stringify(key.name)} seq=${JSON.stringify(key.sequence)} ctrl=${key.ctrl} meta=${key.meta} shift=${key.shift} -> ${consumer ?? "nobody"}\n`,
+		);
+	} catch {
+		// Best-effort logging: never let it break a keypress.
+	}
+}
+
+export function KeyRouter({ children }: { children: ReactNode }) {
+	const [layers] = useState(() => new Set<KeyLayer>());
+
+	useKeyboard((event) => {
+		const key = toKeyPress(event);
+		let consumer: KeyLayerId | null = null;
+		flushSync(() => {
+			consumer = dispatchKey([...layers], key);
+		});
+		logKey(key, consumer);
+	});
+
+	return (
+		<LayersContext.Provider value={layers}>{children}</LayersContext.Provider>
+	);
+}
+
+/**
+ * Register a key layer for as long as the calling component is mounted.
+ *
+ * `active` and `handle` are refreshed on every commit, so the router always
+ * calls the handler from the latest render — never a stale closure.
+ */
+export function useKeyLayer(
+	id: KeyLayerId,
+	active: boolean,
+	handle: (key: KeyPress) => boolean,
+): void {
+	const layers = useContext(LayersContext);
+	if (!layers) throw new Error("useKeyLayer needs a <KeyRouter> above it");
+	const [entry] = useState<KeyLayer>(() => ({ id, active, handle }));
+
+	useLayoutEffect(() => {
+		entry.id = id;
+		entry.active = active;
+		entry.handle = handle;
+	});
+
+	useLayoutEffect(() => {
+		layers.add(entry);
+		return () => {
+			layers.delete(entry);
+		};
+	}, [layers, entry]);
+}
+
+/**
+ * The screen layer: one handler per binding the keymap declares for `screen`.
+ * `active: false` stands the layer down without unmounting it.
+ */
+export function useScreenKeys<S extends Screen>(
+	screen: S,
+	handlers: ScreenHandlers<S>,
+	active = true,
+): void {
+	useKeyLayer("screen", active, (key) =>
+		runBindings(SCREEN_BINDINGS[screen], handlers, key),
+	);
+}
+
+/** A screen's search box, as the input layer drives it. */
+export interface SearchBox {
+	/** The box has focus: what the user types goes into it. */
+	focused: boolean;
+	query: string;
+	/** Add one typed character. */
+	append(char: string): void;
+	/** Delete the last character. */
+	erase(): void;
+	/** Empty the box and stay in it. */
+	clear(): void;
+	/** Leave the box. The filter stays as typed. */
+	blur(): void;
+}
+
+/**
+ * The input layer for a search box.
+ *
+ * While focused it takes every printable key — digits, `j`, `k`, `q`, `?` and
+ * space are typed, not acted on — plus Backspace, Enter (keep the filter, leave
+ * the box) and Esc (clear the text; on an empty box, leave). Up/Down, Tab and the
+ * scroll keys pass through: the list still moves, tabs still cycle, the panel
+ * still scrolls.
+ */
+export function useSearchInput(box: SearchBox): void {
+	useKeyLayer("input", box.focused, (key) => {
+		if (!inputLayerConsumes(key)) return false;
+		switch (key.name) {
+			case "return":
+			case "enter":
+				box.blur();
+				return true;
+			case "escape":
+				if (box.query.length > 0) box.clear();
+				else box.blur();
+				return true;
+			case "backspace":
+			case "delete":
+				box.erase();
+				return true;
+		}
+		const char = typedCharacter(key);
+		if (char !== null) box.append(char);
+		return true;
+	});
+}