diff --git a/PLAN.md b/PLAN.md index 80dce40..95a03f1 100644 --- a/PLAN.md +++ b/PLAN.md @@ -812,4 +812,29 @@ Sub-phases 4b and 4c are scoped in their own `Phase 4b` / `Phase 4c` entries in - Logging: child stdout/stderr surfaced into Qt's log, optional developer console window. - Hot-reload story documented end-to-end (PHP via FrankenPHP `--watch`, QML via Qt tooling). +#### Phase 5 detailed scope + +Phase 5 is genuinely smaller than 4a — closes out outstanding DX seams that PLAN.md §8 promised: child-process log surface, scaffolding for a fresh app, hot-reload story, IDE configs. Then a release-readiness pass so a v0.1.0 tag is plausible. + +**Sub-commits (each ends runnable):** + +1. **Child-output capture + dev console.** `BackendConnection` switches FrankenPHP's `processChannelMode` to merged + readable, surfaces lines via a new `childLogLine(line, level)` signal, and keeps a small ring buffer (~500 lines) accessible via `Q_INVOKABLE childLogTail()`. Ships `DevConsole.qml` — an optional `Item` (apps drop it in via `Loader { source: ... }`) that displays the tail with auto-scroll. Skeleton + example get a `Ctrl+`` (back-tick) keybinding to toggle the console. +2. **Project init script.** `bin/php-qml-init ` (a single bash script, no system-wide install required): copies `framework/skeleton` into `/`, rewrites the path-repo to point at the user's chosen bundle location (vendored copy or absolute path), runs `composer install` and the migrations, and prints the next-step hints. Lives at the repo root so curl-based bootstrap works (`curl … | bash -s -- my-app`). +3. **Hot-reload docs + editor configs.** Documented in `framework/skeleton/README.md`: PHP-side via `frankenphp run --watch` (already what `make dev` uses), QML-side via Qt Creator's *Reload* / `qmlls` live preview / running QML from source rather than baked resources. Skeleton (and example, mirroring) ship `.vscode/launch.json` (Xdebug-into-FrankenPHP attach config + Qt host launch config) and a minimal `.idea/runConfigurations/` set so PhpStorm / Qt Creator users start with a working debugger. +4. **Release-readiness pass + v0.1.0 prep.** Root `README.md` updated to reflect the actual onboarding (clone → `php-qml-init` → `make dev` / `make appimage`). `CHANGELOG.md` created at the repo root following Keep-a-Changelog conventions, with `v0.1.0` entry summarising Phases 0-4a. PLAN.md gets a small "Status" line near the top noting current phase. **Tagging itself stays user-driven** — per the release-process memory, tagging triggers `release.yml`, which I won't pull unilaterally. + +**Out of scope for Phase 5:** + +- A real `composer create-project` package — would require publishing `php-qml/skeleton` as a Composer package, which is overkill for a single-org project. Bash-script init covers the same UX. +- Native log files / log rotation — the dev console is in-memory only. Apps that need persistent logs configure Symfony's monolog as usual; the bundled FrankenPHP already writes to `var/log/`. +- 4b / 4c (macOS / Windows) — same as Phase 4a's deferral. + +**Done criteria:** + +- `bin/php-qml-init my-app` from a fresh clone produces a working dev environment that `make dev` boots. +- Toggling the dev console in the example shows live FrankenPHP child output. +- README walks a newcomer end-to-end without reading PLAN.md. +- CHANGELOG.md records a v0.1.0 entry; tagging is the user's call. +- `make quality` stays green throughout. + After Phase 4 the POC is complete and the architecture is validated on a real packaged binary. Phase 5 is what turns it into something other people would actually adopt.