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

package/skills/woocommerce/references/code-quality.md

@@ -0,0 +1,273 @@
+# Code Quality Commands
+
+## Table of Contents
+
+- [Overview](#overview)
+- [PHP Linting](#php-linting)
+- [JavaScript Linting](#javascript-linting)
+- [Markdown Linting](#markdown-linting)
+- [Important Linting Guidelines](#important-linting-guidelines)
+- [Example Workflow](#example-workflow)
+- [Understanding Linting Output](#understanding-linting-output)
+- [Pre-Commit Checklist](#pre-commit-checklist)
+- [Integration with Development Cycle](#integration-with-development-cycle)
+- [Additional Linting Tools](#additional-linting-tools)
+- [Troubleshooting](#troubleshooting)
+- [Notes](#notes)
+
+## Overview
+
+When making changes to the WooCommerce codebase, run these commands to ensure code quality and adherence to coding standards.
+
+For detailed PHP linting patterns and common issues, see [php-linting-patterns.md](php-linting-patterns.md).
+
+For markdown linting rules and workflow, see [markdown-linting.md](markdown-linting.md).
+
+## PHP Linting
+
+### Check for PHP Linting Issues
+
+```bash
+pnpm run lint:changes:branch:php
+```
+
+Checks changed files for WordPress Coding Standards violations (read-only).
+
+### Fix PHP Code Style Issues
+
+```bash
+# Automatically fix PHP code style issues
+pnpm run lint:php:fix
+```
+
+This command:
+
+- Automatically fixes code style violations where possible
+- Applies WordPress Coding Standards formatting
+- Modifies files in place
+- Should be run before committing
+
+### Advanced PHP Linting
+
+If you need more control, you can use phpcs and phpcbf directly:
+
+```bash
+# Check specific file or directory
+vendor/bin/phpcs path/to/file.php
+
+# Check with specific standard
+vendor/bin/phpcs --standard=WordPress path/to/file.php
+
+# Fix specific file
+vendor/bin/phpcbf path/to/file.php
+
+# Show all violations (including warnings)
+vendor/bin/phpcs -s path/to/file.php
+```
+
+## JavaScript Linting
+
+### Check for JS Linting Issues
+
+```bash
+# Run JS linting on changes in your branch
+pnpm run lint:changes:branch:js
+```
+
+This command:
+
+- Checks only JavaScript/TypeScript files changed in your current branch
+- Identifies code style and potential issues
+- Does not modify files
+
+For detailed JavaScript/TypeScript linting configuration and patterns, see `client/admin/CLAUDE.md`.
+
+## Markdown Linting
+
+Always lint markdown files after making changes. See [markdown-linting.md](markdown-linting.md) for complete details.
+
+**Quick commands:**
+
+```bash
+# Auto-fix most issues
+markdownlint --fix path/to/file.md
+
+# Check for remaining errors
+markdownlint path/to/file.md
+```
+
+## Important Linting Guidelines
+
+### Only Fix Code in Your Branch
+
+**Important:** Only fix linting errors for code that has been added or modified in the branch you are working on.
+
+Do not fix linting errors in unrelated code unless specifically asked to do so.
+
+**Why?**
+
+- Keeps pull requests focused on the actual changes
+- Avoids merge conflicts with other branches
+- Makes code review easier
+- Maintains clear git history
+
+### Example Workflow
+
+```bash
+# 1. Make your code changes
+# ... edit files ...
+
+# 2. Check what you've changed
+git status
+git diff
+
+# 3. Run linting on your changes
+pnpm run lint:changes:branch:php
+
+# 4. Fix issues automatically
+pnpm run lint:php:fix
+
+# 5. Review the fixes
+git diff
+
+# 6. If needed, check JavaScript changes
+pnpm run lint:changes:branch:js
+
+# 7. Commit your changes
+git add .
+git commit -m "Your commit message"
+```
+
+## Understanding Linting Output
+
+### PHP CodeSniffer Output
+
+```text
+FILE: /path/to/file.php
+----------------------------------------------------------------------
+FOUND 2 ERRORS AFFECTING 2 LINES
+----------------------------------------------------------------------
+ 12 | ERROR | [x] Expected 1 space after opening parenthesis;
+    |       |     0 found
+ 25 | ERROR | [ ] Variable "$orderID" is not in valid snake_case
+    |       |     format
+----------------------------------------------------------------------
+```
+
+**Legend:**
+
+- `[x]` - Can be fixed automatically with phpcbf/lint:php:fix
+- `[ ]` - Requires manual fixing
+
+### Common PHP Issues
+
+1. **Spacing issues** - Usually auto-fixable
+
+   ```php
+   // Wrong
+   if($condition){
+
+   // Right
+   if ( $condition ) {
+   ```
+
+2. **Naming conventions** - Requires manual fix
+
+   ```php
+   // Wrong
+   $orderID
+
+   // Right
+   $order_id
+   ```
+
+3. **Yoda conditions** - Requires manual fix
+
+   ```php
+   // Wrong
+   if ( $value === 'active' )
+
+   // Right
+   if ( 'active' === $value )
+   ```
+
+## Pre-Commit Checklist
+
+Before committing your changes:
+
+- [ ] Run `pnpm run lint:changes:branch:php`
+- [ ] Run `pnpm run lint:php:fix` if issues found
+- [ ] Run `pnpm run lint:changes:branch:js` if you modified JS files
+- [ ] Review all automatic fixes with `git diff`
+- [ ] Address any remaining issues that can't be auto-fixed
+- [ ] Run tests to ensure fixes didn't break functionality
+
+## Integration with Development Cycle
+
+Code quality checks fit into the overall development workflow:
+
+1. Make code changes
+2. Run relevant tests (see running-tests.md)
+3. **Run linting checks** ← You are here
+4. **Fix code quality issues** ← You are here
+5. Commit changes only after tests pass and linting is clean
+
+## Additional Linting Tools
+
+### Running Other pnpm Scripts
+
+WooCommerce may have additional linting scripts. Check available scripts:
+
+```bash
+# See all available scripts
+pnpm run
+
+# Common additional scripts may include:
+pnpm run lint           # Lint all files
+pnpm run lint:fix       # Fix all auto-fixable issues
+pnpm run lint:php       # PHP linting only
+pnpm run lint:js        # JavaScript linting only
+```
+
+## Troubleshooting
+
+### Linting Command Not Found
+
+**Problem:** Command fails with "command not found"
+
+**Solution:** Install dependencies:
+
+```bash
+pnpm install
+```
+
+### Too Many Issues Reported
+
+**Problem:** Linting reports issues in files you didn't change
+
+**Solution:** Make sure you're using the branch-specific commands:
+
+```bash
+# Good - only checks your changes
+pnpm run lint:changes:branch:php
+
+# Avoid - checks entire codebase
+pnpm run lint:php
+```
+
+### Conflicts After Auto-Fix
+
+**Problem:** Git conflicts after running lint:php:fix
+
+**Solution:**
+
+1. Review the automatic fixes: `git diff`
+2. If fixes are incorrect, revert: `git checkout -- path/to/file.php`
+3. Address the issues manually instead
+
+## Notes
+
+- Code quality tools help maintain consistency across the codebase
+- Automatic fixes save time but should always be reviewed
+- Some issues require manual intervention and understanding of the context
+- Linting is required before committing to ensure code quality standards

package/skills/woocommerce/references/code-review-guide.md

@@ -0,0 +1,71 @@
+
+# WooCommerce Code Review
+
+Review code changes against WooCommerce coding standards and conventions.
+
+## Critical Violations to Flag
+
+### Backend PHP Code
+
+Consult the `woocommerce-backend-dev` skill for detailed standards. Using these standards as guidance, flag these violations and other similar ones:
+
+**Architecture & Structure:**
+
+- ❌ **Standalone functions** - Must use class methods ([file-entities.md](file-entities.md))
+- ❌ **Using `new` for DI-managed classes** - Classes in `src/` must use `$container->get()` ([dependency-injection.md](dependency-injection.md))
+- ❌ **Classes outside `src/Internal/`** - Default location unless explicitly public ([file-entities.md](file-entities.md))
+
+**Naming & Conventions:**
+
+- ❌ **camelCase naming** - Must use snake_case for methods/variables/hooks ([code-entities.md](code-entities.md))
+- ❌ **Yoda condition violations** - Must follow WordPress Coding Standards ([coding-conventions.md](coding-conventions.md))
+
+**Documentation:**
+
+- ❌ **Missing `@since` annotations** - Required for public/protected methods and hooks ([code-entities.md](code-entities.md))
+- ❌ **Missing docblocks** - Required for all hooks and methods ([code-entities.md](code-entities.md))
+- ❌ **Verbose docblocks** - Keep concise, one line is ideal ([code-entities.md](code-entities.md))
+
+**Data Integrity:**
+
+- ❌ **Missing validation** - Must verify state before deletion/modification ([data-integrity.md](data-integrity.md))
+
+**Testing:**
+
+- ❌ **Using `$instance` in tests** - Must use `$sut` variable name ([unit-tests.md](unit-tests.md))
+- ❌ **Missing `@testdox`** - Required in test method docblocks ([unit-tests.md](unit-tests.md))
+- ❌ **Test file naming** - Must follow convention for `includes/` vs `src/` ([unit-tests.md](unit-tests.md))
+
+### UI Text & Copy
+
+Consult the `woocommerce-copy-guidelines` skill. Flag:
+
+- ❌ **Title Case in UI** - Must use sentence case ([sentence-case.md](sentence-case.md))
+    - Wrong: "Save Changes", "Order Details", "Payment Options"
+    - Correct: "Save changes", "Order details", "Payment options"
+    - Exceptions: Proper nouns (WooPayments), acronyms (API), brand names
+
+## Review Approach
+
+1. **Scan for critical violations** listed above
+2. **Cite specific skill files** when flagging issues
+3. **Provide correct examples** from the skill documentation
+4. **Group related issues** for clarity
+5. **Be constructive** - explain why the standard exists when relevant
+
+## Output Format
+
+For each violation found:
+
+```text
+❌ [Issue Type]: [Specific problem]
+Location: [File path and line number]
+Standard: [Link to relevant skill file]
+Fix: [Brief explanation or example]
+```
+
+## Notes
+
+- All detailed standards are in the `woocommerce-backend-dev`, `woocommerce-dev-cycle`, and `woocommerce-copy-guidelines` skills
+- Consult those skills for complete context and examples
+- When in doubt, refer to the specific skill documentation linked above

package/skills/woocommerce/references/coding-conventions.md

@@ -0,0 +1,182 @@
+# General Coding Conventions
+
+## Table of Contents
+
+- [Code Clarity and Comments](#code-clarity-and-comments)
+- [WordPress Coding Standards](#wordpress-coding-standards)
+- [Internationalization (i18n)](#internationalization-i18n)
+- [Modern CRUD (Getters/Setters)](#modern-crud-getterssetters)
+- [Null Coalescing Operator](#null-coalescing-operator)
+- [Ternary Operator](#ternary-operator)
+- [call_user_func_array() Usage](#call_user_func_array-usage)
+- [Linting](#linting)
+
+## Code Clarity and Comments
+
+Write self-explanatory code. Use comments sparingly - only for non-obvious insights.
+
+**Good - Code explains itself:**
+
+```php
+if ( $order->is_draft() && $user->can_delete_drafts() ) {
+    $order->delete();
+}
+```
+
+**Avoid - Over-commented:**
+
+```php
+// Check if order is draft
+if ( $order->is_draft() ) {
+    // Check if user has permission
+    if ( $user->can_delete_drafts() ) {
+        // Delete the order
+        $order->delete();
+    }
+}
+```
+
+**When to add comments:**
+
+- Unusual decisions, workarounds, or non-obvious business logic
+- Performance considerations
+
+**When NOT to add comments:**
+
+- Explaining what code does (code should be self-explanatory)
+- Restating the obvious
+
+## WordPress Coding Standards
+
+Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/):
+
+- **Yoda conditions**: `'true' === $value` not `$value === 'true'`
+- **Spacing**: Spaces around operators, inside parentheses
+- **Braces**: Opening on same line, closing on new line
+- **Naming**: snake_case for functions and variables
+
+## Internationalization (i18n)
+
+**Mandatory for all user-facing strings.**
+
+- Use `woocommerce` text domain for WooCommerce core-like features.
+- Use `esc_html__`, `esc_attr__`, etc., for output.
+- Avoid HTML in strings.
+- See [php-i18n-patterns.md](php-i18n-patterns.md) for details.
+
+## Modern CRUD (Getters/Setters)
+
+**Always prefer `WC_Data` methods over direct meta access.**
+
+**Good:**
+```php
+$order = wc_get_order( $id );
+$total = $order->get_total();
+$meta  = $order->get_meta( '_my_key' );
+$order->update_meta_data( '_my_key', 'value' );
+$order->save();
+```
+
+**Avoid:**
+```php
+$total = get_post_meta( $id, '_order_total', true );
+update_post_meta( $id, '_my_key', 'value' );
+```
+
+Why? `WC_Data` handles High-Performance Order Storage (HPOS) and standard post meta automatically. Direct `get_post_meta` will fail when HPOS is enabled.
+
+## Null Coalescing Operator
+
+Use `??` instead of `isset` checks for array access.
+
+**Good:**
+
+```php
+if ( 34 === ( $foo['bar'] ?? null ) ) {
+    // ...
+}
+
+$value = $options['setting'] ?? 'default';
+```
+
+**Avoid:**
+
+```php
+if ( isset( $foo['bar'] ) && 34 === $foo['bar'] ) {
+    // ...
+}
+
+if ( isset( $options['setting'] ) ) {
+    $value = $options['setting'];
+} else {
+    $value = 'default';
+}
+```
+
+## Ternary Operator
+
+Prefer the ternary operator over if-else statements for simple conditional returns or assignments, except for very complex cases.
+
+**Good:**
+
+```php
+return $condition ? $true_value : $false_value;
+
+$result = $is_enabled ? 'enabled' : 'disabled';
+
+$price = $has_discount ? $product->get_sale_price() : $product->get_regular_price();
+```
+
+**Avoid:**
+
+```php
+if ( $condition ) {
+    return $true_value;
+}
+return $false_value;
+
+if ( $is_enabled ) {
+    $result = 'enabled';
+} else {
+    $result = 'disabled';
+}
+```
+
+**Exception:** Use traditional if-else for complex conditions or when multiple statements are needed in each branch.
+
+```php
+// OK to use if-else when complex logic is involved
+if ( $order->needs_shipping() && ! $order->has_valid_address() ) {
+    $this->logger->log( 'Invalid shipping address' );
+    $this->notify_customer( $order );
+    return false;
+} else {
+    return true;
+}
+```
+
+## call_user_func_array() Usage
+
+When using `call_user_func_array()`, always use **positional arguments** (numerically indexed array) instead of named/associative arrays for the arguments parameter.
+
+The function uses array values in order and ignores keys, so named keys are misleading.
+
+**Correct:**
+
+```php
+call_user_func_array( array( $obj, 'method' ), array( $code ) );
+call_user_func_array( array( $obj, 'process' ), array( $id, $status, $data ) );
+```
+
+**Wrong:**
+
+```php
+call_user_func_array( array( $obj, 'method' ), array( 'country_code' => $code ) );
+call_user_func_array( array( $obj, 'process' ), array( 'order_id' => $id, 'status' => $status ) );
+```
+
+## Linting
+
+Only fix linting errors for code that has been added or modified in the branch you are working on.
+
+Do not fix linting errors in unrelated code unless specifically asked to do so.

package/skills/woocommerce/references/copy-guidelines-guide.md

@@ -0,0 +1,17 @@
+
+# WooCommerce Copy Guidelines
+
+This skill provides guidelines for writing user-facing copy in WooCommerce, including UI text, labels, buttons, messages, and documentation.
+
+## Instructions
+
+Follow these guidelines when writing any user-facing text:
+
+1. **Sentence case**: See [sentence-case.md](sentence-case.md) for rules on using sentence case for all UI text
+
+## Key Principles
+
+- Always use sentence case for UI text, not title case
+- Keep copy concise and action-oriented
+- Use clear, simple language
+- Be consistent with existing WooCommerce copy patterns

package/skills/woocommerce/references/data-integrity.md

@@ -0,0 +1,164 @@
+# Data Integrity Guidelines
+
+## Table of Contents
+
+- [Preventing Accidental Data Loss](#preventing-accidental-data-loss)
+    - [Validation Before Deletion](#validation-before-deletion)
+    - [Consider Race Conditions](#consider-race-conditions)
+    - [Session-Based Operations](#session-based-operations)
+- [When in Doubt, Ask](#when-in-doubt-ask)
+- [Security Checklist for Data Operations](#security-checklist-for-data-operations)
+- [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
+
+## Preventing Accidental Data Loss
+
+Always verify entity state before deletion/modification to prevent accidental data loss.
+
+### Validation Before Deletion
+
+Always verify the state of the entity before deleting or modifying it.
+
+#### Example: Deleting a draft order
+
+```php
+// GOOD: Verify order status before deletion
+public function delete_draft_order( int $order_id ) {
+    $order = wc_get_order( $order_id );
+
+    if ( ! $order ) {
+        return false;
+    }
+
+    // Verify it's actually a draft or checkout-draft
+    if ( ! in_array( $order->get_status(), array( 'draft', 'checkout-draft' ), true ) ) {
+        throw new \Exception( 'Cannot delete non-draft order' );
+    }
+
+    return $order->delete( true );
+}
+
+// BAD: No verification
+public function delete_draft_order( int $order_id ) {
+    $order = wc_get_order( $order_id );
+    return $order->delete( true );  // Could delete any order!
+}
+```
+
+### Consider Race Conditions
+
+Think about whether race conditions could occur that might affect the wrong data.
+
+#### Example: User-specific data deletion
+
+```php
+// GOOD: Verify ownership before deletion
+public function delete_user_cart_item( int $item_id, int $user_id ) {
+    $item = $this->get_cart_item( $item_id );
+
+    if ( ! $item ) {
+        return false;
+    }
+
+    // Prevent race condition: verify item belongs to this user
+    if ( (int) $item->get_user_id() !== $user_id ) {
+        throw new \Exception( 'Cannot delete item belonging to another user' );
+    }
+
+    return $this->data_store->delete( $item_id );
+}
+
+// BAD: Race condition possible
+public function delete_user_cart_item( int $item_id, int $user_id ) {
+    // Another user could have taken this item in the meantime
+    return $this->data_store->delete( $item_id );
+}
+```
+
+### Session-Based Operations
+
+For session-based operations (like cart or checkout), verify session ownership.
+
+#### Example: Clearing checkout data
+
+```php
+// GOOD: Verify session ownership
+public function clear_checkout_data( int $session_id ) {
+    $current_session_id = WC()->session->get_customer_id();
+
+    if ( $session_id !== $current_session_id ) {
+        throw new \Exception( 'Cannot clear checkout data for another session' );
+    }
+
+    WC()->session->set( 'checkout_data', array() );
+}
+```
+
+## When in Doubt, Ask
+
+If unsure about data operations, ask for clarification about:
+
+- Required state/ownership verifications
+- Soft delete vs hard delete requirements
+- Protected states that prevent deletion
+
+## Security Checklist for Data Operations
+
+Before implementing code that modifies or deletes data:
+
+- [ ] Verify entity exists
+- [ ] Verify entity state (status, type, etc.)
+- [ ] Verify ownership (user_id, session_id, etc.)
+- [ ] Check for race conditions
+- [ ] Consider using soft delete (trash) instead of hard delete
+- [ ] Add appropriate error handling
+- [ ] Log sensitive operations for audit trail
+- [ ] Add capability checks (`current_user_can()`)
+
+## Common Pitfalls to Avoid
+
+### 1. Trusting User Input
+
+```php
+// BAD
+$order_id = $_POST['order_id'];
+$order->delete( true );
+
+// GOOD
+$order_id = absint( $_POST['order_id'] );
+if ( ! current_user_can( 'delete_order', $order_id ) ) {
+    wp_die( 'Unauthorized' );
+}
+// ... additional validation ...
+```
+
+### 2. Batch Operations Without Verification
+
+```php
+// BAD: Deletes all without verification
+foreach ( $order_ids as $order_id ) {
+    wc_delete_order( $order_id );
+}
+
+// GOOD: Verify each item
+foreach ( $order_ids as $order_id ) {
+    $order = wc_get_order( $order_id );
+    if ( $order && $order->get_status() === 'draft' ) {
+        wc_delete_order( $order_id );
+    }
+}
+```
+
+### 3. Ignoring Return Values
+
+```php
+// BAD: Doesn't check if operation succeeded
+$order->delete( true );
+wp_send_json_success();
+
+// GOOD: Check result
+if ( $order->delete( true ) ) {
+    wp_send_json_success();
+} else {
+    wp_send_json_error( 'Failed to delete order' );
+}
+```