Fluxo de trabalho de sincronização de spec OpenAPI com relatório de diff e comando /api-sync

# Configure um fluxo de sincronização de spec OpenAPI neste projeto Quero o mesmo fluxo de trabalho de backend-spec que uso em outro repositório: um script que compara a spec OpenAPI ao vivo com um snapshot local e escreve um relatório de mudanças **orientado ao frontend**, além de um comando slash `/api-sync` que transforma esse relatório em um plano em fases. Preencha estes itens a partir do repositório antes de começar (pergunte-me apenas se não conseguir descobrir): - **Fonte da spec**: encontre você mesmo - veja a Parte 0. Não me pergunte pela URL até ter procurado. O que você encontrar vira o padrão do script, substituível via variável de ambiente `OPENAPI_URL`. - **Caminho do snapshot**: `api-spec/openapi.yaml` · **Caminho do relatório**: `api-spec/CHANGES.md` - **Raiz do código-fonte para referência cruzada**: `src/` (ajuste conforme a estrutura deste repositório) - **Biblioteca de validação de resposta**: zod (ajuste se este repositório usar outra coisa) - **Snapshot no git?** Mantenha o yaml **no gitignore** (grande demais/ruidoso para o histórico), mas **faça commit de `CHANGES.md`** - o relatório gerado é o registro durável do que mudou e quando. Também ignore `api-spec/openapi-*.yaml` e `api-spec/CHANGES-*.md` (arquivos manuais com data). Leia este repositório primeiro (gerenciador de pacotes, convenções de script, como chamadas de API e schemas de resposta são escritos) e siga o estilo dele. Não invente caminhos - use grep para encontrar os reais. --- ## Parte 0 - encontre a spec antes de escrever qualquer coisa Faça isso primeiro e me diga o que encontrou. Não adivinhe uma URL, e não me pergunte até que esta busca retorne vazio. **1. A documentação - o lugar mais barato, e geralmente o correto.** `README.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, qualquer coisa em `docs/`, `.github/`, `.cursor/rules/`, um arquivo de rascunho `*.http`/`*.rest`, ou um checkout do wiki. A URL costuma estar em prosa ("API docs: …/swagger"), em uma etapa de configuração, ou ao lado do link do repositório do backend: ```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 ``` Dois detalhes: um **link do Swagger UI** (`…/swagger-ui/index.html`, `…/docs`, `…/redoc`) é uma página HTML, não a spec - derive a URL de máquina a partir dele (`/swagger-ui/index.html` → `/v3/api-docs`, `/docs` → `/openapi.json`, `/redoc` → o `spec-url` no HTML dele) e verifique com curl. E uma URL de documentação pode estar **desatualizada** - confirme se ela responde antes de adotá-la, e me avise se o README apontar para algo morto. **2. Um arquivo de spec já no repositório ou próximo dele** - alguém geralmente deixou uma cópia: ```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' ``` Também verifique `node_modules/.cache/`, `.next/cache/`, `dist/`, `build/`, `coverage/` e qualquer pasta `api/`, `api-spec/`, `docs/`, `schemas/` no gitignore - uma execução anterior de codegen geralmente deixou uma cópia lá. Uma cópia em cache desatualizada ainda é útil: é uma **base para semear o snapshot**, para que o primeiro diff real seja significativo em vez de "tudo é novo". Se encontrar uma, diga a idade dela (`git log -1` / mtime do arquivo) antes de decidir confiar nela. **3. Uma configuração de gerador que já nomeia a fonte** - este é o hit de maior sinal, porque aponta para a URL ou caminho que o time realmente usa: ```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 ``` Procure especificamente por: config de `openapi-typescript` / `orval.config.*` / `kubb.config.*` / `swagger-typescript-api` / `@hey-api/openapi-ts`, um script npm com cara de `openapi` no package.json, uma URL base de API em `.env*`, URLs de serviço no `docker-compose.yml`, etapas de CI, ou um cliente gerado commitado cujo comentário de cabeçalho cite a spec de origem. **4. Derive a partir da URL base da API.** Se você só encontrar uma URL base, teste os caminhos convencionais para o framework desse backend antes de me perguntar - 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`, além de `/openapi.yaml` e `/swagger.json` simples: ```bash curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json ``` Relate quais responderam. Se todos exigirem autenticação, diga isso - não coloque um token no script. **5. Nada funciona?** Então me pergunte, e me diga o que você descartou. ### Se a spec não estiver acessível via HTTP Não force o design de fetch. Torne a fonte um único `SPEC_SOURCE` que pode ser **uma URL, um caminho local, ou um comando de shell** (ex.: o próprio `make openapi` do repositório do backend, ou o arquivo gerado de um checkout vizinho), resolvido nesta ordem: flag `--to <file>` → env `OPENAPI_URL` → o padrão que você descobriu. Tudo a jusante - diff, relatório, snapshot - fica inalterado. Diga no `CLAUDE.md` qual destes este repositório usa e como atualizá-lo. ## Parte 1 - `scripts/sync-api.mjs` Um script Node ESM único e com poucas dependências (`js-yaml` é a única dependência nova; use o gerenciador de pacotes do repositório). Flags: ``` node scripts/sync-api.mjs busca remoto → diff vs snapshot → escreve relatório + sobrescreve snapshot node scripts/sync-api.mjs --check só diff, snapshot intocado, exit 1 se houver divergência (amigável para CI) node scripts/sync-api.mjs --from <file> diff contra <file> em vez do snapshot node scripts/sync-api.mjs --to <file> trata <file> como "remoto" em vez de buscar (offline) node scripts/sync-api.mjs --json também imprime o diff bruto como JSON no stdout ``` Adicione `"sync:api": "node scripts/sync-api.mjs"` ao package.json. **Se ainda não existir snapshot**: escreva a spec buscada como snapshot, imprima "seeded - re-run after the backend ships to see a diff", exit 0. Nunca relate a API inteira como "nova". Exceção: se a Parte 0 encontrou uma spec em cache/vendada mais antiga, semeie o snapshot a partir **dela** e rode um diff real contra a spec ao vivo na primeira execução - me diga a data da cópia em cache para eu saber o que a base significa. ### O que ele deve comparar Achate `paths` em um mapa de operação `"GET /a/b"` → e compare operações *e* `components.schemas` separadamente: **Operações** - adicionadas / removidas / alteradas - params: novos (marque `required`), flips de required↔opcional, valores de enum adicionados/removidos - identifique um param por `in:name` (ou `ref:Name` para params `$ref`), não por índice de array - schema do corpo da requisição e da resposta de sucesso: se o nome do `$ref` mudou, relate o rename; se a forma for **inline** (sem `$ref`), compare as propriedades aqui - um schema sem nome é comparado aqui ou em lugar nenhum. Resolva wrappers `allOf: [$ref]` para o nome subjacente, e renderize uniões `oneOf`/`anyOf` como `A | B` (ganhar/perder um membro de união é uma mudança comportamental real). - códigos de status não-2xx novos/removidos - mudanças em requisitos de segurança, recém `deprecated` **Schemas** - propriedades adicionadas (marque required) / removidas / com tipo alterado - valores de enum adicionados ou removidos (no schema e em cada propriedade, incluindo `items.enum`) - flips de required↔opcional ### As duas coisas que fazem este relatório valer a pena 1. **Extração de `error_code` a partir da prosa das respostas.** Códigos de erro de máquina geralmente não são documentados em lugar nenhum exceto no texto `description` de cada resposta não-2xx ("… already an active member (already_member)"), então um novo branch que precisamos tratar parece *nada mudou* para um diff em nível de schema. Analise-os por **contexto, não vocabulário**: tokens dentro de `(...)`, tokens após prosa com cara de `error_code`, e qualquer token snake_case que apareça em um enum literal de `error_code` de algum schema. **Não** filtre tokens que colidem com nomes de campos ou valores de enum - essas colisões são exatamente os códigos que mais importam. Descarte tokens introduzidos pela frase "campo X" (esses são nomes de campos, não códigos). Relate códigos adicionados, e para um código que deixou de ser documentado, use grep no código-fonte por `"esse_codigo"` e diga **qual arquivo faz branch nele** - esse é um branch morto. 2. **Referência cruzada de cada mudança contra o código real.** Carregue cada arquivo-fonte uma vez via `git ls-files --cached --others --exclude-standard <raiz do src>` (inclua não-rastreados para que um call site adicionado nesta sessão conte; pule arquivos listados mas excluídos da árvore de trabalho), então: - **Call sites** para um caminho: transforme path params em wildcards de segmento único e exija que a correspondência termine em aspas/backtick/`?` para que `/orgs/{id}` não corresponda a `/orgs/${id}/archive`. Toda operação removida/alterada lista seus call sites, ou "⛔ no call site". - **Espelhos de schema**: encontre o arquivo que contém nosso espelho de validação de resposta de um schema da spec - corresponda `fooBarSchema` em qualquer lugar, além do nome PascalCase puro **apenas dentro de um `schemas.ts`** (em outros lugares ele colide com identificadores TS não relacionados). Adapte a convenção de nomenclatura para o que este repositório realmente usa - use grep primeiro. - Uma operação nova cujo caminho já é referenciado em `src/` recebe uma nota "⚠️ path already referenced - check the method". ### Formato do relatório (`api-spec/CHANGES.md`) Cabeçalho com data de geração, rótulo da base, `info.version` da spec, e contagens de operações e schemas antes→depois; depois uma pequena tabela de adicionados/removidos/alterados; depois seções, nesta ordem: - `## 🔴 Removed operations - breaking if we call them` (com call sites) - `## 🟡 Changed operations` (bullets aninhados por mudança + call sites) - `## 🟢 New operations`, agrupadas por área de caminho (primeiro segmento, com casos especiais sensatos para os prefixos desta API) - resumo, schema de resposta, schema do corpo da requisição - `## 🔴 Removed schemas` (com arquivos espelho) - `## 🟡 Changed schemas` - **os espelhados primeiro, ordenados e em negrito com o arquivo espelho**, já que são os que podem quebrar o parsing hoje; o resto é informativo - `## 🟢 New schemas` (uma linha separada por vírgulas) Se nada mudou, o corpo é exatamente "No changes since the last snapshot." No topo do arquivo, coloque "do not edit by hand". Mantenha o script comentado onde uma decisão não for óbvia (a heurística de error_code, a âncora final do matcher de caminho, por que arquivos não-rastreados são incluídos) - o eu do futuro lê esses comentários. ## Parte 2 - `.claude/commands/api-sync.md` Um comando slash (`/api-sync [scope]`, scope opcional, também aceita `implement`) que executa o fluxo de trabalho. Frontmatter: `description` + `argument-hint`. Etapas: 1. **Diff** - rode `npm run sync:api`, leia `api-spec/CHANGES.md`. Destaque as duas decisões que o relatório pode sinalizar mas não decidir: um **corpo de requisição** alterado em um call site ativo é acionável mesmo sem espelho de schema (construímos corpos manualmente), e um novo **`error_code`** é um branch que ainda não temos - se for um erro de campo, ele deve ser renderizado inline no campo, não apenas como um toast. Se o relatório disser que não há mudanças, diga isso e pare - não invente trabalho. 2. **Classifique cada item** em: Breaking (P0) · Silenciosamente errado - um schema espelhado ganhou um campo required ou um enum cresceu com valores que nosso validador rejeita (P0) · Agora-incompleto - um corpo de requisição construído manualmente ganhou um campo, ou um novo `error_code` no qual não fazemos branch (P1) · Des-mocka uma tela (P1) · Estende uma tela (P2) · Feature totalmente nova (P3) · Somente-backend (descarte). Nunca pule um item; se não se encaixar em lugar nenhum, liste-o como uma pergunta em aberto. Verifique cada classificação contra o código em vez de assumir - abra o arquivo espelho nomeado, use grep para a fixture de mock, confirme que a tela existe. 3. **Escreva o plano** - uma seção datada em `ROADMAP.md` (ou o equivalente deste repositório; crie um se não houver), ordenada por essas prioridades e em fases para que cada fase seja entregue de forma independente. Por item: os endpoints e arquivos que mudam, o que o usuário pode fazer depois que não podia antes (o ponto do trabalho - não "conectar endpoint X"), e se está bloqueado e por quem. Uma linha por item. Depois atualize os docs de cobertura/tracker que este repositório mantém. 4. **Reporte de volta no chat** - o que o backend entregou em um parágrafo em linguagem simples, qualquer coisa quebrada agora com o arquivo para corrigir, as fases em uma linha cada, e perguntas genuínas apenas para o dev do backend. Pare aí; somente se o argumento contiver `implement`, construa **apenas a Fase 1**, depois rode o typecheck + lint deste repositório e reporte antes de continuar. ## Parte 3 - integre tudo - Adicione as entradas de gitignore. - Adicione uma seção curta **Backend-change workflow** ao `CLAUDE.md` (crie se estiver faltando): o snapshot é local e está no gitignore, `CHANGES.md` é o registro commitado, `CHANGES.md` é gerado então nunca edite manualmente, `/api-sync` quando o dev do backend disser que algo foi entregue, `npm run sync:api -- --check` para detectar divergência, e o hábito de arquivar um `api-spec/openapi-YYYY-MM-DD.yaml` datado antes de uma grande mudança de backend como ponto de referência commitado. - Semeie o snapshot rodando o script uma vez, e me mostre o primeiro relatório - além de uma nota de uma linha sobre de onde a spec veio e, se você semeou a partir de uma cópia em cache, o quão desatualizada ela estava.