@ai-kits/wp-ag-kit 1.0.2 → 1.0.3

package/skills/woocommerce/references/php-linting-patterns.md

@@ -0,0 +1,304 @@
+# PHP Linting Patterns and Common Issues
+
+## Table of Contents
+
+- [Critical Rule: Lint Only Specific Files](#critical-rule-lint-only-specific-files)
+- [Common PHP Linting Issues & Fixes](#common-php-linting-issues--fixes)
+- [Translators Comment Placement](#translators-comment-placement)
+- [PSR-12 File Header Order](#psr-12-file-header-order)
+- [Mock Classes with Intentional Violations](#mock-classes-with-intentional-violations)
+- [Multi-line Condition Alignment](#multi-line-condition-alignment)
+- [Unused Closure Parameters](#unused-closure-parameters)
+- [Array and Operator Alignment](#array-and-operator-alignment)
+- [Indentation Rules](#indentation-rules)
+- [Workflow for Fixing PHP Linting Issues](#workflow-for-fixing-php-linting-issues)
+- [Quick Command Reference](#quick-command-reference)
+
+## Critical Rule: Lint Only Specific Files
+
+**NEVER run linting on the entire codebase.** Always lint specific files, changed files or staged files only.
+
+```bash
+# ✅ CORRECT: Check only changed files at the branch level
+pnpm lint:php:changes
+
+# ✅ CORRECT: Check only changed files that are staged
+pnpm lint:php:changes:staged
+
+# ✅ CORRECT: Lint specific file
+pnpm lint:php -- path/to/file.php
+pnpm lint:php:fix -- path/to/file.php
+
+# ❌ WRONG: Lints entire codebase
+pnpm lint:php
+pnpm lint:php:fix
+```
+
+## Common PHP Linting Issues & Fixes
+
+### Quick Reference Table
+
+| Issue | Wrong | Correct |
+|-------|-------|---------|
+| **Translators comment** | Before return | Before function call |
+| **File docblock (PSR-12)** | After `declare()` | Before `declare()` |
+| **Indentation** | Spaces | Tabs only |
+| **Array alignment** | Inconsistent | Align `=>` with context |
+| **Equals alignment** | Inconsistent | Match surrounding style |
+
+## Translators Comment Placement
+
+Translators comments must be placed **immediately before the translation function call**, not before the return statement.
+
+### Wrong - Comment Before Return
+
+```php
+/* translators: %s: Gateway name. */
+return sprintf(
+    esc_html__( '%s is not supported.', 'woocommerce' ),
+    'Gateway'
+);
+```
+
+### Correct - Comment Before Translation Function
+
+```php
+return sprintf(
+    /* translators: %s: Gateway name. */
+    esc_html__( '%s is not supported.', 'woocommerce' ),
+    'Gateway'
+);
+```
+
+### Multiple Parameters
+
+```php
+return sprintf(
+    /* translators: 1: Gateway name, 2: Country code. */
+    esc_html__( '%1$s is not available in %2$s.', 'woocommerce' ),
+    $gateway_name,
+    $country_code
+);
+```
+
+## PSR-12 File Header Order
+
+File docblocks must come **before** the `declare()` statement, not after.
+
+### Wrong - Docblock After declare()
+
+```php
+<?php
+declare( strict_types=1 );
+
+/**
+ * File docblock
+ *
+ * @package WooCommerce
+ */
+```
+
+### Correct - Docblock Before declare()
+
+```php
+<?php
+/**
+ * File docblock
+ *
+ * @package WooCommerce
+ */
+
+declare( strict_types=1 );
+```
+
+## Mock Classes with Intentional Violations
+
+When creating mock classes that must match external class names, use phpcs:disable comments:
+
+```php
+if ( ! class_exists( 'WC_Payments_Utils' ) ) {
+    /**
+     * Mock class for testing.
+     *
+     * phpcs:disable Squiz.Classes.ClassFileName.NoMatch
+     * phpcs:disable Suin.Classes.PSR4.IncorrectClassName
+     * phpcs:disable Squiz.Classes.ValidClassName.NotCamelCaps
+     */
+    class WC_Payments_Utils {
+        /**
+         * Mock implementation.
+         */
+        public static function supported_countries() {
+            return array( 'US', 'GB' );
+        }
+    }
+}
+```
+
+## Multi-line Condition Alignment
+
+Use tabs for continuation lines in multi-line conditions:
+
+```php
+// Correct - tabs for continuation
+if ( class_exists( '\WC_Payments_Utils' ) &&
+    is_callable( '\WC_Payments_Utils::supported_countries' ) ) {
+    // code
+}
+
+// Also correct - align with opening parenthesis
+if ( class_exists( '\WC_Payments_Utils' ) &&
+     is_callable( '\WC_Payments_Utils::supported_countries' ) ) {
+    // code
+}
+```
+
+## Unused Closure Parameters
+
+When creating closures with parameters required by signature but unused, use `unset()` to avoid PHPCS errors:
+
+### The Problem
+
+```php
+// ❌ WRONG - PHPCS error: Generic.CodeAnalysis.UnusedFunctionParameter
+'callback' => function ( string $return_url ) {
+    return array( 'success' => true );
+},
+```
+
+### The Solution
+
+```php
+// ✅ CORRECT - unset unused parameters
+'callback' => function ( string $return_url ) {
+    unset( $return_url ); // Avoid parameter not used PHPCS errors.
+    return array( 'success' => true );
+},
+```
+
+### Multiple Unused Parameters
+
+```php
+'callback' => function ( $arg1, $arg2, $arg3 ) {
+    unset( $arg1, $arg2 ); // Avoid parameter not used PHPCS errors.
+    return $arg3;
+},
+```
+
+### Common Scenarios
+
+- Mock method callbacks in PHPUnit tests
+- Array/filter callbacks where signature is fixed
+- Interface implementations with unused parameters
+
+**Reference:** `tests/php/src/Internal/Admin/Settings/PaymentsRestControllerIntegrationTest.php:1647-1655`
+
+## Array and Operator Alignment
+
+### Array Arrow Alignment
+
+Align `=>` arrows consistently within each array context:
+
+```php
+// Correct - aligned arrows
+$options = array(
+    'gateway_id'   => 'stripe',
+    'enabled'      => true,
+    'country_code' => 'US',
+);
+
+// Also correct - no alignment for short arrays
+$small = array(
+    'id' => 123,
+    'name' => 'Test',
+);
+```
+
+### Assignment Operator Alignment
+
+Match the surrounding code style:
+
+```php
+// When surrounding code aligns, align:
+$gateway_id     = 'stripe';
+$enabled        = true;
+$country_code   = 'US';
+
+// When surrounding code doesn't align, don't align:
+$gateway_id = 'stripe';
+$enabled = true;
+$country_code = 'US';
+```
+
+## Indentation Rules
+
+**Always use tabs, never spaces, for indentation.**
+
+```php
+// ✅ Correct - tabs for indentation
+public function process_payment( $order_id ) {
+→   $order = wc_get_order( $order_id );
+→
+→   if ( ! $order ) {
+→   →   return false;
+→   }
+→
+→   return true;
+}
+
+// ❌ Wrong - spaces for indentation
+public function process_payment( $order_id ) {
+    $order = wc_get_order( $order_id );
+
+    if ( ! $order ) {
+        return false;
+    }
+
+    return true;
+}
+```
+
+## Workflow for Fixing PHP Linting Issues
+
+1. **Run linting on changed files:**
+
+   ```bash
+   pnpm lint:php:changes
+   ```
+
+2. **Auto-fix what you can:**
+
+   ```bash
+   pnpm lint:php:fix -- path/to/file.php
+   ```
+
+3. **Review remaining errors** - Common issues that require manual fixing:
+   - Translators comment placement
+   - File docblock order (PSR-12)
+   - Unused closure parameters (add `unset()`)
+
+4. **Address remaining issues manually**
+
+5. **Verify the output is clean:**
+
+   ```bash
+   pnpm lint:php -- path/to/file.php
+   ```
+
+6. **Commit**
+
+## Quick Command Reference
+
+```bash
+# Check changed files
+pnpm lint:php:changes
+
+# Check specific file
+pnpm lint:php -- src/Internal/Admin/ClassName.php
+
+# Fix specific file
+pnpm lint:php:fix -- src/Internal/Admin/ClassName.php
+
+# Check with error details
+vendor/bin/phpcs -s path/to/file.php
+```

package/skills/woocommerce/references/running-tests.md

@@ -0,0 +1,249 @@
+# Running Tests
+
+## Table of Contents
+
+- [PHP Unit Tests](#php-unit-tests)
+    - [Basic Test Commands](#basic-test-commands)
+    - [Examples](#examples)
+- [Common Test Commands](#common-test-commands)
+- [Test Environment](#test-environment)
+- [Troubleshooting Tests](#troubleshooting-tests)
+- [Interpreting Test Output](#interpreting-test-output)
+- [Best Practices](#best-practices)
+- [Test Configuration](#test-configuration)
+- [JavaScript/Jest Tests](#javascriptjest-tests)
+- [Notes](#notes)
+
+## PHP Unit Tests
+
+To run PHP unit tests in the WooCommerce plugin directory, use the following commands:
+
+### Basic Test Commands
+
+```bash
+# Run all PHP unit tests
+pnpm run test:php:env
+
+# Run specific test class
+pnpm run test:php:env -- --filter TestClassName
+
+# Run specific test method
+pnpm run test:php:env -- --filter TestClassName::test_method_name
+
+# Run tests with verbose output
+pnpm run test:php:env -- --verbose --filter TestClassName
+```
+
+### Examples
+
+```bash
+# Run payment extension suggestions tests
+pnpm run test:php:env -- --filter PaymentsExtensionSuggestionsTest
+
+# Run specific test method
+pnpm run test:php:env -- --filter PaymentsExtensionSuggestionsTest::test_get_country_extensions_count_with_merchant_selling_online
+```
+
+## Common Test Commands
+
+### Run Tests for a Directory
+
+```bash
+# Run all tests in a directory
+pnpm run test:php:env -- tests/php/src/Internal/Admin/
+```
+
+### Run Tests Matching a Pattern
+
+```bash
+# Run all Admin tests
+pnpm run test:php:env -- --filter "Admin.*Test"
+
+# Run all tests with "Payment" in the name
+pnpm run test:php:env -- --filter "Payment"
+```
+
+### Stop on First Failure
+
+```bash
+# Useful during development to quickly identify issues
+pnpm run test:php:env -- --stop-on-failure
+```
+
+### Get Test Coverage
+
+```bash
+# Get coverage report (if configured)
+pnpm run test:php:env -- --coverage-text
+```
+
+## Test Environment
+
+### How It Works
+
+Tests run in Docker via `wp-env` with auto-configured WordPress/WooCommerce (PHPUnit 9.6.24, PHP 8.1).
+
+### Environment Setup
+
+The test environment is managed automatically, but you can control it if needed:
+
+```bash
+# Start the test environment
+wp-env start
+
+# Stop the test environment
+wp-env stop
+
+# Restart the test environment
+wp-env restart
+
+# Destroy and recreate the environment
+wp-env destroy
+wp-env start
+```
+
+## Troubleshooting Tests
+
+| Problem | Solution |
+|---------|----------|
+| "Class not found" errors | Run `pnpm install` |
+| Tests hang/fail to start | `wp-env stop && wp-env start` or `wp-env destroy && wp-env start` |
+| Permission errors | Check Docker permissions |
+| Xdebug warnings | Ignore (don't affect results) |
+
+## Interpreting Test Output
+
+### Successful Test Run
+
+```text
+PHPUnit 9.6.24
+
+..................................................  50 / 100 ( 50%)
+..................................................  100 / 100 (100%)
+
+Time: 00:02.345, Memory: 24.00 MB
+
+OK (100 tests, 250 assertions)
+```
+
+### Failed Test
+
+```text
+PHPUnit 9.6.24
+
+.....F.................................................  50 / 100 ( 50%)
+..................................................  100 / 100 (100%)
+
+Time: 00:02.345, Memory: 24.00 MB
+
+There was 1 failure:
+
+1) PaymentsExtensionSuggestionsTest::test_get_country_extensions_count_for_online_merchants with data set "United States" ('US', 5)
+Expected 5 extensions for online merchant in US
+Failed asserting that 4 matches expected 5.
+
+/path/to/test/file.php:123
+
+FAILURES!
+Tests: 100, Assertions: 250, Failures: 1.
+```
+
+### Understanding Failures
+
+Test failures provide:
+
+- **Which test failed:** Test class and method name
+- **Test data:** Data set used (if using data providers)
+- **Expected vs actual:** What was expected and what was received
+- **Location:** File and line number where assertion failed
+
+## Best Practices
+
+### During Development
+
+1. **Run specific tests** for the code you're changing:
+
+   ```bash
+   pnpm run test:php:env -- --filter YourTestClass
+   ```
+
+2. **Use verbose mode** when debugging:
+
+   ```bash
+   pnpm run test:php:env -- --verbose --filter YourTestClass
+   ```
+
+3. **Stop on first failure** to focus on one issue at a time:
+
+   ```bash
+   pnpm run test:php:env -- --stop-on-failure --filter YourTestClass
+   ```
+
+### Before Committing
+
+1. **Run all affected tests:**
+
+   ```bash
+   pnpm run test:php:env -- tests/php/src/Internal/YourFeature/
+   ```
+
+2. **Ensure all tests pass** before committing
+
+3. **Check code quality** (see code-quality.md)
+
+## Test Configuration
+
+Test configuration file: `plugins/woocommerce/phpunit.xml`
+
+This file contains:
+
+- Test suite definitions
+- Bootstrap files
+- Coverage settings
+- Logging configuration
+
+## JavaScript/Jest Tests
+
+### Running JavaScript Tests
+
+To run JavaScript tests for the admin client, navigate to the `client/admin` directory:
+
+```bash
+# Navigate to client/admin directory first
+cd client/admin
+
+# Run all JavaScript tests
+pnpm test:js
+
+# Run tests in watch mode
+pnpm test:js -- --watch
+
+# Run a specific test file
+pnpm test:js -- status-badge.test.tsx
+
+# Run tests with coverage
+pnpm test:js -- --coverage
+```
+
+### Test File Locations
+
+- JavaScript/Jest tests: `client/admin/client/**/*.test.tsx` or `*.test.ts`
+- Jest configuration: `client/admin/jest.config.js`
+
+### Troubleshooting JavaScript Tests
+
+For detailed Jest configuration and testing patterns, see `client/admin/CLAUDE.md`.
+
+Common issues:
+
+- **Tests not found**: Ensure you're in the `client/admin` directory
+- **Module resolution errors**: Run `pnpm install` in the `client/admin` directory
+- **Cache issues**: Try `pnpm test:js -- --clearCache`
+
+## Notes
+
+- The test environment handles WordPress/WooCommerce setup automatically
+- Extension counts in payment tests must match the actual implementation exactly
+- Test data providers are useful for testing multiple scenarios
+- Always check test output for helpful error messages
+- For React/TypeScript testing patterns, refer to `client/admin/CLAUDE.md`

package/skills/woocommerce/references/security-patterns.md

@@ -0,0 +1,109 @@
+# Security Patterns for WooCommerce
+
+This guide covers security best practices for WooCommerce development, focusing on data sanitization, validation, and escaping.
+
+## Data Sanitization (Inputs)
+
+Always sanitize user input before using it in logic or saving to the database.
+
+| Type | Function |
+|------|----------|
+| Text | `sanitize_text_field()` |
+| Email | `sanitize_email()` |
+| URL | `esc_url_raw()` |
+| Key/Slug | `sanitize_key()` |
+| Array | `array_map( 'sanitize_text_field', $array )` |
+
+```php
+$product_name = sanitize_text_field( $_POST['product_name'] ?? '' );
+```
+
+## Data Validation
+
+Verify data before processing it.
+
+```php
+if ( ! is_numeric( $order_id ) ) {
+    return;
+}
+
+if ( ! is_email( $user_email ) ) {
+    throw new Exception( 'Invalid email' );
+}
+```
+
+## Data Escaping (Outputs)
+
+Always escape data right before echoing it. This is the last line of defense against XSS.
+
+| Type | Function |
+|------|----------|
+| HTML Content | `esc_html()` |
+| HTML Attributes | `esc_attr()` |
+| URLs | `esc_url()` |
+| JavaScript | `esc_js()` |
+| textarea | `esc_textarea()` |
+
+```php
+echo '<div class="name">' . esc_html( $name ) . '</div>';
+echo '<input value="' . esc_attr( $value ) . '">';
+```
+
+## Nonces
+
+Always use nonces to protect against CSRF attacks in forms and AJAX requests.
+
+### Form Verification
+
+```php
+// In the form
+wp_nonce_field( 'my_plugin_action', 'my_plugin_nonce' );
+
+// In the processing logic
+if ( ! isset( $_POST['my_plugin_nonce'] ) || ! wp_verify_nonce( $_POST['my_plugin_nonce'], 'my_plugin_action' ) ) {
+    wp_die( 'Security check failed' );
+}
+```
+
+### URL/AJAX Verification
+
+```php
+// Creating link
+$url = wp_nonce_url( admin_url( 'admin-post.php?action=my_action' ), 'my_action_nonce' );
+
+// Verification
+check_admin_referer( 'my_action_nonce' );
+```
+
+## Database Safety
+
+Use `$wpdb->prepare()` for custom SQL queries to prevent SQL injection.
+
+```php
+global $wpdb;
+$id = 123;
+$results = $wpdb->get_results( $wpdb->prepare(
+    "SELECT * FROM {$wpdb->prefix}posts WHERE ID = %d",
+    $id
+) );
+```
+
+## Capabilities and Permissions
+
+Always check if the current user has the authority to perform an action.
+
+```php
+if ( ! current_user_can( 'manage_woocommerce' ) ) {
+    return;
+}
+
+if ( ! $order->get_customer_id() === get_current_user_id() ) {
+    return;
+}
+```
+
+## WooCommerce Specific Security
+
+- Use `WC_Validation` class for common e-commerce validation (postcodes, phone numbers).
+- Use `WC_Data` getters and setters which perform some internal checks.
+- Be careful with `WC_Checkout::process_checkout` and related hooks.