@trim21/personal-pi-extensions 0.1.495 → 0.1.496

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.495",
+  "version": "0.1.496",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -105,6 +105,7 @@
     "linkedom": "^0.18.0",
     "lodash-es": "^4.18.1",
     "minimatch": "^10.2.6",
+    "octokit": "^5.0.5",
     "turndown": "^7.2.0",
     "vscode-jsonrpc": "^9.0.1",
     "vscode-languageserver-types": "^3.18.0",

package/src/gh-readonly.ts

@@ -38,6 +38,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { createGithubSearch, type GithubSearch, renderHits } from "./lib/github.js";
 import { type ToolPendant } from "./lib/pendant.js";
 import { createSeqState } from "./lib/seq-state.js";
 
@@ -333,52 +334,30 @@ interface ListFilters {
   assignee?: string;
   milestone?: string;
   limit?: number;
+  /** Comma-separated field names for the keyword-search result rows. */
+  fields?: string;
 }
 
 /**
- * Build the `gh` argv for listing or keyword-searching issues/PRs.
+ * Build the `gh` argv for browsing issues/PRs (no keyword search).
  *
- * Keyword searches route through `gh search issues` / `gh search prs`, which rank
- * results by relevance and are the only path that can include closed items.
- * `gh issue list --search` would silently stay on the list's state filter (open
- * by default), so keyword lookups must not use it. Browse calls (no keywords)
- * keep `gh issue list` / `gh pr list` semantics.
- *
- * The state value sets differ between the two command families: `gh issue list`
- * accepts `--state all` and `gh pr list` `--state merged`, while `gh search`
- * only knows `--state open|closed` plus `--merged` for PRs. The shared `state`
- * param is translated here: search defaults to open, `all` means open+closed
- * (no state filter), and `merged` maps to `--merged` for PRs.
+ * 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, keywords, state, label, author, assignee, milestone, limit } = params;
-
-  const addFilters = (args: string[]) => {
-    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;
-  };
-
-  if (keywords) {
-    const args = ["search", kind === "issue" ? "issues" : "prs", ...repoArgs(repo), keywords];
-    if (kind === "pr" && state === "merged") {
-      args.push("--merged");
-    } else if (state && state !== "all") {
-      args.push("--state", state);
-    } else if (!state) {
-      // keep the browse tools' default rather than gh search's implicit
-      // open+closed; pass state="all" to cover closed items
-      args.push("--state", "open");
-    }
-    return addFilters(args);
-  }
+  const { repo, state, label, author, assignee, milestone, limit } = params;
 
   const args = [kind, "list", ...repoArgs(repo)];
   if (state) args.push("--state", state);
-  return addFilters(args);
+  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;
 }
 
 async function listGithub(
@@ -389,6 +368,19 @@ async function listGithub(
   return ghExec(listGithubArgs(kind, params), ctx);
 }
 
+/** Run a keyword search through the octokit client and render the rows. */
+async function searchList(
+  kind: "issue" | "pr",
+  params: ListFilters,
+  githubSearch: GithubSearch,
+): Promise<string> {
+  const hits = await githubSearch.search(kind, params);
+  if (hits.length === 0) {
+    return `(no matching ${kind === "issue" ? "issues" : "pull requests"})`;
+  }
+  return renderHits(hits, { repo: params.repo, fields: params.fields });
+}
+
 // ── CI helpers ───────────────────────────────────────────────────────────────
 
 export interface StepInfo {
@@ -1144,6 +1136,8 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     return;
   }
 
+  const githubSearch = createGithubSearch();
+
   // ── read-github-issue ──────────────────────────────────────────────────────
   pi.registerTool({
     name: "read-github-issue",
@@ -1180,25 +1174,36 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "list-github-issues",
     label: "GitHub Issues List",
     description:
-      'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword results default to open issues — pass state="all" to include closed ones.',
+      'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones. Set fields to choose the columns of each result row.',
     promptSnippet: "List or search GitHub issues",
     parameters: Type.Object({
       repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
       keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
       state: Type.Optional(
         Type.String({
-          description: "open, closed, all (default: open; with keywords, all covers closed too)",
+          description:
+            "open, closed, all (default: open; all applies to keyword search and covers closed too)",
         }),
       ),
       label: Type.Optional(Type.String({ description: "Filter by label" })),
       author: Type.Optional(Type.String({ description: "Filter by author" })),
-      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
       milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 30)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt",
+        }),
+      ),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const result = toToolResult(
-        await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
+        params.keywords
+          ? await searchList("issue", params, githubSearch)
+          : await listGithub("issue", params, { cwd: ctx.cwd, signal, input: params }),
         params,
       );
       result.details.pendant = subtitlePendant(params);
@@ -1242,7 +1247,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "list-github-prs",
     label: "GitHub PRs List",
     description:
