theme-update

テーマの更新 — Weaverse Pilot

Weaverse Pilot テーマを、現在のバージョンから新しいリリースへ安全にアップグレードします。このスキルでは検出、計画、実行、検証を順に行います。明示的な承認なしに、ユーザーのカスタマイズを上書きすることはありません。

ソース

• テーマリポジトリ：https://github.com/Weaverse/pilot
• リリース：https://github.com/Weaverse/pilot/releases
• パッケージ名：@weaverse/pilot
• バージョン形式：YYYY.M.D（例：2026.4.7）。以前は semver（v8.1.0）

クイックチェック

node skills/theme-update/scripts/check_pilot_updates.mjs
node skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7

---

手順

以下のフェーズを順番に進めてください。手順を省略してはいけません。

フェーズ 1 — 検出

1. package.json を読み取り、version フィールドを取得します
2. name が @weaverse/pilot でない場合、このプロジェクトが Pilot ベースかどうかユーザーに確認します
3. リリースを取得します：

curl -s "https://api.github.com/repos/Weaverse/pilot/releases?per_page=50"

4. 現在のバージョンから最新バージョン（またはユーザーが指定した対象バージョン）までのすべてのリリースを特定します
5. 次の内容をユーザーに提示します：
   • 現在のバージョン
   • 対象バージョン（指定がない場合は最新）
   • 中間リリースの数
   • 主な変更点の概要（機能、修正、破壊的変更）

すでに最新バージョンの場合は、ここで停止してユーザーに伝えてください。

フェーズ 2 — ブランチ

git checkout -b update/v{CURRENT}-to-v{TARGET}
git push -u origin update/v{CURRENT}-to-v{TARGET}

必ずブランチ上で作業してください。main で直接更新してはいけません。

フェーズ 3 — 計画

更新範囲内の各リリースについて、古いものから新しいものの順に以下を行います。

1. 連続するバージョン間の差分を取得します：

# Full comparison URL
https://api.github.com/repos/Weaverse/pilot/compare/v{OLD}...v{NEW}

# Raw diff
https://github.com/Weaverse/pilot/compare/v{OLD}...v{NEW}.diff

2. 参照ファイル用に対象バージョンのソースをダウンロードします：

curl -sL "https://api.github.com/repos/Weaverse/pilot/tarball/v{TARGET}" | tar xz

3. 変更されたファイルをすべて、次の 3 つのカテゴリに分類します：

自動マージ（確認なしで適用しても安全）

• package.json のバージョン更新、依存関係
• ロックファイル（package-lock.json、bun.lockb、pnpm-lock.yaml）
• tsconfig.json、vite.config.ts、tailwind.config.ts — ユーザーがカスタマイズしていない場合に限ります
• ユーザーのプロジェクトに存在しない新しいファイル（追加のみ）
• .github/、CHANGELOG.md、LICENSE

要確認（差分を表示し、承認を得る）

• app/components/ — ユーザーがカスタマイズしている可能性がある UI コンポーネント
• app/routes/ — ユーザーが変更している可能性があるルートファイル
• app/lib/ — ユーティリティモジュール
• app/root.tsx、app/entry.client.tsx、app/entry.server.tsx
• app/styles/ — CSS/Tailwind の変更
• ユーザーによるローカル変更があるファイル（git diff で Pilot のベースからの変更が確認できるもの）

スキップ（言及するが、変更しない）

• ユーザーが削除したファイル（その機能を意図的に削除したため）
• ユーザーが再編成したディレクトリ内のファイル
• .env、.env.example — 環境ファイルは上書きしないでください

4. 計画をわかりやすい表で提示します：

## Update Plan: v2026.3.23 → v2026.4.7

### Auto-merge (3 files)
✅ package.json — version + dependency bumps
✅ bun.lockb — lock file update
✅ app/lib/utils.ts — new helper function added

### Needs Review (5 files)
⚠️  app/components/Header.tsx — Pilot added shopify-account web component
    Your version: custom mega menu logic
    Pilot change: replaced AccountButton with <shopify-account>
    → Recommend: keep your mega menu, add shopify-account separately

⚠️  app/routes/_index.tsx — performance improvements
    Your version: added custom hero section
    Pilot change: caching + skeleton loading
    → Recommend: apply caching, keep your hero

### New Files (2 files)
➕ app/components/ScrollReveal.tsx — new scroll animation component
➕ app/lib/reviews.ts — extracted reviews API

### Skipped (1 file)
⏭️  app/components/CombinedListings.tsx — you deleted this file

続行する前に、ユーザーの確認を待ってください。 次のように尋ねます：

「上記の計画をご確認ください。続行を承認するか、処理方法を変更するファイルをお知らせください。」

フェーズ 4 — 実行

複数バージョンをまたぐ更新の場合は、各リリースごとに順番に変更を適用します。

4a. 自動マージ対象ファイル

# Copy new file from Pilot source
cp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}

# Or apply targeted patch
git apply --3way <patch-file>

自動マージのたびに、git diff --stat で確認します。

4b. 要確認ファイル

各ファイルについて、以下を行います。

1. 3 方向比較を表示します：

   • ユーザーのバージョンにおける Pilot（ベースライン）
   • 対象バージョンにおける Pilot（変更内容）
   • ユーザーの現在のファイル（ローカル変更）

2. ユーザーが変更した内容と Pilot が変更した内容を特定します：

   • ユーザーのみの変更 → 保持
   • Pilot のみの変更 → 適用
   • 変更が重複する箇所 → 競合として提示

