111 lines
4.7 KiB
Markdown
111 lines
4.7 KiB
Markdown
# 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
|
|
- Optional at runtime for PDF merge/zip fallback paths: `gs` (Ghostscript), `zip` CLI
|
|
|
|
## Dependency Installation Scripts
|
|
|
|
- `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.
|