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 prüft Archivinhalt, PE/ELF/Mach-O-Format, Architektur, Version, Metadaten, Executable-Rechte und SHA-256. Echte Ziel-/Terminalprüfungen gehören zur Entwicklung vor dem Release-Tag; die vorhandenen lokalen Werkzeuge bleiben verfügbar. Cross-Builds werden nicht als echte Zielausführung ausgegeben. Ein Nachweis-Commit ist nicht erforderlich.
5. Der Tag ist die Freigabeentscheidung des Benutzers nach dessen Tests. Der Release-Workflow startet keine erneute Pflichtabnahme, Fremdprogramm-, Inventar-, Benchmark- oder Terminalnachweisprüfung. Die bestehenden Cargo- und lokalen Abnahmeskripte bleiben unabhängig vom Release verwendbar.
6. Nach erfolgreichen vier Buildjobs lädt derselbe Workflow vier Archive und vier SHA-256-Dateien hoch. Während des Uploads bleibt der Release ein Entwurf; nach vollständiger API-Dateiliste und passenden Größen wird er sofort veröffentlicht. Kein manueller Publish-Workflow, Nachweis-Gate oder Release-Asset-Download. Wiederholungen ergänzen fehlende Dateien, ersetzen aber keine vorhandenen Assets oder veröffentlichten Releases. Der repositorygebundene Jobtoken genügt; TB_RELEASE_TOKEN bleibt optional. Tests erzeugen keine öffentlichen Releases.
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. Zielausführung bleibt eine getrennte Entwicklungsprüfung und keine automatisierte Releasebedingung.
• 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, Paketupload und direkte Veröffentlichung; 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.
• Benutzerentscheidung 11.09.2026: Das Tag bestätigt die vorherigen Tests. Nach erfolgreichem Vierzielbau werden acht Pflichtassets hochgeladen und im selben Workflow direkt veröffentlicht. Normale Commits/PRs erzeugen keine Jobs oder Artefakte; lokale Entwicklungsprüfungen bleiben verfügbar.
• Alle manuellen Freigabe- und Nachweiswege aus dem Releasepfad entfallen. Die Uploadkontrolle verwendet ausschließlich API-Dateiliste und Größen, nachdem lokale Archiv-/Revisions-/Prüfsummenprüfungen bestanden sind.
• Zurückgestellte Linux-/Windows-Ausführung und vollständige Terminalfolgen bleiben spätere Entwicklungsarbeit in 07, ohne den Release zu blockieren.