TerminalBasic/openspec/changes/phase-6-06-gitea-actions-und-releases/design.md

Context

Origin ist https://git.rfc1437.de/hugo/TerminalBasic.git; die read-only Versionsabfrage liefert Gitea 1.25.4. Die vorhandenen Actions-Workflows werden auf Release-Tags beschränkt. Der bestehende Runner wurde am 2026-09-07 per read-only SSH als Linux aarch64 mit laufendem Gitea-Runner-Container bestätigt. Andere Projekte am Origin verwenden bereits linux-arm64 mit cargo-zigbuild und cargo-xwin. Das tatsächliche Label, Toolchain-/SDK-Versionen und der Release-Zugang werden bei der Anbindung dieses Projekts geprüft; Lauf 5 hat die vollständige TerminalBasic-Cross-Matrix nachgewiesen. Der Benutzer verlangt ausschließlich Gitea Actions am Origin und vier native Terminalziele.

Goals / Non-Goals

Goals: In Actions erzeugte, geprüfte und vollständig paketierte Zielartefakte; nachvollziehbare Gitea-Releases.

Non-Goals: Repository-Mirror, zweite CI-Plattform, Installer-/GUI-Produkt, reine Cross-Compile-Ergebnisse als native Abnahme.

Decisions

1. .gitea/workflows/ nutzt den vorhandenen Linux-arm64-Runner für alle vier Build-/Paketziele. Vorhandene Workflowmuster der anderen Origin-Projekte wiederverwenden: cargo-zigbuild für Linux amd64 und macOS arm64, cargo-xwin für Windows amd64/MSVC; Linux arm64 nativ oder mit derselben festgelegten Linux-Zielbaseline. Container/Tools und benötigte SDKs/Sysroots reproduzierbar pinnen; konkrete Rust-/OS-/glibc-Versionen mit TerminalBasic prüfen. Das Runnerlabel linux-arm64 bei Anbindung bestätigen. Vier native Buildrunner sind nicht erforderlich. build-runtime.py erzeugt Vorlagenmetadaten mit dem Hostwerkzeug für das jeweilige Target; fremde Executables werden auf dem Buildhost nicht nativ ausgeführt.
2. Wiederverwendbare Repository-Skripte erledigen Build, Tests, Paketierung und Prüfung auch lokal. Source-Checkout vom Gitea-Origin, alle zusätzlichen Actions nur über explizite Gitea-URLs und feste Revisionen, soweit überhaupt nötig; keine implizite fremde Action-Auflösung. Rust und benötigte Systemwerkzeuge versioniert bereitstellen. Server-/Runner-Kompatibilität praktisch prüfen, statt lediglich YAML zu validieren.
3. Matrixprodukte: terminalbasic-<version>-windows-amd64.7z, terminalbasic-<version>-macos-arm64.tar.gz, terminalbasic-<version>-linux-amd64.tar.gz, terminalbasic-<version>-linux-arm64.tar.gz. Windows enthält tb.exe/tbc.exe/tbrt.exe, übrige tb/tbc/tbrt; tbrt ist die native Exportvorlage unter runtimes/<Target-Triple>/, dazu deren Metadaten, Lizenz, Kurzinstallation. Das vorhandene CLI-/IDE-Suchschema bleibt erhalten. Archive dürfen keine Buildverzeichnis-/Quellbaumabhängigkeiten haben. Exportierte Anwenderprogramme bleiben normale native Einzelartefakte; die Archivformate betreffen die Distribution.
4. Der Linux-Buildhost erzeugt/prüft Windows-Archive mit 7-Zip und Unix-Archive mit tar+gzip unter Erhalt der Executable-Bits. Inhalts-/Formatprüfungen laufen dort; tatsächliche Start-/Exportprüfungen verwenden neu entpackte Pakete auf passenden Zielsystemen aus 05, automatisiert oder dokumentiert manuell. Externe Nachweise müssen an Revision und exakte Paketprüfsumme gebunden und vor Freigabe geprüft sein. Ein gemeinsames TBL-Testartefakt wird einmal erzeugt und mit nachgewiesen identischen Bytes auf allen vier Zielsystemen verwendet. Separate BASIC-Verbraucher werden mit den entpackten TB-Tools verknüpft, als TBC ausgeführt und mit tbrt als EXE exportiert. Library-Quellen sind dabei nicht verfügbar. Erzeugung/Linken werden in einer Umgebung ohne erreichbaren C-/Rust-Compiler oder nativen Linker geprüft; Systemhilfen zur EXE-Finalisierung dürfen verfügbar bleiben. Fertige EXEs laufen anschließend ohne externe TBL/TBC oder TB-Installation.
5. cargo test --locked --workspace, Clippy und Formatprüfung zentral auf dem Linux-arm64-Host; zielabhängige Rust-Testprogramme bei Bedarf cross-kompilieren und auf passenden Prüfsystemen ausführen. Native Tests aus 02/03/04 und automatisierbare Plattformtests aus 05 auf ihren tatsächlichen Zielen ausführen. Buildstatus und Ausführungsnachweise getrennt ausweisen; macOS-EXE-Finalisierung mit codesign erfolgt auf macOS. Den fixierten Fremdprogrammbestand ausdrücklich im erforderlichen Abnahmelauf bereitstellen. Compile-/VM-Messungen auf dokumentiertem Referenzrunner statt instabiler Debug-Zeitlimits in allen Jobs.
6. Gitea-Release erst nach allen Pflichtjobs, zugeordneten echten Zielnachweisen und Vollständigkeits-/Prüfsummenprüfung freigeben. Upload zunächst zu einem als Entwurf erkennbaren Release oder gleichwertigem nicht freigegebenen Staging; anschließend atomare Freigabe im Rahmen der verfügbaren API. Keine Commit-/PR-Jobs. Der Release-Upload nutzt den repositorygebundenen Gitea-Jobtoken; ein explizites TB_RELEASE_TOKEN-Secret kann ihn bei Bedarf ersetzen. Keine persönlichen Zugangswerte werden committed. Tests erzeugen keine öffentlichen Testreleases.
7. README-/PLAN-/Releasehinweise nennen die tatsächlich gemessenen minimalen OS-/Systembibliotheksversionen. Developer-ID-/öffentliche Vertrauenssignatur ist kein Ersatz für lokale Ausführbarkeit; wenn entsprechende Identitäten nicht konfiguriert sind, deren Download-/Vertrauensgrenzen ehrlich dokumentieren. Mac-Artefakte müssen trotzdem lokal korrekt finalisiert und startbar sein.

