# 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.