mise à niveau Lumos pour Astro

Mise à niveau d'un site Lumos

Deux conditions doivent être remplies à la fin de cette opération, et elles sont antagonistes :

1. Rien de ce que l'utilisateur a écrit n'est perdu. Ses surcharges, ses pages, ses tokens, ses composants.
2. Rien ne reste sur les anciennes conventions. Les accessoires renommés le sont, les composants déplacés le sont, les motifs retirés sont effectivement retirés.

Conserver leur travail en le laissant intact viole la deuxième condition. Moderniser en écrasant viole la première. La solution est un merge à trois voies — ce dont ils sont partis, ce qu'ils ont maintenant, ce qui est livré aujourd'hui — et la discipline de demander plutôt que de deviner lorsque ces trois versions divergent.

Point de départ du site

Une mise à niveau n'est aussi bonne que la connaissance du point de départ.

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

• Estampillé — { version, commit, scaffolded } écrit par create-lumos. La version est la publication dont provient le site, pour la lecture ; le commit est ce contre quoi fusionner, et c'est celui qui compte. Ils ne sont pas redondants : un site généré entre deux publications est cette version plus tout ce qui a été publié après, et seul le commit indique la quantité. Les sites estampillés avant l'ajout de la version portent uniquement le commit, ce qui est suffisant. Ce commit est la base de merge. Récupérez-le et vous saurez exactement quelles lignes appartiennent au framework et quelles sont celles de l'utilisateur.
• Non estampillé — le site est antérieur à l'estampillage. Traitez v0.0.1 comme base. Dites-le dans le rapport, clairement : la base est une estimation, donc une plus grande partie du merge générera des conflits et nécessitera une vérification manuelle.

La version du package.json du site lui-même ne veut rien dire — create-lumos définit chaque nouveau site à 0.0.1. Ne l'interprétez pas comme une version du framework.

Étapes

1. Valider ce qui existe

Refusez de démarrer sur un arbre de travail sale — un diff de mise à niveau à mi-parcours est illisible s'il est mélangé avec le travail de la veille.

git status --porcelain          # doit être vide
git commit --allow-empty -m "Avant la mise à niveau Lumos"

Le commit vide est délibéré : c'est l'ancre par rapport à laquelle toute la mise à niveau est lue, et git diff <ce commit> devient la révision.

2. Photographier le site

Avant tout changement, avec le serveur de développement en cours d'exécution :

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

Chaque route statique en version bureau et mobile. C'est la preuve que l'étape 8 vérifiera, et elle ne peut pas être prise après.

3. Obtenir les deux copies de référence

npm create lumos@latest .lumos-upgrade/latest    # ce qui est livré maintenant

Et la base de merge — le commit à partir duquel le site a été généré :

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

Maintenant trois arbres existent : base (là où ils ont commencé), le site (là où ils sont), latest (là où ils vont).

4. Trier chaque fichier dans l'une des quatre piles

Pour chaque fichier de la surface du framework — composants, layouts, styles, utilitaires :

base vs site	base vs latest	Ce que c'est	Que faire
identique	identique	inchangé des deux côtés	laisser
identique	modifié	framework a bougé, utilisateur jamais touché	prendre latest en totalité
modifié	identique	surcharge utilisateur, framework inchangé	garder le leur
modifié	modifié	les deux ont bougé	merge à trois voies, conflits dans le rapport

src/pages, src/content et src/assets sont par définition ceux de l'utilisateur — ne les remplacez jamais. Ils nécessitent tout de même une migration à l'étape 6.

.agents/skills est mis à niveau en totalité, avec une exception. La prose d'une compétence appartient au framework et doit passer à la dernière version, mais une compétence peut contenir une section que le projet a écrite — /lumos-import-webflow's Ce projet en est une, et elle enregistre des chemins, des fournisseurs et des filtres CMS qui n'existent nulle part ailleurs. Transportez toute section de ce type textuellement avant de prendre le nouveau fichier, et dites dans le rapport que vous l'avez fait. Prendre la dernière version en totalité détruit un enregistrement sans autre source.

5. Fusionner base.css plutôt que de le remplacer

Le CSS global est le fichier le plus susceptible de se trouver dans la quatrième pile : le framework ajoute des tokens, l'utilisateur change les couleurs de la marque et les polices. Fusionnez-le à trois voies, token par token, et respectez deux règles :

• Un token que l'utilisateur a modifié conserve sa valeur, même si le framework a changé la valeur par défaut. La couleur de leur marque n'est pas une valeur par défaut obsolète.
• Un token que le framework a ajouté arrive avec la valeur du framework, placé dans sa propre section — pas ajouté à la fin.

