@jmcombs/pi-context7 1.0.0 → 2.0.1

package/README.md

@@ -13,6 +13,33 @@
 
 Real-time documentation for the Pi coding agent via [Context7](https://context7.com). Gives the agent access to up-to-date, version-aware docs and code examples without polluting context with outdated information.
 
+## Breaking changes in v2.0.0
+
+- **`AuthStorage` is gone.** Pi 0.80.8 removed the `AuthStorage` API this extension used to store and read its API key. Credentials now resolve through the [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) **credential API**, which this package now depends on directly and **installs automatically** — no separate install step.
+- **Availability-branched onboarding.** When the `op` CLI is installed and an account is configured, setup opens a 1Password **vault → item → field picker**; when `op` is unavailable it falls back to **masked manual key entry**.
+- **Existing keys keep working.** Any Context7 key already in `~/.pi/agent/auth.json` — a literal value or an `!op read` reference — resolves unchanged. No migration action is required.
+
+## What's New — 1Password credential integration
+
+Context7 now handles your API key through the [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) credential API, which installs automatically as a dependency. What this means for you:
+
+- **Onboarding branches on 1Password availability.** If the `op` CLI is installed and an account is configured, `/context7_setup` opens a live **vault → item → field picker** (or lets you type an `op://…` reference) and stores it as a `!op read '…'` entry that resolves fresh on every use. If `op` is not available, it falls back to **manual API-key entry** and nudges you to enable the 1Password extension for vault integration.
+- **Existing keys keep working.** Any Context7 key already in `~/.pi/agent/auth.json` — a literal key or an `!op read` reference — continues to resolve unchanged. No migration action is required.
+- **The key is never exposed to the model.** Entry happens entirely in the TUI, and only the resolved value is used to call the Context7 API.
+- **Startup warm-up.** With the [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) extension installed and enabled, a one-time `op read` runs at session startup, so the 1Password biometric unlock prompt lands once and later key resolves are silent.
+
+```mermaid
+flowchart TD
+    A["/context7_setup or first tool use"] --> B{"is1PasswordAvailable()<br/>(op installed AND configured)"}
+    B -- "Yes" --> C["Live vault → item → field picker<br/>or manual op:// reference"]
+    C --> D["Store !op read 'op://…' entry"]
+    B -- "No" --> E["Manual API-key entry<br/>+ nudge to enable 1Password"]
+    E --> F["Store literal api_key entry"]
+    D --> G["resolveSecret('context7')<br/>resolves fresh on each tool call"]
+    F --> G
+    G --> H["Bearer token → Context7 API<br/>(never shown to the LLM)"]
+```
+
 ## Quick Start
 
 Get better library documentation in your agent in under a minute.
@@ -20,16 +47,16 @@ Get better library documentation in your agent in under a minute.
 1. Install the extension:
 
    ```bash
-   pi install @jmcombs/pi-context7
+   pi install npm:@jmcombs/pi-context7
    ```
 
 2. Configure your Context7 API key:
 
    ```
-   /context7_onboard
+   /context7_setup
    ```
 
-   The command opens a clean, bordered prompt where you can securely enter your key. You can choose to save it permanently or use it only for the current session.
+   The command opens the onboarding flow above — a 1Password vault picker when `op` is available, or a secure manual-entry prompt otherwise. The value is never visible to the LLM.
 
 After setup, just ask the agent for documentation normally:
 
@@ -46,28 +73,23 @@ This extension registers two tools:
 - `context7_search` — Finds the correct Context7 library ID for a programming language, framework, or library.
 - `context7_get_docs` — Retrieves detailed, version-specific documentation and real code examples for that library.
 
-The tools support two authentication modes:
-
-- **Persisted keys** — Saved via `/context7_onboard` into `~/.pi/agent/auth.json` (supports plain keys and `!op read` references).
-- **Runtime-only keys** — Entered ad-hoc when a tool is called and kept only for the current session (also supports `!op read` references).
-
-This design lets you use Context7 without ever leaking keys into the LLM context.
+Both tools resolve the key through `resolveSecret("context7")` from `@jmcombs/pi-1password`, reading `~/.pi/agent/auth.json` fresh on each call (a literal key or an `!op read` reference). If no key is stored, the tool automatically runs onboarding (the availability branch above), then re-resolves — preserving the "prompt on first use" experience. The key is never leaked into the LLM context.
 
-## /context7_onboard
+## /context7_setup
 
-Run this command to securely configure your Context7 API key:
+Run this command to configure (or update) your Context7 API key at any time:
 
 ```
-/context7_onboard
+/context7_setup
 ```
 
-It supports:
+It delegates to the `@jmcombs/pi-1password` onboarding flow, which:
 
-- Entering keys directly or via `!op read` references
-- Overwriting an existing key (with confirmation)
-- Choosing between permanent storage and runtime-only for the current session
+- Branches on 1Password availability — vault picker (`op://` reference) when `op` is configured, secure manual entry otherwise.
+- Stores the value in `~/.pi/agent/auth.json` (`0600`), never exposing it to the model.
+- Reports the outcome as a status notification.
 
-The command never exposes the actual key to the model.
+To rotate an existing key, install and enable the [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) extension and re-run onboarding through it, or edit `auth.json` directly.
 
 ## After Setup
 
@@ -81,7 +103,7 @@ Examples of good prompts:
 
 ## Checking Status
 
-If you ever need to update or rotate your key, just run `/context7_onboard` again. It will detect the existing key and offer to overwrite it.
+`/context7_setup` will not silently overwrite an existing key — if one is already stored it reports that and leaves it in place. To rotate a key, remove the existing `context7` entry from `~/.pi/agent/auth.json` (or update it through the `@jmcombs/pi-1password` extension), then run `/context7_setup` again.
 
 ## Development
 

package/index.ts

@@ -3,18 +3,23 @@
  *
  * 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`.
+ * Context7 API. Credentials are handled entirely through the imported
+ * `@jmcombs/pi-1password` credential API (`resolveSecret` / `onboardSecret`),
+ * so the key is never leaked into the agent's context.
  *
- * 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
+ * Credential handling:
+ *    1. `resolveSecret("context7")` reads `~/.pi/agent/auth.json` and resolves the
+ *       stored entry (literal key or `!op read 'op://…'` reference) fresh on each use.
+ *    2. If nothing is stored, the tool auto-invokes `onboardSecret`, which branches
+ *       on 1Password availability — the live vault picker when `op` is configured,
+ *       manual API-key entry otherwise — then re-resolves.
+ *    3. `/context7_setup` runs the same onboarding flow on demand.
  */
 
-import { AuthStorage, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
-import { confirmInBorderedPopup, inputInBorderedPopup } from "./ui/bordered-popups.js";
+import type { JsonObject, JsonValue } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { onboardSecret, resolveSecret } from "@jmcombs/pi-1password";
+import { type Static, Type } from "typebox";
 
 const CONTEXT7_API_BASE = "https://context7.com/api/v2";
 
@@ -29,22 +34,6 @@ 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({
@@ -71,11 +60,60 @@ export type Context7GetDocsInput = Static<typeof context7GetDocsSchema>;
 
 // -- Helpers
 
-function formatDocs(data: Context7DocsResponse, query: string): string {
-  const { codeSnippets = [], infoSnippets = [] } = data;
+export function isJsonValue(value: unknown): value is JsonValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+    case "string":
+      return true;
+    case "object": {
+      if (Array.isArray(value)) return value.every(isJsonValue);
+      const nested: unknown[] = Object.values(value);
+      return nested.every(isJsonValue);
+    }
+    default:
+      return false;
+  }
+}
+
+function asJsonObject(value: JsonValue): JsonObject | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as JsonObject;
+}
+
+function formatDocs(data: JsonValue, query: string): string {
+  const obj = asJsonObject(data);
+  const codeSnippetsRaw = obj && Array.isArray(obj.codeSnippets) ? obj.codeSnippets : [];
+  const infoSnippetsRaw = obj && Array.isArray(obj.infoSnippets) ? obj.infoSnippets : [];
+  const codeSnippets: CodeSnippet[] = [];
+  for (const snippet of codeSnippetsRaw) {
+    const item = asJsonObject(snippet);
+    if (!item) continue;
+    const next: CodeSnippet = {};
+    if (typeof item.codeTitle === "string") next.codeTitle = item.codeTitle;
+    if (Array.isArray(item.codeList)) {
+      next.codeList = item.codeList.flatMap((entry) => {
+        const codeItem = asJsonObject(entry);
+        if (!codeItem) return [];
+        const language = typeof codeItem.language === "string" ? codeItem.language : undefined;
+        const code = typeof codeItem.code === "string" ? codeItem.code : undefined;
+        return [{ language, code }];
+      });
+    }
+    codeSnippets.push(next);
+  }
+  const infoSnippets: InfoSnippet[] = [];
+  for (const snippet of infoSnippetsRaw) {
+    const item = asJsonObject(snippet);
+    if (!item) continue;
+    const next: InfoSnippet = {};
+    if (typeof item.content === "string") next.content = item.content;
+    infoSnippets.push(next);
+  }
 
   if (codeSnippets.length === 0 && infoSnippets.length === 0) {
-    return "No documentation snippets found for " + query + ".";
+    return `No documentation snippets found for ${query}.`;
   }
 
   const parts: string[] = [];
@@ -84,13 +122,13 @@ function formatDocs(data: Context7DocsResponse, query: string): string {
     parts.push("--- CODE SNIPPETS ---");
     for (const snippet of codeSnippets) {
       if (snippet.codeTitle) {
-        parts.push("\n## " + 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");
+            parts.push(`\`\`\`${lang}\n${item.code}\n\`\`\`\n`);
           }
         }
       }
