feca-mailshots-plugin/AGENTS.md

Wordpress coding rules

• Escape every rendered variable.
• Never trust request data.
• Validate first, sanitize second.
• Use nonces + capability checks for state changes.
• Use WordPress APIs before custom code.
• Use $wpdb->prepare() for dynamic SQL.
• Prefix all identifiers.
• Wrap user-facing strings in i18n functions.
• Keep templates dumb.
• Prefer readable, hook-friendly code.
• Trap all possible errors for on-screen display. Do not allow Wordpress Cricital Errors to occur.
• Interact with third-party software via well-known interfaces, not custom DOM probing.
• Don't embed magic numbers in the code - such as known memory limits for a particular operation.
• All production configuration is via admin setup page (or user's profile page for per-user setup)

Project Rules

Provide user error feedback on the pane/modal that was enabling user-interaction. Prevent exiting the page with an error that causes loss of data already entered, instead require that the user fix the error or "Quit" the page.

Obey rules in requirements/environment.md

Generated JS/PHP Quoting Safety Rules

1. Never hand-escape JS strings inside PHP string literals when avoidable.
2. When emitting JS from PHP, pass dynamic string values via json_encode(..., JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) and assign them to JS variables.
3. Prefer PHP nowdoc/heredoc blocks for inline JS/HTML over long concatenated quoted strings.
4. Do not use JS regex literals inside PHP-quoted JS when a non-regex alternative exists (split/join, replaceAll, explicit loops).
5. If regex is required, construct with new RegExp(...) from safely encoded string parts, not literal /.../ in PHP-quoted code.
6. Avoid nested quote composition ("\' or \\" chains). Build tokens with template variables + encoded parts.
7. For Twig token generation, standardize one helper function and reuse it everywhere; do not duplicate escaping logic.
8. After any change to embedded JS in PHP, run:
   • php -l <changed php file>
   • project-wide PHP lint for plugin files before finishing.
9. If a change touches emitted JS, include a runtime sanity check step: open affected admin page and confirm browser console has no syntax errors.
10. In fixes for syntax/runtime issues, prefer minimal reversible changes first, then refactor for cleanliness only after recovery.