claude-plugin-wordpress-manager 1.4.0 → 1.7.0

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)

package/skills/wp-headless/references/cors-config.md

@@ -0,0 +1,245 @@
+# CORS Configuration
+
+Use this file when configuring Cross-Origin Resource Sharing for headless WordPress.
+
+## Why CORS matters for headless
+
+In a headless setup, the frontend (e.g., `app.example.com`) and WordPress backend (`wp.example.com`) are on different origins. Browsers block cross-origin requests unless the server explicitly allows them via CORS headers.
+
+## WordPress CORS via PHP
+
+### Allow specific origin (recommended)
+
+```php
+add_action('init', function() {
+    $allowed_origins = [
+        'https://app.example.com',
+        'https://staging.example.com',
+    ];
+
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowed_origins, true)) {
+        header("Access-Control-Allow-Origin: $origin");
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
+        header('Access-Control-Allow-Credentials: true');
+        header('Access-Control-Max-Age: 86400');
+    }
+
+    // Handle preflight
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        status_header(204);
+        exit;
+    }
+});
+```
+
+### REST API specific filter
+
+```php
+add_action('rest_api_init', function() {
+    remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
+
+    add_filter('rest_pre_serve_request', function($value) {
+        $allowed_origins = [
+            'https://app.example.com',
+            'https://staging.example.com',
+        ];
+
+        $origin = get_http_origin();
+
+        if ($origin && in_array($origin, $allowed_origins, true)) {
+            header("Access-Control-Allow-Origin: $origin");
+            header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+            header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
+            header('Access-Control-Allow-Credentials: true');
+        }
+
+        return $value;
+    });
+});
+```
+
+### WPGraphQL CORS
+
+```php
+add_action('graphql_response_headers_to_send', function($headers) {
+    $allowed_origins = [
+        'https://app.example.com',
+    ];
+
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowed_origins, true)) {
+        $headers['Access-Control-Allow-Origin'] = $origin;
+        $headers['Access-Control-Allow-Headers'] = 'Authorization, Content-Type';
+        $headers['Access-Control-Allow-Credentials'] = 'true';
+    }
+
+    return $headers;
+});
+```
+
+## Server-level CORS
+
+### Nginx
+
+```nginx
+# /etc/nginx/conf.d/cors.conf or within server block
+map $http_origin $cors_origin {
+    default "";
+    "https://app.example.com"     "https://app.example.com";
+    "https://staging.example.com" "https://staging.example.com";
+}
+
+server {
+    # ... existing config
+
+    location /wp-json/ {
+        if ($cors_origin != "") {
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-WP-Nonce" always;
+            add_header Access-Control-Allow-Credentials "true" always;
+            add_header Access-Control-Max-Age 86400 always;
+        }
+
+        if ($request_method = OPTIONS) {
+            return 204;
+        }
+
+        # ... proxy or fastcgi config
+    }
+
+    location /graphql {
+        # Same CORS headers as above
+        if ($cors_origin != "") {
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+            add_header Access-Control-Allow-Credentials "true" always;
+        }
+
+        if ($request_method = OPTIONS) {
+            return 204;
+        }
+
+        # ... proxy or fastcgi config
+    }
+}
+```
+
+### Apache (.htaccess)
+
+```apache
+<IfModule mod_headers.c>
+    SetEnvIf Origin "^https://(app|staging)\.example\.com$" CORS_ORIGIN=$0
+    Header always set Access-Control-Allow-Origin %{CORS_ORIGIN}e env=CORS_ORIGIN
+    Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
+    Header always set Access-Control-Allow-Headers "Authorization, Content-Type, X-WP-Nonce"
+    Header always set Access-Control-Allow-Credentials "true"
+    Header always set Access-Control-Max-Age "86400"
+</IfModule>
+
+# Handle preflight
+RewriteEngine On
+RewriteCond %{REQUEST_METHOD} OPTIONS
+RewriteRule ^(.*)$ $1 [R=204,L]
+```
+
+## CORS headers explained
+
+| Header | Purpose |
+|--------|---------|
+| `Access-Control-Allow-Origin` | Which origins can access the resource |
+| `Access-Control-Allow-Methods` | Which HTTP methods are allowed |
+| `Access-Control-Allow-Headers` | Which request headers are allowed |
+| `Access-Control-Allow-Credentials` | Whether cookies/auth can be sent |
+| `Access-Control-Max-Age` | How long preflight results can be cached (seconds) |
+| `Access-Control-Expose-Headers` | Which response headers the client can read |
+
+## Common issues
+
+### "No 'Access-Control-Allow-Origin' header"
+
+The server doesn't include the CORS header. Fix: add the headers as shown above.
+
+### "The value of 'Access-Control-Allow-Origin' is not equal to the supplied origin"
+
+Origin mismatch. Check:
+- Trailing slashes (`https://app.example.com` vs `https://app.example.com/`)
+- Protocol (`http` vs `https`)
+- Port numbers (`localhost:3000` vs `localhost`)
+
+### "Credentials flag is true but Access-Control-Allow-Origin is '*'"
+
+Cannot use `*` with `credentials: true`. Must specify the exact origin:
+```
+Access-Control-Allow-Origin: https://app.example.com  ✓
+Access-Control-Allow-Origin: *                          ✗ (with credentials)
+```
+
+### Preflight (OPTIONS) returns 401/403
+
+WordPress or a security plugin is blocking OPTIONS requests. Fix:
+```php
+add_action('init', function() {
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        // Send CORS headers and exit before WordPress auth runs
+        header('Access-Control-Allow-Origin: https://app.example.com');
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Allow-Credentials: true');
+        status_header(204);
+        exit;
+    }
+});
+```
+
+## Development CORS
+
+```php
+// ONLY for local development — never in production
+if (defined('WP_DEBUG') && WP_DEBUG) {
+    add_action('init', function() {
+        header('Access-Control-Allow-Origin: http://localhost:3000');
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Allow-Credentials: true');
+
+        if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+            status_header(204);
+            exit;
+        }
+    });
+}
+```
+
+## Security rules
+
+1. **Never use `*` in production** — always whitelist specific origins
+2. **Never reflect the Origin header blindly** — validate against a whitelist
+3. **Use `Credentials: true` only when needed** — for authenticated requests
+4. **Set `Max-Age` for caching** — reduces preflight requests (86400 = 24 hours)
+5. **Expose only needed headers** — minimize `Access-Control-Expose-Headers`
+
+## Verification
+
+```bash
+# Test CORS headers
+curl -I -X OPTIONS https://wp.example.com/wp-json/wp/v2/posts \
+  -H "Origin: https://app.example.com" \
+  -H "Access-Control-Request-Method: GET" \
+  -H "Access-Control-Request-Headers: Authorization"
+
+# Check response headers include:
+# Access-Control-Allow-Origin: https://app.example.com
+# Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+# Access-Control-Allow-Headers: Authorization, Content-Type
+
+# Test from frontend
+fetch('https://wp.example.com/wp-json/wp/v2/posts', {
+    credentials: 'include',
+}).then(r => console.log('CORS OK:', r.ok));
+```