@trim21/personal-pi-extensions 0.1.557 → 0.1.558

package/src/gh/index.ts

@@ -0,0 +1,108 @@
+/**
+ * GitHub Read-Only Tools Extension
+ *
+ * Provides individual read-only tools for GitHub operations using the system's `gh` CLI.
+ *
+ * Layout:
+ *   - `base.ts`            shared helpers (gh subprocess, result shaping, REST client, checks watch)
+ *   - `tools/<name>.ts`    one tool per file, each exporting `add<Name>Tool(gh, pi)`
+ *   - `index.ts`           this file: availability checks + tool registration
+ *
+ * Tools:
+ *   - read-github-issue: Get issue details
+ *   - list-github-issues: List or search issues
+ *   - read-github-issue-comments: Get issue comments
+ *   - read-github-pr: Get PR details
+ *   - list-github-prs: List or search PRs
+ *   - read-github-pr-diff: Get PR diff
+ *   - read-github-pr-status: Get PR status checks
+ *   - read-github-pr-comments: Get PR comments
+ *   - read-github-ci-logs: Get CI workflow run logs
+ *   - list-github-workflow-runs: List workflow runs
+ *   - get-github-workflow-jobs: Get workflow run jobs
+ *   - read-github-repo: Get repo info
+ *   - list-github-releases: List releases
+ *   - read-github-release: Get release details
+ *   - download-github-release-assets: Download a release's assets with gh credentials
+ *   - wait-github-pr-checks: Watch PR CI checks
+ *   - wait-github-commit-checks: Watch CI checks of a commit (no PR required)
+ *   - watch-github-run: Watch a workflow run
+ *
+ * Proxy (for the gh CLI and for the octokit-backed search/checks requests):
+ *   ~/.pi/agent/proxy.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }
+ *   HTTPS_PROXY / HTTP_PROXY / ALL_PROXY and NO_PROXY are used instead for the
+ *   fields the config file leaves out. The config is read once per process.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { GhClient, isGhAvailable } from "./base.js";
+import { addDownloadReleaseAssetsTool } from "./tools/download-release-assets.js";
+import { addGetWorkflowJobsTool } from "./tools/get-workflow-jobs.js";
+import { addListIssuesTool } from "./tools/list-issues.js";
+import { addListPrsTool } from "./tools/list-prs.js";
+import { addListReleasesTool } from "./tools/list-releases.js";
+import { addListWorkflowRunsTool } from "./tools/list-workflow-runs.js";
+import { addReadCiLogsTool } from "./tools/read-ci-logs.js";
+import { addReadIssueTool } from "./tools/read-issue.js";
+import { addReadIssueCommentsTool } from "./tools/read-issue-comments.js";
+import { addReadPrTool } from "./tools/read-pr.js";
+import { addReadPrCommentsTool } from "./tools/read-pr-comments.js";
+import { addReadPrDiffTool } from "./tools/read-pr-diff.js";
+import { addReadPrStatusTool } from "./tools/read-pr-status.js";
+import { addReadReleaseTool } from "./tools/read-release.js";
+import { addReadRepoTool } from "./tools/read-repo.js";
+import { addWaitCommitChecksTool } from "./tools/wait-commit-checks.js";
+import { addWaitPrChecksTool } from "./tools/wait-pr-checks.js";
+import { addWatchRunTool } from "./tools/watch-run.js";
+
+// Public API re-exports (tests import these from the extension entry).
+export * from "./base.js";
+export * from "./tools/download-release-assets.js";
+export * from "./tools/read-ci-logs.js";
+export * from "./tools/read-pr-status.js";
+
+export default function ghReadonlyTools(pi: ExtensionAPI) {
+  // Windows 上禁用：gh 可执行文件的探测（无扩展名 + POSIX 路径）与进程
+  // 管理（SIGTERM 信号语义）都是 POSIX 假设，不做 Windows 适配。
+  if (process.platform === "win32") {
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify("gh-readonly tools are disabled on Windows.", "warning");
+    });
+    return;
+  }
+
+  // Fail fast: the `gh` CLI is the only backend for these tools. Without it the
+  // extension registers nothing and reports the problem at session start, so
+  // the user gets one clear error instead of a dozen failing tool calls.
+  if (!isGhAvailable()) {
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify(
+        "gh CLI not found in PATH: GitHub read-only tools are disabled. Install GitHub CLI (https://cli.github.com/) and reload the session.",
+        "error",
+      );
+    });
+    return;
+  }
+
+  const gh = new GhClient();
+
+  addReadIssueTool(gh, pi);
+  addListIssuesTool(gh, pi);
+  addReadIssueCommentsTool(gh, pi);
+  addReadPrTool(gh, pi);
+  addListPrsTool(gh, pi);
+  addReadPrDiffTool(gh, pi);
+  addReadPrStatusTool(gh, pi);
+  addReadPrCommentsTool(gh, pi);
+  addReadCiLogsTool(gh, pi);
+  addListWorkflowRunsTool(gh, pi);
+  addGetWorkflowJobsTool(gh, pi);
+  addReadRepoTool(gh, pi);
+  addListReleasesTool(gh, pi);
+  addReadReleaseTool(gh, pi);
+  addDownloadReleaseAssetsTool(gh, pi);
+  addWaitPrChecksTool(gh, pi);
+  addWaitCommitChecksTool(gh, pi);
+  addWatchRunTool(gh, pi);
+}

package/src/gh/tools/download-release-assets.ts

@@ -0,0 +1,231 @@
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { type ToolPendant } from "../../lib/pendant.js";
+import {
+  type GhClient,
+  GhError,
+  ghExec,
+  repoArgs,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+} from "../base.js";
+
+interface ReleaseDownloadParams {
+  repo?: string;
+  tag?: string;
+  pattern?: string;
+  archive?: "zip" | "tar.gz";
+}
+
+/** `gh release view --json tagName,assets` 里本工具真正读取的字段。 */
+const releaseViewSchema = Type.Object({
+  tagName: Type.String(),
+  assets: Type.Array(Type.Object({ name: Type.String(), size: Type.Number() })),
+});
+
+/** One regular file in a release's download directory. */
+interface ReleaseFile {
+  name: string;
+  path: string;
+  bytes: number;
+}
+
+/**
+ * Directory the release assets of one release are downloaded into:
+ * `~/.cache/pi/github/releases/<owner>/<repo>/<tag>/`.
+ *
+ * A tag is a git ref name and may contain `/`; only the characters that are safe
+ * in one path segment survive, so a tag can never escape its own directory.
+ */
+export function releaseAssetDir(repo: string, tag: string): string {
+  const { owner, repo: name } = splitRepo(repo);
+  const safeTag = tag.replaceAll(/[^A-Za-z0-9._+-]/g, "_").replace(/^\.+$/, "_");
+  return join(homedir(), ".cache", "pi", "github", "releases", owner, name, safeTag);
+}
+
+/** Split the comma-separated `pattern` toolcall parameter into gh pattern values. */
+export function releasePatterns(pattern: string | undefined): string[] {
+  if (pattern === undefined) return [];
+  return pattern
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value !== "");
+}
+
+/**
+ * The `gh release download` argv. `--skip-existing` is always on: the download
+ * directory is a cache, and rewriting a file that is already there would pull
+ * the ground out from under anything reading it.
+ */
+export function releaseDownloadArgs(options: {
+  tag: string;
+  repo: string;
+  dir: string;
+  patterns: readonly string[];
+  archive?: "zip" | "tar.gz";
+}): string[] {
+  const { tag, repo, dir, patterns, archive } = options;
+  const args = ["release", "download", tag, ...repoArgs(repo)];
+  if (archive !== undefined) args.push("--archive", archive);
+  for (const pattern of patterns) args.push("--pattern", pattern);
+  args.push("--dir", dir, "--skip-existing");
+  return args;
+}
+
+/** Regular files directly inside `dir`, with their sizes, sorted by name. */
+async function listReleaseFiles(dir: string): Promise<ReleaseFile[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: ReleaseFile[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const path = join(dir, entry.name);
+    const info = await stat(path);
+    files.push({ name: entry.name, path, bytes: info.size });
+  }
+  return files.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * `gh release download` answers this exact message when a `--pattern` matched no
+ * asset. It is the only signal the CLI offers, so the enrichment below degrades
+ * to gh's own error (still thrown) if the wording ever changes.
+ */
+const GH_NO_ASSET_MATCH = "no assets match the file pattern";
+
+/**
+ * `download-github-release-assets`: fetch a release's assets (or source archive)
+ * into `releaseAssetDir` with the gh credentials, so private repositories work
+ * and the shell sandbox's network limits do not apply.
+ *
+ * The tag is resolved through `gh release view` before downloading: a tag that
+ * does not exist and a pattern that matched nothing are different answers, and
+ * the release's own asset names are what the model needs to fix the second one.
+ */
+export async function downloadReleaseAssets(
+  call: ToolCall<ReleaseDownloadParams>,
+): Promise<ToolResult> {
+  const { params, ctx, signal } = call;
+  const patterns = releasePatterns(params.pattern);
+  if (params.archive !== undefined && patterns.length > 0) {
+    throw new Error(
+      "pattern and archive are mutually exclusive (pick asset globs or the source archive)",
+    );
+  }
+
+  const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
+  const view = Value.Parse(
+    releaseViewSchema,
+    JSON.parse(
+      await ghExec(
+        [
+          "release",
+          "view",
+          ...(params.tag === undefined ? [] : [params.tag]),
+          ...repoArgs(effectiveRepo),
+          "--json",
+          "tagName,assets",
+        ],
+        { cwd: ctx.cwd, signal, input: params },
+      ),
+    ),
+  );
+
+  const assetNames = view.assets.map((asset) => asset.name);
+  const dir = releaseAssetDir(effectiveRepo, view.tagName);
+  await mkdir(dir, { recursive: true });
+  try {
+    await ghExec(
+      releaseDownloadArgs({
+        tag: view.tagName,
+        repo: effectiveRepo,
+        dir,
+        patterns,
+        ...(params.archive !== undefined && { archive: params.archive }),
+      }),
+      { cwd: ctx.cwd, signal, input: params },
+    );
+  } catch (error) {
+    // gh names the fault but not the choices; the release's asset list turns a
+    // dead end into the next toolcall.
+    if (error instanceof GhError && error.stderr.includes(GH_NO_ASSET_MATCH)) {
+      throw new Error(
+        `no asset of ${effectiveRepo}@${view.tagName} matched ${JSON.stringify(patterns)}; the release has: ${assetNames.join(", ") || "(no assets)"}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+
+  const files = await listReleaseFiles(dir);
+  const payload = { repo: effectiveRepo, tag: view.tagName, dir, files };
+  const pendant: ToolPendant | undefined = subtitlePendant(
+    { repo: effectiveRepo, tag: view.tagName },
+    "tag",
+  );
+
+  if (files.length === 0 && params.archive === undefined) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Nothing to download from ${effectiveRepo}@${view.tagName}: the release has no assets (try archive for the source tarball)`,
+        },
+      ],
+      details: {
+        ...payload,
+        available_assets: assetNames,
+        input: params,
+        ...(pendant && { pendant }),
+      },
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: { ...payload, input: params, ...(pendant && { pendant }) },
+  };
+}
+
+export function addDownloadReleaseAssetsTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "download-github-release-assets",
+    label: "GitHub Release Download",
+    description:
+      "Download a GitHub release's assets (or its source archive) into " +
+      "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the gh CLI's credentials, " +
+      "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
+      "Files already in that directory are kept, never re-fetched. The result is the JSON " +
+      "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
+      "directory; file contents are not echoed. Read the entries you need from `path`.",
+    promptSnippet: "Download GitHub release assets",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      tag: Type.Optional(
+        Type.String({ description: "Release tag (defaults to the latest release)" }),
+      ),
+      pattern: Type.Optional(
+        Type.String({
+          description:
+            'Comma-separated glob patterns for asset names, e.g. "*.tar.gz,*.deb" (default: every asset)',
+        }),
+      ),
+      archive: Type.Optional(
+        Type.Union([Type.Literal("zip"), Type.Literal("tar.gz")], {
+          description: "Download the release's source archive instead of its assets",
+        }),
+      ),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return downloadReleaseAssets({ params, ctx, signal });
+    },
+  });
+}

