You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cf9d428
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
`sympress/runtime` will replace WP Starter across the SymPress ecosystem.
4
4
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.**
6
6
7
7
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`.
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.
17
17
18
18
-[Parity acceptance matrix](docs/parity.md)
19
19
-[Source evidence and reproducibility](docs/source-evidence.md)
20
20
-[Architecture decisions](docs/adr/README.md)
21
21
-[Test and delivery plan](docs/test-plan.md)
22
22
-[Implementation and verification record](docs/phase1-progress.md)
23
+
-[Phase 1 review](docs/phase1-review.md)
24
+
-[Phase 2 progress](docs/phase2-progress.md)
23
25
-[Configuration](docs/configuration.md)
24
26
-[CLI](docs/cli.md)
25
27
-[Custom steps and services](docs/custom-steps.md)
Copy file name to clipboardExpand all lines: docs/adr/0008-environment-and-database-boundaries.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,5 +10,6 @@ This implements D06, D09 and D16 without removing the environment, cache or data
10
10
- 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.
11
11
- 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.
12
12
- 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.
13
14
14
15
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.
# 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.
# 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.
# 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.
`--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.
19
21
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.
21
23
22
24
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.
23
25
24
26
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.
25
27
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