@trim21/personal-pi-extensions 0.1.634 → 0.1.636

package/package.json

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

package/src/gh/base.ts

@@ -1,17 +1,19 @@
 /**
- * Shared infrastructure of the GitHub read-only tools: the `gh` subprocess
- * layer, result shaping, the octokit-backed client, and the checks-wait
- * pipeline. Each tool lives in `tools/<tool-name>.ts`; anything used by more
- * than one tool belongs here.
+ * Shared infrastructure of the GitHub read-only tools: result shaping, the
+ * octokit-backed client, and the checks-wait pipeline (running a `gh` process
+ * itself lives in `lib/gh-process.ts`, which also owns the proxy env shared by
+ * the subprocess and octokit). Each tool lives in `tools/<tool-name>.ts`;
+ * anything used by more than one tool belongs here.
  */
 
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { egress } from "../lib/egress.js";
+import { type GhResult, runGh } from "../lib/gh-process.js";
 import {
   type ActionJob,
   type CheckRun,
@@ -19,17 +21,11 @@ import {
   createGithubChecks,
   createGithubSearch,
   type GithubChecksClient,
+  type GithubClientOptions,
   type GithubSearch,
   renderHits,
 } from "../lib/github.js";
 import { type ToolPendant } from "../lib/pendant.js";
-import { createHttpProxy } from "../lib/proxy.js";
-
-/**
- * 代理配置（~/.pi/agent/proxy.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
- * `gh` 子进程与 octokit 请求都从这里取，配置只在首次使用时读一次。
- */
-export const httpProxy = createHttpProxy();
 
 /** A tool result: what the model sees plus the structured details payload. */
 export interface ToolResult {
@@ -46,18 +42,6 @@ export interface ToolCall<Params> {
   onUpdate?: (update: ToolResult) => void;
 }
 
-export interface GhResult {
-  stdout: string;
-  stderr: string;
-  code: number;
-  killed: boolean;
-  combined: string;
-  /** Why the process was killed, when `killed` is true. */
-  reason?: "timeout" | "abort";
-  /** When the process could not be started at all (e.g. `gh` not found in PATH). */
-  spawnError?: string;
-}
-
 /**
  * Check whether the `gh` CLI is on the system, scanning PATH like
  * `findDefaultBwrap`. The extension registers no tools when `gh` is missing, so
@@ -78,120 +62,6 @@ export function isGhAvailable(): boolean {
   return false;
 }
 
-export function runGh(
-  args: string[],
-  ctx: {
-    cwd?: string;
-    signal?: AbortSignal;
-    timeout?: number;
-    /** 追加到子进程环境变量（覆盖进程环境与代理配置），供测试或调用方定制。 */
-    env?: NodeJS.ProcessEnv;
-  },
-): Promise<GhResult> {
-  return new Promise((resolve) => {
-    const proc = spawn("gh", args, {
-      cwd: ctx.cwd,
-      shell: false,
-      stdio: ["ignore", "pipe", "pipe"],
-      // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
-      env: { ...process.env, ...httpProxy.env, ...ctx.env, GH_PAGER: "cat" },
-    });
-
-    let stdout = "";
-    let stderr = "";
-    const combined: string[] = [];
-    let killed = false;
-    let killReason: "timeout" | "abort" | undefined;
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-    let onAbort: (() => void) | undefined;
-
-    const killProcess = (reason: "timeout" | "abort") => {
-      if (killed) {
-        return;
-      }
-
-      killed = true;
-      killReason = reason;
-      proc.kill("SIGTERM");
-      setTimeout(() => {
-        if (!proc.killed) {
-          proc.kill("SIGKILL");
-        }
-      }, 5000);
-    };
-
-    if (ctx.signal) {
-      onAbort = () => killProcess("abort");
-      if (ctx.signal.aborted) {
-        killProcess("abort");
-      } else {
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
-      }
-    }
-
-    // Default timeout: 10 minutes. Long operations like downloading a CI job's
-    // full log routinely take well over 30s, so a short default would kill them
-    // mid-transfer; combined with `code ?? 0` that would silently cache a
-    // truncated log as success. A killed process must never look successful.
-    const timeout = ctx.timeout ?? 600_000;
-    if (timeout > 0) {
-      timeoutId = setTimeout(() => killProcess("timeout"), timeout);
-    }
-
-    proc.stdout.on("data", (data: Buffer) => {
-      const text = data.toString();
-      stdout += text;
-      combined.push(text);
-    });
-    proc.stderr.on("data", (data: Buffer) => {
-      const text = data.toString();
-      stderr += text;
-      combined.push(text);
-    });
-
-    proc.on("close", (code) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-      if (onAbort && ctx.signal) {
-        ctx.signal.removeEventListener("abort", onAbort);
-      }
-      resolve({
-        stdout,
-        stderr,
-        // When killed by a signal the close event's code is null — including
-        // kills we did not initiate. Report failure instead of pretending it
-        // succeeded. -1 is a sentinel for "did not exit normally" — distinct
-        // from a real gh failure exit code (1), which is always in 0-255.
-        code: code ?? -1,
-        killed,
-        combined: combined.join(""),
-        reason: killReason,
-      });
-    });
-
-    proc.on("error", (err: Error) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-      if (onAbort && ctx.signal) {
-        ctx.signal.removeEventListener("abort", onAbort);
-      }
-      // spawn 失败（如 gh 不在 PATH → ENOENT、cwd 不存在）时进程从未启动，
-      // 没有任何 stdout/stderr；把底层错误带上，否则会退化成无信息的 "exit code 1"。
-      resolve({
-        stdout,
-        stderr,
-        code: 1,
-        killed,
-        combined: combined.join(""),
-        reason: killReason,
-        spawnError: err.message,
-      });
-    });
-  });
-}
-
 /**
  * Error thrown by `ghExec` when the `gh` invocation exits non-zero.
  * The message carries the toolcall input (JSON) wrapped in `<input>` markers,
@@ -474,10 +344,13 @@ export class GhClient {
   readonly search: GithubSearch;
   readonly checks: GithubChecksClient;
 
-  constructor(fetchImpl: typeof globalThis.fetch = httpProxy.fetch) {
+  constructor(
+    fetchImpl: typeof globalThis.fetch = egress.fetch,
+    options: Pick<GithubClientOptions, "token"> = {},
+  ) {
     this.fetch = fetchImpl;
-    this.search = createGithubSearch({ fetch: fetchImpl });
-    this.checks = createGithubChecks({ fetch: fetchImpl });
+    this.search = createGithubSearch({ fetch: fetchImpl, ...options });
+    this.checks = createGithubChecks({ fetch: fetchImpl, ...options });
   }
 }
 

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

@@ -1,7 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { type GhClient, repoArgs, runGh, subtitlePendant } from "../base.js";
+import { runGh } from "../../lib/gh-process.js";
+import { type GhClient, repoArgs, subtitlePendant } from "../base.js";
 
 export function addWatchRunTool(_gh: GhClient, pi: ExtensionAPI) {
   pi.registerTool({

package/src/lib/egress.ts

@@ -0,0 +1,29 @@
+/**
+ * 出网入口：代理配置的解析、dispatcher 与 NO_PROXY 分流仍在 `src/lib/proxy.ts`（代理
+ * 适配器），本模块只把它收敛成一处，让所有出网调用方从同一处取 `fetch` 与子进程代理
+ * 环境变量，并保持「配置写错即加载失败」的行为——不静默直连。
+ */
+
+import { createHttpProxy, type HttpProxySettings } from "./proxy.js";
+
+/**
+ * 出网的单一入口：需要的调用方从这里取请求用的 fetch 与子进程代理环境变量，
+ * 不必各自判断「该用代理 fetch 还是全局 fetch」。
+ */
+export interface Egress {
+  /** 生效的代理设置，供诊断与展示。 */
+  readonly settings: HttpProxySettings;
+  /** 请求用的 fetch：undici 的 fetch，配置了代理时自动走代理（NO_PROXY 由 dispatcher 处理）。 */
+  readonly fetch: typeof globalThis.fetch;
+  /** 要注入子进程的代理环境变量；未配置代理时为空对象。 */
+  readonly env: NodeJS.ProcessEnv;
+}
+
+/** 组装出网层（读一次代理配置；配置写错直接抛）。 */
+export function createEgress(): Egress {
+  const proxy = createHttpProxy();
+  return { settings: proxy.settings, fetch: proxy.fetch, env: proxy.env };
+}
+
+/** 共享出网实例：进程内所有出网调用方共用（代理配置在扩展加载时读一次）。 */
+export const egress: Egress = createEgress();

