Lumos for Astro アップグレード

Lumos サイトのアップグレード

この作業が完了した時点で、次の 2 つの条件が同時に満たされている必要があります。これらは互いに相反します。

1. ユーザーが書いたものは何も失われないこと。 オーバーライド、ページ、トークン、コンポーネントのすべてが保持される。
2. 古い規約が残っていないこと。 名前変更されたプロパティは新しい名前に、移動されたコンポーネントは新しい場所に、廃止されたパターンは削除される。

ユーザーの作業をそのまま放置すれば条件 2 を満たせません。上書きして最新化すれば条件 1 を満たせません。解決策は三点マージです。つまり、ユーザーが出発点とした状態、現在の状態、そして今日出荷されている状態を比較し、これらが異なる場合は推測ではなく質問するという規律が必要です。

サイトの出発点

アップグレードの質は、出発点をどれだけ正確に把握しているかにかかっています。

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

• スタンプあり — create-lumos が書き込んだ { version, commit, scaffolded }。version はサイトが由来するリリース（参照用）、commit はマージ対象（これが重要）。これらは冗長ではありません。リリース間にスキャフォールドされたサイトはそのバージョンとそれ以降のコミットを含むため、正確な範囲を示すのはコミットだけです。バージョンが追加される前のサイトはコミットのみを持ちますが、それで十分です。そのコミットがマージベースです。フェッチすれば、どの行がフレームワークのもので、どの行がユーザーのものかが正確にわかります。
• スタンプなし — スタンプ機能以前のサイト。v0.0.1 をベースとして扱います。レポートに「ベースは推測であり、マージのより多くがコンフリクトとして現れ、より多くの目視確認が必要になる」と明記してください。

サイト自身の package.json のバージョンは何も意味しません。create-lumos はすべての新サイトを 0.0.1 に設定します。これをフレームワークのバージョンとして読んではいけません。

手順

1. 現在の状態をコミットする

ダーティなツリーでは開始しないでください。アップグレード中の差分に昨日の作業が混ざると判読できなくなります。

git status --porcelain          # 空である必要あり
git commit --allow-empty -m "Before Lumos upgrade"

空コミットは意図的です。アップグレード全体のアンカーとなり、git diff <そのコミット> がレビューになります。

2. サイトを撮影する

何も変更する前に、開発サーバーを起動した状態で：

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

すべての静的ルートをデスクトップとモバイルで撮影します。これは手順 8 で確認する証拠であり、後から取得することはできません。

3. 両方のリファレンスコピーを取得する

npm create lumos@latest .lumos-upgrade/latest    # 現在出荷されているもの

そしてマージベース（サイトがスキャフォールドされたコミット）：

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

これで 3 つのツリーが存在します：base（ユーザーの出発点）、サイト（現在の状態）、latest（移行先）。

4. すべてのファイルを 4 つのカテゴリに分類する

フレームワークの公開領域（コンポーネント、レイアウト、スタイル、ユーティリティ）の各ファイルについて：

base vs site	base vs latest	意味	対処
同じ	同じ	両側で未変更	そのまま
同じ	変更あり	フレームワークが変更、ユーザーは未操作	最新版をそのまま採用
変更あり	同じ	ユーザーのオーバーライド、フレームワーク未変更	ユーザーのものを維持
変更あり	変更あり	両側で変更	三点マージ、コンフリクトはレポートに記載

src/pages、src/content、src/assets は定義上ユーザーのものです。これらを置き換えてはいけません。ただし手順 6 で移行が必要です。

.agents/skills は例外を除き丸ごとアップグレードします。 スキルの散文はフレームワークのものであり最新版に移行すべきですが、スキルにはプロジェクトが書き込んだセクションが含まれる場合があります。/lumos-import-webflow の This project はその一例で、他のどこにも存在しないパス、プロバイダー、CMS フィルターを記録しています。新しいファイルを採用する前に、そのようなセクションをそのまま引き継ぎ、レポートにその旨を記載してください。最新版を丸ごと採用すると、他の情報源のない記録が破棄されます。

5. base.css を置き換えずにマージする

グローバル CSS は 4 番目のカテゴリに該当する可能性が最も高いファイルです。フレームワークがトークンを追加し、ユーザーがブランドカラーやフォントを変更します。これをトークン単位で三点マージし、次の 2 つのルールを守ってください：

• ユーザーが変更したトークンは、フレームワークがデフォルトを変更した場合でもユーザーの値を保持します。ユーザーのブランドカラーは古いデフォルトではありません。
• フレームワークが追加したトークンは、フレームワークの値で、末尾ではなく専用セクションに配置します。

