@goodfellow-cms/github 0.5.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, 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 } 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}`);

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)),
@@ -985,6 +989,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 +1156,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.6.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.6.0",
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0"
   },