Skip to content

Commit cf9d428

Browse files
Merge pull request #2 from SymPress/phase-2-wordpress-runtime
feat: generate independent WordPress configuration and environment dumps
2 parents d12a963 + 8e74e9d commit cf9d428

49 files changed

Lines changed: 2621 additions & 69 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/differential.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Isolated WP Starter differential
2+
3+
on:
4+
pull_request:
5+
workflow_dispatch:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
differential:
12+
runs-on: ubuntu-24.04
13+
timeout-minutes: 20
14+
env:
15+
COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH_JSON }}
16+
steps:
17+
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
18+
- name: Set up compatible oracle PHP
19+
uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
20+
with:
21+
php-version: '8.2.33'
22+
extensions: curl, dom, mbstring, mysqli
23+
tools: composer:2.10.3
24+
coverage: none
25+
- name: Set up candidate PHP
26+
uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
27+
with:
28+
php-version: '8.5.9'
29+
extensions: curl, dom, mbstring, mysqli
30+
tools: composer:2.10.3
31+
coverage: none
32+
- name: Install candidate dependencies
33+
run: composer install --no-interaction --no-progress --no-plugins --no-scripts
34+
- name: Compare pinned oracles and candidate
35+
run: python3 tools/differential/run.py --oracle-php /usr/bin/php8.2 --candidate-php /usr/bin/php8.5 --composer "$(command -v composer)"
36+
- name: Preserve exact comparison evidence
37+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
38+
with:
39+
name: wpstarter-differential
40+
path: build/differential/report.json
41+
if-no-files-found: error

‎NOTICE‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,10 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
3131
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
3232
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
3333
SOFTWARE.
34+
35+
Generated standalone parser payloads
36+
-----------------------------------
37+
The payload builder scopes the installed Symfony Dotenv parser and its Symfony
38+
Process dependencies into an isolated namespace. It retains their original
39+
copyright headers and distributes each component's MIT LICENSE alongside the
40+
generated source. Composer CLI/DI/Messenger integrations are not bundled.

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
`sympress/runtime` will replace WP Starter across the SymPress ecosystem.
44

5-
**Status: Phase 1 implementation in progress. Phase 0 was approved on 2026-09-29. The foundation is executable; the complete WP Starter replacement is not ready for consumer migration.**
5+
**Status: Phase 1 foundation committed; Phase 2 implementation in progress. Phase 0 was approved on 2026-09-29. The complete WP Starter replacement is not ready for consumer migration.**
66

77
Requires PHP 8.5 and Symfony 8.1. The Composer plugin runs application code in a separate PHP process, with a standalone binary for installs performed using `--no-plugins`.
88

