Build/Test Tools: Support testing unmerged changes from Gutenberg.

The `gutenberg.sha` property in the `package.json` file expects a full-length SHA value to be specified in order to download the built assets from the Gutenberg repository and include the files through the build script.

After WordPress/gutenberg#78211, assets are now published for `pull_request` events in addition to `push` so long as the `HEAD` branch of the pull request exists in the repository and not in a fork. This makes the built assets for pull requests available for testing within `wordpress-develop` before they are merged through a `pr-###` tag on the GHCR package.

To test a given pull request, just set the `gutenberg.sha` value to the corresponding `pr-###` tag. In addition to pull request-specific tags, each `wp/X.Y`, `release/X.Y`, and `trunk` now have a tag that can be used to test the latest changes. Each time `build` or `build:dev` is called the script will attempt to confirm the latest version of the assets are present locally, pulling down the latest changes when an update is available.

All of the tags described in this changeset are mutable, so they should never be committed. Only immutable SHA values should be used for `gutenberg.sha` in commits to this repository.

This commit also adds the related JavaScript files to the TypeScript configuration file.

Props westonruter, jorbin, manhar.
Fixes #65224.

git-svn-id: https://develop.svn.wordpress.org/trunk@62422 602fd350-edb4-49c9-b593-d223f7449a82

Author: desrosj

package-lock.json

@@ -35,6 +35,7 @@
 		"@types/espree": "10.1.0",
 		"@types/htmlhint": "1.1.5",
 		"@types/jquery": "3.5.34",
+		"@types/node": "20.19.41",
 		"@types/underscore": "1.13.0",
 		"@wordpress/e2e-test-utils-playwright": "1.42.0",
 		"@wordpress/prettier-config": "4.42.0",

package.json

@@ -8,18 +8,74 @@
  * existing gutenberg directory is removed before extraction.
  *
  * The artifact is identified by the "gutenberg.sha" value in the root
- * package.json, which is used as the OCI image tag for the gutenberg-build
- * package on GitHub Container Registry.
+ * package.json, which is used as the OCI tag for the gutenberg-wp-develop-build
+ * package on GitHub Container Registry. The value is normally a Git SHA, but
+ * may also be a mutable tag (e.g. "trunk", "pr-12345") in a pull request that
+ * wants to track the latest build of a stream. When the ref is a mutable tag,
+ * the script resolves it to the immutable SHA tag for the actual blob fetch
+ * and falls back to the mutable tag's manifest when the immutable tag is
+ * unavailable.
  *
  * @package WordPress
  */
 
 const { spawn } = require( 'child_process' );
 const fs = require( 'fs' );
-const { Writable } = require( 'stream' );
+const { Readable } = require( 'stream' );
 const { pipeline } = require( 'stream/promises' );
 const zlib = require( 'zlib' );
-const { gutenbergDir, readGutenbergConfig } = require( './utils' );
+const {
+	gutenbergDir,
+	readGutenbergConfig,
+	fetchGhcrToken,
+	fetchManifest,
+} = require( './utils' );
+
+/**
+ * Resolve the manifest to use for downloading.
+ *
+ * For immutable refs (SHA values), the ref is used directly.
+ *
+ * For mutable refs, the mutable tag's manifest is fetched first and the
+ * `image.revision` annotation is read. The corresponding immutable SHA tag is
+ * then preferred. If the immutable SHA tag is unavailable, fall back to the
+ * manifest already fetched via the mutable tag.
+ *
+ * @param {{ ref: string, ghcrRepo: string, isMutable: boolean }} config
+ * @param {string} token
+ * @return {Promise<{ manifest: Record<string, any>, resolvedRef: string }>}
+ */
+async function resolveDownloadManifest( config, token ) {
+	const { ref, ghcrRepo, isMutable } = config;
+
+	const initialManifest = await fetchManifest( ref, ghcrRepo, token );
+
+	if ( ! isMutable ) {
+		return { manifest: initialManifest, resolvedRef: ref };
+	}
+
+	const revision =
+		initialManifest?.annotations?.[ 'org.opencontainers.image.revision' ];
+	if ( ! revision ) {
+		console.log(
+			`ℹ️  No image.revision annotation on "${ ref }"; using mutable tag for download.`
+		);
+		return { manifest: initialManifest, resolvedRef: ref };
+	}
+
+	try {
+		const immutableManifest = await fetchManifest( revision, ghcrRepo, token );
+		return { manifest: immutableManifest, resolvedRef: revision };
+	} catch ( error ) {
+		if ( /** @type {{ status?: number }} */ ( error ).status === 404 ) {
+			console.log(
+				`ℹ️  Immutable SHA tag ${ revision } unavailable; falling back to mutable tag "${ ref }".`
+			);
+			return { manifest: initialManifest, resolvedRef: ref };
+		}
+		throw error;
+	}
+}
 
 /**
  * Main execution function.
@@ -31,61 +87,56 @@ async function main() {
 	 * Read Gutenberg configuration from package.json.
 	 *
 	 * Note: ghcr stands for GitHub Container Registry where wordpress-develop ready builds of the Gutenberg plugin
-	 * are published on every repository push event.
+	 * are published by the Gutenberg build-plugin-zip workflow.
 	 */