3. 競合について、次の選択肢を提示します：

   • Pilot のバージョンを採用する（ユーザーのカスタマイズは失われます）
   • ユーザーのバージョンを保持する（Pilot の改善をスキップします）
   • 手動でマージする（両方を表示し、ユーザーが編集できるようにします）
   • スマートマージする（重複しない範囲に限り、両方の統合を試みます）

4. 続行する前に、各競合についてユーザーの判断を待ちます。

4c. リリースごとにコミット

git add -A
git commit -m "chore: update Pilot v{OLD} → v{NEW}

- [list key changes applied]
- [list files with manual merge decisions]
"

複数バージョンをまたぐ更新の場合は、中間リリースごとに繰り返します。

フェーズ 5 — 検証

すべての変更を適用した後：

# 1. Install dependencies
bun install  # or npm install / pnpm install based on lockfile

# 2. TypeScript check
bun run typecheck

# 3. Build check
bun run build

ビルドに失敗した場合：

1. エラーを一覧表示します
2. 根本原因を分析します（依存関係の不整合か、見落とした破壊的変更か）
3. 修正方法を提案します
4. ユーザーの承認を得て修正を適用します
5. ビルドを再実行します

ビルドに成功した場合：

1. bun run dev を短時間実行し、実行時エラーがないことを確認します
2. 実施したすべての変更を要約します
3. 手動での後続作業があれば一覧表示します：
   • 設定が必要な新機能
   • カスタマイズしたファイルのコード更新が必要な破壊的変更
   • 後で移行する非推奨パターン

フェーズ 6 — 最終確認

1. 最終的な要約を提示します：

## Update Complete: v2026.3.23 → v2026.4.7

✅ 12 files auto-merged
✅ 5 files reviewed and merged
✅ 2 new files added
✅ Build passes
✅ TypeCheck passes

### New features available
- Shopify Account Web Component (<shopify-account>)
- Vite chunk splitting for better caching
- ScrollReveal component for animations

### Manual follow-up (optional)
- Configure shopify-account in your Header if you want native sign-in
- Review ScrollReveal component for use in custom sections

### Rollback
git checkout main
git branch -D update/v2026.3.23-to-v2026.4.7

2. ユーザーに「main にマージする準備はできていますか？」と尋ねます

# If approved
git checkout main
git merge update/v{CURRENT}-to-v{TARGET}
git push origin main

---

安全ルール

1. 必ず最初にブランチを作成する — main を直接更新しないでください
2. 確認なしに上書きしない — ユーザーによる変更が含まれる可能性のあるすべてのファイルを確認する必要があります
3. リリースごとにコミットする — 問題が発生した場合に二分探索しやすくなります
4. ビルドを成功させる — typecheck と build の両方が成功するまで、成功を宣言しないでください
5. ロールバック方法を提示する — 更新全体を元に戻す方法を必ずユーザーに伝えてください
6. ユーザーによる削除を尊重する — ユーザーがファイルを削除している場合、確認なしに再追加しないでください

よくある落とし穴

• バージョン形式：package.json には v 接頭辞がありません（2026.4.7）。GitHub タグには v 接頭辞があります（v2026.4.7）。必ず表記を統一してください。
• ロックファイル：package.json を更新した後は、正しいパッケージマネージャーを必ず実行してください（存在するロックファイルを確認します）
• カスタムコンポーネント：元の Pilot にないユーザーのコンポーネントは必ず保持してください。削除や移動はしないでください
• ルート構造：ユーザーがルートを再編成している場合、Pilot の構造を無理に適用せず、ユーザーの構造に合わせてルートのロジック変更を適用してください
• CSS の競合：Pilot によって Tailwind クラスやベーススタイルが変更される場合があり、ユーザーのスタイルを損なわないよう慎重にマージする必要があります

SDK のみの更新（@weaverse/hydrogen）

依頼がテーマ全体の更新ではなく、「Weaverse SDK の更新」のみである場合があります。検証済みの手順（5.5.0 から 5.15.1 へのクライアント更新で使用）：

1. 更新前にベースラインを取得します。 現在のバージョンで npx react-router typegen && npm run typecheck を実行し、すべてのエラーを記録します（クライアントのフォークには、通常、既存のエラーがあります）。更新後にこのベースラインとの差分を取り、対応が必要なのは差分のみです。ベースラインがないと、以前から存在していたエラーの対応に追われることになります。
2. まずピア依存関係を確認します：npm view @weaverse/hydrogen@<target> peerDependencies。5.15.x／5.16.x では @shopify/hydrogen >=2025.5、react 19、react-router 7、@shopify/remix-oxygen 3 が必要です。react-error-boundary と @weaverse/schema は推移的に導入されるため、テーマの package.json に記載されていなくても問題ありません。
3. 5.15 で確認されている破壊的変更：errorComponent の型が FC<{ error: unknown }> になりました（以前は Error に似たオブジェクトでした）。実行時に型を絞り込む、上流 Pilot の GenericError を移植してください（error && typeof error === "object" && "message" in error）。
4. 最後に shopify hydrogen build --codegen を完全に実行してください。型チェックだけでは、バンドラーのレベルで発生する問題を見落とします。

Weaverse 内部：Pilot のロックファイルとデモのデプロイ

• Pilot は Weaverse の pnpm モノレポ内にありますが、npm のロックファイルを使用します。npm i --package-lock-only --workspaces=false で更新してください。通常の npm i は、モノレポの catalog: プロトコルが原因で失敗します。
• pilot.weaverse.dev をデプロイするには、Weaverse/pilot の main にマージし、その後 gh repo sync Weaverse/pilot-demo --source Weaverse/pilot を実行します。このフォークには Oxygen のデプロイアクションが含まれており、同期時にデプロイされます（約 1 分）。