@astrofoundry/pi-astro 0.3.1 → 0.4.0

package/extensions/grimoire/index.ts

@@ -3,18 +3,23 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { Type } from "typebox";
 
-function loadGrimoireHelp(): string {
+function loadGrimoireHelp(): { help: string; available: boolean } {
     try {
-        return execFileSync("grimoire", ["--help"], {
+        const help = execFileSync("grimoire", ["--help"], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
         }).trim();
+        return { help, available: true };
     } catch {
-        return "grimoire CLI not available on PATH at extension load time.";
+        return { help: "", available: false };
     }
 }
 
-const helpOutput = loadGrimoireHelp();
+const { help: helpOutput, available: grimoireAvailable } = loadGrimoireHelp();
+
+const NOT_INSTALLED_MESSAGE =
+    "grimoire CLI is not installed or not on PATH. Install it per your setup instructions " +
+    "(e.g. `npm install -g @astrofoundry/grimoire`), then restart pi so the extension can re-initialize.";
 
 const params = Type.Object({
     query: Type.String({ description: "Search query — use the library's own terminology." }),
@@ -30,17 +35,27 @@ export default function grimoireExtension(pi: ExtensionAPI): void {
         label: "Grimoire",
         description:
             "Search indexed technical documentation via the grimoire CLI. Prefer this over web search for library/framework docs.",
-        promptGuidelines: [
-            "Use `grimoire` for ALL documentation lookups — libraries, frameworks, APIs, CLIs, cloud services.",
-            "Match query terminology to the library's own docs (e.g. 'Firestore pagination cursors' not 'how do I paginate').",
-            "If the first search misses, rephrase or scope with `source`.",
-            "Cite the URL from results when precision matters.",
-            "",
-            "Current `grimoire --help` output:",
-            helpOutput,
-        ],
+        promptGuidelines: grimoireAvailable
+            ? [
+                  "Use `grimoire` for ALL documentation lookups — libraries, frameworks, APIs, CLIs, cloud services.",
+                  "Match query terminology to the library's own docs (e.g. 'Firestore pagination cursors' not 'how do I paginate').",
+                  "If the first search misses, rephrase or scope with `source`.",
+                  "Cite the URL from results when precision matters.",
+                  "",
+                  "Current `grimoire --help` output:",
+                  helpOutput,
+              ]
+            : [
+                  `grimoire CLI was NOT available when pi started. ${NOT_INSTALLED_MESSAGE}`,
+                  "Any call to this tool will return an error until grimoire is installed and pi is restarted.",
+              ],
         parameters: params,
-        async execute(_toolCallId, input, signal) {
+        async execute(_toolCallId, input, signal, _onUpdate, ctx) {
+            if (!grimoireAvailable) {
+                ctx.ui.notify("grimoire CLI not available — install it and restart pi.", "error");
+                throw new Error(NOT_INSTALLED_MESSAGE);
+            }
+
             return new Promise<AgentToolResult<unknown>>((resolve, reject) => {
                 const args = ["search", input.query, "--compact"];
                 if (input.source) args.push("--source", input.source);
@@ -74,16 +89,43 @@ export default function grimoireExtension(pi: ExtensionAPI): void {
                         );
                         return;
                     }
-                    const text = stdout.trim() || "(no results)";
+
+                    const output = stdout.trim();
+                    const isNoResults = output === "" || /^no results found\.?$/im.test(output);
+
+                    if (isNoResults) {
+                        const scopeNote = input.source ? ` in source '${input.source}'` : "";
+                        const suggestion = input.source
+                            ? "Try rephrasing the query or widening scope by omitting `source`."
+                            : "Try rephrasing with the library's own terminology, or check the indexed sources via `grimoire list --names`.";
+                        ctx.ui.notify(`grimoire: no results for "${input.query}"${scopeNote}`, "warning");
+                        resolve({
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No results found for "${input.query}"${scopeNote}. ${suggestion}`,
+                                },
+                            ],
+                            details: { query: input.query, source: input.source, results: 0 },
+                        });
+                        return;
+                    }
+
                     resolve({
-                        content: [{ type: "text", text }],
+                        content: [{ type: "text", text: output }],
                         details: { query: input.query, source: input.source },
                     });
                 });
 
                 proc.on("error", (err) => {
                     signal?.removeEventListener("abort", abortHandler);
-                    reject(new Error(`grimoire CLI not runnable: ${err.message}`));
+                    const nodeErr = err as NodeJS.ErrnoException;
+                    if (nodeErr.code === "ENOENT") {
+                        ctx.ui.notify("grimoire CLI not available — install it and restart pi.", "error");
+                        reject(new Error(NOT_INSTALLED_MESSAGE));
+                        return;
+                    }
+                    reject(new Error(`grimoire CLI failed to run: ${err.message}`));
                 });
             });
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"