claude-plugin-wordpress-manager 1.4.0 → 1.7.0

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

@@ -0,0 +1,121 @@
+# wp-env Adapter
+
+## Prerequisites
+
+- **Docker** installed and running (`docker info`)
+- **Node.js** 18+ and npm
+- `.wp-env.json` in the project root
+
+## Installation
+
+```bash
+npm -g install @wordpress/env
+# or use npx (no install):
+npx @wordpress/env start
+```
+
+## Configuration (.wp-env.json)
+
+Minimal:
+```json
+{
+  "core": null,
+  "plugins": ["./my-plugin"],
+  "themes": ["./my-theme"]
+}
+```
+
+Full example:
+```json
+{
+  "core": "WordPress/WordPress#6.9",
+  "phpVersion": "8.2",
+  "plugins": [
+    "./my-plugin",
+    "https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip"
+  ],
+  "themes": ["./my-theme"],
+  "port": 8888,
+  "testsPort": 8889,
+  "config": {
+    "WP_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "SCRIPT_DEBUG": true
+  },
+  "mappings": {
+    "wp-content/mu-plugins": "./mu-plugins"
+  }
+}
+```
+
+Override per-developer settings in `.wp-env.override.json` (gitignored).
+
+## Commands
+
+```bash
+# Start development and test environments
+npx wp-env start
+npx wp-env start --update   # Also pull latest images
+
+# Stop environments
+npx wp-env stop
+
+# Destroy (remove containers and data)
+npx wp-env destroy
+
+# Run WP-CLI commands
+npx wp-env run cli wp <command>
+npx wp-env run cli wp plugin list
+npx wp-env run cli wp scaffold block my-block --plugin=my-plugin
+npx wp-env run cli wp db export /tmp/backup.sql
+
+# Run arbitrary commands in containers
+npx wp-env run cli bash
+npx wp-env run tests-cli wp test
+```
+
+## Ports
+
+| Environment | Default port |
+|-------------|-------------|
+| Development | `http://localhost:8888` |
+| Tests | `http://localhost:8889` |
+
+Configurable via `port` and `testsPort` in `.wp-env.json`.
+
+## Default credentials
+
+- **User**: `admin`
+- **Password**: `password`
+- **Database**: Inside Docker container (not directly accessible from host)
+
+## REST API
+
+```bash
+curl http://localhost:8888/wp-json/wp/v2/posts
+curl -u "admin:password" http://localhost:8888/wp-json/wp/v2/posts
+```
+
+## When to use wp-env
+
+- **WordPress core contribution** — standard for Gutenberg development
+- **CI/CD pipelines** — Docker-based, reproducible
+- **Plugin/theme testing** — isolated, disposable
+- **PHPUnit tests** — `npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit`
+
+## When NOT to use wp-env
+
+- Quick theme previews → use WordPress Studio instead
+- Production-parity with specific hosting → use LocalWP
+- No Docker available → use WordPress Studio (WASM-based)
+
+## Comparison with Studio and LocalWP
+
+| Feature | wp-env | Studio | LocalWP |
+|---------|--------|--------|---------|
+| Requires Docker | Yes | No | No |
+| Config as code | `.wp-env.json` | CLI flags | GUI |
+| CI/CD friendly | Excellent | Limited | No |
+| Setup speed | Medium (Docker pull) | Fast (WASM) | Slow (native) |
+| Multiple sites | 2 (dev + test) | Unlimited | Unlimited |
+| Multisite | Yes | No | Yes |

package/skills/wp-local-env/scripts/detect_local_env.mjs

