metabase-modular-embedding-to-modular-embedding-sdk-upgrade

実行契約

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

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

1. 該当ステップを ❌ blocked として記録します。
2. 不足している情報、または発生した問題を具体的に説明します。
3. 作業を停止します（後続のステップには進みません）。

必須の出力構成

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

1. ステップ 0：前提条件の確認
2. ステップ 0.1：移行計画チェックリスト
3. ステップ 1：プロジェクトのスキャン
4. ステップ 2：対象 SDK API
5. ステップ 3：移行マッピング
6. ステップ 4：適用したコード変更
7. ステップ 5：型チェックの検証
8. ステップ 6：最終的な概要

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

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

根拠の要件

• ステップ 0：検出した React（依存関係とバージョン）、Metabase インスタンスのバージョン、対象 SDK のバージョン、パッケージマネージャー。
• ステップ 1：Modular embedding の使用箇所があるすべてのファイル（Web コンポーネント、metabaseConfig、embed.js の script タグ）と、一致する grep の出力行。
• ステップ 2：d.ts がコンテキスト内で読み込まれていることの確認。エクスポートされたコンポーネント、その props、MetabaseProvider の config 型を列挙します。
• ステップ 3：構造化された移行マッピング。すべての Web コンポーネントから React コンポーネントへの対応と prop の変換、認証設定のマッピング、embed.js の削除計画を含めます。
• ステップ 4：ファイルごとに、変更内容と適用した正確な diff。
• ステップ 5：実行した正確な型チェックコマンドと、残っているエラーがある場合はその概要。

認証情報の安全性

この移行では、API キー、JWT、認証設定値（例：window.metabaseConfig）を含むコードを扱うことがあります。次のルールに従ってください。

• 認証情報の値そのものは絶対に出力しないでください。コード内にハードコードされた API キー、トークン、シークレットが見つかった場合は、値を表示せず、変数名またはファイルの場所を参照してください（例：「config.js:12 のキー」）。
• コードの diff と概要では、解決後の値ではなく変数参照を使用してください。
• ハードコードされたシークレットが見つかった場合は、ユーザーに知らせ、移行の一環として環境変数への移動を推奨してください。

パフォーマンス

このワークフローはパイプラインとして設計されています。

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

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

リポジトリのブランチ、コミット、PR、issue は解析しないでください。ノイズが多く、関係ありません。

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

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

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

• *.{jsx,tsx,js,ts} ファイル内の metabase-dashboard、metabase-question、metabase-browser を grep します。
• window.metabaseConfig を grep します。
• /app/embed.js を grep します（script タグを見つけるため）。
• package.json を読み込みます（React の依存関係を確認し、パッケージマネージャーを検出します）。
• ロックファイル（yarn.lock、pnpm-lock.yaml、package-lock.json）を glob で検索します。
• ユーザーが対象バージョンを指定していない場合は、npm view @metabase/embedding-sdk-react version を実行します。

すべてのツール呼び出しを 1 つのメッセージで行います。

ラウンド 2 — prepare.sh の実行とドキュメントの取得（並行して実行）：

bash <skill-path>/scripts/prepare.sh {TARGET_VERSION}

対象の SDK npm パッケージをダウンロードして展開します。SDK_TMPDIR と d.ts の有無を出力します。

同じメッセージ内で、「許可されているドキュメントソース」に記載された URL 形式に従い、対象バージョンの llms-embedding-full.txt を取得します。

ラウンド 3 — read-sources.sh（Bash 呼び出しを 1 回）：

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

対象 SDK の d.ts 型定義を標準出力に出力します。

ラウンド 3 の後は、追加のツール呼び出しを行わずに、ステップ 1 の結果、ステップ 2 の結果、ステップ 3 の移行マッピングを出力してください。データの読み込みが完了したら、続けてステップ 3 をその場で作成してください。

対象範囲

このスキルは、React アプリ内で使用されている Modular embedding（Web コンポーネントベース）を、Modular embedding SDK（@metabase/embedding-sdk-react）に移行します。プロジェクトは、JSX/TSX ファイル内で Modular embedding の Web コンポーネントを使用している React アプリケーションである必要があります。

