@goodfellow-cms/gitlab 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ConflictError, EDITABLE_FOLDERS, GitApiError, SignInError, credentialStorage, encodeBase64Bytes } from "@goodfellow-cms/core";
+import { ConflictError, DomainError, DraftError, EDITABLE_FOLDERS, EditorsError, GitApiError, SetupError, SignInError, UpdatesError, branchDrafts, 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 = {}) {
@@ -25,15 +25,424 @@ 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;
+/** How many files one GraphQL request reads. */
+const GRAPHQL_BATCH = 50;
+/** 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 {
+var GitLabBackend = class GitLabBackend {
 	user;
+	pages;
+	editors;
+	updates;
+	drafts;
+	options;
 	api;
 	project;
 	branch;
@@ -42,11 +451,76 @@ var GitLabBackend = class {
 	trees = /* @__PURE__ */ new Map();
 	blobs = /* @__PURE__ */ new Map();
 	constructor(options) {
+		this.options = 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()));
+		this.drafts = branchDrafts(this, this.draftHost());
+	}
+	/** Drafts on branches of the project, with merge requests for review. */
+	draftHost() {
+		const project = `/projects/${this.project}`;
+		return {
+			liveBranch: this.branch,
+			branchStore: (branch) => new GitLabBackend({
+				...this.options,
+				branch
+			}),
+			createBranch: async (branch, revision) => {
+				if ((await gitlabRequest(this.api, this.repo(`/branches?${new URLSearchParams({
+					branch,
+					ref: revision
+				})}`), {
+					method: "POST",
+					allow: [400]
+				})).status === 400) throw new DraftError("exists", `There's already a draft called ${branch}.`);
+			},
+			deleteBranch: async (branch) => {
+				await gitlabRequest(this.api, this.repo(`/branches/${encodeURIComponent(branch)}`), {
+					method: "DELETE",
+					allow: [404]
+				});
+			},
+			mergeBase: async (branch) => {
+				const query = new URLSearchParams();
+				query.append("refs[]", this.branch);
+				query.append("refs[]", branch);
+				const response = await gitlabRequest(this.api, this.repo(`/merge_base?${query}`), { allow: [400, 404] });
+				if (!response.ok) throw new DraftError("not-found", `There's no draft ${branch}.`);
+				return (await response.json()).id;
+			},
+			openReview: async ({ branch, title, description }) => {
+				const response = await gitlabRequest(this.api, `${project}/merge_requests`, {
+					method: "POST",
+					body: {
+						source_branch: branch,
+						target_branch: this.branch,
+						title,
+						description,
+						remove_source_branch: true
+					},
+					allow: [
+						403,
+						404,
+						409
+					]
+				});
+				if (response.ok) return { url: (await response.json()).web_url };
+				if (response.status !== 409) throw new DraftError("no-reviews", "This sign-in can't open merge requests on the site's project.");
+				const query = new URLSearchParams({
+					source_branch: branch,
+					state: "opened"
+				});
+				const [open] = await gitlabJson(this.api, `${project}/merge_requests?${query}`);
+				if (!open) throw new GitApiError(409, "GitLab couldn't open the merge request.");
+				return { url: open.web_url };
+			}
+		};
 	}
 	repo(path) {
 		return `/projects/${this.project}/repository${path}`;
@@ -98,6 +572,39 @@ var GitLabBackend = class {
 		}
 		return blob;
 	}
+	/** Reads many text files in a few GraphQL requests rather than one request each. */
+	async readFiles(paths) {
+		const tree = await this.currentTree();
+		const wanted = paths.filter((path) => tree.has(path));
+		const fetch = wanted.filter((path) => !this.blobs.has(tree.get(path) ?? ""));
+		const ref = this.pinned ?? await this.revision();
+		for (let start = 0; start < fetch.length; start += GRAPHQL_BATCH) {
+			const batch = fetch.slice(start, start + GRAPHQL_BATCH);
+			const response = await gitlabJson(this.api, "/../graphql", {
+				method: "POST",
+				body: {
+					query: `query ($project: ID!, $ref: String!, $paths: [String!]!) {
+  project(fullPath: $project) { repository { blobs(ref: $ref, paths: $paths) { nodes { path rawTextBlob } } } }
+}`,
+					variables: {
+						project: decodeURIComponent(this.project),
+						ref,
+						paths: batch
+					}
+				}
+			});
+			for (const node of response.data?.project?.repository?.blobs?.nodes ?? []) {
+				const sha = tree.get(node.path);
+				if (sha && typeof node.rawTextBlob === "string") this.blobs.set(sha, Promise.resolve(node.rawTextBlob));
+			}
+		}
+		const result = /* @__PURE__ */ new Map();
+		for (const path of wanted) {
+			const text = await this.read(path);
+			if (text !== void 0) result.set(path, text);
+		}
+		return result;
+	}
 	async readBytes(path) {
 		const sha = (await this.currentTree()).get(path);
 		if (!sha) return void 0;
@@ -108,6 +615,32 @@ var GitLabBackend = class {
 		const prefix = `${dir}/`;
 		return [...(await this.currentTree()).keys()].filter((path) => path.startsWith(prefix)).sort();
 	}
+	/** GitLab's tree doesn't say how large files are, so they're asked for with GraphQL, in batches. */
+	async fileSizes(dir) {
+		const paths = await this.list(dir);
+		const ref = this.pinned ?? await this.revision();
+		const sizes = /* @__PURE__ */ new Map();
+		for (let start = 0; start < paths.length; start += GRAPHQL_BATCH) {
+			const response = await gitlabJson(this.api, "/../graphql", {
+				method: "POST",
+				body: {
+					query: `query ($project: ID!, $ref: String!, $paths: [String!]!) {
+  project(fullPath: $project) { repository { blobs(ref: $ref, paths: $paths) { nodes { path size } } } }
+}`,
+					variables: {
+						project: decodeURIComponent(this.project),
+						ref,
+						paths: paths.slice(start, start + GRAPHQL_BATCH)
+					}
+				}
+			});
+			for (const node of response.data?.project?.repository?.blobs?.nodes ?? []) {
+				const size = Number(node.size);
+				if (Number.isFinite(size)) sizes.set(node.path, size);
+			}
+		}
+		return sizes;
+	}
 	async lastCommitFor(path, ref) {
 		return (await gitlabJson(this.api, this.repo(`/files/${encodeURIComponent(path)}?ref=${ref}`))).last_commit_id;
 	}
@@ -155,6 +688,24 @@ var GitLabBackend = class {
 			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,
@@ -172,10 +723,14 @@ var GitLabBackend = class {
 			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) return {
-				state: "failed",
-				detailsUrl: failed.target_url ?? void 0
-			};
+			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
@@ -189,6 +744,39 @@ var GitLabBackend = class {
 			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();
 	}
@@ -223,6 +811,188 @@ function redirectUri(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() {
@@ -325,6 +1095,7 @@ function gitlab(options) {
 	return {
 		name: "GitLab",
 		canRedirect: Boolean(options.clientId),
+		redirectAddressesListed: Boolean(options.clientId),
 		tokenLinks: [{
 			url: `${webUrl}/-/user_settings/personal_access_tokens?${new URLSearchParams({
 				name: "Goodfellow admin",
@@ -378,4 +1149,4 @@ function gitlab(options) {
 	};
 }
 //#endregion
-export { GitLabBackend, gitlab, redirectUri };
+export { GitLabBackend, gitlab, gitlabPagesRecords, gitlabSetup, redirectUri };