@goodfellow-cms/gitlab 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,1026 @@
+import { ConflictError, DomainError, EDITABLE_FOLDERS, EditorsError, GitApiError, SetupError, SignInError, UpdatesError, buildStepFor, credentialStorage, encodeBase64Bytes, findBuildCause, findUpdateResult } from "@goodfellow-cms/core";
+//#region src/api.ts
+/** Calls the GitLab API. A 401 refreshes the token once; after that it means the sign-in has expired. */
+async function gitlabRequest(api, path, init = {}) {
+	const send = async (refresh) => api.fetch(`${api.apiUrl}${path}`, {
+		method: init.method ?? "GET",
+		headers: {
+			authorization: `Bearer ${await api.token({ refresh })}`,
+			...init.body !== void 0 && { "content-type": "application/json" }
+		},
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body),
+		cache: "no-store"
+	});
+	let response = await send(false);
+	if (response.status === 401 && api.canRefresh) response = await send(true);
+	if (response.status === 401) throw new SignInError("invalid", "GitLab didn't accept the sign-in. It may have expired.");
+	if (!response.ok && !init.allow?.includes(response.status)) {
+		const body = await response.json().catch(() => ({}));
+		const message = typeof body.message === "string" ? body.message : JSON.stringify(body.message ?? body.error ?? "");
+		throw new GitApiError(response.status, `GitLab answered ${response.status}: ${message || response.statusText}`);
+	}
+	return response;
+}
+async function gitlabJson(api, path, init) {
+	return await (await gitlabRequest(api, path, init)).json();
+}
+//#endregion
+//#region src/editors.ts
+/** GitLab's roles: Developer, Maintainer and Owner. */
+const DEVELOPER = 30;
+const MAINTAINER = 40;
+const MEMBER = "member:";
+const INVITATION = "invitation:";
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const USERNAME = /^[\w][\w.-]*$/;
+function roleOf(level) {
+	if (level >= MAINTAINER) return "owner";
+	return level >= DEVELOPER ? "editor" : "viewer";
+}
+function levelOf(role) {
+	return role === "owner" ? MAINTAINER : DEVELOPER;
+}
+function notAllowed$1(error) {
+	if (error instanceof GitApiError && (error.status === 401 || error.status === 403)) throw new EditorsError("not-allowed", "Changing editors on GitLab needs the Maintainer role in the project.");
+	throw error;
+}
+/**
+* The project's members. Editors are Developers, and owners Maintainers,
+* who can also add and remove members. GitLab protects the main branch so
+* only Maintainers can publish to it, until `letEditorsPublish()` lets
+* Developers publish too.
+*/
+function gitlabEditors(api, project, branch, username) {
+	const base = `/projects/${encodeURIComponent(project)}`;
+	const protectedPath = `${base}/protected_branches/${encodeURIComponent(branch)}`;
+	async function all(path) {
+		const found = [];
+		for (let page = 1; page <= 10; page++) {
+			const items = await gitlabJson(api, `${path}${path.includes("?") ? "&" : "?"}per_page=100&page=${page}`);
+			found.push(...items);
+			if (items.length < 100) break;
+		}
+		return found;
+	}
+	return {
+		invitesByEmail: true,
+		async list() {
+			const [everyone, direct] = await Promise.all([all(`${base}/members/all`), all(`${base}/members`)]);
+			const own = new Set(direct.map((member) => member.id));
+			const self = everyone.find((member) => member.username.toLowerCase() === username.toLowerCase());
+			const manage = (self?.access_level ?? 0) >= MAINTAINER;
+			const invitations = manage ? await all(`${base}/invitations`).catch(() => []) : [];
+			const protection = await gitlabRequest(api, protectedPath, { allow: [404] });
+			const levels = protection.ok ? (await protection.json()).push_access_levels ?? [] : [];
+			const editorsCanPublish = !protection.ok || levels.some((level) => level.access_level !== null && level.access_level <= DEVELOPER);
+			return {
+				editors: [...everyone.map((member) => ({
+					id: `${MEMBER}${member.id}`,
+					login: member.username,
+					name: member.name,
+					avatarUrl: member.avatar_url,
+					role: roleOf(member.access_level),
+					...!own.has(member.id) && { inherited: true },
+					...member.id === self?.id && { self: true }
+				})), ...invitations.map((invitation) => ({
+					id: `${INVITATION}${invitation.invite_email}`,
+					email: invitation.invite_email,
+					role: roleOf(invitation.access_level),
+					invited: true
+				}))],
+				manage: manage ? "yes" : "no",
+				editorsCanPublish
+			};
+		},
+		async invite(who, role) {
+			const name = who.trim().replace(/^@/, "");
+			if (name.includes("@")) {
+				if (!EMAIL.test(name)) throw new EditorsError("invalid", "That isn't an email address.");
+				const result = await gitlabJson(api, `${base}/invitations`, {
+					method: "POST",
+					body: {
+						email: name,
+						access_level: levelOf(role)
+					}
+				}).catch(notAllowed$1);
+				if (result.status !== "success") {
+					const message = typeof result.message === "string" ? result.message : Object.values(result.message ?? {})[0];
+					if (/already/i.test(message ?? "")) throw new EditorsError("already", "They've already been invited.");
+					throw new EditorsError("invalid", `GitLab didn't accept the invitation: ${message ?? result.status}`);
+				}
+				return;
+			}
+			if (!USERNAME.test(name)) throw new EditorsError("invalid", "That isn't a GitLab username or email address.");
+			const [user] = await gitlabJson(api, `/users?${new URLSearchParams({ username: name })}`);
+			if (!user) throw new EditorsError("not-found", `There's no GitLab account named ${name}.`);
+			try {
+				await gitlabRequest(api, `${base}/members`, {
+					method: "POST",
+					body: {
+						user_id: user.id,
+						access_level: levelOf(role)
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && error.status === 409) throw new EditorsError("already", `${name} already edits the site.`);
+				notAllowed$1(error);
+			}
+		},
+		async setRole(editor, role) {
+			await gitlabRequest(api, editor.id.startsWith(INVITATION) ? `${base}/invitations/${encodeURIComponent(editor.id.slice(11))}` : `${base}/members/${editor.id.slice(7)}`, {
+				method: "PUT",
+				body: { access_level: levelOf(role) }
+			}).catch(notAllowed$1);
+		},
+		async remove(editor) {
+			await gitlabRequest(api, editor.id.startsWith(INVITATION) ? `${base}/invitations/${encodeURIComponent(editor.id.slice(11))}` : `${base}/members/${editor.id.slice(7)}`, { method: "DELETE" }).catch(notAllowed$1);
+		},
+		async letEditorsPublish() {
+			const protect = (level) => gitlabRequest(api, `${base}/protected_branches`, {
+				method: "POST",
+				body: {
+					name: branch,
+					push_access_level: level,
+					merge_access_level: MAINTAINER,
+					allow_force_push: false
+				}
+			});
+			await gitlabRequest(api, protectedPath, {
+				method: "DELETE",
+				allow: [404]
+			}).catch(notAllowed$1);
+			try {
+				await protect(DEVELOPER);
+			} catch (error) {
+				await protect(MAINTAINER).catch(() => void 0);
+				notAllowed$1(error);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/pages.ts
+/** GitLab.com Pages' addresses for an apex domain, from GitLab's documentation. */
+const PAGES_IPV4 = "35.185.44.232";
+const PAGES_IPV6 = "2600:1901:0:7b8a::";
+/** The domains `connect()` adds: the domain, and `www.` for an apex domain that wants it. */
+function domainsFor(domain, { apex, www }) {
+	return apex && www ? [domain, `www.${domain}`] : [domain];
+}
+/**
+* The records GitLab Pages needs: its address for an apex domain, or an alias
+* of the namespace's gitlab.io otherwise, and a TXT record per domain that
+* proves it's the owner's, with the codes GitLab gave.
+*/
+function gitlabPagesRecords(project, domain, options, codes) {
+	const target = `${(project.split("/")[0] ?? "").toLowerCase()}.gitlab.io`;
+	const site = options.apex ? [{
+		type: "A",
+		name: domain,
+		value: PAGES_IPV4,
+		purpose: "site"
+	}, {
+		type: "AAAA",
+		name: domain,
+		value: PAGES_IPV6,
+		purpose: "site",
+		optional: true
+	}] : [{
+		type: "CNAME",
+		name: domain,
+		value: target,
+		purpose: "site"
+	}];
+	const www = options.apex && options.www ? [{
+		type: "CNAME",
+		name: `www.${domain}`,
+		value: target,
+		purpose: "www",
+		optional: true
+	}] : [];
+	const verification = domainsFor(domain, options).flatMap((name) => {
+		const code = codes[name];
+		if (!code) return [];
+		const value = code.startsWith("gitlab-pages-verification-code=") ? code : `gitlab-pages-verification-code=${code}`;
+		return [{
+			type: "TXT",
+			name: `_gitlab-pages-verification-code.${name}`,
+			value,
+			purpose: "verification",
+			optional: name !== domain
+		}];
+	});
+	return [
+		...site,
+		...www,
+		...verification
+	];
+}
+/** GitLab Pages, for a site's project: where it's published, and its custom domains. */
+function gitlabPages(api, project) {
+	const pagesPath = `/projects/${encodeURIComponent(project)}/pages`;
+	const domainPath = (domain) => `${pagesPath}/domains/${encodeURIComponent(domain)}`;
+	function notAllowed(error) {
+		if (error instanceof GitApiError && (error.status === 401 || error.status === 403)) throw new DomainError("not-allowed", "Connecting a domain on GitLab needs the Maintainer role in the project.");
+		throw error;
+	}
+	async function pages() {
+		const response = await gitlabRequest(api, pagesPath, { allow: [404] }).catch(notAllowed);
+		return response.ok ? await response.json() : void 0;
+	}
+	async function codes(domains) {
+		const found = await Promise.all(domains.map(async (domain) => {
+			const response = await gitlabRequest(api, domainPath(domain), { allow: [404] });
+			if (!response.ok) return [domain, ""];
+			return [domain, (await response.json()).verification_code ?? ""];
+		}));
+		return Object.fromEntries(found);
+	}
+	async function verified(domain) {
+		const found = await gitlabJson(api, domainPath(domain)).catch(notAllowed);
+		if (found.verified) return found;
+		const response = await gitlabRequest(api, `${domainPath(domain)}/verify`, {
+			method: "PUT",
+			allow: [
+				400,
+				404,
+				422
+			]
+		});
+		return response.ok ? await response.json() : found;
+	}
+	return {
+		async site() {
+			const found = await pages();
+			if (!found) return void 0;
+			const names = (await gitlabJson(api, `${pagesPath}/domains`).catch(() => [])).map((entry) => entry.domain);
+			const domain = (found.primary_domain && names.includes(found.primary_domain) ? found.primary_domain : void 0) ?? names.sort((a, b) => a.length - b.length)[0];
+			return {
+				url: found.url,
+				domain
+			};
+		},
+		async connect(domain, options) {
+			const found = await pages();
+			if (found && found.is_unique_domain_enabled === false) await gitlabRequest(api, pagesPath, {
+				method: "PATCH",
+				body: { pages_unique_domain_enabled: true }
+			}).catch(notAllowed);
+			for (const name of domainsFor(domain, options)) try {
+				await gitlabRequest(api, `${pagesPath}/domains`, {
+					method: "POST",
+					body: {
+						domain: name,
+						auto_ssl_enabled: true
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && error.status === 400) {
+					if (/taken/i.test(error.message)) {
+						if ((await gitlabRequest(api, domainPath(name), { allow: [404] })).ok) continue;
+						throw new DomainError("taken", "Another GitLab Pages site already uses this domain.");
+					}
+					throw new DomainError("invalid", "GitLab Pages doesn't accept this domain.");
+				}
+				notAllowed(error);
+			}
+			return gitlabPagesRecords(project, domain, options, await codes(domainsFor(domain, options)));
+		},
+		async records(domain, options) {
+			return gitlabPagesRecords(project, domain, options, await codes(domainsFor(domain, options)));
+		},
+		async status(domain) {
+			const found = await verified(domain);
+			const www = await gitlabRequest(api, domainPath(`www.${domain}`), { allow: [404] });
+			if (www.ok && !(await www.json()).verified) await verified(`www.${domain}`);
+			const settings = await pages();
+			return {
+				verified: found.verified,
+				certificate: found.certificate && !found.certificate.expired ? "ready" : "pending",
+				httpsOnly: settings?.force_https === true,
+				primary: settings?.primary_domain === void 0 || settings.primary_domain === domain
+			};
+		},
+		async secure(domain) {
+			const found = await gitlabJson(api, domainPath(domain)).catch(notAllowed);
+			if (!found.verified || !found.certificate) throw new DomainError("not-ready", "The domain's certificate isn't ready yet.");
+			try {
+				await gitlabRequest(api, pagesPath, {
+					method: "PATCH",
+					body: {
+						pages_https_only: true,
+						pages_primary_domain: domain
+					}
+				});
+			} catch (error) {
+				if (!(error instanceof GitApiError && error.status === 400)) notAllowed(error);
+				await gitlabRequest(api, pagesPath, {
+					method: "PATCH",
+					body: { pages_https_only: true }
+				}).catch(notAllowed);
+			}
+		},
+		async disconnect(domain) {
+			for (const name of [domain, `www.${domain}`]) await gitlabRequest(api, domainPath(name), {
+				method: "DELETE",
+				allow: [404]
+			}).catch(notAllowed);
+		}
+	};
+}
+//#endregion
+//#region src/updates.ts
+const CI_FILE = ".gitlab-ci.yml";
+/** When the nightly schedule the Updates screen adds runs, in UTC, as the GitHub Pages workflow's does. */
+const NIGHTLY = "17 4 * * *";
+function notAllowed(error) {
+	if (error instanceof GitApiError && (error.status === 401 || error.status === 403)) throw new UpdatesError("not-allowed", "Setting up updates on GitLab needs the Maintainer role in the project.");
+	throw error;
+}
+/**
+* The site's nightly update, which runs in its GitLab Pages job on scheduled
+* pipelines, and on pipelines the Updates screen starts with `GOODFELLOW_UPDATE`.
+* It publishes with the job's own token, which GitLab only allows once the
+* project lets job tokens push.
+*/
+function gitlabUpdates(api, project, branch, readAt) {
+	const base = `/projects/${encodeURIComponent(project)}`;
+	async function schedules() {
+		return gitlabJson(api, `${base}/pipeline_schedules`);
+	}
+	return {
+		async setup() {
+			if (!(await readAt(CI_FILE))?.includes("update --publish")) return "missing";
+			try {
+				const [settings, found] = await Promise.all([gitlabJson(api, base), schedules()]);
+				const scheduled = found.some((schedule) => schedule.active && (schedule.ref === branch || schedule.ref === `refs/heads/${branch}`));
+				return settings.ci_push_repository_for_job_token_allowed && scheduled ? "ready" : "needs-setup";
+			} catch (error) {
+				if (error instanceof GitApiError && error.status === 403) return "needs-setup";
+				throw error;
+			}
+		},
+		async enable() {
+			await gitlabRequest(api, base, {
+				method: "PUT",
+				body: { ci_push_repository_for_job_token_allowed: true }
+			}).catch(notAllowed);
+			if (!(await schedules().catch(notAllowed)).some((schedule) => schedule.active && schedule.ref.endsWith(branch))) await gitlabRequest(api, `${base}/pipeline_schedules`, {
+				method: "POST",
+				body: {
+					description: "Rebuild the site and install Goodfellow's fixes each night",
+					ref: branch,
+					cron: NIGHTLY,
+					cron_timezone: "UTC",
+					active: true
+				}
+			}).catch(notAllowed);
+		},
+		async lastRun() {
+			const pipelines = await gitlabJson(api, `${base}/pipelines?${new URLSearchParams({
+				ref: branch,
+				per_page: "20"
+			})}`);
+			for (const pipeline of pipelines) {
+				if (pipeline.source !== "schedule" && pipeline.source !== "api") continue;
+				const run = {
+					date: pipeline.created_at,
+					detailsUrl: pipeline.web_url
+				};
+				if ([
+					"created",
+					"pending",
+					"running",
+					"waiting_for_resource",
+					"preparing"
+				].includes(pipeline.status)) return {
+					state: "running",
+					...run
+				};
+				const job = (await gitlabJson(api, `${base}/pipelines/${pipeline.id}/jobs?per_page=100`)).find((candidate) => candidate.name === "pages");
+				if (!job) continue;
+				const response = await gitlabRequest(api, `${base}/jobs/${job.id}/trace`, { allow: [403, 404] });
+				const result = response.ok ? findUpdateResult(await response.text()) : void 0;
+				if (!result) continue;
+				return {
+					state: result.state,
+					result,
+					...run
+				};
+			}
+		},
+		async start(target) {
+			await gitlabRequest(api, `${base}/pipeline`, {
+				method: "POST",
+				body: {
+					ref: branch,
+					variables: [{
+						key: "GOODFELLOW_UPDATE",
+						variable_type: "env_var",
+						value: target
+					}]
+				}
+			}).catch(notAllowed);
+		}
+	};
+}
+//#endregion
+//#region src/backend.ts
+const PAGE_SIZE = 100;
+/** The color and section codes in GitLab's job logs. */
+const ANSI_CODES = new RegExp(`${String.fromCharCode(27)}\\[[\\d;]*[A-Za-z]`, "g");
+/**
+* The site's files on GitLab. Reads come from the commit `revision()` last
+* returned. Saves are single commits; each changed file carries the commit it
+* was last changed in, so GitLab refuses to overwrite anyone else's edits.
+*/
+var GitLabBackend = class {
+	user;
+	pages;
+	editors;
+	updates;
+	api;
+	project;
+	branch;
+	onSignOut;
+	pinned;
+	trees = /* @__PURE__ */ new Map();
+	blobs = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.api = options.api;
+		this.project = encodeURIComponent(options.project);
+		this.branch = options.branch;
+		this.user = options.user;
+		this.onSignOut = options.onSignOut;
+		this.pages = gitlabPages(this.api, options.project);
+		this.editors = gitlabEditors(this.api, options.project, this.branch, this.user.login);
+		this.updates = gitlabUpdates(this.api, options.project, this.branch, async (path) => this.readAt(path, this.pinned ?? await this.revision()));
+	}
+	repo(path) {
+		return `/projects/${this.project}/repository${path}`;
+	}
+	async revision() {
+		const branch = await gitlabJson(this.api, this.repo(`/branches/${encodeURIComponent(this.branch)}`));
+		this.pinned = branch.commit.id;
+		return this.pinned;
+	}
+	/** Every file in one folder at a commit, page by page. */
+	async listFolder(sha, dir) {
+		const files = [];
+		for (let page = 1;; page++) {
+			const query = new URLSearchParams({
+				ref: sha,
+				path: dir,
+				recursive: "true",
+				per_page: String(PAGE_SIZE),
+				page: String(page)
+			});
+			const response = await gitlabRequest(this.api, this.repo(`/tree?${query}`), { allow: [404] });
+			if (response.status === 404) return files;
+			const entries = await response.json();
+			for (const entry of entries) if (entry.type === "blob") files.push([entry.path, entry.id]);
+			if (entries.length < PAGE_SIZE) return files;
+		}
+	}
+	/** Path → blob id for the editable files at a commit. Commits never change, so this is cached. */
+	tree(sha) {
+		let tree = this.trees.get(sha);
+		if (!tree) {
+			tree = Promise.all(EDITABLE_FOLDERS.map((folder) => this.listFolder(sha, folder))).then((folders) => new Map(folders.flat()));
+			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) {
+		const sha = (await this.currentTree()).get(path);
+		if (!sha) return void 0;
+		let blob = this.blobs.get(sha);
+		if (!blob) {
+			blob = gitlabRequest(this.api, this.repo(`/blobs/${sha}/raw`)).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 gitlabRequest(this.api, this.repo(`/blobs/${sha}/raw`));
+		return new Uint8Array(await response.arrayBuffer());
+	}
+	async list(dir) {
+		const prefix = `${dir}/`;
+		return [...(await this.currentTree()).keys()].filter((path) => path.startsWith(prefix)).sort();
+	}
+	async lastCommitFor(path, ref) {
+		return (await gitlabJson(this.api, this.repo(`/files/${encodeURIComponent(path)}?ref=${ref}`))).last_commit_id;
+	}
+	async write(changes, { message, expectedRevision }) {
+		if (await this.revision() !== expectedRevision) throw new ConflictError();
+		const existing = await this.tree(expectedRevision);
+		const toApply = (await Promise.all(changes.map(async (change) => {
+			const exists = existing.has(change.path);
+			if ("delete" in change) return exists ? {
+				action: "delete",
+				file_path: change.path,
+				last_commit_id: await this.lastCommitFor(change.path, expectedRevision)
+			} : void 0;
+			const content = "bytes" in change ? {
+				content: encodeBase64Bytes(change.bytes),
+				encoding: "base64"
+			} : { content: change.content };
+			return exists ? {
+				action: "update",
+				file_path: change.path,
+				...content,
+				last_commit_id: await this.lastCommitFor(change.path, expectedRevision)
+			} : {
+				action: "create",
+				file_path: change.path,
+				...content
+			};
+		}))).filter((action) => action !== void 0);
+		if (toApply.length === 0) return { revision: expectedRevision };
+		try {
+			const commit = await gitlabJson(this.api, this.repo("/commits"), {
+				method: "POST",
+				body: {
+					branch: this.branch,
+					commit_message: message,
+					actions: toApply
+				}
+			});
+			this.pinned = commit.id;
+			return { revision: commit.id };
+		} catch (error) {
+			if (!(error instanceof GitApiError)) throw error;
+			if (error.status === 403) throw new SignInError("cant-publish", "This GitLab account can't publish to the site.");
+			if (error.status === 400 && /already exists|changed since/i.test(error.message) || await this.revision() !== expectedRevision) throw new ConflictError();
+			throw error;
+		}
+	}
+	async history(path, { page = 1, perPage = 20 } = {}) {
+		const query = new URLSearchParams({
+			ref_name: this.pinned ?? await this.revision(),
+			path,
+			per_page: String(perPage),
+			page: String(page)
+		});
+		return (await gitlabJson(this.api, this.repo(`/commits?${query}`))).map((commit) => ({
+			revision: commit.id,
+			date: commit.authored_date ?? commit.committed_date ?? "",
+			author: commit.author_name || void 0,
+			message: commit.title
+		}));
+	}
+	async readAt(path, revision) {
+		const response = await gitlabRequest(this.api, this.repo(`/files/${encodeURIComponent(path)}/raw?${new URLSearchParams({ ref: revision })}`), { allow: [404] });
+		return response.ok ? response.text() : void 0;
+	}
+	async changedPaths(from, to) {
+		const comparison = await gitlabJson(this.api, this.repo(`/compare?${new URLSearchParams({
+			from,
+			to,
+			straight: "true"
+		})}`));
+		return [...new Set((comparison.diffs ?? []).flatMap((diff) => [diff.old_path, diff.new_path]))];
+	}
+	/**
+	* Reads the commit's pipeline and external statuses (GitLab Pages jobs, or
+	* Vercel). Before any exist, the site counts as building if it has pipelines.
+	*/
+	async deployStatus(revision) {
+		try {
+			const statuses = await gitlabJson(this.api, this.repo(`/commits/${revision}/statuses`));
+			if (statuses.length === 0) return { state: (await gitlabJson(this.api, `/projects/${this.project}/pipelines?per_page=1`)).length > 0 ? "building" : "unknown" };
+			const failed = statuses.find((status) => status.status === "failed" || status.status === "canceled");
+			if (failed) {
+				const problem = await this.jobProblem(revision).catch(() => void 0);
+				return {
+					state: "failed",
+					detailsUrl: failed.target_url ?? void 0,
+					...problem && { problem }
+				};
+			}
+			if (statuses.every((status) => status.status === "success" || status.status === "skipped")) return {
+				state: "live",
+				detailsUrl: statuses[0]?.target_url ?? void 0
+			};
+			return {
+				state: "building",
+				detailsUrl: statuses[0]?.target_url ?? void 0
+			};
+		} catch (error) {
+			if (error instanceof GitApiError) return { state: "unknown" };
+			throw error;
+		}
+	}
+	/** Why a commit's pipeline failed: the failed job's reason, and its log for which command failed and why. */
+	async jobProblem(revision) {
+		const [pipeline] = await gitlabJson(this.api, `/projects/${this.project}/pipelines?${new URLSearchParams({
+			sha: revision,
+			per_page: "1"
+		})}`);
+		if (!pipeline) return void 0;
+		const failed = (await gitlabJson(this.api, `/projects/${this.project}/pipelines/${pipeline.id}/jobs?per_page=100`)).find((job) => job.status === "failed");
+		if (!failed) return void 0;
+		const reason = failed.failure_reason ?? "";
+		const detail = `${failed.name}: ${reason}`;
+		if (reason === "ci_quota_exceeded") return {
+			step: "not-started",
+			detail
+		};
+		if (/runner_system|stuck_or_timeout|scheduler|api_failure|data_integrity|job_execution_timeout/.test(reason)) return {
+			step: "host",
+			detail
+		};
+		if (failed.name === "pages:deploy") return {
+			step: "deploy",
+			detail
+		};
+		const response = await gitlabRequest(this.api, `/projects/${this.project}/jobs/${failed.id}/trace`, { allow: [403, 404] });
+		const trace = response.ok ? await response.text() : "";
+		const cause = findBuildCause(trace);
+		const command = trace.split("\n").map((line) => line.replace(ANSI_CODES, "").replace(/^.*\r/, "")).filter((line) => line.startsWith("$ ")).at(-1);
+		return {
+			step: cause ? "build" : (command ? buildStepFor(command) : void 0) ?? "build",
+			detail,
+			...cause && { cause }
+		};
+	}
+	signOut() {
+		this.onSignOut();
+	}
+};
+//#endregion
+//#region src/oauth.ts
+/** OAuth 2.0 with PKCE: lets the browser sign in to GitLab without any server or client secret. */
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomString(bytes = 32) {
+	return base64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+async function codeChallenge(verifier) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return base64Url(new Uint8Array(digest));
+}
+function toTokens(response, verifier, now = Date.now()) {
+	return {
+		type: "oauth",
+		access: response.access_token,
+		refresh: response.refresh_token,
+		expiresAt: now + (response.expires_in ?? 7200) * 1e3,
+		verifier
+	};
+}
+/** The admin panel's address, with a trailing slash so it always matches the redirect URI registered with GitLab. */
+function redirectUri(href) {
+	const url = new URL(href);
+	return `${url.origin}${url.pathname.replace(/\/?$/, "/")}`;
+}
+//#endregion
+//#region src/setup.ts
+/** The branch the deploy setups build from. */
+const MAIN = "main";
+function browserLocation$1() {
+	return {
+		href: () => window.location.href,
+		assign: (url) => window.location.assign(url),
+		replace: (url) => window.history.replaceState(window.history.state, "", url)
+	};
+}
+/** Signing in to GitLab to create a site's project, with GitLab Pages if wanted. */
+function gitlabSetup(options = {}) {
+	const webUrl = (options.url ?? "https://gitlab.com").replace(/\/$/, "");
+	const apiUrl = `${webUrl}/api/v4`;
+	const fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const pending = credentialStorage("goodfellow:gitlab-setup:pending", options.storage);
+	const location = () => options.location ?? browserLocation$1();
+	async function requestTokens(params) {
+		const response = await fetcher(`${webUrl}/oauth/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams(params)
+		});
+		if (!response.ok) throw new SignInError("invalid", `GitLab didn't accept the sign-in (${response.status}).`);
+		return await response.json();
+	}
+	async function connect(initial) {
+		let credentials = initial;
+		const token = async ({ refresh } = {}) => {
+			if (credentials.type === "token") return credentials.token;
+			if (refresh || credentials.expiresAt - 6e4 < Date.now()) {
+				const { verifier } = credentials;
+				credentials = toTokens(await requestTokens({
+					client_id: options.clientId ?? "",
+					refresh_token: credentials.refresh,
+					grant_type: "refresh_token",
+					redirect_uri: redirectUri(location().href()),
+					code_verifier: verifier
+				}), verifier);
+			}
+			return credentials.access;
+		};
+		const api = {
+			apiUrl,
+			token,
+			canRefresh: credentials.type === "oauth",
+			fetch: fetcher
+		};
+		const user = await gitlabJson(api, "/user");
+		async function isAvailable(owner, name) {
+			return (await gitlabRequest(api, `/projects/${encodeURIComponent(`${owner.path}/${name}`)}`, { allow: [404] })).status === 404;
+		}
+		return {
+			user: {
+				login: user.username,
+				name: user.name,
+				avatarUrl: user.avatar_url
+			},
+			async owners() {
+				const owners = (await gitlabJson(api, "/namespaces?per_page=100")).map((namespace) => ({
+					path: namespace.full_path,
+					name: namespace.kind === "user" ? user.name ?? namespace.name : namespace.name,
+					kind: namespace.kind === "user" ? "personal" : "organization",
+					id: namespace.id
+				}));
+				return [...owners.filter((owner) => owner.kind === "personal"), ...owners.filter((o) => o.kind !== "personal")];
+			},
+			isAvailable,
+			async createSite(site, onStep) {
+				onStep?.("repository");
+				if (!await isAvailable(site.owner, site.name)) throw new SetupError("name-taken", `There's already a project called ${site.owner.path}/${site.name}.`);
+				let project;
+				try {
+					project = await gitlabJson(api, "/projects", {
+						method: "POST",
+						body: {
+							name: site.name,
+							path: site.name,
+							namespace_id: site.owner.id,
+							visibility: site.private ? "private" : "public",
+							description: site.description,
+							...site.pages && { pages_access_level: site.private ? "public" : "enabled" }
+						}
+					});
+				} catch (error) {
+					if (error instanceof GitApiError && error.status === 400) throw new SetupError("name-invalid", `GitLab can't use "${site.name}" as a project name.`);
+					if (error instanceof GitApiError && (error.status === 403 || error.status === 404)) throw new SetupError("not-allowed", `This sign-in can't create projects in ${site.owner.path}.`);
+					throw error;
+				}
+				onStep?.("files");
+				await gitlabRequest(api, `/projects/${project.id}/repository/commits`, {
+					method: "POST",
+					body: {
+						branch: MAIN,
+						commit_message: site.message,
+						actions: site.files.flatMap((file) => "delete" in file ? [] : "content" in file ? [{
+							action: "create",
+							file_path: file.path,
+							content: file.content
+						}] : [{
+							action: "create",
+							file_path: file.path,
+							content: encodeBase64Bytes(file.bytes),
+							encoding: "base64"
+						}])
+					}
+				});
+				return {
+					repo: project.path_with_namespace,
+					webUrl: project.web_url,
+					buildsUrl: `${project.web_url}/-/pipelines`,
+					pagesUrl: site.pages ? `${project.web_url}/pages` : void 0,
+					warnings: []
+				};
+			}
+		};
+	}
+	return {
+		name: "GitLab",
+		canRedirect: Boolean(options.clientId),
+		tokenLinks: [{
+			url: `${webUrl}/-/user_settings/personal_access_tokens?${new URLSearchParams({
+				name: "Goodfellow site setup",
+				scopes: "api"
+			})}`,
+			label: "signIn.token.create"
+		}],
+		async restore() {
+			const url = new URL(location().href());
+			const code = url.searchParams.get("code");
+			const error = url.searchParams.get("error");
+			if (!code && !error) return null;
+			const saved = pending.load();
+			if (!saved) return null;
+			pending.clear();
+			const redirect = JSON.parse(saved);
+			const returnedState = url.searchParams.get("state");
+			for (const key of [
+				"code",
+				"state",
+				"error",
+				"error_description"
+			]) url.searchParams.delete(key);
+			location().replace(url.toString());
+			if (error || !code || returnedState !== redirect.state) throw new SignInError("redirect-failed", "Signing in with GitLab was cancelled or didn't finish.");
+			return connect(toTokens(await requestTokens({
+				client_id: options.clientId ?? "",
+				code,
+				grant_type: "authorization_code",
+				redirect_uri: redirectUri(url.toString()),
+				code_verifier: redirect.verifier
+			}), redirect.verifier));
+		},
+		async signInWithToken(token) {
+			const trimmed = token.trim();
+			if (!trimmed) throw new SignInError("invalid", "Paste a token to sign in.");
+			return connect({
+				type: "token",
+				token: trimmed
+			});
+		},
+		async startRedirect() {
+			if (!options.clientId) throw new Error("gitlabSetup({ clientId }) is needed to sign in with GitLab.");
+			const redirect = {
+				state: randomString(16),
+				verifier: randomString(48)
+			};
+			pending.save(JSON.stringify(redirect), false);
+			const query = new URLSearchParams({
+				client_id: options.clientId,
+				redirect_uri: redirectUri(location().href()),
+				response_type: "code",
+				state: redirect.state,
+				scope: "api",
+				code_challenge: await codeChallenge(redirect.verifier),
+				code_challenge_method: "S256"
+			});
+			location().assign(`${webUrl}/oauth/authorize?${query}`);
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const MIN_ACCESS_LEVEL_TO_PUBLISH = 30;
+function browserLocation() {
+	return {
+		href: () => window.location.href,
+		assign: (url) => window.location.assign(url),
+		replace: (url) => window.history.replaceState(window.history.state, "", url)
+	};
+}
+/** Sign-in and storage for a site whose repository is on GitLab. */
+function gitlab(options) {
+	const webUrl = (options.url ?? "https://gitlab.com").replace(/\/$/, "");
+	const apiUrl = `${webUrl}/api/v4`;
+	const fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const storage = credentialStorage(`goodfellow:gitlab:${webUrl}:${options.project}`, options.storage);
+	const pending = credentialStorage(`goodfellow:gitlab:pending:${options.project}`, options.storage);
+	const location = () => options.location ?? browserLocation();
+	async function requestTokens(params) {
+		const response = await fetcher(`${webUrl}/oauth/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams(params)
+		});
+		if (!response.ok) throw new SignInError("invalid", `GitLab didn't accept the sign-in (${response.status}).`);
+		return await response.json();
+	}
+	async function connect(initial, remember) {
+		let credentials = initial;
+		const token = async ({ refresh } = {}) => {
+			if (credentials.type === "token") return credentials.token;
+			if (refresh || credentials.expiresAt - 6e4 < Date.now()) {
+				const { verifier } = credentials;
+				credentials = toTokens(await requestTokens({
+					client_id: options.clientId ?? "",
+					refresh_token: credentials.refresh,
+					grant_type: "refresh_token",
+					redirect_uri: redirectUri(location().href()),
+					code_verifier: verifier
+				}), verifier);
+				storage.save(JSON.stringify(credentials), remember);
+			}
+			return credentials.access;
+		};
+		const api = {
+			apiUrl,
+			token,
+			canRefresh: credentials.type === "oauth",
+			fetch: fetcher
+		};
+		const user = await gitlabJson(api, "/user");
+		let project;
+		try {
+			project = await gitlabJson(api, `/projects/${encodeURIComponent(options.project)}`);
+		} catch (error) {
+			if (error instanceof GitApiError && (error.status === 404 || error.status === 403)) throw new SignInError("no-access", `The GitLab account ${user.username} can't see ${options.project}.`);
+			throw error;
+		}
+		if (Math.max(project.permissions?.project_access?.access_level ?? 0, project.permissions?.group_access?.access_level ?? 0) < MIN_ACCESS_LEVEL_TO_PUBLISH) throw new SignInError("cant-publish", `The GitLab account ${user.username} can see ${options.project} but can't publish to it.`);
+		storage.save(JSON.stringify(credentials), remember);
+		return new GitLabBackend({
+			api,
+			project: options.project,
+			branch: options.branch ?? project.default_branch,
+			user: {
+				login: user.username,
+				name: user.name,
+				avatarUrl: user.avatar_url
+			},
+			onSignOut: () => storage.clear()
+		});
+	}
+	/** Finishes a redirect sign-in if the page has just come back from GitLab. */
+	async function completeRedirect() {
+		const url = new URL(location().href());
+		const code = url.searchParams.get("code");
+		const returnedState = url.searchParams.get("state");
+		const error = url.searchParams.get("error");
+		if (!code && !error) return null;
+		const saved = pending.load();
+		if (!saved) return null;
+		pending.clear();
+		const redirect = JSON.parse(saved);
+		for (const key of [
+			"code",
+			"state",
+			"error",
+			"error_description"
+		]) url.searchParams.delete(key);
+		url.hash = redirect.hash;
+		location().replace(url.toString());
+		if (error || !code || returnedState !== redirect.state) throw new SignInError("redirect-failed", "Signing in with GitLab was cancelled or didn't finish.");
+		return connect(toTokens(await requestTokens({
+			client_id: options.clientId ?? "",
+			code,
+			grant_type: "authorization_code",
+			redirect_uri: redirectUri(url.toString()),
+			code_verifier: redirect.verifier
+		}), redirect.verifier), redirect.remember);
+	}
+	return {
+		name: "GitLab",
+		canRedirect: Boolean(options.clientId),
+		tokenLinks: [{
+			url: `${webUrl}/-/user_settings/personal_access_tokens?${new URLSearchParams({
+				name: "Goodfellow admin",
+				scopes: "api"
+			})}`,
+			label: "signIn.token.create"
+		}],
+		async restore() {
+			const redirected = await completeRedirect();
+			if (redirected) return redirected;
+			const saved = storage.load();
+			if (!saved) return null;
+			try {
+				return await connect(JSON.parse(saved), storage.remembered());
+			} 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.");
+			return connect({
+				type: "token",
+				token: trimmed
+			}, remember);
+		},
+		async startRedirect(remember) {
+			if (!options.clientId) throw new Error("gitlab({ clientId }) is needed to sign in with GitLab.");
+			const verifier = randomString(48);
+			const state = randomString(16);
+			const here = new URL(location().href());
+			const redirect = {
+				state,
+				verifier,
+				remember,
+				hash: here.hash
+			};
+			pending.save(JSON.stringify(redirect), false);
+			const query = new URLSearchParams({
+				client_id: options.clientId,
+				redirect_uri: redirectUri(here.toString()),
+				response_type: "code",
+				state,
+				scope: "api",
+				code_challenge: await codeChallenge(verifier),
+				code_challenge_method: "S256"
+			});
+			location().assign(`${webUrl}/oauth/authorize?${query}`);
+		}
+	};
+}
+//#endregion
+export { GitLabBackend, gitlab, gitlabPagesRecords, gitlabSetup, redirectUri };