@@ -13,13 +13,15 @@ vendor/bin/sympress-runtime --list-steps
1313
composer qa
1414
```
1515

16-
Built-in WordPress steps are implemented in subsequent phases. Listing identifies pending implementations; executing one fails explicitly. Custom test fixtures already exercise first installation, repeated installation, custom vendor/bin paths, Composer commands and standalone execution.
16+
`checkpaths`, `wpconfig`, `index` and `flushenvcache` are implemented, together with `dump-env` and `flush-env-cache`. Listing identifies the remaining pending steps; executing one fails explicitly. Tests exercise first installation, repeated installation, custom vendor/bin paths, Composer commands, independent generated configuration and standalone execution.
1717

1818
- [Parity acceptance matrix](docs/parity.md)
1919
- [Source evidence and reproducibility](docs/source-evidence.md)
2020
- [Architecture decisions](docs/adr/README.md)
2121
- [Test and delivery plan](docs/test-plan.md)
2222
- [Implementation and verification record](docs/phase1-progress.md)
23+
- [Phase 1 review](docs/phase1-review.md)
24+
- [Phase 2 progress](docs/phase2-progress.md)
2325
- [Configuration](docs/configuration.md)
2426
- [CLI](docs/cli.md)
2527
- [Custom steps and services](docs/custom-steps.md)

‎docs/adr/0008-environment-and-database-boundaries.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@ This implements D06, D09 and D16 without removing the environment, cache or data
1010
- Database probes represent unavailable/unauthorized connections as unknown, not a confirmed absent database. The additional `status()` API exposes nullable existence/installation results and a fixed diagnostic reason. The legacy boolean accessors still exist. Unknown results do not publish false existence flags into the environment.
1111
- Supplied database flags must be complete, boolean and consistent. Upstream skips its probe if any flag exists, which can silently treat incomplete state as authoritative. Native validation fails explicitly. Database/user string `0` is accepted as nonempty; upstream's truthiness check rejects it.
1212
- Host parsing supports explicit TCP ports, bracketed IPv6 and Unix sockets. `mysqlcheck` receives credentials only through a private temporary option file, removed on success and failure. It receives a literal database argument after `--`; no password is interpolated into argv or a shell command.
13+
- Automatic preflight preserves profile timing: native and release check selected runs, dev checks only full runs, and listing never probes. A disabled check remains lazy for later explicit service use. Native `db-check=health` returns failure to the command when health cannot be established; the legacy profile preserves the upstream ignored return value with a diagnostic. Ordinary status discovery can continue setup for a missing/unavailable database and reports unknown state explicitly.
1314

1415
Evidence: `EnvironmentTest`, `EnvironmentFiltersTest`, `ConstantCatalogTest`, `DbCheckerTest` and `DatabaseTest`. Exact differential cases must preserve the source's false/unknown distinction and incomplete-flag behavior rather than normalizing them away.
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# ADR 0009: Independent payload publication and path guards
2+
3+
Status: implementation decision, 2026-09-29; full generated configuration and differential fixtures pending.
4+
5+
The independent parser payload from ADR 0006 is published below `var/runtime/{sha256}`. Its fingerprint includes the builder implementation, environment source, Symfony parser/process source and license notices. A generated configuration references one immutable version. A new build publishes through a sibling temporary directory before any configuration switches to it. Older versions remain available to concurrent requests and are not automatically deleted.
6+
7+
The payload scopes environment and Symfony classes into a fingerprint-specific namespace and provides a local autoloader for that namespace only. It does not require Composer, runner DI or the project's Symfony graph. Symfony Dotenv command substitutions retain the Process implementation, exceptions and platform pipes they need. CLI/Messenger integrations are excluded because the parser does not call them. Both Symfony MIT licenses and the runtime license/NOTICE travel with the payload. Separate-process tests exercise interpolation and a real command substitution without a project autoloader and with a conflicting host Dotenv class.
8+
9+
Existing immutable payloads are checked against their expected bytes. A modified build is reported and preserved, never silently replaced. Staging leftovers from a failed publication are removed only by their creating operation.
10+
11+
Generated targets must remain physically inside the project, including existing ancestors of a missing target. Explicit external environment directories remain supported for environment files/cache; the content and generated-code targets cannot escape through symlinks. `checkpaths` checks readable files rather than accepting a directory named `wp-settings.php`.
12+
13+
When WordPress itself occupies the project/webroot, `index` leaves its existing front controller in place. Generating a wrapper there would make it include itself. This corrects the upstream edge case without removing the root installation mode. The differential case must record the preserved core index explicitly.
14+
15+
`flush-env-cache` removes only the configured runtime cache path. A symlink is unlinked without touching its target. A real directory at that filename is an error and is never removed recursively. Other runtime versions, kernel caches and build-time dumps are unaffected.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# ADR 0010: Managed configuration regeneration and build dumps
2+
3+
Status: implementation decision, 2026-09-29; full differential acceptance pending.
4+
5+
## Generated configuration
6+
7+
Native configuration lives at the project root and a webroot proxy points to it when needed. Release compatibility keeps the webroot location. Every target is checked before publication; `--force` can override file protection but cannot replace directories or symlinks. PHP syntax is checked for both main and proxy content before either is published. Files are replaced atomically with mode 0600, and identical content is not rewritten. Deployment must run PHP with read access to these private files.
8+
9+
The main file retains all 19 section names from the source union. A comment stores hashes of the generated section bodies. On regeneration, a section whose current body differs from the previous generated hash is retained and reported. Untouched sections receive template/settings updates. This protects edits through the section API; arbitrary edits outside sections are not a supported persistence mechanism. A custom template receives a diagnostic that it owns the bootstrap guarantees it replaces, as required by ADR 0006.
10+
11+
The KEYS section is treated specially. Literal fallback salts are read with PHP tokens without executing the existing configuration, including quoted/escaped bytes and literal concatenation. Existing section content is retained and only missing key definitions are appended. Dynamic definitions inside a retained KEYS section remain executable and are preserved. A dynamic salt outside a preservable section causes a diagnostic before replacement, because evaluating user PHP merely to discover a secret would be unsafe; migration must retain that code explicitly. `--force` does not rotate existing salts.
12+
13+
Generated native content paths remain explicit absolute strings even before the directory exists, rather than becoming false from `realpath()`. Relative URL path segments are percent-encoded; filesystem literals preserve their original bytes. Normal upstream directory names produce identical URLs, while quote/space-containing names remain valid. These edge differences require exact differential fixtures.
14+
15+
The native getter and compatible getter/filter use one initialized reader. Legacy runtime calls issue a diagnostic once per alias through WordPress's deprecation API when available, otherwise a PHP deprecation. Existing WordPress constants are retained, environment-specific PHP and early hooks keep the original order, and Site Health exposes only a fixed path/environment/cache/flag allowlist. A proxy WP-CLI invocation returns before loading WordPress settings.
16+
17+
## Build-time dump
18+
19+
`dump-env <raw-environment>` and `composer sympress-runtime:dump-env <raw-environment>` resolve an explicit file chain without running custom steps or run-only autoload code. A conflicting actual process environment fails rather than producing a misleading dump. The explicit selector is included even when no dotenv file exists. The output is `.env.dump.php` in the configured environment directory, distinct from `.env.cached.php`.
20+
21+
The generated runtime prefers a valid build dump over the ordinary cache, even when runtime caching is disabled. It verifies format/profile/environment and retains actual process precedence. Dump mode never schedules runtime cache writes. The dump is published atomically with mode 0600 and may be made read-only for deployment. Flush removes only the ordinary cache. Unmarked existing dump files are preserved.
22+
23+
Evidence includes separate generator/request processes, private/read-only file modes, managed section edits for every named section, real environment overrides, local cache policy/filter behavior, PHP template syntax, target protection and a real WordPress 7.1.1 SHORTINIT database smoke. Full admin/kernel boot and compatibility differential checks remain distinct acceptance gates.
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# ADR 0011: Preserve the default environment directory capability
2+
3+
Status: implementation decision based on a reproduced pinned-source defect, 2026-09-29.
4+
5+
## Evidence
6+
7+
At dev commit `059bbc9198ac51dee86c5233b6b006ca4d8008a4`, Config defaults `env-dir` to null. `Step/WpConfigStep.php:120` unwraps that option without a fallback; `Config/Validator.php:566` rejects null with `Folder name must be in a string.`. The blocking step reports failure and leaves the index absent, but ComposerPlugin does not propagate the step result to its command exit status. The observed exit status is zero. The release baseline resolves the omitted directory through its root fallback instead.
8+
9+
The isolated `dev/default-env-dir` fixture executes the unmodified upstream plugin with the option omitted. It requires the exact diagnostic, exit status and absent index. A matching candidate fixture must generate a working index/config and boot once with database settings from the root environment file. Ordinary generated-runtime comparisons set `env-dir: "."` identically on both sides so the dev oracle can execute; the failure fixture is not waived.
10+
11+
## D23 decision
12+
13+
An omitted environment directory resolves to the project root in every runtime profile. This preserves the required zero-config feature and the release behavior. Reproducing the dev failure would remove that capability. Explicit directory validation and configured paths remain available. Failure exit propagation remains governed separately by D12.
14+
15+
This adds the exact default-directory difference to PAR-OPT-015; it does not allow arbitrary directory or config-validation mismatches. The source checkout and installed oracle remain unmodified.

‎docs/adr/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,6 @@ Implementation decisions after Phase 0:
1515

1616
7. [Filesystem and discovery safety](0007-filesystem-and-discovery-safety.md)
1717
8. [Environment and database service boundaries](0008-environment-and-database-boundaries.md)
18+
9. [Independent payload publication and path guards](0009-independent-payload-and-path-guards.md)
19+
10. [Managed configuration regeneration and build dumps](0010-managed-config-regeneration-and-dumps.md)
20+
11. [Pinned oracle default environment directory defect](0011-oracle-default-env-directory.md)

‎docs/cli.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,19 @@ The standalone runner uses the current project directory and its Composer vendor
1212
| `--list-steps` | List matching steps, sorted; never execute steps or connect to the database |
1313
| `--force` | Allow overwriting protected files; directories and symlinks remain protected |
1414
| `validate` | Validate JSON/schema and semantic configuration without executing PHP providers or the run-only autoload file |
15+
| `flush-env-cache` | Remove only the runtime cache in the configured environment directory; WordPress installation is not required |
16+
| `dump-env <environment>` | Resolve an explicit raw environment into a private `.env.dump.php`; does not execute steps or run-only autoload |
1517
| `-n`, `--no-interaction` | Use documented question defaults |
1618
| `-q`, `-v`, `-vv`, `-vvv`, `--ansi`, `--no-ansi` | Standard Symfony Console output controls |
1719

1820
`--skip` without names is an error. Native explicit selection wins over `skip-steps` and `--skip-custom`. Command-only steps are available only through explicit selection or listing. Unknown selected names produce diagnostics; a partial valid selection still executes, while a selection containing no valid steps fails.
1921

20-
Composer exposes `composer sympress-runtime [steps] [flags]` and `composer sympress-runtime:validate`. Install/update events run at priority 0, before asset-compiler's documented -1000 priority. The host uses Composer APIs and PHP standard-library process launching; project Symfony services are instantiated only in the child.
22+
Composer exposes `composer sympress-runtime [steps] [flags]`, `composer sympress-runtime:validate`, `composer sympress-runtime:flush-env-cache` and `composer sympress-runtime:dump-env <environment>`. Install/update events run at priority 0, before asset-compiler's documented -1000 priority. The host uses Composer APIs and PHP standard-library process launching; project Symfony services are instantiated only in the child.
2123

2224
Exit status is zero for successful/no-op execution, nonzero for invalid input, configuration errors or any failed step. A blocking step stops subsequent work on pure ERROR; SUCCESS|ERROR continues but the command still fails. Composer event failures stop subsequent root scripts.
2325

2426
Legacy profiles retain their documented selection differences, including rejecting positional opt-in combined with listing. Native mode permits this combination. The current test suite verifies root-script ordering; real asset-compiler coexistence remains a later acceptance check.
2527

26-
During phased implementation, pending built-in steps are labeled and fail if selected. `doctor`, `check`, `dump-env`, `migrate` and `flush-env-cache` are reserved command names and are not yet implemented.
28+
During phased implementation, pending built-in steps are labeled and fail if selected. `doctor`, `check` and `migrate` are reserved command names and are not yet implemented.
29+
30+
A build dump takes precedence over the runtime cache and disables request-time cache writes. Actual process values still win. The requested raw environment must agree with an actual process environment selector; otherwise dump creation fails. Remove or rebuild the dump to switch its environment. Flush never deletes a build dump. Deploy generated configuration and dumps with PHP-readable private permissions; defaults are mode 0600.

0 commit comments

Comments
 (0)