@@ -0,0 +1,404 @@
+/**
+ * detect_local_env.mjs — Detect local WordPress development environments.
+ *
+ * Scans for WordPress Studio, LocalWP, and wp-env installations.
+ * Outputs a JSON report to stdout with discovered environments, sites,
+ * recommended tool, and WP-CLI invocation paths.
+ *
+ * Usage:
+ *   node detect_local_env.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — at least one environment found
+ *   1 — no environments found
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execSync } from "node:child_process";
+import os from "node:os";
+
+const TOOL_VERSION = "1.0.0";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function readFileSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJsonSafe(p) {
+  const raw = readFileSafe(p);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function execSafe(cmd, timeoutMs = 5000) {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout: timeoutMs, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function whichSafe(bin) {
+  const cmd = process.platform === "win32" ? `where ${bin}` : `command -v ${bin}`;
+  return execSafe(cmd);
+}
+
+// ---------------------------------------------------------------------------
+// Platform paths
+// ---------------------------------------------------------------------------
+
+function getPlatformPaths() {
+  const home = os.homedir();
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    return {
+      studio: {
+        sites: path.join(home, "Studio"),
+        config: path.join(home, "Library", "Application Support", "WordPressStudio"),
+      },
+      localwp: {
+        sites: path.join(home, "Local Sites"),
+        config: path.join(home, "Library", "Application Support", "Local"),
+        json: path.join(home, "Library", "Application Support", "Local", "sites.json"),
+        lightning: path.join(home, "Library", "Application Support", "Local", "lightning-services"),
+        run: path.join(home, "Library", "Application Support", "Local", "run"),
+      },
+    };
+  }
+
+  if (platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+    return {
+      studio: {
+        sites: path.join(home, "Studio"),
+        config: path.join(localAppData, "WordPressStudio"),
+      },
+      localwp: {
+        sites: path.join(home, "Local Sites"),
+        config: path.join(appData, "Local"),
+        json: path.join(appData, "Local", "sites.json"),
+        lightning: path.join(appData, "Local", "lightning-services"),
+        run: path.join(appData, "Local", "run"),
+      },
+    };
+  }
+
+  // Linux (default)
+  return {
+    studio: {
+      sites: path.join(home, "Studio"),
+      config: path.join(home, ".config", "WordPressStudio"),
+    },
+    localwp: {
+      sites: path.join(home, "Local Sites"),
+      config: path.join(home, ".config", "Local"),
+      json: path.join(home, ".config", "Local", "sites.json"),
+      lightning: path.join(home, ".config", "Local", "lightning-services"),
+      run: path.join(home, ".config", "Local", "run"),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// WordPress Studio detection
+// ---------------------------------------------------------------------------
+
+function detectStudio(paths) {
+  const cli = whichSafe("studio");
+  const sitesDir = paths.studio.sites;
+  const hasSitesDir = statSafe(sitesDir)?.isDirectory();
+
+  if (!cli && !hasSitesDir) return null;
+
+  // Get version from CLI
+  let version = null;
+  if (cli) {
+    const vOut = execSafe("studio --version");
+    if (vOut) version = vOut.replace(/[^0-9.]/g, "") || vOut;
+  }
+
+  // Discover sites
+  const sites = [];
+  if (hasSitesDir) {
+    try {
+      const entries = fs.readdirSync(sitesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const sitePath = path.join(sitesDir, entry.name);
+        const wpConfig = path.join(sitePath, "wp-config.php");
+        if (!statSafe(wpConfig)) continue;
+
+        const site = {
+          name: entry.name,
+          path: sitePath,
+          url: null,
+          status: "unknown",
+          php: null,
+          wp: null,
+          db: "sqlite",
+        };
+
+        // Check if SQLite db exists
+        const sqliteDb = path.join(sitePath, "wp-content", "database", ".ht.sqlite");
+        if (statSafe(sqliteDb)) {
+          site.db = "sqlite";
+        }
+
+        // Try to get site info via CLI
+        if (cli) {
+          const statusOut = execSafe(`studio site status --path="${sitePath}"`);
+          if (statusOut) {
+            const urlMatch = statusOut.match(/URL:\s*(https?:\/\/\S+)/i);
+            if (urlMatch) site.url = urlMatch[1];
+            const phpMatch = statusOut.match(/PHP:\s*(\d+\.\d+)/i);
+            if (phpMatch) site.php = phpMatch[1];
+            const wpMatch = statusOut.match(/WordPress:\s*(\d+\.\d+(?:\.\d+)?)/i);
+            if (wpMatch) site.wp = wpMatch[1];
+            if (/running/i.test(statusOut)) site.status = "running";
+            else if (/stopped/i.test(statusOut)) site.status = "stopped";
+          }
+        }
+
+        sites.push(site);
+      }
+    } catch {
+      // Permission or read error — skip
+    }
+  }
+
+  return {
+    tool: "studio",
+    version,
+    cli: cli || null,
+    sites,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// LocalWP detection
+// ---------------------------------------------------------------------------
+
+function detectLocalWP(paths) {
+  const sitesJson = paths.localwp.json;
+  const sitesData = readJsonSafe(sitesJson);
+  const hasSitesDir = statSafe(paths.localwp.sites)?.isDirectory();
+
+  if (!sitesData && !hasSitesDir) return null;
+
+  // Find wp-cli binary
+  let wpCliBin = null;
+  const lightningDir = paths.localwp.lightning;
+  if (statSafe(lightningDir)?.isDirectory()) {
+    try {
+      const entries = fs.readdirSync(lightningDir);
+      const wcliDir = entries.find((e) => e.startsWith("wp-cli"));
+      if (wcliDir) {
+        const candidate = path.join(lightningDir, wcliDir, "bin", "wp");
+        if (statSafe(candidate)) wpCliBin = candidate;
+      }
+    } catch {
+      // Skip
+    }
+  }
+
+  // Parse sites from sites.json
+  const sites = [];
+  if (sitesData && typeof sitesData === "object") {
+    const siteEntries = Array.isArray(sitesData) ? sitesData : Object.values(sitesData);
+    for (const s of siteEntries) {
+      if (!s || typeof s !== "object") continue;
+
+      const sitePath = s.path
+        ? path.join(s.path, "app", "public")
+        : s.name
+          ? path.join(paths.localwp.sites, s.name, "app", "public")
+          : null;
+
+      const site = {
+        name: s.name || s.domain || "unknown",
+        path: sitePath,
+        url: s.url || (s.domain ? `http://${s.domain}` : null),
+        port: s.services?.nginx?.port || s.services?.apache?.port || null,
+        status: "unknown",
+        php: s.services?.php?.version || null,
+        wp: null,
+        db: "mysql",
+        webServer: s.services?.nginx ? "nginx" : s.services?.apache ? "apache" : null,
+      };
+
+      // Check if site directory exists
+      if (sitePath && statSafe(sitePath)?.isDirectory()) {
+        site.status = "stopped"; // Directory exists but we can't confirm running
+      }
+
+      // Check MySQL socket to determine if running
+      if (s.id && paths.localwp.run) {
+        const socketPath = path.join(paths.localwp.run, s.id, "mysql", "mysqld.sock");
+        if (statSafe(socketPath)) {
+          site.status = "running";
+        }
+      }
+
+      sites.push(site);
+    }
+  }
+
+  // Get LocalWP version
+  let version = null;
+  const pkgJson = readJsonSafe(path.join(paths.localwp.config, "package.json"));
+  if (pkgJson?.version) version = pkgJson.version;
+
+  return {
+    tool: "localwp",
+    version,
+    configPath: sitesJson,
+    wpCliBin,
+    sites,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// wp-env detection
+// ---------------------------------------------------------------------------
+
+function detectWpEnv(cwd) {
+  const wpEnvJson = path.join(cwd, ".wp-env.json");
+  const wpEnvOverride = path.join(cwd, ".wp-env.override.json");
+
+  const config = readJsonSafe(wpEnvJson);
+  if (!config) return null;
+
+  const overrides = readJsonSafe(wpEnvOverride);
+  const merged = overrides ? { ...config, ...overrides } : config;
+
+  const devPort = merged.port || 8888;
+  const testPort = merged.testsPort || 8889;
+
+  return {
+    tool: "wpenv",
+    version: null,
+    configPath: wpEnvJson,
+    sites: [
+      {
+        name: "development",
+        path: cwd,
+        url: `http://localhost:${devPort}`,
+        port: devPort,
+        status: "unknown",
+        php: merged.phpVersion || null,
+        wp: merged.core || null,
+        db: "mysql",
+      },
+      {
+        name: "tests",
+        path: cwd,
+        url: `http://localhost:${testPort}`,
+        port: testPort,
+        status: "unknown",
+        php: merged.phpVersion || null,
+        wp: merged.core || null,
+        db: "mysql",
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Recommendation logic
+// ---------------------------------------------------------------------------
+
+function recommend(environments) {
+  if (environments.length === 0) return null;
+  if (environments.length === 1) return environments[0].tool;
+
+  // Prefer Studio if CLI is available (best automation surface)
+  const studio = environments.find((e) => e.tool === "studio" && e.cli);
+  if (studio) return "studio";
+
+  // Then LocalWP if it has sites
+  const localwp = environments.find((e) => e.tool === "localwp" && e.sites.length > 0);
+  if (localwp) return "localwp";
+
+  // Then wp-env
+  const wpenv = environments.find((e) => e.tool === "wpenv");
+  if (wpenv) return "wpenv";
+
+  return environments[0].tool;
+}
+
+function buildWpCliMap(environments) {
+  const map = {};
+  for (const env of environments) {
+    if (env.tool === "studio" && env.cli) {
+      map.studio = "studio wp --path=<site>";
+    }
+    if (env.tool === "localwp" && env.wpCliBin) {
+      map.localwp = `${env.wpCliBin} --path=<site>`;
+    }
+    if (env.tool === "wpenv") {
+      map.wpenv = "npx wp-env run cli wp";
+    }
+  }
+  return map;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  let cwd = process.cwd();
+  for (const arg of args) {
+    if (arg.startsWith("--cwd=")) cwd = arg.slice(6);
+  }
+
+  const paths = getPlatformPaths();
+  const environments = [];
+
+  const studio = detectStudio(paths);
+  if (studio) environments.push(studio);
+
+  const localwp = detectLocalWP(paths);
+  if (localwp) environments.push(localwp);
+
+  const wpenv = detectWpEnv(cwd);
+  if (wpenv) environments.push(wpenv);
+
+  const report = {
+    version: TOOL_VERSION,
+    timestamp: new Date().toISOString(),
+    platform: process.platform,
+    environments,
+    recommended: recommend(environments),
+    wpCli: buildWpCliMap(environments),
+  };
+
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  process.exit(environments.length > 0 ? 0 : 1);
+}
+
+main();

package/skills/wp-playground/SKILL.md

@@ -99,5 +99,17 @@ npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site
 
 ## Escalation
 
-- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
+- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to a local dev environment.
+- For persistent local development, use the `wp-local-env` skill which supports WordPress Studio (WASM-based, lightweight), LocalWP (native MySQL, production-parity), and wp-env (Docker, CI-friendly).
 - For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/
+
+## Relationship with wp-local-env
+
+| Need | Use |
+|------|-----|
+| Quick disposable test | wp-playground (this skill) |
+| Persistent local dev with DB | `wp-local-env` (Studio/LocalWP/wp-env) |
+| CI/CD testing | wp-playground (blueprints) or wp-env |
+| Plugin/theme development | `wp-local-env` (symlink workflow) |
+| Version switching (ephemeral) | wp-playground (`--wp=` / `--php=`) |
+| Version switching (persistent) | `wp-local-env` (tool-specific settings) |

package/skills/wp-plugin-development/SKILL.md

@@ -112,3 +112,9 @@ See:
 ## Escalation
 
 For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.
+
+## Related skills
+
+- `wp-e2e-testing` — PHPUnit for plugin unit tests, Playwright for E2E, CI integration
+- `wp-i18n` — Text domain setup, translation workflow, WP-CLI i18n commands
+- `wp-security` — Filesystem hardening, wp-config constants, authentication security

package/skills/wp-rest-api/SKILL.md

@@ -114,3 +114,7 @@ Read `references/discovery-and-params.md`.
 ## Escalation
 
 If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.
+
+## Related skills
+
+- `wp-headless` — Decoupled architecture, WPGraphQL, CORS configuration, frontend framework integration, webhooks