@aliou/pi-dev-kit 0.4.9 → 0.5.0

package/src/tools/docs-tool.ts

@@ -0,0 +1,240 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ToolBody, ToolCallHeader, ToolFooter } from "@aliou/pi-utils-ui";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { keyHint } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { findPiInstallation } from "./utils";
+
+const DocsParams = Type.Object({});
+type DocsParamsType = Record<string, never>;
+
+interface DocsDetails {
+  success: boolean;
+  message: string;
+  /** Relative paths from the pi install root, markdown only. */
+  docFiles?: string[];
+  installPath?: string;
+}
+
+type ExecuteResult = AgentToolResult<DocsDetails>;
+
+function listFilesRecursive(dir: string, prefix = ""): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      results.push(...listFilesRecursive(path.join(dir, entry.name), rel));
+    } else {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+export function setupDocsTool(pi: ExtensionAPI) {
+  pi.registerTool<typeof DocsParams, DocsDetails>({
+    name: "pi_docs",
+    label: "Pi Documentation",
+    description:
+      "List Pi markdown documentation files (README, docs/, examples/)",
+
+    parameters: DocsParams,
+
+    async execute(
+      _toolCallId: string,
+      _params: DocsParamsType,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ): Promise<ExecuteResult> {
+      try {
+        const piPath = findPiInstallation();
+        if (!piPath) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Could not locate running Pi installation directory",
+              },
+            ],
+            details: {
+              success: false,
+              message: "Could not locate running Pi installation directory",
+            },
+          };
+        }
+
+        const readmePath = path.join(piPath, "README.md");
+        const docsDir = path.join(piPath, "docs");
+        const examplesDir = path.join(piPath, "examples");
+
+        const docFiles: string[] = [];
+
+        if (fs.existsSync(readmePath)) {
+          docFiles.push("README.md");
+        }
+
+        if (fs.existsSync(docsDir)) {
+          for (const file of listFilesRecursive(docsDir)) {
+            if (file.endsWith(".md")) {
+              docFiles.push(`docs/${file}`);
+            }
+          }
+        }
+
+        if (fs.existsSync(examplesDir)) {
+          for (const file of listFilesRecursive(examplesDir)) {
+            if (file.endsWith(".md")) {
+              docFiles.push(`examples/${file}`);
+            }
+          }
+        }
+
+        if (docFiles.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No markdown documentation found in Pi installation`,
+              },
+            ],
+            details: {
+              success: false,
+              message: `No markdown documentation found in Pi installation`,
+              installPath: piPath,
+            },
+          };
+        }
+
+        // Content sent to LLM: full relative paths so it can read them.
+        const lines = docFiles.map(
+          (rel) => `${path.join(piPath, rel)} (${rel})`,
+        );
+        const message = `${docFiles.length} markdown files:\n${lines.join("\n")}`;
+
+        return {
+          content: [{ type: "text", text: message }],
+          details: {
+            success: true,
+            message: `Found ${docFiles.length} markdown files`,
+            docFiles,
+            installPath: piPath,
+          },
+        };
+      } catch (error) {
+        const message = `Error reading Pi documentation: ${error instanceof Error ? error.message : String(error)}`;
+        return {
+          content: [{ type: "text", text: message }],
+          details: {
+            success: false,
+            message,
+          },
+        };
+      }
+    },
+
+    renderCall(_args: DocsParamsType, theme: Theme) {
+      return new ToolCallHeader({ toolName: "Pi Docs" }, theme);
+    },
+
+    renderResult(
+      result: AgentToolResult<DocsDetails>,
+      options: ToolRenderResultOptions,
+      theme: Theme,
+    ) {
+      const { details } = result;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(
+          text?.type === "text" && text.text ? text.text : "No result",
+          0,
+          0,
+        );
+      }
+
+      const fields: Array<
+        { 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.docFiles || details.docFiles.length === 0) {
+        fields.push({
+          label: "Result",
+          value: theme.fg("warning", "No docs found"),
+          showCollapsed: true,
+        });
+      } else {
+        const lines: string[] = [];
+
+        if (options.expanded) {
+          lines.push(
+            theme.fg("accent", `${details.docFiles.length} markdown files:`),
+            "",
+          );
+          for (const rel of details.docFiles) {
+            lines.push(theme.fg("dim", `  ${rel}`));
+          }
+        } else {
+          lines.push(
+            theme.fg("accent", `${details.docFiles.length} markdown files`) +
+              ` (${keyHint("app.tools.expand", "to expand")})`,
+            "",
+          );
+
+          const filenames = details.docFiles.map((file) => path.basename(file));
+          const maxLen = Math.max(...filenames.map((file) => file.length));
+          const colWidth = maxLen + 2;
+          const cols = Math.max(1, Math.floor(80 / colWidth));
+          for (let i = 0; i < filenames.length; i += cols) {
+            const row = filenames
+              .slice(i, i + cols)
+              .map((file) => file.padEnd(colWidth))
+              .join("");
+            lines.push(theme.fg("dim", row));
+          }
+        }
+
+        fields.push(new Text(lines.join("\n"), 0, 0));
+      }
+
+      return new ToolBody(
+        {
+          fields,
+          footer: new ToolFooter(theme, {
+            items: [
+              {
+                label: "status",
+                value: details.success ? "ok" : "error",
+                tone: details.success ? "success" : "error",
+              },
+              {
+                label: "docs",
+                value: String(details.docFiles?.length ?? 0),
+                tone: "accent",
+              },
+            ],
+          }),
+        },
+        options,
+        theme,
+      );
+    },
+  });
+}

package/src/tools/index.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { setupChangelogTool } from "./changelog-tool";
+import { setupDocsTool } from "./docs-tool";
+import { setupPackageManagerTool } from "./package-manager-tool";
+import { setupVersionTool } from "./version-tool";
+
+export function setupTools(pi: ExtensionAPI) {
+  setupPackageManagerTool(pi);
+  setupVersionTool(pi);
+  setupDocsTool(pi);
+  setupChangelogTool(pi);
+}

package/src/tools/package-manager-tool.ts

@@ -0,0 +1,223 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ToolCallHeader } from "@aliou/pi-utils-ui";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { resolveCtx } from "./utils";
+
+const Params = Type.Object({});
+type ParamsType = Record<string, never>;
+
+interface PackageManagerDetails {
+  success: boolean;
+  message: string;
+  packageManager?: string;
+  version?: string;
+  lockfile?: string;
+  installCommand?: string;
+  runCommand?: string;
+  cwd?: string;
+}
+
+type ExecuteResult = AgentToolResult<PackageManagerDetails>;
+
+const LOCKFILES: Record<string, string> = {
+  "pnpm-lock.yaml": "pnpm",
+  "yarn.lock": "yarn",
+  "package-lock.json": "npm",
+  "bun.lockb": "bun",
+  "bun.lock": "bun",
+};
+
+const COMMANDS: Record<string, { install: string; run: string }> = {
+  pnpm: { install: "pnpm install", run: "pnpm" },
+  yarn: { install: "yarn install", run: "yarn" },
+  npm: { install: "npm install", run: "npm run" },
+  bun: { install: "bun install", run: "bun run" },
+};
+
+export function setupPackageManagerTool(pi: ExtensionAPI) {
+  pi.registerTool<typeof Params, PackageManagerDetails>({
+    name: "detect_package_manager",
+    label: "Package Manager",
+    description:
+      "Detect the package manager used in the current project by checking lockfiles and package.json",
+
+    parameters: Params,
+
+    async execute(
+      _toolCallId: string,
+      _params: ParamsType,
+      signal: AbortSignal | undefined,
+      onUpdate: unknown,
+      ctx: ExtensionContext,
+    ): Promise<ExecuteResult> {
+      const resolvedCtx = resolveCtx(signal, onUpdate, ctx);
+      const cwd = resolvedCtx.cwd;
+
+      try {
+        const packageJsonPath = path.join(cwd, "package.json");
+        if (!fs.existsSync(packageJsonPath)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No package.json found in ${cwd}`,
+              },
+            ],
+            details: {
+              success: false,
+              message: `No package.json found in ${cwd}`,
+              cwd,
+            },
+          };
+        }
+
+        // Walk up from cwd to repo root, collecting packageManager and lockfile.
+        // Stop at .git boundary to avoid escaping the repository.
+        let declaredPm: string | undefined;
+        let declaredVersion: string | undefined;
+        let lockfile: string | undefined;
+        let lockfilePm: string | undefined;
+
+        let searchDir = cwd;
+        while (true) {
+          // Check packageManager field in package.json
+          if (!declaredPm) {
+            const pkgPath = path.join(searchDir, "package.json");
+            try {
+              if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                if (typeof pkg.packageManager === "string") {
+                  const match = pkg.packageManager.match(/^([^@]+)@?(.*)?$/);
+                  if (match) {
+                    declaredPm = match[1];
+                    declaredVersion = match[2] || undefined;
+                  }
+                }
+              }
+            } catch {
+              // Ignore parse errors
+            }
+          }
+
+          // Check lockfiles
+          if (!lockfilePm) {
+            for (const [filename, pm] of Object.entries(LOCKFILES)) {
+              if (fs.existsSync(path.join(searchDir, filename))) {
+                lockfilePm = pm;
+                lockfile = filename;
+                break;
+              }
+            }
+          }
+
+          // Stop if we found both, hit .git, or hit filesystem root
+          if (
+            (declaredPm && lockfilePm) ||
+            fs.existsSync(path.join(searchDir, ".git"))
+          ) {
+            break;
+          }
+          const parent = path.dirname(searchDir);
+          if (parent === searchDir) break;
+          searchDir = parent;
+        }
+
+        const pm = declaredPm || lockfilePm || "npm";
+        const fallback = { install: `${pm} install`, run: pm };
+        const commands = COMMANDS[pm] ?? fallback;
+
+        const parts: string[] = [];
+        parts.push(`Package manager: ${pm}`);
+        if (declaredVersion) {
+          parts.push(`Declared version: ${declaredVersion}`);
+        }
+        if (lockfile) {
+          parts.push(`Lockfile: ${lockfile}`);
+        }
+        if (!lockfile && !declaredPm) {
+          parts.push(
+            "No lockfile or packageManager field found, defaulting to npm",
+          );
+        }
+        parts.push(`Install: ${commands.install}`);
+        parts.push(`Run: ${commands.run}`);
+
+        const message = parts.join("\n");
+
+        return {
+          content: [{ type: "text", text: message }],
+          details: {
+            success: true,
+            message,
+            packageManager: pm,
+            version: declaredVersion,
+            lockfile,
+            installCommand: commands.install,
+            runCommand: commands.run,
+            cwd,
+          },
+        };
+      } catch (error) {
+        const message = `Error detecting package manager: ${error instanceof Error ? error.message : String(error)}`;
+        return {
+          content: [{ type: "text", text: message }],
+          details: {
+            success: false,
+            message,
+            cwd,
+          },
+        };
+      }
+    },
+
+    renderCall(_args: ParamsType, theme: Theme) {
+      return new ToolCallHeader({ toolName: "Detect Package Manager" }, theme);
+    },
+
+    renderResult(
+      result: AgentToolResult<PackageManagerDetails>,
+      _options: ToolRenderResultOptions,
+      theme: Theme,
+    ): Text {
+      const { details } = result;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(
+          text?.type === "text" && text.text ? text.text : "No result",
+          0,
+          0,
+        );
+      }
+
+      if (!details.success) {
+        return new Text(theme.fg("error", details.message), 0, 0);
+      }
+
+      const lines: string[] = [];
+      lines.push(
+        theme.fg(
+          "success",
+          `Package manager: ${theme.bold(details.packageManager || "unknown")}`,
+        ),
+      );
+      if (details.version) {
+        lines.push(theme.fg("dim", `Version: ${details.version}`));
+      }
+      if (details.lockfile) {
+        lines.push(theme.fg("dim", `Lockfile: ${details.lockfile}`));
+      }
+
+      return new Text(lines.join("\n"), 0, 0);
+    },
+  });
+}

