From 454997c876bcc3c6decd6cd4186cd05c8acc0da2 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:25:38 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 + README.md | 3 + plugin.lock.json | 49 +++ skills/wordpress-plugin-scaffold/SKILL.md | 338 ++++++++++++++++++ .../references/wp-cli-installation.md | 292 +++++++++++++++ 5 files changed, 693 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/wordpress-plugin-scaffold/SKILL.md create mode 100644 skills/wordpress-plugin-scaffold/references/wp-cli-installation.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..39895a5 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "wordpress-plugin-scaffold", + "description": "Scaffold WordPress plugins using WP-CLI commands with intelligent environment detection and comprehensive testing support", + "version": "1.0.0", + "author": { + "name": "Em" + }, + "skills": [ + "./skills/wordpress-plugin-scaffold" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..39bf614 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# wordpress-plugin-scaffold + +Scaffold WordPress plugins using WP-CLI commands with intelligent environment detection and comprehensive testing support diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..c72bb1e --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:emdashcodes/wp-ability-toolkit:claude-code-plugins/wordpress-plugin-scaffold", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "ae26f73fea77d0efae9d7bc32fef41f109fd13e4", + "treeHash": "0c4523786fca7f0b06f0925c8f4c69cdc423ca04f56452ff429b920f32400657", + "generatedAt": "2025-11-28T10:16:46.982902Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "wordpress-plugin-scaffold", + "description": "Scaffold WordPress plugins using WP-CLI commands with intelligent environment detection and comprehensive testing support", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "634a9f4c090fadf1e0dfe96fd97dc5bbaa1d085de472dac344907c48a9538f2d" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "ddbc641e527253a2d138d2cb5fb75ead2cfa8fd9a78b3bce1324727681ef732c" + }, + { + "path": "skills/wordpress-plugin-scaffold/SKILL.md", + "sha256": "52f3c8aa7613493cc4de051d3bb9e7d79b2261ea6da8bf873f85480f40b54b18" + }, + { + "path": "skills/wordpress-plugin-scaffold/references/wp-cli-installation.md", + "sha256": "ac3ead63244b2abc48da1b69003b0d292ac4f3ff2b3ad1403e27ae7195490d8d" + } + ], + "dirSha256": "0c4523786fca7f0b06f0925c8f4c69cdc423ca04f56452ff429b920f32400657" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/wordpress-plugin-scaffold/SKILL.md b/skills/wordpress-plugin-scaffold/SKILL.md new file mode 100644 index 0000000..1eaa39c --- /dev/null +++ b/skills/wordpress-plugin-scaffold/SKILL.md @@ -0,0 +1,338 @@ +--- +name: wordpress-plugin-scaffold +description: Scaffold WordPress plugins using WP-CLI commands (wp scaffold plugin, wp scaffold plugin-tests). Use this skill when creating new WordPress plugins or adding test infrastructure to existing plugins. +--- + +# WordPress Plugin Scaffold + +This skill provides guidance for scaffolding WordPress plugins using WP-CLI's scaffold commands. It supports both creating new plugins from scratch and adding test infrastructure to existing plugins. + +**Note:** This skill works seamlessly with the **wp-env skill (if available)**. When wp-env setup or management is needed, activate the wp-env skill for comprehensive environment handling. + +## About WP-CLI Scaffold Commands + +WP-CLI provides two primary scaffolding commands for plugin development: + +### wp scaffold plugin + +Generates starter code for a new plugin, including: + +- Main plugin PHP file +- `readme.txt` for WordPress.org +- `package.json` with Grunt tasks for i18n and readme conversion +- Editor configuration files (`.editorconfig`, `.gitignore`, `.distignore`) +- Optional: PHPUnit test suite, CI configuration, and PHP_CodeSniffer rules + +### wp scaffold plugin-tests + +Adds PHPUnit test infrastructure to an existing plugin, including: + +- `phpunit.xml.dist` configuration +- CI configuration (CircleCI, GitHub Actions, GitLab, Bitbucket) +- `bin/install-wp-tests.sh` for WordPress test suite setup +- `tests/bootstrap.php` to activate the plugin during tests +- `tests/test-sample.php` with example test cases +- `.phpcs.xml.dist` for PHP_CodeSniffer rules + +## Prerequisites + +Verify WP-CLI is installed and accessible: + +```bash +wp --version +``` + +If WP-CLI is not installed, see [references/wp-cli-installation.md](references/wp-cli-installation.md) for comprehensive installation instructions across all platforms. + +## Environment Detection + +**IMPORTANT:** Before running any scaffold commands, detect which WordPress environment is available: + +### Detection Strategy + +1. **Check for existing WordPress installation** (preferred): + + ```bash + wp core version 2>/dev/null + ``` + + - If successful → Use `wp scaffold plugin` directly + - You're already in a WordPress installation, no additional setup needed + +2. **Check for wp-env configuration**: + + ```bash + # Look for wp-env config files + [ -f .wp-env.json ] || [ -f .wp-env.override.json ] + ``` + + - If found → Check if wp-env is running + - If running → Use `wp-env run cli wp scaffold plugin` + - If not running → **Activate the wp-env skill (if available)** to start the environment + +3. **Check for wp-env availability** (fallback): + + ```bash + wp-env --version 2>/dev/null + ``` + + - If available → Ask user if they want to use wp-env + - **Activate the wp-env skill (if available)** for environment setup and management + +4. **No environment available** (error): + - Inform user they need either: + - A WordPress installation with `--path` flag + - wp-env setup (see wp-env skill if available) + +### Command Prefix Selection + +Based on detection, use the appropriate command prefix throughout this skill: + +- **In WordPress installation:** `wp scaffold plugin` +- **Using wp-env:** `wp-env run cli wp scaffold plugin` + +All examples below show the base command. Prepend `wp-env run cli` when using wp-env. + +## Workflow: Creating a New Plugin + +When creating a new WordPress plugin, follow this interactive workflow: + +### 1. Gather Plugin Metadata + +Collect the following information from the user, offering smart defaults: + +- **Plugin slug** (required) - Internal name, lowercase with hyphens + - Default: Infer from current directory name or user's request + +- **Plugin name** - Display name for the plugin header + - Default: Title-case version of slug + +- **Plugin description** - What the plugin does + - Default: Ask user to provide + +- **Plugin author** - Author name + - Default: Use `git config user.name` if available + +- **Plugin author URI** - Author website URL + - Default: Use `git config user.url` if available, otherwise skip + +- **Plugin URI** - Plugin project URL + - Default: Skip unless user provides + +### 2. Determine Additional Options + +Ask the user about these options: + +- **Include tests?** - Whether to generate PHPUnit test files + - Default: Yes (recommended for all plugins) + - Use `--skip-tests` flag to omit + +- **CI provider** - Which continuous integration service to use + - Options: `circle` (default), `github`, `gitlab`, `bitbucket` + - Use `--ci=` flag + +- **Target directory** - Where to create the plugin + - Default: Current working directory + - Use `--dir=` to specify custom location + +### 3. Construct and Execute Command + +Build the `wp scaffold plugin` command with gathered information: + +```bash +wp scaffold plugin \ + --plugin_name="" \ + --plugin_description="" \ + --plugin_author="" \ + --plugin_author_uri="" \ + --plugin_uri="" \ + --ci= +``` + +Add `--skip-tests` if user declined test files. +Add `--dir=` if custom directory specified. + +### 4. Post-Scaffold Actions + +After successfully scaffolding the plugin: + +1. **Verify creation** - Confirm files were generated: + + ```bash + ls -la + ``` + +2. **Ask about activation** - If wp-env is running, offer to activate: + - "Would you like me to activate this plugin in your wp-env environment?" + - If yes, run: `wp-env run cli wp plugin activate ` + - For network activation: `wp-env run cli wp plugin activate --network` + +3. **Next steps guidance** - Inform user about: + - Main plugin file location: `/.php` + - How to run tests if included: `wp-env run tests-cli --env-cwd=wp-content/plugins/ phpunit` + - NPM scripts available: `npm run readme`, `npm run i18n` + +## Workflow: Adding Tests to Existing Plugin + +When adding test infrastructure to an existing plugin: + +### 1. Identify Plugin + +Determine which plugin needs tests: + +- **Plugin slug** - The plugin directory name +- **Plugin directory** - Path to the plugin (use `--dir` if non-standard) + +### 2. Determine CI Provider + +Ask which CI service the user wants: + +- Options: `circle` (default), `github`, `gitlab`, `bitbucket` + +### 3. Execute Command + +Run the scaffold plugin-tests command: + +```bash +# Standard plugin location +wp scaffold plugin-tests --ci= + +# Non-standard location +wp scaffold plugin-tests --dir= --ci= +``` + +Add `--force` flag to overwrite existing test files if needed. + +### 4. Post-Scaffold Actions + +After generating test files: + +1. **Set up test environment** - Guide user through test setup: + + ```bash + # Install WordPress test suite (if not using wp-env) + bash bin/install-wp-tests.sh wordpress_test root password localhost latest + + # Or use wp-env for testing + wp-env run tests-cli --env-cwd=wp-content/plugins/ phpunit + ``` + +2. **Verify test execution** - Run the sample test: + + ```bash + wp-env run tests-cli --env-cwd=wp-content/plugins/ phpunit + ``` + +3. **Next steps** - Inform user about: + - Writing additional tests in `tests/` directory + - Running specific test files or test cases + - CI/CD integration based on chosen provider + +## Common Options Reference + +| Option | Description | Example | +| -------------------- | ---------------------------------------------------- | -------------------- | +| `--skip-tests` | Don't generate PHPUnit test files | `--skip-tests` | +| `--ci=` | CI configuration (circle, github, gitlab, bitbucket) | `--ci=github` | +| `--activate` | Activate plugin after creation | `--activate` | +| `--activate-network` | Network activate plugin after creation | `--activate-network` | +| `--force` | Overwrite existing files | `--force` | +| `--dir=` | Custom directory for plugin | `--dir=/custom/path` | + +**Note:** `--activate` and `--activate-network` flags work with local wp-cli WordPress installations but not with wp-env. For wp-env, use `wp-env run cli wp plugin activate` instead. + +## Best Practices + +### Plugin Naming + +- Use lowercase letters, numbers, and hyphens only +- Be descriptive but concise +- Follow WordPress plugin naming conventions +- Examples: `my-contact-form`, `analytics-dashboard`, `custom-post-types` + +### When to Skip Tests + +Skip tests (`--skip-tests`) only when: + +- Creating a quick prototype or proof-of-concept +- Building a personal plugin that won't be distributed +- Planning to add tests later with `wp scaffold plugin-tests` + +**Always include tests for:** + +- Plugins intended for public distribution +- Team projects with multiple contributors +- Plugins with complex business logic +- Any production-ready code + +### CI Provider Selection + +Choose a CI provider based on your repository host: + +- **GitHub repositories** → `--ci=github` (GitHub Actions) +- **GitLab repositories** → `--ci=gitlab` (GitLab CI) +- **Bitbucket repositories** → `--ci=bitbucket` (Bitbucket Pipelines) +- **Other/unknown** → `--ci=circle` (CircleCI) + +### Working with wp-env + +When developing with wp-env: + +1. **Scaffold inside wp-env directory structure:** + + ```bash + # Create plugin in wp-env's plugin directory + cd /path/to/wp-env-project + wp scaffold plugin my-plugin --dir=plugins/ + ``` + +2. **Or scaffold separately and configure .wp-env.json:** + + ```json + { + "plugins": [".", "../other-plugin"] + } + ``` + +3. **Activate after scaffolding:** + + ```bash + wp-env run cli wp plugin activate my-plugin + ``` + +4. **Run tests in wp-env:** + + ```bash + wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit + ``` + +## Example Interactions + +### Creating a New Plugin + +**User:** "Create a new WordPress plugin called 'site-analytics' for tracking visitor analytics" + +**Process:** + +1. Gather metadata (use smart defaults from git config) +2. Ask about tests (default: yes) and CI provider (default: github) +3. Execute: `wp scaffold plugin site-analytics --plugin_name="Site Analytics" --plugin_description="Track visitor analytics and generate reports" --plugin_author="Em" --ci=github` +4. Ask: "Would you like me to activate this plugin in wp-env?" + +### Adding Tests to Existing Plugin + +**User:** "Add tests to my existing 'custom-widgets' plugin" + +**Process:** + +1. Identify plugin location +2. Ask about CI provider +3. Execute: `wp scaffold plugin-tests custom-widgets --ci=github` +4. Guide user through running tests with wp-env + +## Additional Resources + +- [WP-CLI Scaffold Plugin Documentation](https://developer.wordpress.org/cli/commands/scaffold/plugin/) +- [WP-CLI Scaffold Plugin Tests Documentation](https://developer.wordpress.org/cli/commands/scaffold/plugin-tests/) +- [Plugin Unit Tests Handbook](https://make.wordpress.org/cli/handbook/misc/plugin-unit-tests/) +- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/) diff --git a/skills/wordpress-plugin-scaffold/references/wp-cli-installation.md b/skills/wordpress-plugin-scaffold/references/wp-cli-installation.md new file mode 100644 index 0000000..be83cc6 --- /dev/null +++ b/skills/wordpress-plugin-scaffold/references/wp-cli-installation.md @@ -0,0 +1,292 @@ +# WP-CLI Installation Guide + +This reference provides comprehensive installation instructions for WP-CLI across different platforms and methods. + +## Quick Check + +Verify if WP-CLI is already installed: + +```bash +wp --version +``` + +If installed, you'll see the version number. If not, follow the installation method below that best suits your environment. + +## Recommended Installation (Phar Method) + +The recommended way to install WP-CLI is by downloading the Phar build, marking it executable, and placing it on your PATH. + +### Step 1: Download WP-CLI + +```bash +curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar +``` + +### Step 2: Verify It Works + +```bash +php wp-cli.phar --info +``` + +### Step 3: Make It Executable and Move to PATH + +```bash +chmod +x wp-cli.phar +sudo mv wp-cli.phar /usr/local/bin/wp +``` + +### Step 4: Test the Installation + +```bash +wp --info +``` + +You should see output showing OS, PHP version, WP-CLI version, etc. + +## Updating WP-CLI + +If you installed using the Phar method: + +```bash +wp cli update +``` + +Or with sudo if WP-CLI is owned by root: + +```bash +sudo wp cli update +``` + +For nightly builds (bleeding edge): + +```bash +wp cli update --nightly +``` + +## Platform-Specific Installation + +### macOS (Homebrew) + +```bash +brew install wp-cli +``` + +### Windows + +1. Ensure PHP is installed and in your PATH +2. Download [wp-cli.phar](https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar) to `c:\wp-cli` +3. Create `wp.bat` in `c:\wp-cli`: + + ```batch + @ECHO OFF + php "c:/wp-cli/wp-cli.phar" %* + ``` + +4. Add `c:\wp-cli` to your PATH: + + ```batch + setx path "%path%;c:\wp-cli" + ``` + +### Debian/Ubuntu (.deb package) + +Download and install from: +[https://github.com/wp-cli/builds/tree/gh-pages/deb](https://github.com/wp-cli/builds/tree/gh-pages/deb) + +### Fedora 30+ + +```bash +su -c 'dnf install wp-cli' +``` + +### CentOS + +```bash +su -c 'yum install wp-cli' +``` + +## Alternative Installation Methods + +### Via Composer (Global) + +If you have Composer and `~/.composer/vendor/bin` in your PATH: + +```bash +composer global require wp-cli/wp-cli-bundle +``` + +Update all global packages: + +```bash +composer global update +``` + +### Via Composer (Project) + +Add to your project's `composer.json`: + +```json +"require": { + "wp-cli/wp-cli-bundle": "*" +} +``` + +### Via Docker + +Use the official WordPress CLI image: + +```yaml +image: wordpress:cli +``` + +See [WordPress Docker images](https://hub.docker.com/_/wordpress/) for more details. + +### Specific Version + +Install a specific version via Composer: + +```bash +composer create-project wp-cli/wp-cli-bundle:2.1.0 --no-dev +``` + +### Bleeding Edge (dev-main) + +```bash +composer create-project wp-cli/wp-cli-bundle:dev-main --no-dev +``` + +## Shell Completion + +### Bash & Zsh + +Download the completion script: + +```bash +curl -O https://github.com/wp-cli/wp-cli/raw/main/utils/wp-completion.bash +``` + +Add to `~/.bash_profile` or `~/.zshrc`: + +```bash +source /FULL/PATH/TO/wp-completion.bash +``` + +Reload your profile: + +```bash +source ~/.bash_profile # or source ~/.zshrc +``` + +### Oh My Zsh + +Enable the built-in `wp-cli` plugin in `~/.zshrc`: + +```bash +plugins=(wp-cli git [...]) +``` + +Then reload: + +```bash +source ~/.zshrc +``` + +### Fish + +Download and install completion: + +```bash +curl -O https://github.com/wp-cli/wp-cli/raw/main/utils/wp.fish +mv wp.fish ~/.config/fish/completions/wp.fish +``` + +## Custom PHP Binary (MAMP, etc.) + +If you need to use a custom PHP binary (e.g., MAMP): + +### Latest MAMP PHP Version + +Add to `~/.bash_profile` or `~/.zshrc`: + +```bash +PHP_VERSION=$(ls /Applications/MAMP/bin/php/ | sort -n | tail -1) +export PATH=/Applications/MAMP/bin/php/${PHP_VERSION}/bin:$PATH +``` + +### Specific MAMP PHP Version + +Add to `~/.bash_profile` or `~/.zshrc`: + +```bash +export PATH=/Applications/MAMP/bin/php/php5.5.26/bin:$PATH +``` + +Reload profile: + +```bash +source ~/.bash_profile # or source ~/.zshrc +``` + +Verify: + +```bash +wp --info +``` + +### Using WP_CLI_PHP Environment Variable + +For Composer and Git-based installations: + +```bash +export WP_CLI_PHP=/path/to/custom/php +``` + +## Troubleshooting + +### Command Not Found + +If `wp` command is not found after installation: + +1. Check that `/usr/local/bin` is in your PATH: + + ```bash + echo $PATH + ``` + +2. Verify the file exists and is executable: + + ```bash + ls -la /usr/local/bin/wp + ``` + +3. Try using the full path: + + ```bash + /usr/local/bin/wp --info + ``` + +### Permission Denied + +If you get permission errors: + +```bash +sudo chmod +x /usr/local/bin/wp +``` + +### PHP Version Issues + +WP-CLI requires PHP 7.4 or later. Check your PHP version: + +```bash +php --version +``` + +If your PHP version is too old, you'll need to upgrade PHP or use a custom PHP binary (see above). + +## Additional Resources + +- [Official WP-CLI Installation Guide](https://make.wordpress.org/cli/handbook/guides/installing/) +- [Official WP-CLI Documentation](https://make.wordpress.org/cli/handbook/) +- [WP-CLI Commands Reference](https://developer.wordpress.org/cli/commands/) +- [WP-CLI GitHub Repository](https://github.com/wp-cli/wp-cli) +- [Quick Start Guide](https://make.wordpress.org/cli/handbook/quick-start/)