Pular para o conteúdo principal

Workflow de Release — SDK

Guia end-to-end para alterar pacotes @cactus-agents/*, publicar novas versões e atualizar os consumidores.

Visão geral​

front-cactus-core (SDK)              front-web-base (consumidor)
┌────────────────────────┐           ┌───────────────────────┐
│ 1. Alterar código      │           │                       │
│ 2. Rodar testes        │           │                       │
│ 3. Criar changeset     │           │                       │
│ 4. Commit + push main  │           │                       │
│         │              │           │                       │
│         ▼              │           │                       │
│ 5. CI cria PR versão   │           │                       │
│ 6. Merge PR            │           │                       │
│         │              │           │                       │
│         ▼              │           │                       │
│ 7. CI publica no       │──────────▶│ 8. pnpm update        │
│    GitHub Packages     │           │ 9. Testar + commit    │
└────────────────────────┘           └───────────────────────┘

Regra de ouro: sempre publicar o SDK primeiro, depois atualizar consumidores.

Passo a passo​

1. Alterar e testar​

cd front-cactus-core
# fazer alterações nos pacotes
pnpm build
pnpm test

2. Criar changeset​

pnpm changeset

O CLI interativo pede:

  1. Quais pacotes foram alterados — selecionar com espaço
  2. Tipo de bump — patch / minor / major
  3. Descrição — resumo da mudança (aparece no CHANGELOG)

O changeset gera um arquivo .md em .changeset/ que deve ser commitado.

Quando usar cada bump​

TipoQuando usarExemplo
patchBug fix, melhoria interna sem mudar APICorrigir header faltando
minorNova funcionalidade, novo export (backwards compatible)Adicionar createAuthFromClient
majorBreaking change — assinatura mudou, export removidoRenomear createBrandConfig para outra coisa
dica

Para 0.x.y, semver trata minor como potentially breaking. Na prática, usamos minor para features novas e patch para fixes.

3. Commit e push​

git add .
git commit -m "feat: descrição da mudança"
git push origin main

Ou, se preferir separar o changeset:

git add packages/
git commit -m "feat: descrição da mudança"
git add .changeset/
git commit -m "chore: add changeset"
git push origin main

4. CI cria PR de versão​

O workflow release.yml detecta changesets pendentes e cria um PR automático:

  • Título: "chore: version packages"
  • Conteúdo: bump de versão nos package.json + CHANGELOG atualizado
  • Branch: changeset-release/main

5. Revisar e mergear o PR​

Verificar no PR:

  • As versões foram bumpadas corretamente
  • O CHANGELOG reflete as mudanças

Ao mergear, o CI executa pnpm run release que builda e publica os pacotes no GitHub Packages.

6. Atualizar consumidores​

No front-web-base (e qualquer fork):

cd front-web-base

# Atualizar todos os pacotes @cactus-agents
pnpm update @cactus-agents/api-client @cactus-agents/auth @cactus-agents/brand @cactus-agents/types @cactus-agents/utils

# Verificar
pnpm build
pnpm dev    # testar fluxos principais

# Commit
git add pnpm-lock.yaml package.json
git commit -m "chore: bump @cactus-agents/* to 0.x.0"
git push origin main

Desenvolvimento local (sem publicar)​

Para iterar rapidamente entre SDK e base sem passar pelo ciclo de publish, não precisa linkar nada manualmente. Se o front-cactus-core está clonado ao lado do front-web-base, o Vite / Vitest / tsc do base leem @cactus-agents/* direto do src/*.ts do core via aliases configurados em vite.config.ts, vitest.config.ts e tsconfig.json (paths source-first com fallback pro node_modules quando o core não está clonado).

# Editar o fonte no SDK
#   front-cactus-core/packages/auth/src/types.ts

# Rodar no base — mudanças aparecem via HMR sub-segundo
cd front-web-base
pnpm dev

pnpm typecheck e pnpm test também usam o mesmo resolver — nada quebra entre editar o core e validar no base.

Validar contra o pacote publicado antes de PR​

Antes de abrir PR do base, confirme que a versão publicada do SDK também funciona (caso você esteja consumindo código que ainda não foi released):

cd front-web-base
pnpm dev --registry        # força resolução pelo node_modules (registry)
# ou: CACTUS_FORCE_REGISTRY=1 pnpm dev

Se falhar em --registry mas passar em pnpm dev normal, a mudança no base depende de código do core que ainda não foi publicado — release o core primeiro.

:::caution Nunca commite file: ou link: no package.json O package.json no git sempre mantém as versões do registry (^0.10.0, etc.). Os aliases source-direct são puramente de tempo de resolução — não alteram node_modules nem o lockfile. :::

Troubleshooting​

Pacote não encontrado após publish​

O GitHub Packages pode levar alguns segundos para propagar. Tente:

# Limpar cache do pnpm
pnpm store prune
pnpm install --force

403 Forbidden no CI​

O PAT de leitura (GH_PACKAGES_TOKEN) pode ter expirado. Ver GitHub Packages para instruções de renovação.

Changeset não detectado pelo CI​

Verificar que o arquivo .changeset/*.md foi commitado e está presente no push para main. O workflow release.yml só roda em push para main.

Versão não bumpou​

O PR de versão só é criado quando existem changesets pendentes. Se o PR já existe, ele é atualizado automaticamente com novos changesets.