govoplan/docs/operations/WEBUI_RELEASE_DEPENDENCY_RETRIES.md

WebUI release dependency installer retries

English

This operational note covers install-webui-release-dependencies.sh and the exit-status repair tracked in Meta #54. It applies to release administrators using the legacy runtime WebUI installer; there are no new application settings, permissions, or end-user workflows.

Each retried npm install or Git clone has at most three attempts. The installer waits 10 seconds after the first failure and 20 seconds after the second, and continues immediately after success. If all attempts fail, it exits with the last command's nonzero status. Its set -e execution stops before subsequent installation stages; callers using set -e also stop before subsequent work. Previously, the retry helper could report success after three failures because it captured the status of a completed if statement instead of the command.

On exhaustion, inspect the npm or Git error and correct the reported cause before rerunning the installation. The temporary dependency workspace is removed on exit. Earlier changes to package.json, removal of package-lock.json, cache cleaning, and completed dependency installations are not rolled back; prepare a fresh disposable release workspace when a clean retry is required.

The repair preserves the existing retry count, backoff, cache behavior, and peer-resolution flags. It does not lift the runtime publication hold tracked in Meta #52. Review the historical --legacy-peer-deps workaround separately before lifting that hold. Strict disposable Git-release and signed catalog verification do not use this installer; strict release verification must not bypass peer checks. See Package Registry Releases for release context.

Run the isolated regression suite from the meta repository:

python3 -m unittest -v tests.test_webui_release_dependency_retries

The suite executes the actual Bash installer and a caller using set -e, with local npm, Git, Node, and sleep stubs. It covers success on attempts one, two, and three, final failure status, backoff, and termination at each retry call site. It performs no network access, real waiting, or changes to the real npm cache. It checks shell control flow, not package resolution or runtime publication.

Deutsch

Dieser Betriebshinweis beschreibt install-webui-release-dependencies.sh und die unter Meta #54 erfasste Korrektur des Rückgabestatus. Er richtet sich an Release-Administratoren, die den bisherigen WebUI-Installer für Laufzeit-Releases verwenden. Neue Anwendungseinstellungen, Berechtigungen oder Endanwenderabläufe entstehen nicht.

Jede wiederholte npm-Installation und jeder Git-Klon erhält höchstens drei Versuche. Nach dem ersten Fehlschlag wartet der Installer 10 Sekunden, nach dem zweiten 20 Sekunden; nach einem Erfolg fährt er sofort fort. Scheitern alle Versuche, endet er mit dem letzten von null verschiedenen Rückgabestatus. Durch set -e werden nachfolgende Installationsschritte nicht ausgeführt; auch aufrufende Skripte mit set -e brechen vor ihren nächsten Schritten ab. Bisher konnte die Hilfsfunktion nach drei Fehlschlägen Erfolg melden, weil sie den Status der abgeschlossenen if-Anweisung statt des Befehls übernahm.

Prüfen Sie nach dem Abbruch die npm- oder Git-Fehlermeldung und beheben Sie deren Ursache vor einem erneuten Installationslauf. Das temporäre Verzeichnis für Abhängigkeiten wird beim Beenden entfernt. Vorherige Änderungen an package.json, das Entfernen von package-lock.json, die Cache-Bereinigung und abgeschlossene Installationen werden nicht zurückgerollt. Bereiten Sie bei Bedarf einen neuen temporären Release-Arbeitsbereich für einen sauberen Wiederholungslauf vor.

Die Korrektur erhält Anzahl und Wartezeiten der Versuche, Cache-Verhalten und Optionen zur Peer-Auflösung. Die Sperre für Laufzeitveröffentlichungen aus Meta #52 bleibt bestehen. Der bisherige Einsatz von --legacy-peer-deps muss vor ihrer Aufhebung gesondert geprüft werden. Die strenge Git-Release-Prüfung in einem temporären Arbeitsbereich und die Prüfung signierter Kataloge verwenden diesen Installer nicht; die strenge Release-Prüfung darf Peer-Prüfungen nicht umgehen. Weitere Zusammenhänge erläutert Package Registry Releases.

Führen Sie die isolierten Regressionstests im Meta-Repository aus:

python3 -m unittest -v tests.test_webui_release_dependency_retries

Die Tests führen den tatsächlichen Bash-Installer und ein aufrufendes Skript mit set -e aus. Lokale Testprogramme ersetzen npm, Git, Node und sleep. Geprüft werden Erfolge im ersten, zweiten und dritten Versuch, der letzte Fehlerstatus, Warteintervalle und der Abbruch an jeder Aufrufstelle. Es gibt keine Netzwerkzugriffe, echten Wartezeiten oder Änderungen am tatsächlichen npm-Cache. Die Tests prüfen den Shell-Ablauf, nicht die Paketauflösung oder Veröffentlichung.