Plan Phase 6 runtime, P-code libraries and Gitea releases

openspec/changes/phase-6-02-native-executables/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-07

openspec/changes/phase-6-02-native-executables/design.md

@@ -0,0 +1,29 @@
+## Context
+
+`cmd_build` schreibt momentan nur `.tbc`; `cmd_run`/`run_chain` besitzen CLI-Exitcodes, Terminal-/PipeHost, Forms-Fortsetzung und RUN-Auflösung. `project_io::new_execution` ist bereits gemeinsam. TBC steht aktuell auf Version 4 und trägt die benötigten Projekt-/Forms-/Quellortdaten. Der Plan fordert ausdrücklich einen vorkompilierten Runner statt Cargo beim Anwender.
+
+## Goals / Non-Goals
+
+**Goals:** Wiederverwendbarer nativer Export ohne Compilerinstallation beim Anwender, einheitliche Ausführung und prüfbare Zielartefakte.
+
+**Non-Goals:** JIT/LLVM, Maschinenübersetzung jeder BASIC-Anweisung, Quellcompiler-Neuschreibung, vollständige Cross-Toolchain beim Anwender, Einbettung beliebiger zur Laufzeit per RUN/OPEN/SHELL referenzierter externer Ressourcen.
+
+## Decisions
+
+1. Bestehende CLI-Ausführung in einen nutzbaren gemeinsamen Runnerpfad überführen; CLI und das kleine vorgebaute Executable `tbrt` verwenden dieselbe VM-/Host-/Forms-/RUN-/Drucklogik. `tbrt` enthält nativ kompilierte VM/Runtime samt Terminal-/Forms-Unterstützung, ohne IDE oder BASIC-Quellcompiler. Eine Vorlage ohne Nutzlast meldet kontrolliert das fehlende Programm und ist kein erfolgreicher Anwenderprogrammstart. Der Runner lädt beim ersten Start und bei RUN ohne Namen sein eingebettetes Kompilat, statt sein Executable als BAS zu kompilieren. Benannte RUN-Ziele behalten die dokumentierte externe Auflösung; diese Abhängigkeiten werden nicht als automatisch eingebettet beworben.
+2. Einen kleinen gemeinsamen Exportbereich unterhalb von CLI/IDE einführen (beispielsweise eigene `tb-export`-Crate), weil CLI, Library und IDE denselben Ziel-/Vorlagen-/Publikationsvertrag benötigen. Er erhält für EXE den vollständig verknüpften Projektstand, das Target und den Zielpfad; er hängt nicht von IDE-Dokumenttypen ab. Die IDE adaptiert ihren Revisionsstempel in 04. Kein Hintergrunddienst oder globaler Paketmanager.
+3. Zielmatrix: `x86_64-pc-windows-msvc`, `aarch64-apple-darwin`, `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`. amd64/arm64 sind Anzeigenamen für x86_64/aarch64. Linux-Systembibliotheksbasis wird mit dem tatsächlichen Builder-Image dokumentiert; Standalone bedeutet eingebettete TB-Runtime, nicht ein kernelunabhängiges oder beliebig altes Linux-Binary. Keine Windows-arm64-/macOS-amd64-Produkte.
+4. Release-Pakete enthalten das passende vorgebaute `tbrt` (`tbrt.exe` auf Windows) als Exportvorlage plus Format-/Runtime-/Zielmetadaten und Integritätsdaten. 06 baut sie in Gitea Actions. 02 macht deren Bau und Prüfung zunächst lokal auf dem jeweiligen Ziel ausführbar. --target akzeptiert nur vorhandene und finalisierbare Zielvorlagen; ohne Voraussetzung gibt es eine klare Verfügbarkeitsdiagnose. Keine stillen Netzdownloads und kein impliziter Cargo-Fallback.
+5. Einen versionierten Nutzlastabschluss mit geprüften Längen/Offset und vorhandenen TBC-Laderprüfungen verwenden; Plattformformat und Runtime-Version werden vor Kopieren und Start abgeglichen. Der alte Dokumentationssatz „Anhängen ist portabel“ reicht nicht als Implementierungsbeleg. Insbesondere Mach-O wird nach dem Einbetten korrekt finalisiert/signiert; die Nutzlastauffindung darf nicht annehmen, dass ein durch Signieren veränderliches Dateiende unverändert bleibt. Native macOS-arm64-Probe und Codesign-Prüfung sind ein frühes Umsetzungstor, nicht erst Release-Nacharbeit. Eine unterstützte systemeigene Signierhilfe ist keine Compiler-/Linker-Toolchain. Cross-Export wird nur angeboten, soweit Vorlage und Finalisierung auf dem Host tatsächlich verfügbar sind.
+6. In ein temporäres Geschwisterziel schreiben, validieren/finalisieren und erst dann veröffentlichen. No-clobber und ausdrückliches Ersetzen auch beim finalen Dateischritt erzwingen, Quellen/Manifest/Includes schützen und Abbruch vor Veröffentlichung beachten. Der Vertrag wird von TBL-Export, `tbc link` und IDE wiederverwendet. P-Code-Linken und `tbc link` entstehen in 03; hier genügt das bereits vollständig verknüpfte TBC. Es gibt keine Rückabhängigkeit von 02 auf 03.
+
+## Risks / Trade-offs
+
+- Nachträgliche Binäränderung invalidiert Signaturen → finalisierte Datei auf tatsächlichem Ziel prüfen; Signierung nach Nutzlasteinbau, kein Scheinerfolg. Grundlage: [Apple Code Signing](https://developer.apple.com/library/archive/technotes/tn2206/_index.html).
+- Vorlagen aus anderer Runtime-Version → klare Version-/Zielprüfung; Release-Paket enthält zusammengehörige Erzeuger und Vorlagen.
+- Vier Ziele auf nur einem Entwicklerrechner → lokale Zielprobe ist ein Teilnachweis; 05/06 verlangen tatsächliche Zielausführung.
+- Herauslösen des Runners ändert CLI-Nebenwirkungen → vorhandene CLI-/TBC-/IDE-Parität, Exitcodes, LPRINT und RUN regressionsprüfen.
+
+## Migration Plan
+
+TBC-Standardaufruf erhalten. Native Flags mit klarer Optionsdiagnose ergänzen. Dokumentation für Erzeugen, Laufzeitdateien und Systemvoraussetzungen mitliefern. Vorlagen versionieren; inkompatible Mischungen abweisen statt zu erraten. Vorherige Release-Pakete bleiben separat nutzbar.

openspec/changes/phase-6-02-native-executables/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+`tbc build` erzeugt bisher ausschließlich TBC; ein vorkompiliertes `tbrt` existiert noch nicht. Phase 6 muss daraus direkt ausführbare Terminalprogramme machen, die ohne Quellen, separat installiertes tb/tbc oder Compiler-/Linker-Toolchain beim Anwender laufen und erzeugt werden können.
+
+## What Changes
+
+- `tbc build --exe` und einen gemeinsamen Exportpfad mit geprüften `tbrt`-Vorlagen, eingebettetem Projekt und sicherer Zieldateierzeugung einführen; bestehendes `tbc build` bleibt TBC.
+- `tbrt` enthält nativ kompilierte VM, Runtime und Terminal-/Forms-Unterstützung; BASIC bleibt eingebetteter P-Code.
+- Native Terminal-Executables für Windows amd64, macOS arm64, Linux amd64 und Linux arm64 erzeugen.
+- Dieselbe VM-/Forms-/Host-/RUN-Semantik wie beim CLI verwenden; Container, Runtime-Version und tatsächliches Ziel prüfen.
+- Vorlagenherstellung und native Tests vorbereiten; die vollständige Gitea-Artefaktproduktion übernimmt Change 06, die IDE-Anbindung 04.
+
+## Capabilities
+
+### New Capabilities
+
+- `native-executables`: Toolchainfreie Verpackung und eigenständige Ausführung nativer Terminalprogramme.
+
+### Modified Capabilities
+
+Keine. TBC bleibt ein gesondertes Ausgabeformat mit unverändertem Sprachvertrag.
+
+## Impact
+
+CLI-Build-/Runnerpfad in `crates/tb-cli/src/main.rs`, gemeinsame Projekt-/VM-Erzeugung, neuer wiederverwendbarer Export-/Runnerbereich, Release-Vorlagen und native Prozessprüfungen. Keine LLVM-/JIT-Umstellung. Referenzfälle aus [01](../phase-6-01-kompatibilitaet-und-leistungsabnahme/proposal.md); Auslieferung in 06. Der gleiche Exportvertrag wird von 03 und 04 verwendet.

openspec/changes/phase-6-02-native-executables/specs/native-executables/spec.md

@@ -0,0 +1,41 @@
+## Purpose
+
+Ermöglicht die Erzeugung und Ausführung eigenständiger nativer Terminalprogramme mit eingebettetem Terminal-Basic-Projekt und Runtime.
+
+## ADDED Requirements
+
+### Requirement: Eigenständiges natives Terminalprogramm
+`tbc build --exe` SHALL ein natives Terminal-Executable für Windows amd64, macOS arm64, Linux amd64 oder Linux arm64 erzeugen. Die vorgebaute `tbrt`-Vorlage SHALL die nativ kompilierte VM und Runtime einschließlich Terminal-/Forms-Unterstützung enthalten und das eingebettete BASIC-Programm als P-Code ausführen. Das Ergebnis SHALL auf dem ausgewiesenen Ziel ohne Quellprojekt, separate TBC-Datei oder separat installiertes tbrt/tb/tbc laufen. Sowohl Erzeugung aus ausgelieferten Vorlagen als auch Ausführung SHALL ohne Compiler-/Linker-Toolchain beim Anwender möglich sein; dokumentierte Betriebssystemkomponenten dürfen erforderlich bleiben.
+
+#### Scenario: Leere Runtime-Vorlage
+- **WHEN** tbrt ohne eingebettetes Programm als Vorlage gestartet wird
+- **THEN** diagnostiziert es kontrolliert die fehlende Nutzlast und behauptet keinen erfolgreichen Programmstart
+
+#### Scenario: Ausführung auf sauberem Ziel
+- **WHEN** ein Mehrmodul-/Formular-/Include-Projekt exportiert und allein sein Executable in ein Verzeichnis ohne Quellen und ohne tb/tbc übertragen wird
+- **THEN** läuft es auf dem passenden Zielsystem als Terminalprogramm mit denselben Anfangseigenschaften, Ausgaben und Fehlerorten
+
+### Requirement: Explizites Ausgabeformat und Ziel
+Der bestehende Aufruf `tbc build <Quelle>` SHALL weiterhin TBC erzeugen. Native Erzeugung SHALL eine eindeutige Ziel-/Ausgabewahl und Überschreibentscheidung erlauben. Ungültige Optionen, nicht unterstützte Zielkombinationen, fehlende Vorlagen und inkompatible Runtime-Versionen MUST vor Veröffentlichung einer Zieldatei mit konkreter Diagnose abgewiesen werden. Ein fremdes Hostformat MUST NOT stillschweigend das angeforderte Zielformat ersetzen.
+
+#### Scenario: Vorlage passt nicht
+- **WHEN** eine Windows-amd64-Ausgabe mit einer Linux- oder inkompatiblen Runtime-Vorlage angefordert wird
+- **THEN** scheitert der Export unter Erhalt der bisherigen Zieldatei und nennt den Ziel-/Versionskonflikt
+
+### Requirement: Gemeinsame Laufzeitsemantik
+Native Programme SHALL bei denselben Hostereignissen, Anfangsdateien, Größen und COMMAND$ dieselben Sprach-, Forms-, Datei-, Druck- und Fehlerresultate wie der CLI-Lauf liefern. STOP, Abbruch und Laufzeitfehler SHALL die dokumentierten CLI-Exitcodes erhalten. RUN ohne Ziel SHALL den eingebetteten Anfangsstand neu starten; explizite externe RUN-Ziele SHALL weiter ausdrücklich benötigte Laufzeitdateien sein.
+
+#### Scenario: Neustart aus dem Executable
+- **WHEN** das native Programm Variablen und Dateien verändert und danach RUN ohne Programmziel ausführt
+- **THEN** startet es sein eingebettetes Projekt mit sauberem VM-Anfangszustand und benötigt dafür keine ursprüngliche BAS-/FRM-/MAK-Datei
+
+### Requirement: Validiertes und sicher veröffentlichtes Artefakt
+Der Export SHALL Nutzlastgrenzen, Container-/Runtime-Version und Zielformat prüfen und erst ein vollständiges Artefakt am gewählten Ziel veröffentlichen. Fehler und Abbruch SHALL vorhandene Ziele erhalten und temporäre Ausgaben beseitigen. Ausführungsrechte sowie die für lokale Ausführbarkeit notwendigen Plattform-Metadaten und Signaturen SHALL nach dem Einbetten gültig sein.
+
+#### Scenario: Beschädigte Nutzlast
+- **WHEN** ein erzeugtes Programm mit abgeschnittener oder ungültiger eingebetteter Nutzlast gestartet wird
+- **THEN** endet es mit verständlicher Ladefehlermeldung ohne Zugriff außerhalb der Nutzlast und ohne Ausführung von Projektcode
+
+#### Scenario: Finalisierung schlägt fehl
+- **WHEN** die plattformspezifische Finalisierung eines Exports fehlschlägt
+- **THEN** wird kein Erfolg gemeldet und eine vorhandene Zieldatei bleibt unverändert

openspec/changes/phase-6-02-native-executables/tasks.md

@@ -0,0 +1,19 @@
+## 1. Gemeinsamer Ausführungs- und Exportpfad
+
+- [ ] 1.1 CLI-Laufsteuerung für Quellen, TBC und eingebettete Kompilate wiederverwendbar machen; bestehende CLI-/IDE-Parität, Forms-Ende, STOP-/Fehlerexitcodes, LPRINT und RUN-Regressionen müssen bestehen.
+- [ ] 1.2 Ziel-/Runtime-/Vorlagenmetadaten für die vier vereinbarten Targets sowie kompatible Versionen festlegen; negative Tests müssen falsches System, Architektur, Version und fehlende Vorlage konkret abweisen.
+- [ ] 1.3 Gemeinsame geschützte Ausgabeveröffentlichung implementieren; Konflikt, Schreibfehler, zwischenzeitlich belegtes Ziel und Abbruch müssen ursprüngliche Dateien und Projektdaten erhalten.
+
+## 2. Native Programme
+
+- [ ] 2.1 Das kleine native `tbrt` mit VM/Runtime/Terminal/Forms und versioniertem eingebettetem Kompilat bauen; eine leere Vorlage muss fehlende Nutzlast diagnostizieren, ohne Originalquellen müssen Konsolen- und Forms-Programme laufen, RUN ohne Ziel muss das eingebettete Projekt neu initialisieren.
+- [ ] 2.2 Nutzlastgrenzen/-versionen prüfen und PE/ELF-/Mach-O-Ausgaben korrekt finalisieren; beschädigte Längen und abgeschnittene Nutzlast müssen ohne Absturz mit Ladefehler enden.
+- [ ] 2.3 macOS-arm64-Signierung und stabile Nutzlastauffindung nach Finalisierung praktisch belegen; native Ausführung und Signaturprüfung müssen die endgültige Datei akzeptieren, andernfalls keine Exportfreigabe.
+- [ ] 2.4 `tbc build --exe` mit Ausgabepfad, explizitem Target und Überschreibentscheidung anbinden; CLI-Tests müssen unbekannte Flags abweisen und den bisherigen TBC-Standard unverändert bestätigen.
+- [ ] 2.5 `tbrt`-Vorlagen-Bauaufrufe für Windows amd64, macOS arm64 und Linux amd64/arm64 bereitstellen; native Header-/Architekturprüfung muss jede Vorlage ihrem deklarierten Target zuordnen.
+
+## 3. Abnahme und Übergabe
+
+- [ ] 3.1 Repräsentative Fälle aus 01 als einzelne Executables in sauberen Verzeichnissen ohne Quellen/TBC/tb/tbc/Rust-Toolchain starten; Ausgabe, Dateieffekte, COMMAND$, Fehler und Terminal-/Pipeverhalten müssen mit CLI übereinstimmen.
+- [ ] 3.2 Verfügbarkeit und Systemvoraussetzungen einschließlich externer RUN-/OPEN-Ressourcen dokumentieren; fehlende Finalisierungswerkzeuge dürfen keine stille Ersatzdatei erzeugen.
+- [ ] 3.3 Gemeinsamen Exportvertrag und Zielvorlagen an 03/04/06 übergeben; fokussierte native Tests, Workspace-Regressionen, Clippy, Format- und OpenSpec-Prüfung müssen bestehen, noch ausstehende externe Zielnachweise benannt sein.