@effected/github 0.1.0

package/GitCommit.js

@@ -0,0 +1,183 @@
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { Context, Effect, Layer, Schema } from "effect";
+
+//#region src/GitCommit.ts
+/**
+* A blob's file mode, as the Git Database API spells it.
+*
+* @public
+*/
+const FileMode = Schema.Literals([
+	"100644",
+	"100755",
+	"120000"
+]);
+/**
+* A file to write in a commit.
+*
+* @public
+*/
+var FileContent = class extends Schema.TaggedClass()("FileContent", {
+	/** Repository-relative path. */
+	path: Schema.NonEmptyString,
+	/** The file's new contents. */
+	content: Schema.String,
+	/** Defaults to a regular file. */
+	mode: Schema.optionalKey(FileMode)
+}) {};
+/**
+* A file to remove in a commit.
+*
+* @public
+*/
+var FileDeletion = class extends Schema.TaggedClass()("FileDeletion", { 
+/** Repository-relative path. */
+path: Schema.NonEmptyString }) {};
+/**
+* One change in a commit.
+*
+* @public
+*/
+const FileChange = Schema.Union([FileContent, FileDeletion]);
+/**
+* A commit, projected to the three fields callers actually use.
+*
+* @remarks
+* `treeSha` is here because two surveyed call sites dropped to a raw octokit
+* cast for it alone, both with the comment *"the Git Data API's `base_tree`
+* wants a tree SHA, not a commit SHA"* — the same eight lines written twice, in
+* two files, for one string.
+*
+* @public
+*/
+var CommitRef = class extends Schema.Class("CommitRef")({
+	/** The commit's own sha. */
+	sha: Schema.String,
+	/** The tree the commit points at — what `baseTree` wants. */
+	treeSha: Schema.String,
+	/** Parent commit shas, in order. */
+	parents: Schema.Array(Schema.String)
+}) {};
+/**
+* Commits, trees and blobs.
+*
+* @public
+*/
+var GitCommit = class GitCommit extends Context.Service()("@effected/github/GitCommit") {
+	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		get: overrides.get ?? (() => unstubbed("get")),
+		createTree: overrides.createTree ?? (() => unstubbed("createTree")),
+		createCommit: overrides.createCommit ?? (() => unstubbed("createCommit")),
+		commitFiles: overrides.commitFiles ?? (() => unstubbed("commitFiles"))
+	});
+	/** {@link GitCommit.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(GitCommit, GitCommit.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`GitCommit.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+/** The Git Database tree entry for one change. */
+const treeEntry = (change) => change._tag === "FileContent" ? {
+	path: change.path,
+	mode: change.mode ?? "100644",
+	type: "blob",
+	content: change.content
+} : {
+	path: change.path,
+	mode: "100644",
+	type: "blob",
+	sha: null
+};
+const make = (client) => {
+	const get = Effect.fn("GitCommit.get")(function* (sha) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			sha
+		});
+		const commit = yield* client.request("GET /repos/{owner}/{repo}/git/commits/{commit_sha}", {
+			owner,
+			repo,
+			commit_sha: sha
+		});
+		return CommitRef.make({
+			sha: commit.sha,
+			treeSha: commit.tree.sha,
+			parents: commit.parents.map((parent) => parent.sha)
+		});
+	});
+	const createTree = Effect.fn("GitCommit.createTree")(function* (options) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			changes: options.changes.length
+		});
+		return (yield* client.request("POST /repos/{owner}/{repo}/git/trees", {
+			owner,
+			repo,
+			tree: options.changes.map(treeEntry),
+			...options.baseTree !== void 0 ? { base_tree: options.baseTree } : {}
+		})).sha;
+	});
+	const createCommit = Effect.fn("GitCommit.createCommit")(function* (options) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			tree: options.tree
+		});
+		return (yield* client.request("POST /repos/{owner}/{repo}/git/commits", {
+			owner,
+			repo,
+			message: options.message,
+			tree: options.tree,
+			parents: [...options.parents]
+		})).sha;
+	});
+	return {
+		get,
+		createTree,
+		createCommit,
+		commitFiles: Effect.fn("GitCommit.commitFiles")(function* (options) {
+			const { owner, repo } = yield* Repo;
+			const short = options.branch.replace(/^refs\/heads\//, "").replace(/^heads\//, "");
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				branch: short,
+				changes: options.changes.length
+			});
+			const ref = yield* client.request("GET /repos/{owner}/{repo}/git/ref/{ref}", {
+				owner,
+				repo,
+				ref: `heads/${short}`
+			});
+			const head = yield* get(ref.object.sha);
+			const tree = yield* createTree({
+				changes: options.changes,
+				baseTree: head.treeSha
+			});
+			const commit = yield* createCommit({
+				message: options.message,
+				tree,
+				parents: [head.sha]
+			});
+			yield* client.request("PATCH /repos/{owner}/{repo}/git/refs/{ref}", {
+				owner,
+				repo,
+				ref: `heads/${short}`,
+				sha: commit,
+				force: false
+			});
+			return commit;
+		})
+	};
+};
+
+//#endregion
+export { CommitRef, FileChange, FileContent, FileDeletion, FileMode, GitCommit };

