TerminalBasic/docs/distribution.md

# Gitea-Build und Distribution

Change 06 baut ausschließlich am Origin `git.rfc1437.de/hugo/TerminalBasic`.
Die Actions verwenden das bestätigte Label `linux-arm64` und vier Zieltriple.
Build, Pflichtabnahme und Artefaktuploads starten ausschließlich bei neuen
Release-Tags `vX.Y.Z`, erstmals `v1.0.0`. Normale Commits und PRs starten
keine CI. Tagformat und Übereinstimmung mit der Workspace-Version werden
vor dem Cargo-Build geprüft; ein manueller Paketbuild ist nicht vorgesehen.
Kein Cross-Build ist ein Windows-/macOS-/Linux-Emulatornachweis.

## Buildumgebung

| Ziel | Builder | Fixierte Baseline |
|---|---|---|
| Windows amd64 | cargo-xwin 0.23.0 | VS-Kanal 17 mit festen SDK-/CRT-Versionen: SDK 10.0.26100, CRT 14.44.17.14; statische CRT |
| macOS arm64 | cargo-zigbuild 0.23.0, Zig 0.16.0 | enthaltenes MacOSX11.3.sdk; Deployment Target 11.0 |
| Linux amd64/arm64 | cargo-zigbuild 0.23.0, Zig 0.16.0 | glibc 2.28 |

Rust 1.97.1 ist in `rust-toolchain.toml` fixiert. Die Images stehen mit Digest
in `.gitea/workflows/build.yml`; SDK/Clang/Zig stammen aus diesen Images.
7-Zip 25.01 wird mit fester SHA-256 in `bootstrap.sh` bereitgestellt.
Vor dem Checkout installieren beide Workflows Node.js 22.22.0 mit fester
SHA-256: Die Cross-Images enthalten keine Laufzeit für JavaScript-Actions.
Zusätzlich prüft der Windows-Build einen festen Hash aller SDK-/CRT-Dateien
und Symlinks. Änderungen unter derselben Microsoft-Versionsbezeichnung
werden damit abgelehnt; der Pin muss dann ausdrücklich aktualisiert werden.
Die Tabelle nennt Buildvorgaben, keine gemessenen minimalen OS-Versionen.
Die tatsächliche Cross-Matrix und OS-Läufe sind im Changebericht auszuweisen.

Der Builder erfordert Linux aarch64. Zwei Cargo-Buildjobs und eine sequenzielle
Zielmatrix begrenzen die Last. Host-`tb-template` prüft über denselben Parser
wie der Exportdienst PE32+/amd64/Console, Mach-O/arm64 oder ELF/Linux/64-Bit;
fremde Executables werden beim Paketieren nicht ausgeführt.

Lokaler Aufruf innerhalb des betreffenden gepinnten Containers:

```sh
sh .gitea/scripts/bootstrap.sh
python3 .gitea/scripts/build.py --target x86_64-pc-windows-msvc --output dist
```

Eigene native Testpakete lassen sich mit `distribution.py pack --bin-dir ...
--target ... --output ... --inspector .../tb-template` erstellen. Uncommittete
Quellen bleiben in `manifest.json` markiert und sind nicht freigabefähig.

## Origin-Konfiguration und Rechte

Actions sind am Repository aktiviert. Der gemeinsame Runner heißt
`gitea-arm64-01`. Der Benutzer hat seinen Neustartfehler behoben; die
Repository-Workflows ändern keine globale Docker-/AppArmor-Konfiguration.

Erforderliche Konfiguration:

- Variable `TB_VBDOS_REPOSITORY`: erreichbarer Git-Bestand des in
  `foreign.rs` fixierten Referenzprojekts. Der Checkout muss exakt
  `1cdd2b32b829fe1721d0b6aecc433abc47a96fb6` liefern. Fehlende Konfiguration
  lässt den Pflichtjob scheitern; Fremdprogramme werden nicht übersprungen.
