wordpress-agent-kit 0.4.0 → 0.6.0

package/skills-custom/wp-wpengine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wp-wpengine
-description: "Optional: Use for WP Engine hosting workflows — SSH-based git push to WP Engine environments, managing installs/domains/cache/backups via the wpe-labs Claude Code skills, and WP Engine API access. Requires WPE_USERNAME and WPE_PASSWORD env vars."
+description: "Optional: Use for WP Engine hosting workflows — SSH-based git push, remote WP-CLI via SSH gateway, GitHub Actions CI/CD with safety-gated deploys to dev/staging/production, managing installs/domains/cache/backups via the wpe-labs Claude Code skills, and WP Engine API access. Requires SSH key setup and WPE_USERNAME/WPE_PASSWORD env vars for API operations."
 license: GPL-2.0-or-later
 optional: true
 ---
@@ -9,17 +9,26 @@ optional: true
 
 ## When to use
 
-- Deploy WordPress code to a WP Engine environment via `git push`.
+- Deploy WordPress code to a WP Engine environment via `git push` or GitHub Actions.
+- Set up a branch-gated CI/CD pipeline: `develop` → dev, `staging` → staging, `main` → production.
+- Run WP-CLI commands remotely on a WP Engine install (plugin updates, cache flush, DB ops, search-replace).
 - Manage WP Engine installs, domains, cache, backups, or users through natural language.
 - Generate monthly usage/bandwidth reports across WP Engine accounts.
 - Manage LargeFS media offload configuration.
 
 ## Prerequisites
 
-- SSH key for WP Engine git push stored in 1Password (`Employee` vault, item `wpengine_ed25519`).
+- SSH key stored in 1Password (`Employee` vault, item `wpengine_ed25519`).
+  > **Key type note:** RSA 4096-bit is the historically proven key type for WP Engine git push.
+  > Ed25519 is more modern and works on current WP Engine infrastructure, but if you're
+  > setting up a new key, RSA 4096 is the safest choice: `ssh-keygen -t rsa -b 4096 -f ~/.ssh/wpengine_rsa`
+- SSH key registered in the WP Engine portal — both under **Git Push** and **SSH Keys** (two separate registrations, same key).
 - WP Engine API credentials in 1Password (`Employee` vault, item `WP Engine API`).
 - `op` CLI authenticated (`op whoami` works).
-- The `wpe-labs` Claude Code skills installed (`~/.claude/skills/wpe-labs:*`).
+- SSH gateway access requires a **Professional plan or higher**.
+- The `wpe-labs` Claude Code skills installed (`~/.claude/skills/wpe-labs:*`) for natural language management.
+
+---
 
 ## Procedure
 
@@ -30,46 +39,343 @@ Pull the private key from 1Password and configure SSH:
 ```bash
 op read "op://Employee/wpengine_ed25519/private key" > ~/.ssh/wpengine_ed25519
 chmod 600 ~/.ssh/wpengine_ed25519
-ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts
+
+# Trust WP Engine git push host (RSA — what WP Engine's git.wpengine.com serves)
+ssh-keyscan -t rsa git.wpengine.com >> ~/.ssh/known_hosts
+# Gateway: scan the specific install hostname (each install has its own subdomain)
+# Do this once per environment you connect to:
+ssh-keyscan -H <install>.ssh.wpengine.net >> ~/.ssh/known_hosts
+# e.g.: ssh-keyscan -H mysite.ssh.wpengine.net >> ~/.ssh/known_hosts
 ```
 
 Add to `~/.ssh/config` (before any `Host *` block):
+
 ```
+# WP Engine git push
 Host git.wpengine.com
   User git
   IdentityFile ~/.ssh/wpengine_ed25519
   IdentitiesOnly yes
+
+# WP Engine SSH gateway (WP-CLI + file transfer)
+Host *.ssh.wpengine.net
+  IdentityFile ~/.ssh/wpengine_ed25519
+  IdentitiesOnly yes
+  ControlMaster auto
+  ControlPath ~/.ssh/wpe-%r@%h:%p
+  ControlPersist 10m
+  StrictHostKeyChecking accept-new
 ```
 
