@trim21/personal-pi-extensions 0.1.684 → 0.1.687

package/src/gh/tools/read-pr-diff.ts

@@ -1,27 +1,39 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+import { parseDiffStats } from "../render.js";
+import { ghDiffPayloadSchema } from "../schemas.js";
 
-export function addReadPrDiffTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr-diff",
-    label: "GitHub PR Diff",
-    description: "Get the diff of a GitHub pull request.",
-    promptSnippet: "Read a GitHub PR diff",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+export function addReadPrDiffTool(gh: GhClient, bus: ToolBus) {
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr-diff",
+      label: "GitHub PR Diff",
+      description: "Get the diff of a GitHub pull request.",
+      promptSnippet: "Read a GitHub PR diff",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghDiffPayloadSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { number, repo } = params;
+        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const diff = await gh.reads.pullDiff(owner, repoName, Number(number), signal);
+        const result = toToolResult(diff, params);
+        result.details.pendant = subtitlePendant(params, "number");
+        // 文本是原始 diff（没有 JSON 形式），载荷从同一份 diff 解析出变更统计
+        return withStructuredResult(result, { text: diff, ...parseDiffStats(diff) });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const args = ["pr", "diff", String(number), ...repoArgs(repo)];
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+  );
 }

package/src/gh/tools/read-pr.ts

@@ -3,14 +3,14 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toStructuredJsonResult,
 } from "../base.js";
 import { prViewSchema } from "../schemas.js";
 
-export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
+export function addReadPrTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-pr",
@@ -24,18 +24,10 @@ export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: prViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const out = await ghExec(
-          [
-            "pr",
-            "view",
-            String(number),
-            ...repoArgs(repo),
-            "--json",
-            "title,state,body,author,createdAt,updatedAt,mergedAt,mergedBy,headRefName,baseRefName,url,additions,deletions,changedFiles,labels,assignees,reviewRequests,reviews,comments,number",
-          ],
-          { cwd: ctx.cwd, signal, input: params },
-        );
-        const result = toStructuredJsonResult(out, params, prViewSchema);
+        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const data = await gh.reads.pull(owner, repoName, Number(number), signal);
+        const result = toStructuredJsonResult(JSON.stringify(data, null, 2), params, prViewSchema);
         result.details.pendant = subtitlePendant(params, "number");
         return result;
       },

package/src/gh/tools/read-release.ts

@@ -1,30 +1,42 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+import { renderReleaseView } from "../render.js";
+import { ghReleaseViewPayloadSchema, ghReleaseViewSchema } from "../schemas.js";
 
-export function addReadReleaseTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-release",
-    label: "GitHub Release",
-    description: "Get details of a specific GitHub release by tag.",
-    promptSnippet: "Read a GitHub release",
-    parameters: Type.Object({
-      tag: Type.String({ description: "Release tag name" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+export function addReadReleaseTool(gh: GhClient, bus: ToolBus) {
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-release",
+      label: "GitHub Release",
+      description:
+        "Get details of a specific GitHub release by tag: metadata, asset list and release notes.",
+      promptSnippet: "Read a GitHub release",
+      parameters: Type.Object({
+        tag: Type.String({ description: "Release tag name" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghReleaseViewPayloadSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { tag, repo } = params;
+        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const data = await gh.reads.release(owner, repoName, tag, signal);
+        const view = parseWithSchema(ghReleaseViewSchema, data);
+        const text = renderReleaseView(view);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params, "tag");
+        return withStructuredResult(result, { text, release: view });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { tag, repo } = params;
-      const result = toToolResult(
-        await ghExec(["release", "view", tag, ...repoArgs(repo)], {
-          cwd: ctx.cwd,
-          signal,
-          input: params,
-        }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "tag");
-      return result;
-    },
-  });
+  );
 }

package/src/gh/tools/read-repo.ts

@@ -1,29 +1,40 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+import { renderRepoView } from "../render.js";
+import { ghRepoPayloadSchema, ghRepoViewSchema } from "../schemas.js";
 
-export function addReadRepoTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-repo",
-    label: "GitHub Repo",
-    description: "Get repository information.",
-    promptSnippet: "Read GitHub repo info",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+export function addReadRepoTool(gh: GhClient, bus: ToolBus) {
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-repo",
+      label: "GitHub Repo",
+      description: "Get repository information.",
+      promptSnippet: "Read GitHub repo info",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghRepoPayloadSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { repo } = params;
+        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const data = await gh.reads.repository(owner, repoName, signal);
+        const view = parseWithSchema(ghRepoViewSchema, data);
+        const text = renderRepoView(view);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params);
+        return withStructuredResult(result, { text, repo: view });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { repo } = params;
-      const args = ["repo", "view"];
-      if (repo) {
-        args.push(repo);
-      }
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
-    },
-  });
+  );
 }

