@effected/github 0.1.0

package/Repo.js

@@ -0,0 +1,107 @@
+import { Config, Context, Effect, Layer, Result, Schema } from "effect";
+
+//#region src/Repo.ts
+/**
+* A repository slug was not `owner/repo`.
+*
+* @public
+*/
+var InvalidRepoRefError = class extends Schema.TaggedErrorClass()("InvalidRepoRefError", { 
+/** What was handed in. */
+input: Schema.String }) {
+	get message() {
+		return `not an owner/repo slug: ${JSON.stringify(this.input)}`;
+	}
+};
+/**
+* Which repository an operation acts on.
+*
+* @public
+*/
+var RepoRef = class RepoRef extends Schema.Class("RepoRef")({
+	/** The user or organization. */
+	owner: Schema.NonEmptyString,
+	/** The repository name, without the owner. */
+	repo: Schema.NonEmptyString
+}) {
+	/**
+	* Parse `"owner/repo"`, synchronously.
+	*
+	* @remarks
+	* The sync `Result` primitive; {@link RepoRef.parse} is the `Effect` form over
+	* it. `make` is reserved by the class factory for the validated field
+	* constructor, which is why string parsing is named rather than overloaded.
+	*/
+	static parseResult(slug) {
+		const parts = slug.split("/");
+		const [owner, repo] = parts;
+		if (parts.length !== 2 || owner === void 0 || repo === void 0 || owner === "" || repo === "") return Result.fail(new InvalidRepoRefError({ input: slug }));
+		return Result.succeed(RepoRef.make({
+			owner,
+			repo
+		}));
+	}
+	/** Parse `"owner/repo"`. */
+	static parse = Effect.fn("RepoRef.parse")((slug) => Effect.fromResult(RepoRef.parseResult(slug)));
+	/** `"owner/repo"`. */
+	get slug() {
+		return `${this.owner}/${this.repo}`;
+	}
+};
+/**
+* The repository the surrounding program acts on.
+*
+* @remarks
+* Every resource service takes this in its `R` and **no method takes an
+* `{ owner, repo }` argument**, which is what makes a read like
+* `GitHubRepository.defaultBranch` a single expression instead of a preamble.
+*
+* The package this replaces read `process.env.GITHUB_REPOSITORY` in three
+* places — inside the client, inside the App layer, and transitively in every
+* caller of `client.repo` — which is most of what coupled a GitHub API client to
+* the GitHub Actions runtime. Here the coordinate is a value, the env-driven way
+* to get one is a layer variant **named for being env-driven**, and a program
+* that acts on several repositories uses {@link Repo.provide}:
+*
+* @example
+* ```ts
+* import { Repo } from "@effected/github";
+* import { Effect } from "effect";
+*
+* declare const syncOne: Effect.Effect<void, never, Repo>;
+* declare const targets: ReadonlyArray<Repo["Service"]>;
+*
+* const syncAll = Effect.forEach(targets, (target) => syncOne.pipe(Repo.provide(target)), {
+*   concurrency: 4,
+* });
+* ```
+*
+* **A deliberate exception to "no non-effectful members on a service shape."**
+* This shape is entirely one immutable value: there is nothing to leave
+* unimplemented, so `Layer.mock` has nothing to degrade and `Layer.succeed` is
+* the correct double. The rule exists to stop a sync member from quietly
+* degrading a *mixed* shape's partial mock. The boundary to hold: the moment a
+* method appears here, this is a service again and the rule applies.
+*
+* @public
+*/
+var Repo = class Repo extends Context.Service()("@effected/github/Repo") {
+	/** The repository, as a value you already have. */
+	static layer = (ref) => Layer.succeed(Repo, ref);
+	/** The repository, from an `"owner/repo"` slug. */
+	static layerFromSlug = (slug) => Layer.effect(Repo, RepoRef.parse(slug));
+	/**
+	* The repository from configuration, `GITHUB_REPOSITORY` by default.
+	*
+	* @remarks
+	* The one env-driven variant, read through the ambient `ConfigProvider` rather
+	* than `process.env` — so a test provides a provider instead of mutating the
+	* environment, and a consumer outside Actions can source it however it likes.
+	*/
+	static layerFromConfig = (options = {}) => Layer.effect(Repo, Effect.flatMap(Config.string(options.name ?? "GITHUB_REPOSITORY"), (slug) => RepoRef.parse(slug)));
+	/** Run `effect` against a different repository. */
+	static provide = (ref) => (effect) => Effect.provideService(effect, Repo, ref);
+};
+
+//#endregion
+export { InvalidRepoRefError, Repo, RepoRef };

