feca-mailshots-plugin/requirements/environment.md

Mailshot Plugin Environment Baseline

Purpose

Define the persistent environment assumptions for this plugin so all requirements and implementation work use the same baseline.

Global Requirement Context

This document will be referenced from every requirements specification document in this repository. This document remains in the working context for all operations.

Core Policy

"Do not use fallbacks without specific instruction"

No fallback behavior may be introduced or enabled unless a requirement explicitly instructs it.

Use the following rule in prompts: Hard constraints for this task:

1. No fallbacks unless explicitly listed below.
2. No synthetic placeholders/default labels.
3. Fail fast on missing/invalid data paths.
4. Show explicit errors at point of detection.
5. If a fallback seems necessary, stop and ask first.

Repository Context

• Primary workspace: mailshot-plugin
• Reference implementation patterns: ../members-list-plugin
• Requirements folder: requirements/
• Credentials folder (local dev only): credentials/
• Results folder for test outputs and investigation findings: results/

Development Assumptions

• Development should support a local fixture/harness workflow where practical.
• Runtime code paths used in tests should match production plugin code paths as closely as possible.
• Environment-specific behavior must be explicit, documented, and testable.

Configuration Principles

• Use a single clear active configuration path per environment.
• Prefer explicit configuration over implicit defaults.
• Keep secrets outside committed source files.

Database Routing Contract

• Mailshot feature writable state (definitions, assets, run logs, and related mailshot tables) must be stored in the database named by .env variable MAILSHOTS_REMOTE_MYSQL_DB.
• Recipient/source data reads (for DSL execution against contacts/accounts/renewals and approved custom source tables) must use the database named by .env variable MEMBERS_REMOTE_MYSQL_DB.
• Requirements documents must state whether each table/operation is a write-path (MAILSHOTS_REMOTE_MYSQL_DB) or read-path (MEMBERS_REMOTE_MYSQL_DB).

Testing Hygiene

• Every test must clean up its own test artefacts.
• No test may leave persistent data/files/state behind unless a requirement explicitly allows it.
• Test results and investigation findings must be written under results/.

Build And Release Scripts

• scripts/ must contain a deployment script for deploying to the production server.
• scripts/ must contain a packaging script that creates an uploadable WordPress plugin package.

Third-Party Software Inventory

• PHP/Composer libraries (installed into vendor/):
  • twig/twig
  • dompdf/dompdf
  • transitive dependencies from composer.lock (for example masterminds/html5, sabberworm/php-css-parser, thecodingmachine/safe, Symfony polyfills)
• Frontend editor/runtime assets (vendored under plugin assets/vendor/):
  • Jodit rich-text editor
  • Ace editor (ace.js, html mode/worker, language tools, theme)
• Node/test toolchain:
  • @playwright/test
  • Playwright Chromium browser binaries (installed by Playwright CLI)
• System CLI/runtime dependencies used by scripts/runtime:
  • zip (required for plugin packaging)
  • ssh and rsync (required for remote deployment)
  • PHP CLI
  • Node.js / npm
  • gs (Ghostscript), required at runtime for merged PDF downloads
  • PHP ZipArchive, preferred at runtime for ZIP PDF downloads
  • zip CLI, required at runtime only when PHP ZipArchive is unavailable for ZIP PDF downloads

Dependency Installation Scripts

Runtime Composer dependencies must be autoloaded lazily when Twig or Dompdf is first used. Ordinary WordPress/admin bootstrap requests must not load Composer-generated runtime function files.

Mailshot database schema installation/checking must run only when the schema version or database configuration changes. Normal page reads must not execute CREATE TABLE, ALTER TABLE, or information_schema migration checks.

• scripts/install_dependencies.sh
  • Installs Composer dependencies (vendor/) for plugin runtime.
  • Installs/bundles editor assets (Jodit + Ace) into feca_mailshots_plugin/assets/vendor/.
  • Installs Node dependencies (npm ci) unless skipped by flag.
• scripts/package_plugin.sh
  • Calls scripts/install_dependencies.sh --skip-node before packaging.
  • Builds versioned WordPress zip under dist/, including runtime vendor/ and bundled editor assets.
• scripts/deploy_remote.sh
  • Calls scripts/install_dependencies.sh --skip-node before deploy.
  • Deploys plugin files and runtime vendor/ to the configured remote WordPress plugin directory.
• tests/e2e/run.sh
  • Installs Node modules if missing, installs Playwright Chromium, and runs E2E tests (fixture or remote mode).

Versioning Requirements

• The code must expose a WordPress-reportable semantic version number in x.y.z format.
• x is major, y is minor, z is patch level.
• Every deployment must increment patch level z.

Documentation Contract

Each future requirements document should:

1. Link or refer to requirements/environment.md.
2. Declare any additional environment constraints beyond this baseline.
3. State if a requirement is local-only, test-only, or production-relevant.