@aliou/pi-dev-kit 0.5.0 → 0.6.1

package/src/tools/changelog-tool.ts

@@ -20,7 +20,7 @@ const GITHUB_RAW_CHANGELOG_URL =
 // Params
 // ---------------------------------------------------------------------------
 
-const ChangelogParams = Type.Object({
+const ChangelogParamsSchema = Type.Object({
   version: Type.Optional(
     Type.String({
       description:
@@ -29,10 +29,10 @@ const ChangelogParams = Type.Object({
   ),
 });
 
-type ChangelogParamsType = Static<typeof ChangelogParams>;
+type ChangelogParams = Static<typeof ChangelogParamsSchema>;
 
-const ChangelogVersionsParams = Type.Object({});
-type ChangelogVersionsParamsType = Record<string, never>;
+const ChangelogVersionsParamsSchema = Type.Object({});
+type ChangelogVersionsParams = Record<string, never>;
 
 // ---------------------------------------------------------------------------
 // Types
@@ -44,21 +44,15 @@ interface ChangelogEntry {
 }
 
 interface ChangelogDetails {
-  success: boolean;
-  message: string;
   changelog?: ChangelogEntry;
   source?: "local" | "github";
 }
 
 interface ChangelogVersionsDetails {
-  success: boolean;
-  message: string;
   versions?: string[];
   source?: "local" | "github";
 }
 
-type ExecuteResult = AgentToolResult<ChangelogDetails>;
-
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
@@ -115,56 +109,36 @@ function parseChangelogEntries(changelogContent: string): ParsedChangelog {
 function findChangelogEntry(
   changelogContent: string,
   requestedVersion?: string,
-): {
-  success: boolean;
-  changelog?: ChangelogEntry;
-  message: string;
-} {
-  try {
-    const { entries } = parseChangelogEntries(changelogContent);
-    if (entries.length === 0) {
-      return { success: false, message: "No version entries found" };
-    }
-
-    if (requestedVersion) {
-      const normalizedRequested = requestedVersion.replace(/^v/, "");
-      const entry = entries.find(
-        (e) =>
-          e.version === requestedVersion ||
-          e.version === `v${normalizedRequested}` ||
-          e.version.replace(/^v/, "") === normalizedRequested,
-      );
-
-      if (entry) {
-        return {
-          success: true,
-          changelog: { version: entry.version, content: entry.content },
-          message: `Found changelog for version ${entry.version}`,
-        };
-      }
+): ChangelogEntry {
+  const { entries } = parseChangelogEntries(changelogContent);
+  if (entries.length === 0) {
+    throw new Error("No version entries found in changelog");
+  }
 
-      const allVersions = entries.map((e) => e.version);
-      return {
-        success: false,
-        message: `Version ${requestedVersion} not found. Available: ${allVersions.join(", ")}`,
-      };
+  if (requestedVersion) {
+    const normalizedRequested = requestedVersion.replace(/^v/, "");
+    const entry = entries.find(
+      (e) =>
+        e.version === requestedVersion ||
+        e.version === `v${normalizedRequested}` ||
+        e.version.replace(/^v/, "") === normalizedRequested,
+    );
+
+    if (entry) {
+      return { version: entry.version, content: entry.content };
     }
 
-    const latest = entries[0];
-    if (!latest) {
-      return { success: false, message: "No version entries found" };
-    }
-    return {
-      success: true,
-      changelog: { version: latest.version, content: latest.content },
-      message: `Latest changelog entry: ${latest.version}`,
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: `Error parsing changelog: ${error instanceof Error ? error.message : String(error)}`,
-    };
+    const allVersions = entries.map((e) => e.version);
+    throw new Error(
+      `Version ${requestedVersion} not found. Available versions: ${allVersions.join(", ")}`,
+    );
+  }
+
+  const latest = entries[0];
+  if (!latest) {
+    throw new Error("No version entries found in changelog");
   }
+  return { version: latest.version, content: latest.content };
 }
 
 // ---------------------------------------------------------------------------
@@ -188,21 +162,34 @@ function isNewerThanInstalled(requestedVersion: string): boolean {
   return false;
 }
 
-async function fetchGithubChangelog(): Promise<string | null> {
+async function fetchGithubChangelog(): Promise<string> {
   try {
     const res = await fetch(GITHUB_RAW_CHANGELOG_URL);
-    if (!res.ok) return null;
+    if (!res.ok) {
+      throw new Error(
+        `Failed to fetch changelog from GitHub: ${res.status} ${res.statusText}`,
+      );
+    }
     return await res.text();
-  } catch {
-    return null;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Failed to fetch")) {
+      throw error;
+    }
+    throw new Error(
+      `Failed to fetch changelog from GitHub: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
 }
 
-function readLocalChangelog(): { content: string; piPath: string } | null {
+function readLocalChangelog(): { content: string; piPath: string } {
   const piPath = findPiInstallation();
-  if (!piPath) return null;
+  if (!piPath) {
+    throw new Error("Could not locate Pi installation");
+  }
   const changelogPath = path.join(piPath, "CHANGELOG.md");
-  if (!fs.existsSync(changelogPath)) return null;
+  if (!fs.existsSync(changelogPath)) {
+    throw new Error(`Changelog file not found at ${changelogPath}`);
+  }
   return { content: fs.readFileSync(changelogPath, "utf-8"), piPath };
 }
 
@@ -249,110 +236,58 @@ function renderChangelogContent(
 // ---------------------------------------------------------------------------
 
 export function setupChangelogTool(pi: ExtensionAPI) {
-  pi.registerTool<typeof ChangelogParams, ChangelogDetails>({
+  pi.registerTool<typeof ChangelogParamsSchema, ChangelogDetails>({
     name: "pi_changelog",
     label: "Pi Changelog",
     description:
       "Get changelog entry for a Pi version. Returns latest by default. Use pi_changelog_versions to list all available versions.",
+    promptSnippet: `pi_changelog version="1.2.3" // Get changelog for specific version
+pi_changelog // Get latest changelog`,
+    promptGuidelines: [
+      "Use this tool to check what's new in a Pi version",
+      "Use pi_changelog_versions first to list available versions",
+      "Leave version empty to get the latest changelog",
+    ],
 
-    parameters: ChangelogParams,
+    parameters: ChangelogParamsSchema,
 
     async execute(
       _toolCallId: string,
-      params: ChangelogParamsType,
+      params: ChangelogParams,
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
       _ctx: ExtensionContext,
-    ): Promise<ExecuteResult> {
-      try {
-        // Newer than installed -> fetch from GitHub
-        if (params.version && isNewerThanInstalled(params.version)) {
-          const githubContent = await fetchGithubChangelog();
-          if (!githubContent) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `Version ${params.version} is newer than installed (${VERSION}) and GitHub fetch failed.`,
-                },
-              ],
-              details: {
-                success: false,
-                message: `Version ${params.version} is newer than installed (${VERSION}) and GitHub fetch failed.`,
-              },
-            };
-          }
-
-          const result = findChangelogEntry(githubContent, params.version);
-          if (!result.success || !result.changelog) {
-            return {
-              content: [{ type: "text", text: result.message }],
-              details: {
-                success: false,
-                message: result.message,
-                source: "github",
-              },
-            };
-          }
-
-          const message = `${result.message} (from GitHub)\n\n## ${result.changelog.version}\n\n${result.changelog.content}`;
-          return {
-            content: [{ type: "text", text: message }],
-            details: {
-              success: true,
-              message: `${result.message} (from GitHub)`,
-              changelog: result.changelog,
-              source: "github",
-            },
-          };
-        }
-
-        // Local
-        const local = readLocalChangelog();
-        if (!local) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Could not locate Pi installation or CHANGELOG.md",
-              },
-            ],
-            details: {
-              success: false,
-              message: "Could not locate Pi installation or CHANGELOG.md",
-            },
-          };
-        }
-
-        const result = findChangelogEntry(local.content, params.version);
-        if (!result.success || !result.changelog) {
-          return {
-            content: [{ type: "text", text: result.message }],
-            details: { success: false, message: result.message },
-          };
-        }
-
-        const { changelog } = result;
-        const message = `${result.message}\n\n## ${changelog.version}\n\n${changelog.content}`;
+    ): Promise<AgentToolResult<ChangelogDetails>> {
+      // Newer than installed -> fetch from GitHub
+      if (params.version && isNewerThanInstalled(params.version)) {
+        const githubContent = await fetchGithubChangelog();
+        const changelog = findChangelogEntry(githubContent, params.version);
+
+        const message = `Changelog for ${changelog.version} (from GitHub)\n\n## ${changelog.version}\n\n${changelog.content}`;
         return {
           content: [{ type: "text", text: message }],
           details: {
-            success: true,
-            message: result.message,
             changelog,
-            source: "local",
+            source: "github",
           },
         };
-      } catch (error) {
-        const message = `Error reading Pi changelog: ${error instanceof Error ? error.message : String(error)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          details: { success: false, message },
-        };
       }
+
+      // Local
+      const local = readLocalChangelog();
+      const changelog = findChangelogEntry(local.content, params.version);
+
+      const message = `Changelog for ${changelog.version}\n\n## ${changelog.version}\n\n${changelog.content}`;
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          changelog,
+          source: "local",
+        },
+      };
     },
 
-    renderCall(args: ChangelogParamsType, theme: Theme) {
+    renderCall(args: ChangelogParams, theme: Theme) {
       return new ToolCallHeader(
         {
           toolName: "Pi Changelog",
@@ -369,7 +304,8 @@ export function setupChangelogTool(pi: ExtensionAPI) {
     ) {
       const { details } = result;
 
-      if (!details) {
+      // Check for missing expected fields to detect errors
+      if (!details?.changelog) {
         const text = result.content[0];
         return new Text(
           text?.type === "text" && text.text ? text.text : "No result",
@@ -382,62 +318,57 @@ export function setupChangelogTool(pi: ExtensionAPI) {
         { label: string; value: string; showCollapsed?: boolean } | Text
       > = [];
 
-      if (!details.success) {
-        fields.push({
-          label: "Error",
-          value: theme.fg("error", details.message),
-          showCollapsed: true,
-        });
-      } else if (!details.changelog) {
-        fields.push({
-          label: "Result",
-          value: theme.fg("success", details.message),
-          showCollapsed: true,
-        });
+      const lines: string[] = [];
+
+      if (options.expanded) {
+        // Expanded view: show full changelog content
+        lines.push(
+          theme.fg(
+            "accent",
+            theme.bold(`Version: ${details.changelog.version}`),
+          ),
+          "",
+        );
+        lines.push(...renderChangelogContent(details.changelog.content, theme));
+        fields.push(new Text(lines.join("\n"), 0, 0));
       } else {
-        const lines: string[] = [];
-        const sourceTag =
-          details.source === "github" ? theme.fg("muted", " (github)") : "";
-        lines.push(theme.fg("success", details.message) + sourceTag, "");
+        // Collapsed view: show version + first few lines of changelog + expand hint
         lines.push(
-          theme.fg("accent", `Version: ${details.changelog.version}`),
+          theme.fg(
+            "accent",
+            theme.bold(`Version: ${details.changelog.version}`),
+          ),
           "",
         );
         lines.push(
           ...renderChangelogContent(
             details.changelog.content,
             theme,
-            options.expanded ? undefined : COLLAPSED_LINES,
+            COLLAPSED_LINES,
           ),
         );
-
-        if (!options.expanded) {
-          lines.push(
-            "",
-            theme.fg("muted", `${keyHint("app.tools.expand", "to expand")}`),
-          );
-        }
-
+        lines.push(
+          "",
+          theme.fg("muted", `${keyHint("app.tools.expand", "to expand")}`),
+        );
         fields.push(new Text(lines.join("\n"), 0, 0));
       }
 
+      // Footer: show source tag only
+      const footer = new ToolFooter(theme, {
+        items: [
+          {
+            label: "source",
+            value: details.source ?? "local",
+            tone: "accent",
+          },
+        ],
+      });
+
       return new ToolBody(
         {
           fields,
-          footer: new ToolFooter(theme, {
-            items: [
-              {
-                label: "status",
-                value: details.success ? "ok" : "error",
-                tone: details.success ? "success" : "error",
-              },
-              {
-                label: "source",
-                value: details.source ?? "local",
-                tone: "accent",
-              },
-            ],
-          }),
+          footer,
         },
         options,
         theme,
@@ -449,72 +380,44 @@ export function setupChangelogTool(pi: ExtensionAPI) {
   // pi_changelog_versions
   // -------------------------------------------------------------------------
 
-  pi.registerTool<typeof ChangelogVersionsParams, ChangelogVersionsDetails>({
+  pi.registerTool<
+    typeof ChangelogVersionsParamsSchema,
+    ChangelogVersionsDetails
+  >({
     name: "pi_changelog_versions",
     label: "Pi Changelog Versions",
     description: "List all available Pi changelog versions",
+    promptSnippet: `pi_changelog_versions // List all available versions`,
 
-    parameters: ChangelogVersionsParams,
+    parameters: ChangelogVersionsParamsSchema,
 
     async execute(
       _toolCallId: string,
-      _params: ChangelogVersionsParamsType,
+      _params: ChangelogVersionsParams,
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
       _ctx: ExtensionContext,
     ): Promise<AgentToolResult<ChangelogVersionsDetails>> {
-      try {
-        const local = readLocalChangelog();
-        if (!local) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Could not locate Pi installation or CHANGELOG.md",
-              },
-            ],
-            details: {
-              success: false,
-              message: "Could not locate Pi installation or CHANGELOG.md",
-            },
-          };
-        }
-
-        const { entries } = parseChangelogEntries(local.content);
-        if (entries.length === 0) {
-          return {
-            content: [
-              { type: "text", text: "No version entries found in changelog" },
-            ],
-            details: {
-              success: false,
-              message: "No version entries found in changelog",
-            },
-          };
-        }
-
-        const versions = entries.map((e) => e.version);
-        const message = `${versions.length} versions available:\n${versions.join(", ")}`;
+      const local = readLocalChangelog();
+      const { entries } = parseChangelogEntries(local.content);
 
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            success: true,
-            message: `Found ${versions.length} versions`,
-            versions,
-            source: "local",
-          },
-        };
-      } catch (error) {
-        const message = `Error reading changelog: ${error instanceof Error ? error.message : String(error)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          details: { success: false, message },
-        };
+      if (entries.length === 0) {
+        throw new Error("No version entries found in changelog");
       }
+
+      const versions = entries.map((e) => e.version);
+      const message = `${versions.length} versions available:\n${versions.join(", ")}`;
+
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          versions,
+          source: "local",
+        },
+      };
     },
 
-    renderCall(_args: ChangelogVersionsParamsType, theme: Theme) {
+    renderCall(_args: ChangelogVersionsParams, theme: Theme) {
       return new ToolCallHeader({ toolName: "Pi Changelog Versions" }, theme);
     },
 
@@ -525,7 +428,8 @@ export function setupChangelogTool(pi: ExtensionAPI) {
     ) {
       const { details } = result;
 
-      if (!details) {
+      // Check for missing expected fields to detect errors
+      if (!details?.versions) {
         const text = result.content[0];
         return new Text(
           text?.type === "text" && text.text ? text.text : "No result",
@@ -538,55 +442,39 @@ export function setupChangelogTool(pi: ExtensionAPI) {
         { label: string; value: string; showCollapsed?: boolean } | Text
       > = [];
 
-      if (!details.success) {
-        fields.push({
-          label: "Error",
-          value: theme.fg("error", details.message),
-          showCollapsed: true,
-        });
-      } else if (!details.versions || details.versions.length === 0) {
-        fields.push({
-          label: "Result",
-          value: theme.fg("warning", "No versions found"),
-          showCollapsed: true,
-        });
-      } else {
-        const lines: string[] = [
-          theme.fg("accent", `${details.versions.length} versions available:`),
-          "",
-        ];
-        const cols = 6;
-        const maxLen = Math.max(
-          ...details.versions.map((version) => version.length),
-        );
-        const colWidth = maxLen + 2;
-        for (let i = 0; i < details.versions.length; i += cols) {
-          const row = details.versions
-            .slice(i, i + cols)
-            .map((version) => version.padEnd(colWidth))
-            .join("");
-          lines.push(theme.fg("dim", row));
-        }
-        fields.push(new Text(lines.join("\n"), 0, 0));
+      const lines: string[] = [
+        theme.fg("accent", `${details.versions.length} versions available:`),
+        "",
+      ];
+      const cols = 6;
+      const maxLen = Math.max(
+        ...details.versions.map((version) => version.length),
+      );
+      const colWidth = maxLen + 2;
+      for (let i = 0; i < details.versions.length; i += cols) {
+        const row = details.versions
+          .slice(i, i + cols)
+          .map((version) => version.padEnd(colWidth))
+          .join("");
+        lines.push(theme.fg("dim", row));
       }
+      fields.push(new Text(lines.join("\n"), 0, 0));
+
+      // Footer: just show version count
+      const footer = new ToolFooter(theme, {
+        items: [
+          {
+            label: "count",
+            value: String(details.versions.length),
+            tone: "accent",
+          },
+        ],
+      });
 
       return new ToolBody(
         {
           fields,
-          footer: new ToolFooter(theme, {
-            items: [
-              {
-                label: "status",
-                value: details.success ? "ok" : "error",
-                tone: details.success ? "success" : "error",
-              },
-              {
-                label: "versions",
-                value: String(details.versions?.length ?? 0),
-                tone: "accent",
-              },
-            ],
-          }),
+          footer,
         },
         options,
         theme,