claude-plugin-wordpress-manager 2.2.0 → 2.3.0

package/skills/wp-multilang-network/scripts/multilang_inspect.mjs

@@ -0,0 +1,308 @@
+/**
+ * multilang_inspect.mjs — Detect multi-language network readiness.
+ *
+ * Scans for WordPress Multisite status, multilingual plugins, sub-site
+ * language patterns, hreflang tags, and WPLANG configuration.
+ * Outputs a JSON report to stdout.
+ *
+ * Usage:
+ *   node multilang_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — multi-language network indicators detected
+ *   1 — no multi-language network 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 WordPress Multisite
+// ---------------------------------------------------------------------------
+
+function detectMultisite(cwd) {
+  const result = { is_multisite: false, site_count: 0 };
+
+  // Check wp-config.php for MULTISITE constant
+  const wpConfig = readFileSafe(path.join(cwd, "wp-config.php"));
+  if (wpConfig) {
+    if (/define\s*\(\s*['"]MULTISITE['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+      result.is_multisite = true;
+    }
+    if (/define\s*\(\s*['"]WP_ALLOW_MULTISITE['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+      result.is_multisite = true;
+    }
+  }
+
+  // Try WP-CLI for site count
+  const siteCount = execSafe("wp site list --format=count 2>/dev/null", cwd);
+  if (siteCount) {
+    const count = parseInt(siteCount);
+    if (count > 1) {
+      result.is_multisite = true;
+      result.site_count = count;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect multilingual plugins
+// ---------------------------------------------------------------------------
+
+function detectMultilingualPlugin(cwd) {
+  const result = { detected: false, plugin: null };
+
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const multilingualPlugins = [
+    { dir: "sitepress-multilingual-cms", name: "WPML" },
+    { dir: "polylang", name: "Polylang" },
+    { dir: "polylang-pro", name: "Polylang Pro" },
+    { dir: "multilingualpress", name: "MultilingualPress" },
+    { dir: "translatepress-multilingual", name: "TranslatePress" },
+    { dir: "weglot", name: "Weglot" },
+  ];
+
+  for (const plugin of multilingualPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.plugin = plugin.name;
+      return result;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect language patterns in sub-sites
+// ---------------------------------------------------------------------------
+
+function detectLanguagePatterns(cwd) {
+  const result = { detected_languages: [], sites: [] };
+
+  // ISO 639-1 language codes to look for
+  const langCodes = new Set([
+    "en", "it", "de", "fr", "es", "pt", "nl", "pl", "sv", "da", "no", "fi",
+    "ru", "ja", "zh", "ko", "ar", "he", "hi", "tr", "el", "cs", "ro", "hu",
+    "uk", "bg", "hr", "sk", "sl", "et", "lv", "lt", "th", "vi", "id", "ms",
+  ]);
+
+  // Try WP-CLI to list sites with paths
+  const siteList = execSafe("wp site list --fields=blog_id,url,path --format=json 2>/dev/null", cwd);
+  if (siteList) {
+    try {
+      const sites = JSON.parse(siteList);
+      for (const site of sites) {
+        const pathSlug = (site.path || "").replace(/\//g, "").toLowerCase();
+        const isLang = langCodes.has(pathSlug);
+        result.sites.push({
+          blog_id: site.blog_id,
+          url: site.url,
+          path: site.path,
+          detected_language: isLang ? pathSlug : null,
+        });
+        if (isLang && !result.detected_languages.includes(pathSlug)) {
+          result.detected_languages.push(pathSlug);
+        }
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect hreflang tags
+// ---------------------------------------------------------------------------
+
+function detectHreflang(cwd) {
+  const result = { detected: false, sources: [] };
+
+  // Check mu-plugins for hreflang generation
+  const muPluginsDir = path.join(cwd, "wp-content", "mu-plugins");
+  const muFiles = readdirSafe(muPluginsDir);
+  for (const file of muFiles) {
+    if (!file.endsWith(".php")) continue;
+    const content = readFileSafe(path.join(muPluginsDir, file));
+    if (content && /hreflang/i.test(content)) {
+      result.detected = true;
+      result.sources.push(`mu-plugin: ${file}`);
+    }
+  }
+
+  // Check theme files for hreflang
+  const themesDir = path.join(cwd, "wp-content", "themes");
+  const themes = readdirSafe(themesDir);
+  for (const theme of themes) {
+    const headerPhp = readFileSafe(path.join(themesDir, theme, "header.php"));
+    if (headerPhp && /hreflang/i.test(headerPhp)) {
+      result.detected = true;
+      result.sources.push(`theme: ${theme}/header.php`);
+    }
+    const functionsPhp = readFileSafe(path.join(themesDir, theme, "functions.php"));
+    if (functionsPhp && /hreflang/i.test(functionsPhp)) {
+      result.detected = true;
+      result.sources.push(`theme: ${theme}/functions.php`);
+    }
+  }
+
+  // Multilingual plugins typically handle hreflang automatically
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const hreflangPlugins = [
+    { dir: "sitepress-multilingual-cms", name: "WPML (auto hreflang)" },
+    { dir: "polylang", name: "Polylang (auto hreflang)" },
+    { dir: "multilingualpress", name: "MultilingualPress (auto hreflang)" },
+  ];
+  for (const plugin of hreflangPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.sources.push(`plugin: ${plugin.name}`);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect WPLANG configuration
+// ---------------------------------------------------------------------------
+
+function detectWplang(cwd) {
+  const wpConfig = readFileSafe(path.join(cwd, "wp-config.php"));
+  if (!wpConfig) return null;
+
+  const match = wpConfig.match(/define\s*\(\s*['"]WPLANG['"]\s*,\s*['"]([\w_]+)['"]\s*\)/i);
+  return match ? match[1] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const multisite = detectMultisite(cwd);
+  const multilingual = detectMultilingualPlugin(cwd);
+  const languages = detectLanguagePatterns(cwd);
+  const hreflang = detectHreflang(cwd);
+  const wplang = detectWplang(cwd);
+
+  const detected = multisite.is_multisite || multilingual.detected || languages.detected_languages.length > 0;
+
+  const report = {
+    tool: "multilang_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected,
+    is_multisite: multisite.is_multisite,
+    site_count: multisite.site_count,
+    multilingual_plugin: multilingual.plugin,
+    detected_languages: languages.detected_languages,
+    sites: languages.sites,
+    has_hreflang: hreflang.detected,
+    hreflang_sources: hreflang.sources,
+    wplang: wplang,
+    multilang_readiness: "unknown",
+    recommendations: [],
+  };
+
+  // Assess readiness
+  if (multisite.is_multisite && multilingual.detected && hreflang.detected && languages.detected_languages.length >= 2) {
+    report.multilang_readiness = "high";
+  } else if (multisite.is_multisite && (multilingual.detected || languages.detected_languages.length > 0)) {
+    report.multilang_readiness = "medium";
+  } else if (multisite.is_multisite) {
+    report.multilang_readiness = "low";
+  } else {
+    report.multilang_readiness = "not_ready";
+  }
+
+  // Recommendations
+  if (!multisite.is_multisite) {
+    report.recommendations.push("WordPress Multisite is not enabled. Enable Multisite to create per-language sub-sites. See wp-multisite skill.");
+  }
+  if (multisite.is_multisite && !multilingual.detected) {
+    report.recommendations.push("No multilingual plugin detected. Install WPML, Polylang, or MultilingualPress for translation management.");
+  }
+  if (multisite.is_multisite && languages.detected_languages.length === 0) {
+    report.recommendations.push("No language-coded sub-sites detected. Create sub-sites with ISO 639-1 slugs (e.g., /it/, /de/, /fr/).");
+  }
+  if (multisite.is_multisite && !hreflang.detected) {
+    report.recommendations.push("No hreflang tags detected. Install the hreflang mu-plugin or configure your multilingual plugin to generate hreflang.");
+  }
+  if (multisite.is_multisite && multisite.site_count <= 1) {
+    report.recommendations.push("Only one site in the network. Create additional sub-sites for each target language.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(detected ? 0 : 1);
+}
+
+main();

package/skills/wp-multisite/SKILL.md

@@ -90,3 +90,4 @@ For complex multi-step multisite operations, use the `wp-site-manager` agent (wh
 - `wp-wpcli-and-ops` — WP-CLI command reference and multisite flags
 - `wp-security` — Super Admin capabilities and multisite security
 - `wp-deploy` — Deploy to multisite network
+- `wp-multilang-network` — Multi-language network orchestration (hreflang, content sync, international SEO)

package/skills/wp-programmatic-seo/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wp-programmatic-seo
+description: |
+  This skill should be used when the user asks to "generate template pages",
+  "create city pages", "programmatic SEO", "scalable landing pages", "dynamic pages
+  from data", "product variant pages", "location-based SEO", "ISR pages at scale",
+  "bulk page generation", or mentions creating large numbers of pages from templates
+  or data sources using WordPress as content backend.
+version: 1.0.0
+---
+
+## Overview
+
+Programmatic SEO is the systematic generation of large-scale, search-optimized pages from structured data. WordPress serves as the canonical content source (via custom post types, taxonomies, and REST API), while a headless frontend (Next.js, Nuxt, Astro) renders the pages using ISR/SSG for performance and crawlability.
+
+This skill orchestrates existing MCP tools — content CRUD, multisite management, headless architecture — into scalable page generation workflows. No new tools are required.
+
+## When to Use
+
+- User wants to generate 100s–1000s of pages from templates and structured data
+- City/location pages (e.g., "plumber in {city}" for 200 cities)
+- Product variant pages (size/color/model combinations)
+- Comparison pages (product A vs product B)
+- Directory listings from external data (CSV, API)
+- Any `/{entity}/{location}/{variant}` URL pattern at scale
+
+## Programmatic SEO vs Manual Content
+
+| Aspect | Programmatic SEO | Manual Content |
+|--------|-----------------|----------------|
+| Scale | 100s–1000s of pages | 1–50 pages |
+| Consistency | Template-enforced uniformity | Variable quality |
+| Maintenance | Update template → all pages update | Edit each page individually |
+| SEO value | Long-tail keyword coverage | High per-page authority |
+| Setup cost | Higher initial (template + data) | Lower initial, higher ongoing |
+| Content depth | Data-driven, structured | Human-crafted, nuanced |
+
+## Prerequisites / Detection
+
+```bash
+node skills/wp-programmatic-seo/scripts/programmatic_seo_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script checks headless frontend presence, SEO plugins, content volume, custom post types, and WPGraphQL availability.
+
+## Programmatic SEO Operations Decision Tree
+
+1. **What type of programmatic content?**
+
+   - "template pages" / "page templates" / "dynamic templates"
+     → **Template Architecture** — Read: `references/template-architecture.md`
+
+   - "city pages" / "location pages" / "LocalBusiness" / "service area pages"
+     → **Location-Based SEO** — Read: `references/location-seo.md`
+
+   - "product variants" / "filtered pages" / "comparison pages" / "category landing"
+     → **Product Programmatic SEO** — Read: `references/product-seo.md`
+
+   - "data-driven" / "API pages" / "custom endpoint" / "CSV import" / "external data"
+     → **Data-Driven Content** — Read: `references/data-sources.md`
+
+   - "sitemap" / "indexing" / "crawl budget" / "canonical" / "Core Web Vitals"
+     → **Technical SEO** — Read: `references/technical-seo.md`
+
+2. **Common workflow (all types):**
+   1. Assess data source — what structured data exists? (products, locations, categories)
+   2. Design URL pattern — `/{service}/{city}` or `/{product}/{variant}`
+   3. Create CPT or taxonomy in WordPress if needed (via `create_content` MCP tool)
+   4. Build page template with dynamic fields (title, meta, H1, body)
+   5. Generate content in bulk using REST API (loop with `create_content`)
+   6. Configure headless frontend ISR/SSG (reference: template-architecture)
+   7. Generate and submit XML sitemap (reference: technical-seo)
+
+## Recommended Agent
+
+`wp-content-strategist` — handles content strategy, template design, and bulk generation workflows.
+
+## Additional Resources
+
+### Reference Files
+
+| File | Description |
+|------|-------------|
+| **`references/template-architecture.md`** | Page template patterns, URL design, ISR/SSG config, bulk creation |
+| **`references/location-seo.md`** | City/location pages, LocalBusiness schema, geo-targeting |
+| **`references/product-seo.md`** | Product variants, comparison pages, Product schema |
+| **`references/data-sources.md`** | REST API, WPGraphQL, external data, content quality gates |
+| **`references/technical-seo.md`** | Sitemaps, crawl budget, canonicals, internal linking, CWV |
+
+### Related Skills
+
+- `wp-headless` — headless architecture, ISR/SSG, webhooks
+- `wp-multisite` — multisite network for segmented content at scale
+- `wp-woocommerce` — product data as SEO content source
+- `wp-rest-api` — REST API endpoints for content CRUD
+- `wp-content` — content management fundamentals
+- `wp-content-repurposing` — transform existing content into new formats

package/skills/wp-programmatic-seo/references/data-sources.md

@@ -0,0 +1,200 @@
+# Data Sources for Programmatic SEO
+
+Use this file when connecting structured data (WordPress REST API, WPGraphQL, external APIs, CSV imports) to programmatic page generation, including quality gates and freshness strategies.
+
+## WordPress REST API as Data Source
+
+The REST API provides paginated, filterable access to all WordPress content:
+
+### Pagination for Large Datasets
+
+```bash
+# Fetch all posts with pagination (100 per page max)
+GET /wp-json/wp/v2/posts?per_page=100&page=1
+# Check X-WP-TotalPages header for total pages
+
+# Fetch with filters
+GET /wp-json/wp/v2/location?per_page=100&status=publish&orderby=title
+
+# Embed related data (featured image, author, terms)
+GET /wp-json/wp/v2/posts?_embed&per_page=50
+```
+
+### Filtering and Search
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `categories` | Filter by category ID | `?categories=5,12` |
+| `tags` | Filter by tag ID | `?tags=8` |
+| `search` | Full-text search | `?search=miami` |
+| `before`/`after` | Date range | `?after=2024-01-01T00:00:00` |
+| `meta_key`/`meta_value` | Custom field filter (requires plugin) | `?meta_key=city&meta_value=Miami` |
+| `orderby` | Sort: date, title, modified, rand | `?orderby=title&order=asc` |
+
+### Custom REST Fields
+
+Expose CPT meta for programmatic consumption:
+
+```php
+register_rest_field('location', 'seo_data', [
+    'get_callback' => function ($post) {
+        return [
+            'city'        => get_post_meta($post['id'], 'city', true),
+            'state'       => get_post_meta($post['id'], 'state', true),
+            'population'  => (int) get_post_meta($post['id'], 'population', true),
+            'coordinates' => [
+                'lat' => (float) get_post_meta($post['id'], 'lat', true),
+                'lng' => (float) get_post_meta($post['id'], 'lng', true),
+            ],
+        ];
+    },
+]);
+```
+
+## WPGraphQL Queries for Programmatic Content
+
+WPGraphQL is more efficient for complex, nested data fetching:
+
+### Batch Queries with Fragments
+
+```graphql
+fragment LocationFields on Location {
+  id
+  title
+  slug
+  locationMeta {
+    city
+    state
+    population
+    latitude
+    longitude
+  }
+  seo {
+    title
+    metaDesc
+    canonical
+  }
+}
+
+query AllLocations($first: Int!, $after: String) {
+  locations(first: $first, after: $after) {
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      ...LocationFields
+    }
+  }
+}
+```
+
+### Advantages over REST API for Programmatic SEO
+
+| Aspect | REST API | WPGraphQL |
+|--------|----------|-----------|
+| Payload size | Full objects, many unused fields | Only requested fields |
+| Nested data | Multiple requests or `_embed` | Single query with relations |
+| Pagination | Offset-based (slow at high pages) | Cursor-based (consistent speed) |
+| Batch queries | N requests for N types | 1 request with aliases |
+
+## Custom REST Endpoints
+
+Register specialized endpoints for aggregated programmatic data:
+
+```php
+add_action('rest_api_init', function () {
+    register_rest_route('programmatic-seo/v1', '/page-data', [
+        'methods'  => 'GET',
+        'callback' => function ($request) {
+            $type = $request->get_param('type') ?? 'location';
+            $posts = get_posts([
+                'post_type'      => $type,
+                'posts_per_page' => -1,
+                'post_status'    => 'publish',
+            ]);
+            return array_map(function ($post) {
+                return [
+                    'slug'    => $post->post_name,
+                    'title'   => $post->post_title,
+                    'content' => apply_filters('the_content', $post->post_content),
+                    'meta'    => get_post_meta($post->ID),
+                ];
+            }, $posts);
+        },
+        'permission_callback' => '__return_true',
+    ]);
+});
+```
+
+## External Data Integration
+
+### CSV Import → CPT
+
+```bash
+# Workflow:
+# 1. Parse CSV with Node.js or WP-CLI
+# 2. Create WordPress posts via REST API
+
+# WP-CLI approach:
+wp post create --post_type=location --post_title="Plumbing in Miami" \
+  --post_status=publish --meta_input='{"city":"Miami","state":"FL","zip":"33101"}'
+
+# MCP tool approach (in loop):
+create_content(type="location", title="Plumbing in Miami", status="publish",
+  meta={"city": "Miami", "state": "FL", "zip": "33101"})
+```
+
+### API Sync → WordPress
+
+For data from external APIs (property listings, job boards, etc.):
+
+1. **Cron-based sync:** WP-Cron or system cron triggers API fetch + `wp_insert_post()`
+2. **Webhook-based sync:** External service sends webhooks → WordPress receiver updates CPT
+3. **Manual import:** Admin uploads CSV → background job creates/updates posts
+
+## Data Freshness Strategies
+
+| Strategy | Trigger | Use Case |
+|----------|---------|----------|
+| Cron update | Scheduled (hourly/daily) | Price updates, stock changes |
+| Webhook revalidation | External event | Order status, inventory sync |
+| On-demand ISR | Manual admin action | Content corrections, new pages |
+| Build-time SSG | Git push / deploy | Static directories, rarely changing data |
+
+### Webhook-Triggered Revalidation
+
+```javascript
+// Next.js API route for on-demand ISR
+// POST /api/revalidate?secret=TOKEN&path=/services/miami
+export default async function handler(req, res) {
+  if (req.query.secret !== process.env.REVALIDATION_SECRET) {
+    return res.status(401).json({ message: 'Invalid token' });
+  }
+  await res.revalidate(req.query.path);
+  return res.json({ revalidated: true });
+}
+```
+
+## Content Quality Gates
+
+Before publishing programmatic pages, enforce minimum quality standards:
+
+| Gate | Threshold | Action if Fails |
+|------|-----------|-----------------|
+| Word count | >= 300 words | Block publish, flag for review |
+| Required fields | All template vars populated | Block publish, log missing fields |
+| SEO score | Title + meta desc + H1 present | Warning, auto-generate from template |
+| Duplicate check | No existing page with same slug | Skip creation, log duplicate |
+| Image present | Featured image or OG image set | Warning, use category default image |
+| Schema valid | JSON-LD parses without errors | Block publish, fix template |
+
+**Implementation:** Add validation in the bulk creation loop before calling `create_content`.
+
+## Decision Checklist
+
+1. Is REST API or WPGraphQL better for this dataset? → Complex nesting = WPGraphQL; simple = REST
+2. Are all needed fields exposed via API? → Register `rest_field` or GraphQL fields if not
+3. How will data stay fresh? → Choose cron/webhook/ISR based on update frequency
+4. Are quality gates enforced before publish? → Never publish without validation
+5. Can the data source handle bulk queries? → Test pagination at expected scale