@@ -101,57 +139,23 @@ function formatDocs(data: Context7DocsResponse, query: string): string {
     parts.push("\n--- INFO SNIPPETS ---");
     for (const snippet of infoSnippets) {
       if (snippet.content) {
-        parts.push("\n" + snippet.content);
+        parts.push(`\n${snippet.content}`);
       }
     }
   }
 
-  return "Documentation for " + query + ":" + "\n\n" + parts.join("\n");
+  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).",
+  // -- /context7_setup (user-facing command)
+  pi.registerCommand("context7_setup", {
+    description: "Set up or update your Context7 API key (never shown to the agent).",
     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");
+      const result = await onboardSecret(ctx, { name: "context7", label: "Context7" });
+      ctx.ui.notify(result.message, result.ok ? "info" : "warning");
     },
   });
 
@@ -165,97 +169,24 @@ export default function (pi: ExtensionAPI): void {
       "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");
-
+      let apiKey = await resolveSecret("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,
-          };
+        const r = await onboardSecret(ctx, { name: "context7", label: "Context7" });
+        if (r.ok) {
+          apiKey = await resolveSecret("context7");
         }
       }
+      if (!apiKey) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Search cancelled: no Context7 API key provided.",
+            },
+          ],
+          details: { error: "missing_api_key" },
+        };
+      }
 
       try {
         const url = new URL("/api/v2/libs/search", CONTEXT7_API_BASE);
@@ -266,7 +197,7 @@ export default function (pi: ExtensionAPI): void {
 
         const response = await fetch(url.toString(), {
           signal,
-          headers: { Authorization: "Bearer " + apiKey },
+          headers: { Authorization: `Bearer ${apiKey}` },
         });
 
         if (!response.ok) {
@@ -277,11 +208,10 @@ export default function (pi: ExtensionAPI): void {
                   type: "text",
                   text:
                     "Context7 API error: 401 Unauthorized. Your Context7 API key " +
-                    "may be missing or invalid. Run /context7_onboard to configure it.",
+                    "may be missing or invalid. Run /context7_setup to configure it.",
                 },
               ],
               details: { status: 401 },
-              isError: true,
             };
           }
           if (response.status === 429) {
@@ -295,7 +225,6 @@ export default function (pi: ExtensionAPI): void {
                 },
               ],
               details: { status: 429 },