package/Resilience.js

@@ -0,0 +1,146 @@
+import { Duration, Effect, Random, Schedule, Schema } from "effect";
+
+//#region src/Resilience.ts
+/**
+* What GitHub's rate-limit headers said on the most recent REST response.
+*
+* @remarks
+* Every REST response carries `x-ratelimit-remaining`, `x-ratelimit-limit` and
+* `x-ratelimit-reset`; the client parses them into this and keeps the latest
+* one. Read it through the client's `rateLimit` member when you want to pace
+* yourself — **nothing in this package throttles on your behalf.**
+*
+* The package this replaces coupled the writer and the reader through an
+* optional shared `Ref` service that both resolved with `Effect.serviceOption`,
+* so an application that forgot to provide it got two private cells and a
+* silently dead feature. Here the cell lives inside the client layer that writes
+* it, and this is the only way to read it.
+*
+* @public
+*/
+var RateLimitSnapshot = class extends Schema.Class("RateLimitSnapshot")({
+	/** Requests left in the current window. */
+	remaining: Schema.Int,
+	/** The window's ceiling. */
+	limit: Schema.Int,
+	/** When the window resets, as epoch **seconds** — GitHub's own unit. */
+	resetEpochSeconds: Schema.Int
+}) {
+	/** Milliseconds until the window resets, relative to `nowMillis`, floored at zero. */
+	millisUntilReset(nowMillis) {
+		return Math.max(0, this.resetEpochSeconds * 1e3 - nowMillis);
+	}
+	/** True when the budget is spent. */
+	get isExhausted() {
+		return this.remaining <= 0;
+	}
+};
+/**
+* How the client retries a failed request.
+*
+* @remarks
+* There is exactly **one** retry policy in this package, and it is wired into
+* the client so every resource inherits it and no resource carries its own. The
+* package this replaces shipped four mutually inconsistent policies — a
+* hand-rolled recursive loop, a second exported `Schedule` that ignored
+* server-advised delays, a per-operation branch retry layered on top of the
+* client's, and a rate-limiter retry with no predicate at all, which cheerfully
+* retried permission denials — and consumers added two more on top.
+*
+* Only failures that report `retryable` are retried, which for `GitHubError` means a transport failure or a rate limit. A 404, a
+* validation rejection and an authorization failure fail on the first attempt.
+*
+* @public
+*/
+var RetryPolicy = class RetryPolicy extends Schema.Class("RetryPolicy")({
+	/** Retries after the first attempt. `0` disables retrying. */
+	maxRetries: Schema.Int.check(Schema.isBetween({
+		minimum: 0,
+		maximum: 10
+	})),
+	/** The first backoff step; doubles per attempt. */
+	baseDelay: Schema.DurationFromMillis,
+	/** The computed backoff never exceeds this. */
+	maxDelay: Schema.DurationFromMillis,
+	/** Prefer GitHub's `retry-after` / rate-limit reset over the computed backoff. */
+	respectRetryAfter: Schema.Boolean,
+	/**
+	* Refuse to wait longer than this for a server-advised delay.
+	*
+	* @remarks
+	* A primary rate-limit window can be three quarters of an hour out. Sleeping
+	* through it converts a failure into a hang, so past this ceiling the error
+	* is re-failed immediately and the caller decides what to do.
+	*/
+	maxServerAdvisedDelay: Schema.DurationFromMillis
+}) {
+	/** Four retries, 1s base, 30s cap, honoring server-advised delays up to a minute. */
+	static default = RetryPolicy.make({
+		maxRetries: 4,
+		baseDelay: Duration.seconds(1),
+		maxDelay: Duration.seconds(30),
+		respectRetryAfter: true,
+		maxServerAdvisedDelay: Duration.seconds(60)
+	});
+	/** Retries nothing; every failure surfaces on the first attempt. */
+	static none = RetryPolicy.make({
+		maxRetries: 0,
+		baseDelay: Duration.zero,
+		maxDelay: Duration.zero,
+		respectRetryAfter: false,
+		maxServerAdvisedDelay: Duration.zero
+	});
+	/**
+	* Whether this policy would retry `failure` at all, ignoring attempt counts.
+	*
+	* @remarks
+	* Pure and total, so the classification is testable without a clock, a
+	* runtime or a schedule.
+	*/
+	retries(failure) {
+		if (this.maxRetries === 0 || !failure.retryable) return false;
+		const advised = this.advisedMillis(failure);
+		return advised === void 0 || advised <= Duration.toMillis(this.maxServerAdvisedDelay);
+	}
+	/**
+	* The delay before the given attempt, for a failure and a `[0, 1)` draw.
+	*
+	* @remarks
+	* A server-advised delay wins outright when `respectRetryAfter`
+	* is set: GitHub knows when its window reopens and a computed backoff can only
+	* guess. Otherwise this is **full jitter** — a uniform draw from
+	* `[0, min(baseDelay * 2^(attempt-1), maxDelay)]` — which spreads a fleet of
+	* retrying callers rather than synchronizing them into a second herd.
+	*
+	* `random` is a parameter so the arithmetic is checkable without stubbing a
+	* generator.
+	*/
+	delayFor(failure, attempt, random) {
+		const advised = this.advisedMillis(failure);
+		if (advised !== void 0) return Duration.millis(advised);
+		const uncapped = Duration.toMillis(this.baseDelay) * 2 ** Math.max(0, attempt - 1);
+		const capped = Math.min(uncapped, Duration.toMillis(this.maxDelay));
+		return Duration.millis(Math.floor(capped * random));
+	}
+	/** The server-advised delay, when there is one and this policy honors it. */
+	advisedMillis(failure) {
+		return this.respectRetryAfter ? failure.retryAfterMillis : void 0;
+	}
+	/**
+	* The `Schedule` this policy compiles to, for `Effect.retry`.
+	*
+	* @remarks
+	* Built on `Schedule.modifyDelay`, whose callback receives the schedule's
+	* `Metadata` — including the **input that failed**. That is what makes a
+	* header-driven policy expressible as a `Schedule` at all: the delay is a
+	* function of the error, not only of the attempt number. Not knowing this was
+	* available is why the package this replaces hand-rolled a recursive retry
+	* loop instead of using `Effect.retry`.
+	*/
+	schedule() {
+		return Schedule.forever.pipe(Schedule.modifyDelay(({ input, attempt }) => Effect.map(Random.next, (random) => this.delayFor(input, attempt, random))), Schedule.while(({ input, attempt }) => attempt <= this.maxRetries && this.retries(input)));
+	}
+};
+
+//#endregion
+export { RateLimitSnapshot, RetryPolicy };

