claude-plugin-wordpress-manager 1.4.0 → 1.7.0

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();

package/skills/wp-i18n/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: wp-i18n
+description: "Use when internationalizing WordPress plugins or themes: PHP gettext functions (__/esc_html__/etc.), JavaScript i18n (@wordpress/i18n), .pot/.po/.mo translation workflow, WP-CLI i18n commands, RTL stylesheet support, and multilingual plugin setup (Polylang/WPML)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. WP-CLI required for i18n make-pot/make-json."
+version: 1.0.0
+source: "vinmor/wordpress-manager"
+---
+
+# WP i18n
+
+## When to use
+
+- Adding internationalization (i18n) to a WordPress plugin or theme
+- Preparing a plugin or theme for WordPress.org submission (i18n is required)
+- Generating `.pot` template files from source code
+- Adding JavaScript translations via `@wordpress/i18n`
+- Supporting right-to-left (RTL) languages such as Arabic, Hebrew, or Persian
+- Setting up a multilingual WordPress site with Polylang or WPML
+
+## Inputs required
+
+- **Repo root** — path to the plugin or theme project directory
+- **Text domain** — the unique slug used in all gettext calls (matches the plugin/theme slug)
+- **Project kind** — `plugin` or `theme` (determines how text domain is loaded)
+- **Target languages** — locale codes for translations (e.g., `it_IT`, `de_DE`, `ar`)
+- **Whether JS translation is needed** — true if the project has JavaScript files with user-facing strings
+
+## Procedure
+
+### 0) Detect i18n status
+
+Run the detection script to assess the current state of internationalization:
+
+```bash
+node skills/wp-i18n/scripts/i18n_inspect.mjs --cwd=/path/to/project
+node skills/wp-project-triage/scripts/detect_wp_project.mjs
+```
+
+The i18n inspection script outputs JSON with:
+- `textDomain` — the text domain declared in the plugin/theme header
+- `phpI18n` — count and distribution of PHP gettext function usage
+- `jsI18n` — whether `@wordpress/i18n` is installed and configured
+- `translationFiles` — existing .pot, .po, .mo, and .json files
+- `issues[]` — problems found with severity and suggested fixes
+
+If the project has no i18n at all, start from step 1. If partial i18n exists, jump to the step that addresses the gaps.
+
+### 1) PHP internationalization
+
+Wrap all user-facing strings in PHP files with the appropriate gettext function:
+
+| Function | Use case |
+|----------|----------|
+| `__('text', 'domain')` | Return translated string |
+| `_e('text', 'domain')` | Echo translated string |
+| `esc_html__('text', 'domain')` | Return translated + HTML-escaped |
+| `esc_html_e('text', 'domain')` | Echo translated + HTML-escaped |
+| `esc_attr__('text', 'domain')` | Return translated + attribute-escaped |
+| `_n('single', 'plural', $count, 'domain')` | Pluralization |
+| `_x('text', 'context', 'domain')` | Disambiguation context |
+| `sprintf(__('Hello %s', 'domain'), $name)` | Variable substitution |
+
+Key rules:
+- The text domain **must** match the `Text Domain:` header in the main plugin file or `style.css`
+- Never pass variables as the first argument — strings must be literal for extraction
+- Use `sprintf()` / `printf()` for dynamic content, never string concatenation
+- Load the text domain: `load_plugin_textdomain()` on `init` or `load_theme_textdomain()` on `after_setup_theme`
+
+Read: `references/php-i18n.md`
+
+### 2) JavaScript internationalization
+
+For JavaScript files with user-facing strings, use `@wordpress/i18n`:
+
+```js
+import { __, _n, _x, sprintf } from '@wordpress/i18n';
+const label = __('Save Changes', 'my-plugin');
+```
+
+Setup requires:
+1. Add `@wordpress/i18n` as a dependency (or use `wp-scripts` which includes it)
+2. Register script translations in PHP via `wp_set_script_translations()`
+3. Generate JSON translation files from `.po` files via `wp i18n make-json`
+4. For blocks, set the `textdomain` field in `block.json`
+
+Read: `references/js-i18n.md`
+
+### 3) Translation file workflow
+
+The WordPress translation pipeline has four file types:
+
+1. **`.pot`** — Template with all extractable strings (generated, never edited manually)
+2. **`.po`** — Per-locale translations (human-edited or via Poedit/GlotPress)
+3. **`.mo`** — Compiled binary for PHP runtime (generated from `.po`)
+4. **`.json`** — Compiled translations for JavaScript (generated from `.po`)
+
+File naming: `{text-domain}-{locale}.{po|mo}` (e.g., `my-plugin-it_IT.po`)
+
+Workflow: extract → `.pot` → create/update `.po` → compile `.mo` + `.json`
+
+Read: `references/translation-workflow.md`
+
+### 4) WP-CLI i18n commands
+
+```bash
+wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
+wp i18n make-json languages/ --no-purge
+wp i18n make-mo languages/
+wp i18n update-po languages/my-plugin.pot languages/
+```
+
+Integrate into `package.json`:
+```json
+{
+  "scripts": {
+    "i18n:pot": "wp i18n make-pot . languages/my-plugin.pot",
+    "i18n:json": "wp i18n make-json languages/ --no-purge",
+    "i18n:mo": "wp i18n make-mo languages/",
+    "i18n:build": "npm run i18n:pot && npm run i18n:mo && npm run i18n:json"
+  }
+}
+```
+
+Read: `references/wpcli-i18n.md`
+
+### 5) RTL support
+
+WordPress auto-loads `style-rtl.css` when the locale is RTL:
+- Use CSS logical properties (`margin-inline-start` vs `margin-left`)
+- Use `@wordpress/scripts` with `rtlcss` to auto-generate RTL stylesheets
+- Use `is_rtl()` in PHP for conditional logic
+- Test with an RTL locale (Arabic `ar` or Hebrew `he_IL`)
+
+Read: `references/rtl-support.md`
+
+### 6) Multilingual site setup
+
+For content translation (not just UI strings):
+- **Polylang** (free) — `pll_register_string()`, `pll__()`, `pll_e()`
+- **WPML** (paid) — `wpml-config.xml` for custom post types and taxonomies
+- Both require hreflang tags and a language switcher
+
+Read: `references/multilingual-setup.md`
+
+## Verification
+
+- `.pot` file generates without errors: `wp i18n make-pot . languages/<domain>.pot`
+- Translations load in the UI: switch locale and confirm translated strings
+- RTL renders correctly: switch to Arabic and check layout
+- Text domain matches: `Text Domain:` header matches domain in all gettext calls
+- JS translations work: `wp.i18n.__()` returns translated strings in browser console
+- No untranslated strings: search for hardcoded user-facing strings
+
+Re-run: `node skills/wp-i18n/scripts/i18n_inspect.mjs --cwd=/path`
+
+## Failure modes / debugging
+
+- **Translations not loading** — `load_plugin_textdomain()` missing or called on wrong hook; `languages/` path incorrect
+- **Wrong text domain** — domain in gettext calls must exactly match `Text Domain:` header
+- **JS translations missing** — `wp_set_script_translations()` must be called after `wp_enqueue_script()`; JSON files must exist with correct handle-based naming
+- **`.mo` not found** — file must follow `{domain}-{locale}.mo` naming convention
+- **Plural forms broken** — verify `Plural-Forms` header in `.po` matches target language
+- **`make-pot` misses strings** — strings with variables or concatenation cannot be extracted; refactor to literals with `sprintf()`
+- **RTL layout broken** — hardcoded `left`/`right` in CSS; use logical properties or `rtlcss`
+
+## Escalation
+
+- 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/

