claude-plugin-wordpress-manager 1.5.0 → 1.7.1

package/skills/wp-headless/references/wpgraphql.md

@@ -0,0 +1,331 @@
+# WPGraphQL
+
+Use this file when setting up and using WPGraphQL for headless WordPress.
+
+## Installation
+
+```bash
+wp plugin install wp-graphql --activate
+
+# Verify
+wp graphql --help
+curl -s http://localhost:8888/graphql -H "Content-Type: application/json" \
+  -d '{"query": "{ generalSettings { title } }"}' | jq
+```
+
+GraphQL IDE: `http://localhost:8888/wp-admin/admin.php?page=graphiql-ide`
+
+## Common queries
+
+### Posts
+
+```graphql
+# List posts with pagination
+query GetPosts($first: Int = 10, $after: String) {
+  posts(first: $first, after: $after) {
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      id
+      databaseId
+      title
+      slug
+      date
+      excerpt
+      content
+      uri
+      featuredImage {
+        node {
+          sourceUrl(size: LARGE)
+          altText
+          mediaDetails {
+            width
+            height
+          }
+        }
+      }
+      author {
+        node {
+          name
+          avatar {
+            url
+          }
+        }
+      }
+      categories {
+        nodes {
+          name
+          slug
+        }
+      }
+      tags {
+        nodes {
+          name
+          slug
+        }
+      }
+    }
+  }
+}
+```
+
+### Single post by slug
+
+```graphql
+query GetPost($slug: ID!) {
+  post(id: $slug, idType: SLUG) {
+    title
+    content
+    date
+    modified
+    seo {
+      title
+      metaDesc
+      opengraphImage {
+        sourceUrl
+      }
+    }
+    author {
+      node {
+        name
+        description
+      }
+    }
+  }
+}
+```
+
+### Pages
+
+```graphql
+query GetPage($uri: String!) {
+  pageBy(uri: $uri) {
+    title
+    content
+    template {
+      templateName
+    }
+    children {
+      nodes {
+        ... on Page {
+          title
+          uri
+        }
+      }
+    }
+  }
+}
+```
+
+### Menus
+
+```graphql
+query GetMenu {
+  menus(where: { location: PRIMARY }) {
+    nodes {
+      menuItems(first: 50) {
+        nodes {
+          id
+          label
+          url
+          parentId
+          cssClasses
+          target
+        }
+      }
+    }
+  }
+}
+```
+
+### Custom Post Types
+
+```php
+// Register CPT with GraphQL support
+register_post_type('product', [
+    'label'               => 'Products',
+    'public'              => true,
+    'show_in_graphql'     => true,
+    'graphql_single_name' => 'product',
+    'graphql_plural_name' => 'products',
+]);
+```
+
+```graphql
+query GetProducts {
+  products(first: 12) {
+    nodes {
+      title
+      slug
+      productFields {   # ACF field group
+        price
+        sku
+      }
+    }
+  }
+}
+```
+
+### Custom Taxonomies
+
+```php
+register_taxonomy('product_category', 'product', [
+    'label'               => 'Product Categories',
+    'show_in_graphql'     => true,
+    'graphql_single_name' => 'productCategory',
+    'graphql_plural_name' => 'productCategories',
+]);
+```
+
+## ACF integration
+
+```bash
+wp plugin install wpgraphql-acf --activate
+```
+
+ACF fields are automatically exposed when the field group's "Show in GraphQL" setting is enabled.
+
+```graphql
+query GetPostWithACF {
+  post(id: "hello-world", idType: SLUG) {
+    title
+    customFields {       # ACF field group name (camelCase)
+      subtitle
+      heroImage {
+        sourceUrl
+        altText
+      }
+      features {         # Repeater field
+        title
+        description
+      }
+    }
+  }
+}
+```
+
+## Custom resolvers
+
+```php
+// Add custom field to existing type
+add_action('graphql_register_types', function() {
+    register_graphql_field('Post', 'readingTime', [
+        'type'        => 'Int',
+        'description' => 'Estimated reading time in minutes',
+        'resolve'     => function($post) {
+            $content = get_post_field('post_content', $post->databaseId);
+            $word_count = str_word_count(strip_tags($content));
+            return max(1, ceil($word_count / 200));
+        },
+    ]);
+});
+
+// Add custom root query
+add_action('graphql_register_types', function() {
+    register_graphql_field('RootQuery', 'siteOptions', [
+        'type'        => 'SiteOptions',
+        'description' => 'Global site options',
+        'resolve'     => function() {
+            return [
+                'phone'   => get_option('site_phone'),
+                'address' => get_option('site_address'),
+            ];
+        },
+    ]);
+
+    register_graphql_object_type('SiteOptions', [
+        'fields' => [
+            'phone'   => ['type' => 'String'],
+            'address' => ['type' => 'String'],
+        ],
+    ]);
+});
+```
+
+## Mutations
+
+```graphql
+# Create a comment (authenticated)
+mutation CreateComment($input: CreateCommentInput!) {
+  createComment(input: $input) {
+    success
+    comment {
+      id
+      content
+      date
+      author {
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+Variables:
+```json
+{
+  "input": {
+    "commentOn": 1,
+    "content": "Great post!",
+    "author": "John"
+  }
+}
+```
+
+## Performance
+
+### Query complexity limits
+
+WPGraphQL enforces query depth and complexity limits by default.
+
+```php
+// Adjust limits in wp-config.php or plugin
+add_filter('graphql_max_query_amount', function() {
+    return 100; // max nodes per query (default: 100)
+});
+```
+
+### Persisted queries
+
+```php
+// Register a persisted query
+add_action('graphql_register_types', function() {
+    register_graphql_query_alias('homepage', '
+        query Homepage {
+            posts(first: 6) { nodes { title slug excerpt } }
+            menus(where: { location: PRIMARY }) { nodes { menuItems { nodes { label url } } } }
+        }
+    ');
+});
+```
+
+### Object caching
+
+WPGraphQL integrates with WordPress object cache. Use Redis or Memcached for production:
+
+```bash
+wp plugin install wp-graphql-smart-cache --activate
+```
+
+## Verification
+
+```bash
+# Test GraphQL endpoint
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ posts(first: 1) { nodes { title } } }"}' | jq
+
+# Check schema introspection
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ __schema { types { name } } }"}' | jq '.data.__schema.types | length'
+
+# Verify CPT is registered in schema
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ __type(name: \"Product\") { name fields { name } } }"}' | jq
+```

package/skills/wp-headless/scripts/headless_inspect.mjs

@@ -0,0 +1,321 @@
+/**
+ * headless_inspect.mjs — Detect headless WordPress configuration.
+ *
+ * Scans for WPGraphQL, CORS config, frontend framework integration,
+ * and decoupled architecture indicators.
+ * Outputs a JSON report to stdout.
+ *
+ * Usage:
+ *   node headless_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — headless indicators detected
+ *   1 — no headless indicators 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 readdirSafe(dir) {
+  try {
+    return fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse --cwd argument
+// ---------------------------------------------------------------------------
+
+function parseCwd() {
+  const cwdArg = process.argv.find((a) => a.startsWith("--cwd="));
+  return cwdArg ? cwdArg.slice(6) : process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// Detect WPGraphQL
+// ---------------------------------------------------------------------------
+
+function detectWPGraphQL(cwd) {
+  const result = { detected: false, plugins: [] };
+
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const graphqlPlugins = [
+    { dir: "wp-graphql", name: "WPGraphQL" },
+    { dir: "wpgraphql-acf", name: "WPGraphQL for ACF" },
+    { dir: "wp-graphql-jwt-authentication", name: "WPGraphQL JWT Auth" },
+    { dir: "wp-graphql-smart-cache", name: "WPGraphQL Smart Cache" },
+    { dir: "wp-graphql-woocommerce", name: "WPGraphQL WooCommerce" },
+    { dir: "wp-gatsby", name: "WP Gatsby" },
+  ];
+
+  for (const plugin of graphqlPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.plugins.push(plugin.name);
+    }
+  }
+
+  // Check composer.json for WPGraphQL
+  const composer = readJsonSafe(path.join(cwd, "composer.json"));
+  if (composer) {
+    const allDeps = { ...composer.require, ...composer["require-dev"] };
+    if (allDeps["wp-graphql/wp-graphql"]) {
+      result.detected = true;
+      if (!result.plugins.includes("WPGraphQL")) result.plugins.push("WPGraphQL (composer)");
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect CORS configuration
+// ---------------------------------------------------------------------------
+
+function detectCORS(cwd) {
+  const result = { detected: false, sources: [] };
+
+  // Check .htaccess
+  const htaccess = readFileSafe(path.join(cwd, ".htaccess"));
+  if (htaccess && /Access-Control-Allow-Origin/i.test(htaccess)) {
+    result.detected = true;
+    result.sources.push(".htaccess");
+  }
+
+  // Check wp-config.php for CORS constants
+  const wpConfig = readFileSafe(path.join(cwd, "wp-config.php"));
+  if (wpConfig && /CORS|Access-Control/i.test(wpConfig)) {
+    result.detected = true;
+    result.sources.push("wp-config.php");
+  }
+
+  // Check PHP files for CORS headers
+  const corsPhp = execSafe(
+    `grep -rl --include="*.php" "Access-Control-Allow-Origin" . 2>/dev/null | head -5`,
+    cwd
+  );
+  if (corsPhp && corsPhp.length > 0) {
+    result.detected = true;
+    const files = corsPhp.split("\n").map((f) => path.relative(cwd, f));
+    result.sources.push(...files.filter((f) => !result.sources.includes(f)));
+  }
+
+  // Check nginx config (common locations)
+  for (const confPath of ["/etc/nginx/sites-enabled/default", "/etc/nginx/conf.d/default.conf"]) {
+    const content = readFileSafe(confPath);
+    if (content && /Access-Control-Allow-Origin/i.test(content)) {
+      result.detected = true;
+      result.sources.push(confPath);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect frontend framework
+// ---------------------------------------------------------------------------
+
+function detectFrontend(cwd) {
+  const result = { detected: false, framework: null, location: null };
+
+  // Check for frontend directories
+  const frontendDirs = ["frontend", "client", "app", "web", "next", "nuxt"];
+  for (const dir of frontendDirs) {
+    const pkgPath = path.join(cwd, dir, "package.json");
+    const pkg = readJsonSafe(pkgPath);
+    if (pkg) {
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (allDeps["next"]) {
+        result.detected = true;
+        result.framework = "Next.js";
+        result.location = dir;
+        return result;
+      }
+      if (allDeps["nuxt"] || allDeps["nuxt3"]) {
+        result.detected = true;
+        result.framework = "Nuxt";
+        result.location = dir;
+        return result;
+      }
+      if (allDeps["astro"]) {
+        result.detected = true;
+        result.framework = "Astro";
+        result.location = dir;
+        return result;
+      }
+      if (allDeps["gatsby"]) {
+        result.detected = true;
+        result.framework = "Gatsby";
+        result.location = dir;
+        return result;
+      }
+    }
+  }
+
+  // Check root package.json
+  const rootPkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (rootPkg) {
+    const allDeps = { ...rootPkg.dependencies, ...rootPkg.devDependencies };
+    if (allDeps["next"]) { result.detected = true; result.framework = "Next.js"; result.location = "."; }
+    else if (allDeps["nuxt"] || allDeps["nuxt3"]) { result.detected = true; result.framework = "Nuxt"; result.location = "."; }
+    else if (allDeps["astro"]) { result.detected = true; result.framework = "Astro"; result.location = "."; }
+    else if (allDeps["gatsby"]) { result.detected = true; result.framework = "Gatsby"; result.location = "."; }
+    else if (allDeps["gatsby-source-wordpress"]) { result.detected = true; result.framework = "Gatsby"; result.location = "."; }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect headless indicators in WordPress
+// ---------------------------------------------------------------------------
+
+function detectHeadlessIndicators(cwd) {
+  const result = { indicators: [] };
+
+  // Check for headless theme (minimal or API-only themes)
+  const themeDir = path.join(cwd, "wp-content", "themes");
+  if (statSafe(themeDir)?.isDirectory()) {
+    const themes = readdirSafe(themeDir);
+    for (const theme of themes) {
+      const functionsPhp = readFileSafe(path.join(themeDir, theme, "functions.php"));
+      if (functionsPhp && /headless|decoupled|api.only/i.test(functionsPhp)) {
+        result.indicators.push(`Headless theme detected: ${theme}`);
+      }
+    }
+  }
+
+  // Check for webhook configuration
+  const wpConfig = readFileSafe(path.join(cwd, "wp-config.php"));
+  if (wpConfig) {
+    if (/HEADLESS_WEBHOOK/i.test(wpConfig)) {
+      result.indicators.push("Webhook configuration found in wp-config.php");
+    }
+    if (/HEADLESS_FRONTEND|FRONTEND_URL/i.test(wpConfig)) {
+      result.indicators.push("Frontend URL constant found in wp-config.php");
+    }
+  }
+
+  // Check for REST API customizations
+  const restCustom = execSafe(
+    `grep -rl --include="*.php" "register_rest_route" . 2>/dev/null | wc -l`,
+    cwd
+  );
+  if (restCustom && parseInt(restCustom) > 3) {
+    result.indicators.push(`${restCustom} files with custom REST routes detected`);
+  }
+
+  // Check for headless plugins
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const headlessPlugins = [
+    { dir: "faust-wordpress", name: "Faust.js (WP Engine)" },
+    { dir: "atlas-content-modeler", name: "Atlas Content Modeler" },
+    { dir: "wp-gatsby", name: "WP Gatsby" },
+    { dir: "headless-mode", name: "Headless Mode" },
+  ];
+
+  for (const plugin of headlessPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.indicators.push(`Plugin: ${plugin.name}`);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const graphql = detectWPGraphQL(cwd);
+  const cors = detectCORS(cwd);
+  const frontend = detectFrontend(cwd);
+  const indicators = detectHeadlessIndicators(cwd);
+
+  const detected = graphql.detected || cors.detected || frontend.detected || indicators.indicators.length > 0;
+
+  const report = {
+    tool: "headless_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected,
+    graphql,
+    cors,
+    frontend,
+    indicators: indicators.indicators,
+    apiLayer: graphql.detected ? "WPGraphQL" : "REST API",
+    recommendations: [],
+  };
+
+  // Recommendations
+  if (frontend.detected && !graphql.detected && !cors.detected) {
+    report.recommendations.push("Frontend framework detected but no CORS or GraphQL setup found. Configure CORS headers for cross-origin API access.");
+  }
+  if (graphql.detected && !cors.detected) {
+    report.recommendations.push("WPGraphQL detected but no CORS configuration found. Add CORS headers for frontend access.");
+  }
+  if (frontend.framework === "Gatsby" && !graphql.detected) {
+    report.recommendations.push("Gatsby detected. Install WPGraphQL for optimal integration with gatsby-source-wordpress.");
+  }
+  if (detected && indicators.indicators.length === 0) {
+    report.recommendations.push("Consider adding a webhook system to notify the frontend of content changes.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(detected ? 0 : 1);
+}
+
+main();