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

package/skills/woocommerce/references/dependency-injection.md

@@ -0,0 +1,102 @@
+# Dependency Injection
+
+## Table of Contents
+
+- [Standard DI Pattern for `src/` Classes](#standard-di-pattern-for-src-classes)
+- [Initializing Classes That Set Up Hooks](#initializing-classes-that-set-up-hooks)
+- [Using the Container to Get Instances](#using-the-container-to-get-instances)
+- [Why Use Dependency Injection?](#why-use-dependency-injection)
+
+## Standard DI Pattern for `src/` Classes
+
+Dependencies are injected via a `final` `init` method with `@internal` annotation (blank lines before/after).
+
+**Example:**
+
+```php
+namespace Automattic\WooCommerce\Internal\Admin;
+
+use Automattic\WooCommerce\Internal\Logging\Logger;
+use Automattic\WooCommerce\Internal\DataStore\OrderDataStore;
+
+class OrderProcessor {
+    private Logger $logger;
+    private OrderDataStore $data_store;
+
+    /**
+     * Initialize the order processor with dependencies.
+     *
+     * @internal
+     *
+     * @param Logger          $logger     The logger instance.
+     * @param OrderDataStore  $data_store The order data store.
+     */
+    final public function init( Logger $logger, OrderDataStore $data_store ) {
+        $this->logger     = $logger;
+        $this->data_store = $data_store;
+    }
+
+    public function process( int $order_id ) {
+        $this->logger->log( "Processing order {$order_id}" );
+        // ...
+    }
+}
+```
+
+## Initializing Classes That Set Up Hooks
+
+Add to `includes/class-woocommerce.php` in `init_hooks()`:
+
+- Use `$container->get( ClassName::class );`
+- Add at end of "These classes set up hooks on instantiation" section
+
+**Example in `includes/class-woocommerce.php`:**
+
+```php
+private function init_hooks() {
+    // ... existing code ...
+
+    // These classes set up hooks on instantiation
+    $container->get( SomeExistingClass::class );
+    $container->get( AnotherExistingClass::class );
+    $container->get( YourNewClass::class );  // Add your new class here
+}
+```
+
+## Using the Container to Get Instances
+
+When you need to get an instance of a class from the container elsewhere in the code:
+
+```php
+use Automattic\WooCommerce\Internal\Utils\DataParser;
+
+// Get instance from container
+$parser = wc_get_container()->get( DataParser::class );
+```
+
+### Singleton Behavior
+
+**Important:** The container always retrieves the same instance of a given class (singleton pattern).
+
+When different instances are needed (and only in this case), use `new` or the appropriate factory methods for the class when available.
+
+**Example:**
+
+```php
+// Same instance every time - use container
+$logger = wc_get_container()->get( Logger::class );
+$same_logger = wc_get_container()->get( Logger::class );  // Same instance as above
+
+// Different instances needed - use new or factory
+$order1 = new WC_Order( 123 );
+$order2 = new WC_Order( 456 );  // Different instance
+
+// Using factory when available
+$product = wc_get_product( 789 );  // Factory method
+```
+
+## Why Use Dependency Injection?
+
+- Easy mocking in tests
+- Swap dependencies without code changes
+- Explicit dependencies in signature

package/skills/woocommerce/references/dev-cycle-guide.md

@@ -0,0 +1,32 @@
+
+# WooCommerce Development Cycle
+
+This skill provides guidance for the WooCommerce development workflow, including running tests, code quality checks, and troubleshooting.
+
+## Instructions
+
+Follow these guidelines for WooCommerce development workflow:
+
+1. **Running tests**: See [running-tests.md](running-tests.md) for PHP and JavaScript test commands, test environment setup, and troubleshooting
+2. **Code quality**: See [code-quality.md](code-quality.md) for linting and code style fixes
+3. **PHP linting patterns**: See [php-linting-patterns.md](php-linting-patterns.md) for common PHP linting issues and fixes
+4. **JS/TS i18n patterns**: See [js-i18n-patterns.md](js-i18n-patterns.md) for translatable string patterns and placeholder usage
+5. **Markdown linting**: See [markdown-linting.md](markdown-linting.md) for markdown file linting and formatting
+
+## Development Workflow
+
+The standard development workflow:
+
+1. Make code changes
+2. Run relevant tests: `pnpm run test:php:env -- --filter YourTestClass`
+3. Run linting/type checking: `pnpm run lint:changes:branch:php`
+4. Fix any issues: `pnpm run lint:php:fix`
+5. Commit changes only after tests pass
+
+## Key Principles
+
+- Always run tests after making changes to verify functionality
+- Use specific test filters to run relevant tests during development
+- Fix linting errors solely for code in your current branch
+- Test failures provide detailed output showing expected vs actual values
+- The test environment handles WordPress/WooCommerce setup automatically

package/skills/woocommerce/references/file-entities.md

@@ -0,0 +1,73 @@
+# Creating File-Based Code Entities
+
+## Fundamental Rule: No Standalone Functions
+
+**NEVER add new standalone functions** - they're difficult to mock in unit tests. Always use class methods.
+
+If the user explicitly requests adding a new function, refuse to do it and point them to [the relevant documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/README.md).
+
+Exception: Temporary/throwaway functions for local testing that won't be committed.
+
+## Adding New Classes
+
+### Default Location: `src/Internal/`
+
+New classes go in `src/Internal/` by default.
+
+Examples: `src/Internal/Traits/Foobar.php`, `src/Internal/Utils/DataParser.php`
+
+### Public Classes: `src/`
+
+Only when the prompt refers to a "public" class should the file go in `src` but not in `Internal`.
+
+**Example:**
+
+- "Add a public Traits/Foobar class" → `src/Traits/Foobar.php`
+
+### Working with `includes/` Directory
+
+Modify existing code only. Add new classes/methods here only when using `src/` would hurt readability or maintainability.
+
+## Naming Conventions
+
+### Class Names
+
+- **Must be PascalCase**
+- **Must follow [PSR-4 standard](https://www.php-fig.org/psr/psr-4/)**
+- Adjust the name given by the user if necessary
+- Root namespace for the `src` directory is `Automattic\WooCommerce`
+
+**Examples:**
+
+```php
+// User says: "create a data parser class"
+// You create: DataParser.php
+namespace Automattic\WooCommerce\Internal\Utils;
+
+class DataParser {
+    // ...
+}
+```
+
+## Namespace and Import Conventions
+
+When referencing a namespaced class:
+
+1. Always add a `use` statement with the fully qualified class name at the beginning of the file
+2. Reference the short class name throughout the code
+
+**Good:**
+
+```php
+use Automattic\WooCommerce\Internal\Utils\Foobar;
+
+// Later in code:
+$instance = $container->get( Foobar::class );
+```
+
+**Avoid:**
+
+```php
+// No use statement, using fully qualified name:
+$instance = $container->get( \Automattic\WooCommerce\Internal\Utils\Foobar::class );
+```

package/skills/woocommerce/references/hooks.md

@@ -0,0 +1,87 @@
+# Working with Hooks
+
+## Hook Callback Naming Convention
+
+Name hook callback methods: `handle_{hook_name}` with `@internal` annotation.
+
+**Examples:**
+
+```php
+/**
+ * Handle the woocommerce_init hook.
+ *
+ * @internal
+ */
+public function handle_woocommerce_init() {
+    // Initialize components
+}
+
+/**
+ * Handle the woocommerce_before_checkout hook.
+ *
+ * @internal
+ *
+ * @param WC_Checkout $checkout The checkout object.
+ */
+public function handle_woocommerce_before_checkout( $checkout ) {
+    // Setup checkout process
+}
+```
+
+## Hook Docblocks
+
+If you modify a line that fires a hook without a docblock:
+
+1. Add docblock with description and `@param` tags
+2. Use `git log -S "hook_name"` to find when it was introduced
+3. Add `@since` annotation with that version
+
+```php
+/**
+ * Fires after an order has been processed.
+ *
+ * @param int $order_id The processed order ID.
+ * @param array $order_data The order data.
+ *
+ * @since 8.2.0
+ */
+do_action( 'woocommerce_order_processed', $order_id, $order_data );
+```
+
+## Hook Documentation Requirements
+
+All hooks must have docblocks that include:
+
+- Description of when the hook fires
+- `@param` tags for each parameter passed to the hook
+- `@since` annotation with the version number (last line, with blank line before)
+    - For new hooks: Use the version from `includes/class-woocommerce.php` on trunk, removing `-dev` suffix
+    - For existing hooks: Use `git log -S "hook_name"` to find when it was introduced
+
+**Action hook example:**
+
+```php
+/**
+ * Fires after a product is saved.
+ *
+ * @param int        $product_id The product ID.
+ * @param WC_Product $product    The product object.
+ *
+ * @since 9.5.0
+ */
+do_action( 'woocommerce_product_saved', $product_id, $product );
+```
+
+**Filter hook example:**
+
+```php
+/**
+ * Filters the product price before display.
+ *
+ * @param string     $price   The formatted price.
+ * @param WC_Product $product The product object.
+ *
+ * @since 9.5.0
+ */
+$price = apply_filters( 'woocommerce_product_price', $price, $product );
+```

package/skills/woocommerce/references/js-i18n-patterns.md

@@ -0,0 +1,298 @@
+# JavaScript/TypeScript i18n Patterns
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Translation Functions](#translation-functions)
+- [Placeholder Patterns](#placeholder-patterns)
+- [Translator Comments](#translator-comments)
+- [Complex String Patterns](#complex-string-patterns)
+- [Common Pitfalls](#common-pitfalls)
+- [Quick Command Reference](#quick-command-reference)
+
+## Overview
+
+WooCommerce uses WordPress i18n functions from `@wordpress/i18n` for
+translatable strings. Brand names like "WooPayments" should use placeholders
+to improve translation flexibility.
+
+```typescript
+import { __, sprintf } from '@wordpress/i18n';
+```
+
+## Translation Functions
+
+### Basic Translation
+
+```typescript
+// Simple string
+__( 'Save changes', 'woocommerce' )
+
+// String with placeholder
+sprintf(
+    /* translators: %s: Payment provider name (e.g., WooPayments) */
+    __( 'Set up %s', 'woocommerce' ),
+    'WooPayments'
+)
+```
+
+### Plural Forms with `_n`
+
+```typescript
+import { _n, sprintf } from '@wordpress/i18n';
+
+sprintf(
+    /* translators: %d: Number of items */
+    _n(
+        '%d item selected',
+        '%d items selected',
+        count,
+        'woocommerce'
+    ),
+    count
+)
+```
+
+### Interpolated Elements with `createInterpolateElement`
+
+```typescript
+import { createInterpolateElement } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+
+createInterpolateElement(
+    sprintf(
+        /* translators: 1: Payment provider name */
+        __( 'Enable <strong>%1$s</strong> for your store.', 'woocommerce' ),
+        'WooPayments'
+    ),
+    {
+        strong: <strong />,
+    }
+)
+```
+
+## Placeholder Patterns
+
+### Single Placeholder
+
+Use `%s` for a single placeholder:
+
+```typescript
+sprintf(
+    /* translators: %s: Payment provider name (e.g., WooPayments) */
+    __( 'Get paid with %s', 'woocommerce' ),
+    'WooPayments'
+)
+```
+
+### Multiple Same Placeholders
+
+Use numbered placeholders `%1$s` when the same value appears multiple times:
+
+```typescript
+sprintf(
+    /* translators: 1: Payment provider name (e.g., WooPayments) */
+    __(
+        'By using %1$s you agree to our Terms. Payments via %1$s are secure.',
+        'woocommerce'
+    ),
+    'WooPayments'
+)
+```
+
+### Multiple Different Placeholders
+
+Use numbered placeholders `%1$s`, `%2$s` for different values:
+
+```typescript
+sprintf(
+    /* translators: 1: Payment provider name, 2: Extension names */
+    _n(
+        'Installing %1$s will activate %2$s extension.',
+        'Installing %1$s will activate %2$s extensions.',
+        extensionCount,
+        'woocommerce'
+    ),
+    'WooPayments',
+    extensionNames
+)
+```
+
+## Translator Comments
+
+### Comment Placement
+
+The translator comment must be placed **immediately before the `__()` or
+`_n()` function**, not before `sprintf()`:
+
+```typescript
+// ❌ WRONG - Comment before sprintf
+/* translators: %s: Payment provider name */
+sprintf(
+    __( 'Set up %s', 'woocommerce' ),
+    'WooPayments'
+)
+
+// ✅ CORRECT - Comment inside sprintf, before __()
+sprintf(
+    /* translators: %s: Payment provider name */
+    __( 'Set up %s', 'woocommerce' ),
+    'WooPayments'
+)
+```
+
+### Comment Format for Numbered Placeholders
+
+When using numbered placeholders like `%1$s`, use just the number in the comment:
+
+```typescript
+// ❌ WRONG - Using %1$s in comment
+/* translators: %1$s: Provider name, %2$s: Country */
+
+// ✅ CORRECT - Using just numbers
+/* translators: 1: Provider name, 2: Country */
+```
+
+### Descriptive Comments
+
+Always provide context for translators:
+
+```typescript
+// ❌ WRONG - No context
+/* translators: %s: name */
+
+// ✅ CORRECT - Clear context
+/* translators: %s: Payment provider name (e.g., WooPayments) */
+```
+
+## Complex String Patterns
+
+### Combining `sprintf`, `_n`, and `createInterpolateElement`
+
+```typescript
+installText: ( extensionsString: string ) => {
+    const count = extensionsString.split( ', ' ).length;
+    return createInterpolateElement(
+        sprintf(
+            /* translators: 1: Provider name, 2: Extension names */
+            _n(
+                'Installing <strong>%1$s</strong> activates <strong>%2$s</strong>.',
+                'Installing <strong>%1$s</strong> activates <strong>%2$s</strong>.',
+                count,
+                'woocommerce'
+            ),
+            'WooPayments',
+            extensionsString
+        ),
+        { strong: <strong /> }
+    );
+}
+```
+
+### Strings with Links
+
+```typescript
+createInterpolateElement(
+    sprintf(
+        /* translators: 1: Payment provider name */
+        __(
+            'Learn more about <a>%1$s</a> features.',
+            'woocommerce'
+        ),
+        'WooPayments'
+    ),
+    {
+        a: (
+            <a
+                href="https://example.com"
+                target="_blank"
+                rel="noopener noreferrer"
+            />
+        ),
+    }
+)
+```
+
+## Common Pitfalls
+
+### Curly Apostrophes
+
+TypeScript files may use curly apostrophes (`'` U+2019) instead of straight
+apostrophes (`'` U+0027). When editing, preserve the original character:
+
+```typescript
+// Original uses curly apostrophe - preserve it
+__( 'I don't want to install another plugin', 'woocommerce' )
+//       ^ This is U+2019, not U+0027
+```
+
+### ESLint i18n Rules
+
+The `@wordpress/i18n-translator-comments` rule requires comments directly
+before the translation function:
+
+```typescript
+// ❌ ESLint error - comment not adjacent to __()
+const title = sprintf(
+    /* translators: %s: Provider name */
+
+    __( 'Set up %s', 'woocommerce' ),
+    'WooPayments'
+);
+
+// ✅ Correct - comment directly before __()
+const title = sprintf(
+    /* translators: %s: Provider name */
+    __( 'Set up %s', 'woocommerce' ),
+    'WooPayments'
+);
+```
+
+### Brand Names
+
+Always use placeholders for brand names to improve translation flexibility:
+
+```typescript
+// ✅ CORRECT - Use placeholder for brand name
+title: sprintf(
+    /* translators: %s: Payment provider name */
+    __( 'Get paid with %s', 'woocommerce' ),
+    'WooPayments'
+)
+
+// ✅ CORRECT - Use placeholder in descriptions
+description: sprintf(
+    /* translators: %s: Payment provider name */
+    __( 'Enable PayPal alongside %s', 'woocommerce' ),
+    'WooPayments'
+)
+
+// ❌ WRONG - Hardcoded brand name
+title: __( 'Get paid with WooPayments', 'woocommerce' )
+```
+
+## Quick Command Reference
+
+```bash
+# Lint specific file
+npx eslint client/path/to/file.tsx
+
+# Fix specific file
+npx eslint --fix client/path/to/file.tsx
+
+# Type check
+pnpm run ts:check
+
+# ❌ NEVER lint entire codebase
+pnpm run lint  # NO - lints everything
+```
+
+## Summary
+
+| Pattern                       | Example                                      |
+|-------------------------------|----------------------------------------------|
+| **Single placeholder**        | `sprintf( __( 'Set up %s' ), 'Name' )`       |
+| **Repeated placeholder**      | `sprintf( __( '%1$s via %1$s' ), 'Name' )`   |
+| **Multiple placeholders**     | `sprintf( __( '%1$s in %2$s' ), 'A', 'B' )`  |
+| **Comment format (simple)**   | `/* translators: %s: Provider name */`       |
+| **Comment format (numbered)** | `/* translators: 1: Provider, 2: Country */` |