runtime-resolver 0.3.12 → 0.3.14

package/layers/DenoResolverLive.js

@@ -0,0 +1,84 @@
+import { DenoReleaseCache } from "../services/DenoReleaseCache.js";
+import { VersionNotFoundError } from "../errors/VersionNotFoundError.js";
+import { DenoResolver } from "../services/DenoResolver.js";
+import { Effect, Layer } from "effect";
+import { SemVer } from "semver-effect";
+
+//#region src/layers/DenoResolverLive.ts
+/**
+* Provides the {@link DenoResolver} service backed by a {@link DenoReleaseCache}.
+*
+* This layer composes with any of the three Deno cache strategy layers to form
+* a complete resolver stack. It implements semver range filtering and increment
+* grouping (latest per major, latest per minor, or all patch versions) using
+* the releases already loaded into the cache.
+*
+* @example
+* ```ts
+* import { DenoResolverLive, AutoDenoCacheLive, DenoVersionFetcherLive, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+* import { DenoResolver } from "runtime-resolver";
+* import { Effect, Layer } from "effect";
+*
+* const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+* const CacheLayer = AutoDenoCacheLive.pipe(Layer.provide(DenoVersionFetcherLive.pipe(Layer.provide(GitHubLayer))));
+* const ResolverLayer = DenoResolverLive.pipe(Layer.provide(CacheLayer));
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* DenoResolver;
+*   const result = yield* resolver.resolve({ semverRange: "^2.0.0" });
+*   console.log(result.latest);
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+* ```
+*
+* @see {@link DenoResolver}
+* @see {@link DenoReleaseCache}
+* @see {@link AutoDenoCacheLive}
+* @see {@link FreshDenoCacheLive}
+* @see {@link OfflineDenoCacheLive}
+* @public
+*/
+const DenoResolverLive = Layer.effect(DenoResolver, Effect.gen(function* () {
+	const cache = yield* DenoReleaseCache;
+	return { resolve: (options) => Effect.gen(function* () {
+		const semverRange = options?.semverRange ?? "*";
+		const increments = options?.increments ?? "latest";
+		const matching = yield* cache.filter(semverRange).pipe(Effect.catchAll(() => Effect.succeed([])));
+		let resultReleases;
+		if (increments === "latest") {
+			const groups = /* @__PURE__ */ new Map();
+			for (const r of matching) {
+				const existing = groups.get(r.version.major);
+				if (!existing || SemVer.gt(r.version, existing.version)) groups.set(r.version.major, r);
+			}
+			resultReleases = [...groups.values()];
+		} else if (increments === "minor") {
+			const groups = /* @__PURE__ */ new Map();
+			for (const r of matching) {
+				const key = `${r.version.major}.${r.version.minor}`;
+				const existing = groups.get(key);
+				if (!existing || SemVer.gt(r.version, existing.version)) groups.set(key, r);
+			}
+			resultReleases = [...groups.values()];
+		} else resultReleases = [...matching];
+		if (resultReleases.length === 0) return yield* Effect.fail(new VersionNotFoundError({
+			runtime: "deno",
+			constraint: semverRange,
+			message: `No Deno versions found matching "${semverRange}"`
+		}));
+		const versions = SemVer.rsort(resultReleases.map((r) => r.version)).map((v) => v.toString());
+		const latest = versions[0];
+		let resolvedDefault;
+		if (options?.defaultVersion) resolvedDefault = yield* cache.resolve(options.defaultVersion).pipe(Effect.map((r) => r.version.toString()), Effect.catchAll(() => Effect.succeed(void 0)));
+		return {
+			source: "api",
+			versions,
+			latest,
+			...resolvedDefault ? { default: resolvedDefault } : {}
+		};
+	}) };
+}));
+
+//#endregion
+export { DenoResolverLive };

package/layers/DenoVersionFetcherLive.js

