claude-plugin-wordpress-manager 1.4.0

package/skills/wp-interactivity-api/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: wp-interactivity-api
+description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+version: 1.0.0
+source: "WordPress/agent-skills (GPL-2.0-or-later)"
+---
+
+# WP Interactivity API
+
+## When to use
+
+Use this skill when the user mentions:
+
+- Interactivity API, `@wordpress/interactivity`,
+- `data-wp-interactive`, `data-wp-on--*`, `data-wp-bind--*`, `data-wp-context`,
+- block `viewScriptModule` / module-based view scripts,
+- hydration issues or “directives don’t fire”.
+
+## Inputs required
+
+- Repo root + triage output (`wp-project-triage`).
+- Which block/theme/plugin surfaces are affected (frontend, editor, both).
+- Any constraints: WP version, whether modules are supported in the build.
+
+## Procedure
+
+### 1) Detect existing usage + integration style
+
+Search for:
+
+- `data-wp-interactive`
+- `@wordpress/interactivity`
+- `viewScriptModule`
+
+Decide:
+
+- Is this a block providing interactivity via `block.json` view script module?
+- Is this theme-level interactivity?
+- Is this plugin-side “enhance existing markup” usage?
+
+If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:
+
+- `@wordpress/create-block-interactive-template` (via `@wordpress/create-block`)
+
+### 2) Identify the store(s)
+
+Locate store definitions and confirm:
+
+- state shape,
+- actions (mutations),
+- callbacks/event handlers used by `data-wp-on--*`.
+
+### 3) Server-side rendering (best practice)
+
+**Pre-render HTML on the server** before outputting to ensure:
+
+- Correct initial state in the HTML before JavaScript loads (no layout shift).
+- SEO benefits and faster perceived load time.
+- Seamless hydration when the client-side JavaScript takes over.
+
+#### Enable server directive processing
+
+For components using `block.json`, add `supports.interactivity`:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+For themes/plugins without `block.json`, use `wp_interactivity_process_directives()` to process directives.
+
+#### Initialize state/context in PHP
+
+Use `wp_interactivity_state()` to define initial global state:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'hasItems' => true,
+));
+```
+
+For local context, use `wp_interactivity_data_wp_context()`:
+
+```php
+<?php
+$context = array( 'isOpen' => false );
+?>
+<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
+  ...
+</div>
+```
+
+#### Define derived state in PHP
+
+When derived state affects initial HTML rendering, replicate the logic in PHP:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana' ),
+  'hasItems' => function() {
+    $state = wp_interactivity_state();
+    return count( $state['items'] ) > 0;
+  }
+));
+```
+
+This ensures directives like `data-wp-bind--hidden="!state.hasItems"` render correctly on first load.
+
+For detailed examples and patterns, see `references/server-side-rendering.md`.
+
+### 4) Implement or change directives safely
+
+When touching markup directives:
+
+- keep directive usage minimal and scoped,
+- prefer stable data attributes that map clearly to store state,
+- ensure server-rendered markup + client hydration align.
+
+**WordPress 6.9 changes:**
+
+- **`data-wp-ignore` is deprecated** and will be removed in future versions. It broke context inheritance and caused issues with client-side navigation. Avoid using it.
+- **Unique directive IDs**: Multiple directives of the same type can now exist on one element using the `---` separator (e.g., `data-wp-on--click---plugin-a="..."` and `data-wp-on--click---plugin-b="..."`).
+- **New TypeScript types**: `AsyncAction<ReturnType>` and `TypeYield<T>` help with async action typing.
+
+For quick directive reminders, see `references/directives-quickref.md`.
+
+### 5) Build/tooling alignment
+
+Verify the repo supports the required module build path:
+
+- if it uses `@wordpress/scripts`, prefer its conventions.
+- if it uses custom bundling, confirm module output is supported.
+
+### 6) Debug common failure modes
+
+If “nothing happens” on interaction:
+
+- confirm the `viewScriptModule` is enqueued/loaded,
+- confirm the DOM element has `data-wp-interactive`,
+- confirm the store namespace matches the directive’s value,
+- confirm there are no JS errors before hydration.
+
+See `references/debugging.md`.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesInteractivityApi: true` after your change (if applicable).
+- Manual smoke test: directive triggers and state updates as expected.
+- If tests exist: add/extend Playwright E2E around the interaction path.
+
+## Failure modes / debugging
+
+- Directives present but inert:
+  - view script not loading, wrong module entrypoint, or missing `data-wp-interactive`.
+- Hydration mismatch / flicker:
+  - server markup differs from client expectations; simplify or align initial state.
+  - derived state not defined in PHP: use `wp_interactivity_state()` with closures.
+- Initial content missing or wrong:
+  - `supports.interactivity` not set in `block.json` (for blocks).
+  - `wp_interactivity_process_directives()` not called (for themes/plugins).
+  - state/context not initialized in PHP before render.
+- Layout shift on load:
+  - derived state like `state.hasItems` missing on server, causing `hidden` attribute to be absent.
+- Performance regressions:
+  - overly broad interactive roots; scope interactivity to smaller subtrees.
+- Client-side navigation issues (WordPress 6.9):
+  - `getServerState()` and `getServerContext()` now reset between page transitions—ensure your code doesn't assume stale values persist.
+  - Router regions now support `attachTo` for rendering overlays (modals, pop-ups) dynamically.
+
+## Escalation
+
+- If repo build constraints are unclear, ask: "Is this using `@wordpress/scripts` or a custom bundler (webpack/vite)?"
+- Consult:
+  - `references/server-side-rendering.md`
+  - `references/directives-quickref.md`
+  - `references/debugging.md`

package/skills/wp-interactivity-api/references/debugging.md

@@ -0,0 +1,29 @@
+# Debugging checklist
+
+1. Confirm the interactive root exists in the rendered HTML (`data-wp-interactive`).
+2. Confirm the view script module is loaded (network + source maps).
+3. Confirm store namespace matches what markup expects.
+4. Check console for errors before any interaction.
+5. Reduce scope:
+   - temporarily remove directives to isolate which directive/store path breaks.
+6. If hydration mismatch occurs:
+   - ensure initial state/context matches server markup.
+
+## WordPress 6.9 specific issues
+
+**State not persisting across navigation:**
+- `getServerState()` and `getServerContext()` now reset between client-side page transitions.
+- If you relied on stale values persisting, refactor to use the store's reactive state instead.
+
+**Multiple plugins conflicting on same element:**
+- Use unique directive IDs with the `---` separator to avoid attribute collisions.
+- Example: `data-wp-on--click---my-plugin="actions.handle"`
+
+**`data-wp-ignore` not working:**
+- This directive is deprecated in 6.9 and will be removed. It caused context inheritance and navigation bugs.
+- Find an alternative approach (conditional rendering, separate interactive regions).
+
+**Router regions / overlays not rendering:**
+- WordPress 6.9 adds `attachTo` property for router regions to render overlays anywhere on the page.
+- Ensure nested router regions are properly structured.
+

package/skills/wp-interactivity-api/references/directives-quickref.md

@@ -0,0 +1,30 @@
+# Directives quick reference (high level)
+
+Common directives to recognize in markup:
+
+- `data-wp-interactive`: declares an interactive region (and often a store namespace).
+- `data-wp-context`: provides server-rendered context/state.
+- `data-wp-on--event`: attaches event handlers (e.g. `click`, `submit`).
+- `data-wp-on-async--event`: async event handlers (preferred for most actions).
+- `data-wp-bind--attr`: binds DOM attributes to state.
+- `data-wp-class--name`: toggles CSS classes based on state.
+
+Use these as search anchors when triaging bugs.
+
+## Unique directive IDs (WordPress 6.9+)
+
+HTML doesn't allow duplicate attributes. To attach multiple handlers of the same type from different plugins, use the `---` separator:
+
+```html
+<button
+  data-wp-on--click---plugin-a="actions.handleA"
+  data-wp-on--click---plugin-b="actions.handleB"
+>
+```
+
+Both handlers will fire. The ID after `---` must be unique per element.
+
+## Deprecated directive
+
+- **`data-wp-ignore`**: Deprecated in WordPress 6.9. It was intended to prevent hydration of a region but broke context inheritance and client-side navigation. Will be removed in future versions. Avoid using it.
+

package/skills/wp-interactivity-api/references/server-side-rendering.md

@@ -0,0 +1,310 @@
+# Server-Side Rendering for Interactivity API
+
+- **Faster initial render**: HTML arrives ready with correct values.
+- **No layout shift**: Hidden elements stay hidden from the first paint.
+- **SEO benefits**: Search engines see fully rendered content.
+- **Graceful degradation**: Content displays correctly even before JavaScript loads.
+
+## Setup Requirements
+
+### 1. Enable Server Directive Processing
+
+**For components using `block.json`:**
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins without `block.json`:**
+
+Use `wp_interactivity_process_directives()` to manually process directives (see "Themes and Plugins without block.json" section below).
+
+### 2. Initialize Global State with `wp_interactivity_state()`
+
+Define initial state values in PHP before rendering:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'isLoading' => false,
+  'count'     => 3,
+));
+```
+
+The state is serialized and available to client JavaScript automatically.
+
+### 3. Initialize Local Context with `wp_interactivity_data_wp_context()`
+
+For element-scoped context:
+
+```php
+<?php
+$context = array(
+  'isOpen'   => false,
+  'itemId'   => 42,
+  'itemName' => 'Example',
+);
+?>
+<div
+  data-wp-interactive="myPlugin"
+  <?php echo wp_interactivity_data_wp_context( $context ); ?>
+>
+  <button data-wp-on-async--click="actions.toggle">
+    Toggle
+  </button>
+  <div data-wp-bind--hidden="!context.isOpen">
+    Content for <?php echo esc_html( $context['itemName'] ); ?>
+  </div>
+</div>
+```
+
+## Derived State on the Server
+
+When derived state affects the initial HTML, define it in PHP to avoid layout shifts.
+
+### Static Derived State
+
+When the derived value is known at render time:
+
+```php
+$fruits    = array( 'Apple', 'Banana', 'Cherry' );
+$hasFruits = count( $fruits ) > 0;
+
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => $hasFruits,
+));
+```
+
+### Dynamic Derived State (using closures)
+
+When the value depends on context (e.g., inside `data-wp-each` loops):
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'       => array( 'apple', 'banana', 'cherry' ),
+  'shoppingList' => array( 'apple', 'cherry' ),
+  'onShoppingList' => function() {
+    $state   = wp_interactivity_state();
+    $context = wp_interactivity_get_context();
+    return in_array( $context['item'], $state['shoppingList'] ) ? 'Yes' : 'No';
+  },
+));
+```
+
+The closure is evaluated during directive processing for each element.
+
+## Complete Example: List with Server Rendering
+
+### PHP (render callback or template)
+
+```php
+<?php
+$fruits = array( 'Apple', 'Banana', 'Cherry' );
+
+wp_interactivity_state( 'myFruitPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => count( $fruits ) > 0,
+  'mango'     => __( 'Mango' ),
+));
+?>
+
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">
+    <?php esc_html_e( 'Add Mango' ); ?>
+  </button>
+  <button data-wp-on-async--click="actions.clearAll">
+    <?php esc_html_e( 'Clear All' ); ?>
+  </button>
+
+  <ul data-wp-bind--hidden="!state.hasFruits">
+    <template data-wp-each="state.fruits">
+      <li data-wp-text="context.item"></li>
+    </template>
+  </ul>
+
+  <p data-wp-bind--hidden="state.hasFruits">
+    <?php esc_html_e( 'No fruits available.' ); ?>
+  </p>
+</div>
+```
+
+### JavaScript (view.js)
+
+```javascript
+import { store, getContext } from '@wordpress/interactivity';
+
+const { state } = store( 'myFruitPlugin', {
+  state: {
+    get hasFruits() {
+      return state.fruits.length > 0;
+    },
+  },
+  actions: {
+    addMango() {
+      state.fruits.push( state.mango );
+    },
+    clearAll() {
+      state.fruits = [];
+    },
+  },
+});
+```
+
+### Rendered Output (initial HTML)
+
+```html
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">Add Mango</button>
+  <button data-wp-on-async--click="actions.clearAll">Clear All</button>
+
+  <ul>
+    <li>Apple</li>
+    <li>Banana</li>
+    <li>Cherry</li>
+  </ul>
+
+  <p hidden>No fruits available.</p>
+</div>
+```
+
+The `hidden` attribute is added server-side because `state.hasFruits` is true.
+
+## Serializing Values for Client Use
+
+Use `wp_interactivity_state()` to pass server values to client JavaScript:
+
+### Translations
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'labels' => array(
+    'add'    => __( 'Add Item', 'textdomain' ),
+    'remove' => __( 'Remove Item', 'textdomain' ),
+    'empty'  => __( 'No items found', 'textdomain' ),
+  ),
+));
+```
+
+### Ajax URLs and Nonces
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+  'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
+  'restUrl' => rest_url( 'myPlugin/v1/' ),
+));
+```
+
+### Client Usage
+
+```javascript
+const { state } = store( 'myPlugin', {
+  actions: {
+    *fetchData() {
+      const formData = new FormData();
+      formData.append( 'action', 'my_action' );
+      formData.append( '_ajax_nonce', state.nonce );
+
+      const response = yield fetch( state.ajaxUrl, {
+        method: 'POST',
+        body: formData,
+      });
+      return yield response.json();
+    },
+  },
+});
+```
+
+## Themes and Plugins without block.json
+
+For themes or plugins not using `block.json`, use `wp_interactivity_process_directives()`:
+
+```php
+<?php
+wp_interactivity_state( 'myTheme', array(
+  'menuOpen' => false,
+));
+
+ob_start();
+?>
+
+<nav
+  data-wp-interactive="myTheme"
+  data-wp-class--is-open="state.menuOpen"
+>
+  <button data-wp-on-async--click="actions.toggleMenu">
+    Menu
+  </button>
+  <ul data-wp-bind--hidden="!state.menuOpen">
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<?php
+$html = ob_get_clean();
+echo wp_interactivity_process_directives( $html );
+```
+
+Only call `wp_interactivity_process_directives()` once at the outermost template level.
+
+## PHP Helper Functions Reference
+
+| Function | Purpose |
+|----------|---------|
+| `wp_interactivity_state( $namespace, $state )` | Initialize/get global state for a namespace |
+| `wp_interactivity_data_wp_context( $context )` | Generate `data-wp-context` attribute |
+| `wp_interactivity_get_context( $namespace )` | Get current context during directive processing |
+| `wp_interactivity_process_directives( $html )` | Manually process directives (themes/plugins) |
+
+## Common Pitfalls
+
+### Server Directive Processing Not Enabled
+
+**For `block.json` users:** Without `supports.interactivity`, directives are not processed:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins:** Ensure `wp_interactivity_process_directives()` is called on the HTML output.
+
+### Derived State Missing on Server
+
+If `state.hasFruits` is only defined in JavaScript, the `hidden` attribute won't be set:
+
+```html
+<!-- Without server state: shows briefly then hides (layout shift) -->
+<p data-wp-bind--hidden="state.hasFruits">No fruits</p>
+```
+
+### State Not Matching Client Expectations
+
+Ensure PHP and JavaScript derived state logic matches:
+
+```php
+// PHP
+'hasFruits' => count( $fruits ) > 0,
+```
+
+```javascript
+// JavaScript - must match PHP logic
+get hasFruits() {
+  return state.fruits.length > 0;
+}
+```
+
+## External References
+
+- [WordPress: Server-side rendering](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/server-side-rendering/)
+- [WordPress: Understanding global state, local context and derived state](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state/)
+- [WordPress: Interactivity API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/)

package/skills/wp-migrate/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: wp-migrate
+description: This skill should be used when the user asks to "migrate a site", "move
+  WordPress", "transfer my site", "clone site", "copy site to new hosting", or mentions
+  any WordPress migration between hosts or platforms. Covers full site, content-only,
+  and database migrations.
+version: 1.0.0
+---
+
+# WordPress Migration Skill
+
+## Overview
+
+Guides WordPress site migrations between hosting providers, platforms, and environments. Supports full-site, content-only, and staging-to-production migrations.
+
+## When to Use
+
+- User wants to move a WordPress site to new hosting
+- User needs to clone a site for staging/development
+- User wants to migrate from WordPress.com to self-hosted
+- User needs to transfer content between WordPress installations
+- User is consolidating multiple sites
+
+## Migration Decision Tree
+
+1. **What is the source?**
+   - WordPress self-hosted → Full site or content export
+   - WordPress.com → WXR export or WordPress.com MCP
+   - Static site → Fresh WordPress installation + content import
+
+2. **What is the destination?**
+   - Hostinger → Use `hosting_importWordpressWebsite` (preferred)
+   - Other hosting → Use SSH/SFTP transfer
+   - WordPress.com → Content import via WP admin
+
+3. **What scope?**
+   - Full site (files + database + config) → Full migration
+   - Content only (posts, pages, media) → WXR or API transfer
+   - Theme/plugins only → Selective file transfer
+
+## Migration Workflows
+
+### Full Site Migration to Hostinger
+1. **Backup source**: Database dump + wp-content archive
+2. **Prepare archive**: Combine into single zip/tar.gz
+3. **Import**: Use `hosting_importWordpressWebsite` with archive + SQL dump
+4. **DNS update**: Point domain to new hosting
+5. **Verify**: Check site loads correctly on new host
+
+### Content-Only Migration (API-based)
+1. **Connect both sites**: Ensure both are in `WP_SITES_CONFIG`
+2. **Export from source**: Use `list_content` to enumerate all content
+3. **Transform**: Adapt URLs, media references
+4. **Import to destination**: Use `create_content` for each item
+5. **Transfer media**: Download and re-upload media files
+6. **Verify**: Check content integrity and links
+
+### WordPress.com to Self-Hosted
+1. **Export from WordPress.com**: WXR export via wp-admin or WP.com MCP
+2. **Prepare destination**: Fresh WordPress on Hostinger
+3. **Import**: Use WordPress Importer plugin or API
+4. **Redirect**: Set up domain forwarding from WordPress.com
+
+## Pre-Migration Checklist
+
+- [ ] Full backup of source site created and verified
+- [ ] Full backup of destination site (if not empty)
+- [ ] DNS TTL lowered to 300 (5 min) at least 24h before migration
+- [ ] All credentials documented (source + destination)
+- [ ] Plugin list documented (to reinstall if needed)
+- [ ] Custom configuration noted (wp-config.php settings)
+- [ ] SSL certificate ready for new hosting
+- [ ] User informed about expected downtime
+
+## Post-Migration Checklist
+
+- [ ] Site loads on new hosting
+- [ ] All pages and posts accessible
+- [ ] Media files loading correctly
+- [ ] Forms and interactive features working
+- [ ] SSL/HTTPS working
+- [ ] DNS propagation verified
+- [ ] Search and replace for old URLs completed
+- [ ] Caching cleared and rebuilt
+- [ ] Search Console updated with new sitemap
+- [ ] Old hosting cancelled or archived
+
+## Safety
+
+- ALWAYS backup before migration — both source AND destination
+- NEVER delete the source site until migration is fully verified
+- DNS changes take 24-72 hours to propagate worldwide
+- Test the migrated site using hosts file or staging URL before DNS switch
+- Keep source accessible for at least 1 week after migration
+
+## Additional Resources
+
+### Reference Files
+- **`references/hostinger-migration.md`** - Hostinger-specific migration procedures
+- **`references/cross-platform.md`** - Cross-platform migration strategies