@shivaedev/github 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/github",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Typed GitHub REST requests, conditional reads and resource budgets for Effect applications",
   "keywords": [
     "effect"
@@ -51,17 +51,24 @@
     "@effect/platform-node": "4.0.6",
     "@effect/platform-node-shared": "4.0.6",
     "@effect/vitest": "4.0.6",
-    "@shivaedev/quality": "0.55.0",
-    "@shivaedev/test": "0.12.1",
-    "@shivaedev/test-story": "0.33.0",
+    "@shivaedev/quality": "0.56.0",
+    "@shivaedev/test": "0.13.0",
+    "@shivaedev/test-story": "0.34.0",
     "@types/node": "24.19.2",
+    "@zip.js/zip.js": "2.24.0",
     "effect": "4.0.6",
     "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "peerDependencies": {
+    "@zip.js/zip.js": "2.24.0",
     "effect": "4.0.6"
   },
+  "peerDependenciesMeta": {
+    "@zip.js/zip.js": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24"
   },

package/src/GitHub.ts

@@ -5,7 +5,9 @@ import { artifacts } from "#artifacts.ts";
 import { checkRuns } from "#checkRuns.ts";
 import { GitHubConfig } from "#GitHubConfig.ts";
 import { GitHubToken } from "#GitHubToken.ts";
+import { decodedPages, type ListOptions } from "#pagedLists.ts";
 import { rateLimits } from "#rateLimits.ts";
+import { repositoryReads } from "#repositoryReads.ts";
 import { representations } from "#representations.ts";
 import { requests } from "#requests.ts";
 import { stickyComments } from "#stickyComments.ts";
