wordpress-agent-kit 0.3.2 → 0.5.1

package/.agents/skills/wp-playground/references/debugging.md

@@ -0,0 +1,16 @@
+## Debugging WordPress Playground
+
+- Start CLI with Xdebug: `server --auto-mount --xdebug` (or `--enable-xdebug` depending on release). The CLI prints host/port and IDE key to configure your debugger.
+- If breakpoints are not hit, confirm:
+  - IDE listens on the port shown by CLI.
+  - Path mappings include the mounted VFS path used by Playground.
+- For slow or stuck runs:
+  - Add `--verbosity=debug` to see step-level logs.
+  - Disable `--experimental-multi-worker` if it was enabled.
+- For mount issues:
+  - Prefer absolute paths in `--mount`.
+  - Use `--mount-before-install` when installer steps need files present early.
+- To inspect runtime state:
+  - Open the Playground browser console; the Service Worker logs network/FS events.
+  - Use the “Terminal” tab (if available) to run WP-CLI inside the instance.
+

package/.agents/skills/wp-playground/references/e2e-playwright.md

@@ -0,0 +1,115 @@
+# E2E Testing with Playwright + WordPress Playground
+
+## Install
+
+```bash
+npm install --save-dev @playwright/test @wp-playground/cli
+npx playwright install chromium
+```
+
+## playwright.config.ts
+
+```ts
+import { defineConfig } from '@playwright/test';
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  timeout: 120_000,
+  expect: { timeout: 30_000 },
+  use: { screenshot: 'only-on-failure', trace: 'on-first-retry' },
+});
+```
+
+## Server lifecycle
+
+**Shared** (faster, tests can affect each other — use for read-only tests):
+```ts
+test.beforeAll(async () => { cli = await runCLI({ command: 'server', blueprint }); });
+test.afterAll(async () => { await cli?.server?.close(); });
+```
+
+**Per-test** (isolated, slower — use when tests modify state):
+```ts
+test.beforeEach(async () => { cli = await runCLI({ command: 'server', blueprint }); });
+test.afterEach(async () => { await cli?.server?.close(); });
+```
+
+## Blueprint fixtures
+
+Installing from wordpress.org:
+```ts
+steps: [{ step: 'installPlugin', pluginData: { resource: 'wordpress.org/plugins', slug: 'contact-form-7' } }]
+```
+
+Creating content:
+```ts
+steps: [{ step: 'runPHP', code: `<?php require '/wordpress/wp-load.php'; wp_insert_post([...]);` }]
+```
+
+## WordPress-specific locator guidance
+
+- `page.getByRole('button', { name: 'Save Changes' })` — works for standard WP buttons
+- `page.getByLabel('API Key')` — works for labeled form fields
+- `page.locator('#wpadminbar')` — CSS required for WP core layout elements (no ARIA)
+- Add `data-testid` to your own plugin markup for stable selectors
+- Run `npx playwright codegen localhost:9400/wp-admin/` to auto-generate locators
+
+## Page Object Model
+
+```ts
+// tests/e2e/pages/plugin-settings.ts
+export class PluginSettingsPage {
+  constructor(readonly page: Page) {}
+  async goto(baseUrl: string) { await this.page.goto(`${baseUrl}/wp-admin/options-general.php?page=my-plugin`); }
+  async setApiKey(key: string) {
+    await this.page.getByLabel('API Key').fill(key);
+    await this.page.getByRole('button', { name: 'Save Changes' }).click();
+  }
+  async expectSaved() { await expect(this.page.getByText('Settings saved')).toBeVisible(); }
+}
+```
+
+## GitHub Actions CI
+
+```yaml
+name: E2E Tests
+on:
+  push: { branches: [main] }
+  pull_request: { branches: [main] }
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: 'npm' }
+      - run: npm ci
+      - uses: actions/cache@v4
+        id: playwright-cache
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ hashFiles('package-lock.json') }}
+      - if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install chromium --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with: { name: playwright-report, path: playwright-report/, retention-days: 30 }
+```
+
+## Troubleshooting
+
+- **Timeout errors** — increase `timeout` in config; CI needs 120–180s
+- **Port conflicts** — don't hardcode ports; use `cli.serverUrl`
+- **Browser not found** — run `npx playwright install chromium`
+- **Passes locally, fails CI** — increase timeouts, ensure `workers: 1`
+- **Debug** — `npx playwright test --debug` or `--ui` for interactive mode
+
+## Docs
+
+- https://wordpress.github.io/wordpress-playground/guides/e2e-testing-with-playwright
+- https://wordpress.github.io/wordpress-playground/guides/programmatic-playground-cli