package/src/gh/tools/get-workflow-jobs.ts

@@ -0,0 +1,48 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type GhClient,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+  toPositiveId,
+  toToolResult,
+} from "../base.js";
+
+interface RunIdParams {
+  run_id: number | string;
+  repo?: string;
+}
+
+/** The toolcall handler behind `get-github-workflow-jobs`: every job of a run, all pages. */
+async function workflowJobs(gh: GhClient, call: ToolCall<RunIdParams>): Promise<ToolResult> {
+  const { params, ctx, signal } = call;
+  const runId = toPositiveId(params.run_id, "run_id");
+  const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
+  const { owner, repo: name } = splitRepo(effectiveRepo);
+
+  const jobs = await gh.checks.runJobs(owner, name, runId, signal);
+  const result = toToolResult(JSON.stringify({ total_count: jobs.length, jobs }), params);
+  result.details.pendant = subtitlePendant(params, "run_id");
+  return result;
+}
+
+export function addGetWorkflowJobsTool(gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "get-github-workflow-jobs",
+    label: "GitHub Workflow Jobs",
+    description:
+      "Get every job of a workflow run as JSON {total_count, jobs:[{id, run_id, run_url, name, status, conclusion, html_url, steps:[{name, number, status, conclusion, started_at}]}]}. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
+    promptSnippet: "Get GitHub workflow run jobs",
+    parameters: Type.Object({
+      run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return workflowJobs(gh, { params, ctx, signal, onUpdate });
+    },
+  });
+}

