Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 20 additions & 5 deletions .github/workflows/differential.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,20 @@ jobs:
timeout-minutes: 20
env:
COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH_JSON }}
RUNTIME_TEST_DB_HOST: '127.0.0.1:3306'
RUNTIME_TEST_DB_USER: root
RUNTIME_TEST_DB_PASSWORD: runtime-ci-fixture
services:
database:
image: mariadb:11.4
env:
MARIADB_ROOT_PASSWORD: runtime-ci-fixture
MARIADB_ROOT_HOST: '%'
ports:
- 3306:3306
options: >-
--health-cmd="healthcheck.sh --connect --innodb_initialized"
--health-interval=5s --health-timeout=5s --health-retries=20
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
- name: Set up compatible oracle PHP
Expand All @@ -31,13 +45,13 @@ jobs:
coverage: none
- name: Install candidate dependencies
run: composer install --no-interaction --no-progress --no-plugins --no-scripts
- name: Install VCS fixture tools
run: sudo apt-get update -qq && sudo apt-get install -y -qq mercurial subversion
- name: Verify real VCS integrations
run: php vendor/bin/phpunit --filter VcsIgnoreStepTest --no-progress --fail-on-skipped
- name: Install VCS and database fixture tools
run: sudo apt-get update -qq && sudo apt-get install -y -qq mercurial subversion mariadb-client
- name: Prepare pinned WordPress and WP-CLI fixtures
run: python3 tools/ci-fixtures.py
- name: Verify executed evidence for every parity row
run: |
php vendor/bin/phpunit --no-progress
php vendor/bin/phpunit --no-progress --fail-on-skipped
php vendor/bin/phpunit --no-logging --list-tests-xml build/test-list.xml
python3 -m unittest discover -s tools/tests
python3 tools/parity-evidence.py
Expand All @@ -51,4 +65,5 @@ jobs:
build/differential/report.json
build/parity-evidence.json
build/phpunit.xml
build/ci-fixtures/manifest.json
if-no-files-found: error
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# SymPress Runtime agent contract

## Current gate
## Current delivery state

The project owner approved Phase 0 and authorized Phase 1 on 2026-09-29. Implement the foundation according to the accepted ADRs. Consumer migration remains in Phase 6.
The project owner approved Phase 0 on 2026-09-29 and subsequently authorized PR review and merges. Phases 1–6 are merged. Implement review corrections according to the accepted ADRs and track fresh evidence in `docs/acceptance.md`; do not treat historical phase reports as current completion claims.

## Implementation contract after approval

Expand Down
13 changes: 10 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,14 @@
## Unreleased

- Approved source-derived WP Starter parity inventory and architecture decisions.
- Begin the isolated Composer/standalone runner, configuration/schema, CLI and service foundation.
- Add real Composer fixture tests and PHP 8.5 / PHPUnit 13 quality gates.
- Implement isolated Composer and standalone setup, all twelve default steps, configuration validation, extension services/events, legacy API adapters and migration diagnostics.
- Generate WordPress configuration with an independent environment-parser payload, stable salts, managed sections, environment caches and production dumps.
- Add kernel diagnostics, cache maintenance and optional boot ownership.
- Preserve WPackagist/private/path package installation and bounded offline recovery after Composer plugins are disabled.
- Preserve correctly installed root and nested layouts, and replace URL-dropin symlinks only after download verification.
- Restore early Composer autoload through `wp-config-autoload` (enabled by default in legacy profiles), and bound service downloads through `download-max-bytes`.
- Honor disabled compatibility for legacy environment sentinels and constant mappings, including cached and dumped environments.
- Provide deployment and user guides, explicit upstream interface attribution, and a CI suite requiring real database/WordPress/WP-CLI fixtures with no skipped tests.
- Add real Composer fixture tests, pinned differential comparisons and PHP 8.5 / PHPUnit 13 quality gates.

This is an incomplete development branch, not a production release or a completed drop-in replacement.
Unreleased work remains subject to the acceptance record; passing a fixture suite does not establish compatibility with every third-party extension or installer layout.
10 changes: 10 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,16 @@ resources/legacy-mu-loader.php.txt and resources/legacy-mu-loader-dev.php.txt ar
the pinned upstream MU loader templates, retained only for byte-exact
recognition of generated files during migration.

