Merge branch 'trunk' into renovate/pnpm-9.x

Author: kraftbj

.cursor/rules/adding-changelog.mdc

@@ -0,0 +1,21 @@
+---
+description: How changelog entries must be structured for each change
+globs: 
+---
+Every change in the `/projects` directory will need to add a specially-formatted file to the project's specified `changelog` directory.
+
+The change file is a text file with a header-and-body format, like HTTP or email. A change file might look like this:
+
+```
+Significance: patch
+Type: compat
+
+Block Editor: update all blocks to be fully compatible with WordPress 5.7.
+```
+
+The “Significance” header specifies the significance of change in the style of semantic versioning: patch, minor, or major.
+
+The “Type” header categorizes the change in the changelog. In Jetpack, for example, our changelog divides changes into “Major Enhancements”, “Enhancements”, “Improved compatibility”, and “Bugfixes”.
+Type must be "security", "added", "changed", "deprecated", "removed", or "fixed"
+
+The body is separated from the headers by a blank line, and is the text that actually goes into the changelog. This should follow our recommendations at [writing-a-good-changelog-entry.md](mdc:jetpack/jetpack/jetpack/docs/writing-a-good-changelog-entry.md).

.cursor/rules/code-style-structure.mdc

@@ -0,0 +1,13 @@
+---
+description: General guidelines on code style and structure
+globs: 
+---
+General guidelines are defined in [coding-guidelines.md](mdc:jetpack/jetpack/jetpack/jetpack/jetpack/jetpack/jetpack/jetpack/jetpack/jetpack/docs/coding-guidelines.md).
+
+### Naming Conventions
+
+- Use WordPress naming conventions for functions and classes
+- Prefix any global php functions or hooks with `jetpack_`
+- Use lowercase with underscores for PHP functions
+- Follow WordPress React component naming patterns
+- Use BEM-like naming for SCSS

.cursor/rules/development-guidelines.mdc

@@ -0,0 +1,42 @@
+---
+description: General development guidelines
+globs: 
+---
+You are an expert WordPress plugin developer specializing in site building tools, with deep expertise in WordPress core, React, PHP, and modern frontend development. You prioritize WordPress coding standards while delivering maintainable, accessible solutions.
+
+## Short codes
+
+Check the start of any user message for the following short codes and act appropriately:
+
+- ddc - short for `discuss don't code` so do not make any code changes only discuss the options until given the go ahead to make changes.
+- jdi - short for `just do it` so this is giving approval to go ahead and make the changes that have been discussed.
+
+## Analysis Process
+
+Before responding to any request, follow these steps:
+
+1. Request Analysis
+
+- Determine if task involves plugin core (PHP) or frontend (JS/React)
+- Identify WordPress hooks and filters needed
+- Note compatibility requirements (WordPress version, PHP version), based on the different versions specified in [versions.sh](mdc:jetpack/jetpack/jetpack/jetpack/jetpack/.github/versions.sh)
+- Define core functionality and user experience goals
+- Consider WordPress coding standards compliance
+
+2. Solution Planning
+
+- Break down solution into WordPress-compatible components
+- Consider plugin activation/deactivation hooks
+- Identify necessary WordPress API integrations
+- Plan for internationalization (i18n)
+- Evaluate security implications
+
+3. Implementation Strategy
+
+- Choose appropriate WordPress design patterns
+- Consider performance impact on WordPress site
+- Plan for WordPress error handling conventions
+- Ensure WordPress coding standards compliance
+- Verify accessibility requirements
+
+Always prioritize WordPress coding standards and best practices while delivering functionality that enhances the WordPress site-building experience.

.cursor/rules/js-react-standards.mdc