package/.agents/skills/wp-plugin-development/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: wp-plugin-development
+description: "Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging."
+license: GPL-2.0-or-later
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Plugin Development
+
+## When to use
+
+Use this skill for plugin work such as:
+
+- creating or refactoring plugin structure (bootstrap, includes, namespaces/classes)
+- adding hooks/actions/filters
+- activation/deactivation/uninstall behavior and migrations
+- adding settings pages / options / admin UI (Settings API)
+- security fixes (nonces, capabilities, sanitization/escaping, SQL safety)
+- packaging a release (build artifacts, readme, assets)
+
+## Inputs required
+
+- Repo root + target plugin(s) (path to plugin main file if known).
+- Where this plugin runs: single site vs multisite; WP.com conventions if applicable.
+- Target WordPress + PHP versions (affects available APIs and placeholder support in `$wpdb->prepare()`).
+
+## Procedure
+
+### 0) Triage and locate plugin entrypoints
+
+1. Run triage:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Detect plugin headers (deterministic scan):
+   - `node skills/wp-plugin-development/scripts/detect_plugins.mjs`
+
+If this is a full site repo, pick the specific plugin under `wp-content/plugins/` or `mu-plugins/` before changing code.
+
+### 1) Follow a predictable architecture
+
+Guidelines:
+
+- Keep a single bootstrap (main plugin file with header).
+- Avoid heavy side effects at file load time; load on hooks.
+- Prefer a dedicated loader/class to register hooks.
+- Keep admin-only code behind `is_admin()` (or admin hooks) to reduce frontend overhead.
+
+See:
+- `references/structure.md`
+
+### 2) Hooks and lifecycle (activation/deactivation/uninstall)
+
+Activation hooks are fragile; follow guardrails:
+
+- register activation/deactivation hooks at top-level, not inside other hooks
+- flush rewrite rules only when needed and only after registering CPTs/rules
+- uninstall should be explicit and safe (`uninstall.php` or `register_uninstall_hook`)
+
+See:
+- `references/lifecycle.md`
+
+### 3) Settings and admin UI (Settings API)
+
+Prefer Settings API for options:
+
+- `register_setting()`, `add_settings_section()`, `add_settings_field()`
+- sanitize via `sanitize_callback`
+
+See:
+- `references/settings-api.md`
+
+### 4) Security baseline (always)
+
+Before shipping:
+
+- Validate/sanitize input early; escape output late.
+- Use nonces to prevent CSRF *and* capability checks for authorization.
+- Avoid directly trusting `$_POST` / `$_GET`; use `wp_unslash()` and specific keys.
+- Use `$wpdb->prepare()` for SQL; avoid building SQL with string concatenation.
+
+See:
+- `references/security.md`
+
+### 5) Data storage, cron, migrations (if needed)
+
+- Prefer options for small config; custom tables only if necessary.
+- For cron tasks, ensure idempotency and provide manual run paths (WP-CLI or admin).
+- For schema changes, write upgrade routines and store schema version.
+
+See:
+- `references/data-and-cron.md`
+
+## Verification
+
+- Plugin activates with no fatals/notices.
+- Settings save and read correctly (capability + nonce enforced).
+- Uninstall removes intended data (and nothing else).
+- Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets.
+
+## Failure modes / debugging
+
+- Activation hook not firing:
+  - hook registered incorrectly (not in main file scope), wrong main file path, or plugin is network-activated
+- Settings not saving:
+  - settings not registered, wrong option group, missing capability, nonce failure
+- Security regressions:
+  - nonce present but missing capability checks; or sanitized input not escaped on output
+
+See:
+- `references/debugging.md`
+
+## Escalation
+
+For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.

package/.agents/skills/wp-plugin-development/references/data-and-cron.md

