⚙️ 🤖 Offline-API: gemeinsame Episoden-Bibliothek für CLI, Import und Web-Editor (zpub episode new) #126

Closed
opened 2026-11-04 11:05:35 +01:00 by holm · 2 comments
Owner
Dimension Bewertung Einschätzung
Aufwand ██████░░░░ Mittel-hoch — Schema + Bibliothek, zwei bestehende Schreibpfade umstellen
Nutzen ████████░░ Hoch — ein Regelwerk für CLI, Import und Web-Editor; zpub episode new fällt fast gratis ab
Bruchhäufigkeit █████░░░░░ Mittel — heute driften die Schreibpfade auseinander (Beleg unten)
Nachhaltigkeit █████████░ Sehr hoch — neue Felder einmal, alle Oberflächen erben sie
Dringlichkeit ████░░░░░░ Mittel — nächster Kalender (2026) braucht neue Folgen

Ziel (Holm 2026-11-04, Entscheid 46)

„Offline-API“: eine Bibliothek, die CLI (zpub episode new), Feed-Importer und Web-Editor gemeinsam nutzen — kein redundanter Code.

Befund: heute zwei getrennte Schreibpfade für episode.md

Pfad Datei Eigenheiten
Web-Editor POST /api/episode webwizard/app.sh create_episode eigene Validierung (Slug, ISO-Datum, _norm_time), eigener TOML-Writer per printf; kein season — für Mehrstaffel-Tenants wie advent unbrauchbar
Importer scripts/import-feed.sh (jq-Writer) season, guid, transcript_*, Herkunfts-Kommentar; Datum nach UTC
CLI — fehlt (zpub episode new)

