refactor(cli)!: hard-cut legacy scripts and standardize console runtime

- remove legacy bin/module-*.php and bin/doctor.php entry scripts

- move module/doctor execution into class-based runners under lib/Console

- add stable JSON output for doctor and module:sync

- introduce bin/dev for init/up/down/logs/console/qa workflow

- update DI wiring, phpstan scan config, tests, and docs to new CLI contract
This commit is contained in:
2026-04-01 17:14:20 +02:00
parent 0bf7f62fd8
commit 7121732fcf
38 changed files with 1686 additions and 986 deletions

View File

@@ -103,6 +103,6 @@ $meinService = app(\MintyPHP\Service\MeinNeuerService::class);
den konkreten Service direkt registrieren und per `app()` holen.
- Der Container lebt **pro HTTP-Anfrage** — er wird in `web/index.php` initialisiert
und über `setAppContainer()` im globalen State abgelegt.
- In CLI-Skripten (`bin/`) wird der Container separat initialisiert (s. `bin/module-cli-bootstrap.php`).
- In CLI-Commands wird der Container separat initialisiert (ueber die Runtime-Bootstrap-Klassen unter `lib/Console/Support/`).
- In `lib/Service/**` außerhalb von `*Factory.php` niemals `new ...Factory()`,
`new ...Service()` oder `new ...Repository()` direkt instanziieren.

View File