@@ -0,0 +1,26 @@
+---
+description: JavaScript/React Standards
+globs: *.js, *.jsx, *.ts, *.tsx
+---
+## General guidelines
+
+- Write modern ES6+ code following WordPress JS standards
+- Use WordPress data store for state management
+- Follow WordPress component patterns
+- Implement proper WordPress hooks system
+- Structure components using WordPress conventions
+- Where it applies, make strings available for translation.
+- Use Gutenberg's `@wordpress/i18n` package to handle translations.
+- Use an appropriate unique text domain in your JS code.
+
+## React Components
+
+- Use WordPress `@wordpress/element` instead of direct React import
+- Implement WordPress hooks system
+- Follow WordPress component lifecycle patterns
+- Use the WordPress block editor data stores for state management of WordPress block editor components
+- Follow WordPress accessibility guidelines
+
+## TypeScript
+
+- When using TypeScript in Webpack, use `@babel/preset-typescript` rather than `ts-loader`.

.cursor/rules/js-testing.mdc

@@ -0,0 +1,14 @@
+---
+description: Guidelines to write JavaScript tests
+globs: 
+---
+- Use Jest with WordPress test utilities
+- Follow WordPress testing patterns
+- Test React components with `@testing-library/react`
+- Implement proper async testing
+- Use WordPress mocking patterns
+
+
+Check [component.tsx](mdc:jetpack/jetpack/jetpack/jetpack/projects/packages/my-jetpack/_inc/components/connection-status-card/test/component.tsx) for an example.
+
+Find out more about how to develop tests at [automated-testing.md](mdc:jetpack/jetpack/docs/automated-testing.md)

.cursor/rules/php-standards.mdc

@@ -0,0 +1,20 @@
+---
+description: PHP coding standards
+globs: *.php
+---
+- Follow WordPress PHP Coding Standards
+- Use proper WordPress prefix for functions and classes
+- Implement WordPress nonce verification
+- Follow WordPress database operations best practices
+- Structure plugin hooks logically
+
+## Package Version Annotations
+
+When needing to add a package version number inside a DocBlock, please use `$$next-version$$` as such:
+
+- `@since $$next-version$$`
+- `@deprecated $$next-version$$`
+- `@deprecated since $$next-version$$`
+- `_deprecated_function( __METHOD__, 'package-$$next-version$$' );` (other WordPress deprecation functions also work, but note it must be all on one line).
+
+The `$$next-version$$` specifier will be automatically replaced with the correct package version number the next time a new version of that package is released.

.cursor/rules/php-testing.mdc

@@ -0,0 +1,14 @@
+---
+description: Guidelines when testing PHP
+globs: 
+---
+When developing Unit Tests in PHP, follow these guidelines:
+
+- Use PHPUnit with WordPress test framework
+- Follow WordPress testing conventions
+- Use WordPress fixtures and mocks
+- Test WordPress hooks and filters
+
+Check [test_Manager_integration.php](mdc:jetpack/jetpack/jetpack/jetpack/projects/packages/connection/tests/php/test_Manager_integration.php) for an example.
+
+Find out more rules on how to write tests at [automated-testing.md](mdc:jetpack/jetpack/docs/automated-testing.md)

.github/files/setup-wordpress-env.sh

@@ -33,6 +33,12 @@ git clone --depth=1 --branch "$WORDPRESS_TAG" git://develop.git.wordpress.org/ "
 # We need a built version of WordPress to test against, so download that into the src directory instead of what's in wordpress-develop.
 rm -rf "/tmp/wordpress-$WP_BRANCH/src"
 git clone --depth=1 --branch "$WORDPRESS_TAG" git://core.git.wordpress.org/ "/tmp/wordpress-$WP_BRANCH/src"
+
+echo "::group::Setting up WordPress uploads directory"
+mkdir -p "/tmp/wordpress-$WP_BRANCH/src/wp-content/uploads"
+chmod -R 777 "/tmp/wordpress-$WP_BRANCH/src/wp-content/uploads"
+echo "::endgroup::"
+
 echo "::endgroup::"
 
 if [[ -n "$GITHUB_ENV" ]]; then
