claude-plugin-wordpress-manager 2.2.1 → 2.3.0

package/skills/wp-content-attribution/scripts/attribution_inspect.mjs

@@ -0,0 +1,277 @@
+/**
+ * attribution_inspect.mjs — Detect content-commerce attribution readiness.
+ *
+ * Scans for WooCommerce presence, analytics plugins, UTM tracking setup,
+ * content/product volume, and existing order meta with source fields.
+ * Outputs a JSON report to stdout.
+ *
+ * Usage:
+ *   node attribution_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — attribution indicators detected
+ *   1 — no attribution 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 WooCommerce
+// ---------------------------------------------------------------------------
+
+function detectWooCommerce(cwd) {
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  if (statSafe(path.join(pluginsDir, "woocommerce"))?.isDirectory()) return true;
+
+  const composer = readJsonSafe(path.join(cwd, "composer.json"));
+  if (composer) {
+    const allDeps = { ...composer.require, ...composer["require-dev"] };
+    if (allDeps["woocommerce/woocommerce"] || allDeps["wpackagist-plugin/woocommerce"]) return true;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Detect analytics plugins
+// ---------------------------------------------------------------------------
+
+function detectAnalyticsPlugin(cwd) {
+  const result = { detected: false, plugin: null };
+
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const analyticsPlugins = [
+    { dir: "google-analytics-for-wordpress", name: "MonsterInsights" },
+    { dir: "google-site-kit", name: "Google Site Kit" },
+    { dir: "woocommerce-google-analytics-integration", name: "WooCommerce Google Analytics" },
+    { dir: "ga-google-analytics", name: "GA Google Analytics" },
+    { dir: "analytify", name: "Analytify" },
+    { dir: "matomo", name: "Matomo Analytics" },
+  ];
+
+  for (const plugin of analyticsPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.plugin = plugin.name;
+      return result;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect UTM tracking
+// ---------------------------------------------------------------------------
+
+function detectUtmTracking(cwd) {
+  const result = { detected: false, sources: [] };
+
+  // Check mu-plugins for UTM capture
+  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 && /utm_source|utm_campaign|utm_medium/i.test(content)) {
+      result.detected = true;
+      result.sources.push(`mu-plugin: ${file}`);
+    }
+  }
+
+  // Check plugins for UTM tracking
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const utmPlugins = [
+    { dir: "utm-dot-io", name: "UTM.io" },
+    { dir: "campaign-url-builder", name: "Campaign URL Builder" },
+    { dir: "leadin", name: "HubSpot (UTM tracking)" },
+  ];
+
+  for (const plugin of utmPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.sources.push(`plugin: ${plugin.name}`);
+    }
+  }
+
+  // Check theme functions.php for UTM capture
+  const themesDir = path.join(cwd, "wp-content", "themes");
+  const themes = readdirSafe(themesDir);
+  for (const theme of themes) {
+    const functionsPhp = readFileSafe(path.join(themesDir, theme, "functions.php"));
+    if (functionsPhp && /utm_source|utm_campaign/i.test(functionsPhp)) {
+      result.detected = true;
+      result.sources.push(`theme: ${theme}/functions.php`);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect content volume
+// ---------------------------------------------------------------------------
+
+function detectContentVolume(cwd) {
+  const result = { content_count: 0, product_count: 0 };
+
+  const postCount = execSafe("wp post list --post_type=post --post_status=publish --format=count 2>/dev/null", cwd);
+  if (postCount) result.content_count = parseInt(postCount) || 0;
+
+  const productCount = execSafe("wp post list --post_type=product --post_status=publish --format=count 2>/dev/null", cwd);
+  if (productCount) result.product_count = parseInt(productCount) || 0;
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect existing order meta with source fields
+// ---------------------------------------------------------------------------
+
+function detectOrderMeta(cwd) {
+  // Check if any completed orders have UTM meta
+  const orderMeta = execSafe(
+    `wp db query "SELECT COUNT(*) as c FROM $(wp db prefix 2>/dev/null)postmeta WHERE meta_key LIKE '%utm_source%'" --format=csv 2>/dev/null`,
+    cwd
+  );
+
+  if (orderMeta && /\d+/.test(orderMeta)) {
+    const count = parseInt(orderMeta.match(/\d+/)[0]);
+    return count > 0;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const hasWoocommerce = detectWooCommerce(cwd);
+  const analytics = detectAnalyticsPlugin(cwd);
+  const utm = detectUtmTracking(cwd);
+  const volume = detectContentVolume(cwd);
+  const hasOrderMeta = detectOrderMeta(cwd);
+
+  const detected = hasWoocommerce && (analytics.detected || utm.detected || volume.content_count > 0);
+
+  const report = {
+    tool: "attribution_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected,
+    has_woocommerce: hasWoocommerce,
+    analytics_plugin: analytics.plugin,
+    has_utm_tracking: utm.detected,
+    utm_sources: utm.sources,
+    content_count: volume.content_count,
+    product_count: volume.product_count,
+    has_order_attribution_meta: hasOrderMeta,
+    attribution_readiness: "unknown",
+    recommendations: [],
+  };
+
+  // Assess readiness
+  if (hasWoocommerce && utm.detected && analytics.detected && volume.content_count > 10) {
+    report.attribution_readiness = "high";
+  } else if (hasWoocommerce && (utm.detected || analytics.detected) && volume.content_count > 0) {
+    report.attribution_readiness = "medium";
+  } else if (hasWoocommerce && volume.content_count > 0) {
+    report.attribution_readiness = "low";
+  } else {
+    report.attribution_readiness = "not_ready";
+  }
+
+  // Recommendations
+  if (!hasWoocommerce) {
+    report.recommendations.push("WooCommerce not detected. Content-commerce attribution requires WooCommerce for sales data.");
+  }
+  if (hasWoocommerce && !utm.detected) {
+    report.recommendations.push("No UTM tracking detected. Install the UTM capture mu-plugin to link content visits to orders.");
+  }
+  if (hasWoocommerce && !analytics.detected) {
+    report.recommendations.push("No analytics plugin detected. Install MonsterInsights or Google Site Kit for traffic data.");
+  }
+  if (volume.content_count === 0) {
+    report.recommendations.push("No published content found. Create blog posts/content to drive traffic to products.");
+  }
+  if (volume.content_count > 0 && volume.product_count === 0) {
+    report.recommendations.push("Content exists but no products found. Verify WooCommerce products are published.");
+  }
+  if (hasWoocommerce && utm.detected && !hasOrderMeta) {
+    report.recommendations.push("UTM tracking is set up but no order attribution meta found yet. Place a test order to verify.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(detected ? 0 : 1);
+}
+
+main();

package/skills/wp-headless/SKILL.md

@@ -167,3 +167,4 @@ Read: `references/webhooks.md`
 - For REST endpoint development, use the `wp-rest-api` skill
 - For authentication security, use the `wp-security` skill
 - For webhook configuration and management, use the `wp-webhooks` skill
+- For scalable programmatic page generation with ISR/SSG, use the `wp-programmatic-seo` skill

package/skills/wp-i18n/SKILL.md

@@ -168,3 +168,4 @@ Re-run: `node skills/wp-i18n/scripts/i18n_inspect.mjs --cwd=/path`
 - WordPress i18n Handbook: https://developer.wordpress.org/plugins/internationalization/
 - CLDR Plural Rules: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
 - Translator Handbook: https://make.wordpress.org/polyglots/handbook/
+- For multisite multi-language network orchestration (hreflang, content sync, international SEO), use the `wp-multilang-network` skill

package/skills/wp-multilang-network/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: wp-multilang-network
+description: |
+  This skill should be used when the user asks to "set up multilingual site",
+  "multisite per language", "hreflang tags", "international SEO", "translate site
+  network", "language-specific sub-sites", "multi-language WordPress", "localize
+  content across sites", "content translation sync", "geo-targeting",
+  or mentions orchestrating a WordPress Multisite network where each sub-site
+  serves a different language or locale.
+version: 1.0.0
+---
+
+## Overview
+
+Multi-Language Network uses WordPress Multisite to create a coordinated network where each sub-site serves a different language or locale. Content is synchronized across sites via translation plugins or manual workflows, with hreflang tags ensuring search engines serve the correct language variant to users.
+
+This skill orchestrates existing multisite MCP tools (10 tools), the `wp-i18n` skill for translation best practices, and multilingual plugin workflows (WPML, Polylang, MultilingualPress). No new tools are required.
+
+## When to Use
+
+- User needs international presence with 2+ languages
+- "Set up Italian and Spanish versions of our site"
+- "Add hreflang tags across our multisite network"
+- "Translate content and keep translations in sync"
+- "Set up language-specific sub-sites"
+- "Configure international SEO for multiple languages"
+- "Redirect users based on browser language"
+
+## Multi-Language Network vs Single-Site Plugin
+
+| Aspect | Multisite Network | Single-Site Plugin |
+|--------|------------------|-------------------|
+| Scalability | Excellent — independent sites per language | Good for 2–5 languages, complex beyond |
+| SEO control | Full — separate sitemaps, robots.txt, GSC per site | Shared — one sitemap with hreflang |
+| Content independence | Each site can have unique content | All content on one database |
+| Maintenance overhead | Higher — plugins/themes per site (unless network-activated) | Lower — one site to maintain |
+| Performance | Better — smaller DB per language | Can degrade with many languages |
+| Domain flexibility | Subdomains, subdirectories, or separate domains | Subdirectories or query params |
+| Plugin compatibility | Standard WP plugins work per-site | Must be compatible with multilingual plugin |
+
+## Prerequisites
+
+- WordPress Multisite enabled (reference: `wp-multisite` skill)
+- WP-CLI access for network operations
+- Multilingual plugin installed (WPML, Polylang, or MultilingualPress)
+- DNS configured for subdomains or subdirectories
+
+## Prerequisites / Detection
+
+```bash
+node skills/wp-multilang-network/scripts/multilang_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script checks Multisite status, multilingual plugins, sub-site count, language patterns in slugs, hreflang presence, and WPLANG configuration.
+
+## Multi-Language Network Operations Decision Tree
+
+1. **What multi-language task?**
+
+   - "set up multisite per language" / "create language sites" / "network architecture"
+     → **Network Architecture** — Read: `references/network-architecture.md`
+
+   - "hreflang" / "language alternates" / "x-default" / "hreflang tags"
+     → **Hreflang Configuration** — Read: `references/hreflang-config.md`
+
+   - "translate content" / "sync content" / "keep translations in sync" / "translation workflow"
+     → **Content Synchronization** — Read: `references/content-sync.md`
+
+   - "language switcher" / "language detection" / "redirect by language" / "browser language"
+     → **Language Routing** — Read: `references/language-routing.md`
+
+   - "international SEO" / "geo-targeting" / "language sitemaps" / "search console per language"
+     → **International SEO** — Read: `references/seo-international.md`
+
+2. **Common workflow (new multi-language network):**
+   1. Assess current network: `list_sites` + run `multilang_inspect.mjs`
+   2. Create language sub-sites: `ms_create_site` per language (slug = ISO 639-1 code)
+   3. Install and configure multilingual plugin network-wide
+   4. Set up hreflang tags (mu-plugin or plugin)
+   5. Establish content sync workflow (manual or plugin-assisted)
+   6. Configure language routing and switcher widget
+   7. Set up per-language XML sitemaps
+   8. Verify with international SEO checklist
+
+## Recommended Agent
+
+`wp-site-manager` — handles multisite network operations, sub-site management, and cross-site coordination.
+
+## Additional Resources
+
+### Reference Files
+
+| File | Description |
+|------|-------------|
+| **`references/network-architecture.md`** | Subdomain vs subdirectory vs domains, plugin comparison, naming conventions |
+| **`references/hreflang-config.md`** | Hreflang format, mu-plugin auto-generation, validation, common mistakes |
+| **`references/content-sync.md`** | WPML/Polylang/MultilingualPress workflows, translation status tracking |
+| **`references/language-routing.md`** | Browser detection, geo-IP redirect, language switcher, cookie preference |
+| **`references/seo-international.md`** | GSC per language, language sitemaps, schema localization, CDN per region |
+
+### Related Skills
+
+- `wp-multisite` — multisite network management (10 MCP tools)
+- `wp-i18n` — internationalization and localization best practices
+- `wp-headless` — headless frontend with i18n routing (Next.js i18n, Nuxt i18n)
+- `wp-programmatic-seo` — scalable page generation (complement for multi-language SEO)
+- `wp-content` — content management for each language sub-site

package/skills/wp-multilang-network/references/content-sync.md

@@ -0,0 +1,182 @@
+# Content Synchronization
+
+Use this file when establishing content translation and synchronization workflows across a WordPress Multisite network — plugin-specific workflows, manual sync procedures, and translation status tracking.
+
+## Synchronization Strategies
+
+| Strategy | Description | Effort | Best For |
+|----------|-------------|--------|----------|
+| **Manual** | Create content independently per site | High ongoing | Fully independent content |
+| **Semi-automatic** | Create on primary, replicate structure, translate manually | Medium | Shared structure, unique translations |
+| **Fully automatic** | Plugin syncs content, human reviews translation | Low ongoing | High-volume, similar content |
+
+## WPML Network Mode
+
+WPML can operate across multisite with the "WPML for Multisite" add-on:
+
+### Setup
+
+1. Network-activate WPML on all sites
+2. Configure primary language per site (each site = one language)
+3. Enable translation management across network
+
+### Workflow
+
+```
+1. Create content on primary site (e.g., English)
+2. WPML sends content to translation queue
+3. Translator works via WPML Translation Management or XLIFF export
+4. Translated content auto-publishes on target language site
+5. WPML maintains content connections (post ID mapping)
+```
+
+### Key WPML Functions
+
+```php
+// Get translation of a post on another site
+$translated_id = apply_filters('wpml_object_id', $post_id, 'post', false, 'it');
+
+// Get all translations of current post
+$translations = apply_filters('wpml_active_languages', null);
+```
+
+## Polylang for Multisite
+
+Polylang's multisite extension assigns one language per sub-site:
+
+### Setup
+
+1. Install Polylang Pro + Polylang for Multisite
+2. Assign language to each sub-site in Network Admin → Sites → Polylang
+3. Configure which content types are translatable
+
+### Workflow
+
+```
+1. Create post on primary site
+2. Polylang shows "Translate" button for each target language
+3. Click creates a linked draft on the target language site
+4. Translator fills in translation
+5. Publish triggers hreflang auto-generation
+```
+
+### Polylang API
+
+```php
+// Get translation link
+$translation_id = pll_get_post($post_id, 'it');
+
+// Get language of current post
+$language = pll_get_post_language($post_id);
+
+// Set translation relationship
+pll_set_post_language($post_id, 'it');
+```
+
+## MultilingualPress
+
+MultilingualPress is built specifically for WordPress Multisite:
+
+### Setup
+
+1. Install and network-activate MultilingualPress
+2. Go to Network Admin → MultilingualPress → set language per site
+3. Define content relationships between sites
+
+### Workflow
+
+```
+1. Create content on any site in the network
+2. In the editor, MultilingualPress shows "Translation" metabox
+3. Select target sites and either:
+   a. Copy content (for later manual translation)
+   b. Link existing content on target site
+4. MultilingualPress maintains bidirectional content connections
+5. Hreflang tags generated automatically from connections
+```
+
+### Advantages for Multisite
+
+- Native multisite architecture (no complex DB tables like WPML)
+- Each site has its own standard WP database tables
+- Content connections stored as post meta (lightweight)
+- Works with standard WordPress REST API per-site
+
+## Manual Sync Workflow
+
+When no multilingual plugin is used, sync content manually via MCP tools:
+
+```bash
+# 1. Create content on primary site
+switch_site(site_id=1)  # Switch to English site
+create_content(type="post", title="Cactus Water Benefits", slug="cactus-water-benefits",
+  content="...", status="publish")
+
+# 2. Replicate structure on Italian site
+switch_site(site_id=2)  # Switch to Italian site
+create_content(type="post", title="Benefici dell'Acqua di Cactus", slug="cactus-water-benefits",
+  content="[Italian translation]", status="draft")
+
+# 3. Replicate on German site
+switch_site(site_id=3)  # Switch to German site
+create_content(type="post", title="Vorteile von Kaktuswasser", slug="cactus-water-benefits",
+  content="[German translation]", status="draft")
+
+# 4. Switch back to primary
+switch_site(site_id=1)
+```
+
+**Important:** Keep the **slug identical** across all language sites for hreflang matching (the mu-plugin matches by slug).
+
+## Translation Status Tracking
+
+Track the translation state of each content piece:
+
+| Status | Meaning | Visual Indicator |
+|--------|---------|-----------------|
+| `untranslated` | No translation exists on target site | Red dot |
+| `draft` | Translation created but not reviewed | Yellow dot |
+| `pending_review` | Translation complete, awaiting review | Orange dot |
+| `published` | Translation live and approved | Green dot |
+| `outdated` | Source content updated after translation | Blue dot with warning |
+
+### Custom Meta for Tracking
+
+```php
+// On the primary site post, track translation status
+update_post_meta($post_id, '_translation_status_it', 'published');
+update_post_meta($post_id, '_translation_status_de', 'draft');
+update_post_meta($post_id, '_translation_status_fr', 'untranslated');
+
+// When source is updated, mark translations as outdated
+add_action('post_updated', function ($post_id) {
+    $languages = ['it', 'de', 'fr', 'es'];
+    foreach ($languages as $lang) {
+        $current = get_post_meta($post_id, "_translation_status_{$lang}", true);
+        if ($current === 'published') {
+            update_post_meta($post_id, "_translation_status_{$lang}", 'outdated');
+        }
+    }
+});
+```
+
+## Media Library Sharing
+
+By default, each multisite sub-site has its own media library. Options for sharing:
+
+| Approach | Plugin | Description |
+|----------|--------|-------------|
+| **Network Media Library** | Network Media Library plugin | Shared library accessible from all sites |
+| **Global Media** | Network Shared Media plugin | Central media site, others embed |
+| **Manual upload** | None | Upload same images per site (wasteful but independent) |
+
+**Recommendation:** Use Network Media Library for brand assets (logo, product images) that are identical across languages. Allow per-site uploads for language-specific images (localized banners, team photos).
+
+## Decision Checklist
+
+1. Which sync strategy: manual, semi-automatic, or fully automatic? → Match to team size and budget
+2. Is a multilingual plugin chosen and installed? → MultilingualPress for multisite-native; WPML for feature-rich
+3. Are content connections established between sites? → Verify via plugin admin or custom meta
+4. Do translated pages use matching slugs for hreflang? → Audit sample pages
+5. Is translation status tracked? → Custom meta or plugin dashboard
+6. Is the media library shared or per-site? → Shared for brand assets, per-site for localized content