Source-derived API compatibility files (verified against upstream dev revision
059bbc9198ac51dee86c5233b6b006ca4d8008a4):
- src/Process/PhpTool.php adapts src/Cli/PhpTool.php: tool interface method
signatures, with SymPress namespace and service types.
- src/Step/NullStep.php adapts src/Step/NullStep.php: extensible no-op step
contract and return values, using SymPress StepInterface.
- src/Step/ScriptHaltSignal.php adapts src/Step/ScriptHaltSignal.php: propagation
and step-halting factories/accessors, with readonly promoted properties.
These adaptations remain covered by the following retained upstream MIT notice.

The MIT License (MIT)

Copyright (c) 2023 Giuseppe Mazzapica and contributors.
Expand Down
11 changes: 9 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# SymPress Runtime

`sympress/runtime` will replace WP Starter across the SymPress ecosystem.
`sympress/runtime` provides Composer project setup and generated WordPress runtime configuration for SymPress, with WP Starter migration support.

**Status: Phases 1-5 are available as stacked draft PRs. Phase 6 implements migration and compatibility diagnostics; full parity acceptance and consumer migration remain open. Phase 0 was approved on 2026-09-29.**
**Status: Phases 1–6 are merged. Review corrections and final parity acceptance are tracked in [the acceptance record](docs/acceptance.md). No stable release or universal drop-in acceptance is claimed.**

Requires PHP 8.5 and Symfony 8.1. The Composer plugin runs application code in a separate PHP process. The standalone binary also recovers standard WordPress package paths after `composer install --no-plugins`, before loading project code. WPackagist, private repositories and local Composer packages keep the regular installer workflow; dependency resolution and downloads stay with Composer. See [the package-layout boundaries](docs/adr/0019-standalone-wordpress-package-layout.md) and [the acceptance record](docs/acceptance.md).

Expand All @@ -15,6 +15,13 @@ composer qa

All twelve inventoried setup steps are implemented, together with scripts/events, extension autoloading, legacy step adapters, environment dumps and cache flushing. Kernel maintenance, optional boot ownership and doctor/check support standalone, Composer and kernel-console workflows. Tests cover isolated Composer execution, independent generated configuration, real WordPress/WP-CLI/VCS fixtures and an actual compiled kernel on a read-only filesystem.

- [Getting started](docs/getting-started.md)
- [Settings cheat sheet](docs/settings-cheat-sheet.md)
- [Environment, caches and dumps](docs/environment.md)
- [Generated wp-config and sections](docs/wp-config.md)
- [Setup steps](docs/steps.md)
- [WP-CLI](docs/wp-cli.md)
- [Deployment and payload retention](docs/deployment.md)
- [Parity acceptance matrix](docs/parity.md)
- [Source evidence and reproducibility](docs/source-evidence.md)
- [Architecture decisions](docs/adr/README.md)
Expand Down
16 changes: 12 additions & 4 deletions docs/acceptance.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Runtime acceptance record

