docs(readme): talk wrap dokumentieren — --Semantik, Label, Exit-Codes

Neuer Abschnitt zur Befehlsummwicklung: Aufrufform, Schutzwirkung des
ersten „--“, Label (wrap.label/TALK_WRAP_LABEL/Basisname) samt Sprach-
erkennung, Exit-Code-Politik (Befehls-Code gewinnt immer, 127 für nicht
startbare Befehle, 1 für Signaltode), geerbte say-Flags und der
Ansageweg über Daemon/Degraded Mode; Implementiert-Liste um wrap ergänzt.
This commit is contained in:
m3ta-chiron committed 2026-10-18 21:01:13 +02:00
1 parent 6877d64042
commit acfba19fc2
1 file changed
+45 -2
+45 -2
View File
@@ -30,8 +30,9 @@ Say-Flags (gelten auch für `talk "Text"`): `--wait`, `--now`, `--priority`,
**Hinweis:** In diesem Stand sind implementiert: `say` (und `talk "Text"`)
mit der kompletten Provider-Kette und Daemon-Anbindung (non-blocking über
`talkd`, siehe unten), `mute`, `unmute`, `status`, `cancel`. Die übrigen
Befehle sind Stubs und melden `not implemented yet` (Exit-Code ≠ 0).
`talkd`, siehe unten), `mute`, `unmute`, `status`, `cancel` sowie `wrap`.
Die übrigen Befehle sind Stubs und melden `not implemented yet` (Exit-Code
≠ 0).
## Daemon talkd (Task 04–06)
@@ -219,6 +220,48 @@ Der OS-Provider `osbuiltin` nutzt auf Linux zwei Wege:
`TALK_AUDIO_SINK=null` (oder `audio.sink = "null"` in der config.toml)
schaltet jede Tongabe ab — für CI und Server.
## `talk wrap` — Befehle annoncieren (Task 07)
`talk wrap -- <Befehl> [Argumente …]` führt den Befehl aus und macht das
Ergebnis hörbar: stdin/stdout/stderr werden durchgereicht — stdout gehört
allein dem Befehl, Informationszeilen von talk (z. B. die Item-ID der
Ansage) gehen auf stderr, damit Pipes und Redirects sauber bleiben. Die
Wandzeit wird gemessen und nach dem Ende des Befehls angesagt:
- Erfolg: „sleep erfolgreich. Dauer: 2 Sekunden."
- Misserfolg: „sh fehlgeschlagen, Code 2." (ohne Dauer)
```console
talk wrap -- sleep 2
talk wrap --wait -- make test
```
- **`--` schirmt den Befehl komplett ab:** Das erste allein stehende `--`
beendet die talk-Flag-Auswertung — alles danach geht unverändert an den
Befehl. `talk wrap -- foo --bar` reicht `--bar` an foo weiter, statt es
als talk-Flag zu fehlzuinterpretieren. talk-Flags für die Ansage stehen
deshalb davor (`talk wrap --wait -- …`); ohne `--` gelten die üblichen
Regeln (Flags überall, auch nach Positionalargumenten).
- **Label** der Ansage: `wrap.label` in der config.toml (Env
`TALK_WRAP_LABEL` schlägt die Datei) oder der Basisname des Befehls
(`/usr/bin/make` → „make"). Die Sprache erkennt langdetect am Label
(de/en, deutscher Default); `--lang` überschreibt.
- **Exit-Code-Politik:** wrap exitet immer mit dem Code des Befehls —
scheitert die Ansage selbst, bleibt der Befehls-Code trotzdem (nur eine
Warning auf stderr; talk-Fehler ≠ Befehls-Fehler). Nicht startbare
Befehle (Binary nicht gefunden) zählen als 127 (Shell-Konvention),
Signaltode portabel als 1. Benutzungsfehler von talk selbst (kein
Befehl, ungültige Flags) scheitern vor dem Start des Befehls.
- **Ansageweg:** derselbe wie say — Daemon-Pfad (enqueue, non-blocking;
`--wait` respektiert), ohne Daemon Degraded Mode über die Lock-Datei.
wrap erbt die say-Flags (`--wait`, `--now`, `--priority`, `--voice`,
`--lang`, `--provider`) und reicht sie an die Ansage durch.
```toml
[wrap]
label = "Deployment" # Ansage-Label statt Befehls-Basisname (TALK_WRAP_LABEL)
```
## Entwicklung
```console