@@ -105,19 +111,6 @@ for PLUGIN in projects/plugins/*/composer.json; do
 	fi
 	cd "$BASE"
 
-	# Upgrade/downgrade WorDBless if necessary.
-	if [[ ( "$WP_BRANCH" == 'trunk' || "$WP_BRANCH" == 'previous' ) && "$TEST_SCRIPT" == "test-php" ]]; then
-		VER=$(composer --format=json --working-dir="$DIR" show | jq -r '.installed[] | select( .name == "roots/wordpress" ) | .version')
-		if [[ -n "$VER" ]]; then
-			INSVER=$WORDPRESS_TAG
-			[[ "$WORDPRESS_TAG" == 'trunk' ]] && INSVER="dev-main as $VER"
-			echo "Supposed to run tests against WordPress $WORDPRESS_TAG, so setting roots/wordpress and roots/wordpress-no-content to \"$INSVER\""
-			# Composer seems to sometimes have issues with deleting the wordpress dir on its own, so do it manually first.
-			rm -rf "$DIR/wordpress"
-			composer --working-dir="$DIR" require --dev roots/wordpress="$INSVER" roots/wordpress-no-content="$INSVER"
-		fi
-	fi
-
 	cp -r "$DIR" "/tmp/wordpress-$WP_BRANCH/src/wp-content/plugins/$NAME"
 	# Plugin dir for tests in WP >= 5.6-beta1
 	ln -s "/tmp/wordpress-$WP_BRANCH/src/wp-content/plugins/$NAME" "/tmp/wordpress-$WP_BRANCH/tests/phpunit/data/plugins/$NAME"

.github/workflows/tests.yml

@@ -86,14 +86,6 @@ jobs:
           pnpm install
           echo "::endgroup::"
 
-          # If we're going to be making WorDBless use WP "nightlies", remove the relevant package from Composer's cache to get the latest version.
-          if [[ "$WP_BRANCH" == 'trunk' && ( "$TEST_SCRIPT" == "test-php" || "$TEST_SCRIPT" == "test-coverage" ) ]]; then
-            echo "::group::Clear composer cache for roots/wordpress"
-            DIR=$(composer config cache-files-dir)
-            rm -rf "$DIR/roots/wordpress" "$DIR/roots/wordpress-no-content"
-            echo "::endgroup::"
-          fi
-
       - name: Detect changed projects
         id: changed
         run: |
@@ -110,9 +102,45 @@ jobs:
           echo "any-plugins=${ANY_PLUGINS}" >> "$GITHUB_OUTPUT"
 
       - name: Select WordPress version
-        if: steps.changed.outputs.any-plugins != 'true' && matrix.wp != 'none'
+        if: matrix.wp != 'none'
         run: .github/files/select-wordpress-tag.sh
 
+      - name: Composer Install
+        run: |
+          # If we're going to be making WorDBless use WP "nightlies", remove the relevant package from Composer's cache to get the latest version.
+          if [[ "$WP_BRANCH" == 'trunk' && ( "$TEST_SCRIPT" == "test-php" || "$TEST_SCRIPT" == "test-coverage" ) ]]; then
+            echo "::group::Clear composer cache for roots/wordpress"
+            DIR=$(composer config cache-files-dir)
+            rm -rf "$DIR/roots/wordpress" "$DIR/roots/wordpress-no-content"
+            echo "::endgroup::"
+          fi
+
+          echo "::group::Composer"
+          composer install --working-dir=tools/php-test-env
+
+          # Add WorDBless for various package tests that use uploads since concurrency can nuke uploads that are in use.
+          # @todo Update WorDBless to be able to use a customized upload dir, do that, and remove this.
+          if [[ "$TEST_SCRIPT" =~ ^test-(php|coverage)$ ]]; then
+            VER=$( jq -r '.require["automattic/wordbless"]' tools/php-test-env/composer.json )
+            for pkg in packages/image-cdn packages/publicize packages/videopress; do
+              echo "Adding WordBless for $pkg tests"
+              composer require --working-dir="projects/$pkg" "automattic/wordbless:$VER" --dev --no-update
+            done
+          fi
+
+          if [[ ( "$TEST_SCRIPT" == "test-php" || "$TEST_SCRIPT" == "test-coverage" ) && ( "$WP_BRANCH" == 'trunk' || "$WP_BRANCH" == 'previous' ) ]]; then
+            VER=$(composer --format=json --working-dir="tools/php-test-env" show | jq -r '.installed[] | select( .name == "roots/wordpress" ) | .version')
+            if [[ -n "$VER" ]]; then
+              INSVER=$WORDPRESS_TAG
+              [[ "$WORDPRESS_TAG" == 'trunk' ]] && INSVER="dev-main as $VER"
+              echo "Supposed to run tests against WordPress $WORDPRESS_TAG, so setting roots/wordpress and roots/wordpress-no-content to \"$INSVER\""
+              # Composer seems to sometimes have issues with deleting the wordpress dir on its own, so do it manually first.
+              rm -rf "tools/php-test-env/wordpress"
+              composer --working-dir="tools/php-test-env" require --dev "roots/wordpress:$INSVER" "roots/wordpress-no-content:$INSVER"
+            fi
+          fi
+          echo "::endgroup::"
+
       - name: Setup WordPress environment for plugin tests
         env:
           API_TOKEN_GITHUB: ${{ secrets.GITHUB_TOKEN }}
@@ -196,18 +224,6 @@ jobs:
                       echo 'Platform reqs failed, running `composer update`'
                       composer --working-dir="$DIR" update
                     fi
-
-                    if [[ "$WP_BRANCH" == 'trunk' || "$WP_BRANCH" == 'previous' ]]; then
-                      VER=$(composer --format=json --working-dir="$DIR" show | jq -r '.installed[] | select( .name == "roots/wordpress" ) | .version')
-                      if [[ -n "$VER" ]]; then
-                        INSVER=$WORDPRESS_TAG
-                        [[ "$WORDPRESS_TAG" == 'trunk' ]] && INSVER="dev-main as $VER"
-                        echo "Supposed to run tests against WordPress $WORDPRESS_TAG, so setting roots/wordpress and roots/wordpress-no-content to \"$INSVER\""
-                        # Composer seems to sometimes have issues with deleting the wordpress dir on its own, so do it manually first.
-                        rm -rf "$DIR/wordpress"
-                        composer --working-dir="$DIR" require --dev roots/wordpress="$INSVER" roots/wordpress-no-content="$INSVER"
-                      fi
-                    fi
                   fi
                 fi
 

.github/workflows/update-phan-stubs.yml

@@ -63,7 +63,7 @@ jobs:
           git checkout -b update/phan-custom-stubs
           git commit -am 'phan: Update custom stubs'
           git push origin HEAD
-          gh pr create --title 'phan: Update custom stubs' --body 'This is an automatic update generated by a GitHub Action. If closed it will be recreated the next time the action runs.' --label '[Pri] Normal' --label '[Type] Janitorial' --label '[Status] Needs Review'
+          gh pr create --title 'phan: Update custom stubs' --body 'This is an automatic update generated by a GitHub Action. If closed it will be recreated the next time the action runs.' --label '[Pri] Normal' --label '[Type] Janitorial' --label '[Status] Needs Review' --reviewer Automattic/jetpack-garage
 
       - name: Update existing branch
         if: steps.changes.outputs.needed == 'true' && steps.changes.outputs.has-branch == 'true'

.phan/config.base.php

@@ -137,6 +137,25 @@ function make_phan_config( $dir, $options = array() ) {
 		$internal_stubs[ $stub ] = $stub_file_path;
 	}
 
+	// Check if test-environment is a dependency and add WorDBless if it is
+	$composer_json = $dir . '/composer.json';
+	if ( file_exists( $composer_json ) ) {
+		$composer_data = json_decode( file_get_contents( $composer_json ), true );
+		foreach ( array( 'require', 'require-dev' ) as $require_type ) {
+			if ( isset( $composer_data[ $require_type ]['automattic/jetpack-test-environment'] ) ) {
+				// Use absolute path to ensure WorDBless is found
+				$wordbless_path = dirname( __DIR__ ) . '/tools/php-test-env/vendor/automattic/wordbless';
+				if ( is_dir( $wordbless_path ) ) {
+					// Only include the src directory
+					$options['directory_list'][] = $wordbless_path . '/src';
+					// Exclude from analysis
+					$options['exclude_analysis_directory_list'][] = $wordbless_path;
+				}
+				break;
+			}
+		}
+	}
+
 	$config = array(
 		// Apparently this is only useful when upgrading from php 5, not for 7-to-8.
 		'backward_compatibility_checks'          => false,

.phan/config.php

@@ -27,6 +27,8 @@
 				// Ignore stuff in various subdirs too.
 				'.*/node_modules/',
 				'tools/docker/',