package/GitHubApp.js

@@ -0,0 +1,363 @@
+import { GitHubError } from "./GitHubError.js";
+import { GitHubGraphQLError } from "./GraphQL.js";
+import { GitHubClient, makeClientShape } from "./GitHubClient.js";
+import { Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Stream } from "effect";
+import githubAppJwt from "universal-github-app-jwt";
+
+//#region src/GitHubApp.ts
+/**
+* A GitHub App call failed.
+*
+* @remarks
+* Distinct from `GitHubError` because "I could not obtain credentials" and "the
+* API call failed" are different problems with different fixes: the first is a
+* misconfigured app, a wrong private key or a missing installation; the second
+* is the request that used the credentials.
+*
+* @public
+*/
+var GitHubAppError = class GitHubAppError extends Schema.TaggedErrorClass()("GitHubAppError", {
+	/** Which step failed. */
+	kind: Schema.Literals([
+		"jwt",
+		"token",
+		"revoke",
+		"identity",
+		"installation"
+	]),
+	/** Human-readable cause. */
+	reason: Schema.String,
+	/** The underlying failure, when there is one. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `GitHub App ${this.kind} failed: ${this.reason}`;
+	}
+	/** @internal */
+	static of(kind, reason, cause) {
+		return new GitHubAppError({
+			kind,
+			reason,
+			...cause !== void 0 ? { cause } : {}
+		});
+	}
+};
+/**
+* An installation access token and what GitHub said about it.
+*
+* @remarks
+* Encodable on purpose. `@effected/github-actions` persists one across the
+* `pre`/`main`/`post` process boundary through `GITHUB_STATE`, and
+* `Schema.encodeUnknownEffect` produces JSON with the token as a plain string
+* and `expiresAt` as an ISO instant. A `Redacted` cannot survive serialization
+* by design, so masking the encoded value is the caller's job — Actions calls
+* `::add-mask::`.
+*
+* @public
+*/
+var InstallationToken = class extends Schema.Class("InstallationToken")({
+	/** The token. Decodes to `Redacted`, encodes back to the raw string. */
+	token: Schema.RedactedFromValue(Schema.String),
+	/** When GitHub will stop accepting it — about an hour out. */
+	expiresAt: Schema.DateTimeUtcFromString,
+	/** The installation it is scoped to. */
+	installationId: Schema.Int,
+	/** The permissions GitHub actually granted, which may be narrower than requested. */
+	permissions: Schema.Record(Schema.String, Schema.String),
+	/** The app's slug, when identity was resolved. */
+	appSlug: Schema.optionalKey(Schema.String),
+	/** The app's bot user id, when identity was resolved. */
+	appUserId: Schema.optionalKey(Schema.Int),
+	/** The app's display name, when identity was resolved. */
+	appName: Schema.optionalKey(Schema.String)
+}) {
+	/**
+	* Whether this token is spent, `skew` before its stated expiry.
+	*
+	* @remarks
+	* Modelled **and enforced**. The package this replaces persisted `expiresAt`
+	* and read it nowhere, so a long `main` phase that outlived the hour simply
+	* started answering 401 with no explanation.
+	*/
+	isExpired(nowMillis, skew = DEFAULT_SKEW) {
+		return DateTime.toEpochMillis(this.expiresAt) - Duration.toMillis(skew) <= nowMillis;
+	}
+	/** The committer identity a commit made with this token should carry. */
+	botIdentity() {
+		return this.appSlug === void 0 ? BotIdentity.githubActions : BotIdentity.forApp({
+			appSlug: this.appSlug,
+			...this.appUserId !== void 0 ? { appUserId: this.appUserId } : {}
+		});
+	}
+};
+/** Re-mint a minute before GitHub would start refusing the token. */
+const DEFAULT_SKEW = Duration.seconds(60);
+/**
+* Who a bot commits as.
+*
+* @remarks
+* A **pure class**, not a service member. The package this replaces put
+* `botIdentity(source?)` on the `GitHubApp` service shape as a plain synchronous
+* method, which makes it required in every `Layer.mock` and silently degrades
+* every partial double to a full implementation.
+*
+* @public
+*/
+var BotIdentity = class BotIdentity extends Schema.Class("BotIdentity")({
+	/** The git author/committer name, e.g. `"my-app[bot]"`. */
+	name: Schema.String,
+	/** The no-reply address GitHub attributes to that account. */
+	email: Schema.String
+}) {
+	/** The identity for an app, given whatever of its identity is known. */
+	static forApp(source) {
+		const name = `${source.appSlug}[bot]`;
+		return BotIdentity.make({
+			name,
+			email: source.appUserId === void 0 ? `${name}@users.noreply.github.com` : `${source.appUserId}+${name}@users.noreply.github.com`
+		});
+	}
+	/** The well-known identity of the `github-actions` bot. */
+	static githubActions = BotIdentity.make({
+		name: "github-actions[bot]",
+		email: "41898282+github-actions[bot]@users.noreply.github.com"
+	});
+};
+/**
+* What GitHub knows about the app itself.
+*
+* @public
+*/
+var AppIdentity = class extends Schema.Class("AppIdentity")({
+	/** The URL slug, e.g. `"my-app"`. */
+	slug: Schema.String,
+	/** The display name. */
+	name: Schema.String,
+	/** The bot user's numeric id, when it could be resolved. */
+	userId: Schema.optionalKey(Schema.Int)
+}) {
+	/** The committer identity for this app. */
+	botIdentity() {
+		return BotIdentity.forApp({
+			appSlug: this.slug,
+			...this.userId !== void 0 ? { appUserId: this.userId } : {}
+		});
+	}
+};
+/**
+* One installation of the app.
+*
+* @public
+*/
+var Installation = class extends Schema.Class("Installation")({
+	/** The installation id, which is what a token is minted against. */
+	id: Schema.Int,
+	/** The account the app is installed on, when GitHub reported one. */
+	account: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* GitHub App authentication: mint, revoke and identify.
+*
+* @remarks
+* **This is the only module in the package that imports a JWT signer**, which is
+* what makes the tree-shaking invariant structural rather than aspirational: a
+* consumer that authenticates with a token it already holds imports
+* `GitHubClient` and never reaches this module or its dependency.
+*
+* That constraint is also why the App-authenticated **client** layer lives here
+* as {@link GitHubApp.clientLayer} rather than as a third static on
+* `GitHubClient`: statics on one class share one module, and putting it there
+* would make every token-only consumer link the signer. The kit has this shape
+* already — `@effected/workspaces` ships `localExecLayer`, which builds
+* `@effected/commands`' service, for the same reason.
+*
+* The JWT signer is `universal-github-app-jwt` — zero dependencies, and
+* `@octokit/auth-app`'s own JWT dependency. Taking it directly rather than
+* taking `auth-app` leaves behind roughly half a megabyte of OAuth app, user and
+* device-flow machinery that this package never calls.
+*
+* @public
+*/
+var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitHubApp") {
+	/** The default transport. Bind it once; layers are memoized by reference. */
+	static layer = Layer.effect(this, makeApp({}));
+	/**
+	* A transport with custom settings.
+	*
+	* @remarks
+	* Parameterized, so **bind the result to a `const`** and reuse it. Calling
+	* this at two provide sites builds two instances, because layers are
+	* memoized by reference.
+	*/
+	static layerWith = (options) => Layer.effect(GitHubApp, makeApp(options));
+	/**
+	* A {@link GitHubClient} authenticated as an app installation.
+	*
+	* @remarks
+	* The token's lifetime is the layer's scope: it is minted on build and
+	* **revoked on release**, best-effort, so a workflow does not leave live
+	* credentials behind. It is also **re-minted automatically** a minute before
+	* it expires, which the package this replaces did not do — it persisted
+	* `expiresAt` and read it nowhere, so a `main` phase outliving the hour
+	* started answering 401 with nothing explaining why.
+	*
+	* A failure to obtain credentials surfaces to the caller as a
+	* `GitHubError { kind: "unauthorized" }` carrying the `GitHubAppError` as its
+	* cause: from a request's point of view, "could not authenticate" is an
+	* authorization failure, and widening every method's error channel to say so
+	* would tax every caller for a case only this layer can produce.
+	*/
+	static clientLayer = (request, options = {}) => Layer.effect(GitHubClient, Effect.flatMap(GitHubApp, (app) => makeRotatingClient(app, request, options))).pipe(Layer.provide(GitHubApp.layerWith(options)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		token: overrides.token ?? (() => unstubbed("token")),
+		scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
+		revoke: overrides.revoke ?? (() => unstubbed("revoke")),
+		identity: overrides.identity ?? (() => unstubbed("identity")),
+		installations: overrides.installations ?? (() => unstubbed("installations"))
+	});
+	/** {@link GitHubApp.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(GitHubApp, GitHubApp.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`GitHubApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+/** Mint an app JWT. The only cryptography in this package, and it is a leaf call. */
+const mintJwt = (credentials) => Effect.tryPromise({
+	try: () => githubAppJwt({
+		id: credentials.appId,
+		privateKey: Redacted.value(credentials.privateKey)
+	}),
+	catch: (error) => GitHubAppError.of("jwt", error instanceof Error ? error.message : "could not sign the app JWT", error)
+}).pipe(Effect.map((result) => Redacted.make(result.token)));
+/** A client speaking as the app itself. */
+const asApp = (credentials, options) => Effect.flatMap(mintJwt(credentials), (jwt) => makeClientShape({
+	...options,
+	token: jwt
+}));
+/** A client speaking as a holder of `token`, or as nobody when there is none. */
+const asBearer = (token, options) => makeClientShape({
+	...options,
+	token: token ?? Redacted.make("")
+});
+const appFailure = (kind) => (error) => Effect.fail(GitHubAppError.of(kind, error.reason, error));
+function makeApp(options) {
+	return Effect.sync(() => {
+		const installations = Effect.fn("GitHubApp.installations")(function* (credentials) {
+			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => Installation.make({
+				id: entry.id,
+				...entry.account !== null && entry.account !== void 0 && "login" in entry.account ? { account: entry.account.login } : {}
+			}));
+		});
+		const resolveInstallationId = (request) => request.installationId !== void 0 ? Effect.succeed(request.installationId) : Effect.gen(function* () {
+			const all = yield* installations(request);
+			if (request.owner !== void 0) {
+				const wanted = request.owner.toLowerCase();
+				const match = all.find((entry) => entry.account?.toLowerCase() === wanted);
+				if (match !== void 0) return match.id;
+				return yield* Effect.fail(GitHubAppError.of("installation", `the app is not installed on ${request.owner} (installed on: ${all.map((entry) => entry.account ?? entry.id).join(", ") || "nothing"})`));
+			}
+			const only = all[0];
+			if (all.length === 1 && only !== void 0) return only.id;
+			return yield* Effect.fail(GitHubAppError.of("installation", all.length === 0 ? "the app has no installations" : `the app has ${all.length} installations; pass installationId or owner`));
+		});
+		const token = Effect.fn("GitHubApp.token")(function* (request) {
+			const installationId = yield* resolveInstallationId(request);
+			const minted = yield* (yield* asApp(request, options)).request("POST /app/installations/{installation_id}/access_tokens", { installation_id: installationId }).pipe(Effect.catch(appFailure("token")));
+			return yield* Schema.decodeUnknownEffect(InstallationToken)({
+				token: minted.token,
+				expiresAt: minted.expires_at,
+				installationId,
+				permissions: normalizePermissions(minted.permissions)
+			}).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubAppError.of("token", "GitHub returned an unexpected token payload", error))));
+		});
+		const revoke = Effect.fn("GitHubApp.revoke")(function* (value) {
+			yield* (yield* asBearer(value, options)).request("DELETE /installation/token", {}).pipe(Effect.catch(appFailure("revoke")));
+		});
+		const scopedToken = (request) => Effect.acquireRelease(token(request), (minted) => Effect.ignore(revoke(minted.token)));
+		return {
+			token,
+			scopedToken,
+			revoke,
+			identity: Effect.fn("GitHubApp.identity")(function* (request) {
+				const app = yield* (yield* asApp(request, options)).request("GET /app", {}).pipe(Effect.catch(appFailure("identity")));
+				if (app === null) return yield* Effect.fail(GitHubAppError.of("identity", "GET /app returned no app"));
+				const slug = app.slug ?? "";
+				const name = app.name;
+				const user = yield* (yield* asBearer(request.installationToken, options)).request("GET /users/{username}", { username: `${slug}[bot]` }).pipe(Effect.option);
+				return AppIdentity.make({
+					slug,
+					name,
+					...Option.isSome(user) ? { userId: user.value.id } : {}
+				});
+			}),
+			installations
+		};
+	});
+}
+/** GitHub's permission values are strings; anything else is not a permission. */
+const normalizePermissions = (raw) => {
+	if (typeof raw !== "object" || raw === null) return {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) if (typeof value === "string") out[key] = value;
+	return out;
+};
+/**
+* A client shape that re-mints its installation token before it expires.
+*
+* @remarks
+* The rotation is invisible to a caller: each member resolves the current
+* client first, and "current" means "minted, and not within a minute of
+* expiry". Rotating revokes the token it replaces, so at most one live token
+* exists at a time and the scope's release revokes the last of them.
+*/
+const makeRotatingClient = (app, request, options) => Effect.gen(function* () {
+	const held = yield* Ref.make(Option.none());
+	const revokeHeld = Effect.flatMap(Ref.get(held), (current) => Option.isSome(current) ? Effect.ignore(app.revoke(current.value.token.token)) : Effect.void);
+	const rotate = Effect.gen(function* () {
+		yield* revokeHeld;
+		const minted = yield* app.token(request);
+		const client = yield* makeClientShape({
+			...options,
+			token: minted.token
+		});
+		yield* Ref.set(held, Option.some({
+			token: minted,
+			client
+		}));
+		return client;
+	});
+	yield* rotate;
+	yield* Effect.addFinalizer(() => revokeHeld);
+	/** The live client, re-minting first if the held token is spent. */
+	const fresh = Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		const state = yield* Ref.get(held);
+		if (Option.isSome(state) && !state.value.token.isExpired(now)) return state.value.client;
+		return yield* rotate;
+	});
+	const current = fresh.pipe(Effect.catchTag("GitHubAppError", (error) => Effect.fail(new GitHubError({
+		kind: "unauthorized",
+		operation: "GitHubApp.clientLayer",
+		reason: error.reason,
+		cause: error
+	}))));
+	const currentForGraphQL = fresh.pipe(Effect.catchTag("GitHubAppError", (error) => Effect.fail(new GitHubGraphQLError({
+		kind: "unauthorized",
+		operation: "GitHubApp.clientLayer",
+		reason: error.reason,
+		errors: [],
+		cause: error
+	}))));
+	return {
+		request: (route, params) => Effect.flatMap(current, (client) => client.request(route, params)),
+		requestDecoded: (route, params, schema) => Effect.flatMap(current, (client) => client.requestDecoded(route, params, schema)),
+		paginate: (route, params, pageOptions) => Effect.flatMap(current, (client) => client.paginate(route, params, pageOptions)),
+		paginateStream: (route, params, pageOptions) => Stream.unwrap(Effect.map(current, (client) => client.paginateStream(route, params, pageOptions))),
+		graphql: (document, variables) => Effect.flatMap(currentForGraphQL, (client) => client.graphql(document, variables)),
+		rateLimit: Effect.flatMap(Ref.get(held), (state) => Option.isSome(state) ? state.value.client.rateLimit : Effect.succeed(Option.none()))
+	};
+});
+
+//#endregion
+export { AppIdentity, BotIdentity, GitHubApp, GitHubAppError, Installation, InstallationToken };