lumosframework/lumos-for-astro

Atualizando um site Lumos

Duas coisas precisam ser verdade quando isso terminar, e elas puxam uma contra a outra:

1. Nada que o usuário escreveu é perdido. Suas sobrescritas, suas páginas, seus tokens, seus componentes.
2. Nada fica em convenções antigas. Props renomeadas renomeadas, componentes movidos movidos, padrões aposentados aposentados.

Manter o trabalho deles deixando-o como está falha no segundo. Modernizar sobrescrevendo falha no primeiro. O caminho é uma mesclagem de três vias — de onde eles partiram, o que eles têm agora, o que é enviado hoje — e a disciplina de perguntar em vez de adivinhar quando esses três discordam.

De onde o site partiu

Uma atualização é tão boa quanto seu conhecimento do ponto de partida.

node -p "JSON.parse(require('fs').readFileSync('package.json')).lumos ?? 'unstamped'"

• Com carimbo (stamped) — { version, commit, scaffolded } escrito por create-lumos. A versão é o lançamento de onde o site veio, para leitura; o commit é contra o qual fazer merge, e é o que importa. Eles não são redundantes: um site gerado entre lançamentos é aquela versão mais o que quer que tenha sido adicionado depois, e apenas o commit diz o quanto. Sites carimbados antes da versão ser adicionada carregam apenas o commit, o que é suficiente. Esse commit é a base do merge. Busque-o e você saberá exatamente quais linhas são do framework e quais são do usuário.
• Sem carimbo (unstamped) — o site é anterior ao carimbo. Trate v0.0.1 como a base. Diga isso no relatório, claramente: a base é um palpite, então mais do merge resultará em conflitos e mais disso precisa de olhos.

A própria versão do package.json do site não diz nada — create-lumos define cada novo site como 0.0.1. Não a leia como uma versão do framework.

Passos

1. Faça commit do que está lá

Recuse-se a começar em uma árvore suja — um diff de atualização no meio fica ilegível se misturado com o trabalho de ontem.

git status --porcelain          # deve estar vazio
git commit --allow-empty -m "Antes da atualização Lumos"

O commit vazio é deliberado: é a âncora contra a qual toda a atualização é lida, e git diff <esse commit> se torna a revisão.

2. Fotografe o site

Antes de qualquer coisa mudar, com o servidor de desenvolvimento rodando:

astro dev --background
node .agents/skills/lumos-upgrade-version/visual-check.mjs capture before

Cada rota estática em desktop e mobile. Esta é a evidência que o passo 8 verifica, e não pode ser tirada depois.

3. Obtenha ambas as cópias de referência

npm create lumos@latest .lumos-upgrade/latest    # o que é enviado agora

E a base do merge — o commit a partir do qual o site foi gerado:

curl -sL https://codeload.github.com/lumosframework/lumos-for-astro/tar.gz/<commit> \
  | tar -xz -C .lumos-upgrade --one-top-level=base --strip-components=1

Agora três árvores existem: base (de onde partiram), o site (onde estão), latest (para onde estão indo).

4. Classifique cada arquivo em uma de quatro pilhas

Para cada arquivo na superfície do framework — componentes, layouts, estilos, utilitários:

base vs site	base vs latest	O que é	O que fazer
iguais	iguais	intocado em ambos os lados	deixar
iguais	alterados	framework mudou, usuário nunca tocou	pegar o mais recente integralmente
alterados	iguais	sobrescrita do usuário, framework inalterado	manter o deles
alterados	alterados	ambos mudaram	mesclagem de três vias, conflitos para o relatório

src/pages, src/content e src/assets são do usuário por definição — nunca os substitua. Eles ainda precisam de migração no passo 6.

.agents/skills é atualizado integralmente, com uma exceção. A prosa de uma skill é do framework e deve ir para a versão mais recente, mas uma skill pode conter uma seção que o projeto escreveu nela — o Este projeto de /lumos-import-webflow é uma, e ela registra caminhos, provedores e filtros de CMS que não existem em nenhum outro lugar. Carregue qualquer seção dessas literalmente antes de pegar o novo arquivo, e diga no relatório que fez isso. Pegar o mais recente integralmente destrói um registro sem outra fonte.

5. Faça merge de base.css em vez de substituí-lo

O CSS global é o arquivo com maior probabilidade de estar na quarta pilha: o framework adiciona tokens, o usuário muda cores de marca e fontes. Faça merge dele de três maneiras, token por token, e siga duas regras:

