@underactive/pi-topping 0.5.1 → 0.6.1

package/src/session.ts

@@ -33,11 +33,15 @@ import {
 	TOKEN_RATE_PLACEHOLDER,
 	StreamingWordCounter,
 } from "./format.ts";
+import { isSiblingSetupEnabled } from "./flags.ts";
 import { showMenu } from "./menu.ts";
+import { registerSetupCommand } from "./setup-command.ts";
 import { applyMenuResult, buildMenuSections, loadSettings, saveSettings, type SettingColor } from "./settings.ts";
+import { notifyMissingToppingsOnce } from "./toppings.ts";
 import { PreviewRenderer } from "./preview.ts";
-import { buildCompletionMarkerContent, buildCompletionMarkerLine, PROMPT_BOX_TYPE, promptBoxRenderer, stripControlChars, type PromptBoxDetails } from "./prompt-decorator.ts";
-import { pickRandomWord, pickRawWord } from "./words.ts";
+import { buildCompletionMarkerContent, buildCompletionMarkerLine, PROMPT_BOX_TYPE, promptBoxRenderer, type PromptBoxDetails } from "./prompt-decorator.ts";
+import { stripControlChars } from "./util.ts";
+import { loadBundledWordPacks, loadUserWordPacks, pickWorkingTextSelection, type WorkingTextSelection, type WordPack } from "./word-packs.ts";
 
 type MessageStartEvent = Extract<ExtensionEvent, { type: "message_start" }>;
 type MessageUpdateEvent = Extract<ExtensionEvent, { type: "message_update" }>;