package/src/lib/gh-process.ts

@@ -0,0 +1,151 @@
+/**
+ * `gh` subprocess adapter: start a `gh` process, collect its output, apply the
+ * shared timeout / kill semantics, and hand it the proxy env from the shared
+ * egress layer. It lives in `lib/` so both the gh tool layer (`src/gh/`) and
+ * the octokit clients (`lib/github.ts`) can depend on it without a cycle.
+ */
+
+import { spawn } from "node:child_process";
+
+import { egress } from "./egress.js";
+
+export interface GhResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed: boolean;
+  combined: string;
+  /** Why the process was killed, when `killed` is true. */
+  reason?: "timeout" | "abort";
+  /** When the process could not be started at all (e.g. `gh` not found in PATH). */
+  spawnError?: string;
+}
+
+export interface GhRunContext {
+  cwd?: string;
+  signal?: AbortSignal;
+  timeout?: number;
+  /** 追加到子进程环境变量（覆盖进程环境与代理配置），供测试或调用方定制。 */
+  env?: NodeJS.ProcessEnv;
+}
+
+export function runGh(args: string[], ctx: GhRunContext): Promise<GhResult> {
+  return new Promise((resolve) => {
+    const proc = spawn("gh", args, {
+      cwd: ctx.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
+      env: { ...process.env, ...egress.env, ...ctx.env, GH_PAGER: "cat" },
+    });
+
+    let stdout = "";
+    let stderr = "";
+    const combined: string[] = [];
+    let killed = false;
+    let killReason: "timeout" | "abort" | undefined;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+
+    const killProcess = (reason: "timeout" | "abort") => {
+      if (killed) {
+        return;
+      }
+
+      killed = true;
+      killReason = reason;
+      proc.kill("SIGTERM");
+      setTimeout(() => {
+        if (!proc.killed) {
+          proc.kill("SIGKILL");
+        }
+      }, 5000);
+    };
+
+    if (ctx.signal) {
+      onAbort = () => killProcess("abort");
+      if (ctx.signal.aborted) {
+        killProcess("abort");
+      } else {
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+
+    // Default timeout: 10 minutes. Long operations like downloading a CI job's
+    // full log routinely take well over 30s, so a short default would kill them
+    // mid-transfer; combined with `code ?? 0` that would silently cache a
+    // truncated log as success. A killed process must never look successful.
+    const timeout = ctx.timeout ?? 600_000;
+    if (timeout > 0) {
+      timeoutId = setTimeout(() => killProcess("timeout"), timeout);
+    }
+
+    proc.stdout.on("data", (data: Buffer) => {
+      const text = data.toString();
+      stdout += text;
+      combined.push(text);
+    });
+    proc.stderr.on("data", (data: Buffer) => {
+      const text = data.toString();
+      stderr += text;
+      combined.push(text);
+    });
+
+    proc.on("close", (code) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (onAbort && ctx.signal) {
+        ctx.signal.removeEventListener("abort", onAbort);
+      }
+      resolve({
+        stdout,
+        stderr,
+        // When killed by a signal the close event's code is null — including
+        // kills we did not initiate. Report failure instead of pretending it
+        // succeeded. -1 is a sentinel for "did not exit normally" — distinct
+        // from a real gh failure exit code (1), which is always in 0-255.
+        code: code ?? -1,
+        killed,
+        combined: combined.join(""),
+        reason: killReason,
+      });
+    });
+
+    proc.on("error", (err: Error) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (onAbort && ctx.signal) {
+        ctx.signal.removeEventListener("abort", onAbort);
+      }
+      // spawn 失败（如 gh 不在 PATH → ENOENT、cwd 不存在）时进程从未启动，
+      // 没有任何 stdout/stderr；把底层错误带上，否则会退化成无信息的 "exit code 1"。
+      resolve({
+        stdout,
+        stderr,
+        code: 1,
+        killed,
+        combined: combined.join(""),
+        reason: killReason,
+        spawnError: err.message,
+      });
+    });
+  });
+}
+
+/** Read the logged-in token from the system `gh` CLI (`gh auth token`). */
+export async function ghAuthToken(): Promise<string> {
+  const result = await runGh(["auth", "token"], { timeout: 10_000 });
+  if (result.spawnError) {
+    throw new Error(`failed to start gh: ${result.spawnError}`);
+  }
+  const token = result.stdout.trim();
+  if (token && result.code === 0) {
+    return token;
+  }
+  throw new Error(
+    result.stderr.trim() ||
+      `gh auth token exited with code ${result.code} — run "gh auth login" first`,
+  );
+}

