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,12 +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:
-      - name: Install WordPress Coding Standards
+          composer-options: "--prefer-dist --no-progress"
-        run: |
-          composer require --dev wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer
-          vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs
 
       - name: Run PHPCS
         run: composer phpcs
@@ -59,10 +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:
-      - name: Install PHPStan WordPress stubs
+          composer-options: "--prefer-dist --no-progress"
-        run: composer require --dev szepeviktor/phpstan-wordpress
 
       - name: Run PHPStan
         run: composer phpstan
@@ -83,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,17 +28,13 @@ 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: Debug test file content
+      - name: Run tests
-      #   run: echo "--- Debugging tests/test-admin.php lines 75-95 ---" && sed -n '75,95p' tests/test-admin.php && echo "--- End Debugging ---"
+        run: ./vendor/bin/phpunit
-
-      # - name: Run tests
-      #   run: ./vendor/bin/phpunit
 
   code-style:
     name: Code Style
@@ -57,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/

.wiki/Coding-Standards.md

@@ -67,7 +67,7 @@ if ($condition) {
 ### Documentation
 
 * All classes, methods, and functions should be documented using PHPDoc
-* Include a description of the parameters, return values, and possible exceptions
+* Include descriptions of parameters, return values, and any exceptions thrown
 
 ```php
 /**
@@ -271,7 +271,7 @@ To ensure your code passes the quality checks from these tools, follow these gui
 3. **Using AI Assistants with Code Quality Tools**
    * When you receive feedback from code quality tools, you can use AI assistants to help address the issues
    * Copy the output from the code quality tool and paste it into your AI assistant chat
-   * Ask the AI to help you understand and resolve the issues
+   * Request the AI's assistance to interpret and resolve the reported issues
    * Example prompt:
 
      ```text

.wiki/Contributing.md

@@ -106,7 +106,7 @@ When you receive feedback from these code quality tools, you can use AI assistan
 
 1. Copy the output from the code quality tool
 2. Paste it into your AI assistant chat
-3. Ask the AI to help you understand and resolve the issues
+3. Request the AI's assistance to interpret and resolve the reported issues
 4. Apply the suggested fixes
 5. Commit the changes and verify that the issues are resolved
 
@@ -143,7 +143,7 @@ To ensure your code meets the quality standards, run these commands before submi
 * Check JavaScript coding standards: `npm run lint:js`
 * Check CSS coding standards: `npm run lint:css`
 
-These checks will help identify and fix issues before they are caught by the automated code quality tools in the pull request process.
+These checks will assist in identifying and resolving issues before they are caught by the automated code quality tools in the pull request process.
 
 ## Documentation
 

.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
 

README.md

@@ -376,7 +376,7 @@ When you receive feedback from these code quality tools, you can use AI assistan
 
 1. Copy the output from the code quality tool
 2. Paste it into your AI assistant chat
-3. Ask the AI to help you understand and resolve the issues
+3. Request the AI's assistance to interpret and resolve the reported issues
 4. Apply the suggested fixes
 5. Commit the changes and verify that the issues are resolved
 

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;

bin/setup-test-env.sh

@@ -13,9 +13,25 @@ ENV_TYPE=$1
 
 # Function to check if a command exists
 command_exists() {
-    command -v "$1" &> /dev/null
+	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
@@ -47,7 +63,7 @@ if [ "$ENV_TYPE" == "single" ]; then
 	ATTEMPT=0
 	echo "Waiting for WordPress to be ready..."
 	until wp-env run cli wp core is-installed || [ $ATTEMPT -ge $MAX_ATTEMPTS ]; do
-        ATTEMPT=$((ATTEMPT+1))
+		ATTEMPT=$((ATTEMPT + 1))
 		echo "Attempt $ATTEMPT/$MAX_ATTEMPTS..."
 		sleep 2
 	done
@@ -81,7 +97,7 @@ elif [ "$ENV_TYPE" == "multisite" ]; then
 	ATTEMPT=0
 	echo "Waiting for WordPress to be ready..."
 	until wp-env run cli wp core is-installed || [ $ATTEMPT -ge $MAX_ATTEMPTS ]; do
-        ATTEMPT=$((ATTEMPT+1))
+		ATTEMPT=$((ATTEMPT + 1))
 		echo "Attempt $ATTEMPT/$MAX_ATTEMPTS..."
 		sleep 2
 	done
@@ -120,7 +136,7 @@ elif [ "$ENV_TYPE" == "playground-single" ]; then
 	zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
 
 	# Update blueprint to use local plugin
-    cat > playground/blueprint.json << EOF
+	cat >playground/blueprint.json <<EOF
 {
   "landingPage": "/wp-admin/",
   "preferredVersions": {
@@ -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
@@ -187,7 +205,7 @@ elif [ "$ENV_TYPE" == "playground-multisite" ]; then
 	zip -r dist/plugin.zip . -x "node_modules/*" "dist/*" ".git/*"
 
 	# Update blueprint to use local plugin
-    cat > playground/multisite-blueprint.json << EOF
+	cat >playground/multisite-blueprint.json <<EOF
 {
   "landingPage": "/wp-admin/network/",
   "preferredVersions": {
@@ -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

@@ -71,7 +71,7 @@ if [ -d "vendor" ]; then
 	cp -R vendor "$BUILD_DIR/"
 fi
 
-# Create ZIP file
+# Create ZIP file.
 echo "Creating ZIP file..."
 cd build || exit 1
 zip -r "../$ZIP_FILE" "$PLUGIN_SLUG" -x "*.DS_Store" -x "*.git*" -x "*.github*"
@@ -87,7 +87,7 @@ if [ -f "$ZIP_FILE" ]; then
 		printf '\nDeploying to local WordPress installation...\n'
 		echo "Deploying to local WordPress installation..."
 
-		# Remove existing plugin directory
+		# Remove existing plugin directory.
 		rm -rf "${WP_LOCAL_PLUGIN_DIR:?}/$PLUGIN_SLUG"
 
 		# Copy files to local WordPress installation

phpcs-simple.xml

@@ -14,7 +14,7 @@
     <exclude-pattern>*/build/*</exclude-pattern>
     <exclude-pattern>*/dist/*</exclude-pattern>
 
-    <!-- Command line arguments -->
+    <!-- Command line arguments: combined short flags (-s shows sniff codes, -p shows progress) -->
     <arg value="sp"/>
     <arg name="extensions" value="php"/>
     <arg name="basepath" value="."/>

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>

readme.txt

@@ -150,7 +150,7 @@ When you receive feedback from these code quality tools, you can use AI assistan
 
 1. Copy the output from the code quality tool
 2. Paste it into your AI assistant chat
-3. Ask the AI to help you understand and resolve the issues
+3. Request the AI's assistance to interpret and resolve the reported issues
 4. Apply the suggested fixes
 5. Commit the changes and verify that the issues are resolved