claude-plugin-wordpress-manager 2.2.1 → 2.3.0

package/skills/wp-programmatic-seo/references/template-architecture.md

@@ -0,0 +1,125 @@
+# Template Architecture
+
+Use this file when designing page templates for headless WordPress programmatic SEO — custom post types as data source, URL structure, ISR/SSG configuration, and bulk content creation.
+
+## Custom Post Types as Data Source
+
+WordPress CPTs are the ideal data backbone for programmatic pages:
+
+```php
+// Register a CPT for programmatic content (e.g., locations)
+register_post_type('location', [
+    'public'       => true,
+    'show_in_rest' => true,  // Required for headless access
+    'supports'     => ['title', 'editor', 'custom-fields', 'thumbnail'],
+    'rewrite'      => ['slug' => 'locations'],
+    'has_archive'  => true,
+]);
+```
+
+**Required CPT fields for programmatic SEO:**
+- Title → H1 and `<title>` tag
+- Custom fields → template variables (city, service, price, etc.)
+- Taxonomy → category/tag for clustering
+- Featured image → OG image
+
+## URL Structure Design
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| `/{service}/{city}` | `/plumbing/miami` | Service-area pages |
+| `/{product}/{variant}` | `/shoes/red-size-10` | Product variants |
+| `/{category}/{item}` | `/restaurants/joes-pizza` | Directory listings |
+| `/{brand}/{model}/{year}` | `/toyota/camry/2024` | Multi-attribute pages |
+| `/{topic}/{subtopic}` | `/learn/react-hooks` | Educational content |
+
+**URL rules:**
+- Lowercase, hyphenated slugs
+- Max 3 levels deep (SEO best practice)
+- Include primary keyword in first path segment
+- Avoid query parameters for indexable pages
+
+## ISR Configuration (Headless Frontend)
+
+### Next.js (App Router)
+
+```javascript
+// app/[service]/[city]/page.js
+export async function generateStaticParams() {
+  const res = await fetch(`${WP_API}/wp/v2/location?per_page=100`);
+  const locations = await res.json();
+  return locations.map((loc) => ({
+    service: loc.acf.service_slug,
+    city: loc.slug,
+  }));
+}
+
+export const revalidate = 3600; // ISR: revalidate every hour
+```
+
+### Nuxt
+
+```javascript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/services/**': { isr: 3600 },
+  },
+});
+```
+
+### Astro
+
+```javascript
+// astro.config.mjs — hybrid mode for ISR-like behavior
+export default defineConfig({
+  output: 'hybrid',
+  adapter: node({ mode: 'standalone' }),
+});
+```
+
+**Revalidate intervals by content type:**
+
+| Content Type | Interval | Reason |
+|-------------|----------|--------|
+| Location pages | 3600s (1h) | Rarely change |
+| Product pages | 900s (15m) | Price/stock updates |
+| Blog/guides | 86400s (24h) | Stable content |
+| Comparison pages | 3600s (1h) | Data-driven, periodic |
+
+## Template Variables
+
+A programmatic page template maps CPT fields to HTML:
+
+```
+Title:       "{service_name} in {city_name} — {brand}"
+Meta desc:   "Professional {service_name} in {city_name}. {unique_selling_point}."
+H1:          "{service_name} in {city_name}"
+Body:        Template paragraph using {city_population}, {service_details}, {local_info}
+Schema:      LocalBusiness JSON-LD with {name}, {address}, {phone}, {geo}
+```
+
+**Anti-pattern:** Avoid thin content — each page must have enough unique value to justify indexing. Minimum 300 words of meaningful, varied content per page.
+
+## Bulk Content Creation Workflow
+
+1. **Prepare data:** CSV or JSON with one row per page (city, service, attributes)
+2. **Create CPT entries:** Loop via WordPress REST API:
+
+```bash
+# Using wp-rest-bridge create_content tool
+for each row in data:
+  create_content(type="location", title=row.title, content=row.body, meta=row.fields)
+```
+
+3. **Assign taxonomies:** Tag each entry with relevant terms for clustering
+4. **Generate frontend paths:** Run `generateStaticParams` or equivalent build step
+5. **Verify:** Spot-check 5–10 pages for content quality and schema validity
+
+## Decision Checklist
+
+1. Is the data structured and repeatable? → Yes = proceed with CPT
+2. Will each page have unique, valuable content? → Yes = proceed; No = consolidate
+3. Is the URL pattern SEO-friendly and max 3 levels? → Verify before building
+4. Is ISR/SSG configured with appropriate revalidation? → Match to content freshness
+5. Are sitemaps generated for all programmatic pages? → See `technical-seo.md`

package/skills/wp-programmatic-seo/scripts/programmatic_seo_inspect.mjs

