From 3a90960cdaef0914c04d61603085c4ddab55a5af Mon Sep 17 00:00:00 2001 From: Soare Robert-Daniel Date: Tue, 24 Feb 2026 12:26:57 +0200 Subject: [PATCH 1/4] dev: add AGENTS.md --- .distignore | 1 + AGENTS.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 AGENTS.md diff --git a/.distignore b/.distignore index f5aec773..b807e722 100644 --- a/.distignore +++ b/.distignore @@ -49,3 +49,4 @@ test-results wp-scripts.config.js README.md CHANGELOG.md +AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2df092cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# Agent Workflow + +## What This Is + +Optimole WordPress plugin — cloud-based image optimization with CDN delivery, lazy loading, WebP/AVIF conversion, media offloading, and a Digital Asset Management (DAM) interface. Version 4.2.1, requires PHP 7.4+, WordPress 5.5+. + +## Build & Dev Commands + +```bash +# Install dependencies +npm install && composer install + +# Build all assets (production) +npm run build + +# Development with HMR (all targets in parallel) +npm run dev + +# Build individual targets +npm run build:dashboard # Admin settings UI +npm run build:widget # Dashboard widget +npm run build:media # Media library integration +npm run build:optimizer # Frontend lazy loading script +npm run build:video-player-editor +npm run build:video-player-frontend +``` + +## Testing + +```bash +# PHP unit tests (requires WP test suite) +composer phpunit +composer install-wp-tests # First-time setup + +# Run a specific PHP test file +phpunit tests/test-replacer.php + +# Run a specific test method +phpunit --filter="test_method_name" + +# JavaScript tests +npm test +npm run test:watch +npm run test:coverage + +# E2E tests (Playwright, base URL: http://testing.optimole.com) +npm run e2e:run +npm run e2e:open # Interactive UI mode +``` + +## Linting & Static Analysis + +```bash +# JavaScript +npm run lint # ESLint +npm run format # ESLint --fix + +# PHP +composer phpcs # PHP CodeSniffer (WordPress-Core standard) +composer format # Auto-fix with phpcbf +composer phpstan # PHPStan level 2 +``` + +## Architecture + +### Two-era codebase: v1 (legacy) and v2 (modern) + +**Legacy code (`inc/*.php`)** — Class prefix `Optml_*`, loaded by custom autoloader in `optimole-wp.php`. This is the bulk of the plugin. + +**Modern code (`inc/v2/`)** — PSR-4 autoloaded under `OptimoleWP\` namespace via Composer. New features should go here. + +### Plugin initialization flow + +``` +optimole-wp.php → optml() → Optml_Main::instance() (singleton) + ├── Optml_Manager — Orchestrates replacers and loads compatibilities + ├── Optml_Admin — Admin dashboard UI, conflict detection + ├── Optml_Rest — REST API endpoints for the dashboard + ├── Optml_Media_Offload — Cloud offloading/restoration of media + ├── Optml_Dam — Digital Asset Management UI + ├── Optml_Video_Player — Video player blocks + └── Optml_Cli — WP-CLI commands (when available) +``` + +### Core subsystems + +- **URL/Tag replacement** (`tag_replacer.php`, `url_replacer.php`, `app_replacer.php`) — Parses HTML output, rewrites image URLs to Optimole CDN URLs with optimization parameters. +- **Lazy loading** (`lazyload_replacer.php`, `inc/v2/BgOptimizer/`) — Viewport-based and background-image lazy loading. Frontend JS in `assets/js/optimizer.js`. +- **Media offloading** (`media_offload.php`) — Moves media to/from Optimole cloud storage, handles bulk operations. +- **Settings** (`settings.php`) — Central settings schema and management, stores in `wp_options`. +- **Compatibility layer** (`inc/compatibilities/`) — 49+ integrations for page builders (Elementor, Divi, Beaver Builder), caching plugins (WP Rocket, LiteSpeed), WooCommerce, etc. Each extends `Optml_compatibility`. + +### Frontend assets (`assets/src/`) + +React-based, built with `@wordpress/scripts`: +- `dashboard/` — Main admin settings page (React + @wordpress/components) +- `widget/` — Admin dashboard widget +- `media/` — Media library DAM integration +- `video-player/` — Editor and frontend video player blocks + +Built output goes to `assets/build/`. The `assets/js/optimizer.js` is the frontend lazy-loading script. + +## Code Standards + +- **PHP**: WordPress-Core via PHPCS. Text domain: `optimole-wp`. +- **JS**: WordPress ESLint config. Tabs, single quotes, semicolons. +- **v2 PHP code** requires PHPStan-compatible PHPDoc annotations, full namespace paths, type hints, and constants for magic values (e.g., `Profile::DEVICE_TYPE_MOBILE` not `1`). +- Error handling: return `WP_Error` for WordPress-compatible errors, `false` for simple failures. +- Debug logging: `do_action( 'optml_log', $message )` when `OPTML_DEBUG` is true. + +## Key Constants + +Defined in `optimole-wp.php`: `OPTML_URL`, `OPTML_PATH`, `OPTML_VERSION`, `OPTML_NAMESPACE` (`'optml'`), `OPTML_BASEFILE`, `OPTML_DEBUG`, `OPTML_DEBUG_MEDIA`. From 31c5befef61fe683a97781237ad643d3610672d8 Mon Sep 17 00:00:00 2001 From: Soare Robert-Daniel Date: Tue, 24 Feb 2026 15:06:52 +0200 Subject: [PATCH 2/4] Update AGENTS.md --- AGENTS.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2df092cb..a4556b5b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,32 @@ React-based, built with `@wordpress/scripts`: Built output goes to `assets/build/`. The `assets/js/optimizer.js` is the frontend lazy-loading script. +## Task Routing (Where to Start) + +- Bootstrap/hooks: `optimole-wp.php`, `inc/main.php`, `inc/manager.php`, `inc/filters.php`. +- URL/CDN rewriting: `inc/tag_replacer.php`, `inc/url_replacer.php`, `inc/app_replacer.php` + `tests/test-replacer.php`. +- Lazyload: `inc/lazyload_replacer.php`, `inc/v2/BgOptimizer/Lazyload.php`, `assets/js/optimizer.js` + `tests/test-lazyload.php`. +- Admin/REST/settings: `inc/admin.php`, `inc/rest.php`, `inc/settings.php`, `assets/src/dashboard/`. +- Media/DAM: `inc/media_offload.php`, `inc/dam.php`, `assets/src/media/`. +- Compat/conflicts: `inc/compatibilities/`, `inc/conflicts/`, related `tests/e2e/*.spec.ts`. +- Video player: `inc/video_player.php`, `assets/src/video-player/`, `tests/test-video.php`. + +## Security Checklist (WordPress-Specific) + +- State-changing actions: capability check + nonce verification. +- Input/output: sanitize on input, escape on output. +- REST: always set strict `permission_callback` for write routes. +- SQL: use `$wpdb->prepare()` for dynamic queries. +- Safety: do not leak secrets/tokens; validate remote and file/media operations before mutate/delete. + +## Agent Execution Policy + +- Keep changes surgical; avoid unrelated refactors/cleanups. +- Prefer `inc/v2/` for new logic unless legacy coupling forces `inc/*.php`. +- Trace hooks and callsites before editing behavior. +- Add/update the smallest relevant test and run targeted checks first. +- Build only touched frontend targets; call out intentional build artifacts. + ## Code Standards - **PHP**: WordPress-Core via PHPCS. Text domain: `optimole-wp`. From 052f51861ef2945ce9524d93683047aed033b1fa Mon Sep 17 00:00:00 2001 From: Soare Robert Daniel Date: Wed, 25 Feb 2026 17:33:04 +0200 Subject: [PATCH 3/4] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a4556b5b..4acfdfd3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ npm run format # ESLint --fix # PHP composer phpcs # PHP CodeSniffer (WordPress-Core standard) composer format # Auto-fix with phpcbf -composer phpstan # PHPStan level 2 +composer phpstan # PHPStan level 6 ``` ## Architecture From 94076237e8f374a59ad0f923d20bac6e84a625d4 Mon Sep 17 00:00:00 2001 From: Soare Robert Daniel Date: Wed, 25 Feb 2026 17:33:20 +0200 Subject: [PATCH 4/4] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4acfdfd3..73d75399 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,7 +88,7 @@ optimole-wp.php → optml() → Optml_Main::instance() (singleton) - **Lazy loading** (`lazyload_replacer.php`, `inc/v2/BgOptimizer/`) — Viewport-based and background-image lazy loading. Frontend JS in `assets/js/optimizer.js`. - **Media offloading** (`media_offload.php`) — Moves media to/from Optimole cloud storage, handles bulk operations. - **Settings** (`settings.php`) — Central settings schema and management, stores in `wp_options`. -- **Compatibility layer** (`inc/compatibilities/`) — 49+ integrations for page builders (Elementor, Divi, Beaver Builder), caching plugins (WP Rocket, LiteSpeed), WooCommerce, etc. Each extends `Optml_compatibility`. +- **Compatibility layer** (`inc/compatibilities/`) — 47+ integrations for page builders (Elementor, Divi, Beaver Builder), caching plugins (WP Rocket, LiteSpeed), WooCommerce, etc. Each extends `Optml_compatibility`. ### Frontend assets (`assets/src/`)