claude-plugin-wordpress-manager 1.8.0 → 1.9.0

package/skills/wp-multisite/references/migration-multisite.md

@@ -0,0 +1,76 @@
+# Migration: Single-site to Multisite and Back
+
+Migrating between single-site and multisite WordPress installations requires careful planning due to database structure differences.
+
+## Single-site to Multisite
+
+### Prerequisites
+- WordPress installed at domain root (not a subdirectory)
+- All plugins deactivated
+- Permalink structure using "pretty permalinks" (not plain)
+- Full database and file backup
+
+### Procedure
+
+1. **Backup**: Full database dump + wp-content directory
+2. **Deactivate all plugins** via wp-admin or wp-cli
+3. **Enable multisite**: Add `define('WP_ALLOW_MULTISITE', true);` to wp-config.php
+4. **Network Setup**: Navigate to Tools > Network Setup, choose sub-directory or sub-domain
+5. **Apply configuration**: Copy generated code to wp-config.php and .htaccess
+6. **Re-login**: WordPress redirects to login — sign in as Super Admin
+7. **Re-activate plugins**: One by one, test each plugin for multisite compatibility
+8. **Verify**: Check permalink structure, media uploads, and user roles
+
+### What Changes in the Database
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Tables | `wp_posts`, `wp_options`, ... | Same (become site 1) |
+| New tables | — | `wp_blogs`, `wp_site`, `wp_sitemeta`, `wp_registration_log`, `wp_signups` |
+| Options | `wp_options` | `wp_options` (site 1) + `wp_sitemeta` (network) |
+
+## Multisite to Single-site
+
+This migration is more complex because you need to extract one sub-site from the network.
+
+### Procedure (extract sub-site)
+
+1. **Backup**: Full database dump + wp-content directory
+2. **Export content**: Use WordPress Export (Tools > Export) on the target sub-site
+3. **Fresh WordPress install**: Install a clean single-site WordPress
+4. **Import content**: Use WordPress Importer plugin
+5. **Copy uploads**: Copy `wp-content/uploads/sites/{blog_id}/` to `wp-content/uploads/`
+6. **Activate theme and plugins**: Install and activate the same theme and plugins
+7. **Verify**: Check media URLs, internal links, shortcodes
+
+### Alternative: Direct Database Extraction
+
+For large sites where export/import is impractical:
+
+1. Export tables with prefix `wp_{blog_id}_` (e.g., `wp_2_posts`, `wp_2_options`)
+2. Rename tables to standard prefix (e.g., `wp_2_posts` → `wp_posts`)
+3. Update `siteurl` and `home` in `wp_options`
+4. Search-replace old URLs in content
+5. Remove multisite constants from wp-config.php
+6. Update .htaccess to standard WordPress rules
+
+## WP-CLI Migration Commands
+
+```bash
+# Export single site from multisite
+wp db export site-backup.sql --url=subsite.example.com
+
+# Search-replace URLs after migration
+wp search-replace 'subsite.example.com' 'newdomain.com' --all-tables
+
+# Export content as WXR
+wp export --url=subsite.example.com --dir=/tmp/exports/
+```
+
+## Tips and Gotchas
+
+- **Media paths**: Multisite stores uploads in `uploads/sites/{blog_id}/`. After migration to single-site, media URLs need search-replace.
+- **User roles**: Users may have different roles on different sub-sites. When extracting, only the target site's role assignments transfer.
+- **Plugins**: Some plugins store network-wide options in `wp_sitemeta`. These are lost when extracting to single-site.
+- **Test first**: Always perform migration on a staging environment before production.
+- **Backup twice**: Keep backups of both the source (multisite) and target (single-site) before starting.

package/skills/wp-multisite/references/network-plugins.md