package/src/lib/github.ts

@@ -8,11 +8,10 @@
  * rendered state is derived from `pull_request.merged_at`.
  */
 
-import { spawn } from "node:child_process";
-
 import { Octokit } from "octokit";
 import { type Static, Type } from "typebox";
 
+import { ghAuthToken } from "./gh-process.js";
 import { parseWithSchema } from "./parse-with-schema.js";
 
 export type SearchKind = "issue" | "pr";
@@ -218,38 +217,6 @@ function normalize(raw: SearchItem): SearchHit {
   };
 }
 
-function ghAuthToken(): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const proc = spawn("gh", ["auth", "token"], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => proc.kill("SIGTERM"), 10_000);
-    proc.stdout.on("data", (d: Buffer) => {
-      stdout += String(d);
-    });
-    proc.stderr.on("data", (d: Buffer) => {
-      stderr += String(d);
-    });
-    proc.on("error", (err) => {
-      clearTimeout(timer);
-      reject(new Error(`failed to start gh: ${err.message}`));
-    });
-    proc.on("close", (code) => {
-      clearTimeout(timer);
-      const token = stdout.trim();
-      if (code === 0 && token) {
-        resolve(token);
-      } else {
-        reject(
-          new Error(
-            stderr.trim() || `gh auth token exited with code ${code} — run "gh auth login" first`,
-          ),
-        );
-      }
-    });
-  });
-}
-
 /**
  * Error thrown when the GitHub search API rejects the request. Carries the
  * original toolcall params so the model can see the exact input.
@@ -291,6 +258,8 @@ export interface GithubClientOptions {
    * proxy dispatcher attached. Defaults to the global fetch.
    */
   fetch?: typeof globalThis.fetch;
