Website: Query API options to preconfigure the GitHub export form (#1174

)

Adds a `custom-paths` export type to enable exporting a subset of a directory:

<img width="300"
src="https://github.com/WordPress/wordpress-playground/assets/205419/881e0013-d338-43c1-a5bb-ad05d13ce853">

Furthermore, it adds new Query API parameters to preconfigure the GitHub
export form:

* `gh-ensure-auth`: If set to `yes`, Playground will display a modal to
ensure the
					user is authenticated with GitHub before proceeding.
* `ghexport-repo-url`: The URL of the GitHub repository to export to.
* `ghexport-pr-action`: The action to take when exporting (create or
update).
* `ghexport-playground-root`: The root directory in the Playground to
export from.
* `ghexport-repo-root`: The root directory in the repository to export
to.
* `ghexport-content-type`: The content type of the export (plugin,
theme, wp-content, custom-paths).
* `ghexport-plugin`: Plugin path. When the content type is `plugin`,
pre-select the plugin to export.
* `ghexport-theme`: Theme directory name. When the content type is
`theme`, pre-select the theme to export.
* `ghexport-path`: A path relative to `ghexport-playground-root`. Can be
provided multiple times. When the
content type is `custom-paths`, it pre-populates the list of paths to
export.
* `ghexport-commit-message`: The commit message to use when exporting.
* `ghexport-allow-include-zip`: Whether to offer an option to include a
zip file in the GitHub
export (yes, no). Optional. Defaults to `yes`.

Related to https://github.com/adamziel/playground-docs-workflow

## Testing instructions

* Confirm the GitHub export form continues to work as it did before this
PR, that is you're able to export plugins, themes, and the entire
wp-content directory as pull requests.
* Go through the Query API options and confirm each does what the
description says.
* Attempt exporting two directories in the `custom-paths` mode.

Also, [click
here](http://localhost:5400/website-server/?gh-ensure-auth=yes&ghexport-repo-url=https%3A%2F%2Fgit.luolix.top%2Fadamziel%2Fplayground-docs-workflow&ghexport-content-type=custom-paths&ghexport-path=plugins/wp-docs-plugin&ghexport-path=html-pages&ghexport-path=uploads&ghexport-path=blueprint.json&ghexport-commit-message=Documentation+update&ghexport-playground-root=/wordpress/wp-content&ghexport-repo-root=/wp-content&blueprint-url=https%3A%2F%2Fraw.luolix.top%2Fadamziel%2Fplayground-docs-workflow%2Ftrunk%2Fwp-content%2Fblueprint.json&ghexport-pr-action=create&ghexport-allow-include-zip=no)
and confirm you're asked to authenticate with GitHub, the doc editing
plugin gets installed, and that you can make changes to docs pages and
export them to GitHub as a PR.

packages/docs/site/docs/08-query-api/01-index.md

@@ -50,3 +50,22 @@ For example, the following code embeds a Playground with a preinstalled Gutenber
 To import files from a URL, such as a site zip package, they must be served with `Access-Control-Allow-Origin` header set. For reference, see: [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_response_headers).
 
 :::
+
+## GitHub Export Options
+
+The following additional query parameters may be used to pre-configure the GitHub export form:
+
+-   `gh-ensure-auth`: If set to `yes`, Playground will display a modal to ensure the
+    user is authenticated with GitHub before proceeding.
+-   `ghexport-repo-url`: The URL of the GitHub repository to export to.
+-   `ghexport-pr-action`: The action to take when exporting (create or update).
+-   `ghexport-playground-root`: The root directory in the Playground to export from.
+-   `ghexport-repo-root`: The root directory in the repository to export to.
+-   `ghexport-content-type`: The content type of the export (plugin, theme, wp-content, custom-paths).
+-   `ghexport-plugin`: Plugin path. When the content type is `plugin`, pre-select the plugin to export.
+-   `ghexport-theme`: Theme directory name. When the content type is `theme`, pre-select the theme to export.
+-   `ghexport-path`: A path relative to `ghexport-playground-root`. Can be provided multiple times. When the
+    content type is `custom-paths`, it pre-populates the list of paths to export.
+-   `ghexport-commit-message`: The commit message to use when exporting.
+-   `ghexport-allow-include-zip`: Whether to offer an option to include a zip file in the GitHub
+    export (yes, no). Optional. Defaults to `yes`.

packages/playground/storage/src/lib/changeset.ts

@@ -8,6 +8,11 @@ export type IterateFilesOptions = {
 	 */
 	relativePaths?: boolean;
 
+	/**
+	 * The root directory that Playground paths start from.
+	 */
+	playgroundRoot?: string;
+
 	/**
 	 * A prefix to add to all paths.
 	 * Only used if `relativePaths` is true.
@@ -31,13 +36,21 @@ export type IterateFilesOptions = {
 export async function* iterateFiles(
 	playground: UniversalPHP,
 	root: string,
-	{
-		relativePaths = true,
-		pathPrefix,
-		exceptPaths = [],
-	}: IterateFilesOptions = {}
+	{ exceptPaths = [] }: IterateFilesOptions = {}
 ): AsyncGenerator<FileEntry> {
 	root = normalizePath(root);
+	// If the root is be a file, not a directory, then
+	// just yield it and return immediately.
+	if (!(await playground.isDir(root))) {
+		if (await playground.fileExists(root)) {
+			yield {
+				path: root,
+				read: async () => await playground.readFileAsBuffer(root),
+			};
+		}
+		return;
+	}
+
 	const stack: string[] = [root];
 	while (stack.length) {
 		const currentParent = stack.pop();
@@ -46,21 +59,15 @@ export async function* iterateFiles(
 		}
 		const files = await playground.listFiles(currentParent);
 		for (const file of files) {
-			const absPath = `${currentParent}/${file}`;
+			const absPath = joinPaths(currentParent, file);
 			if (exceptPaths.includes(absPath.substring(root.length + 1))) {
 				continue;
 			}
-			const isDir = await playground.isDir(absPath);
-			if (isDir) {
+			if (await playground.isDir(absPath)) {
 				stack.push(absPath);
 			} else {
 				yield {
-					path: relativePaths
-						? joinPaths(
-								pathPrefix || '',
-								absPath.substring(root.length + 1)
-						  )
-						: absPath,
+					path: absPath,
 					read: async () =>
 						await playground.readFileAsBuffer(absPath),
 				};
@@ -106,7 +113,7 @@ export type Changeset = {
  */
 export async function changeset(
 	filesBefore: Map<string, Uint8Array>,
-	filesAfter: AsyncGenerator<FileEntry>
+	filesAfter: AsyncGenerator<FileEntry> | Iterable<FileEntry>
 ) {
 	const changes: Changeset = {
 		create: new Map(),