@@ -0,0 +1,66 @@
+# Network Plugins and Themes
+
+In WordPress Multisite, plugins and themes can be managed at the network level (Super Admin) or at the individual site level (Site Admin). Understanding the activation modes prevents conflicts.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_network_plugins` | List all plugins with network activation status |
+| `ms_network_activate_plugin` | Activate a plugin across the entire network |
+| `ms_network_deactivate_plugin` | Deactivate a plugin from the entire network |
+
+## Plugin Activation Modes
+
+| Mode | Who Controls | Scope | Use Case |
+|------|-------------|-------|----------|
+| Network-activated | Super Admin | All sites | Security plugins, caching, essential functionality |
+| Per-site activated | Site Admin | One site | Site-specific features |
+| Must-use (mu-plugins) | Developer | All sites, always on | Core business logic, cannot be deactivated |
+
+## Procedures
+
+### Network-Activate a Plugin
+
+1. `ms_network_activate_plugin` with the plugin slug
+2. The plugin immediately activates on ALL sub-sites
+3. Site Admins cannot deactivate a network-activated plugin
+
+### Network-Deactivate a Plugin
+
+1. `ms_network_deactivate_plugin` with the plugin slug
+2. The plugin deactivates on ALL sub-sites simultaneously
+3. Per-site activation state is lost
+
+### Check Plugin Status
+
+1. `ms_list_network_plugins` — returns all plugins with their status
+2. Look for `network_only: true` in the response for network-activated plugins
+
+## Theme Management
+
+Themes in multisite work differently from plugins:
+
+| Action | Level | Effect |
+|--------|-------|--------|
+| Network Enable | Super Admin | Theme becomes available for site admins to activate |
+| Network Disable | Super Admin | Theme removed from site admin's theme list |
+| Activate | Site Admin | Theme becomes active for that specific site |
+
+A theme must be **network-enabled** before any site admin can use it.
+
+## Must-Use Plugins
+
+- Location: `wp-content/mu-plugins/`
+- Always active on ALL sites — cannot be deactivated via UI
+- Loaded before regular plugins
+- No activation hooks (code runs immediately)
+- Useful for: custom login, security rules, performance optimizations
+
+## Tips and Gotchas
+
+- **Network activation is immediate**: No confirmation dialog. All sites are affected instantly.
+- **Plugin conflicts**: A network-activated plugin may conflict with per-site plugins. Test thoroughly.
+- **Updates**: Plugin updates on multisite affect all sites. Test in staging first.
+- **Memory**: Each network-activated plugin increases memory usage across all sites.
+- **Drop-in replacements**: `object-cache.php`, `advanced-cache.php`, `db.php` are shared across all sites.

package/skills/wp-multisite/references/network-setup.md

@@ -0,0 +1,69 @@
+# Network Setup
+
+WordPress Multisite allows a single WordPress installation to host multiple websites (sub-sites) sharing the same codebase and database. Understanding the setup options is critical for architecture decisions.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_get_network_settings` | View current network configuration |
+
+## Sub-directory vs Sub-domain
+
+| Mode | URL Pattern | Example | Requirements |
+|------|------------|---------|-------------|
+| Sub-directory | `example.com/site1/` | `example.com/blog/` | Default, works everywhere |
+| Sub-domain | `site1.example.com` | `blog.example.com` | Wildcard DNS (`*.example.com`), wildcard SSL |
+
+Decision factors:
+- **Sub-directory**: simpler DNS, single SSL cert, better for related sites
+- **Sub-domain**: each site feels independent, better for unrelated brands
+
+## wp-config.php Constants
+
+Required constants for multisite (set during network installation):
+
+```php
+define('WP_ALLOW_MULTISITE', true);     // Step 1: enables Network Setup menu
+define('MULTISITE', true);               // Step 2: after network creation
+define('SUBDOMAIN_INSTALL', false);      // true for sub-domain, false for sub-directory
+define('DOMAIN_CURRENT_SITE', 'example.com');
+define('PATH_CURRENT_SITE', '/');
+define('SITE_ID_CURRENT_SITE', 1);
+define('BLOG_ID_CURRENT_SITE', 1);
+```
+
+## Installation Procedure
+
+1. Start with a fresh single-site WordPress installation
+2. Add `define('WP_ALLOW_MULTISITE', true);` to wp-config.php
+3. Navigate to Tools > Network Setup in wp-admin
+4. Choose sub-directory or sub-domain
+5. WordPress generates the remaining constants and .htaccess rules
+6. Add the generated code to wp-config.php and .htaccess
+7. Log in again — Network Admin menu appears
+
+## .htaccess Rules (sub-directory mode)
+
+```apache
+RewriteEngine On
+RewriteBase /
+RewriteRule ^index\.php$ - [L]
+
+# add a trailing slash to /wp-admin
+RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]
+
+RewriteCond %{REQUEST_FILENAME} -f [OR]
+RewriteCond %{REQUEST_FILENAME} -d
+RewriteRule ^ - [L]
+RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]
+RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\.php)$ $2 [L]
+RewriteRule . index.php [L]
+```
+
+## Tips and Gotchas
+
+- **Cannot switch modes**: You cannot change from sub-directory to sub-domain (or vice versa) after network creation without a fresh install or complex migration.
+- **Existing content**: If the single site already has content, sub-directory mode may conflict with existing page slugs.
+- **SSL**: Sub-domain mode requires wildcard SSL (`*.example.com`). Let's Encrypt supports wildcard via DNS-01 challenge.
+- **WP_ALLOW_MULTISITE vs MULTISITE**: `WP_ALLOW_MULTISITE` enables the setup UI; `MULTISITE` activates the network. They are different constants.