package/skills/wp-i18n/references/js-i18n.md

@@ -0,0 +1,201 @@
+# JavaScript Internationalization
+
+Use this file when internationalizing JavaScript code in WordPress blocks, plugins, and themes.
+
+## @wordpress/i18n package
+
+### Installation
+
+```bash
+npm install @wordpress/i18n
+```
+
+### Core functions
+
+```js
+import { __, _x, _n, _nx, sprintf } from '@wordpress/i18n';
+
+// Simple translation
+const label = __('Save', 'my-text-domain');
+
+// With context
+const post = _x('Post', 'verb', 'my-text-domain');
+
+// Plurals
+const message = sprintf(
+    _n('%d item', '%d items', count, 'my-text-domain'),
+    count
+);
+
+// Plurals with context
+const posts = sprintf(
+    _nx('%d post', '%d posts', count, 'blog posts', 'my-text-domain'),
+    count
+);
+```
+
+### sprintf for variable substitution
+
+```js
+import { __, sprintf } from '@wordpress/i18n';
+
+// Positional placeholders
+const text = sprintf(
+    /* translators: 1: product name, 2: price */
+    __('%1$s costs %2$s', 'my-text-domain'),
+    productName,
+    price
+);
+
+// %s placeholder
+const greeting = sprintf(
+    /* translators: %s: user name */
+    __('Hello, %s!', 'my-text-domain'),
+    userName
+);
+```
+
+## Block editor (Gutenberg) usage
+
+### Block registration
+
+```js
+import { registerBlockType } from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+
+registerBlockType('my-plugin/my-block', {
+    title: __('My Block', 'my-text-domain'),
+    description: __('A custom block.', 'my-text-domain'),
+    keywords: [
+        __('example', 'my-text-domain'),
+        __('custom', 'my-text-domain'),
+    ],
+    // ...
+});
+```
+
+### InspectorControls
+
+```js
+import { InspectorControls } from '@wordpress/block-editor';
+import { PanelBody, ToggleControl } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+<InspectorControls>
+    <PanelBody title={__('Settings', 'my-text-domain')}>
+        <ToggleControl
+            label={__('Show title', 'my-text-domain')}
+            help={__('Toggle the title visibility.', 'my-text-domain')}
+            checked={showTitle}
+            onChange={(val) => setAttributes({ showTitle: val })}
+        />
+    </PanelBody>
+</InspectorControls>
+```
+
+## Translation file loading
+
+### For blocks (block.json method — recommended)
+
+```json
+{
+    "name": "my-plugin/my-block",
+    "title": "My Block",
+    "textdomain": "my-text-domain"
+}
+```
+
+WordPress automatically loads translation files for blocks with `textdomain` in `block.json`.
+
+### For non-block scripts
+
+Register script translations in PHP:
+
+```php
+add_action('init', function() {
+    wp_set_script_translations(
+        'my-script-handle',    // Same handle used in wp_register_script
+        'my-text-domain',
+        plugin_dir_path(__FILE__) . 'languages'
+    );
+});
+```
+
+### Translation file format
+
+JS translations use JSON (JED format). Generated by WP-CLI:
+
+```bash
+wp i18n make-json languages/ --no-purge
+```
+
+Output files: `my-text-domain-{locale}-{md5hash}.json`
+
+## block.json translatable fields
+
+These fields are automatically translated when `textdomain` is set:
+
+```json
+{
+    "title": "My Block",
+    "description": "Block description here.",
+    "keywords": ["example", "demo"],
+    "styles": [
+        { "name": "default", "label": "Default" },
+        { "name": "fancy", "label": "Fancy" }
+    ],
+    "variations": [
+        {
+            "name": "wide",
+            "title": "Wide",
+            "description": "Wide layout variation."
+        }
+    ],
+    "textdomain": "my-text-domain"
+}
+```
+
+## Common mistakes
+
+### Do NOT use template literals for translation keys
+
+```js
+// WRONG — extraction tools cannot parse
+const text = __(`Hello ${name}`, 'my-text-domain');
+
+// CORRECT
+const text = sprintf(__('Hello %s', 'my-text-domain'), name);
+```
+
+### Do NOT use dynamic text domains
+
+```js
+// WRONG
+const text = __(message, domain);
+
+// CORRECT — literal string only
+const text = __('Hello', 'my-text-domain');
+```
+
+### Do NOT concatenate inside translation calls
+
+```js
+// WRONG
+const text = __('Total: ' + count + ' items', 'my-text-domain');
+
+// CORRECT
+const text = sprintf(__('Total: %d items', 'my-text-domain'), count);
+```
+
+## Verification
+
+```bash
+# Generate POT from JS files
+wp i18n make-pot . languages/my-text-domain.pot --include="src/**/*.js,src/**/*.jsx"
+
+# Generate JSON translation files
+wp i18n make-json languages/ --no-purge
+
+# Check for untranslated strings in JS
+grep -rn "['\"]\`" --include="*.js" --include="*.jsx" src/ | grep -v "__\|_x\|_n\|sprintf"
+```