+  /** gh token provider；缺省读系统 `gh auth token`（见 lib/gh-process.ts）。 */
+  token?: () => Promise<string>;
 }
 
 /**
@@ -304,7 +273,7 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
 
   async function getClient(): Promise<Octokit> {
     client ??= new Octokit({
-      auth: await ghAuthToken(),
+      auth: await (options.token ?? ghAuthToken)(),
       ...(options.fetch && { request: { fetch: options.fetch } }),
     });
     return client;

package/src/web/fetch.ts

@@ -4,9 +4,9 @@
  * SSRF 防护：DNS 预解析 + 拒绝私有/保留地址 + 每跳重定向重新校验，
  * 防止把 agent 变成内网探测口。正文提取用 readability 主内容算法。
  *
- * 出网走 `src/lib/proxy.ts` 的代理层（~/.pi/agent/proxy.json，回退 HTTPS_PROXY 等环境
- * 变量）：Node 的全局 fetch 不认代理环境变量，GitHub 的用户附件、release 资产这类只在
- * 代理可达的 host 上，必须从这里挂出去，否则沙箱内一律 fetch failed。
+ * 出网走共享出网层 `src/lib/egress.ts`（代理配置 ~/.pi/agent/proxy.json，回退 HTTPS_PROXY
+ * 等环境变量）：Node 的全局 fetch 不认代理环境变量，GitHub 的用户附件、release 资产这类
+ * 只在代理可达的 host 上，必须从这里挂出去，否则沙箱内一律 fetch failed。
  *
  * 本文件是独立扩展入口（见 package.json 的 pi.extensions），可在配置里单独禁用。
  */
@@ -21,13 +21,11 @@ import { parseHTML } from "linkedom";
 import TurndownService from "turndown";
 import { Type } from "typebox";
 
+import { egress } from "../lib/egress.js";
 import { resolvePathArg } from "../lib/path.js";
-import { createHttpProxy } from "../lib/proxy.js";
 import { createRequestPolicy } from "../lib/request-policy.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 
-const httpProxy = createHttpProxy();
-
 const MAX_REDIRECTS = 5;
 const TIMEOUT_MS = 30_000;
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -143,7 +141,7 @@ interface SavedFile {
 async function fetchWithRedirects(
   url: URL,
   signal: AbortSignal | undefined,
-  fetchFn: typeof fetch = httpProxy.fetch,
+  fetchFn: typeof fetch = egress.fetch,
 ): Promise<{ response: Response; url: URL }> {
   let current = url;
   for (let redirects = 0; ; redirects++) {

package/src/web/search.ts

@@ -11,6 +11,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { egress } from "../lib/egress.js";
 import { loadSearch1ApiKey } from "./config.js";
 
 const SEARCH_URL = "https://api.search1api.com/search";
@@ -150,7 +151,7 @@ export async function searchWeb(
   apiKey: string,
   options: SearchOptions = {},
 ): Promise<SearchResult> {
-  const response = await fetch(SEARCH_URL, {
+  const response = await egress.fetch(SEARCH_URL, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${apiKey}`,