magus-cli 7.3.0 → 7.4.0

package/src/tui.tsx

@@ -10,6 +10,7 @@
 import { RGBA, type ThemeMode, createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { App } from "./ui/App.js";
+import { installShutdown } from "./ui/runtime/shutdown.js";
 import { setThemeMode } from "./ui/theme-mode.js";
 import { type ThemeEnv, resolveTheme } from "./ui/theme-resolve.js";
 
@@ -57,6 +58,49 @@ export async function startTui({
 		backgroundColor: RGBA.defaultBackground(),
 		useMouse: true,
 		enableMouseMovement: false,
+		// BOTH, so the renderer registers no signal handler and never quits on
+		// Ctrl+C by itself: `installShutdown` below is the ONE teardown owner.
+		// Left at their defaults the renderer is a second owner — it destroys
+		// itself first on a signal and the React tree is torn down after the
+		// terminal was already restored (measured; see ui/runtime/shutdown.ts).
+		exitSignals: [],
+		exitOnCtrlC: false,
+		// OFF, so a click never gives a renderable keyboard focus. With it on, one
+		// click in a scrollbox made that box a second key receiver: OpenTUI hands
+		// every key to the focused element as well as to the KeyRouter, so arrows
+		// and PgUp/PgDn acted twice (measured on the test renderer: scrollTop 0 → 2
+		// after a click, 0 → 0 with this off). The router is the one key owner;
+		// InputModal focuses its own <input>, which is the only focus magus needs.
+		autoFocus: false,
+	});
+
+	// Wired immediately, before anything that can wait: theme resolution below
+	// can probe the terminal for 250ms, and a signal or a throw landing in that
+	// window must restore the terminal too.
+	//
+	// SIGINT/SIGTERM/SIGHUP/… restore the terminal and exit 128 + signum; an
+	// uncaught exception or unhandled rejection restores it, prints the error,
+	// and exits 1. `shutdown(0)` is the clean quit.
+	const root = createRoot(renderer);
+	const shutdown = installShutdown(renderer, root);
+	const quit = (): void => {
+		void shutdown(0);
+	};
+
+	// Ctrl+C is a KEYPRESS here, not a signal: raw mode clears ISIG, so the tty
+	// delivers 0x03 and SIGINT is never raised. Without this listener
+	// (`exitOnCtrlC: false` above) Ctrl+C would do nothing at all.
+	//
+	// It is registered on the renderer before React mounts, so it runs ahead of
+	// every `useKeyboard` handler — and stopping propagation means no screen or
+	// modal ever sees the key. That is what makes Ctrl+C quit from under any
+	// modal, including the undismissable profile gate, and from a screen whose
+	// render crashed.
+	renderer.keyInput.on("keypress", (key) => {
+		if (key.ctrl && key.name === "c") {
+			key.stopPropagation();
+			quit();
+		}
 	});
 
 	// Mouse selection → system clipboard, on release. OSC 52 survives SSH;
@@ -86,27 +130,10 @@ export async function startTui({
 	});
 	setThemeMode(mode);
 
-	const root = createRoot(renderer);
-
-	// Cleanup function to restore terminal
-	const cleanup = () => {
-		root.unmount();
-		renderer.destroy(); // CRITICAL: Never use process.exit() directly
-	};
-
-	// Handle cleanup on exit signals
-	const handleExit = () => {
-		cleanup();
-		// Exit after cleanup completes
-		process.exit(0);
-	};
-
-	process.on("SIGINT", handleExit);
-	process.on("SIGTERM", handleExit);
-
-	// Render the OpenTUI app with exit handler
-	root.render(<App onExit={handleExit} />);
+	// `q`, Escape on the home tab and the profile gate's quit all end here.
+	root.render(<App onExit={quit} />);
 
-	// Wait indefinitely (app runs until user exits)
+	// Wait indefinitely: every exit goes through `shutdown`, which ends the
+	// process itself.
 	await new Promise(() => {});
 }

package/src/ui/App.tsx

@@ -1,5 +1,3 @@
-import fs from "node:fs";
-import { useRenderer } from "@opentui/react";
 import React, { useEffect, useState } from "react";
 import { activePluginPins } from "../services/active-closure.js";
 import { isClaudeAvailable } from "../services/claude-cli.js";
