fix: add retry logic to composer install steps to resolve DNS timeout failures

Replace bare 'composer install' with ramsey/composer-install action (which
provides built-in retry, caching, and --prefer-dist) in code-quality.yml and
tests.yml. Add a 3-attempt shell retry loop in release.yml where --no-dev
--optimize-autoloader flags are required.

phpunit.yml already used ramsey/composer-install and is unaffected.

Closes #57

.agents/error-checking-feedback-loops.md

@@ -23,34 +23,39 @@ AI assistants can directly monitor GitHub Actions workflows using the GitHub API
 
 This helps identify failures and diagnose issues:
 
-```
+```text
 github-api /repos/{owner}/{repo}/actions/runs
 ```
 
 #### Step-by-Step Process
 
 1. **Get Recent Workflow Runs**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs
    ```
 
 2. **Filter for Failed Runs**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs?status=failure
    ```
 
 3. **Get Details for a Specific Run**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs/{run_id}
    ```
 
 4. **Get Jobs for a Workflow Run**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/runs/{run_id}/jobs
    ```
 
 5. **Analyze Job Logs** (if accessible via API):
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/actions/jobs/{job_id}/logs
    ```
 
@@ -61,6 +66,7 @@ github-api /repos/{owner}/{repo}/actions/runs
 **Error**: `Missing download info for actions/upload-artifact@v3`
 
 **Solution**: Update to the latest version of the action:
+
 ```yaml
 uses: actions/upload-artifact@v4
 ```
@@ -70,6 +76,7 @@ uses: actions/upload-artifact@v4
 **Error**: `The current host is 127.0.0.1:8888, but WordPress multisites do not support custom ports.`
 
 **Solution**: Use port 80 for multisite environments:
+
 ```yaml
 npx @wp-playground/cli server --blueprint playground/multisite-blueprint.json --port 80 --login &
 ```
@@ -79,6 +86,7 @@ npx @wp-playground/cli server --blueprint playground/multisite-blueprint.json --
 **Error**: Invalid path syntax for artifacts
 
 **Solution**: Use multi-line format for better readability:
+
 ```yaml
 path: |
   cypress/videos
@@ -90,6 +98,7 @@ path: |
 **Problem**: Redundant workflow runs when multiple commits land quickly
 
 **Solution**: Add concurrency control to cancel in-progress runs:
+
 ```yaml
 concurrency:
   group: playground-tests-${{ github.ref }}
@@ -125,16 +134,19 @@ npm run test:playground:multisite
 ### Capturing and Analyzing Test Output
 
 1. **Run Tests with Output Capture**:
+
    ```bash
    npm run test:single > test-output.log 2>&1
    ```
 
 2. **Analyze Output for Errors**:
+
    ```bash
    cat test-output.log | grep -i 'error\|fail\|exception'
    ```
 
 3. **Parse Structured Test Results** (if available):
+
    ```bash
    cat cypress/results/results.json
    ```
@@ -146,6 +158,7 @@ npm run test:playground:multisite
 **Error**: `The current host is 127.0.0.1:8888, but WordPress multisites do not support custom ports.`
 
 **Solution**: Modify the port in the blueprint or test configuration:
