shopify-ai-backup/EXTERNAL_WP_CLI_TESTING_SETUP.md

External WP-CLI Testing Setup

This guide explains how to enable and run External WP-CLI Testing from the Builder, with tools loaded into OpenCode only when the feature toggle is enabled.

What This Adds

• A gated MCP tool named test_plugin_external_wp (plus a helper tool external_wp_testing_config).
• Tools are injected into OpenCode only when the Builder toggle is on.
• All connection/auth settings are controlled via environment variables.

Prerequisites

1. A reachable WordPress host with WP-CLI installed.
2. SSH access to that host from the server running the chat app.
3. The SSH user must be able to run WP-CLI at the configured path.

Required Environment Variables

Set these in the environment where the chat server runs (the same process that launches OpenCode).

• TEST_WP_HOST (or EXTERNAL_WP_HOST)
  • Hostname or IP of the WordPress server.
• TEST_WP_SSH_USER (or EXTERNAL_WP_SSH_USER)
  • SSH username for the WordPress server.
• TEST_WP_SSH_KEY (or TEST_WP_SSH_KEY_PATH, or EXTERNAL_WP_SSH_KEY)
  • Path to the SSH private key file.

If these are missing, the tool will return a clear error.

Optional Environment Variables

• TEST_WP_PATH (or EXTERNAL_WP_PATH)
  • Default: /var/www/html
  • Path to the WordPress root on the remote host.
• TEST_WP_BASE_URL (or EXTERNAL_WP_BASE_URL)
  • Default: https://<TEST_WP_HOST>
  • Base URL for the site.
• TEST_WP_MULTISITE (or EXTERNAL_WP_MULTISITE)
  • Default: true
  • Enables multisite subsite isolation.
• TEST_WP_SUBSITE_PREFIX (or EXTERNAL_WP_SUBSITE_PREFIX)
  • Default: test
  • Prefix for created subsites.
• TEST_WP_SUBSITE_DOMAIN (or EXTERNAL_WP_SUBSITE_DOMAIN)
  • Default: empty (falls back to host)
  • Domain used when subsite mode is subdomain.
• TEST_WP_SUBSITE_MODE (or EXTERNAL_WP_SUBSITE_MODE)
  • Default: subdirectory
  • Allowed values: subdirectory, subdomain.
• TEST_WP_ERROR_LOG (or EXTERNAL_WP_ERROR_LOG)
  • Default: /var/log/wp-errors.log
  • Used by the default "Scan error log" scenario.
• TEST_SSH_STRICT (or EXTERNAL_WP_SSH_STRICT)
  • Default: false
  • When true, enforces strict host key checking.
• TEST_MAX_CONCURRENT (or EXTERNAL_WP_MAX_CONCURRENT)
  • Default: 20
  • Max concurrent tests.
• TEST_QUEUE_TIMEOUT (or EXTERNAL_WP_QUEUE_TIMEOUT)
  • Default: 300000 (ms)
• TEST_TIMEOUT (or EXTERNAL_WP_TEST_TIMEOUT)
  • Default: 600000 (ms)
• TEST_AUTO_CLEANUP (or EXTERNAL_WP_AUTO_CLEANUP)
  • Default: true
  • Cleans up subsites after tests complete.
• TEST_CLEANUP_DELAY (or EXTERNAL_WP_CLEANUP_DELAY)
  • Default: 3600000 (ms)

Example .env

TEST_WP_HOST=wp-test.example.com TEST_WP_SSH_USER=wordpress TEST_WP_SSH_KEY=C:\keys\wp-test.pem TEST_WP_PATH=/var/www/html TEST_WP_BASE_URL=https://wp-test.example.com TEST_WP_MULTISITE=true TEST_WP_SUBSITE_MODE=subdirectory TEST_WP_SUBSITE_PREFIX=test TEST_WP_ERROR_LOG=/var/log/wp-errors.log TEST_SSH_STRICT=false TEST_MAX_CONCURRENT=20 TEST_TIMEOUT=600000

Builder Toggle Behavior

• Open the Builder and enable the "External WP CLI testing" toggle.
• When enabled, the chat server injects the MCP server definition via OPENCODE_EXTRA_MCP_SERVERS.
• When disabled, the environment variable is removed before OpenCode is spawned, so the tools are not exposed.

Running a Test

1. Enable the toggle in Builder.
2. Proceed with the build or let the AI call test_plugin_external_wp.
3. The tool runs WP-CLI commands over SSH and returns a JSON report.

Quick Sanity Check Tool

You can ask the AI to call external_wp_testing_config to validate your settings. It returns the resolved config and a list of missing required variables.

Notes

• test_plugin_external_wp only supports test_mode=cli in the current implementation.
• Ensure the SSH user can execute WP-CLI and write to the plugin directory.