@@ -26,15 +24,18 @@ import {
 	checkForUpdates,
 	getCurrentVersion,
 } from "../services/version-check.js";
+import { ScreenErrorBoundary } from "./components/ScreenErrorBoundary.js";
+import { TABS } from "./components/TabBar.js";
 import { ProgressBar } from "./components/layout/ProgressBar.js";
 import { ModalContainer } from "./components/modals/index.js";
 import { useGitignoreModal } from "./hooks/useGitignoreModal.js";
-import { useKeyboardHandler } from "./hooks/useKeyboardHandler.js";
 import { useProfileStartupModal } from "./hooks/useProfileStartupModal.js";
 import {
 	staleLoadRepairSummary,
 	useStaleLoadModal,
 } from "./hooks/useStaleLoadModal.js";
+import { KeyRouter, useKeyLayer } from "./input/KeyRouter.js";
+import { type GlobalHandlers, runGlobalBindings } from "./keymap.js";
 import {
 	AliasScreen,
 	CliToolsScreen,
@@ -65,13 +66,22 @@ export const VERSION = getCurrentVersion();
 
 /**
  * Router Component
- * Renders the current screen based on route
+ * Renders the current screen based on route, inside a boundary that confines a
+ * render error to that screen — see ScreenErrorBoundary.
  */
 function Router() {
 	const { state } = useApp();
-	const { currentRoute } = state;
+	const { screen } = state.currentRoute;
 
-	switch (currentRoute.screen) {
+	return (
+		<ScreenErrorBoundary screen={screen}>
+			<RouteScreen screen={screen} />
+		</ScreenErrorBoundary>
+	);
+}
+
+function RouteScreen({ screen }: { screen: Screen }) {
+	switch (screen) {
 		case "plugins":
 			return <PluginsScreen />;
 		case "mcp":
@@ -100,181 +110,47 @@ function Router() {
 }
 
 /**
- * GlobalKeyHandler Component
- * Handles global keyboard shortcuts (1-8, Tab, Escape, q, Ctrl+C, ?, Shift+D)
- * Does not render anything (returns null)
+ * GlobalKeys Component
+ * The GLOBAL key layer — the lowest one: tab digits, Tab / Shift+Tab, `q`,
+ * `?` and Esc, from `GLOBAL_BINDINGS` in ui/keymap.ts. It only ever sees a key
+ * that the modal, a focused search box, the screen and the panel scroll all
+ * declined, so a digit typed into a search box never switches tab and an Esc
+ * that cleared a filter never also quits.
+ *
+ * Ctrl+C is NOT here. It is owned by the bootstrap (src/tui.tsx), which
+ * catches it on the renderer before any React handler, stops its propagation
+ * and runs the one shutdown routine — so it quits from any screen, from under
+ * any modal (the profile gate cannot be dismissed), and even after a render
+ * error has taken the React tree down.
  */
-function GlobalKeyHandler({
-	onDebugToggle,
-	onExit,
-}: { onDebugToggle: () => void; onExit: () => void }): null {
+function GlobalKeys({ onExit }: { onExit: () => void }): null {
 	const { state } = useApp();
 	const { navigateToScreen } = useNavigation();
 	const modal = useModal();
-	const renderer = useRenderer();
-
-	useKeyboardHandler((input, key) => {
-		// Debug key (Shift+D) - always available
-		if (input === "D" && key.shift) {
-			onDebugToggle();
-			// Write debug info to file
-			const debugInfo = {
-				timestamp: new Date().toISOString(),
-				terminal: { rows: renderer.height, columns: renderer.width },
-				state: {
-					currentRoute: state.currentRoute,
-					isSearching: state.isSearching,
-					modal: state.modal ? { type: state.modal.type } : null,
-					plugins: {
-						scope: state.plugins.scope,
-						selectedIndex: state.plugins.selectedIndex,
-						searchQuery: state.plugins.searchQuery,
-						marketplacesStatus: state.plugins.marketplaces.status,
-						pluginsStatus: state.plugins.plugins.status,
-					},
-				},
-			};
-			fs.writeFileSync(
-				"/tmp/magus-debug.json",
-				JSON.stringify(debugInfo, null, 2),
-			);
-			return;
-		}
-
-		// Ctrl+C quits from ANYWHERE, including from under an open modal, and is
-		// checked before the guard below rather than beside `q` further down.
-		//
-		// Every modal used to be dismissable, so Escape-then-Ctrl+C always worked
-		// and this ordering never mattered. The profile gate cannot be dismissed —
-		// by design, since there is nothing to carry on to — which left Ctrl+C
-		// swallowed by the guard and no interrupt at all. A terminal app that
-		// ignores Ctrl+C is indistinguishable from one that has hung.
-		//
-		// `q` deliberately does NOT get the same treatment: a modal may want it
-		// (the select list's own cancel), and it is a printable character an input
-		// modal has to receive.
-		if (key.ctrl && input === "c") {
-			onExit();
-			return;
-		}
-
-		// Don't handle keys when modal is open or searching
-		if (state.modal || state.isSearching) return;
-
-		// Global navigation shortcuts (1-9, then 0) - include mcp-registry as it's
-		// a sub-screen of mcp
-		const isTopLevel = [
-			"plugins",
-			"mcp",
-			"mcp-registry",
-			"settings",
-			"cli-tools",
-			"profiles",
-			"skills",
-			"styles",
-			"gitignore",
-			"alias",
-			"models",
-		].includes(state.currentRoute.screen);
-
-		if (isTopLevel) {
-			if (input === "1") navigateToScreen("plugins");
-			else if (input === "2") navigateToScreen("skills");
-			else if (input === "3") navigateToScreen("mcp");
-			else if (input === "4") navigateToScreen("settings");
-			else if (input === "5") navigateToScreen("profiles");
-			else if (input === "6") navigateToScreen("cli-tools");
-			else if (input === "7") navigateToScreen("gitignore");
-			else if (input === "8") navigateToScreen("alias");
-			else if (input === "9") navigateToScreen("styles");
-			else if (input === "0") navigateToScreen("models");
-
-			// Tab navigation cycling
-			if (key.tab) {
-				const screens: Screen[] = [
-					"plugins",
-					"skills",
-					"mcp",
-					"settings",
-					"profiles",
-					"cli-tools",
-					"gitignore",
-					"alias",
-					"styles",
-					"models",
-				];
-				const currentIndex = screens.indexOf(
-					state.currentRoute.screen as Screen,
-				);
-				if (currentIndex !== -1) {
-					const nextIndex = key.shift
-						? (currentIndex - 1 + screens.length) % screens.length
-						: (currentIndex + 1) % screens.length;
-					navigateToScreen(screens[nextIndex]);
-				}
-			}
-		}
-
-		// q or Ctrl+C quits from anywhere — no need to bounce to home first.
-		if (input === "q" || (key.ctrl && input === "c")) {
-			onExit();
-			return;
-		}
-
-		// Escape goes back: registry → mcp, any other tab → plugins home,
-		// already-home → exit. But when a screen has a focused sub-view open
-		// (e.g. the Alias flag-detail editor), that sub-view owns Escape and
-		// backs out to itself — don't let the global handler jump to home.
-		// Scoped to the Escape branch ONLY so q/Ctrl+C still quit from anywhere.
-		if (key.escape) {
-			if (state.detailActive) return;
-			if (state.currentRoute.screen === "plugins") {
-				onExit();
-			} else if (state.currentRoute.screen === "mcp-registry") {
-				navigateToScreen("mcp");
-			} else {
-				navigateToScreen("plugins");
-			}
-		}
-
-		// ? for help
-		if (input === "?") {
-			modal.message(
-				"magus Help",
-				`Navigation
-  ↑/↓ or j/k    Move selection
-  Enter         Select / Toggle
-  Escape        Back (to home)
-  q / Ctrl+C    Quit (from anywhere)
-  ?             This help
-
-Quick Navigation
-  1  Plugins      4  Settings    7  Git State   0  Models
-  2  Skills       5  Profiles    8  Alias
-  3  MCP Servers  6  CLI Tools   9  Styles
-
-Plugin Actions
-  u  Update        d  Uninstall
-  a  Update All    r  Refresh
-
-MCP Servers
-  /  Search local + remote
-  r  Browse MCP registry
-
-Styles
-  Space  Tick / untick a style
-  a      Apply the selection to this project
-  x      Reset the selection to what is live
-  c      Clear the active output style
-
-Models
-  a / Enter  Route this project through the selected preset
-  c          Turn model tiers off
-  r          Re-read the config`,
-				"info",
-			);
-		}
-	});
+	const screen = state.currentRoute.screen;
+
+	const handlers: GlobalHandlers = {
+		help: () => modal.help(screen),
+		quit: () => onExit(),
+		"cycle-tab": (key) => {
+			// The registry is a sub-screen of MCP, so it cycles from MCP's place.
+			const from = screen === "mcp-registry" ? "mcp" : screen;
+			const index = TABS.findIndex((tab) => tab.screen === from);
+			if (index === -1) return;
+			const step = key.shift ? TABS.length - 1 : 1;
+			const next = TABS[(index + step) % TABS.length];
+			if (next) navigateToScreen(next.screen);
+		},
+		// Back: registry → MCP, any other tab → Plugins, Plugins → quit.
+		back: () => {
+			if (screen === "plugins") onExit();
+			else if (screen === "mcp-registry") navigateToScreen("mcp");
+			else navigateToScreen("plugins");
+		},
+		tab: (target) => navigateToScreen(target),
+	};
+
+	useKeyLayer("global", true, (key) => runGlobalBindings(handlers, key));
 
 	return null;
 }
@@ -287,7 +163,7 @@ function UpdateBanner({ result }: { result: VersionCheckResult }) {
 	if (!result.updateAvailable) return null;
 
 	return (
-		<box paddingLeft={1} paddingRight={1}>
+		<box flexDirection="row" paddingLeft={1} paddingRight={1}>
 			<text bg={theme.colors.warning} fg={theme.hints.fg}>
 				<strong> UPDATE </strong>
 			</text>
@@ -326,16 +202,12 @@ function ProgressIndicator({
  * Main app layout with all UI elements
  */
 interface AppContentInnerProps {
-	showDebug: boolean;
-	onDebugToggle: () => void;
 	updateInfo: VersionCheckResult | null;
 	onExit: () => void;
 	recoveryReport: string | null;
 }
 
 function AppContentInner({
-	showDebug,
-	onDebugToggle,
 	updateInfo,
 	onExit,
 	recoveryReport,
@@ -352,15 +224,6 @@ function AppContentInner({
 					<text fg={theme.colors.success}>✓ Fixed: {recoveryReport}</text>
 				</box>
 			)}
-			{showDebug && (
-				<box paddingLeft={1} paddingRight={1}>
-					<text fg={theme.colors.muted}>
-						DEBUG: {dimensions.terminalWidth}x{dimensions.terminalHeight} |
-						content={dimensions.contentHeight} | screen=
-						{state.currentRoute.screen}
-					</text>
-				</box>
-			)}
 			{progress && <ProgressIndicator {...progress} />}
 			<box
 				flexDirection="column"
@@ -370,7 +233,7 @@ function AppContentInner({
 			>
 				<Router />
 			</box>
-			<GlobalKeyHandler onDebugToggle={onDebugToggle} onExit={onExit} />
+			<GlobalKeys onExit={onExit} />
 			<ModalContainer />
 		</box>
 	);
@@ -387,7 +250,6 @@ interface AppContentProps {
 function AppContent({ onExit }: AppContentProps) {
 	const { state, dispatch } = useApp();
 	const { progress } = state;
-	const [showDebug, setShowDebug] = useState(false);
 	const [updateInfo, setUpdateInfo] = useState<VersionCheckResult | null>(null);
 	const [recoveryReport, setRecoveryReport] = useState<string | null>(null);
 	const [gitignoreData, setGitignoreData] = useState<{
@@ -623,13 +485,10 @@ function AppContent({ onExit }: AppContentProps) {
 	return (
 		<DimensionsProvider
 			showProgress={!!progress}
-			showDebug={showDebug}
 			showUpdateBanner={!!updateInfo?.updateAvailable}
 			transientBannerCount={transientBannerCount}
 		>
 			<AppContentInner
-				showDebug={showDebug}
-				onDebugToggle={() => setShowDebug((s) => !s)}
 				updateInfo={updateInfo}
 				onExit={onExit}
 				recoveryReport={recoveryReport}
@@ -650,7 +509,9 @@ interface AppProps {
 export function App({ onExit }: AppProps) {
 	return (
 		<AppProvider>
-			<AppContent onExit={onExit} />
+			<KeyRouter>
+				<AppContent onExit={onExit} />
+			</KeyRouter>
 		</AppProvider>
 	);
 }

package/src/ui/adapters/cliToolsAdapter.ts

@@ -8,9 +8,11 @@
  * `classifyTool(spec, facts)`, and for a tool the active profile declares the
  * spec IS the profile's (`specForCatalogTool`), so the two cannot differ.
  *
- * The same goes for the COMMANDS: a declared tool's row builds them with
- * `binCommandForState`, the rule `magus update`'s apply path uses, so the
- * row's target and the row's key can never aim at different versions.
+ * The same goes for the COMMANDS: the probe's own `upgradeCommand` when it
+ * built one (an npm prefix, Claude Code's updater) — the very argv `magus
+ * update` carries on its plan item — and otherwise `binCommandForState`, the
+ * rule the apply path uses, so the row's target and the row's key can never
+ * aim at different versions.
  *
  * Pure: no IO, no React. The screen gathers facts; this only assembles.
  */
@@ -23,6 +25,7 @@ import {
 import {
 	type InstallInfo,
 	type ToolFacts,
+	type ToolReason,
 	type ToolStatus,
 	classifyTool,
 } from "../../services/tool-probe.js";
@@ -80,7 +83,13 @@ export function buildToolRow(
 	const base = { tool, spec, installCommand, ...(install ? { install } : {}) };
 	if (!facts) return { ...base, checking: true, status: null };
 	const status = classifyTool(spec, facts);
-	const updateCommand = updateCommandFor(tool, declared, status, install);
+	const updateCommand = updateCommandFor(
+		tool,
+		declared,
+		status,
+		facts,
+		install,
+	);
 	return {
 		...base,
 		checking: false,
@@ -92,11 +101,16 @@ export function buildToolRow(
 /**
  * The command the row's key runs, from the same rule as the row's state.
  *
- * A declared tool goes through `binCommandForState` — the CLI apply path's own
- * builder over the PROFILE's requirement — so a row whose target is the pin
- * installs the pin. Building `@latest` here (what this used to do, always) let
- * the TUI overshoot a pin the CLI hits exactly, and the tool then classified
- * `unknown / ahead-of-pin` for good: magus never downgrades.
+ * First the probe's own `upgradeCommand`: set when the file PATH runs belongs
+ * to an owner the spec's installer would miss — another npm prefix, Claude
+ * Code's native installer — and already aimed at the pin when there is one.
+ * `magus update` runs the same value, so Enter and the CLI cannot differ.
+ *
+ * Otherwise a declared tool goes through `binCommandForState` — the CLI apply
+ * path's own builder over the PROFILE's requirement — so a row whose target is
+ * the pin installs the pin. Building `@latest` here (what this used to do,
+ * always) let the TUI overshoot a pin the CLI hits exactly, and the tool then
+ * classified `unknown / ahead-of-pin` for good: magus never downgrades.
  *
  * An undeclared catalogue tool keeps the screen's own rule, "follow how it IS
  * installed": there is no pin to honour, and `pnpm`/`yarn` have no
@@ -106,9 +120,11 @@ function updateCommandFor(
 	tool: CliTool,
 	declared: ResolvedBin | null,
 	status: ToolStatus,
+	facts: ToolFacts,
 	install: InstallInfo | undefined,
 ): Command | undefined {
 	if (!isInstalled(status)) return undefined;
+	if (facts.upgradeCommand) return facts.upgradeCommand;
 	if (declared) {
 		return binCommandForState("upgrade", status.target, declared) ?? undefined;
 	}
@@ -126,6 +142,78 @@ export function displayVersion(v: string): string {
 	return `v${v.replace(/^v/i, "")}`;
 }
 
+/** What Enter does on one row. */
+export interface CliToolEnterAction {
+	kind: "install" | "update" | "update-anyway" | "reinstall";
+	/** The footer hint's label, e.g. "update". */
+	label: string;
+	/** The detail pane's words beside the Enter chip, e.g. "Update to v0.95.0". */
+	detail: string;
+	/** The progress word while it runs, e.g. "Updating". */
+	progress: string;
+	command: Command;
+}
+
+/**
+ * What Enter does on `row` — null while the row is still being checked, when
+ * Enter does nothing.
+ *
+ * The footer hint, the detail pane and the handler each used to decide this
+ * on their own, and the footer said "install" on every row while the detail
+ * pane beside it said "Update to v0.95.0". All three read this now.
+ *
+ * An `unknown` row still offers the detected method's command: an explicit
+ * user action, not a plan, and the detail pane shows why beside it.
+ */
+export function cliToolEnterAction(row: CliToolRow): CliToolEnterAction | null {
+	const { status, updateCommand, installCommand } = row;
+	if (row.checking || !status) return null;
+	// Installed NEWER than its pin: every command there is wrong. The pin's own
+	// command downgrades — for an npm prefix or Claude Code's native installer the
+	// probe aims its command AT the pin — and latest moves further past the pin
+	// the profile asked for. Enter does nothing; the row's note says why.
+	if (status.reason === "ahead-of-pin") return null;
+	if (!isInstalled(status)) {
+		return {
+			kind: "install",
+			label: "install",
+			detail: "Install",
+			progress: "Installing",
+			command: installCommand,
+		};
+	}
+	// Both commands come from the row, which built them from the SAME rule its
+	// state came from — a declared tool's pin included.
+	const command = updateCommand ?? installCommand;
+	if (status.state === "upgrade") {
+		return {
+			kind: "update",
+			label: "update",
+			detail: status.target
+				? `Update to ${displayVersion(status.target)}`
+				: "Update",
+			progress: "Updating",
+			command,
+		};
+	}
+	if (status.state === "unknown") {
+		return {
+			kind: "update-anyway",
+			label: "update anyway",
+			detail: "Update anyway",
+			progress: "Updating",
+			command,
+		};
+	}
+	return {
+		kind: "reinstall",
+		label: "reinstall",
+		detail: "Reinstall",
+		progress: "Reinstalling",
+		command,
+	};
+}
+
 export interface CliToolStatusText {
 	/** Text after the version, with its leading space; "" for nothing to say. */
 	suffix: string;
@@ -133,8 +221,49 @@ export interface CliToolStatusText {
 }
 
 /**
- * The row's status words. An `unknown` shows its note verbatim — the same
- * string `magus update` prints for that tool.
+ * The row's short word for WHY an `unknown` could not be checked.
+ *
+ * A label, never the note. The note is a sentence with a path in it ("on PATH
+ * at /Users/…, which npm … does not own — …"); a list row has room for a
+ * version, a method tag and a few words, so printing the note there cut it off
+ * mid-path on every machine. The full note stays in the detail pane's "Why"
+ * line, the same string `magus update` prints.
+ *
+ * Every label is at most 19 cells, so the row suffix (" ? " + label) stays
+ * within 24. Keyed by reason alone — plus the spec's installer, which is a
+ * word, never a path.
+ */
+function unknownLabel(reason: ToolReason, via: BinRequirement["via"]): string {
+	switch (reason) {
+		case "not-managed":
+			return `not managed by ${via}`;
+		case "version-unreadable":
+			return "version unreadable";
+		case "latest-unavailable":
+			return "latest unavailable";
+		case "unorderable":
+			return "not comparable";
+		case "ahead-of-pin":
+			return "ahead of pin";
+		case "held-back":
+			return "held back";
+		case "pin-not-installable":
+			return "pin not installable";
+		case "not-probed":
+			return "not checked";
+		// Never `unknown`: these reasons plan work or report `current`.
+		case "absent":
+		case "up-to-date":
+		case "behind":
+		case "at-pin":
+		case "behind-pin":
+			return "not checked";
+	}
+}
+
+/**
+ * The row's status words. An `unknown` shows a short label for its reason
+ * ({@link unknownLabel}); the detail pane carries the full note.
  */
 export function cliToolStatusText(row: CliToolRow): CliToolStatusText {
 	const { status } = row;
@@ -142,7 +271,7 @@ export function cliToolStatusText(row: CliToolRow): CliToolStatusText {
 	switch (status.state) {
 		case "unknown":
 			return {
-				suffix: ` ? ${status.note ?? "cannot tell whether it is current"}`,
+				suffix: ` ? ${unknownLabel(status.reason, row.spec.via)}`,
 				tone: "warning",
 			};
 		case "upgrade":