ima-claude 2.9.0

package/plugins/ima-claude/skills/php-fp-wordpress/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: "php-fp-wordpress"
+description: "Security-first WordPress development with PHP FP principles - pure business logic + WordPress integration"
+---
+
+# PHP FP - WordPress
+
+Security-first WordPress development combining PHP functional programming principles with mandatory WordPress security practices.
+
+## When to Use This Skill
+
+- Building WordPress plugins or themes
+- Need security-first development practices
+- Implementing pure business logic with WordPress integration
+- Testing WordPress functionality
+
+## Core Philosophy
+
+**Security practices prevent vulnerabilities, not architectural patterns.**
+
+Hybrid approach:
+1. **Pure functions** for business logic (testable, no WordPress deps)
+2. **WordPress wrappers** with mandatory security (capability, nonce, sanitize, escape, prepare)
+
+**Foundation**: Reference `../php-fp/SKILL.md` for PHP FP core principles.
+
+## The 5 Non-Negotiable Security Practices
+
+**Evidence**: Analysis of 7,966 vulnerabilities (2024) shows these prevent 95%+ of WordPress plugin vulnerabilities.
+
+| Practice | Prevents | Rule |
+|----------|----------|------|
+| **Capability Checks** | 53% of XSS | `current_user_can()` before ANY privileged operation |
+| **Nonce Verification** | 15-17% CSRF | `wp_verify_nonce()` on ALL form/AJAX submissions |
+| **Input Sanitization** | Injection | Sanitize ALL user input by type |
+| **Output Escaping** | XSS | Escape ALL output by context |
+| **Prepared Statements** | SQL injection | `$wpdb->prepare()` for ALL queries |
+
+### Quick Reference: Security Functions
+
+**Sanitization (Input)**:
+| Function | Use For |
+|----------|---------|
+| `sanitize_text_field()` | Plain text |
+| `sanitize_email()` | Email addresses |
+| `absint()` | Positive integers |
+| `wp_kses_post()` | HTML content |
+| `esc_url_raw()` | URLs (for storage) |
+
+**Escaping (Output)**:
+| Function | Context |
+|----------|---------|
+| `esc_html()` | HTML body |
+| `esc_attr()` | HTML attributes |
+| `esc_url()` | URLs in href/src |
+| `wp_json_encode()` | JavaScript data |
+
+### Minimal Security Pattern
+
+```php
+<?php
+add_action('wp_ajax_my_action', function() {
+    // 1. Capability check
+    if (!current_user_can('edit_posts')) {
+        wp_send_json_error('Unauthorized', 403);
+    }
+
+    // 2. Nonce verification
+    check_ajax_referer('my_action_nonce', 'nonce');
+
+    // 3. Sanitize input
+    $id = absint($_POST['id']);
+    $name = sanitize_text_field($_POST['name']);
+
+    // 4. Use prepared statement
+    global $wpdb;
+    $result = $wpdb->get_row($wpdb->prepare(
+        "SELECT * FROM {$wpdb->prefix}my_table WHERE id = %d",
+        $id
+    ));
+
+    // 5. Escape output
+    wp_send_json_success(['name' => esc_html($result->name)]);
+});
+```
+
+## Pure Logic + WordPress Wrapper Pattern
+
+**Separate testable business logic from WordPress integration.**
+
+```php
+<?php
+// PURE: Zero WordPress dependencies, fully testable
+namespace MyPlugin\Pure;
+
+function calculate_discount(float $price, string $tier): float {
+    $rates = ['bronze' => 0.05, 'silver' => 0.10, 'gold' => 0.15];
+    return round($price * (1 - ($rates[$tier] ?? 0)), 2);
+}
+
+// WRAPPER: WordPress integration with security
+namespace MyPlugin;
+
+add_filter('product_price', function($price) {
+    if (!is_user_logged_in()) return $price;
+
+    $tier = get_user_meta(get_current_user_id(), 'tier', true);
+    return Pure\calculate_discount($price, $tier);
+});
+```
+
+## Inter-Plugin Communication: Hooks Only
+
+**Rule**: ALL cross-plugin calls use WordPress hooks. NEVER `function_exists()`.
+
+Hooks are safe no-ops — if nobody listens, nothing happens. `function_exists()` is tight coupling disguised as loose coupling.
+
+```php
+<?php
+// BAD — tight coupling, breaks silently on rename
+if (function_exists('ima_discourse_refresh_user_meta')) {
+    ima_discourse_refresh_user_meta($user_id);
+}
+
+// GOOD — fire-and-forget side effect
+do_action('ima_discourse_refresh_user_meta', $user_id);
+
+// GOOD — transform with safe default (function composition via WP)
+$result = apply_filters('ima_membership_cancel_subscription', ['success' => true], $user_id, $sub_id);
+```
+
+**Actions** (`do_action`): Side effects — "something happened, react if you care."
+**Filters** (`apply_filters`): Data transformation — chained function composition with a default return.
+
+The handler registers itself:
+```php
+<?php
+// ima-discourse registers once — or doesn't. Either way, callers don't crash.
+add_action('ima_discourse_refresh_user_meta', 'ima_discourse_refresh_user_meta', 10, 1);
+```
+
+**When `function_exists()` is acceptable**: Internal guard clauses within a single plugin checking if its own functions are loaded, or checking PHP extensions (`function_exists('sodium_crypto_secretbox')`).
+
+## Plugin Complexity Guide
+
+| Size | Lines | Pattern |
+|------|-------|---------|
+| Simple | <500 | Namespaced functions |
+| Medium | 500-2000 | Classes + pure functions |
+| Complex | 2000+ | DI Container + Services |
+
+**Rule**: Start simple, add complexity only when needed.
+
+## File Organization
+
+```
+my-plugin/
+├── my-plugin.php              # Bootstrap
+├── includes/
+│   └── functions.php          # Pure business logic
+├── admin/
+│   └── ajax-handlers.php      # WordPress integration
+└── tests/
+    ├── unit/                  # Pure function tests (fast)
+    └── integration/           # WordPress tests
+```
+
+## Security Checklist
+
+- [ ] Capability checks on all privileged operations
+- [ ] Nonces on all form/AJAX submissions
+- [ ] Input sanitized by type
+- [ ] Output escaped by context
+- [ ] SQL uses `$wpdb->prepare()`
+- [ ] File uploads use `wp_handle_upload()`
+- [ ] No hardcoded credentials
+- [ ] Cross-plugin calls use hooks, not `function_exists()`
+
+## Quality Gates
+
+1. **Security**: All 5 mandatory practices implemented?
+2. **Pure logic**: Business logic separated from WordPress?
+3. **Testability**: Pure functions have unit tests?
+4. **Complexity**: Architecture matches plugin size?
+
+## When to Load Reference Files
+
+### Security Deep-Dive
+**File**: [`references/security-examples.md`](references/security-examples.md)
+**Load when**: Need detailed security patterns, vulnerable vs. safe comparisons
+**Contains**: Full examples for all 5 practices, security function reference tables
+
+### FP Patterns
+**File**: [`references/fp-patterns.md`](references/fp-patterns.md)
+**Load when**: Implementing pure logic + wrapper pattern, function factories
+**Contains**: Complete membership system example, production email validator example
+
+### Plugin Architecture
+**File**: [`references/plugin-architecture.md`](references/plugin-architecture.md)
+**Load when**: Deciding plugin structure, implementing DI container
+**Contains**: Simple/medium/complex plugin patterns, file organization examples
+
+### Testing Strategy
+**File**: [`references/testing-strategy.md`](references/testing-strategy.md)
+**Load when**: Setting up tests, writing security tests
+**Contains**: Unit/integration test examples, minimal mock bootstrap, security test patterns
+
+## Success Metrics
+
+- **Security**: Zero vulnerabilities from missing practices
+- **Testability**: 95%+ coverage for pure functions
+- **Maintainability**: Clear separation of concerns
+
+---
+
+**Evidence Base**: Analysis of 7,966 WordPress vulnerabilities (2024), WordPress Core Team standards, Wordfence/Patchstack research.