package/src/gh/tools/list-issues.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type GhClient,
+  type ListFilters,
+  listGithub,
+  searchList,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+  toToolResult,
+} from "../base.js";
+
+async function listIssues(gh: GhClient, call: ToolCall<ListFilters>): Promise<ToolResult> {
+  const { params, ctx, signal } = call;
+  const result = toToolResult(
+    params.keywords
+      ? await searchList("issue", params, gh.search)
+      : await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
+    params,
+  );
+  result.details.pendant = subtitlePendant(params);
+  return result;
+}
+
+export function addListIssuesTool(gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "list-github-issues",
+    label: "GitHub Issues List",
+    description:
+      'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones. Set fields to choose the columns of each result row.',
+    promptSnippet: "List or search GitHub issues",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
+      state: Type.Optional(
+        Type.String({
+          description:
+            "open, closed, all (default: open; all applies to keyword search and covers closed too)",
+        }),
+      ),
+      label: Type.Optional(Type.String({ description: "Filter by label" })),
+      author: Type.Optional(Type.String({ description: "Filter by author" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
+      milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt",
+        }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return listIssues(gh, { params, ctx, signal, onUpdate });
+    },
+  });
+}

package/src/gh/tools/list-prs.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type GhClient,
+  type ListFilters,
+  listGithub,
+  searchList,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+  toToolResult,
+} from "../base.js";
+
+async function listPrs(gh: GhClient, call: ToolCall<ListFilters>): Promise<ToolResult> {
+  const { params, ctx, signal } = call;
+  const result = toToolResult(
+    params.keywords
+      ? await searchList("pr", params, gh.search)
+      : await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
+    params,
+  );
+  result.details.pendant = subtitlePendant(params);
+  return result;
+}
+
+export function addListPrsTool(gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "list-github-prs",
+    label: "GitHub PRs List",
+    description:
+      'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden. Set fields to choose the columns of each result row.',
+    promptSnippet: "List or search GitHub PRs",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
+      state: Type.Optional(
+        Type.String({
+          description:
+            "open, closed, merged, all (default: open; all applies to keyword search and covers open + closed + merged)",
+        }),
+      ),
+      label: Type.Optional(Type.String({ description: "Filter by label" })),
+      author: Type.Optional(Type.String({ description: "Filter by author" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
+      milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt,mergedAt",
+        }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return listPrs(gh, { params, ctx, signal, onUpdate });
+    },
+  });
+}