@@ -0,0 +1,51 @@
+import { DenoVersionFetcher } from "../services/DenoVersionFetcher.js";
+import { retryOnRateLimit } from "../lib/retry.js";
+import { tryParseSemVer } from "../lib/semver.js";
+import { GitHubClient } from "../services/GitHubClient.js";
+import { Effect, Layer, Option } from "effect";
+
+//#region src/layers/DenoVersionFetcherLive.ts
+/**
+* Provides the {@link DenoVersionFetcher} service using the live GitHub API.
+*
+* Fetches Deno releases from the `denoland/deno` GitHub repository using the
+* provided {@link GitHubClient}. Draft releases and pre-releases are excluded.
+* Tag names are normalized by stripping any leading `v` before parsing as
+* semver.
+*
+* This layer is a required dependency of {@link AutoDenoCacheLive} and
+* {@link FreshDenoCacheLive}. It is not needed by {@link OfflineDenoCacheLive}.
+*
+* @see {@link DenoVersionFetcher}
+* @see {@link GitHubClient}
+* @see {@link AutoDenoCacheLive}
+* @see {@link FreshDenoCacheLive}
+* @public
+*/
+const DenoVersionFetcherLive = Layer.effect(DenoVersionFetcher, Effect.gen(function* () {
+	const client = yield* GitHubClient;
+	return { fetch: () => Effect.gen(function* () {
+		const releases = yield* retryOnRateLimit(client.listReleases("denoland", "deno", {
+			perPage: 100,
+			pages: 3
+		}));
+		const fallbackDate = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+		const parsed = yield* Effect.forEach(releases.filter((r) => !r.draft && !r.prerelease), (release) => {
+			const stripped = release.tag_name.startsWith("v") ? release.tag_name.slice(1) : release.tag_name;
+			return tryParseSemVer(stripped).pipe(Effect.map((opt) => Option.isSome(opt) ? Option.some({
+				version: opt.value,
+				input: {
+					version: stripped,
+					date: release.published_at ?? fallbackDate
+				}
+			}) : Option.none()));
+		}, { concurrency: "unbounded" });
+		return {
+			versions: parsed.flatMap(Option.toArray).map(({ version }) => version),
+			inputs: parsed.flatMap(Option.toArray).map(({ input }) => input)
+		};
+	}) };
+}));
+
+//#endregion
+export { DenoVersionFetcherLive };

package/layers/FreshBunCacheLive.js

@@ -0,0 +1,60 @@
+import { BunRelease } from "../schemas/bun-release.js";
+import { BunReleaseCache } from "../services/BunReleaseCache.js";
+import { BunVersionFetcher } from "../services/BunVersionFetcher.js";
+import { BunReleaseCacheLive } from "./BunReleaseCacheLive.js";
+import { FreshnessError } from "../errors/FreshnessError.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/FreshBunCacheLive.ts
+const freshSetup = Effect.gen(function* () {
+	const cache = yield* BunReleaseCache;
+	const { inputs } = yield* (yield* BunVersionFetcher).fetch().pipe(Effect.catchTags({
+		AuthenticationError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but authentication failed: ${err.message}`
+		})),
+		NetworkError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but network unavailable: ${err.message}`
+		})),
+		ParseError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but parse failed: ${err.message}`
+		})),
+		RateLimitError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but rate limit exceeded: ${err.message}`
+		}))
+	}));
+	const releases = yield* Effect.all(inputs.map((input) => BunRelease.fromInput(input)), { concurrency: "unbounded" }).pipe(Effect.orElseSucceed(() => []));
+	yield* cache.load(releases);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = BunReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link BunReleaseCache} service using the "Fresh" cache strategy.
+*
+* Requires live release data from the GitHub API via {@link BunVersionFetcher}.
+* If the fetch fails for any reason — authentication errors, network errors,
+* parse errors, or rate-limit errors — the layer fails with a `FreshnessError`
+* rather than falling back to stale data.
+*
+* Use this strategy in contexts where working with outdated version data would
+* be incorrect or misleading, such as CI pipelines or tooling that must reflect
+* the true current state of Bun releases.
+*
+* The three Bun cache strategy layers are:
+* - {@link AutoBunCacheLive} — tries API first, falls back to bundled defaults on any error
+* - `FreshBunCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineBunCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link BunReleaseCache}
+* @see {@link AutoBunCacheLive}
+* @see {@link OfflineBunCacheLive}
+* @public
+*/
+const FreshBunCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => freshSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { FreshBunCacheLive };

package/layers/FreshDenoCacheLive.js

@@ -0,0 +1,60 @@
+import { DenoRelease } from "../schemas/deno-release.js";
+import { DenoReleaseCache } from "../services/DenoReleaseCache.js";
+import { DenoVersionFetcher } from "../services/DenoVersionFetcher.js";
+import { DenoReleaseCacheLive } from "./DenoReleaseCacheLive.js";
+import { FreshnessError } from "../errors/FreshnessError.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/FreshDenoCacheLive.ts
+const freshSetup = Effect.gen(function* () {
+	const cache = yield* DenoReleaseCache;
+	const { inputs } = yield* (yield* DenoVersionFetcher).fetch().pipe(Effect.catchTags({
+		AuthenticationError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but authentication failed: ${err.message}`
+		})),
+		NetworkError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but network unavailable: ${err.message}`
+		})),
+		ParseError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but parse failed: ${err.message}`
+		})),
+		RateLimitError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but rate limit exceeded: ${err.message}`
+		}))
+	}));
+	const releases = yield* Effect.all(inputs.map((input) => DenoRelease.fromInput(input)), { concurrency: "unbounded" }).pipe(Effect.orElseSucceed(() => []));
+	yield* cache.load(releases);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = DenoReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link DenoReleaseCache} service using the "Fresh" cache strategy.
+*
+* Requires live release data from the GitHub API via {@link DenoVersionFetcher}.
+* If the fetch fails for any reason — authentication errors, network errors,
+* parse errors, or rate-limit errors — the layer fails with a `FreshnessError`
+* rather than falling back to stale data.
+*
+* Use this strategy in contexts where working with outdated version data would
+* be incorrect or misleading, such as CI pipelines or tooling that must reflect
+* the true current state of Deno releases.
+*
+* The three Deno cache strategy layers are:
+* - {@link AutoDenoCacheLive} — tries API first, falls back to bundled defaults on any error
+* - `FreshDenoCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineDenoCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link DenoReleaseCache}
+* @see {@link AutoDenoCacheLive}
+* @see {@link OfflineDenoCacheLive}
+* @public
+*/
+const FreshDenoCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => freshSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { FreshDenoCacheLive };