package/Rest.js

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+
+//#region src/Rest.ts
+/**
+* How far a paginated read should go.
+*
+* @remarks
+* Both fields are honored by every paginating method in this package. The
+* package it replaces accepted them on the client and then passed `{}` at six
+* of its eight call sites, so callers silently got 100-item pages and an
+* unbounded walk with no way to say otherwise.
+*
+* `perPage` is **validated, not clamped**: GitHub caps a page at 100 and
+* silently ignores anything larger, so a caller asking for 250 has a bug whose
+* arithmetic is already wrong. Failing at the boundary is cheaper than
+* discovering it in production.
+*
+* @public
+*/
+var PageOptions = class PageOptions extends Schema.Class("PageOptions")({
+	/** Items requested per page. GitHub's ceiling is 100. */
+	perPage: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 100
+	}))),
+	/** Stop after this many pages. Absent means "until GitHub stops". */
+	maxPages: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0)))
+}) {
+	/** Reads every page, 100 at a time — GitHub's maximum page size. */
+	static all = PageOptions.make({ perPage: 100 });
+	/**
+	* Reads at most one page of `perPage` items.
+	*
+	* @remarks
+	* The shape a "is there any?" or "give me the newest few" read wants, where
+	* walking every page is waste.
+	*/
+	static first(perPage) {
+		return PageOptions.make({
+			perPage,
+			maxPages: 1
+		});
+	}
+};
+
+//#endregion
+export { PageOptions };

