@stacksjs/github 0.70.162 → 0.70.163

package/dist/client.d.ts

@@ -1,4 +1,8 @@
 export declare function ghHeaders(): Record<string, string>;
+export declare function githubHeaders(token?: string): Record<string, string>;
+/** Provider-neutral GitHub request helper for both reads and writes. */
+export declare function githubRequest(path: string, init?: RequestInit, options?: GitHubClientOptions, attempt?: number): Promise<Response>;
+export declare function githubJson<T>(path: string, init?: RequestInit, options?: GitHubClientOptions): Promise<T>;
 /**
  * `fetch` against the GitHub API that retries on secondary rate limits.
  *
@@ -13,3 +17,8 @@ export declare function ghFetch(url: string, attempt?: number): Promise<Response
  */
 export declare function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
 export declare const GITHUB_API: 'https://api.github.com';
+export declare interface GitHubClientOptions {
+  token?: string
+  apiUrl?: string
+  fetch?: typeof globalThis.fetch
+}

package/dist/client.js

@@ -5,6 +5,11 @@ function getToken() {
     throw Error("GITHUB_TOKEN environment variable is required");
   return token;
 }
+function resolveToken(token) {
+  if (token)
+    return token;
+  return getToken();
+}
 export function ghHeaders() {
   return {
     Authorization: `Bearer ${getToken()}`,
@@ -12,6 +17,50 @@ export function ghHeaders() {
     "X-GitHub-Api-Version": "2022-11-28"
   };
 }
+export function githubHeaders(token) {
+  return {
+    Authorization: `Bearer ${resolveToken(token)}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28"
+  };
+}
+function retryDelay(res, attempt) {
+  if (!(res.status === 429 || res.status === 403 && (res.headers.get("x-ratelimit-remaining") === "0" || !!res.headers.get("retry-after"))))
+    return null;
+  const retryAfterHeader = res.headers.get("retry-after"), resetHeader = res.headers.get("x-ratelimit-reset");
+  if (retryAfterHeader)
+    return Number(retryAfterHeader) * 1000;
+  if (resetHeader)
+    return Math.max(0, Number(resetHeader) * 1000 - Date.now()) + 500;
+  return 1000 * 2 ** attempt;
+}
+export async function githubRequest(path, init = {}, options = {}, attempt = 0) {
+  const fetcher = options.fetch ?? globalThis.fetch, url = path.startsWith("http") ? path : `${options.apiUrl ?? GITHUB_API}${path.startsWith("/") ? path : `/${path}`}`, response = await fetcher(url, {
+    ...init,
+    headers: { ...githubHeaders(options.token), ...init.headers }
+  });
+  if (response.ok || attempt >= 3)
+    return response;
+  const waitMs = retryDelay(response, attempt);
+  if (waitMs === null)
+    return response;
+  await new Promise((resolve) => setTimeout(resolve, Math.min(waitMs, 30000)));
+  return githubRequest(path, init, options, attempt + 1);
+}
+export async function githubJson(path, init = {}, options = {}) {
+  const response = await githubRequest(path, init, options);
+  if (!response.ok) {
+    const payload = await response.text();
+    let message = payload;
+    try {
+      message = JSON.parse(payload).message || payload;
+    } catch {}
+    throw Error(`GitHub API ${response.status}: ${message || response.statusText}`);
+  }
+  if (response.status === 204)
+    return;
+  return await response.json();
+}
 export async function ghFetch(url, attempt = 0) {
   const res = await fetch(url, { headers: ghHeaders() });
   if (res.ok || attempt >= 3)

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { GitHubClientOptions } from './client';
 export type { DetectOptions, FailedTransition, PreviousRunState } from './failure-detector';
 export type { WorkflowJob, WorkflowRun } from './run-history';
 export type {
@@ -6,6 +7,13 @@ export type {
   RunnerAlertState,
   RunnerSample,
 } from './runner-pressure-detector';
+export type {
+  CreatedPullRequest,
+  CreatePullRequestWithFilesOptions,
+  RepositoryFileChange,
+  RepositoryTree,
+  RepositoryTreeEntry,
+} from './pull-requests';
 export type {
   DashboardData,
   DashboardOptions,
@@ -25,7 +33,7 @@ export type {
  * single dimension without pulling the whole snapshot through.
  */
 export { fetchBotPRCounts } from './bots';
-export { ghFetch, ghHeaders, GITHUB_API, mapWithConcurrency } from './client';
+export { ghFetch, ghHeaders, githubHeaders, githubJson, githubRequest, GITHUB_API, mapWithConcurrency } from './client';
 export { clearDashboardCache, getDashboardData } from './dashboard';
 export { detectNewlyFailedRuns } from './failure-detector';
 export { fetchAllRepos } from './repos';
@@ -33,3 +41,4 @@ export { fetchRepoActiveRuns } from './runners';
 export { fetchRunJobs, fetchWorkflowRuns } from './run-history';
 export { detectRunnerPressure } from './runner-pressure-detector';
 export { fetchFailedJobs, fetchRepoStatus } from './runs';
+export { createPullRequestWithFiles, fetchRepositoryFile, fetchRepositoryTree } from './pull-requests';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { fetchBotPRCounts } from "./bots";
-export { ghFetch, ghHeaders, GITHUB_API, mapWithConcurrency } from "./client";
+export { ghFetch, ghHeaders, githubHeaders, githubJson, githubRequest, GITHUB_API, mapWithConcurrency } from "./client";
 export { clearDashboardCache, getDashboardData } from "./dashboard";
 export { detectNewlyFailedRuns } from "./failure-detector";
 export { fetchAllRepos } from "./repos";
@@ -7,3 +7,4 @@ export { fetchRepoActiveRuns } from "./runners";
 export { fetchRunJobs, fetchWorkflowRuns } from "./run-history";
 export { detectRunnerPressure } from "./runner-pressure-detector";
 export { fetchFailedJobs, fetchRepoStatus } from "./runs";
+export { createPullRequestWithFiles, fetchRepositoryFile, fetchRepositoryTree } from "./pull-requests";

package/dist/pull-requests.d.ts

@@ -0,0 +1,43 @@
+import type { GitHubClientOptions } from './client';
+export declare function fetchRepositoryTree(owner: string, repo: string, ref: string, options?: GitHubClientOptions): Promise<RepositoryTree>;
+export declare function fetchRepositoryFile(owner: string, repo: string, path: string, ref: string, options?: GitHubClientOptions & { maxBytes?: number }): Promise<string>;
+/**
+ * Create one commit containing all file replacements, expose it through a new
+ * branch, and open a pull request. The branch is only created after every blob,
+ * tree, and commit has succeeded, so partial generation never exposes half a fix.
+ */
+export declare function createPullRequestWithFiles(options: CreatePullRequestWithFilesOptions): Promise<CreatedPullRequest>;
+export declare interface RepositoryFileChange {
+  path: string
+  content: string
+}
+export declare interface CreatePullRequestWithFilesOptions extends GitHubClientOptions {
+  owner: string
+  repo: string
+  branch: string
+  title: string
+  body: string
+  commitMessage: string
+  files: RepositoryFileChange[]
+  base?: string
+  draft?: boolean
+}
+export declare interface CreatedPullRequest {
+  number: number
+  url: string
+  branch: string
+  base: string
+  commitSha: string
+}
+export declare interface RepositoryTreeEntry {
+  path: string
+  mode: string
+  type: 'blob' | 'tree' | 'commit'
+  sha: string
+  size?: number
+}
+export declare interface RepositoryTree {
+  sha: string
+  truncated: boolean
+  entries: RepositoryTreeEntry[]
+}

package/dist/pull-requests.js

@@ -0,0 +1,83 @@
+import { githubJson } from "./client";
+function repoPath(owner, repo) {
+  if (!/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo))
+    throw Error("GitHub owner and repository names contain invalid characters");
+  return `/repos/${owner}/${repo}`;
+}
+function validateBranch(branch) {
+  if (!branch || branch.length > 240 || branch.startsWith("/") || branch.endsWith("/") || branch.includes("..") || /[~^:?*[\\\s]/.test(branch))
+    throw Error(`Invalid Git branch name: ${branch}`);
+}
+function validateFiles(files) {
+  if (!files.length)
+    throw Error("At least one file change is required");
+  if (files.length > 100)
+    throw Error("A pull request may change at most 100 files");
+  const seen = new Set;
+  let bytes = 0;
+  for (const file of files) {
+    if (!file.path || file.path.startsWith("/") || file.path.includes("\\") || file.path.split("/").includes(".."))
+      throw Error(`Unsafe repository path: ${file.path}`);
+    if (seen.has(file.path))
+      throw Error(`Duplicate repository path: ${file.path}`);
+    seen.add(file.path);
+    bytes += Buffer.byteLength(file.content);
+  }
+  if (bytes > 5242880)
+    throw Error("Combined file content exceeds the 5 MiB safety limit");
+}
+export async function fetchRepositoryTree(owner, repo, ref, options = {}) {
+  const payload = await githubJson(`${repoPath(owner, repo)}/git/trees/${encodeURIComponent(ref)}?recursive=1`, {}, options);
+  return { sha: payload.sha, truncated: !!payload.truncated, entries: payload.tree ?? [] };
+}
+export async function fetchRepositoryFile(owner, repo, path, ref, options = {}) {
+  validateFiles([{ path, content: "" }]);
+  const payload = await githubJson(`${repoPath(owner, repo)}/contents/${path.split("/").map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`, {}, options);
+  if (payload.type !== "file" || payload.encoding !== "base64" || typeof payload.content !== "string")
+    throw Error(`GitHub path is not a base64 encoded file: ${path}`);
+  const maxBytes = options.maxBytes ?? 262144;
+  if ((payload.size ?? 0) > maxBytes)
+    throw Error(`GitHub file exceeds the ${maxBytes} byte safety limit: ${path}`);
+  const content = Buffer.from(payload.content.replace(/\n/g, ""), "base64");
+  if (content.byteLength > maxBytes)
+    throw Error(`Decoded GitHub file exceeds the ${maxBytes} byte safety limit: ${path}`);
+  return content.toString("utf8");
+}
+export async function createPullRequestWithFiles(options) {
+  validateBranch(options.branch);
+  validateFiles(options.files);
+  const basePath = repoPath(options.owner, options.repo), client = { token: options.token, apiUrl: options.apiUrl, fetch: options.fetch };
+  let base = options.base;
+  if (!base)
+    base = (await githubJson(basePath, {}, client)).default_branch;
+  if (!base)
+    throw Error("GitHub repository has no default branch");
+  const reference = await githubJson(`${basePath}/git/ref/heads/${encodeURIComponent(base)}`, {}, client), baseCommit = await githubJson(`${basePath}/git/commits/${reference.object.sha}`, {}, client), blobs = await Promise.all(options.files.map(async (file) => {
+    const blob = await githubJson(`${basePath}/git/blobs`, {
+      method: "POST",
+      body: JSON.stringify({ content: file.content, encoding: "utf-8" })
+    }, client);
+    return { path: file.path, mode: "100644", type: "blob", sha: blob.sha };
+  })), tree = await githubJson(`${basePath}/git/trees`, {
+    method: "POST",
+    body: JSON.stringify({ base_tree: baseCommit.tree.sha, tree: blobs })
+  }, client), commit = await githubJson(`${basePath}/git/commits`, {
+    method: "POST",
+    body: JSON.stringify({ message: options.commitMessage, tree: tree.sha, parents: [reference.object.sha] })
+  }, client);
+  await githubJson(`${basePath}/git/refs`, {
+    method: "POST",
+    body: JSON.stringify({ ref: `refs/heads/${options.branch}`, sha: commit.sha })
+  }, client);
+  const pull = await githubJson(`${basePath}/pulls`, {
+    method: "POST",
+    body: JSON.stringify({
+      title: options.title,
+      body: options.body,
+      head: options.branch,
+      base,
+      draft: options.draft ?? !0
+    })
+  }, client);
+  return { number: pull.number, url: pull.html_url, branch: options.branch, base, commitSha: commit.sha };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/github",
   "type": "module",
-  "version": "0.70.162",
+  "version": "0.70.163",
   "description": "GitHub API client used by Stacks framework features (dashboard CI surface, notifications, runner alerts).",
   "author": "Chris Breuer",
   "contributors": [