-Verify:
+> **`StrictHostKeyChecking accept-new`**: automatically accepts and stores the host key on first connection, then rejects any change to that key (MITM protection). Safer than `no`; avoids having to manually `ssh-keyscan` each install hostname.
+>
+> **ControlMaster / ControlPersist**: multiplexes SSH connections so subsequent commands over the same gateway reuse the existing connection. Cuts per-command latency from ~2 s to ~100 ms for repeated WP-CLI invocations.
+
+Verify git push access:
+
 ```bash
 ssh git@git.wpengine.com info
 # Expected: hello <username> / R W <install-name>
 ```
 
-The public key is already registered on WP Engine — no portal action needed on new machines.
+Verify SSH gateway access (replace `<install>` with the WP Engine install slug):
 
-### 2) Add a WP Engine git remote
+```bash
+ssh <install>@<install>.ssh.wpengine.net wp --info
+# Expected: WP-CLI version + paths
+```
+
+---
 
-Find the remote URL on the WP Engine portal: `https://my.wpengine.com/installs/<ENV>/git_push`
+### 2) Deploy via git push
+
+**Always get the exact remote URL from the WP Engine portal** — it includes the environment prefix:
+`https://my.wpengine.com/installs/<ENV>/git_push`
+
+The URL format is: `git@git.wpengine.com:<environment>/<install-name>.git`  
+where `<environment>` is `production`, `staging`, or `development`.
 
 ```bash
-git remote add wpengine git@git.wpengine.com:<install-name>.git
-# Example for staging:
+# Production (copy exact URL from portal)
+# ⚠️  Always copy the exact URL from the WP Engine portal — formats vary by account:
+#    https://my.wpengine.com/installs/<ENV>/git_push
+#
+# Modern accounts (most common):
+git remote add wpengine-prod git@git.wpengine.com:<install-name>.git
+# Legacy accounts (some plans add an environment prefix):
+# git remote add wpengine-prod git@git.wpengine.com:production/<install-name>.git
+
+# Staging (check portal for exact URL)
 git remote add wpengine-staging git@git.wpengine.com:<install-name>stg.git
-```
 
-### 3) Deploy via git push
+# Development (check portal for exact URL)
+git remote add wpengine-dev git@git.wpengine.com:<install-name>dev.git
+```
 
+Deploy:
 ```bash