Risks / Trade-offs

• Cross-Toolchain/SDK fehlt oder ist inkompatibel → Buildbootstrap korrigieren und echte Vierzielpakete nachweisen. Fehlende Zielausführung auf Prüfsystemen sperrt weiterhin Abschluss/Release; erfolgreiche Cross-Builds allein reichen nicht.
• Vorlagen passen nicht zum Tool → Manifest-/Prüfsummen-/Versionscheck und Export aus entpacktem Paket.
• Plattformwerkzeuge variieren → Buildhost prüft Archiv-/Cross-Werkzeuge, Prüfsysteme prüfen benötigte Signierwerkzeuge; keine stillen Ersatzformate.
• Fehler beim Upload → vollständige Pflichtasset-Liste vor Freigabe prüfen; bestehende vollständige Releases nicht beschädigen.

Migration Plan

Lokale Skripte zuerst lauffähig machen, dann Gitea-Runner und Workflows anbinden. Nur neue Tags im Format vX.Y.Z starten Build, Pflichtabnahme und Paketupload; keine Branch-/PR- oder manuellen Buildtrigger. Der Prüfjob lehnt ungültige Tags und Abweichungen von Cargo.toml vor dem Cargo-Build ab; die Zielmatrix hängt von diesem Job ab. Bisherige lokale Cargo-Nutzung erhalten. Rollback über vorheriges vollständiges Release und Rücknahme der Workflowänderung; keine Server-/Runnerinstallation durch bloße Proposal-Erstellung.

Konkretisierung während der Umsetzung

• Rust 1.97.1, vorhandene Cross-Images per Digest, 7-Zip 25.01 und Node.js 22.22.0 per SHA-256. Node wird vor checkout bereitgestellt, da die Cross-Images keine JavaScript-Actions-Laufzeit enthalten. SDK-/CRT-Versionen und ein Hash ihrer exakten Header-/Library-Bytes sind für Windows fixiert; macOS-SDK/Zig stammen aus dem gepinnten Image.
• tb-template --inspect nutzt den vorhandenen PE/ELF/Mach-O-Parser auch für tb/tbc. Build und Paketprüfung laufen auf dem Host ohne fremde Programme auszuführen. Die Anwenderpakete benötigen tb-template nicht.
• Taglauf erzeugt erst nach Build/Grundabnahme einen überprüften Entwurf. v1.0.0 bezeichnet die erste Releaseversion. Normale Commits/PRs erzeugen keine Jobs oder Artefakte; lokale Entwicklungsprüfungen bleiben verfügbar. Originalpakete werden auf separaten Systemen geprüft. Ein manueller Workflow auf main bindet deren Nachweise aus einem Origin-Commit an Tag, Revision und Paket-SHA-256 und gibt erst dann denselben Entwurf frei; kein erneuter Bau.
• Die Benutzerentscheidung aus 05, Windows-Ausführung vorerst offen zu lassen, bleibt erhalten. Sie macht Windows-Builds zulässig, aber keinen Release mit fehlender Windows-Abnahme erfolgreich. Fehlende Nachweise werden nicht auf Basis der gemeinsamen ANSI-Technik von macOS/Linux pauschal abgehakt.