-	let sha, ghcrRepo;
+	let config;
 	try {
-		( { sha, ghcrRepo } = readGutenbergConfig() );
-		console.log( `   SHA: ${ sha }` );
-		console.log( `   GHCR repository: ${ ghcrRepo }` );
+		config = readGutenbergConfig();
+		console.log(
+			`   Ref: ${ config.ref }${
+				config.isMutable ? ' (mutable tag)' : ''
+			}`
+		);
+		console.log( `   GHCR repository: ${ config.ghcrRepo }` );
 	} catch ( error ) {
-		console.error( '❌ Error reading package.json:', error.message );
+		console.error( '❌ Error reading package.json:', /** @type {Error} */ ( error ).message );
 		process.exit( 1 );
 	}
 
 	// Step 1: Get an anonymous GHCR token for pulling.
 	console.log( '\n🔑 Fetching GHCR token...' );
 	let token;
 	try {
-		const response = await fetch( `https://ghcr.io/token?scope=repository:${ ghcrRepo }:pull&service=ghcr.io` );
-		if ( ! response.ok ) {
-			throw new Error( `Failed to fetch token: ${ response.status } ${ response.statusText }` );
-		}
-		const data = await response.json();
-		token = data.token;
-		if ( ! token ) {
-			throw new Error( 'No token in response' );
-		}
+		token = await fetchGhcrToken( config.ghcrRepo );
 		console.log( '✅ Token acquired' );
 	} catch ( error ) {
-		console.error( '❌ Failed to fetch token:', error.message );
+		console.error( '❌ Failed to fetch token:', /** @type {Error} */ ( error ).message );
 		process.exit( 1 );
 	}
 
-	// Step 2: Get the manifest to find the blob digest.
-	console.log( `\n📋 Fetching manifest for ${ sha }...` );
-	let digest;
+	// Step 2: Resolve the manifest to use for download.
+	console.log( `\n📋 Fetching manifest for ${ config.ref }...` );
+	let manifest, resolvedRef;
 	try {
-		const response = await fetch( `https://ghcr.io/v2/${ ghcrRepo }/manifests/${ sha }`, {
-			headers: {
-				Authorization: `Bearer ${ token }`,
-				Accept: 'application/vnd.oci.image.manifest.v1+json',
-			},
-		} );
-		if ( ! response.ok ) {
-			throw new Error( `Failed to fetch manifest: ${ response.status } ${ response.statusText }` );
-		}
-		const manifest = await response.json();
-		digest = manifest?.layers?.[ 0 ]?.digest;
-		if ( ! digest ) {
-			throw new Error( 'No layer digest found in manifest' );
+		( { manifest, resolvedRef } = await resolveDownloadManifest(
+			config,
+			token
+		) );
+		if ( resolvedRef !== config.ref ) {
+			console.log( `   Resolved to immutable SHA tag: ${ resolvedRef }` );
 		}
-		console.log( `✅ Blob digest: ${ digest }` );
 	} catch ( error ) {
-		console.error( '❌ Failed to fetch manifest:', error.message );
+		console.error( '❌ Failed to fetch manifest:', /** @type {Error} */ ( error ).message );
 		process.exit( 1 );
 	}
 
+	const digest = manifest?.layers?.[ 0 ]?.digest;
+	if ( ! digest ) {
+		console.error( '❌ No layer digest found in manifest' );
+		process.exit( 1 );
+	}
+	console.log( `✅ Blob digest: ${ digest }` );
+
 	// Remove existing gutenberg directory so the extraction is clean.
 	if ( fs.existsSync( gutenbergDir ) ) {
 		console.log( '\n🗑️  Removing existing gutenberg directory...' );
@@ -100,14 +151,17 @@ async function main() {
 	 */
 	console.log( `\n📥 Downloading and extracting artifact...` );
 	try {
-		const response = await fetch( `https://ghcr.io/v2/${ ghcrRepo }/blobs/${ digest }`, {
+		const response = await fetch( `https://ghcr.io/v2/${ config.ghcrRepo }/blobs/${ digest }`, {
 			headers: {
 				Authorization: `Bearer ${ token }`,
 			},
 		} );
 		if ( ! response.ok ) {
 			throw new Error( `Failed to download blob: ${ response.status } ${ response.statusText }` );
 		}
+		if ( ! response.body ) {
+			throw new Error( 'Blob response has no body' );
+		}
 
 		/*
 		 * Spawn tar to read from stdin and extract into gutenbergDir.
@@ -117,6 +171,7 @@ async function main() {
 			stdio: [ 'pipe', 'inherit', 'inherit' ],
 		} );
 
+		/** @type {Promise<void>} */
 		const tarDone = new Promise( ( resolve, reject ) => {
 			tar.on( 'close', ( code ) => {
 				if ( code !== 0 ) {
@@ -134,16 +189,18 @@ async function main() {
 		 * consistent and means tar only sees plain tar data on stdin.
 		 */
 		await pipeline(
-			response.body,
+			Readable.fromWeb(
+				/** @type {import('stream/web').ReadableStream} */ ( response.body )
+			),
 			zlib.createGunzip(),
-			Writable.toWeb( tar.stdin ),
+			tar.stdin,
 		);
 
 		await tarDone;
 
 		console.log( '✅ Download and extraction complete' );
 	} catch ( error ) {
-		console.error( '❌ Download/extraction failed:', error.message );
+		console.error( '❌ Download/extraction failed:', /** @type {Error} */ ( error ).message );
 		process.exit( 1 );
 	}