-              isError: true,
             };
           }
 
@@ -314,19 +243,34 @@ export default function (pi: ExtensionAPI): void {
               },
             ],
             details: { status: response.status, body: errorText },
-            isError: true,
           };
         }
 
-        const data = (await response.json()) as Context7SearchResponse;
-        const libs = data.results ?? [];
+        const parsed: unknown = await response.json();
+        if (!isJsonValue(parsed)) {
+          return {
+            content: [{ type: "text", text: "Context7 API returned invalid JSON." }],
+            details: { error: "invalid_json" },
+          };
+        }
+        const data = parsed;
+        const obj = asJsonObject(data);
+        const libsRaw = obj && Array.isArray(obj.results) ? obj.results : [];
+        const libs: { id: string; title: string }[] = [];
+        for (const lib of libsRaw) {
+          const item = asJsonObject(lib);
+          if (!item) continue;
+          if (typeof item.id === "string" && typeof item.title === "string") {
+            libs.push({ id: item.id, title: item.title });
+          }
+        }
 
         if (libs.length === 0) {
           return {
             content: [
               {
                 type: "text",
-                text: "No libraries found matching " + params.libraryName + ".",
+                text: `No libraries found matching ${params.libraryName}.`,
               },
             ],
             details: { libraryName: params.libraryName, raw: data },
@@ -334,9 +278,7 @@ export default function (pi: ExtensionAPI): void {
         }
 
         const formatted = libs
-          .map(function (lib, i) {
-            return String(i + 1) + ". " + lib.title + " (ID: " + lib.id + ")";
-          })
+          .map((lib, i) => `${String(i + 1)}. ${lib.title} (ID: ${lib.id})`)
           .join("\n");
 
         return {
@@ -359,11 +301,10 @@ export default function (pi: ExtensionAPI): void {
           content: [
             {
               type: "text",
-              text: "Error performing Context7 search: " + message,
+              text: `Error performing Context7 search: ${message}`,
             },
           ],
           details: { error: message },
-          isError: true,
         };
       }
     },
@@ -379,97 +320,24 @@ export default function (pi: ExtensionAPI): void {
       "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");
-
+      let apiKey = await resolveSecret("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,
-          };
+        const r = await onboardSecret(ctx, { name: "context7", label: "Context7" });
+        if (r.ok) {
+          apiKey = await resolveSecret("context7");
         }
       }
