rde-data-apps

rde-data-apps

データアプリは、リモート同期で接続されたリポジトリ内の data_apps/<slug>/ から、Metabase が /apps/<slug> で提供する React バンドルです。これをビルドするのが metabase-data-apps スキルです。このスキルは、rde がすでに把握している情報から質問への回答を見つけるため、rde では把握できないことだけをユーザーに尋ねます。また、アプリが読み取るコンテンツがアプリのビルド前にそのリポジトリ内にあることを確認してから、引き継ぎます。セクション 4〜6 は、データアプリスキルと異なる場合、スキーマの範囲、コミットとプッシュの順序、同期前の確認について優先されます。

1. インスタンス

rde status --json では、url がインスタンス（シークレットではありません）で、version は v65 以降またはヘッドビルドである必要があります。mb auth list --json で、url が一致するプロファイルを確認し、$PROFILE として使用します。Metabase がアプリを提供するには、リモート同期とデータアプリに対応したライセンスが必要です。rde doctor --json の license 行を確認してください。ライセンスがない場合、ユーザーは自身のターミナルで rde init --only license（またはこのセッションで ! rde init --only license）を実行して有効化します。トークンがチャットに入ることはありません。コンテンツの同期には remote-sync-type が read-write に設定されている必要があります（mb setting get remote-sync-type --json）。この設定の変更は同期の変更にあたるため、セクション 6 と同様に確認を得てください。

2. リポジトリ

rde status --json の contentRepository はリモート同期リポジトリの作業ディレクトリであり、metabase-data-apps セットアップガイドのステップ 1 への回答です。これを示して使用し、ユーザーには尋ねないでください。これが null で、ライセンスがリモート同期に対応している場合は、リポジトリの保存場所を尋ねてから、rde init --only git-sync --git-dir <path> --git-remote local を実行します（アカウントは不要で、~/.rde 内のベアリモートを使用します）。ホスト型リモートには Git トークンが必要なため、ユーザー自身に rde init --only git-sync を実行してもらいます。rde が作成するリポジトリでは、すでに .env.local、node_modules/、その他データアプリからプッシュしてはならないものが無視されます。

3. 認証情報

データアプリスキルは、リポジトリのルートにある .env.local から DATA_APP_MB_URL と DATA_APP_MB_API_KEY を読み取り、会話にキーを含めることを禁止しています。rde は mb が使用する API キーを保存しており、rde credentials --api-key はそれだけを出力します。セットアップガイドが認証情報のステップに進んだとき、またはチェック結果に MISSING と表示されたときは、ユーザーに尋ねる代わりにこのコマンドでファイルを作成します。ステップ 1 の <url> とステップ 2 の <repo> を使用してください。このコマンドは creds written だけを出力し、ファイル内のほかの行を保持して、.env.local が無視されることを確認します。

ROOT="$(git -C "<repo>" rev-parse --show-toplevel)" && KEY="$(rde credentials --api-key)" &&
{ grep -qxF .env.local "$ROOT/.gitignore" 2>/dev/null || echo .env.local >> "$ROOT/.gitignore"; } &&
{ if [ -f "$ROOT/.env.local" ]; then grep -v -e '^DATA_APP_MB_URL=' -e '^DATA_APP_MB_API_KEY=' "$ROOT/.env.local"; fi
  printf 'DATA_APP_MB_URL=%s\nDATA_APP_MB_API_KEY=%s\n' "<url>" "$KEY"; } > "$ROOT/.env.local.tmp" &&
mv "$ROOT/.env.local.tmp" "$ROOT/.env.local" && chmod 600 "$ROOT/.env.local" && echo "creds written"

出力がこちらに返ってくる場所では rde credentials --api-key を実行せず、.env.local を出力しないでください。キーは rde の管理者に属するため、アプリの対象がより限定されたユーザー向けの場合は、そのことを伝えてください。

4. リポジトリが信頼できる唯一の情報源です

データアプリはリモート同期を通じてのみ存在するため、ここでは提案ではなく必須要件です。セクション 2 では、リモート同期が未設定の場合に設定します。rde が自発的にリモート同期を提案するのはこの場合のみです。ユーザーがアプリを求めているためです。STATE.md に remote_sync として記録してください。アプリ以外では、リモート同期がすでに設定されている場合に限り、rde スキルが同期を取り上げます。

バンドルは、Metabase オブジェクトを ID と型付きスキーマを通じて参照します。インスタンス内にしか存在しないコンテンツを基に構築したアプリは、そのインスタンスでしか動作しません。リポジトリを別のインスタンスにインポートしても、アプリは読み込む定義を伴わずに持ち込まれるため、クエリは失敗します。そのため、アプリが読み込むものはすべてアプリの構築前にリポジトリに存在している必要があり、ビルドで作成されるものはすべてアプリと一緒にリポジトリに保存されます。

