@goodfellow-cms/github 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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";
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, OwnerAccess, PagesDomains, PluginTasks, RedirectOptions, RepositoryVisibility, RevisionFiles, ScheduledBuilds, SetupHost, SignInError, SiteComments, 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 {
@@ -38,6 +38,8 @@ interface GitHubBackendOptions {
   onSignOut: () => void;
   /** Where to create the owner token, which can change editors and GitHub Pages settings. */
   ownerTokenLink: TokenLink;
+  /** Where to create a token for the comments' repository, where the sign-in can't reach it. */
+  commentsTokenLink?: TokenLink;
   /** Signs in as an owner through the sign-in worker instead of with a token, where it's available. */
   ownerRedirect?: (options?: RedirectOptions) => Promise<void>;
   /**
@@ -80,6 +82,7 @@ export declare class GitHubBackend implements GitBackend {
   readonly drafts: SiteDrafts;
   readonly scheduledBuilds: ScheduledBuilds;
   readonly tasks: PluginTasks;
+  readonly comments: SiteComments;
   readonly contentOnly: boolean;
   private readonly options;
   private readonly api;
@@ -131,19 +134,19 @@ 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, or what
-   * Cloudflare Pages reports on it, and for GitHub Actions, the workflow run
+   * Reads the deployment GitHub Pages, Vercel or Netlify created for a commit,
+   * or what Cloudflare Pages or Netlify 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.
+   * What Cloudflare Pages or Netlify 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;
+  private hostBuild;
   /** 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. */
@@ -233,6 +236,7 @@ export declare function githubTokenLinks(repo: string, webUrl?: string): {
   fineGrained: string;
   classic: string;
   owner: string;
+  comments: string;
 };
 /** Sign-in and storage for a site whose repository is on GitHub. */
 export declare function github(options: GitHubOptions): GitHost;

package/dist/index.js

@@ -1,4 +1,4 @@
-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, withRateLimits } from "@goodfellow-cms/core";
+import { CommentsError, ConflictError, DomainError, DraftError, EditorsError, GISCUS_APP_URL, 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, withRateLimits } 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 = {}) {
@@ -30,6 +30,242 @@ function repoPath(repo) {
 	return repo.split("/").map((part) => encodeURIComponent(part)).join("/");
 }
 //#endregion
+//#region src/comments.ts
+/**
+* Comments on GitHub: the repository Giscus keeps them in, made or found
+* with REST, and its discussions read and moderated with GraphQL. Uses the
+* comments token where one is in use, and otherwise the site's own sign-in,
+* which reaches the repository where it's a token for every repository.
+*/
+/** How many pages' discussions one call lists, and how many comments and replies each brings. */
+const THREADS_PER_PAGE = 20;
+const COMMENTS_PER_THREAD = 50;
+const REPLIES_PER_COMMENT = 50;
+const CLASSIFIERS = {
+	spam: "SPAM",
+	abuse: "ABUSE",
+	"off-topic": "OFF_TOPIC"
+};
+/** The category Giscus recommends, where only it and the repository's owners can start discussions. */
+const ANNOUNCEMENTS = "announcements";
+const COMMENT_FIELDS = `id url bodyText createdAt isMinimized minimizedReason author { login url avatarUrl }`;
+const THREADS_QUERY = `query ($owner: String!, $name: String!, $category: ID!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    discussions(first: ${THREADS_PER_PAGE}, after: $after, categoryId: $category, orderBy: { field: UPDATED_AT, direction: DESC }) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id title url locked updatedAt
+        comments(first: ${COMMENTS_PER_THREAD}) {
+          nodes { ${COMMENT_FIELDS} replies(first: ${REPLIES_PER_COMMENT}) { nodes { ${COMMENT_FIELDS} } } }
+        }
+      }
+    }
+  }
+}`;
+const CATEGORIES_QUERY = `query ($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    discussionCategories(first: 25) { nodes { id name slug } }
+  }
+}`;
+function comment(node) {
+	return {
+		id: node.id,
+		author: {
+			login: node.author?.login ?? "ghost",
+			url: node.author?.url ?? "https://github.com/ghost",
+			...node.author?.avatarUrl && { avatarUrl: node.author.avatarUrl }
+		},
+		text: node.bodyText,
+		createdAt: node.createdAt,
+		url: node.url,
+		hidden: node.isMinimized,
+		...node.isMinimized && node.minimizedReason && { hiddenReason: node.minimizedReason.toLowerCase() },
+		replies: (node.replies?.nodes ?? []).map(comment)
+	};
+}
+/** Giscus's install page, for the account the repository is in. */
+function installUrl(ownerId) {
+	return `${GISCUS_APP_URL}/installations/new/permissions?target_id=${ownerId}`;
+}
+function isRefused(error) {
+	return error instanceof SignInError || error instanceof GitApiError && [403, 404].includes(error.status);
+}
+/**
+* Where to create a token for comments: a classic one with \`public_repo\`,
+* which can create a public repository and moderate its discussions. A
+* fine-grained token can't reach a repository that doesn't exist yet.
+*/
+function commentsTokenLink(webUrl, siteRepo) {
+	return {
+		url: `${webUrl}/settings/tokens/new?${new URLSearchParams({
+			scopes: "public_repo",
+			description: `Goodfellow comments for ${siteRepo}`
+		})}`,
+		label: "comments.token.create"
+	};
+}
+function githubComments(base, siteRepo, tokenLink) {
+	let own;
+	const api = () => own ?? base;
+	async function graphql(query, variables) {
+		const answer = await githubJson(api(), "/graphql", {
+			method: "POST",
+			body: {
+				query,
+				variables
+			}
+		}).catch((error) => {
+			if (isRefused(error)) throw new CommentsError("no-access", "GitHub refused the sign-in for comments.");
+			throw error;
+		});
+		const error = answer.errors?.[0];
+		if (error) {
+			if (error.type === "FORBIDDEN" || error.type === "NOT_FOUND" || /not have permission|resource not accessible/i.test(error.message)) throw new CommentsError("no-access", error.message);
+			throw new Error(error.message);
+		}
+		return answer.data;
+	}
+	/** The repository's category for announcements, or else its first, as Giscus needs. */
+	async function placeOf(found) {
+		const [owner = "", name = ""] = found.full_name.split("/");
+		let categories = [];
+		for (let attempt = 0; attempt < 3; attempt++) {
+			categories = (await graphql(CATEGORIES_QUERY, {
+				owner,
+				name
+			})).repository?.discussionCategories.nodes ?? [];
+			if (categories.length > 0) break;
+			await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
+		}
+		const category = categories.find((candidate) => candidate.slug === ANNOUNCEMENTS) ?? categories[0];
+		if (!category) throw new CommentsError("no-category", "The repository's Discussions have no categories yet.", `${found.html_url}/discussions`);
+		return {
+			repo: found.full_name,
+			repoId: found.node_id,
+			category: category.name,
+			categoryId: category.id,
+			webUrl: found.html_url,
+			installUrl: installUrl(found.owner.id)
+		};
+	}
+	/** Turns Discussions on where they're off, which needs the repository's admin. */
+	async function withDiscussions(found) {
+		if (found.has_discussions) return found;
+		if (found.permissions?.admin === false) throw new CommentsError("no-discussions", "Discussions are off.", `${found.html_url}/settings`);
+		return githubJson(api(), `/repos/${repoPath(found.full_name)}`, {
+			method: "PATCH",
+			body: { has_discussions: true }
+		}).catch((error) => {
+			if (isRefused(error)) throw new CommentsError("no-discussions", "Discussions are off.", `${found.html_url}/settings`);
+			throw error;
+		});
+	}
+	async function mutate(mutation, input) {
+		await graphql(`mutation ($input: ${mutation}Input!) { ${mutation[0]?.toLowerCase()}${mutation.slice(1)}(input: $input) { clientMutationId } }`, { input });
+	}
+	return {
+		access: {
+			tokenLink,
+			get active() {
+				return own !== void 0;
+			},
+			async applyToken(token) {
+				const candidate = {
+					...base,
+					token: token.trim()
+				};
+				try {
+					await githubJson(candidate, "/user");
+				} catch (error) {
+					if (isRefused(error)) throw new CommentsError("no-access", "GitHub didn't accept this token.");
+					throw error;
+				}
+				own = candidate;
+			},
+			forget() {
+				own = void 0;
+			}
+		},
+		async create(name, description) {
+			const wanted = name.trim();
+			if (!/^[\w.-]+$/.test(wanted) || /^\.+$/.test(wanted)) throw new CommentsError("name-invalid", "That can't be a repository's name.");
+			const user = await githubJson(api(), "/user").catch((error) => {
+				if (isRefused(error)) throw new CommentsError("no-access", "GitHub refused the sign-in for comments.");
+				throw error;
+			});
+			const siteOwner = siteRepo.split("/")[0] ?? "";
+			const path = siteOwner.toLowerCase() === user.login.toLowerCase() ? "/user/repos" : `/orgs/${encodeURIComponent(siteOwner)}/repos`;
+			return placeOf(await withDiscussions(await githubJson(api(), path, {
+				method: "POST",
+				body: {
+					name: wanted,
+					description,
+					private: false,
+					has_discussions: true,
+					has_issues: false,
+					has_projects: false,
+					has_wiki: false,
+					auto_init: true
+				}
+			}).catch((error) => {
+				if (error instanceof GitApiError && error.status === 422) throw new CommentsError("name-taken", "There's already a repository with that name.");
+				if (isRefused(error)) throw new CommentsError("no-access", "This sign-in can't create repositories there.");
+				throw error;
+			})));
+		},
+		async find(repo) {
+			const wanted = repo.trim().replace(/^https:\/\/github\.com\//i, "").replace(/\/+$/, "");
+			if (!/^[\w.-]+\/[\w.-]+$/.test(wanted)) throw new CommentsError("not-found", "That isn't a repository's name.");
+			const found = await githubJson(api(), `/repos/${repoPath(wanted)}`).catch((error) => {
+				if (isRefused(error)) throw new CommentsError("not-found", "GitHub has no such repository for this sign-in.");
+				throw error;
+			});
+			if (found.private) throw new CommentsError("not-public", "The repository is private.", `${found.html_url}/settings`);
+			return placeOf(await withDiscussions(found));
+		},
+		async threads(place, next) {
+			const [owner = "", name = ""] = place.repo.split("/");
+			const data = await graphql(THREADS_QUERY, {
+				owner,
+				name,
+				category: place.categoryId,
+				after: next ?? null
+			});
+			if (!data.repository) throw new CommentsError("not-found", "GitHub has no such repository for this sign-in.");
+			const { pageInfo, nodes } = data.repository.discussions;
+			return {
+				threads: nodes.map((node) => ({
+					id: node.id,
+					title: node.title,
+					url: node.url,
+					locked: node.locked,
+					updatedAt: node.updatedAt,
+					comments: node.comments.nodes.map(comment)
+				})),
+				...pageInfo.hasNextPage && pageInfo.endCursor && { next: pageInfo.endCursor }
+			};
+		},
+		async hide(commentId, reason) {
+			await mutate("MinimizeComment", {
+				subjectId: commentId,
+				classifier: CLASSIFIERS[reason]
+			});
+		},
+		async show(commentId) {
+			await mutate("UnminimizeComment", { subjectId: commentId });
+		},
+		async remove(commentId) {
+			await mutate("DeleteDiscussionComment", { id: commentId });
+		},
+		async lock(threadId) {
+			await mutate("LockLockable", { lockableId: threadId });
+		},
+		async unlock(threadId) {
+			await mutate("UnlockLockable", { lockableId: threadId });
+		}
+	};
+}
+//#endregion
 //#region src/editors.ts
 /** GitHub account names: letters, digits and single hyphens, up to 39 characters. */
 const USERNAME = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i;
@@ -66,15 +302,19 @@ function githubEditors(read, manage, repo, login) {
 			throw error;
 		}
 	}
-	async function collaborators(api) {
+	/** Every page of a list, 100 at a time. */
+	async function allPages(api, list) {
 		const all = [];
 		for (let page = 1; page <= 10; page++) {
-			const found = await githubJson(api, `${path}/collaborators?per_page=100&page=${page}`);
+			const found = await githubJson(api, `${path}/${list}?per_page=100&page=${page}`);
 			all.push(...found);
 			if (found.length < 100) break;
 		}
 		return all;
 	}
+	function collaborators(api) {
+		return allPages(api, "collaborators");
+	}
 	return {
 		invitesByEmail: false,
 		async list() {
@@ -82,7 +322,7 @@ function githubEditors(read, manage, repo, login) {
 			const people = await collaborators(api);
 			let invitations;
 			try {
-				invitations = await githubJson(api, `${path}/invitations?per_page=100`);
+				invitations = await allPages(api, "invitations");
 			} catch (error) {
 				if (!isNotAllowed(error)) throw error;
 			}
@@ -620,10 +860,20 @@ function githubCodeUpdates(options) {
 }
 //#endregion
 //#region src/backend.ts
-/** Cloudflare Pages' check runs (its GitHub App is "Cloudflare Workers and Pages") and commit statuses. */
-const CLOUDFLARE = /cloudflare/i;
+/**
+* The check runs and commit statuses of hosts that build the site themselves
+* and report to GitHub: Cloudflare Pages (its GitHub App is "Cloudflare Workers
+* and Pages") and Netlify's deploys (`netlify/<site>/deploy…`), but not its
+* other checks, such as "Header rules", which finish before the deploy does.
+* Netlify's GitHub App also creates a deployment, which `deployStatus()` reads first.
+*/
+const HOST_BUILDS = /cloudflare|netlify\/\S+\/deploy/i;
 /** How many files one GraphQL request reads. */
 const GRAPHQL_BATCH = 100;
+/** The most files GitHub's compare lists. */
+const COMPARE_FILES_LIMIT = 300;
+/** How many pages of open pull requests are read for drafts' reviews: a thousand. */
+const REVIEW_PAGES = 10;
 const COMMIT_MUTATION = `mutation ($input: CreateCommitOnBranchInput!) {
   createCommitOnBranch(input: $input) { commit { oid } }
 }`;
@@ -647,6 +897,7 @@ var GitHubBackend = class GitHubBackend {
 	drafts;
 	scheduledBuilds;
 	tasks;
+	comments;
 	contentOnly;
 	options;
 	api;
@@ -693,6 +944,7 @@ 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);
+		this.comments = githubComments(this.api, options.repo, options.commentsTokenLink ?? commentsTokenLink("https://github.com", options.repo));
 	}
 	async repositoryVisibility() {
 		const found = await githubJson(this.api, `/repos/${this.repo}`);
@@ -775,10 +1027,17 @@ var GitHubBackend = class GitHubBackend {
 				return { url: review.html_url };
 			},
 			listReviews: async (prefix) => {
-				const pulls = await githubJson(this.api, `${base}/pulls?${new URLSearchParams({
-					state: "open",
-					per_page: "100"
-				})}`);
+				const pulls = [];
+				for (let page = 1; page <= REVIEW_PAGES; page++) {
+					const query = new URLSearchParams({
+						state: "open",
+						per_page: "100",
+						page: String(page)
+					});
+					const found = await githubJson(this.api, `${base}/pulls?${query}`);
+					pulls.push(...found);
+					if (found.length < 100) break;
+				}
 				const repo = decodeURIComponent(this.repo).toLowerCase();
 				return pulls.filter((pull) => pull.head.ref.startsWith(prefix) && (pull.head.repo?.full_name ?? repo).toLowerCase() === repo).map((pull) => ({
 					branch: pull.head.ref,
@@ -1043,12 +1302,13 @@ var GitHubBackend = class GitHubBackend {
 		return this.readFrom(await this.tree(revision), path);
 	}
 	async changedPaths(from, to) {
-		const comparison = await githubJson(this.api, `/repos/${this.repo}/compare/${from}...${to}`);
-		return [...new Set((comparison.files ?? []).flatMap((file) => [file.filename, file.previous_filename ?? []].flat()))];
+		const files = (await githubJson(this.api, `/repos/${this.repo}/compare/${from}...${to}`)).files ?? [];
+		if (files.length >= COMPARE_FILES_LIMIT) throw new GitApiError(0, `More files changed between ${from} and ${to} than GitHub lists.`);
+		return [...new Set(files.flatMap((file) => [file.filename, file.previous_filename ?? []].flat()))];
 	}
 	/**
-	* 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
+	* Reads the deployment GitHub Pages, Vercel or Netlify created for a commit,
+	* or what Cloudflare Pages or Netlify 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.
@@ -1080,8 +1340,8 @@ var GitHubBackend = class GitHubBackend {
 					};
 				}
 			}
-			const cloudflare = await this.cloudflareBuild(revision);
-			if (cloudflare) return cloudflare;
+			const hosted = await this.hostBuild(revision);
+			if (hosted) return hosted;
 			const run = await this.workflowRun(revision);
 			if (run?.status === "completed" && run.conclusion === "cancelled") {
 				const head = await this.head();
@@ -1098,22 +1358,22 @@ var GitHubBackend = class GitHubBackend {
 			};
 			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" };
+			return { state: parent && await this.hostBuild(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.
+	* What Cloudflare Pages or Netlify 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) {
+	async hostBuild(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}`));
+			const run = found.find((candidate) => HOST_BUILDS.test(`${candidate.app?.slug ?? ""} ${candidate.name}`));
 			if (run) {
 				const detailsUrl = run.details_url ?? run.html_url ?? void 0;
 				if (run.status !== "completed") return {
@@ -1136,7 +1396,7 @@ var GitHubBackend = class GitHubBackend {
 		}
 		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));
+		const status = (await statuses.json()).find((candidate) => HOST_BUILDS.test(candidate.context));
 		if (!status) return void 0;
 		const detailsUrl = status.target_url ?? void 0;
 		if (status.state === "success") return {
@@ -1194,6 +1454,7 @@ var GitHubBackend = class GitHubBackend {
 	}
 	signOut() {
 		this.ownerAccess.forget();
+		this.comments.access.forget();
 		this.onSignOut();
 	}
 };
@@ -1636,11 +1897,20 @@ async function tokenCreator(api) {
 			avatarUrl: user.avatar_url
 		},
 		async owners() {
-			return [{
+			const own = {
 				path: user.login,
 				name: user.name || user.login,
 				kind: "personal"
-			}, ...(await githubJson(api, "/user/orgs?per_page=100").catch(() => [])).map((org) => ({
+			};
+			const orgs = [];
+			try {
+				for (let page = 1; page <= 10; page++) {
+					const found = await githubJson(api, `/user/orgs?per_page=100&page=${page}`);
+					orgs.push(...found);
+					if (found.length < 100) break;
+				}
+			} catch {}
+			return [own, ...orgs.map((org) => ({
 				path: org.login,
 				name: org.login,
 				kind: "organization"
@@ -1840,7 +2110,8 @@ function githubTokenLinks(repo, webUrl = "https://github.com") {
 	return {
 		fineGrained: `${webUrl}/settings/personal-access-tokens/new?${fineGrained}`,
 		classic: `${webUrl}/settings/tokens/new?${classic}`,
-		owner: `${webUrl}/settings/personal-access-tokens/new?${owner}`
+		owner: `${webUrl}/settings/personal-access-tokens/new?${owner}`,
+		comments: commentsTokenLink(webUrl, repo).url
 	};
 }
 /** Sign-in and storage for a site whose repository is on GitHub. */
@@ -1945,6 +2216,10 @@ function github(options) {
 				url: links.owner,
 				label: "owner.token.create"
 			},
+			commentsTokenLink: {
+				url: links.comments,
+				label: "comments.token.create"
+			},
 			ownerRedirect: (redirectOptions) => redirect("owner", false, redirectOptions)
 		});
 	}
@@ -2041,6 +2316,10 @@ function github(options) {
 				url: links.owner,
 				label: "owner.token.create"
 			},
+			commentsTokenLink: {
+				url: links.comments,
+				label: "comments.token.create"
+			},
 			...service && { ownerRedirect: (redirectOptions) => redirect("owner", false, redirectOptions) }
 		});
 	}
@@ -2073,6 +2352,10 @@ function github(options) {
 				url: links.owner,
 				label: "owner.token.create"
 			},
+			commentsTokenLink: {
+				url: links.comments,
+				label: "comments.token.create"
+			},
 			...revision && { revision },
 			...author && { author }
 		});

package/dist/testing.d.ts

@@ -24,6 +24,8 @@ export interface FakeGitHubUser {
   variables?: boolean;
   /** Whether the token may set Actions secrets and add deploy keys. Defaults to true. */
   secrets?: boolean;
+  /** A fine-grained token's repositories, which it alone reaches. Others reach every repository the user can. */
+  repositories?: string[];
 }
 /** A GitHub Actions workflow run, with its jobs and their steps. */
 export interface FakeRun {
@@ -85,6 +87,14 @@ export interface FakeGitHubOptions {
     afterChecks: number;
     report?: "check-runs" | "statuses";
   };
+  /**
+   * Simulates Netlify, as `cloudflare` does Cloudflare Pages: its GitHub App's
+   * "Header rules" check run, which finishes at once, and a commit status for
+   * the deploy, which reports success after being checked this many times.
+   */
+  netlify?: {
+    afterChecks: number;
+  };
   /** 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. */
@@ -97,6 +107,8 @@ export interface FakeGitHubOptions {
   pages?: boolean;
   /** Domains another GitHub Pages site already uses. */
   takenDomains?: string[];
+  /** Turning on Discussions makes no categories yet, as GitHub sometimes doesn't until someone opens them. */
+  noDiscussionCategories?: boolean;
   /** Other GitHub accounts that exist, which can be invited. Every token's user exists too. */
   accounts?: string[];
   /** GitHub Apps, which the sign-in worker signs people in with. */
@@ -174,6 +186,33 @@ export interface FakeCreatedRepo {
   secretKey?: CryptoKeyPair;
   /** People's permission on it, by login, as `collaborators/{login}/permission` says; others have none. */
   collaborators?: Map<string, "admin" | "write" | "read">;
+  /** Whether Discussions are on, and their categories and discussions, as the Comments block keeps them. */
+  discussions?: boolean;
+  categories: FakeDiscussionCategory[];
+  threads: FakeDiscussion[];
+}
+export interface FakeDiscussionCategory {
+  id: string;
+  name: string;
+  slug: string;
+}
+/** A visitor's comment on a page's discussion, or a reply to one. */
+export interface FakeDiscussionComment {
+  id: string;
+  login: string;
+  text: string;
+  createdAt: string;
+  minimized?: string;
+  replies: FakeDiscussionComment[];
+}
+/** A page's discussion, as Giscus starts one. */
+export interface FakeDiscussion {
+  id: string;
+  title: string;
+  categoryId: string;
+  locked: boolean;
+  updatedAt: string;
+  comments: FakeDiscussionComment[];
 }
 interface Deployment {
   id: number;
@@ -208,7 +247,22 @@ export declare function fakeGitHub(options: FakeGitHubOptions): {
     files?: Record<string, string>;
     private?: boolean;
     collaborators?: Record<string, "admin" | "write" | "read">;
+    /** Turns Discussions on, with GitHub's usual categories. */
+    discussions?: boolean;
   }) => FakeCreatedRepo;
+  /** Starts a page's discussion in a repository with Discussions, as Giscus does. */
+  addDiscussion: (fullName: string, discussion: {
+    title: string;
+    category?: string;
+    comments: Array<{
+      login: string;
+      text: string;
+      replies?: Array<{
+        login: string;
+        text: string;
+      }>;
+    }>;
+  }) => FakeDiscussion;
   /** The site's GitHub Pages settings, which tests can change, such as to issue the certificate. */
   pages: {
     current?: FakePages;

package/dist/testing.js

@@ -29,6 +29,15 @@ function decodeJwtPart(part) {
 		return;
 	}
 }
+/** The categories GitHub makes as Discussions are turned on. */
+const DEFAULT_CATEGORIES = [
+	"Announcements",
+	"General",
+	"Ideas",
+	"Polls",
+	"Q&A",
+	"Show and tell"
+];
 function json(body, status = 200) {
 	return new Response(JSON.stringify(body), {
 		status,
@@ -225,18 +234,167 @@ function fakeGitHub(options) {
 			rulesets: [],
 			deployKeys: [],
 			secrets: /* @__PURE__ */ new Map(),
-			collaborators: new Map(Object.entries(repoOptions.collaborators ?? {}))
+			collaborators: new Map(Object.entries(repoOptions.collaborators ?? {})),
+			categories: [],
+			threads: []
 		};
+		if (repoOptions.discussions) enableDiscussions(added);
 		created.set(fullName, added);
 		return added;
 	}
+	let nextNode = 1;
+	function enableDiscussions(target) {
+		target.discussions = true;
+		if (target.categories.length > 0 || options.noDiscussionCategories) return;
+		target.categories = DEFAULT_CATEGORIES.map((category) => ({
+			id: `DIC_${target.id}_${nextNode++}`,
+			name: category,
+			slug: category.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
+		}));
+	}
+	/** Starts a page's discussion with comments, as Giscus does when visitors write them. */
+	function addDiscussion(fullName, discussion) {
+		const target = created.get(fullName);
+		if (!target?.discussions) throw new Error(`${fullName} has no Discussions.`);
+		const category = target.categories.find((candidate) => candidate.name === (discussion.category ?? "Announcements")) ?? target.categories[0];
+		const at = new Date(Date.UTC(2026, 9, 1, 12, nextNode)).toISOString();
+		const made = (comment) => ({
+			id: `DC_${nextNode++}`,
+			login: comment.login,
+			text: comment.text,
+			createdAt: at,
+			replies: (comment.replies ?? []).map((reply) => made(reply))
+		});
+		const added = {
+			id: `D_${nextNode++}`,
+			title: discussion.title,
+			categoryId: category?.id ?? "",
+			locked: false,
+			updatedAt: at,
+			comments: discussion.comments.map(made)
+		};
+		target.threads.unshift(added);
+		return added;
+	}
+	/** GitHub's GraphQL for Discussions, as the admin panel's comments screen asks it. */
+	function handleDiscussions(body, principal) {
+		const variables = body.variables ?? {};
+		const query = body.query.trimStart();
+		if (query.startsWith("query") && /discussionCategories|discussions\(/.test(query)) {
+			const fullName = `${variables.owner}/${variables.name}`;
+			const target = created.get(fullName);
+			if (!target || principal.bot || !canSee(principal, fullName)) return json({
+				data: { repository: null },
+				errors: [{
+					type: "NOT_FOUND",
+					message: "Could not resolve to a Repository"
+				}]
+			});
+			if (query.includes("discussionCategories")) return json({ data: { repository: { discussionCategories: { nodes: target.categories } } } });
+			const comment = (item) => ({
+				id: item.id,
+				url: `https://github.com/${fullName}/discussions#${item.id}`,
+				bodyText: item.text,
+				createdAt: item.createdAt,
+				isMinimized: item.minimized !== void 0,
+				minimizedReason: item.minimized ?? null,
+				author: {
+					login: item.login,
+					url: `https://github.com/${item.login}`,
+					avatarUrl: `https://avatars.example/${item.login}`
+				},
+				replies: { nodes: item.replies.map(comment) }
+			});
+			const inCategory = target.threads.filter((thread) => thread.categoryId === variables.category);
+			const start = typeof variables.after === "string" ? Number(variables.after) : 0;
+			const more = start + 20 < inCategory.length;
+			return json({ data: { repository: { discussions: {
+				pageInfo: {
+					hasNextPage: more,
+					endCursor: more ? String(start + 20) : null
+				},
+				nodes: inCategory.slice(start, start + 20).map((thread) => ({
+					id: thread.id,
+					title: thread.title,
+					url: `https://github.com/${fullName}/discussions/${thread.id}`,
+					locked: thread.locked,
+					updatedAt: thread.updatedAt,
+					comments: { nodes: thread.comments.map(comment) }
+				}))
+			} } } });
+		}
+		const mutation = query.match(/\b(minimizeComment|unminimizeComment|deleteDiscussionComment|lockLockable|unlockLockable)\(/)?.[1];
+		if (!mutation || !query.startsWith("mutation")) return void 0;
+		const input = variables.input ?? {};
+		const id = input.subjectId ?? input.id ?? input.lockableId ?? "";
+		const find = (items) => {
+			for (const item of items) {
+				if (item.id === id) return {
+					list: items,
+					item
+				};
+				const inner = find(item.replies);
+				if (inner) return inner;
+			}
+		};
+		for (const target of created.values()) {
+			const thread = target.threads.find((candidate) => candidate.id === id);
+			const found = target.threads.map((candidate) => find(candidate.comments)).find(Boolean);
+			if (!thread && !found) continue;
+			const role = target.collaborators?.get(principal.login);
+			if (!(!principal.bot && canSee(principal, target.fullName) && (target.collaborators?.size ? role === "admin" || role === "write" : true))) return json({
+				data: null,
+				errors: [{
+					type: "FORBIDDEN",
+					message: "Resource not accessible by personal access token"
+				}]
+			});
+			if (thread) thread.locked = mutation === "lockLockable";
+			else if (found) {
+				if (mutation === "deleteDiscussionComment") found.list.splice(found.list.indexOf(found.item), 1);
+				if (mutation === "minimizeComment") found.item.minimized = (input.classifier ?? "").toLowerCase().replace(/_/g, "-");
+				if (mutation === "unminimizeComment") delete found.item.minimized;
+			}
+			return json({ data: { [mutation]: { clientMutationId: null } } });
+		}
+		return json({
+			data: null,
+			errors: [{
+				type: "NOT_FOUND",
+				message: `Could not resolve to a node with the global id of '${id}'`
+			}]
+		});
+	}
+	/** A repository as GitHub's REST API describes it. */
+	function repositoryJson(site, principal) {
+		const [ownerLogin = ""] = site.fullName.split("/");
+		const role = site.collaborators?.get(principal.login);
+		const admin = site.collaborators?.size ? role === "admin" : true;
+		return {
+			id: site.id,
+			node_id: `R_${site.id}`,
+			full_name: site.fullName,
+			html_url: `https://github.com/${site.fullName}`,
+			private: site.private,
+			default_branch: site.repo.defaultBranch,
+			has_discussions: site.discussions === true,
+			owner: {
+				id: accountId(ownerLogin),
+				login: ownerLogin
+			},
+			permissions: {
+				push: admin || role === "write",
+				admin
+			}
+		};
+	}
 	/** Repository creation and the Git data API, for repositories created through the fake. */
 	async function handleCreated(request, path, principal) {
 		const login = principal.login;
 		if (path === "/user/orgs") return json((options.orgs ?? []).map((org) => ({ login: org })));
 		const create = path === "/user/repos" ? login : path.match(/^\/orgs\/([^/]+)\/repos$/)?.[1];
 		if (create !== void 0 && request.method === "POST") {
-			if (principal.bot || principal.app && principal.permissions?.administration !== "write") return json({ message: "Resource not accessible by integration" }, 403);
+			if (principal.bot || principal.repositories || principal.app && principal.permissions?.administration !== "write") return json({ message: "Resource not accessible by integration" }, 403);
 			if (path !== "/user/repos" && !options.orgs?.includes(create)) return json({ message: "Not Found" }, 404);
 			const body = await request.json();
 			if (!/^[\w.-]+$/.test(body.name)) return json({ message: "Repository creation failed." }, 422);
@@ -255,14 +413,13 @@ function fakeGitHub(options) {
 				repo,
 				rulesets: [],
 				deployKeys: [],
-				secrets: /* @__PURE__ */ new Map()
+				secrets: /* @__PURE__ */ new Map(),
+				categories: [],
+				threads: []
 			});
-			return json({
-				id,
-				full_name: fullName,
-				html_url: `https://github.com/${fullName}`,
-				default_branch: repo.defaultBranch
-			}, 201);
+			const made = created.get(fullName);
+			if (made && body.has_discussions) enableDiscussions(made);
+			return json(made ? repositoryJson(made, principal) : {}, 201);
 		}
 		const match = path.match(/^\/repos\/([^/]+\/[^/]+)(\/.*)?$/);
 		const site = created.get(decodeURIComponent(match?.[1] ?? ""));
@@ -271,16 +428,7 @@ function fakeGitHub(options) {
 		const { repo } = site;
 		const rest = match[2] ?? "";
 		const method = request.method;
-		if (rest === "" && method === "GET") return json({
-			id: site.id,
-			full_name: site.fullName,
-			private: site.private,
-			default_branch: repo.defaultBranch,
-			permissions: {
-				push: true,
-				admin: true
-			}
-		});
+		if (rest === "" && method === "GET") return json(repositoryJson(site, principal));
 		const tree = rest.match(/^\/git\/trees\/([0-9a-f]{40})$/);
 		if (tree && method === "GET" && repo.commitAt(tree[1] ?? "")) {
 			const entries = [...repo.files(tree[1] ?? "")].map(([file, content]) => ({
@@ -318,14 +466,14 @@ function fakeGitHub(options) {
 		}
 		if (rest === "" && method === "PATCH") {
 			const body = await request.json();
+			if (!repositoryJson(site, principal).permissions.admin) return json({ message: "Must have admin rights to Repository." }, 403);
 			if (body.default_branch) {
 				if (!repo.branches.has(body.default_branch)) return json({ message: "Not Found" }, 422);
 				repo.defaultBranch = body.default_branch;
 			}
-			return json({
-				full_name: site.fullName,
-				default_branch: repo.defaultBranch
-			});
+			if (body.has_discussions) enableDiscussions(site);
+			if (body.has_discussions === false) site.discussions = false;
+			return json(repositoryJson(site, principal));
 		}
 		const ref = rest.match(/^\/git\/refs?\/heads\/(.+)$/);
 		if (ref && method === "GET") {
@@ -475,7 +623,7 @@ function fakeGitHub(options) {
 		}
 	}
 	function deploy(sha) {
-		if (options.cloudflare) cloudflareBuilds.set(sha, { checks: 0 });
+		if (options.cloudflare || options.netlify) cloudflareBuilds.set(sha, { checks: 0 });
 		if (options.deployAfterChecks === void 0) return;
 		deployments.unshift({
 			id: nextDeployment++,
@@ -490,7 +638,7 @@ function fakeGitHub(options) {
 		if (!build) return void 0;
 		build.checks += 1;
 		if (build.failed) return "failure";
-		return build.checks > (options.cloudflare?.afterChecks ?? 0) ? "success" : "building";
+		return build.checks > (options.cloudflare?.afterChecks ?? options.netlify?.afterChecks ?? 0) ? "success" : "building";
 	}
 	function failCloudflare(sha) {
 		cloudflareBuilds.set(sha, {
@@ -752,6 +900,8 @@ function fakeGitHub(options) {
 			return accounts.has(login) ? json({ login }) : json({ message: "Not Found" }, 404);
 		}
 		if (path === "/graphql" && request.method === "POST") {
+			const discussions = handleDiscussions(await request.clone().json(), user);
+			if (discussions) return discussions;
 			const body = await request.clone().json();
 			if (body.query.trimStart().startsWith("query")) {
 				if (`${body.variables?.owner}/${body.variables?.name}` !== options.repo) return json({
@@ -868,7 +1018,10 @@ function fakeGitHub(options) {
 		}
 		if (rest === "/pulls" && request.method === "GET") {
 			const head = url.searchParams.get("head")?.split(":")[1];
-			return json(repo.reviews.filter((review) => review.state === "open" && (!head || review.branch === head)).map((review) => ({
+			const found = repo.reviews.filter((review) => review.state === "open" && (!head || review.branch === head));
+			const perPage = Number(url.searchParams.get("per_page") ?? 30);
+			const page = Number(url.searchParams.get("page") ?? 1);
+			return json(found.slice((page - 1) * perPage, page * perPage).map((review) => ({
 				number: review.number,
 				title: review.title,
 				html_url: `https://github.com/${options.repo}/pull/${review.number}`,
@@ -1108,6 +1261,19 @@ function fakeGitHub(options) {
 		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);
+			if (options.netlify) {
+				const known = cloudflareBuilds.has(checkRunsSha);
+				return json({
+					total_count: known ? 1 : 0,
+					check_runs: known ? [{
+						id: 1,
+						name: "Header rules - parish",
+						app: { slug: "netlify" },
+						status: "completed",
+						conclusion: "neutral"
+					}] : []
+				});
+			}
 			const state = options.cloudflare?.report === "statuses" ? void 0 : cloudflareState(checkRunsSha);
 			const runsFound = state ? [{
 				id: 1,
@@ -1125,6 +1291,15 @@ function fakeGitHub(options) {
 		}
 		const statusesSha = rest.match(/^\/commits\/([0-9a-f]{40})\/statuses$/)?.[1];
 		if (statusesSha) {
+			if (options.netlify) {
+				const deploy = cloudflareState(statusesSha);
+				return json(deploy ? [{
+					context: "netlify/parish/deploy-preview",
+					state: deploy === "building" ? "pending" : deploy,
+					target_url: `https://app.netlify.com/sites/parish/deploys/${statusesSha}`,
+					description: deploy === "failure" ? "Deploy failed" : "Deploy is ready!"
+				}] : []);
+			}
 			const state = options.cloudflare?.report === "statuses" ? cloudflareState(statusesSha) : void 0;
 			return json(state ? [{
 				context: "Cloudflare Pages",
@@ -1168,6 +1343,8 @@ function fakeGitHub(options) {
 		/** Repositories created through the API, or added with `addRepo()`, by `owner/name`. */
 		created,
 		addRepo,
+		/** Starts a page's discussion in a repository with Discussions, as Giscus does. */
+		addDiscussion,
 		/** The site's GitHub Pages settings, which tests can change, such as to issue the certificate. */
 		pages,
 		/** The repository's collaborators, by login, and invitations waiting to be accepted. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodfellow-cms/github",
-  "version": "0.7.0",
-  "description": "Edit a Goodfellow site stored on GitHub, straight from the browser.",
+  "version": "0.9.0",
+  "description": "Edit a Goodfellow CMS site stored on GitHub, straight from the browser.",
   "keywords": [
     "goodfellow",
     "cms",
@@ -12,6 +12,10 @@
   ],
   "homepage": "https://goodfellow-cms.github.io/goodfellow-cms/docs/hosts",
   "bugs": "https://github.com/goodfellow-cms/goodfellow-cms/issues",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/goodfellow-cms"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,7 +39,7 @@
     "dist"
   ],
   "dependencies": {
-    "@goodfellow-cms/core": "0.7.0",
+    "@goodfellow-cms/core": "0.9.0",
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0"
   },