@trim21/personal-pi-extensions 0.1.685 → 0.1.687

package/src/lib/github-reads.ts

@@ -0,0 +1,405 @@
+/**
+ * gh 工具的 REST 读取层：把「按 owner/repo/编号取数据」这一件事集中在这里，让工具文件
+ * 只关心渲染与载荷（与 `createGithubSearch` / `createGithubChecks` 并列）。
+ *
+ * 与 `gh … --json` 的差别：字段名是 GitHub REST 的（`html_url` / `closed_at` / `user.login`），
+ * 工具因此直接把响应原物给模型与结构化载荷，不再有 GraphQL 形状的中间层。
+ *
+ * 认证、代理与 401 重试都由 `createGithubApi` 承担（同一个缓存 client）；二进制下载走
+ * `rawFetch`，因为 octokit 会把响应体按 JSON 解析。
+ */
+
+import { createWriteStream } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import type { Octokit } from "octokit";
+
+import { createGithubApi, type GithubClientOptions } from "./github.js";
+
+/** `actions.listWorkflowRuns*` 的 `status` 取值（octokit 是字面量联合，工具参数是 string）。 */
+type WorkflowRunParams = NonNullable<
+  Parameters<Octokit["rest"]["actions"]["listWorkflowRunsForRepo"]>[0]
+>;
+type WorkflowRunStatus = NonNullable<WorkflowRunParams["status"]>;
+
+/** 列表类查询的公共过滤条件；与工具的 `ListFilters` 一一对应。 */
+export interface ListQuery {
+  state?: string;
+  label?: string;
+  author?: string;
+  assignee?: string;
+  milestone?: string;
+  limit?: number;
+}
+
+export interface GithubReads {
+  issue(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<unknown>;
+  pull(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<unknown>;
+  issueComments(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullReviewComments(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullReviews(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  listIssues(
+    owner: string,
+    repo: string,
+    query: ListQuery,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  listPulls(
+    owner: string,
+    repo: string,
+    query: ListQuery,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullDiff(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<string>;
+  listReleases(
+    owner: string,
+    repo: string,
+    limit: number | undefined,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  /** `tag` 缺省时取 latest release（与 `gh release view` 的缺省一致）。 */
+  release(
+    owner: string,
+    repo: string,
+    tag: string | undefined,
+    signal?: AbortSignal,
+  ): Promise<unknown>;
+  listRuns(
+    owner: string,
+    repo: string,
+    query: { workflow?: string; status?: string; limit?: number },
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  run(owner: string, repo: string, runId: number, signal?: AbortSignal): Promise<unknown>;
+  repository(owner: string, repo: string, signal?: AbortSignal): Promise<unknown>;
+  /** job 的原始日志文本（GitHub 只有按 job id 取日志的端点）。 */
+  jobLogs(owner: string, repo: string, jobId: number, signal?: AbortSignal): Promise<string>;
+  /** 下载一个 release 资产到 `destPath`（流式，不整体驻留内存）。 */
+  downloadAssetTo(
+    owner: string,
+    repo: string,
+    assetId: number,
+    destPath: string,
+    signal?: AbortSignal,
+  ): Promise<void>;
+  /** 下载仓库源码归档（`gh release download --archive` 的对应物）。 */
+  downloadArchiveTo(
+    owner: string,
+    repo: string,
+    format: "zip" | "tar.gz",
+    ref: string | undefined,
+    destPath: string,
+    signal?: AbortSignal,
+  ): Promise<void>;
+}
+
+/** REST 列表查询把工具的 state 过滤映射成 `state` 参数（issue/PR 的值集合相同）。 */
+function stateParam(state: string | undefined): "open" | "closed" | "all" | undefined {
+  if (state === undefined || state === "all") {
+    return state === "all" ? "all" : undefined;
+  }
+  if (state === "open" || state === "closed") {
+    return state;
+  }
+  // merged 只对搜索路径有意义（列表端点没有这个状态），列表侧按 all 处理
+  if (state === "merged") {
+    return "all";
+  }
+  throw new Error(`invalid state: ${state} (expected open, closed, all)`);
+}
+
+/** `@me` 是 gh CLI 的简写，REST 列表端点不认识；按字面量转发（用户明确不做展开）。 */
+function listParams(query: ListQuery): {
+  state?: "open" | "closed" | "all";
+  labels?: string;
+  assignee?: string;
+  creator?: string;
+  milestone?: string;
+} {
+  const state = stateParam(query.state);
+  return {
+    ...(state !== undefined && { state }),
+    ...(query.label !== undefined && { labels: query.label }),
+    ...(query.assignee !== undefined && { assignee: query.assignee }),
+    ...(query.author !== undefined && { creator: query.author }),
+    ...(query.milestone !== undefined && { milestone: query.milestone }),
+  };
+}
+
+function limitOf(limit: number | undefined, fallback: number): number {
+  return Math.min(Math.max(limit ?? fallback, 1), 100);
+}
+
+/** 响应体不是 2xx 时抛错（状态、URL 与 GitHub 的 message 都在里面）。 */
+async function ensureOk(response: Response): Promise<Response> {
+  if (response.ok) {
+    return response;
+  }
+  let detail: string | undefined;
+  try {
+    const body = await response.text();
+    detail = (JSON.parse(body) as { message?: string }).message ?? body.slice(0, 200);
+  } catch {
+    detail = undefined;
+  }
+  throw new Error(
+    `GitHub API error (HTTP ${response.status}) at ${response.url}${detail === undefined || detail === "" ? "" : `: ${detail}`}`,
+  );
+}
+
+function octokitRequest(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal };
+}
+
+/** 把 octokit 的类型化 data 当外部 JSON 交出去：调用方用 schema 校验自己读的字段。 */
+function asJson(value: unknown): unknown {
+  return value;
+}
+
+export function createGithubReads(options: GithubClientOptions = {}): GithubReads {
+  const api = createGithubApi(options);
+
+  return {
+    async issue(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.issues.get({ owner, repo, issue_number: number, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async pull(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.pulls.get({ owner, repo, pull_number: number, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async issueComments(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.issues.listComments, {
+          owner,
+          repo,
+          issue_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async pullReviewComments(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.listReviewComments, {
+          owner,
+          repo,
+          pull_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async pullReviews(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.listReviews, {
+          owner,
+          repo,
+          pull_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async listIssues(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 30);
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.issues.listForRepo, {
+          owner,
+          repo,
+          per_page: limit,
+          ...listParams(query),
+          ...octokitRequest(signal),
+        }),
+      );
+      // 列表端点混着 PR（REST 的 issues 列表包含 PR），与 gh issue list 一致地过滤掉
+      const issues = data.filter((item) => !("pull_request" in item));
+      return issues.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async listPulls(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 30);
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.list, {
+          owner,
+          repo,
+          per_page: limit,
+          ...listParams(query),
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async pullDiff(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.pulls.get({
+          owner,
+          repo,
+          pull_number: number,
+          mediaType: { format: "diff" },
+          ...octokitRequest(signal),
+        }),
+      );
+      // diff 媒体类型下 data 是原始 diff 文本；octokit 的类型仍按 JSON 声明，所以这里
+      // 显式断言而不是把对象 stringify（[object Object] 会静默毁掉 diff）
+      return data as unknown as string;
+    },
+
+    async listReleases(owner, repo, limit, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.repos.listReleases, {
+          owner,
+          repo,
+          per_page: limitOf(limit, 10),
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async release(owner, repo, tag, signal) {
+      const { data } = await api.call((octokit) =>
+        tag === undefined
+          ? octokit.rest.repos.getLatestRelease({ owner, repo, ...octokitRequest(signal) })
+          : octokit.rest.repos.getReleaseByTag({ owner, repo, tag, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async listRuns(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 20);
+      let workflowId: number | undefined;
+      if (query.workflow !== undefined) {
+        const workflows = await api.call((octokit) =>
+          octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
+            owner,
+            repo,
+            per_page: 100,
+            ...octokitRequest(signal),
+          }),
+        );
+        const wanted = query.workflow.toLowerCase();
+        const match = workflows.find(
+          (workflow) =>
+            workflow.name.toLowerCase() === wanted ||
+            workflow.path.toLowerCase() === wanted ||
+            workflow.path.toLowerCase().endsWith(`/${wanted}`),
+        );
+        if (match === undefined) {
+          const names = workflows.map((workflow) => workflow.name).join(", ");
+          throw new Error(`workflow "${query.workflow}" not found (available: ${names})`);
+        }
+        workflowId = match.id;
+      }
+      const data = await api.call(async (octokit) => {
+        const params = {
+          owner,
+          repo,
+          per_page: limit,
+          // REST 的 status 同时接受运行状态与结论（success / failure / in_progress …）；
+          // octokit 把取值声明成字面量联合，这里按它的类型断言（非法取值由 API 报 422）
+          ...(query.status !== undefined && { status: query.status as WorkflowRunStatus }),
+          ...octokitRequest(signal),
+        };
+        return workflowId === undefined
+          ? octokit.paginate(octokit.rest.actions.listWorkflowRunsForRepo, params)
+          : octokit.paginate(octokit.rest.actions.listWorkflowRuns, {
+              ...params,
+              workflow_id: workflowId,
+            });
+      });
+      return data.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async run(owner, repo, runId, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.getWorkflowRun({
+          owner,
+          repo,
+          run_id: runId,
+          ...octokitRequest(signal),
+        }),
+      );
+      return asJson(data);
+    },
+
+    async repository(owner, repo, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.repos.get({ owner, repo, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async jobLogs(owner, repo, jobId, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.downloadJobLogsForWorkflowRun({
+          owner,
+          repo,
+          job_id: jobId,
+          ...octokitRequest(signal),
+        }),
+      );
+      // 日志端点的响应体是文本；octokit 的类型是 `unknown`（按响应内容而定），这里断言
+      return data as string;
+    },
+
+    async downloadAssetTo(owner, repo, assetId, destPath, signal) {
+      const response = await api.rawFetch(
+        `https://api.github.com/repos/${owner}/${repo}/releases/assets/${assetId}`,
+        { headers: { accept: "application/octet-stream" }, ...(signal && { signal }) },
+      );
+      await ensureOk(response);
+      await streamToFile(response, destPath);
+    },
+
+    async downloadArchiveTo(owner, repo, format, ref, destPath, signal) {
+      const kind = format === "zip" ? "zipball" : "tarball";
+      const suffix = ref === undefined ? "" : `/${ref}`;
+      const response = await api.rawFetch(
+        `https://api.github.com/repos/${owner}/${repo}/${kind}${suffix}`,
+        { ...(signal && { signal }) },
+      );
+      await ensureOk(response);
+      await streamToFile(response, destPath);
+    },
+  };
+}
+
+/** 把响应体流式写入文件；响应没有 body（空资产）时写空文件。 */
+async function streamToFile(response: Response, destPath: string): Promise<void> {
+  const body = response.body;
+  if (body === null) {
+    await pipeline(Readable.from([]), createWriteStream(destPath));
+    return;
+  }
+  await pipeline(Readable.fromWeb(body), createWriteStream(destPath));
+}

package/src/lib/github.ts

@@ -223,70 +223,47 @@ function normalize(raw: SearchItem): SearchHit {
 }
 
 /**
- * `gh issue list --json …` / `gh pr list --json …` 的响应形状。gh 走 GraphQL，字段是
- * camelCase，`state` 是大写的 `OPEN` / `CLOSED` / `MERGED`，`comments` 是整个评论数组
- * （不是计数）——所以浏览分支要在归一化这一步把它压成计数，才能和搜索分支（REST，
- * 下划线命名、state 小写、comments 是数字）共用同一套 SearchHit、渲染与载荷。
+ * REST 列表端点（`issues.listForRepo` / `pulls.list`）的条目形状。与搜索 API 的条目差别：
+ * repo 不在条目里（由调用方给），PR 的合并信息在 `merged_at`/`merged`。
  */
-const ghListRecordSchema = Type.Object({
+const restListItemSchema = Type.Object({
   number: Type.Number(),
-  title: Type.String(),
   state: Type.String(),
-  url: Type.String(),
-  labels: Type.Array(Type.Object({ name: Type.String() }, { additionalProperties: true })),
-  milestone: Type.Union([
-    Type.Object({ title: Type.String() }, { additionalProperties: true }),
-    Type.Null(),
-  ]),
-  assignees: Type.Array(Type.Object({ login: Type.String() }, { additionalProperties: true })),
-  author: Type.Union([
-    Type.Object({ login: Type.String() }, { additionalProperties: true }),
-    Type.Null(),
-  ]),
-  comments: Type.Array(Type.Unknown()),
-  createdAt: Type.String(),
-  updatedAt: Type.String(),
-  closedAt: Type.Union([Type.String(), Type.Null()]),
-  mergedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  title: Type.String(),
+  html_url: Type.String(),
+  user: Type.Union([Type.Object({ login: Type.String() }), Type.Null()]),
+  labels: Type.Array(Type.Object({ name: Type.Optional(Type.String()) })),
+  milestone: Type.Union([Type.Object({ title: Type.Optional(Type.String()) }), Type.Null()]),
+  assignees: Type.Union([Type.Array(Type.Object({ login: Type.String() })), Type.Null()]),
+  comments: Type.Optional(Type.Number()),
+  created_at: Type.String(),
+  updated_at: Type.String(),
+  closed_at: Type.Union([Type.String(), Type.Null()]),
+  merged_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
 });
 
-/** 浏览分支要 gh 给的字段，与 `SearchHit` 的列一一对应（`comments` 只用来数个数）。 */
-export const GH_LIST_FIELDS = [
-  "number",
-  "title",
-  "state",
-  "url",
-  "labels",
-  "milestone",
-  "assignees",
-  "author",
-  "comments",
-  "createdAt",
-  "updatedAt",
-  "closedAt",
-  "mergedAt",
-].join(",");
-
-/** 把 `gh issue list --json` / `gh pr list --json` 的输出归一到 `SearchHit`（repo 由调用方给）。 */
-export function normalizeGhList(stdout: string, repo: string): SearchHit[] {
-  const items = parseWithSchema(Type.Array(ghListRecordSchema), JSON.parse(stdout));
-  return items.map((item) => {
-    const mergedAt = item.mergedAt ?? null;
+/**
+ * 把 REST 列表条目归一到 `SearchHit`，与搜索分支共用一套渲染与载荷。`repo` 由调用方给
+ * （REST 列表端点的条目里没有仓库信息）。
+ */
+export function normalizeRestList(items: unknown, repo: string): SearchHit[] {
+  return parseWithSchema(Type.Array(restListItemSchema), items).map((item) => {
+    const mergedAt = item.merged_at ?? null;
     return {
       number: item.number,
-      // gh 给 MERGED 状态的 PR 与 OPEN/CLOSED 一样是 state 字段，merged 语义与搜索分支对齐
-      state: mergedAt ? "merged" : (item.state.toLowerCase() as SearchHit["state"]),
+      // 已合并的 PR 在 REST 里也是 `closed`，merged 语义与搜索分支一致地由 merged_at 推断
+      state: mergedAt === null ? (item.state === "open" ? "open" : "closed") : "merged",
       title: item.title,
-      url: item.url,
+      url: item.html_url,
       repo,
-      author: item.author?.login ?? "",
-      labels: item.labels.map((label) => label.name),
+      author: item.user?.login ?? "",
+      labels: item.labels.map((label) => label.name ?? ""),
       milestone: item.milestone?.title ?? "",
-      assignees: item.assignees.map((assignee) => assignee.login),
-      comments: item.comments.length,
-      createdAt: toDate(item.createdAt),
-      updatedAt: toDate(item.updatedAt),
-      closedAt: toDate(item.closedAt),
+      assignees: (item.assignees ?? []).map((assignee) => assignee.login),
+      comments: item.comments ?? 0,
+      createdAt: toDate(item.created_at),
+      updatedAt: toDate(item.updated_at),
+      closedAt: toDate(item.closed_at),
       mergedAt: toDate(mergedAt),
     };
   });
@@ -321,9 +298,14 @@ function describeHttpError(status: number | undefined): string {
   return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
 }
 
-interface GithubApi {
+export interface GithubApi {
   /** Run an octokit request; retries once with a fresh token on 401. */
   call<T>(fn: (octokit: Octokit) => Promise<T>): Promise<T>;
+  /**
+   * 用同一个 token 直接 fetch（二进制资产、源码归档这类要走原始响应体、不能经 octokit
+   * 的 JSON 解析的请求）。重定向自动跟随，401 同样丢缓存重试一次。
+   */
+  rawFetch(url: string, init?: RequestInit): Promise<Response>;
 }
 
 export interface GithubClientOptions {
@@ -343,17 +325,41 @@ export interface GithubClientOptions {
  * module-level state. A stale cached token can produce 401s; the cache is
  * dropped and the request retried once in that case.
  */
-function createGithubApi(options: GithubClientOptions = {}): GithubApi {
+export function createGithubApi(options: GithubClientOptions = {}): GithubApi {
   let client: Octokit | undefined;
+  // token 单独缓存：rawFetch（二进制/归档下载）不走 octokit，但同样不该每次 spawn
+  // `gh auth token`。401 时两个缓存一起丢。
+  let token: string | undefined;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const tokenProvider = options.token ?? ghAuthToken;
+
+  async function getToken(): Promise<string> {
+    token ??= await tokenProvider();
+    return token;
+  }
 
   async function getClient(): Promise<Octokit> {
     client ??= new Octokit({
-      auth: await (options.token ?? ghAuthToken)(),
+      auth: await getToken(),
       ...(options.fetch && { request: { fetch: options.fetch } }),
     });
     return client;
   }
 
+  async function rawFetchOnce(url: string, init: RequestInit = {}): Promise<Response> {
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${await getToken()}`);
+    headers.set("accept", "application/vnd.github+json");
+    headers.set("x-github-api-version", "2022-11-28");
+    const response = await fetchImpl(url, { ...init, headers });
+    if (response.status === 401) {
+      // 缓存的 token 可能已过期：丢缓存后由调用方重试一次
+      token = undefined;
+      client = undefined;
+    }
+    return response;
+  }
+
   return {
     async call(fn) {
       for (let attempt = 0; ; attempt += 1) {
@@ -362,6 +368,7 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
         } catch (error) {
           const status = (error as { status?: number }).status;
           if (status === 401 && attempt === 0 && client) {
+            token = undefined;
             client = undefined;
             continue;
           }
@@ -369,6 +376,16 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
         }
       }
     },
+
+    async rawFetch(url, init) {
+      for (let attempt = 0; ; attempt += 1) {
+        const response = await rawFetchOnce(url, init);
+        if (response.status !== 401 || attempt > 0) {
+          return response;
+        }
+        await response.body?.cancel();
+      }
+    },
   };
 }