@goodfellow-cms/github 0.5.0 → 0.7.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, 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, 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;
   /**
@@ -68,6 +79,7 @@ export declare class GitHubBackend implements GitBackend {
   readonly updates?: SiteUpdates;
   readonly drafts: SiteDrafts;
   readonly scheduledBuilds: ScheduledBuilds;
+  readonly tasks: PluginTasks;
   readonly contentOnly: boolean;
   private readonly options;
   private readonly api;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ConflictError, DomainError, DraftError, EditorsError, GitApiError, NIGHTLY_VARIABLE, REBUILD_JOB, SetupError, SignInError, UpdatesError, assertContentChanges, branchDrafts, buildStepFor, compareReleases, credentialStorage, decodeBase64, encodeBase64, encodeBase64Bytes, hostSource, nightlyMode, 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, 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 = {}) {
@@ -349,6 +349,71 @@ function githubScheduledBuilds(read) {
 	} };
 }
 //#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";
@@ -581,6 +646,7 @@ var GitHubBackend = class GitHubBackend {
 	updates;
 	drafts;
 	scheduledBuilds;
+	tasks;
 	contentOnly;
 	options;
 	api;
@@ -626,6 +692,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);
 	}
 	async repositoryVisibility() {
 		const found = await githubJson(this.api, `/repos/${this.repo}`);
@@ -636,6 +703,14 @@ var GitHubBackend = class GitHubBackend {
 	draftHost() {
 		const base = `/repos/${this.repo}`;
 		const ref = (branch) => `${base}/git/refs/heads/${encodeURIComponent(branch)}`;
+		const openPulls = (branch) => {
+			const owner = decodeURIComponent(this.repo).split("/")[0];
+			const query = new URLSearchParams({
+				head: `${owner}:${branch}`,
+				state: "open"
+			});
+			return githubJson(this.api, `${base}/pulls?${query}`);
+		};
 		return {
 			liveBranch: this.branch,
 			branchStore: (branch) => new GitHubBackend({
@@ -666,7 +741,7 @@ var GitHubBackend = class GitHubBackend {
 			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 }) => {
+			openReview: async ({ branch, title, description, reviewers = [] }) => {
 				const response = await githubRequest(this.api, `${base}/pulls`, {
 					method: "POST",
 					body: {
@@ -681,16 +756,46 @@ var GitHubBackend = class GitHubBackend {
 						422
 					]
 				});
-				if (response.ok) return { url: (await response.json()).html_url };
-				if (response.status !== 422) throw new DraftError("no-reviews", "This sign-in can't open pull requests on the site's repository.");
-				const owner = decodeURIComponent(this.repo).split("/")[0];
-				const query = new URLSearchParams({
-					head: `${owner}:${branch}`,
-					state: "open"
+				let review;
+				if (response.ok) review = await response.json();
+				else if (response.status !== 422) throw new DraftError("no-reviews", "This sign-in can't open pull requests on the site's repository.");
+				else {
+					[review] = await openPulls(branch);
+					if (!review) throw new GitApiError(422, "GitHub couldn't open the pull request.");
+				}
+				for (const reviewer of reviewers) await githubRequest(this.api, `${base}/pulls/${review.number}/requested_reviewers`, {
+					method: "POST",
+					body: { reviewers: [reviewer] },
+					allow: [
+						403,
+						404,
+						422
+					]
+				});
+				return { url: review.html_url };
+			},
+			listReviews: async (prefix) => {
+				const pulls = await githubJson(this.api, `${base}/pulls?${new URLSearchParams({
+					state: "open",
+					per_page: "100"
+				})}`);
+				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,
+					url: pull.html_url,
+					title: pull.title
+				}));
+			},
+			closeReview: async (branch) => {
+				for (const pull of await openPulls(branch)) await githubRequest(this.api, `${base}/pulls/${pull.number}`, {
+					method: "PATCH",
+					body: { state: "closed" },
+					allow: [
+						403,
+						404,
+						422
+					]
 				});
-				const [open] = await githubJson(this.api, `${base}/pulls?${query}`);
-				if (!open) throw new GitApiError(422, "GitHub couldn't open the pull request.");
-				return { url: open.html_url };
 			}
 		};
 	}
@@ -1753,7 +1858,7 @@ function github(options) {
 	const links = githubTokenLinks(options.repo, options.webUrl);
 	const storage = credentialStorage(`goodfellow:github:${options.repo}`, options.storage);
 	const pending = credentialStorage(`goodfellow:github:pending:${options.repo}`, options.storage);
-	const fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const fetcher = withRateLimits(options.fetch ?? ((input, init) => globalThis.fetch(input, init)), { host: "GitHub" });
 	const location = options.location ?? browserLocation();
 	const signInUrl = options.signIn;
 	const service = signInUrl && location && !isLocalAddress(location.href()) ? new SignInService(signInUrl, fetcher) : void 0;

package/dist/testing.d.ts

@@ -103,6 +103,21 @@ export interface FakeGitHubOptions {
   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 {
@@ -208,6 +223,11 @@ export declare function fakeGitHub(options: FakeGitHubOptions): {
   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;

package/dist/testing.js

@@ -55,6 +55,8 @@ function fakeGitHub(options) {
 	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 = [];
@@ -811,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)),
@@ -866,9 +870,33 @@ function fakeGitHub(options) {
 			const head = url.searchParams.get("head")?.split(":")[1];
 			return json(repo.reviews.filter((review) => review.state === "open" && (!head || review.branch === head)).map((review) => ({
 				number: review.number,
-				html_url: `https://github.com/${options.repo}/pull/${review.number}`
+				title: review.title,
+				html_url: `https://github.com/${options.repo}/pull/${review.number}`,
+				head: {
+					ref: review.branch,
+					repo: { full_name: options.repo }
+				}
 			})));
 		}
+		const pull = rest.match(/^\/pulls\/(\d+)(\/requested_reviewers)?$/);
+		if (pull) {
+			const review = repo.reviews.find((found) => found.number === Number(pull[1]));
+			if (!review) return json({ message: "Not Found" }, 404);
+			if (user.bot && user.permissions?.pull_requests !== "write") return json({ message: "Resource not accessible by integration" }, 403);
+			if (pull[2] && request.method === "POST") {
+				const body = await request.json();
+				if ((body.reviewers ?? []).some((login) => login === user.login || login.startsWith("not-"))) return json({ message: "Reviews may only be requested from collaborators." }, 422);
+				review.reviewers.push(...body.reviewers ?? []);
+				return json({ number: review.number }, 201);
+			}
+			if (!pull[2] && request.method === "PATCH") {
+				if ((await request.json()).state === "closed") review.state = "closed";
+				return json({
+					number: review.number,
+					state: review.state
+				});
+			}
+		}
 		if (rest === "/pages" && request.method === "GET") {
 			const site = pages.current;
 			if (!site) return json({ message: "Not Found" }, 404);
@@ -985,6 +1013,17 @@ function fakeGitHub(options) {
 				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;
@@ -1141,6 +1180,8 @@ function fakeGitHub(options) {
 		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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfellow-cms/github",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Edit a Goodfellow site stored on GitHub, straight from the browser.",
   "keywords": [
     "goodfellow",
@@ -35,7 +35,7 @@
     "dist"
   ],
   "dependencies": {
-    "@goodfellow-cms/core": "0.5.0",
+    "@goodfellow-cms/core": "0.7.0",
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0"
   },