talk/.superpowers/sdd/plan/task-1-report.md

Task 1 Report: Repo-Skeleton & CI-Backbone

Status: DONE Branch: feat/v1 (Basis c8f3902, nie gepusht) Commits:

• 24dfe4d chore: bootstrap go module, license, readme and package skeleton
• 33b97a5 feat(cli): add subcommand dispatch, --version and stub commands
• fa4f193 ci: add gitea actions test workflow (vet, gofmt, test, build)

Implementiert

Go-Modul & Layout

• go.mod: module code.m3ta.dev/m3tam3re/talk, go 1.26.8 (aktuelle stabile Version des Dev-Hosts; CI liest sie per go-version-file: go.mod). Keine externen Dependencies, keine go.sum.
• Verzeichnisgerüst komplett:
  • cmd/talk/ (3 Dateien), cmd/talkd/ (1 Datei)
  • internal/{provider,queue,audio,notify,config,api,langdetect}/doc.go — jeweils nur Package-Doku mit Zweck + Task-Verweis, kein toter Code.

CLI (cmd/talk/)

• main.go: ldflags-Variablen version = "dev", commit = "" verdrahtet (Paket main, injizierbar per -X main.version=… -X main.commit=…); main() delegiert an run() mit injizierbaren Writer/Return-Code-Design.
• cli.go: datengetriebene Befehlstabelle (alle 10 Subcommands aus der bindenden CLI-Surface: say, wrap, mute, unmute, status, cancel, voices, test, doctor, setup) + Dispatch:
  • talk "Text" → Default-Pfad, mappt auf say (Stub vermeldet talk say is not implemented yet).
  • talk <Befehl> → Subcommand-Stub: non-zero (Exit 1) + klare not implemented yet-Meldung auf stderr.
  • --version → talk version dev (bzw. talk version <v> (<commit>) wenn Commit injiziert — manuell verifiziert: talk version 1.0.0-test (abc1234)).
  • --help / help [Befehl] / <Befehl> --help → Hilfe aus derselben Tabelle generiert (keine Drift zwischen Hilfe und Dispatch möglich).
  • say-Flags gemäß Spec bereits registriert und dokumentiert: --wait, --now, --priority, --voice, --lang, --provider (gelten auch für den Default-Pfad talk "Text" --wait …).
  • Exit-Code-Konvention: 0 = OK (inkl. help/version), 1 = Stub/Fehler, 2 = Benutzungsfehler (unbekannte Flags, Aufruf ohne Argumente).
  • Erweiterbar für Task 09 (Bubble Tea): neuer Eintrag in commands bzw. austauschbares register/Run-Verhalten, ohne run()-Dispatch-Umbau.

Daemon-Stub (cmd/talkd/main.go)

Startet, loggt eine Zeile (talkd: Platzhalter — Daemon-Implementierung folgt in Task 04), beendet mit Exit 0. Verifiziert.

CI (.gitea/workflows/test.yml)

Push + PR; Steps: checkout@v4 → setup-go@v5 (go-version-file: go.mod) → go vet ./... → gofmt-Check (gofmt -l ., fail bei nicht-leerem Output) → go test ./... → go build ./.... YAML validiert (nixpkgs-yq-Parser).

Meta

• .gitignore: /talk, /talkd, .exe-Varianten, *.test, *.out, /dist/.
• LICENSE: MIT, Copyright (c) 2026 m3tam3re.
• README.md (deutsch): Zweck (1 Satz), Status WIP + Spec/Plan-Verweis, Befehlstabelle, say-Flags, Entwicklungs-/CI-Hinweise, Lizenz.

Getestet (Ergebnisse)

cmd/talk/cli_test.go — 9 Black-Box-Tests über die run()-Seam (in-process, kein Subprocess-Bedarf, alle extern beobachtbares Verhalten):

Test	Assertion
TestHelpListetAlleSubcommands	--help listet alle 10 Befehle (zeilenpräzise, hartkodierte Soll-Liste aus der Spec, nicht aus der Tabelle abgeleitet)
TestVersionDefault	--version → Exit 0, exakt talk version dev\n
TestVersionStringMitCommit	Commit-Injection → talk version dev (c0ffee1)
TestSubcommandStubs	alle 10 Befehle: Exit non-zero, stderr enthält Befehlsnamen + not implemented yet, stdout leer
TestDefaultAufrufMapptAufSay	talk "Hallo Welt" → talk say is not implemented yet
TestSayHelpZeigtFlags	say --help zeigt alle 6 say-Flags
TestHelpSubcommand	help + help mute → Exit 0, korrekte Hilfe
TestOhneArgumenteZeigtUsage	nackter Aufruf → Usage auf stderr, Exit 2
TestUnbekanntesFlag	--bogus → Exit 2 + Fehlermeldung

Vollständige Abnahme vor Commit und final auf dem Commit-Stand: gofmt -l . leer · go vet ./... grün · go test -count=1 ./... grün · go build ./... grün · Working Tree clean.

Manuelle Smoke-Tests: --version, --help, say --help, talk "Hallo Welt" (Exit 1), talk mute (Exit 1), talk --bogus (Exit 2), talkd (loggt, Exit 0), ldflags-Injection.

Self-Review

• Vollständigkeit gegen Brief: jedes Punkt abgedeckt (Modul ✓, Gerüst ✓, Dispatch ✓, Version ✓, talkd ✓, CI ✓, .gitignore/LICENSE/README ✓, sinnvoller Test ✓, Conventional Commits ✓, kein Push ✓, .superpowers// .scratch/ unangetastet ✓).
• YAGNI-Check: Say-Flags im Stub bewusst registriert — sie sind Teil der bindenden CLI-Surface und machen <Befehl> --help korrekt (Brief fordert „korrektes --help“); keine weiteren Vorab-Strukturen gebaut.
• Test-Hygiene: nur extern beobachtbares Verhalten (Exit-Codes, stdout, stderr); keine Implementationsdetails; Spec-Liste hartcodiert als Drift-Wächter.

Concerns / Hinweise für Folgetasks

1. Stdlib-flag-Parsing-Stil: Flags müssen vor dem Text stehen (talk --wait "Text", nicht talk "Text" --wait) — stdlib-Limitierung. Task 02 sollte das Parsing-Verhalten explizit festlegen.
2. Nackter talk-Aufruf ist aktuell Benutzungsfehler (Exit 2); Task 02 ändert das ggf. zu stdin-Lesung (Kommentar im Code markiert die Stelle).
3. --version nur auf Root-Ebene (talk --version); Subcommand-Flagsets kennen es nicht (talk say --version → Exit 2) — bewusst, Standard bei Subcommand-CLIs.
4. .gitea/workflows/test.yml ist noch nie in echter Gitea-Runner-Umgebung gelaufen (Syntax validiert, Semantik nach bekannten Actions-Konventionen); erster echter Push zeigt es.