package/src/gh/tools/wait-pr-checks.ts

@@ -4,7 +4,6 @@ import { Value } from "typebox/value";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
   resolveRepo,
   splitRepo,
   type StructuredResultOf,
@@ -20,7 +19,8 @@ interface PrChecksWaitParams {
   fail_fast?: boolean;
 }
 
-const prHeadSchema = Type.Object({ headRefOid: Type.String() });
+/** pulls.get 里我们只需要 head commit 的 SHA（它决定查哪个 commit 的 checks）。 */
+const pullHeadSchema = Type.Object({ head: Type.Object({ sha: Type.String() }) });
 
 /** The toolcall handler behind `wait-github-pr-checks`. */
 async function waitPrChecks(
@@ -39,18 +39,17 @@ async function waitPrChecks(
   const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
   const { owner, repo: repoName } = splitRepo(effectiveRepo);
 
-  const prOut = await ghExec(
-    ["pr", "view", String(number), "--repo", effectiveRepo, "--json", "headRefOid"],
-    { cwd: ctx.cwd, signal, input: params },
+  const pull = Value.Parse(
+    pullHeadSchema,
+    await gh.reads.pull(owner, repoName, Number(number), signal),
   );
-  const { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
 
   return waitChecksReport({
     checks: gh.checks,
     subject: `PR #${number}`,
     owner,
     repo: repoName,
-    headSha: headRefOid,
+    headSha: pull.head.sha,
     failFast: fail_fast === true,
     signal,
     onUpdate,

package/src/gh/tools/watch-run.ts

@@ -1,46 +1,72 @@
 import { Type } from "typebox";
 
-import { runGh } from "../../lib/gh-process.js";
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, repoArgs, subtitlePendant } from "../base.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  renderRunStatus,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolResult,
+  watchRun,
+} from "../base.js";
+import { ghRunPayloadSchema } from "../schemas.js";
 
-export function addWatchRunTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "watch-github-run",
-    label: "Watch GitHub Workflow Run",
-    description:
-      "Watch a GitHub Actions workflow run until it completes. " +
-      "Blocks until the run finishes and shows the final status.",
-    promptSnippet: "Watch and wait for a GitHub Actions run to complete",
-    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) {
-      const { run_id, repo } = params;
+export function addWatchRunTool(gh: GhClient, bus: ToolBus) {
+  bus.register(
+    defineStructuredTool({
+      name: "watch-github-run",
+      label: "Watch GitHub Workflow Run",
+      description:
+        "Watch a GitHub Actions workflow run until it completes. " +
+        "Blocks until the run finishes and shows the final status.",
+      promptSnippet: "Watch and wait for a GitHub Actions run to complete",
+      parameters: Type.Object({
+        run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghRunPayloadSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        const { run_id, repo } = params;
+
+        const pendant = subtitlePendant(params, "run_id");
+        const publish = (message: ToolResult) => onUpdate?.(message);
+        publish({
+          content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
+          details: {},
+        });
 
-      const pendant = subtitlePendant(params, "run_id");
-      onUpdate?.({
-        content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
-        details: {},
-      });
+        // 轮询循环要求非空 signal（与两个 wait 工具一致：没有就自建一个）
+        const pollSignal = signal ?? new AbortController().signal;
+        const effectiveRepo = await resolveRepo(repo, pollSignal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const outcome = await watchRun({
+          owner,
+          repo: repoName,
+          runId: Number(run_id),
+          reads: gh.reads,
+          signal: pollSignal,
+          onUpdate: publish,
+        });
 
-      const result = await runGh(["run", "watch", String(run_id), ...repoArgs(repo)], {
-        cwd: ctx.cwd,
-        signal,
-        timeout: 600_000,
-      });
+        if (outcome.outcome === "timeout") {
+          throw new Error(
+            `workflow run ${run_id} did not finish within ${Math.round(outcome.elapsedMs / 1000)}s; last status: ${renderRunStatus(outcome.run)}`,
+          );
+        }
 
-      if (result.code !== 0) {
-        throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
-      }
+        const heading =
+          outcome.run.conclusion === "success"
+            ? `## Workflow Run ${run_id} Completed`
+            : `## Workflow Run ${run_id} Finished (${outcome.run.conclusion ?? "unknown"})`;
+        const text = `${heading}\n\n${renderRunStatus(outcome.run)}`;
 
-      return {
-        content: [
-          { type: "text", text: `## Workflow Run ${run_id} Completed\n\n${result.stdout}` },
-        ],
-        details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
-      };
-    },
-  });
+        return {
+          content: [{ type: "text" as const, text }],
+          details: { input: params, ...(pendant && { pendant }) },
+          structuredResult: { ok: true as const, value: { text, run: outcome.run } },
+        };
+      },
+    }),
+  );
 }