# Development Environment

## Purpose
Define the standard development environment for the WordPress calendar plugin so that development, testing, packaging, and deployment are consistent across contributors.

## Repository Layout
The repository is organized into the following top-level folders:

- `requirements/`: Functional and non-functional requirements.
- `docs/`: Documentation (test execution, installation, data structures, workflows).
- `code/`: Plugin source code.
- `compatibility-layer/`: Local WordPress emulation and stand-alone harness/shim code for tests.
- `tests/`: Automated and manual test assets.
- `package/`: Build outputs and distributable plugin package artifacts.

Note: the project convention may refer to `documentation/`; in this workspace the equivalent directory is `docs/`.

## Supported Development Platforms
Developers should use one of:

- Linux (preferred)
- macOS

Windows is acceptable when using WSL2 with a Linux userland.

## Core Tooling
Minimum expected tools:

- `bash` shell
- `ssh` client for remote test server access
- `zip` (or equivalent) for plugin packaging
- `rsync` or `scp` for deployment transfer
- Subversion (`svn`) and/or Git as required by the hosting/deployment workflow

If project scripts introduce additional dependencies (for example PHP CLI, Composer, Node.js, or WP-CLI), those requirements must be documented in `docs/` and kept aligned with this environment spec.

## Runtime Targets
Development and verification occur against two runtime targets:

1. Local compatibility harness (`compatibility-layer/`)
2. Remote WordPress test server (via SSH)

Production deployment is by packaged plugin artifact, not by direct source sync from `code/`.

Strict runtime/code separation requirements are defined in `requirements/architecture.md`.

## Local Development Workflow Expectations
- Implement plugin changes in `code/`.
- Keep requirements updates in `requirements/`.
- Add or update tests in `tests/`.
- Validate behavior first in the local compatibility harness (`compatibility-layer/`).
- Build distributable package into `package/`.

## Local Compatibility Harness Environment
The local harness in `compatibility-layer/` must emulate the WordPress functions/APIs needed by the plugin.

Environment expectations:

- Deterministic startup and teardown for repeatable tests.
- Isolated test data/state between runs.
- Ability to run plugin unit/integration-style tests without external network dependencies unless explicitly required.
- Clear commands documented in `docs/` for:
  - harness startup
  - test execution
  - harness reset/cleanup

## Data Access Boundaries (Compatibility Harness and Tests)
When code under `code/` is exercised via the compatibility harness, data access must remain within approved WordPress mechanisms.

Requirements:

- Plugin code must access persistent data through WordPress-supported mechanisms (for example `$wpdb`, WordPress options/settings APIs, and documented plugin tables via WordPress DB access patterns).
- Plugin code must not bypass WordPress mechanisms by directly accessing external/non-WordPress data stores during compatibility-harness execution.
- Compatibility-harness and test runs must not depend on or read data outside the harness-managed test database/state.
- Any integration that requires external data access must be explicitly documented and excluded from default regression runs unless intentionally enabled.

## Remote Test Server Environment
Remote test validation is performed over SSH to a dedicated test environment.

Environment expectations:

- SSH access is key-based and restricted to authorized developers.
- Test server WordPress and PHP versions should mirror production as closely as practical.
- Deployment to test should use packaged plugin artifacts or an equivalent controlled sync process.
- Test data handling must avoid accidental production data access.

Required documentation in `docs/`:

- Host access method
- Deployment command(s)
- Rollback approach
- Post-deploy smoke test checklist

## Packaging and Deployment Environment
Production release uses a packaged plugin artifact produced from repository sources.

Detailed remote deployment and exact-match validation requirements are defined in `requirements/deployment.md`.

Packaging expectations:

- Package is generated in `package/` with versioned naming.
- Artifact contains only required plugin files.
- Development-only files (temporary files, compatibility-layer artifacts, etc.) are excluded.
- Package integrity is validated before deployment.

Deployment expectations:

- Upload/install package on production server via approved operational process.
- Record deployed version and deployment timestamp.
- Maintain a rollback artifact for the previous known-good release.

## Configuration and Secrets
- Do not commit secrets to source control.
- SSH credentials/keys, server addresses, and environment-specific configuration must be stored outside the repo (or in approved secret management).
- Local and remote environment variables should be documented by name and purpose in `docs/` without exposing secret values.
- Compatibility-harness email workflows use SMTP variables sourced from `credentials/.env` (or process env):
- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USE_TLS`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_ADMIN_TO`

## Quality Gates
Before packaging for test or production:

- Requirements impacted by change are updated.
- Relevant tests in `tests/` pass in local compatibility harness.
- Remote test server smoke checks pass.
- Package contents are verified.

## Change Control
Any material change to tools, runtime versions, harness behavior, or deployment process must update:

- this file (`requirements/environment.md`)
- corresponding operational docs in `docs/`