- Releasezugriff: standardmäßig der eingebaute repositorygebundene
  `gitea.token`, optional ein explizites Secret `TB_RELEASE_TOKEN`.
  Nur Upload/Freigabe verwenden ihn für Releasezugriffe; der Checkout
  speichert keine Credentials. Die tatsächliche Uploadberechtigung wird
  im Taglauf geprüft. Gitea 1.25 ignoriert die deklarativen `permissions`-
  Angaben; diese allein sind kein Nachweis getrennter Jobrechte.
  Siehe [Gitea-1.25-Kompatibilität](https://docs.gitea.com/1.25/usage/actions/comparison/).
- Keine Branch-/PR-Trigger und kein manueller Buildtrigger. Der manuelle
  Freigabeworkflow verarbeitet nur vorhandene taggebundene Originalpakete.

Die Actions-URLs sind explizite Gitea-URLs mit festen Commit-IDs.
[Absolute Action-URLs](https://docs.gitea.com/usage/actions/comparison/)
und [Runnerlabels](https://docs.gitea.com/runner/) entsprechen dem Gitea-Modell.

## Pakete und Zielprüfungen

`terminalbasic-<version>-windows-amd64.7z` sowie `...-macos-arm64.tar.gz`,
`...-linux-amd64.tar.gz`, `...-linux-arm64.tar.gz` enthalten `tb`/`tbc` im Hauptverzeichnis und
`runtimes/<Target-Triple>/tbrt` samt `tbrt.meta` (Windows jeweils `.exe`
bzw. `tbrt.exe.meta`),
`LICENSE`, `INSTALL.txt` und `manifest.json`. Unix-Executables besitzen 0755.
Das Manifest bindet Version, Revision, Rust, Buildhost/Image, Target und
SHA-256 jeder Datei. Jedes Paket erhält zusätzlich eine `.sha256`-Datei.

Auf dem passenden Prüfsystem das unveränderte Paket herunterladen und ausführen:

```sh
python3 .gitea/scripts/distribution.py target-check \
  --archive /pakete/terminalbasic-1.0.0-macos-arm64.tar.gz \
  --target aarch64-apple-darwin --output /nachweise/aarch64-apple-darwin
```

Das Prüfsystem braucht Python und den Prüfharness dieser Revision; die
Produkte selbst laufen aus einem neu entpackten temporären Verzeichnis.
Native-/TBL-Prüfungen verwenden einen leeren PATH, separate Verbraucher,
keine Library-Quellen und die vorhandenen paketierten Metadaten. Auf macOS
bleibt `/usr/bin/codesign` als Systemhilfe zulässig. Erzeugte Executables
laufen nach Entfernen von Quellen, TBL/TBC und Vorlagen weiter.
Die gemeinsame `portable.tbl` wird auf allen Zielen unverändert verwendet,
SHA-256 `5d25c2f8c95ae535e55a6c84c1ddd0d964358863f4f3c780c50ac4a2eb3594df`.

Windows erfordert zusätzlich `--windows-console-test <tb-ui-Testexecutable>`
derselben Revision. Dieses Testexecutable kann der Linux-Builder mit
`cargo xwin test --locked --target x86_64-pc-windows-msvc -p tb-ui
--features terminal --no-run` erzeugen; es gehört zum Prüfharness, nicht zum
Anwenderpaket. DOSBox kann diese Windows-PE-Programme nicht ausführen.
Windows bleibt auf Benutzerentscheidung vorerst offen.

Der automatisch erzeugte `report.json` lässt die manuelle Terminalabnahme
offen. Die Bedienfolge steht in `docs/plattformmatrix.md`. Je Target sind
zusätzlich `manual.json` und die referenzierten nichtleeren Belegdateien nötig:

```json
{
  "target": "aarch64-apple-darwin",
  "revision": "<40-stellige Revision>",
  "package_sha256": "<SHA-256 des Originalpakets>",
  "passed": true,
  "tester": "<Prüfer>",
  "terminal_versions": {"terminal.app": "<gemessene Version>"},
  "cases": {"f1_f12": true, "modifiers": true, "mouse": true,
    "unicode_colors": true, "resize": true, "input_break": true, "shell": true},
  "evidence": ["terminal-protokoll.txt"]
}
```

Windows verlangt `windows-terminal`, beide Linux-Ziele jeweils `xterm` und
`vte` mit Versionen. Nur tatsächlich bestandene Schritte auf true setzen.
Die Felder dienen einer verantworteten manuellen Bestätigung; sie ersetzen
keine Durchführung. Herkunft wird über den geprüften Origin-Commit gebunden.

## Entwurf und Veröffentlichung

Ein Push eines neuen passenden Tags `vX.Y.Z` (beispielsweise `v1.0.0`) baut/testet alle vier Ziele und lädt
erst danach neun Assets in einen Gitea-Entwurf: vier Pakete, vier SHA-Dateien,
`acceptance.json`. Dessen Referenzlauf enthält Fremdprogramme, Inventar,
Workspace/Clippy/Format, Compile-/VM-Benchmarks und die ausdrücklich gestartete
native IDE-Abnahme. Golden-Erzeugung bleibt bewusst ignoriert. Echte native
Paket-/Terminalprüfungen sind eine zusätzliche Freigabebedingung.

Nachweise auf separaten Systemen beziehen sich auf diese Originalpakete.
Unter `release-evidence/v<version>/<target>/` werden `report.json`, Logs,
`manual.json` und dessen Belege in einem Origin-Commit bereitgestellt.
Der manuell auf main gestartete Workflow „Geprüften Gitea-Entwurf freigeben“
erhält Tag und vollständige Nachweisrevision. Er lädt die ursprünglichen
Entwurfsassets, prüft vier exakte Paketbindungen, Ziel-/Terminalresultate,
gemeinsame TBL-Prüfsumme und die Grundabnahme aus dem ursprünglichen Taglauf.
Er baut die Pakete dabei nicht erneut. Fehlende oder abweichende Daten sperren
Freigabe. Der Tag muss zur Paketversion und zur geprüften Revision passen.

Uploads werden zurückgelesen und bytegenau geprüft. Wiederholungen ergänzen
nur fehlende identische Assets eines Entwurfs. Abweichende Assets oder ein
bereits veröffentlichter Release werden nicht überschrieben. Erst der letzte
API-Aufruf ändert `draft` auf false. Die Regressionen simulieren insbesondere
fehlende Uploads, falsche Nachweise, korrupte Pakete und bestehende Releases;
sie erzeugen keine öffentlichen Testreleases.