• アプリが読み込めるもの。 フィールドのメタデータ、メジャー、セグメントを含むライブラリ公開テーブル、ライブラリのメトリクスコレクションに登録されたメトリクス、アプリがアクションを実行するモデル（同期済みコレクション内のもの）。これ以外は読み込めません。
• 「リポジトリに存在する」の意味。 ライブラリのコレクションに is_remote_synced: true が設定されていること（mb git-sync status --json の synced_collections）、コンテンツがエクスポート済みであること、そして git pull によって作業ツリーに取り込まれていることです。ファイルが databases/…/tables/<table>/ と collections/… の下に実際にあり、確認済みであることを意味します。存在すると仮定するだけでは不十分です。
• メジャーとセグメントには公開テーブルが必要です（rde スキルの references/remote-sync.md の「What belongs in git」を参照）。ライブラリがない場合（mb library get --json が失敗する場合）は、メトリクスを同期済みコレクションに登録し、メジャーとセグメントは引き継げないことを伝えてください。
• アプリ独自のコレクションも同期対象です。 npm run build は sync-resources を実行し、各 queries/ 定義を Data App: <slug> の質問として保存します。そのコレクションをアプリと一緒に同期するよう設定してください。質問を作成または変更するビルドのたびに、mb git-sync dirty --json にエクスポート対象として表示されます。表示されない場合は、回避策を講じるのではなく、引き継ぎ時にその旨を伝えてください。
• スキーマの範囲。 metabase.data.ts はライブラリのスコープのみを使って生成します。include-data-library=true、include-metric-library=true、または library-collections=<ids> を指定し、アプリがアクションを実行する場合は include-models=true も指定します。database=<id> は絶対に指定しないでください。これは同期の有無にかかわらず、インスタンスからテーブルを直接読み込み、リポジトリにないコンテンツを基にアプリが構築される原因になります。
• ビルド中にエンティティの不足が判明した場合（メジャー、セグメント、メトリクス、公開テーブル、アクション）は、rde スキルに戻ります。ライブラリ内に作成し、ゲートを通し、同期し（セクション 5 および 6）、git pull を実行し、スキーマを再生成してから続行してください。UI のブロックを解除するために、その場しのぎで作成してはいけません。
• アプリのコードを最初に 1 行書く前に、アプリに必要なすべてのエンティティがライブラリのスコープから生成したスキーマに含まれ、そのファイルが作業ツリーに存在していなければなりません。不足しているものがあれば、作業を止めて rde に戻ってください。

5. 安全に同期する

リモート同期では何もマージされず、競合も解決されません。インスタンス側（インポートやエクスポートの前に毎回確認すること、どちらを先に行うか、ユーザーの「はい」がない限り --force を使わないこと）とステージングからの引き継ぎについては、rde スキルの references/remote-sync.md にある「各ステップの前に」と「ステージング」を参照してください。ここでは、Metabase のエクスポート後の git push も拒否されます。また、Metabase のエクスポートとアプリのコミットという2つの書き込み元が同じリモートにプッシュするため、手順を合わせてください。

• ワーキングツリー側。 アプリのコミットが変更するのは data_apps/<slug>/ のみです。エクスポートされた Metabase YAML を手作業で編集することはありません。Metabase のエクスポートをプルする前に、git stash --include-untracked、git pull --ff-only、git stash pop の順に実行します。git push の前には毎回、あらためて git pull --ff-only を実行します。ファストフォワードできないプルが発生した場合は停止し、両方の履歴を報告してください。マージも強制プッシュもしないでください。
• デリバリーの順序。 各ステップはクリーンな状態から開始します。npm run build（アプリの質問が作成される場合があります）→ インスタンスの変更セット（アプリの質問と新しい定義があればそれも）をエクスポート → ワーキングツリーで stash、pull、pop → resources_metadata.json を含めてアプリをコミット → pull、push → mb git-sync import → <url>/apps/<slug> を開く。
• ブランチ。 インスタンスが追跡するブランチは1つです（mb git-sync status --json の branch）。明示的な「はい」がない限り、main または master へのエクスポートやプッシュはしないでください。それ以外の場合は mb git-sync create-branch agent/<slug> を実行し、アプリも同じブランチにプッシュして、コンテンツとアプリを一緒に移動させてください。

6. 同期に関わる操作の前に確認する

同期の各ステップは、同期先リモートへの git push も含め、まず承認を得ます。同期ポイントごとに1回確認してください。rde スキルの references/remote-sync.md にある「各同期ステップの前に確認する」を参照してください。「このジョブの残りはすべて許可する」という回答は記録し、再度確認しません。それ以外の回答の場合は、次の同期ポイントであらためて確認します。

ビルドの前に「今はしない」と言われた場合、選べるのは1つだけです。開発プレビューのみとし、このインスタンス単独で動作し、リポジトリをインポートした先では動作しないことを明記します。参照するコンテンツが同期されるまで、同期対象のブランチには何もプッシュしません。

7. 引き継ぎ

metabase-data-apps スキルには各ステップのガイドがあります。セクション4から6を優先しつつ、アプリのコードについてはそのガイドに従ってください。

ステップ	metabase-data-apps のガイド
アプリがまだない場合：作成、ひな形の作成、セットアップ	setup/setup.md
アプリが Metabase のテーブル、メトリクス、メジャー、またはセグメント（生成された metabase.data.ts）を読み取る場合	セクション4のライブラリスコープを含む semantic-layer/semantic-layer.md
ページが複数ある場合	routing/routing.md
書き込み操作：フォーム、更新、削除、保存済みアクション	actions/actions.md

8. アプリが使うデータ

アプリは、セマンティックレイヤーがライブラリに公開するデータを読み取ります。表示する数値の背後にメトリクスやメジャーがまだない場合は、まず rde スキルに戻ります（元データが未加工の場合は、先にそのセマンティックレイヤーのプレイブックに従い、テーブルを整えます）。その後、セクション4から6を経てリポジトリに反映します。これにより、アプリは定義をIDでクエリし、queries/ で再導出することはありません。rde スキルが ./.scratch/STATE.md を管理している場合は、アプリのスラッグ、読み取るID、同期対象のコレクション、各同期についての判断を記録してください。

9. デリバリー

セットアップガイドはコミットとプッシュで終わります。セクション6で確認を得た後、セクション5の順序で実行してください。rde のローカルリモートを使う場合、プッシュ先は ~/.rde 内のベアリポジトリです。続いて mb --profile $PROFILE git-sync import --json を実行すると、アプリが Metabase に取り込まれ、<url>/apps/<slug> で開けるようになります。引き継ぎでは、何をどのブランチに、どのコミットで同期したかを明記してください。