両側で変更されたすべてのトークンは、両方の値をレポートに記載します。代わりに選択してはいけません。

6. サイト自身のコードを移行する

base と latest の差分から何が移動したかを把握し、それを src/pages およびユーザーが書いたすべてのコードに適用します：

• 名前変更または移動されたコンポーネント — すべてのインポートとタグを更新します。フォルダを移動してプレフィックスが失われたコンポーネント（FormInput → Form/Input.astro）は 2 つの変更が同時に発生しています。両方とも対応してください。
• 名前変更されたプロパティ — すべての呼び出し箇所で名前を変更します。
• 削除されたプロパティ — 停止して質問します。 それぞれについて、プロパティをローカルオーバーライドとして保持する、削除する、または置き換えられたものに移行する、という 3 つの現実的な選択肢を提示します。黙って決めてはいけません。削除されたプロパティには通常意味があります。
• 削除されたコンポーネント — ユーザーのコピーを保持します。 base からコンポーネントをサイト自身のコンポーネントフォルダにコピーしてサイトがビルドされ見た目も同じになるようにし、フラグを立てます。それはフレームワークによって保守されなくなり、置き換えがあればその内容を記載します。

7. ビルドできることを確認する

npx astro check && npx astro build

スクリーンショットの確認に進む前に、両方とも警告なしでパスする必要があります。ここで発見された型エラーは、見逃された移行箇所です。

ついでに Astro のペアリングも確認してください。 Astro はサイト自身の依存関係であり、フレームワークのものではありません。Lumos はスキャフォールドされるものであり、インストールされるものではありません。そのためアップグレードは確認の自然なタイミングですが、強制するライセンスではありません。サイトの astro のバージョンとマージ対象のリリースを比較し、サイトがメジャーバージョンで遅れている場合はレポートに記載し、サイトのオーナーに判断を委ねます。

アップグレードは手動ではなく npx @astrojs/upgrade で行います。これにより @astrojs/* の統合機能も Astro と一緒にアップグレードされます。@astrojs/sitemap は astro へのピア依存関係を宣言していないため、バージョンが不一致でも警告なしにインストールされ、ビルド失敗やサイレントにサイトマップが生成されなくなるという形で現れます。

8. 何も移動していないことを確認する

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

すべてのルートを手順 2 とピクセル単位で比較し、アンチエイリアスの許容範囲を設け、0.1% を超えるピクセル差がある場合はハイライトされた差分を生成します。何かが移動した場合、終了コードは非ゼロになります。

デザインが変わったアップグレードはどこかで間違っています。 トークンが間違った方法でマージされた、プロパティが削除された、コンポーネントが同等でないものに置き換えられた、などが原因です。差分画像から逆方向に作業し、それぞれが説明できるまで追究します。正当なものもあります。上流の真のバグ修正はピクセルを動かします。ルールは「差異がないこと」ではなく、「説明できない差異がないこと」です。

9. 結果をコミットする

git add -A && git commit -m "Upgrade Lumos to <commit>"

package.json のスタンプを今回マージしたコミットに更新し、次回のアップグレードが正確なベースを持てるようにします。その後 .lumos-upgrade/ を削除します。

レポート

• 最新版から採用 — 未変更であったため丸ごと置き換えられたファイル。
• ユーザーのものを維持 — オーバーライドは保存され、フレームワークの変更は却下された。
• マージされた — 両側で変更があったファイル。どこから何が来たかを記載。
• 移行された — ユーザーのコードに適用された名前変更や移動。件数を記載。
• 生存維持された — 上流で削除されサイトにコピーされたコンポーネント。その置き換え内容も記載。
• 回答済み — 削除されたプロパティと、ユーザーがそれぞれをどう解決したか。
• 視覚的な差異 — 移動したすべてのビューとその理由。
• 未解決 — 未解決の項目。アップグレードはこのリストが空でなくても完了できますが、その旨を明記する必要があります。

バージョン

• スキルバージョン — 1.0.0。
• フレームワーク — 現時点ではリリースと呼べるものはありません。create-lumos は main ブランチの HEAD からスキャフォールドするため、「最新」とは最新のコミットを意味し、マージベースはタグではなくコミットです。タグ付きリリースが登場した場合は、スタンプのタグを優先し、手順 4 で変更履歴を読み取ってください。盲目的に差分を取らないでください。

Claude Code なしでの使用

手順はプレーンな git と Node.js です。visual-check.mjs にはヘッドレス Chrome と sharp が必要ですが、どちらも Mac 上の Astro プロジェクトはすでに持っています。自動トリガーと /lumos-upgrade だけが Claude Code の機能です。