claude-plugin-wordpress-manager 1.5.0 → 1.7.1

package/skills/wp-e2e-testing/scripts/test_inspect.mjs

@@ -0,0 +1,375 @@
+/**
+ * test_inspect.mjs — Detect testing frameworks and configuration in a WordPress project.
+ *
+ * Scans for Playwright, Jest, PHPUnit, wp-env, and CI config.
+ * Outputs a JSON report to stdout with detected frameworks,
+ * test directories, configuration files, and CI integration.
+ *
+ * Usage:
+ *   node test_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — at least one test framework detected
+ *   1 — no test frameworks detected
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execSync } from "node:child_process";
+
+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, cwd, timeoutMs = 5000) {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout: timeoutMs, cwd, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function globDirs(base, patterns) {
+  const found = [];
+  for (const pattern of patterns) {
+    const full = path.join(base, pattern);
+    if (statSafe(full)?.isDirectory()) {
+      found.push(pattern);
+    }
+  }
+  return found;
+}
+
+function globFiles(base, patterns) {
+  const found = [];
+  for (const pattern of patterns) {
+    const full = path.join(base, pattern);
+    if (statSafe(full)?.isFile()) {
+      found.push(pattern);
+    }
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Parse --cwd argument
+// ---------------------------------------------------------------------------
+
+function parseCwd() {
+  const cwdArg = process.argv.find((a) => a.startsWith("--cwd="));
+  return cwdArg ? cwdArg.slice(6) : process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// Detect Playwright
+// ---------------------------------------------------------------------------
+
+function detectPlaywright(cwd) {
+  const result = { detected: false, configFile: null, testDirs: [], wpE2eUtils: false };
+
+  const configFiles = [
+    "playwright.config.js",
+    "playwright.config.ts",
+    "playwright.config.mjs",
+  ];
+  const found = globFiles(cwd, configFiles);
+  if (found.length > 0) {
+    result.detected = true;
+    result.configFile = found[0];
+  }
+
+  const testDirs = globDirs(cwd, [
+    "tests/e2e",
+    "tests/playwright",
+    "e2e",
+    "test/e2e",
+    "specs",
+  ]);
+  result.testDirs = testDirs;
+
+  // Check for @wordpress/e2e-test-utils-playwright
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (pkg) {
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps["@wordpress/e2e-test-utils-playwright"]) {
+      result.wpE2eUtils = true;
+      result.detected = true;
+    }
+    if (allDeps["@playwright/test"] || allDeps["playwright"]) {
+      result.detected = true;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect Jest
+// ---------------------------------------------------------------------------
+
+function detectJest(cwd) {
+  const result = { detected: false, configFile: null, testDirs: [], wpScripts: false };
+
+  const configFiles = [
+    "jest.config.js",
+    "jest.config.ts",
+    "jest.config.mjs",
+    "jest.config.json",
+  ];
+  const found = globFiles(cwd, configFiles);
+  if (found.length > 0) {
+    result.detected = true;
+    result.configFile = found[0];
+  }
+
+  // Check package.json for jest config
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (pkg) {
+    if (pkg.jest) {
+      result.detected = true;
+      result.configFile = result.configFile || "package.json (jest key)";
+    }
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps["@wordpress/scripts"]) {
+      result.wpScripts = true;
+      result.detected = true;
+    }
+    if (allDeps["jest"]) {
+      result.detected = true;
+    }
+  }
+
+  const testDirs = globDirs(cwd, [
+    "tests/js",
+    "tests/unit",
+    "tests/jest",
+    "src/__tests__",
+    "__tests__",
+    "test/js",
+  ]);
+  result.testDirs = testDirs;
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect PHPUnit
+// ---------------------------------------------------------------------------
+
+function detectPHPUnit(cwd) {
+  const result = { detected: false, configFile: null, testDirs: [], bootstrap: null };
+
+  const configFiles = [
+    "phpunit.xml",
+    "phpunit.xml.dist",
+    "phpunit.dist.xml",
+  ];
+  const found = globFiles(cwd, configFiles);
+  if (found.length > 0) {
+    result.detected = true;
+    result.configFile = found[0];
+
+    // Parse bootstrap path from XML
+    const content = readFileSafe(path.join(cwd, found[0]));
+    if (content) {
+      const match = content.match(/bootstrap="([^"]+)"/);
+      if (match) result.bootstrap = match[1];
+    }
+  }
+
+  const testDirs = globDirs(cwd, [
+    "tests/phpunit",
+    "tests/php",
+    "tests/unit",
+    "tests",
+  ]);
+  result.testDirs = testDirs;
+
+  // Check composer.json
+  const composer = readJsonSafe(path.join(cwd, "composer.json"));
+  if (composer) {
+    const allDeps = { ...composer.require, ...composer["require-dev"] };
+    if (allDeps["phpunit/phpunit"] || allDeps["yoast/phpunit-polyfills"]) {
+      result.detected = true;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect wp-env
+// ---------------------------------------------------------------------------
+
+function detectWpEnv(cwd) {
+  const result = { detected: false, configFile: null, running: false };
+
+  if (statSafe(path.join(cwd, ".wp-env.json"))?.isFile()) {
+    result.detected = true;
+    result.configFile = ".wp-env.json";
+  }
+
+  if (statSafe(path.join(cwd, ".wp-env.override.json"))?.isFile()) {
+    result.detected = true;
+  }
+
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (pkg) {
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps["@wordpress/env"]) {
+      result.detected = true;
+    }
+  }
+
+  // Check if wp-env is running (Docker containers)
+  const dockerCheck = execSafe("docker ps --filter name=wp-env --format '{{.Names}}'", cwd);
+  if (dockerCheck && dockerCheck.length > 0) {
+    result.running = true;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect CI configuration
+// ---------------------------------------------------------------------------
+
+function detectCI(cwd) {
+  const result = { detected: false, provider: null, hasTestStep: false };
+
+  // GitHub Actions
+  const ghDirs = globDirs(cwd, [".github/workflows"]);
+  if (ghDirs.length > 0) {
+    const workflowDir = path.join(cwd, ".github", "workflows");
+    try {
+      const files = fs.readdirSync(workflowDir);
+      for (const file of files) {
+        if (file.endsWith(".yml") || file.endsWith(".yaml")) {
+          result.detected = true;
+          result.provider = "github-actions";
+          const content = readFileSafe(path.join(workflowDir, file));
+          if (content && /phpunit|jest|playwright|wp-env|npm test|npm run test/i.test(content)) {
+            result.hasTestStep = true;
+          }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // GitLab CI
+  if (statSafe(path.join(cwd, ".gitlab-ci.yml"))?.isFile()) {
+    result.detected = true;
+    result.provider = result.provider || "gitlab-ci";
+    const content = readFileSafe(path.join(cwd, ".gitlab-ci.yml"));
+    if (content && /phpunit|jest|playwright|wp-env/i.test(content)) {
+      result.hasTestStep = true;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect npm test scripts
+// ---------------------------------------------------------------------------
+
+function detectScripts(cwd) {
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (!pkg?.scripts) return {};
+
+  const testScripts = {};
+  for (const [key, value] of Object.entries(pkg.scripts)) {
+    if (/test|e2e|playwright|jest|phpunit/i.test(key)) {
+      testScripts[key] = value;
+    }
+  }
+  return testScripts;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const playwright = detectPlaywright(cwd);
+  const jest = detectJest(cwd);
+  const phpunit = detectPHPUnit(cwd);
+  const wpEnv = detectWpEnv(cwd);
+  const ci = detectCI(cwd);
+  const scripts = detectScripts(cwd);
+
+  const anyDetected = playwright.detected || jest.detected || phpunit.detected;
+
+  const report = {
+    tool: "test_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected: anyDetected,
+    frameworks: {
+      playwright,
+      jest,
+      phpunit,
+    },
+    environment: {
+      wpEnv,
+    },
+    ci,
+    scripts,
+    recommendations: [],
+  };
+
+  // Generate recommendations
+  if (!anyDetected) {
+    report.recommendations.push("No test frameworks detected. Consider adding Playwright for E2E and PHPUnit for unit tests.");
+  }
+  if (!wpEnv.detected && (playwright.detected || phpunit.detected)) {
+    report.recommendations.push("Consider adding .wp-env.json for a consistent WordPress test environment.");
+  }
+  if (anyDetected && !ci.hasTestStep) {
+    report.recommendations.push("Test frameworks detected but CI does not run tests. Add a test step to your CI pipeline.");
+  }
+  if (playwright.detected && !playwright.wpE2eUtils) {
+    report.recommendations.push("Consider using @wordpress/e2e-test-utils-playwright for WordPress-specific test helpers.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(anyDetected ? 0 : 1);
+}
+
+main();

package/skills/wp-headless/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: wp-headless
+description: "Use when building headless/decoupled WordPress architectures: choosing between REST API and WPGraphQL, headless authentication (JWT, application passwords, NextAuth), CORS configuration, frontend framework integration (Next.js, Nuxt, Astro), content webhooks, and ISR/SSG strategies."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node."
+version: 1.0.0
+source: "vinmor/wordpress-manager"
+---
+
+# WP Headless
+
+## When to use
+
+Use this skill when building or maintaining a decoupled/headless WordPress architecture:
+
+- Building a decoupled site with WordPress as the CMS and a separate frontend
+- Choosing between REST API and WPGraphQL for data fetching
+- Configuring WordPress as a headless CMS backend
+- Integrating with Next.js, Nuxt, or Astro frontends
+- Setting up headless authentication (JWT, application passwords, NextAuth/Auth.js)
+- Configuring CORS for cross-origin API access
+- Implementing content webhooks for on-demand revalidation (ISR)
+- Planning SSG, SSR, or ISR rendering strategies
+
+## Inputs required
+
+- **WordPress site**: URL, admin access, hosting type
+- **Frontend framework**: Next.js, Nuxt, Astro, or other
+- **Authentication requirements**: public content only vs authenticated features
+- **Hosting for frontend**: Vercel, Netlify, self-hosted, or other
+- **Deployment strategy**: SSG (static), SSR (server), ISR (incremental), or hybrid
+
+## Procedure
+
+### 0) Detect headless setup
+
+Run the detection script to assess the current architecture:
+
+```bash
+node skills/wp-headless/scripts/headless_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script outputs JSON with:
+- `apiLayer` — REST API and/or WPGraphQL availability, custom endpoints count
+- `frontend` — detected frontend framework (Next.js, Nuxt, Astro)
+- `auth` — authentication methods available
+- `cors` — CORS configuration status and allowed origins
+- `webhooks` — outgoing webhook configuration
+- `isHeadless` — boolean assessment of whether the setup is headless
+
+### 1) Choose API layer
+
+Decide between REST API (built-in) and WPGraphQL (plugin) based on project needs.
+
+| Factor | REST API | WPGraphQL |
+|--------|----------|-----------|
+| Installation | Built-in, zero setup | Requires plugin |
+| Data fetching | Fixed response shape | Fetch exactly what you need |
+| Related data | Multiple requests | Single query with connections |
+| Learning curve | Low (familiar HTTP) | Medium (GraphQL syntax) |
+| Caching | Simple (HTTP cache) | Complex (query-level) |
+| Best for | Simple sites, mobile apps | Complex content, performance-critical |
+
+Use REST with `_fields` parameter for simple needs. Use WPGraphQL for complex content models.
+
+Read: `references/api-layer-choice.md`
+
+For REST endpoint development, also reference the `wp-rest-api` skill.
+
+### 2) WPGraphQL setup
+
+If using WPGraphQL:
+1. Install: `wp plugin install wp-graphql --activate`
+2. Explore schema at `/graphql` endpoint with GraphiQL
+3. Register custom types and fields
+4. Use cursor-based pagination (`first`/`after`)
+5. Consider WPGraphQL Smart Cache for performance
+
+Read: `references/wpgraphql.md`
+
+### 3) Headless authentication
+
+Choose the authentication method based on use case:
+
+- **Application Passwords** (built-in): best for server-to-server and build-time fetching
+- **JWT** (plugin): best for client-side authentication flows
+- **NextAuth/Auth.js**: best for Next.js projects with WordPress as OAuth provider
+- **Preview mode**: special auth for draft content preview
+
+For security best practices in authentication, reference the `wp-security` skill.
+
+Read: `references/headless-auth.md`
+
+### 4) CORS configuration
+
+Configure Cross-Origin Resource Sharing to allow the frontend to access WordPress APIs:
+
+```php
+add_filter('allowed_http_origins', function($origins) {
+    $origins[] = 'https://frontend.example.com';
+    return $origins;
+});
+```
+
+Key rules:
+- Never use `Access-Control-Allow-Origin: *` with credentials
+- Always specify exact origins in production
+- Handle preflight `OPTIONS` requests
+- WPGraphQL has built-in CORS settings
+
+Read: `references/cors-config.md`
+
+### 5) Frontend integration
+
+Connect the frontend framework to WordPress data:
+
+- **Next.js**: `fetch()` in App Router with `revalidate`, `getStaticProps` in Pages Router, ISR for incremental updates
+- **Nuxt**: `useFetch()` / `useAsyncData()`, ISR with `routeRules`
+- **Astro**: content collections from API, static-first with on-demand rendering
+
+Common patterns: centralized API client, TypeScript types from schema, image optimization with WordPress media URLs.
+
+Read: `references/frontend-integration.md`
+
+### 6) Content webhooks and revalidation
+
+Trigger frontend rebuilds or cache invalidation when WordPress content changes:
+
+```php
+add_action('transition_post_status', function($new, $old, $post) {
+    if ($new === 'publish') {
+        wp_remote_post('https://frontend.example.com/api/revalidate', [
+            'body'    => json_encode(['path' => '/' . $post->post_name]),
+            'headers' => ['Content-Type' => 'application/json', 'Authorization' => 'Bearer SECRET'],
+        ]);
+    }
+}, 10, 3);
+```
+
+Strategies: path-based ISR, tag-based revalidation, full rebuild triggers. WPGraphQL Smart Cache provides automatic invalidation.
+
+Read: `references/webhooks.md`
+
+## Verification
+
+- API returns data: `curl https://wp.example.com/wp-json/wp/v2/posts` returns JSON
+- Frontend renders WordPress content correctly
+- Authentication works: protected endpoints require credentials, public ones don't
+- CORS headers correct: check `Access-Control-Allow-Origin` in response headers
+- Preview mode: draft content visible in frontend preview
+- Webhooks trigger: publish a post and confirm frontend revalidates
+- Builds succeed: `next build` / `nuxt generate` / `astro build` completes
+
+## Failure modes / debugging
+
+- **CORS errors**: check browser DevTools Network tab for preflight failures; verify origin whitelist matches exactly (protocol + domain + port)
+- **Authentication failures**: verify application password format (`user:xxxx xxxx xxxx`), check JWT token expiry, confirm `Authorization` header is forwarded
+- **Stale content**: ISR `revalidate` interval too high; webhook not triggering; check `transition_post_status` hook fires on publish
+- **GraphQL schema missing fields**: custom post types need `show_in_graphql => true`; ACF fields need WPGraphQL for ACF extension
+- **Preview not working**: draft mode API route misconfigured; preview secret mismatch; WordPress preview URL not pointing to frontend
+- **Build failures**: API unreachable during build; increase timeout; add fallback for missing data
+
+## Escalation
+
+- WPGraphQL documentation: https://www.wpgraphql.com/docs
+- Next.js WordPress examples: https://github.com/vercel/next.js/tree/canary/examples/cms-wordpress
+- Astro WordPress integration: https://docs.astro.build/en/guides/cms/wordpress/
+- For REST endpoint development, use the `wp-rest-api` skill
+- For authentication security, use the `wp-security` skill

package/skills/wp-headless/references/api-layer-choice.md

@@ -0,0 +1,160 @@
+# API Layer Choice
+
+Use this file when deciding between REST API and WPGraphQL for a headless WordPress project.
+
+## Comparison matrix
+
+| Criterion | REST API | WPGraphQL |
+|-----------|----------|-----------|
+| Built into core | Yes (since 4.7) | Plugin required |
+| Data fetching | Fixed endpoints, multiple requests | Single query, exact fields |
+| Over-fetching | Common (returns all fields) | Eliminated (request only what you need) |
+| Under-fetching | Common (need multiple requests) | Eliminated (nested queries) |
+| Caching | HTTP caching (CDN-friendly) | Requires custom caching layer |
+| Learning curve | Lower (familiar REST patterns) | Higher (GraphQL query language) |
+| Community/ecosystem | Largest | Growing, strong Gatsby/Next.js integration |
+| Real-time | Polling or custom | Subscriptions (with extensions) |
+| Authentication | Cookie, Application Passwords, JWT | Same as REST + GraphQL-specific |
+| File uploads | Native multipart | Requires separate REST endpoint |
+| Performance | Predictable | Faster for complex pages, slower for simple |
+| Debugging | Standard HTTP tools | Requires GraphQL client (GraphiQL) |
+
+## When to choose REST API
+
+- **Simple content sites** — blog, portfolio, brochure
+- **CDN-heavy architecture** — REST responses cache naturally at edge
+- **Team unfamiliar with GraphQL** — lower learning curve
+- **Third-party integrations** — most services expect REST
+- **WooCommerce headless** — WooCommerce REST API is mature and well-documented
+- **Mobile apps** — REST is universal across platforms
+- **Server-side rendering with few queries** — ISR/SSG pages that make 1-3 API calls
+
+## When to choose WPGraphQL
+
+- **Complex page compositions** — homepage with posts, categories, menus, options, custom fields
+- **Component-driven frontend** — React/Vue components that each declare their data needs
+- **Gatsby projects** — gatsby-source-wordpress uses WPGraphQL natively
+- **Deeply nested data** — posts → author → posts → categories in one query
+- **Multiple content types per page** — dashboard-style layouts
+- **Rapid frontend development** — frontend devs query exactly what they need
+
+## Hybrid approach
+
+Use both:
+
+```
+REST API → Simple CRUD, file uploads, WooCommerce, webhooks
+WPGraphQL → Complex page data fetching, component queries
+```
+
+This is common in production. Example:
+- Blog listing page: WPGraphQL (needs posts + categories + featured images + author in one query)
+- Contact form submission: REST API (simple POST)
+- WooCommerce cart/checkout: WooCommerce REST API
+- Media upload: REST API (multipart form data)
+
+## REST API quick setup for headless
+
+```php
+// Register custom endpoint
+add_action('rest_api_init', function() {
+    register_rest_route('myapp/v1', '/homepage', [
+        'methods'  => 'GET',
+        'callback' => 'get_homepage_data',
+        'permission_callback' => '__return_true',
+    ]);
+});
+
+function get_homepage_data() {
+    return [
+        'hero'  => get_field('hero', 'option'),
+        'posts' => get_posts(['numberposts' => 6, 'post_type' => 'post']),
+        'menu'  => wp_get_nav_menu_items('primary'),
+    ];
+}
+```
+
+## WPGraphQL quick setup for headless
+
+```bash
+wp plugin install wp-graphql --activate
+```
+
+```graphql
+# Single query for a complex homepage
+query Homepage {
+  posts(first: 6) {
+    nodes {
+      title
+      excerpt
+      uri
+      featuredImage {
+        node {
+          sourceUrl(size: MEDIUM_LARGE)
+          altText
+        }
+      }
+      categories {
+        nodes {
+          name
+          slug
+        }
+      }
+    }
+  }
+  menus(where: { location: PRIMARY }) {
+    nodes {
+      menuItems {
+        nodes {
+          label
+          url
+        }
+      }
+    }
+  }
+}
+```
+
+## Performance considerations
+
+### REST API
+
+```
+Homepage data:
+  GET /wp-json/wp/v2/posts?per_page=6          → 1 request
+  GET /wp-json/wp/v2/categories                  → 1 request
+  GET /wp-json/wp/v2/media/{id} (per post)       → 6 requests
+  GET /wp-json/wp/v2/menus/primary               → 1 request
+  Total: 9 requests, ~150KB response (with over-fetching)
+```
+
+### WPGraphQL
+
+```
+Homepage data:
+  POST /graphql (single query)                   → 1 request
+  Total: 1 request, ~25KB response (exact fields only)
+```
+
+### Mitigation for REST over-fetching
+
+```php
+// Use _fields parameter to reduce payload
+// GET /wp-json/wp/v2/posts?_fields=id,title,excerpt,featured_media
+
+// Or create custom endpoints that aggregate data
+register_rest_route('myapp/v1', '/homepage', [
+    'callback' => function() {
+        // Return exactly what the frontend needs
+    }
+]);
+```
+
+## Decision checklist
+
+1. What is the team's GraphQL experience? (low → REST)
+2. How many API calls per page? (>3 → consider WPGraphQL)
+3. Is edge caching critical? (yes → REST preferred)
+4. Using Gatsby? (yes → WPGraphQL)
+5. Using WooCommerce? (yes → REST for commerce, WPGraphQL for content)
+6. How nested is the data model? (deeply nested → WPGraphQL)