116 lines
5.7 KiB
Markdown
116 lines
5.7 KiB
Markdown
# 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.
|