metabase-modular-embedding-version-upgrade

実行契約

ワークフローの各ステップを順番に実行してください。手順を飛ばしてはいけません。まずチェックリストを作成し、その後、各ステップを実行して、根拠を示しながら明示的に完了と記してください。各ステップの出力は次のステップに引き継がれるため、手順を省くと誤った移行につながります。

情報不足またはツールの失敗によりステップを完了できない場合は、必ず次の対応をしてください。

1. そのステップを ❌ blocked と記録します。
2. 不足している情報、または失敗した内容を正確に説明します。
3. 停止します（後続のステップには進みません）。

必須の出力構成

回答には、次のセクションをこの順序で含めてください。

1. ステップ 0：アップグレード計画チェックリスト
2. ステップ 1 の結果：プロジェクトのスキャン
3. ステップ 2 の結果：d.ts の差分／対象ドキュメント（プライマリまたはフォールバック）
4. ステップ 3：変更カタログ
5. ステップ 4：ファイルごとの移行（ファイルごとにサブセクションを 1 つ）
6. ステップ 5：型チェックの検証
7. ステップ 6：最終サマリー

各ステップのセクションは、次のステータス行で終えてください。

• Status: ✅ complete または Status: ❌ blocked

根拠の提示要件

• ステップ 1：一致したファイルパスをすべて列挙し、一致した grep 行（SDK のインポート、または Modular の埋め込み API 呼び出し／スクリプトタグ）を示します。ファイル全体の分析はステップ 4 で行います。
• ステップ 2（プライマリパス）：d.ts ファイル間の差分出力を示します。（ハイブリッド／フォールバックパス）：取得した URL をそれぞれ列挙し、ファイルがコンテキストに読み込まれていることを確認します。ここでは型の分析や解決を行わないでください。それはステップ 3 の作業です。
• ステップ 3：構造化された変更カタログを作成します。変更・削除・追加された各シンボルについて、完全に解決された具体的な型を示します。
• ステップ 4：ファイルごとに、検出された SDK／Modular 埋め込みの使用箇所（コンポーネント、props、設定オプション、コールバック、データフロー）、そのファイルに影響するカタログ項目、無効な使用箇所、適用した正確な差分を示します。
• ステップ 5：実行した正確なコマンドと、エラーが残っている場合はその概要を示します。

パフォーマンス

このワークフローは、並列処理を最大限に活用するパイプラインとして設計されています。

Round 1 (grep+glob+pkg) ──► Round 2 (prepare.sh) ──► Round 3 (read-sources.sh) ──► Step 3 (catalog, inline)
                                                                                          │
                                                                                    Step 4 per-file:
                                                                                     ├── Read FileA → match catalog → validate → fix
                                                                                     ├── Read FileB → match catalog → validate → fix
                                                                                     └── Read FileC → match catalog → validate → fix
                                                                                           │
                                                                                     Step 5 (typecheck) ──► Step 6

Claude Code では、並列ツール呼び出しを使用するか、サブエージェントに run_in_background: true を設定してください。

リポジトリのブランチ、コミット、PR、イシューは解析しないでください。バージョン差分の確認には関係がなく、ノイズになるためです。

ステップ 1＋2 のツール呼び出しラウンド数の上限

ステップ 1＋2 は、3 回のツール呼び出しラウンドで完了してください。

ラウンド 1 — 検出（すべて同時に、1 つのメッセージで実行）：

• @metabase/embedding-sdk-react のインポートを grep する（ファイルパスを取得します。まだファイルを読み込まないでください）
• ロックファイルを glob する（yarn.lock、pnpm-lock.yaml、package-lock.json）
• package.json を読み込む（現在のバージョンを確認します）
• npm view @metabase/embedding-sdk-react version を実行する（ユーザーが対象バージョンを指定していない場合）

4 つのツール呼び出しをすべて 1 つのメッセージで行ってください。

ラウンド 2 — prepare.sh の実行とドキュメントの取得（同時に実行）：

bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --sdk
# or for Modular embedding (embed.js):
bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --embedjs

埋め込みの種類を示すため、必ず --sdk または --embedjs を指定してください。このスクリプトは、両方のバージョンで npm pack（SDK のみ）、d.ts の確認、変更履歴の取得と切り詰めを行います。SDK_TMPDIR と d.ts の利用可否を出力します。

同じメッセージで、現在のバージョンと対象バージョンの両方について llms-embedding-full.txt を取得してください（URL 形式は「許可されているドキュメントソース」を参照）。