package/src/tools/utils.ts

@@ -0,0 +1,62 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Find the currently running Pi installation directory by resolving the
+ * pi-coding-agent package location.
+ */
+export function findPiInstallation(): string | null {
+  try {
+    const piModulePath = require.resolve(
+      "@mariozechner/pi-coding-agent/package.json",
+    );
+    return path.dirname(piModulePath);
+  } catch (_error) {
+    const scriptPath = process.argv[1];
+    if (scriptPath) {
+      let currentDir = path.dirname(scriptPath);
+
+      while (currentDir !== path.dirname(currentDir)) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+          try {
+            const packageContent = fs.readFileSync(packageJsonPath, "utf-8");
+            const packageJson = JSON.parse(packageContent);
+            if (packageJson.name === "@mariozechner/pi-coding-agent") {
+              return currentDir;
+            }
+          } catch {
+            // Continue searching
+          }
+        }
+        currentDir = path.dirname(currentDir);
+      }
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Resolve ExtensionContext from execute args, compatible with Pi 0.50.x and
+ * 0.51.0+.
+ *
+ * Pi 0.50.x: execute(id, params, onUpdate, ctx, signal)
+ * Pi 0.51.0+: execute(id, params, signal, onUpdate, ctx)
+ *
+ * When compiled against 0.51.0+, the typed params are (signal, onUpdate, ctx).
+ * On 0.50.x at runtime, `signal` actually receives the onUpdate callback
+ * (a function), `onUpdate` receives ctx, and `ctx` receives signal.
+ */
+export function resolveCtx(
+  signal: AbortSignal | undefined,
+  onUpdate: unknown,
+  ctx: ExtensionContext,
+): ExtensionContext {
+  // AbortSignal is never callable; a function here means we got onUpdate (0.50.x)
+  if (typeof signal === "function") {
+    return onUpdate as ExtensionContext;
+  }
+  return ctx;
+}

package/src/tools/version-tool.ts

@@ -0,0 +1,77 @@
+import { ToolCallHeader } from "@aliou/pi-utils-ui";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { VERSION } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+const VersionParams = Type.Object({});
+type VersionParamsType = Record<string, never>;
+
+interface VersionDetails {
+  success: boolean;
+  message: string;
+  version: string;
+}
+
+type ExecuteResult = AgentToolResult<VersionDetails>;
+
+export function setupVersionTool(pi: ExtensionAPI) {
+  pi.registerTool<typeof VersionParams, VersionDetails>({
+    name: "pi_version",
+    label: "Pi Version",
+    description: "Get the version of the currently running Pi instance",
+
+    parameters: VersionParams,
+
+    async execute(
+      _toolCallId: string,
+      _params: VersionParamsType,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ): Promise<ExecuteResult> {
+      const message = `Pi version ${VERSION}`;
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          success: true,
+          message,
+          version: VERSION,
+        },
+      };
+    },
+
+    renderCall(_args: VersionParamsType, theme: Theme) {
+      return new ToolCallHeader({ toolName: "Pi Version" }, theme);
+    },
+
+    renderResult(
+      result: AgentToolResult<VersionDetails>,
+      _options: ToolRenderResultOptions,
+      theme: Theme,
+    ): Text {
+      const { details } = result;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(
+          text?.type === "text" && text.text ? text.text : "No result",
+          0,
+          0,
+        );
+      }
+
+      return new Text(
+        theme.fg("accent", `Pi version: ${details.version}`),
+        0,
+        0,
+      );
+    },
+  });
+}