Tutorial 4: Atualizando e Desinstalando o Hermes

Bem-vindo de volta à nossa série de tutoriais sobre o Hermes Agent! Nesta edição, vamos falar sobre algo que todo usuário eventualmente precisa saber: como manter o Hermes atualizado e como se despedir quando chegar a hora. Não se preocupe — é muito mais simples do que parece.

Atualizando o Hermes: A Um Comando de Distância

A maneira mais fácil de atualizar o Hermes é com um único comando:

hermes update

É isso. Este comando faz todo o trabalho pesado para você. Ele puxa o código mais recente do branch main, atualiza suas dependências e até pergunta sobre novas opções de configuração que foram adicionadas desde a sua última atualização. Bem legal, não é?

O Que Realmente Acontece Durante uma Atualização?

Você deve estar se perguntando o que acontece nos bastidores. Aqui está o detalhamento:

Snapshot pré-atualização — Antes de qualquer mudança, o Hermes salva um snapshot leve dos seus arquivos de estado importantes (dados de pareamento, cron jobs, config.yaml, .env e outros). Arquivos acima de 1 GiB são ignorados para que um banco de dados enorme não deixe tudo lento. Este snapshot é feito para cada perfil na sua instalação, cada um armazenado em seu próprio diretório state-snapshots/.
Git pull — O Hermes puxa o código mais recente do branch main e atualiza os submódulos.
Validação de sintaxe pós-pull + rollback automático — Após o pull, o Hermes verifica os nove arquivos críticos que todo comando precisa na inicialização. Se algum falhar ao ser analisado (como um marcador de conflito de merge perdido), o Hermes reverte automaticamente para a versão anterior para que seu shell permaneça utilizável. Você pode simplesmente executar hermes update novamente quando a correção chegar ao repositório upstream.
Instalação de dependências — Executa uv pip install -e ".[all]" para baixar quaisquer dependências novas ou alteradas.
Migração de configuração — Detecta novas opções de configuração e solicita que você as defina.
Reinício automático do gateway — Os gateways em execução são atualizados para que o novo código entre em vigor imediatamente. Gateways gerenciados por serviços (systemd no Linux, launchd no macOS) reiniciam através do gerenciador de serviços, enquanto gateways manuais são relançados automaticamente.

Pulou o Prompt de Configuração? Sem Problemas!

Se você pulou o prompt de configuração durante uma atualização, pode recuperar o atraso depois:

hermes config check    # veja o que está faltando
hermes config migrate  # adicione interativamente

Atualizando a Partir de um Branch Diferente

Por padrão, o hermes update rastreia o origin/main. Mas e se você quiser testar um release candidate ou um branch de funcionalidade? Use a flag --branch:

hermes update --branch release-candidate
hermes update --check --branch experimental   # apenas visualize o quanto você está atrasado

Se o seu checkout local estiver em um branch diferente, o Hermes faz stash automático de qualquer trabalho não commitado, alterna para o branch de destino e faz o pull. Branches que não existem localmente são rastreados automaticamente a partir de origin/<nome>. Se um branch não existir em lugar nenhum, o comando falha de forma limpa e restaura suas alterações do stash.

E os Branches Estacionados?

Se o seu checkout estiver em um branch de funcionalidade, o hermes update lida com isso de forma inteligente:

Branch totalmente mesclado — O Hermes informa que está totalmente mesclado e volta para o main.
Commits não mesclados, árvore limpa — O Hermes ainda alterna para o main para que a atualização prossiga (importante para chamadas não interativas, como o aplicativo desktop ou cron jobs). Seus commits ficam intactos, e o Hermes exibe um aviso bem visível com o nome do branch e como voltar a ele.

Se você deliberadamente mantém patches personalizados em um branch, defina isto no config.yaml:

updates:
  parked_branch_strategy: update_in_place

Isso mescla o origin/main dentro do seu branch em vez de alternar para outro. Fast-forward quando possível; em caso de divergência, cria uma tag de segurança e para de forma limpa em conflito.

Alterações Locais Durante Atualizações Não Interativas

Quando você executa hermes update em um terminal, o Hermes faz stash das alterações não commitadas, faz o pull e depois pergunta se deseja restaurá-las. Mas quando a atualização roda sem terminal (como a partir do aplicativo desktop), o Hermes pula a atualização se a árvore estiver suja — com um aviso bem visível nomeando o branch e o quanto ele está atrasado. Sem fingir que a atualização foi bem-sucedida!

Desinstalando o Hermes

Quando chegar a hora de se separar, desinstalar é simples. Certifique-se de verificar a documentação específica da sua plataforma para os passos exatos de remoção, mas em geral você vai querer remover o binário do Hermes e limpar os diretórios de configuração que ele criou.

Concluindo

Manter o Hermes atualizado é muito fácil com o hermes update. As redes de segurança integradas — snapshots, rollback automático e gerenciamento de branches — significam que você pode atualizar com confiança. E se você precisar se afastar, desinstalar é igualmente simples.

Fique ligado para o próximo tutorial da nossa série!