+      if (!apiKey) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Documentation retrieval cancelled: no Context7 API key provided.",
+            },
+          ],
+          details: { error: "missing_api_key" },
+        };
+      }
 
       try {
         const url = new URL("/api/v2/context", CONTEXT7_API_BASE);
@@ -479,7 +347,7 @@ export default function (pi: ExtensionAPI): void {
 
         const response = await fetch(url.toString(), {
           signal,
-          headers: { Authorization: "Bearer " + apiKey },
+          headers: { Authorization: `Bearer ${apiKey}` },
         });
 
         if (!response.ok) {
@@ -490,11 +358,10 @@ export default function (pi: ExtensionAPI): void {
                   type: "text",
                   text:
                     "Context7 API error: 401 Unauthorized. Your Context7 API key " +
-                    "may be missing or invalid. Run /context7_onboard to configure it.",
+                    "may be missing or invalid. Run /context7_setup to configure it.",
                 },
               ],
               details: { status: 401 },
-              isError: true,
             };
           }
           if (response.status === 429) {
@@ -508,7 +375,6 @@ export default function (pi: ExtensionAPI): void {
                 },
               ],
               details: { status: 429 },
-              isError: true,
             };
           }
 
@@ -527,11 +393,17 @@ export default function (pi: ExtensionAPI): void {
               },
             ],
             details: { status: response.status, body: errorText },
-            isError: true,
           };
         }
 
-        const data = (await response.json()) as Context7DocsResponse;
+        const parsed: unknown = await response.json();
+        if (!isJsonValue(parsed)) {
+          return {
+            content: [{ type: "text", text: "Context7 API returned invalid JSON." }],
+            details: { error: "invalid_json" },
+          };
+        }
+        const data = parsed;
         return {
           content: [{ type: "text", text: formatDocs(data, params.query) }],
           details: { libraryId: params.libraryId, query: params.query, raw: data },
@@ -542,11 +414,10 @@ export default function (pi: ExtensionAPI): void {
           content: [
             {
               type: "text",
-              text: "Error fetching Context7 documentation: " + message,
+              text: `Error fetching Context7 documentation: ${message}`,
             },
           ],
           details: { error: message },
-          isError: true,
         };
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmcombs/pi-context7",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "private": false,
   "description": "Real-time documentation for the Pi coding agent via Context7.",
   "homepage": "https://github.com/jmcombs/pi-extensions/tree/main/packages/context7",
@@ -19,7 +19,6 @@
   "types": "./index.ts",
   "files": [
     "index.ts",
-    "ui/",
     "README.md",
     "LICENSE"
   ],
@@ -35,11 +34,13 @@
     "image": "https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/context7/preview.png"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@jmcombs/pi-1password": "^1.0.2 || ^2.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   }
 }

package/ui/bordered-popups.ts

@@ -1,319 +0,0 @@
-/**
- * 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 },
-  );
-}