one-code-extension 0.4.0 → 0.5.0

package/extensions/plan-mode/viewer.ts

@@ -6,18 +6,54 @@
  *
  * Every rendered line must stay within the width given: pi-tui crashes the
  * whole app on an overwide line. Content is wrapped (not truncated — a plan
- * must stay readable in full), and chrome lines are cut plain-text *before*
- * painting so ANSI escapes never confuse the width accounting.
+ * must stay readable in full) and then cut ANSI-aware as a guard, and chrome
+ * lines are cut plain-text *before* painting so ANSI escapes never confuse
+ * the width accounting.
  */
 
-import { cutPlainText } from "../lib/tui-render.ts";
+import { cutPlainText, hintLines, truncateLine, wrapProse } from "../lib/tui-render.ts";
+import { keyId } from "../lib/key-input.ts";
 
-/** Hard-wrap plain text to `width` columns, preserving blank lines. */
-export { wrapPlainText as wrapPlanText } from "../lib/tui-render.ts";
+/** Renders Markdown to painted lines at a width (pi-tui's Markdown, which the transcript uses). */
+export type PlanMarkdown = (text: string, width: number) => string[];
+
+/**
+ * The plan's lines at `width`: Markdown rendered the way the transcript renders
+ * assistant text when a renderer is available, else plain text wrapped at word
+ * boundaries. A renderer that throws falls back to the plain wrap, so a
+ * Markdown failure never costs the user the plan.
+ */
+export function planLines(plan: string, width: number, markdown?: PlanMarkdown): string[] {
+	if (markdown) {
+		try {
+			return markdown(plan, width);
+		} catch {
+			// fall through to the plain wrap
+		}
+	}
+	return wrapProse(plan, width);
+}
 
 /** What the dialog resolves to; index into the choices list, or null for cancel. */
 export type PlanChoice = number;
 
