@jmcombs/pi-context7 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Combs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @jmcombs/pi-EXTENSION_NAME
+
+> TODO: One-paragraph description of what this extension does and who it is
+> for. Mention the tools and/or commands it provides.
+
+## Install
+
+```bash
+# Globally (recommended)
+pi install npm:@jmcombs/pi-EXTENSION_NAME
+
+# For a single session, without installing
+pi -e npm:@jmcombs/pi-EXTENSION_NAME
+```
+
+See the [Pi packages documentation](https://pi.dev/docs/packages) for git, local
+path, project-scoped install, and filtering options.
+
+## What It Adds
+
+- **Tool**: `example_echo` — TODO: describe the tool, its parameters, and what
+  the LLM uses it for.
+- **Command**: `/example-hello [name]` — TODO: describe the command and any
+  arguments.
+
+## Configuration
+
+<!-- Delete this section if your extension does not need any configuration. -->
+
+### API Keys / Secrets
+
+If this extension calls a third-party service, store the credential using one
+of Pi's recommended auth storage methods. **Never** hard-code API keys or commit
+them to source control.
+
+#### Option 1 — Environment variable
+
+```bash
+export EXAMPLE_API_KEY="…"
+```
+
+#### Option 2 — `~/.pi/agent/auth.json`
+
+```json
+{
+  "example": {
+    "type": "api_key",
+    "key": "EXAMPLE_API_KEY"
+  }
+}
+```
+
+#### Option 3 — Shell-resolved secret (macOS Keychain, 1Password, pass, etc.)
+
+```json
+{
+  "example": {
+    "type": "api_key",
+    "key": "!security find-generic-password -ws 'example'"
+  }
+}
+```
+
+```json
+{
+  "example": {
+    "type": "api_key",
+    "key": "!op read 'op://Personal/example/credential'"
+  }
+}
+```
+
+The extension reads the key with:
+
+```ts
+import { AuthStorage } from "@earendil-works/pi-coding-agent";
+const auth = AuthStorage.create();
+const apiKey = (await auth.getApiKey("example")) ?? process.env.EXAMPLE_API_KEY;
+```
+
+## Requirements
+
+- Pi `>= TODO: minimum tested pi version`
+- Node `>= 20.6.0`
+
+## Development
+
+This package lives in the [pi-extensions monorepo](https://github.com/jmcombs/pi-extensions).
+See `CONTRIBUTING.md` at the repo root for project conventions.
+
+```bash
+# From the repo root
+npm ci
+npm run check       # full quality gate
+npm run test        # this package's smoke test
+```
+
+To try local changes against a real Pi session:
+
+```bash
+pi -e ./packages/EXTENSION_NAME
+```
+
+## License
+
+[MIT](./LICENSE) © Jeremy Combs

package/index.ts

@@ -0,0 +1,554 @@
+/**
+ * @jmcombs/pi-context7 — Real-time documentation for the Pi coding agent via Context7.
+ *
+ * Registers `context7_search` and `context7_get_docs` tools that let the LLM
+ * find and retrieve version-aware documentation and code snippets from the
+ * Context7 API. If no Context7 API key is configured, the tool prompts the user
+ * interactively via the TUI (never leaking the key into the agent's context).
+ * The key can also be set manually by running `/context7_onboard`.
+ *
+ * Supported configuration (if not using interactive prompt):
+ *    1. `AuthStorage` under the "context7" key (`~/.pi/agent/auth.json`)
+ *    2. Auto-prompt via the TUI if no key is found
+ */
+
+import { AuthStorage, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { confirmInBorderedPopup, inputInBorderedPopup } from "./ui/bordered-popups.js";
+
+const CONTEXT7_API_BASE = "https://context7.com/api/v2";
+
+// -- Context7 API response types
+
+interface CodeSnippet {
+  codeTitle?: string;
+  codeList?: { language?: string; code?: string }[];
+}
+
+interface InfoSnippet {
+  content?: string;
+}
+
+interface Context7SearchResult {
+  id: string;
+  title: string;
+  [key: string]: unknown;
+}
+
+interface Context7SearchResponse {
+  results?: Context7SearchResult[];
+}
+
+interface Context7DocsResponse {
+  codeSnippets?: CodeSnippet[];
+  infoSnippets?: InfoSnippet[];
+  [key: string]: unknown;
+}
+
+// -- Tool parameter schemas
+
+const context7SearchSchema = Type.Object({
+  libraryName: Type.String({
+    description: "The name of the library (e.g., 'next.js', 'supabase').",
+  }),
+  query: Type.Optional(
+    Type.String({
+      description: "A specific question/topic to refine search results.",
+    }),
+  ),
+});
+export type Context7SearchInput = Static<typeof context7SearchSchema>;
+
+const context7GetDocsSchema = Type.Object({
+  libraryId: Type.String({
+    description: "The Context7 Library ID (e.g., '/vercel/next.js').",
+  }),
+  query: Type.String({
+    description: "The specific technical question or implementation pattern requested.",
+  }),
+});
+export type Context7GetDocsInput = Static<typeof context7GetDocsSchema>;
+
+// -- Helpers
+
+function formatDocs(data: Context7DocsResponse, query: string): string {
+  const { codeSnippets = [], infoSnippets = [] } = data;
+
+  if (codeSnippets.length === 0 && infoSnippets.length === 0) {
+    return "No documentation snippets found for " + query + ".";
+  }
+
+  const parts: string[] = [];
+
+  if (codeSnippets.length > 0) {
+    parts.push("--- CODE SNIPPETS ---");
+    for (const snippet of codeSnippets) {
+      if (snippet.codeTitle) {
+        parts.push("\n## " + snippet.codeTitle);
+      }
+      if (snippet.codeList && snippet.codeList.length > 0) {
+        for (const item of snippet.codeList) {
+          if (item.code) {
+            const lang = item.language ?? "typescript";
+            parts.push("```" + lang + "\n" + item.code + "\n```\n");
+          }
+        }
+      }
+    }
+  }
+
+  if (infoSnippets.length > 0) {
+    parts.push("\n--- INFO SNIPPETS ---");
+    for (const snippet of infoSnippets) {
+      if (snippet.content) {
+        parts.push("\n" + snippet.content);
+      }
+    }
+  }
+
+  return "Documentation for " + query + ":" + "\n\n" + parts.join("\n");
+}
+
+// -- Extension factory
+
+export default function (pi: ExtensionAPI): void {
+  const authStorage = AuthStorage.create();
+  // -- /context7_onboard (user-facing command)
+  pi.registerCommand("context7_onboard", {
+    description: "Securely save your Context7 API key (input never visible to LLM).",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify("Context7 Onboarding", "info");
+
+      const existing = await authStorage.getApiKey("context7");
+      if (existing) {
+        const overwrite = await confirmInBorderedPopup(ctx, {
+          title: "Context7 API key already exists, overwrite?",
+          message: "A Context7 API key is already saved. Overwrite it?",
+        });
+        if (!overwrite) {
+          ctx.ui.notify("Context7 onboarding cancelled.", "warning");
+          return;
+        }
+      }
+
+      const apiKey = await inputInBorderedPopup(ctx, {
+        title: "Context7 Onboarding",
+        prompt: "Enter your Context7 API key:",
+        helpText: "Enter to confirm • Esc = cancel",
+      });
+
+      if (!apiKey) {
+        ctx.ui.notify("Context7 onboarding cancelled.", "warning");
+        return;
+      }
+
+      authStorage.set("context7", {
+        type: "api_key" as const,
+        key: apiKey,
+      });
+      authStorage.removeRuntimeApiKey("context7");
+      const errs = authStorage.drainErrors();
+      if (errs.length > 0) {
+        ctx.ui.notify(`onboard ERRORS: ${errs.map((e) => e.message).join("; ")}`, "warning");
+      }
+      ctx.ui.notify("Context7 API key saved successfully.", "info");
+    },
+  });
+
+  // -- context7_search
+  pi.registerTool({
+    name: "context7_search",
+    label: "Context7: Find Library ID",
+    description:
+      "Use this tool to search Context7 for the correct library ID of a programming language, framework, or library. " +
+      "Call this when the user needs up-to-date documentation, code examples, configuration guidance, or implementation details for something like Supabase, React, Rust, Tailwind, Prisma, or any other programming language, framework, or library. " +
+      "Always prefer this tool over general web search when you need accurate, version-aware information for coding or development tasks.",
+    parameters: context7SearchSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      let apiKey = await authStorage.getApiKey("context7");
+
+      if (!apiKey) {
+        const entered = await inputInBorderedPopup(ctx, {
+          title: "Context7 Authentication",
+          prompt: "Enter your Context7 API key:",
+          helpText: "Enter to confirm • Esc = cancel",
+        });
+        if (!entered) {
+          ctx.ui.notify("Context7 search cancelled.", "warning");
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Search cancelled: no Context7 API key provided.",
+              },
+            ],
+            details: { error: "missing_api_key" },
+            isError: true,
+          };
+        }
+
+        // Always use the entered value for this request (supports raw keys and !op read)
+        apiKey = entered;
+
+        const savePermanently = await confirmInBorderedPopup(ctx, {
+          title: "Save API Key?",
+          message:
+            "Save this value permanently in auth.json?\n\n" +
+            "Note: 1Password references (!op read ...) only resolve when saved permanently. " +
+            "Choosing No will store the resolved secret for this session only.",
+        });
+
+        if (savePermanently === null) {
+          // User cancelled the confirmation dialog — abort the entire key entry
+          ctx.ui.notify("Context7 authentication cancelled.", "warning");
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  "The user explicitly cancelled Context7 authentication. " +
+                  "Do not attempt to use context7_search or context7_get_docs again in this session " +
+                  "without the user re-initiating the flow.",
+              },
+            ],
+            details: { error: "cancelled" },
+            isError: true,
+          };
+        }
+
+        if (savePermanently) {
+          authStorage.set("context7", {
+            type: "api_key" as const,
+            key: entered,
+          });
+          authStorage.removeRuntimeApiKey("context7");
+          const errs = authStorage.drainErrors();
+          if (errs.length > 0) {
+            ctx.ui.notify(
+              `[context7] search save ERRORS: ${errs.map((e) => e.message).join("; ")}`,
+              "warning",
+            );
+          }
+        } else {
+          let keyForRuntime = entered;
+          if (entered.trim().startsWith("!op read")) {
+            // Temporarily store the reference so AuthStorage resolves it via the normal path (1Password, etc.)
+            authStorage.set("context7", { type: "api_key" as const, key: entered });
+            const resolved = await authStorage.getApiKey("context7");
+            authStorage.remove("context7");
+            if (resolved) {
+              keyForRuntime = resolved;
+            }
+          }
+          authStorage.setRuntimeApiKey("context7", keyForRuntime);
+        }
+        apiKey = (await authStorage.getApiKey("context7")) ?? entered;
+        if (!apiKey) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Failed to resolve Context7 API key. Check your shell configuration.",
+              },
+            ],
+            details: { error: "missing_api_key" },
+            isError: true,
+          };
+        }
+      }
+
+      try {
+        const url = new URL("/api/v2/libs/search", CONTEXT7_API_BASE);
+        url.searchParams.set("libraryName", params.libraryName);
+        if (params.query) {
+          url.searchParams.set("query", params.query);
+        }
+
+        const response = await fetch(url.toString(), {
+          signal,
+          headers: { Authorization: "Bearer " + apiKey },
+        });
+
+        if (!response.ok) {
+          if (response.status === 401) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Context7 API error: 401 Unauthorized. Your Context7 API key " +
+                    "may be missing or invalid. Run /context7_onboard to configure it.",
+                },
+              ],
+              details: { status: 401 },
+              isError: true,
+            };
+          }
+          if (response.status === 429) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Context7 API error: 429 Too Many Requests. You are being rate " +
+                    "limited — please wait a moment and try again.",
+                },
+              ],
+              details: { status: 429 },
+              isError: true,
+            };
+          }
+
+          const errorText = await response.text();
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  "Context7 API error: " +
+                  String(response.status) +
+                  " " +
+                  response.statusText +
+                  "\n" +
+                  errorText,
+              },
+            ],
+            details: { status: response.status, body: errorText },
+            isError: true,
+          };
+        }
+
+        const data = (await response.json()) as Context7SearchResponse;
+        const libs = data.results ?? [];
+
+        if (libs.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No libraries found matching " + params.libraryName + ".",
+              },
+            ],
+            details: { libraryName: params.libraryName, raw: data },
+          };
+        }
+
+        const formatted = libs
+          .map(function (lib, i) {
+            return String(i + 1) + ". " + lib.title + " (ID: " + lib.id + ")";
+          })
+          .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                "Context7 library search results for " +
+                params.libraryName +
+                ":\n\n" +
+                formatted +
+                "\n\nUse context7_get_docs with a Library ID to retrieve documentation.",
+            },
+          ],
+          details: { libraryName: params.libraryName, raw: data },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error performing Context7 search: " + message,
+            },
+          ],
+          details: { error: message },
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // -- context7_get_docs
+  pi.registerTool({
+    name: "context7_get_docs",
+    label: "Context7: Query Documentation",
+    description:
+      "Use this tool to retrieve detailed, version-specific documentation and real code examples from Context7 for a programming language, framework, or library. " +
+      "Call this when the user needs implementation details, code snippets, configuration examples, best practices, or answers to technical questions about a specific language, framework, or library. " +
+      "You should usually call context7_search first to obtain the correct Library ID. Prefer this tool when you need reliable, current technical documentation rather than general explanations.",
+    parameters: context7GetDocsSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      let apiKey = await authStorage.getApiKey("context7");
+
+      if (!apiKey) {
+        const entered = await inputInBorderedPopup(ctx, {
+          title: "Context7 Authentication",
+          prompt: "Enter your Context7 API key:",
+          helpText: "Enter to confirm • Esc = cancel",
+        });
+        if (!entered) {
+          ctx.ui.notify("Context7 documentation retrieval cancelled.", "warning");
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Documentation retrieval cancelled: no Context7 API key provided.",
+              },
+            ],
+            details: { error: "missing_api_key" },
+            isError: true,
+          };
+        }
+
+        // Always use the entered value for this request (supports raw keys and !op read)
+        apiKey = entered;
+
+        const savePermanently = await confirmInBorderedPopup(ctx, {
+          title: "Save API Key?",
+          message:
+            "Save this value permanently in auth.json?\n\n" +
+            "Note: 1Password references (!op read ...) only resolve when saved permanently. " +
+            "Choosing No will store the resolved secret for this session only.",
+        });
+
+        if (savePermanently === null) {
+          // User cancelled the confirmation dialog — abort the entire key entry
+          ctx.ui.notify("Context7 authentication cancelled.", "warning");
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  "The user explicitly cancelled Context7 authentication. " +
+                  "Do not attempt to use context7_search or context7_get_docs again in this session " +
+                  "without the user re-initiating the flow.",
+              },
+            ],
+            details: { error: "cancelled" },
+            isError: true,
+          };
+        }
+
+        if (savePermanently) {
+          authStorage.set("context7", {
+            type: "api_key" as const,
+            key: entered,
+          });
+          authStorage.removeRuntimeApiKey("context7");
+          const errs = authStorage.drainErrors();
+          if (errs.length > 0) {
+            ctx.ui.notify(
+              `get_docs save ERRORS: ${errs.map((e) => e.message).join("; ")}`,
+              "warning",
+            );
+          }
+        } else {
+          let keyForRuntime = entered;
+          if (entered.trim().startsWith("!op read")) {
+            // Temporarily store the reference so AuthStorage resolves it via the normal path (1Password, etc.)
+            authStorage.set("context7", { type: "api_key" as const, key: entered });
+            const resolved = await authStorage.getApiKey("context7");
+            authStorage.remove("context7");
+            if (resolved) {
+              keyForRuntime = resolved;
+            }
+          }
+          authStorage.setRuntimeApiKey("context7", keyForRuntime);
+        }
+        apiKey = (await authStorage.getApiKey("context7")) ?? entered;
+        if (!apiKey) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Failed to resolve Context7 API key. Check your shell configuration.",
+              },
+            ],
+            details: { error: "missing_api_key" },
+            isError: true,
+          };
+        }
+      }
+
+      try {
+        const url = new URL("/api/v2/context", CONTEXT7_API_BASE);
+        url.searchParams.set("libraryId", params.libraryId);
+        url.searchParams.set("query", params.query);
+        url.searchParams.set("type", "json");
+
+        const response = await fetch(url.toString(), {
+          signal,
+          headers: { Authorization: "Bearer " + apiKey },
+        });
+
+        if (!response.ok) {
+          if (response.status === 401) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Context7 API error: 401 Unauthorized. Your Context7 API key " +
+                    "may be missing or invalid. Run /context7_onboard to configure it.",
+                },
+              ],
+              details: { status: 401 },
+              isError: true,
+            };
+          }
+          if (response.status === 429) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "Context7 API error: 429 Too Many Requests. You are being rate " +
+                    "limited — please wait a moment and try again.",
+                },
+              ],
+              details: { status: 429 },
+              isError: true,
+            };
+          }
+
+          const errorText = await response.text();
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  "Context7 API error: " +
+                  String(response.status) +
+                  " " +
+                  response.statusText +
+                  "\n" +
+                  errorText,
+              },
+            ],
+            details: { status: response.status, body: errorText },
+            isError: true,
+          };
+        }
+
+        const data = (await response.json()) as Context7DocsResponse;
+        return {
+          content: [{ type: "text", text: formatDocs(data, params.query) }],
+          details: { libraryId: params.libraryId, query: params.query, raw: data },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error fetching Context7 documentation: " + message,
+            },
+          ],
+          details: { error: message },
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@jmcombs/pi-context7",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Real-time documentation for the Pi coding agent via Context7.",
+  "homepage": "https://github.com/jmcombs/pi-extensions/tree/main/packages/context7",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmcombs/pi-extensions.git",
+    "directory": "packages/context7"
+  },
+  "bugs": {
+    "url": "https://github.com/jmcombs/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Jeremy Combs",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "ui/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "context7",
+    "documentation"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/context7/preview.png"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}

package/ui/bordered-popups.ts

@@ -0,0 +1,319 @@
+/**
+ * Bordered Popup TUI Helpers
+ *
+ * These are reusable, self-contained helpers for creating polished,
+ * consistent bordered popups inside Pi extensions using `ctx.ui.custom({ overlay: true })`.
+ *
+ * They were originally developed in the 1Password extension and are provided
+ * here as a copy-paste starting point for any extension that needs rich
+ * interactive flows (select lists with live filtering, text input, confirms)
+ * that look and feel better than the basic `ctx.ui.select / input / confirm`.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   selectInBorderedPopup,
+ *   confirmInBorderedPopup,
+ *   inputInBorderedPopup,
+ * } from "./ui/bordered-popups.js";
+ *
+ * const choice = await selectInBorderedPopup(ctx, {
+ *   title: "Select something",
+ *   items: [...],
+ * });
+ *
+ * const confirmed = await confirmInBorderedPopup(ctx, {
+ *   title: "Are you sure?",
+ * });
+ *
+ * const name = await inputInBorderedPopup(ctx, {
+ *   title: "Enter name",
+ *   prompt: "What should we call it?",
+ * });
+ * ```
+ *
+ * The helpers automatically handle:
+ * - Consistent 4-sided borders (╭─╮│╰╯) with stable right edge
+ * - Proper ANSI-aware padding using Pi's `truncateToWidth`
+ * - Live filtering on long lists
+ * - Back navigation ("← Go back") and Esc-to-cancel semantics
+ * - Theming consistent with the rest of Pi
+ *
+ * ## When to use
+ *
+ * Use these when you have:
+ * - Long lists that benefit from filtering
+ * - Multi-step wizards
+ * - Situations where the basic Pi UI dialogs feel too plain
+ *
+ * For very simple one-off prompts, the built-in `ctx.ui.select/input/confirm`
+ * are still perfectly acceptable and require less code.
+ */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+
+// No static imports from @earendil-works/pi-tui are used for types.
+// We rely on inference for ctx.ui.custom callback parameters (sourced via the
+// pi-coding-agent peer) and a minimal local facade for the runtime values
+// obtained via dynamic import. This avoids duplicate module declarations
+// (pi-tui types nested inside coding-agent vs. direct peer) that would
+// otherwise break tsc strict under the project's monorepo layout.
+
+/** Internal helper to render a consistent bordered box. */
+export function renderBorderedBox(
+  width: number,
+  title: string,
+  bodyLines: string[],
+  footer: string | undefined,
+  theme: Pick<Theme, "fg" | "bold">,
+  truncateToWidthFn: (s: string, w: number, e?: string, pad?: boolean) => string,
+): string[] {
+  const innerWidth = Math.max(20, width - 4);
+  const top = theme.fg("accent", "╭" + "─".repeat(width - 2) + "╮");
+  const bottom = theme.fg("accent", "╰" + "─".repeat(width - 2) + "╯");
+
+  const rawTitle = theme.fg("accent", theme.bold(title));
+  const titlePadded = truncateToWidthFn(rawTitle, innerWidth, "", true);
+  const borderedTitle = theme.fg("accent", "│ ") + titlePadded + theme.fg("accent", " │");
+
+  const borderedBody = bodyLines.map((line) => {
+    const padded = truncateToWidthFn(line || "", innerWidth, "", true);
+    return theme.fg("accent", "│ ") + padded + theme.fg("accent", " │");
+  });
+
+  const lines = [top, borderedTitle, ...borderedBody];
+
+  if (footer) {
+    const rawFooter = theme.fg("dim", footer);
+    const footerPadded = truncateToWidthFn(rawFooter, innerWidth, "", true);
+    lines.push(theme.fg("accent", "│ ") + footerPadded + theme.fg("accent", " │"));
+  }
+
+  lines.push(bottom);
+  return lines;
+}
+
+/**
+ * High-level helper for a filterable list inside a bordered popup.
+ * Returns the chosen `.value` or `null` (on cancel / Esc).
+ */
+export async function selectInBorderedPopup<T = string>(
+  ctx: ExtensionContext,
+  opts: {
+    title: string;
+    items: { value: T; label: string; description?: string }[];
+    helpText?: string;
+    maxVisible?: number;
+  },
+): Promise<T | null> {
+  const maxVis = opts.maxVisible ?? 14;
+  const help = opts.helpText ?? "↑↓ • Enter • Esc = cancel • Type to filter";
+
+  // Pure local interface (no `extends` of the real SelectList type) describing
+  // exactly the surface we use. Avoids pulling in conflicting .d.ts copies of
+  // pi-tui that exist via the coding-agent transitive dep vs. our direct peer.
+  interface SelectListHandle {
+    render(w: number): string[];
+    invalidate(): void;
+    handleInput(d: string): void;
+    onSelect: (item: { value: T }) => void;
+    onCancel: () => void;
+  }
+
+  // Let inference provide the exact callback parameter types from the
+  // ExtensionCommandContext (via coding-agent peer). Explicit annotations
+  // referencing TUI/KeybindingsManager etc. from pi-tui trigger the
+  // "separate declarations of private property" tsc error in the monorepo.
+  return await ctx.ui.custom<T | null>(
+    async (tui, theme, _kb, done) => {
+      const piTui = (await import("@earendil-works/pi-tui")) as unknown as {
+        SelectList: new (
+          items: { value: T; label: string; description?: string }[],
+          maxVisible: number,
+          theme: unknown,
+        ) => SelectListHandle;
+        Container: new () => { invalidate(): void };
+        truncateToWidth: (s: string, w: number, e?: string, pad?: boolean) => string;
+      };
+
+      const { SelectList, Container, truncateToWidth: truncateToWidthFn } = piTui;
+
+      let currentList: SelectListHandle | null = null;
+
+      function build() {
+        currentList = new SelectList(
+          opts.items.map((it) => ({
+            value: it.value,
+            label: it.label,
+            description: it.description,
+          })),
+          maxVis,
+          {
+            selectedPrefix: (t: string) => theme.fg("accent", t),
+            selectedText: (t: string) => theme.fg("accent", t),
+            description: (t: string) => theme.fg("muted", t),
+            scrollInfo: (t: string) => theme.fg("dim", t),
+            noMatch: (t: string) => theme.fg("warning", t),
+          },
+        );
+        currentList.onSelect = (item) => {
+          done(item.value);
+        };
+        currentList.onCancel = () => {
+          done(null);
+        };
+      }
+
+      build();
+
+      const container = new Container();
+
+      const popup: {
+        render(w: number): string[];
+        invalidate(): void;
+        handleInput?(d: string): void;
+        dispose?(): void;
+      } = {
+        render(width: number) {
+          const listLines = currentList ? currentList.render(Math.max(20, width - 4)) : [];
+          return renderBorderedBox(width, opts.title, listLines, help, theme, truncateToWidthFn);
+        },
+        invalidate() {
+          container.invalidate();
+          currentList?.invalidate();
+        },
+        handleInput(d: string) {
+          currentList?.handleInput(d);
+          tui.requestRender();
+        },
+      };
+
+      return popup;
+    },
+    { overlay: true },
+  );
+}
+
+/** Yes/No (or custom labels) confirmation inside a bordered popup. */
+export async function confirmInBorderedPopup(
+  ctx: ExtensionContext,
+  opts: {
+    title: string;
+    message?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+  },
+): Promise<boolean | null> {
+  const yes = opts.confirmLabel ?? "Yes";
+  const no = opts.cancelLabel ?? "No";
+  const items = [
+    { value: true, label: yes },
+    { value: false, label: no },
+  ];
+
+  const choice = await selectInBorderedPopup(ctx, {
+    title: opts.title,
+    items,
+    helpText: "↑↓ • Enter to confirm • Esc = cancel",
+    maxVisible: 5,
+  });
+
+  if (choice === null) return null; // user cancelled the dialog
+  return choice;
+}
+
+/**
+ * Bordered popup text input powered by Pi's Editor component.
+ * Good for free-text entry while staying inside the custom popup aesthetic.
+ */
+export async function inputInBorderedPopup(
+  ctx: ExtensionContext,
+  opts: {
+    title: string;
+    prompt?: string;
+    defaultValue?: string;
+    helpText?: string;
+  },
+): Promise<string | undefined> {
+  const help = opts.helpText ?? "Enter to confirm • Esc = cancel";
+
+  // Pure local interface (no extends) for the submit hook.
+  interface EditorHandle {
+    render(w: number): string[];
+    invalidate(): void;
+    handleInput(d: string): void;
+    setText(s: string): void;
+    onSubmit: (value: string) => void;
+  }
+
+  // Inference for callback params (see selectInBorderedPopup for rationale).
+  return await ctx.ui.custom<string | undefined>(
+    async (tui, theme, _kb, done) => {
+      const piTui = (await import("@earendil-works/pi-tui")) as unknown as {
+        Editor: new (tui: unknown, theme: unknown) => EditorHandle;
+        matchesKey: (data: string, key: string) => boolean;
+        truncateToWidth: (s: string, w: number, e?: string, pad?: boolean) => string;
+      };
+
+      const { Editor, matchesKey, truncateToWidth: truncateToWidthFn } = piTui;
+
+      const editorTheme = {
+        borderColor: (s: string) => theme.fg("accent", s),
+        selectList: {
+          selectedPrefix: (t: string) => theme.fg("accent", t),
+          selectedText: (t: string) => theme.fg("accent", t),
+          description: (t: string) => theme.fg("muted", t),
+          scrollInfo: (t: string) => theme.fg("dim", t),
+          noMatch: (t: string) => theme.fg("warning", t),
+        },
+      };
+
+      const editor = new Editor(tui, editorTheme);
+
+      if (opts.defaultValue) {
+        editor.setText(opts.defaultValue);
+      }
+
+      editor.onSubmit = (value: string) => {
+        done(value.trim() || undefined);
+      };
+
+      const popup: {
+        render(w: number): string[];
+        invalidate(): void;
+        handleInput?(d: string): void;
+        dispose?(): void;
+      } = {
+        render(width: number) {
+          const innerWidth = Math.max(20, width - 4);
+          const body: string[] = [];
+
+          if (opts.prompt) {
+            body.push(theme.fg("text", opts.prompt));
+            body.push("");
+          }
+
+          const editorLines = editor.render(innerWidth);
+          body.push(...editorLines);
+
+          return renderBorderedBox(width, opts.title, body, help, theme, truncateToWidthFn);
+        },
+        invalidate() {
+          editor.invalidate();
+        },
+        handleInput(data: string) {
+          if (matchesKey(data, "escape")) {
+            done(undefined);
+            return;
+          }
+          editor.handleInput(data);
+          tui.requestRender();
+        },
+      };
+
+      return popup;
+    },
+    { overlay: true },
+  );
+}