# 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.