ラウンド 3 — read-sources.sh（単一の Bash 呼び出し。参照データのみを対象とし、プロジェクトファイルは読み込まない）：

bash <skill-path>/scripts/read-sources.sh {SDK_TMPDIR}

SDK の参照データ（d.ts の差分または生の d.ts、変更履歴）を標準出力に出力します。プロジェクトファイルは読み込みません。プロジェクトファイルはステップ 4 で 1 つずつ読み込みます。

ラウンド 3 の後、追加のツール呼び出しを行わずに、ステップ 1 の結果（grep で取得したファイル一覧）、ステップ 2 の結果、ステップ 3 の変更カタログを出力します。ステップ 3 を独立した思考フェーズとして扱わないでください。データの読み込み直後に続けて作成してください。

対象範囲

このスキルが対応するアップグレード：

• @metabase/embedding-sdk-react（React SDK、v52 以降）— プライマリパスまたはフォールバックパスを使用
• embed.js を介した Modular 埋め込み（v56 以降）— 常にフォールバックパスを使用（npm の型定義はありません）
  • v56～v57：ドキュメントは embedded-analytics-js.md にあります
  • v58 以降：ドキュメントは components.md、appearance.md、authentication.md に分割されています

このスキルでは対応しないこと

• 異なる埋め込み技術間の移行

許可されているドキュメントソース

次の URL を使って、バージョン固有の llms-embedding-full.txt を取得します。

https://www.metabase.com/docs/v0.{VERSION}/llms-embedding-full.txt

URL のバージョン形式は v0.58 です（正規化：先頭の v または 0. を削除し、パッチバージョンを除きます。例：0.58.1 → 58 → URL では v0.58 を使用）。この単一のファイルには、そのバージョンの埋め込みドキュメントがすべて含まれており、LLM での利用に最適化されています。

その他の制約：

• GitHub の PR／issue や npm のページは使用しないでください。
• changelog のリンクから GitHub に移動したり、URL を推測したりしないでください。

バージョンの検出

バージョンの検出はすべてラウンド 1（ツール呼び出しのラウンド予算を参照）で行ってください。独立した事前ステップとして実施しないでください。

• 現在のバージョン：プロジェクトの package.json で @metabase/embedding-sdk-react のバージョンを確認します（dependencies と devDependencies を確認してください）。モノレポでは、ワークスペースレベルの package.json ファイルも確認してください。
• 移行先のバージョン：
  • ユーザーが指定した場合は、そのバージョンを使用します。
  • 指定がない場合は、npm view @metabase/embedding-sdk-react version を実行します。これをラウンド 1 の並行ツール呼び出しに含めてください。
• パッケージマネージャー：ロックファイルから検出します。yarn.lock → yarn、pnpm-lock.yaml → pnpm、package-lock.json → npm。ステップ 4 では、対応するインストールコマンドを使用します（例：yarn install、pnpm install）。

パッケージが存在しない場合、または Modular embedding（embed.js）をアップグレードする場合：

• 現在と移行先の Metabase インスタンスのバージョンをユーザーに確認します。Modular embedding（embed.js）は Metabase インスタンスから提供されるため、そのバージョンはインスタンスのバージョンと一致します。Claude Code では、AskUserQuestion ツールを使用してください。
• 回答があるまで、ステップ 0 を ❌ blocked とします。

複数バージョンを経由する移行

アップグレードで大きな構造上の境界（例：v0.54 → v0.58 では、v0.55 の認証設定変更と v0.58 のドキュメントレイアウト変更をまたぐ）を越える場合は、移行先バージョンへの単一の移行として処理し、中間バージョンへのアップグレードは行わないでください。ただし、ステップ 3 では認証設定の変遷に関するセクションを確認し、移行経路上のすべての破壊的変更を反映してください。たとえば、v0.52 → v0.58 では、認証設定の形式変更（v0.55）と jwtProviderUri の追加（v0.58）の両方を移行に反映する必要があります。

ワークフロー前の手順

アップグレード計画チェックリスト（他の作業に先立って必須）

進捗を追跡するためのチェックリストを作成してください。Claude Code では、TaskCreate／TaskUpdate ツールを使用します。

• ステップ 1：プロジェクト内の使用箇所を調査
• ステップ 2：d.ts の差分を抽出、またはドキュメントを取得
• ステップ 3：変更内容のカタログを作成
• ステップ 4：ファイルごとに移行（ファイルごとにサブタスクを 1 つ作成）
• ステップ 5：型チェックと修正
• ステップ 6：最終サマリー

