@goodfellow-cms/github 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,926 @@
+import { ConflictError, DomainError, EditorsError, GitApiError, SetupError, SignInError, UpdatesError, buildStepFor, compareReleases, credentialStorage, encodeBase64, encodeBase64Bytes, siteVersion } from "@goodfellow-cms/core";
+//#region src/api.ts
+/** Calls the GitHub REST or GraphQL API. Treats 401 as an expired sign-in; other errors become `GitApiError`. */
+async function githubRequest({ apiUrl, token, fetch }, path, init = {}) {
+	const response = await fetch(`${apiUrl}${path}`, {
+		method: init.method ?? "GET",
+		headers: {
+			accept: init.accept ?? "application/vnd.github+json",
+			authorization: `Bearer ${token}`,
+			"x-github-api-version": "2022-11-28",
+			...init.body !== void 0 && { "content-type": "application/json" }
+		},
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body),
+		cache: "no-store"
+	});
+	if (response.status === 401) throw new SignInError("invalid", "GitHub didn't accept the sign-in. It may have expired.");
+	if (!response.ok && !init.allow?.includes(response.status)) {
+		const body = await response.json().catch(() => ({}));
+		throw new GitApiError(response.status, `GitHub answered ${response.status}: ${body.message ?? response.statusText}`);
+	}
+	return response;
+}
+async function githubJson(options, path, init) {
+	return await (await githubRequest(options, path, init)).json();
+}
+/** Path segments of a repository name, encoded for URLs: `owner/name` stays `owner/name`. */
+function repoPath(repo) {
+	return repo.split("/").map((part) => encodeURIComponent(part)).join("/");
+}
+//#endregion
+//#region src/editors.ts
+/** GitHub account names: letters, digits and single hyphens, up to 39 characters. */
+const USERNAME = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i;
+const INVITATION = "invitation:";
+function roleOf(permissions) {
+	if (permissions?.admin) return "owner";
+	return permissions?.maintain || permissions?.push ? "editor" : "viewer";
+}
+function invitationRole(permission) {
+	if (permission === "admin") return "owner";
+	return permission === "write" || permission === "maintain" ? "editor" : "viewer";
+}
+function isNotAllowed(error) {
+	return error instanceof GitApiError && (error.status === 403 || error.status === 404);
+}
+/**
+* The repository's collaborators. Anyone who can publish can list them, but
+* inviting and removing people needs a token with GitHub's Administration
+* permission, which signing in doesn't ask for: `manage()` gives the owner
+* token when one is in use.
+*/
+function githubEditors(read, manage, repo, login) {
+	const path = `/repos/${repo}`;
+	function managing() {
+		const api = manage();
+		if (!api) throw new EditorsError("not-allowed", "Changing editors on GitHub needs an owner token.");
+		return api;
+	}
+	async function change(run) {
+		try {
+			await run(managing());
+		} catch (error) {
+			if (isNotAllowed(error)) throw new EditorsError("not-allowed", "This token can't change the site's editors.");
+			throw error;
+		}
+	}
+	async function collaborators(api) {
+		const all = [];
+		for (let page = 1; page <= 10; page++) {
+			const found = await githubJson(api, `${path}/collaborators?per_page=100&page=${page}`);
+			all.push(...found);
+			if (found.length < 100) break;
+		}
+		return all;
+	}
+	return {
+		invitesByEmail: false,
+		async list() {
+			const api = manage() ?? read;
+			const people = await collaborators(api);
+			let invitations;
+			try {
+				invitations = await githubJson(api, `${path}/invitations?per_page=100`);
+			} catch (error) {
+				if (!isNotAllowed(error)) throw error;
+			}
+			const editors = [...people.map((person) => ({
+				id: person.login,
+				login: person.login,
+				avatarUrl: person.avatar_url,
+				role: roleOf(person.permissions),
+				...person.login.toLowerCase() === login.toLowerCase() && { self: true }
+			})), ...(invitations ?? []).flatMap((invitation) => invitation.invitee ? [{
+				id: `${INVITATION}${invitation.id}`,
+				login: invitation.invitee.login,
+				avatarUrl: invitation.invitee.avatar_url,
+				role: invitationRole(invitation.permissions),
+				invited: true
+			}] : [])];
+			const owner = editors.some((editor) => editor.self && editor.role === "owner");
+			return {
+				editors,
+				manage: invitations ? "yes" : owner ? "token" : "no",
+				editorsCanPublish: true
+			};
+		},
+		async invite(who, role) {
+			const name = who.trim().replace(/^@/, "");
+			if (!USERNAME.test(name)) throw new EditorsError("invalid", "That isn't a GitHub username.");
+			const api = managing();
+			try {
+				await githubRequest(api, `${path}/collaborators/${encodeURIComponent(name)}`, {
+					method: "PUT",
+					body: { permission: role === "owner" ? "admin" : "push" }
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && error.status === 404) {
+					if ((await githubRequest(api, `/users/${encodeURIComponent(name)}`, { allow: [404] })).status === 404) throw new EditorsError("not-found", `There's no GitHub account named ${name}.`);
+				}
+				if (isNotAllowed(error)) throw new EditorsError("not-allowed", "This token can't change the site's editors.");
+				if (error instanceof GitApiError && error.status === 422) throw new EditorsError("invalid", `GitHub didn't accept the invitation: ${error.message}`);
+				throw error;
+			}
+		},
+		async setRole(editor, role) {
+			await change(async (api) => {
+				if (editor.id.startsWith(INVITATION)) await githubRequest(api, `${path}/invitations/${editor.id.slice(11)}`, {
+					method: "PATCH",
+					body: { permissions: role === "owner" ? "admin" : "write" }
+				});
+				else await githubRequest(api, `${path}/collaborators/${encodeURIComponent(editor.id)}`, {
+					method: "PUT",
+					body: { permission: role === "owner" ? "admin" : "push" }
+				});
+			});
+		},
+		async remove(editor) {
+			await change((api) => githubRequest(api, editor.id.startsWith(INVITATION) ? `${path}/invitations/${editor.id.slice(11)}` : `${path}/collaborators/${encodeURIComponent(editor.id)}`, { method: "DELETE" }));
+		}
+	};
+}
+/** The owner token: GitHub's Administration and Pages permissions, for this tab only. */
+function githubOwnerAccess(base, repo, tokenLink) {
+	let owner;
+	return {
+		access: {
+			tokenLink,
+			get active() {
+				return owner !== void 0;
+			},
+			async applyToken(token) {
+				const api = {
+					...base,
+					token: token.trim()
+				};
+				try {
+					if (!(await githubJson(api, `/repos/${repo}`)).permissions?.admin) throw new EditorsError("not-allowed", "This token's account isn't an owner of the site.");
+					await githubJson(api, `/repos/${repo}/invitations?per_page=1`);
+				} catch (error) {
+					if (error instanceof EditorsError) throw error;
+					if (error instanceof SignInError || isNotAllowed(error)) throw new EditorsError("not-allowed", "This token can't change the site's editors.");
+					throw error;
+				}
+				owner = api;
+			},
+			forget() {
+				owner = void 0;
+			}
+		},
+		api: () => owner
+	};
+}
+//#endregion
+//#region src/pages.ts
+/** GitHub Pages' addresses for an apex domain, from GitHub's documentation. */
+const PAGES_IPV4 = [
+	"185.199.108.153",
+	"185.199.109.153",
+	"185.199.110.153",
+	"185.199.111.153"
+];
+const PAGES_IPV6 = [
+	"2606:50c0:8000::153",
+	"2606:50c0:8001::153",
+	"2606:50c0:8002::153",
+	"2606:50c0:8003::153"
+];
+/** Certificate states in which GitHub serves the domain over HTTPS. */
+const READY = /* @__PURE__ */ new Set([
+	"approved",
+	"issued",
+	"uploaded"
+]);
+const FAILED = /* @__PURE__ */ new Set([
+	"errored",
+	"bad_authz",
+	"authorization_revoked"
+]);
+/** The records GitHub Pages needs: its addresses for an apex domain, or an alias of the owner's github.io. */
+function githubPagesRecords(repo, domain, { apex, www }) {
+	const target = `${(repo.split("/")[0] ?? "").toLowerCase()}.github.io`;
+	if (!apex) return [{
+		type: "CNAME",
+		name: domain,
+		value: target,
+		purpose: "site"
+	}];
+	return [
+		...PAGES_IPV4.map((value) => ({
+			type: "A",
+			name: domain,
+			value,
+			purpose: "site"
+		})),
+		...PAGES_IPV6.map((value) => ({
+			type: "AAAA",
+			name: domain,
+			value,
+			purpose: "site",
+			optional: true
+		})),
+		...www ? [{
+			type: "CNAME",
+			name: `www.${domain}`,
+			value: target,
+			purpose: "www",
+			optional: true
+		}] : []
+	];
+}
+/**
+* GitHub Pages, for a site's repository: where it's published, and its custom
+* domain. `api` gives the owner token when one is in use (see `ownerAccess`).
+*/
+function githubPages(api, repo) {
+	const path = `/repos/${repo}/pages`;
+	async function pages() {
+		const response = await githubRequest(api(), path, { allow: [404] });
+		return response.status === 404 ? void 0 : await response.json();
+	}
+	async function update(body) {
+		try {
+			await githubRequest(api(), path, {
+				method: "PUT",
+				body
+			});
+		} catch (error) {
+			if (error instanceof GitApiError && (error.status === 403 || error.status === 404)) throw new DomainError("not-allowed", "This sign-in can't change the site's GitHub Pages settings.");
+			if (error instanceof GitApiError && (error.status === 400 || error.status === 422)) {
+				if (/taken|already/i.test(error.message)) throw new DomainError("taken", "Another GitHub Pages site already uses this domain.");
+				if ("https_enforced" in body) throw new DomainError("not-ready", "The domain's certificate isn't ready yet.");
+				throw new DomainError("invalid", "GitHub Pages doesn't accept this domain.");
+			}
+			throw error;
+		}
+	}
+	return {
+		async site() {
+			const found = await pages();
+			return found && {
+				url: found.html_url,
+				domain: found.cname ?? void 0
+			};
+		},
+		async connect(domain, options) {
+			await update({ cname: domain });
+			return githubPagesRecords(repo, domain, options);
+		},
+		async records(domain, options) {
+			return githubPagesRecords(repo, domain, options);
+		},
+		async status(domain) {
+			const found = await githubJson(api(), path);
+			const state = found.https_certificate?.state ?? "";
+			return {
+				verified: true,
+				certificate: READY.has(state) ? "ready" : FAILED.has(state) ? "failed" : "pending",
+				httpsOnly: found.https_enforced === true,
+				primary: found.cname === domain
+			};
+		},
+		async secure() {
+			await update({ https_enforced: true });
+		},
+		async disconnect() {
+			await update({ cname: null });
+		}
+	};
+}
+//#endregion
+//#region src/updates.ts
+/** The starters' GitHub Pages workflow, which runs `goodfellow update` each night and when it's dispatched. */
+const WORKFLOW = "deploy.yml";
+const WORKFLOW_FILE = `.github/workflows/${WORKFLOW}`;
+/**
+* The site's nightly update, which runs in its GitHub Pages workflow. Running
+* it now dispatches the workflow, which needs GitHub's Actions permission
+* with write access: `manage()` gives the owner token when one is in use.
+*/
+function githubUpdates(read, manage, repo, branch, files) {
+	const path = `/repos/${repo}/actions/workflows/${WORKFLOW}`;
+	return {
+		async setup() {
+			return (await files.read(WORKFLOW_FILE))?.includes("update --publish") ? "ready" : "missing";
+		},
+		async lastRun() {
+			const response = await githubRequest(read, `${path}/runs?branch=${encodeURIComponent(branch)}&per_page=20`, { allow: [403, 404] });
+			if (!response.ok) return void 0;
+			const { workflow_runs: runs = [] } = await response.json();
+			for (const run of runs.filter((candidate) => ["schedule", "workflow_dispatch"].includes(candidate.event))) {
+				const base = {
+					date: run.created_at,
+					detailsUrl: run.html_url
+				};
+				if (run.status !== "completed") return {
+					state: "running",
+					...base
+				};
+				const { jobs = [] } = await githubJson(read, `/repos/${repo}/actions/runs/${run.id}/jobs`);
+				const job = jobs.find((candidate) => candidate.name === "update");
+				if (!job || job.conclusion === "skipped") continue;
+				if (job.conclusion !== "success") return {
+					state: "failed",
+					...base
+				};
+				const before = siteVersion(await files.readAt("package.json", run.head_sha) ?? "");
+				const now = siteVersion(await files.read("package.json") ?? "");
+				if (!before || !now || before === now) return {
+					state: "up-to-date",
+					...base
+				};
+				const rollback = compareReleases(now, before) < 0;
+				return {
+					state: "updated",
+					...base,
+					result: {
+						state: "updated",
+						from: before,
+						to: now,
+						...rollback && { rollback }
+					}
+				};
+			}
+		},
+		async start(target) {
+			try {
+				await githubRequest(manage() ?? read, `${path}/dispatches`, {
+					method: "POST",
+					body: {
+						ref: branch,
+						inputs: { update: target }
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && (error.status === 403 || error.status === 401)) throw new UpdatesError("not-allowed", "Running the update needs a token that can run the site's workflows.");
+				if (error instanceof GitApiError && (error.status === 404 || error.status === 422)) throw new UpdatesError("missing", "The site's GitHub Pages workflow doesn't update Goodfellow.");
+				throw error;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/backend.ts
+const COMMIT_MUTATION = `mutation ($input: CreateCommitOnBranchInput!) {
+  createCommitOnBranch(input: $input) { commit { oid } }
+}`;
+/**
+* The site's files on GitHub. Reads come from the commit `revision()` last
+* returned; saves are single commits made with GraphQL's `createCommitOnBranch`,
+* which fails if the branch has moved, so nothing is ever overwritten.
+*/
+var GitHubBackend = class {
+	user;
+	pages;
+	editors;
+	ownerAccess;
+	updates;
+	api;
+	repo;
+	branch;
+	onSignOut;
+	pinned;
+	trees = /* @__PURE__ */ new Map();
+	blobs = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.api = options.api;
+		this.repo = repoPath(options.repo);
+		this.branch = options.branch;
+		this.user = options.user;
+		this.onSignOut = options.onSignOut;
+		const owner = githubOwnerAccess(this.api, this.repo, options.ownerTokenLink);
+		this.ownerAccess = owner.access;
+		this.pages = githubPages(() => owner.api() ?? this.api, this.repo);
+		this.editors = githubEditors(this.api, owner.api, this.repo, this.user.login);
+		this.updates = githubUpdates(this.api, owner.api, this.repo, this.branch, this);
+	}
+	async revision() {
+		const ref = await githubJson(this.api, `/repos/${this.repo}/git/ref/heads/${encodeURIComponent(this.branch)}`);
+		this.pinned = ref.object.sha;
+		return this.pinned;
+	}
+	/** Path → blob id for every file at a commit. Commits never change, so this is cached. */
+	tree(sha) {
+		let tree = this.trees.get(sha);
+		if (!tree) {
+			tree = githubJson(this.api, `/repos/${this.repo}/git/trees/${sha}?recursive=1`).then((response) => {
+				if (response.truncated) throw new GitApiError(413, "The repository has too many files for GitHub to list at once.");
+				return new Map(response.tree.filter((entry) => entry.type === "blob").map((entry) => [entry.path, entry.sha]));
+			});
+			tree.catch(() => this.trees.delete(sha));
+			this.trees.set(sha, tree);
+		}
+		return tree;
+	}
+	async currentTree() {
+		return this.tree(this.pinned ?? await this.revision());
+	}
+	async read(path) {
+		return this.readFrom(await this.currentTree(), path);
+	}
+	readFrom(tree, path) {
+		const sha = tree.get(path);
+		if (!sha) return Promise.resolve(void 0);
+		let blob = this.blobs.get(sha);
+		if (!blob) {
+			blob = githubRequest(this.api, `/repos/${this.repo}/git/blobs/${sha}`, { accept: "application/vnd.github.raw+json" }).then((response) => response.text());
+			blob.catch(() => this.blobs.delete(sha));
+			this.blobs.set(sha, blob);
+		}
+		return blob;
+	}
+	async readBytes(path) {
+		const sha = (await this.currentTree()).get(path);
+		if (!sha) return void 0;
+		const response = await githubRequest(this.api, `/repos/${this.repo}/git/blobs/${sha}`, { accept: "application/vnd.github.raw+json" });
+		return new Uint8Array(await response.arrayBuffer());
+	}
+	async list(dir) {
+		const prefix = `${dir}/`;
+		return [...(await this.currentTree()).keys()].filter((path) => path.startsWith(prefix)).sort();
+	}
+	async write(changes, { message, expectedRevision }) {
+		const existing = await this.tree(expectedRevision);
+		const additions = changes.flatMap((change) => "delete" in change ? [] : [{
+			path: change.path,
+			contents: "bytes" in change ? encodeBase64Bytes(change.bytes) : encodeBase64(change.content)
+		}]);
+		const deletions = changes.flatMap((change) => "delete" in change && existing.has(change.path) ? [{ path: change.path }] : []);
+		if (additions.length === 0 && deletions.length === 0) return { revision: expectedRevision };
+		const response = await githubJson(this.api, "/graphql", {
+			method: "POST",
+			body: {
+				query: COMMIT_MUTATION,
+				variables: { input: {
+					branch: {
+						repositoryNameWithOwner: decodeURIComponent(this.repo),
+						branchName: this.branch
+					},
+					message: { headline: message },
+					expectedHeadOid: expectedRevision,
+					fileChanges: {
+						additions,
+						deletions
+					}
+				} }
+			}
+		});
+		const oid = response.data?.createCommitOnBranch?.commit?.oid;
+		if (oid) {
+			this.pinned = oid;
+			return { revision: oid };
+		}
+		if (await this.revision() !== expectedRevision) throw new ConflictError();
+		const error = response.errors?.[0];
+		if (error?.type === "FORBIDDEN") throw new SignInError("cant-publish", "This GitHub account can't publish to the site.");
+		throw new GitApiError(422, `GitHub couldn't save the changes: ${error?.message ?? "unknown error"}`);
+	}
+	async history(path, { page = 1, perPage = 20 } = {}) {
+		const query = new URLSearchParams({
+			sha: this.pinned ?? await this.revision(),
+			path,
+			per_page: String(perPage),
+			page: String(page)
+		});
+		return (await githubJson(this.api, `/repos/${this.repo}/commits?${query}`)).map((commit) => ({
+			revision: commit.sha,
+			date: commit.commit.author?.date ?? "",
+			author: commit.commit.author?.name || commit.author?.login || void 0,
+			message: commit.commit.message.split("\n")[0] ?? ""
+		}));
+	}
+	async readAt(path, revision) {
+		return this.readFrom(await this.tree(revision), path);
+	}
+	async changedPaths(from, to) {
+		const comparison = await githubJson(this.api, `/repos/${this.repo}/compare/${from}...${to}`);
+		return [...new Set((comparison.files ?? []).flatMap((file) => [file.filename, file.previous_filename ?? []].flat()))];
+	}
+	/**
+	* Reads the deployment GitHub Pages or Vercel created for a commit, and for
+	* GitHub Actions, the workflow run that builds it: a build that fails never
+	* creates a deployment. Before either exists, the site counts as building
+	* if it has ever been deployed.
+	*/
+	async deployStatus(revision) {
+		try {
+			const latest = (await githubJson(this.api, `/repos/${this.repo}/deployments?sha=${revision}&per_page=5`))[0];
+			if (latest) {
+				const [status] = await githubJson(this.api, `/repos/${this.repo}/deployments/${latest.id}/statuses?per_page=1`);
+				const detailsUrl = status?.log_url || status?.target_url || void 0;
+				switch (status?.state) {
+					case "success":
+					case "inactive": return {
+						state: "live",
+						detailsUrl
+					};
+					case "failure":
+					case "error": {
+						const run = await this.workflowRun(revision);
+						return {
+							state: "failed",
+							detailsUrl,
+							problem: run ? await this.runProblem(run) : { step: "deploy" }
+						};
+					}
+					default: return {
+						state: "building",
+						detailsUrl
+					};
+				}
+			}
+			const run = await this.workflowRun(revision);
+			if (run?.status === "completed" && run.conclusion !== "success" && run.conclusion !== "skipped") return {
+				state: "failed",
+				detailsUrl: run.html_url,
+				problem: await this.runProblem(run)
+			};
+			if (run) return {
+				state: "building",
+				detailsUrl: run.html_url
+			};
+			return { state: (await githubJson(this.api, `/repos/${this.repo}/deployments?per_page=1`)).length > 0 ? "building" : "unknown" };
+		} catch (error) {
+			if (error instanceof GitApiError) return { state: "unknown" };
+			throw error;
+		}
+	}
+	/** The site's deploy workflow run for a commit, or `undefined` if there's none or the token can't see Actions. */
+	async workflowRun(revision) {
+		const response = await githubRequest(this.api, `/repos/${this.repo}/actions/runs?head_sha=${revision}&per_page=20`, { allow: [403, 404] });
+		if (!response.ok) return void 0;
+		const { workflow_runs: runs = [] } = await response.json();
+		return runs.find((run) => /deploy|pages/i.test(`${run.path ?? ""} ${run.name ?? ""}`)) ?? runs[0];
+	}
+	/** Which step of a failed run failed. */
+	async runProblem(run) {
+		const response = await githubRequest(this.api, `/repos/${this.repo}/actions/runs/${run.id}/jobs?per_page=50`, { allow: [403, 404] });
+		const failed = (response.ok ? (await response.json()).jobs ?? [] : []).find((job) => job.conclusion === "failure");
+		if (!failed) return {
+			step: run.conclusion === "startup_failure" ? "not-started" : "host",
+			detail: run.conclusion ?? void 0
+		};
+		const step = failed.steps?.find((candidate) => candidate.conclusion === "failure");
+		if (!step) return {
+			step: "not-started",
+			detail: failed.name
+		};
+		return {
+			step: buildStepFor(step.name) ?? (/deploy/i.test(failed.name) ? "deploy" : "build"),
+			detail: `${failed.name}: ${step.name}`
+		};
+	}
+	signOut() {
+		this.ownerAccess.forget();
+		this.onSignOut();
+	}
+};
+//#endregion
+//#region src/setup.ts
+/** The branch the deploy setups build from. */
+const MAIN = "main";
+/**
+* Links to GitHub's token pages with what creating a site needs: creating the
+* repository (administration), writing its files and its build setup
+* (contents and workflows), and turning on GitHub Pages (pages).
+*/
+function githubSetupTokenLinks(webUrl = "https://github.com") {
+	const fineGrained = new URLSearchParams({
+		name: "Goodfellow site setup",
+		description: "Create a Goodfellow site. It can be deleted once the site is created.",
+		expires_in: "7",
+		administration: "write",
+		contents: "write",
+		workflows: "write",
+		pages: "write"
+	});
+	const classic = new URLSearchParams({
+		scopes: "repo,workflow",
+		description: "Goodfellow site setup"
+	});
+	return {
+		fineGrained: `${webUrl}/settings/personal-access-tokens/new?${fineGrained}`,
+		classic: `${webUrl}/settings/tokens/new?${classic}`
+	};
+}
+/** Signing in to GitHub to create a site's repository, with GitHub Pages if wanted. */
+function githubSetup(options = {}) {
+	const apiUrl = (options.apiUrl ?? "https://api.github.com").replace(/\/$/, "");
+	const links = githubSetupTokenLinks(options.webUrl);
+	const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+	async function connect(token) {
+		const api = {
+			apiUrl,
+			token,
+			fetch: fetcher
+		};
+		const user = await githubJson(api, "/user");
+		async function owners() {
+			return [{
+				path: user.login,
+				name: user.name || user.login,
+				kind: "personal"
+			}, ...(await githubJson(api, "/user/orgs?per_page=100").catch(() => [])).map((org) => ({
+				path: org.login,
+				name: org.login,
+				kind: "organization"
+			}))];
+		}
+		async function isAvailable(owner, name) {
+			return (await githubRequest(api, `/repos/${repoPath(`${owner.path}/${name}`)}`, { allow: [404] })).status === 404;
+		}
+		async function createRepository(site) {
+			const path = site.owner.kind === "personal" ? "/user/repos" : `/orgs/${encodeURIComponent(site.owner.path)}/repos`;
+			if (!await isAvailable(site.owner, site.name)) throw new SetupError("name-taken", `There's already a repository called ${site.owner.path}/${site.name}.`);
+			try {
+				return await githubJson(api, path, {
+					method: "POST",
+					body: {
+						name: site.name,
+						private: site.private,
+						description: site.description,
+						auto_init: true
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && error.status === 422) throw new SetupError("name-invalid", `GitHub can't use "${site.name}" as a repository name.`);
+				if (error instanceof GitApiError && (error.status === 403 || error.status === 404)) throw new SetupError("not-allowed", `This sign-in can't create repositories in ${site.owner.path}.`);
+				throw error;
+			}
+		}
+		/** Makes `main` the default branch, which the deploy setups build from. */
+		async function useMainBranch(repo) {
+			if (repo.default_branch === MAIN) return;
+			const base = `/repos/${repoPath(repo.full_name)}`;
+			const ref = await githubJson(api, `${base}/git/ref/heads/${repo.default_branch}`);
+			await githubRequest(api, `${base}/git/refs`, {
+				method: "POST",
+				body: {
+					ref: `refs/heads/${MAIN}`,
+					sha: ref.object.sha
+				}
+			});
+			await githubRequest(api, base, {
+				method: "PATCH",
+				body: { default_branch: MAIN }
+			});
+			await githubRequest(api, `${base}/git/refs/heads/${repo.default_branch}`, { method: "DELETE" });
+		}
+		/** Turns on GitHub Pages, published by the site's own workflow. Returns the site's address. */
+		async function turnOnPages(repo) {
+			try {
+				return (await githubJson(api, `/repos/${repoPath(repo.full_name)}/pages`, {
+					method: "POST",
+					body: { build_type: "workflow" }
+				})).html_url;
+			} catch (error) {
+				if (error instanceof GitApiError && [
+					403,
+					404,
+					409,
+					422
+				].includes(error.status)) return void 0;
+				throw error;
+			}
+		}
+		/** Writes every file in one commit, which replaces the starting README rather than following it. */
+		async function writeFiles(repo, site) {
+			const base = `/repos/${repoPath(repo.full_name)}`;
+			const tree = [];
+			for (const file of site.files) {
+				if ("delete" in file) continue;
+				if ("content" in file) {
+					tree.push({
+						path: file.path,
+						mode: "100644",
+						type: "blob",
+						content: file.content
+					});
+					continue;
+				}
+				const blob = await githubJson(api, `${base}/git/blobs`, {
+					method: "POST",
+					body: {
+						content: encodeBase64Bytes(file.bytes),
+						encoding: "base64"
+					}
+				});
+				tree.push({
+					path: file.path,
+					mode: "100644",
+					type: "blob",
+					sha: blob.sha
+				});
+			}
+			try {
+				const created = await githubJson(api, `${base}/git/trees`, {
+					method: "POST",
+					body: { tree }
+				});
+				const commit = await githubJson(api, `${base}/git/commits`, {
+					method: "POST",
+					body: {
+						message: site.message,
+						tree: created.sha,
+						parents: []
+					}
+				});
+				await githubRequest(api, `${base}/git/refs/heads/${MAIN}`, {
+					method: "PATCH",
+					body: {
+						sha: commit.sha,
+						force: true
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && (error.status === 403 || error.status === 404)) throw new SetupError("not-allowed", "This sign-in can't write the site's files, or its build setup.");
+				throw error;
+			}
+		}
+		/** Stops anyone rewriting or deleting the main branch's history. Not every plan allows it. */
+		async function protectMain(repo) {
+			return (await githubRequest(api, `/repos/${repoPath(repo.full_name)}/rulesets`, {
+				method: "POST",
+				body: {
+					name: "Protect the published history",
+					target: "branch",
+					enforcement: "active",
+					conditions: { ref_name: {
+						include: ["~DEFAULT_BRANCH"],
+						exclude: []
+					} },
+					rules: [{ type: "non_fast_forward" }, { type: "deletion" }]
+				},
+				allow: [
+					403,
+					404,
+					422
+				]
+			})).ok;
+		}
+		return {
+			user: {
+				login: user.login,
+				name: user.name ?? void 0,
+				avatarUrl: user.avatar_url
+			},
+			owners,
+			isAvailable,
+			async createSite(site, onStep) {
+				const warnings = [];
+				onStep?.("repository");
+				const repo = await createRepository(site);
+				await useMainBranch(repo);
+				let siteUrl;
+				if (site.pages) {
+					onStep?.("pages");
+					siteUrl = await turnOnPages(repo);
+					if (!siteUrl) warnings.push("pages-unavailable");
+				}
+				onStep?.("files");
+				await writeFiles(repo, site);
+				onStep?.("protection");
+				if (!await protectMain(repo)) warnings.push("protection-unavailable");
+				return {
+					repo: repo.full_name,
+					webUrl: repo.html_url,
+					siteUrl,
+					buildsUrl: `${repo.html_url}/actions`,
+					pagesUrl: site.pages ? `${repo.html_url}/settings/pages` : void 0,
+					warnings
+				};
+			}
+		};
+	}
+	return {
+		name: "GitHub",
+		canRedirect: false,
+		tokenLinks: [{
+			url: links.fineGrained,
+			label: "signIn.token.create"
+		}, {
+			url: links.classic,
+			label: "signIn.token.createBroad",
+			hint: "signIn.token.createBroadHint"
+		}],
+		async restore() {
+			return null;
+		},
+		async signInWithToken(token) {
+			const trimmed = token.trim();
+			if (!trimmed) throw new SignInError("invalid", "Paste a token to sign in.");
+			return connect(trimmed);
+		},
+		async startRedirect() {
+			throw new Error("Signing in by redirect needs a sign-in server, which isn't supported for GitHub yet.");
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Links to GitHub's token page with everything filled in except the
+* repository, which GitHub doesn't let links choose.
+*/
+function githubTokenLinks(repo, webUrl = "https://github.com") {
+	const [repoOwner = ""] = repo.split("/");
+	const fineGrained = new URLSearchParams({
+		name: "Goodfellow admin",
+		description: `Edit ${repo} in its admin panel`,
+		target_name: repoOwner,
+		expires_in: "90",
+		contents: "write",
+		deployments: "read",
+		actions: "read"
+	});
+	const classic = new URLSearchParams({
+		scopes: "repo",
+		description: `Goodfellow admin for ${repo}`
+	});
+	const owner = new URLSearchParams({
+		name: "Goodfellow owner",
+		description: `Manage the editors, domain and updates of ${repo}`,
+		target_name: repoOwner,
+		expires_in: "1",
+		administration: "write",
+		pages: "write",
+		actions: "write"
+	});
+	return {
+		fineGrained: `${webUrl}/settings/personal-access-tokens/new?${fineGrained}`,
+		classic: `${webUrl}/settings/tokens/new?${classic}`,
+		owner: `${webUrl}/settings/personal-access-tokens/new?${owner}`
+	};
+}
+/** Sign-in and storage for a site whose repository is on GitHub. */
+function github(options) {
+	if (!/^[\w.-]+\/[\w.-]+$/.test(options.repo)) throw new Error(`github({ repo }) must look like "owner/name" (got "${options.repo}").`);
+	const apiUrl = (options.apiUrl ?? "https://api.github.com").replace(/\/$/, "");
+	const links = githubTokenLinks(options.repo, options.webUrl);
+	const storage = credentialStorage(`goodfellow:github:${options.repo}`, options.storage);
+	async function connect(token) {
+		const api = {
+			apiUrl,
+			token,
+			fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+		};
+		const user = await githubJson(api, "/user");
+		let repo;
+		try {
+			repo = await githubJson(api, `/repos/${repoPath(options.repo)}`);
+		} catch (error) {
+			if (error instanceof GitApiError && (error.status === 404 || error.status === 403)) throw new SignInError("no-access", `The GitHub account ${user.login} can't see ${options.repo}.`);
+			throw error;
+		}
+		if (repo.permissions?.push === false) throw new SignInError("cant-publish", `The GitHub account ${user.login} can see ${options.repo} but can't publish to it.`);
+		return new GitHubBackend({
+			api,
+			repo: options.repo,
+			branch: options.branch ?? repo.default_branch,
+			user: {
+				login: user.login,
+				name: user.name ?? void 0,
+				avatarUrl: user.avatar_url
+			},
+			onSignOut: () => storage.clear(),
+			ownerTokenLink: {
+				url: links.owner,
+				label: "owner.token.create"
+			}
+		});
+	}
+	return {
+		name: "GitHub",
+		canRedirect: false,
+		tokenLinks: [{
+			url: links.fineGrained,
+			label: "signIn.token.create"
+		}, {
+			url: links.classic,
+			label: "signIn.token.createBroad",
+			hint: "signIn.token.createBroadHint"
+		}],
+		async restore() {
+			const token = storage.load();
+			if (!token) return null;
+			try {
+				return await connect(token);
+			} catch (error) {
+				if (error instanceof SignInError) storage.clear();
+				throw error;
+			}
+		},
+		async signInWithToken(token, remember) {
+			const trimmed = token.trim();
+			if (!trimmed) throw new SignInError("invalid", "Paste a token to sign in.");
+			const backend = await connect(trimmed);
+			storage.save(trimmed, remember);
+			return backend;
+		},
+		async startRedirect() {
+			throw new Error("Signing in by redirect needs a sign-in server, which isn't supported for GitHub yet.");
+		}
+	};
+}
+//#endregion
+export { GitHubBackend, github, githubPagesRecords, githubSetup, githubSetupTokenLinks, githubTokenLinks };