package/src/gh/tools/list-releases.ts

@@ -0,0 +1,28 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+
+export function addListReleasesTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "list-github-releases",
+    label: "GitHub Releases List",
+    description: "List GitHub releases.",
+    promptSnippet: "List GitHub releases",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { repo, limit } = params;
+      const args = ["release", "list", ...repoArgs(repo)];
+      if (limit) args.push("--limit", String(limit));
+      const result = toToolResult(
+        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
+        params,
+      );
+      result.details.pendant = subtitlePendant(params);
+      return result;
+    },
+  });
+}

package/src/gh/tools/list-workflow-runs.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+
+export function addListWorkflowRunsTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "list-github-workflow-runs",
+    label: "GitHub Workflow Runs",
+    description: "List GitHub Actions workflow runs.",
+    promptSnippet: "List GitHub workflow runs",
+    parameters: Type.Object({
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 20)" })),
+      status: Type.Optional(
+        Type.String({ description: "Filter by status: success, failure, cancelled, etc." }),
+      ),
+      workflow: Type.Optional(Type.String({ description: "Filter by workflow name or file" })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { repo, limit, status, workflow } = params;
+      const args = ["run", "list", ...repoArgs(repo)];
+      if (limit) args.push("--limit", String(limit));
+      if (status) args.push("--status", status);
+      if (workflow) args.push("--workflow", workflow);
+      const result = toToolResult(
+        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
+        params,
+      );
+      result.details.pendant = subtitlePendant(params);
+      return result;
+    },
+  });
+}