claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-local-env/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: wp-local-env
+description: "Use when the user wants to work with a local WordPress development environment
+  — WordPress Studio, LocalWP, or wp-env. Handles environment detection, site lifecycle,
+  WP-CLI proxy, REST API access, symlink workflows, database operations, and preview/share."
+compatibility: "Cross-platform (Linux, macOS, Windows). WordPress Studio requires the desktop app + CLI enabled. LocalWP requires the desktop app. wp-env requires Docker + Node.js."
+version: 1.0.0
+---
+
+# Local WordPress Environment
+
+## When to use
+
+Use this skill when the task involves local WordPress development environments:
+
+- Detecting which local dev tool is installed (Studio, LocalWP, wp-env)
+- Creating, starting, stopping, or deleting local WordPress sites
+- Running WP-CLI commands against a local site
+- Setting up plugin/theme development via symlinks
+- Accessing the local REST API or database
+- Switching PHP/WordPress versions for testing
+- Previewing or sharing a local site externally
+- Preparing a local site for deployment to production
+
+## Inputs required
+
+- Whether the user has WordPress Studio, LocalWP, or wp-env (auto-detected)
+- The site to operate on (name, path, or auto-detected from current directory)
+- The desired operation (lifecycle, development, testing, deploy prep)
+
+## Procedure
+
+### 0) Detect local environments
+
+Run the detection script to discover installed tools and sites:
+
+```bash
+node skills/wp-local-env/scripts/detect_local_env.mjs
+```
+
+The script outputs JSON with:
+- `environments[]` — each tool found with its sites
+- `recommended` — which tool to prefer for automation
+- `wpCli` — how to invoke WP-CLI for each tool
+
+If no environment is found, suggest installation:
+- **WordPress Studio** (lightweight, fast): https://developer.wordpress.com/studio/
+- **LocalWP** (production-parity): https://localwp.com/
+- **wp-env** (Docker-based, for contributors): `npm -g install @wordpress/env`
+
+### 1) Site lifecycle
+
+#### Create a new local site
+
+**WordPress Studio:**
+```bash
+studio site create --path ~/Studio/my-site
+# Optional flags: --php-version=8.2 --domain=mysite.wp.local --https
+```
+
+**LocalWP:** Site creation is GUI-only. Guide the user through:
+1. Open LocalWP → "Create a new site"
+2. Choose site name, PHP version, web server (NGINX/Apache)
+3. Set WordPress admin credentials
+
+**wp-env:** Create `.wp-env.json` in the project root:
+```json
+{
+  "core": "WordPress/WordPress#6.9",
+  "plugins": ["./my-plugin"],
+  "themes": ["./my-theme"]
+}
+```
+Then: `npx wp-env start`
+
+#### Start / stop / delete
+
+| Operation | Studio | LocalWP | wp-env |
+|-----------|--------|---------|--------|
+| Start | `studio site start --path=<path>` | GUI only | `npx wp-env start` |
+| Stop | `studio site stop --path=<path>` | GUI only | `npx wp-env stop` |
+| Delete | `studio site delete --path=<path>` | GUI only | `npx wp-env destroy` |
+| Status | `studio site status --path=<path>` | Parse `sites.json` | `npx wp-env run cli wp option get siteurl` |
+
+### 2) WP-CLI operations
+
+WP-CLI is the primary automation interface for all local tools. Each tool has a different invocation method:
+
+**WordPress Studio** (no separate WP-CLI install needed):
+```bash
+studio wp <command> --path=<site-path>
+# Examples:
+studio wp plugin list --path=~/Studio/my-site
+studio wp scaffold plugin my-plugin --path=~/Studio/my-site
+studio wp db export backup.sql --path=~/Studio/my-site
+```
+
+**LocalWP** (uses bundled WP-CLI binary):
+```bash
+# Find the binary from detect_local_env.mjs output, then:
+<wp-cli-bin> --path=<site-root> <command>
+# Typical path on Linux:
+~/.config/Local/lightning-services/wp-cli-*/bin/wp --path="~/Local Sites/my-site/app/public" plugin list
+```
+
+**wp-env** (Docker-wrapped):
+```bash
+npx wp-env run cli wp <command>
+# Examples:
+npx wp-env run cli wp plugin list
+npx wp-env run cli wp scaffold block my-block --plugin=my-plugin
+```
+
+Read: `references/studio-adapter.md`, `references/localwp-adapter.md`, `references/wpenv-adapter.md`
+
+### 3) Development workflow (symlink pattern)
+
+For active plugin/theme development, symlink your project into the local site:
+
+**WordPress Studio:**
+```bash
+ln -s /path/to/my-plugin ~/Studio/my-site/wp-content/plugins/my-plugin
+studio wp plugin activate my-plugin --path=~/Studio/my-site
+```
+
+**LocalWP:**
+```bash
+ln -s /path/to/my-plugin ~/Local\ Sites/my-site/app/public/wp-content/plugins/my-plugin
+<wp-cli-bin> --path="~/Local Sites/my-site/app/public" plugin activate my-plugin
+```
+
+**wp-env:** Map in `.wp-env.json` instead of symlinking:
+```json
+{ "plugins": ["./my-plugin", "/absolute/path/to/other-plugin"] }
+```
+
+### 4) REST API access
+
+All local tools expose the WordPress REST API:
+
+| Tool | URL pattern |
+|------|-------------|
+| Studio | `http://localhost:888x/wp-json/wp/v2/` |
+| LocalWP | `http://<name>.local/wp-json/wp/v2/` or `http://127.0.0.1:<port>/wp-json/wp/v2/` |
+| wp-env | `http://localhost:8888/wp-json/wp/v2/` |
+
+For authenticated requests, create an Application Password:
+```bash
+studio wp user application-password create admin "claude-code" --path=<site>
+# or via the WP-CLI equivalent for LocalWP / wp-env
+```
+
+The existing `wp-rest-bridge` MCP server can connect to local sites by configuring `WP_SITES_CONFIG` with the local URL.
+
+### 5) Database operations
+
+**Studio (SQLite):**
+```bash
+# Export as SQL (MySQL-compatible):
+studio wp db export backup.sql --path=<site>
+# Direct SQLite access:
+sqlite3 ~/Studio/<site>/wp-content/database/.ht.sqlite
+```
+
+**LocalWP (MySQL):**
+```bash
+# Via WP-CLI:
+<wp-cli-bin> --path=<site-root> db export backup.sql
+# Direct MySQL access (credentials: root/root, db: local):
+mysql --socket=~/.config/Local/run/<site-id>/mysql/mysqld.sock -u root -proot local
+```
+
+**wp-env (MySQL in Docker):**
+```bash
+npx wp-env run cli wp db export /tmp/backup.sql
+```
+
+### 6) Testing and version switching
+
+**Switch PHP version:**
+- Studio: `studio site set --php-version=8.2 --path=<site>`
+- LocalWP: GUI → Site Settings → PHP Version
+- wp-env: Set `"phpVersion": "8.2"` in `.wp-env.json`, then `npx wp-env start --update`
+
+**Switch WordPress version:**
+- Studio: `studio site set --wp-version=6.8 --path=<site>` (if supported) or `studio wp core update --version=6.8`
+- LocalWP: `<wp-cli-bin> --path=<site-root> core update --version=6.8`
+- wp-env: Set `"core": "WordPress/WordPress#6.8"` in `.wp-env.json`
+
+### 7) Preview and share
+
+**Studio:** Built-in preview deployment to WordPress.com:
+```bash
+studio preview create --path=<site>
+# Returns a public URL like https://<hash>.wp.build
+studio preview update <host> --path=<site>
+studio preview delete <host>
+```
+
+**LocalWP:** Live Links feature (GUI only). Alternative:
+```bash
+# Use ngrok or cloudflared for tunneling:
+ngrok http <port>
+cloudflared tunnel --url http://localhost:<port>
+```
+
+**wp-env:** No built-in sharing. Use ngrok against port 8888.
+
+### 8) MCP integration (optional)
+
+For deeper AI integration, consider setting up the WordPress MCP Adapter plugin (WordPress 6.9+). This turns any local WordPress site into an MCP server.
+
+Read: `references/mcp-adapter-setup.md`
+
+## Verification
+
+- Re-run `detect_local_env.mjs` after installing/removing tools or creating/deleting sites.
+- Verify WP-CLI access: run `wp option get siteurl` via the tool-specific method.
+- Verify REST API: `curl <site-url>/wp-json/wp/v2/` should return the API index.
+
+## Failure modes / debugging
+
+- **Studio CLI not found**: Enable CLI in Studio → Settings → toggle CLI.
+- **LocalWP sites.json missing**: LocalWP may not be installed, or is a very old version.
+- **LocalWP WP-CLI fails**: The MySQL server for that site must be running (start via GUI).
+- **wp-env fails to start**: Check Docker is running (`docker info`).
+- **Port conflicts**: Studio uses 8881+, LocalWP uses 10000+, wp-env uses 8888. If conflict, check `lsof -i :<port>`.
+
+## Escalation
+
+- If the user needs features not available in their tool (e.g., multisite on Studio, Xdebug on Studio), recommend switching to LocalWP or wp-env.
+- If no local tool is installed and Docker is not available, fall back to `wp-playground` (ephemeral WASM-based).
+- For production-parity testing, always recommend LocalWP (MySQL + native PHP).