React ベースではないプロジェクトには、このスキルは適用されません。Web コンポーネントではなく iframe を使用しているプロジェクトでは、代わりに metabase-full-app-to-modular-embedding-upgrade スキルを使用してください。

このスキルで対応する内容

• JSX/TSX 内の <metabase-dashboard>、<metabase-question>、<metabase-browser> Web コンポーネントを、それぞれ対応する SDK の React コンポーネントに置き換えます
• @metabase/embedding-sdk-react npm パッケージをインストールします
• React コンポーネントツリーの適切な階層に <MetabaseProvider> を追加します
• window.metabaseConfig を MetabaseProvider の設定 props に変換します
• embed.js の <script> タグを削除します（通常は index.html または HTML エントリポイントにあります）
• window.metabaseConfig の代入を削除します
• HTML 属性名（ケバブケース）を React の prop 名（キャメルケース）に変換します

このスキルで対応しない内容

• 通常の HTML／テンプレートで Modular embedding の Web コンポーネントを使用している、React 以外のプロジェクト

使用可能なドキュメントソース

次の 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 を推測したりしないでください

バージョンの検出

バージョンの検出はすべて Round 1 で行ってください。

• Metabase インスタンスのバージョン：Docker イメージタグ（metabase/metabase:v、metabase/metabase-enterprise:v）、METABASE_VERSION、または env ファイル内のバージョン参照を検索します。検出できない場合は、AskUserQuestion を使用してください。
• 対象 SDK バージョン：
  • ユーザーが指定している場合は、そのバージョンを使用します。
  • それ以外の場合は、Metabase インスタンスのバージョンに基づいて対応する SDK バージョンを特定します（同じバージョン体系を使用します。Metabase v0.58 → SDK 0.58.x）。npm view @metabase/embedding-sdk-react version を実行し、対応する最新バージョンを確認してください。
• パッケージマネージャー：ロックファイルから検出します。例：yarn.lock → yarn、pnpm-lock.yaml → pnpm、package-lock.json → npm。

ワークフロー開始前の手順

移行計画チェックリスト

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

• Step 0：前提条件の確認
• Step 1：Modular embedding の使用状況をスキャン
• Step 2：対象 SDK の API を取得
• Step 3：移行マッピングを作成
• Step 4：コードを変更（ファイルごとにサブタスクを 1 つ作成）
• Step 5：型チェックと修正
• Step 6：最終要約

ワークフロー

Step 0：前提条件の確認

開始前に、以下を確認してください。

1. React 依存関係：package.json の dependencies または devDependencies に react があるか確認します。ない場合は、このスキルは React プロジェクトにのみ適用されるため、❌ 対応不可として記録します。
2. JSX/TSX 内の Web コンポーネント：Round 1 の grep 結果で、.jsx、.tsx、.js、.ts ファイル内に <metabase-* の使用があることを確認します（通常の HTML ファイルのみでの使用は対象外です）。Web コンポーネントが通常の HTML ファイル内でのみ使われている場合、このスキルでは React 内ですでに Web コンポーネントが使われている必要があるため、❌ 対応不可として記録します。
3. Metabase インスタンスのバージョン：「バージョンの検出」セクションを参照して、検出するかユーザーに確認します。
4. 対象 SDK バージョン：「バージョンの検出」の説明に従って特定します。
5. パッケージマネージャー：ロックファイルから検出します。

ステップ 1：Modular の埋め込みの使用状況をスキャンする

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

次のパターンを（すべて並列で）grep します。

• *.{jsx,tsx,js,ts} ファイル内の <metabase-dashboard — ダッシュボードの Web コンポーネント
• *.{jsx,tsx,js,ts} ファイル内の <metabase-question — 質問の Web コンポーネント
• *.{jsx,tsx,js,ts} ファイル内の <metabase-browser — コレクションブラウザーの Web コンポーネント
• window.metabaseConfig — グローバル設定の割り当て（index.html または JS/TS ファイルにある場合があります）
• /app/embed.js — embed.js の script タグ（通常は index.html にあります）

これにより、ファイルパスと一致する行が返されます。まだプロジェクトファイルは読み込まないでください。読み込みはステップ 4 で行います。

出力：カテゴリ別にまとめたファイル一覧：

