@boxxy/forge-github 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/forge-github</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/forge-github"><img src="https://img.shields.io/npm/v/@boxxy/forge-github" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's `Forge` port on GitHub: it reads a pull request, its commits and the open pull requests of a
+repo over the REST API.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/forge-github) with Bun:
+
+```bash
+bun add @boxxy/forge-github
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `createGithubForge({ fetch, baseUrl, token? })` returns a `Forge`. The app passes the `fetch` and
+  the REST root, such as `https://api.github.com`.
+- The `token` is optional, because a deployment's broker can add the credential on the way out. The
+  adapter sends it as a bearer token, and never logs it or puts it in an error.
+- A pull request carries GitHub's own `id`, which pepys builds its entity ID from.
+- A missing pull request reads as `not-found`. Any other failure throws, and the caller reads that
+  as "the forge did not answer".
+
+## Documentation
+
+[The pull request watch](../../docs/design/boxxy/v1-lifecycle.md#the-pull-request-watch) describes
+the calls and the GitHub permissions they need.

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const forgeLimits: {
+    readonly pageSize: 100;
+    readonly maxListPages: 20;
+    readonly maxCommitPages: 3;
+};
+export declare const apiVersion = "2022-11-28";

package/dist/create-github-forge.d.ts

@@ -0,0 +1,3 @@
+import type { Forge } from '@boxxy/model';
+import type { GithubForgeOptions } from './types.ts';
+export declare function createGithubForge(options: GithubForgeOptions): Forge;

package/dist/github-forge-error.d.ts

@@ -0,0 +1,4 @@
+export declare class GithubForgeError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status: number | null);
+}