package/TokenPermissions.js

@@ -0,0 +1,188 @@
+import { Effect, Schema } from "effect";
+
+//#region src/TokenPermissions.ts
+/**
+* How much access a permission grants.
+*
+* @public
+*/
+const PermissionLevel = Schema.Literals([
+	"read",
+	"write",
+	"admin"
+]);
+/** `read` < `write` < `admin`. */
+const RANK = {
+	read: 1,
+	write: 2,
+	admin: 3
+};
+/**
+* A permission the token does not have enough of.
+*
+* @public
+*/
+var PermissionGap = class extends Schema.Class("PermissionGap")({
+	/** The permission's name, e.g. `"contents"`. */
+	permission: Schema.String,
+	/** What was asked for. */
+	required: PermissionLevel,
+	/** What the token has, when it has any at all. */
+	granted: Schema.optionalKey(PermissionLevel)
+}) {};
+/**
+* A permission the token has and did not need.
+*
+* @public
+*/
+var ExtraPermission = class extends Schema.Class("ExtraPermission")({
+	permission: Schema.String,
+	granted: PermissionLevel,
+	/** What was asked for, when anything was. */
+	required: Schema.optionalKey(PermissionLevel)
+}) {};
+/**
+* What comparing a token's permissions against a requirement found.
+*
+* @public
+*/
+var PermissionResult = class extends Schema.Class("PermissionResult")({
+	/** Permissions that are missing or too weak. */
+	missing: Schema.Array(PermissionGap),
+	/** Permissions granted beyond what was asked for. */
+	extra: Schema.Array(ExtraPermission)
+}) {
+	/** Nothing missing. */
+	get satisfied() {
+		return this.missing.length === 0;
+	}
+	/** Nothing missing and nothing spare. */
+	get exact() {
+		return this.satisfied && this.extra.length === 0;
+	}
+};
+/**
+* A token asked for access it does not have, or has access it did not ask for.
+*
+* @public
+*/
+var TokenPermissionError = class extends Schema.TaggedErrorClass()("TokenPermissionError", {
+	/** Which assertion failed. */
+	kind: Schema.Literals(["insufficient", "excess"]),
+	/** The comparison that produced it. */
+	result: PermissionResult
+}) {
+	get message() {
+		return this.kind === "insufficient" ? `token is missing ${this.result.missing.map((gap) => `${gap.permission}:${gap.required}`).join(", ")}` : `token has unrequested ${this.result.extra.map((extra) => `${extra.permission}:${extra.granted}`).join(", ")}`;
+	}
+};
+/**
+* The permissions a token was granted, and what they satisfy.
+*
+* @remarks
+* **A pure class, not a service.** The version this replaces was a
+* `Context.Service` whose live layer was a `Layer.succeed` with zero octokit
+* calls and an empty `R` — a `read < write < admin` comparator behind a service
+* boundary that bought nothing. It cost something, though: its test double
+* reimplemented the entire ranking and every assertion branch, making it the
+* heaviest of the thirty-eight doubles in the package.
+*
+* Here there is no service, no layer and no double: a caller holds the
+* permissions GitHub already gave it (`InstallationToken.permissions`) and
+* compares them. The only `Effect`s are the two assertions, and they exist only
+* because failing typed is more useful than returning a boolean.
+*
+* @example
+* ```ts
+* import { TokenPermissions } from "@effected/github";
+* import { Effect } from "effect";
+*
+* declare const permissions: Record<string, string>;
+*
+* const check = Effect.gen(function* () {
+*   const granted = TokenPermissions.fromGitHub(permissions);
+*   yield* granted.assertSufficient({ contents: "write", pull_requests: "write" });
+* });
+* ```
+*
+* @public
+*/
+var TokenPermissions = class TokenPermissions extends Schema.Class("TokenPermissions")({ 
+/** Permission name to level. */
+granted: Schema.Record(Schema.String, PermissionLevel) }) {
+	/**
+	* Read GitHub's permission map, ignoring anything unrecognized.
+	*
+	* @remarks
+	* GitHub adds permission levels over time; a token carrying one this package
+	* does not know about is not a reason to fail a comparison about a different
+	* permission entirely.
+	*/
+	static fromGitHub(permissions) {
+		const granted = {};
+		for (const [name, level] of Object.entries(permissions)) if (level === "read" || level === "write" || level === "admin") granted[name] = level;
+		return TokenPermissions.make({ granted });
+	}
+	/** Compare against a requirement. Pure and total. */
+	compare(required) {
+		const missing = [];
+		const extra = [];
+		for (const [permission, want] of Object.entries(required)) {
+			const have = this.granted[permission];
+			if (have === void 0) missing.push(PermissionGap.make({
+				permission,
+				required: want
+			}));
+			else if (RANK[have] < RANK[want]) missing.push(PermissionGap.make({
+				permission,
+				required: want,
+				granted: have
+			}));
+		}
+		for (const [permission, have] of Object.entries(this.granted)) {
+			const want = required[permission];
+			if (want === void 0) extra.push(ExtraPermission.make({
+				permission,
+				granted: have
+			}));
+			else if (RANK[have] > RANK[want]) extra.push(ExtraPermission.make({
+				permission,
+				granted: have,
+				required: want
+			}));
+		}
+		return PermissionResult.make({
+			missing,
+			extra
+		});
+	}
+	/** Fail unless every required permission is held at least at the level asked for. */
+	assertSufficient(required) {
+		const result = this.compare(required);
+		return result.satisfied ? Effect.void : Effect.fail(new TokenPermissionError({
+			kind: "insufficient",
+			result
+		}));
+	}
+	/**
+	* Fail unless the token holds exactly what was asked for.
+	*
+	* @remarks
+	* For the workflow that wants a least-privilege token and treats a broader
+	* one as a misconfiguration worth stopping for.
+	*/
+	assertExact(required) {
+		const result = this.compare(required);
+		if (!result.satisfied) return Effect.fail(new TokenPermissionError({
+			kind: "insufficient",
+			result
+		}));
+		return result.extra.length === 0 ? Effect.void : Effect.fail(new TokenPermissionError({
+			kind: "excess",
+			result
+		}));
+	}
+};
+
+//#endregion
+export { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, TokenPermissionError, TokenPermissions };

