@trim21/personal-pi-extensions 0.1.557 → 0.1.558

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

@@ -0,0 +1,36 @@
+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 addReadPrTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "read-github-pr",
+    label: "GitHub PR",
+    description: "Get details of a GitHub pull request by number.",
+    promptSnippet: "Read a GitHub PR",
+    parameters: Type.Object({
+      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { number, repo } = params;
+      const result = toToolResult(
+        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 },
+        ),
+        params,
+      );
+      result.details.pendant = subtitlePendant(params, "number");
+      return result;
+    },
+  });
+}

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

@@ -0,0 +1,30 @@
+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 addReadReleaseTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    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" })),
+    }),
+    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

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type GhClient, ghExec, subtitlePendant, toToolResult } from "../base.js";
+
+export function addReadRepoTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    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" })),
+    }),
+    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-commit-checks.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type GhClient,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+  waitChecksReport,
+} from "../base.js";
+
+interface CommitChecksWaitParams {
+  commit: number | string;
+  repo?: string;
+  event?: string;
+  fail_fast?: boolean;
+}
+
+/** The toolcall handler behind `wait-github-commit-checks`. */
+async function waitCommitChecks(
+  gh: GhClient,
+  call: ToolCall<CommitChecksWaitParams>,
+): Promise<ToolResult> {
+  const { params, ctx, signal, onUpdate } = call;
+  const { commit, repo, event, fail_fast } = params;
+
+  const pendant = subtitlePendant(params, "commit");
+  onUpdate?.({
+    content: [{ type: "text", text: `Watching CI checks for commit ${commit}...` }],
+    details: {},
+  });
+
+  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+
+  const pollSignal = signal ?? new AbortController().signal;
+  const sha = await gh.checks.headSha(owner, repoName, String(commit), pollSignal);
+
+  return waitChecksReport({
+    checks: gh.checks,
+    subject: `commit ${sha.slice(0, 7)}`,
+    owner,
+    repo: repoName,
+    headSha: sha,
+    failFast: fail_fast === true,
+    event,
+    signal,
+    onUpdate,
+    params,
+    pendant,
+  });
+}
+
+export function addWaitCommitChecksTool(gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "wait-github-commit-checks",
+    label: "Watch GitHub Commit Checks",
+    description:
+      "Watch CI status checks for a commit until they complete — no pull request required. " +
+      "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
+      "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
+      "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
+      "commit statuses have an unknown trigger event and are excluded under a filter. " +
+      "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
+    promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
+    parameters: Type.Object({
+      commit: Type.Union([Type.Number(), Type.String()], {
+        description:
+          "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
+      }),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      event: Type.Optional(
+        Type.String({
+          description:
+            "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+        }),
+      ),
+      fail_fast: Type.Optional(
+        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return waitCommitChecks(gh, { params, ctx, signal, onUpdate });
+    },
+  });
+}

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

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+import {
+  type GhClient,
+  ghExec,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolCall,
+  type ToolResult,
+  waitChecksReport,
+} from "../base.js";
+
+interface PrChecksWaitParams {
+  number: number | string;
+  repo?: string;
+  fail_fast?: boolean;
+}
+
+const prHeadSchema = Type.Object({ headRefOid: Type.String() });
+
+/** The toolcall handler behind `wait-github-pr-checks`. */
+async function waitPrChecks(gh: GhClient, call: ToolCall<PrChecksWaitParams>): Promise<ToolResult> {
+  const { params, ctx, signal, onUpdate } = call;
+  const { number, repo, fail_fast } = params;
+
+  const pendant = subtitlePendant(params, "number");
+  onUpdate?.({
+    content: [{ type: "text", text: `Watching CI checks for PR #${number}...` }],
+    details: {},
+  });
+
+  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 { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
+
+  return waitChecksReport({
+    checks: gh.checks,
+    subject: `PR #${number}`,
+    owner,
+    repo: repoName,
+    headSha: headRefOid,
+    failFast: fail_fast === true,
+    signal,
+    onUpdate,
+    params,
+    pendant,
+  });
+}
+
+export function addWaitPrChecksTool(gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "wait-github-pr-checks",
+    label: "Watch GitHub PR Checks",
+    description:
+      "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
+      "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
+      "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
+      "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
+      "Use this when you need to wait for CI to complete and see the final result.",
+    promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
+    parameters: Type.Object({
+      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      fail_fast: Type.Optional(
+        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return waitPrChecks(gh, { params, ctx, signal, onUpdate });
+    },
+  });
+}

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

@@ -0,0 +1,45 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type GhClient, repoArgs, runGh, subtitlePendant } from "../base.js";
+
+export function addWatchRunTool(_gh: GhClient, pi: ExtensionAPI) {
+  pi.registerTool({
+    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;
+
+      const pendant = subtitlePendant(params, "run_id");
+      onUpdate?.({
+        content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
+        details: {},
+      });
+
+      const result = await runGh(["run", "watch", String(run_id), ...repoArgs(repo)], {
+        cwd: ctx.cwd,
+        signal,
+        timeout: 600_000,
+      });
+
+      if (result.code !== 0) {
+        throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
+      }
+
+      return {
+        content: [
+          { type: "text", text: `## Workflow Run ${run_id} Completed\n\n${result.stdout}` },
+        ],
+        details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
+      };
+    },
+  });
+}