completed tools and setup

EXTERNAL_WP_CLI_TESTING_SETUP.md

@@ -0,0 +1,103 @@
+# 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.