wordpress-agent-kit 0.5.1 → 0.6.0

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

@@ -1,16 +0,0 @@
-## 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/.github/skills/wp-playground/references/e2e-playwright.md

@@ -1,115 +0,0 @@
-# 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/.github/skills/wp-plugin-development/SKILL.md

@@ -1,113 +0,0 @@
----
-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/.github/skills/wp-plugin-development/references/data-and-cron.md

@@ -1,19 +0,0 @@
-# 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/.github/skills/wp-plugin-development/references/debugging.md

@@ -1,19 +0,0 @@
-# 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/.github/skills/wp-plugin-development/references/lifecycle.md

@@ -1,33 +0,0 @@
-# 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/.github/skills/wp-plugin-development/references/security.md

@@ -1,29 +0,0 @@
-# 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/.github/skills/wp-plugin-development/references/settings-api.md

@@ -1,22 +0,0 @@
-# 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/.github/skills/wp-plugin-development/references/structure.md

@@ -1,16 +0,0 @@
-# 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/.github/skills/wp-plugin-development/scripts/detect_plugins.mjs

@@ -1,122 +0,0 @@
-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/.github/skills/wp-plugin-directory-guidelines/SKILL.md

@@ -1,133 +0,0 @@
----
-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.