• Um token que o usuário mudou mantém seu valor, mesmo quando o framework mudou o padrão. A cor da marca deles não é um padrão desatualizado.
• Um token que o framework adicionou chega com o valor do framework, colocado em sua própria seção — não anexado ao final.

Cada token onde ambos os lados mudaram vai para o relatório com ambos os valores. Não escolha por eles.

6. Migre o código próprio do site

Diferença base contra latest para aprender o que mudou, então aplique a src/pages e a qualquer coisa que o usuário escreveu:

• Componentes renomeados ou movidos — atualize cada import e tag. Um componente que mudou de pasta e perdeu um prefixo (FormInput → Form/Input.astro) são duas mudanças em uma; faça ambas.
• Props renomeadas — renomeie em cada ponto de chamada.
• Props removidas — pare e pergunte. Para cada uma, ofereça as três opções reais: manter a prop como uma sobrescrita local, descartá-la, ou mover para o que quer que a tenha substituído. Nunca decida silenciosamente; uma prop removida geralmente significava algo.
• Componentes deletados — mantenha a cópia do usuário. Copie o componente de base para a própria pasta de componentes do site para que o site ainda construa e ainda pareça o mesmo, e sinalize-o: ele não é mais mantido pelo framework, e aqui está o que o substituiu, se houver algo.

7. Prove que ele compila

npx astro check && npx astro build

Ambos limpos antes de chegar perto das capturas de tela. Um erro de tipo encontrado agora é uma migração que foi esquecida.

Verifique o emparelhamento do Astro enquanto você já está aqui. Astro é a própria dependência do site, não do framework — Lumos é gerado nele, não instalado — então uma atualização é o momento natural para olhar, não uma licença para forçar uma. Compare o astro do site com o lançamento que está sendo mesclado; se o site estiver atrasado em uma versão principal, diga isso no relatório e deixe seu dono decidir.

Atualize-o com npx @astrojs/upgrade em vez de manualmente. Ele move as integrações @astrojs/* com Astro, e @astrojs/sitemap não declara nenhuma dependência de pares no astro — então um par incompatível instala sem uma palavra e aparece como uma falha de compilação, ou como um sitemap que silenciosamente deixa de ser escrito.

8. Prove que nada mudou

node .agents/skills/lumos-upgrade-version/visual-check.mjs capture after
node .agents/skills/lumos-upgrade-version/visual-check.mjs compare

Diferença de pixel em cada rota contra o passo 2 com tolerância para antialiasing, e escreve um diff destacado para qualquer coisa acima de 0.1% dos pixels. O código de saída é diferente de zero quando algo mudou.

Uma atualização que muda o design deu errado em algum lugar — um token mesclado do jeito errado, uma prop descartada, um componente trocado por um que não é exatamente o mesmo. Trabalhe de volta a partir da imagem de diff até que cada uma seja explicada. Algumas são legítimas: uma correção de bug genuína upstream moverá pixels. A regra não é "sem diferenças", é "sem diferenças inexplicadas".

9. Faça commit do resultado

git add -A && git commit -m "Atualizar Lumos para <commit>"

Atualize o carimbo em package.json para o commit que acabou de ser mesclado, para que a próxima atualização tenha uma base exata. Então delete .lumos-upgrade/.

O relatório

• Tirado da versão mais recente — arquivos substituídos integralmente, porque não foram tocados.
• Mantidos como seus — sobrescritas preservadas, mudanças do framework recusadas.
• Mesclados — arquivos onde ambos os lados mudaram, com o que veio de onde.
• Migrados — renomeações e movimentos aplicados ao próprio código do usuário, contados.
• Mantidos vivos — componentes deletados upstream que foram copiados para o site, com o que os substituiu.
• Respondidos — props removidas e como o usuário escolheu resolver cada uma.
• Diferenças visuais — cada visualização que mudou, e por quê.
• Ainda em aberto — qualquer coisa não resolvida. Uma atualização pode terminar com esta lista não vazia, desde que seja declarada.

Versões

• Versão da skill — 1.0.0.
• Framework — ainda não há lançamentos propriamente ditos: create-lumos gera a partir do HEAD do main, então "mais recente" significa o commit mais novo, e a base do merge é um commit em vez de uma tag. Se lançamentos com tag chegarem, prefira a tag no carimbo e leia o changelog no passo 4 em vez de fazer diff no escuro.

Usando isso sem Claude Code

Os passos são git e node puros. visual-check.mjs precisa de Chrome headless e sharp, ambos os quais um projeto Astro em um Mac já possui. Apenas o acionamento automático e /lumos-upgrade são recursos do Claude Code.