lumosframework/lumos-for-astro

Actualización de un sitio Lumos

Dos cosas deben ser ciertas cuando esto termine, y se contraponen entre sí:

1. Nada de lo que el usuario escribió se pierde. Sus anulaciones, sus páginas, sus tokens, sus componentes.
2. Nada se queda en convenciones antiguas. Propiedades renombradas renombradas, componentes movidos movidos, patrones retirados retirados.

Conservar su trabajo dejándolo como está falla la segunda. Modernizar sobrescribiendo falla la primera. El camino es una fusión a tres bandas — con lo que comenzaron, lo que tienen ahora, lo que se envía hoy — y la disciplina de preguntar en lugar de adivinar cuando esos tres no coinciden.

Dónde comenzó el sitio

Una actualización es tan buena como su conocimiento del punto de partida.

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

• Con sello — { version, commit, scaffolded } escrito por create-lumos. La versión es el lanzamiento del que provino el sitio, para lectura; el commit es contra qué fusionar, y es el que importa. No son redundantes: un sitio generado entre lanzamientos es esa versión más lo que llegó después, y solo el commit dice cuánto. Los sitios sellados antes de que se agregara la versión llevan solo el commit, lo cual es suficiente. Ese commit es la base de fusión. Tráelo y sabrás exactamente qué líneas son del framework y cuáles son del usuario.
• Sin sello — el sitio es anterior al sellado. Trata v0.0.1 como la base. Dilo en el informe, claramente: la base es una suposición, por lo que más de la fusión resultará en conflictos y necesitará revisión.

La versión del package.json del sitio no dice nada — create-lumos establece cada sitio nuevo en 0.0.1. No lo leas como una versión del framework.

Pasos

1. Confirma lo que hay

Rehúsa comenzar en un árbol sucio — un diff a medio actualizar es ilegible si se mezcla con el trabajo de ayer.

git status --porcelain          # debe estar vacío
git commit --allow-empty -m "Antes de la actualización de Lumos"

El commit vacío es deliberado: es el ancla contra la que se lee toda la actualización, y git diff <ese commit> se convierte en la revisión.

2. Fotografía el sitio

Antes de que nada cambie, con el servidor de desarrollo en ejecución:

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

Cada ruta estática en escritorio y móvil. Esta es la evidencia contra la que el paso 8 verifica, y no se puede tomar después.

3. Obtén ambas copias de referencia

npm create lumos@latest .lumos-upgrade/latest    # lo que se envía ahora

Y la base de fusión — el commit desde el que se generó el sitio:

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

Ahora existen tres árboles: base (donde empezaron), el sitio (donde están), latest (hacia donde van).

4. Clasifica cada archivo en uno de cuatro montones

Para cada archivo en la superficie del framework — componentes, layouts, estilos, utilidades:

base vs sitio	base vs latest	Qué es	Qué hacer
igual	igual	intacto en ambos lados	dejar
igual	cambiado	framework se movió, usuario nunca lo tocó	tomar latest completo
cambiado	igual	anulación del usuario, framework sin cambios	mantener lo suyo
cambiado	cambiado	ambos se movieron	fusión a tres bandas, conflictos al informe

src/pages, src/content y src/assets son del usuario por definición — nunca los reemplaces. Aún necesitan migración en el paso 6.

.agents/skills se actualiza por completo, con una excepción. El texto de un skill es del framework y debe pasar a latest, pero un skill puede contener una sección que el proyecto escribió en él — el Este proyecto de /lumos-import-webflow es una, y registra rutas, proveedores y filtros de CMS que no existen en ningún otro lugar. Traslada dicha sección textualmente antes de tomar el nuevo archivo, y di en el informe que lo hiciste. Tomar latest completo destruye un registro sin otra fuente.

5. Fusiona base.css en lugar de reemplazarlo

El CSS global es el archivo con más probabilidades de estar en el cuarto montón: el framework agrega tokens, el usuario cambia colores de marca y fuentes. Fusiónalo a tres bandas, token por token, y respeta dos reglas:

• Un token que el usuario cambió mantiene su valor, incluso si el framework cambió el valor predeterminado. El color de su marca no es un valor predeterminado obsoleto.
• Un token que el framework agregó llega con el valor del framework, colocado en su propia sección — no añadido al final.

Cada token en el que ambos lados cambiaron va al informe con ambos valores. No elijas por ellos.

