@goodfellow-cms/gitlab 0.4.0 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@ import { gitlab } from "@goodfellow-cms/gitlab";
 export default defineConfig({ blocks, backend: gitlab({ project: "your-name/your-site" }) });
 ```
 
-[Goodfellow](https://github.com/goodfellow-cms/goodfellow-cms) is a website builder for people who aren't developers, with no server or database: pages are files in your own GitHub or GitLab repository, edited in a visual editor built on [Puck](https://puckeditor.com). To start a new site, run `npm create goodfellow@latest my-site`. See the [documentation](https://goodfellow-cms.github.io/goodfellow-cms/) for everything else.
+[Goodfellow](https://github.com/goodfellow-cms/goodfellow-cms) is a website builder for people who aren't developers, with no server or database: pages are files in your own GitHub, GitLab or Bitbucket repository, edited in a visual editor built on [Puck](https://puckeditor.com). To start a new site, run `npm create goodfellow@latest my-site`. See the [documentation](https://goodfellow-cms.github.io/goodfellow-cms/) for everything else.
 
 More in the docs: [Hosts and business sites](https://goodfellow-cms.github.io/goodfellow-cms/docs/hosts).
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, PagesDomains, SetupHost, SiteDrafts, SiteEditors, SiteUpdates, StorageLike, WriteOptions } from "@goodfellow-cms/core";
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, PagesDomains, PluginTasks, RepositoryVisibility, RevisionFiles, ScheduledBuilds, SetupHost, SiteDrafts, SiteEditors, SiteUpdates, StorageLike, WriteOptions } from "@goodfellow-cms/core";
 //#region src/api.d.ts
 interface ApiOptions {
   /** The API root, such as `https://gitlab.com/api/v4`. */
@@ -12,6 +12,15 @@ interface ApiOptions {
   fetch: typeof fetch;
 }
 //#endregion
+//#region src/tasks.d.ts
+interface GitLabTasksOptions {
+  /** How often to look for the answer, and how long to wait for it. */
+  pollMs?: number;
+  timeoutMs?: number;
+  /** Waits between looks; tests pass one that doesn't. */
+  wait?: (ms: number) => Promise<void>;
+}
+//#endregion
 //#region src/backend.d.ts
 interface GitLabBackendOptions {
   api: ApiOptions;
@@ -26,6 +35,8 @@ interface GitLabBackendOptions {
   };
   /** The commit reads see until `revision()` is next called, as a full-stack site's server reads what a browser loaded. */
   revision?: string;
+  /** How plugins' tasks wait for their answers; tests pass short waits. */
+  tasks?: GitLabTasksOptions;
   /** The project holds only the site's content, with its code in a project of its own (`GitBackend.contentOnly`). */
   contentOnly?: boolean;
   /** The code project, for a project that holds only content, where the site's updates run. */
@@ -46,6 +57,8 @@ export declare class GitLabBackend implements GitBackend {
   /** Absent where the project holds only content: the update job runs where the code is. */
   readonly updates?: SiteUpdates;
   readonly drafts: SiteDrafts;
+  readonly scheduledBuilds: ScheduledBuilds;
+  readonly tasks: PluginTasks;
   readonly contentOnly: boolean;
   private readonly options;
   private readonly api;
@@ -56,23 +69,32 @@ export declare class GitLabBackend implements GitBackend {
   private readonly trees;
   private readonly blobs;
   constructor(options: GitLabBackendOptions);
+  repositoryVisibility(): Promise<RepositoryVisibility>;
   /** Drafts on branches of the project, with merge requests for review. */
   private draftHost;
   private repo;
   revision(): Promise<string>;
+  /** The branch's latest commit, without moving the revision reads are pinned to. */
+  private head;
   /** Every file in one folder at a commit, page by page. */
   private listFolder;
   /** Path → blob id for the editable files at a commit. Commits never change, so this is cached. */
   private tree;
   private currentTree;
   read(path: string): Promise<string | undefined>;
+  private readFrom;
   /** Reads many text files in a few GraphQL requests rather than one request each. */
   readFiles(paths: string[]): Promise<Map<string, string>>;
+  private readFilesFrom;
   readBytes(path: string): Promise<Uint8Array | undefined>;
+  private bytesFrom;
   list(dir: string): Promise<string[]>;
+  filesAt(revision: string): RevisionFiles;
   /** GitLab's tree doesn't say how large files are, so they're asked for with GraphQL, in batches. */
   fileSizes(dir: string): Promise<Map<string, number>>;
   private lastCommitFor;
+  /** Whether a file exists at a commit: from the cached tree in the editable folders, and from GitLab elsewhere, such as the config. */
+  private existsAt;
   write(changes: FileChange[], { message, expectedRevision }: WriteOptions): Promise<{
     revision: string;
   }>;
@@ -81,9 +103,11 @@ export declare class GitLabBackend implements GitBackend {
   changedPaths(from: string, to: string): Promise<string[]>;
   /**
    * 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.
+   * Vercel or Cloudflare Pages). Before any exist, the site counts as building
+   * if it has pipelines, or if the host reported on the commit before.
    */
   deployStatus(revision: string): Promise<DeployStatus>;
+  private statuses;
   /** Why a commit's pipeline failed: the failed job's reason, and its log for which command failed and why. */
   private jobProblem;
   signOut(): void;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ConflictError, DomainError, DraftError, EDITABLE_FOLDERS, EditorsError, GitApiError, REBUILD_JOB, SetupError, SignInError, UpdatesError, assertContentChanges, branchDrafts, buildStepFor, credentialStorage, encodeBase64Bytes, findBuildCause, findUpdateResult } from "@goodfellow-cms/core";
+import { ConflictError, DomainError, DraftError, EDITABLE_FOLDERS, EditorsError, GitApiError, LOCKFILE_JOB, NIGHTLY_VARIABLE, PluginTaskError, REBUILD_JOB, ScheduledBuildsError, SetupError, SignInError, TASK_JOB, TASK_POLL_MS, TASK_RESULT_FILE, TASK_TIMEOUT_MS, UpdatesError, assertContentChanges, branchDrafts, buildStepFor, credentialStorage, encodeBase64Bytes, findBuildCause, findUpdateResult, hostSource, taskRequestProblem } 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 = {}) {
@@ -40,7 +40,7 @@ function roleOf(level) {
 function levelOf(role) {
 	return role === "owner" ? MAINTAINER : DEVELOPER;
 }
-function notAllowed$1(error) {
+function notAllowed$2(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;
 }
@@ -102,7 +102,7 @@ function gitlabEditors(api, project, branch, username) {
 						email: name,
 						access_level: levelOf(role)
 					}
-				}).catch(notAllowed$1);
+				}).catch(notAllowed$2);
 				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.");
@@ -123,17 +123,17 @@ function gitlabEditors(api, project, branch, username) {
 				});
 			} catch (error) {
 				if (error instanceof GitApiError && error.status === 409) throw new EditorsError("already", `${name} already edits the site.`);
-				notAllowed$1(error);
+				notAllowed$2(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);
+			}).catch(notAllowed$2);
 		},
 		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);
