Atualização de Versão e Fluxo de Lançamento

IMPORTANTE: Planeje e escreva notas de lançamento detalhadas antes de começar.

CRÍTICO: Faça commit de TUDO (incluindo artefatos de build). Ao final deste fluxo, NADA deve ficar sem commit ou sem push. Execute git status no final para verificar.

Preparação

1. Analisar: Determine se a alteração é PATCH (correções de bugs), MINOR (novos recursos) ou MAJOR (mudanças que quebram a compatibilidade).

2. Ambiente: Identifique o proprietário/nome do repositório a partir de git remote -v.

3. Caminhos — todos os arquivos que contêm a string de versão:

   • package.json — a versão publicada no npm/npx (npx claude-mem@X.Y.Z é resolvido a partir disso)
   • plugin/package.json — dependências do runtime do plugin empacotado
   • .claude-plugin/marketplace.json — versão dentro de plugins[0].version
   • .claude-plugin/plugin.json — manifesto do plugin Claude de nível superior
   • plugin/.claude-plugin/plugin.json — manifesto do plugin Claude empacotado
   • .codex-plugin/plugin.json — manifesto do Codex-plugin
   • plugin/.codex-plugin/plugin.json — manifesto do Codex-plugin empacotado
   • .qoder-plugin/plugin.json — manifesto do Qoder plugin
   • plugin/.qoder-plugin/plugin.json — manifesto do Qoder plugin empacotado
   • openclaw/openclaw.plugin.json — manifesto do OpenClaw plugin
   • .grok-plugin/plugin.json — manifesto do Grok plugin
   • claude-mem-cursor/.cursor-plugin/plugin.json — manifesto do Cursor plugin
   • claude-mem-grok-bot/.cursor-plugin/plugin.json — manifesto do Grok Bot Cursor plugin
   • dsh/package.json — pacote do plugin DSH empacotado
   • README.md — o badge de versão (version-X.Y.Z-green), não uma chave "version"

   Verifique a cobertura antes de editar: git grep -l "\"version\": \"<OLD>\"" deve listar os quatorze arquivos JSON acima, e git grep -n "version-<OLD>-green" o badge do README. Se um novo manifesto foi adicionado desde a última atualização deste documento, atualize esta lista.

Fluxo de Trabalho

1. Atualizar: Incremente a string de versão em todos os caminhos acima. NÃO toque em CHANGELOG.md — ele é regenerado.
2. Verificar: git grep -n "\"version\": \"<NEW>\"" — confirme se todos os quatorze arquivos JSON correspondem e se o badge do README exibe version-<NEW>-green. git grep -n "\"version\": \"<OLD>\"" — deve retornar zero resultados.
3. Build e sincronização: npm run build-and-sync para regenerar artefatos, sincronizar a cópia local do marketplace, reiniciar o worker e limpar a fila. Não use npm run build puro para validação de lançamento, pois ele pode deixar o marketplace/worker local dessincronizado.
4. Commit: git add -A && git commit -m "chore: bump version to X.Y.Z".
5. Tag: git tag -a vX.Y.Z -m "Version X.Y.Z".
6. Push: git push origin main && git push origin vX.Y.Z.
7. Release no GitHub: gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES".
8. Changelog: Regenerar através do script de changelog do projeto:

   npm run changelog:generate
   

   (Executa node scripts/generate-changelog.js, que busca releases da API do GitHub e reescreve CHANGELOG.md.)
9. Sincronizar changelog: Faça commit e push do CHANGELOG.md atualizado.
10. Auditoria pré-publicação: Verifique se o commit de release, a tag, o release no GitHub e o changelog foram enviados; confirme se a área de trabalho de release não tem alterações rastreadas pendentes; e garanta que suas dependências de build estejam presentes, pois prepublishOnly reconstrói o pacote. Se npm view claude-mem@X.Y.Z version já resolver, pule a publicação e continue com as verificações pós-publicação.
11. Publicar no npm — o agente executa. A antiga regra de "entrega manual" é obsoleta: o mantenedor permite que agentes publiquem. O token é um token npm granular de 30 dias (leitura/escrita apenas em claude-mem, ignora 2FA) no ~/.npmrc do Mac do mantenedor; ele emite um novo a cada mês. Ele é deliberadamente NÃO incluído em nenhum backup (grok-bot-backups exclui segredos), então não o procure em outro lugar. Publique a partir de uma área de trabalho limpa da tag (dentro do .scratch/ do projeto) para que edições não commitadas nunca sejam enviadas:

    git worktree add --detach .scratch/release-X.Y.Z vX.Y.Z
    cd .scratch/release-X.Y.Z && npm install --ignore-scripts
    npm whoami                    # must print thedotmack; 401 = token expired
    npm publish --access public   # prepublishOnly rebuilds the package
    

    Se npm whoami falhar, o token mensal expirou. Conclua todas as outras etapas e, em seguida: abra https://www.npmjs.com/settings/thedotmack/tokens/granular-access-tokens/new

…