package/skills/wp-local-env/references/localwp-adapter.md

@@ -0,0 +1,156 @@
+# LocalWP Adapter
+
+## Prerequisites
+
+- LocalWP desktop app installed (https://localwp.com/)
+- Site must be started via GUI before WP-CLI or REST API access
+
+## Site discovery
+
+LocalWP stores all site metadata in a JSON file:
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.config/Local/sites.json` |
+| macOS | `~/Library/Application Support/Local/sites.json` |
+| Windows | `%APPDATA%\Local\sites.json` |
+
+### sites.json schema (per site)
+
+```json
+{
+  "<site-id>": {
+    "id": "<uuid>",
+    "name": "My Site",
+    "domain": "my-site.local",
+    "path": "/home/user/Local Sites/my-site",
+    "services": {
+      "nginx": { "port": 10006, "sslPort": 10007 },
+      "mysql": { "port": 10008 },
+      "php": { "version": "8.2.10" }
+    },
+    "url": "http://my-site.local",
+    "sslUrl": "https://my-site.local"
+  }
+}
+```
+
+## Directory structure
+
+```
+~/Local Sites/<site-name>/
+├── app/
+│   └── public/              ← WordPress root (document root)
+│       ├── wp-content/
+│       │   ├── themes/
+│       │   ├── plugins/
+│       │   └── uploads/
+│       ├── wp-config.php
+│       └── ...
+├── conf/
+│   ├── nginx/site.conf
+│   ├── php/php.ini
+│   └── mysql/my.cnf
+└── logs/
+    ├── nginx/{error.log, access.log}
+    ├── php/error.log
+    └── mysql/error.log
+```
+
+## WP-CLI access
+
+LocalWP bundles WP-CLI. Find the binary at:
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.config/Local/lightning-services/wp-cli-<version>/bin/wp` |
+| macOS | `~/Library/Application Support/Local/lightning-services/wp-cli-<version>/bin/wp` |
+| Windows | `%APPDATA%\Local\lightning-services\wp-cli-<version>\bin\wp.bat` |
+
+Usage:
+```bash
+<wp-cli-bin> --path="~/Local Sites/my-site/app/public" <command>
+
+# Examples:
+<wp-cli-bin> --path="$HOME/Local Sites/my-site/app/public" plugin list
+<wp-cli-bin> --path="$HOME/Local Sites/my-site/app/public" db export backup.sql
+<wp-cli-bin> --path="$HOME/Local Sites/my-site/app/public" scaffold plugin my-plugin
+```
+
+**Important**: The site's MySQL server must be running (started via GUI) for WP-CLI to work.
+
+## MySQL access
+
+Default credentials for all LocalWP sites:
+- **User**: `root`
+- **Password**: `root`
+- **Database**: `local`
+
+### Via socket
+
+```bash
+# Find socket path from sites.json site id:
+mysql --socket=~/.config/Local/run/<site-id>/mysql/mysqld.sock -u root -proot local
+```
+
+### Via TCP
+
+```bash
+# Port from sites.json → services.mysql.port:
+mysql -h 127.0.0.1 -P <port> -u root -proot local
+```
+
+## REST API
+
+Accessible when site is running:
+```bash
+# Via custom domain (requires hosts file entry, managed by LocalWP):
+curl http://my-site.local/wp-json/wp/v2/posts
+
+# Via port directly:
+curl http://127.0.0.1:<nginx-port>/wp-json/wp/v2/posts
+```
+
+## Blueprints
+
+LocalWP supports site blueprints (templates):
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.config/Local/blueprints/` |
+| macOS | `~/Library/Application Support/Local/blueprints/` |
+
+Create: Right-click site → "Save as Blueprint"
+Use: New site → select Blueprint during creation
+
+## Symlink workflow
+
+```bash
+ln -s /path/to/my-plugin "$HOME/Local Sites/my-site/app/public/wp-content/plugins/my-plugin"
+<wp-cli-bin> --path="$HOME/Local Sites/my-site/app/public" plugin activate my-plugin
+```
+
+## Logs
+
+Direct access to web server, PHP, and MySQL logs:
+```bash
+tail -f ~/Local\ Sites/my-site/logs/nginx/error.log
+tail -f ~/Local\ Sites/my-site/logs/php/error.log
+tail -f ~/Local\ Sites/my-site/logs/mysql/error.log
+```
+
+## Known limitations
+
+- **No CLI for site creation/start/stop** — GUI only
+- **Live Links** — GUI only (not scriptable)
+- **Heavy resource usage** — runs native NGINX + PHP-FPM + MySQL processes per site
+- **PHP version changes** — GUI only
+
+## Strengths over Studio
+
+- **Full MySQL** — production parity, no SQLite compatibility issues
+- **Multisite** — WordPress network fully supported
+- **Xdebug** — available via add-on
+- **MailHog** — email testing built-in
+- **NGINX or Apache** — choose per site
+- **Native PHP extensions** — full set available

package/skills/wp-local-env/references/mcp-adapter-setup.md

@@ -0,0 +1,153 @@
+# WordPress MCP Adapter Setup
+
+## What is the MCP Adapter?
+
+The MCP Adapter is a WordPress plugin (available from WordPress 6.9+) that turns any WordPress installation into an MCP (Model Context Protocol) server. This allows AI agents like Claude Code to interact with WordPress through a standardized protocol.
+
+**Source**: https://github.com/WordPress/mcp-adapter
+
+## Transport modes
+
+### STDIO (for local sites via WP-CLI)
+
+The STDIO transport runs the MCP server as a WP-CLI command. Best for local development sites.
+
+**Requirements:**
+- WP-CLI available (via Studio, LocalWP bundled, or system install)
+- MCP Adapter plugin installed and activated on the local site
+- A WordPress user with sufficient permissions
+
+### HTTP (for remote sites)
+
+The HTTP transport exposes an MCP endpoint via the WordPress REST API. Best for remote or staging sites.
+
+**Requirements:**
+- MCP Adapter plugin installed and activated
+- Application Password for authentication
+- Site accessible via HTTPS (recommended)
+
+## Setup: STDIO with WordPress Studio
+
+1. Install the MCP Adapter plugin:
+```bash
+studio wp plugin install mcp-adapter --activate --path=~/Studio/my-site
+```
+
+2. Add to `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "wp-local-mcp": {
+      "command": "studio",
+      "args": [
+        "wp", "mcp-adapter", "serve",
+        "--server=mcp-adapter-default-server",
+        "--user=admin",
+        "--path=/home/user/Studio/my-site"
+      ]
+    }
+  }
+}
+```
+
+## Setup: STDIO with LocalWP
+
+1. Find the WP-CLI binary (from `detect_local_env.mjs` output or manually):
+```bash
+WP_CLI=~/.config/Local/lightning-services/wp-cli-*/bin/wp
+```
+
+2. Install the MCP Adapter plugin:
+```bash
+$WP_CLI --path="$HOME/Local Sites/my-site/app/public" plugin install mcp-adapter --activate
+```
+
+3. Add to `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "wp-local-mcp": {
+      "command": "/home/user/.config/Local/lightning-services/wp-cli-2.11.0/bin/wp",
+      "args": [
+        "--path=/home/user/Local Sites/my-site/app/public",
+        "mcp-adapter", "serve",
+        "--server=mcp-adapter-default-server",
+        "--user=admin"
+      ]
+    }
+  }
+}
+```
+
+**Note**: The LocalWP site must be started (via GUI) for the MySQL connection to work.
+
+## Setup: STDIO with wp-env
+
+```json
+{
+  "mcpServers": {
+    "wp-local-mcp": {
+      "command": "npx",
+      "args": [
+        "wp-env", "run", "cli", "wp",
+        "mcp-adapter", "serve",
+        "--server=mcp-adapter-default-server",
+        "--user=admin"
+      ]
+    }
+  }
+}
+```
+
+## Setup: HTTP (remote sites)
+
+1. Install and activate the MCP Adapter plugin on the remote site.
+
+2. Create an Application Password for the user (WP Admin → Users → Profile).
+
+3. Use the remote MCP client:
+```json
+{
+  "mcpServers": {
+    "wp-remote-mcp": {
+      "command": "npx",
+      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
+      "env": {
+        "WP_API_URL": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
+        "WP_API_USERNAME": "admin",
+        "WP_API_PASSWORD": "<application-password>"
+      }
+    }
+  }
+}
+```
+
+## Studio MCP Server (alternative)
+
+Automattic also publishes a dedicated Studio MCP server in the `wordpress-agent-skills` repo. This provides site management tools without requiring the MCP Adapter plugin.
+
+Setup:
+```bash
+git clone https://github.com/Automattic/wordpress-agent-skills.git
+cd wordpress-agent-skills/studio-mcp && npm install && npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "studio-mcp": {
+      "command": "node",
+      "args": ["/path/to/wordpress-agent-skills/studio-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Which approach to choose?
+
+| Scenario | Recommended |
+|----------|-------------|
+| Quick local dev with Studio | Studio MCP Server |
+| Full WP operations on local site | MCP Adapter (STDIO) |
+| Remote/staging site | MCP Adapter (HTTP) via `@automattic/mcp-wordpress-remote` |
+| Existing wp-rest-bridge setup | Point `WP_SITES_CONFIG` at `localhost:<port>` |

package/skills/wp-local-env/references/studio-adapter.md

@@ -0,0 +1,127 @@
+# WordPress Studio Adapter
+
+## Prerequisites
+
+- WordPress Studio desktop app installed and running
+- CLI enabled: Studio → Settings → toggle "Enable CLI"
+- The `studio` command must be available in PATH
+
+## CLI reference
+
+### Site lifecycle
+
+```bash
+# Create a new site
+studio site create --path ~/Studio/my-site
+studio site create --path ~/Studio/my-site --php-version=8.2 --https --domain=mysite.wp.local
+
+# List all sites
+studio site list
+
+# Site status
+studio site status --path=~/Studio/my-site
+
+# Start / stop
+studio site start --path=~/Studio/my-site
+studio site stop --path=~/Studio/my-site
+
+# Delete (--files removes files on disk)
+studio site delete --path=~/Studio/my-site
+studio site delete --path=~/Studio/my-site --files
+
+# Configure
+studio site set --php-version=8.3 --path=~/Studio/my-site
+```
+
+### WP-CLI proxy
+
+No separate WP-CLI installation needed. Studio bundles and configures it automatically.
+
+```bash
+studio wp <command> --path=<site-path>
+
+# Common operations:
+studio wp plugin list --path=~/Studio/my-site
+studio wp plugin install woocommerce --activate --path=~/Studio/my-site
+studio wp theme activate twentytwentyfive --path=~/Studio/my-site
+studio wp scaffold plugin my-plugin --path=~/Studio/my-site
+studio wp scaffold block my-block --plugin=my-plugin --path=~/Studio/my-site
+studio wp user create testuser test@example.com --role=editor --path=~/Studio/my-site
+studio wp db export backup.sql --path=~/Studio/my-site
+studio wp eval 'echo get_bloginfo("name");' --path=~/Studio/my-site
+studio wp option update blogname "My Site" --path=~/Studio/my-site
+```
+
+### Preview (WordPress.com deployment)
+
+```bash
+studio preview create --path=~/Studio/my-site
+studio preview list
+studio preview update <host> --path=~/Studio/my-site
+studio preview delete <host>
+```
+
+### Authentication
+
+```bash
+studio auth login    # OAuth browser flow to WordPress.com
+studio auth status
+studio auth logout
+```
+
+## Path conventions
+
+| Item | Path |
+|------|------|
+| Sites root | `~/Studio/` |
+| WordPress root | `~/Studio/<site-name>/` |
+| Plugins | `~/Studio/<site-name>/wp-content/plugins/` |
+| Themes | `~/Studio/<site-name>/wp-content/themes/` |
+| Uploads | `~/Studio/<site-name>/wp-content/uploads/` |
+| SQLite DB | `~/Studio/<site-name>/wp-content/database/.ht.sqlite` |
+| App config (Linux) | `~/.config/WordPressStudio/` |
+| App config (macOS) | `~/Library/Application Support/WordPressStudio/` |
+
+## Ports
+
+Sites are assigned ports sequentially starting at **8881**:
+- First site: `http://localhost:8881`
+- Second site: `http://localhost:8882`
+
+Custom domains with HTTPS are supported via `--domain` and `--https` flags.
+
+## Database (SQLite)
+
+Studio uses SQLite instead of MySQL. The database file is at:
+```
+<site-root>/wp-content/database/.ht.sqlite
+```
+
+Direct access:
+```bash
+sqlite3 ~/Studio/my-site/wp-content/database/.ht.sqlite
+sqlite> .tables
+sqlite> SELECT * FROM wp_options WHERE option_name = 'siteurl';
+```
+
+**SQLite limitations:**
+- No stored procedures or complex triggers
+- Some plugins with complex MySQL-specific queries may break (notably WooCommerce complex queries)
+- SQLite dumps are NOT directly compatible with MySQL — use `wp db export` for MySQL-compatible `.sql` files
+
+## Symlink workflow
+
+For development, symlink your project repo into the site:
+
+```bash
+ln -s /home/user/projects/my-plugin ~/Studio/my-site/wp-content/plugins/my-plugin
+studio wp plugin activate my-plugin --path=~/Studio/my-site
+```
+
+## Known limitations
+
+- **No multisite / WordPress network**
+- **No Xdebug** (WASM runtime does not support it)
+- **Limited PHP extensions** (only those compiled to WASM)
+- **Linux**: may require building from source (no official package)
+- **Requires Studio app running** for CLI to work (IPC communication)