magus-cli 7.12.2 → 7.14.0

package/src/tui-runtime.tsx

@@ -0,0 +1,142 @@
+/**
+ * What every magus TUI shares before its first screen: the renderer, the one
+ * shutdown owner, Ctrl+C, the OSC 52 copy of a mouse selection, and the light
+ * or dark theme. `tui.tsx` (bare `magus`) and `market-tui.tsx` (`magus
+ * edit`) each hand `mountTui` the React tree they draw.
+ *
+ * Like those two, this module is only ever imported dynamically from
+ * `main.tsx`, so nothing on a non-interactive path loads `@opentui/*`.
+ */
+
+import { RGBA, type ThemeMode, createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import type { ReactNode } from "react";
+import { installShutdown } from "./ui/runtime/shutdown.js";
+import { setThemeMode } from "./ui/theme-mode.js";
+import { type ThemeEnv, resolveTheme } from "./ui/theme-resolve.js";
+
+export interface MountTuiOptions {
+	/** From `--theme`, already validated by the router. */
+	theme?: ThemeMode;
+	/** The theme variables, snapshotted in main.tsx BEFORE any .env merge. */
+	env: ThemeEnv;
+	/** stdin AND stdout are TTYs. Decided by the caller. */
+	isInteractive: boolean;
+}
+
+/** How long the terminal may take to answer the light-or-dark probe. */
+const THEME_PROBE_MS = 250;
+
+/**
+ * Start a TUI drawing `render(quit)`. Never resolves — the app runs until the
+ * user exits, and every exit goes through the one shutdown routine.
+ */
+export async function mountTui(
+	{ theme, env, isInteractive }: MountTuiOptions,
+	render: (quit: () => void) => ReactNode,
+): Promise<void> {
+	// Create OpenTUI renderer (handles alternate screen buffer automatically).
+	//
+	// The background is the terminal's own, not a colour of ours: painting an
+	// absolute fill would box the UI into whatever theme we guessed. OpenTUI's
+	// built-in default for unstyled cells is truecolor white, which is why every
+	// element now names an adaptive colour explicitly — see src/ui/theme.ts.
+	// The mouse is ON, everywhere — it carries real features now: the wheel
+	// scrolls the pane under the cursor, and a drag selects text from ONE pane
+	// at a time (terminal-native selection is a screen-wide rectangle that
+	// grabs both columns), OSC 52-copied on release below.
+	//
+	// This deliberately includes tmux. Two earlier revisions got this wrong in
+	// opposite directions: one disabled the mouse everywhere on the theory that
+	// capture breaks tmux-level pane clicking, the next kept it off only inside
+	// tmux. Both dated from when magus had no mouse features, so disabling
+	// cost nothing. MEASURED on a heavily tmux'd machine: tmux forwards mouse
+	// to a pane application that asks for it (htop in the same session took
+	// clicks and wheel fine while magus sat inert), and tmux's own `mouse`
+	// option keeps governing pane management. Terminal-native selection stays
+	// reachable via Shift+drag in most terminals.
+	//
+	// enableMouseMovement (mode-1003 "report all motion") stays off — selection
+	// needs only button-held drag events, which button reporting delivers.
+	const renderer = await createCliRenderer({
+		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, 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;
+	// terminals that block it simply ignore the sequence. Never fires where the
+	// mouse is off, so the tmux path pays nothing.
+	renderer.on("selection", (selection: { getSelectedText(): string }) => {
+		const text = selection?.getSelectedText() ?? "";
+		if (text.length > 0) renderer.copyToClipboardOSC52(text);
+	});
+
+	// Resolve light vs dark once: --theme, MAGUS_THEME, TERM_THEME, the OSC
+	// probe, COLORFGBG, dark — see src/ui/theme-resolve.ts. Only the disabled-row
+	// tint and the chips need this (src/ui/theme-mode.ts explains why that one
+	// case cannot be solved the way the rest of the palette is).
+	//
+	// The renderer sends OSC 10/11 at creation regardless: @opentui/core 0.1.107
+	// has no option to suppress it. So the rule "TERM_THEME skips the probe" is
+	// satisfied by NOT AWAITING — when steps 1-3 answer, `probe` is never called,
+	// `waitForThemeMode` never runs, first paint is not delayed, and
+	// `renderer.themeMode` is never read anywhere in magus. Any late reply the
+	// terminal sends is consumed by OpenTUI's own handleSequence and ignored here.
+	const { mode } = await resolveTheme({
+		flag: theme,
+		env,
+		isInteractive,
+		probe: () => renderer.waitForThemeMode(THEME_PROBE_MS).catch(() => null),
+	});
+	setThemeMode(mode);
+
+	root.render(render(quit));
+
+	// Wait indefinitely: every exit goes through `shutdown`, which ends the
+	// process itself.
+	await new Promise(() => {});
+}

package/src/tui.tsx

@@ -1,139 +1,22 @@
 /**
- * The interactive TUI: renderer creation, theme resolution, and the React root.
+ * The interactive TUI behind bare `magus`.
  *
  * Split out of `main.tsx` so that nothing on a non-interactive path — above all
  * `magus hook …`, which Claude Code runs on every matching tool call — has
  * to load `@opentui/*` or `src/ui/` to reach its own code. `main.tsx` imports
- * this module dynamically, at the last possible moment.
+ * this module dynamically, at the last possible moment. The renderer, the
+ * shutdown, Ctrl+C and the theme are `mountTui`'s (src/tui-runtime.tsx).
  */
 
-import { RGBA, type ThemeMode, createCliRenderer } from "@opentui/core";
-import { createRoot } from "@opentui/react";
+import { type MountTuiOptions, mountTui } from "./tui-runtime.js";
 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";
 
-export interface StartTuiOptions {
-	/** From `--theme`, already validated by the router. */
-	theme?: ThemeMode;
-	/** The theme variables, snapshotted in main.tsx BEFORE any .env merge. */
-	env: ThemeEnv;
-	/** stdin AND stdout are TTYs. Decided by the caller. */
-	isInteractive: boolean;
-}
+export type StartTuiOptions = MountTuiOptions;
 
 /**
  * Start the TUI. Never resolves — the app runs until the user exits.
  */
-export async function startTui({
-	theme,
-	env,
-	isInteractive,
-}: StartTuiOptions): Promise<void> {
-	// Create OpenTUI renderer (handles alternate screen buffer automatically).
-	//
-	// The background is the terminal's own, not a colour of ours: painting an
-	// absolute fill would box the UI into whatever theme we guessed. OpenTUI's
-	// built-in default for unstyled cells is truecolor white, which is why every
-	// element now names an adaptive colour explicitly — see src/ui/theme.ts.
-	// The mouse is ON, everywhere — it carries real features now: the wheel
-	// scrolls the pane under the cursor, and a drag selects text from ONE pane
-	// at a time (terminal-native selection is a screen-wide rectangle that
-	// grabs both columns), OSC 52-copied on release below.
-	//
-	// This deliberately includes tmux. Two earlier revisions got this wrong in
-	// opposite directions: one disabled the mouse everywhere on the theory that
-	// capture breaks tmux-level pane clicking, the next kept it off only inside
-	// tmux. Both dated from when magus had no mouse features, so disabling
-	// cost nothing. MEASURED on a heavily tmux'd machine: tmux forwards mouse
-	// to a pane application that asks for it (htop in the same session took
-	// clicks and wheel fine while magus sat inert), and tmux's own `mouse`
-	// option keeps governing pane management. Terminal-native selection stays
-	// reachable via Shift+drag in most terminals.
-	//
-	// enableMouseMovement (mode-1003 "report all motion") stays off — selection
-	// needs only button-held drag events, which button reporting delivers.
-	const renderer = await createCliRenderer({
-		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;
-	// terminals that block it simply ignore the sequence. Never fires where the
-	// mouse is off, so the tmux path pays nothing.
-	renderer.on("selection", (selection: { getSelectedText(): string }) => {
-		const text = selection?.getSelectedText() ?? "";
-		if (text.length > 0) renderer.copyToClipboardOSC52(text);
-	});
-
-	// Resolve light vs dark once: --theme, MAGUS_THEME, TERM_THEME, the OSC
-	// probe, COLORFGBG, dark — see src/ui/theme-resolve.ts. Only the disabled-row
-	// tint and the chips need this (src/ui/theme-mode.ts explains why that one
-	// case cannot be solved the way the rest of the palette is).
-	//
-	// The renderer sends OSC 10/11 at creation regardless: @opentui/core 0.1.107
-	// has no option to suppress it. So the rule "TERM_THEME skips the probe" is
-	// satisfied by NOT AWAITING — when steps 1-3 answer, `probe` is never called,
-	// `waitForThemeMode(250)` never runs, first paint is not delayed, and
-	// `renderer.themeMode` is never read anywhere in magus. Any late reply the
-	// terminal sends is consumed by OpenTUI's own handleSequence and ignored here.
-	const { mode } = await resolveTheme({
-		flag: theme,
-		env,
-		isInteractive,
-		probe: () => renderer.waitForThemeMode(250).catch(() => null),
-	});
-	setThemeMode(mode);
-
+export async function startTui(opts: StartTuiOptions): Promise<void> {
 	// `q`, Escape on the home tab and the profile gate's quit all end here.
-	root.render(<App onExit={quit} />);
-
-	// Wait indefinitely: every exit goes through `shutdown`, which ends the
-	// process itself.
-	await new Promise(() => {});
+	await mountTui(opts, (quit) => <App onExit={quit} />);
 }

package/src/types/index.ts

@@ -50,6 +50,13 @@ export interface Marketplace {
 	featured?: boolean; // Featured marketplaces have plugins fetched by default (like official)
 	deprecated?: boolean; // Deprecated marketplaces are sorted to the bottom of the list
 	owned?: boolean; // Our own marketplaces (magus*): always listed even when uninstalled, and sorted to the top
+	/**
+	 * A company marketplace on this machine: its manifest carries the company
+	 * marker and this machine trusts it. Listed above every other marketplace.
+	 */
+	company?: boolean;
+	/** `owner.name` from the marketplace's own manifest, when it names one. */
+	ownerName?: string;
 }
 
 export interface DiscoveredMarketplace {

package/src/ui/adapters/marketAdapter.ts

@@ -0,0 +1,366 @@
+/**
+ * The market screens' rows and words, built from what the market services
+ * read: the overview of each company marketplace, the installs of its
+ * plugins, and how this project's skill copies stand. Pure, so the rows are
+ * tested without a renderer.
+ */
+
+import type {
+	MarketOverviewEntry,
+	OverviewFreshness,
+} from "../../services/market-ops.js";
+import type {
+	InstallScope,
+	LocalItem,
+	MarketResult,
+	SkillStatusRow,
+} from "../../services/market-types.js";
+import type { FailureReport, FailureRow } from "../state/types.js";
+import { displayWidth, truncate } from "../text-width.js";
+import type { theme } from "../theme.js";
+
+// ─── Screen 1 ────────────────────────────────────────────────────────────────
+
+export type MarketplacesItem =
+	| {
+			kind: "marketplace";
+			entry: MarketOverviewEntry;
+			/** Its plugins with skills edited here, ready to push. */
+			toPush: readonly string[];
+	  }
+	| { kind: "create" }
+	| { kind: "connect" }
+	/** The heading over the local rows; never selected. */
+	| { kind: "local-heading"; count: number }
+	| { kind: "local"; item: LocalItem };
+
+/**
+ * The marketplaces, the two rows that add one, then — when there are any —
+ * the skills and plugin folders here that no marketplace holds yet.
+ */
+export function marketplacesItems(
+	entries: readonly MarketOverviewEntry[],
+	status: readonly SkillStatusRow[] = [],
+	local: readonly LocalItem[] = [],
+): MarketplacesItem[] {
+	return [
+		...entries.map((entry) => ({
+			kind: "marketplace" as const,
+			entry,
+			toPush: pluginsToPush(entry.name, status),
+		})),
+		{ kind: "create" },
+		{ kind: "connect" },
+		...(local.length > 0
+			? [
+					{ kind: "local-heading" as const, count: local.length },
+					...local.map((item) => ({ kind: "local" as const, item })),
+				]
+			: []),
+	];
+}
+
+/** Whether a row can hold the selection: every row but a heading. */
+export function selectable(item: MarketplacesItem | undefined): boolean {
+	return item !== undefined && item.kind !== "local-heading";
+}
+
+/**
+ * The next selectable index from `from` in direction `step` (±1), or `from`
+ * when there is none that way.
+ */
+export function nextSelectable(
+	items: readonly MarketplacesItem[],
+	from: number,
+	step: number,
+): number {
+	for (let i = from + step; i >= 0 && i < items.length; i += step) {
+		if (selectable(items[i])) return i;
+	}
+	return from;
+}
+
+/** The skill rows `edited` here, by the plugin `ref` that owns them. */
+export function editedSkills(
+	status: readonly SkillStatusRow[],
+	ref: string,
+): string[] {
+	return [
+		...new Set(
+			status
+				.filter((r) => r.state === "edited" && r.owner === ref)
+				.map((r) => r.skill),
+		),
+	].sort();
+}
+
+/** The plugins of `marketplace` with at least one skill edited here. */
+export function pluginsToPush(
+	marketplace: string,
+	status: readonly SkillStatusRow[],
+): string[] {
+	const suffix = `@${marketplace}`;
+	return [
+		...new Set(
+			status
+				.filter(
+					(r) => r.state === "edited" && r.owner?.endsWith(suffix) === true,
+				)
+				.map((r) => (r.owner as string).slice(0, -suffix.length)),
+		),
+	].sort();
+}
+
+/** What a local row is, in the user's words. */
+export function localKindWords(item: LocalItem): string {
+	return item.kind === "plugin" ? "plugin" : "skill";
+}
+
+/** The narrowest a cut secondary text is still worth showing. */
+const MIN_CUT = 4;
+
+/**
+ * Fit one list row into `width` columns without wrapping. The name and the
+ * parts of `fixed` columns (a scope badge, the gaps around it) always show:
+ * the name is cut with "…" to leave them room. The secondary texts follow in
+ * order while each fits whole after a gap of `gap`; the first that does not
+ * is cut to what is left (when that is at least a few columns), and the rest
+ * are dropped.
+ */
+export function fitRow<T extends { text: string }>(
+	width: number,
+	name: string,
+	fixed: number,
+	secondary: readonly T[],
+	gap = 2,
+): { name: string; secondary: T[] } {
+	const nameOut = truncate(name, Math.max(1, width - fixed));
+	let used = displayWidth(nameOut) + fixed;
+	const out: T[] = [];
+	for (const part of secondary) {
+		const need = gap + displayWidth(part.text);
+		if (used + need <= width) {
+			out.push(part);
+			used += need;
+			continue;
+		}
+		const room = width - used - gap;
+		if (room >= MIN_CUT) out.push({ ...part, text: truncate(part.text, room) });
+		break;
+	}
+	return { name: nameOut, secondary: out };
+}
+
+/** "1 plugin", "3 plugins". */
+export function plural(n: number, word: string): string {
+	return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+/** How current a marketplace's rows are, in one short phrase. */
+export function freshnessWords(freshness: OverviewFreshness): string {
+	return freshness === "fresh" ? "up to date" : "not current";
+}
+
+/** The tone {@link freshnessWords} are shown in. */
+export function freshnessTone(
+	freshness: OverviewFreshness,
+): "success" | "warning" {
+	return freshness === "fresh" ? "success" : "warning";
+}
+
+// ─── Screen 2 ────────────────────────────────────────────────────────────────
+
+/** Installed versions of one plugin, by scope; null where it is not installed. */
+export type ScopeVersions = Record<InstallScope, string | null>;
+
+export const NO_INSTALLS: ScopeVersions = {
+	user: null,
+	project: null,
+	local: null,
+};
+
+export type MarketplaceItem =
+	| {
+			kind: "plugin";
+			/** `plugin@marketplace`. */
+			ref: string;
+			name: string;
+			version: string;
+			skills: readonly string[];
+			installs: ScopeVersions;
+			expanded: boolean;
+			/** Its skills edited here, which `p` pushes as one new version. */
+			edited: readonly string[];
+	  }
+	| {
+			kind: "skill";
+			ref: string;
+			plugin: string;
+			skill: string;
+			/** This project's or your USER copy of the skill, when there is one. */
+			local: SkillStatusRow | null;
+	  };
+
+/**
+ * The local copy a skill row speaks for: this project's when there is one,
+ * else your USER copy. Only rows the plugin `ref` owns count, including a
+ * row several plugins hold a skill of that name for: the row names the plugin
+ * explicitly, so a publish from it goes to `ref`.
+ */
+export function localCopyFor(
+	rows: readonly SkillStatusRow[],
+	ref: string,
+	skill: string,
+): SkillStatusRow | null {
+	const mine = rows.filter(
+		(r) => r.skill === skill && (r.owner === ref || !!r.owners?.includes(ref)),
+	);
+	return mine.find((r) => r.from === "project") ?? mine[0] ?? null;
+}
+
+/** Plugin rows, each followed by its skill rows while expanded. */
+export function marketplaceItems(
+	entry: MarketOverviewEntry,
+	installs: Readonly<Record<string, ScopeVersions>>,
+	status: readonly SkillStatusRow[],
+	expanded: ReadonlySet<string>,
+): MarketplaceItem[] {
+	const items: MarketplaceItem[] = [];
+	for (const p of entry.plugins) {
+		const ref = `${p.name}@${entry.name}`;
+		const open = expanded.has(ref);
+		items.push({
+			kind: "plugin",
+			ref,
+			name: p.name,
+			version: p.version,
+			skills: p.skills,
+			installs: installs[ref] ?? NO_INSTALLS,
+			expanded: open,
+			edited: editedSkills(status, ref),
+		});
+		if (!open) continue;
+		for (const skill of p.skills) {
+			items.push({
+				kind: "skill",
+				ref,
+				plugin: p.name,
+				skill,
+				local: localCopyFor(status, ref, skill),
+			});
+		}
+	}
+	return items;
+}
+
+type MetaTone = keyof typeof theme.meta;
+
+export interface SkillMark {
+	glyph: string;
+	words: string;
+	tone: MetaTone;
+}
+
+/** How a local copy stands, as a skill row draws it; null when it needs nothing. */
+export function skillMark(row: SkillStatusRow | null): SkillMark | null {
+	switch (row?.state) {
+		case "edited":
+			return { glyph: "●", words: "edited here", tone: "warning" };
+		case "no-base":
+			return {
+				glyph: "◇",
+				words: "edited here, origin unknown",
+				tone: "warning",
+			};
+		case "conflict":
+			return {
+				glyph: "⚠",
+				words: "changed here and on GitHub",
+				tone: "danger",
+			};
+		case "plugin-newer":
+			return {
+				glyph: "↓",
+				words: "plugin has a newer version",
+				tone: "info",
+			};
+		case "not-checked":
+			return { glyph: "?", words: "not checked — r to fetch", tone: "muted" };
+		case "ambiguous":
+			return { glyph: "?", words: "in more than one plugin", tone: "muted" };
+		default:
+			return null;
+	}
+}
+
+/** Whether `p` has anything to publish on this row. */
+export function publishable(row: SkillStatusRow | null): boolean {
+	return (
+		row?.state === "edited" ||
+		row?.state === "no-base" ||
+		row?.state === "conflict"
+	);
+}
+
+/** Whose copy a local row is, in the user's words. */
+export function copyWords(row: SkillStatusRow): string {
+	return row.from === "user" ? "your USER copy" : "this project's copy";
+}
+
+// ─── Results ─────────────────────────────────────────────────────────────────
+
+const SETTLED: ReadonlySet<MarketResult["outcome"]> = new Set([
+	"ok",
+	"unchanged",
+	"plugin-newer",
+	"pull-request",
+]);
+
+/** The line a finished change leaves on its marketplace, or null for none. */
+export function resultNote(result: MarketResult): string | null {
+	if (result.outcome === "pull-request") {
+		return result.pullRequest
+			? `Pull request opened: ${result.pullRequest}`
+			: result.message;
+	}
+	if (!SETTLED.has(result.outcome)) return null;
+	return result.message;
+}
+
+/**
+ * The one failure popup for a result, or null when nothing failed. A change
+ * that landed but left installs behind (`partial`) names each install.
+ */
+export function marketFailureReport(
+	result: MarketResult,
+	subject: string,
+): FailureReport | null {
+	const failedInstalls = (result.installs ?? []).filter(
+		(i) => i.status === "failed",
+	);
+	if (SETTLED.has(result.outcome) && failedInstalls.length === 0) return null;
+	const rows: FailureRow[] = [];
+	for (const i of failedInstalls) {
+		rows.push({
+			subject: `${result.plugin ?? subject} at ${i.scope.toUpperCase()}`,
+			reason: i.message ?? "the install did not move",
+			...(i.fix ? { fix: i.fix } : {}),
+		});
+	}
+	const failedStep = result.steps.find((s) => s.status === "failed");
+	if (rows.length === 0) {
+		rows.push({
+			subject,
+			reason:
+				result.error?.message ?? failedStep?.detail ?? "it did not complete",
+		});
+	}
+	const fixes = new Set(rows.map((r) => r.fix).filter(Boolean));
+	const fix =
+		result.error?.fix ?? (fixes.size === 1 ? ([...fixes][0] as string) : null);
+	return {
+		headline: result.message,
+		rows: fix ? rows.map(({ fix: _drop, ...r }) => r) : rows,
+		fix,
+	};
+}