The implementation is available through the six stacked Runtime PRs, ending at [Phase 6](https://github.com/SymPress/runtime/pull/6). Consumer changes are separate drafts: [starter #29](https://github.com/SymPress/starter/pull/29) and [demo #49](https://github.com/SymPress/demo/pull/49). Their lockfiles pin Runtime commit `cfc5ffd`. This record deliberately keeps final acceptance open.
All six Runtime implementation PRs are merged; [Phase 6](https://github.com/SymPress/runtime/pull/6) merged as `b1c166205cd907b93a216b82b65b2d49ffec3f32` on 2026-09-30. Review corrections are being validated on top of that baseline. Consumer changes remain separate open PRs: [starter #29](https://github.com/SymPress/starter/pull/29) and [demo #49](https://github.com/SymPress/demo/pull/49). Their final dependency locks and checks must be verified after the Runtime corrections merge. This record deliberately keeps final acceptance open.

## Reproduced evidence

- Full local package QA passes with 1,043 tests / 7,298 assertions, no skips, coding standards and PHPStan max.
- Full local package QA after the review corrections passes with 1,059 tests / 7,365 assertions, no skips, coding standards and PHPStan max.
- All 407 source-inventory rows map to executed PHPUnit behavioral tests. The evidence checker also rejects duplicate or unknown IDs, missing results, failed tests and skipped-only rows. It does not claim complete branch coverage from a passing test count.
- The isolated differential harness passes 249 cases against the exact release and development commits in `upstream-inventory.json`. It compares constant types and values, environment precedence, generated configuration execution, cache behavior, content hashes/links, WP-CLI arguments, lifecycle callbacks, extension loading, effective step order, all nineteen section edits, MU-loader execution, parsed WP-CLI YAML and active env-example assignments. Intentional differences are asserted as exact expected values, not unrestricted exclusions.
- The isolated differential harness passes 251 cases against the exact release and development commits in `upstream-inventory.json`, including early Composer classes and hooks. It compares constant types and values, environment precedence, generated configuration execution, cache behavior, content hashes/links, WP-CLI arguments, lifecycle callbacks, extension loading, effective step order, all nineteen section edits, MU-loader execution, parsed WP-CLI YAML and active env-example assignments. Intentional differences are asserted as exact expected values, not unrestricted exclusions.
- Real WordPress SHORTINIT connects to a disposable MariaDB database without a Composer autoloader. Its production build dump also boots under an unprivileged identity with read-only project files and unchanged file hashes. A separate actual SiteKernel test loads a precompiled production container under the same permission constraint.
- Fresh, separate DDEV starter and demo projects install WordPress, authenticate into the admin dashboard, boot the kernel once and run `wp console debug:container`. Browser checks capture HTTP 200 responses and zero JavaScript errors. Starter QA passes 6 tests / 47 assertions; demo QA passes 27 tests / 213 assertions plus REST/block/render/ORM smoke.
- Repeated normal Composer installation, a global `composer install --no-plugins`, and the standalone runner preserve 543 starter and 664 demo artifact hashes/link targets. The replay follows each project's configured content path and includes built demo assets and the deterministic package-layout record. Both consumer QA suites pass again after this recovery.
Expand All @@ -15,13 +15,21 @@ The implementation is available through the six stacked Runtime PRs, ending at [
## Open acceptance gates

1. **Layout boundary review.** The reproduced starter/demo and WPackagist no-plugins gaps are fixed by offline package placement and metadata/autoload recovery, documented in [ADR 0019](adr/0019-standalone-wordpress-package-layout.md). Root-directory installs, overlapping package destinations and arbitrary third-party installer semantics still require the regular Composer installers. Unknown destination conflicts fail while preserving files. This is a deliberate safety boundary, not a claim that every possible Composer installer layout has been verified.
2. **Consumer CI access.** The [QA PHPUnit 13 PR](https://github.com/SymPress/qa/pull/3) and Runtime phases 1–5 were reviewed and merged after successful CI. All six Runtime PRs passed remote QA before the final Phase 6 review fixes; those fixes pass the complete local suite above and require their own final CI result before merging. Starter and demo still need CI read access to the private Runtime repository and must move their dependency to Runtime main after Phase 6 merges. No CI credentials or repository access have been changed.
2. **Corrected revision and consumer CI.** The [QA PHPUnit 13 PR](https://github.com/SymPress/qa/pull/3) and all Runtime phases are merged. The review corrections pass full local QA and differential comparisons; their no-skip integration CI result remains required. Consumer PRs must install the reviewed Runtime revision with their own CI credentials and pass their checks before merging. GitHub rejects deploy keys for Runtime; a read credential is still needed, and no rejected key or temporary SSH secret was retained.
3. **Final parity sign-off.** Matrix rows remain `partial` until the preceding gates are resolved and the complete acceptance record is reviewed. The implementation and behavioral evidence are present; there is no claim of complete drop-in acceptance yet.

## Review corrections

The standards review found that offline recovery restrictions also rejected already-correct root and nested package layouts. Preparation now preserves those regular-installer layouts, with regression tests for repeated setup and rejection without mutation when recovery is actually required. The specification review found that URL dropins ignored `--force` when the destination was a symlink. Verified downloads now replace only the link; failed checksum verification leaves the link and its source intact. Both corrections are covered by the full local suite above.

The subsequent independent review identified missing early project autoload, unbounded service downloads, missing fixture enforcement in CI and incomplete user/deployment documentation. [ADR 0020](adr/0020-early-autoload-and-download-limits.md) records the implementation corrections. User guides now include required payload deployment and rollback-safe retention; old payloads are never automatically pruned. NOTICE identifies the three source-derived API files individually.

Final source review also found legacy loaded-marker/constant-mapping controls remained active with compatibility disabled. Runner, generated configuration, doctor and cached/dumped environments now honor that switch. Regression tests cover ignored legacy controls, retained native controls, name-only diagnostics and cache-mode mismatches.

The consumer URL correction restores `WP_SITEURL=${WP_HOME}`. Both Nginx configurations are byte-identical to their original PR bases. Starter setup/dry-run defaults agree; its updated QA passes 7 tests / 49 assertions. Demo QA passes 27 tests / 213 assertions plus live runtime smoke. Fresh browser sessions verify root login form actions, root admin dashboards, HTTP 200 homepages and no JavaScript errors. Existing cached environment values were cleared with Runtime's cache-flush command.

The differential workflow now provisions disposable MariaDB, mysqlcheck, Git/Hg/SVN and pinned SHA-256-verified WordPress 7.1.1/WP-CLI 2.12.0 fixtures before running the **entire** PHPUnit suite with `--fail-on-skipped`. The generic reusable QA job may still lack integration fixtures; its green result alone is not full integration evidence. `tools/ci-fixtures.py` was exercised locally, and all six fixture-dependent DB/WordPress/WP-CLI/read-only tests passed (81 assertions, no skips) using its downloaded artifacts. A successful remote run of the corrected workflow remains required.

## Reproduction

Run `composer qa` with the dedicated `RUNTIME_TEST_DB_HOST`, `RUNTIME_TEST_WORDPRESS_DIR` and `RUNTIME_TEST_WPCLI_BOOTSTRAP` fixtures configured. Then run:
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0005-compatibility-and-differences.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The feature union stays available. Differences below are scoped behaviors with s
| D10 | WP Starter deletes package dropin source directories after publishing; this can break symlinks or destroy package contents. | Publish safely and retain sources; transactional replacement, no dangling links. Move-content remains explicitly available. |
| D11 | Source supports ten static dropin filenames; current WordPress has additional entries. | Use the verified current core catalog plus upstream union, including multisite. Unknown dropin support remains via the R option and explicit map. |
| D12 | R global script names are pre-wpstarter/post-wpstarter; brief calls them pre-/post-. D adds halt signals; automatic errors can be swallowed. | Support canonical run names, bare names and legacy aliases. Preserve halt/propagation controls, report aggregate failure with nonzero exit; isolate callback failures as documented. |
| D13 | Generated config imports vendor/autoload.php and upstream/Symfony classes. | Generate a self-contained bootstrap artifact; no Composer classloader required for WordPress config runtime. Keep extension autoload as a runner feature and let the existing MU package load application dependencies. ADR 0006. |
| D13 | Generated config imports vendor/autoload.php and upstream/Symfony classes. | The environment parser uses a self-contained bootstrap artifact. Native `wp-config-autoload=false` permits configuration runtime without Composer; `true` restores early project autoload after WordPress's hook API. Both legacy profiles default true and migration records that behavior. Runner extension autoload remains separate. ADR 0006 and ADR 0020; exact `release/early-project-autoload` and `dev/early-project-autoload` differential cases retain upstream hook/class availability. |
| D14 | Legacy constructors/callbacks can require Composer internals. | Preserve equivalent operations through native services, provide adapters where type-compatible, and report concrete PHP rewrites. No false promise that arbitrary Composer-typed callbacks run unchanged; ADR 0004. |
| D15 | Section editors use regex replacement strings that interpret dollar/backslash content. R also repeats identical append/prepend calls and throws on a missing section; D deduplicates by call site and leaves missing sections unchanged. | Resolve the generated target, keep replacement text literal, and consistently use D's call-site deduplication and missing-section no-op behavior. This preserves editable sections while making repeated generation safe. All nineteen sections have explicit R/D differential cases. |
| D16 | DB flags can short-circuit on any existing flag; failure paths can conflict with immutable env writes. R probes DB in selected mode; D limits automatic preflight to full runs. | Keep profile-specific behavior; native enabled preflight runs before selected steps except listing, validates complete externally supplied status, reports unknown separately and writes a consistent result once. Preserve valid/env/exists/installed evaluation order and health checks. |
Expand Down
Loading
Loading