-git push wpengine main
+git push wpengine-prod main
+# WP Engine expects the branch name 'main' on its remote
+git push wpengine-staging staging:main
 ```
 
 - WP Engine deploys the pushed branch automatically.
-- Only the WordPress files are pushed (not `node_modules`, build artifacts, etc.).
-- After push, WP Engine may take 1–2 min to propagate the deploy.
+- Only WordPress files are pushed — not `node_modules`, build artifacts, or `.git/`.
+- After push, allow 1–2 min for propagation.
+
+> **Verify the remote URL**: `git remote -v` should show `git@git.wpengine.com:production/<install>.git`.
+> If it shows `git@git.wpengine.com:<install>.git` (no environment prefix), update it — that is an older format that may no longer work.
+
+---
+
+### 3) WP-CLI via SSH gateway
+
+WP Engine's SSH gateway host is `{install}.ssh.wpengine.net` with username `{install}`.  
+The WordPress root on the server is `/home/wpe-user/sites/{install}`.
+
+#### Method A — Direct SSH command (simplest)
+
+```bash
+ssh <install>@<install>.ssh.wpengine.net wp <command>
+```
+
+WP-CLI on WP Engine already knows the WordPress path, so `--path` is usually not required. If needed:
+
+```bash
+ssh <install>@<install>.ssh.wpengine.net wp plugin list --path=/home/wpe-user/sites/<install>
+```
+
+Always use `--skip-plugins --skip-themes` on production for safety:
+
+```bash
+ssh <install>@<install>.ssh.wpengine.net \
+  wp cache flush --skip-plugins --skip-themes
+```
+
+#### Method B — WP-CLI `--ssh` flag
+
+WP-CLI's native `--ssh` flag runs any command against a remote install without logging in first:
+
+```bash
+# Format: --ssh=user@host/path
+wp --ssh=<install>@<install>.ssh.wpengine.net:/home/wpe-user/sites/<install> plugin list
+
+# Shorthand — omit path if WP-CLI finds WP at the SSH user's home:
+wp --ssh=<install>@<install>.ssh.wpengine.net cache flush
+```
+
+#### Method C — `wp-cli.yml` aliases (best for repeated use)
+
+Create or update `wp-cli.yml` in your local repo root:
+
+```yaml
+# wp-cli.yml
+@production:
+  ssh: <install>@<install>.ssh.wpengine.net
+  path: /home/wpe-user/sites/<install>
+
+@staging:
+  ssh: <install>stg@<install>stg.ssh.wpengine.net
+  path: /home/wpe-user/sites/<install>stg
+```
+
+Then use the alias for any command:
+
+```bash
+wp @production plugin list --format=json
+wp @staging cache flush
+wp @production db export - > backup-$(date +%F).sql
+wp @production search-replace 'old-domain.com' 'new-domain.com' --dry-run
+```
+
+> Commit `wp-cli.yml` to the repo so all team members and CI pipelines share the same remote aliases.
+
+#### Method D — SCP / rsync for file transfer
+
+The SSH gateway also accepts SCP and rsync (port 22). Use this to pull/push files without a full git push:
+
+```bash
+# SCP: download a file from the server
+scp -P 22 <install>@<install>.ssh.wpengine.net:sites/<install>/wp-content/uploads/large-file.zip ./
+
+# SCP: upload a file to the server
+scp -P 22 ./my-patch.php <install>@<install>.ssh.wpengine.net:sites/<install>/wp-content/plugins/my-plugin/
+
+# rsync: sync wp-content/uploads from production to local (read-only pull)
+rsync -avz --progress \
+  -e "ssh -p 22" \
+  <install>@<install>.ssh.wpengine.net:sites/<install>/wp-content/uploads/ \
+  ./local-uploads/
+
+# rsync: push a theme to staging (careful with --delete)
+rsync -avz --dry-run \
+  -e "ssh -p 22" \
+  ./my-theme/ \
+  <install>stg@<install>stg.ssh.wpengine.net:sites/<install>stg/wp-content/themes/my-theme/
+```
+
+> **WP Engine server path**: WordPress root is `sites/<install>/` relative to the SSH home, or `/home/wpe-user/sites/<install>` as an absolute path. `wp-content/` lives inside that root.
+
+#### Method E — Multiple commands via heredoc
+
+Run several commands in one SSH session without reconnecting:
+
+```bash
+# Heredoc over SSH (most efficient — one connection for all commands)
+ssh <install>@<install>.ssh.wpengine.net bash -s << 'EOF'
+  set -e
+  wp cache flush --skip-plugins --skip-themes
+  wp rewrite flush --skip-plugins --skip-themes
+  wp cron event run --due-now --skip-plugins --skip-themes
+  wp core version --skip-plugins --skip-themes
+EOF
+
+# Interactive WP-CLI commands need -t (pseudo-TTY allocation)
+# e.g. wp shell for a REPL session
+ssh -t <install>@<install>.ssh.wpengine.net wp shell
+```
+
+#### SSH gateway environment notes
+
+- **Restricted shell**: The gateway provides a limited shell environment. WP-CLI, PHP, basic POSIX utilities (echo, cat, stat, du, find, grep) and rsync/SCP are available. Package installation (`apt`, `yum`), sudo, and arbitrary service management are **not** available.
+- **PHP version**: Matches the PHP version configured for that WP Engine install. `php --version` to confirm.
+- **WordPress path**: `~/sites/<install>/` (relative to SSH home) or `/home/wpe-user/sites/<install>` (absolute).
+- **`--path` flag**: If WP-CLI returns "not a WordPress installation", add `--path=/home/wpe-user/sites/<install>` explicitly.
+- **Legacy gateway**: `ssh.wpengine.net` (no subdomain) is the old generic gateway address. Current convention always uses `<install>.ssh.wpengine.net`.
+
+---
+
+### 4) Common remote WP-CLI operations
+
+Always run `--dry-run` or a read-only check first. All examples use Method C aliases.
+
+#### Inspect the environment
 
-### 4) wpe-labs skills (natural language management)
+```bash
+wp @production cli info
+wp @production option get siteurl
+wp @production option get home
+wp @production core version
+```
+
+#### Plugin and theme management
+
+```bash
+# List all plugins with status
+wp @production plugin list --format=json
+
+# Update a specific plugin
+wp @production plugin update woocommerce
+
+# Update all plugins (preview first)
+wp @production plugin update --all --dry-run
+wp @production plugin update --all
+
+# Activate/deactivate
+wp @production plugin activate <slug>
+wp @production plugin deactivate <slug> --skip-plugins --skip-themes
+```
+
+#### Cache flush (always safe post-deploy)
+
+```bash
+wp @production cache flush
+wp @production rewrite flush
+wp @production transient delete --all
+```
+
+#### Database operations
+
+```bash
+# Export to local file (streams via SSH)
+wp @production db export - > backup-$(date +%F-%H%M).sql
+
+# Check DB size
+wp @production db size --tables --format=table
+
+# Run a specific query
+wp @production db query "SELECT option_name, option_value FROM wp_options WHERE autoload='yes' LIMIT 20"
+```
+
+#### Search and replace (migration / domain change)
+
+```bash
+# Always dry-run first
+wp @production search-replace 'http://old-domain.com' 'https://new-domain.com' \
+  --dry-run --report-changed-only
+
+# Then apply (--precise handles serialized data safely)
+wp @production search-replace 'http://old-domain.com' 'https://new-domain.com' \
+  --precise --report-changed-only
+
+# Flush after replace
+wp @production cache flush && wp @production rewrite flush
+```
+
+See `wp-wpcli-and-ops` skill → `references/search-replace.md` for full search-replace patterns.
+
+#### User management
+
+```bash
+# List admin users
+wp @production user list --role=administrator --format=table
+
+# Create a temporary admin (disable after)
+wp @production user create tempagent temp@example.com --role=administrator --user_pass=<strong-pass>
+# ... do work ...
+wp @production user delete tempagent --reassign=1
+```
+
+#### Cron inspection and triggering
+
+```bash
+wp @production cron event list --format=table
+wp @production cron event run --due-now
+wp @production cron event run <hook-name>
+```
+
+---
+
+### 7) GitHub Actions CI/CD pipeline
+
+For full branch-gated deploys with safety guards, pre-deploy backups, smoke tests, and auto-rollback:
+
+Read: `references/github-actions-deploy.md`
+
+**CI gate policy — no `--no-verify`:**
+- All lint, typecheck, tests, and build checks must pass before any push reaches a deploy branch.
+- `--no-verify` is explicitly forbidden. Hooks exist to surface problems early — bypass them and you own the breakage.
+- The CI gate runs two parallel jobs (`php-gate` + `js-gate`) for every push to a protected branch. Required status check.
+- Every deploy workflow runs a `verify` job as its first dependency — deploys never start without it passing.
+
+Read: `references/ci-gate.md`
+
+**Agent-runnable scripts:**
+
+| Script | Purpose | When to use |
+|--------|---------|-------------|
+| `scripts/ci-gate.sh` | Run the full local CI gate (PHP + JS/TS) | Before any push to a deploy branch |
+| `scripts/wpe-preflight.sh` | Pre-deploy sanity checks (SSH, WP, HTTP) | Before triggering a deploy |
+| `scripts/wpe-check.sh` | SSH connectivity to all configured installs | After machine setup or debugging SSH |
+
+Run CI gate locally:
+```bash
+bash {baseDir}/scripts/ci-gate.sh
+```
+
+Run pre-deploy preflight:
+```bash
+INSTALL=mysite bash {baseDir}/scripts/wpe-preflight.sh production
+```
+
+Check all SSH connections:
+```bash
+bash {baseDir}/scripts/wpe-check.sh
+```
+
+---
+
+### 8) wpe-labs skills (natural language management)
 
 Load API credentials, then use any `/wpe-labs:*` skill:
 
@@ -78,8 +384,6 @@ Load API credentials, then use any `/wpe-labs:*` skill:
 eval $(op run --env-file ~/.config/op-ssh/.env.1pass -- env | grep ^WPE | sed 's/^/export /')
 ```
 
