@trim21/personal-pi-extensions 0.1.685 → 0.1.688

package/README.md

@@ -16,7 +16,7 @@
 | [写保护（内置）](#写保护内置)             | 写工具内置：限制文件写入在 workspace 内，外部写入需审批                                       |
 | [LSP（内置）](#lsp内置)                   | 文件工具内置 LSP 诊断 + `lsp-rename`/`lsp-inspect`/`lsp-find-definition`/`lsp-find-reference` |
 | [aft](#aft)                               | AFT 只读代码感知：`aft_outline`/`aft_zoom`/`aft_callgraph`/`aft_search`                       |
-| [gh-readonly](#gh-readonly)               | GitHub 只读工具集（issue / PR / CI / release），基于 `gh` CLI                                 |
+| [gh-readonly](#gh-readonly)               | GitHub 只读工具集（issue / PR / CI / release），数据走 octokit REST                           |
 | [spawn-agent](#spawn-agent)               | 把任务委派给独立上下文窗口的子代理                                                            |
 | [system-prompt](#system-prompt)           | 完全替换 pi 默认 system prompt                                                                |
 | [vision-agent](#vision-agent)             | 视觉代理：主模型不支持视觉时提供 `describe_image`，调用视觉模型识别图片                       |
@@ -461,7 +461,7 @@ pi -e ./src/aft/index.ts
 
 ## gh-readonly
 
-GitHub 只读工具集，基于系统 [`gh`](https://cli.github.com/) CLI（关键词搜索与 checks 查询走 octokit REST）。`gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。
+GitHub 只读工具集。取数走 octokit REST（`src/lib/github-reads.ts`）；只有「当前仓库」解析（`gh repo view`）与 token 获取（`gh auth token`）还用系统 [`gh`](https://cli.github.com/)，因此 `gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。
 
 - **Issue / PR**：`read-github-issue`、`list-github-issues`、`read-github-issue-comments`、`read-github-pr`、`list-github-prs`、`read-github-pr-diff`、`read-github-pr-status`、`read-github-pr-comments`
 - **CI**：`read-github-ci-logs`、`list-github-workflow-runs`、`get-github-workflow-jobs`、`wait-github-pr-checks`、`wait-github-commit-checks`、`watch-github-run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.685",
+  "version": "0.1.688",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/gh/base.ts

@@ -20,14 +20,14 @@ import {
   type CommitStatus,
   createGithubChecks,
   createGithubSearch,
-  GH_LIST_FIELDS,
   type GithubChecksClient,
   type GithubClientOptions,
   type GithubSearch,
-  normalizeGhList,
+  normalizeRestList,
   renderHits,
   type SearchHit,
 } from "../lib/github.js";
+import { createGithubReads, type GithubReads } from "../lib/github-reads.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { type ToolPendant } from "../lib/pendant.js";
 import { type StructuredResult } from "../lib/tool-bus.js";
@@ -143,24 +143,6 @@ export async function ghExec(
   return result.stdout;
 }
 
-export function repoArgs(repo?: string): string[] {
-  return repo ? ["--repo", repo] : [];
-}
-
-/**
- * `gh api` for a JSON-array endpoint, following pagination. The REST API pages
- * these lists at 30 items by default, so a single page silently drops the rest;
- * `--slurp` is required because `--paginate` alone prints the pages back to back
- * (not valid JSON), and the page arrays are flattened back into one list.
- */
-export async function ghApiList(
-  path: string,
-  ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
-): Promise<unknown[]> {
-  const out = await ghExec(["api", "--paginate", "--slurp", path], ctx);
-  return Value.Parse(Type.Array(Type.Array(Type.Unknown())), JSON.parse(out)).flat();
-}
-
 /** Split `OWNER/REPO`; throws when the name doesn't have exactly one slash. */
 export function splitRepo(nameWithOwner: string): { owner: string; repo: string } {
   const slash = nameWithOwner.indexOf("/");
@@ -326,53 +308,30 @@ export interface ListFilters {
 }
 
 /**
- * Build the `gh` argv for browsing issues/PRs (no keyword search).
- *
- * Keyword searches no longer go through the `gh` CLI — the octokit-based client
- * in `../lib/github.ts` handles them with state values (`all`, and `merged` for
- * PRs) that `gh search` cannot express. Browse calls keep `gh issue list` /
- * `gh pr list` semantics: `state` is passed through verbatim, since `gh issue
- * list` accepts open/closed/all and `gh pr list` additionally accepts merged.
- */
-export function listGithubArgs(kind: "issue" | "pr", params: ListFilters): string[] {
-  const { repo, state, label, author, assignee, milestone, limit } = params;
-
-  const args = [kind, "list", ...repoArgs(repo)];
-  if (state) {
-    args.push("--state", state);
-  }
-  if (label) {
-    args.push("--label", label);
-  }
-  if (author) {
-    args.push("--author", author);
-  }
-  if (assignee) {
-    args.push("--assignee", assignee);
-  }
-  if (milestone) {
-    args.push("--milestone", milestone);
-  }
-  if (limit) {
-    args.push("--limit", String(limit));
-  }
-  return args;
-}
-
-/**
- * 浏览分支（`gh issue list` / `gh pr list`，不带 keywords）：直接要 `--json`，再归一到与
- * 搜索分支同一套 `SearchHit`。repo 缺省时先解析当前仓库——文本要据此决定是否带 repo 列，
- * 载荷里也必须有值。
+ * 浏览分支（不带 keywords）：走 octokit 的 REST 列表端点，再归一到与搜索分支同一套
+ * `SearchHit`。repo 缺省时先解析当前仓库——文本要据此决定是否带 repo 列，载荷里也必须有值。
  */
 export async function browseList(
+  gh: GhClient,
   kind: "issue" | "pr",
   params: ListFilters,
   ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
 ): Promise<{ repo: string; hits: SearchHit[] }> {
   const repo = params.repo ?? (await resolveRepo(undefined, ctx.signal, ctx.cwd, ctx.input));
-  const args = [...listGithubArgs(kind, params), "--json", GH_LIST_FIELDS];
-  const stdout = await ghExec(args, ctx);
-  return { repo, hits: normalizeGhList(stdout, repo) };
+  const { owner, repo: repoName } = splitRepo(repo);
+  const query = {
+    state: params.state,
+    label: params.label,
+    author: params.author,
+    assignee: params.assignee,
+    milestone: params.milestone,
+    limit: params.limit,
+  };
+  const items =
+    kind === "issue"
+      ? await gh.reads.listIssues(owner, repoName, query, ctx.signal)
+      : await gh.reads.listPulls(owner, repoName, query, ctx.signal);
+  return { repo, hits: normalizeRestList(items, repo) };
 }
 
 /** 行列表的文本：两条分支共用一套 TSV 渲染；空结果是成功结果。 */
@@ -400,6 +359,8 @@ export class GhClient {
   readonly fetch: typeof globalThis.fetch;
   readonly search: GithubSearch;
   readonly checks: GithubChecksClient;
+  /** REST 读取层：gh 工具的取数都走它（不再 spawn `gh` 取数据）。 */
+  readonly reads: GithubReads;
 
   constructor(
     fetchImpl: typeof globalThis.fetch = egress.fetch,
@@ -408,12 +369,31 @@ export class GhClient {
     this.fetch = fetchImpl;
     this.search = createGithubSearch({ fetch: fetchImpl, ...options });
     this.checks = createGithubChecks({ fetch: fetchImpl, ...options });
+    this.reads = createGithubReads({ fetch: fetchImpl, ...options });
   }
 }
 
 // ── checks watch (pure rendering + poll loop) ────────────────────────────────
 
 const CHECKS_POLL_INTERVAL_MS = 30_000;
+/** `watch-github-run` 的轮询间隔与上限。 */
+const RUN_WATCH_INTERVAL_MS = 30_000;
+const RUN_WATCH_DEADLINE_MS = 600_000;
+
+/** 运行快照：只声明我们渲染与载荷用到的字段，其余由 REST 原样带过。 */
+const runSnapshotSchema = Type.Object({
+  id: Type.Number(),
+  name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  display_title: Type.Optional(Type.String()),
+  status: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  conclusion: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  head_branch: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  event: Type.Optional(Type.String()),
+  created_at: Type.Optional(Type.String()),
+  updated_at: Type.Optional(Type.String()),
+  run_started_at: Type.Optional(Type.String()),
+  html_url: Type.Optional(Type.String()),
+});
 const CHECKS_WATCH_DEADLINE_MS = 600_000;
 
 export type CheckBucket = "pass" | "skipped" | "fail" | "pending";
@@ -654,6 +634,81 @@ export async function pollPrChecks(options: PollPrChecksOptions): Promise<Checks
   }
 }
 
+/** One polled workflow run: the REST fields the watch loop reports and renders. */
+export interface RunSnapshot {
+  id: number;
+  name?: string | null;
+  display_title?: string;
+  status?: string | null;
+  conclusion?: string | null;
+  head_branch?: string | null;
+  event?: string;
+  created_at?: string;
+  updated_at?: string;
+  run_started_at?: string;
+  html_url?: string;
+}
+
+/** 一行运行状态：`工作流 · 事件 · 分支 — 状态`（附耗时与链接）。 */
+export function renderRunStatus(run: RunSnapshot, elapsedMs?: number): string {
+  const state = run.conclusion ?? run.status ?? "unknown";
+  const facts = [run.name, run.event, run.head_branch].filter(Boolean).join(" · ");
+  const elapsed = elapsedMs === undefined ? "" : ` (${Math.round(elapsedMs / 1000)}s)`;
+  return `${facts} — ${state}${elapsed}${run.html_url === undefined ? "" : `\n${run.html_url}`}`;
+}
+
+export interface WatchRunOptions {
+  owner: string;
+  repo: string;
+  runId: number;
+  reads: GithubReads;
+  /** Owned by the caller; the poll loop observes it but never aborts it. */
+  signal: AbortSignal;
+  /** Test overrides. */
+  intervalMs?: number;
+  deadlineMs?: number;
+  onUpdate?: (msg: ToolResult) => void;
+}
+
+export interface RunWatchResult {
+  outcome: "completed" | "timeout";
+  run: RunSnapshot;
+  elapsedMs: number;
+}
+
+/**
+ * 轮询 `getWorkflowRun` 直到运行结束（`gh run watch` 的替代）：固定间隔轮询，每轮通过
+ * onUpdate 报一次当前状态，超过上限以 timeout 结束（不挂住）。
+ */
+export async function watchRun(options: WatchRunOptions): Promise<RunWatchResult> {
+  const { owner, repo, runId, reads, signal, onUpdate } = options;
+  const intervalMs = options.intervalMs ?? RUN_WATCH_INTERVAL_MS;
+  const deadlineMs = options.deadlineMs ?? RUN_WATCH_DEADLINE_MS;
+
+  const watchStart = Date.now();
+  for (;;) {
+    signal.throwIfAborted();
+    const run = parseWithSchema(runSnapshotSchema, await reads.run(owner, repo, runId, signal));
+    const elapsedMs = Date.now() - watchStart;
+    onUpdate?.({
+      content: [
+        {
+          type: "text",
+          text: `Watching workflow run ${runId}...\n${renderRunStatus(run, elapsedMs)}`,
+        },
+      ],
+      details: {},
+    });
+    if (run.status === "completed") {
+      return { outcome: "completed", run, elapsedMs };
+    }
+    if (elapsedMs >= deadlineMs) {
+      return { outcome: "timeout", run, elapsedMs };
+    }
+    await sleepInterruptibly(intervalMs, signal);
+  }
+}
+
 /** Job conclusions that count as "did not succeed" for CI result reporting. */
 const FAILED_JOB_CONCLUSIONS = new Set([
   "failure",

package/src/gh/render.ts

@@ -6,15 +6,20 @@
 
 import { dateOnly } from "../lib/github.js";
 
-/** 一行一个 release：`tag  标记  发布日期  标题`。 */
+/**
+ * 一行一个 release：`tag  标记  发布日期  标题`。
+ *
+ * 标记有 `latest`（该仓库最新发布）/ `prerelease` / `draft`；REST 没有「isLatest」字段
+ * （那是 gh 按列表顺序算的），所以由调用方按第一个非 draft/prerelease 的条目传进来。
+ */
 export function renderReleaseList(
   releases: {
-    tagName: string;
-    name?: string;
-    isLatest?: boolean;
-    isPrerelease?: boolean;
-    isDraft?: boolean;
-    publishedAt?: string | null;
+    tag_name: string;
+    name?: string | null;
+    latest?: boolean;
+    prerelease?: boolean;
+    draft?: boolean;
+    published_at?: string | null;
   }[],
 ): string {
   if (releases.length === 0) {
@@ -23,14 +28,14 @@ export function renderReleaseList(
   return releases
     .map((release) => {
       const flags = [
-        release.isLatest ? "latest" : "",
-        release.isPrerelease ? "prerelease" : "",
-        release.isDraft ? "draft" : "",
+        release.latest ? "latest" : "",
+        release.prerelease ? "prerelease" : "",
+        release.draft ? "draft" : "",
       ].filter(Boolean);
       return [
-        release.tagName,
+        release.tag_name,
         flags.join(","),
-        dateOnly(release.publishedAt),
+        dateOnly(release.published_at),
         release.name ?? "",
       ].join("\t");
     })
@@ -40,14 +45,14 @@ export function renderReleaseList(
 /** 一行一个运行：`id  状态  结论  工作流  分支  事件  创建时间  链接`。 */
 export function renderRunList(
   runs: {
-    databaseId: number;
-    status?: string;
+    id: number;
+    status?: string | null;
     conclusion?: string | null;
-    workflowName?: string;
-    headBranch?: string;
+    name?: string | null;
+    head_branch?: string | null;
     event?: string;
-    createdAt?: string;
-    url?: string;
+    created_at?: string;
+    html_url?: string;
   }[],
 ): string {
   if (runs.length === 0) {
@@ -56,14 +61,14 @@ export function renderRunList(
   return runs
     .map((run) =>
       [
-        String(run.databaseId),
+        String(run.id),
         run.status ?? "",
         run.conclusion ?? "",
-        run.workflowName ?? "",
-        run.headBranch ?? "",
+        run.name ?? "",
+        run.head_branch ?? "",
         run.event ?? "",
-        dateOnly(run.createdAt),
-        run.url ?? "",
+        dateOnly(run.created_at),
+        run.html_url ?? "",
       ].join("\t"),
     )
     .join("\n");
@@ -71,37 +76,35 @@ export function renderRunList(
 
 /** 仓库概览：标题行 + 一行事实 + 一行链接 + 一行日期/许可。 */
 export function renderRepoView(repo: {
-  nameWithOwner?: string;
-  description?: string;
-  url?: string;
+  full_name?: string;
+  description?: string | null;
+  html_url?: string;
   visibility?: string;
-  primaryLanguage?: { name: string } | null;
-  defaultBranchRef?: { name: string } | null;
-  stargazerCount?: number;
-  forkCount?: number;
-  issues?: { totalCount: number } | null;
-  pullRequests?: { totalCount: number } | null;
-  licenseInfo?: { name: string } | null;
-  pushedAt?: string;
-  createdAt?: string;
+  language?: string | null;
+  default_branch?: string;
+  stargazers_count?: number;
+  forks_count?: number;
+  open_issues_count?: number;
+  license?: { name?: string } | null;
+  pushed_at?: string;
+  created_at?: string;
 }): string {
   const facts = [
     repo.visibility?.toLowerCase(),
-    repo.primaryLanguage?.name,
-    repo.defaultBranchRef && `default branch ${repo.defaultBranchRef.name}`,
-    repo.stargazerCount !== undefined && `stars ${repo.stargazerCount}`,
-    repo.forkCount !== undefined && `forks ${repo.forkCount}`,
-    repo.issues && `open issues ${repo.issues.totalCount}`,
-    repo.pullRequests && `open PRs ${repo.pullRequests.totalCount}`,
+    repo.language,
+    repo.default_branch && `default branch ${repo.default_branch}`,
+    repo.stargazers_count !== undefined && `stars ${repo.stargazers_count}`,
+    repo.forks_count !== undefined && `forks ${repo.forks_count}`,
+    repo.open_issues_count !== undefined && `open issues ${repo.open_issues_count}`,
   ].filter(Boolean);
   return [
-    [repo.nameWithOwner, repo.description].filter(Boolean).join(" — "),
+    [repo.full_name, repo.description].filter(Boolean).join(" — "),
     facts.join(" · "),
-    repo.url ?? "",
+    repo.html_url ?? "",
     [
-      repo.pushedAt && `pushed ${dateOnly(repo.pushedAt)}`,
-      repo.createdAt && `created ${dateOnly(repo.createdAt)}`,
-      repo.licenseInfo?.name,
+      repo.pushed_at && `pushed ${dateOnly(repo.pushed_at)}`,
+      repo.created_at && `created ${dateOnly(repo.created_at)}`,
+      repo.license?.name,
     ]
       .filter(Boolean)
       .join(" · "),
@@ -112,33 +115,30 @@ export function renderRepoView(repo: {
 
 /** release 详情：标题、事实、资产清单、正文。 */
 export function renderReleaseView(release: {
-  tagName?: string;
-  name?: string;
-  url?: string;
-  isLatest?: boolean;
-  isPrerelease?: boolean;
-  isDraft?: boolean;
-  publishedAt?: string | null;
-  createdAt?: string;
+  tag_name?: string;
+  name?: string | null;
+  html_url?: string;
+  /** 由调用方按「列表里第一个非 draft / prerelease」推断（REST 没有这个字段）。 */
+  latest?: boolean;
+  prerelease?: boolean;
+  draft?: boolean;
+  published_at?: string | null;
+  created_at?: string;
   author?: { login?: string } | null;
-  assets?: { name?: string; size?: number; downloadCount?: number }[];
-  body?: string;
+  assets?: { name?: string; size?: number; download_count?: number }[];
+  body?: string | null;
 }): string {
-  const flags = [
-    release.isLatest && "latest",
-    release.isPrerelease && "prerelease",
-    release.isDraft && "draft",
-  ]
+  const flags = [release.prerelease && "prerelease", release.draft && "draft"]
     .filter(Boolean)
     .join(",");
   const assets = release.assets ?? [];
   const lines = [
-    [release.tagName, release.name].filter(Boolean).join(" — "),
+    [release.tag_name, release.name].filter(Boolean).join(" — "),
     [
-      `published ${dateOnly(release.publishedAt ?? release.createdAt)}`,
+      `published ${dateOnly(release.published_at ?? release.created_at)}`,
       flags,
       release.author?.login && `by ${release.author.login}`,
-      release.url,
+      release.html_url,
     ]
       .filter(Boolean)
       .join(" · "),
@@ -147,7 +147,7 @@ export function renderReleaseView(release: {
     lines.push(`assets (${assets.length}):`);
     for (const asset of assets) {
       lines.push(
-        `- ${asset.name ?? ""} ${asset.size ?? 0} bytes, ${asset.downloadCount ?? 0} downloads`,
+        `- ${asset.name ?? ""} ${asset.size ?? 0} bytes, ${asset.download_count ?? 0} downloads`,
       );
     }
   }