パスの選択

使用するパスを決定します。

• @metabase/embedding-sdk-react をアップグレードする場合 → primary path（d.ts の差分）を試し、d.ts が利用できない場合はフォールバックします（ステップ 2 で判断）。
• Modular embedding（embed.js）をアップグレードする場合 → fallback path（d.ts の抽出を完全にスキップ）を使用します。

ワークフロー

ステップ 1：プロジェクトのコードを調査

調査結果はメインコンテキストに保持してください（サブエージェントに委任しないでください）。ステップ 3 で相互参照するために必要です。

SDK のアップグレード（@metabase/embedding-sdk-react）の場合：

ステップ 1 はラウンド 1 で実施します。grep のみを行い、ファイルは読み込みません。

• @metabase/embedding-sdk-react からのすべてのインポートを grep します。これにより、ファイルパスと一致したインポート行が返されます。
• パッケージマネージャーも検出します（ロックファイルを glob で検索）。
• 出力：grep の結果に表示された SDK インポートを含むファイル一覧。

Modular embedding（embed.js）のアップグレードの場合：

• grep の対象となる npm パッケージはありません。代わりに、コードベースを検索して次を確認します。
  • Metabase embed の <script> タグ（例：metabase.js、embed.js、embedding-sdk、Metabase インスタンスの URL などのパターン）
  • Metabase の埋め込み API を呼び出す JavaScript（例：MetabaseEmbed、Metabase.embed、window.MetabaseEmbed、initMetabase、コンポーネントの初期化呼び出し）
• 出力：一致した grep 行を含むファイル一覧。

Step 2: API の変更を抽出する

Round 2 で prepare.sh を実行します（ラウンドの予算を参照）。スクリプトは次の内容を出力します。

• SDK_TMPDIR — 両方の SDK パッケージが格納された一時ディレクトリ（Round 3 で read-sources.sh に渡します）
• current_dts=yes/no、target_dts=yes/no — d.ts の有無（情報出力用）
• DTS_DIFF_PATH — d.ts の差分ファイル（両方のバージョンに d.ts がある場合）
• CURRENT_DTS_PATH / TARGET_DTS_PATH — d.ts の生ファイルのパス（ハイブリッドモードのみ）

これらのファイルを手動で読む必要はありません。read-sources.sh が処理します。

Step 3: 変更カタログを作成する（Step 1〜2 が ✅ 完了した後）

対象は、Step 1 の grep 出力に表示されたシンボルに影響する変更のみです。 たとえば、grep に MetabaseProvider、InteractiveQuestion、CollectionBrowser のインポートが表示されている場合は、それらのコンポーネントと、その props／型／コールバックに対する変更のみをカタログに記載します。プロジェクトがインポートしていないコンポーネントの変更は省略します。

d.ts の差分、ドキュメントの比較、変更履歴から変更を抽出し、カタログを作成します。

• 削除されたエクスポート／props／型
• 名前が変更されたシンボル（旧名 → 新名）
• 型が変更された props — 型エイリアスはすべて具体的な型に解決します。エイリアス名だけで済ませてはいけません。基となる型が変わっていても、エイリアス自体は変わらない場合があります。たとえば、SdkCollectionId は現行バージョンでは number だったものが、対象バージョンでは number | "personal" | "root" | "tenant" | SdkEntityId になっている可能性があります。
• シグネチャが変更された関数／コールバック（引数の数、引数の型、戻り値の型）
• 追加された props／エクスポート（情報出力用として、Step 1 の grep 出力に含まれるコンポーネントのみ）
• 非推奨になった API（推奨される代替手段も記載）
• 認証設定の変更 — 特に注意してください。変更履歴とドキュメントに詳細が記載されています。型名の変更、fetchRequestToken のシグネチャの変更、jwtProviderUri などの新しいプロパティを確認してください。

カタログの形式

## Change Catalog (v0.54 → v0.58)

### fetchRequestToken
- Change: signature changed
- Old: `(url: string) => Promise<any>`
- New: `() => Promise<{jwt: string}>` (resolved from `MetabaseFetchRequestTokenFn`)
- Severity: 🔴 Breaking

### SdkCollectionId (type widening)
- Change: type widened
- Old: `number`
- New: `number | "personal" | "root" | "tenant" | SdkEntityId`
- Affects: any prop/callback param typed as `SdkCollectionId`, including `item.id` in CollectionBrowser callbacks
- Severity: 🔴 Breaking for code storing in `number`-typed variables