+
 ```json
 {
   "features": {
@@ -159,6 +172,7 @@ npm run test:playground:multisite
 **Error**: `Timed out retrying after 4000ms: expected '<body...>' to have class 'wp-admin'`
 
 **Solution**: Update selectors to be more robust and handle login states:
+
 ```javascript
 cy.get('body').then(($body) => {
   if ($body.hasClass('login')) {
@@ -199,16 +213,19 @@ npm run lint:css
 ### Parsing Code Quality Tool Output
 
 1. **Run Code Quality Check**:
+
    ```bash
    composer run phpcs > phpcs-output.log 2>&1
    ```
 
 2. **Analyze Output for Errors**:
+
    ```bash
    cat phpcs-output.log | grep -i 'ERROR\|WARNING'
    ```
 
 3. **Automatically Fix Issues** (when possible):
+
    ```bash
    composer run phpcbf
    ```
@@ -221,13 +238,13 @@ AI assistants can check these comments to identify and address issues.
 
 #### Accessing PR Comments via GitHub API
 
-```
+```text
 github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/comments
 ```
 
 #### Accessing PR Review Comments
 
-```
+```text
 github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/reviews
 ```
 
@@ -236,7 +253,8 @@ github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pul
 CodeRabbit provides AI-powered code review comments via the GitHub API.
 
 1. **Get PR Comments**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{pull_number}/comments
    ```
 
@@ -254,12 +272,14 @@ CodeRabbit provides AI-powered code review comments via the GitHub API.
 These tools provide automated code quality checks and post results as PR comments.
 
 1. **Check PR Status Checks**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs
    ```
 
 2. **Get Detailed Reports** (if available via API):
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs/{id}
    ```
 
@@ -275,7 +295,8 @@ These tools provide automated code quality checks and post results as PR comment
 SonarCloud provides detailed code quality and security analysis.
 
 1. **Check SonarCloud Status**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/commits/{sha}/check-runs?check_name=SonarCloud
    ```
 
@@ -293,6 +314,7 @@ SonarCloud provides detailed code quality and security analysis.
 **Error**: `ERROR: Expected snake_case for function name, but found camelCase`
 
 **Solution**: Rename functions to follow snake_case convention:
+
 ```php
 // Before
 function getPluginVersion() { ... }
@@ -306,6 +328,7 @@ function get_plugin_version() { ... }
 **Error**: `ERROR: Missing doc comment for function`
 
 **Solution**: Add proper docblocks:
+
 ```php
 /**
  * Get the plugin version.
@@ -332,7 +355,8 @@ function get_plugin_version() { ... }
 #### Extracting Actionable Items from PR Comments
 
 1. **Collect All Feedback**:
-   ```
+
+   ```text
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{number}/comments
    github-api /repos/wpallstars/wp-plugin-starter-template-for-ai-coding/pulls/{number}/reviews
    ```
@@ -364,7 +388,7 @@ function get_plugin_version() { ... }
 
 ### Complete Feedback Loop System
 
-```
+```text
 Code Changes ──► Local Testing ──► GitHub Actions
      │                │                  │
      ▼                ▼                  ▼
@@ -395,7 +419,7 @@ These can be directly accessed and processed.
 
 #### Example CodeRabbit Feedback
 
-```
+```text
 coderabbitai bot left a comment
 Actionable comments posted: 1
 
@@ -424,14 +448,14 @@ These tools provide structured feedback that can be systematically addressed.
 
 #### Example SonarCloud Feedback
 
-```
+```text
 SonarCloud Quality Gate failed
 - 3 Bugs
 - 5 Code Smells
 - 1 Security Hotspot
 ```
 
-#### Processing Steps
+#### SonarCloud Processing Steps
 
 1. **Access Detailed Reports**:
    * Use the SonarCloud API or web interface
@@ -479,6 +503,7 @@ AI assistants can contribute fixes upstream.
 ### Workflow for External Contributions
 
 1. **Clone the Repository Locally**:
+
    ```bash
    cd ~/Git
    git clone https://github.com/owner/repo.git
@@ -487,6 +512,7 @@ AI assistants can contribute fixes upstream.
    ```
 
 2. **Make Changes and Commit**:
+
    ```bash
    # Make your changes
    git add -A
@@ -498,6 +524,7 @@ AI assistants can contribute fixes upstream.
    ```
 
 3. **Fork and Push**:
+
    ```bash
    # Create a fork (if not already forked)
    gh repo fork owner/repo --clone=false --remote=true
@@ -510,6 +537,7 @@ AI assistants can contribute fixes upstream.
    ```
 
 4. **Create Pull Request**:
+
    ```bash
    gh pr create \
      --repo owner/repo \

.eslintrc.js

@@ -16,9 +16,23 @@ module.exports = {
     sourceType: 'module'
   },
   rules: {
+    'comma-dangle': ['error', 'never'],
     'no-console': 'warn',
     'no-unused-vars': 'warn'
   },
+  overrides: [
+    {
+      // cypress.config.js uses CommonJS (require/module.exports).
+      // Override sourceType to 'script' so ESLint does not flag require as undefined.
+      files: ['cypress.config.js', 'cypress.config.cjs'],
+      parserOptions: {
+        sourceType: 'script'
+      },
+      env: {
+        node: true
+      }
+    }
+  ],
   globals: {
     cy: 'readonly',
     Cypress: 'readonly',

.github/workflows/code-quality.yml

@@ -27,7 +27,9 @@ jobs:
           tools: composer:v2
 
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
+        with:
+          composer-options: "--prefer-dist --no-progress"
 
       - name: Run PHPCS
         run: composer phpcs
@@ -54,7 +56,9 @@ jobs:
           tools: composer:v2, phpstan
 
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
+        with:
+          composer-options: "--prefer-dist --no-progress"
 
       - name: Run PHPStan
         run: composer phpstan
@@ -75,7 +79,9 @@ jobs:
           tools: composer:v2, phpmd
 
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
+        with:
+          composer-options: "--prefer-dist --no-progress"
 
       - name: Run PHPMD
         run: composer phpmd

.github/workflows/release.yml

@@ -34,7 +34,12 @@ jobs:
           echo "VERSION=$VERSION" >> $GITHUB_ENV
 
       - name: Install dependencies
-        run: composer install --no-dev --optimize-autoloader
+        run: |
+          for i in 1 2 3; do
+            composer install --no-dev --optimize-autoloader --prefer-dist && break
+            echo "Composer install attempt $i failed, retrying in 15s..."
+            sleep 15
+          done
 
       - name: Create build directory
         run: |

.github/workflows/tests.yml

@@ -28,11 +28,10 @@ jobs:
           extensions: mbstring, intl, zip
           tools: composer:v2
 
-      - name: Clear Composer Cache
-        run: composer clear-cache
-
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
+        with:
+          composer-options: "--prefer-dist --no-progress"
 
       - name: Run tests
         run: ./vendor/bin/phpunit
@@ -54,11 +53,10 @@ jobs:
           extensions: mbstring, intl, zip
           tools: composer:v2, phpcs
 
-      - name: Clear Composer Cache
-        run: composer clear-cache
-
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6 # v2.2.0
+        with:
+          composer-options: "--prefer-dist --no-progress"
 
       - name: Run PHPCS
         run: composer run phpcs

.gitignore

@@ -63,3 +63,6 @@ temp/
 coverage/
 .phpunit.result.cache
 .agents/loop-state/
+
+# Local tool configs
+.superset/

.markdownlint.json

@@ -1,4 +1,7 @@
 {
+  "MD004": {
+    "style": "asterisk"
+  },
   "MD012": false,
   "MD022": false,
   "MD031": false,

.wiki/Contributing.md

@@ -6,11 +6,11 @@ Thank you for considering contributing to this project! This document provides g
 
 By participating in this project, you agree to abide by our code of conduct:
 
-- Be respectful and inclusive
+* Be respectful and inclusive
-- Be patient and welcoming
+* Be patient and welcoming
-- Be considerate
+* Be considerate
-- Be collaborative
+* Be collaborative
-- Be open-minded
+* Be open-minded
 
 ## How to Contribute
 
@@ -26,12 +26,12 @@ If you find a bug, please report it by creating an issue on GitHub:
 
 Please include:
 
-- A clear, descriptive title
+* A clear, descriptive title
-- Steps to reproduce the bug
+* Steps to reproduce the bug
-- Expected behavior
+* Expected behavior
-- Actual behavior
+* Actual behavior
-- Screenshots (if applicable)
+* Screenshots (if applicable)
-- Your environment (WordPress version, PHP version, browser, etc.)
+* Your environment (WordPress version, PHP version, browser, etc.)
 
 ### Suggesting Enhancements
 
@@ -45,10 +45,10 @@ If you have an idea for an enhancement:
 
 Please include:
 
-- A clear, descriptive title
+* A clear, descriptive title
-- A detailed description of the enhancement
+* A detailed description of the enhancement
-- Why this enhancement would be useful
+* Why this enhancement would be useful
-- Any relevant examples or mockups
+* Any relevant examples or mockups
 
 ### Pull Requests
 

.wiki/Playground-Testing.md

@@ -24,9 +24,10 @@ The easiest way to test our plugin with WordPress Playground is to use the onlin
 [playground-single]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2
 [playground-multisite]: https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/multisite-blueprint.json&_t=2
 
-These links automatically set up WordPress with multisite enabled and WP_DEBUG enabled.
+Both links automatically set up WordPress with WP_DEBUG enabled and the Plugin Toggle and
+Kadence Blocks plugins pre-installed and activated.
 
-Both the Plugin Toggle and Kadence Blocks plugins are pre-activated.
+The multisite link additionally enables WordPress multisite and network-activates both plugins.
 
 ## WP-CLI Commands for WordPress Playground
 
@@ -101,14 +102,14 @@ In a WordPress multisite environment, there are two ways to activate plugins:
 1. **Network Activation**: Activates a plugin for all sites in the network
    * In the WordPress admin, go to Network Admin > Plugins
    * Click "Network Activate" under the plugin
-   * Or use WP-CLI: `wp plugin install plugin-name --activate-network`
+   * Or use WP-CLI: `wp plugin activate plugin-name --network`
 
 2. **Per-Site Activation**: Activates a plugin for a specific site
    * In the WordPress admin, go to the specific site's admin area
    * Go to Plugins and activate the plugin for that site only
    * Or use WP-CLI: `wp plugin activate plugin-name --url=site-url`
 
-Our multisite blueprint uses network activation for the Plugin Toggle plugin as an example.
+Our multisite blueprint uses network activation for both the Plugin Toggle and Kadence Blocks plugins.
 
 ## Running Tests with WordPress Playground
 

admin/css/admin-styles.css

@@ -124,7 +124,7 @@
 }
 
 /* Responsive Styles */
-@media screen and (width <= 782px) {
+@media screen and (max-width: 782px) {
     .wpst-form-table th {
         width: 100%;
         display: block;

admin/js/admin-scripts.js

@@ -105,10 +105,16 @@
 		 * @param {string} message Notice message
 		 */
     showNotice: function (type, message) {
-      const $notice = $( '<div class="wpst-notice ' + type + '"><p>' + message + '</p></div>' );
+      const allowedTypes = [ 'success', 'error', 'warning' ];
+      const safeType     = allowedTypes.includes( type ) ? type : 'error';
+      const $p           = $( '<p>' );
+      const $notice      = $( '<div>' ).addClass( 'wpst-notice ' + safeType ).append( $p );
+
+      // Set message as plain text to prevent XSS.
+      $p.text( message );
 
       // Add notice to the page.
-      $( '.wpst-notices' ).html( $notice );
+      $( '.wpst-notices' ).empty().append( $notice );
 
       // Automatically remove notice after 5 seconds.
       setTimeout(

admin/js/update-source-selector.js

@@ -153,8 +153,8 @@
     showMessage: function (type, message) {
       const $message = this.$modal.find( '.wpst-modal-message' );
 
-      // Set message content and type.
+      // Set message as plain text to prevent XSS, then apply type class.
-      $message.html( message ).removeClass( 'success error' ).addClass( type ).show();
+      $message.text( message ).removeClass( 'success error' ).addClass( type ).show();
 
       // Hide message after a delay for success messages.
       if (type === 'success') {

admin/templates/modal.php

@@ -12,11 +12,22 @@ if ( ! defined( 'ABSPATH' ) ) {
 ?>
 
 <!-- Update Source Modal -->
-<div id="wpst-update-source-modal" class="wpst-modal">
+<div
+    id="wpst-update-source-modal"
+    class="wpst-modal"
+    role="dialog"
+    aria-modal="true"
+    aria-labelledby="wpst-update-source-modal-title"
+    tabindex="-1"
+>
     <div class="wpst-modal-content">
         <div class="wpst-modal-header">
-            <h2 class="wpst-modal-title"><?php esc_html_e( 'Select Update Source', 'wp-plugin-starter-template' ); ?></h2>
+            <h2 id="wpst-update-source-modal-title" class="wpst-modal-title"><?php esc_html_e( 'Select Update Source', 'wp-plugin-starter-template' ); ?></h2>
-            <span class="wpst-modal-close">&times;</span>
+            <button
+                type="button"
+                class="wpst-modal-close"
+                aria-label="<?php esc_attr_e( 'Close dialog', 'wp-plugin-starter-template' ); ?>"
+            >&times;</button>
         </div>
         
         <div class="wpst-modal-body">

bin/install-wp-tests.sh

@@ -17,15 +17,19 @@ WP_TESTS_DIR=${WP_TESTS_DIR-/tmp/wordpress-tests-lib}
 WP_CORE_DIR=${WP_CORE_DIR-/tmp/wordpress/}
 
 download() {
-    if command -v curl > /dev/null; then
+	if command -v curl >/dev/null 2>&1; then
-        curl -s "$1" > "$2";
+		curl -fsSL "$1" -o "$2"
-    elif command -v wget > /dev/null; then
+	elif command -v wget >/dev/null 2>&1; then
-        wget -nv -O "$2" "$1"
+		wget -qO "$2" "$1"
+	else
+		echo "Error: Neither curl nor wget is installed" >&2
+		exit 1
 	fi
 }
 
 if [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+\-(beta|RC)[0-9]+$ ]]; then
 	WP_BRANCH=${WP_VERSION%\-*}
+	WP_TESTS_TAG="branches/$WP_BRANCH"
 elif [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+$ ]]; then
 	WP_TESTS_TAG="branches/$WP_VERSION"
 elif [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0-9]+ ]]; then
@@ -40,20 +44,31 @@ elif [[ $WP_VERSION == 'nightly' || $WP_VERSION == 'trunk' ]]; then
 else
 	# http serves a single offer, whereas https serves multiple. we only want one
 	download http://api.wordpress.org/core/version-check/1.7/ /tmp/wp-latest.json
-	grep '[0-9]+\.[0-9]+(\.[0-9]+)?' /tmp/wp-latest.json
+	LATEST_VERSION=$(grep -o '"version":"[^"]*' /tmp/wp-latest.json | sed 's/"version":"//' | head -1)
-	LATEST_VERSION=$(grep -o '"version":"[^"]*' /tmp/wp-latest.json | sed 's/"version":"//')
 	if [[ -z "$LATEST_VERSION" ]]; then
 		echo "Latest WordPress version could not be found"
 		exit 1
 	fi
 	WP_TESTS_TAG="tags/$LATEST_VERSION"
 fi
+
+# Derive a git ref from WP_TESTS_TAG by stripping the SVN-style prefix.
+# WP_TESTS_TAG uses "tags/X.Y.Z", "branches/X.Y", or "trunk".
+# git clone --branch requires the bare ref name ("X.Y.Z", "X.Y", or "trunk").
+if [[ "$WP_TESTS_TAG" == tags/* ]]; then
+	GIT_REF="${WP_TESTS_TAG#tags/}"
+elif [[ "$WP_TESTS_TAG" == branches/* ]]; then
+	GIT_REF="${WP_TESTS_TAG#branches/}"
+else
+	GIT_REF="$WP_TESTS_TAG"
+fi
+
 set -ex
 
 install_wp() {
 
 	if [ -d "$WP_CORE_DIR" ]; then
-		return;
+		return
 	fi
 
 	mkdir -p "$WP_CORE_DIR"
@@ -71,6 +86,7 @@ install_wp() {
 			if [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0] ]]; then
 				LATEST_VERSION=${WP_VERSION%??}
 			else
+				# shellcheck disable=SC2001
 				VERSION_ESCAPED=$(echo "$WP_VERSION" | sed 's/\./\\\\./g')
 				LATEST_VERSION=$(grep -o '"version":"'"$VERSION_ESCAPED"'[^"]*' "$WP_CORE_DIR/wp-latest.json" | sed 's/"version":"//' | head -1)
 			fi
@@ -101,12 +117,21 @@ install_test_suite() {
 	# set up testing suite if it doesn't yet exist
 	if [ ! -d "$WP_TESTS_DIR" ]; then
 		mkdir -p "$WP_TESTS_DIR"
-		git clone --quiet --depth=1 https://github.com/WordPress/wordpress-develop.git /tmp/wordpress-develop
+		if ! git clone --quiet --depth=1 --branch "$GIT_REF" https://github.com/WordPress/wordpress-develop.git /tmp/wordpress-develop; then
+			echo "Error: Failed to clone wordpress-develop at branch/tag $GIT_REF" >&2
+			exit 1
+		fi
 		if [ -d /tmp/wordpress-develop/tests/phpunit/includes ]; then
-			cp -r /tmp/wordpress-develop/tests/phpunit/includes "$WP_TESTS_DIR/"
+			if ! cp -r /tmp/wordpress-develop/tests/phpunit/includes "$WP_TESTS_DIR/"; then
+				echo "Error: Failed to copy phpunit includes to $WP_TESTS_DIR" >&2
+				exit 1
+			fi
 		fi
 		if [ -d /tmp/wordpress-develop/tests/phpunit/data ]; then
-			cp -r /tmp/wordpress-develop/tests/phpunit/data "$WP_TESTS_DIR/"
+			if ! cp -r /tmp/wordpress-develop/tests/phpunit/data "$WP_TESTS_DIR/"; then
+				echo "Error: Failed to copy phpunit data to $WP_TESTS_DIR" >&2
+				exit 1
+			fi
 		fi
 	fi
 
@@ -116,15 +141,15 @@ install_test_suite() {
 		else
 			download https://raw.githubusercontent.com/WordPress/wordpress-develop/master/wp-tests-config-sample.php "$WP_TESTS_DIR"/wp-tests-config.php
 		fi
-		WP_CORE_DIR=$(echo "$WP_CORE_DIR" | sed "s:/\+$::")
+		WP_CORE_DIR="${WP_CORE_DIR%/}"
-		sed $ioption "s:dirname( __FILE__ ) . '/src/':'$WP_CORE_DIR/':" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed "$ioption" "s:dirname( __FILE__ ) . '/src/':'$WP_CORE_DIR/':" "$WP_TESTS_DIR"/wp-tests-config.php
-		sed $ioption "s/youremptytestdbnamehere/$DB_NAME/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed "$ioption" "s/youremptytestdbnamehere/$DB_NAME/" "$WP_TESTS_DIR"/wp-tests-config.php
-		sed $ioption "s/yourusernamehere/$DB_USER/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed "$ioption" "s/yourusernamehere/$DB_USER/" "$WP_TESTS_DIR"/wp-tests-config.php
-		sed $ioption "s/yourpasswordhere/$DB_PASS/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed "$ioption" "s/yourpasswordhere/$DB_PASS/" "$WP_TESTS_DIR"/wp-tests-config.php
-		sed $ioption "s|localhost|${DB_HOST}|" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed "$ioption" "s|localhost|${DB_HOST}|" "$WP_TESTS_DIR"/wp-tests-config.php
 
 		if [ "$MULTISITE" = "true" ]; then
-			sed $ioption "s:// define( 'WP_TESTS_MULTISITE', true );:define( 'WP_TESTS_MULTISITE', true );:" "$WP_TESTS_DIR"/wp-tests-config.php
+			sed "$ioption" "s:// define( 'WP_TESTS_MULTISITE', true );:define( 'WP_TESTS_MULTISITE', true );:" "$WP_TESTS_DIR"/wp-tests-config.php
 		fi
 	fi
 
@@ -132,14 +157,14 @@ install_test_suite() {
 
 install_db() {
 
-	if [ ${SKIP_DB_CREATE} = "true" ]; then
+	if [ "${SKIP_DB_CREATE}" = "true" ]; then
 		return 0
 	fi
 
 	local PARTS
 	IFS=':' read -ra PARTS <<<"$DB_HOST"
-	local DB_HOSTNAME=${PARTS[0]};
+	local DB_HOSTNAME=${PARTS[0]}
-	local DB_SOCK_OR_PORT=${PARTS[1]};
+	local DB_SOCK_OR_PORT=${PARTS[1]}
 	local EXTRA=""
 
 	if [ -n "$DB_HOSTNAME" ]; then
@@ -152,7 +177,7 @@ install_db() {
 		fi
 	fi
 
-	mysqladmin create "$DB_NAME" --user="$DB_USER" --password="$DB_PASS"$EXTRA || true
+	mysqladmin create "$DB_NAME" --user="$DB_USER" --password="$DB_PASS""$EXTRA" || true
 }
 
 install_wp

bin/setup-test-env.sh

@@ -14,8 +14,24 @@ ENV_TYPE=$1
 # Function to check if a command exists
 command_exists() {
 	command -v "$1" &>/dev/null
+	return $?
 }
 
+# PID of the background Python HTTP server (set when started).
+PYTHON_PID=""
+
+# Function to clean up resources on exit.
+cleanup() {
+	if [ -n "$PYTHON_PID" ]; then
+		echo "Stopping Python HTTP server (PID: $PYTHON_PID)..."
+		kill "$PYTHON_PID" 2>/dev/null || true
+	fi
+	return 0
+}
+
+# Trap EXIT, INT, and TERM so the server is always stopped on script exit.
+trap cleanup EXIT INT TERM
+
 # Function to install wp-env if needed
 install_wp_env() {
 	if ! command_exists wp-env; then
@@ -152,6 +168,8 @@ EOF
 	echo "Starting WordPress Playground..."
 	if command_exists python3; then
 		python3 -m http.server 8888 --directory playground &
+		PYTHON_PID=$!
+		echo "Started Python HTTP server with PID: $PYTHON_PID"
 		echo "Opening WordPress Playground in your browser..."
 		if command_exists open; then
 			open http://localhost:8888/index.html
@@ -259,6 +277,8 @@ EOF
 	echo "Starting WordPress Playground..."
 	if command_exists python3; then
 		python3 -m http.server 8888 --directory playground &
+		PYTHON_PID=$!
+		echo "Started Python HTTP server with PID: $PYTHON_PID"
 		echo "Opening WordPress Playground in your browser..."
 		if command_exists open; then
 			open http://localhost:8888/multisite.html

build.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -euo pipefail
 
 # WordPress Plugin Build Script
 # This script creates a clean build of the plugin for distribution
@@ -39,7 +40,7 @@ composer install --no-dev --optimize-autoloader
 
 # Copy plugin files to build directory
 echo "Copying plugin files..."
-cp -R *.php "$BUILD_DIR/"
+cp -R ./*.php "$BUILD_DIR/"
 cp -R README.md LICENSE CHANGELOG.md readme.txt composer.json "$BUILD_DIR/"
 
 # Copy directories
@@ -83,7 +84,7 @@ if [ -f "$ZIP_FILE" ]; then
 
 	# Deploy to local WordPress installation if environment variable is set
 	if [ -n "$WP_LOCAL_PLUGIN_DIR" ]; then
-		echo "\nDeploying to local WordPress installation..."
+		printf '\nDeploying to local WordPress installation...\n'
 		echo "Deploying to local WordPress installation..."
 
 		# Remove existing plugin directory.

cypress/e2e/playground-single-site.cy.js

@@ -18,6 +18,14 @@ describe('WordPress Playground Single Site Tests', () => {
     cy.visit('/wp-admin/plugins.php', { timeout: 30000 });
 
     cy.get('body', { timeout: 15000 }).then(($body) => {
+      // Verify the starter template plugin exists and is activated.
+      if ($body.find('tr[data-slug="wp-plugin-starter-template-for-ai-coding"]').length) {
+        cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"]').should('exist');
+        cy.get('tr[data-slug="wp-plugin-starter-template-for-ai-coding"] .deactivate a').should('exist');
+      } else {
+        cy.log('Starter template plugin not found by slug, skipping check');
+      }
+
       if ($body.text().includes('Plugin Toggle')) {
         cy.contains('tr', 'Plugin Toggle').should('exist');
         cy.contains('tr', 'Plugin Toggle').find('.deactivate').should('exist');

cypress/e2e/single-site.cy.js

@@ -1,3 +1,4 @@
+/* eslint-env mocha, jquery, cypress */
 describe( 'WordPress Single Site Tests', () => {
     it( 'Can access the site', () => {
         cy.visit( '/' );
@@ -11,20 +12,64 @@ describe('WordPress Single Site Tests', () => {
     } );
 
     it( 'Plugin is activated', () => {
-    // Use our custom command to check and activate the plugin if needed
+        // Use our custom command to check and activate the plugin if needed.
         cy.activatePlugin( 'wp-plugin-starter-template-for-ai-coding' );
 
-    // Verify it's active
+        // Verify it's active.
         cy.get( 'tr[data-slug="wp-plugin-starter-template-for-ai-coding"] .deactivate' ).should( 'exist' );
     } );
 
-  it('Plugin settings page loads correctly', () => {
+    it( 'Plugin row is visible on the plugins page', () => {
         cy.loginAsAdmin();
+        cy.visit( '/wp-admin/plugins.php' );
 
-    // Navigate to the plugin settings page (if it exists)
+        // Verify the plugin row exists with the correct slug.
-    cy.visit('/wp-admin/options-general.php?page=wp-plugin-starter-template');
+        cy.get( 'tr[data-slug="wp-plugin-starter-template-for-ai-coding"]' ).should( 'exist' );
 
-    // This is a basic check - adjust based on your actual plugin's settings page
+        // Verify the plugin name is displayed.
-    cy.get('h1').should('contain', 'WP Plugin Starter Template');
+        cy.get( 'tr[data-slug="wp-plugin-starter-template-for-ai-coding"] .plugin-title strong' )
+            .should( 'contain', 'WordPress Plugin Starter Template' );
+    } );
+
+    it( 'Update source selector link is present in the plugin row', () => {
+        cy.loginAsAdmin();
+        cy.visit( '/wp-admin/plugins.php' );
+
+        // The update source selector link should be rendered in the plugin row.
+        cy.get( 'tr[data-slug="wp-plugin-starter-template-for-ai-coding"]' )
+            .find( '.wpst-update-source-selector' )
+            .should( 'exist' );
+    } );
+
+    it( 'Update source modal opens and displays source options', () => {
+        cy.loginAsAdmin();
+        cy.visit( '/wp-admin/plugins.php' );
+
+        // Click the update source selector link to open the modal.
+        cy.get( '.wpst-update-source-selector' ).first().click();
+
+        // Modal should be visible.
+        cy.get( '#wpst-update-source-modal' ).should( 'be.visible' );
+
+        // Modal should contain the three update source options.
+        cy.get( '#wpst-update-source-modal input[name="update_source"][value="wordpress.org"]' ).should( 'exist' );
+        cy.get( '#wpst-update-source-modal input[name="update_source"][value="github"]' ).should( 'exist' );
+        cy.get( '#wpst-update-source-modal input[name="update_source"][value="gitea"]' ).should( 'exist' );
+
+        // Save button should be present.
+        cy.get( '#wpst-save-source' ).should( 'exist' );
+    } );
+
+    it( 'Update source modal can be closed', () => {
+        cy.loginAsAdmin();
+        cy.visit( '/wp-admin/plugins.php' );
+
+        // Open the modal.
+        cy.get( '.wpst-update-source-selector' ).first().click();
+        cy.get( '#wpst-update-source-modal' ).should( 'be.visible' );
+
+        // Close the modal via the close button.
+        cy.get( '#wpst-update-source-modal .wpst-modal-close' ).click();
+        cy.get( '#wpst-update-source-modal' ).should( 'not.be.visible' );
     } );
 } );

includes/Admin/class-admin.php

@@ -69,10 +69,12 @@ class Admin {
         // Get the plugin version.
         $plugin_version = $this->core->get_plugin_version();
 
+        $plugin_url = $this->get_plugin_base_url();
+
         // Enqueue styles.
         \wp_enqueue_style(
             'wpst-admin-styles',
-            plugin_dir_url( dirname( __DIR__ ) ) . 'admin/css/admin-styles.css',
+            $plugin_url . 'admin/css/admin-styles.css',
             array(), // Dependencies.
             $plugin_version // Version.
         );
@@ -80,7 +82,7 @@ class Admin {
         // Enqueue admin scripts.
         \wp_enqueue_script(
             'wpst-admin-script',
-            plugin_dir_url( dirname( __DIR__ ) ) . 'admin/js/admin-scripts.js',
+            $plugin_url . 'admin/js/admin-scripts.js',
             array( 'jquery' ),
             $plugin_version, // Version.
             true
@@ -99,4 +101,21 @@ class Admin {
             $data
         );
     }
+
+    /**
+     * Get plugin base URL.
+     *
+     * @return string Plugin base URL with trailing slash.
+     */
+    private function get_plugin_base_url(): string {
+        if ( defined( 'WP_PLUGIN_STARTER_TEMPLATE_URL' ) ) {
+            return WP_PLUGIN_STARTER_TEMPLATE_URL;
+        }
+
+        if ( defined( 'WPST_PLUGIN_URL' ) ) {
+            return WPST_PLUGIN_URL;
+        }
+
+        return \plugin_dir_url( dirname( __DIR__, 2 ) );
+    }
 }

includes/Multisite/class-multisite.php

@@ -6,10 +6,10 @@
  * Extend this file or create additional classes in this directory
  * to implement multisite features for your plugin.
  *
- * @package WP_Plugin_Starter_Template_For_AI_Coding
+ * @package WPALLSTARS\PluginStarterTemplate
  */
 
-namespace WP_Plugin_Starter_Template_For_AI_Coding\Multisite;
+namespace WPALLSTARS\PluginStarterTemplate\Multisite;
 
 // Exit if accessed directly.
 if ( ! defined( 'ABSPATH' ) ) {

package.json

@@ -29,6 +29,7 @@
     "test:phpunit:multisite": "WP_MULTISITE=1 composer test",
     "build": "./build.sh",
     "lint:js": "eslint cypress/",
+    "lint:css": "stylelint \"**/*.css\" --allow-empty-input",
     "lint:php": "composer run-script phpcs",
     "lint:php:simple": "composer run-script phpcs:simple",
     "lint:phpstan": "composer run-script phpstan",
@@ -38,7 +39,7 @@
     "test:php": "composer run-script test",
     "lint": "composer run-script lint",
     "fix": "composer run-script fix",
-    "quality": "npm run lint && npm run test:php"
+    "quality": "npm run lint && npm run lint:css && npm run test:php"
   },
   "repository": {
     "type": "git",
@@ -64,6 +65,8 @@
     "@wp-playground/cli": "^3.0.22",
     "cypress": "^13.17.0",
     "eslint": "^8.57.0",
-    "eslint-plugin-cypress": "^2.15.1"
+    "eslint-plugin-cypress": "^2.15.1",
+    "stylelint": "^16.0.0",
+    "stylelint-config-standard": "^36.0.0"
   }
 }

phpmd.xml

@@ -15,6 +15,8 @@
         <exclude name="CamelCaseMethodName" />
         <exclude name="CamelCaseParameterName" />
         <exclude name="CamelCaseVariableName" />
+        <!-- WordPress plugins use filter_input() for production and $_GET for testing; Superglobals rule is not applicable. -->
+        <exclude name="Superglobals" />
     </rule>
     <rule ref="rulesets/design.xml" />
     <rule ref="rulesets/naming.xml">

phpstan.neon

@@ -5,13 +5,6 @@ parameters:
         - admin
         - wp-plugin-starter-template.php
     excludePaths:
-        analyse:
-            - vendor
-            - node_modules
-            - tests
-            - bin
-            - build
-            - dist
         analyseAndScan:
             - vendor
             - node_modules

playground/index.html

@@ -21,6 +21,6 @@
     </style>
 </head>
 <body>
-    <iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json&_t=2" title="WordPress Playground Single Site Environment"></iframe>
+    <iframe src="https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpallstars/wp-plugin-starter-template-for-ai-coding/main/playground/blueprint.json" title="WordPress Playground Single Site Environment"></iframe>
 </body>
 </html>

playground/test.html

@@ -68,7 +68,7 @@
             "landingPage": "/wp-admin/",
             "login": true,
             "features": {
-                "networking": true
+                "networking": false
             },
             "steps": [
                 {

tests/phpunit/bootstrap.php

@@ -46,7 +46,7 @@ if ( getenv( 'WP_PHPUNIT__DIR' ) ) {
     // Include plugin files needed for tests.
     require_once WPST_PLUGIN_DIR . 'includes/class-core.php';
     require_once WPST_PLUGIN_DIR . 'includes/class-plugin.php';
-    if ( file_exists( WPST_PLUGIN_DIR . 'admin/lib/admin.php' ) ) {
+    if ( file_exists( WPST_PLUGIN_DIR . 'includes/Admin/class-admin.php' ) ) {
-        require_once WPST_PLUGIN_DIR . 'admin/lib/admin.php';
+        require_once WPST_PLUGIN_DIR . 'includes/Admin/class-admin.php';
     }
 }

tests/phpunit/test-admin.php

@@ -101,17 +101,12 @@ class AdminTest extends \WP_Mock\Tools\TestCase {
             'return' => 'wp_plugin_starter_template_settings',
         ]);
 
-        // Mock WordPress functions used in the method
-        WP_Mock::userFunction('plugin_dir_url', [
-            'return' => 'http://example.com/wp-content/plugins/wp-plugin-starter-template/includes/Admin/',
-        ]);
-
         // Mock wp_enqueue_style
         WP_Mock::userFunction('wp_enqueue_style', [
             'times' => 1,
             'args' => [
                 'wpst-admin-styles',
-                'http://example.com/wp-content/plugins/wp-plugin-starter-template/includes/Admin/../../admin/css/admin-styles.css',
+                'http://example.org/wp-content/plugins/wp-plugin-starter-template/admin/css/admin-styles.css',
                 [],
                 '1.0.0',
             ],
@@ -122,7 +117,7 @@ class AdminTest extends \WP_Mock\Tools\TestCase {
             'times' => 1,
             'args' => [
                 'wpst-admin-script',
-                'http://example.com/wp-content/plugins/wp-plugin-starter-template/includes/Admin/../../admin/js/admin-scripts.js',
+                'http://example.org/wp-content/plugins/wp-plugin-starter-template/admin/js/admin-scripts.js',
                 ['jquery'],
                 '1.0.0',
                 true,

wp-plugin-starter-template.php

@@ -55,13 +55,19 @@ spl_autoload_register(
         // Get the relative class name.
         $relative_class = substr( $className, $len );
 
-        // Convert namespace to path.
+        // Build class file path using WordPress-style class file names.
-        $file = WP_PLUGIN_STARTER_TEMPLATE_PATH . 'includes/' . str_replace( '\\', '/', $relative_class ) . '.php';
+        $relative_path = str_replace( '\\', '/', $relative_class );
+        $path_parts = explode( '/', $relative_path );
+        $class_name = array_pop( $path_parts );
+        $directory = '';
 
-        // Convert class name format to file name format.
+        if ( ! empty( $path_parts ) ) {
-        $file = str_replace( 'class-', '', $file );
+            $directory = implode( '/', $path_parts ) . '/';
-        $file = preg_replace( '/([a-z])([A-Z])/', '$1-$2', $file );
+        }
-        $file = strtolower( $file );
+
+        $class_file = preg_replace( '/([a-z])([A-Z])/', '$1-$2', $class_name );
+        $class_file = 'class-' . strtolower( $class_file ) . '.php';
+        $file = WP_PLUGIN_STARTER_TEMPLATE_PATH . 'includes/' . $directory . $class_file;
 
         // If the file exists, require it.
         if ( file_exists( $file ) ) {