Web components (JSX/TSX):
  - src/pages/Dashboard.tsx:15 — <metabase-dashboard dashboard-id="123">
  - src/pages/Analytics.tsx:22 — <metabase-question question-id="456">
Config:
  - public/index.html:8 — window.metabaseConfig = { ... }
Script tag:
  - public/index.html:12 — <script defer src="...embed.js"></script>

ステップ 2：対象 SDK の API を取得する

Round 2 で prepare.sh を実行します（ラウンドの予算を参照）。続いて Round 3 で read-sources.sh を実行し、d.ts をコンテキストに読み込みます。

d.ts が利用可能な場合は、次の情報を抽出します。

• エクスポートされているすべての React コンポーネント（例：MetabaseProvider、ダッシュボード／質問／コレクションのコンポーネント）
• 各コンポーネントの prop 型（エイリアス名だけでなく、具体的な型まで解決する）
• MetabaseProvider の設定型（受け付けるフィールド）
• 認証設定型

Round 2 で取得する埋め込みドキュメント（llms-embedding-full.txt）は、コンポーネントの使用方法、設定オプション、移行ガイダンスの補足資料です。完全に把握するため、d.ts と併せて使用してください。

d.ts が利用できない場合（SDK バージョン 0.52.0 より前では、単一の index.d.ts が同梱されていません）は、埋め込みドキュメントを主な API リファレンスとして使用します。d.ts もドキュメントも利用できない場合は、ステップ 2 を ❌ ブロックとして記録します。

ステップ 3：移行マッピングを作成する（ステップ 1～2 が完了し、✅ になった後）

対象範囲：ステップ 1 のスキャンで実際に見つかったコンポーネントと設定のみをマッピングします。

次の内容を網羅するマッピングを作成します。

コンポーネントのマッピング

ステップ 1 で見つかった各 Web コンポーネントについて、d.ts から対応する SDK の React コンポーネントを特定します。属性を prop にマッピングします。

## Migration Mapping

### <metabase-dashboard> → {SDK dashboard component from d.ts}
- `dashboard-id` → `dashboardId` (camelCase)
- `with-title` → `withTitle` (boolean prop)
- `drills` → check d.ts for equivalent prop name
- Other attributes → map to corresponding React props from d.ts

### <metabase-question> → {SDK question component from d.ts}
- `question-id` → `questionId` (camelCase)
- Other attributes → map from d.ts

### <metabase-browser> → {SDK collection component from d.ts}
- `initial-collection` → check d.ts for prop name
- Other attributes → map from d.ts

各マッピングについて、対象 prop の型を具体的な型まで解決します。属性に対応する SDK の prop がない場合は、「削除（SDK では非対応）」または「代替方法が必要」と記載します。

認証設定のマッピング

window.metabaseConfig のフィールドを MetabaseProvider の設定にマッピングします。

### Auth & Config
- window.metabaseConfig.instanceUrl → config.metabaseInstanceUrl (check d.ts for exact field name)
- window.metabaseConfig.jwtProviderUri → authConfig.jwtProviderUri or authConfig.authProviderUri or config.authProviderUri (check d.ts — the field was renamed from `jwtProviderUri` to `authProviderUri` in some versions)
- window.metabaseConfig.locale → locale prop or config field (check d.ts)

フィールド名の正確な情報源は d.ts です。推測しないでください。window.metabaseConfig のフィールドに SDK の設定型で対応するものがない場合は、その旨を記載します。

MetabaseProvider の配置

<MetabaseProvider> を追加する場所を特定します。

• Modular の埋め込み Web コンポーネントをすべて含む、最も階層が上の共通祖先コンポーネントを見つけます。
• 通常はアプリのルート（App.tsx、App.jsx、または同等のコンポーネント）です。
• プロバイダーはすべての SDK コンポーネントをラップする必要があります。ただし、コンポーネントがサブツリーにのみ存在する場合は、アプリ全体を不必要にラップしないでください。

削除計画

• embed.js の <script> タグ：削除するファイルと正確なコードを特定します。
• window.metabaseConfig の割り当て：削除するファイルと正確なコードを特定します。

ステップ 4：コードを変更する

ファイルごとの作業を始める前に：

1. SDK パッケージをインストールします。

   {package-manager} add @metabase/embedding-sdk-react@{TARGET_VERSION}
   