@@ -58,7 +62,7 @@ interface DoneEntryData {
 
 interface SessionState {
 	startTime: number;
-	currentWord: string;
+	workingText: WorkingTextSelection;
 	confirmTokens: number;
 	liveTokens: number;
 	shimmerOrigin: number;
@@ -90,7 +94,7 @@ function resetTokenRateState(state: SessionState): void {
 function makeFreshState(): SessionState {
 	return {
 		startTime: 0,
-		currentWord: "",
+		workingText: { text: "", pastTense: "Worked" },
 		confirmTokens: 0,
 		liveTokens: 0,
 		shimmerOrigin: 0,
@@ -112,6 +116,8 @@ export class SessionManager {
 	#counter = new StreamingWordCounter();
 	#state = makeFreshState();
 	#settings = loadSettings();
+	#userPacks: WordPack[] = [];
+	#bundledPacks = loadBundledWordPacks();
 	#currentCtx: ExtensionContext | null = null;
 	readonly #pi: ExtensionAPI;
 
@@ -124,9 +130,13 @@ export class SessionManager {
 		this.#counter.reset();
 		this.#state = makeFreshState();
 		this.#settings = loadSettings();
+		this.#userPacks = loadUserWordPacks();
 		this.#state.activityMeter.setDirection(this.#settings.decorations.meterDirection);
 		this.#currentCtx = ctx;
-		if (this.usable(ctx)) this.applyIndicator(ctx);
+		if (this.usable(ctx)) {
+			this.applyIndicator(ctx);
+			if (isSiblingSetupEnabled()) notifyMissingToppingsOnce(this.#pi, ctx.ui);
+		}
 	};
 
 	#onInput = async (event: InputEvent, ctx: ExtensionContext): Promise<InputEventResult | void> => {
@@ -209,7 +219,7 @@ export class SessionManager {
 	#onToolExecutionStart = async (_e: ToolExecutionStartEvent, ctx: ExtensionContext): Promise<void> => {
 		this.#currentCtx = ctx;
 		if (this.usable(ctx)) {
-			this.#state.currentWord = pickRandomWord();
+			this.#state.workingText = this.pickWorkingWord();
 			this.#state.shimmerOrigin = Date.now();
 			this.tick();
 		}
@@ -232,7 +242,7 @@ export class SessionManager {
 		this.#state.lastMessage = NOT_SENT;
 		if (this.#settings.features.doneMarker && hadPrompt) {
 			this.#pi.appendEntry<DoneEntryData>(DONE_ENTRY_TYPE, {
-				word: this.#settings.features.randomizeDoneMarker ? pickRawWord().past_tense : "Worked",
+				word: this.#settings.features.randomizeDoneMarker ? this.#state.workingText.pastTense : "Worked",
 				elapsedMs,
 				tokens: this.#state.confirmTokens,
 				midTurnInputs: this.#state.midTurnInputs,
@@ -259,6 +269,7 @@ export class SessionManager {
 		const markerContent = buildCompletionMarkerContent(theme, icon, word, formatElapsed(elapsedMs), details);
 		const borderStyle = this.#settings.decorations.doneMarkerBorderStyle;
 		const borderColor = this.#settings.decorations.doneMarkerBorderColor;
+		const markerStyle = this.#settings.decorations.doneMarkerStyle;
 		if (borderStyle === "none") return new Text(markerContent);
 
 		let cachedWidth: number | undefined;
@@ -267,7 +278,7 @@ export class SessionManager {
 			render(width: number): string[] {
 				if (cachedWidth !== width) {
 					cachedWidth = width;
-					cachedLines = ["", ` ${buildCompletionMarkerLine(markerContent, width - 2, theme, borderStyle, borderColor)}`, ""];
+					cachedLines = ["", buildCompletionMarkerLine(markerContent, width, theme, borderStyle, borderColor, markerStyle), ""];
 				}
 				return cachedLines!;
 			},
@@ -294,6 +305,7 @@ export class SessionManager {
 			description: "Configure prompt decoration, working-loader features/order, and completion-marker settings.",
 			handler: async (_a, ctx) => this.showSettings(ctx),
 		});
+		if (isSiblingSetupEnabled()) registerSetupCommand(this.#pi);
 	}
 
 	private usable(ctx: ExtensionContext): boolean {
@@ -367,11 +379,15 @@ export class SessionManager {
 		if (interval) this.#state.timer = setInterval(() => this.tick(), interval);
 	}
 
+	private pickWorkingWord(): WorkingTextSelection {
+		return pickWorkingTextSelection(this.#settings.wordPacks, [...this.#bundledPacks, ...this.#userPacks]);
+	}
+
 	private resetTurn(now: number): void {
 		const state = this.#state;
 		state.startTime = now;
 		state.shimmerOrigin = now;
-		state.currentWord = pickRandomWord();
+		state.workingText = this.pickWorkingWord();
 		state.confirmTokens = 0;
 		state.liveTokens = 0;
 		state.activityMeter.reset();
@@ -413,7 +429,7 @@ export class SessionManager {
 			return;
 		}
 
-		const word = features.substituteDefaultMessage ? state.currentWord : DEFAULT_WORKING_WORD;
+		const word = features.substituteDefaultMessage ? state.workingText.text : DEFAULT_WORKING_WORD;
 		const styled = decorations.shimmer
 			? shimmerString(word, now - state.shimmerOrigin, ctx.ui.theme, decorations.shimmerDirection, decorations.shimmerSpeed, decorations.shimmerInverted)
 			: ctx.ui.theme.fg("text", word);
@@ -476,11 +492,12 @@ export class SessionManager {
 			return;
 		}
 
+		this.#userPacks = loadUserWordPacks();
 		const before = this.indicatorFingerprint();
-		const preview = new PreviewRenderer(ctx);
+		const preview = new PreviewRenderer(ctx, [...this.#bundledPacks, ...this.#userPacks]);
 		const result = await showMenu<Record<string, boolean | string>>(ctx, {
 			title: "Pi Topping: Settings",
-			sections: buildMenuSections(this.#settings),
+			sections: buildMenuSections(this.#settings, this.#bundledPacks, this.#userPacks),
 			hints: ["↑↓ move", "←→ select", "␣ toggle", "⏎ apply", "esc cancel"],
 			preview: preview.render.bind(preview),
 		});

package/src/settings.ts

@@ -3,6 +3,8 @@ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { DEFAULT_LOADER_ORDER, type LoaderElement } from "./format.ts";
 import type { MenuSection } from "./menu.ts";
+import { isWordPackEnabled, isWordPackId, type WordPack } from "./word-packs.ts";
+import { isPlainObject } from "./util.ts";
 
 export const SETTING_COLOR_VALUES = ["accent", "border", "borderAccent", "success", "error", "warning"] as const;
 export type SettingColor = (typeof SETTING_COLOR_VALUES)[number];
@@ -11,6 +13,8 @@ export const BORDER_STYLE_VALUES = ["double", "single", "rounded", "heavy"] as c
 export type BorderStyle = (typeof BORDER_STYLE_VALUES)[number];
 export const DONE_MARKER_BORDER_STYLE_VALUES = [...BORDER_STYLE_VALUES, "none"] as const;
 export type DoneMarkerBorderStyle = (typeof DONE_MARKER_BORDER_STYLE_VALUES)[number];
+export const DONE_MARKER_STYLE_VALUES = ["elite", "bookend"] as const;
+export type DoneMarkerStyle = (typeof DONE_MARKER_STYLE_VALUES)[number];
 
 export function isBorderStyle(value: unknown): value is BorderStyle {
 	return typeof value === "string" && BORDER_STYLE_VALUES.some(style => style === value);
@@ -20,6 +24,10 @@ export function isDoneMarkerBorderStyle(value: unknown): value is DoneMarkerBord
 	return typeof value === "string" && DONE_MARKER_BORDER_STYLE_VALUES.some(style => style === value);
 }
 
+export function isDoneMarkerStyle(value: unknown): value is DoneMarkerStyle {
+	return typeof value === "string" && DONE_MARKER_STYLE_VALUES.some(style => style === value);
+}
+
 export function isSettingColor(value: unknown): value is SettingColor {
 	return typeof value === "string" && SETTING_COLOR_VALUES.some(color => color === value);
 }
@@ -43,6 +51,7 @@ export interface DecoratorSettings {
 		borderStyleEnabled: boolean;
 		doneMarkerBorderStyle: DoneMarkerBorderStyle;
 		doneMarkerBorderColor: SettingColor;
+		doneMarkerStyle: DoneMarkerStyle;
 		spinnerColor: SettingColor;
 		spinnerColorEnabled: boolean;
 		meterColor: SettingColor;
@@ -68,12 +77,14 @@ export interface DecoratorSettings {
 		doneMarkerInputs: boolean;
 	};
 	loaderOrder: LoaderElement[];
+	wordPacks: Record<string, boolean>;
 }
 
 export const DEFAULT_SETTINGS: DecoratorSettings = {
-	decorations: { animatedSpinner: true, shimmer: true, shimmerInverted: false, shimmerDirection: "ltr", shimmerDirectionEnabled: true, shimmerSpeed: "normal", shimmerSpeedEnabled: true, tokenActivityMonitor: true, meterDirection: "rtl", meterDirectionEnabled: true, decorateUserPrompt: true, borderColor: "borderAccent", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "borderAccent", spinnerColor: "accent", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, tokenRateColor: "warning", tokenRateDimmed: false, promptIcon: true, promptTimestamp: true, promptProvider: true, promptModel: true, useNerdFont: true },
+	decorations: { animatedSpinner: true, shimmer: true, shimmerInverted: false, shimmerDirection: "ltr", shimmerDirectionEnabled: true, shimmerSpeed: "normal", shimmerSpeedEnabled: true, tokenActivityMonitor: true, meterDirection: "rtl", meterDirectionEnabled: true, decorateUserPrompt: true, borderColor: "borderAccent", borderColorEnabled: true, borderStyle: "double", borderStyleEnabled: true, doneMarkerBorderStyle: "none", doneMarkerBorderColor: "borderAccent", doneMarkerStyle: "elite", spinnerColor: "accent", spinnerColorEnabled: true, meterColor: "accent", meterColorEnabled: true, meterDimmed: false, tokenRateColor: "warning", tokenRateDimmed: false, promptIcon: true, promptTimestamp: true, promptProvider: true, promptModel: true, useNerdFont: true },
 	features: { substituteDefaultMessage: true, elapsedTime: true, outputTokens: true, tokenRate: true, doneMarker: true, doneMarkerIcon: true, randomizeDoneMarker: true, doneMarkerTokens: true, doneMarkerInputs: true },
 	loaderOrder: [...DEFAULT_LOADER_ORDER],
+	wordPacks: {},
 };
 
 /** Menu key carrying the loader element order as a comma-joined list of element ids. */
@@ -104,7 +115,6 @@ export function parseLoaderOrder(value: unknown): LoaderElement[] {
 }
 
 export function settingsPath(): string { return join(getAgentDir(), "pi-topping", "settings.json"); }
-function isPlainObject(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function mergeGroup<T extends Record<string, boolean | string>>(defaults: T, parsed: unknown): T {
 	const merged = { ...defaults };
 	if (!isPlainObject(parsed)) return merged;
@@ -117,6 +127,7 @@ function mergeGroup<T extends Record<string, boolean | string>>(defaults: T, par
 		else if (key.endsWith("Color") && isSettingColor(value)) valid = value;
 		else if (key === "borderStyle" && isBorderStyle(value)) valid = value;
 		else if (key === "doneMarkerBorderStyle" && isDoneMarkerBorderStyle(value)) valid = value;
+		else if (key === "doneMarkerStyle" && isDoneMarkerStyle(value)) valid = value;
 		if (valid !== undefined) (merged as Record<string, boolean | string>)[key] = valid;
 	}
 	return merged;
@@ -188,6 +199,7 @@ export const MENU_ENTRIES: readonly MenuEntry[] = [
 	{ id: "tokenRateColor", label: "Token rate color", section: "“Working” Loader", group: "decorations", key: "tokenRateColor", cycleValues: SETTING_COLOR_VALUES },
 	{ id: "tokenRateDimmed", label: "Token rate dimmed", section: "“Working” Loader", group: "decorations", key: "tokenRateDimmed" },
 	{ id: "doneMarker", label: "Show completion marker", section: "Completion Marker", group: "features", key: "doneMarker" },
+	{ id: "doneMarkerStyle", label: "Marker style", section: "Completion Marker", group: "decorations", key: "doneMarkerStyle", cycleValues: DONE_MARKER_STYLE_VALUES },
 	{ id: "doneMarkerBorderStyle", label: "Border style", section: "Completion Marker", group: "decorations", key: "doneMarkerBorderStyle", cycleValues: DONE_MARKER_BORDER_STYLE_VALUES },
 	{ id: "doneMarkerBorderColor", label: "Border color", section: "Completion Marker", group: "decorations", key: "doneMarkerBorderColor", cycleValues: SETTING_COLOR_VALUES },
 	{ id: "doneMarkerIcon", label: "Pi icon", section: "Completion Marker", group: "features", key: "doneMarkerIcon" },
@@ -225,6 +237,9 @@ function setDecorationCycleValue(decorations: DecorationSettings, key: keyof Dec
 		case "doneMarkerBorderStyle":
 			if (isDoneMarkerBorderStyle(stored)) decorations[key] = stored;
 			return;
+		case "doneMarkerStyle":
+			if (isDoneMarkerStyle(stored)) decorations[key] = stored;
+			return;
 		case "shimmerDirection":
 		case "meterDirection":
 			if (stored === "ltr" || stored === "rtl") decorations[key] = stored;
@@ -242,12 +257,14 @@ function buildSection(title: MenuSectionName, settings: DecoratorSettings): Menu
 	return { title, items: MENU_ENTRIES.filter(entry => entry.section === title).map(entry => menuItem(entry, settings)) };
 }
 
-export function buildMenuSections(settings: DecoratorSettings): MenuSection[] {
+export function buildMenuSections(settings: DecoratorSettings, bundledPacks: readonly WordPack[], userPacks: readonly WordPack[] = []): MenuSection[] {
+	const packs = [...bundledPacks, ...userPacks];
 	return [
 		buildSection("User Prompt", settings),
 		buildSection("“Working” Loader", settings),
 		{ title: "Elements Order", items: parseLoaderOrder(settings.loaderOrder).map(id => ({ id, label: LOADER_ELEMENT_LABELS[id], value: false, reorderGroup: LOADER_ORDER_ID })) },
 		buildSection("Completion Marker", settings),
+		{ title: "Word Packs", items: packs.map((pack) => ({ id: `pack:${pack.id}`, label: pack.name, value: isWordPackEnabled(pack.id, settings.wordPacks) })) },
 		buildSection("Options", settings),
 	];
 }
@@ -266,6 +283,11 @@ export function applyMenuResult(settings: DecoratorSettings, values: Record<stri
 			next.features[entry.key] = value;
 		}
 	}
+	for (const [id, value] of Object.entries(values)) {
+		if (!id.startsWith("pack:") || typeof value !== "boolean") continue;
+		const packId = id.slice("pack:".length);
+		if (isWordPackId(packId)) next.wordPacks[packId] = value;
+	}
 	if (typeof values[LOADER_ORDER_ID] === "string") next.loaderOrder = parseLoaderOrder(values[LOADER_ORDER_ID]);
 	return next;
 }
@@ -280,7 +302,16 @@ export function loadSettings(): DecoratorSettings {
 	try {
 		const parsed = JSON.parse(readFileSync(settingsPath(), "utf8"));
 		if (!isPlainObject(parsed)) return structuredClone(DEFAULT_SETTINGS);
-		const settings = { decorations: mergeGroup(DEFAULT_SETTINGS.decorations, parsed.decorations), features: mergeGroup(DEFAULT_SETTINGS.features, parsed.features), loaderOrder: parseLoaderOrder(parsed.loaderOrder) };
+		const wordPacks: Record<string, boolean> = { ...DEFAULT_SETTINGS.wordPacks };
+		if (isPlainObject(parsed.wordPacks)) {
+			for (const [id, enabled] of Object.entries(parsed.wordPacks)) {
+				if (isWordPackId(id) && typeof enabled === "boolean") wordPacks[id] = enabled;
+			}
+		}
+		if (isPlainObject(parsed.features) && parsed.features.simCityWorkingText === true && !("simcity" in wordPacks)) {
+			wordPacks.simcity = true;
+		}
+		const settings = { decorations: mergeGroup(DEFAULT_SETTINGS.decorations, parsed.decorations), features: mergeGroup(DEFAULT_SETTINGS.features, parsed.features), loaderOrder: parseLoaderOrder(parsed.loaderOrder), wordPacks };
 		for (const entry of MENU_ENTRIES) {
 			if (entry.group === "decorations" && entry.cycleEnabledBy && entry.cycleDisabledValue !== undefined && !settings.decorations[entry.cycleEnabledBy]) {
 				setDecorationCycleValue(settings.decorations, entry.key, entry.cycleDisabledValue);
@@ -290,15 +321,18 @@ export function loadSettings(): DecoratorSettings {
 	} catch { return structuredClone(DEFAULT_SETTINGS); }
 }
 
-export function saveSettings(settings: DecoratorSettings): void {
-	const path = settingsPath();
+export function atomicWriteFile(path: string, contents: string): void {
 	mkdirSync(dirname(path), { recursive: true });
 	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
 	try {
-		writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`, { flag: "wx" });
+		writeFileSync(tmpPath, contents, { flag: "wx" });
 		renameSync(tmpPath, path);
 	} catch (err) {
 		try { unlinkSync(tmpPath); } catch { /* tmp file was never created */ }
 		throw err;
 	}
 }
+
+export function saveSettings(settings: DecoratorSettings): void {
+	atomicWriteFile(settingsPath(), `${JSON.stringify(settings, null, 2)}\n`);
+}

package/src/setup-check.ts

@@ -0,0 +1,20 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { atomicWriteFile } from "./settings.ts";
+import { isPlainObject } from "./util.ts";
+
+const setupCheckPath = (): string => join(getAgentDir(), "pi-topping", "setup-check.json");
+
+export function isSetupCheckDisabled(): boolean {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(setupCheckPath(), "utf8"));
+		return isPlainObject(parsed) && parsed.disabled === true;
+	} catch {
+		return false;
+	}
+}
+
+export function setSetupCheckDisabled(disabled: boolean): void {
+	atomicWriteFile(setupCheckPath(), `${JSON.stringify({ disabled })}\n`);
+}

package/src/setup-command.ts

@@ -0,0 +1,136 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { hyperlink } from "@earendil-works/pi-tui";
+import { showMenu } from "./menu.ts";
+import { type PiInstallResult, spawnPiInstall } from "./pi-installer.ts";
+import { stripControlChars } from "./util.ts";
+import { setSetupCheckDisabled } from "./setup-check.ts";
+import { findMissingToppings, type ToppingStatus } from "./toppings.ts";
+
+const INSTALL_TIMEOUT_MS = 120_000;
+const STDERR_SNIPPET_CHARS = 300;
+
+type ToppingInstaller = (spec: string, timeoutMs: number) => Promise<PiInstallResult>;
+
+type FailedInstall = { spec: string; error: string };
+
+function selectedToppings(missing: readonly ToppingStatus[], values: Record<string, boolean>): ToppingStatus[] {
+	return missing.filter(({ topping }) => values[topping.pkg] === true);
+}
+
+function renderDescription(missing: readonly ToppingStatus[], activeItemId: string | undefined): string[] {
+	const active = missing.find(({ topping }) => topping.pkg === activeItemId);
+	if (!active) return ["Select a topping to see what it does."];
+	const url = `https://pi.dev/packages/${active.topping.pkg}`;
+	return [active.topping.provides, "", hyperlink(url, url)];
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function buildReport(succeeded: string[], failed: FailedInstall[]): string {
+	const lines: string[] = [];
+	if (succeeded.length > 0) lines.push(`✓ Installed: ${succeeded.join(", ")}`);
+	if (failed.length > 0) {
+		lines.push("✗ Failed:");
+		for (const failure of failed) lines.push(`  ${failure.spec}: ${failure.error}`);
+	}
+	if (succeeded.length > 0) {
+		lines.push("");
+		lines.push("Restart Pi afterwards to activate them.");
+	}
+	return lines.join("\n");
+}
+
+async function installSelected(
+	ctx: ExtensionCommandContext,
+	selected: readonly ToppingStatus[],
+	install: ToppingInstaller,
+): Promise<{ succeeded: string[]; failed: FailedInstall[] }> {
+	const succeeded: string[] = [];
+	const failed: FailedInstall[] = [];
+	for (const { topping } of selected) {
+		const spec = `npm:${topping.pkg}`;
+		ctx.ui.notify(`Installing ${spec}…`, "info");
+		try {
+			const result = await install(spec, INSTALL_TIMEOUT_MS);
+			if (result.code === 0) {
+				succeeded.push(spec);
+			} else {
+				failed.push({ spec, error: stripControlChars((result.stderr || result.stdout || `exit ${result.code}`).trim()).slice(0, STDERR_SNIPPET_CHARS) });
+			}
+		} catch (error) {
+			failed.push({ spec, error: stripControlChars(errorMessage(error)).slice(0, STDERR_SNIPPET_CHARS) });
+		}
+	}
+	return { succeeded, failed };
+}
+
+export function registerSetupCommand(pi: ExtensionAPI, install: ToppingInstaller = spawnPiInstall): void {
+	pi.registerCommand("topping-setup", {
+		description: "Install missing Pi Topping sibling extensions or manage the missing-extension notice.",
+		handler: async (args, ctx) => {
+			const action = args.trim();
+			if (action === "disable-side-toppings-check" || action === "enable-side-toppings-check") {
+				try {
+					const disabled = action === "disable-side-toppings-check";
+					setSetupCheckDisabled(disabled);
+					ctx.ui.notify(
+						disabled
+							? "Missing topping check disabled. Run `/topping-setup enable-side-toppings-check` to re-enable it."
+							: "Missing topping check enabled.",
+						"info",
+					);
+				} catch {
+					ctx.ui.notify(`Failed to ${action === "disable-side-toppings-check" ? "disable" : "enable"} the missing topping check.`, "error");
+				}
+				return;
+			}
+			if (action) {
+				ctx.ui.notify("Usage: /topping-setup [disable-side-toppings-check|enable-side-toppings-check]", "error");
+				return;
+			}
+
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/topping-setup requires TUI mode", "error");
+				return;
+			}
+
+			const missing = findMissingToppings(pi);
+			if (missing.length === 0) {
+				ctx.ui.notify("All Pi Topping extensions are already active in this session.", "info");
+				return;
+			}
+
+			const result = await showMenu<Record<string, boolean>>(ctx, {
+				title: "Pi Topping: Setup",
+				sections: [
+					{
+						title: "Missing Toppings",
+						items: missing.map(({ topping, onDisk }) => ({
+							id: topping.pkg,
+							label: `${topping.pkg}${onDisk ? " (on disk, not active)" : ""}`,
+							value: true,
+						})),
+					},
+				],
+				hints: ["↑↓ move", "␣ toggle", "⏎ install", "esc cancel"],
+				previewTitle: "Description",
+				preview: (_values, _elapsedMs, activeItemId) => ({ lines: renderDescription(missing, activeItemId) }),
+			});
+			if (!result.applied) {
+				ctx.ui.notify("Pi Topping setup cancelled.", "info");
+				return;
+			}
+
+			const selected = selectedToppings(missing, result.values);
+			if (selected.length === 0) {
+				ctx.ui.notify("No Pi Topping extensions selected.", "info");
+				return;
+			}
+
+			const { succeeded, failed } = await installSelected(ctx, selected, install);
+			ctx.ui.notify(buildReport(succeeded, failed), failed.length > 0 ? "warning" : "info");
+		},
+	});
+}

package/src/toppings.ts

@@ -0,0 +1,158 @@
+import { getAgentDir, type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isSetupCheckDisabled } from "./setup-check.ts";
+import { isPlainObject } from "./util.ts";
+
+export interface Topping {
+	readonly pkg: string;
+	readonly matches: RegExp;
+	readonly dir: string;
+	readonly provides: string;
+}
+
+export interface ToppingStatus {
+	readonly topping: Topping;
+	readonly active: boolean;
+	readonly onDisk: boolean;
+}
+
+export const TOPPINGS: readonly Topping[] = [
+	{
+		pkg: "@underactive/pi-topping-statusline",
+		matches: /pi-topping-statusline/i,
+		dir: "pi-topping-statusline",
+		provides: "status line customization",
+	},
+	{
+		pkg: "@underactive/pi-topping-splash",
+		matches: /pi-topping-splash/i,
+		dir: "pi-topping-splash",
+		provides: "startup splash screen",
+	},
+	{
+		pkg: "@underactive/pi-topping-persona-audit",
+		matches: /pi-topping-persona-audit/i,
+		dir: "pi-topping-persona-audit",
+		provides: "persona audit tools",
+	},
+	{
+		pkg: "@underactive/pi-topping-web-tools",
+		matches: /pi-topping-web-tools/i,
+		dir: "pi-topping-web-tools",
+		provides: "web research and browser automation",
+	},
+];
+
+interface PiSettings {
+	packages?: unknown;
+	extensions?: unknown;
+}
+
+interface SettingsToppingState {
+	packageInstalled: boolean;
+	extensionPresent: boolean;
+	extensionActive: boolean;
+}
+
+let setupNoticeHandled = false;
+
+function stringEntries(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function readPiSettings(): PiSettings | undefined {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(join(getAgentDir(), "settings.json"), "utf8"));
+		return isPlainObject(parsed) ? parsed as PiSettings : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function extensionEntry(entry: string): { value: string; disabled: boolean } {
+	const value = entry.trim();
+	if (value.startsWith("+") || value.startsWith("-")) return { value: value.slice(1), disabled: value.startsWith("-") };
+	return { value, disabled: false };
+}
+
+function settingsState(settings: PiSettings | undefined, topping: Topping): SettingsToppingState {
+	let packageInstalled = false;
+	let extensionPresent = false;
+	let extensionActive = false;
+	for (const entry of stringEntries(settings?.packages)) {
+		if (topping.matches.test(entry)) packageInstalled = true;
+	}
+	for (const entry of stringEntries(settings?.extensions)) {
+		const normalized = extensionEntry(entry);
+		if (!topping.matches.test(normalized.value)) continue;
+		extensionPresent = true;
+		if (!normalized.disabled) extensionActive = true;
+	}
+	return { packageInstalled, extensionPresent, extensionActive };
+}
+
+function runtimeActiveToppings(pi: ExtensionAPI): Array<true | undefined> | undefined {
+	try {
+		const commands = pi.getCommands();
+		return TOPPINGS.map((topping) =>
+			commands.some((command) =>
+				command.source === "extension" && topping.matches.test(command.sourceInfo.path),
+			)
+				? true
+				: undefined,
+		);
+	} catch {
+		// The extension runtime has not yet been bound during initial load.
+		return undefined;
+	}
+}
+
+export function detectToppings(pi: ExtensionAPI): ToppingStatus[] {
+	const runtime = runtimeActiveToppings(pi);
+	const settings = readPiSettings();
+	const extensionsDir = join(getAgentDir(), "extensions");
+	return TOPPINGS.map((topping, index) => {
+		const configured = settingsState(settings, topping);
+		const checkoutPresent = existsSync(join(extensionsDir, topping.dir));
+		const onDisk = configured.packageInstalled || configured.extensionPresent || checkoutPresent;
+		const fallbackActive = configured.packageInstalled || configured.extensionActive || checkoutPresent;
+		return { topping, active: runtime?.[index] ?? fallbackActive, onDisk };
+	});
+}
+
+export function findMissingToppings(pi: ExtensionAPI): ToppingStatus[] {
+	return detectToppings(pi).filter((status) => !status.active);
+}
+
+function renderMissingBanner(missing: readonly ToppingStatus[]): string {
+	const title = `pi-topping: ${missing.length} topping extensions missing`;
+	const body = [
+		...missing.map(({ topping }) => `• ${topping.pkg} — ${topping.provides}`),
+		"",
+		"Run `/topping-setup` to selectively install them",
+		"Run `/topping-setup disable-side-toppings-check` to suppress this message",
+	];
+	const width = Math.max(title.length + 6, ...body.map((line) => line.length + 4));
+	const blankRow = `│${" ".repeat(width - 2)}│`;
+	return [
+		`╭─ ${title} ${"─".repeat(width - title.length - 5)}╮`,
+		blankRow,
+		...body.map((line) => `│ ${line.padEnd(width - 4)} │`),
+		blankRow,
+		`╰${"─".repeat(width - 2)}╯`,
+	].join("\n");
+}
+
+export function notifyMissingToppingsOnce(pi: ExtensionAPI, ui: Pick<ExtensionUIContext, "notify">): void {
+	if (setupNoticeHandled) return;
+	setupNoticeHandled = true;
+	if (isSetupCheckDisabled()) return;
+	const missing = findMissingToppings(pi);
+	if (missing.length > 0) ui.notify(`\n${renderMissingBanner(missing)}`, "warning");
+}
+
+/** Test-only reset for the once-per-process session-start notice. */
+export function __resetSetupNotice(): void {
+	setupNoticeHandled = false;
+}

package/src/util.ts

@@ -0,0 +1,9 @@
+/** True for object records, excluding arrays and null. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Strip control and formatting characters from untrusted single-line text. */
+export function stripControlChars(text: string): string {
+	return text.replace(/[\p{Cc}\p{Cf}]/gu, "");
+}