1

2026-03-23 17:20:51 +00:00
parent e78a41f11c
commit 0570052fec
21 changed files with 15889 additions and 0 deletions
--- a/v2/V2-Execution-Docs/03D-toolkit-plugin.md
+++ b/v2/V2-Execution-Docs/03D-toolkit-plugin.md
@@ -0,0 +1,467 @@
+# IGNY8 Phase 3: Toolkit Plugin (03D)
+## Utility Plugin — Performance, Forms, Security, SMTP, WooCommerce
+
+**Document Version:** 1.0
+**Date:** 2026-03-23
+**Phase:** IGNY8 Phase 3 — WordPress Ecosystem
+**Status:** Build Ready
+**Source of Truth:** Codebase at `/data/app/igny8/`
+**Audience:** Claude Code, WordPress Developers, Architects
+
+---
+
+## 1. CURRENT STATE
+
+### No Toolkit Exists
+- Users rely on multiple plugins for common utilities: WP Super Cache, Contact Form 7, Wordfence, WP Mail SMTP, etc.
+- Each additional plugin adds overhead, potential conflicts, and security surface area
+- No IGNY8-branded utility layer exists
+
+### Relationship to IGNY8 Ecosystem
+- **Independent** — toolkit works without the main IGNY8 plugin or companion theme
+- **Complementary** — designed to pair with the companion theme (03C) for a complete site stack
+- **Defers** — if both toolkit and main IGNY8 plugin are installed, toolkit's SMTP module defers to IGNY8's SMTP (03A Module 9b) to avoid conflict
+- **Same module pattern** — uses identical `register()`, `activate()`, `deactivate()`, `is_active()`, `boot()` module architecture as 03A
+
+### Plugin Identity
+- **Plugin Name:** IGNY8 Toolkit
+- **Text Domain:** `igny8-toolkit`
+- **Option Prefix:** `igny8_toolkit_`
+- **Table Prefix:** `{wp_prefix}igny8_toolkit_`
+- **Min Requirements:** WordPress 5.9+, PHP 7.4+
+- **License:** GPL v2+
+- **Freemium Model:** Core features free, advanced features premium (detailed per module below)
+
+---
+
+## 2. WHAT TO BUILD
+
+### Overview
+A separate utility plugin with 5 infrastructure modules. Each module is independently toggleable and has zero performance impact when disabled. Follows the same module manager pattern as the main IGNY8 plugin (03A).
+
+### Module 1: Performance
+
+**Purpose:** Page caching, asset optimization, image optimization, and database cleanup.
+
+**Classes:**
+| Class | File | Purpose |
+|-------|------|---------|
+| `Toolkit_Performance_Module` | `modules/performance/class-performance-module.php` | Module bootstrap |
+| `Toolkit_Page_Cache` | `modules/performance/class-page-cache.php` | File-based page cache |
+| `Toolkit_Asset_Optimizer` | `modules/performance/class-asset-optimizer.php` | CSS/JS combine + minify |
+| `Toolkit_Image_Optimizer` | `modules/performance/class-image-optimizer.php` | WebP conversion, lazy loading |
+| `Toolkit_Critical_CSS` | `modules/performance/class-critical-css.php` | Above-fold CSS extraction |
+| `Toolkit_HTML_Minifier` | `modules/performance/class-html-minifier.php` | Remove whitespace/comments |
+| `Toolkit_Browser_Cache` | `modules/performance/class-browser-cache.php` | Expires + cache-control headers |
+| `Toolkit_Preload` | `modules/performance/class-preload.php` | `<link rel="preload">` injection |
+| `Toolkit_Database_Optimizer` | `modules/performance/class-database-optimizer.php` | Clean transients, revisions, spam |
+
+**Features:**
+
+| Feature | Tier | Description |
+|---------|------|-------------|
+| Page cache (basic) | Free | File-based cache, auto-purge on `save_post` |
+| HTML minification | Free | Strip whitespace and comments from HTML output |
+| Asset optimizer | Premium | Combine + minify CSS/JS with exclusion rules |
+| Image optimizer | Premium | WebP conversion via GD/Imagick, lazy loading, responsive srcset |
+| Critical CSS | Premium | Extract above-fold CSS for faster FCP |
+| Browser cache headers | Premium | Expires + cache-control via `.htaccess` or `send_headers` |
+| Preload/prefetch | Premium | `<link rel="preload">` for key resources |
+| Gzip compression check | Free | Display gzip status in dashboard |
+| Database optimizer | Premium | Clean transients, post revisions, spam comments, orphan meta |
+
+**Database Table: `{prefix}igny8_toolkit_cache_stats`**
+```sql
+CREATE TABLE {prefix}igny8_toolkit_cache_stats (
+  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+  hits            INT DEFAULT 0,
+  misses          INT DEFAULT 0,
+  purges          INT DEFAULT 0,
+  last_purge      DATETIME NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+### Module 2: Forms
+
+**Purpose:** Drag-and-drop form builder with submissions storage, email notifications, and anti-spam.
+
+**Classes:**
+| Class | File | Purpose |
+|-------|------|---------|
+| `Toolkit_Forms_Module` | `modules/forms/class-forms-module.php` | Module bootstrap |
+| `Toolkit_Form_Builder` | `modules/forms/class-form-builder.php` | Admin form editor |
+| `Toolkit_Form_Renderer` | `modules/forms/class-form-renderer.php` | Frontend rendering via shortcode/block |
+| `Toolkit_Form_Processor` | `modules/forms/class-form-processor.php` | Submission handling |
+| `Toolkit_Form_Notifications` | `modules/forms/class-form-notifications.php` | Email notifications |
+| `Toolkit_Form_Entries` | `modules/forms/class-form-entries.php` | Submission viewer + export |
+| `Toolkit_Form_AntiSpam` | `modules/forms/class-form-antispam.php` | Honeypot + token validation |
+
+**Features:**
+
+| Feature | Tier | Description |
+|---------|------|-------------|
+| Basic builder (5 field types) | Free | text, email, textarea, select, checkbox |
+| Simple rendering | Free | Shortcode `[igny8_form id="X"]` |
+| All field types | Premium | + radio, file upload, hidden, number, date |
+| Conditional logic | Premium | Show/hide fields based on other field values |
+| Multi-step forms | Premium | Step-by-step form wizard |
+| Submissions dashboard | Premium | View, search, export CSV, delete entries |
+| Email templates | Premium | Customizable notification templates |
+
+**Anti-spam:** Honeypot field + basic token validation — no external service dependency.
+
+**Embed:** Shortcode `[igny8_form id="X"]` + Gutenberg block for insertion.
+
+**Database Table: `{prefix}igny8_toolkit_submissions`**
+```sql
+CREATE TABLE {prefix}igny8_toolkit_submissions (
+  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+  form_id         INT NOT NULL,
+  data            LONGTEXT NOT NULL,
+  ip_hash         VARCHAR(64) NULL,
+  user_agent      VARCHAR(500) NULL,
+  created_at      DATETIME NOT NULL,
+  INDEX idx_form (form_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+### Module 3: Security
+
+**Purpose:** Login protection, basic firewall, WordPress hardening, and audit logging.
+
+**Classes:**
+| Class | File | Purpose |
+|-------|------|---------|
+| `Toolkit_Security_Module` | `modules/security/class-security-module.php` | Module bootstrap |
+| `Toolkit_Login_Protection` | `modules/security/class-login-protection.php` | Brute-force protection |
+| `Toolkit_Firewall` | `modules/security/class-firewall.php` | Bad user agent blocking, upload protection |
+| `Toolkit_Hardening` | `modules/security/class-hardening.php` | XML-RPC disable, file editor, WP version |
+| `Toolkit_Headers` | `modules/security/class-headers.php` | Security headers |
+| `Toolkit_Audit_Log` | `modules/security/class-audit-log.php` | Event tracking |
+
+**Features:**
+
+| Feature | Tier | Description |
+|---------|------|-------------|
+| Login attempts limit | Free | Default 5 attempts, 15min lockout |
+| File editor disable | Free | `DISALLOW_FILE_EDIT` constant |
+| Security headers | Free | X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy |
+| Hide WP version | Free | Remove generator meta tag |
+| XML-RPC disable | Free | Block XML-RPC requests |
+| Advanced firewall | Premium | Block bad user agents, PHP execution in uploads |
+| 2FA via email code | Premium | Two-factor authentication on login |
+| Full audit logging | Premium | Track logins, settings changes, plugin activations, role changes |
+| IP allowlist/blocklist | Premium | Manage access by IP address |
+
+**Database Table: `{prefix}igny8_toolkit_audit_log`**
+```sql
+CREATE TABLE {prefix}igny8_toolkit_audit_log (
+  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+  event_type      VARCHAR(50) NOT NULL,
+  user_id         BIGINT NULL,
+  object_type     VARCHAR(50) NULL,
+  object_id       BIGINT NULL,
+  details         LONGTEXT NULL,
+  ip              VARCHAR(45) NULL,
+  created_at      DATETIME NOT NULL,
+  INDEX idx_event (event_type, created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+### Module 4: SMTP
+
+**Purpose:** SMTP mail override for sites NOT using the main IGNY8 plugin. If both installed, this module defers to IGNY8's SMTP (03A Module 9b).
+
+**Classes:**
+| Class | File | Purpose |
+|-------|------|---------|
+| `Toolkit_SMTP_Module` | `modules/smtp/class-smtp-module.php` | Module bootstrap (checks for main plugin) |
+| `Toolkit_SMTP_Mailer` | `modules/smtp/class-smtp-mailer.php` | SMTP mail override |
+| `Toolkit_Email_Log` | `modules/smtp/class-email-log.php` | Delivery log with status |
+| `Toolkit_Email_Test` | `modules/smtp/class-email-test.php` | Test email sender |
+
+**Features:**
+
+| Feature | Tier | Description |
+|---------|------|-------------|
+| SMTP override | Free | Host, port, username, password, encryption (SSL/TLS) |
+| From name/email | Free | Override WordPress default sender |
+| Mail sending | Free | Route all `wp_mail()` through SMTP |
+| Email delivery log | Premium | Track sent/failed with error details |
+| Email templates | Premium | Customizable notification email templates |
+| Resend failed | Premium | Retry failed deliveries |
+
+**Conflict Resolution:** On `boot()`, check `class_exists('IGNY8_SMTP_Module')` — if main plugin SMTP is active, this module auto-deactivates and shows admin notice: "SMTP is handled by the IGNY8 plugin."
+
+**Database Table: `{prefix}igny8_toolkit_email_log`**
+```sql
+CREATE TABLE {prefix}igny8_toolkit_email_log (
+  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+  to_email        VARCHAR(320) NOT NULL,
+  subject         VARCHAR(500) NOT NULL,
+  status          VARCHAR(20) NOT NULL,
+  error_message   TEXT NULL,
+  sent_at         DATETIME NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+### Module 5: WooCommerce Enhancements
+
+**Purpose:** UX improvements for WooCommerce stores. Entirely premium — only available in paid version.
+
+**Classes:**
+| Class | File | Purpose |
+|-------|------|---------|
+| `Toolkit_WooCommerce_Module` | `modules/woocommerce/class-woocommerce-module.php` | Module bootstrap (requires WooCommerce) |
+| `Toolkit_Quick_View` | `modules/woocommerce/class-quick-view.php` | Modal product preview on shop pages |
+| `Toolkit_Wishlist` | `modules/woocommerce/class-wishlist.php` | Cookie-based (guest) + user meta (logged in) |
+| `Toolkit_AJAX_Cart` | `modules/woocommerce/class-ajax-cart.php` | AJAX add-to-cart on archive pages |
+| `Toolkit_Product_Filters` | `modules/woocommerce/class-product-filters.php` | Price/attribute/category AJAX filters |
+| `Toolkit_Product_Gallery` | `modules/woocommerce/class-product-gallery.php` | Zoom, lightbox, thumbnails |
+
+**Features (all Premium):**
+- Quick view modal on shop/archive pages
+- Wishlist (cookie-based for guests, user meta for logged-in)
+- AJAX add-to-cart on archive pages (no page reload)
+- Product filters (price range, attributes, categories) with AJAX
+- Product gallery enhancement (zoom, lightbox, thumbnail navigation)
+
+**Conditional Loading:** Module only loads when WooCommerce is active (`class_exists('WooCommerce')`).
+
+---
+
+## 3. DATA MODELS & APIS
+
+### Database Tables (4 total)
+
+All tables created on plugin activation by installer class:
+
+| # | Table | Module | Purpose |
+|---|-------|--------|---------|
+| 1 | `{prefix}igny8_toolkit_submissions` | Forms | Form submission data (JSON) |
+| 2 | `{prefix}igny8_toolkit_email_log` | SMTP | Email delivery tracking |
+| 3 | `{prefix}igny8_toolkit_audit_log` | Security | Security event log |
+| 4 | `{prefix}igny8_toolkit_cache_stats` | Performance | Cache hit/miss stats |
+
+### Options Summary
+
+All options use `igny8_toolkit_` prefix:
+
+| Option Key | Module | Content |
+|------------|--------|---------|
+| `igny8_toolkit_performance_settings` | Performance | Cache, minify, optimize toggles |
+| `igny8_toolkit_forms` | Forms | JSON: `[{id, name, fields, settings}]` |
+| `igny8_toolkit_security_settings` | Security | Login limits, hardening toggles |
+| `igny8_toolkit_smtp_settings` | SMTP | Host, port, user, pass, encryption |
+| `igny8_toolkit_woocommerce_settings` | WooCommerce | Feature toggles |
+| `igny8_toolkit_license_key` | Global | Premium license key |
+| `igny8_toolkit_license_status` | Global | active/expired/invalid |
+
+### No REST API Endpoints
+The toolkit plugin does not expose REST endpoints. All admin pages are standard WordPress admin screens.
+
+---
+
+## 4. IMPLEMENTATION STEPS
+
+### Plugin Architecture
+
+```
+igny8-toolkit/
+├── igny8-toolkit.php                  # Plugin header, constants, module loader
+├── readme.txt                         # WordPress.org readme
+├── uninstall.php                      # Full cleanup on uninstall
+├── includes/
+│   ├── class-toolkit.php              # Main singleton class
+│   ├── class-module-manager.php       # Module toggle (same pattern as 03A)
+│   ├── class-installer.php            # Create 4 DB tables on activation
+│   ├── class-license.php              # Premium license validation
+│   ├── modules/
+│   │   ├── performance/               # Module 1 — 9 class files
+│   │   ├── forms/                     # Module 2 — 7 class files
+│   │   ├── security/                  # Module 3 — 6 class files
+│   │   ├── smtp/                      # Module 4 — 4 class files
+│   │   └── woocommerce/               # Module 5 — 6 class files
+│   └── admin/
+│       ├── class-dashboard.php        # Toolkit dashboard
+│       └── views/                     # Admin page templates
+├── admin/                             # Admin CSS + JS
+│   ├── css/
+│   └── js/
+├── frontend/                          # Frontend CSS + JS
+│   ├── css/
+│   └── js/
+└── languages/
+    └── igny8-toolkit.pot              # Translation template
+```
+
+### Build Sequence
+
+**Phase 1: Foundation (Days 1-2)**
+1. Create `igny8-toolkit.php` with header, constants, autoloader
+2. Build `class-toolkit.php` singleton — `instance()`, `init()`, `load_modules()`
+3. Build `class-module-manager.php` — same pattern as 03A
+4. Build `class-installer.php` — create 4 DB tables via `dbDelta()`
+5. Build `class-license.php` — premium license validation
+6. Build `admin/class-dashboard.php` — toolkit overview page
+
+**Phase 2: Performance Module (Days 3-5)**
+1. Build page cache (file-based, purge on `save_post`)
+2. Build HTML minifier (output buffer processing)
+3. Build asset optimizer (combine/minify with exclusions)
+4. Build image optimizer (WebP via GD/Imagick, lazy loading)
+5. Build critical CSS generator
+6. Build browser cache + preload
+7. Build database optimizer
+
+**Phase 3: Forms Module (Days 6-8)**
+1. Build form builder admin UI
+2. Build form renderer (shortcode + block)
+3. Build form processor (validation + sanitization)
+4. Build notifications (email on submission)
+5. Build anti-spam (honeypot + token)
+6. Build entries admin page (view + CSV export)
+
+**Phase 4: Security Module (Days 9-11)**
+1. Build login protection (attempt tracking, lockout)
+2. Build firewall (bad user agents, upload protection)
+3. Build hardening (XML-RPC, file editor, version hide, headers)
+4. Build audit log (event tracking)
+5. Build 2FA (premium — email code on login)
+
+**Phase 5: SMTP Module (Days 12-13)**
+1. Build SMTP mailer (override `wp_mail`)
+2. Build conflict check (defer to main IGNY8 plugin if active)
+3. Build email log
+4. Build test email sender
+
+**Phase 6: WooCommerce Module (Days 14-16)**
+1. Build quick view modal
+2. Build wishlist (cookie + user meta)
+3. Build AJAX cart
+4. Build product filters
+5. Build gallery enhancements
+
+**Phase 7: Compliance (Days 17-18)**
+1. WordPress.org compliance — sanitize/escape, nonces, capability checks
+2. i18n pass — all strings via `igny8-toolkit` text domain
+3. readme.txt with feature list, changelog
+4. Accessibility review
+
+### Admin Menu Structure
+
+```
+IGNY8 Toolkit (top-level, dashicons-admin-tools)
+├── Dashboard        — Overview, module status, cache stats
+├── Performance      — Cache, minify, optimize, image settings
+├── Forms            — Form builder, entries, settings
+├── Security         — Login protection, hardening, audit log
+├── SMTP             — Mail settings, log, test
+├── WooCommerce      — Feature toggles (when WooCommerce active)
+└── License          — Premium license management
+```
+
+---
+
+## 5. ACCEPTANCE CRITERIA
+
+### Performance (Module 1)
+- [ ] Page cache creates static HTML files and serves them on repeat visits
+- [ ] Cache auto-purges on `save_post` for the updated post's URL
+- [ ] HTML minification reduces output size by removing whitespace/comments
+- [ ] Image optimizer converts uploads to WebP format
+- [ ] Lazy loading adds `loading="lazy"` to images below fold
+- [ ] Database optimizer cleans transients, revisions, spam comments
+- [ ] Cache stats table tracks hits/misses/purges
+
+### Forms (Module 2)
+- [ ] Form builder creates forms with configurable fields
+- [ ] `[igny8_form id="X"]` shortcode renders form on frontend
+- [ ] Form submissions stored in `igny8_toolkit_submissions` table
+- [ ] Email notification sent on submission
+- [ ] Honeypot field blocks spam submissions
+- [ ] Entries admin page shows submissions with CSV export
+- [ ] All form data sanitized: `sanitize_text_field()`, `sanitize_email()`, `wp_kses_post()` per field type
+
+### Security (Module 3)
+- [ ] Login attempts limited to 5 per 15 minutes (configurable)
+- [ ] Lockout message displayed after threshold exceeded
+- [ ] XML-RPC disabled when hardening active
+- [ ] File editor disabled via `DISALLOW_FILE_EDIT`
+- [ ] WP version removed from `<head>` and feeds
+- [ ] Security headers set: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
+- [ ] Audit log records login attempts, settings changes, plugin activations
+
+### SMTP (Module 4)
+- [ ] SMTP override routes `wp_mail()` through configured server
+- [ ] Test email sends successfully with configured SMTP
+- [ ] Module auto-deactivates when main IGNY8 plugin SMTP is active
+- [ ] Email log records sent/failed status with error messages
+
+### WooCommerce (Module 5)
+- [ ] Quick view modal opens on shop/archive pages
+- [ ] Wishlist persists for guests (cookie) and users (user meta)
+- [ ] AJAX add-to-cart works without page reload
+- [ ] Product filters update results via AJAX
+- [ ] Module only loads when WooCommerce is active
+
+### Cross-Module
+- [ ] All 5 modules independently toggleable — zero impact when disabled
+- [ ] Plugin activates without errors on WordPress 5.9+ with PHP 7.4+
+- [ ] All 4 database tables created on activation
+- [ ] All strings translatable via `igny8-toolkit` text domain
+- [ ] All inputs sanitized, all outputs escaped
+- [ ] Nonce verification on all form submissions
+- [ ] Premium features gated behind license validation
+
+---
+
+## 6. CLAUDE CODE INSTRUCTIONS
+
+### Context Requirements
+Before starting implementation:
+1. Read 03A (main plugin) — understand module manager pattern to replicate
+2. Read 03C (companion theme) — understand theme as primary consumer of toolkit features
+
+### Execution Order
+```
+Foundation → Performance → Forms → Security → SMTP → WooCommerce → Compliance
+```
+
+### Critical Rules
+1. **Independent plugin** — must work without main IGNY8 plugin or companion theme
+2. **Same module pattern** — `register()`, `activate()`, `deactivate()`, `is_active()`, `boot()` — identical to 03A
+3. **SMTP conflict resolution** — check `class_exists('IGNY8_SMTP_Module')` on boot, auto-defer if main plugin active
+4. **WooCommerce conditional** — Module 5 only loads when `class_exists('WooCommerce')` is true
+5. **Table prefix** — all tables use `{wp_prefix}igny8_toolkit_` (different from main plugin's `{wp_prefix}igny8_`)
+6. **Option prefix** — all options use `igny8_toolkit_` prefix
+7. **Text domain** — `igny8-toolkit` (different from plugin's `igny8` and theme's `igny8-theme`)
+8. **Freemium** — free features work without license, premium features check `class-license.php` validation
+9. **Sanitize/escape** — same WordPress standards as 03A
+10. **No external dependencies** — no CDN scripts, no external API calls (except SMTP + optional license check)
+
+### File Creation Order
+```
+1. igny8-toolkit.php (plugin header + bootstrap)
+2. includes/class-toolkit.php (singleton)
+3. includes/class-module-manager.php (module orchestration)
+4. includes/class-installer.php (4 DB tables)
+5. includes/class-license.php (premium validation)
+6. includes/admin/class-dashboard.php (overview page)
+7. includes/modules/performance/* (9 files)
+8. includes/modules/forms/* (7 files)
+9. includes/modules/security/* (6 files)
+10. includes/modules/smtp/* (4 files)
+11. includes/modules/woocommerce/* (6 files)
+12. admin/ (CSS + JS assets)
+13. frontend/ (CSS + JS assets)
+14. uninstall.php (cleanup)
+15. languages/igny8-toolkit.pot (i18n)
+```
+
+### Cross-References
+
+| Doc | Relationship |
+|-----|-------------|
+| 03A WP Plugin Standalone | Module manager pattern replicated; SMTP conflict resolution when both installed |
+| 03C Companion Theme | Theme is primary consumer of toolkit features (forms, performance) |