# 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.