@@ -0,0 +1,264 @@
+/**
+ * programmatic_seo_inspect.mjs — Detect programmatic SEO readiness.
+ *
+ * Scans for headless frontend, SEO plugins, content volume, custom post types,
+ * and WPGraphQL availability to assess readiness for programmatic page generation.
+ * Outputs a JSON report to stdout.
+ *
+ * Usage:
+ *   node programmatic_seo_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — programmatic SEO indicators detected
+ *   1 — no programmatic SEO 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 headless frontend
+// ---------------------------------------------------------------------------
+
+function detectHeadlessFrontend(cwd) {
+  const result = { detected: false, framework: null, location: null };
+
+  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) continue;
+    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 for config files directly
+  const configFiles = [
+    { file: "next.config.js", fw: "Next.js" },
+    { file: "next.config.mjs", fw: "Next.js" },
+    { file: "next.config.ts", fw: "Next.js" },
+    { file: "nuxt.config.ts", fw: "Nuxt" },
+    { file: "nuxt.config.js", fw: "Nuxt" },
+    { file: "astro.config.mjs", fw: "Astro" },
+    { file: "astro.config.ts", fw: "Astro" },
+  ];
+  for (const { file, fw } of configFiles) {
+    if (statSafe(path.join(cwd, file))) {
+      result.detected = true;
+      result.framework = fw;
+      result.location = ".";
+      return result;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect SEO plugins
+// ---------------------------------------------------------------------------
+
+function detectSeoPlugin(cwd) {
+  const result = { detected: false, plugin: null };
+
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  const seoPlugins = [
+    { dir: "wordpress-seo", name: "Yoast SEO" },
+    { dir: "seo-by-rank-math", name: "Rank Math" },
+    { dir: "all-in-one-seo-pack", name: "All in One SEO" },
+    { dir: "the-seo-framework-extension-manager", name: "The SEO Framework" },
+  ];
+
+  for (const plugin of seoPlugins) {
+    if (statSafe(path.join(pluginsDir, plugin.dir))?.isDirectory()) {
+      result.detected = true;
+      result.plugin = plugin.name;
+      return result;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect content counts by type
+// ---------------------------------------------------------------------------
+
+function detectContentCounts(cwd) {
+  const result = { posts: 0, pages: 0, products: 0, custom_post_types: [] };
+
+  // Try WP-CLI for accurate counts
+  const postCount = execSafe("wp post list --post_type=post --post_status=publish --format=count 2>/dev/null", cwd);
+  if (postCount) result.posts = parseInt(postCount) || 0;
+
+  const pageCount = execSafe("wp post list --post_type=page --post_status=publish --format=count 2>/dev/null", cwd);
+  if (pageCount) result.pages = parseInt(pageCount) || 0;
+
+  const productCount = execSafe("wp post list --post_type=product --post_status=publish --format=count 2>/dev/null", cwd);
+  if (productCount) result.products = parseInt(productCount) || 0;
+
+  // Detect custom post types via WP-CLI
+  const cptList = execSafe("wp post-type list --_builtin=0 --format=json 2>/dev/null", cwd);
+  if (cptList) {
+    try {
+      const cpts = JSON.parse(cptList);
+      result.custom_post_types = cpts.map((c) => c.name || c);
+    } catch { /* ignore parse errors */ }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect WPGraphQL
+// ---------------------------------------------------------------------------
+
+function detectWPGraphQL(cwd) {
+  const pluginsDir = path.join(cwd, "wp-content", "plugins");
+  if (statSafe(path.join(pluginsDir, "wp-graphql"))?.isDirectory()) return true;
+
+  const composer = readJsonSafe(path.join(cwd, "composer.json"));
+  if (composer) {
+    const allDeps = { ...composer.require, ...composer["require-dev"] };
+    if (allDeps["wp-graphql/wp-graphql"]) return true;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const headless = detectHeadlessFrontend(cwd);
+  const seo = detectSeoPlugin(cwd);
+  const content = detectContentCounts(cwd);
+  const hasWpgraphql = detectWPGraphQL(cwd);
+  const hasCustomPostTypes = content.custom_post_types.length > 0;
+
+  const detected = headless.detected || seo.detected || hasCustomPostTypes;
+
+  const report = {
+    tool: "programmatic_seo_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected,
+    has_headless_frontend: headless.detected,
+    headless_framework: headless.framework,
+    headless_location: headless.location,
+    seo_plugin: seo.plugin,
+    content_counts: {
+      posts: content.posts,
+      pages: content.pages,
+      products: content.products,
+    },
+    has_custom_post_types: hasCustomPostTypes,
+    custom_post_types: content.custom_post_types,
+    has_wpgraphql: hasWpgraphql,
+    programmatic_seo_readiness: "unknown",
+    recommendations: [],
+  };
+
+  // Assess readiness
+  if (headless.detected && seo.detected && hasCustomPostTypes) {
+    report.programmatic_seo_readiness = "high";
+  } else if (headless.detected || (seo.detected && hasCustomPostTypes)) {
+    report.programmatic_seo_readiness = "medium";
+  } else if (seo.detected) {
+    report.programmatic_seo_readiness = "low";
+  } else {
+    report.programmatic_seo_readiness = "not_ready";
+  }
+
+  // Recommendations
+  if (!headless.detected) {
+    report.recommendations.push("No headless frontend detected. Install Next.js, Nuxt, or Astro for ISR/SSG page rendering.");
+  }
+  if (!seo.detected) {
+    report.recommendations.push("No SEO plugin detected. Install Yoast SEO or Rank Math for sitemap generation and meta management.");
+  }
+  if (!hasCustomPostTypes) {
+    report.recommendations.push("No custom post types found. Create CPTs to serve as structured data sources for programmatic pages.");
+  }
+  if (!hasWpgraphql && headless.detected) {
+    report.recommendations.push("WPGraphQL not installed. Consider it for efficient batch data fetching from headless frontend.");
+  }
+  if (content.posts === 0 && content.pages === 0 && content.products === 0) {
+    report.recommendations.push("No published content found. Create initial content or verify WP-CLI access for accurate counts.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(detected ? 0 : 1);
+}
+
+main();

package/skills/wp-woocommerce/SKILL.md

@@ -109,3 +109,4 @@ For complex multi-step WooCommerce operations, use the `wp-ecommerce-manager` ag
 - `wp-audit` — Audit WooCommerce store security and performance
 - `wp-backup` — Backup WooCommerce database and uploads
 - `wp-webhooks` — WooCommerce webhook management (order/product/customer event notifications)
+- `wp-content-attribution` — Content-commerce attribution, UTM tracking, revenue per content piece