@@ -1,16 +1,29 @@
# Lokale Entwicklung
Letzte Aktualisierung: 2026-03-18
Letzte Aktualisierung: 2026-04-01
## Ziel
Kompakter Tagesworkflow für Entwicklung, Tests und schema-nahe Änderungen.
## First-Time Workflow
```bash
bin/dev init
```
`bin/dev init` ist nicht-destruktiv und fuehrt aus:
1. `.env` aus `.env.example` erstellen (falls fehlend)
2. `docker compose up --build -d`
3. `module:sync`
4. `doctor`
## Start/Stop
```bash
docker compose up -d
docker compose down
bin/dev up
bin/dev down
```
Hinweis: `up -d` startet auch den Scheduler-Service.
@@ -34,6 +47,7 @@ Dieser Befehl fuehrt automatisch aus: `migrate` → `permissions-sync` → `buil
Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist der Sync noetig.
Alle verfuegbaren CLI-Kommandos: `php bin/console list` (siehe `/docs/reference-cli-commands.md`).
Alle Dev-Orchestrator-Kommandos: `bin/dev --help`.
## Schema-Stand

View File

@@ -1,6 +1,6 @@
# CLI-Kommandoreferenz
Letzte Aktualisierung: 2026-03-25
Letzte Aktualisierung: 2026-04-01
## Einstiegspunkt
@@ -36,6 +36,12 @@ Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MOD
Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist dieser Befehl die Loesung.
Maschinenlesbar:
```bash
docker compose exec php php bin/console module:sync --format=json
```
### module:migrate
Wendet ausstehende SQL-Migrationen aus aktiven Modulen an.
@@ -120,6 +126,27 @@ docker compose exec php php bin/console doctor
Siehe `/docs/howto-betriebscheck-doctor.md` fuer Details.
Maschinenlesbar:
```bash
docker compose exec php php bin/console doctor --format=json
```
## Developer-Orchestrator (`bin/dev`)
Fuer lokalen Workflow gibt es zusaetzlich den Dev-Orchestrator:
```bash
bin/dev init
bin/dev up
bin/dev down
bin/dev logs [service]
bin/dev console module:sync
bin/dev qa
```
`bin/dev console ...` delegiert intern auf `docker compose exec -T php php bin/console ...`.
## Neue Kommandos anlegen
1. Klasse in `lib/Console/Commands/` erstellen, die `MintyPHP\Console\Command` erweitert.
@@ -156,13 +183,4 @@ Die `Command`-Basisklasse stellt Helfer bereit:
|---|---|
| `$this->bootstrapApp($channel)` | App-Bootstrap fuer Nicht-Modul-Kommandos |
| `$this->bootstrapModuleApp()` | App-Bootstrap mit Modul-Error-Policy und Locking |
| `$this->requireBinScript('name.php')` | Laedt ein `bin/`-Script ohne fragile relative Pfade |
| `$this->projectRoot()` | Gibt den absoluten Projekt-Root-Pfad zurueck |
## Legacy-Scripts
Die alten `bin/*.php`-Scripts funktionieren weiterhin, geben aber einen Hinweis auf `bin/console` aus:
```
Hint: prefer `php bin/console module:sync` instead.
```

View File

@@ -25,7 +25,7 @@ Diese Readiness-Doku ist bewusst kurz und verweist fuer Felddefinitionen/Guards
- Tenant-Scope serverseitig pruefen.
- POST-Mutationen mit CSRF absichern.
4. **Runtime-Hygiene absichern**
- `php bin/module-runtime-sync.php` laeuft reproduzierbar mit standardisierter Step-Summary.
- `php bin/console module:sync` laeuft reproduzierbar mit standardisierter Step-Summary.
- Keine First-party CLI-Warnings/Notices/Deprecations; Vendor-Rauschen wird nur gezaehlt/reportet.
5. **Testbarkeit und Gates**
- Architektur- und Domain-Tests fuer neue Logik ergaenzen.

View File

@@ -63,5 +63,5 @@ Letzte Aktualisierung: 2026-03-24
- `docker compose exec php vendor/bin/phpunit`
- `docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress`
- bei Modul-/Manifest-Aenderungen: `docker compose exec php php bin/module-runtime-sync.php`
- bei Modul-/Manifest-Aenderungen: `docker compose exec php php bin/console module:sync`
- bei JS-Änderungen: Browser-Smoke mit DevTools-Console (keine JS-Errors)

View File

@@ -63,8 +63,8 @@ Der `ModuleAutoloader` registriert daraus den absoluten Pfad `modules/<id>/i18n/
```
- `key` und `description` sind Pflichtfelder.
- Runtime-Sync erfolgt ueber `php bin/module-permissions-sync.php`.
- `module-runtime-sync` fuehrt diesen Sync automatisch aus.
- Runtime-Sync erfolgt ueber `php bin/console module:sync`.
- `module:sync` fuehrt diesen Sync automatisch aus.
## `scheduler_jobs` Contract
@@ -120,9 +120,9 @@ Abgrenzung CSS:
`web/index.php` validiert bei jedem Request, dass der Runtime-Stand zur aktuellen Modul-Konfiguration passt.
- `bin/module-build.php` schreibt nach jedem Build `storage/runtime/.module-fingerprint` (sortierte Modul-IDs, kommasepariert).
- `php bin/console module:build` schreibt nach jedem Build `storage/runtime/.module-fingerprint` (sortierte Modul-IDs, kommasepariert).
- `web/index.php` vergleicht den Fingerprint mit der erwarteten Modul-Liste.
- Bei Mismatch: `RuntimeException` mit Hinweis auf `php bin/module-runtime-sync.php`.
- Bei Mismatch: `RuntimeException` mit Hinweis auf `php bin/console module:sync`.
- Kein Auto-Build im Request-Pfad — Build ist ausschliesslich CLI-Aufgabe.
Methoden: `ModuleRuntimePageBuilder::expectedFingerprint()`, `readFingerprint()`, `writeFingerprint()`.
@@ -138,12 +138,12 @@ API-Requests (`api/`-Prefix) ueberspringen den gesamten Web-Session-Flow:
## Standard-Runbook
`php bin/module-runtime-sync.php` fuehrt in fester Reihenfolge aus:
`php bin/console module:sync` fuehrt in fester Reihenfolge aus:
1. `module-migrate`
2. `module-permissions-sync`
3. `module-build`
4. `module-assets-sync`
1. `module:migrate`
2. `module:permissions-sync`
3. `module:build`
4. `module:assets-sync`
Der Output enthaelt eine deterministische Step-Summary (`migrate`, `permissions-sync`, `build`, `assets-sync`) inklusive `vendor_warnings_ignored=<n>`.
First-party Warnings/Notices/Deprecations gelten als Fehler (fail-fast).