-Available skills:
-
 | Skill | What it does | Risk |
 |---|---|---|
 | `/wpe-labs:account-usage` | Bandwidth, visits, storage across accounts | 🟢 Read-only |
@@ -92,6 +396,7 @@ Available skills:
 | `/wpe-labs:offload` | LargeFS media offload config | 🟡 Write |
 
 Example prompts:
+
 ```
 /wpe-labs:account-usage which accounts are closest to their bandwidth limit?
 /wpe-labs:cache purge all cache for uofdev production
@@ -100,28 +405,58 @@ Example prompts:
 /wpe-labs:monthly-report last month
 ```
 
-### 5) Re-installing wpe-labs skills
+### 9) Re-installing wpe-labs skills
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/wpengine/wpe-labs-platform-skills/main/install.sh | bash
 ```
 
+---
+
 ## Verification
 
-- SSH: `ssh git@git.wpengine.com info` — should return `hello <username> / R W <install>`
-- API: `op run --env-file ~/.config/op-ssh/.env.1pass -- bash -c 'curl -s -u "$WPE_USERNAME:$WPE_PASSWORD" https://api.wpengineapi.com/v1/user | jq .email'`
+| Check | Command |
+|---|---|
+| Git push SSH | `ssh git@git.wpengine.com info` → `hello <user> / R W <install>` |
+| SSH gateway | `ssh <install>@<install>.ssh.wpengine.net wp --info` |
+| WP-CLI alias | `wp @production core version` |
+| API credentials | `op run --env-file ~/.config/op-ssh/.env.1pass -- bash -c 'curl -s -u "$WPE_USERNAME:$WPE_PASSWORD" https://api.wpengineapi.com/v1/user | jq .email'` |
+
+---
+
+## Safety guardrails for remote operations
+
+- **Always `--dry-run` first** for any search-replace or destructive DB operation.
+- **Always export a DB backup** before schema changes or large search-replaces.
+- **Use `--skip-plugins --skip-themes`** on production for cache flush, deactivations, and anything where a broken plugin might short-circuit the operation.
+- **Prefer staging** for testing WP-CLI commands before running on production.
+- **ControlMaster is safe** — it reuses an existing authenticated session; no new credentials are stored.
+- **wpe-labs write operations** (`backups`, `cache`, `installs`, `users`, `domains`) should be confirmed before execution.
+
+---
 
 ## Failure modes
 
-- **SSH: Host key verification failed** — re-run `ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts`
-- **SSH: Permission denied** — confirm the key is at `~/.ssh/wpengine_ed25519` with `chmod 600`
-- **git push rejected** — verify the remote URL matches the install name exactly
-- **wpe-labs: 401 Unauthorized** — regenerate API credentials at `https://my.wpengine.com/api_access` and update the `WP Engine API` item in 1Password
-- **wpe-labs: storage shows zero** — ask Claude to "refresh storage" (async recalculation, ~30–60s)
+| Symptom | Fix |
+|---|---|
+| `Host key verification failed` (git) | `ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts` |
+| `Host key verification failed` (gateway) | Run `ssh-keyscan -H <install>.ssh.wpengine.net >> ~/.ssh/known_hosts` for that specific install hostname. Or add `StrictHostKeyChecking accept-new` to the `*.ssh.wpengine.net` SSH config block — it will auto-accept on first connect. |
+| `Permission denied` | Confirm key at `~/.ssh/wpengine_ed25519`, `chmod 600`. Check the key is registered under **SSH Keys** in the WP Engine portal (separate from git push keys). |
+| `git push rejected` | Get the exact URL from the portal (`https://my.wpengine.com/installs/<ENV>/git_push`). URL format varies by account — copy it verbatim. |
+| SSH gateway hangs | Kill stale ControlMaster socket: `ssh -O stop <install>@<install>.ssh.wpengine.net` |
+| `wp: command not found` on gateway | WP Engine's WP-CLI path: try `php /usr/local/bin/wp` or contact WP Engine support |
+| WP-CLI returns wrong site | Add `--path=/home/wpe-user/sites/<install>` explicitly |
+| `401 Unauthorized` (wpe-labs) | Regenerate API credentials at `https://my.wpengine.com/api_access`, update 1Password item |
+| `storage shows zero` (wpe-labs) | Ask to "refresh storage" (async recalculation, ~30–60 s) |
+
+---
 
 ## References
 
+- WP Engine SSH gateway docs: `https://wpengine.com/support/ssh-gateway/`
 - WP Engine git push portal: `https://my.wpengine.com/installs/<ENV>/git_push`
+- WP Engine SSH Keys portal: `https://my.wpengine.com/ssh_keys`
 - WP Engine API access: `https://my.wpengine.com/api_access`
+- WP-CLI `--ssh` docs: `https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/`
 - wpe-labs skills source: `https://github.com/wpengine/wpe-labs-platform-skills`
 - SSH setup log (first machine): gist `602d6a16ddfea438c0611a8e5cc31d5e`