-      'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword results default to open PRs — pass state="all" (open + closed) or state="merged" to broaden.',
+      'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden. Set fields to choose the columns of each result row.',
     promptSnippet: "List or search GitHub PRs",
     parameters: Type.Object({
       repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
@@ -1250,18 +1255,28 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       state: Type.Optional(
         Type.String({
           description:
-            "open, closed, merged, all (default: open; with keywords, merged and all broaden the search)",
+            "open, closed, merged, all (default: open; all applies to keyword search and covers open + closed + merged)",
         }),
       ),
       label: Type.Optional(Type.String({ description: "Filter by label" })),
       author: Type.Optional(Type.String({ description: "Filter by author" })),
-      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      assignee: Type.Optional(
+        Type.String({ description: "Filter by assignee (@me for yourself)" }),
+      ),
       milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 30)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            "Comma-separated columns for keyword-search rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt,mergedAt",
+        }),
+      ),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const result = toToolResult(
-        await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
+        params.keywords
+          ? await searchList("pr", params, githubSearch)
+          : await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
         params,
       );
       result.details.pendant = subtitlePendant(params);

package/src/lib/github.ts

@@ -0,0 +1,294 @@
+/**
+ * GitHub search client built on octokit, authenticated with the token from the
+ * system `gh` CLI (`gh auth token`). Used by the gh-readonly search tools.
+ *
+ * Unlike the `gh search` CLI, the search API has no `--state all` and treats a
+ * merged PR's state as `closed` — so merged/closed disambiguation is expressed
+ * through qualifiers here (`is:merged`, `state:closed -is:merged`) and the
+ * rendered state is derived from `pull_request.merged_at`.
+ */
+
+import { spawn } from "node:child_process";
+
+import { Octokit } from "octokit";
+
+export type SearchKind = "issue" | "pr";
+
+export interface SearchParams {
+  repo?: string;
+  keywords?: string;
+  state?: string;
+  label?: string;
+  author?: string;
+  assignee?: string;
+  milestone?: string;
+  limit?: number;
+}
+
+/** REST /search/issues response shape we consume (item is an issue/pr union). */
+interface RawSearchItem {
+  number: number;
+  state: string;
+  title: string;
+  html_url: string;
+  /** The search API exposes the repo as a URL, not as an object. */
+  repository_url: string;
+  user: { login: string } | null;
+  labels: { name: string }[];
+  milestone: { title: string } | null;
+  assignees: { login: string }[];
+  comments: number;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  pull_request: { merged_at: string | null } | null;
+}
+
+export interface SearchHit {
+  number: number;
+  /** `open`, `closed` or `merged` (merged is inferred from pull_request.merged_at). */
+  state: "open" | "closed" | "merged";
+  title: string;
+  url: string;
+  repo: string;
+  author: string;
+  labels: string[];
+  milestone: string;
+  assignees: string[];
+  comments: number;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string;
+  mergedAt: string;
+}
+
+/**
+ * Build the `q` parameter for the issues-and-pull-requests search endpoint.
+ *
+ * State semantics (the whole reason this client exists):
+ * - default is `open`, matching the browse tools
+ * - `all` applies no state filter (open + closed)
+ * - for PRs, `merged` maps to `is:merged` and `closed` excludes merged PRs,
+ *   because the search API reports a merged PR's state as `closed`
+ */
+export function buildSearchQuery(kind: SearchKind, params: SearchParams): string {
+  const { repo, keywords, label, author, assignee, milestone } = params;
+  const state = params.state ?? "open";
+
+  const parts: string[] = [];
+  if (repo) parts.push(`repo:${repo}`);
+  parts.push(kind === "issue" ? "is:issue" : "is:pr");
+  switch (state) {
+    case "open": {
+      parts.push("state:open");
+
+      break;
+    }
+    case "closed": {
+      parts.push(kind === "pr" ? "state:closed -is:merged" : "state:closed");
+
+      break;
+    }
+    case "merged": {
+      if (kind === "issue") throw new Error("state=merged is only valid for PR searches");
+      parts.push("is:merged");
+
+      break;
+    }
+    default: {
+      if (state !== "all") {
+        throw new Error(
+          `invalid state: ${state} (expected open, closed, ${kind === "pr" ? "merged, " : ""}all)`,
+        );
+      }
+    }
+  }
+  if (keywords) parts.push(keywords);
+  if (label) parts.push(`label:${quoteQualifier(label)}`);
+  if (author) parts.push(`author:${author}`);
+  if (assignee) parts.push(`assignee:${assignee}`);
+  if (milestone) parts.push(`milestone:${quoteQualifier(milestone)}`);
+  return parts.join(" ");
+}
+
+/** Quote a qualifier value that contains whitespace or special characters. */
+function quoteQualifier(value: string): string {
+  if (/^[\w@./-]+$/.test(value)) return value;
+  return `"${value.replaceAll('"', String.raw`\"`)}"`;
+}
+
+const FIELD_EXTRACTORS: Record<string, (hit: SearchHit) => string> = {
+  number: (h) => String(h.number),
+  state: (h) => h.state,
+  title: (h) => h.title,
+  url: (h) => h.url,
+  repo: (h) => h.repo,
+  author: (h) => h.author,
+  labels: (h) => h.labels.join(","),
+  milestone: (h) => h.milestone,
+  assignees: (h) => h.assignees.join(","),
+  comments: (h) => String(h.comments),
+  createdAt: (h) => h.createdAt,
+  updatedAt: (h) => h.updatedAt,
+  closedAt: (h) => h.closedAt,
+  mergedAt: (h) => h.mergedAt,
+};
+
+export const SEARCH_FIELDS: readonly string[] = Object.keys(FIELD_EXTRACTORS);
+
+/** Render search hits as tab-separated rows; one row per hit, one column per field. */
+export function renderHits(hits: SearchHit[], options: { repo?: string; fields?: string }): string {
+  const requested = options.fields
+    ? options.fields
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean)
+    : options.repo
+      ? ["number", "state", "title", "labels", "updatedAt"]
+      : ["repo", "number", "state", "title", "labels", "updatedAt"];
+  const unknown = requested.filter((f) => !(f in FIELD_EXTRACTORS));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown field${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} (valid: ${SEARCH_FIELDS.join(", ")})`,
+    );
+  }
+  return hits.map((hit) => requested.map((f) => FIELD_EXTRACTORS[f](hit)).join("\t")).join("\n");
+}
+
+function toDate(iso: string | null | undefined): string {
+  return iso ? iso.slice(0, 10) : "";
+}
+
+const REPO_URL_RE = /\/repos\/([^/]+\/[^/]+)$/;
+
+/** repository_url looks like https://api.github.com/repos/OWNER/REPO */
+function repoName(raw: RawSearchItem): string {
+  const match = REPO_URL_RE.exec(raw.repository_url);
+  return match?.[1] ?? "";
+}
+
+function normalize(raw: RawSearchItem): SearchHit {
+  const mergedAt = raw.pull_request?.merged_at ?? "";
+  return {
+    number: raw.number,
+    state: mergedAt ? "merged" : (raw.state as "open" | "closed"),
+    title: raw.title,
+    url: raw.html_url,
+    repo: repoName(raw),
+    author: raw.user?.login ?? "",
+    labels: raw.labels.map((l) => l.name),
+    milestone: raw.milestone?.title ?? "",
+    assignees: raw.assignees.map((a) => a.login),
+    comments: raw.comments,
+    createdAt: toDate(raw.created_at),
+    updatedAt: toDate(raw.updated_at),
+    closedAt: toDate(raw.closed_at),
+    mergedAt: toDate(mergedAt),
+  };
+}
+
+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.
+ */
+export class GithubSearchError extends Error {
+  readonly params: SearchParams;
+  readonly status: number | undefined;
+
+  constructor(message: string, params: SearchParams, status?: number) {
+    super(`${message} (input: ${JSON.stringify(params)})`);
+    this.name = "GithubSearchError";
+    this.params = params;
+    this.status = status;
+  }
+}
+
+function describeHttpError(status: number | undefined): string {
+  if (status === 401)
+    return 'GitHub auth failed (401): token invalid or expired — run "gh auth login"';
+  if (status === 403) return "GitHub rate limit or permissions error (403)";
+  if (status === 404) return "repository not found, or the token has no access to it (404)";
+  return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
+}
+
+export interface GithubSearch {
+  search(kind: SearchKind, params: SearchParams): Promise<SearchHit[]>;
+}
+
+/**
+ * Create a search client. The octokit instance (and its auth token) is cached
+ * in the returned closure, so repeated searches reuse the same client without
+ * module-level state.
+ */
+export function createGithubSearch(): GithubSearch {
+  let client: Octokit | undefined;
+
+  async function getClient(): Promise<Octokit> {
+    client ??= new Octokit({ auth: await ghAuthToken() });
+    return client;
+  }
+
+  return {
+    async search(kind, params) {
+      const limit = Math.min(Math.max(params.limit ?? 30, 1), 100);
+      const effective = { ...params, limit };
+
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          const octokit = await getClient();
+          if (effective.assignee === "@me") {
+            const { data } = await octokit.rest.users.getAuthenticated();
+            effective.assignee = data.login;
+          }
+          const q = buildSearchQuery(kind, effective);
+          const { data } = await octokit.rest.search.issuesAndPullRequests({
+            q,
+            per_page: limit,
+          });
+          return data.items.map((item) => normalize(item as unknown as RawSearchItem));
+        } catch (error) {
+          const status = (error as { status?: number }).status;
+          // A stale cached token can produce 401s; drop the cache and retry once.
+          if (status === 401 && attempt === 0 && client) {
+            client = undefined;
+            continue;
+          }
+          const message = (error as { message?: string }).message ?? String(error);
+          throw new GithubSearchError(`${describeHttpError(status)}: ${message}`, params, status);
+        }
+      }
+    },
+  };
+}