@@ -21,7 +23,7 @@ export const GitHub = defineService({
 		const refresh = yield* TokenRefresh;
 		return {
 			apiUrl: config.apiUrl,
-			archive: artifacts(config.apiUrl, client, token, rates, refresh),
+			archive: yield* artifacts(config.apiUrl, rates),
 			rates,
 			request: requests(client, token, rates, refresh),
 			responseByteLimit: config.responseByteLimit,
@@ -35,6 +37,7 @@ export const GitHub = defineService({
 			...archive,
 			...stickyComments(client),
 			...checkRuns(client),
+			...repositoryReads(client),
 			observations: () => Effect.sync(() => [...rates.observations.values()]),
 			resource: (path: string) => Effect.sync(() => rates.resource(new URL(path, apiUrl).pathname)),
 			text: (path: string, accept: string, limit: number) =>
@@ -48,19 +51,23 @@ export function read<TSchema extends Schema.Constraint>(path: string, schema: TS
 	return Effect.flatMap(GitHub, (github) => Effect.flatMap(github.read(path, responseByteLimit), (response) => response.decode(schema)));
 }
 
-export function list<TSchema extends Schema.Constraint>(path: string, schema: TSchema, responseByteLimit?: number) {
-	return Stream.unwrap(Effect.flatMap(GitHub, (github) => github.list(path, undefined, responseByteLimit))).pipe(
-		Stream.mapEffect((response) => response.decode(Schema.Array(schema))),
-		Stream.flatMap(Stream.fromIterable),
-	);
+export function listPages<TSchema extends Schema.Constraint>(path: string, schema: TSchema, options?: ListOptions | number) {
+	return Stream.unwrap(Effect.map(GitHub, (github) => decodedPages(github, path, schema, options)));
+}
+
+export function list<TSchema extends Schema.Constraint>(path: string, schema: TSchema, options?: ListOptions | number) {
+	return listPages(path, schema, options).pipe(Stream.flatMap((page) => Stream.fromIterable(page.items)));
 }
 
-export function listBounded<TSchema extends Schema.Constraint>(path: string, schema: TSchema, pageCap: number, responseByteLimit?: number) {
-	return Stream.unwrap(Effect.flatMap(GitHub, (github) => github.list(path, undefined, responseByteLimit))).pipe(
+export function listBounded<TSchema extends Schema.Constraint>(path: string, schema: TSchema, pageCap: number, options?: ListOptions | number) {
+	return listPages(path, schema, options).pipe(
 		Stream.take(pageCap),
-		Stream.mapEffect((page) => Effect.map(page.decode(Schema.Array(schema)), (items) => ({ items, truncated: page.hasNext }))),
 		Stream.runCollect,
-		Effect.map((pages) => ({ items: pages.flatMap((page) => page.items), truncated: pages.at(-1)?.truncated ?? false })),
+		Effect.map((pages) => ({
+			items: pages.flatMap((page) => page.items),
+			skipped: pages.reduce((count, page) => count + page.skipped, 0),
+			truncated: pages.at(-1)?.hasNext ?? false,
+		})),
 	);
 }
 

package/src/adapters/resolveApiUrl.ts

@@ -0,0 +1,5 @@
+export function resolveApiUrl(apiUrl: string, path: string) {
+	const base = new URL(apiUrl);
+	base.pathname = `${base.pathname.replace(/\/$/u, "")}/`;
+	return new URL(path.replace(/^\/(?!\/)/u, ""), base).href;
+}

package/src/adapters/zipEntries.ts

@@ -0,0 +1,69 @@
+import type { Entry } from "@zip.js/zip.js";
+import { Effect, Stream } from "effect";
+import { GitHubArtifactCompressionRatio, GitHubArtifactExtractedTooLarge, GitHubArtifactExtractionError } from "#artifactErrors.ts";
+
+interface ReadLimits {
+	readonly compressionRatioLimit: number;
+	readonly remaining: number;
+	readonly totalSizeLimit: number;
+}
+
+function invalidArchive() {
+	return new GitHubArtifactExtractionError({ reason: "invalid-archive" });
+}
+
+function readEntry(entry: Entry, limits: ReadLimits) {
+	return Effect.tryPromise({
+		catch: (error) =>
+			error instanceof GitHubArtifactExtractedTooLarge || error instanceof GitHubArtifactCompressionRatio ? error : invalidArchive(),
+		try: async (signal) => {
+			let size = 0;
+			const chunks: Uint8Array[] = [];
+			const output = new WritableStream<Uint8Array>({
+				write(chunk) {
+					size += chunk.byteLength;
+					if (size > limits.remaining) {
+						throw new GitHubArtifactExtractedTooLarge({ limit: limits.totalSizeLimit });
+					}
+					if (size > entry.compressedSize * limits.compressionRatioLimit) {
+						throw new GitHubArtifactCompressionRatio({ limit: limits.compressionRatioLimit, path: entry.filename });
+					}
+					chunks.push(chunk);
+				},
+			});
+			if (!entry.directory) {
+				await entry.getData(output, { signal });
+			}
+			const result = new Uint8Array(size);
+			let offset = 0;
+			for (const chunk of chunks) {
+				result.set(chunk, offset);
+				offset += chunk.byteLength;
+			}
+			return result;
+		},
+	});
+}
+
+export const zipEntries = Effect.fn("GitHub.zipEntries")(function* (bytes: Uint8Array) {
+	const { ZipReader, Uint8ArrayReader } = yield* Effect.tryPromise({
+		catch: () => new GitHubArtifactExtractionError({ reason: "reader-unavailable" }),
+		try: () => import("@zip.js/zip.js"),
+	});
+	const reader = new ZipReader(new Uint8ArrayReader(bytes), {
+		checkCrc32: true,
+		// Core validates paths so refusals retain their dedicated typed error.
+		filenameValidation: "tolerant",
+		useWebWorkers: false,
+	});
+	return Stream.fromAsyncIterable(reader.getEntriesGenerator(), invalidArchive).pipe(
+		Stream.map((entry) => ({
+			compressedSize: entry.compressedSize,
+			directory: entry.directory,
+			path: entry.filename,
+			read: (limits: ReadLimits) => readEntry(entry, limits),
+			symlink: entry.symlink,
+			uncompressedSize: entry.uncompressedSize,
+		})),
+	);
+});

package/src/appTokens.ts

@@ -1,6 +1,7 @@
 import { Cache, Clock, Context, Effect, Exit, Layer, Option, type Redacted, Schema } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { readBoundedJson } from "@shivaedev/http/body.ts";
+import { resolveApiUrl } from "#adapters/resolveApiUrl.ts";
 import { appJwt } from "#appJwt.ts";
 import { authenticatedRequest } from "#authenticatedRequest.ts";
 import { GitHubAppError } from "#errors.ts";
@@ -65,7 +66,7 @@ function appRequests(client: HttpClient.HttpClient, apiUrl: string) {
 		schema: TSchema,
 		body?: unknown,
 	) {
-		let input = HttpClientRequest.make(method)(new URL(path, apiUrl).href, {
+		let input = HttpClientRequest.make(method)(resolveApiUrl(apiUrl, path), {
 			headers: { Accept: "application/vnd.github+json" },
 		});
 		if (body !== undefined) {

package/src/artifactErrors.ts

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+
+export class GitHubArtifactPathTraversal extends Schema.TaggedError<GitHubArtifactPathTraversal>()("GitHubArtifactPathTraversal", {
+	path: Schema.String,
+}) {}
+
+export class GitHubArtifactSymlink extends Schema.TaggedError<GitHubArtifactSymlink>()("GitHubArtifactSymlink", {
+	path: Schema.String,
+}) {}
+
+export class GitHubArtifactDuplicateEntry extends Schema.TaggedError<GitHubArtifactDuplicateEntry>()("GitHubArtifactDuplicateEntry", {
+	path: Schema.String,
+}) {}
+
+export class GitHubArtifactCompressionRatio extends Schema.TaggedError<GitHubArtifactCompressionRatio>()("GitHubArtifactCompressionRatio", {
+	limit: Schema.Number,
+	path: Schema.String,
+}) {}
+
+export class GitHubArtifactExtractedTooLarge extends Schema.TaggedError<GitHubArtifactExtractedTooLarge>()("GitHubArtifactExtractedTooLarge", {
+	limit: Schema.Number,
+}) {}
+
+export class GitHubArtifactExtractionError extends Schema.TaggedError<GitHubArtifactExtractionError>()("GitHubArtifactExtractionError", {
+	reason: Schema.Literals(["reader-unavailable", "invalid-archive", "invalid-limits"]),
+}) {}

package/src/artifactExtraction.ts

@@ -0,0 +1,62 @@
+import { Effect, Stream } from "effect";
+import { zipEntries } from "#adapters/zipEntries.ts";
+import {
+	GitHubArtifactCompressionRatio,
+	GitHubArtifactExtractedTooLarge,
+	GitHubArtifactExtractionError,
+	GitHubArtifactSymlink,
+} from "#artifactErrors.ts";
+import { artifactPaths } from "#artifactPaths.ts";
+
+export interface ArtifactExtractionOptions {
+	readonly compressionRatioLimit?: number;
+	readonly totalSizeLimit?: number;
+}
+
+export interface ArtifactFile {
+	readonly bytes: Uint8Array;
+	readonly path: string;
+}
+
+export const extractArtifactArchive = Effect.fn("GitHub.extractArtifactArchive")(function* (bytes: Uint8Array, options: ArtifactExtractionOptions) {
+	const totalSizeLimit = options.totalSizeLimit ?? 100 * 1024 * 1024;
+	const compressionRatioLimit = options.compressionRatioLimit ?? 100;
+	if (!Number.isSafeInteger(totalSizeLimit) || totalSizeLimit < 0 || !Number.isFinite(compressionRatioLimit) || compressionRatioLimit <= 0) {
+		return yield* new GitHubArtifactExtractionError({ reason: "invalid-limits" });
+	}
+	const entries = yield* zipEntries(bytes);
+	const pathOf = artifactPaths();
+	const files: ArtifactFile[] = [];
+	let total = 0;
+	yield* entries.pipe(
+		Stream.runForEach((entry) =>
+			Effect.gen(function* () {
+				const path = yield* pathOf(entry.path, entry.directory);
+				yield* validateEntry(entry, total, { compressionRatioLimit, totalSizeLimit });
+				const content = yield* entry.read({ compressionRatioLimit, remaining: totalSizeLimit - total, totalSizeLimit });
+				total += content.byteLength;
+				if (!entry.directory) {
+					files.push({ bytes: content, path });
+				}
+			}),
+		),
+	);
+	return files;
+});
+
+type ZipEntry = Stream.Success<Effect.Success<ReturnType<typeof zipEntries>>>;
+
+const validateEntry = Effect.fnUntraced(function* (entry: ZipEntry, total: number, options: Required<ArtifactExtractionOptions>) {
+	if (entry.symlink) {
+		return yield* new GitHubArtifactSymlink({ path: entry.path });
+	}
+	if (entry.directory && entry.uncompressedSize !== 0) {
+		return yield* new GitHubArtifactExtractionError({ reason: "invalid-archive" });
+	}
+	if (total + entry.uncompressedSize > options.totalSizeLimit) {
+		return yield* new GitHubArtifactExtractedTooLarge({ limit: options.totalSizeLimit });
+	}
+	if (entry.uncompressedSize > entry.compressedSize * options.compressionRatioLimit) {
+		return yield* new GitHubArtifactCompressionRatio({ limit: options.compressionRatioLimit, path: entry.path });
+	}
+});

package/src/artifactPaths.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect";
+import { GitHubArtifactDuplicateEntry, GitHubArtifactPathTraversal } from "#artifactErrors.ts";
+
+const safeName = Effect.fnUntraced(function* (path: string, directory: boolean) {
+	const name = directory && path.endsWith("/") ? path.slice(0, -1) : path;
+	const segments = name.split("/");
+	if (/[\\:\0]/u.test(name) || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+		return yield* new GitHubArtifactPathTraversal({ path });
+	}
+	return { name, segments };
+});
+
+export function artifactPaths() {
+	const entries = new Set<string>();
+	const files = new Set<string>();
+	const directories = new Set<string>();
+	const registerParents = Effect.fnUntraced(function* (path: string, segments: readonly string[]) {
+		for (let index = 1; index < segments.length; index += 1) {
+			const parent = segments.slice(0, index).join("/");
+			if (files.has(parent)) {
+				return yield* new GitHubArtifactDuplicateEntry({ path });
+			}
+			directories.add(parent);
+		}
+	});
+	return Effect.fnUntraced(function* (path: string, directory: boolean) {
+		const { name, segments } = yield* safeName(path, directory);
+		if (entries.has(name) || (!directory && directories.has(name))) {
+			return yield* new GitHubArtifactDuplicateEntry({ path });
+		}
+		yield* registerParents(path, segments);
+		entries.add(name);
+		(directory ? directories : files).add(name);
+		return name;
+	});
+}

package/src/artifacts.ts

@@ -4,13 +4,15 @@ import * as HttpStatus from "effect/http/HttpStatus";
 import { readBoundedBody } from "@shivaedev/http/body.ts";
 import type { RemoteStatusError } from "@shivaedev/http/errors.ts";
 import { filterStatus } from "@shivaedev/http/filterStatus.ts";
-import { authenticatedRequest } from "./authenticatedRequest.ts";
-import { GitHubArtifactError, GitHubArtifactTooLarge, GitHubTransportError } from "./errors.ts";
-import type { GitHubToken } from "./GitHubToken.ts";
-import type { RateLimits } from "./rateLimits.ts";
-import type { TokenRefresh } from "./TokenRefresh.ts";
+import { resolveApiUrl } from "#adapters/resolveApiUrl.ts";
+import { type ArtifactExtractionOptions, extractArtifactArchive } from "#artifactExtraction.ts";
+import { authenticatedRequest } from "#authenticatedRequest.ts";
+import { GitHubArtifactError, GitHubArtifactTooLarge, GitHubTransportError } from "#errors.ts";
+import { GitHubToken } from "#GitHubToken.ts";
+import type { RateLimits } from "#rateLimits.ts";
+import { TokenRefresh } from "#TokenRefresh.ts";
 
-export interface ArtifactArchiveOptions {
+export interface ArtifactArchiveOptions extends ArtifactExtractionOptions {
 	readonly artifactId: number;
 	readonly byteLimit: number;
 	readonly owner: string;
@@ -23,41 +25,36 @@ function downloadFailure(path: string, cause: HttpClientError.HttpClientError |
 		: new GitHubArtifactError({ stage: "download", status: cause.status });
 }
 
-export function artifacts(
-	apiUrl: string,
-	client: HttpClient.HttpClient,
-	token: GitHubToken["Service"],
-	rates: RateLimits,
-	refresh: typeof TokenRefresh.Service = undefined,
-) {
+export const artifacts = Effect.fn("GitHub.artifacts")(function* (apiUrl: string, rates: RateLimits) {
+	const client = yield* HttpClient.HttpClient;
+	const token = yield* GitHubToken;
+	const refresh = yield* TokenRefresh;
 	const send = authenticatedRequest(HttpClient.withScope(client), token, rates, refresh);
 	const download = filterStatus(HttpClient.withScope(client));
 	return {
-		downloadArtifactArchive: (options: ArtifactArchiveOptions) =>
-			Effect.scoped(
-				Effect.gen(function* () {
-					const path = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/actions/artifacts/${options.artifactId}/zip`;
-					const redirect = yield* send(HttpClientRequest.get(new URL(path, apiUrl).href, { accept: "application/vnd.github+json" }), "manual").pipe(
-						Effect.catchTags({
-							RemoteGone: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
-							RemoteNotFound: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
-						}),
-					);
-					const location = redirect.headers.location;
-					if (redirect.status !== HttpStatus.fromLiteral("Found") || location === undefined) {
-						return yield* new GitHubArtifactError({ stage: "redirect", status: redirect.status });
-					}
-					const response = yield* download.get(location).pipe(
-						Effect.provideService(FetchHttpClient.RequestInit, { credentials: "omit", redirect: "manual" }),
-						Effect.mapError((cause) => downloadFailure(path, cause)),
-					);
-					return yield* readBoundedBody(response, options.byteLimit).pipe(
-						Effect.catchTags({
-							HttpClientError: (cause) => Effect.fail(new GitHubTransportError({ path }, { cause })),
-							ResponseBodyTooLarge: (cause) => Effect.fail(new GitHubArtifactTooLarge({ limit: cause.limit }, { cause })),
-						}),
-					);
+		downloadArtifactArchive: Effect.fn("GitHub.downloadArtifactArchive")(function* (options: ArtifactArchiveOptions) {
+			const path = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/actions/artifacts/${options.artifactId}/zip`;
+			const redirect = yield* send(HttpClientRequest.get(resolveApiUrl(apiUrl, path), { accept: "application/vnd.github+json" }), "manual").pipe(
+				Effect.catchTags({
+					RemoteGone: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
+					RemoteNotFound: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
 				}),
-			),
+			);
+			const location = redirect.headers.location;
+			if (redirect.status !== HttpStatus.fromLiteral("Found") || location === undefined) {
+				return yield* new GitHubArtifactError({ stage: "redirect", status: redirect.status });
+			}
+			const response = yield* download.get(location).pipe(
+				Effect.provideService(FetchHttpClient.RequestInit, { credentials: "omit", redirect: "manual" }),
+				Effect.mapError((cause) => downloadFailure(path, cause)),
+			);
+			return yield* readBoundedBody(response, options.byteLimit).pipe(
+				Effect.catchTags({
+					HttpClientError: (cause) => Effect.fail(new GitHubTransportError({ path }, { cause })),
+					ResponseBodyTooLarge: (cause) => Effect.fail(new GitHubArtifactTooLarge({ limit: cause.limit }, { cause })),
+				}),
+				Effect.flatMap((bytes) => extractArtifactArchive(bytes, options)),
+			);
+		}, Effect.scoped),
 	};
-}
+});

package/src/checkRuns.ts

@@ -1,4 +1,5 @@
 import { Effect, Option, Schema, Stream } from "effect";
+import { decodedPages } from "#pagedLists.ts";
 import type { Representations } from "#representations.ts";
 
 export const CheckRunOutput = Schema.Struct({
@@ -50,8 +51,6 @@ export const CheckRun = Schema.Struct({
 	status: CheckRunStatus,
 }).pipe(Schema.encodeKeys({ detailsUrl: "details_url", headSha: "head_sha" }));
 
-const CheckRunPage = Schema.Struct({ checkRuns: Schema.Array(CheckRun) }).pipe(Schema.encodeKeys({ checkRuns: "check_runs" }));
-
 export const FindCheckRun = Schema.Union([
 	Schema.Struct({ appId: Schema.optional(Schema.Number), headSha: Schema.String, name: Schema.String }),
 	Schema.Struct({ appId: Schema.Number, headSha: Schema.String, name: Schema.optional(Schema.String) }),
@@ -74,10 +73,11 @@ export function checkRuns(client: Representations) {
 		if (name !== undefined) {
 			query.set("check_name", name);
 		}
-		const pages = yield* client.list(`/repos/${owner}/${repo}/commits/${encodeURIComponent(headSha)}/check-runs?${query}`);
+		const pages = decodedPages(client, `/repos/${owner}/${repo}/commits/${encodeURIComponent(headSha)}/check-runs?${query}`, CheckRun, {
+			arrayKey: "check_runs",
+		});
 		return yield* pages.pipe(
-			Stream.mapEffect((page) => page.decode(CheckRunPage)),
-			Stream.flatMap((page) => Stream.fromIterable(page.checkRuns)),
+			Stream.flatMap((page) => Stream.fromIterable(page.items)),
 			Stream.filter((run) => (name === undefined || run.name === name) && (appId === undefined || run.app?.id === appId)),
 			Stream.runFold(
 				() => Option.none<typeof CheckRun.Type>(),

package/src/gitSchemas.ts

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+import { PullRequestFile, User } from "#repositorySchemas.ts";
+
+const CommitIdentity = Schema.Struct({ date: Schema.String, email: Schema.String, name: Schema.String });
+const CommitData = Schema.Struct({
+	author: Schema.NullOr(CommitIdentity),
+	committer: Schema.NullOr(CommitIdentity),
+	message: Schema.String,
+	tree: Schema.Struct({ sha: Schema.String, url: Schema.String }),
+});
+
+const commitFields = {
+	author: Schema.NullOr(User),
+	commit: CommitData,
+	committer: Schema.NullOr(User),
+	htmlUrl: Schema.String,
+	parents: Schema.Array(Schema.Struct({ sha: Schema.String, url: Schema.String })),
+	sha: Schema.String,
+};
+
+export const Commit = Schema.Struct(commitFields).pipe(Schema.encodeKeys({ htmlUrl: "html_url" }));
+
+export const CommitDetail = Schema.Struct({
+	...commitFields,
+	files: Schema.optional(Schema.Array(PullRequestFile)),
+	stats: Schema.Struct({ additions: Schema.Number, deletions: Schema.Number, total: Schema.Number }),
+}).pipe(Schema.encodeKeys({ htmlUrl: "html_url" }));
+
+export const Comparison = Schema.Struct({
+	aheadBy: Schema.Number,
+	behindBy: Schema.Number,
+	commits: Schema.Array(Commit),
+	files: Schema.optional(Schema.Array(PullRequestFile)),
+	status: Schema.Literals(["diverged", "ahead", "behind", "identical"]),
+	totalCommits: Schema.Number,
+}).pipe(Schema.encodeKeys({ aheadBy: "ahead_by", behindBy: "behind_by", totalCommits: "total_commits" }));
+
+export const GitTree = Schema.Struct({
+	sha: Schema.String,
+	tree: Schema.Array(
+		Schema.Struct({
+			mode: Schema.String,
+			path: Schema.String,
+			sha: Schema.String,
+			size: Schema.optional(Schema.Number),
+			type: Schema.Literals(["blob", "tree", "commit"]),
+			url: Schema.optional(Schema.String),
+		}),
+	),
+	truncated: Schema.Boolean,
+	url: Schema.String,
+});

package/src/installationClients.ts

@@ -5,34 +5,40 @@ import type { AppCredentials } from "#appJwt.ts";
 import { appTokens } from "#appTokens.ts";
 import { GitHub } from "#GitHub.ts";
 import { GitHubConfig } from "#GitHubConfig.ts";
+import { viewerRepositoryAccess } from "#viewerRepositoryAccess.ts";
 
 export const GitHubAppCredentials = Context.Service<{ readonly credentials: AppCredentials }>("@shivaedev/github/AppCredentials");
 
 export const GitHubApp = defineService({
 	id: "@shivaedev/github/GitHubApp",
 	initialize: Effect.gen(function* () {
-		const { credentials } = yield* GitHubAppCredentials;
+		const { credentials: supplied } = yield* GitHubAppCredentials;
+		const credentials = { appId: supplied.appId, privateKey: supplied.privateKey };
 		const http = yield* HttpClient.HttpClient;
 		const config = yield* GitHubConfig;
-		return yield* Cache.make({
+		const environment = Layer.mergeAll(Layer.succeed(HttpClient.HttpClient)(http), Layer.succeed(GitHubConfig)(config));
+		const app = yield* Layer.build(GitHub.layer.pipe(Layer.provide(appTokens(credentials)), Layer.provide(environment))).pipe(
+			Effect.scoped,
+			Effect.map((context) => Context.get(context, GitHub)),
+		);
+		const clients = yield* Cache.make({
 			capacity: 100,
 			lookup: (installationId: number) =>
-				Layer.build(
-					GitHub.layer.pipe(
-						Layer.provide(appTokens({ ...credentials, installationId })),
-						Layer.provide(Layer.succeed(HttpClient.HttpClient)(http)),
-						Layer.provide(Layer.succeed(GitHubConfig)(config)),
-					),
-				).pipe(
+				Layer.build(GitHub.layer.pipe(Layer.provide(appTokens({ ...credentials, installationId })), Layer.provide(environment))).pipe(
 					Effect.scoped,
 					Effect.map((context) => Context.get(context, GitHub)),
 				),
 			timeToLive: "30 minutes",
 		});
+		function installation(id: number) {
+			return Cache.get(clients, id).pipe(Effect.tap((client) => Cache.set(clients, id, client)));
+		}
+		return { installation, viewers: yield* viewerRepositoryAccess(app, installation) };
 	}),
-	methods: (clients) => ({
-		installation: (installationId: number) =>
-			Cache.get(clients, installationId).pipe(Effect.tap((client) => Cache.set(clients, installationId, client))),
+	methods: ({ installation, viewers }) => ({
+		installation,
+		viewerRepositories: (account: number | string) =>
+			Cache.get(viewers, typeof account === "number" ? `id:${account}` : `login:${account.toLowerCase()}`),
 	}),
 	requires: [GitHubAppCredentials, HttpClient.HttpClient, GitHubConfig],
 });

package/src/pagedLists.ts

@@ -0,0 +1,40 @@
+import { Effect, Option, Schema, Stream } from "effect";
+import type { ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
+import type { Representations } from "#representations.ts";
+
+export interface ListOptions {
+	readonly arrayKey?: string | undefined;
+	readonly beforeRequest?: (resource: string) => Effect.Effect<void, ServiceUnavailable>;
+	readonly onDecodeError?: "fail" | "skip" | undefined;
+	readonly responseByteLimit?: number | undefined;
+}
+
+export function decodedPages<TSchema extends Schema.Constraint>(
+	client: Representations,
+	path: string,
+	schema: TSchema,
+	options: ListOptions | number = {},
+) {
+	const settings = typeof options === "number" ? { responseByteLimit: options } : options;
+	const decode = Schema.decodeUnknownEffect(schema);
+	return Stream.unwrap(client.list(path, settings.beforeRequest, settings.responseByteLimit)).pipe(
+		Stream.mapEffect((page) =>
+			Effect.gen(function* () {
+				const body = yield* page.decode(Schema.Unknown);
+				const source =
+					settings.arrayKey === undefined
+						? body
+						: (yield* Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown))(body))[settings.arrayKey];
+				const values = yield* Schema.decodeUnknownEffect(Schema.Array(Schema.Unknown))(source);
+				const decoded = yield* Effect.forEach(values, (value) =>
+					decode(value).pipe(
+						Effect.map(Option.some),
+						Effect.catchTag("SchemaError", (error) => (settings.onDecodeError === "skip" ? Effect.succeed(Option.none()) : Effect.fail(error))),
+					),
+				);
+				const items = decoded.flatMap(Option.toArray);
+				return { hasNext: page.hasNext, items, skipped: values.length - items.length };
+			}),
+		),
+	);
+}

package/src/repositoryReads.ts

@@ -0,0 +1,61 @@
+import { Effect } from "effect";
+import { Commit, CommitDetail, Comparison, GitTree } from "#gitSchemas.ts";
+import { decodedPages, type ListOptions } from "#pagedLists.ts";
+import { CollaboratorPermission, Issue, PullRequestFile, User } from "#repositorySchemas.ts";
+import type { Representations } from "#representations.ts";
+
+export interface RepositoryListOptions extends ListOptions {
+	readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
+}
+
+export function repositoryReads(client: Representations) {
+	function repository(owner: string, repo: string) {
+		return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+	}
+	function pathWithQuery(path: string, options?: RepositoryListOptions) {
+		const query = new URLSearchParams({ "per_page": "100" });
+		for (const [key, value] of Object.entries(options?.query ?? {})) {
+			if (value !== undefined) {
+				query.set(key, String(value));
+			}
+		}
+		return `${path}?${query}`;
+	}
+	return {
+		compareCommits: (owner: string, repo: string, base: string, head: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`, byteLimit), (page) =>
+				page.decode(Comparison),
+			),
+		getCollaboratorPermission: (owner: string, repo: string, username: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/collaborators/${encodeURIComponent(username)}/permission`, byteLimit), (page) =>
+				page.decode(CollaboratorPermission),
+			),
+		getCommit: (owner: string, repo: string, ref: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/commits/${encodeURIComponent(ref)}`, byteLimit), (page) => page.decode(CommitDetail)),
+		getIssue: (owner: string, repo: string, number: number, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/issues/${number}`, byteLimit), (page) => page.decode(Issue)),
+		getTree: (
+			owner: string,
+			repo: string,
+			sha: string,
+			options?: { readonly recursive?: boolean; readonly responseByteLimit?: number | undefined },
+		) =>
+			Effect.flatMap(
+				client.read(
+					`${repository(owner, repo)}/git/trees/${encodeURIComponent(sha)}${options?.recursive ? "?recursive=1" : ""}`,
+					options?.responseByteLimit,
+				),
+				(page) => page.decode(GitTree),
+			),
+		getUser: (username?: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(username === undefined ? "/user" : `/users/${encodeURIComponent(username)}`, byteLimit), (page) =>
+				page.decode(User),
+			),
+		listCommits: (owner: string, repo: string, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/commits`, options), Commit, options)),
+		listIssues: (owner: string, repo: string, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/issues`, options), Issue, options)),
+		listPullRequestFiles: (owner: string, repo: string, number: number, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/pulls/${number}/files`, options), PullRequestFile, options)),
+	};
+}