+				'tools/php-test-env/wordpress/',
+				'tools/php-test-env/vendor/',
 				// Don't load the stubs. (if we need to start loading _a_ stub for the "monorepo", do like `(?!filename\.php)` to exclude it from the exclusion.)
 				'.phan/stubs/',
 			),

.phan/stubs/akismet-stubs.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Stubs automatically generated from Akismet 5.3.5
+ * Stubs automatically generated from Akismet 5.3.6
  * using the definition file `tools/stubs/akismet-stub-defs.php` in the Jetpack monorepo.
  *
  * Do not edit this directly! Run tools/stubs/update-stubs.sh to regenerate it.

.phan/stubs/gutenberg-stubs.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Stubs automatically generated from Gutenberg 20.1.0
+ * Stubs automatically generated from Gutenberg 20.2.0
  * using the definition file `tools/stubs/gutenberg-stub-defs.php` in the Jetpack monorepo.
  *
  * Do not edit this directly! Run tools/stubs/update-stubs.sh to regenerate it.

.phan/stubs/woocommerce-internal-stubs.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Stubs automatically generated from WooCommerce 9.7.0-dev
+ * Stubs automatically generated from WooCommerce 9.6.1
  * using the definition file `tools/stubs/woocommerce-internal-stub-defs.php` in the Jetpack monorepo.
  *
  * Do not edit this directly! Run tools/stubs/update-stubs.sh to regenerate it.