package/skills/wp-multisite/references/site-management.md

@@ -0,0 +1,67 @@
+# Site Management
+
+Sub-site lifecycle in a WordPress Multisite network: creating, configuring, activating/deactivating, and deleting sites.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_sites` | List all sub-sites with status |
+| `ms_get_site` | Get details of a specific sub-site |
+| `ms_create_site` | Create a new sub-site |
+| `ms_activate_site` | Activate or deactivate a sub-site |
+| `ms_delete_site` | Permanently delete a sub-site |
+
+## Sub-site Lifecycle
+
+```
+Create → Active → [Deactivate → Archived/Spam/Deleted]
+                 → [Delete permanently]
+```
+
+## Common Procedures
+
+### List All Sub-sites
+
+1. `ms_list_sites` — returns blog_id, url, registered date, status for all sites
+2. Review the `archived`, `spam`, `deleted` flags for each
+
+### Create a New Sub-site
+
+1. `ms_create_site` with slug, title, admin email
+2. WordPress creates the sub-site with default theme and plugins
+3. The specified email becomes the sub-site admin
+
+### Deactivate a Sub-site
+
+1. `ms_activate_site` with `active: false` and the target blog_id
+2. Deactivated sites return a "This site has been archived" message to visitors
+3. Content and settings are preserved
+
+### Delete a Sub-site
+
+1. `ms_delete_site` with blog_id and `confirm: true`
+2. **Permanent**: removes all content, settings, and uploads for that sub-site
+3. Database tables for the sub-site are dropped
+
+## Site Properties
+
+| Property | Description |
+|----------|-------------|
+| `blog_id` | Unique numeric identifier |
+| `domain` | Domain name of the sub-site |
+| `path` | URL path (e.g., `/blog/` in sub-directory mode) |
+| `registered` | Creation timestamp |
+| `last_updated` | Last modification timestamp |
+| `public` | Whether the site appears in search results |
+| `archived` | Manually archived by network admin |
+| `spam` | Marked as spam |
+| `deleted` | Soft-deleted (not permanently removed) |
+
+## Tips and Gotchas
+
+- **Blog ID 1**: The main site always has `blog_id: 1`. Do not delete it.
+- **Uploads**: Each sub-site has its own uploads directory under `wp-content/uploads/sites/{blog_id}/`.
+- **Database tables**: Each sub-site gets its own set of tables with prefix `wp_{blog_id}_` (e.g., `wp_2_posts`, `wp_2_options`).
+- **Default content**: New sub-sites get a "Hello World" post and sample page, similar to a fresh WordPress install.
+- **Themes**: Sub-sites can only use themes that are network-enabled or network-activated. See `network-plugins.md`.

package/skills/wp-multisite/references/user-roles.md

@@ -0,0 +1,73 @@
+# User Roles in Multisite
+
+WordPress Multisite adds a Super Admin role above the standard role hierarchy. Users can have different roles on different sub-sites within the same network.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `ms_list_super_admins` | List all Super Admin users in the network |
+
+## Role Hierarchy
+
+| Role | Scope | Key Capabilities |
+|------|-------|-----------------|
+| Super Admin | Entire network | All capabilities on all sites, network settings, site CRUD |
+| Administrator | Single site | Full control of one sub-site (cannot install plugins/themes) |
+| Editor | Single site | Manage and publish all posts on one site |
+| Author | Single site | Publish own posts |
+| Contributor | Single site | Write drafts, cannot publish |
+| Subscriber | Single site | Read-only access |
+
+## Super Admin vs Administrator (Multisite)
+
+| Capability | Super Admin | Site Administrator |
+|-----------|-------------|-------------------|
+| Install plugins | Yes | No |
+| Install themes | Yes | No |
+| Create/delete sub-sites | Yes | No |
+| Network activate plugins | Yes | No |
+| Edit wp-config.php | Yes | No |
+| Manage network settings | Yes | No |
+| Edit files (theme/plugin editor) | Yes | No (disabled by default) |
+| Manage site users | Yes | Yes (own site only) |
+| Manage site options | Yes | Yes (own site only) |
+
+## User Registration Modes
+
+Network-wide setting (Network Admin > Settings):
+
+| Mode | Description |
+|------|-------------|
+| Registration disabled | No one can register |
+| User accounts may be registered | Users can register but not create sites |
+| Logged-in users may register new sites | Existing users can create sub-sites |
+| Both user accounts and sites can be registered | Open registration for users and sites |
+
+## Common Operations
+
+### List Super Admins
+1. `ms_list_super_admins` — returns usernames with super admin status
+
+### Add Super Admin (via wp-cli)
+```bash
+wp super-admin add username
+```
+
+### Remove Super Admin (via wp-cli)
+```bash
+wp super-admin remove username
+```
+
+### Add User to Sub-site (via wp-cli)
+```bash
+wp user set-role username editor --url=site1.example.com
+```
+
+## Tips and Gotchas
+
+- **Super Admin bypass**: Super Admins bypass all capability checks. Use this role sparingly.
+- **User exists once**: A user account exists once in the network but can have different roles on different sub-sites.
+- **Cannot demote yourself**: The last Super Admin cannot remove their own super admin status.
+- **wp-admin vs network-admin**: Super Admins see both site-level wp-admin and network-level wp-admin/network/.
+- **Plugin capability checks**: Plugins using `current_user_can()` should work correctly with multisite, but some older plugins may not distinguish Super Admin from site Administrator.

package/skills/wp-multisite/scripts/multisite_inspect.mjs

@@ -0,0 +1,160 @@
+/**
+ * multisite_inspect.mjs — Detect WordPress Multisite configuration.
+ *
+ * Scans for multisite indicators: wp-config.php constants, WP_SITES_CONFIG flags,
+ * sunrise.php (domain mapping), .htaccess multisite rewrite rules.
+ *
+ * Usage:
+ *   node multisite_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — multisite indicators found
+ *   1 — no multisite indicators found
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, env, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectWpConfig(cwd) {
+  const paths = [
+    join(cwd, 'wp-config.php'),
+    join(cwd, '../wp-config.php'),  // wp-config one level up (common setup)
+  ];
+
+  for (const p of paths) {
+    const content = readFileSafe(p);
+    if (!content) continue;
+
+    const multisite = /define\s*\(\s*['"]MULTISITE['"]\s*,\s*true\s*\)/i.test(content);
+    const subdomain = content.match(/define\s*\(\s*['"]SUBDOMAIN_INSTALL['"]\s*,\s*(true|false)\s*\)/i);
+    const domain = content.match(/define\s*\(\s*['"]DOMAIN_CURRENT_SITE['"]\s*,\s*['"]([^'"]+)['"]\s*\)/i);
+    const pathMatch = content.match(/define\s*\(\s*['"]PATH_CURRENT_SITE['"]\s*,\s*['"]([^'"]+)['"]\s*\)/i);
+
+    if (multisite) {
+      return {
+        found: true,
+        path: p,
+        subdomain_install: subdomain ? subdomain[1] === 'true' : null,
+        domain_current_site: domain ? domain[1] : null,
+        path_current_site: pathMatch ? pathMatch[1] : null,
+      };
+    }
+  }
+  return null;
+}
+
+function detectSitesConfig() {
+  const sitesJson = env.WP_SITES_CONFIG;
+  if (!sitesJson) return null;
+  try {
+    const sites = JSON.parse(sitesJson);
+    const msSites = sites.filter(s => s.is_multisite === true);
+    const cliSites = sites.filter(s => s.wp_path);
+    return {
+      multisite_sites: msSites.map(s => ({
+        id: s.id,
+        wp_path: s.wp_path || null,
+        ssh_host: s.ssh_host || null,
+        has_wpcli: !!s.wp_path,
+      })),
+      cli_ready_sites: cliSites.map(s => s.id),
+      count: msSites.length,
+    };
+  } catch { return null; }
+}
+
+function detectSunrise(cwd) {
+  const paths = [
+    join(cwd, 'wp-content/sunrise.php'),
+    join(cwd, 'sunrise.php'),
+  ];
+  for (const p of paths) {
+    if (existsSafe(p)) {
+      return { found: true, path: p };
+    }
+  }
+  return null;
+}
+
+function detectHtaccessMultisite(cwd) {
+  const content = readFileSafe(join(cwd, '.htaccess'));
+  if (!content) return null;
+
+  // WordPress multisite .htaccess has specific rewrite rules
+  const hasMultisiteRules = /RewriteRule\s+\.\s+index\.php/i.test(content) &&
+    (/upload/.test(content) || /files/.test(content) || /blogs\.dir/.test(content));
+
+  return hasMultisiteRules ? { found: true } : null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const wpConfig = detectWpConfig(cwd);
+  const sitesConfig = detectSitesConfig();
+  const sunrise = detectSunrise(cwd);
+  const htaccess = detectHtaccessMultisite(cwd);
+
+  const signals = [];
+  if (wpConfig) signals.push('wp_config_multisite');
+  if (sitesConfig?.count > 0) signals.push('sites_config_multisite');
+  if (sunrise) signals.push('sunrise_domain_mapping');
+  if (htaccess) signals.push('htaccess_multisite_rules');
+
+  const report = {
+    tool: 'multisite_inspect',
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    cwd,
+    found: signals.length > 0,
+    signals,
+    details: {
+      wp_config: wpConfig || undefined,
+      sites_config: sitesConfig || undefined,
+      sunrise: sunrise || undefined,
+      htaccess: htaccess || undefined,
+    },
+    recommendations: [],
+  };
+
+  if (wpConfig && !sitesConfig?.count) {
+    report.recommendations.push('Multisite detected in wp-config.php but no site in WP_SITES_CONFIG has is_multisite: true');
+  }
+  if (sitesConfig?.count > 0) {
+    const noCli = sitesConfig.multisite_sites.filter(s => !s.has_wpcli);
+    if (noCli.length > 0) {
+      report.recommendations.push(`Sites without wp_path (no wp-cli access): ${noCli.map(s => s.id).join(', ')}`);
+    }
+    report.recommendations.push(`${sitesConfig.count} multisite network(s) configured — 10 ms_* tools available`);
+  }
+  if (sunrise) {
+    report.recommendations.push('sunrise.php detected — domain mapping is active');
+  }
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(signals.length > 0 ? 0 : 1);
+}
+
+main();

package/skills/wp-security/SKILL.md

@@ -177,3 +177,7 @@ After hardening, verify the security posture:
 ## Recommended Agent
 
 For implementing hardening fixes and incident response, use the **`wp-security-hardener`** agent. For read-only security audits, use the **`wp-security-auditor`** agent.
+
+### Multisite Security
+
+For Super Admin capabilities and multisite-specific security considerations, see the `wp-multisite` skill (`references/user-roles.md`).

package/skills/wp-wpcli-and-ops/SKILL.md

@@ -129,3 +129,7 @@ See:
 - If you cannot confirm environment safety, do not run write operations.
 - If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.
 - If working with a local dev environment (Studio/LocalWP/wp-env), route to the `wp-local-env` skill for environment-specific WP-CLI setup.
+
+### Multisite Operations
+
+For WordPress Multisite network management (sub-sites, network plugins, Super Admin), see the `wp-multisite` skill which provides 10 dedicated MCP tools.