From 93a1d95c076b51eedb11f176b9d582a3ea5c40fe Mon Sep 17 00:00:00 2001 From: fs Date: Thu, 19 Mar 2026 19:25:38 +0100 Subject: [PATCH] docs: add CLI command reference and update key docs to use bin/console New docs/reference-cli-commands.md covers all commands, bootstrap helpers, and how to add new commands. Updated lokale-entwicklung, entwickler-checkliste, betriebscheck-doctor, index, and web/index.php error message to reference bin/console instead of legacy bin/*.php scripts. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/howto-betriebscheck-doctor.md | 10 +- docs/howto-lokale-entwicklung.md | 6 +- docs/index.md | 11 +- docs/reference-cli-commands.md | 147 ++++++++++++++++++++++++ docs/reference-entwickler-checkliste.md | 6 +- web/index.php | 4 +- 6 files changed, 165 insertions(+), 19 deletions(-) create mode 100644 docs/reference-cli-commands.md diff --git a/docs/howto-betriebscheck-doctor.md b/docs/howto-betriebscheck-doctor.md index 41093b5..52a1282 100644 --- a/docs/howto-betriebscheck-doctor.md +++ b/docs/howto-betriebscheck-doctor.md @@ -1,10 +1,10 @@ -# Betriebscheck mit `bin/doctor.php` +# Betriebscheck mit `doctor` -Letzte Aktualisierung: 2026-03-06 +Letzte Aktualisierung: 2026-03-19 ## Ziel -`bin/doctor.php` ist der schnelle Gesundheitscheck fuer eine Instanz. +`php bin/console doctor` ist der schnelle Gesundheitscheck fuer eine Instanz. Er prueft unter anderem: @@ -21,13 +21,13 @@ Er prueft unter anderem: Lokal (wenn PHP + DB direkt erreichbar sind): ```bash -php bin/doctor.php +php bin/console doctor ``` Im Docker-Setup: ```bash -docker compose exec php sh -lc "php bin/doctor.php" +docker compose exec php php bin/console doctor ``` ## Exit-Code diff --git a/docs/howto-lokale-entwicklung.md b/docs/howto-lokale-entwicklung.md index e833886..c6d5c26 100644 --- a/docs/howto-lokale-entwicklung.md +++ b/docs/howto-lokale-entwicklung.md @@ -26,13 +26,15 @@ docker compose restart php nginx Nach Aenderungen an Modulen, Manifesten oder `APP_ENABLED_MODULES`: ```bash -docker compose exec php php bin/module-runtime-sync.php +docker compose exec php php bin/console module:sync ``` Dieser Befehl fuehrt automatisch aus: `migrate` → `permissions-sync` → `build` → `assets-sync`. 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`). + ## Schema-Stand - Basis-Schema + Seeds: `db/init/init.sql` @@ -57,7 +59,7 @@ docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress Bei Modul-/Manifest-Aenderungen zusaetzlich: ```bash -docker compose exec php php bin/module-runtime-sync.php +docker compose exec php php bin/console module:sync ``` Bei JS-Änderungen zusätzlich Browser-Smoke mit DevTools-Console (keine JS-Errors). diff --git a/docs/index.md b/docs/index.md index ccd51e8..d5bde34 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,7 +50,7 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: - `/docs/howto-docker-produktiv.md` - Produktivbetrieb mit Docker. - `/docs/howto-betriebscheck-doctor.md` - - Schneller Systemcheck mit `bin/doctor.php`. + - Schneller Systemcheck mit `php bin/console doctor`. - `/docs/howto-fehlerbehebung.md` - Haeufige Fehler und schnelle Loesungen. - `/docs/howto-lokale-entwicklung.md` @@ -97,11 +97,8 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert: - Standard-Prompts fuer Skill-basierte Planung und Implementierung. - `/docs/reference-extension-readiness.md` - Freigabe-Checkliste fuer weitere Module auf Basis des bestehenden Modul-Contracts. +- `/docs/reference-cli-commands.md` + - Alle CLI-Kommandos (`php bin/console`), Bootstrap-Helfer, Anleitung neue Kommandos. - `/docs/reference-module-manifest-contract.md` - Verbindlicher Runtime- und Manifest-Contract fuer Module (V1.1). -- `/docs/reference-agents-overview.md` - - Einstieg in das Rollenmodell und die Artefakte. -- `/docs/reference-agents-roles.md` - - Klare Verantwortung je Rolle (Planner, Executor, Reviewer, Finalizer). -- `/docs/reference-agents-flow.md` - - State-Flow mit Fail-Loop zur Executor-Iteration. +- Agent-Workflow (Rollen, State-Machine, Contracts): siehe `/.agents/workflow.md` diff --git a/docs/reference-cli-commands.md b/docs/reference-cli-commands.md new file mode 100644 index 0000000..8630f82 --- /dev/null +++ b/docs/reference-cli-commands.md @@ -0,0 +1,147 @@ +# CLI-Kommandoreferenz + +Letzte Aktualisierung: 2026-03-19 + +## Einstiegspunkt + +Alle CLI-Kommandos laufen ueber einen einzigen Einstiegspunkt: + +```bash +php bin/console [argumente] [optionen] +``` + +Uebersicht aller verfuegbaren Kommandos: + +```bash +php bin/console list +``` + +Hilfe zu einem einzelnen Kommando: + +```bash +php bin/console --help +``` + +## Kommandos + +### module:sync + +Fuehrt den vollstaendigen Modul-Runtime-Sync aus: `migrate` → `permissions-sync` → `build` → `assets-sync`. + +```bash +docker compose exec php php bin/console module:sync +``` + +Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES`. + +Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist dieser Befehl die Loesung. + +### module:migrate + +Wendet ausstehende SQL-Migrationen aus aktiven Modulen an. + +```bash +docker compose exec php php bin/console module:migrate +``` + +### module:permissions-sync + +Synchronisiert Modul-Permissions in die DB. Deaktiviert verwaiste System-Permissions (`is_system=1`), die kein aktives Modul mehr beansprucht. + +```bash +docker compose exec php php bin/console module:permissions-sync +``` + +### module:build + +Baut die Runtime-Seitenstruktur (`storage/runtime/pages/`) mit Symlinks zu Modul-Pages. + +```bash +docker compose exec php php bin/console module:build +``` + +### module:assets-sync + +Publiziert Modul-Assets nach `web/modules//`. + +```bash +docker compose exec php php bin/console module:assets-sync +``` + +### module:deactivate + +Fuehrt den optionalen Deactivation-Handler eines Moduls aus. + +```bash +docker compose exec php php bin/console module:deactivate --confirm +docker compose exec php php bin/console module:deactivate --dry-run +``` + +Das Modul muss nicht in der Aktivliste stehen. `--dry-run` validiert den Handler ohne Ausfuehrung. + +### scheduler:run + +Fuehrt faellige Scheduler-Jobs aus. + +```bash +docker compose exec php php bin/console scheduler:run +``` + +Der Docker-Scheduler-Service ruft dieses Kommando automatisch alle 60 Sekunden auf. + +### doctor + +Fuehrt System-Gesundheitschecks aus (ENV, DB, RBAC, Scheduler-Heartbeat). + +```bash +docker compose exec php php bin/console doctor +``` + +Siehe `/docs/howto-betriebscheck-doctor.md` fuer Details. + +## Neue Kommandos anlegen + +1. Klasse in `lib/Console/Commands/` erstellen, die `MintyPHP\Console\Command` erweitert. +2. `name()`, `description()` und `execute()` implementieren. +3. Optional: `usage()` fuer `--help`-Ausgabe ueberschreiben. + +Das Kommando wird automatisch erkannt — kein manuelles Registrieren noetig. + +Beispiel: + +```php +namespace MintyPHP\Console\Commands\Make; + +use MintyPHP\Console\Command; + +final class ModuleCommand extends Command +{ + public function name(): string { return 'make:module'; } + public function description(): string { return 'Scaffold a new module'; } + + public function execute(array $args, array $options): int + { + // ... + return 0; + } +} +``` + +## Bootstrap-Helfer + +Die `Command`-Basisklasse stellt Helfer bereit: + +| Methode | Zweck | +|---|---| +| `$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. +``` diff --git a/docs/reference-entwickler-checkliste.md b/docs/reference-entwickler-checkliste.md index 5b19435..71d5c1a 100644 --- a/docs/reference-entwickler-checkliste.md +++ b/docs/reference-entwickler-checkliste.md @@ -71,12 +71,12 @@ Kurze Definition of Done vor Merge. - [ ] `docker compose exec php vendor/bin/phpunit` zweimal hintereinander in identischer Umgebung (beide Runs gruen) - [ ] `docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress` - [ ] `docker compose exec php vendor/bin/phpunit tests/Architecture/CoreStarterkitContractTest.php` -- [ ] bei Modul-/Manifest-/Routen-Aenderungen: `APP_ENABLED_MODULES='' php bin/module-runtime-sync.php` -- [ ] bei Modul-/Manifest-/Routen-Aenderungen: `APP_ENABLED_MODULES='addressbook,bookmarks' php bin/module-runtime-sync.php` +- [ ] bei Modul-/Manifest-/Routen-Aenderungen: `APP_ENABLED_MODULES='' php bin/console module:sync` +- [ ] bei Modul-/Manifest-/Routen-Aenderungen: `APP_ENABLED_MODULES='addressbook,bookmarks' php bin/console module:sync` - [ ] Runtime-Sync erzeugt Step-Summary (`migrate`, `permissions-sync`, `build`, `assets-sync`) und `vendor_warnings_ignored=` - [ ] Keine First-party CLI-Warnings/Notices/Deprecations im Runtime-Sync (Vendor-Warnings sind nur temporaer toleriert und muessen gezaehlt sichtbar sein) - [ ] bei Docs-/Skills-Aenderungen: `docker compose exec php vendor/bin/phpunit tests/Architecture/CodexSkillsContractTest.php` -- [ ] bei Docs-/Skills-Aenderungen: `bin/docs-link-check.sh` (scannt standardmaessig ohne `agent-system/runs/**`) +- [ ] bei Docs-/Skills-Aenderungen: `bin/docs-link-check.sh` (scannt standardmaessig ohne `.agents/runs/**`) - [ ] bei Docs-/Skills-Aenderungen: `bin/codex-skills-sync.sh --check` - [ ] bei JS-Änderungen: Browser-Smoke mit DevTools-Console (keine JS-Errors) - [ ] bei API-Änderungen: `docs/openapi.yaml` aktualisiert diff --git a/web/index.php b/web/index.php index 679a234..78ff647 100644 --- a/web/index.php +++ b/web/index.php @@ -32,7 +32,7 @@ setAppContainer($container); // ── 2. Module runtime validation ──────────────────────────────────── // Fail-fast if the runtime page root is stale (modules changed without // running module-runtime-sync). No auto-build in the request path — -// that is the responsibility of bin/module-runtime-sync.php. +// that is the responsibility of `php bin/console module:sync`. $moduleRegistry = app(ModuleRegistry::class); $runtimePageRoot = __DIR__ . '/../storage/runtime/pages'; @@ -44,7 +44,7 @@ if (count($activeModules) > 0 || is_dir($runtimePageRoot) || is_link($runtimePag if ($expectedFingerprint !== $actualFingerprint) { throw new RuntimeException( "Module runtime is stale (expected: '{$expectedFingerprint}', actual: '{$actualFingerprint}'). " - . 'Run: php bin/module-runtime-sync.php' + . 'Run: php bin/console module:sync' ); } if (is_dir($runtimePageRoot) || is_link($runtimePageRoot)) {