@@ -0,0 +1,19 @@
+# Data storage, cron, and upgrades
+
+Use this file when adding persistent storage, background jobs, or upgrade routines.
+
+## Data storage
+
+- Prefer Options API for small config/state.
+- Use custom tables only when needed; store schema version and provide upgrade paths.
+
+## Cron
+
+- Ensure tasks are idempotent (may run late or multiple times).
+- Provide a manual trigger path for debugging (WP-CLI or admin-only action).
+
+## Database safety note
+
+If using `$wpdb->prepare()`, avoid building queries with concatenated user input.
+Recent WordPress versions support identifier placeholders (`%i`) but you must not assume it exists without checking capabilities or target versions.
+

package/.agents/skills/wp-plugin-development/references/debugging.md

@@ -0,0 +1,19 @@
+# Debugging quick routes
+
+## Plugin doesn’t load / fatal errors
+
+- Confirm correct plugin main file and header.
+- Check PHP error logs and `WP_DEBUG_LOG`.
+- If the repo is a site repo, confirm you edited the correct plugin under `wp-content/plugins/`.
+
+## Activation hook surprises
+
+- Hooks must be registered at top-level.
+- Activation runs in a special context; avoid assuming other hooks already ran.
+
+## Settings not saving
+
+- Confirm `register_setting()` is called.
+- Confirm the option group matches the form.
+- Confirm capability checks and nonces.
+

package/.agents/skills/wp-plugin-development/references/lifecycle.md

@@ -0,0 +1,33 @@
+# Activation, deactivation, uninstall
+
+Use this file for lifecycle changes and data cleanup.
+
+## Activation / deactivation hooks
+
+- `register_activation_hook( __FILE__, 'callback' )`
+- `register_deactivation_hook( __FILE__, 'callback' )`
+
+Guardrails:
+
+- These hooks must be registered at top-level (not inside other hooks).
+- If you flush rewrite rules, ensure rules are registered first (often via a shared function called both on `init` and activation).
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/activation-deactivation-hooks/
+
+## Uninstall
+
+Preferred approaches:
+
+- `uninstall.php` (runs only on uninstall)
+- `register_uninstall_hook()`
+
+Guardrails:
+
+- Check `WP_UNINSTALL_PLUGIN` before running destructive cleanup.
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/
+

package/.agents/skills/wp-plugin-development/references/security.md

@@ -0,0 +1,29 @@
+# Security guardrails (plugin work)
+
+Use this file when making security fixes or when handling any input/output.
+
+## Nonces + permissions
+
+- Nonces help prevent CSRF, not authorization.
+- Always pair nonces with capability checks (`current_user_can()` or a more specific capability).
+
+Upstream reference:
+
+- https://developer.wordpress.org/apis/security/nonces/
+
+## Sanitization and escaping
+
+Golden rule:
+
+- sanitize/validate on input, escape on output.
+
+Practical rules:
+
+- never process the entire `$_POST` / `$_GET` array; read explicit keys
+- use `wp_unslash()` before sanitizing when needed
+- use prepared statements for SQL; avoid interpolating user input into queries
+
+Common review guidance:
+
+- https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
+

package/.agents/skills/wp-plugin-development/references/settings-api.md

@@ -0,0 +1,22 @@
+# Settings API (admin options)
+
+Use this file when adding settings pages or storing user-configurable options.
+
+Core APIs:
+
+- `register_setting()`
+- `add_settings_section()`
+- `add_settings_field()`
+
+Upstream references:
+
+- Settings API overview: https://developer.wordpress.org/plugins/settings/settings-api/
+- Register settings: https://developer.wordpress.org/plugins/settings/registration/
+- Add settings fields: https://developer.wordpress.org/plugins/settings/settings-fields/
+
+Practical guardrails:
+
+- Use `sanitize_callback` to validate/sanitize data.
+- Use capability checks (commonly `manage_options`) for settings screens and saves.
+- Escape values on output (`esc_attr`, `esc_html`, etc.).
+

package/.agents/skills/wp-plugin-development/references/structure.md

@@ -0,0 +1,16 @@
+# Plugin structure and loading
+
+Use this file when introducing or refactoring a plugin architecture.
+
+## Core concepts
+
+- Main plugin file contains the plugin header and bootstraps the plugin.
+- Prefer predictable init:
+  - minimal boot file
+  - a loader/class that registers hooks
+  - admin-only code behind admin hooks
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/
+