Chaque token où les deux côtés ont changé va dans le rapport avec les deux valeurs. Ne choisissez pas à leur place.

6. Migrer le code propre du site

Différenciez base par rapport à latest pour apprendre ce qui a bougé, puis appliquez-le à src/pages et à tout ce que l'utilisateur a écrit :

• Composants renommés ou déplacés — mettez à jour chaque import et chaque balise. Un composant qui a changé de dossier et perdu un préfixe (FormInput → Form/Input.astro) représente deux changements en un ; faites les deux.
• Accessoires renommés — renommez à chaque site d'appel.
• Accessoires supprimés — arrêtez-vous et demandez. Pour chacun, proposez les trois vraies options : conserver l'accessoire comme surcharge locale, le supprimer ou le déplacer vers ce qui l'a remplacé. Ne décidez jamais en silence ; un accessoire supprimé avait généralement une signification.
• Composants supprimés — conservez la copie de l'utilisateur. Copiez le composant depuis base dans le dossier de composants du site pour que le site continue de se construire et de ressembler à ce qu'il était, et signalez-le : il n'est plus maintenu par le framework, et voici ce qui l'a remplacé, le cas échéant.

7. Prouver qu'il se construit

npx astro check && npx astro build

Les deux doivent être propres avant d'approcher les captures d'écran. Une erreur de type trouvée maintenant est une migration qui a été oubliée.

Vérifiez l'appairage Astro pendant que vous êtes déjà là. Astro est la dépendance propre du site, pas celle du framework — Lumos est généré, pas installé — donc une mise à niveau est le moment naturel pour regarder, pas une licence pour en forcer une. Comparez l'astro du site avec la version fusionnée ; si le site est en retard sur une version majeure, dites-le dans le rapport et laissez son propriétaire décider.

Mettez-la à niveau avec npx @astrojs/upgrade plutôt qu'à la main. Cela déplace les intégrations @astrojs/* avec Astro, et @astrojs/sitemap ne déclare aucune dépendance peer sur astro — donc une paire incompatible s'installe sans un mot et se manifeste comme un échec de construction, ou comme un sitemap qui cesse silencieusement d'être écrit.

8. Prouver que rien n'a bougé

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

Compare pixel par pixel chaque route par rapport à l'étape 2 avec une tolérance pour l'anticrénelage, et écrit un diff surligné pour tout ce qui dépasse 0,1 % des pixels. Le code de sortie est non nul lorsque quelque chose a bougé.

Une mise à niveau qui change le design a mal tourné quelque part — un token fusionné du mauvais côté, un accessoire supprimé, un composant échangé contre un autre qui n'est pas tout à fait identique. Travaillez à rebours à partir de l'image de diff jusqu'à ce que chacun soit expliqué. Certains sont légitimes : un véritable correctif de bogue en amont déplacera des pixels. La règle n'est pas "aucune différence", c'est "aucune différence inexpliquée".

9. Valider le résultat

git add -A && git commit -m "Mise à niveau Lumos vers <commit>"

Mettez à jour l'estampille dans package.json vers le commit qui vient d'être fusionné, afin que la prochaine mise à niveau ait une base exacte. Supprimez ensuite .lumos-upgrade/.

Le rapport

• Pris de la dernière version — fichiers remplacés en totalité, car ils n'avaient pas été touchés.
• Conservés comme vôtres — surcharges préservées, changements du framework refusés.
• Fusionnés — fichiers où les deux côtés ont bougé, avec ce qui vient d'où.
• Migrés — renommages et déplacements appliqués au code propre de l'utilisateur, comptés.
• Gardés en vie — composants supprimés en amont qui ont été copiés dans le site, avec ce qui les a remplacés.
• Répondu — accessoires supprimés et comment l'utilisateur a choisi de résoudre chacun.
• Différences visuelles — chaque vue qui a bougé, et pourquoi.
• Toujours ouvert — tout ce qui n'est pas résolu. Une mise à niveau peut se terminer avec cette liste non vide, tant que c'est déclaré.

Versions

• Version de la compétence — 1.0.0.
• Framework — il n'y a pas encore de publications à proprement parler : create-lumos génère à partir de la HEAD de main, donc "dernière version" signifie le commit le plus récent, et la base de merge est un commit plutôt qu'un tag. Si des versions étiquetées arrivent, préférez le tag dans l'estampille et lisez le changelog à l'étape 4 plutôt que de différencier à l'aveugle.

Utilisation sans Claude Code

Les étapes sont du git et du node simples. visual-check.mjs nécessite un Chrome sans tête et sharp, que tout projet Astro sur Mac possède déjà. Seuls le déclenchement automatique et /lumos-upgrade sont des fonctionnalités de Claude Code.