6. Migra el código propio del sitio

Diferencia base contra latest para saber qué se movió, luego aplícalo a src/pages y a cualquier cosa que el usuario haya escrito:

• Componentes renombrados o movidos — actualiza cada importación y etiqueta. Un componente que cambió de carpeta y perdió un prefijo (FormInput → Form/Input.astro) es dos cambios en uno; aplica ambos.
• Propiedades renombradas — renómbralas en cada lugar de uso.
• Propiedades eliminadas — detente y pregunta. Para cada una, ofrece las tres opciones reales: mantener la propiedad como una anulación local, eliminarla o pasarla a lo que la reemplazó. Nunca decidas en silencio; una propiedad eliminada solía significar algo.
• Componentes eliminados — conserva la copia del usuario. Copia el componente desde base a la propia carpeta de componentes del sitio para que el sitio aún compile y se vea igual, y márcalo: ya no recibe mantenimiento del framework, y aquí está qué lo reemplazó, si es que hay algo.

7. Prueba que compila

npx astro check && npx astro build

Ambos limpios antes de acercarse a las capturas de pantalla. Un error de tipo encontrado ahora es una migración que se pasó por alto.

Verifica el emparejamiento de Astro mientras ya estás aquí. Astro es la dependencia propia del sitio, no del framework — Lumos se genera como parte del sitio, no se instala — por lo que una actualización es el momento natural para mirar, no una licencia para forzarlo. Compara el astro del sitio contra el lanzamiento que se está fusionando; si el sitio está atrasado en una versión principal, dilo en el informe y deja que su propietario decida.

Actuálizalo con npx @astrojs/upgrade en lugar de hacerlo manualmente. Mueve las integraciones de @astrojs/* con Astro, y @astrojs/sitemap no declara dependencia de pares con astro — por lo que un par no coincidente se instala sin decir nada y aparece como un error de compilación, o como un mapa del sitio que deja de escribirse silenciosamente.

8. Prueba que nada se movió

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

Compara píxel a píxel cada ruta contra el paso 2 con una tolerancia para el antialiasing, y escribe un diff resaltado para cualquier cosa por encima del 0.1% de los píxeles. El código de salida es distinto de cero cuando algo se movió.

Una actualización que cambia el diseño ha salido mal en algún lado — un token fusionado de manera incorrecta, una propiedad eliminada, un componente intercambiado por uno que no es exactamente igual. Trabaja hacia atrás desde la imagen diff hasta que cada una esté explicada. Algunas son legítimas: una corrección de error genuina aguas arriba moverá píxeles. La regla no es "ninguna diferencia", es "ninguna diferencia sin explicación".

9. Confirma el resultado

git add -A && git commit -m "Actualizar Lumos a <commit>"

Actualiza el sello en package.json al commit recién fusionado, para que la próxima actualización tenga una base exacta. Luego elimina .lumos-upgrade/.

El informe

• Tomado de latest — archivos reemplazados por completo, porque estaban intactos.
• Conservado como tuyo — anulaciones preservadas, cambios del framework rechazados.
• Fusionado — archivos donde ambos lados se movieron, con qué vino de dónde.
• Migrado — cambios de nombre y movimientos aplicados al código propio del usuario, contabilizados.
• Mantenido con vida — componentes eliminados aguas arriba que se copiaron en el sitio, con qué los reemplazó.
• Respondido — propiedades eliminadas y cómo el usuario eligió resolver cada una.
• Diferencias visuales — cada vista que se movió, y por qué.
• Aún abierto — cualquier cosa sin resolver. Una actualización puede terminar con esta lista no vacía, siempre que esté indicado.

Versiones

• Versión del skill — 1.0.0.
• Framework — todavía no hay lanzamientos como tales: create-lumos genera desde el HEAD de main, por lo que "latest" significa el commit más reciente, y la base de fusión es un commit en lugar de una etiqueta. Si llegan lanzamientos etiquetados, prefiere la etiqueta en el sello y lee el registro de cambios en el paso 4 en lugar de diferenciar a ciegas.

Usar esto sin Claude Code

Los pasos son git y node simples. visual-check.mjs necesita Chrome sin interfaz y sharp, ambos de los cuales un proyecto de Astro en una Mac ya tiene. Solo el disparo automático y /lumos-upgrade son características de Claude Code.