From 7c60bfb22d834a63e4fb07c81d6c77762a4f6361 Mon Sep 17 00:00:00 2001 From: Dan Knauss Date: Fri, 20 Mar 2026 17:35:20 -0600 Subject: [PATCH 1/3] Add studio and studio-xdebug skills for WordPress Studio development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two new skills for developing and debugging in WordPress Studio: studio — Covers site creation, WP-CLI via Studio's bundled PHP, SQLite database access, plugin/theme symlink workflows, Playwright E2E testing, and environment troubleshooting. Includes defensive checks for common conflicts: port collisions, stale /etc/hosts entries, global WP-CLI configs, and rogue processes on development ports. studio-xdebug — Covers Xdebug step debugging in Studio's WASM PHP environment: VS Code launch.json with /wordpress/ path mappings, reading enhanced stack traces, diagnostic mu-plugins, and resolving port 9003 contention. Documents Studio-specific behaviors (appdata-v1.json trust over wp-config.php, single-site Xdebug constraint, WASM internal paths). Both skills include agents/ configs (Claude and OpenAI) and references/ with canonical source links. Co-Authored-By: Claude Opus 4.6 --- README.md | 2 + skills/studio-xdebug/SKILL.md | 255 ++++++++++++++++++ skills/studio-xdebug/agents/claude.yaml | 6 + skills/studio-xdebug/agents/openai.yaml | 6 + .../references/canonical-sources.md | 7 + skills/studio/SKILL.md | 229 ++++++++++++++++ skills/studio/agents/claude.yaml | 6 + skills/studio/agents/openai.yaml | 6 + skills/studio/references/canonical-sources.md | 8 + 9 files changed, 525 insertions(+) create mode 100644 skills/studio-xdebug/SKILL.md create mode 100644 skills/studio-xdebug/agents/claude.yaml create mode 100644 skills/studio-xdebug/agents/openai.yaml create mode 100644 skills/studio-xdebug/references/canonical-sources.md create mode 100644 skills/studio/SKILL.md create mode 100644 skills/studio/agents/claude.yaml create mode 100644 skills/studio/agents/openai.yaml create mode 100644 skills/studio/references/canonical-sources.md diff --git a/README.md b/README.md index 13273a7..a0ca1ba 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,8 @@ Agent Skills solve this by giving AI assistants **expert-level WordPress knowled | **wp-performance** | Profiling, caching, database optimization, Server-Timing | | **wp-phpstan** | PHPStan static analysis for WordPress projects (config, baselines, WP-specific typing) | | **wp-playground** | WordPress Playground for instant local environments | +| **studio** | WordPress Studio: site management, WP-CLI, SQLite, Playwright, environment troubleshooting | +| **studio-xdebug** | Xdebug in WordPress Studio: step debugging, stack traces, VS Code configuration | | **wpds** | WordPress Design System | ## Quick Start diff --git a/skills/studio-xdebug/SKILL.md b/skills/studio-xdebug/SKILL.md new file mode 100644 index 0000000..1fc2b75 --- /dev/null +++ b/skills/studio-xdebug/SKILL.md @@ -0,0 +1,255 @@ +--- +name: "studio-xdebug" +description: "Debug WordPress with Xdebug in WordPress Studio. Read error logs, parse stack traces, configure VS Code step debugging, and resolve environmental conflicts (port 9003 contention, stale php.ini Xdebug configs, wrong PHP binary on PATH). Use when debugging PHP in Studio or when Xdebug won't connect to a Studio site." +--- + +# Xdebug in WordPress Studio + +## Credit + +- Original direction: Dan Knauss. +- Drafted and maintained with Claude assistance. +- Preserve this attribution when adapting this skill. + +## Scope + +- Use this skill when debugging PHP errors, tracing execution, or setting up step debugging in WordPress Studio. +- Covers reading Xdebug-enhanced error logs, parsing stack traces, configuring VS Code, and resolving conflicts that prevent Xdebug from working. +- For non-debugging Studio issues (site creation, routing, ports, WP-CLI), prefer `studio`. +- For environments running multiple dev tools side by side, see `local-studio-env` and `xdebug-local-studio`. +- For WP-CLI operations, prefer `wp-wpcli-and-ops`. + +## Execution Boundary + +- Primary responsibility: read and interpret Xdebug output to diagnose issues. +- Claude Code cannot connect as a DAP/DBGp step debugger. It can read log files, curl pages for Xdebug HTML output, and configure IDE debug settings. +- Do not install or uninstall Xdebug extensions. Activation is managed through the Studio app UI. + +## Studio Xdebug Reference + +| Property | Value | +|---|---| +| PHP runtime | WASM (WordPress Playground), not native | +| Xdebug activation | Studio app UI toggle (`enableXdebug` in appdata) | +| Xdebug mode | `debug,develop` when enabled | +| Xdebug port | 9003 | +| WP_DEBUG control | Studio app UI toggles (`enableDebugLog`, `enableDebugDisplay`); overrides wp-config.php at runtime | +| Debug log path | `~/Studio//wp-content/debug.log` | +| Internal document root | `/wordpress/` (WASM filesystem) | +| Site port | Site-specific — check `lsof -iTCP -sTCP:LISTEN -n -P \| grep node` | +| Constraint | Only one Studio site can have Xdebug enabled at a time | +| Appdata location | `~/Library/Application Support/Studio/appdata-v1.json` | + +**Key behavior:** Studio's wp-config.php may say `define('WP_DEBUG', false)` even when debugging is active. Studio injects debug constants at the WASM PHP bootstrap level. Trust the appdata, not wp-config.php. + +## Pre-Flight: Verify Xdebug Is Actually Working + +Before any debugging session, confirm the full chain is healthy. + +### 1. Confirm Xdebug is loaded in Studio's PHP + +Install a temporary mu-plugin: + +```php + 'GET', + 'callback' => function() { + return [ + 'xdebug_loaded' => extension_loaded('xdebug'), + 'xdebug_version' => phpversion('xdebug') ?: 'not loaded', + 'xdebug_mode' => ini_get('xdebug.mode') ?: 'not set', + 'xdebug_port' => ini_get('xdebug.client_port') ?: '9003', + 'php_version' => PHP_VERSION, + 'wp_debug' => defined('WP_DEBUG') && WP_DEBUG, + 'wp_debug_log' => defined('WP_DEBUG_LOG') && WP_DEBUG_LOG, + ]; + }, + 'permission_callback' => '__return_true', + ]); +}); +``` + +```bash +curl -s "http://localhost:/wp-json/debug/v1/xdebug-check" | python3 -m json.tool +``` + +**Always delete the mu-plugin after checking.** + +### 2. Confirm port 9003 is clear + +```bash +lsof -i :9003 +``` + +If anything other than your IDE is listening on 9003, Xdebug connections will fail silently. Common occupants: + +- **Another PHP process** with Xdebug enabled — a different dev environment's PHP may have grabbed the port. Stop it: + ```bash + kill $(lsof -t -i :9003) + ``` +- **A stale debug listener** from a previous IDE session. + +### 3. Confirm no rogue PHP processes interfere + +Other tools may leave PHP processes running with their own Xdebug configuration, competing for port 9003: + +```bash +# Find all PHP processes and their Xdebug state +ps aux | grep -i php | grep -v grep +``` + +If non-Studio PHP processes are running with Xdebug enabled, they will intercept debug connections intended for Studio. Stop them before starting a Studio debug session. + +### 4. Check for conflicting global Xdebug configuration + +Studio bundles its own PHP. But if another tool installed PHP system-wide (via Homebrew, MAMP, or a dev environment app), that installation may have written Xdebug settings to a global `php.ini` or a file in a `conf.d/` scan directory. + +```bash +# Check what ini files the system PHP loads (this is NOT Studio's PHP) +php --ini 2>/dev/null + +# Check common locations for Xdebug configs that could leak +ls /usr/local/etc/php/*/conf.d/*xdebug* 2>/dev/null +ls /opt/homebrew/etc/php/*/conf.d/*xdebug* 2>/dev/null +ls /etc/php/*/conf.d/*xdebug* 2>/dev/null +``` + +These configs don't directly affect Studio's WASM PHP, but they affect any `php` command run from your terminal. If you're using CLI tools that shell out to `php` (e.g., PHPStan, Composer, PHPCS), the system PHP's Xdebug will slow them down and may grab port 9003. + +**Fix:** Disable Xdebug in the system PHP when you're not actively using it: + +```bash +# Temporarily disable system Xdebug without deleting the config +# (rename the ini file so it's not loaded) +sudo mv /usr/local/etc/php/8.3/conf.d/20-xdebug.ini \ + /usr/local/etc/php/8.3/conf.d/20-xdebug.ini.disabled +``` + +## Reading Error Output + +### From debug.log + +```bash +tail -50 ~/Studio//wp-content/debug.log +``` + +When Xdebug `develop` mode is active, log entries include full stack traces with argument values. + +### From HTTP responses + +When `xdebug.mode` includes `develop` and an error occurs, the HTTP response body contains Xdebug's formatted HTML stack trace: + +```bash +curl -s "http://localhost:/wp-admin/some-page" \ + | grep -A 50 "xdebug-error" +``` + +The HTML tables contain error type, message, file, line number, full call stack with frame numbers, timing, memory usage, function names, and argument values. + +### Trigger a specific code path + +```bash +curl -s -X POST "http://localhost:/wp-admin/plugins.php" \ + -d "action=activate&plugin=your-plugin/your-plugin.php&_wpnonce=" \ + -b "" +``` + +Then check `debug.log` for the trace. + +## VS Code Step Debugging + +### Prerequisites + +1. Install `xdebug.php-debug` VS Code extension. +2. Enable Xdebug in Studio app UI for the target site. +3. Confirm port 9003 is clear (pre-flight step 2 above). + +### launch.json + +Create `.vscode/launch.json` in your project root (add to `.gitignore`): + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Studio: ", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/wordpress/wp-content/plugins/": "${workspaceFolder}" + }, + "hostname": "127.0.0.1", + "log": true, + "xdebugSettings": { + "max_children": 128, + "max_data": 1024, + "max_depth": 5 + } + } + ] +} +``` + +**Critical path mapping rule:** Studio's PHP sees `/wordpress/` as its document root (WASM internal path), not the host filesystem path. The left side of `pathMappings` must use `/wordpress/...`, not `~/Library/Application Support/...`. + +For symlinked plugins, the right side (`${workspaceFolder}`) should point to your repo — VS Code resolves the symlink automatically. + +### Debugging procedure + +1. Start the debug configuration in VS Code (F5). +2. Set breakpoints in your plugin source files. +3. Trigger the code path in the browser. +4. VS Code pauses at breakpoints. Inspect variables, step through code, evaluate expressions. +5. When done, disable Xdebug in Studio UI — it impacts site performance. + +## Troubleshooting + +| Symptom | Check | +|---|---| +| No Xdebug output at all | Is Xdebug enabled in Studio UI? Run the mu-plugin check. | +| Loaded but no stack traces | Is `xdebug.mode` set to `develop` or `debug,develop`? | +| Stack traces in browser but not in log | Is `WP_DEBUG_LOG` enabled in Studio UI? (Check appdata, not wp-config.php.) | +| Step debugger won't connect | Is VS Code listening on 9003? Is port 9003 clear of other processes? | +| Breakpoints set but never hit | Path mapping wrong — must use `/wordpress/...` on the left side, not host paths. | +| Step debugger connects to wrong site | Only one Studio site can have Xdebug active. Disable it on other sites. | +| Port 9003 already in use | Another PHP process grabbed it — `lsof -i :9003`, kill it, retry. | +| CLI tools (PHPStan, Composer) slow | System PHP has Xdebug enabled — disable it in the system `php.ini` or `conf.d/`. | +| Studio site returning 503 | Studio's node server not running — restart the site in Studio app. | +| wp-config.php says WP_DEBUG false but errors appear | Normal — Studio overrides at WASM bootstrap. Trust appdata. | + +## Claude Code Integration + +**Can do:** +1. Read enhanced stack traces from log files — full call chains with argument values. +2. Read `wp-content/debug.log` for WP_DEBUG_LOG output. +3. Curl pages and parse Xdebug HTML from error responses. +4. Install temporary diagnostic mu-plugins. Always clean up after. +5. Configure `.vscode/launch.json` for step debugging. +6. Diagnose port conflicts and identify rogue processes. + +**Cannot do:** +1. Connect as a step debugger (no DAP/DBGp client). +2. Set breakpoints or inspect variables at runtime. +3. Toggle Xdebug on/off (managed through Studio UI). + +## Cleanup Rules + +- **Always delete temporary mu-plugins** after diagnostic checks. +- **Never leave debug REST endpoints deployed** beyond the current session. +- **Do not modify Studio's `appdata-v1.json`** directly — use the Studio app UI. +- **Disable Xdebug in Studio UI** when not actively debugging. + +## Done Criteria + +- Xdebug status verified (loaded, correct mode, port 9003 clear). +- Error output successfully read from at least one channel (log file or HTTP response). +- No competing processes on port 9003. +- No system-level Xdebug configs interfering with Studio or CLI tools. +- Temporary diagnostic files cleaned up. +- Root cause identified or narrowed with evidence from stack traces. +- If step debugging attempted: VS Code connection status confirmed with correct `/wordpress/` path mappings. diff --git a/skills/studio-xdebug/agents/claude.yaml b/skills/studio-xdebug/agents/claude.yaml new file mode 100644 index 0000000..691c5b2 --- /dev/null +++ b/skills/studio-xdebug/agents/claude.yaml @@ -0,0 +1,6 @@ +# Claude Code agent configuration for studio-xdebug +# Load SKILL.md as system context when this skill is active. +agent: + name: "studio-xdebug" + instructions: "./SKILL.md" + model: "claude-sonnet-4-6" diff --git a/skills/studio-xdebug/agents/openai.yaml b/skills/studio-xdebug/agents/openai.yaml new file mode 100644 index 0000000..05a3cd4 --- /dev/null +++ b/skills/studio-xdebug/agents/openai.yaml @@ -0,0 +1,6 @@ +# OpenAI Codex agent configuration for studio-xdebug +# Load SKILL.md as system context when this skill is active. +agent: + name: "studio-xdebug" + instructions: "./SKILL.md" + model: "o3" diff --git a/skills/studio-xdebug/references/canonical-sources.md b/skills/studio-xdebug/references/canonical-sources.md new file mode 100644 index 0000000..da412db --- /dev/null +++ b/skills/studio-xdebug/references/canonical-sources.md @@ -0,0 +1,7 @@ +# Canonical Sources — studio-xdebug + +- WordPress Studio Xdebug docs: https://developer.wordpress.com/docs/developer-tools/studio/xdebug/ +- Xdebug documentation: https://xdebug.org/docs/ +- Xdebug step debugging: https://xdebug.org/docs/step_debug +- VS Code PHP Debug extension: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug +- WordPress Debugging guide: https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/ diff --git a/skills/studio/SKILL.md b/skills/studio/SKILL.md new file mode 100644 index 0000000..0fd2ee0 --- /dev/null +++ b/skills/studio/SKILL.md @@ -0,0 +1,229 @@ +--- +name: "studio" +description: "WordPress Studio development environment: site creation, WP-CLI, plugin/theme development, SQLite databases, Playwright E2E testing, Xdebug, and resolving environmental conflicts (port collisions, stale DNS, conflicting PHP/WP-CLI configs). Use when working in WordPress Studio or troubleshooting Studio site issues." +--- + +# WordPress Studio + +## Scope + +- Use this skill when developing in WordPress Studio (Automattic). +- Covers site creation, WP-CLI access, plugin/theme development, database access, E2E testing, and debugging. +- Includes defensive checks for environmental conflicts caused by other tools occupying ports, writing `/etc/hosts` entries, or installing global PHP/WP-CLI configs. +- For WP-CLI command reference, combine with `wp-wpcli-and-ops`. +- For Playground-based workflows, defer to `wp-playground`. +- For environments that also run Local by Flywheel, see `local-studio-env` for cross-environment workflows. + +## Site Management + +- Studio manages sites in `~/Library/Application Support/com.wordpress.studio/` (macOS). +- Each site gets its own PHP runtime and SQLite database by default. +- Sites are accessible at `http://localhost:` — Studio assigns ports automatically (typically 8881+). +- Custom `.test` domains are not used by default; Studio relies on `localhost` with port isolation. + +### Creating Sites + +Use the Studio app GUI or: + +```bash +# List existing Studio sites +ls ~/Library/Application\ Support/com.wordpress.studio/ +``` + +Each site directory contains a full WordPress installation with `wp-content/`, `wp-config.php`, and Studio's bundled PHP. + +## WP-CLI Access + +Studio bundles its own PHP and WP-CLI. Do not rely on a system or globally-installed WP-CLI. + +```bash +# Use Studio's bundled WP-CLI +/Applications/WordPress\ Studio.app/Contents/Resources/wp-cli.phar \ + --path=/path/to/studio-site + +# Or use Studio's built-in terminal (preferred — automatically sets the right PHP and path) +``` + +### Conflict: Wrong PHP version or WP-CLI config + +If `wp` commands return unexpected PHP versions or connect to wrong databases: + +1. Check for a global WP-CLI config overriding Studio's settings: + ```bash + cat ~/.wp-cli/config.yml 2>/dev/null + ``` + If this file exists and sets `path:` or `php:`, it will shadow Studio's bundled PHP. Either remove conflicting entries or use `--path=` and Studio's explicit binary to override. + +2. Check which PHP binary is being used: + ```bash + which php + php -v + ``` + If this isn't Studio's PHP, another tool installed a global PHP that takes precedence on `$PATH`. + +## Plugin and Theme Development + +Symlink your development plugin or theme into the Studio site: + +```bash +ln -s /path/to/your-plugin \ + ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/plugins/your-plugin +``` + +Changes in your repo appear immediately in the site — no copy step needed. + +### Verifying the Symlink + +```bash +# Confirm it resolved correctly +ls -la ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/plugins/your-plugin + +# Activate via WP-CLI +/Applications/WordPress\ Studio.app/Contents/Resources/wp-cli.phar \ + --path=~/Library/Application\ Support/com.wordpress.studio/site-name \ + plugin activate your-plugin +``` + +## Database Access + +Studio uses SQLite by default. The database file is at: + +``` +~/Library/Application Support/com.wordpress.studio/site-name/wp-content/database/.ht.sqlite +``` + +To inspect: + +```bash +sqlite3 ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/database/.ht.sqlite +``` + +```sql +-- List tables +.tables + +-- Check options +SELECT option_name, option_value FROM wp_options WHERE option_name IN ('siteurl', 'home', 'blogname'); +``` + +### Conflict: MySQL processes blocking port 3306 + +If another tool left a MySQL process running on port 3306, Studio's SQLite won't be affected directly. But plugins that hardcode MySQL assumptions may fail. Check: + +```bash +lsof -i :3306 +``` + +If a rogue MySQL process is running, stop it: + +```bash +# Find and stop the process +kill $(lsof -t -i :3306) +``` + +## Port Conflicts + +Studio assigns `localhost` ports automatically. When a port is already occupied: + +### Diagnosis + +```bash +# Check what's using common ports +lsof -i :80 +lsof -i :443 +lsof -i :8881 +lsof -i :8882 +``` + +### Common Conflict Sources + +- **Web servers** (nginx, Apache, Caddy) installed by other tools or Homebrew +- **DNS routing daemons** that write `/etc/hosts` entries claiming `.local` or `.test` domains +- **Container runtimes** (Docker Desktop) binding to low ports +- **Other dev environment tools** whose background processes persist after the app is closed — check Activity Monitor or: + ```bash + # Find persistent background processes on common dev ports + for port in 80 443 3306 8080 8443 8881 8882; do + pid=$(lsof -t -i :$port 2>/dev/null) + if [ -n "$pid" ]; then + echo "Port $port: PID $pid — $(ps -p $pid -o comm= 2>/dev/null)" + fi + done + ``` + +### Resolution + +1. Stop the conflicting process, or +2. Restart Studio — it will find the next available port, or +3. If a tool wrote `/etc/hosts` entries that interfere with `localhost` resolution: + ```bash + grep -v "^#" /etc/hosts | grep -i "localhost\|\.local\|\.test" + ``` + Remove stale entries that another tool left behind (requires `sudo`). + +## E2E Testing with Playwright + +```typescript +// playwright.config.ts +import { defineConfig } from '@playwright/test'; + +export default defineConfig({ + use: { + baseURL: 'http://localhost:8881', // Match your Studio site's port + }, + webServer: { + // Studio manages the server — no command needed + // Just ensure the site is running in Studio before tests + url: 'http://localhost:8881', + reuseExistingServer: true, + }, +}); +``` + +### Pre-flight Check + +Before running tests, verify Studio is serving: + +```bash +curl -sI http://localhost:8881 | head -5 +``` + +If this fails, open Studio and start the site. + +### wp-env Alternative for CI + +For CI-reproducible environments where Studio isn't available: + +```bash +npx wp-env start +npx playwright test +npx wp-env stop +``` + +`wp-env` uses Docker and provides consistent environments across developers and CI. Studio is for local development; `wp-env` is for reproducibility. + +## Xdebug + +For Xdebug setup, step debugging, stack trace reading, and resolving port 9003 conflicts, use the **`studio-xdebug`** skill. It covers Studio's WASM PHP specifics, VS Code launch.json configuration, and conflict resolution for competing Xdebug configs. + +## Troubleshooting Checklist + +When a Studio site isn't working: + +1. **Site not loading** — Is Studio running? Is the site started? Check `curl -sI http://localhost:`. +2. **Wrong content** — Verify you're hitting the right port. Check `wp option get siteurl`. +3. **Plugin not appearing** — Verify symlink resolves: `ls -la wp-content/plugins/your-plugin`. +4. **WP-CLI wrong output** — Check for global `~/.wp-cli/config.yml` conflicts. Use Studio's bundled WP-CLI explicitly. +5. **Port occupied** — Run the port scan from the Port Conflicts section above. +6. **DNS oddity** — Check `/etc/hosts` for stale entries from other tools. +7. **Xdebug not connecting** — Use `studio-xdebug` skill for diagnosis. + +## Done Criteria + +- Studio site accessible at `http://localhost:` and serving correct content. +- Plugin/theme symlinked and activated without errors. +- WP-CLI commands work using Studio's bundled binary. +- SQLite database accessible and queryable. +- No port conflicts with other services. +- E2E tests run against the Studio site with correct baseURL. +- No stale `/etc/hosts` entries or global configs interfering with Studio's operation. diff --git a/skills/studio/agents/claude.yaml b/skills/studio/agents/claude.yaml new file mode 100644 index 0000000..ff863d3 --- /dev/null +++ b/skills/studio/agents/claude.yaml @@ -0,0 +1,6 @@ +# Claude Code agent configuration for studio +# Load SKILL.md as system context when this skill is active. +agent: + name: "studio" + instructions: "./SKILL.md" + model: "claude-sonnet-4-6" diff --git a/skills/studio/agents/openai.yaml b/skills/studio/agents/openai.yaml new file mode 100644 index 0000000..89a1abc --- /dev/null +++ b/skills/studio/agents/openai.yaml @@ -0,0 +1,6 @@ +# OpenAI Codex agent configuration for studio +# Load SKILL.md as system context when this skill is active. +agent: + name: "studio" + instructions: "./SKILL.md" + model: "o3" diff --git a/skills/studio/references/canonical-sources.md b/skills/studio/references/canonical-sources.md new file mode 100644 index 0000000..9cecc26 --- /dev/null +++ b/skills/studio/references/canonical-sources.md @@ -0,0 +1,8 @@ +# Canonical Sources — studio + +- WordPress Studio: https://developer.wordpress.com/studio/ +- Studio GitHub repo: https://github.com/Automattic/studio +- WP-CLI handbook: https://make.wordpress.org/cli/handbook/ +- WordPress Playground: https://developer.wordpress.org/playground/ +- Playwright docs: https://playwright.dev/docs/intro +- SQLite Database Integration plugin: https://wordpress.org/plugins/sqlite-database-integration/ From 0bfce33a4e808956e6394f7373bb3f1c44319e52 Mon Sep 17 00:00:00 2001 From: Dan Knauss Date: Fri, 20 Mar 2026 17:55:40 -0600 Subject: [PATCH 2/3] Add missing compatibility frontmatter to pass eval harness The CI runner (eval/harness/run.mjs) requires a 'compatibility' field in each SKILL.md frontmatter. Both studio and studio-xdebug were missing it. Co-Authored-By: Claude Opus 4.6 --- skills/studio-xdebug/SKILL.md | 1 + skills/studio/SKILL.md | 1 + 2 files changed, 2 insertions(+) diff --git a/skills/studio-xdebug/SKILL.md b/skills/studio-xdebug/SKILL.md index 1fc2b75..aa4834a 100644 --- a/skills/studio-xdebug/SKILL.md +++ b/skills/studio-xdebug/SKILL.md @@ -1,6 +1,7 @@ --- name: "studio-xdebug" description: "Debug WordPress with Xdebug in WordPress Studio. Read error logs, parse stack traces, configure VS Code step debugging, and resolve environmental conflicts (port 9003 contention, stale php.ini Xdebug configs, wrong PHP binary on PATH). Use when debugging PHP in Studio or when Xdebug won't connect to a Studio site." +compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WordPress Studio on macOS with Xdebug enabled via Studio UI. VS Code with PHP Debug extension for step debugging." --- # Xdebug in WordPress Studio diff --git a/skills/studio/SKILL.md b/skills/studio/SKILL.md index 0fd2ee0..373dcd7 100644 --- a/skills/studio/SKILL.md +++ b/skills/studio/SKILL.md @@ -1,6 +1,7 @@ --- name: "studio" description: "WordPress Studio development environment: site creation, WP-CLI, plugin/theme development, SQLite databases, Playwright E2E testing, Xdebug, and resolving environmental conflicts (port collisions, stale DNS, conflicting PHP/WP-CLI configs). Use when working in WordPress Studio or troubleshooting Studio site issues." +compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WordPress Studio on macOS. Some workflows require WP-CLI (bundled with Studio)." --- # WordPress Studio From 6c7fab227a6f31207b95bb912631b52ea5d98585 Mon Sep 17 00:00:00 2001 From: Dan Knauss Date: Fri, 20 Mar 2026 19:06:30 -0600 Subject: [PATCH 3/3] Update studio skill with operational findings from real deployment Corrections and additions based on actual Studio + Local coexistence testing: - Fix site path: ~/Studio//, not ~/Library/Application Support/ - Document appdata-v1.json as authoritative config: customDomain and enableHttps override wp-config.php and database at WASM bootstrap - Document that appdata changes require full Studio quit/reopen - Document custom domain conflicts with other web servers on ports 80/443 - Expand troubleshooting checklist with HTTPS redirect loop, custom domain routing, and appdata-specific debugging steps - Remove redundant Xdebug section (defers to studio-xdebug skill) Co-Authored-By: Claude Opus 4.6 --- skills/studio/SKILL.md | 71 ++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 17 deletions(-) diff --git a/skills/studio/SKILL.md b/skills/studio/SKILL.md index 373dcd7..2bb1d96 100644 --- a/skills/studio/SKILL.md +++ b/skills/studio/SKILL.md @@ -17,22 +17,55 @@ compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WordPress Studio ## Site Management -- Studio manages sites in `~/Library/Application Support/com.wordpress.studio/` (macOS). -- Each site gets its own PHP runtime and SQLite database by default. +- Studio stores sites in `~/Studio//` (macOS). +- Configuration lives in `~/Library/Application Support/Studio/appdata-v1.json`. +- Each site gets its own PHP runtime (WASM) and SQLite database by default. - Sites are accessible at `http://localhost:` — Studio assigns ports automatically (typically 8881+). -- Custom `.test` domains are not used by default; Studio relies on `localhost` with port isolation. ### Creating Sites -Use the Studio app GUI or: +Use the Studio app GUI. Site directories are at: ```bash -# List existing Studio sites -ls ~/Library/Application\ Support/com.wordpress.studio/ +ls ~/Studio/ ``` Each site directory contains a full WordPress installation with `wp-content/`, `wp-config.php`, and Studio's bundled PHP. +### appdata-v1.json Is the Source of Truth + +Studio's `appdata-v1.json` controls runtime behavior and **overrides both wp-config.php and the database** at the WASM PHP bootstrap level. Key fields per site: + +| Field | Effect | +|---|---| +| `port` | Which localhost port the Express server listens on | +| `customDomain` | Overrides `siteurl`/`home` at bootstrap — database values are ignored when set | +| `enableHttps` | Forces HTTPS redirects at the WASM level — wp-config.php `FORCE_SSL_ADMIN` is irrelevant | +| `enableDebugLog` | Overrides `WP_DEBUG_LOG` — wp-config.php value is ignored | +| `enableDebugDisplay` | Overrides `WP_DEBUG_DISPLAY` | +| `enableXdebug` | Toggles Xdebug in the WASM PHP runtime | + +**Critical:** When troubleshooting URL redirects or debug settings, check appdata first — not wp-config.php, not the database. Studio injects these constants before WordPress loads. + +To edit: + +```bash +# Read current config +cat ~/Library/Application\ Support/Studio/appdata-v1.json | python3 -m json.tool +``` + +**After editing appdata-v1.json, you must fully quit and reopen WordPress Studio.** A site stop/start within the app is not sufficient — the Express server reads appdata at app launch. + +### Custom Domains + +Studio supports custom domains via the `customDomain` field in appdata. However: + +- **Custom domains require a `/etc/hosts` entry** pointing the domain to `127.0.0.1`. +- **If another tool's web server (nginx, Apache) is listening on ports 80/443**, the hosts entry will route traffic to that server instead of Studio. Studio's Express server runs on high ports (8881+), not 80/443. +- **`enableHttps: true` with a custom domain will fail** if Studio doesn't control ports 443. The WASM PHP forces HTTPS redirects, but there's no HTTPS listener on Studio's port. +- **To use a custom domain with SSL, stop any other web server on 80/443 first.** Otherwise, use `http://localhost:` without a custom domain. +- **To clear a custom domain:** set `"customDomain": ""` in appdata and restart Studio. You must also update the database `siteurl`/`home` to `http://localhost:` since Studio no longer overrides them when `customDomain` is empty. + ## WP-CLI Access Studio bundles its own PHP and WP-CLI. Do not rely on a system or globally-installed WP-CLI. @@ -68,7 +101,7 @@ Symlink your development plugin or theme into the Studio site: ```bash ln -s /path/to/your-plugin \ - ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/plugins/your-plugin + ~/Studio/site-name/wp-content/plugins/your-plugin ``` Changes in your repo appear immediately in the site — no copy step needed. @@ -77,11 +110,11 @@ Changes in your repo appear immediately in the site — no copy step needed. ```bash # Confirm it resolved correctly -ls -la ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/plugins/your-plugin +ls -la ~/Studio/site-name/wp-content/plugins/your-plugin # Activate via WP-CLI /Applications/WordPress\ Studio.app/Contents/Resources/wp-cli.phar \ - --path=~/Library/Application\ Support/com.wordpress.studio/site-name \ + --path=~/Studio/site-name \ plugin activate your-plugin ``` @@ -90,13 +123,13 @@ ls -la ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/ Studio uses SQLite by default. The database file is at: ``` -~/Library/Application Support/com.wordpress.studio/site-name/wp-content/database/.ht.sqlite +~/Studio/site-name/wp-content/database/.ht.sqlite ``` To inspect: ```bash -sqlite3 ~/Library/Application\ Support/com.wordpress.studio/site-name/wp-content/database/.ht.sqlite +sqlite3 ~/Studio/site-name/wp-content/database/.ht.sqlite ``` ```sql @@ -212,12 +245,16 @@ For Xdebug setup, step debugging, stack trace reading, and resolving port 9003 c When a Studio site isn't working: 1. **Site not loading** — Is Studio running? Is the site started? Check `curl -sI http://localhost:`. -2. **Wrong content** — Verify you're hitting the right port. Check `wp option get siteurl`. -3. **Plugin not appearing** — Verify symlink resolves: `ls -la wp-content/plugins/your-plugin`. -4. **WP-CLI wrong output** — Check for global `~/.wp-cli/config.yml` conflicts. Use Studio's bundled WP-CLI explicitly. -5. **Port occupied** — Run the port scan from the Port Conflicts section above. -6. **DNS oddity** — Check `/etc/hosts` for stale entries from other tools. -7. **Xdebug not connecting** — Use `studio-xdebug` skill for diagnosis. +2. **HTTPS redirect loop** — Check `enableHttps` and `customDomain` in appdata-v1.json. If `enableHttps: true` but nothing serves HTTPS on the custom domain, you get an infinite redirect. Fix: set `enableHttps: false` or clear `customDomain`, then fully restart Studio. +3. **Custom domain goes to wrong server** — Another tool's web server on ports 80/443 is intercepting the domain. Either stop that server or clear `customDomain` and use `localhost:`. +4. **Database URL changes have no effect** — Studio's `customDomain` overrides `siteurl`/`home` at the WASM bootstrap. Clear `customDomain` in appdata first, then update the database. +5. **appdata changes have no effect** — You must fully quit and reopen Studio. A site stop/start is not enough. +6. **Wrong content** — Verify you're hitting the right port. Check `wp option get siteurl`. +7. **Plugin not appearing** — Verify symlink resolves: `ls -la wp-content/plugins/your-plugin`. +8. **WP-CLI wrong output** — Check for global `~/.wp-cli/config.yml` conflicts. Use Studio's bundled WP-CLI explicitly. +9. **Port occupied** — Run the port scan from the Port Conflicts section above. +10. **DNS oddity** — Check `/etc/hosts` for stale entries from other tools. +11. **Xdebug not connecting** — Use `studio-xdebug` skill for diagnosis. ## Done Criteria