.phan/stubs/woocommerce-payments-stubs.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Stubs automatically generated from WooPayments 8.7.0
+ * Stubs automatically generated from WooPayments 8.9.0
  * using the definition file `tools/stubs/woocommerce-payments-stub-defs.php` in the Jetpack monorepo.
  *
  * Do not edit this directly! Run tools/stubs/update-stubs.sh to regenerate it.

.phan/stubs/wpcom-stubs.php

@@ -4,7 +4,7 @@
  * `bin/teamcity-builds/jetpack-stubs/stub-defs.php` and regenerate the stubs
  * by triggering the Jetpack Staging → Update WPCOM Stubs job in TeamCity.
  *
- * Stubs automatically generated from WordPress.com commit 58daa278d1c6807cf18400dee1d9f45815e24fae.
+ * Stubs automatically generated from WordPress.com commit 57b033879305add761d5f6f4ae7858580a986d8e.
  */
 
 namespace {
@@ -1070,7 +1070,7 @@ function show_subscription_checkbox($id = \false)
     {
     }
     /**
-     * @return bool
+     * @return int|bool
      */
     function wpcom_subs_is_subscribed($args = array())
     {

composer.json

@@ -69,6 +69,12 @@
 		],
 		"test-js": [
 			"cd tools/cli && pnpm test"
+		],
+		"post-install-cmd": [
+			"cd tools/php-test-env && composer install"
+		],
+		"post-update-cmd": [
+			"cd tools/php-test-env && composer update"
 		]
 	},
 	"scripts-descriptions": {