2. embed.js の <script> タグを削除します。
3. window.metabaseConfig の割り当てを削除します。
4. 移行した設定を指定して、決定した場所に <MetabaseProvider> のラッパーを追加します。

ファイルごとのタスク（Web コンポーネントを含む各ファイルについて）：

1. ファイルを読む — ファイルの内容を初めて読み込みます。
2. マッピング項目を照合する — このファイルに含まれる Web コンポーネントと、現在の属性を確認します。
3. 各 Web コンポーネントを変換する：
   • Web コンポーネントのタグを SDK の React コンポーネントに置き換えます。
   • HTML 属性（ケバブケース）を React prop（キャメルケース）に変換します。
   • 文字列の属性値を適切な JS 型に変換します（例："false" → {false}、"123" → {123}）。
   • SDK コンポーネントの import 文を追加します。
4. 報告する — 変更内容を出力します。

並列化の方針：

• ファイル数が 10 以下：すべてメインエージェントで処理します。
• ファイル数が 10 を超える場合：3～5 個のサブエージェントに分割します。それぞれにファイルパスと移行マッピング全体を渡します。

型変換ルール

HTML 属性値を React の props に変換する場合：

• 文字列 "true" / "false" → ブール値 {true} / {false}
• 数値文字列 "123" → 数値 {123}
• JSX 内にすでにあるテンプレート式（例：{dashboardId}）→ そのまま維持
• 静的な文字列 ID → d.ts の prop 型が文字列を受け付ける場合は文字列のまま維持し、それ以外の場合は変換

Step 5: 型チェックによる検証

1. 型チェックを実行 — npm run typecheck、tsc --noEmit、またはプロジェクトで同等のコマンドを実行します。
2. エラーを分析 — SDK 関連のエラーを根本原因ごとに分類します。
3. 期待される型を調べる — インストール済みの node_modules/@metabase/embedding-sdk-react/dist/index.d.ts で、失敗した各シンボルを検索します。
4. まとめて修正 — 型チェックを再実行する前に、すべての修正を適用します。
5. 検証 — 型チェックを再実行します。3 回試行してもエラーが残る場合は、❌ ブロックとします。

プロジェクトで TypeScript を使用していない場合は、d.ts と照らし合わせて変更内容を手動で確認し、prop 名と型が一致することを検証します。手動で検証した旨を添えて、Step 5 を ✅ とします。

Step 6: 出力の概要

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

1. 適用した変更 — 変更したファイルをすべて列挙し、それぞれの変更内容を 1 行で説明します。

2. コンポーネントの対応表 — 各旧 Web コンポーネントと新しい React コンポーネントの対応表：

| File | Old | New | Props Changed |
|---|---|---|---|
| src/Dashboard.tsx | <metabase-dashboard dashboard-id="1"> | <InteractiveDashboard dashboardId={1} /> | dashboard-id → dashboardId |

3. 認証の移行 — window.metabaseConfig を MetabaseProvider の設定にどのように変換したか。

4. 削除した成果物 — embed.js の script タグ、window.metabaseConfig、使用されなくなったコード。

5. 新機能 — Modular embedding では利用できなかった、現在利用可能な SDK 機能（例：React フック、型付きコールバック、InteractiveQuestion.FilterBar などのサブコンポーネント）。簡潔にまとめます。

6. インスタンス要件 — 必要な Metabase インスタンスの最低バージョン。Metabase インスタンスのバージョンは SDK のバージョンと一致している必要があります（例：SDK 0.58.x には Metabase v0.58 以降が必要です）。

再試行ポリシー

ドキュメントの取得：

• llms-embedding-full.txt の取得時に 404 が返された場合は、Metabase のバージョン番号を確認して再試行します。それでも失敗する場合は、ドキュメントを参照せずに進めます（主な情報源は d.ts です）。

npm pack：

• 対象のバージョンで npm pack が失敗する場合、そのバージョンは npm に存在しない可能性があります。❌ ブロックとし、その旨をユーザーに伝えます。

npm install：

• peer dependency の競合でパッケージのインストールに失敗した場合は、--legacy-peer-deps（npm）または同等のオプションを試します。競合についてユーザーに報告します。