package/.agents/skills/wp-plugin-development/scripts/detect_plugins.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+]);
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function readFileSafe(p, maxBytes = 128 * 1024) {
+  try {
+    const buf = fs.readFileSync(p);
+    if (buf.byteLength > maxBytes) return buf.subarray(0, maxBytes).toString("utf8");
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function findFilesRecursive(repoRoot, predicate, { maxFiles = 6000, maxDepth = 10 } = {}) {
+  const results = [];
+  const queue = [{ dir: repoRoot, depth: 0 }];
+  let visited = 0;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      const fullPath = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (DEFAULT_IGNORES.has(ent.name)) continue;
+        queue.push({ dir: fullPath, depth: depth + 1 });
+        continue;
+      }
+      if (!ent.isFile()) continue;
+
+      visited += 1;
+      if (visited > maxFiles) return { results, truncated: true };
+      if (predicate(fullPath)) results.push(fullPath);
+    }
+  }
+
+  return { results, truncated: false };
+}
+
+function parsePluginHeader(contents) {
+  // WordPress reads plugin headers from the top of the file. We only need key fields.
+  const header = {};
+  const pairs = [
+    ["Plugin Name", "name"],
+    ["Plugin URI", "uri"],
+    ["Description", "description"],
+    ["Version", "version"],
+    ["Author", "author"],
+    ["Author URI", "authorUri"],
+    ["Text Domain", "textDomain"],
+    ["Domain Path", "domainPath"],
+  ];
+  for (const [label, key] of pairs) {
+    const m = contents.match(new RegExp(`^\\s*${label}:\\s*(.+)\\s*$`, "im"));
+    if (m) header[key] = m[1].trim();
+  }
+  if (!header.name) return null;
+  return header;
+}
+
+function main() {
+  const repoRoot = process.cwd();
+
+  const { results: phpFiles, truncated } = findFilesRecursive(repoRoot, (p) => p.toLowerCase().endsWith(".php"), {
+    maxFiles: 5000,
+    maxDepth: 10,
+  });
+
+  const plugins = [];
+
+  for (const phpPath of phpFiles) {
+    const txt = readFileSafe(phpPath);
+    if (!txt) continue;
+    if (!/Plugin Name:/i.test(txt)) continue;
+    const header = parsePluginHeader(txt);
+    if (!header) continue;
+    plugins.push({
+      pluginFile: path.relative(repoRoot, phpPath),
+      ...header,
+    });
+  }
+
+  const report = {
+    tool: { name: "detect_plugins", version: "0.1.0" },
+    repoRoot,
+    truncated,
+    count: plugins.length,
+    plugins,
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();
+

package/.agents/skills/wp-plugin-directory-guidelines/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wp-plugin-directory-guidelines
+description: "Use when reviewing WordPress plugins for GPL compliance, checking license headers or compatibility, evaluating upsell/freemium/trialware patterns, validating plugin naming or trademark rules, checking plugin slugs, understanding why a plugin was rejected from WordPress.org, or answering any question about the 18 WordPress.org Plugin Directory guidelines — even if the user doesn't mention 'guidelines' explicitly."
+license: GPL-2.0-or-later
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+)."
+---
+
+## Overview
+
+Authoritative reference for the 18 WordPress.org Plugin Directory guidelines. Covers GPL licensing, plugin naming/trademark rules, trialware restrictions, and all other submission requirements.
+
+## When to use
+
+Use this skill when you need to:
+- Review a WordPress plugin for compliance with the WordPress.org Plugin Directory guidelines
+- Check GPL license compatibility for a plugin or its bundled libraries
+- Verify license headers in plugin files
+- Identify common guideline violations before submission
+- Answer questions about what is or is not allowed on WordPress.org
+- Evaluate premium/upsell flows, license checks, or freemium positioning
+- Review "teaser" or "preview" UI for trialware violations
+
+## Inputs required
+
+- Plugin source code (or specific files to review)
+- Optional: plugin readme and plugin header metadata for naming and license checks
+
+## Procedure
+
+1. Check the plugin's license header against the **Valid License Headers** section below.
+2. Walk through the **18 Guidelines** checklist, paying special attention to Guidelines 1, 4, 5, 7, 8, and 17.
+3. Confirm trialware/freemium compliance using the checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md) (Guideline 5 section).
+4. For bundled third-party code, verify license compatibility against **GPL-Compatible Licenses (Quick)** below.
+5. Flag matches from **Common GPL Violations (Quick)** below.
+6. For edge cases, consult the detailed references and the [GNU GPL FAQ](https://www.gnu.org/licenses/gpl-faq.html).
+
+## 18-Guideline Review Checklist
+
+Use the detailed, per-guideline checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md). Load this reference file only when a full guideline audit is requested.
+
+## GPL Compliance (Guideline 1 in Detail)
+
+Use [gpl-compliance.md](references/gpl-compliance.md) for full license tables, compatibility nuances, and examples. Keep this inline section as a quick decision aid.
+
+### Verification (Licensing)
+
+- Every licensing-related issue must cite **Guideline 1** and include the file path and exact license string.
+- Confirm compatibility claims against **GPL-Compatible Licenses (Quick)** and escalate ambiguous licenses.
+
+### Failure modes (Licensing)
+
+- If a license is not clearly GPL-compatible, do not guess. Check the [GNU license list](https://www.gnu.org/licenses/license-list.html).
+- For dual-license packages, verify both licenses and redistribution terms.
+
+### Quick Reference: WordPress GPL Requirements
+
+- WordPress is **GPLv2 or later**.
+- Plugins distributed on WordPress.org must be 100% GPL-compatible (code and assets).
+- Include a valid `License:` header and `License URI:` in the main plugin file.
+- Do not add restrictions that conflict with GPL freedoms.
+
+### Valid License Headers
+
+## GPL Versions Summary
+
+| Version | Year | Key Addition |
+|---------|------|--------------|
+| GPLv1 | 1989 | Base copyleft: share-alike for modifications |
+| GPLv2 | 1991 | "Liberty or death" clause (Section 7), clearer distribution terms |
+| GPLv3 | 2007 | Anti-tivoization, explicit patent grants, compatibility provisions |
+
+WordPress uses **GPLv2 or later**, meaning plugins can use GPLv2, GPLv3, or "GPLv2 or later".
+
+For full license texts, see:
+- [GNU General Public License v1](https://www.gnu.org/licenses/gpl-1.0.html)
+- [GNU General Public License v2](https://www.gnu.org/licenses/gpl-2.0.html)
+- [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.html)
+
+## License Compliance Checklist
+
+When reviewing a plugin, verify:
+
+- [ ] Main plugin file has a valid `License:` header (e.g., `GPL-2.0-or-later`, `GPL-2.0+`, `GPLv2 or later`)
+- [ ] Main plugin file has a `License URI:` header pointing to the GPL text
+- [ ] If bundled libraries exist, each has a GPL-compatible license
+- [ ] No "split licensing" (e.g., code GPL but premium features proprietary)
+- [ ] No additional restrictions beyond what GPL allows
+- [ ] No clauses restricting commercial use, modification, or redistribution
+- [ ] No obfuscated code (violates the spirit of source code availability)
+
+## Valid License Headers for WordPress Plugins
+
+```
+License: GPL-2.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+```text
+License: GPL-3.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-3.0.html
+```
+
+```text
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+### GPL-Compatible Licenses (Quick)
+
+- Safe defaults: GPL-2.0-or-later, GPL-3.0-or-later.
+- Commonly accepted permissive families: MIT/Expat, BSD, ISC, zlib, Boost.
+- Conditional compatibility requires care: Apache-2.0 and MPL-2.0 (verify usage context).
+- For full accepted and rejected identifiers, use [gpl-compliance.md](references/gpl-compliance.md).
+
+### Common GPL Violations (Quick)
+
+- Split licensing that restricts distributed code.
+- Obfuscated or non-corresponding source distribution.
+- Restrictive clauses (non-commercial, no-resale, forced backlink).
+- Bundling GPL-incompatible libraries or assets.
+
+## Plugin Naming Rules (Guideline 17)
+
+Use [naming-rules.md](references/naming-rules.md) for full trademark lists, slug blocks, and naming examples. Keep this inline checklist for quick screening.
+
+### Naming Checklist (Quick)
+
+- Name is not a placeholder and has at least 5 alphanumeric characters.
+- Header name and readme name match.
+- Name is specific and function-related; avoid keyword stuffing.
+- Trademark/project names appear only after connectors like `for`, `with`, `using`, `and`.
+- No banned/discouraged terms or trademark portmanteaus.
+- Slug is lowercase, hyphenated, <= 50 chars, and avoids blocked terms.