### SdkDashboardId (type widening)
- Change: type widened
- Old: `number`
- New: `number | string | SdkEntityId`
- Affects: any prop/callback param typed as `SdkDashboardId`
- Severity: 🔴 Breaking for code storing in `number`-typed variables

### jwtProviderUri
- Change: new property added to `MetabaseProvider` authConfig
- Severity: 🟢 Info — can replace manual `fetchRequestToken`

### questionHeight
- Change: new optional prop on `StaticQuestion`
- Severity: 🟢 Info

カタログは Step 4 への入力として使います。Step 4 のサブエージェントが d.ts を読み直さずに互換性を評価できるよう、具体的な型をすべて解決して記載する必要があります。

ステップ 4：ファイルごとの移行（並列処理）

各プロジェクトファイルを、変更カタログに照らし合わせて個別に分析し、修正します。ここが並列化の主なポイントです。

ファイルごとの作業を始める前に： package.json のバージョンを更新し、依存関係をインストールします。docker ファイル（docker-compose.yml、Dockerfile、.env）がある場合は、Metabase インスタンスのバージョンも更新します。これらはファイルごとではなく、一度だけ実施します。

ファイルごとのタスク（ステップ 1 のファイル一覧にある各ファイルについて）：

各ファイルに対して、読み込み、分析、修正をまとめて一度に行います。

1. ファイルを読む — ファイルの内容を読み込むのはこれが初めてです。使用されている SDK コンポーネント、フック、型、プロパティ、ドットサブコンポーネント（例：<InteractiveQuestion.Title />、<InteractiveQuestion.FilterBar />）、コールバックのデータフローを抽出します。
2. カタログ項目を照合する — カタログにある変更のうち、このファイルでの使用に影響するものを特定します。
3. 現在の使用方法を移行先 API に照らして検証する — 2 つのバージョン間に破壊的変更がなくても、ファイル内で無効なプロパティ名、誤った属性名、存在しないコンポーネント名、正しくないシグネチャが使われている場合があります。ファイル内のすべての使用箇所を移行先バージョンの API（d.ts またはドキュメント）と比較し、一致しないものがあれば報告します。これにより、アップグレードでは自動的に修正されない既存のエラーを検出できます。特に、型チェッカーが間違いを検出できない JS のみのプロジェクトや EmbedJS の統合でよく見られます。
4. 詳細に分析する — カタログとの一致項目または無効な使用箇所ごとに、以下を行います。
   • ファイル内の現在の使用方法を、カタログに記載された移行先の型と比較します。
   • コールバックプロパティの場合：このファイル内でコールバック引数のフィールドがどこで使われているか（状態セッター、変数、API 呼び出し、ルートパラメーターなど）を追跡します。受け取る側の型が、移行先で拡張される可能性のある型と互換性があるか確認します。たとえば、onClick: (item) => setSelectedId(item.id) で、カタログに item.id が number から SdkCollectionId に拡張されると記載されており、setSelectedId が useState<number> の場合は、破壊的変更として報告します。
5. 修正を適用する — ファイルを編集し、すべての破壊的変更を移行して、無効な使用箇所も修正します。
6. 報告する — このファイルで見つかった内容と変更点を出力します。

並列化の戦略：

• ファイル数が 10 以下：メインエージェントですべて処理します。各ファイルを読み、カタログと照合して修正し、次のファイルに進みます。
• ファイル数が 10 を超える場合：ファイルを 3～5 個のサブエージェントに均等に分けて割り当てます。各サブエージェントにはファイルパスと変更カタログ全体を渡し、各ファイルを読み込んで修正を適用し、結果を報告させます。Claude Code では、run_in_background: true を指定して起動します。

ファイルごとの出力例

## src/components/CollectionPage.tsx

### Catalog matches:
- SdkCollectionId type widening → affects `onClick` callback
- (no other catalog entries match this file)

### Analysis:
- `onClick: (item) => setSelectedId(item.id)`
  - `item.id` is now `SdkCollectionId` (number | "personal" | "root" | "tenant" | SdkEntityId)
  - `setSelectedId` is `useState<number | undefined>[1]`
  - 🔴 BREAKING: string variants won't fit `number` state

### Fix applied:
- Widened state: `useState<number | undefined>` → `useState<SdkCollectionId | undefined>`
- Added import: `import type { SdkCollectionId } from '@metabase/embedding-sdk-react'`

Status: ✅ complete

ステップ 5：型チェックを検証する（一括修正）

SDK のアップグレード（TypeScript プロジェクト）の場合：