package/WorkflowDispatch.js

@@ -0,0 +1,124 @@
+import { GitHubError } from "./GitHubError.js";
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { PageOptions } from "./Rest.js";
+import { Clock, Context, Duration, Effect, Layer, Option, Schedule, Schema } from "effect";
+
+//#region src/WorkflowDispatch.ts
+/**
+* Where a workflow run has got to.
+*
+* @public
+*/
+var WorkflowRunStatus = class extends Schema.Class("WorkflowRunStatus")({
+	id: Schema.Int,
+	/** `queued`, `in_progress`, `completed`, … */
+	status: Schema.String,
+	/** Set once `status` is `completed`. */
+	conclusion: Schema.optionalKey(Schema.String),
+	url: Schema.String
+}) {
+	/** Has the run finished, whatever the outcome? */
+	get isDone() {
+		return this.status === "completed";
+	}
+};
+const DEFAULT_INTERVAL = Duration.seconds(10);
+const DEFAULT_TIMEOUT = Duration.minutes(5);
+/**
+* Workflow dispatch.
+*
+* @public
+*/
+var WorkflowDispatch = class WorkflowDispatch extends Context.Service()("@effected/github/WorkflowDispatch") {
+	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		dispatch: overrides.dispatch ?? (() => unstubbed("dispatch")),
+		runStatus: overrides.runStatus ?? (() => unstubbed("runStatus")),
+		dispatchAndWait: overrides.dispatchAndWait ?? (() => unstubbed("dispatchAndWait"))
+	});
+	/** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(WorkflowDispatch, WorkflowDispatch.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`WorkflowDispatch.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const statusOf = (raw) => WorkflowRunStatus.make({
+	id: raw.id,
+	status: raw.status ?? "unknown",
+	...raw.conclusion != null ? { conclusion: raw.conclusion } : {},
+	url: raw.html_url
+});
+const make = (client) => {
+	const dispatch = Effect.fn("WorkflowDispatch.dispatch")(function* (workflow, ref, inputs) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			workflow,
+			ref
+		});
+		yield* client.request("POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches", {
+			owner,
+			repo,
+			workflow_id: workflow,
+			ref,
+			...inputs !== void 0 ? { inputs } : {}
+		});
+	});
+	return {
+		dispatch,
+		runStatus: Effect.fn("WorkflowDispatch.runStatus")(function* (runId) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				runId
+			});
+			const raw = yield* client.request("GET /repos/{owner}/{repo}/actions/runs/{run_id}", {
+				owner,
+				repo,
+				run_id: runId
+			});
+			return statusOf(raw);
+		}),
+		dispatchAndWait: Effect.fn("WorkflowDispatch.dispatchAndWait")(function* (workflow, ref, options) {
+			const { owner, repo } = yield* Repo;
+			const interval = options?.poll?.interval ?? DEFAULT_INTERVAL;
+			const timeout = options?.poll?.timeout ?? DEFAULT_TIMEOUT;
+			const attempts = Math.max(1, Math.ceil(Duration.toMillis(timeout) / Duration.toMillis(interval)));
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				workflow,
+				ref,
+				attempts
+			});
+			const dispatchedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
+			yield* dispatch(workflow, ref, options?.inputs);
+			const findRun = Effect.gen(function* () {
+				const match = (yield* client.paginate("GET /repos/{owner}/{repo}/actions/runs", {
+					owner,
+					repo,
+					created: `>=${dispatchedAt}`,
+					branch: ref
+				}, PageOptions.make({
+					perPage: 10,
+					maxPages: 1
+				}))).find((run) => run.path?.endsWith(workflow) ?? true);
+				return match === void 0 ? Option.none() : Option.some(statusOf(match));
+			});
+			const settled = yield* Effect.repeat(findRun, {
+				while: (found) => Option.isNone(found) || !found.value.isDone,
+				schedule: Schedule.spaced(interval),
+				times: attempts
+			});
+			if (Option.isNone(settled) || !settled.value.isDone) return yield* Effect.fail(GitHubError.rejected("WorkflowDispatch.dispatchAndWait", 408, `workflow ${workflow} did not finish within ${Duration.format(timeout)}`));
+			return settled.value;
+		})
+	};
+};
+
+//#endregion
+export { WorkflowDispatch, WorkflowRunStatus };