package/plugins/ima-claude/skills/php-fp-wordpress/references/fp-patterns.md

@@ -0,0 +1,275 @@
+# Pure Logic + WordPress Wrapper Patterns
+
+## Table of Contents
+1. [Core Pattern](#core-pattern)
+2. [Complete Example: Membership System](#complete-example-membership-system)
+3. [Function Factory Pattern](#function-factory-pattern)
+4. [Production Example: Email Validator](#production-example-email-validator)
+
+---
+
+## Core Pattern
+
+**Separate pure business logic from WordPress integration.**
+
+```
+┌─────────────────────────────────────────┐
+│     PURE BUSINESS LOGIC                 │
+│  • Zero WordPress dependencies          │
+│  • Deterministic, testable              │
+│  • Returns data, no side effects        │
+└─────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────┐
+│     WORDPRESS WRAPPER                   │
+│  • Security checks (capability, nonce)  │
+│  • Input sanitization                   │
+│  • Database operations                  │
+│  • Output escaping                      │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Complete Example: Membership System
+
+### Pure Business Logic (Zero WordPress Dependencies)
+
+```php
+<?php
+namespace MyPlugin\BusinessLogic;
+
+/**
+ * Calculate membership discount
+ * @pure - No side effects, deterministic, easily testable
+ */
+function calculate_discount(float $price, string $tier, int $days_member): float {
+    $tier_multipliers = [
+        'bronze' => 0.05,
+        'silver' => 0.10,
+        'gold' => 0.15,
+        'platinum' => 0.20
+    ];
+
+    $base_discount = $tier_multipliers[$tier] ?? 0;
+    $loyalty_bonus = min($days_member / 365 * 0.02, 0.05); // Max 5% loyalty
+    $total_discount = min($base_discount + $loyalty_bonus, 0.25); // Max 25%
+
+    return round($price * (1 - $total_discount), 2);
+}
+
+/**
+ * Validate membership tier upgrade
+ * @pure - Returns validation result, no database queries
+ */
+function validate_tier_upgrade(string $current_tier, string $new_tier): array {
+    $tier_hierarchy = ['bronze', 'silver', 'gold', 'platinum'];
+    $current_level = array_search($current_tier, $tier_hierarchy);
+    $new_level = array_search($new_tier, $tier_hierarchy);
+
+    if ($current_level === false || $new_level === false) {
+        return ['valid' => false, 'error' => 'Invalid tier specified'];
+    }
+
+    if ($new_level <= $current_level) {
+        return ['valid' => false, 'error' => 'Cannot downgrade or stay at same tier'];
+    }
+
+    return ['valid' => true, 'upgrade_levels' => $new_level - $current_level];
+}
+
+/**
+ * Format membership data for display
+ * @pure - Data transformation only
+ */
+function format_membership_display(array $membership): array {
+    return [
+        'tier' => ucfirst($membership['tier']),
+        'expires' => date('F j, Y', strtotime($membership['expires'])),
+        'days_remaining' => max(0, (strtotime($membership['expires']) - time()) / DAY_IN_SECONDS),
+        'status' => strtotime($membership['expires']) > time() ? 'Active' : 'Expired'
+    ];
+}
+```
+
+### WordPress Integration Layer
+
+```php
+<?php
+namespace MyPlugin;
+
+use MyPlugin\BusinessLogic;
+
+/**
+ * WordPress filter hook - uses pure function
+ */
+add_filter('woocommerce_product_price', function($price, $product) {
+    if (!is_user_logged_in()) {
+        return $price;
+    }
+
+    $user_id = get_current_user_id();
+    $tier = get_user_meta($user_id, 'membership_tier', true);
+    $member_since = get_user_meta($user_id, 'member_since', true);
+    $days_member = (time() - strtotime($member_since)) / DAY_IN_SECONDS;
+
+    // Pure function call - easily testable
+    return BusinessLogic\calculate_discount($price, $tier, $days_member);
+}, 10, 2);
+
+/**
+ * WordPress action hook - handles side effects with security
+ */
+add_action('wp_ajax_upgrade_membership', function() {
+    // 1. Security first - capability check
+    if (!current_user_can('edit_user')) {
+        wp_send_json_error('Insufficient permissions', 403);
+    }
+
+    // 2. Security first - nonce verification
+    check_ajax_referer('upgrade_membership', 'nonce');
+
+    // 3. Sanitize inputs
+    $user_id = absint($_POST['user_id']);
+    $new_tier = sanitize_text_field($_POST['new_tier']);
+
+    // 4. Get current data (side effect)
+    $current_tier = get_user_meta($user_id, 'membership_tier', true);
+
+    // 5. Use pure function for validation
+    $validation = BusinessLogic\validate_tier_upgrade($current_tier, $new_tier);
+
+    if (!$validation['valid']) {
+        wp_send_json_error($validation['error']);
+    }
+
+    // 6. Update database (side effect)
+    update_user_meta($user_id, 'membership_tier', $new_tier);
+    update_user_meta($user_id, 'tier_upgraded_at', current_time('mysql'));
+
+    // 7. Send response (escaped)
+    wp_send_json_success([
+        'message' => 'Membership upgraded successfully',
+        'new_tier' => esc_html($new_tier)
+    ]);
+});
+```
+
+---
+
+## Function Factory Pattern
+
+**Pre-compile configuration for performance.**
+
+```php
+<?php
+namespace MyPlugin\Pure;
+
+/**
+ * Function factory: Pre-compile email validator
+ * @pure - Configuration captured in closure
+ */
+function create_email_validator(
+    array $bad_domains,
+    array $typo_corrections
+): callable {
+    // Configuration pre-compiled once during factory creation
+    return function (string $email) use ($bad_domains, $typo_corrections): array {
+        return validate_email_domain($email, $bad_domains, $typo_corrections);
+    };
+}
+
+/**
+ * Validate email domain
+ * @pure - Deterministic, no WordPress dependencies
+ */
+function validate_email_domain(
+    string $email,
+    array $bad_domains,
+    array $typo_domains
+): array {
+    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
+        return ['valid' => false, 'error' => 'Invalid email format'];
+    }
+
+    $domain = strtolower(substr($email, strpos($email, '@') + 1));
+
+    if (in_array($domain, $bad_domains, true)) {
+        return ['valid' => false, 'error' => 'Disposable email domain'];
+    }
+
+    if (isset($typo_domains[$domain])) {
+        return [
+            'valid' => false,
+            'error' => 'Possible typo',
+            'suggestion' => $typo_domains[$domain]
+        ];
+    }
+
+    return ['valid' => true];
+}
+```
+
+---
+
+## Production Example: Email Validator
+
+**From ima-espo plugin - 130 tests, <30ms execution.**
+
+```php
+<?php
+use function MyPlugin\Pure\create_email_validator;
+
+/**
+ * WordPress wrapper class using function factory pattern
+ */
+class EmailValidatorCore {
+    protected $validator = null;
+    protected $bad_domains = [];
+    protected $typo_domains = [];
+
+    /**
+     * Constructor: Pre-compile validator function once
+     */
+    public function __construct(array $bad_domains = [], array $typo_domains = []) {
+        $this->bad_domains = $bad_domains;
+        $this->typo_domains = $typo_domains;
+
+        // Function factory: Configuration pre-compiled once
+        // Performance: 2-5x speedup when validating multiple emails
+        $this->validator = create_email_validator($bad_domains, $typo_domains);
+    }
+
+    /**
+     * WordPress integration method
+     */
+    public function validate_email_domain(string $email) {
+        // Security: Sanitize input
+        $email = sanitize_email($email);
+
+        // Use pre-compiled validator
+        $result = ($this->validator)($email);
+
+        // WordPress integration: Log failures in debug mode
+        if (!$result['valid'] && defined('WP_DEBUG') && WP_DEBUG) {
+            error_log(sprintf('[Plugin] Email validation failed: %s - %s', $email, $result['error']));
+        }
+
+        return $result;
+    }
+
+    /**
+     * Allow customization via WordPress filters
+     */
+    public function get_bad_domains(): array {
+        return apply_filters('my_plugin_bad_email_domains', $this->bad_domains);
+    }
+}
+```
+
+### Benefits
+- **Performance**: 2-5x faster (configuration pre-compiled once)
+- **Testability**: Pure functions fully testable without WordPress
+- **Security**: Sanitization at wrapper boundary
+- **Extensibility**: WordPress filters allow customization