+/**
+ * The approval through a plain select, for RPC: its `custom()` resolves
+ * undefined (findings §8), which read as "dismissed" and rejected every plan.
+ * The plan rides in the title; a reply that is no choice is a dismissal.
+ */
+export async function selectPlanChoice(
+	ui: { select(title: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined> },
+	plan: string,
+	path: string,
+	choices: string[],
+	signal?: AbortSignal,
+): Promise<PlanChoice | null> {
+	const label = await ui.select(`Plan (${path}):\n\n${plan}\n\nApprove the plan?`, choices, { signal });
+	const index = signal?.aborted || label === undefined ? -1 : choices.indexOf(label);
+	return index >= 0 ? index : null;
+}
+
 export type ViewerKey =
 	| { kind: "scroll"; delta: number }
 	| { kind: "choice"; delta: number }
@@ -32,33 +68,29 @@ export type ViewerKey =
  * classifier model is reachable).
  */
 export function decodeViewerKey(data: string, page: number): ViewerKey | undefined {
-	switch (data) {
-		case "\x1b[A":
-		case "\x1bOA":
+	const id = keyId(data);
+	switch (id) {
+		case "up":
 			return { kind: "scroll", delta: -1 };
-		case "\x1b[B":
-		case "\x1bOB":
+		case "down":
 			return { kind: "scroll", delta: 1 };
-		case "\x1b[5~":
+		case "pageUp":
 			return { kind: "scroll", delta: -page };
-		case "\x1b[6~":
+		case "pageDown":
 			return { kind: "scroll", delta: page };
-		case "\x1b[D":
-		case "\x1bOD":
+		case "left":
 			return { kind: "choice", delta: -1 };
-		case "\x1b[C":
-		case "\x1bOC":
-		case "\t":
+		case "right":
+		case "tab":
 			return { kind: "choice", delta: 1 };
-		case "\r":
-		case "\n":
+		case "enter":
 			return { kind: "confirm" };
-		case "\x1b":
-		case "\x03": // ctrl+c — same intent as escape while the dialog is focused
+		case "escape":
+		case "ctrl+c": // same intent as escape while the dialog is focused
 			return { kind: "cancel" };
 		default:
-			if (data.length === 1 && data >= "1" && data <= "9") {
-				return { kind: "pick", index: Number(data) - 1 };
+			if (id && id.length === 1 && id >= "1" && id <= "9") {
+				return { kind: "pick", index: Number(id) - 1 };
 			}
 			return undefined;
 	}
@@ -90,7 +122,7 @@ export function initialPlanChoice(options: readonly { mode?: string; restore?: b
 export type Paint = (color: string, text: string) => string;
 
 export interface PlanViewerView {
-	/** Pre-wrapped plain-text plan lines (wrapPlanText output for this width). */
+	/** The plan's lines for this width (planLines output: painted Markdown or plain wrapped text). */
 	lines: string[];
 	offset: number;
 	choice: PlanChoice;
@@ -103,18 +135,20 @@ export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: numb
 	const maxVisible = view.maxVisible ?? 12;
 	// Cut plain text before painting so escapes never enter the width math.
 	const cut = (line: string) => cutPlainText(line, width);
-	const rule = paint("dim", "─".repeat(Math.max(0, Math.min(width, 72))));
+	const rule = paint("dim", "─".repeat(Math.max(0, width)));
 	const pickHint = view.choices.length > 1 ? `1-${view.choices.length} pick · ` : "";
 
 	const out: string[] = [];
 	out.push("");
 	out.push(paint("accent", cut("Approve this plan?")));
-	out.push(paint("dim", cut(`↑/↓ scroll · ←/→ switch choice · ${pickHint}enter confirm · esc keep planning`)));
+	// Each hint sits beside what its keys move: scrolling above the plan, choosing under the choices.
+	out.push(paint("dim", cut("↑/↓ scroll the plan")));
 	out.push(rule);
 
+	// Plan lines may arrive painted (Markdown), so the guard cut is ANSI-aware.
 	const offset = clampOffset(view.offset, view.lines.length, maxVisible);
 	for (const line of view.lines.slice(offset, offset + maxVisible)) {
-		out.push(cut(line));
+		out.push(truncateLine(line, width));
 	}
 	if (view.lines.length > maxVisible) {
 		const last = Math.min(view.lines.length, offset + maxVisible);
@@ -128,6 +162,37 @@ export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: numb
 			index === view.choice ? paint("accent", cut(`❯ ${numbered}`)) : cut(`  ${numbered}`),
 		);
 	}
+	// The keys wrap at their separators on a narrow terminal, so "esc cancel" is never cut.
+	out.push(...hintLines(`←/→ choose · ${pickHint}enter confirm · esc cancel`, width).map((line) => paint("dim", line)));
 	out.push("");
 	return out;
 }
+
+/** The question the keep-planning choice asks (Claude Code's placeholder, naming the agent). */
+export const KEEP_PLANNING_QUESTION = "Tell the agent what to change";
+
+/** How the approval ended: an approving choice, or a rejection carrying the user's words when they gave some. */
+export type PlanDecision = { kind: "approve"; index: PlanChoice } | { kind: "reject"; feedback?: string };
+
+/**
+ * The approval flow, as in Claude Code: keeping planning asks what to change,
+ * and those words go back to the model, which keeps planning. A blank answer
+ * returns to the dialog (Claude Code ignores Enter on an empty "keep planning"
+ * input). Esc on the dialog or on the question rejects without words, which
+ * stops the turn. The option without a mode is the keep-planning one.
+ */
+export async function runPlanApproval(
+	options: readonly { mode?: string }[],
+	showDialog: () => Promise<PlanChoice | null>,
+	askFeedback: () => Promise<string | undefined>,
+	signal?: AbortSignal,
+): Promise<PlanDecision> {
+	for (;;) {
+		const choice = await showDialog();
+		if (choice == null || signal?.aborted) return { kind: "reject" };
+		if (options[choice]?.mode) return { kind: "approve", index: choice };
+		const feedback = await askFeedback();
+		if (feedback === undefined || signal?.aborted) return { kind: "reject" };
+		if (feedback.trim()) return { kind: "reject", feedback: feedback.trim() };
+	}
+}

package/extensions/plugins/counts.ts

@@ -48,9 +48,9 @@ export async function fetchInstallCounts(root: string, now: Date = new Date()):
 	if (cached) return cached;
 
 	try {
-		const response = await fetchWithTimeout(INSTALL_COUNTS_URL, FETCH_TIMEOUT_MS);
-		if (!response.ok) return undefined;
-		const counts = (await response.json()) as CountsCache["counts"];
+		const counts = await fetchWithTimeout(INSTALL_COUNTS_URL, FETCH_TIMEOUT_MS, async (response) =>
+			response.ok ? ((await response.json()) as CountsCache["counts"]) : undefined,
+		);
 		if (!Array.isArray(counts)) return undefined;
 		writeJsonAtomic(join(root, CACHE_FILE), { version: 1, fetchedAt: now.toISOString(), counts } satisfies CountsCache);
 		return toMap(counts);

package/extensions/plugins/index.ts

@@ -16,14 +16,16 @@
  * ~/.claude is read-only here, always.
  */
 
-import { execFile } from "node:child_process";
 import { readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { promisify } from "node:util";
+import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readFavorites, toggleFavorite } from "../lib/favorites.ts";
+import { announceArgumentHint, type CommandHint, frontmatterCommandHint } from "../lib/argument-hints.ts";
 import { MCP_STATUS_CHANNEL, MCP_STATUS_REQUEST_CHANNEL, type McpStatusEvent } from "../lib/mcp-status.ts";
+import { canShowCustomUi, notifyOrPrint, notifyRpcReadOnly } from "../lib/headless-output.ts";
+import { createUserMessageSender, sessionOutlivesTurn } from "../lib/notifications.ts";
+import { ONE_SHOT_COMMAND_FAILED_CHANNEL } from "../lib/interrupt.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
 import { setOverride } from "../lib/plugin-overrides.ts";
 import { pathWithinBase, pluginRoot } from "../lib/plugin-root.ts";
@@ -62,13 +64,15 @@ import { decodePanelKey } from "./panel/keys.ts";
 import { type DiscoverDetail, renderPanel, type PanelPaint } from "./panel/render.ts";
 import { buildDiscoverRows, buildInstalledRows, buildMarketplaceRows, type DiscoverRow } from "./panel/rows.ts";
 import { applyPanelKey, initialPanelState, type PanelEffect, type PanelView } from "./panel/state.ts";
-import { findShellPlaceholders, replaceShellPlaceholders, substituteArguments } from "./template.ts";
+import { expandTemplate, runPlaceholderCommand } from "./shell-expand.ts";
+import { watchPermissionBridge } from "../permissions/subagent-gate.ts";
+import { followWorkCwd } from "../lib/worktree-channel.ts";
 import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
+import { promptCommandText } from "../skill/invoke.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 
-const run = promisify(execFile);
-const SHELL_TIMEOUT_MS = 30_000;
 
 // The panel is a bounded dock like Claude Code's /plugins, NOT a full-screen
 // takeover: it swaps the editor container and leaves the transcript visible
@@ -76,36 +80,6 @@ const SHELL_TIMEOUT_MS = 30_000;
 // terminals still shrink to fit. ~6 discover rows show at this cap.
 const PANEL_MAX_HEIGHT = 22;
 
-async function expandTemplate(body: string, args: string, cwd: string, persist?: { dir: string; name: string }): Promise<string> {
-	const withArgs = substituteArguments(body, args);
-	const commands = [...new Set(findShellPlaceholders(withArgs))];
-	if (commands.length === 0) return withArgs;
-
-	const outputs = new Map<string, string>();
-	await Promise.all(
-		commands.map(async (command, index) => {
-			let text: string;
-			try {
-				const { stdout, stderr } = await run(command, {
-					cwd,
-					shell: true,
-					timeout: SHELL_TIMEOUT_MS,
-					maxBuffer: 2 * 1024 * 1024,
-				});
-				text = (stdout || stderr || "").trim();
-			} catch (error) {
-				const detail = error as { stdout?: string; stderr?: string; message?: string };
-				text = (detail.stdout || detail.stderr || detail.message || "command failed").trim();
-			}
-			// A `!`command's output (a `git diff` of a large change) lands in the
-			// user turn bounded only by maxBuffer — persist it past the cap so the
-			// model gets a preview plus the path, never a wall of text (review L3).
-			outputs.set(command, persist ? persistIfLarge(text, { dir: persist.dir, id: `plugin-cmd-${persist.name}-${index}` }) : text);
-		}),
-	);
-	return replaceShellPlaceholders(withArgs, outputs);
-}
-
 /** An empty discovery result — the fallback when a scan throws. */
 function emptyDiscovered(): DiscoveredPlugins {
 	return {
@@ -136,6 +110,9 @@ function safeDiscover(roots: ReturnType<typeof defaultDiscoverRoots>): Discovere
 }
 
 export default function pluginsExtension(pi: ExtensionAPI) {
+	const sendUserMessage = createUserMessageSender(pi);
+	const getPermissionBridge = watchPermissionBridge(pi);
+	const workCwd = followWorkCwd(pi.events);
 	// False once the session is replaced: a panel action still awaiting then
 	// throws on its first pi.* call, which is expected and not an error to show.
 	const alive = sessionAlive(pi);
@@ -155,7 +132,7 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 				plugins.plugins.find((p) => p.name === command.plugin);
 			if (!plugin) continue;
 			registeredCommands.add(command.name);
-			registerPluginCommand(pi, plugin, command.name, command.path);
+			registerPluginCommand(pi, plugin, command.name, command.path, sendUserMessage, getPermissionBridge, workCwd);
 		}
 	};
 
@@ -183,7 +160,7 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 		panelOpen = true;
 		let restartNotice = false;
 		try {
-			await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+			await panelUi(pi.events, ctx.ui).custom<null>((tui, theme, _keybindings, done) => {
 				const paint: PanelPaint = {
 					fg: safeThemePaint(theme),
 					bold: safeThemeBold(theme),
@@ -522,10 +499,11 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 	registerLocalCommand(pi, "plugins", {
 		description: "Browse, install, and manage Claude Code-compatible plugins and marketplaces",
 		handler: async (args, ctx) => {
-			if (ctx.hasUI) {
+			if (canShowCustomUi(ctx)) {
 				await openPanel(ctx);
 				return;
 			}
+			notifyRpcReadOnly(ctx, "/plugins", "install or manage plugins and marketplaces");
 			// Non-interactive fallback: the old text listing.
 			if (discovered.plugins.length === 0) {
 				ctx.ui.notify("No plugins installed.", "info");
@@ -547,34 +525,71 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 	});
 }
 
-function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, path: string): void {
+function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, path: string, sendUserMessage: ReturnType<typeof createUserMessageSender>, getPermissionBridge: ReturnType<typeof watchPermissionBridge>, workCwd: (sessionCwd: string) => string): void {
 	let description = `Command from the ${plugin.name} plugin`;
-	let argumentHint: string | undefined;
+	let argumentHint: CommandHint | undefined;
 	try {
 		const { frontmatter } = parseFrontmatterLoosely(readFileSync(path, "utf-8")) as {
 			frontmatter?: Record<string, unknown>;
 		};
 		if (typeof frontmatter?.description === "string") description = frontmatter.description;
-		if (typeof frontmatter?.["argument-hint"] === "string") argumentHint = frontmatter["argument-hint"];
+		argumentHint = frontmatterCommandHint(frontmatter);
 	} catch {
 		// Fall back to the generic description.
 	}
 
+	if (argumentHint) announceArgumentHint(pi, name, argumentHint);
 	pi.registerCommand(name, {
-		description: argumentHint ? `${description} (${argumentHint})` : description,
+		description: argumentHint?.hint ? `${description} (${argumentHint.hint})` : description,
 		handler: async (args, ctx) => {
+			// Registered commands cannot be removed from pi. Resolve their live
+			// owner and path on invocation, after toggles, updates or a cwd change.
+			const current = safeDiscover(defaultDiscoverRoots(getAgentDir(), ctx.cwd));
+			const command = current.commands.find((entry) => entry.name === name);
+			const plugin = command && current.enabledPlugins.find((entry) =>
+				entry.name === command.plugin && dirname(command.path) === join(entry.path, "commands"),
+			);
+			if (!command || !plugin) {
+				notifyOrPrint(ctx, `/${name} is unavailable in this project. Enable or reinstall its plugin in /plugins, then retry.`, "error");
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
+				return;
+			}
+			const path = command.path;
 			let body: string;
 			try {
 				const parsed = parseFrontmatterLoosely(readFileSync(path, "utf-8")) as { body: string };
 				body = parsed.body;
 			} catch (error) {
-				ctx.ui.notify(`Could not read ${path}: ${(error as Error).message}`, "error");
+				notifyOrPrint(ctx, `Could not read ${path}: ${(error as Error).message}. Restore the command file or reinstall the ${plugin.name} plugin, then retry.`, "error");
+				// A one-shot run must not exit 0 for a command that never ran (exit/index.ts).
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
+				return;
+			}
+			// A `!`command's output (a `git diff` of a large change) lands in the
+			// user turn: persist it past the cap so the model gets a preview plus
+			// the path, never a wall of text (review L3).
+			const dir = sessionResultsDir(ctx);
+			let expanded: string;
+			try {
+				// Placeholders run where the session works: an entered worktree, not the checkout it left.
+				expanded = await expandTemplate(body, args, workCwd(ctx.cwd), {
+					persist: (text, index) => persistIfLarge(text, { dir, id: `plugin-cmd-${name}-${index}` }),
+					run: async (command, cwd) => {
+						const decide = getPermissionBridge();
+						if (!decide) throw new Error("The permission gate is unavailable. Load the permissions extension before running shell placeholders.");
+						const decision = await decide({ toolName: "bash", input: { command }, cwd, model: ctx.model });
+						if (decision?.block) throw new Error(`Shell placeholder blocked: ${decision.reason}`);
+						return runPlaceholderCommand(command, cwd);
+					},
+				});
+			} catch (error) {
+				notifyOrPrint(ctx, `Could not expand /${name}: ${(error as Error).message}`, "error");
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
 				return;
 			}
-			const expanded = await expandTemplate(body, args, ctx.cwd, { dir: sessionResultsDir(ctx), name });
 			recordUsage(pluginRoot(getAgentDir()), "command", name);
 			// Deliver as a user turn, which is how Claude Code runs a command template.
-			pi.sendUserMessage(expanded);
+			await sendUserMessage(ctx, promptCommandText(name, args.trim(), expanded));
 		},
 	});
 }

package/extensions/plugins/install/install.ts

@@ -18,6 +18,7 @@ import { gitClone, gitHeadSha } from "../marketplace/git.ts";
 import type { MarketplaceEntry } from "../marketplace/types.ts";
 import { addInstalledPlugin, installedEntry, removeInstalledPlugin } from "./registry.ts";
 import { pluginCacheDir, versionedCachePath, withinBase } from "./paths.ts";
+import { loadInstalledPlugins, validPluginName } from "../../lib/plugins.ts";
 
 export interface InstallResult {
 	id: string;
@@ -82,6 +83,7 @@ export async function installPlugin(
 	contentRoot: string | undefined,
 ): Promise<InstallResult> {
 	const id = `${entry.name}@${marketplaceName}`;
+	if (validPluginName(entry.name) !== entry.name) throw new Error(`${id}: invalid plugin name — refusing to install`);
 	const raw = entry.raw;
 	if (raw.dependencies !== undefined) {
 		throw new Error(`${id}: plugin dependencies are not supported yet — install the dependencies manually first`);
@@ -99,6 +101,9 @@ export async function installPlugin(
 		}
 		sourceDir = resolve(contentRoot, source);
 		if (!existsSync(sourceDir)) throw new Error(`${id}: source path "${source}" does not exist in the marketplace`);
+		if (!withinBase(realpathSync(contentRoot), realpathSync(sourceDir))) {
+			throw new Error(`${id}: source path "${source}" escapes the marketplace directory through a symlink — refusing to install`);
+		}
 	} else if (source.source === "github" || source.source === "url" || source.source === "git-subdir") {
 		if (source.sha) {
 			throw new Error(`${id}: commit-sha pinning is not supported yet — use a ref (branch/tag) instead`);
@@ -121,6 +126,10 @@ export async function installPlugin(
 			rmSync(temp, { recursive: true, force: true });
 			throw new Error(`${id}: "${source.source === "git-subdir" ? source.path : url}" has no content at the expected path`);
 		}
+		if (source.source === "git-subdir" && !withinBase(realpathSync(cloneDir), realpathSync(sourceDir))) {
+			rmSync(temp, { recursive: true, force: true });
+			throw new Error(`${id}: git-subdir path "${source.path}" escapes the repository through a symlink — refusing to install`);
+		}
 	} else {
 		throw new Error(`${id}: source kind "${(source as { source: string }).source}" is not supported`);
 	}
@@ -137,6 +146,13 @@ export async function installPlugin(
 		if (!withinBase(pluginCacheBase, installPath)) {
 			throw new Error(`${id}: computed install path "${installPath}" escapes the plugin cache directory — refusing to install`);
 		}
+		// Sanitization is lossy (a.b and a-b share a cache segment). Never
+		// replace files that another registered plugin still owns.
+		if (existsSync(installPath)) {
+			const target = realpathSync(installPath);
+			const owner = loadInstalledPlugins(root).find((plugin) => plugin.id !== id && realpathSync(plugin.path) === target);
+			if (owner) throw new Error(`${id}: cache path "${installPath}" is already owned by ${owner.id} — refusing to overwrite it`);
+		}
 		copyIntoCache(sourceDir, installPath);
 		const now = new Date().toISOString();
 		addInstalledPlugin(root, id, {

package/extensions/plugins/marketplace/sync.ts

@@ -46,9 +46,15 @@ function cloneUrl(source: MarketplaceSource): string | undefined {
 const FETCH_TIMEOUT_MS = 10_000;
 
 async function fetchManifestJson(url: string): Promise<unknown> {
-	const response = await fetchWithTimeout(url, FETCH_TIMEOUT_MS, { headers: { "user-agent": "one-code-plugins" } });
-	if (!response.ok) throw new Error(`HTTP ${response.status}`);
-	return await response.json();
+	return fetchWithTimeout(
+		url,
+		FETCH_TIMEOUT_MS,
+		async (response) => {
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			return (await response.json()) as unknown;
+		},
+		{ init: { headers: { "user-agent": "one-code-plugins" } } },
+	);
 }
 
 /**

package/extensions/plugins/marketplace/types.ts

@@ -8,6 +8,8 @@
  * entry never blanks the rest of the marketplace.
  */
 
+import { validPluginName } from "../../lib/plugins.ts";
+
 export type MarketplaceSource =
 	| { source: "github"; repo: string; ref?: string }
 	| { source: "git"; url: string; ref?: string }
@@ -81,7 +83,7 @@ export function parseMarketplaceManifest(raw: unknown): { manifest?: Marketplace
 
 	const plugins: MarketplaceEntry[] = [];
 	for (const [index, entry] of raw.plugins.entries()) {
-		if (!isRecord(entry) || typeof entry.name !== "string" || entry.name.length === 0 || entry.name.includes(" ")) {
+		if (!isRecord(entry) || typeof entry.name !== "string" || validPluginName(entry.name) !== entry.name) {
 			errors.push(`plugins[${index}]: missing or invalid "name" — entry skipped`);
 			continue;
 		}

package/extensions/plugins/panel/keys.ts

@@ -1,52 +1,49 @@
 /**
- * Raw-byte key decoding for the /plugins panel (pure).
+ * Key decoding for the /plugins panel (pure), named through
+ * `lib/key-input.ts` so every terminal encoding of a key decodes alike.
  *
- * Navigation bytes are always controls; any other printable input is a `text`
+ * Navigation keys are always controls; any other printable input is a `text`
  * intent the state layer routes (search box, Add Marketplace draft, or a
  * single-letter action where the active view has no text field). Unrecognized
  * escape sequences are swallowed so they never leak into a draft.
  */
 
+import { keyId, keyText } from "../../lib/key-input.ts";
+
 export type PanelKey =
 	| { kind: "up" | "down" | "pageUp" | "pageDown" | "nextTab" | "prevTab" | "enter" | "back" | "space" | "backspace" | "close" }
 	| { kind: "text"; text: string };
 
 export function decodePanelKey(data: string): PanelKey | undefined {
-	switch (data) {
-		case "\x1b[A":
-		case "\x1bOA":
+	switch (keyId(data)) {
+		case "up":
 			return { kind: "up" };
-		case "\x1b[B":
-		case "\x1bOB":
+		case "down":
 			return { kind: "down" };
-		case "\x1b[5~":
+		case "pageUp":
 			return { kind: "pageUp" };
-		case "\x1b[6~":
+		case "pageDown":
 			return { kind: "pageDown" };
-		case "\x1b[C":
-		case "\x1bOC":
-		case "\t":
+		case "right":
+		case "tab":
 			return { kind: "nextTab" };
-		case "\x1b[D":
-		case "\x1bOD":
-		case "\x1b[Z":
+		case "left":
+		case "shift+tab":
 			return { kind: "prevTab" };
-		case "\r":
-		case "\n":
+		case "enter":
 			return { kind: "enter" };
-		case "\x1b":
+		case "escape":
 			return { kind: "back" };
-		case " ":
+		case "space":
 			return { kind: "space" };
-		case "\x7f":
-		case "\b":
+		case "backspace":
+		case "ctrl+backspace":
 			return { kind: "backspace" };
-		case "\x03": // ctrl+c
+		case "ctrl+c":
 			return { kind: "close" };
 		default:
 			break;
 	}
-	if (data.startsWith("\x1b")) return undefined;
-	const text = [...data].filter((ch) => ch >= " " && ch !== "\x7f").join("");
+	const text = keyText(data);
 	return text ? { kind: "text", text } : undefined;
 }

package/extensions/plugins/panel/render.ts

@@ -7,7 +7,7 @@
  */
 
 import { formatInstallCount } from "../counts.ts";
-import { cutPlainText, panelTopRule, type RenderBlock as Block, searchBoxLines, windowBlocks } from "../../lib/tui-render.ts";
+import { cutPlainText, hintLines, panelTopRule, type RenderBlock as Block, searchBoxLines, windowBlocks } from "../../lib/tui-render.ts";
 import type { DiscoverRow, InstalledRow } from "./rows.ts";
 import { clampPanelState, type PanelState, type PanelView, resolveDetail, selectableRows, TABS, type Tab } from "./state.ts";
 
@@ -176,7 +176,7 @@ function detailLines(input: PanelRenderInput, paint: PanelPaint): { lines: strin
 		const discover = row as DiscoverRow;
 		const detail = input.discoverDetails.get(discover.id);
 		push(`${discover.name} · ${discover.marketplace}`, paint.bold);
-		if (discover.description) push(discover.description);
+		if (discover.description) for (const line of wrapNote(discover.description, width - 4)) push(line);
 		push("");
 		if (detail?.version) push(`Version: ${detail.version}`, (t) => paint.fg("dim", t));
 		if (detail?.author) push(`Author: ${detail.author}`, (t) => paint.fg("dim", t));
@@ -250,20 +250,26 @@ const FOOTERS: Record<Tab, string[]> = {
 /** Installed search hints while the `/` box is open (Esc leaves it). */
 const INSTALLED_SEARCH_FOOTER = ["Type to search · Enter/Space to toggle · Esc to leave search"];
 
+/** Footer hint lines wrapped at their separators to the panel's width (one leading space), so no key is cut off. */
+function fitFooter(lines: string[], width: number): string[] {
+	return hintLines(lines, width - 1, " ");
+}
+
 export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[] {
 	const { state, view, width, height } = input;
 	clampPanelState(state, view);
 
 	const out: string[] = [panelTopRule(paint.fg, width), tabBar(state, view, paint, width), ""];
+	// Wrapped to the width where it is set: the list counts its lines for the budget.
 	let footer: string[];
 
 	if (state.addDialog) {
 		out.push(...addDialogLines(state.addDialog.draft, paint, width));
-		footer = ["Enter to add · Esc to cancel"];
+		footer = fitFooter(["Enter to add · Esc to cancel"], width);
 	} else if (state.detail) {
 		const detail = detailLines(input, paint);
 		out.push(...detail.lines);
-		footer = [detail.footer];
+		footer = fitFooter([detail.footer], width);
 	} else {
 		let blocks: Block[];
 		switch (state.tab) {
@@ -293,7 +299,7 @@ export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[
 				break;
 			}
 		}
-		footer = state.tab === "installed" && state.installedSearching ? INSTALLED_SEARCH_FOOTER : FOOTERS[state.tab];
+		footer = fitFooter(state.tab === "installed" && state.installedSearching ? INSTALLED_SEARCH_FOOTER : FOOTERS[state.tab], width);
 		const budget = Math.max(3, height - out.length - 2 - footer.length);
 		const windowed = windowBlocks(blocks, state.cursor[state.tab], budget);
 		out.push(...windowed.lines);
@@ -310,6 +316,6 @@ export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[
 			),
 		);
 	}
-	out.push("", ...footer.map((line) => paint.fg("dim", cutPlainText(` ${line}`, width - 1))));
+	out.push("", ...footer.map((line) => paint.fg("dim", line)));
 	return out;
 }