@goodfellow-cms/github 0.4.0 → 0.6.0

package/README.md

@@ -8,7 +8,7 @@ import { github } from "@goodfellow-cms/github";
 export default defineConfig({ blocks, backend: github({ repo: "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, OwnerAccess, PagesDomains, RedirectOptions, SetupHost, SignInError, SiteDrafts, SiteEditors, SiteUpdates, StorageLike, TokenLink, WriteOptions } from "@goodfellow-cms/core";
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, OwnerAccess, PagesDomains, PluginTasks, RedirectOptions, RepositoryVisibility, RevisionFiles, ScheduledBuilds, SetupHost, SignInError, SiteDrafts, SiteEditors, SiteUpdates, StorageLike, TokenLink, WriteOptions } from "@goodfellow-cms/core";
 //#region src/sign-in.d.ts
 /** The page's address and how to change it. Replaceable in tests. */
 interface BrowserLocation {
@@ -20,6 +20,15 @@ interface ApiOptions {
   fetch: typeof fetch;
 }
 //#endregion
+//#region src/tasks.d.ts
+interface GitHubTasksOptions {
+  /** 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 GitHubBackendOptions {
   api: ApiOptions;
@@ -42,6 +51,8 @@ interface GitHubBackendOptions {
   };
   /** 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?: GitHubTasksOptions;
   /** The repository holds only the site's content, with its code in a repository of its own (`GitBackend.contentOnly`). */
   contentOnly?: boolean;
   /**
@@ -67,6 +78,8 @@ export declare class GitHubBackend implements GitBackend {
   /** Absent where the repository 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;
@@ -81,9 +94,12 @@ export declare class GitHubBackend implements GitBackend {
   private readonly treeSizes;
   private readonly blobs;
   constructor(options: GitHubBackendOptions);
+  repositoryVisibility(): Promise<RepositoryVisibility>;
   /** Drafts on branches of the repository, with pull requests for review. */
   private draftHost;
   revision(): Promise<string>;
+  /** The branch's latest commit, without moving the revision reads are pinned to. */
+  private head;
   /** Path → blob id for every file at a commit. Commits never change, so this is cached. */
   private tree;
   private currentTree;
@@ -91,8 +107,11 @@ export declare class GitHubBackend implements GitBackend {
   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;
   fileSizes(dir: string): Promise<Map<string, number>>;
   /** Uses an owner's sign-in through the worker for editors and GitHub Pages settings, until it's forgotten. */
   useOwnerSignIn(token: TokenSource, end: () => void, codeToken?: TokenSource): void;
@@ -112,12 +131,21 @@ export declare class GitHubBackend implements GitBackend {
   readAt(path: string, revision: string): Promise<string | undefined>;
   changedPaths(from: string, to: string): Promise<string[]>;
   /**
-   * Reads the deployment GitHub Pages or Vercel created for a commit, and for
-   * GitHub Actions, the workflow run that builds it: a build that fails never
-   * creates a deployment. Before either exists, the site counts as building
-   * if it has ever been deployed.
+   * Reads the deployment GitHub Pages or Vercel created for a commit, or what
+   * Cloudflare Pages reports on it, and for GitHub Actions, the workflow run
+   * that builds it: a build that fails never creates a deployment. Before any
+   * exists, the site counts as building if it has ever been deployed, or if
+   * Cloudflare reported on the commit before.
    */
   deployStatus(revision: string): Promise<DeployStatus>;
+  /**
+   * What Cloudflare Pages reports on a commit: a check run of its GitHub App,
+   * or a commit status, which fine-grained tokens can read where check runs
+   * need a GitHub App's permission. `undefined` if it reported nothing.
+   */
+  private cloudflareBuild;
+  /** The commit a commit was made on top of, if the token can see it. */
+  private parentOf;
   /** The site's deploy workflow run for a commit, or `undefined` if there's none or the token can't see Actions. */
   private workflowRun;
   /** Which step of a failed run failed. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ConflictError, DomainError, DraftError, EditorsError, GitApiError, REBUILD_JOB, SetupError, SignInError, UpdatesError, assertContentChanges, branchDrafts, buildStepFor, compareReleases, credentialStorage, decodeBase64, encodeBase64, encodeBase64Bytes, siteVersion } from "@goodfellow-cms/core";
+import { ConflictError, DomainError, DraftError, EditorsError, GitApiError, NIGHTLY_VARIABLE, PluginTaskError, REBUILD_JOB, SetupError, SignInError, TASK_BRANCH_PREFIX, TASK_EVENT, TASK_POLL_MS, TASK_RESULT_FILE, TASK_TIMEOUT_MS, TASK_WORKFLOW, UpdatesError, assertContentChanges, branchDrafts, buildStepFor, compareReleases, credentialStorage, decodeBase64, encodeBase64, encodeBase64Bytes, hostSource, nightlyMode, siteVersion, taskRequestProblem } from "@goodfellow-cms/core";
 //#region src/api.ts
 /** Calls the GitHub REST or GraphQL API. Treats 401 as an expired sign-in; other errors become `GitApiError`. */
 async function githubRequest({ apiUrl, token, fetch }, path, init = {}) {
@@ -295,6 +295,7 @@ function githubPages(api, repo) {
 		}
 	}
 	return {
+		severalDomains: false,
 		async site() {
 			const found = await pages();
 			return found && {
@@ -328,11 +329,98 @@ function githubPages(api, repo) {
 	};
 }
 //#endregion
+//#region src/scheduled-builds.ts
+/** The starters' hourly check, which builds the site once a scheduled change has come due. */
+const SCHEDULED_WORKFLOW = ".github/workflows/scheduled.yml";
+/** Workflows that build the site, or ask another host to, each night. */
+const NIGHTLY_WORKFLOWS = [".github/workflows/deploy.yml", ".github/workflows/rebuild.yml"];
+/**
+* Scheduled changes on GitHub go live within the hour after their time, with
+* the starters' hourly check (`scheduled.yml`), which builds the site only
+* once one has come due. Sites set up without it get them with the nightly
+* build.
+*/
+function githubScheduledBuilds(read) {
+	return { async timing() {
+		const [scheduled, ...nightly] = await Promise.all([SCHEDULED_WORKFLOW, ...NIGHTLY_WORKFLOWS].map(read));
+		if (scheduled && /\bdue\b/.test(scheduled) && /\bschedule:/.test(scheduled)) return "hourly";
+		if (nightly.some((workflow) => workflow && /\bschedule:/.test(workflow))) return "nightly";
+		return "none";
+	} };
+}
+//#endregion
+//#region src/tasks.ts
+/** GitHub's own pages for an API address: `github.com` for its API, the host itself for GitHub Enterprise's `/api/v3`. */
+function webBase(apiUrl) {
+	const url = new URL(apiUrl);
+	if (url.hostname === "api.github.com") return "https://github.com";
+	return `${url.origin}${url.pathname.replace(/\/api\/v3\/?$/, "")}`.replace(/\/+$/, "");
+}
+/**
+* Plugins' tasks on GitHub, through the starters' `plugin-task.yml`: a
+* `repository_dispatch` event starts it, which editors' tokens can send with
+* the Contents permission they publish with, and its `answer` job leaves the
+* sealed answer on a branch of its own, `goodfellow-task-<request>`, which is
+* read here and deleted. No Actions permission is needed.
+*/
+function githubTasks(api, repo, branch, options = {}) {
+	const wait = options.wait ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+	const contents = (path, ref) => githubRequest(api, `/repos/${repo}/contents/${path}?ref=${encodeURIComponent(ref)}`, { allow: [404] });
+	const supported = async () => (await contents(`.github/workflows/${TASK_WORKFLOW}`, branch)).ok;
+	return {
+		supported,
+		secretsPlace: async () => ({
+			kind: "github",
+			url: `${webBase(api.apiUrl)}/${repo}/settings/secrets/actions/new`
+		}),
+		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: it needs plugin-task.yml.");
+			try {
+				await githubRequest(api, `/repos/${repo}/dispatches`, {
+					method: "POST",
+					body: {
+						event_type: TASK_EVENT,
+						client_payload: {
+							request: request.id,
+							plugin: request.plugin,
+							task: request.task,
+							input: request.input,
+							key: request.key
+						}
+					}
+				});
+			} catch (error) {
+				if (error instanceof GitApiError && (error.status === 403 || error.status === 404)) throw new PluginTaskError("not-allowed", "Running plugins' tasks needs a sign-in that can publish to the site.");
+				throw error;
+			}
+			const answerBranch = `${TASK_BRANCH_PREFIX}${request.id}`;
+			const deadline = Date.now() + (options.timeoutMs ?? TASK_TIMEOUT_MS);
+			for (;;) {
+				const found = await contents(TASK_RESULT_FILE, answerBranch);
+				if (found.ok) {
+					const { content = "" } = await found.json();
+					await githubRequest(api, `/repos/${repo}/git/refs/heads/${encodeURIComponent(answerBranch)}`, {
+						method: "DELETE",
+						allow: [404, 422]
+					}).catch(() => {});
+					return new TextDecoder().decode(decodeBase64(content.replace(/\s/g, "")));
+				}
+				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
 /** The starters' GitHub Pages workflow, which runs `goodfellow update` each night and when it's dispatched. */
 const WORKFLOW = "deploy.yml";
 /** The code repository's workflow, where a site keeps its content in a repository of its own. */
 const CODE_WORKFLOW = "update.yml";
+/** The job that publishes the update, which the job that builds the site with it can't. */
+const PUBLISH_JOB = "publish-update";
 /**
 * The site's nightly update, which runs in its GitHub Pages workflow. Running
 * it now dispatches the workflow, which needs GitHub's Actions permission
@@ -343,7 +431,8 @@ function githubUpdates(read, manage, repo, branch, files, workflow = WORKFLOW) {
 	const workflowFile = `.github/workflows/${workflow}`;
 	return {
 		async setup() {
-			return (await files.read(workflowFile))?.includes("update --publish") ? "ready" : "missing";
+			const text = await files.read(workflowFile);
+			return text && /update --(publish|commit)\b/.test(text) ? "ready" : "missing";
 		},
 		async lastRun() {
 			const response = await githubRequest(read, `${path}/runs?branch=${encodeURIComponent(branch)}&per_page=20`, { allow: [403, 404] });
@@ -365,6 +454,11 @@ function githubUpdates(read, manage, repo, branch, files, workflow = WORKFLOW) {
 					state: "failed",
 					...base
 				};
+				const publish = jobs.find((candidate) => candidate.name === PUBLISH_JOB);
+				if (publish && publish.conclusion !== "success" && publish.conclusion !== "skipped") return {
+					state: "failed",
+					...base
+				};
 				const before = siteVersion(await files.readAt("package.json", run.head_sha) ?? "");
 				const now = siteVersion(await files.read("package.json") ?? "");
 				if (!before || !now || before === now) return {
@@ -384,20 +478,73 @@ function githubUpdates(read, manage, repo, branch, files, workflow = WORKFLOW) {
 				};
 			}
 		},
+		nightly: githubNightly(read, manage, repo, () => files.read(workflowFile)),
+		async rebuild() {
+			await dispatch({});
+		},
 		async start(target) {
-			try {
-				await githubRequest(manage() ?? read, `${path}/dispatches`, {
-					method: "POST",
-					body: {
-						ref: branch,
-						inputs: { update: target }
-					}
-				});
-			} catch (error) {
-				if (error instanceof GitApiError && (error.status === 403 || error.status === 401)) throw new UpdatesError("not-allowed", "Running the update needs a token that can run the site's workflows.");
-				if (error instanceof GitApiError && (error.status === 404 || error.status === 422)) throw new UpdatesError("missing", "The site's GitHub Pages workflow doesn't update Goodfellow.");
-				throw error;
+			await dispatch({ update: target });
+		}
+	};
+	/** Runs the workflow, with an update to install, or none to only build the site. */
+	async function dispatch(inputs) {
+		try {
+			await githubRequest(manage() ?? read, `${path}/dispatches`, {
+				method: "POST",
+				body: {
+					ref: branch,
+					inputs
+				}
+			});
+		} catch (error) {
+			if (error instanceof GitApiError && (error.status === 403 || error.status === 401)) throw new UpdatesError("not-allowed", "Running the site's build needs a token that can run its workflows.");
+			if (error instanceof GitApiError && (error.status === 404 || error.status === 422)) throw new UpdatesError("missing", "The site's GitHub Pages workflow doesn't update Goodfellow.");
+			throw error;
+		}
+	}
+}
+/**
+* The nightly build setting, kept in the repository variable the workflow's
+* jobs read in their conditions (`GOODFELLOW_NIGHTLY`), which needs GitHub's
+* Variables permission: the owner's sign-in, or a token that has it.
+*/
+function githubNightly(read, manage, repo, workflow) {
+	const path = `/repos/${repo}/actions/variables`;
+	const notAllowed = (error) => {
+		if (error instanceof GitApiError && (error.status === 401 || error.status === 403)) throw new UpdatesError("not-allowed", "Changing when the site rebuilds needs GitHub's Variables permission.");
+		throw error;
+	};
+	return {
+		async supported() {
+			return (await workflow())?.includes(NIGHTLY_VARIABLE) ?? false;
+		},
+		async get() {
+			const response = await githubRequest(manage() ?? read, `${path}/${NIGHTLY_VARIABLE}`, { allow: [403, 404] });
+			if (response.status === 404) return "changed";
+			if (!response.ok) return void 0;
+			return nightlyMode((await response.json()).value);
+		},
+		async set(mode) {
+			const api = manage() ?? read;
+			if (mode === "changed") {
+				await githubRequest(api, `${path}/${NIGHTLY_VARIABLE}`, {
+					method: "DELETE",
+					allow: [404]
+				}).catch(notAllowed);
+				return;
 			}
+			const body = {
+				name: NIGHTLY_VARIABLE,
+				value: mode
+			};
+			if ((await githubRequest(api, `${path}/${NIGHTLY_VARIABLE}`, {
+				method: "PATCH",
+				body,
+				allow: [404]
+			}).catch(notAllowed)).status === 404) await githubRequest(api, path, {
+				method: "POST",
+				body
+			}).catch(notAllowed);
 		}
 	};
 }
@@ -465,16 +612,26 @@ function githubCodeUpdates(options) {
 		},
 		async start(target) {
 			await (await updates()).start(target);
+		},
+		async rebuild() {
+			await (await updates()).rebuild?.();
 		}
 	};
 }
 //#endregion
 //#region src/backend.ts
+/** Cloudflare Pages' check runs (its GitHub App is "Cloudflare Workers and Pages") and commit statuses. */
+const CLOUDFLARE = /cloudflare/i;
 /** How many files one GraphQL request reads. */
 const GRAPHQL_BATCH = 100;
 const COMMIT_MUTATION = `mutation ($input: CreateCommitOnBranchInput!) {
   createCommitOnBranch(input: $input) { commit { oid } }
 }`;
+/** The files under a folder of a tree, in order. */
+function listFrom(tree, dir) {
+	const prefix = `${dir}/`;
+	return [...tree.keys()].filter((path) => path.startsWith(prefix)).sort();
+}
 /**
 * The site's files on GitHub. Reads come from the commit `revision()` last
 * returned; saves are single commits made with GraphQL's `createCommitOnBranch`,
@@ -488,6 +645,8 @@ var GitHubBackend = class GitHubBackend {
 	/** Absent where the repository holds only content: the update job runs where the code is. */
 	updates;
 	drafts;
+	scheduledBuilds;
+	tasks;
 	contentOnly;
 	options;
 	api;
@@ -532,6 +691,13 @@ var GitHubBackend = class GitHubBackend {
 			})
 		});
 		this.drafts = branchDrafts(this, this.draftHost());
+		this.scheduledBuilds = githubScheduledBuilds((path) => this.read(path));
+		this.tasks = githubTasks(this.api, this.repo, this.branch, options.tasks);
+	}
+	async repositoryVisibility() {
+		const found = await githubJson(this.api, `/repos/${this.repo}`);
+		if (found.visibility === "internal") return "internal";
+		return found.private === false || found.visibility === "public" ? "public" : "private";
 	}
 	/** Drafts on branches of the repository, with pull requests for review. */
 	draftHost() {
@@ -564,6 +730,9 @@ var GitHubBackend = class GitHubBackend {
 				if (response.status === 404) throw new DraftError("not-found", `There's no draft ${branch}.`);
 				return (await response.json()).merge_base_commit.sha;
 			},
+			listBranches: async (prefix) => {
+				return (await githubJson(this.api, `${base}/git/matching-refs/heads/${encodeURIComponent(prefix)}`)).map((found) => found.ref.replace(/^refs\/heads\//, ""));
+			},
 			openReview: async ({ branch, title, description }) => {
 				const response = await githubRequest(this.api, `${base}/pulls`, {
 					method: "POST",
@@ -593,10 +762,13 @@ var GitHubBackend = class GitHubBackend {
 		};
 	}
 	async revision() {
-		const ref = await githubJson(this.api, `/repos/${this.repo}/git/ref/heads/${encodeURIComponent(this.branch)}`);
-		this.pinned = ref.object.sha;
+		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 githubJson(this.api, `/repos/${this.repo}/git/ref/heads/${encodeURIComponent(this.branch)}`)).object.sha;
+	}
 	/** Path → blob id for every file at a commit. Commits never change, so this is cached. */
 	tree(sha) {
 		let tree = this.trees.get(sha);
@@ -631,7 +803,9 @@ var GitHubBackend = class GitHubBackend {
 	}
 	/** Reads many text files in a few GraphQL requests rather than one request each. */
 	async readFiles(paths) {
-		const tree = await this.currentTree();
+		return this.readFilesFrom(await this.currentTree(), paths);
+	}
+	async readFilesFrom(tree, paths) {
 		const wanted = paths.flatMap((path) => {
 			const sha = tree.get(path);
 			return sha ? [[path, sha]] : [];
@@ -664,14 +838,24 @@ var GitHubBackend = class GitHubBackend {
 		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 githubRequest(this.api, `/repos/${this.repo}/git/blobs/${sha}`, { accept: "application/vnd.github.raw+json" });
 		return new Uint8Array(await response.arrayBuffer());
 	}
 	async list(dir) {
-		const prefix = `${dir}/`;
-		return [...(await this.currentTree()).keys()].filter((path) => path.startsWith(prefix)).sort();
+		return listFrom(await this.currentTree(), dir);
+	}
+	filesAt(revision) {
+		return {
+			read: async (path) => this.readFrom(await this.tree(revision), path),
+			readFiles: async (paths) => this.readFilesFrom(await this.tree(revision), paths),
+			readBytes: async (path) => this.bytesFrom(await this.tree(revision), path),
+			list: async (dir) => listFrom(await this.tree(revision), dir)
+		};
 	}
 	async fileSizes(dir) {
 		const prefix = `${dir}/`;
@@ -825,10 +1009,11 @@ var GitHubBackend = class GitHubBackend {
 		return [...new Set((comparison.files ?? []).flatMap((file) => [file.filename, file.previous_filename ?? []].flat()))];
 	}
 	/**
-	* Reads the deployment GitHub Pages or Vercel created for a commit, and for
-	* GitHub Actions, the workflow run that builds it: a build that fails never
-	* creates a deployment. Before either exists, the site counts as building
-	* if it has ever been deployed.
+	* Reads the deployment GitHub Pages or Vercel created for a commit, or what
+	* Cloudflare Pages reports on it, and for GitHub Actions, the workflow run
+	* that builds it: a build that fails never creates a deployment. Before any
+	* exists, the site counts as building if it has ever been deployed, or if
+	* Cloudflare reported on the commit before.
 	*/
 	async deployStatus(revision) {
 		try {
@@ -857,7 +1042,13 @@ var GitHubBackend = class GitHubBackend {
 					};
 				}
 			}
+			const cloudflare = await this.cloudflareBuild(revision);
+			if (cloudflare) return cloudflare;
 			const run = await this.workflowRun(revision);
+			if (run?.status === "completed" && run.conclusion === "cancelled") {
+				const head = await this.head();
+				if (head !== revision) return this.deployStatus(head);
+			}
 			if (run?.status === "completed" && run.conclusion !== "success" && run.conclusion !== "skipped") return {
 				state: "failed",
 				detailsUrl: run.html_url,
@@ -867,12 +1058,76 @@ var GitHubBackend = class GitHubBackend {
 				state: "building",
 				detailsUrl: run.html_url
 			};
-			return { state: (await githubJson(this.api, `/repos/${this.repo}/deployments?per_page=1`)).length > 0 ? "building" : "unknown" };
+			if ((await githubJson(this.api, `/repos/${this.repo}/deployments?per_page=1`)).length > 0) return { state: "building" };
+			const parent = await this.parentOf(revision);
+			return { state: parent && await this.cloudflareBuild(parent) ? "building" : "unknown" };
 		} catch (error) {
 			if (error instanceof GitApiError) return { state: "unknown" };
 			throw error;
 		}
 	}
+	/**
+	* What Cloudflare Pages reports on a commit: a check run of its GitHub App,
+	* or a commit status, which fine-grained tokens can read where check runs
+	* need a GitHub App's permission. `undefined` if it reported nothing.
+	*/
+	async cloudflareBuild(revision) {
+		const checks = await githubRequest(this.api, `/repos/${this.repo}/commits/${revision}/check-runs?per_page=50`, { allow: [403, 404] });
+		if (checks.ok) {
+			const { check_runs: found = [] } = await checks.json();
+			const run = found.find((candidate) => CLOUDFLARE.test(`${candidate.app?.slug ?? ""} ${candidate.name}`));
+			if (run) {
+				const detailsUrl = run.details_url ?? run.html_url ?? void 0;
+				if (run.status !== "completed") return {
+					state: "building",
+					detailsUrl
+				};
+				if (run.conclusion === "success" || run.conclusion === "neutral" || run.conclusion === "skipped") return {
+					state: "live",
+					detailsUrl
+				};
+				return {
+					state: "failed",
+					detailsUrl,
+					problem: {
+						step: "build",
+						detail: run.output?.title ?? void 0
+					}
+				};
+			}
+		}
+		const statuses = await githubRequest(this.api, `/repos/${this.repo}/commits/${revision}/statuses?per_page=50`, { allow: [403, 404] });
+		if (!statuses.ok) return void 0;
+		const status = (await statuses.json()).find((candidate) => CLOUDFLARE.test(candidate.context));
+		if (!status) return void 0;
+		const detailsUrl = status.target_url ?? void 0;
+		if (status.state === "success") return {
+			state: "live",
+			detailsUrl
+		};
+		if (status.state === "pending") return {
+			state: "building",
+			detailsUrl
+		};
+		return {
+			state: "failed",
+			detailsUrl,
+			problem: {
+				step: "build",
+				detail: status.description ?? void 0
+			}
+		};
+	}
+	/** The commit a commit was made on top of, if the token can see it. */
+	async parentOf(revision) {
+		const response = await githubRequest(this.api, `/repos/${this.repo}/commits/${revision}`, { allow: [
+			403,
+			404,
+			422
+		] });
+		if (!response.ok) return void 0;
+		return (await response.json()).parents?.[0]?.sha;
+	}
 	/** The site's deploy workflow run for a commit, or `undefined` if there's none or the token can't see Actions. */
 	async workflowRun(revision) {
 		const response = await githubRequest(this.api, `/repos/${this.repo}/actions/runs?head_sha=${revision}&per_page=20`, { allow: [403, 404] });
@@ -1143,6 +1398,25 @@ function setupAccount(creator) {
 			throw error;
 		}
 	}
+	/** Gives the repository's Pages a domain of its own, saying whether GitHub took it. */
+	async function setDomain(api, repo, domain) {
+		try {
+			await githubRequest(api, `/repos/${repoPath(repo.full_name)}/pages`, {
+				method: "PUT",
+				body: { cname: domain }
+			});
+			return true;
+		} catch (error) {
+			if (error instanceof GitApiError && [
+				400,
+				403,
+				404,
+				409,
+				422
+			].includes(error.status)) return false;
+			throw error;
+		}
+	}
 	/** Writes every file in one commit, which replaces the starting README rather than following it. */
 	async function writeFiles(api, repo, site) {
 		const base = `/repos/${repoPath(repo.full_name)}`;
@@ -1287,6 +1561,10 @@ function setupAccount(creator) {
 				onStep?.("pages");
 				siteUrl = await turnOnPages(api, repo);
 				if (!siteUrl) warnings.push("pages-unavailable");
+				else if (site.domain) {
+					if (await setDomain(api, repo, site.domain)) siteUrl = `https://${site.domain}/`;
+					else warnings.push("domain-unavailable");
+				}
 			}
 			createdApis.set(repo.full_name.toLowerCase(), api);
 			if (site.link && !await connect(site.link)) warnings.push("connect-unavailable");
@@ -1504,7 +1782,8 @@ function githubTokenLinks(repo, webUrl = "https://github.com") {
 		expires_in: "90",
 		contents: "write",
 		deployments: "read",
-		actions: "read"
+		actions: "read",
+		statuses: "read"
 	});
 	const classic = new URLSearchParams({
 		scopes: "repo",
@@ -1517,7 +1796,8 @@ function githubTokenLinks(repo, webUrl = "https://github.com") {
 		expires_in: "1",
 		administration: "write",
 		pages: "write",
-		actions: "write"
+		actions: "write",
+		variables: "write"
 	});
 	return {
 		fineGrained: `${webUrl}/settings/personal-access-tokens/new?${fineGrained}`,
@@ -1768,7 +2048,20 @@ function github(options) {
 	}
 	return {
 		name: "GitHub",
+		source: hostSource("@goodfellow-cms/github", "github", options, [
+			"fetch",
+			"storage",
+			"location"
+		]),
 		canRedirect: service !== void 0,
+		setup: () => githubSetup({
+			...options.apiUrl && { apiUrl: options.apiUrl },
+			...options.webUrl && { webUrl: options.webUrl },
+			...options.fetch && { fetch: options.fetch },
+			...options.storage && { storage: options.storage },
+			...options.location && { location: options.location },
+			signIn: false
+		}),
 		tokenLinks: [{
 			url: links.fineGrained,
 			label: "signIn.token.create"

package/dist/testing.d.ts

@@ -20,6 +20,8 @@ export interface FakeGitHubUser {
   actions?: boolean;
   /** Whether the token may run workflows, as owner tokens can. Defaults to the `administration` setting. */
   actionsWrite?: boolean;
+  /** Whether the token may read and change Actions variables, as owner tokens can. Defaults to the `administration` setting. */
+  variables?: boolean;
   /** Whether the token may set Actions secrets and add deploy keys. Defaults to true. */
   secrets?: boolean;
 }
@@ -74,6 +76,17 @@ export interface FakeGitHubOptions {
    * reports success after being checked this many times. Off by default.
    */
   deployAfterChecks?: number;
+  /**
+   * Simulates Cloudflare Pages: every commit to the default branch gets a
+   * build, which reports success after being checked this many times, as a
+   * check run of Cloudflare's GitHub App, or as a commit status. Off by default.
+   */
+  cloudflare?: {
+    afterChecks: number;
+    report?: "check-runs" | "statuses";
+  };
+  /** Answers 403 to reading check runs, as GitHub does for fine-grained tokens, which can't have the permission. */
+  checkRunsForbidden?: boolean;
   /** Organizations the users belong to, which new repositories can be created in. */
   orgs?: string[];
   /** The default branch of repositories created through the API, as an account's settings choose. Defaults to `main`. */
@@ -88,6 +101,23 @@ export interface FakeGitHubOptions {
   accounts?: string[];
   /** GitHub Apps, which the sign-in worker signs people in with. */
   apps?: FakeGitHubApp[];
+  /** Whether the site's repository is private. Public by default. */
+  private?: boolean;
+  /**
+   * Answers plugins' tasks, as the site's `plugin-task.yml` would: given each
+   * `repository_dispatch` event's payload, it gives the text the workflow's
+   * `answer` job leaves on the request's branch, or nothing for a workflow
+   * that never answers. Without it, events are only recorded.
+   */
+  tasks?: (payload: FakeTaskPayload) => string | undefined | Promise<string | undefined>;
+}
+/** A plugin task's `repository_dispatch` payload, as the admin panel sends it. */
+export interface FakeTaskPayload {
+  request: string;
+  plugin: string;
+  task: string;
+  input: string;
+  key: string;
 }
 /** A GitHub App, as the sign-in worker uses one: its JWTs, installations, OAuth sign-in and tokens. */
 export interface FakeGitHubApp {
@@ -129,6 +159,7 @@ export interface FakeCreatedRepo {
   repo: FakeRepo;
   pages?: {
     build_type: string;
+    cname?: string;
   };
   rulesets: unknown[];
   /** Deploy keys added to it, by their public key. */
@@ -150,6 +181,11 @@ interface Deployment {
   statuses: FakeDeploymentStatus[];
   checks: number;
 }
+/** A build Cloudflare Pages reports on a commit, which tests can fail with `failCloudflare()`. */
+export interface FakeCloudflareBuild {
+  checks: number;
+  failed?: boolean;
+}
 export declare function fakeGitHub(options: FakeGitHubOptions): {
   repo: FakeRepo;
   /** How many GraphQL requests read files, as `readFiles()` makes. */
@@ -182,9 +218,20 @@ export declare function fakeGitHub(options: FakeGitHubOptions): {
   invitations: FakeInvitation[];
   accept: (login: string) => void;
   deployments: Deployment[];
-  /** GitHub Actions workflow runs, which tests add with `failBuild()`. */
+  /** Cloudflare Pages' builds, by commit, with `cloudflare`; `failCloudflare()` makes one fail. */
+  cloudflareBuilds: Map<string, FakeCloudflareBuild>;
+  failCloudflare: (sha: string) => void;
+  /** GitHub Actions workflow runs, which tests add with `failBuild()` and `cancelBuild()`. */
   runs: FakeRun[];
+  /** `repository_dispatch` events sent, such as plugins' tasks. */
+  dispatches: {
+    event_type: string;
+    client_payload: FakeTaskPayload;
+  }[];
+  /** The repository's Actions variables, such as `GOODFELLOW_NIGHTLY`. */
+  variables: Map<string, string>;
   failBuild: (sha: string, step?: string, job?: string) => FakeRun;
+  cancelBuild: (sha: string) => FakeRun;
   /** Every request received, for checking what the backend sent. */
   requests: Request[];
   /** Simulates someone else publishing. */

package/dist/testing.js

@@ -53,7 +53,12 @@ function fakeGitHub(options) {
 	let nextToken = 1;
 	let nextRepoId = 100;
 	const deployments = [];
+	const cloudflareBuilds = /* @__PURE__ */ new Map();
 	const runs = [];
+	/** `repository_dispatch` events, in the order they were sent. */
+	const dispatches = [];
+	/** The repository's Actions variables, by name. */
+	const variables = /* @__PURE__ */ new Map();
 	const requests = [];
 	let nextDeployment = 1;
 	let graphqlReads = 0;
@@ -187,6 +192,23 @@ function fakeGitHub(options) {
 		runs.push(run);
 		return run;
 	}
+	/**
+	* Simulates the deploy workflow's run for a commit being cancelled, as a
+	* newer run in its concurrency group replaces one still waiting: it never
+	* deploys.
+	*/
+	function cancelBuild(sha) {
+		for (const [index, deployment] of [...deployments.entries()].reverse()) if (deployment.sha === sha) deployments.splice(index, 1);
+		const run = {
+			id: runs.length + 1,
+			sha,
+			status: "completed",
+			conclusion: "cancelled",
+			jobs: []
+		};
+		runs.push(run);
+		return run;
+	}
 	/** Simulates an invited person accepting the invitation. */
 	function accept(login) {
 		const index = invitations.findIndex((invitation) => invitation.login === login);
@@ -333,6 +355,12 @@ function fakeGitHub(options) {
 				build_type: site.pages.build_type
 			}, 201);
 		}
+		if (rest === "/pages" && method === "PUT" && site.pages) {
+			const body = await request.json();
+			if (body.cname && options.takenDomains?.includes(body.cname)) return json({ message: `The CNAME \`${body.cname}\` is already taken.` }, 422);
+			if (body.cname) site.pages.cname = body.cname;
+			return new Response(null, { status: 204 });
+		}
 		const notAllowed = (permission) => principal.app ? principal.permissions?.[permission] !== "write" : principal.secrets === false;
 		if (rest === "/keys" && method === "POST") {
 			if (notAllowed("administration")) return json({ message: "Resource not accessible by integration" }, 403);
@@ -447,6 +475,7 @@ function fakeGitHub(options) {
 		}
 	}
 	function deploy(sha) {
+		if (options.cloudflare) cloudflareBuilds.set(sha, { checks: 0 });
 		if (options.deployAfterChecks === void 0) return;
 		deployments.unshift({
 			id: nextDeployment++,
@@ -455,6 +484,20 @@ function fakeGitHub(options) {
 			checks: 0
 		});
 	}
+	/** Where a Cloudflare build is up to, counting the check. */
+	function cloudflareState(sha) {
+		const build = cloudflareBuilds.get(sha);
+		if (!build) return void 0;
+		build.checks += 1;
+		if (build.failed) return "failure";
+		return build.checks > (options.cloudflare?.afterChecks ?? 0) ? "success" : "building";
+	}
+	function failCloudflare(sha) {
+		cloudflareBuilds.set(sha, {
+			checks: 0,
+			failed: true
+		});
+	}
 	function commit(changes, message, expectedHead, author, branch = repo.defaultBranch) {
 		const sha = repo.commit(changes, message, {
 			expectedHead,
@@ -517,7 +560,8 @@ function fakeGitHub(options) {
 			pages: app.permissions.pages === "write",
 			workflow: app.permissions.workflows === "write",
 			actions: app.permissions.actions !== void 0,
-			actionsWrite: app.permissions.actions === "write"
+			actionsWrite: app.permissions.actions === "write",
+			variables: app.permissions.variables === "write"
 		});
 		refreshTokens.set(refresh, {
 			app,
@@ -625,7 +669,8 @@ function fakeGitHub(options) {
 				administration: permissions.administration === "write",
 				admin: permissions.administration === "write",
 				actions: permissions.actions !== void 0,
-				actionsWrite: permissions.actions === "write"
+				actionsWrite: permissions.actions === "write",
+				variables: permissions.variables === "write"
 			});
 			issued.push({
 				token,
@@ -768,7 +813,9 @@ function fakeGitHub(options) {
 		const contents = rest.match(/^\/contents\/(.+)$/);
 		if (contents && request.method === "GET") {
 			if (user.bot && !user.permissions?.contents) return json({ message: "Resource not accessible by integration" }, 403);
-			const file = repo.files(url.searchParams.get("ref") ?? repo.defaultBranch).get(decodeURIComponent(contents[1] ?? ""));
+			const ref = url.searchParams.get("ref") ?? repo.defaultBranch;
+			if (!repo.branches.has(ref) && !repo.commitAt(ref)) return json({ message: `No commit found for the ref ${ref}` }, 404);
+			const file = repo.files(ref).get(decodeURIComponent(contents[1] ?? ""));
 			if (file === void 0) return json({ message: "Not Found" }, 404);
 			return request.headers.get("accept")?.includes("raw") ? new Response(fakeFileBytes(file)) : json({
 				content: encodeBase64Bytes(fakeFileBytes(file)),
@@ -789,6 +836,17 @@ function fakeGitHub(options) {
 				object: { sha: body.sha }
 			}, 201);
 		}
+		const matching = rest.match(/^\/git\/matching-refs\/heads\/(.*)$/);
+		if (matching) {
+			const prefix = decodeURIComponent(matching[1] ?? "");
+			return json([...repo.branches].filter(([branch]) => branch.startsWith(prefix)).map(([branch, sha]) => ({
+				ref: `refs/heads/${branch}`,
+				object: {
+					sha,
+					type: "commit"
+				}
+			})));
+		}
 		const branchRef = rest.match(/^\/git\/refs\/heads\/(.+)$/);
 		if (branchRef && request.method === "DELETE") {
 			if (user.push === false) return json({ message: "Resource not accessible by integration" }, 403);
@@ -846,6 +904,8 @@ function fakeGitHub(options) {
 		if (rest === "") return json({
 			id: 1,
 			full_name: options.repo,
+			private: options.private === true,
+			visibility: options.private === true ? "private" : "public",
 			default_branch: repo.defaultBranch,
 			permissions: {
 				push: user.push !== false,
@@ -904,6 +964,42 @@ function fakeGitHub(options) {
 				author: null
 			})));
 		}
+		const variable = rest.match(/^\/actions\/variables(?:\/([\w-]+))?$/);
+		if (variable) {
+			if (!(user.variables ?? user.administration)) return json({ message: "Resource not accessible by personal access token" }, 403);
+			const [, name] = variable;
+			if (!name && request.method === "POST") {
+				const body = await request.json();
+				if (variables.has(body.name)) return json({ message: "Already exists" }, 409);
+				variables.set(body.name, body.value);
+				return new Response(null, { status: 201 });
+			}
+			if (name && !variables.has(name)) return json({ message: "Not Found" }, 404);
+			if (name && request.method === "GET") return json({
+				name,
+				value: variables.get(name)
+			});
+			if (name && request.method === "PATCH") {
+				const body = await request.json();
+				variables.set(name, body.value);
+				return new Response(null, { status: 204 });
+			}
+			if (name && request.method === "DELETE") {
+				variables.delete(name);
+				return new Response(null, { status: 204 });
+			}
+		}
+		if (rest === "/dispatches" && request.method === "POST") {
+			if (user.push === false || user.bot && user.permissions?.contents !== "write") return json({ message: "Resource not accessible by integration" }, 403);
+			const body = await request.json();
+			dispatches.push(body);
+			const answer = await options.tasks?.(body.client_payload);
+			if (answer !== void 0 && body.event_type === "goodfellow-plugin-task") {
+				const sha = repo.addCommit(void 0, `The answer to plugin task ${body.client_payload.request}`, /* @__PURE__ */ new Map([["goodfellow-task-result.json", `${answer}\n`]]));
+				repo.branches.set(`goodfellow-task-${body.client_payload.request}`, sha);
+			}
+			return new Response(null, { status: 204 });
+		}
 		const workflowFile = rest.match(/^\/actions\/workflows\/([\w.-]+)\/(?:dispatches|runs)$/)?.[1];
 		const workflowPath = `.github/workflows/${workflowFile}`;
 		const ofWorkflow = (run) => (run.path ?? ".github/workflows/deploy.yml") === workflowPath;
@@ -976,6 +1072,43 @@ function fakeGitHub(options) {
 				files: repo.changedPaths(base, b).map((filename) => ({ filename }))
 			});
 		}
+		const commitSha = rest.match(/^\/commits\/([0-9a-f]{40})$/)?.[1];
+		if (commitSha) {
+			const found = repo.commitAt(commitSha);
+			if (!found) return json({ message: "No commit found for SHA" }, 422);
+			return json({
+				sha: commitSha,
+				parents: found.parent ? [{ sha: found.parent }] : []
+			});
+		}
+		const checkRunsSha = rest.match(/^\/commits\/([0-9a-f]{40})\/check-runs$/)?.[1];
+		if (checkRunsSha) {
+			if (options.checkRunsForbidden) return json({ message: "Resource not accessible by personal access token" }, 403);
+			const state = options.cloudflare?.report === "statuses" ? void 0 : cloudflareState(checkRunsSha);
+			const runsFound = state ? [{
+				id: 1,
+				name: "Cloudflare Pages",
+				app: { slug: "cloudflare-workers-and-pages" },
+				status: state === "building" ? "in_progress" : "completed",
+				conclusion: state === "building" ? null : state,
+				details_url: `https://dash.cloudflare.com/builds/${checkRunsSha}`,
+				output: { title: state === "failure" ? "Build failed" : "Deployed" }
+			}] : [];
+			return json({
+				total_count: runsFound.length,
+				check_runs: runsFound
+			});
+		}
+		const statusesSha = rest.match(/^\/commits\/([0-9a-f]{40})\/statuses$/)?.[1];
+		if (statusesSha) {
+			const state = options.cloudflare?.report === "statuses" ? cloudflareState(statusesSha) : void 0;
+			return json(state ? [{
+				context: "Cloudflare Pages",
+				state: state === "building" ? "pending" : state,
+				target_url: `https://dash.cloudflare.com/builds/${statusesSha}`,
+				description: state === "failure" ? "Build failed" : "Deployed"
+			}] : []);
+		}
 		if (rest === "/deployments") {
 			const sha = url.searchParams.get("sha");
 			return json(deployments.filter((deployment) => !sha || deployment.sha === sha).slice(0, Number(url.searchParams.get("per_page") ?? 30)).map(({ id, sha }) => ({
@@ -1018,9 +1151,17 @@ function fakeGitHub(options) {
 		invitations,
 		accept,
 		deployments,
-		/** GitHub Actions workflow runs, which tests add with `failBuild()`. */
+		/** Cloudflare Pages' builds, by commit, with `cloudflare`; `failCloudflare()` makes one fail. */
+		cloudflareBuilds,
+		failCloudflare,
+		/** GitHub Actions workflow runs, which tests add with `failBuild()` and `cancelBuild()`. */
 		runs,
+		/** `repository_dispatch` events sent, such as plugins' tasks. */
+		dispatches,
+		/** The repository's Actions variables, such as `GOODFELLOW_NIGHTLY`. */
+		variables,
 		failBuild,
+		cancelBuild,
 		/** Every request received, for checking what the backend sent. */
 		requests,
 		/** Simulates someone else publishing. */

package/package.json

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