package/dist/github-schemas.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const githubSchemas: {
+    readonly pullRequest: z.ZodObject<{
+        id: z.ZodNumber;
+        html_url: z.ZodURL;
+        state: z.ZodEnum<{
+            closed: "closed";
+            open: "open";
+        }>;
+        merged_at: z.ZodNullable<z.ZodISODateTime>;
+        merge_commit_sha: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    readonly commitPage: z.ZodArray<z.ZodObject<{
+        sha: z.ZodString;
+        commit: z.ZodObject<{
+            message: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    readonly pullRequestPage: z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+    }, z.core.$strip>>;
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createGithubForge } from './create-github-forge.ts';
+export { GithubForgeError } from './github-forge-error.ts';
+export type { ForgeFetch, GithubForgeOptions } from './types.ts';

package/dist/test-utils/create-fake-github-fetch.d.ts

@@ -0,0 +1,14 @@
+import type { SeededPullRequest } from '@boxxy/dispatch/test-utils/create-fake-forge';
+import type { ForgeFetch } from '../types.ts';
+interface FakeGithubRequest {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface FakeGithubFetch {
+    readonly fetch: ForgeFetch;
+    readonly requests: readonly FakeGithubRequest[];
+    seed: (pullRequest: SeededPullRequest) => void;
+    answerWith: (status: number, body: string) => void;
+}
+export declare function createFakeGithubFetch(): FakeGithubFetch;
+export {};

package/dist/to-pull-request-reading.d.ts

@@ -0,0 +1,4 @@
+import type { PullRequestReading } from '@boxxy/model';
+import type { z } from 'zod';
+import type { githubSchemas } from './github-schemas.ts';
+export declare function toPullRequestReading(pullRequest: z.infer<typeof githubSchemas.pullRequest>, commits: z.infer<typeof githubSchemas.commitPage>): PullRequestReading;

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+interface ForgeRequestInit {
+    readonly method: 'GET';
+    readonly headers: Readonly<Record<string, string>>;
+}
+export type ForgeFetch = (url: string, init: ForgeRequestInit) => Promise<Response>;
+export interface GithubForgeOptions {
+    readonly fetch: ForgeFetch;
+    readonly baseUrl: string;
+    readonly token?: string;
+}
+export {};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@boxxy/forge-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "boxxy's forge port on GitHub: reads a pull request over the REST API",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/forge-github#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "adapters/forge-github"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/model": "0.1.3",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.1.3"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,12 @@
+export const forgeLimits = {
+  // GitHub's largest page size
+  pageSize: 100,
+
+  // 2,000 open pull requests of one repo; a deployment with more reads the first 2,000
+  maxListPages: 20,
+
+  // GitHub lists at most 250 commits of a pull request
+  maxCommitPages: 3,
+} as const;
+
+export const apiVersion = '2022-11-28';

package/src/create-github-forge.ts

@@ -0,0 +1,114 @@
+import type { Forge, PullRequestRef } from '@boxxy/model';
+import type { z } from 'zod';
+import { apiVersion, forgeLimits } from './constants.ts';
+import { GithubForgeError } from './github-forge-error.ts';
+import { githubSchemas } from './github-schemas.ts';
+import { toPullRequestReading } from './to-pull-request-reading.ts';
+import type { GithubForgeOptions } from './types.ts';
+
+// The `Forge` port on the GitHub REST API. A call that fails for any reason but a missing pull
+// request throws, and the caller reads that as "the forge did not answer".
+export function createGithubForge(options: GithubForgeOptions): Forge {
+  const baseUrl = options.baseUrl.replace(/\/+$/u, '');
+
+  const headers: Record<string, string> = {
+    accept: 'application/vnd.github+json',
+    'x-github-api-version': apiVersion,
+    'user-agent': 'boxxy-forge-github',
+    ...(options.token === undefined ? {} : { authorization: `Bearer ${options.token}` }),
+  };
+
+  // `null` for a 404
+  const readJson = async <Schema extends z.ZodType>(
+    path: string,
+    schema: Schema,
+  ): Promise<z.infer<Schema> | null> => {
+    const response = await options.fetch(`${baseUrl}${path}`, { method: 'GET', headers });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new GithubForgeError(
+        `GitHub answered ${response.status} to GET ${path}`,
+        response.status,
+      );
+    }
+
+    const body: unknown = await response.json();
+
+    const parsed = schema.safeParse(body);
+
+    if (!parsed.success) {
+      throw new GithubForgeError(`GitHub gave an unknown body to GET ${path}`, response.status);
+    }
+
+    return parsed.data;
+  };
+
+  // pages until a short one, up to `maxPages`; a 404 in the middle of a list is an error
+  const readPages = async <Item>(
+    path: string,
+    maxPages: number,
+    schema: z.ZodType<Item[]>,
+  ): Promise<Item[]> => {
+    const items: Item[] = [];
+
+    for (let page = 1; page <= maxPages; page += 1) {
+      const query = `per_page=${forgeLimits.pageSize}&page=${page}`;
+      const separator = path.includes('?') ? '&' : '?';
+
+      const rows = await readJson(`${path}${separator}${query}`, schema);
+
+      if (rows === null) {
+        throw new GithubForgeError(`GitHub did not find GET ${path}`, 404);
+      }
+
+      items.push(...rows);
+
+      if (rows.length < forgeLimits.pageSize) {
+        break;
+      }
+    }
+
+    return items;
+  };
+
+  return {
+    readPullRequest: async (ref) => {
+      const path = toPullPath(ref);
+
+      const pullRequest = await readJson(path, githubSchemas.pullRequest);
+
+      if (pullRequest === null) {
+        return 'not-found';
+      }
+
+      const commits = await readPages(
+        `${path}/commits`,
+        forgeLimits.maxCommitPages,
+        githubSchemas.commitPage,
+      );
+
+      return toPullRequestReading(pullRequest, commits);
+    },
+    listOpenPullRequests: async (repo) => {
+      const rows = await readPages(
+        `/repos/${repo}/pulls?state=open&sort=created&direction=asc`,
+        forgeLimits.maxListPages,
+        githubSchemas.pullRequestPage,
+      );
+
+      return rows.map((row) => ({ repo, number: row.number }));
+    },
+  };
+}
+
+function toPullPath(ref: PullRequestRef): string {
+  if (!Number.isInteger(ref.number) || ref.number < 1) {
+    throw new GithubForgeError(`not a pull request number: ${ref.number}`, null);
+  }
+
+  return `/repos/${ref.repo}/pulls/${ref.number}`;
+}

package/src/github-forge-error.ts

@@ -0,0 +1,12 @@
+// A call that GitHub did not answer with a pull request or a clean miss: a status outside 2xx
+// and 404, or a body of an unknown shape. The message holds the path and the status, never a header.
+export class GithubForgeError extends Error {
+  readonly status: number | null;
+
+  constructor(message: string, status: number | null) {
+    super(message);
+
+    this.name = 'GithubForgeError';
+    this.status = status;
+  }
+}

package/src/github-schemas.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+const commit = z.object({ sha: z.string(), commit: z.object({ message: z.string() }) });
+
+export const githubSchemas = {
+  pullRequest: z.object({
+    id: z.number().int().positive(),
+    html_url: z.url(),
+    state: z.enum(['open', 'closed']),
+    merged_at: z.iso.datetime({ offset: true }).nullable(),
+    merge_commit_sha: z.string().nullable(),
+  }),
+  commitPage: z.array(commit),
+  pullRequestPage: z.array(z.object({ number: z.number().int().positive() })),
+} as const;

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createGithubForge } from './create-github-forge.ts';
+export { GithubForgeError } from './github-forge-error.ts';
+export type { ForgeFetch, GithubForgeOptions } from './types.ts';

package/src/test-utils/create-fake-github-fetch.ts

@@ -0,0 +1,108 @@
+import type { SeededPullRequest } from '@boxxy/dispatch/test-utils/create-fake-forge';
+import type { ForgeFetch } from '../types.ts';
+
+interface FakeGithubRequest {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export interface FakeGithubFetch {
+  readonly fetch: ForgeFetch;
+  readonly requests: readonly FakeGithubRequest[];
+  seed: (pullRequest: SeededPullRequest) => void;
+
+  // every later call answers with the status and the body text
+  answerWith: (status: number, body: string) => void;
+}
+
+// A GitHub REST API that serves the pull requests a test seeds: one pull request, its commits
+// and the list of open ones, each by pages of the size in `per_page`.
+export function createFakeGithubFetch(): FakeGithubFetch {
+  const pullRequests: SeededPullRequest[] = [];
+  const requests: FakeGithubRequest[] = [];
+  let fixed: { readonly status: number; readonly body: string } | null = null;
+
+  const read: ForgeFetch = (url, init) => {
+    requests.push({ url, headers: init.headers });
+
+    if (fixed !== null) {
+      return Promise.resolve(new Response(fixed.body, { status: fixed.status }));
+    }
+
+    return Promise.resolve(answer(new URL(url), pullRequests));
+  };
+
+  return {
+    fetch: read,
+    requests,
+    seed: (pullRequest) => {
+      pullRequests.push(pullRequest);
+    },
+    answerWith: (status, body) => {
+      fixed = { status, body };
+    },
+  };
+}
+
+const pullPattern =
+  /^\/repos\/(?<repo>[^/]+\/[^/]+)\/pulls\/(?<number>\d+)(?<commits>\/commits)?$/u;
+
+const listPattern = /^\/repos\/(?<repo>[^/]+\/[^/]+)\/pulls$/u;
+
+function answer(url: URL, pullRequests: readonly SeededPullRequest[]): Response {
+  const page = Number(url.searchParams.get('page') ?? '1');
+  const perPage = Number(url.searchParams.get('per_page') ?? '30');
+
+  const slice = <Item>(items: readonly Item[]): Item[] =>
+    items.slice((page - 1) * perPage, page * perPage);
+
+  const pull = pullPattern.exec(url.pathname);
+
+  if (pull !== null) {
+    const found = pullRequests.findLast(
+      (candidate) =>
+        candidate.ref.repo === pull.groups?.['repo'] &&
+        candidate.ref.number === Number(pull.groups?.['number']),
+    );
+
+    if (found === undefined) {
+      return Response.json({ message: 'Not Found' }, { status: 404 });
+    }
+
+    if (pull.groups?.['commits'] !== undefined) {
+      return Response.json(
+        slice(found.reading.commits).map((commit) => ({
+          sha: commit.sha,
+          commit: { message: commit.message },
+        })),
+      );
+    }
+
+    const merged = found.reading.state === 'merged';
+
+    return Response.json({
+      id: found.githubId,
+      number: found.ref.number,
+      html_url: `https://github.com/${found.ref.repo}/pull/${found.ref.number}`,
+      state: found.reading.state === 'open' ? 'open' : 'closed',
+      merged_at:
+        found.reading.mergedAt === null ? null : new Date(found.reading.mergedAt).toISOString(),
+      merge_commit_sha: merged ? found.reading.mergeCommit : null,
+    });
+  }
+
+  const list = listPattern.exec(url.pathname);
+
+  if (list !== null && url.searchParams.get('state') === 'open') {
+    const open = pullRequests
+      .filter(
+        (candidate) =>
+          candidate.ref.repo === list.groups?.['repo'] && candidate.reading.state === 'open',
+      )
+      .toSorted((first, second) => first.ref.number - second.ref.number);
+
+    return Response.json(slice(open).map((candidate) => ({ number: candidate.ref.number })));
+  }
+
+  return Response.json({ message: 'Not Found' }, { status: 404 });
+}

package/src/to-pull-request-reading.ts

@@ -0,0 +1,30 @@
+import type { PullRequestReading } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { z } from 'zod';
+import type { githubSchemas } from './github-schemas.ts';
+
+// A merged pull request is one with a merge time; GitHub reports it as `closed`.
+export function toPullRequestReading(
+  pullRequest: z.infer<typeof githubSchemas.pullRequest>,
+  commits: z.infer<typeof githubSchemas.commitPage>,
+): PullRequestReading {
+  const mergedAt =
+    pullRequest.merged_at === null
+      ? null
+      : brandSchemas.instant.parse(Date.parse(pullRequest.merged_at));
+
+  return {
+    url: pullRequest.html_url,
+    githubId: pullRequest.id,
+    state: mergedAt === null ? pullRequest.state : 'merged',
+    mergedAt,
+    mergeCommit:
+      mergedAt === null || pullRequest.merge_commit_sha === null
+        ? null
+        : brandSchemas.commitSha.parse(pullRequest.merge_commit_sha),
+    commits: commits.map((commit) => ({
+      sha: brandSchemas.commitSha.parse(commit.sha),
+      message: commit.commit.message,
+    })),
+  };
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+interface ForgeRequestInit {
+  readonly method: 'GET';
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+// The one call the adapter needs, shaped as the platform's `fetch` takes it.
+export type ForgeFetch = (url: string, init: ForgeRequestInit) => Promise<Response>;
+
+export interface GithubForgeOptions {
+  readonly fetch: ForgeFetch;
+
+  // the REST root, such as `https://api.github.com`; a deployment points it at its broker
+  readonly baseUrl: string;
+
+  // Sent as a bearer token when given. A deployment whose broker adds the credential on the way
+  // out leaves it out. The adapter never logs it and never puts it in an error.
+  readonly token?: string;
+}