Release, Changesets 0.1.0 e publicação no Docker Hub #31

Contexto

docs/decisoes-iniciais.md §1 e §4: SemVer a partir de 0.1.0 com Changesets; imagem multi-arch amd64 + arm64 construída no GitHub Actions e publicada em tmsoftbrasil/thinker com os secrets DOCKERHUB_USERNAME/DOCKERHUB_TOKEN, que o usuário cadastra. O CI de PR já existe (#38, #20); falta o caminho de release.

Ordem dos secrets: o usuário só cadastra DOCKERHUB_USERNAME/DOCKERHUB_TOKEN depois que o docker.yml herdado tiver saído (#38) e o docker.yml de publicação desta issue tiver sido revisado. Antes disso, um workflow herdado poderia publicar com eles.

O release.yml herdado usava um GitHub App (APP_ID/APP_PRIVATE_KEY) para que o PR de versão disparasse o CI. Com GITHUB_TOKEN, o PR "Version Packages" não dispara workflows. É preciso escolher: o usuário fecha e reabre o PR de versão a cada release, ou cadastra um PAT fino (RELEASE_TOKEN). Registrar a escolha aqui.

Decisão do mantenedor (2026-10-11): este fluxo de release já nasce com o Changesets 3 e o changesets/action@v2, em vez do Changesets 2 com a action v1. O upgrade sai do v0.2 (antes #88, que ficou só com o resto do alerta 95 do Dependabot), para o release.yml ser escrito uma vez só. O que muda no 3 e importa aqui (CHANGELOG oficial):

• pacotes privados deixam de ser versionados por padrão. Todos os workspaces do Thinker são privados, inclusive packages/thinker; sem privatePackages explícito, o changeset version para de subir a versão do produto em silêncio;
• changeset tag foi renomeado para changeset git-tag;
• changeset version sai com código 1 quando não há changesets;
• o changesets/action@v2 exige o CLI 3. As entradas foram renomeadas para kebab-case (ex.: version → version-script), o github-token é passado como entrada, o push é feito pela API por padrão, e scripts próprios recebem CHANGESETS_OUTPUT;
• Node ^22.11 || ^24 || >=26 e npm >=10.9.0 (o packageManager é npm@10.9.2).

Escopo

• Changesets 3:

  • @changesets/cli em ^3.0 na raiz;
  • packages/thinker na versão 0.1.0, com CHANGELOG.md zerado (sem o histórico do Manifest);
  • todos os workspaces em 0.1.0 (thinker-cli vem de 6.24.0);
  • .changeset/config.json revisado: sem publicação no npm e com "privatePackages": { "version": true, "tag": true } explícito, para que os workspaces privados continuem sendo versionados;
  • remover o override read-yaml-file → js-yaml 3.15.2 do package.json da raiz, que fica morto com o Changesets 3;
  • scripts/check-changesets.js e .changeset/README.md atualizados.

• release.yml: em push na main, o changesets/action@v2 (fixado por SHA, entradas em kebab-case, github-token como entrada) abre o PR de versão. O version-script não chama changeset version quando não há changesets pendentes (no 3 ele sai com código 1). Para a tag, usar changeset git-tag (o antigo changeset tag) ou criá-la no próprio workflow. Quando não houver changesets pendentes e a versão de packages/thinker/package.json ainda não tiver tag:

  • cria a tag vX.Y.Z;
  • cria o GitHub Release com as notas de docs/releases/X.Y.Z.md (PT-BR);
  • chama docker.yml.
    Sem hook de site e sem npm.

• docker.yml (workflow_call/workflow_dispatch):

  • build por plataforma (amd64 em ubuntu-latest, arm64 em ubuntu-24.04-arm), push by digest e merge do manifest list;
  • esquema completo de tags:
    • versão estável X.Y.Z: X.Y.Z, X.Y, latest e sha-<curto>;
    • pré-release X.Y.Z-rc.N: X.Y.Z-rc.N e sha-<curto>, sem mover X.Y nem latest;
    • sha-<curto> = os 7 primeiros caracteres do commit;
    • sem tag só de major enquanto a versão for 0.x;
  • provenance e SBOM; assinatura cosign keyless (mantida do upstream).

• dockerhub-description.yml recriado para tmsoftbrasil/thinker, lendo docker/DOCKER_README.md.

• Guard de nomes legados, scripts/check-legacy-names.js (+ teste): acusa manifest/mnfst fora da allowlist.

  • Entra em modo relatório no ci.yml: lista as ocorrências no resumo do job e não falha. Com --strict, sai com código diferente de 0. Ele não pode bloquear agora, porque o guia do desenvolvedor (Guia do desenvolvedor do Thinker #32) e o README/docs (README e documentação do usuário em PT-BR #33) ainda não foram reescritos.
  • Vira bloqueante só depois de Guia do desenvolvedor do Thinker #32 e README e documentação do usuário em PT-BR #33: o qa-docker roda --strict em Baseline do qa-docker: smoke e e2e da imagem v0.1 #34, e o devops liga --strict no ci.yml no primeiro passo de Release 0.1.0 e primeira imagem no Docker Hub #35.
  • A allowlist tem dois tipos de entrada:
    • arquivos e pastas inteiros:
      • todo arquivo de licença (LICENSE, **/LICENSE*), que mantém o copyright da MNFST, Inc.;
      • upstream/, docs/adr/, docs/decisoes-iniciais.md, CLAUDE.md, docs/agentes.md;
      • docs/referencia/ (artefatos do upstream guardados como insumo, ex.: o PoC de autofix movido em Remover Autofix/Phoenix do backend #16);
      • docs/releases/ (as notas comparam com o Manifest 6.28.6);
      • .claude/agents/ inteiro (o manifest-tracker e as referências ao upstream nos demais agentes);
      • docs/dev/manifest-*.md, só até Guia do desenvolvedor do Thinker #32, que apaga esses arquivos e tira a entrada da allowlist;
      • os arquivos do próprio guard (scripts/check-legacy-names.js, o teste e o arquivo de allowlist, se separado);
      • as migrations até 1803100000000;
    • linhas de atribuição e crédito, em qualquer arquivo: uma linha é aceita quando cita a origem por um destes marcadores: mnfst/llm-gateway, MNFST, Inc/MNFST Inc, manifest@6.28.6 ou "Manifest 6.28.6". Cobre o parágrafo de origem do README, o SECURITY.md ("O Thinker deriva do projeto mnfst/llm-gateway…"), o CONTRIBUTING.md, o docker/DOCKER_README.md e o crédito nas telas de ajuda. O guard tira os marcadores da linha e acusa o que sobrar: uma linha com marcador e outra menção legada (ex.: mnfst_) continua sendo acusada;
    • usos genéricos por linha ("image manifest", "web manifest", "manifest list").

• Validação sem release real: workflow_dispatch com a versão 0.1.0-rc.1 publica tmsoftbrasil/thinker:0.1.0-rc.1 e sha-<curto> sem tocar em 0.1 nem em latest. Antes disso, o usuário cadastra os secrets (na ordem acima) e confirma o repositório no Docker Hub.

• Passo do mantenedor: incluir o SHA do changesets/action@v2 na lista de actions permitidas do repositório.

Fora de escopo

• O release 0.1.0 em si (Release 0.1.0 e primeira imagem no Docker Hub #35).
• Notas de release (escritas em Release 0.1.0 e primeira imagem no Docker Hub #35 pelo docs-ptbr).

Critérios de aceite

• docker buildx imagetools inspect tmsoftbrasil/thinker:0.1.0-rc.1 lista linux/amd64 e linux/arm64; a tag sha-<curto> existe; latest e 0.1 não existem.
• O guard roda em modo relatório no ci.yml sem falhar o job; com --strict, falha num commit de teste que introduza mnfst_ fora da allowlist.
• A escolha entre PAT e fechar/reabrir o PR de versão está registrada nesta issue.
• npm ls @changesets/cli mostra 3.x e npm ls read-yaml-file não encontra nada. Num branch de teste, um changeset de patch para thinker mais npx changeset version sobe packages/thinker (pacote privado); sem changesets, o workflow não falha.

Dependências

• CI completa com os nomes novos #20
• Rebranding do backend: textos, e-mails, MCP e atribuição de provedores #22, CLI thinker #23, Nó n8n do Thinker #24, Rebranding do dashboard #25, Docker, Compose e instalador do Thinker #26, Templates de deploy da comunidade #30: o release e o relatório do guard partem do rebranding de código completo.

Agente responsável

devops