OpenAPI-Spec-Sync-Workflow mit Diff-Bericht und /api-sync-Befehl

# Richte einen OpenAPI-Spec-Sync-Workflow in diesem Projekt ein Ich möchte denselben Backend-Spec-Workflow wie in einem anderen Repo: ein Skript, das die Live-OpenAPI-Spec gegen einen lokalen Snapshot diffed und einen **frontend-orientierten** Änderungsbericht schreibt, plus einen `/api-sync`-Slash-Command, der diesen Bericht in einen phasenweisen Plan umwandelt. Fülle diese aus dem Repo aus, bevor du beginnst (frag mich nur, wenn du es nicht herausfinden kannst): - **Spec-Quelle**: Finde sie selbst - siehe Teil 0. Frag mich nicht nach der URL, bevor du geschaut hast. Was auch immer du findest, wird zum Standard des Skripts, überschreibbar über eine `OPENAPI_URL`-Env-Variable. - **Snapshot-Pfad**: `api-spec/openapi.yaml` · **Berichtspfad**: `api-spec/CHANGES.md` - **Quell-Root zum Querverweisen**: `src/` (an das Layout dieses Repos anpassen) - **Response-Validierungs-Bibliothek**: zod (anpassen, falls dieses Repo etwas anderes verwendet) - **Snapshot in Git?** Halte die YAML **gitignored** (zu groß/verrauscht für die Historie), aber **committe `CHANGES.md`** - der generierte Bericht ist der dauerhafte Nachweis darüber, was sich wann geändert hat. Ignoriere außerdem `api-spec/openapi-*.yaml` und `api-spec/CHANGES-*.md` (datierte manuelle Archive). Lies zuerst dieses Repo (Paketmanager, Skript-Konventionen, wie API-Aufrufe und Response-Schemas geschrieben werden) und passe den Stil an. Erfinde keine Pfade - grep nach den echten. --- ## Teil 0 - Finde die Spec, bevor du etwas schreibst Mach das zuerst und sag mir, was du gefunden hast. Rate keine URL und frag mich nicht, bis dies leer bleibt. **1. Die Doku - der günstigste Ort und normalerweise richtig.** `README.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, alles unter `docs/`, `.github/`, `.cursor/rules/`, eine `*.http`/`*.rest`-Kratzdatei oder ein Wiki-Checkout. Die URL steht oft im Prosa ("API-Doku: …/swagger"), in einem Setup-Schritt oder neben dem Backend-Repo-Link: ```bash grep -rniE 'swagger|openapi|api-?docs|redoc|\/v3\/api-docs' --include='*.md' --include='*.mdx' --include='*.txt' --include='*.http' --include='*.rest' . | grep -v node_modules ``` Zwei Stolperfallen: Ein **Swagger-UI-Link** (`…/swagger-ui/index.html`, `…/docs`, `…/redoc`) ist eine HTML-Seite, nicht die Spec - leite die Maschinen-URL daraus ab (`/swagger-ui/index.html` → `/v3/api-docs`, `/docs` → `/openapi.json`, `/redoc` → die `spec-url` in seinem HTML) und verifiziere mit curl. Und eine Doku-URL kann **veraltet** sein - bestätige, dass sie antwortet, bevor du sie übernimmst, und sag mir, wenn das README auf etwas Totes zeigt. **2. Eine Spec-Datei bereits im oder nahe dem Repo** - jemand hat normalerweise eine eingecheckt: ```bash find . -path ./node_modules -prune -o -iregex '.*\(swagger\|openapi\|api-docs\).*\.\(ya?ml\|json\)' -print git ls-files | grep -iE 'swagger|openapi|api-docs' ``` Prüfe auch `node_modules/.cache/`, `.next/cache/`, `dist/`, `build/`, `coverage/` und jeden gitignored `api/`, `api-spec/`, `docs/`, `schemas/`-Ordner - ein früherer Codegen-Lauf hat oft eine Kopie dort hinterlassen. Eine veraltete Cache-Kopie ist trotzdem nützlich: Sie ist eine **Basislinie, um den Snapshot zu seeden**, damit der erste echte Diff aussagekräftig ist statt "alles ist neu". Wenn du eine findest, sag, wie alt sie ist (`git log -1` / Datei-mtime), bevor du entscheidest, ihr zu vertrauen. **3. Eine Generator-Konfiguration, die die Quelle bereits benennt** - das ist der Treffer mit dem höchsten Signal, weil er auf die URL oder den Pfad zeigt, den das Team tatsächlich verwendet: ```bash grep -rniE 'openapi|swagger|api-docs' --include='*.json' --include='*.ts' --include='*.js' --include='*.mjs' --include='*.yaml' --include='*.yml' --include='.env*' --include='Makefile' --include='*.sh' -l . | grep -v node_modules ``` Schau gezielt nach: `openapi-typescript` / `orval.config.*` / `kubb.config.*` / `swagger-typescript-api` / `@hey-api/openapi-ts`-Konfiguration, einem `openapi`-ähnlichen npm-Skript in package.json, einer `.env*`-API-Basis-URL, `docker-compose.yml`-Service-URLs, CI-Workflow-Schritten oder einem eingecheckten generierten Client, dessen Header-Kommentar seine Quell-Spec zitiert. **4. Leite sie aus der API-Basis-URL ab.** Wenn du nur eine Basis-URL findest, teste die üblichen Pfade für das Framework dieses Backends, bevor du mich fragst - FastAPI `/openapi.json`, Spring/springdoc `/v3/api-docs` (+ `.yaml`), ASP.NET `/swagger/v1/swagger.json`, NestJS `/api-json`, Rails/rswag `/api-docs/v1/swagger.yaml`, plus einfaches `/openapi.yaml` und `/swagger.json`: ```bash curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json ``` Berichte, welche geantwortet haben. Wenn alle Auth benötigen, sag es - bake kein Token in das Skript. **5. Nichts funktioniert?** Dann frag mich und sag mir, was du ausgeschlossen hast. ### Wenn die Spec nicht über HTTP erreichbar ist Erzwinge das Fetch-Design nicht. Mache die Quelle zu einer einzigen `SPEC_SOURCE`, die **eine URL, ein lokaler Pfad oder ein Shell-Befehl** sein kann (z.B. das eigene `make openapi` des Backend-Repos oder eine generierte Datei eines Schwester-Checkouts), aufgelöst in dieser Reihenfolge: `--to <datei>`-Flag → `OPENAPI_URL`-Env → der von dir entdeckte Standard. Alles danach - Diff, Bericht, Snapshot - bleibt unverändert. Sag in `CLAUDE.md`, welche dieses Repo verwendet und wie man sie aktualisiert. ## Teil 1 - `scripts/sync-api.mjs` Ein einzelnes dependency-armes Node-ESM-Skript (`js-yaml` ist die einzige neue Abhängigkeit; verwende den Paketmanager des Repos). Flags: ``` node scripts/sync-api.mjs Remote abrufen → Diff vs. Snapshot → Bericht schreiben + Snapshot überschreiben node scripts/sync-api.mjs --check Nur Diff, Snapshot unangetastet, Exit 1 bei Abweichung (CI-freundlich) node scripts/sync-api.mjs --from <datei> Diff gegen <datei> statt gegen den Snapshot node scripts/sync-api.mjs --to <datei> Behandle <datei> als "Remote" statt zu fetchen (offline) node scripts/sync-api.mjs --json Gib den rohen Diff zusätzlich als JSON auf stdout aus ``` Füge `"sync:api": "node scripts/sync-api.mjs"` zu package.json hinzu. **Wenn noch kein Snapshot existiert**: Schreibe die abgerufene Spec als Snapshot, gib "geseedet - nach dem Backend-Release erneut ausführen, um einen Diff zu sehen" aus, Exit 0. Melde niemals die gesamte API als "neu". Ausnahme: Wenn Teil 0 eine ältere gecachte/vendored Spec zutage gefördert hat, seede den Snapshot von **dieser** und führe beim ersten Lauf einen echten Diff gegen die Live-Spec aus - sag mir das Datum der Cache-Kopie, damit ich weiß, was die Basislinie bedeutet. ### Was es diffen muss Flache `paths` in eine `"GET /a/b"` → Operation-Map ab und diffe Operationen *und* `components.schemas` getrennt: **Operationen** - hinzugefügt / entfernt / geändert - Parameter: neue (Flag `required`), required↔optional-Flips, Enum-Werte hinzugefügt/entfernt - Schlüssele einen Parameter mit `in:name` (oder `ref:Name` für `$ref`-Parameter), nicht nach Array-Index - Request-Body und Erfolgs-Response-Schema: Wenn sich der `$ref`-Name geändert hat, melde die Umbenennung; wenn die Form **inline** ist (kein `$ref`), diffe ihre Eigenschaften hier - ein unbenanntes Schema wird hier oder nirgendwo gedifft. Löse `allOf: [$ref]`-Wrapper zum zugrunde liegenden Namen auf und rendere `oneOf`/`anyOf`-Unions als `A | B` (ein Union-Member zu gewinnen/verlieren ist eine echte Verhaltensänderung). - neue/entfernte Nicht-2xx-Statuscodes - Security-Anforderungsänderungen, neu `deprecated` **Schemas** - Eigenschaften hinzugefügt (als required markieren) / entfernt / umtypisiert - Enum-Werte hinzugefügt oder entfernt (auf dem Schema und auf jeder Eigenschaft, einschließlich `items.enum`) - required↔optional-Flips ### Die zwei Dinge, die diesen Bericht wertvoll machen 1. **`error_code`-Extraktion aus Response-Prosa.** Maschinen-Fehlercodes sind normalerweise nirgendwo dokumentiert außer im `description`-Text jeder Nicht-2xx-Response ("… bereits ein aktives Mitglied (already_member)"), also sieht ein neuer Zweig, den wir behandeln müssen, für einen Schema-Diff wie *nichts geändert* aus. Parse sie nach **Kontext, nicht Vokabular**: Tokens in `(...)`, Tokens nach `error_code`-ähnlichem Prosa und jedes snake_case-Token, das in einem literalen `error_code`-Enum eines Schemas vorkommt. Filtere **nicht** Tokens heraus, die mit Feldnamen oder Enum-Werten kollidieren - diese Kollisionen sind genau die Codes, die am wichtigsten sind. Verwerfe Tokens, die durch "Feld X"-Formulierungen eingeführt werden (das sind Feldnamen, keine Codes). Melde hinzugefügte Codes, und für einen Code, der nicht mehr dokumentiert wird, grep die Quelle nach `"that_code"` und sag, **welche Datei darauf verzweigt** - das ist ein toter Zweig. 2. **Kreuze jede Änderung mit dem tatsächlichen Code ab.** Lade jede Quelldatei einmal über `git ls-files --cached --others --exclude-standard <src root>` (untracked einbeziehen, damit eine in dieser Session hinzugefügte Call-Site zählt; überspringe Dateien, die gelistet, aber aus dem Arbeitsbaum gelöscht sind), dann: - **Call-Sites** für einen Pfad: Wandle Pfad-Parameter in Ein-Segment-Wildcards um und verlange, dass der Match an einem Quote/Backtick/`?` endet, damit `/orgs/{id}` nicht `/orgs/${id}/archive` matcht. Jede entfernte/geänderte Operation listet ihre Call-Sites oder "⛔ keine Call-Site". - **Schema-Spiegel**: Finde die Datei, die unseren Response-Validierungs-Spiegel eines Spec-Schemas enthält - matche `fooBarSchema` überall plus den nackten PascalCase-Namen **nur innerhalb einer `schemas.ts`** (anderswo kollidiert es mit unabhängigen TS-Identifiers). Passe die Namenskonvention an, was auch immer dieses Repo tatsächlich verwendet - grep zuerst. - Eine neue Operation, deren Pfad bereits in `src/` referenziert wird, erhält einen "⚠️ Pfad bereits referenziert - Methode prüfen"-Hinweis. ### Berichtsformat (`api-spec/CHANGES.md`) Kopfzeile mit Generierungsdatum, Basislinien-Label, Spec `info.version` und Vorher→Nachher-Operations- und Schema-Zählern; dann eine kleine hinzugefügt/entfernt/geändert-Tabelle; dann Abschnitte in dieser Reihenfolge: - `## 🔴 Entfernte Operationen - brechend, wenn wir sie aufrufen` (mit Call-Sites) - `## 🟡 Geänderte Operationen` (verschachtelte Bullets pro Änderung + Call-Sites) - `## 🟢 Neue Operationen`, gruppiert nach Pfadbereich (erstes Segment, mit sinnvollen Sonderfällen für die Präfixe dieser API) - Zusammenfassung, Response-Schema, Request-Body-Schema - `## 🔴 Entfernte Schemas` (mit Spiegel-Dateien) - `## 🟡 Geänderte Schemas` - **gespiegelte zuerst sortiert und mit der Spiegel-Datei fettgedruckt**, da diese heute das Parsing brechen können; der Rest ist informativ - `## 🟢 Neue Schemas` (eine kommagetrennte Zeile) Wenn nichts geändert ist, ist der Body exakt "Keine Änderungen seit dem letzten Snapshot." Setze oben in die Datei "nicht von Hand bearbeiten". Halte das Skript dort kommentiert, wo eine Entscheidung nicht offensichtlich ist (die error_code-Heuristik, der End-Anker des Pfad-Matchers, warum untracked Dateien einbezogen werden) - zukünftiges-Ich liest diese. ## Teil 2 - `.claude/commands/api-sync.md` Ein Slash-Command (`/api-sync [scope]`, scope optional, akzeptiert auch `implement`), der den Workflow ausführt. Frontmatter: `description` + `argument-hint`. Schritte: 1. **Diff** - führe `npm run sync:api` aus, lies `api-spec/CHANGES.md`. Weise auf die zwei Ermessensentscheidungen hin, die der Bericht flaggen, aber nicht entscheiden kann: Ein geänderter **Request-Body** an einer Live-Call-Site ist umsetzbar, auch ohne Schema-Spiegel (wir bauen Bodies von Hand), und ein neuer **`error_code`** ist ein Zweig, den wir noch nicht haben - wenn es ein Feld-Fehler ist, muss er inline am Feld gerendert werden, nicht nur als Toast. Wenn der Bericht keine Änderungen meldet, sag das und stoppe - erfinde keine Arbeit. 2. **Klassifiziere jedes Element** in: Brechend (P0) · Still falsch - ein gespiegeltes Schema hat ein Pflichtfeld gewonnen oder ein Enum hat Werte gewonnen, die unser Validator ablehnt (P0) · Jetzt-unvollständig - ein handgebauter Request-Body hat ein Feld gewonnen, oder ein neuer `error_code`, auf den wir nicht verzweigen (P1) · Ent-mockt einen Screen (P1) · Erweitert einen Screen (P2) · Net-neues Feature (P3) · Nur-Backend (verwerfen). Überspringe nie ein Element; wenn es nirgendwo passt, liste es als offene Frage. Verifiziere jede Klassifizierung gegen den Code, statt anzunehmen - öffne die benannte Spiegel-Datei, grep nach dem Mock-Fixture, bestätige, dass der Screen existiert. 3. **Schreibe den Plan** - einen datierten Abschnitt in `ROADMAP.md` (oder das Äquivalent dieses Repos; erstelle einen, wenn keiner existiert), geordnet nach diesen Prioritäten und phasiert, sodass jede Phase unabhängig ausgeliefert wird. Pro Element: die Endpunkte und Dateien, die sich ändern, was der Benutzer danach tun kann, das er heute nicht kann (der Punkt der Arbeit - nicht "Endpunkt X verdrahten"), und ob es blockiert ist und von wem. Eine Zeile pro Element. Aktualisiere dann alle Coverage-/Tracker-Dokumente, die dieses Repo führt. 4. **Berichte im Chat zurück** - was das Backend in einem einfachen Absatz geliefert hat, alles, was gerade kaputt ist, mit der zu fixenden Datei, die Phasen je eine Zeile, und echte Fragen nur an den Backend-Dev. Stopp dort; nur wenn das Argument `implement` enthält, baue **nur Phase 1**, führe dann Typecheck + Lint dieses Repos aus und berichte, bevor du fortfährst. ## Teil 3 - Verdrahte es - Füge die Gitignore-Einträge hinzu. - Füge einen kurzen **Backend-Änderungs-Workflow**-Abschnitt zu `CLAUDE.md` hinzu (erstelle ihn, wenn fehlend): Der Snapshot ist lokal und gitignored, `CHANGES.md` ist der committete Nachweis, `CHANGES.md` ist generiert, also nie von Hand bearbeiten, `/api-sync` wenn der Backend-Dev sagt, dass etwas geliefert wurde, `npm run sync:api -- --check` zur Erkennung von Abweichungen, und die Gewohnheit, vor einer großen Backend-Änderung eine datierte `api-spec/openapi-YYYY-MM-DD.yaml` als committeten Referenzpunkt zu archivieren. - Seede den Snapshot, indem du das Skript einmal ausführst, und zeig mir den ersten Bericht - plus eine einzeilige Notiz, woher die Spec stammt und, wenn du von einer Cache-Kopie geseedet hast, wie veraltet sie war.