package/layers/FreshNodeCacheLive.js

@@ -0,0 +1,55 @@
+import { NodeReleaseCache } from "../services/NodeReleaseCache.js";
+import { NodeScheduleFetcher } from "../services/NodeScheduleFetcher.js";
+import { NodeVersionFetcher } from "../services/NodeVersionFetcher.js";
+import { NodeReleaseCacheLive } from "./NodeReleaseCacheLive.js";
+import { FreshnessError } from "../errors/FreshnessError.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/FreshNodeCacheLive.ts
+const freshSetup = Effect.gen(function* () {
+	const cache = yield* NodeReleaseCache;
+	const versionFetcher = yield* NodeVersionFetcher;
+	const scheduleFetcher = yield* NodeScheduleFetcher;
+	const [fetchResult, scheduleData] = yield* Effect.all([versionFetcher.fetch(), scheduleFetcher.fetch()]).pipe(Effect.catchTags({
+		NetworkError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but network unavailable: ${err.message}`
+		})),
+		ParseError: (err) => Effect.fail(new FreshnessError({
+			strategy: "api",
+			message: `Fresh data required but response could not be parsed: ${err.message}`
+		}))
+	}));
+	yield* cache.updateSchedule(scheduleData);
+	yield* cache.loadFromInputs(fetchResult.inputs);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = NodeReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link NodeReleaseCache} service using the "Fresh" cache strategy.
+*
+* Requires live release data from `nodejs.org/dist/index.json` via
+* {@link NodeVersionFetcher} and the release schedule from the `nodejs/Release`
+* repository via {@link NodeScheduleFetcher}. If either fetch fails — due to
+* network errors or parse errors — the layer fails with a `FreshnessError`
+* rather than falling back to stale data.
+*
+* Use this strategy in contexts where working with outdated version data would
+* be incorrect or misleading, such as CI pipelines or tooling that must reflect
+* the true current state of Node.js releases and LTS schedule.
+*
+* The three Node cache strategy layers are:
+* - {@link AutoNodeCacheLive} — tries API first, falls back to bundled defaults on any error
+* - `FreshNodeCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineNodeCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link NodeReleaseCache}
+* @see {@link AutoNodeCacheLive}
+* @see {@link OfflineNodeCacheLive}
+* @public
+*/
+const FreshNodeCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => freshSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { FreshNodeCacheLive };

package/layers/GitHubAppAuth.js

@@ -0,0 +1,58 @@
+import { OctokitInstance } from "../services/OctokitInstance.js";
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { Effect, Layer } from "effect";
+import { Octokit } from "octokit";
+import { createAppAuth } from "@octokit/auth-app";
+
+//#region src/layers/GitHubAppAuth.ts
+const resolveInstallationId = async (auth, installationId) => {
+	if (installationId) return installationId;
+	const { token: jwt } = await auth({ type: "app" });
+	const response = await fetch("https://api.github.com/app/installations?per_page=100", { headers: {
+		Authorization: `Bearer ${jwt}`,
+		Accept: "application/vnd.github+json"
+	} });
+	if (!response.ok) throw new Error(`Failed to list installations: ${response.status}`);
+	const installations = await response.json();
+	if (installations.length === 0) throw new Error("No installations found for this GitHub App");
+	return installations[0].id;
+};
+/**
+* Provides an {@link OctokitInstance} authenticated as a GitHub App installation.
+*
+* Accepts a {@link GitHubAppAuthConfig} and uses `@octokit/auth-app` to obtain
+* an installation access token. If `installationId` is omitted, the first
+* installation returned by the GitHub API is used automatically (suitable for
+* apps with a single installation). If authentication fails for any reason the
+* layer fails with an `AuthenticationError`.
+*
+* Use this auth method when your integration runs as a GitHub App rather than
+* as an individual user or a CI token.
+*
+* @param config - App credentials and optional installation ID.
+*
+* @see {@link GitHubAppAuthConfig}
+* @see {@link OctokitInstance}
+* @see {@link GitHubAutoAuth}
+* @see {@link GitHubTokenAuth}
+* @public
+*/
+const GitHubAppAuth = (config) => Layer.effect(OctokitInstance, Effect.tryPromise({
+	try: async () => {
+		const auth = createAppAuth({
+			appId: config.appId,
+			privateKey: config.privateKey
+		});
+		return new Octokit({ auth: (await auth({
+			type: "installation",
+			installationId: await resolveInstallationId(auth, config.installationId)
+		})).token });
+	},
+	catch: (error) => new AuthenticationError({
+		method: "app",
+		message: error instanceof Error ? error.message : String(error)
+	})
+}));
+
+//#endregion
+export { GitHubAppAuth };

package/layers/GitHubAutoAuth.js

@@ -0,0 +1,70 @@
+import { OctokitInstance } from "../services/OctokitInstance.js";
+import { GitHubAppAuth } from "./GitHubAppAuth.js";
+import { Effect, Layer } from "effect";
+import { Octokit } from "octokit";
+
+//#region src/layers/GitHubAutoAuth.ts
+/**
+* Provides an {@link OctokitInstance} by auto-detecting the available
+* authentication credentials from environment variables at layer construction
+* time.
+*
+* Credentials are evaluated in the following priority order:
+* 1. **GitHub App** — when both `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`
+*    are set, authenticates as a GitHub App installation via {@link GitHubAppAuth}.
+*    `GITHUB_APP_INSTALLATION_ID` is optional; if absent the first installation
+*    is used automatically.
+* 2. **Personal Access Token** — when `GITHUB_PERSONAL_ACCESS_TOKEN` is set,
+*    authenticates with that token.
+* 3. **`GITHUB_TOKEN`** — when `GITHUB_TOKEN` is set (e.g., the default token
+*    injected in GitHub Actions), authenticates with that token.
+* 4. **Unauthenticated** — falls back to an unauthenticated Octokit instance
+*    when no credentials are found (lower rate limits apply).
+*
+* If both App and token credentials are present, App auth takes precedence and
+* a warning is logged. This layer fails with `AuthenticationError` only when
+* App credentials are present but the App authentication itself fails.
+*
+* Use this layer as the default auth strategy in most applications. Switch to
+* {@link GitHubTokenAuth} or {@link GitHubAppAuth} when you need explicit control
+* over which credential source is used.
+*
+* @example
+* ```ts
+* import { GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+* import { Layer } from "effect";
+*
+* const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+* ```
+*
+* @see {@link OctokitInstance}
+* @see {@link GitHubTokenAuth}
+* @see {@link GitHubAppAuth}
+* @public
+*/
+const GitHubAutoAuth = Layer.effect(OctokitInstance, Effect.gen(function* () {
+	const appId = process.env.GITHUB_APP_ID;
+	const privateKey = process.env.GITHUB_APP_PRIVATE_KEY;
+	const installationId = process.env.GITHUB_APP_INSTALLATION_ID;
+	const pat = process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+	const token = process.env.GITHUB_TOKEN;
+	const hasApp = appId && privateKey;
+	if (hasApp && (pat || token)) {
+		const tokenSource = pat ? "GITHUB_PERSONAL_ACCESS_TOKEN" : "GITHUB_TOKEN";
+		yield* Effect.logWarning(`Multiple GitHub credential sources found. Using GitHub App authentication (from GITHUB_APP_ID). Ignoring ${tokenSource}.`);
+	}
+	if (hasApp) {
+		const appLayer = GitHubAppAuth({
+			appId,
+			privateKey,
+			...installationId ? { installationId: Number(installationId) } : {}
+		});
+		return yield* Effect.provide(OctokitInstance, appLayer);
+	}
+	if (pat) return new Octokit({ auth: pat });
+	if (token) return new Octokit({ auth: token });
+	return new Octokit();
+}));
+
+//#endregion
+export { GitHubAutoAuth };

package/layers/GitHubClientLive.js

@@ -0,0 +1,130 @@
+import { GitHubClient } from "../services/GitHubClient.js";
+import { OctokitInstance } from "../services/OctokitInstance.js";
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { NetworkError } from "../errors/NetworkError.js";
+import { ParseError } from "../errors/ParseError.js";
+import { RateLimitError } from "../errors/RateLimitError.js";
+import { GitHubReleaseList, GitHubTagList } from "../schemas/github.js";
+import { Effect, Layer, Schema } from "effect";
+
+//#region src/layers/GitHubClientLive.ts
+const mapOctokitError = (error, url) => {
+	const err = error;
+	if (err.status === 401) return new AuthenticationError({
+		method: "token",
+		message: `GitHub API authentication failed for ${url}`
+	});
+	if (err.status === 403 || err.status === 429) {
+		const headers = err.response?.headers ?? {};
+		const retryAfterStr = headers["retry-after"];
+		return new RateLimitError({
+			...retryAfterStr ? { retryAfter: Number.parseInt(retryAfterStr, 10) } : {},
+			limit: headers["x-ratelimit-limit"] ? Number.parseInt(headers["x-ratelimit-limit"], 10) : 0,
+			remaining: headers["x-ratelimit-remaining"] ? Number.parseInt(headers["x-ratelimit-remaining"], 10) : 0,
+			message: `GitHub API rate limit exceeded for ${url}`
+		});
+	}
+	return new NetworkError({
+		url,
+		...err.status !== void 0 ? { status: err.status } : {},
+		message: error instanceof Error ? error.message : String(error)
+	});
+};
+const decodeTagList = Schema.decodeUnknown(GitHubTagList);
+const decodeReleaseList = Schema.decodeUnknown(GitHubReleaseList);
+/**
+* Provides the {@link GitHubClient} service backed by an {@link OctokitInstance}.
+*
+* This layer wraps an Octokit instance and exposes a typed, Effect-native API
+* for listing GitHub releases, listing tags, and fetching arbitrary JSON from
+* URLs. HTTP errors are mapped to typed domain errors (`NetworkError`,
+* `RateLimitError`, `AuthenticationError`) so they can be handled precisely in
+* calling code.
+*
+* Pair this layer with one of the auth layers to form a complete GitHub
+* integration stack:
+* - {@link GitHubAutoAuth} — auto-detects auth from environment variables
+* - {@link GitHubTokenAuth} — authenticates using a personal access token
+* - {@link GitHubAppAuth} — authenticates as a GitHub App installation
+*
+* @see {@link GitHubClient}
+* @see {@link OctokitInstance}
+* @see {@link GitHubAutoAuth}
+* @public
+*/
+const GitHubClientLive = Layer.effect(GitHubClient, Effect.gen(function* () {
+	const octokit = yield* OctokitInstance;
+	return {
+		listTags: (owner, repo, options) => Effect.gen(function* () {
+			const perPage = options?.perPage ?? 100;
+			const maxPages = options?.pages ?? Number.POSITIVE_INFINITY;
+			const allTags = [];
+			for (let page = 1; page <= maxPages; page++) {
+				const response = yield* Effect.tryPromise({
+					try: () => octokit.rest.repos.listTags({
+						owner,
+						repo,
+						per_page: perPage,
+						page
+					}),
+					catch: (error) => mapOctokitError(error, `repos/${owner}/${repo}/tags`)
+				});
+				const tags = yield* decodeTagList(response.data).pipe(Effect.mapError((e) => new ParseError({
+					source: `repos/${owner}/${repo}/tags`,
+					message: `Schema validation failed: ${e.message}`
+				})));
+				allTags.push(...tags);
+				if (response.data.length < perPage) break;
+			}
+			return allTags;
+		}),
+		listReleases: (owner, repo, options) => Effect.gen(function* () {
+			const perPage = options?.perPage ?? 100;
+			const maxPages = options?.pages ?? Number.POSITIVE_INFINITY;
+			const allReleases = [];
+			for (let page = 1; page <= maxPages; page++) {
+				const response = yield* Effect.tryPromise({
+					try: () => octokit.rest.repos.listReleases({
+						owner,
+						repo,
+						per_page: perPage,
+						page
+					}),
+					catch: (error) => mapOctokitError(error, `repos/${owner}/${repo}/releases`)
+				});
+				const releases = yield* decodeReleaseList(response.data).pipe(Effect.mapError((e) => new ParseError({
+					source: `repos/${owner}/${repo}/releases`,
+					message: `Schema validation failed: ${e.message}`
+				})));
+				allReleases.push(...releases);
+				if (response.data.length < perPage) break;
+			}
+			return allReleases;
+		}),
+		getJson: (url, schema) => Effect.gen(function* () {
+			const response = yield* Effect.tryPromise({
+				try: () => fetch(url),
+				catch: (error) => new NetworkError({
+					url,
+					message: error instanceof Error ? error.message : String(error)
+				})
+			});
+			if (!response.ok) yield* Effect.fail(new NetworkError({
+				url,
+				status: response.status,
+				message: `HTTP ${response.status}: ${response.statusText}`
+			}));
+			const json = yield* Effect.tryPromise({
+				try: () => response.json(),
+				catch: () => new ParseError({
+					source: url,
+					message: "Failed to parse JSON response"
+				})
+			});
+			return yield* schema.decode(json);
+		})
+	};
+}));
+
+//#endregion
+export { GitHubClientLive };

package/layers/GitHubTokenAuth.js

@@ -0,0 +1,50 @@
+import { OctokitInstance } from "../services/OctokitInstance.js";
+import { Effect, Layer } from "effect";
+import { Octokit } from "octokit";
+
+//#region src/layers/GitHubTokenAuth.ts
+const resolveToken = Effect.sync(() => process.env.GITHUB_PERSONAL_ACCESS_TOKEN || process.env.GITHUB_TOKEN || "");
+/**
+* Provides an {@link OctokitInstance} authenticated with a GitHub personal
+* access token read from the environment at layer construction time.
+*
+* The token is resolved by checking, in order:
+* 1. `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable
+* 2. `GITHUB_TOKEN` environment variable
+*
+* If neither variable is set the layer constructs an unauthenticated Octokit
+* instance (lower rate limits apply). This layer never fails.
+*
+* Use {@link GitHubTokenAuthFromToken} when you have the token value available
+* programmatically at construction time.
+*
+* @see {@link OctokitInstance}
+* @see {@link GitHubTokenAuthFromToken}
+* @see {@link GitHubAutoAuth}
+* @see {@link GitHubAppAuth}
+* @public
+*/
+const GitHubTokenAuth = Layer.effect(OctokitInstance, Effect.gen(function* () {
+	const token = yield* resolveToken;
+	return new Octokit(token ? { auth: token } : {});
+}));
+/**
+* Provides an {@link OctokitInstance} authenticated with the given personal
+* access token string.
+*
+* Use this variant when the token is available as a value in your program
+* rather than read from an environment variable. The resulting layer never
+* fails.
+*
+* @param token - A GitHub personal access token string.
+*
+* @see {@link OctokitInstance}
+* @see {@link GitHubTokenAuth}
+* @see {@link GitHubAutoAuth}
+* @see {@link GitHubAppAuth}
+* @public
+*/
+const GitHubTokenAuthFromToken = (token) => Layer.succeed(OctokitInstance, new Octokit({ auth: token }));
+
+//#endregion
+export { GitHubTokenAuth, GitHubTokenAuthFromToken };