1. 型チェックを 1 回実行する — プロジェクトの型チェックコマンド（例：npm run typecheck、tsc --noEmit、またはプロジェクトのビルドツールに相当するコマンド）を実行します。
2. すべてのエラーをまとめて分析する — エラー出力全体を読み、SDK 関連の各エラーを根本原因ごとに分類します（例：「削除されたプロップ」「型シグネチャの変更」「エクスポート名の変更」）。根本原因が共通するエラーはまとめて修正します。
3. 想定される型を調べる — 失敗しているシンボルごとに node_modules/@metabase/embedding-sdk-react/dist/index.d.ts を検索し、移行先の型を確認します。修正を始める前に、すべての確認を済ませてください。これにより、読み取りと編集を何度も繰り返さずに済みます。
4. すべての修正を一括で適用する — 型チェックを再実行する前に、すべてのファイルにあるエラーを修正します。Claude Code では、可能な場合、1 つのメッセージ内ですべての Edit 呼び出しを行います。
5. 最後に型チェックを 1 回実行して検証する — 型チェックコマンドを再実行します。新しいエラーが発生した場合（例：修正によって二次的な問題が生じた場合）は、別の一括修正を適用して再実行します。3 回の一括修正を行ってもエラーが残る場合は、ステップ 5 を ❌ ブロックとして記録し、解決できなかったエラーを報告します。

SDK のアップグレード（通常の JavaScript プロジェクト）の場合：

• 型チェッカーは利用できません。代わりに、ステップ 4 の変更を移行先 SDK の API と照らし合わせて手動で確認します。
  • 関数シグネチャが一致していることを確認します（引数の数、戻り値の型）。
  • プロップ名と値が、移行先バージョンの要件に合っていることを確認します。
  • 名前が変更されたインポートや削除されたエクスポートがないか確認します。
• 検証は手動で行った（TypeScript なし）ことを注記して、ステップ 5 を ✅ 完了として記録します。

モジュラー埋め込み（embed.js）のアップグレードの場合：

• 型チェックに利用できる npm の型定義はありません。代わりに、次の手順を行います。
  • プロジェクトで TypeScript を使用している場合は、移行で発生した一般的な TS エラーを検出するため、型チェックコマンドを実行します。
  • プロジェクトが通常の JavaScript の場合は、型チェックを省略します。代わりに、変更した埋め込み設定オブジェクトがすべて移行先バージョンのドキュメントに記載されたオプションに合っていることを手動で確認します。
• 実施した検証の内容を注記して、ステップ 5 を ✅ 完了として記録します。

ステップ 6：概要を出力する

次のセクションに分けて整理します。

1. 修正した破壊的変更 — 破壊的変更ごとに、重大度と実施した対応を記載します。

• 🔴 破壊的変更（ビルド時または実行時エラーの原因となるもの）：例：「fetchRequestToken を 1 引数のシグネチャから 0 引数のシグネチャに移行」
• 🟡 非推奨（現在は動作するものの、今後動作しなくなるもの）：例：「appearance プロップの名前を theme に変更 — 更新済み」

2. 非推奨の警告 — 移行先バージョンで非推奨とされているものの、引き続き動作する API を記載します。今後の変更を計画できるよう、推奨される代替手段も含めます。

3. 利用可能な新機能 — プロジェクトで活用できる、移行先バージョンの関連する新しい API やオプション（例：手動の fetchRequestToken に代わる jwtProviderUri）を記載します。簡潔にまとめ、紹介にとどめます。

4. インスタンス要件 — 移行先 SDK バージョンで必要となる Metabase インスタンスの最低バージョンを記載します。プロジェクトに docker-compose などのファイルがある場合は、インスタンスのバージョンも更新されたかどうかを記載します。

5. 技術的な詳細 — 使用したパス（主要な d.ts の差分／ハイブリッド／ドキュメントでの代替手段）、アップグレードしたバージョン（変更前 → 変更後）、使用したパッケージマネージャーを記載します。

再試行ポリシー

URL の取得：

• llms-embedding-full.txt の取得で 404 が返された場合、そのバージョンのドキュメントが存在しない可能性があります。何も記録せずにスキップしてください。
• その他のエラー（5xx、タイムアウト、ネットワーク）：すぐに 1 回再試行します。それでも失敗する場合は、そのステップを ❌ ブロックとして記録し、停止します。

npm pack：

• あるバージョンの npm pack が失敗した場合、そのバージョンは npm に存在しない可能性があります。❌ ブロックとして記録し、ユーザーに知らせます。