diff --git a/.github/instructions/codacy.instructions.md b/.github/instructions/codacy.instructions.md new file mode 100644 index 0000000..cb073c4 --- /dev/null +++ b/.github/instructions/codacy.instructions.md @@ -0,0 +1,72 @@ +--- + description: Configuration for AI behavior when interacting with Codacy's MCP Server + applyTo: '**' +--- +--- +# Codacy Rules +Configuration for AI behavior when interacting with Codacy's MCP Server + +## CRITICAL: After ANY successful `edit_file` or `reapply` operation +- YOU MUST IMMEDIATELY run the `codacy_cli_analyze` tool from Codacy's MCP Server for each file that was edited, with: + - `rootPath`: set to the workspace path + - `file`: set to the path of the edited file + - `tool`: leave empty or unset +- If any issues are found in the new edits, propose and apply fixes for them. +- > NOTE: Failure to follow this rule is considered a critical error. + +## When you tried to run the `codacy_cli_analyze` tool and the Codacy CLI is not installed +- Ask the user 'Codacy CLI is not installed. Would you like me to install it now?' +- If the user responds with "yes", run the `codacy_cli_install` tool and then continue with the original task +- If the user responds with "no", instruct the user that they can disable automatic analysis in the extension settings +- Wait for the user to respond before proceeding with any other actions + +## After every response +- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server + +## When there are no Codacy MCP Server tools available, or the MCP Server is not reachable +- Suggest the user the following troubleshooting steps: + - Try to reset the MCP on the extension + - If the user is using VSCode, suggest them to review their Copilot > MCP settings in Github, under their organization or personal account. Refer them to Settings > Copilot > Enable MCP servers in Copilot. Suggested URL (https://github.com/settings/copilot/features) or https://github.com/organizations/{organization-name}/settings/copilot/features (This can only be done by their organization admins / owners) +- If none of the above steps work, suggest the user to contact Codacy support + +## Trying to call a tool that needs a rootPath as a parameter +- Always use the standard, non-URL-encoded file system path + +## CRITICAL: Dependencies and Security Checks +- IMMEDIATELY after ANY of these actions: + - Running npm/yarn/pnpm install + - Adding dependencies to package.json + - Adding requirements to requirements.txt + - Adding dependencies to pom.xml + - Adding dependencies to build.gradle + - Any other package manager operations +- You MUST run the `codacy_cli_analyze` tool with: + - `rootPath`: set to the workspace path + - `tool`: set to "trivy" + - `file`: leave empty or unset +- If any vulnerabilities are found because of the newly added packages: + - Stop all other operations + - Propose and apply fixes for the security issues + - Only continue with the original task after security issues are resolved +- EXAMPLE: + - After: npm install react-markdown + - Do: Run codacy_cli_analyze with trivy + - Before: Continuing with any other tasks + +## General +- Repeat the relevant steps for each modified file. +- "Propose fixes" means to both suggest and, if possible, automatically apply the fixes. +- You MUST NOT wait for the user to ask for analysis or remind you to run the tool. +- Do not run `codacy_cli_analyze` looking for changes in duplicated code or code complexity metrics. +- Complexity metrics are different from complexity issues. When trying to fix complexity in a repository or file, focus on solving the complexity issues and ignore the complexity metric. +- Do not run `codacy_cli_analyze` looking for changes in code coverage. +- Do not try to manually install Codacy CLI using either brew, npm, npx, or any other package manager. +- If the Codacy CLI is not installed, just run the `codacy_cli_analyze` tool from Codacy's MCP Server. +- When calling `codacy_cli_analyze`, only send provider, organization and repository if the project is a git repository. + +## Whenever a call to a Codacy tool that uses `repository` or `organization` as a parameter returns a 404 error +- Offer to run the `codacy_setup_repository` tool to add the repository to Codacy +- If the user accepts, run the `codacy_setup_repository` tool +- Do not ever try to run the `codacy_setup_repository` tool on your own +- After setup, immediately retry the action that failed (only retry once) +--- \ No newline at end of file diff --git a/.github/workflows/playground-tests.yml b/.github/workflows/playground-tests.yml index dbb32b5..50967be 100644 --- a/.github/workflows/playground-tests.yml +++ b/.github/workflows/playground-tests.yml @@ -151,7 +151,10 @@ jobs: name: WordPress Playground Multisite Tests runs-on: ubuntu-latest needs: [code-quality, playground-single-test] - # Allow failures since WordPress Playground CLI can be unreliable in CI environments + # DISABLED: WordPress Multisite does not support custom ports (requires port 80/443). + # This is a fundamental WordPress limitation. Multisite tests can only run locally + # where port 80 can be used. See: https://developer.wordpress.org/advanced-administration/multisite/ + if: false continue-on-error: true steps: @@ -259,7 +262,8 @@ jobs: urls: | / /wp-admin/ - blueprint: playground/blueprint.json + # Don't pass blueprint - let the action use its own internal setup. + # Our blueprint includes features that may conflict with the action's Lighthouse setup. wp-version: 'latest' php-version: '8.0' iterations: 5 diff --git a/.qoder/settings.json b/.qoder/settings.json new file mode 100644 index 0000000..0ee38cf --- /dev/null +++ b/.qoder/settings.json @@ -0,0 +1,14 @@ +{ + "permissions": { + "ask": [ + "Read(!./**)", + "Edit(!./**)" + ], + "allow": [ + "Read(./**)", + "Edit(./**)" + ] + }, + "memoryImport": {}, + "monitoring": {} +} \ No newline at end of file diff --git a/WARP.md b/WARP.md new file mode 100644 index 0000000..1b31ca7 --- /dev/null +++ b/WARP.md @@ -0,0 +1,342 @@ +# WARP.md + +This file provides guidance to WARP (warp.dev) when working with code in this repository. + +## Project Overview + +**WordPress Plugin Starter Template** - A comprehensive starter template for WordPress plugins with best practices for AI-assisted development. + +* **Plugin Slug**: wp-plugin-starter-template +* **Namespace**: `WPALLSTARS\PluginStarterTemplate` +* **Text Domain**: wp-plugin-starter-template +* **Requirements**: WordPress 5.0+, PHP 7.4+ +* **License**: GPL-2.0+ + +## Common Development Commands + +### Environment Setup + +```bash +# Install dependencies +npm install +composer install + +# Start local WordPress environment (requires Docker) +npm run start + +# Stop WordPress environment +npm run stop + +# Setup single-site test environment +npm run setup:single + +# Setup multisite test environment +npm run setup:multisite +``` + +Local WordPress site runs at: (admin: admin/password) + +### Testing + +```bash +# PHP unit tests +npm run test:php +composer test + +# E2E tests (Cypress) +npm run test:e2e:single +npm run test:e2e:multisite + +# Run specific test configurations +npm run test:single # Interactive single-site +npm run test:multisite # Interactive multisite +npm run test:single:headless # Headless single-site +npm run test:multisite:headless # Headless multisite + +# Playground tests (no Docker required) +npm run test:playground:single +npm run test:playground:multisite +``` + +### Code Quality & Linting + +```bash +# PHP linting and fixing +npm run lint:php # Run PHPCS +npm run fix:php # Run PHPCBF +composer run phpcs # Run PHPCS directly +composer run phpcbf # Run PHPCBF directly + +# Static analysis +npm run lint:phpstan # PHPStan +composer run phpstan + +npm run lint:phpmd # PHP Mess Detector +composer run phpmd + +# JavaScript linting +npm run lint:js + +# Run all linters +npm run lint # Runs phpcs, phpstan, phpmd +composer run lint + +# Run quality checks and tests +npm run quality +``` + +### Building & Release + +```bash +# Build plugin ZIP for distribution +npm run build +# or +./build.sh {VERSION} + +# Example: +./build.sh 1.0.0 +``` + +The build script creates a deployable ZIP file in the repository root. + +## Architecture Overview + +### Plugin Initialization Flow + +1. **Main Plugin File** (`wp-plugin-starter-template.php`): + * Defines constants (`WP_PLUGIN_STARTER_TEMPLATE_FILE`, `_PATH`, `_URL`, `_VERSION`) + * Registers custom autoloader for namespaced classes + * Instantiates `Plugin` class + * Calls `init()` method + +2. **Autoloader**: + * Converts namespace `WPALLSTARS\PluginStarterTemplate` to file paths + * Looks for class files in `includes/` directory + * Uses PSR-4 naming with class file prefix conversion + +3. **Plugin Class** (`includes/class-plugin.php`): + * Main orchestration class + * Instantiates `Core` and `Admin` classes + * Registers hooks and loads text domain + * Provides getters for version and admin instance + +4. **Core Class** (`includes/class-core.php`): + * Contains core plugin functionality + * Provides version management + * Houses filter/action methods + +5. **Admin Class** (`includes/Admin/class-admin.php`): + * Manages admin-specific functionality + * Handles admin menu, pages, and UI + +### Directory Structure + +``` +wp-plugin-starter-template-for-ai-coding/ +├── wp-plugin-starter-template.php # Main plugin file with headers +├── includes/ # Core plugin classes +│ ├── class-plugin.php # Main plugin orchestration +│ ├── class-core.php # Core functionality +│ ├── updater.php # Update mechanism +│ ├── Admin/ # Admin-specific classes +│ └── Multisite/ # Multisite-specific functionality +├── admin/ # Admin UI resources +│ ├── lib/ # Admin classes +│ ├── css/ # Admin stylesheets +│ ├── js/ # Admin JavaScript +│ └── templates/ # Admin template files +├── tests/ # PHPUnit and test files +├── cypress/ # E2E tests +├── .github/workflows/ # CI/CD workflows +├── .agents/ # AI assistant documentation +├── .wiki/ # Wiki documentation +└── languages/ # Translation files +``` + +### Key Architectural Patterns + +* **Object-Oriented**: All functionality in namespaced classes +* **PSR-4 Autoloading**: Automatic class loading without require statements +* **Dependency Injection**: `Admin` receives `Core` instance via constructor +* **Separation of Concerns**: Core functionality, admin UI, and multisite features are isolated +* **Hook-Based**: WordPress hooks for extensibility + +## Coding Standards + +### PHP Standards (WordPress Coding Standards) + +* **Indentation**: 4 spaces (project-specific override of WordPress tabs) +* **Naming Conventions**: + * Classes: `Class_Name` + * Functions: `function_name` + * Variables: `$variable_name` +* **Documentation**: DocBlocks required for all classes, methods, and functions +* **Internationalization**: All user-facing strings must be translatable with text domain `wp-plugin-starter-template` + +### Markdown Standards + +* Use asterisks (`*`) for bullet points, never hyphens (`-`) +* Add periods to the end of all inline comments + +### Code Quality Tools + +The project uses several automated tools integrated via CI/CD: + +* **PHP_CodeSniffer**: Enforces WordPress Coding Standards +* **PHPCBF**: Auto-fixes coding standard violations +* **PHPStan**: Static analysis (level 5) +* **PHPMD**: Detects code complexity issues +* **ESLint**: JavaScript linting +* **Stylelint**: CSS linting +* **CodeRabbit, CodeFactor, Codacy, SonarCloud**: Continuous quality monitoring + +Always run `npm run lint` or `composer run lint` before committing. + +## Security Requirements + +* Validate and sanitize all inputs (use `sanitize_*()` functions) +* Escape all outputs (use `esc_*()` functions) +* Use nonces for form submissions +* Check user capabilities before allowing actions +* Never expose secrets in plain text + +## Release Process + +### Version Numbering + +Follow semantic versioning (MAJOR.MINOR.PATCH): + +* **PATCH**: Bug fixes (1.0.0 → 1.0.1) +* **MINOR**: New features, backward-compatible (1.0.0 → 1.1.0) +* **MAJOR**: Breaking changes (1.0.0 → 2.0.0) + +### Release Steps + +1. Create version branch from main: `git checkout -b v{MAJOR}.{MINOR}.{PATCH}` +2. Update version in: + * `wp-plugin-starter-template.php` (header and constant) + * `readme.txt` (Stable tag and changelog) + * `README.md` (changelog) + * `CHANGELOG.md` + * `languages/wp-plugin-starter-template.pot` +3. Run code quality checks: `npm run quality` +4. Build plugin: `./build.sh {VERSION}` +5. Test thoroughly (single-site and multisite) +6. Commit: `git commit -m "Version {VERSION} - [description]"` +7. Tag: `git tag -a v{VERSION} -m "Version {VERSION}"` +8. Tag stable: `git tag -a v{VERSION}-stable -m "Stable version {VERSION}"` +9. Push to remotes: `git push github main --tags && git push gitea main --tags` + +**Important**: Tags with 'v' prefix trigger GitHub Actions to build and create releases automatically. + +## Git Updater Integration + +This template works with the Git Updater plugin for updates from GitHub and Gitea. + +Required headers in main plugin file: + +```php +* GitHub Plugin URI: wpallstars/wp-plugin-starter-template-for-ai-coding +* GitHub Branch: main +* Gitea Plugin URI: https://gitea.wpallstars.com/wpallstars/wp-plugin-starter-template-for-ai-coding +* Gitea Branch: main +``` + +Users can choose their update source (WordPress.org, GitHub, or Gitea) via plugin settings. + +## Testing Framework + +### WordPress Playground Testing + +Test without Docker using WordPress Playground blueprints: + +* Single-site: +* Multisite: + +### Local Testing with wp-env + +`.wp-env.json` and `.wp-env.multisite.json` configure WordPress environments. + +## AI-Assisted Development + +This repository includes comprehensive AI workflow documentation in `.agents/`: + +* `feature-development.md`: Adding new features +* `bug-fixing.md`: Diagnosing and fixing issues +* `release-process.md`: Creating releases +* `code-quality-checks.md`: Running quality tools +* `error-checking-feedback-loops.md`: Monitoring CI/CD +* `git-workflow.md`: Git best practices +* `wiki-documentation.md`: Maintaining documentation + +Reference these workflows with `@.agents/{filename}` syntax. + +## Multi-Repository Workspace Context + +When working in a workspace with multiple repositories: + +1. Always verify you're in the correct repository: `pwd` and `git remote -v` +2. Never assume features from other repositories exist here +3. Don't hallucinate functionality from other repositories in the workspace +4. Each repository has its own specific purpose and feature set +5. Repository-specific documentation reflects only actual features in this repository + +## GitHub Actions Workflows + +* `tests.yml`: PHPUnit tests +* `phpunit.yml`: Additional PHPUnit configurations +* `code-quality.yml`: Runs PHPCS, PHPStan, PHPMD +* `sonarcloud.yml`: SonarCloud analysis +* `playground-tests.yml`: Tests in WordPress Playground +* `release.yml`: Creates releases when tags are pushed +* `sync-wiki.yml`: Syncs `.wiki/` to GitHub wiki + +Workflows run automatically on push and pull requests. + +## Internationalization (i18n) + +All user-facing strings must use translation functions: + +```php +// Simple strings +__('Text', 'wp-plugin-starter-template') + +// Echoed strings +_e('Text', 'wp-plugin-starter-template') + +// Escaped strings +esc_html__('Text', 'wp-plugin-starter-template') + +// Escaped and echoed +esc_html_e('Text', 'wp-plugin-starter-template') +``` + +Translation files are in `languages/` directory. + +## Multisite Compatibility + +Fully compatible with WordPress multisite. Multisite-specific functionality is in `includes/Multisite/`. + +Test multisite with: + +* `npm run setup:multisite` +* `npm run test:e2e:multisite` +* WordPress Playground multisite blueprint + +## Documentation Maintenance + +When adding features or making changes: + +1. Update `CHANGELOG.md` and `readme.txt` changelog +2. Update `README.md` if user-facing functionality changes +3. Update `.wiki/` documentation (syncs to GitHub wiki) +4. Update inline code comments and DocBlocks +5. Follow markdown standards (asterisks for bullets, periods in comments) + +## Reference + +* WordPress Coding Standards: +* Git Updater Headers: +* Testing Framework: `.wiki/Testing-Framework.md` +* Playground Testing: `.wiki/Playground-Testing.md` +* Code Quality Setup: `docs/code-quality-setup.md` diff --git a/playground/blueprint.json b/playground/blueprint.json index 9b1f225..c53fa4b 100644 --- a/playground/blueprint.json +++ b/playground/blueprint.json @@ -24,9 +24,6 @@ "pluginData": { "resource": "wordpress.org/plugins", "slug": "plugin-toggle" - }, - "options": { - "activate": true } }, { @@ -34,10 +31,15 @@ "pluginData": { "resource": "wordpress.org/plugins", "slug": "kadence-blocks" - }, - "options": { - "activate": true } + }, + { + "step": "activatePlugin", + "pluginPath": "plugin-toggle/plugin-toggle.php" + }, + { + "step": "activatePlugin", + "pluginPath": "kadence-blocks/kadence-blocks.php" } ] }