+			await gitlabRequest(api, editor.id.startsWith(INVITATION) ? `${base}/invitations/${encodeURIComponent(editor.id.slice(11))}` : `${base}/members/${editor.id.slice(7)}`, { method: "DELETE" }).catch(notAllowed$2);
 		},
 		async letEditorsPublish() {
 			const protect = (level) => gitlabRequest(api, `${base}/protected_branches`, {
@@ -141,19 +141,19 @@ function gitlabEditors(api, project, branch, username) {
 				body: {
 					name: branch,
 					push_access_level: level,
-					merge_access_level: MAINTAINER,
+					merge_access_level: level,
 					allow_force_push: false
 				}
 			});
 			await gitlabRequest(api, protectedPath, {
 				method: "DELETE",
 				allow: [404]
-			}).catch(notAllowed$1);
+			}).catch(notAllowed$2);
 			try {
 				await protect(DEVELOPER);
 			} catch (error) {
 				await protect(MAINTAINER).catch(() => void 0);
-				notAllowed$1(error);
+				notAllowed$2(error);
 			}
 		}
 	};
@@ -250,6 +250,7 @@ function gitlabPages(api, project) {
 		return response.ok ? await response.json() : found;
 	}
 	return {
+		severalDomains: true,
 		async site() {
 			const found = await pages();
 			if (!found) return void 0;
@@ -301,9 +302,16 @@ function gitlabPages(api, project) {
 				primary: settings?.primary_domain === void 0 || settings.primary_domain === domain
 			};
 		},
-		async secure(domain) {
+		async secure(domain, { primary = true } = {}) {
 			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.");
+			if (!primary) {
+				await gitlabRequest(api, pagesPath, {
+					method: "PATCH",
+					body: { pages_https_only: true }
+				}).catch(notAllowed);
+				return;
+			}
 			try {
 				await gitlabRequest(api, pagesPath, {
 					method: "PATCH",
@@ -329,6 +337,146 @@ function gitlabPages(api, project) {
 	};
 }
 //#endregion
+//#region src/scheduled-builds.ts
+/** The start of the description of the pipeline schedules the admin panel adds, which `sync()` keeps. */
+const SCHEDULED_BUILD_DESCRIPTION = "Goodfellow: build the site for a scheduled change at ";
+/** The variable those schedules' pipelines have, which the starters' pipelines read to skip the nightly update. */
+const SCHEDULED_CHANGE_VARIABLE = "GOODFELLOW_SCHEDULED_CHANGE";
+function notAllowed$1(error) {
+	if (error instanceof GitApiError && (error.status === 401 || error.status === 403)) throw new ScheduledBuildsError("not-allowed", "Adding pipeline schedules on GitLab needs the Developer role, with permission to merge to the main branch.");
+	throw error;
+}
+/** A cron line for one instant, in UTC: it comes once a year, and `sync()` removes it once it has passed. */
+function cronAt(at) {
+	return `${at.getUTCMinutes()} ${at.getUTCHours()} ${at.getUTCDate()} ${at.getUTCMonth() + 1} *`;
+}
+/** An instant to the minute, as the schedules' descriptions and variables name it: `2026-11-29T14:00Z`. */
+function minute(at) {
+	return `${at.toISOString().slice(0, 16)}Z`;
+}
+/**
+* Scheduled changes on GitLab go live at their time: the admin panel adds a
+* pipeline schedule for each, which builds the site then. The pipeline is the
+* project's own, so any project with a `.gitlab-ci.yml` that builds the site
+* on its main branch does.
+*/
+function gitlabScheduledBuilds(api, project, branch, readCi, now = () => /* @__PURE__ */ new Date()) {
+	const base = `/projects/${encodeURIComponent(project)}/pipeline_schedules`;
+	return {
+		async timing() {
+			return await readCi() === void 0 ? "none" : "exact";
+		},
+		async sync(times) {
+			const after = now();
+			const wanted = /* @__PURE__ */ new Map();
+			for (const at of [...times].filter((time) => time > after).sort((a, b) => a.getTime() - b.getTime())) {
+				if (wanted.size >= 50) break;
+				wanted.set(minute(at), at);
+			}
+			const found = await gitlabJson(api, `${base}?per_page=100`).catch(notAllowed$1);
+			const ours = /* @__PURE__ */ new Map();
+			for (const schedule of found) {
+				if (!schedule.description?.startsWith("Goodfellow: build the site for a scheduled change at ")) continue;
+				ours.set(schedule.description.slice(53), schedule);
+			}
+			for (const [time, schedule] of ours) {
+				if (wanted.has(time)) continue;
+				await gitlabRequest(api, `${base}/${schedule.id}`, {
+					method: "DELETE",
+					allow: [403, 404]
+				});
+			}
+			for (const [time, at] of wanted) {
+				if (ours.has(time)) continue;
+				const created = await gitlabJson(api, base, {
+					method: "POST",
+					body: {
+						description: `${SCHEDULED_BUILD_DESCRIPTION}${time}`,
+						ref: branch,
+						cron: cronAt(at),
+						cron_timezone: "UTC",
+						active: true
+					}
+				}).catch(notAllowed$1);
+				await gitlabRequest(api, `${base}/${created.id}/variables`, {
+					method: "POST",
+					body: {
+						key: SCHEDULED_CHANGE_VARIABLE,
+						value: time,
+						variable_type: "env_var"
+					}
+				}).catch(notAllowed$1);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/tasks.ts
+/**
+* Plugins' tasks on GitLab, through the starters' `plugin-task` job: a
+* pipeline started with the request's variables (`GOODFELLOW_TASK_PLUGIN` and
+* the rest), whose job leaves the sealed answer as its artifact, read here.
+* Starting pipelines on the main branch needs Developer access, which
+* editors have once `letEditorsPublish()` lets them publish.
+*/
+function gitlabTasks(api, project, branch, readSetup, options = {}) {
+	const base = `/projects/${encodeURIComponent(project)}`;
+	const wait = options.wait ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+	const supported = async () => (await readSetup().catch(() => void 0) ?? "").includes("$GOODFELLOW_TASK_PLUGIN");
+	return {
+		supported,
+		secretsPlace: async () => ({
+			kind: "gitlab",
+			url: `${api.apiUrl.replace(/\/api\/v4\/?$/, "")}/${project}/-/settings/ci_cd#js-cicd-variables-settings`
+		}),
+		async run(request) {
+			const problem = taskRequestProblem(request);
+			if (problem) throw new PluginTaskError("failed", problem);
+			if (!await supported()) throw new PluginTaskError("missing", "The site's setup files don't run plugins' tasks: .gitlab-ci.yml needs the plugin-task job.");
+			const variable = (key, value) => ({
+				key,
+				variable_type: "env_var",
+				value
+			});
+			let pipeline;
+			try {
+				pipeline = await gitlabJson(api, `${base}/pipeline`, {
+					method: "POST",
+					body: {
+						ref: branch,
+						variables: [
+							variable("GOODFELLOW_TASK_REQUEST", request.id),
+							variable("GOODFELLOW_TASK_PLUGIN", request.plugin),
+							variable("GOODFELLOW_TASK_NAME", request.task),
+							variable("GOODFELLOW_TASK_INPUT", request.input),
+							variable("GOODFELLOW_TASK_KEY", request.key)
+						]
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && (error.status === 403 || error.status === 401)) throw new PluginTaskError("not-allowed", "Running plugins' tasks needs a sign-in that can publish to the site.");
+				throw error;
+			}
+			const deadline = Date.now() + (options.timeoutMs ?? TASK_TIMEOUT_MS);
+			for (;;) {
+				const job = (await gitlabJson(api, `${base}/pipelines/${pipeline.id}/jobs?per_page=100`)).find((candidate) => candidate.name === TASK_JOB);
+				if (job?.status === "success") {
+					const answer = await gitlabRequest(api, `${base}/jobs/${job.id}/artifacts/${TASK_RESULT_FILE}`, { allow: [404] });
+					if (answer.ok) return await answer.text();
+					throw new PluginTaskError("failed", "The site's build service ran the task but left no answer.");
+				}
+				if (job && [
+					"failed",
+					"canceled",
+					"skipped"
+				].includes(job.status)) throw new PluginTaskError("failed", "The site's build service couldn't run the task.");
+				if (Date.now() >= deadline) throw new PluginTaskError("timeout", "The site's build service didn't answer in time.");
+				await wait(options.pollMs ?? TASK_POLL_MS);
+			}
+		}
+	};
+}
+//#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. */
@@ -348,12 +496,16 @@ function gitlabUpdates(api, project, branch, readAt, jobName = "pages") {
 	async function schedules() {
 		return gitlabJson(api, `${base}/pipeline_schedules`);
 	}
+	/** The nightly schedule: the branch's, other than those the admin panel adds for scheduled changes. */
+	async function nightlySchedule() {
+		return (await schedules()).find((schedule) => (schedule.ref === branch || schedule.ref === `refs/heads/${branch}`) && !schedule.description?.startsWith("Goodfellow: build the site for a scheduled change at "));
+	}
 	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}`));
+				const scheduled = found.some((schedule) => (schedule.ref === branch || schedule.ref === `refs/heads/${branch}`) && (schedule.active || !schedule.description?.startsWith("Goodfellow: build the site for a scheduled change at ")));
 				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";
@@ -365,7 +517,7 @@ function gitlabUpdates(api, project, branch, readAt, jobName = "pages") {
 				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`, {
+			if (!await nightlySchedule().catch(notAllowed)) await gitlabRequest(api, `${base}/pipeline_schedules`, {
 				method: "POST",
 				body: {
 					description: "Rebuild the site and install Goodfellow's fixes each night",
@@ -397,7 +549,7 @@ function gitlabUpdates(api, project, branch, readAt, jobName = "pages") {
 					state: "running",
 					...run
 				};
-				const job = (await gitlabJson(api, `${base}/pipelines/${pipeline.id}/jobs?per_page=100`)).find((candidate) => candidate.name === jobName);
+				const job = (await gitlabJson(api, `${base}/pipelines/${pipeline.id}/jobs?per_page=100`)).find((candidate) => candidate.name === jobName || candidate.name === "update");
 				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;
@@ -421,6 +573,61 @@ function gitlabUpdates(api, project, branch, readAt, jobName = "pages") {
 					}]
 				}
 			}).catch(notAllowed);
+		},
+		nightly: {
+			async supported() {
+				return (await readAt(CI_FILE))?.includes("nightly") ?? false;
+			},
+			async get() {
+				try {
+					const found = await nightlySchedule();
+					if (!found) return void 0;
+					if (!found.active) return "off";
+					return (await gitlabJson(api, `${base}/pipeline_schedules/${found.id}`)).variables?.find((variable) => variable.key === NIGHTLY_VARIABLE)?.value === "always" ? "always" : "changed";
+				} catch (error) {
+					if (error instanceof GitApiError && error.status === 403) return void 0;
+					throw error;
+				}
+			},
+			async set(mode) {
+				const found = await nightlySchedule().catch(notAllowed);
+				if (!found) throw new UpdatesError("missing", "The site has no nightly schedule yet: turn on updates first.");
+				const path = `${base}/pipeline_schedules/${found.id}`;
+				await gitlabRequest(api, path, {
+					method: "PUT",
+					body: { active: mode !== "off" }
+				}).catch(notAllowed);
+				if (mode === "always") {
+					const body = {
+						key: NIGHTLY_VARIABLE,
+						value: "always"
+					};
+					if ((await gitlabRequest(api, `${path}/variables/${NIGHTLY_VARIABLE}`, {
+						method: "PUT",
+						body,
+						allow: [404]
+					}).catch(notAllowed)).status === 404) await gitlabRequest(api, `${path}/variables`, {
+						method: "POST",
+						body
+					}).catch(notAllowed);
+				} else if (mode === "changed") await gitlabRequest(api, `${path}/variables/${NIGHTLY_VARIABLE}`, {
+					method: "DELETE",
+					allow: [404]
+				}).catch(notAllowed);
+			}
+		},
+		async rebuild() {
+			await gitlabRequest(api, `${base}/pipeline`, {
+				method: "POST",
+				body: {
+					ref: branch,
+					variables: [{
+						key: "GOODFELLOW_REBUILD",
+						variable_type: "env_var",
+						value: "true"
+					}]
+				}
+			}).catch(notAllowed);
 		}
 	};
 }
@@ -479,6 +686,9 @@ function gitlabCodeUpdates(options) {
 		},
 		async start(target) {
 			await (await updates()).start(target);
+		},
+		async rebuild() {
+			await (await updates()).rebuild?.();
 		}
 	};
 }
@@ -490,6 +700,19 @@ 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");
 /**
+* Whether a status says when the site is live. A job that only asks another
+* host to rebuild the site doesn't, and nor do the nightly update and the
+* job that writes the lockfile where Cloudflare builds the site, which run
+* on the newest commit too.
+*/
+function builds(status) {
+	return status.name !== REBUILD_JOB && status.name !== "update" && status.name !== LOCKFILE_JOB;
+}
+function listFrom(tree, dir) {
+	const prefix = `${dir}/`;
+	return [...tree.keys()].filter((path) => path.startsWith(prefix)).sort();
+}
+/**
 * 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.
@@ -501,6 +724,8 @@ var GitLabBackend = class GitLabBackend {
 	/** Absent where the project holds only content: the update job runs where the code is. */
 	updates;
 	drafts;
+	scheduledBuilds;
+	tasks;
 	contentOnly;
 	options;
 	api;
@@ -538,6 +763,12 @@ var GitLabBackend = class GitLabBackend {
 			});
 		}
 		this.drafts = branchDrafts(this, this.draftHost());
+		this.scheduledBuilds = gitlabScheduledBuilds(this.api, options.project, this.branch, async () => this.readAt(".gitlab-ci.yml", this.pinned ?? await this.revision()));
+		this.tasks = gitlabTasks(this.api, options.project, this.branch, async () => this.readAt(".gitlab-ci.yml", this.pinned ?? await this.revision()), options.tasks);
+	}
+	async repositoryVisibility() {
+		const { visibility } = await gitlabJson(this.api, `/projects/${this.project}`);
+		return visibility === "public" || visibility === "internal" ? visibility : "private";
 	}
 	/** Drafts on branches of the project, with merge requests for review. */
 	draftHost() {
@@ -571,6 +802,13 @@ var GitLabBackend = class GitLabBackend {
 				if (!response.ok) throw new DraftError("not-found", `There's no draft ${branch}.`);
 				return (await response.json()).id;
 			},
+			listBranches: async (prefix) => {
+				const query = new URLSearchParams({
+					search: `^${prefix}`,
+					per_page: "100"
+				});
+				return (await gitlabJson(this.api, this.repo(`/branches?${query}`))).map((found) => found.name).filter((name) => name.startsWith(prefix));
+			},
 			openReview: async ({ branch, title, description }) => {
 				const response = await gitlabRequest(this.api, `${project}/merge_requests`, {
 					method: "POST",
@@ -603,10 +841,13 @@ var GitLabBackend = class GitLabBackend {
 		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;
+		this.pinned = await this.head();
 		return this.pinned;
 	}
+	/** The branch's latest commit, without moving the revision reads are pinned to. */
+	async head() {
+		return (await gitlabJson(this.api, this.repo(`/branches/${encodeURIComponent(this.branch)}`))).commit.id;
+	}
 	/** Every file in one folder at a commit, page by page. */
 	async listFolder(sha, dir) {
 		const files = [];
@@ -639,8 +880,11 @@ var GitLabBackend = class GitLabBackend {
 		return this.tree(this.pinned ?? await this.revision());
 	}
 	async read(path) {
-		const sha = (await this.currentTree()).get(path);
-		if (!sha) return void 0;
+		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 = gitlabRequest(this.api, this.repo(`/blobs/${sha}/raw`)).then((response) => response.text());
@@ -651,10 +895,12 @@ var GitLabBackend = class GitLabBackend {
 	}
 	/** Reads many text files in a few GraphQL requests rather than one request each. */
 	async readFiles(paths) {
-		const tree = await this.currentTree();
+		const ref = this.pinned ?? await this.revision();
+		return this.readFilesFrom(ref, await this.tree(ref), paths);
+	}
+	async readFilesFrom(ref, tree, paths) {
 		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", {
@@ -677,20 +923,30 @@ var GitLabBackend = class GitLabBackend {
 		}
 		const result = /* @__PURE__ */ new Map();
 		for (const path of wanted) {
-			const text = await this.read(path);
+			const text = await this.readFrom(tree, path);
 			if (text !== void 0) result.set(path, text);
 		}
 		return result;
 	}
 	async readBytes(path) {
-		const sha = (await this.currentTree()).get(path);
+		return this.bytesFrom(await this.currentTree(), path);
+	}
+	async bytesFrom(tree, path) {
+		const sha = tree.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();
+		return listFrom(await this.currentTree(), dir);
+	}
+	filesAt(revision) {
+		return {
+			read: async (path) => this.readFrom(await this.tree(revision), path),
+			readFiles: async (paths) => this.readFilesFrom(revision, await this.tree(revision), paths),
+			readBytes: async (path) => this.bytesFrom(await this.tree(revision), path),
+			list: async (dir) => listFrom(await this.tree(revision), dir)
+		};
 	}
 	/** GitLab's tree doesn't say how large files are, so they're asked for with GraphQL, in batches. */
 	async fileSizes(dir) {
@@ -721,12 +977,20 @@ var GitLabBackend = class GitLabBackend {
 	async lastCommitFor(path, ref) {
 		return (await gitlabJson(this.api, this.repo(`/files/${encodeURIComponent(path)}?ref=${ref}`))).last_commit_id;
 	}
+	/** Whether a file exists at a commit: from the cached tree in the editable folders, and from GitLab elsewhere, such as the config. */
+	async existsAt(tree, path, ref) {
+		if (EDITABLE_FOLDERS.some((folder) => path.startsWith(`${folder}/`))) return tree.has(path);
+		return this.lastCommitFor(path, ref).then(() => true, (error) => {
+			if (error instanceof GitApiError && error.status === 404) return false;
+			throw error;
+		});
+	}
 	async write(changes, { message, expectedRevision }) {
 		if (this.contentOnly) assertContentChanges(changes);
 		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);
+			const exists = await this.existsAt(existing, change.path, expectedRevision);
 			if ("delete" in change) return exists ? {
 				action: "delete",
 				file_path: change.path,
@@ -798,15 +1062,24 @@ var GitLabBackend = class GitLabBackend {
 	}
 	/**
 	* 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.
+	* Vercel or Cloudflare Pages). Before any exist, the site counts as building
+	* if it has pipelines, or if the host reported on the commit before.
 	*/
 	async deployStatus(revision) {
 		try {
-			const all = await gitlabJson(this.api, this.repo(`/commits/${revision}/statuses`));
-			const statuses = all.filter((status) => status.name !== REBUILD_JOB);
+			const all = await this.statuses(revision);
+			const statuses = all.filter(builds);
 			if (all.length > 0 && statuses.length === 0) return { state: "unknown" };
-			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 (statuses.length === 0) {
+				if ((await gitlabJson(this.api, `/projects/${this.project}/pipelines?per_page=1`)).length > 0) return { state: "building" };
+				const { parent_ids: parents = [] } = await gitlabJson(this.api, this.repo(`/commits/${revision}`));
+				return { state: (parents[0] ? (await this.statuses(parents[0])).filter(builds) : []).length > 0 ? "building" : "unknown" };
+			}
+			const failed = statuses.find((status) => status.status === "failed") ?? statuses.find((status) => status.status === "canceled");
+			if (failed?.status === "canceled") {
+				const head = await this.head();
+				if (head !== revision) return this.deployStatus(head);
+			}
 			if (failed) {
 				const problem = await this.jobProblem(revision).catch(() => void 0);
 				return {
@@ -828,6 +1101,9 @@ var GitLabBackend = class GitLabBackend {
 			throw error;
 		}
 	}
+	statuses(revision) {
+		return gitlabJson(this.api, this.repo(`/commits/${revision}/statuses`));
+	}
 	/** 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({
@@ -1029,6 +1305,29 @@ function gitlabSetup(options = {}) {
 					onStep?.("connect");
 					if (!await connectProjects(site.link)) warnings.push("connect-unavailable");
 				}
+				let siteUrl;
+				if (site.pages && site.domain) {
+					onStep?.("pages");
+					try {
+						await gitlabRequest(api, `/projects/${project.id}/pages/domains`, {
+							method: "POST",
+							body: {
+								domain: site.domain,
+								auto_ssl_enabled: true
+							}
+						});
+						siteUrl = `https://${site.domain}/`;
+					} catch (error) {
+						if (!(error instanceof GitApiError) || ![
+							400,
+							403,
+							404,
+							409,
+							422
+						].includes(error.status)) throw error;
+						warnings.push("domain-unavailable");
+					}
+				}
 				onStep?.("files");
 				await gitlabRequest(api, `/projects/${project.id}/repository/commits`, {
 					method: "POST",
@@ -1050,6 +1349,7 @@ function gitlabSetup(options = {}) {
 				return {
 					repo: project.path_with_namespace,
 					webUrl: project.web_url,
+					...siteUrl && { siteUrl },
 					buildsUrl: `${project.web_url}/-/pipelines`,
 					pagesUrl: site.pages ? `${project.web_url}/pages` : void 0,
 					warnings
@@ -1265,7 +1565,18 @@ function gitlab(options) {
 	}
 	return {
 		name: "GitLab",
+		source: hostSource("@goodfellow-cms/gitlab", "gitlab", options, [
+			"fetch",
+			"storage",
+			"location"
+		]),
 		canRedirect: Boolean(options.clientId),
+		setup: () => gitlabSetup({
+			...options.url && { url: options.url },
+			...options.fetch && { fetch: options.fetch },
+			...options.storage && { storage: options.storage },
+			...options.location && { location: options.location }
+		}),
 		redirectAddressesListed: Boolean(options.clientId),
 		tokenLinks: [{
 			url: `${webUrl}/-/user_settings/personal_access_tokens?${new URLSearchParams({

package/dist/testing.d.ts

@@ -23,6 +23,11 @@ export interface FakeGitLabOptions {
   deployAfterChecks?: number;
   /** The job each published commit's pipeline runs: `pages` by default. */
   deployJob?: string;
+  /**
+   * Has `deployJob` report as a host outside GitLab does, such as Cloudflare
+   * Pages: a commit status with no pipeline the project lists.
+   */
+  external?: boolean;
   /** The job the update runs in, which `addUpdateRun()` logs: `pages` by default, as in the starters, or a code project's `update`. */
   updateJob?: string;
   /** Groups the users belong to, which new projects can be created in. */
@@ -31,8 +36,30 @@ export interface FakeGitLabOptions {
   pages?: {
     uniqueDomain?: boolean;
   };
+  /** Domains another GitLab Pages site already uses. */
+  takenDomains?: string[];
   /** Other GitLab accounts that exist, which can be added to the project. Every token's user exists and is a member. */
   accounts?: string[];
+  /** Who can see the project. Private by default. */
+  visibility?: "public" | "internal" | "private";
+  /**
+   * Answers plugins' tasks, as the site's `plugin-task` job would: given each
+   * pipeline's task variables, it gives the text the job leaves as its
+   * artifact, or nothing for a job that fails. Without it, task pipelines fail.
+   */
+  tasks?: (variables: Record<string, string>) => string | undefined | Promise<string | undefined>;
+}
+/** A pipeline schedule, such as the nightly one or one the admin panel adds for a scheduled change. */
+export interface FakeSchedule {
+  id: number;
+  ref: string;
+  cron: string;
+  cronTimezone?: string;
+  description?: string;
+  active: boolean;
+  /** Who added it, who alone (with Maintainers) can change it. */
+  owner?: string;
+  variables?: Record<string, string>;
 }
 /** A member of the site's project. */
 export interface FakeMember {
@@ -77,6 +104,8 @@ export interface FakeCreatedProject {
     cron: string;
     active: boolean;
   }>;
+  /** Domains of its own its Pages were given. */
+  pagesDomains: string[];
 }
 export declare function fakeGitLab(options: FakeGitLabOptions): {
   /** How many GraphQL requests read files, as `readFiles()` makes. */
@@ -94,15 +123,11 @@ export declare function fakeGitLab(options: FakeGitLabOptions): {
     failureReason?: string;
     trace?: string;
   }) => void;
+  cancelBuild: (sha: string) => void;
   /** The project's update settings, and the pipelines the update ran in, which tests add with `addUpdateRun()`. */
   updateSettings: {
     jobTokenPush: boolean;
-    schedules: Array<{
-      id: number;
-      ref: string;
-      cron: string;
-      active: boolean;
-    }>;
+    schedules: FakeSchedule[];
   };
   updateRuns: {
     id: number;

package/dist/testing.js

@@ -158,6 +158,7 @@ function fakeGitLab(options) {
 		jobTokenPush: false,
 		schedules: []
 	};
+	let scheduleIds = 0;
 	/** Pipelines the update ran in: scheduled, or started through the API, with the pages job's log. */
 	const updateRuns = [];
 	/** Simulates a scheduled (or API) pipeline whose pages job logged `trace`. */
@@ -172,7 +173,9 @@ function fakeGitLab(options) {
 		updateRuns.push(added);
 		return added;
 	}
-	/** Failed jobs, by commit, which tests add with `failBuild()`. */
+	/** Pipelines started for plugins' tasks, with their `plugin-task` job's artifact. */
+	const taskRuns = [];
+	/** Failed jobs, by commit, which tests add with `failBuild()` and `cancelBuild()`. */
 	const failures = /* @__PURE__ */ new Map();
 	/**
 	* Simulates the pipeline for a commit failing: its `pages` job (or another,
@@ -182,10 +185,21 @@ function fakeGitLab(options) {
 		if (!pipelines.has(sha)) pipelines.set(sha, { checks: 0 });
 		failures.set(sha, {
 			job: failure.job ?? "pages",
+			status: "failed",
 			failureReason: failure.failureReason ?? "script_failure",
 			trace: failure.trace ?? ""
 		});
 	}
+	/** Simulates a commit's `pages` job being cancelled, as a newer pipeline on the branch cancels an interruptible one. */
+	function cancelBuild(sha) {
+		if (!pipelines.has(sha)) pipelines.set(sha, { checks: 0 });
+		failures.set(sha, {
+			job: "pages",
+			status: "canceled",
+			failureReason: "",
+			trace: ""
+		});
+	}
 	const pipelineId = (sha) => [...pipelines.keys()].indexOf(sha) + 1;
 	const requests = [];
 	let counter = 0;
@@ -302,7 +316,8 @@ function fakeGitLab(options) {
 				repo: new FakeRepo({}),
 				jobTokenAllowlist: [],
 				jobTokenPush: false,
-				schedules: []
+				schedules: [],
+				pagesDomains: []
 			};
 			created.set(fullPath, project);
 			return json({
@@ -339,6 +354,15 @@ function fakeGitLab(options) {
 				target_project_id: body.target_project_id
 			}, 201);
 		}
+		if (rest === "/pages/domains" && request.method === "POST") {
+			const body = await request.json();
+			if (options.takenDomains?.includes(body.domain)) return json({ message: { domain: ["has already been taken"] } }, 400);
+			project.pagesDomains.push(body.domain);
+			return json({
+				domain: body.domain,
+				url: `https://${body.domain}`
+			}, 201);
+		}
 		if (rest === "/pipeline_schedules" && request.method === "POST") {
 			const body = await request.json();
 			project.schedules.push({
@@ -481,12 +505,21 @@ function fakeGitLab(options) {
 		if (membersResponse) return membersResponse;
 		if (rest === "" && request.method !== "PUT") return json({
 			default_branch: repo.defaultBranch,
+			visibility: options.visibility ?? "private",
 			permissions: {
 				project_access: { access_level: accessLevel },
 				group_access: null
 			},
 			ci_push_repository_for_job_token_allowed: updateSettings.jobTokenPush
 		});
+		if (rest === "/repository/branches" && request.method === "GET") {
+			const search = url.searchParams.get("search") ?? "";
+			const matches = (name) => search.startsWith("^") ? name.startsWith(search.slice(1)) : name.includes(search);
+			return json([...repo.branches].filter(([name]) => matches(name)).map(([name, sha]) => ({
+				name,
+				commit: { id: sha }
+			})));
+		}
 		if (rest === "/repository/branches" && request.method === "POST") {
 			if (accessLevel < 30) return json({ message: "403 Forbidden" }, 403);
 			const name = url.searchParams.get("branch") ?? "";
@@ -617,6 +650,15 @@ function fakeGitLab(options) {
 				committed_date: commit.date
 			})));
 		}
+		const commitSha = rest.match(/^\/repository\/commits\/([0-9a-f]{40})$/)?.[1];
+		if (commitSha) {
+			const found = repo.commitAt(commitSha);
+			if (!found) return json({ message: "404 Commit Not Found" }, 404);
+			return json({
+				id: commitSha,
+				parent_ids: found.parent ? [found.parent] : []
+			});
+		}
 		if (rest === "/repository/compare") return json({ diffs: repo.changedPaths(url.searchParams.get("from") ?? "", url.searchParams.get("to") ?? "").map((changedPath) => ({
 			old_path: changedPath,
 			new_path: changedPath
@@ -630,7 +672,7 @@ function fakeGitLab(options) {
 				const id = pipelineId(statuses[1] ?? "");
 				return json([{
 					name: failure.job,
-					status: "failed",
+					status: failure.status,
 					target_url: `${webUrl}/${options.project}/-/jobs/${id}`
 				}]);
 			}
@@ -651,10 +693,25 @@ function fakeGitLab(options) {
 		})));
 		if (rest === "/pipeline" && request.method === "POST") {
 			if (accessLevel < 30) return json({ message: "403 Forbidden" }, 403);
+			const body = await request.json();
+			const variables = Object.fromEntries((body.variables ?? []).map(({ key, value }) => [key, value]));
+			if (variables.GOODFELLOW_TASK_PLUGIN) {
+				const id = 9e4 + taskRuns.length;
+				taskRuns.push({
+					id,
+					job: id + 5e4,
+					variables,
+					answer: await options.tasks?.(variables)
+				});
+				return json({
+					id,
+					status: "created"
+				}, 201);
+			}
 			const run = addUpdateRun({
 				source: "api",
 				status: "created",
-				variables: (await request.json()).variables
+				variables: body.variables
 			});
 			return json({
 				id: run.id,
@@ -665,23 +722,100 @@ function fakeGitLab(options) {
 			if (accessLevel < 30) return json({ message: "403 Forbidden" }, 403);
 			if (request.method === "POST") {
 				const body = await request.json();
+				const protection = protectedBranches.get(body.ref);
+				if (protection && accessLevel < protection.merge) return json({ message: "403 Forbidden" }, 403);
 				const schedule = {
-					id: updateSettings.schedules.length + 1,
+					id: ++scheduleIds,
 					ref: body.ref,
 					cron: body.cron,
-					active: body.active ?? true
+					active: body.active ?? true,
+					...body.description !== void 0 && { description: body.description },
+					...body.cron_timezone !== void 0 && { cronTimezone: body.cron_timezone },
+					owner: user.username
 				};
 				updateSettings.schedules.push(schedule);
 				return json(schedule, 201);
 			}
 			return json(updateSettings.schedules);
 		}
+		const scheduleMatch = rest.match(/^\/pipeline_schedules\/(\d+)(\/variables)?(?:\/([\w-]+))?$/);
+		if (scheduleMatch) {
+			const schedule = updateSettings.schedules.find((candidate) => candidate.id === Number(scheduleMatch[1]));
+			if (!schedule) return json({ message: "404 Not found" }, 404);
+			const variables = () => Object.entries(schedule.variables ?? {}).map(([key, value]) => ({
+				key,
+				value,
+				variable_type: "env_var"
+			}));
+			if (request.method === "GET" && !scheduleMatch[2]) {
+				if (accessLevel < 30) return json({ message: "403 Forbidden" }, 403);
+				return json({
+					...schedule,
+					variables: variables()
+				});
+			}
+			if (accessLevel < 30 || accessLevel < 40 && schedule.owner !== user.username) return json({ message: "403 Forbidden" }, 403);
+			const key = scheduleMatch[3];
+			if (scheduleMatch[2] && !key && request.method === "POST") {
+				const body = await request.json();
+				schedule.variables = {
+					...schedule.variables,
+					[body.key]: body.value
+				};
+				return json(body, 201);
+			}
+			if (scheduleMatch[2] && key) {
+				if (!(key in (schedule.variables ?? {}))) return json({ message: "404 Variable Not Found" }, 404);
+				if (request.method === "PUT") {
+					const body = await request.json();
+					schedule.variables = {
+						...schedule.variables,
+						[key]: body.value
+					};
+					return json({
+						key,
+						value: body.value
+					});
+				}
+				if (request.method === "DELETE") {
+					const { [key]: _removed, ...rest } = schedule.variables ?? {};
+					schedule.variables = rest;
+					return json({ key });
+				}
+			}
+			if (!scheduleMatch[2] && request.method === "PUT") {
+				const body = await request.json();
+				if (body.active !== void 0) schedule.active = body.active;
+				if (body.cron !== void 0) schedule.cron = body.cron;
+				if (body.description !== void 0) schedule.description = body.description;
+				return json({
+					...schedule,
+					variables: variables()
+				});
+			}
+			if (!scheduleMatch[2] && request.method === "DELETE") {
+				updateSettings.schedules = updateSettings.schedules.filter((candidate) => candidate !== schedule);
+				return new Response(null, { status: 204 });
+			}
+		}
 		if (rest === "" && request.method === "PUT") {
 			if (accessLevel < 40) return json({ message: "403 Forbidden" }, 403);
 			const body = await request.json();
 			if (body.ci_push_repository_for_job_token_allowed !== void 0) updateSettings.jobTokenPush = body.ci_push_repository_for_job_token_allowed;
 			return json({ ci_push_repository_for_job_token_allowed: updateSettings.jobTokenPush });
 		}
+		const taskJobs = rest.match(/^\/pipelines\/(\d+)\/jobs$/);
+		const taskRun = taskJobs && taskRuns.find((candidate) => candidate.id === Number(taskJobs[1]));
+		if (taskRun) return json([{
+			id: taskRun.job,
+			name: "plugin-task",
+			status: taskRun.answer === void 0 ? "failed" : "success"
+		}]);
+		const artifact = rest.match(/^\/jobs\/(\d+)\/artifacts\/(.+)$/);
+		if (artifact) {
+			const run = taskRuns.find((candidate) => candidate.job === Number(artifact[1]));
+			return run?.answer !== void 0 && artifact[2] === "goodfellow-task-result.json" ? new Response(`${run.answer}\n`) : json({ message: "404 Not Found" }, 404);
+		}
 		const updateJobs = rest.match(/^\/pipelines\/(\d{4,})\/jobs$/);
 		if (updateJobs) {
 			const run = updateRuns.find((candidate) => candidate.id === Number(updateJobs[1]));
@@ -698,7 +832,7 @@ function fakeGitLab(options) {
 		}
 		if (rest === "/pipelines") {
 			const sha = url.searchParams.get("sha");
-			return json([...pipelines.keys()].map((pipelineSha, index) => ({
+			return json([...options.external ? [] : pipelines.keys()].map((pipelineSha, index) => ({
 				id: index + 1,
 				sha: pipelineSha
 			})).filter((pipeline) => !sha || pipeline.sha === sha));
@@ -712,7 +846,7 @@ function fakeGitLab(options) {
 			return json([failure ? {
 				id,
 				name: failure.job,
-				status: "failed",
+				status: failure.status,
 				failure_reason: failure.failureReason
 			} : {
 				id,
@@ -738,6 +872,7 @@ function fakeGitLab(options) {
 		invitations,
 		protectedBranches,
 		failBuild,
+		cancelBuild,
 		/** The project's update settings, and the pipelines the update ran in, which tests add with `addUpdateRun()`. */
 		updateSettings,
 		updateRuns,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfellow-cms/gitlab",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Edit a Goodfellow site stored on GitLab, straight from the browser.",
   "keywords": [
     "goodfellow",
@@ -35,13 +35,13 @@
     "dist"
   ],
   "dependencies": {
-    "@goodfellow-cms/core": "0.4.0"
+    "@goodfellow-cms/core": "0.6.0"
   },
   "devDependencies": {
     "@puckeditor/core": "0.23.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "publishConfig": {
     "access": "public"