Vorschlag

  • scripts/lib/episode.sh (Bash + jq + yq, kein Python): JSON rein, JSON raus, Exit-Codes statt HTTP
    • episode_next <projekt> [--season S] → nächste freie Nummer/Slug
    • episode_validate → normalisiertes JSON oder Fehlerliste (Slug, Datum mit Zeitzone, Dauer, Typ, Sprecher existieren)
    • episode_write <projekt> → episodes/<slug>/episode.md + Ordner audio/, gimmicks/; nie überschreiben
    • speaker_list, episode_list (heute im Web-Editor)
  • Ein Feld-Schema (jq-Datei) als einzige Quelle: Feldliste, Pflicht/optional, Normalisierung — Doku-Tabelle daraus prüfbar
  • Aufrufer werden dünn:
    • zpub api <verb> (stdin JSON → stdout JSON) — die eigentliche „Offline-API“, auch für Scripts
    • zpub episode new [--season 2026] [--title …] baut das JSON aus Flags/Defaults
    • Web-Editor-Handler: HTTP-Prüfungen bleiben (#77/#78), Fachlogik → Bibliothek; Exit-Code → HTTP-Status
    • Importer: Frontmatter über episode_write, Shownotes/Gimmicks bleiben im Importer

Schwächster Punkt

Der Importer schreibt mehr Felder als der Editor (guid, transcript, Kommentare). Das Schema muss die Obermenge tragen — das ist die eigentliche Arbeit, nicht die Funktionen. Zweitens: pro Folge mehrere jq/yq-Prozesse; beim Import von 100 Folgen spürbar, aber im Sekundenbereich.

Abnahme

  • zpub episode new --season 2026 im advent-Tenant erzeugt 2026-01 mit gültigem Frontmatter, Build ✅
  • Web-Editor legt Folgen mit season an; bestehende Editor-Tests grün
  • Re-Import advent in Staging: byte-gleiche episode.md wie vor dem Umbau

🤖 angelegt von Claude v00 (API/Token holm)

| Dimension | Bewertung | Einschätzung | |---|---|---| | Aufwand | `██████░░░░` | Mittel-hoch — Schema + Bibliothek, zwei bestehende Schreibpfade umstellen | | Nutzen | `████████░░` | Hoch — ein Regelwerk für CLI, Import und Web-Editor; `zpub episode new` fällt fast gratis ab | | Bruchhäufigkeit | `█████░░░░░` | Mittel — heute driften die Schreibpfade auseinander (Beleg unten) | | Nachhaltigkeit | `█████████░` | Sehr hoch — neue Felder einmal, alle Oberflächen erben sie | | Dringlichkeit | `████░░░░░░` | Mittel — nächster Kalender (2026) braucht neue Folgen | ## Ziel (Holm 2026-11-04, Entscheid 46) „Offline-API“: eine Bibliothek, die CLI (`zpub episode new`), Feed-Importer und Web-Editor gemeinsam nutzen — kein redundanter Code. ## Befund: heute zwei getrennte Schreibpfade für `episode.md` | Pfad | Datei | Eigenheiten | |---|---|---| | Web-Editor `POST /api/episode` | `webwizard/app.sh` `create_episode` | eigene Validierung (Slug, ISO-Datum, `_norm_time`), eigener TOML-Writer per `printf`; **kein `season`** — für Mehrstaffel-Tenants wie advent unbrauchbar | | Importer | `scripts/import-feed.sh` (jq-Writer) | `season`, `guid`, `transcript_*`, Herkunfts-Kommentar; Datum nach UTC | | CLI | — | fehlt (`zpub episode new`) | ## Vorschlag - `scripts/lib/episode.sh` (Bash + jq + yq, kein Python): **JSON rein, JSON raus**, Exit-Codes statt HTTP - `episode_next <projekt> [--season S]` → nächste freie Nummer/Slug - `episode_validate` → normalisiertes JSON oder Fehlerliste (Slug, Datum mit Zeitzone, Dauer, Typ, Sprecher existieren) - `episode_write <projekt>` → `episodes/<slug>/episode.md` + Ordner `audio/`, `gimmicks/`; nie überschreiben - `speaker_list`, `episode_list` (heute im Web-Editor) - Ein Feld-Schema (jq-Datei) als einzige Quelle: Feldliste, Pflicht/optional, Normalisierung — Doku-Tabelle daraus prüfbar - Aufrufer werden dünn: - `zpub api <verb>` (stdin JSON → stdout JSON) — die eigentliche „Offline-API“, auch für Scripts - `zpub episode new [--season 2026] [--title …]` baut das JSON aus Flags/Defaults - Web-Editor-Handler: HTTP-Prüfungen bleiben (#77/#78), Fachlogik → Bibliothek; Exit-Code → HTTP-Status - Importer: Frontmatter über `episode_write`, Shownotes/Gimmicks bleiben im Importer ## Schwächster Punkt Der Importer schreibt mehr Felder als der Editor (guid, transcript, Kommentare). Das Schema muss die Obermenge tragen — das ist die eigentliche Arbeit, nicht die Funktionen. Zweitens: pro Folge mehrere jq/yq-Prozesse; beim Import von 100 Folgen spürbar, aber im Sekundenbereich. ## Abnahme - `zpub episode new --season 2026` im advent-Tenant erzeugt `2026-01` mit gültigem Frontmatter, Build ✅ - Web-Editor legt Folgen mit `season` an; bestehende Editor-Tests grün - Re-Import advent in Staging: byte-gleiche `episode.md` wie vor dem Umbau > 🤖 angelegt von Claude v00 (API/Token holm)
Author
Owner

In Arbeit (Holm 2026-11-04: „126 go worker“)

  • Worker w-126, worktree-isoliert, Branch feat/126-…; Merge nach dev durch v00 nach Abnahme
  • Parallel: #126, #127, #128, #129 — Merges seriell

🤖 angelegt von Claude v00 (API/Token holm)

## In Arbeit (Holm 2026-11-04: „126 go worker“) - Worker w-126, worktree-isoliert, Branch `feat/126-…`; Merge nach dev durch v00 nach Abnahme - Parallel: #126, #127, #128, #129 — Merges seriell > 🤖 angelegt von Claude v00 (API/Token holm)
Author
Owner

Erledigt — gemergt nach dev (412c090)

Abnahme Beleg
zpub episode new --season 2026 im advent-Tenant Worker (Staging-Kopie): episodes/2026-01/episode.md (season 2026, Sprecher der neuesten Folge), Build rc=0, Folge in Feed + Index; zweiter Lauf rc=3 (existiert)
Web-Editor legt Folgen mit season an Worker: End-to-End über serve.sh 43 ✓ / 0 ✗ (inkl. aller 400-Fälle #77/#78, 403, 415, 409; nach 400 kein Ordner)
Re-Import byte-gleich Worker: advent-Rohsicherung 56/56 episode.md + podcast.toml byte-gleich; synthetischer Grenzfall-Feed 4/4
v00-Stichprobe zpub episode new --dry-run sample_project → gültiges Frontmatter 007; zpub api validate → JSON-Fehlerliste; Build + zpub check 14 ✓ 0 ✗ 0 ⚠; schema-doc.sh: 22 Felder dokumentiert

Neu: scripts/lib/episode.sh + scripts/lib/episode-schema.jq (einzige Feldquelle, inkl. event für #128), zpub episode new [--season] [--title] [--speaker] [--episode] [--slug] [--dry-run], zpub api <schema|speakers|episodes|next|validate|write> (stdin JSON → stdout JSON; Exit 0 ok · 1 ungültig/400 · 2 Fehler/500 · 3 existiert/409 · 4 kein Tenant/404). Web-Editor-Handler und Importer nutzen die Bibliothek.

Abweichungen: Tags beliebiger Text ohne Steuerzeichen (Obermenge Importer); Zeit ohne Zeitzone abgewiesen; duration = "" immer geschrieben; Importer bricht bei ungültigem Typ/Titel an der Folge ab statt still zu schreiben.

Grenzen: Importer prüft je Folge beim Schreiben, nicht vorab → ein ungültiges Item mitten im Feed hinterlässt einen Teilimport. Laufzeit Import +7 s auf 56 Folgen. Nebenbefund escape-test.sh (10 FAIL auf Basis und Branch identisch) → #132 (escape-test.sh veraltet).

🤖 angelegt von Claude v00 (API/Token holm)

## Erledigt — gemergt nach dev (412c090) | Abnahme | Beleg | |---|---| | `zpub episode new --season 2026` im advent-Tenant | Worker (Staging-Kopie): `episodes/2026-01/episode.md` (season 2026, Sprecher der neuesten Folge), Build rc=0, Folge in Feed + Index; zweiter Lauf rc=3 (existiert) | | Web-Editor legt Folgen mit `season` an | Worker: End-to-End über serve.sh 43 ✓ / 0 ✗ (inkl. aller 400-Fälle #77/#78, 403, 415, 409; nach 400 kein Ordner) | | Re-Import byte-gleich | Worker: advent-Rohsicherung 56/56 `episode.md` + podcast.toml byte-gleich; synthetischer Grenzfall-Feed 4/4 | | v00-Stichprobe | `zpub episode new --dry-run sample_project` → gültiges Frontmatter 007; `zpub api validate` → JSON-Fehlerliste; Build + `zpub check` 14 ✓ 0 ✗ 0 ⚠; `schema-doc.sh`: 22 Felder dokumentiert | **Neu:** `scripts/lib/episode.sh` + `scripts/lib/episode-schema.jq` (einzige Feldquelle, inkl. `event` für #128), `zpub episode new [--season] [--title] [--speaker] [--episode] [--slug] [--dry-run]`, `zpub api <schema|speakers|episodes|next|validate|write>` (stdin JSON → stdout JSON; Exit 0 ok · 1 ungültig/400 · 2 Fehler/500 · 3 existiert/409 · 4 kein Tenant/404). Web-Editor-Handler und Importer nutzen die Bibliothek. **Abweichungen:** Tags beliebiger Text ohne Steuerzeichen (Obermenge Importer); Zeit ohne Zeitzone abgewiesen; `duration = ""` immer geschrieben; Importer bricht bei ungültigem Typ/Titel an der Folge ab statt still zu schreiben. **Grenzen:** Importer prüft je Folge beim Schreiben, nicht vorab → ein ungültiges Item mitten im Feed hinterlässt einen Teilimport. Laufzeit Import +7 s auf 56 Folgen. Nebenbefund `escape-test.sh` (10 FAIL auf Basis und Branch identisch) → [#132](https://forgejo.mueller.network/Zentonic/zentonic-publisher/issues/132) (escape-test.sh veraltet). > 🤖 angelegt von Claude v00 (API/Token holm)
holm closed this issue 2026-11-04 18:41:26 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Zentonic/zentonic-publisher#126
No description provided.