Merge pull request #226 from w3bdesign/develop

Add AGENTS.md with plugin architecture guidance

Author: w3bdesign

.github/workflows/phpcs-autofix.yml

@@ -42,6 +42,9 @@ jobs:
         run: vendor/bin/phpcbf --standard=phpcs.xml --extensions=php . || true
 
       - name: Commit and Push PHPCBF fixes
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          REF_NAME: ${{ github.ref_name }}
         run: |
           git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
@@ -66,11 +69,10 @@ jobs:
             # Determine the branch to push to
             # For PRs, github.head_ref is the source branch name.
             # For workflow_dispatch, github.ref_name is the branch the workflow was run on.
-            BRANCH_NAME=""
-            if [[ -n "${{ github.head_ref }}" ]]; then
-              BRANCH_NAME="${{ github.head_ref }}"
+            if [[ -n "$HEAD_REF" ]]; then
+              BRANCH_NAME="$HEAD_REF"
             else
-              BRANCH_NAME="${{ github.ref_name }}"
+              BRANCH_NAME="$REF_NAME"
             fi
             
             echo "Pushing changes to branch: $BRANCH_NAME"

.github/workflows/phpcs.yml

@@ -1,6 +1,12 @@
 on: pull_request
 
 name: Inspections
+
+permissions:
+  contents: read
+  pull-requests: write
+  checks: write
+
 jobs:
   runPHPCSInspection:
     name: Run PHPCS inspection

.roo/rules-architect/AGENTS.md

@@ -0,0 +1,12 @@
+# Project Architecture Rules (Non-Obvious Only)
+
+- Plugin follows WordPress plugin architecture, not MVC - all classes are utility/service classes
+- Singleton pattern required for main class to prevent multiple AJAX handler registrations
+- No dependency injection - classes access WordPress globals and functions directly
+- AJAX endpoints registered globally but handled by specific class methods (tight coupling by design)
+- Plugin settings stored as individual prefixed options (not single serialized array for performance)
+- Activation/deactivation hooks in main file, but actual logic delegated to class methods
+- No autoloader - classes included manually via `require_once` in main file
+- WordPress hooks used for integration points, not observer patterns or events
+- Algolia client instantiated fresh each time (no connection pooling or reuse)
+- Product data transformation happens in loops without caching (potential performance bottleneck)

.roo/rules-ask/AGENTS.md

@@ -0,0 +1,12 @@
+# Project Documentation Rules (Non-Obvious Only)
+
+- Main plugin file (`algolia-woo-indexer.php`) contains WordPress plugin headers but core logic is in `classes/` directory
+- `DOCS/repository_context.txt` contains comprehensive project context not found in README
+- Class files use WordPress naming convention (`class-name.php`) but implement PHP namespacing patterns
+- Plugin functionality is split across 4 separate classes with specific responsibilities (not MVC pattern)
+- Settings structure documented in code comments, not external docs
+- Composer is used for development tools only (PHPCS), not for plugin dependencies
+- Translation files in `languages/` directory use WordPress translation system, not standard gettext
+- Plugin header mentions PHP 8.1+ but error messages reference PHP 7.2+ (outdated messaging)
+- Constants are scattered: some in main class, others in `Send_Products` class
+- Product categories are required - plugin silently skips products without categories (undocumented behavior)

.roo/rules-code/AGENTS.md

@@ -0,0 +1,12 @@
+# Project Coding Rules (Non-Obvious Only)
+
+- Always use singleton pattern for main plugin class via `get_instance()` method (not direct instantiation)
+- AJAX handlers must call `Verify_Nonces::verify_nonce()` instead of WordPress standard `wp_verify_nonce()` for consistency
+- Product data uses custom field mapping in `Send_Products::prepare_product_data()` - don't rely on WooCommerce defaults
+- Settings access must go through main class wrapper methods, not direct `get_option()` calls
+- Error responses use `wp_send_json_error()` with specific error codes matching the class error handling patterns
+- Plugin text domain is `algolia-woo-indexer` - must match directory name exactly for translations
+- Constants are defined in `Send_Products` class: `ALGOWOO_DB_OPTION`, `ALGOLIA_API_KEY`, `INDEX_NAME`, etc.
+- Database options use prefix pattern: `ALGOWOO_DB_OPTION . SUFFIX` (e.g., `_algolia_woo_indexer_application_id`)
+- All database operations assume WooCommerce is active - no fallback checks in core functionality
+- Product price extraction differs by type: use `get_variation_sale_price('min', true)` for variable products

.roo/rules-debug/AGENTS.md

@@ -0,0 +1,11 @@
+# Project Debug Rules (Non-Obvious Only)
+
+- WordPress debug logs are only location for error output - plugin doesn't write to separate log files
+- AJAX debugging requires checking both browser network tab AND WordPress debug log (errors split between both)
+- Plugin activation errors only visible in WordPress admin, not in server logs  
+- Requirements check failures prevent plugin activation silently - check `Check_Requirements` class output
+- Algolia API errors are caught and logged but don't prevent page loading (silent failures possible)
+- Settings validation errors only show in WordPress admin notices, not AJAX responses
+- Uninstall process leaves no traces if `WP_UNINSTALL_PLUGIN` constant isn't properly set
+- Algolia connection test happens via `listApiKeys()` call - not a ping or simple connection check
+- Product indexing failures return `NullResponse` class - check `get_class($result)` for this specific string

AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## WordPress Plugin Architecture (Non-obvious patterns)
+
+- Plugin initialization happens in two phases: main file registers hooks, then `Algolia_Woo_Indexer` class handles functionality via singleton pattern with `get_instance()`
+- All AJAX/form actions use custom nonce verification through `Verify_Nonces` class, not standard WordPress `wp_verify_nonce()` directly
+- Product indexing is batched via `Send_Products::send_products_to_algolia()` - processes arrays, not individual products
+- Settings stored as individual prefixed options (`ALGOWOO_DB_OPTION . SUFFIX`), accessed via wrapper methods, not direct `get_option()` calls
+- Constants defined in `Send_Products` class, not main file - `ALGOWOO_DB_OPTION`, `ALGOLIA_API_KEY`, etc.
+- Plugin requires PHP 8.1+ and WordPress 6.1+ (despite error message mentioning 7.2/5.0)
+- Uninstall process in `uninstall.php` requires `WP_UNINSTALL_PLUGIN` constant check before executing
+- All classes use manual loading via `require_once` - no autoloader used
+- Image extraction uses regex parsing: `preg_match('/<img(.*)src(.*)=(.*)"(.*)"/U', $product->get_image(), $result)`
+- WooCommerce product price logic differs by type: `simple` vs `variable` products use different getter methods
+
+## Development Commands
+
+- Run PHP_CodeSniffer: `vendor/bin/phpcs` (WordPress-Core, WordPress-Docs, WordPress-Extra rules)  
+- Fix coding standards: `vendor/bin/phpcbf`
+- PHPCS excludes: file naming rules (`WordPress.Files.FileName.*`)
+- Plugin must be tested within WordPress environment (no standalone testing)

README.md

@@ -32,6 +32,7 @@ Note that this plugin is designed for developers developing headless Ecommerce s
 - All variables are properly sanitized to ensure that no security issues are present
 - AI Repository documentation located in `/DOCS/repository_context.txt`
 - PHPCS Autofix with Github actions
+- AI Assistant guidance files (`AGENTS.md` and `.roo/rules-*/AGENTS.md`) for immediate productivity with AI coding tools
 
 ## Requirements