OpenAPI spec-sync वर्कफ़्लो जिसमें diff रिपोर्ट और /api-sync कमांड शामिल है

# इस प्रोजेक्ट में OpenAPI स्पेक-सिंक वर्कफ़्लो सेट अप करें मुझे वही बैकएंड-स्पेक वर्कफ़्लो चाहिए जो मैं दूसरे रेपो में उपयोग करता हूं: एक स्क्रिप्ट जो लाइव OpenAPI स्पेक को लोकल स्नैपशॉट के साथ डिफ करती है और एक **फ्रंटएंड-ओरिएंटेड** चेंज रिपोर्ट लिखती है, साथ ही एक `/api-sync` स्लैश कमांड जो उस रिपोर्ट को फेज़्ड प्लान में बदल देता है। शुरू करने से पहले रेपो से ये भरें (केवल मुझसे पूछें यदि आप इसे समझ नहीं सकते): - **स्पेक स्रोत**: इसे स्वयं खोजें - भाग 0 देखें। देखने से पहले मुझसे URL न पूछें। जो भी मिले वह स्क्रिप्ट का डिफ़ॉल्ट बन जाता है, `OPENAPI_URL` env var के माध्यम से ओवरराइड करने योग्य। - **स्नैपशॉट पथ**: `api-spec/openapi.yaml` · **रिपोर्ट पथ**: `api-spec/CHANGES.md` - **क्रॉस-रेफरेंस के लिए स्रोत रूट**: `src/` (इस रेपो के लेआउट के अनुसार समायोजित करें) - **रेस्पॉन्स-वैलिडेशन लाइब्रेरी**: zod (यदि यह रेपो कुछ और उपयोग करता है तो समायोजित करें) - **गिट में स्नैपशॉट?** YAML को **गिटिग्नोर** रखें (इतिहास के लिए बहुत बड़ा/शोरगुल वाला) लेकिन **`CHANGES.md` को कमिट** करें - जेनरेट की गई रिपोर्ट क्या और कब बदला इसका स्थायी रिकॉर्ड है। साथ ही `api-spec/openapi-*.yaml` और `api-spec/CHANGES-*.md` (दिनांकित मैनुअल आर्काइव) को इग्नोर करें। पहले यह रेपो पढ़ें (पैकेज मैनेजर, स्क्रिप्ट कन्वेंशन, API कॉल और रेस्पॉन्स स्कीमा कैसे लिखे जाते हैं) और इसकी शैली से मेल खाएं। पाथ का आविष्कार न करें - वास्तविक के लिए grep करें। --- ## भाग 0 - कुछ भी लिखने से पहले स्पेक खोजें पहले यह करें और मुझे बताएं कि आपको क्या मिला। URL का अनुमान न लगाएं, और जब तक यह खाली न आए तब तक मुझसे न पूछें। **1. दस्तावेज़ - सबसे सस्ती जगह, और आमतौर पर सही।** `README.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `docs/` के अंतर्गत कुछ भी, `.github/`, `.cursor/rules/`, एक `*.http`/`*.rest` स्क्रैच फ़ाइल, या एक wiki चेकआउट। URL अक्सर गद्य में होता है ("API docs: …/swagger"), एक सेटअप चरण में, या बैकएंड रेपो लिंक के बगल में: ```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 ``` दो समस्याएं: एक **Swagger UI लिंक** (`…/swagger-ui/index.html`, `…/docs`, `…/redoc`) एक HTML पेज है, स्पेक नहीं - इससे मशीन URL प्राप्त करें (`/swagger-ui/index.html` → `/v3/api-docs`, `/docs` → `/openapi.json`, `/redoc` → इसके HTML में `spec-url`) और curl से सत्यापित करें। और एक docs URL **पुराना** हो सकता है - अपनाने से पहले पुष्टि करें कि यह उत्तर देता है, और मुझे बताएं कि क्या README किसी मृत स्थान की ओर इशारा करता है। **2. रेपो में या उसके पास पहले से एक स्पेक फ़ाइल** - आमतौर पर किसी ने एक वेंडर किया होता है: ```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' ``` साथ ही `node_modules/.cache/`, `.next/cache/`, `dist/`, `build/`, `coverage/` और किसी भी गिटिग्नोर किए गए `api/`, `api-spec/`, `docs/`, `schemas/` फ़ोल्डर की जांच करें - पिछला कोडजेन रन अक्सर वहां एक कॉपी छोड़ देता है। एक पुरानी कैश्ड कॉपी अभी भी उपयोगी है: यह स्नैपशॉट को सीड करने के लिए एक **बेसलाइन** है, ताकि पहला वास्तविक डिफ "सब कुछ नया है" के बजाय सार्थक हो। यदि कोई मिले, तो भरोसा करने का निर्णय लेने से पहले बताएं कि यह कितना पुराना है (`git log -1` / फ़ाइल mtime)। **3. एक जेनरेटर कॉन्फ़िग जो पहले से स्रोत का नाम बताता है** - यह सबसे अधिक सिग्नल वाला हिट है, क्योंकि यह उस URL या पाथ की ओर इशारा करता है जिसे टीम वास्तव में उपयोग करती है: ```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 ``` विशेष रूप से देखें: `openapi-typescript` / `orval.config.*` / `kubb.config.*` / `swagger-typescript-api` / `@hey-api/openapi-ts` कॉन्फ़िग, package.json में एक `openapi`-जैसी npm स्क्रिप्ट, एक `.env*` API बेस URL, `docker-compose.yml` सेवा URL, CI वर्कफ़्लो चरण, या एक कमिटेड जेनरेटेड क्लाइंट जिसकी हेडर टिप्पणी अपने स्रोत स्पेक का उल्लेख करती है। **4. इसे API बेस URL से प्राप्त करें।** यदि आपको केवल एक बेस URL मिलता है, तो मुझसे पूछने से पहले उस बैकएंड के फ्रेमवर्क के लिए पारंपरिक पाथ की जांच करें - 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`, साथ ही सादा `/openapi.yaml` और `/swagger.json`: ```bash curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json ``` रिपोर्ट करें कि कौन से उत्तर दिए। यदि सभी को प्रमाणीकरण की आवश्यकता है, तो कहें - स्क्रिप्ट में टोकन न डालें। **5. कुछ भी काम नहीं करता?** फिर मुझसे पूछें, और बताएं कि आपने क्या खारिज किया। ### यदि स्पेक HTTP पर पहुंच योग्य नहीं है फ़ेच डिज़ाइन को बल न दें। स्रोत को एकल `SPEC_SOURCE` बनाएं जो **URL, स्थानीय पाथ, या शेल कमांड** हो सकता है (जैसे बैकएंड रेपो का अपना `make openapi`, या सहोदर चेकआउट की जेनरेटेड फ़ाइल), इस क्रम में हल किया गया: `--to <file>` फ़्लैग → `OPENAPI_URL` env → आपके द्वारा खोजा गया डिफ़ॉल्ट। नीचे की सब चीज़ें - डिफ, रिपोर्ट, स्नैपशॉट - अपरिवरत् हैं। `CLAUDE.md` में बताएं कि यह रेपो कौन सा स्ोत उपयोग करता है और उसे कैस रीफ्रेश करन ा है। ## भाग 1 - `scripts/sync-api.mjs` एक हल्का-डिपेंडेंसी Node ESM स्क्रिप्ट (`js-yaml` एकमात्र नया डिप है; रेपो के पैकेज मैनेजर क उपयोग करें)। फ्लैग: ``` node scripts/sync-api.mjs रिमोट फैच करें → स्नैपशॉट क साथ डिफ करें → रिपोर्ट लिखें + स्नैपशॉट ओवरराइट करें node scripts/sync-api.mjs --check कवल डिफ, स्नैपशॉट अछुआ, डिफट होन पर एग्ज़िट 1 (CI-फ्रेंडल) node scripts/sync-api.mjs --from <file> स्नैपशॉट क बजाए <file> क साथ डिफ करें node scripts/sync-api.mjs --to <file> फैच करन क बजाए <file> क "रिमोट" मानें (ऑफलाइन) node scripts/sync-api.mjs --json स्टडआउट पर कच्चा डिफ JSON के रूप में भी प्रिंट करें ``` package.json में `"sync:api": "node scripts/sync-api.mjs"` जोड़ें। **यद क ई स्नैपशॉट मौजूद नहीं**: फैच क गई स्पेक क स्नैपशॉट क रूप म लिखें, "सीडेड - बैकएंड शिप करन क बाद दोबारा चलाएं ताक डिफ दिखे" प्रिंट करें, एग्ज़िट 0। पूर एपी क "नय" क रूप म कभ न रिपोर्ट करें। अपवाद: यद भाग 0 म पुरान स्पेक मिला ह, तो उसक बजाए उस स्नैपशॉट क सीड करें और पहल रन म लाइव स्पेक क साथ वास्तवक डिफ चलाएं - मुझ कैश्ड कॉपी क तारीख बताएं ताक मुझ जानू क बेसलाइन क मतलब क्या है। ### उसे क्या डिफ करन चा हिए `paths` क `"GET /a/b"` → ऑपरेशन मैप म फ्लैट करें और ऑपरेशन *और* `components.schemas` क अलग-अलग डिफ करें: **ऑपरेशन** - जोड़े / हटाए / बदले - पैराम: नए (फ्लैग `required`), आवश्यक↔ वैकल्पिक फ्लिप, एनुम मान जोड़े/हटाए - पैराम क `in:name` (य `ref:Name` `$ref` पैराम क लिए) स कुंजी दें, ऐरै इंडेक् स नहीं - रिक्वेस्ट बॉड और सफल-रिस्पॉन्स स्कीमा: यद `$ref` नाम बदल ह, रिनेम क रिपोर्ट करें; यद शेप **इनलाइन** है (क ई `$ref` नहीं), उसक प्रॉपटीज़ क यहां डिफ करें - एक अनामेड स्कीमा क यहां य कहीं नहीं डिफ किया जाता। `allOf: [$ref]` रैपरज़ क अंतग़ित नाम म हल करें, और `oneOf`/`anyOf` युनियन क `A | B` क रूप म रेंडर करें (युनियन सदसय क जोड़न/हटाना एक वास्तविक व्ावहारिक परिवर्तन है)। - नए/हटाए गए गैर-2xx स्टैटस कड - सिक्योरिटी आवश्यकताएं परिवर्तन, नई `deprecated` **स्कीमा** - प्रॉपटीज़ जोड़ी गईं (आवश्यक चिह्नित करें) / हटाई गईं / रीटाइप की गईं - एनम मान जोड़े या हटाए (स्कीमा पर और प्रत्येक प्रॉपटी पर, `items.enum` सहित) - आवश्यक↔वैकल्पिक फ्लिप ### दो चीजें जो इस रिपोर्ट को मूल्यवान बनाती हैं 1. **रेस्पॉन्स गद्य से `error_code` निष्कर्षण।** मशीन एरर कोड आमतौर पर कहीं भी प्रलेखित नहीं होते हैं लेकिन प्रत्येक गैर-2xx रेस्पॉन्स के `description` टेक्स्ट में ("… पहले से एक सक्रिय सदसय (already_member)"), इसलिए एक नई शाखा जिसे हमें संभालन क जरूरत है स्कीमा-स्तर डिफ क लिए *कछ बदल नहीं* दिखती है। उनहें **संदभ क अनुसार पारस करें, शबदावली स नहीं**: टोकन `(...)` क अंदर, `error_code`-जैसी गदय क बाद क टोकन, और क ई snake_case टोकन जो किसी स्कीमा क शाब्दिक `error_code` एनम म दिखाई देत है। उन टोकन को फ़लटर न करें जो फीलड नाम य एनम वैलयू क साथ टकरात ह - वे टकरालीसें ठीक वे कोड हैं जो सबस जयाद मायने रखत हैं। "फीलड X" वाकयांश स पेश किए गए टोकन क छोड़ दें (वे फीलड नाम हैं, कोड नहीं)। जोड़े गए कोड क रिपोर्ट करें, और एक कोड क लिए जो दस्तावेजीकरण बंद हो गय है, स्रोत म `"that_code"` क लिए grep करें और बताएं **कौन सी फ़ाइल उस पर ब्रांच करती है** - वह एक मृत ब्रांच है। 2. **हर परिवर्तन क वास्तविक कोड क साथ क्रॉस-रेफरेंस करें।** `git ls-files --cached --others --exclude-standard <src root>` क माध्यम स हर स्रोत फ़ाइल क एक बार लोड करें (अनट्रैकड सभी शामिल करें ताक इस सेशन म जोड़ा गय कॉल साइट गिनत ह; सूचीबदध लेकिन वकंग ट्री स हटाई गई फ़ाइलें छोड़ दें), फिर: - एक पाथ क लिए **कॉल साइटस**: पाथ पैराम क सिंगल-सेगमेंट वाइडकाडड म बदलें और मैच क एक क्वोट/बैकटिक/`?` पर समाप्त होन क आवश्यकता रखें ताक `/orgs/{id}` `/orgs/${id}/archive` स मैच न हो। हर हटाया/बदल गय ऑपरेशन अपन कॉल साइटस सूचीबदध करत ह, य " नहीं कॉल साइट"। - **स्कीमा मिररर**: वह फ़ाइल ढूंढें जिसमें स्पेक स्कीमा का हमारा रेस्पॉन्स-वैलिडेशन मिरर ह - `fooBarSchema` कहीं भी मैच करें, साथ ही नंगा PascalCase नाम **केवल `schemas.ts` क अंदर** (अन्यथा यह असंबंधित TS पहचानकरों स टकरात ह)। नामकरण परंपरा क इस रेपो क वास्तविक उपयोग क अनुसार अनुकूलित करें - पहले grep करें। - एक नया ऑपरेशन जिसक पाथ पहले स `src/` म संदभित ह, उसे "⚠️ पाथ पहले स संदभित - मेथड क जांच करें" नोट मिलत ह। ### रिपोर्ट प्रारूप (`api-spec/CHANGES.md`) जेनरेशन तारीख, बेसलाइन लेबल, स्पेक `info.version`, और पहले→बाद ऑपरेशन और स्कीमा गिनती क साथ हेडर; फिर एक छोटी जोड़ी/हटाई/बदली तालिका; फिर सेक्शन, इस क्रम म: - `## 🔴 रिमोवेड ऑपरेशन - ब्रैकिंग यदि हम उन्हें कॉल करते हैं` (कॉल साइट्स के साथ) - `## 🟡 चेंजड ऑपरेशन्स` (प्रति चेंज नेस्टेड बुलेट्स + कॉल साइट्स) - `## 🟢 नए ऑपरेशन`, पाथ क्षेत्र द्वारा समूहीकृत (पहला सेगमेंट, इस API के उपसर्गों के लिए समझदार विशेष मामलों के साथ) - सारांश, रेस्पॉन्स स्कीमा, रिक्वेस्ट-बॉडी स्कीमा - `## 🔴 रिमूव्ड स्कीमास` (मिरर फाइलों के साथ) - `## 🟡 चेंजड स्कीमास` - **मिरर की गई पहले सॉर्ट की गई और मिरर फाइल के साथ बोल्ड**, क्योंकि वे आज पार्सिंग तोड़ सकती हैं; बाकी सूचनात्मक हैं - `## नई स्कीमा` (एक कॉमा-सेपरेटेड लाइन) यदि कुछ नहीं बदला, तो बॉडी बिल्कुल "पिछले स्नैपशॉट के बाद से कोई बदलाव नहीं।" है। फाइल के शीर्ष पर "हाथ से संपादित न करें" लिखें। स्क्रिप्ट को टिप्पणी रखें जहां निर्णय गैर-स्पषट ह (एरर_कोड हीरिस्टिक, पाथ मैचर का एंड एंकर, अनट्रैक्ड फाइलें कयों शामिल हैं) - भविष्य-में वह पढ़ता है। ## भाग 2 - `.claude/commands/api-sync.md` एक स्लैश कमांड (`/api-sync [scope]`, स्कोप वैकल्पिक, `implement` भी स्वीकरत है) जो वर्कफ़्लो चलाता है। फ्रंटमैटर: `description` + `argument-hint`। चरण: 1. **डिफ** - `npm run sync:api` चलाएं, `api-spec/CHANGES.md` पढ़ें। दो निर्णय कॉल बताएं जो रिपोर्ट फ्लैग कर सकत है लेकिन तय नहीं कर सकता: एक बदला हुआ **रिक्वेस्ट बॉडी** एक लाइव कॉल साइट पर कार्रवाई योग्य है भले ही कोई स्कीमा मिरर न हो (हम बॉडीज हाथ स बनाते हैं), और एक नया **`error_code`** एक शाखा है जो हमारे पास अभी नहीं है - यदि यह एक फील्ड त्रुटि है तो इसे फील्ड पर इनलाइन रेंडर होना चाहिए, न कि केवल एक टोस्ट के रूप में। यदि रिपोर्ट कोई बदलाव नहीं कहती है, तो कहें और रुकें - काम का आविष्कार न करें। 2. **हर आइटम को वर्गीकृत करें**: ब्रेकिंग (P0) · साइलेंटली गलत - एक मिरर की गई स्कीमा ने एक आवश्यक फील्ड प्राप्त किया या एक एनम ने मान बढ़ाए जो हमारा वैलिडेटर अस्वीकार करता है (P0) · अब-अपूर्ण - एक हाथ से बनाया गया रिक्वेस्ट बॉडी ने एक फील्ड प्राप्त किया, या एक नया `error_code` जिस पर हम शाखा नहीं करते (P1) · अन-मॉक्स ए स्क्रीन (P1) · एक्सटेंड्स ए स्क्रीन (P2) · नेट-न्यू फीचर (P3) · बैकएंड-ओनली (ड्रॉप)। कभी भी किसी आइटम को स्किप न करें; यद यह कहीं फिट नहीं होता, तो इसे एक खुले प्रश्न के रूप में सूचीबद्ध करें। कोड के खिलाफ प्रत्येक वर्गीकरण को सत्यापित करें न कि मानकर - नामित मिरर फाइल खोलें, मॉक फिक्स्चर के लिए grep करें, पुष्टि करें कि स्क्रीन मौजूद है। 3. **प्लान लिखें** - `ROADMAP.md` में एक दिनांकित अनुभाग (या इस रेपो के समकक्ष; यदि कोई नहीं है तो एक बनाएं), उन प्राथमिकताओं क अनुसार क्रमबदध और फेज्ड ताक प्रतयेक फेज सवतंत्र रूप स शिप हो। प्ार ट आइटम: वे एंडपॉइंट्स और फाइलें जो बदलती हैं, उपयोगकर्ता बाद में क्या कर सकता है जो आज नहीं कर सकता (काम क बिंदु - "वायर एंडपॉइंट X" नहीं), और क्या यह अवरुदध है और किस पर। प्ार ट आइटम एक लाइन। फिर इस रेपो क रखे जाने वाले कवरेज/ट्रैकर दस्तावेजों को अपडेट करें। 4. **चैट में रिपोर्ट करें** - बैकएंड ने एक सादे-भाषा पैराग्राफ में क्या भेजा, अभी कुछ भी टूटा हुआ है जिसे ठीक करने के लिए फाइल है, चरण एक लाइन प्रत्येक, और बैकएंड डेव क लिए केवल वास्तविक प्रश्न। वहीं रुकें; केवल यदि तर्क में `implement` है, तो **केवल चरण 1** बनाएं, फिर इस रेपो का टाइपचेक + लिंट चलाएं और जारी रखने से पहले रिपोर्ट करें। ## भाग 3 - इसे वायर करें - गिटिग्नोर प्रविष्टियां जोड़ें। - `CLAUDE.md` में एक छोटा **बैकएंड-चेंज वर्कफ्लो** अनुभाग जोड़ें (यदि गायब है तो बनाएं): स्नैपशॉट स्थानीय और गिटिग्नोर है, `CHANGES.md` प्रतिबद्ध रिकॉर्ड है, `CHANGES.md` जेनरेट किया गया है इसलिए इसे कभी हाथ से संपादित न करें, `/api-sync` जब बैकएंड डेव कहता है कि कुछ भेज दिया गया है, `npm run sync:api -- --check` ड्रिफ्ट का पता लगाने के लिए, और एक बड़े बैकएंड परिवर्तन से पहले एक दिनांकित `api-spec/openapi-YYYY-MM-DD.yaml` को संदर्भ बिंदु के रूप में संग्रहीत करने की आदत। - स्क्रिप्ट को एक बार चलाकर स्नैपशॉट को सीड करें, और मुझे पहली रिपोर्ट दिखाएं - साथ ही एक-लाइन नोट कि स्पेक कहां से आया और, यदि आपने कैश्ड कॉपी से सीड किया, तो वह कितनी पुरानी थी।