Code Apps 開発スキル

Power Apps Code Apps（コードファースト）を TypeScript + React + Tailwind CSS で開発する。 UI 設計・CSP 構成・メール送信パターンまで Code Apps 開発の全領域をカバーする統合スキル。

プラント・設備の JSON 駆動設計: モジュール設計パターン と 追加テンプレート を参照。敷地・ユニット・ポート接続、CSP 対応検証器、 Python 候補生成、Dataverse 改訂・提案レビューを再利用できる。既存アプリへのアドオンであり scaffold 元ではない。 型・形状・共有保存の単独テストを先に通し、導入後のブラウザー/Teams/一般利用者権限は別ゲートで実測する。

設計と保守を統合する場合: Plant Design & Maintenance サンプル を参照。 既存画面・合成3Dモデル・部位別の故障／修理・ヒートマップ・AI候補の変更前後比較を同梱。 npm ci → Python依存導入 → npm run generate → npm run predeploy で単体検証できる。 AI候補は確定まで下書きに適用せず、共有保存と分離する。外部接続は既定無効。Code App は Dataverse と Copilot Studio の生成サービスだけへ接続し、MCP Server は Copilot Studio のツールとして構成する。

3D モデル（建物・家具・設備）を扱う場合: 3D 資産の共通利用 を参照。 既定 CSP で読める資産の持ち方（画像は img-src 'self'、JSON は import、GLB の扱い）、素材ライブラリの色合わせ・ライセンス、 契約検証（scripts/validate_3d_assets.py）とヘッドレス描画確認（scripts/capture_3d.mjs。ソフトウェア描画で黒くなる問題を含む）、 実在の GLB（テクスチャ埋め込み）を既定 CSP の中で表示する方法（?inline + createImageBitmap のプラグイン）を再利用できる。 工事・設備の進捗を 3D で見せる場合（完成形を破線、施工中をクリッピングで立ち上げる、部位と工程の対応、GLB の書き出し）は 3D 施工進捗モデル を参照。drei の <Environment preset> は CSP で失敗するとアプリ全体が落ちるので使わない（チェック 13 が検出）。

図面レビューを非同期会話で回す場合: 図面コミュニケーション アドオン と PoC サンプル を参照。版付き図面 JSON と検証器、A3 の SVG 描画、 注釈／タスク、候補の差分・採用・Undo、会話の相関コントラクト（会話 ID・ターン ID・編集バージョン・基準ハッシュ、重複ターン拒否）、 A3 PDF を生成する Python スキルを再利用できる。Dataverse 未接続時は DEMO ワーカーであることを UI に明示し、実エージェント応答と偽らない。

[!NOTE] 本スキルは React + Vite の Web Code Apps 用。Expo／React Native、camera／barcode／location 等の 端末ネイティブ機能、Power Apps Developer app、Wrap が要件なら mobile-apps へ切り替える。Native は Private Preview で本番利用できない。

[!NOTE] Microsoft Learn の現行概要では、Code Apps は React / Vue などの SPA を Power Apps 上でホストする仕組み とされている。 この開発標準はその中でも React ベース実装に標準化したガイドであり、他フレームワーク一般論ではなく、このリポジトリのテンプレートと運用実績に基づく推奨事項をまとめている。

1. 概要

Code Apps 開発は 設計 → 初回デプロイ → データソース接続 → 改善デプロイ の順に進む。

[!NOTE] サブエージェント並行実行パターン: architecture スキルで Code Apps が確定し、dataverse スキルで スキーマが承認されたタイミングで、このスキルがサブエージェントとして起動される。 Dataverse 構築（--skip-localize フェーズ）と Code Apps 開発（scaffold → deploy → add-data-source）は 並行して進める。Dataverse 構築が先に終わったら --localize-only でローカライズ＆デモデータ投入。

標準ワークフロー全体像

[設計]  ① デザインテンプレートを選ばせる（6種・プレビュー付き）
        ② 画面設計（design-pattern）→ ユーザー承認
          │
[§2 初回デプロイ]
        ③ テンプレート scaffold + npm install（業務テンプレートがあれば templates/sales-crm 等から生成。Dataverse 構築 Phase 2 と並行して即着手／VS Code では Code Apps サブエージェントとして起動）
        ④ ソリューション + 接続参照を用意（setup_connection_reference.py）★init より前
        ⑤ npx pa app init（power.config.json 生成）
        ⑥ vite.config.ts 必須設定の確認 / .env 設定
        ⑦ npm run deploy -- --solution-id {GUID}（build + pa app push）★初回 push でソリューション所属が確定
          │
[§3 データソース接続]
        ⑧ npx pa app add data-source --connector shared_commondataserviceforapps --connection-ref ... -s ...（1 回だけ）
        ⑨ MicrosoftDataverseService + *WithOrganization ラッパーを実装
          │
[§4 改善デプロイ]
  ⑩ src/ 実装 → npm run deploy（pa app push を反復）
  ⑪ 最終 push 後に pa app share（利用者は play、共同開発者だけ edit）

この後の章構成

章	内容
§1 概要（本章）	標準ワークフロー全体像・大前提・設計フェーズ（デザインテンプレート選択）
§2 初回デプロイ	環境前提・scaffold・ソリューション/接続参照の準備・init・初回 build & push
§3 データソース接続	add_data_source.py（コネクタ ID 自動解決・非対話）・接続参照バインド・MicrosoftDataverseService・Lookup 名前解決
§4 改善デプロイ	開発時の必須ルール・再デプロイ・プレデプロイレビュー
§5 リファレンス	全リファレンス索引・技術スタック・.env

[!NOTE] 本スキル内のコード例は {prefix}_tablename 等のプレースホルダーで汎用化されています。 実際のテーブル名・型名は、あなたのプロジェクトのエンティティに読み替えてください。 パターン（Lookup 名前解決、SDK ラッパー、useMemo マップ等）はそのまま適用できます。

設計フェーズ（実装前に必須）

コードを書く前に、デザインテンプレートの選択と UI 設計を行い、ユーザーの承認を得ること。 手順:

1. デザインテンプレート集 の 6 種を一覧＋プレビューで提示し、ユーザーに 1 つ選んでもらう（デプロイされるアプリは常に 1 テンプレート。dark/light は ThemeProvider + ModeToggle）。
2. デザインシステム を読み込み、画面構成・コンポーネント選定・Lookup 名前解決パターンを設計する。
3. 設計（選択テンプレート＋画面設計）を提示し、「この設計で進めてよいですか？」と承認を得る。承認の証跡を残す場合は、設計承認 Issue テンプレート を対象プロジェクトの .github/ISSUE_TEMPLATE/ にコピーして Issue を作成する。
4. 承認後、選択テンプレートの CSS Variables を styles/index.pcss に適用してから実装する（変数一式・適用手順は デザインテンプレート集）。

CRUD 画面は CRUD UI 標準パターン に必ず従う: 一覧は行／カード全体をクリックして詳細を開く（目アイコン等の小さなクリック領域は使わない）、詳細の編集はモーダルではなくインライン編集モード、行内の削除・クイック操作は e.stopPropagation()、削除確認はブラウザの confirm() ではなくモーダル（useConfirm() / AlertDialog）。指示がなくても、テーブルごとに「一覧・詳細（インライン編集）・作成・削除」を標準実装すること。

画面の骨格は デザインシステム からコピーして書き始める: マルチカラムは grid-cols-[minmax(0,1fr)_...]（素の 1fr は使わない）＋直接の子すべてに min-w-0、長文は break-words ではなく [overflow-wrap:anywhere]、コード・表・JSON は overflow-x-auto で閉じ込める。min-w-0 は後付けすると必ず抜けるため最初から書く。npm run predeploy のチェック 7 が抜けを警告する。

画面が 3 つ以上あるアプリには 使い方ガイド を標準実装する: 初回起動でカルーセルを自動表示し、「使い方を見る」から実操作ツアーへ繋ぐ。設計提示の段階でスライド構成（4〜6 枚）とツアー手順を画面一覧と一緒に示す。

設計で提示する内容: 選択テンプレート、画面一覧（ページ名・ルート）、各画面のコンポーネント構成、カラム定義、Lookup 名前解決方法（_xxx_value + useMemo Map）、ナビゲーション構造、テレメトリの転送先と監視する SLI（転送しない場合も明記）。

大前提（ソリューション運用）: Dataverse テーブル・Code Apps・Power Automate・Copilot Studio は同一ソリューション内に開発し、.env の SOLUTION_NAME / PUBLISHER_PREFIX を全フェーズで統一する。詳細は standard スキル。

2. 初回デプロイ

環境の前提条件（デプロイ前に必ず確認）

1. Power Platform 管理センターで「コード アプリを許可する」がオン
   → オフの場合: CodeAppOperationNotAllowedInEnvironment (403) エラー

2. npm CLI のアクティブアカウントが対象テナント用
  npx pa auth status
  npx pa auth switch --account user@contoso.com

3. power.config.json は npx pa app init で生成する
   → テンプレートから手動コピーしない
   → 別環境の appId が残っていると: AppLeaseMissing (409) エラー
  → 新規環境では必ず npx pa app init で新規生成

環境全体の状態（既定環境ではないか / マネージド環境 / Dataverse / Code Apps / MCP / セキュリティ ロール / DLP）は admin スキル の check_environment.py でまとめて確認できる。 開発着手前に一度実行しておくと、デプロイ直前の 403 を避けられる。 Code Apps の必須条件は環境で「コード アプリを許可する」が有効であること。 マネージド環境はガバナンス上の選択肢であり、Code Apps のデプロイ要件ではない。 CLI の実行ファイル名は pa。@microsoft/power-apps-cli は bin を power-apps から pa にリネームし、 コマンドも group 化した（init → app init、push → app push、auth-status → auth status）。 旧名を呼ぶと npm error could not determine executable to run だけが出て原因が見えない。 npm run predeploy（チェック 11）が package.json のデプロイコマンドとインストール済み bin 名の不一致を検出する。 全コマンドの対応表は npm CLI リファレンス。

プロジェクトの 3 つの生成段階（生成物は手動作成・コピー禁止）

生成元	主な生成物
① テンプレート scaffold	vite.config.ts / plugins/ / styles/ / src/ / tsconfig* / package.json 一式
② npx pa app init	power.config.json（＋ .power/）。vite.config.ts や plugins/ は生成しない
③ npx pa app add data-source --connector shared_commondataserviceforapps	.power/schemas/appschemas/dataSourcesInfo.ts / src/generated/services/MicrosoftDataverseService.ts / src/generated/models/MicrosoftDataverseModel.ts

どのファイルを誰が生成し、何をカスタマイズしてよいかの一覧は ビルドリファレンス。SDK 管理ファイル（power.config.json / dataSourcesInfo.ts / src/generated/）は手動編集禁止。

テンプレートのプレースホルダー設計

テンプレートのデモメニューには template: true フラグが付いている。このフラグが残ったまま npm run predeploy を実行するとエラーになるため、削除忘れを防げる。

// template: true が付いた行はデプロイ前に削除 or テーマ用に書き換える
{ label: "顧客", path: "customers", iconKey: "customers", template: true },
// テーマ固有のメニュー（template フラグなし）
{ label: "ダッシュボード", path: "dashboard", iconKey: "dashboard" },

デプロイ前は npm run predeploy（.env・power.config.json を自動検証）→ npm run deploy（predeploy + build + push を一括実行）。

テンプレートは src/lib/telemetry.ts を含み、起動時に initializeLogger を登録する。既定では外部送信せず、 クエリ文字列・フラグメント・GUID を除去したメトリクスだけを code-apps:telemetry イベントへ出力する。 Application Insights 等へ転送する場合は custom sink と CSP の connect-src を合わせて設計する （テレメトリ / 可観測性パターン）。

標準ワークフロー

上から順に実行すれば動く正常系フロー。各 Step の詳細・必須設定・型定義は ビルドリファレンス を参照。

# Step 0: テンプレート scaffold（標準では @GeekPowerCode が scaffold）
# Code Apps 採用が決まった時点（設計承認後）で、Dataverse 構築（Phase 2）と並行して着手する
# （npm install はネットワーク待ちのみで Dataverse 構築をブロックしないため、待たずに並行実行する）。
# VS Code では本トラック全体を「Code Apps サブエージェント」として並行起動できる。
# 先行工程（scaffold / init / 初回 build & push）はテーブル不要。以下は Dataverse 接続情報の準備を待つ同期点:
#   ★同期①: shared_commondataserviceforapps の connectionId / orgUrl が揃ったら add data-source を 1 回実行
#   ★同期②: pa app add flow は Power Automate Phase 5（フロー実装）完了後に実行
# 詳細は standard §8「開発フロー全体図」を参照。
cp -n .github/skills/standard/references/gitignore-template .gitignore   # .gitignore がなければコピー
# 共通スキャフォールダーで生成計画を確認し、同じコマンドから --dry-run を外して生成する
python .github/skills/update-skills/scripts/scaffold_from_template.py \
  --template .github/skills/code-apps/templates/generic-base --target {TARGET_DIR} --dry-run
python .github/skills/update-skills/scripts/scaffold_from_template.py \
  --template .github/skills/code-apps/templates/generic-base --target {TARGET_DIR}
# 業務テンプレートから始める場合は --template を差し替える（generic-base を extends 済み。例: 営業支援 CRM）
#   --template .github/skills/code-apps/templates/sales-crm
#   --template .github/skills/code-apps/templates/agm-qa-assist   # 株主総会 Q&A アシスト
#   --template .github/skills/code-apps/templates/store-ordering  # 店舗発注システム（業務端末風 UI ＋ Dataverse ＋ 合成デモデータ）
#   --template .github/skills/code-apps/templates/construction-cockpit   # 建設現場コックピット（--var PUBLISHER_PREFIX / COWORK_PLUGIN_ID / DATAVERSE_ORIGIN）
#   --template .github/skills/code-apps/templates/perse3d-studio   # パース3D内見スタジオ（--var PUBLISHER_PREFIX）
# scaffold.json に questions があるテンプレートは、値を AskUserQuestion で 1 問ずつ聞いてから生成する:
#   --questions --env <answers.env> で未回答の質問（JSON）を出す → 1 問ずつ聞いて answers.env に追記 → [] になるまで繰り返す
#   → --env <answers.env> --write-env {TARGET_DIR}/.env で生成（答えが .env にも入る）
# 対象ディレクトリは空（.git / .github / .vscode / .env だけなら空とみなす）であること
npm install --no-audit --no-fund

# 既存プロジェクトを更新するときは SDK / CLI とも latest を候補にし、build と CLI help を再検証する
npm install @microsoft/power-apps@latest
npm install -D @microsoft/power-apps-cli@latest
npx pa --help          # ★ bin 名は pa。コマンドは auth / app / connector / connection / solution の group 制
npm run build
# バージョン方針と検証項目: references/cli-reference.md#バージョン方針

# Step 1: ソリューションと接続参照を用意（init より前に必須）
# 接続 ID 直バインドはソリューションに入らないため、接続参照（Connection Reference）を先に作る。
# 既存 CR 流用ファースト → 無ければ Dataverse Web API で新規作成（ポータル操作不要）。
python .github/skills/code-apps/scripts/setup_connection_reference.py
#   → 出力される {CONNECTION_REFERENCE_LOGICAL_NAME} と {SOLUTION_ID} を控える
#   → 詳細は references/solution-alm.md

# Step 2: npm CLI の認証先を確認して初期化
npx pa auth status
npx pa auth switch --account user@contoso.com
npx pa app init --environment-id {ENVIRONMENT_ID} --display-name "AppName" --app-type CodeApp

# Step 3: vite.config.ts 必須設定を確認（base: "./" / external に @microsoft/power-apps を含めない）
#         → references/build-reference.md Step 2

# Step 4: .env.example を .env にコピーしてテーマ固有の値を設定

# Step 5: 初回ビルド＆デプロイ — ★必ず -s を付ける（almMode が Solution になるのは初回 push だけ）
#         対象環境は power.config.json の environmentId を使う（push には --environment-id が無い）
npm run build
npx pa app push --solution-id {SOLUTION_ID}

# Step 6: Dataverse コネクタを 1 回追加（全テーブル共通・接続参照バインド）
npx pa app add data-source --connector shared_commondataserviceforapps \
  --connection-ref {CONNECTION_REFERENCE_LOGICAL_NAME} \
  --solution-id {SOLUTION_ID} \
  --org-url {DATAVERSE_URL} \
  --non-interactive

# Step 7: src/ を実装（MicrosoftDataverseService を薄くラップ）
#   業務ロジックに入る前に 1 回 predeploy を通し、config.ts と router.tsx の不整合を早期検知する
npm run predeploy
#   → 以降はページを追加するたびに実行する（ナビとルートの不一致はデプロイ後にしか見えない）

# 再ビルド＆デプロイ（反復）
npm run build
npx pa app push

# Step 8: 最終 push 後に共有（カンマ区切りで複数指定可）
#   共有先環境は power.config.json で決まる（share に --environment-id は無い）
npx pa app share --principal "${CODE_APP_PLAY_PRINCIPALS}" \
  --access play --non-interactive --json

共有対象のユーザー／サービスプリンシパル、edit の最小権限ルール、CI/CD 例は npm CLI リファレンスの app shareを参照する。

Step 5 の --solution-id は後戻りできない: 初回の pa app push --solution-id がアプリを almMode: Solution にするのは appId 未割当の初回 push のみ。almMode: Environment で作ってしまったアプリは、後から -s を付けて push してもソリューションに入らず、Power Apps ポータルの「既存の追加 → アプリ → コード アプリ」でしか 復旧できない。詳細は ソリューション ALM リファレンス。

-s に渡す値は CLI で違う: pac code push -s はソリューション名だが、 npx pa app push -s は GUID を要求する（CLI 0.13.0 で GUID 検証が入り、名前はエラーになった）。 詳細は ソリューション ALM。

インポート／ラッパーの必須パターン: 生成された MicrosoftDataverseService を薄いラッパーで包み、ListRecordsWithOrganization / CreateRecordWithOrganization / GetItemWithOrganization / UpdateRecordWithOrganization / DeleteRecordWithOrganization に Dataverse URL（organization）を必ず渡す。organization を省略すると Invalid organization URL 'null' provided で失敗する。詳細は ビルドリファレンス を参照。

デプロイコマンドの選択

コマンド	認証基盤	テナント問題	推奨度
python scripts/setup_connection_reference.py	auth_helper（PAC プロファイル再利用）	なし	✅ 標準（init の前に実行）
npx pa auth status / pa auth switch --account {UPN}	Power Apps npm CLI	アクティブアカウントを明示	✅ テナント切り替え時に必須
npx pa app init --environment-id {ID} --display-name "Name" --app-type CodeApp	Power Apps npm CLI	上記で確認	✅ 標準
npx pa app push --solution-id {GUID}	Power Apps npm CLI	上記で確認	✅ 標準（初回から GUID 必須。環境は power.config.json から）
npx pa app add data-source --connector shared_commondataserviceforapps --connection-ref {CR} --solution-id {GUID} --org-url {url}	Power Apps npm CLI + 接続参照	pa auth が別キャッシュ	✅ 標準（ALM 対応）
npx pa app add data-source ... --connection-id {id}	Power Apps npm CLI + 接続	同上	△ ソリューションに入らない（PoC のみ）
pac code *	PAC CLI プロファイル	npm CLI と別キャッシュ	△ npm CLI で解決できない場合のみの移行時代替
npm run deploy -- --solution-id {GUID}	Power Apps npm CLI	auth switch で切り替え	✅ 初回デプロイに推奨（predeploy チェック付き）

CI/CD・秘匿化（チーム開発で継続的にデプロイする場合）

.env の秘匿化・${VAR} テンプレートの汎用化・pre-commit ゲート・レビューゲート・ 承認付きデプロイ・リリース記録は alm スキル が担当する。 npm run deploy を alm のデプロイジョブに差し込むだけで、同じ ALM 基盤に載せられる。

Code Apps での alm 実行可否チェック（最小検証）

# 1) ALM スクリプトと設定雛形を取り込む
cp .github/skills/alm/scripts/*.py scripts/
cp .github/skills/alm/alm.config.example.json alm.config.json

# 2) Code Apps 用にパス定義を最小調整（例）
#    templates: ["power.config.template.json"]
#    rendered : ["power.config.json"]
#    artifacts: ["dist/**"]
#    non_secret_vars: ["APP_NAME"]

# 3) 決定論ゲートを実行
python scripts/review_sanitization.py
python scripts/gate_rules.py --gate quality --out .gate/quality.json
python scripts/gate_rules.py --gate generalization --out .gate/generalization.json
python scripts/review_report.py --verdict-dir .gate --out .gate/review-report.md

運用モジュール（選択式）

モジュール	構成	使うとき
pp-only	Power Platform 単体（PAC CLI + npm run deploy）	まず Code Apps 単体で ALM を確立したい
pp-azure-gha	GitHub Actions + Azure（OIDC）	GitHub 中心で Azure 連携も必要
pp-azure-ado	Azure DevOps + Azure（WIF）	Azure DevOps の承認・監査を使いたい

モジュール別の詳細は alm/references/ci-providers.md を参照。

→ 詳細: alm スキル

接続方式の比較

比較対象	参考
shared_commondataserviceforapps を 1 回追加して MicrosoftDataverseService を共有する方式	connector-reference.md, build-reference.md
pac code add-data-source -a dataverse -t <table-logical-name> をテーブル単位で追加する方式	Microsoft Learn: How to: Connect your code app to Dataverse, Microsoft Learn: Troubleshoot adding a data source

[!NOTE] Microsoft Learn との比較: Learn の現行ガイド「How to: Connect your code app to Dataverse」（2026-04-07 更新）と 「Troubleshoot adding a data source」（2026-02-02 更新）は、どちらも pac code add-data-source -a dataverse -t <table-logical-name> を Dataverse 追加の基本手順として説明している。 このスキルの shared_commondataserviceforapps 手順は このリポジトリで採用する connector-first パターンであり、 Learn の基本手順をそのまま置き換えたものではない。判断基準は次のとおり:

• Learn / PAC 標準: テーブルごとの型付き Service / Model を生成したい
• 本スキル標準: 1 回の接続で MicrosoftDataverseService を生成し、entityName で複数テーブルを横断したい
• 性能面: Microsoft Learn に両者の明確なベンチマーク差は記載されていない。通常は Dataverse 側のクエリ形状 （$select / $filter / $top）、ページング、ネットワーク待ちの影響が支配的で、接続方式そのものの差は主因になりにくい
• 実務上の判断: 性能よりも、型安全性・再生成コスト・複数テーブル横断のしやすさで選ぶ

3. データソース接続

MCP Server は Copilot Studio 経由に統一する

Code App に MCP カスタムコネクタを直接追加しない。会話・検索・原本取得は Code App → Copilot Studio → MCP Server、画面表示用の構造化データやページ画像は 取り込み処理 → Dataverse → Code App と分離する。画像や大きなバイナリをエージェント応答へ載せない。

同じ MCP 接続が Code App の同意一覧へ重複すると、接続更新ボタンが反応せずモーダルが閉じないことがある。 誤って追加した場合は SDK 管理ファイルを手編集せず、CLI で削除する。

npx pa app remove data-source --connector <shared_mcp_connector_id> --force --non-interactive

標準 pre-deploy-check.mjs は .power と src/generated の /api/mcp / InvokeServer を検出し、 直接 MCP データソースが残ったデプロイを拒否する。詳しい切り分けは トラブルシューティング を参照する。

正常系: コネクタ ID は聞かずに解決する（add_data_source.py）

npx pa app add data-source はコネクタ ID や接続を省略すると 対話プロンプトで停止し、 スクリプト実行・CI・エージェント実行が入力待ちのまま固まる。これを避けるため、 データソース追加は次のラッパーを正常フローとする。コネクタは「SharePoint」「Outlook」などの 通称で指定でき、スクリプトが shared_xxx に解決してから --non-interactive で CLI を起動する。

# SharePoint（接続は環境内に 1 つなら自動選択）
python .github/skills/code-apps/scripts/add_data_source.py --connector sharepoint `
  --dataset "{SITE_URL}" --table "{LIST_ID}"
# ファイル作成などの操作はテーブルとは別に --as action で追加する（troubleshooting #57）
python .github/skills/code-apps/scripts/add_data_source.py --connector sharepoint --as action `
  --connection-ref {CONNECTION_REFERENCE_LOGICAL_NAME} --solution-id {SOLUTION_ID}

# Dataverse（ALM 標準: 接続参照バインド。--org-url は .env の DATAVERSE_URL を既定値にする）
python .github/skills/code-apps/scripts/add_data_source.py --connector dataverse `
  --connection-ref {CONNECTION_REFERENCE_LOGICAL_NAME} --solution-id {SOLUTION_ID}

# 使えるコネクタの通称一覧 / 実行せずコマンドだけ確認
python .github/skills/code-apps/scripts/add_data_source.py --list-connectors
python .github/skills/code-apps/scripts/add_data_source.py --connector teams --dry-run

解決すること	方法
コネクタ ID	コネクタ ID カタログ の通称・別名で解決。無ければ pa connector list --search で環境から解決
バインド先	--connection-ref + --solution-id（ALM 標準）。未指定なら pa connection list で接続を 1 つに絞れたときだけ自動選択
追加値	--org-url / --dataset / --table / --procedure。コネクタごとの必須項目はカタログの requires

ハングしない仕組み: CLI は必ず --non-interactive かつ 標準入力を閉じた状態で起動し、 --timeout（既定 600 秒）を超えたら停止する。値が足りないときはプロンプトを出さずに NG: と不足項目・取得コマンドを表示して終了コード 1 で止まる。 候補が複数のときも勝手に選ばず、候補一覧を出して止める（誤ったコネクタへのバインドを防ぐため）。

カタログに無いコネクタ: --connector shared_xxx のように ID を直接渡せばそのまま通る。 繰り返し使うものは connector-catalog.json に id / displayName / aliases / requires を追記する（他スキルの DLP 事前チェックでも同じ通称が使える）。

Microsoft Dataverse connector（shared_commondataserviceforapps）

Dataverse 接続は shared_commondataserviceforapps を 1 回だけ追加する方式を標準とする。これにより、テーブルごとに add data-source を繰り返さなくても、生成された MicrosoftDataverseService から entityName を実行時に渡して全テーブルへ CRUD できる。

npx pa app add data-source --connector shared_commondataserviceforapps を 1 回実行すると、.power/schemas/appschemas/dataSourcesInfo.ts に加え src/generated/services/MicrosoftDataverseService.ts と src/generated/models/MicrosoftDataverseModel.ts が生成される。アプリ側ではこの生成サービスを薄いラッパーで包み、organization に対象環境の Dataverse URL を明示的に渡す。

バインド先は 接続 ID ではなく接続参照（--connection-ref）を標準とする。接続はソリューション コンポーネントになれないが、接続参照はなれるため、環境間移送ができる。

# Step 1 で作成済みの接続参照にバインドする（add_data_source.py が内部で実行するコマンド）
npx pa app add data-source --connector shared_commondataserviceforapps \
  --connection-ref {CONNECTION_REFERENCE_LOGICAL_NAME} \
  --solution-id {SOLUTION_ID} \
  --org-url {DATAVERSE_URL} \
  --non-interactive

接続参照にしても 「1 回の追加で全テーブルをカバーする」設計は変わらない（--connector はコネクタ単位。生成ファイル 2 つ・生成メソッド同一・アプリコード変更不要）。power.config.json には xrmConnectionReferenceLogicalName が 1 行追加されるだけである。検証結果と確認コマンドは ソリューション ALM リファレンス。

接続参照は CLI では作れない: --connection-ref に未存在の論理名を渡すと Failed to resolve connection ID for reference '...' で失敗する（自動作成されない）。 ポータル手作業を避けるため、Step 1 の setup_connection_reference.py（Dataverse Web API）を標準とする。

add data-source に --environment-id は渡せない: --help には載っているが実際には error: unknown option '--environment-id' で拒否される。対象環境は power.config.json から読まれる。 同じく pa app push も -e / --environment-id を拒否する。

PoC やソリューション不要の場合のみ、--connection-ref {CR} --solution-id {SOLUTION_ID} を --connection-id {DATAVERSE_CONNECTION_ID}（npx pa connection list で取得）に置き換えてもよい。 ただしそのデータソースはソリューションに入らず、環境間移送できない。

Lookup 列の書き込みは従来どおり parentcustomerid_account@odata.bind のような @odata.bind 形式を使う。organization を省略した通常メソッドは Invalid organization URL 'null' provided で失敗しやすいため、*WithOrganization 系メソッドを使う。

旧方式の扱い: pac code add-data-source -a dataverse -t {table} によるテーブル別の強い型付け生成は、既存プロジェクト互換やテーブル単位の Service が必須な場合のみに限定する。日本語 DisplayName 対策など旧方式の補足は 日本語サニタイズリファレンス を参照。

4. 改善デプロイ

CSP（Content Security Policy）違反の回避

Power Apps ランタイムはデフォルトで connect-src 'none'。外部 API への fetch はブロックされる。 Code Apps が生成する Dataverse SDK / MicrosoftDataverseService のような Power Apps ランタイム経由の API のみ CSP 安全。

iframe 埋め込み（地図・PDF ビューア等）を入れる場合は、デプロイする前に CSP を確認・追加する。

# 不足があれば終了コード 1（デプロイ前チェック）
python .github/skills/code-apps/scripts/configure_code_app_csp.py `
  --directive Frame-Src --source https://www.google.com --assert

npm run predeploy のチェック 13（scripts/detect-csp-hazards.mjs）は、既定 CSP でエラーを出さずに動かないだけになる書き方 （fetch / XMLHttpRequest / WebSocket / three.js などのローダー / Worker / Draco・KTX2 / blob: 画像）をデプロイ前に止める。 CSP を追加した環境では .env に CODE_APP_CSP_ALLOW=connect-src のように書いて外す。

→ 詳細: CSP 構成

マイク・録音・音声ストリーミング

マイクは使えるが、AudioContext はクリック ハンドラ内（await より前）で開始する。1 本の MediaStream を録音と PCM 変換で共有し、 PCM 変換は public/ に置いた同一オリジンの AudioWorklet で行う。音声系 SDK にはマイクを直接渡さず Push ストリームで PCM を渡し、 data: Worker を使う SDK 機能は無効にする（Azure AI Speech は WebWorkerLoadType=off。放置すると文字起こしが無言で止まる）。 録音の再生は data: URL、WebSocket は connect-src に wss:// を追加する。 ホストの条件はローカルで再現して試験できる（別オリジン iframe + 既定 CSP + 疑似マイク）。

→ 詳細: デバイス・メディア / ホスト再現テスト

ログインユーザーの systemuserid 取得

SDK 1.5+ の getContext().user.systemUserId を優先する。古い host で省略された場合だけ user.objectId（Entra AAD Object ID）を取得し、systemuser テーブルの azureactivedirectoryobjectid でマッピングして systemuserid を解決する。 Xrm・fetch・executeAsync は CSP でブロックされるため使用不可。

→ 詳細: ユーザー識別リファレンス

ディープリンク: 外部から Code Apps の特定ページに遷移

SDK の getContext().app.queryParams で親ウィンドウの URL パラメータを取得する（cross-origin iframe のため window.location.search は不可）。

→ 詳細: ディープリンクリファレンス

基本設計方針: モーダル操作 + z-index ルール

新規作成・編集・削除はすべてモーダル（Dialog / AlertDialog）で操作する。 サイドバー z-40 / Dialog z-[300]/z-[400] で重なり問題を回避。

SDK 生成サービスとデータソースパターン

フロー連携時は統合 dataSourcesInfo が必須（Dataverse connector・フロー・Copilot Studio を同居させる場合、最初に解決されるデータソース定義へ必要なエントリをそろえておく）。

→ 詳細: データソースパターン

環境接続前のモックデータ開発

取得系画面は createMockDataExecutor でローカル確認できる。モックは import.meta.env.DEV と VITE_USE_MOCK=1 の両方で制限し、動的 import して本番成果物から除去する。 SDK 1.2.7 の標準 executor は作成・更新・削除をサポートしないため、書き込み成功のテストには使わない。

→ 詳細: モックデータ開発パターン

Lookup 名はクライアントサイド名前解決が必須

SDK 生成サービスは Lookup 名フィールド（createdbyname 等）を返さない。 _xxx_value（GUID）+ useMemo マップで名前解決する。 データソース未登録テーブルの場合は OData FormattedValue アノテーションを使う。 所有者（「誰のレコードか」）の表示は _owninguser_value + systemusers Map で解決する（取得 hook の $select に _owninguser_value を含めること）。

→ 詳細: Lookup 名前解決リファレンス

一覧の検索・フィルター・重要列（所有者・金額）

営業系の一覧は名称検索だけで終わらせず、所有者列・金額列などの重要項目を表示し、ステータス／所有者で絞り込み・横断検索できる構成を標準とする。所有者フィルターは実データに存在する所有者のみを列挙し、絞り込み結果の件数・合計をツールバーに表示する。

→ 詳細: CRUD UI 標準パターン の「一覧の検索・フィルター・重要列」

ステージ矢羽（Stage Path）— OptionSet の進捗を可視化＆クリックで変更

商談ステージ・リードステータス等、順序を持つ OptionSet を Salesforce 風の矢羽（シェブロン）で表示する。onSelect でその場ステージ変更（patch）も可能。失注・不認定など否定的終端は negativeValue で赤表示。

→ 詳細: ステージ矢羽パターン

使い方ガイド（オンボーディング）— 全アプリ標準

画面が 3 つ以上あるアプリには、指示がなくても使い方ガイドを実装する。 初回起動時にカルーセル（4〜6 枚）を自動表示し、「使い方を見る」で実際の画面を操作しながら案内するツアーへ繋ぐ。2 回目以降はサイドバー／ヘッダーのボタンから任意に開く。

• 定義は src/guide-config.ts の GUIDE_SLIDES / TOUR_STEPS に集約し、画面側は data-tour="..." を足すだけにする
• Context とフックは guide-context.ts（.ts）に分離する。guide-provider.tsx に混ぜると react-refresh/only-export-components で lint が落ちる
• autoClick に削除・送信など破壊的操作を指定しない

→ 詳細: 使い方ガイドパターン

scaffold できるテンプレート

templates/*/scaffold.json を持つ全テンプレートは、update-skills の共通スキャフォールダーで取得する。 まず --dry-run でコピー対象と Next を確認し、問題なければ外して実行する。

python .github/skills/update-skills/scripts/scaffold_from_template.py `
  --template .github/skills/code-apps/templates/<template-name> `
  --target <出力先> --dry-run

テンプレート	種別	開始方法
templates/generic-base	完全なベース	新規プロジェクトの出力先へ生成する
templates/sales-crm	完全な業務テンプレート（generic-base を extends）	営業支援 CRM（マネージャー ダッシュボード・営業ホーム・CRUD・Outlook/Teams/Cowork 連携）を空のディレクトリから生成する
templates/construction-cockpit	完全な業務テンプレート（generic-base を extends・Copilot Studio エージェント同梱）	建設現場コックピット: Google Maps の工事ポートフォリオ、Three.js の進捗 3D（工事種別 6 種・完成形の点線・CAD の GLB/OBJ/STL/FBX 取り込みと施工単位の対応付け・施工位置イメージ）、React Flow ガント/因果関係、工事・ユーザーの Dataverse 検索ドロップダウン、監督の承認待ち（日報・現場写真・進捗の下書き）、KY・ヒヤリハット・日報・ナレッジのグラフ付き一覧と詳細、KY の AI 危険予測（Dataverse 要求/結果 + Workflow）、Copilot Studio「現場コックピット アシスタント」（Teams での日報と写真の報告・施工単位での進捗報告・まとめ登録・承認）、Cowork、本格デモデータを生成する
templates/perse3d-studio	完全な業務テンプレート（generic-base を extends・Blender パイプライン・カスタム コネクタ同梱）	パース3D内見スタジオ: 間取り図・パース・物件 URL から 3D 建物を生成し、内見（ドールハウス・歩行・階段）・家具配置・提案プラン・Blender 出力まで行う。データソース追加前でもビルドでき（生成サービスは遅延読み込み）、npm run deploy の predeploy がデータソースの実在を確かめる
templates/agm-qa-assist	完全な業務テンプレート（generic-base を extends・Azure Functions 同梱）	株主総会 Q&A アシスト（連続の文字起こし・株主の AI 照合・想定問答の検索と根拠つき回答案・録音と記録・総会の集計・LIVE 共有）。変数は --questions の順に AskUserQuestion で聞いてから生成する
templates/store-ordering	完全な業務テンプレート（generic-base を extends・Dataverse 8 テーブルと合成デモデータの生成器を同梱）	店舗発注システム: 小売店の発注端末を模した業務端末風 UI（F1〜F10 キー・単品発注 → 確認 → 送信・発注照会と取消・在庫照会・天気と催事）。単位（個・本・パック）つきの合成データ（50 品目 × 90 日・シナリオ切り替え）を Dataverse に作る。Cowork の店長アシスト（cowork スキルの templates/store-assist-plugin）と同じテーブル。データソース追加前でもビルドできる遅延版クライアント。変数は --questions の順に AskUserQuestion で聞いてから生成する
templates/account-link-admin	アドオン	空の作業ディレクトリへ生成し、README に従ってホストへ統合する
templates/drawing-communication	アドオン	空の作業ディレクトリへ生成・単体検証後、必要なモジュールをホストへ統合する
templates/modular-plant	アドオン	空の作業ディレクトリへ生成・単体検証後、必要なモジュールをホストへ統合する

アドオンをホストのルートへ --force で直接重ねると README.md や package.json を上書きし得るため、 必ず独立した出力先へ生成してから統合する。

samples/geek-* は業務ページ実装の参照専用で、scaffold 元にはしない （業務固有のページ・型・サービス、および samples/geek-sales の CommandPalette / QuickActivityFab のような テーマ固有コンポーネントが混入するため）。営業支援を始める場合は templates/sales-crm を使う。

業務テンプレートはデータソース追加前にビルドできること: 初回 push（Step 5）は add data-source（Step 6）より前に build するため、生成サービスを静的 import すると空のディレクトリからの初回デプロイが型エラーで止まる。 templates/sales-crm/src/lib/dataverse-client.ts のように import.meta.glob("../generated/services/MicrosoftDataverseService.ts") で遅延解決し、未追加時は画面に追加手順を出す。

npx pa は --no を付ける: ローカルに pa（@microsoft/power-apps-cli v1 以降の bin）が無い状態で npx pa を実行すると、 npm 上の無関係なパッケージ pa を取得して実行する（依存未導入・旧 CLI 0.x のままで起きる）。手動実行は npx --no pa ...、 npm scripts では pa app push を直接呼ぶ。npm run predeploy のチェック 12 がこの状態を検出する。

外部 API 呼び出しを含むデモページ（design-examples.tsx / use-learn-catalog.ts / learn-client.ts 等）は CSP 違反になるため、業務テーマに不要なものは最初から生成しない。標準コンポーネント（form-modal.tsx / list-table.tsx / inline-edit-table.tsx / sidebar*.tsx / ui/ 等）は残す。

→ 含める／含めないファイルの完全な一覧は 新規テーマ開始チェックリスト。

アドオンテンプレート（generic-base に重ねる差分）

templates/ には完全な generic-base に加えて、特定業務の画面だけを差分ファイルとして重ねるアドオンを置く。 アドオンは独立した作業ディレクトリへ scaffold し、README の手順どおり必要なファイル、依存、ルート、ナビを統合する。

アドオン	用途	使う場面
templates/account-link-admin	contact に account（取引先企業）を割り当てる管理画面	Power Pages で Account アクセスを選んだとき（power-pages スキル Step 4-G）。必須
templates/drawing-communication	図面の注釈・改訂・非同期会話	図面レビュー機能を既存 Code Apps に追加するとき
templates/modular-plant	JSON 駆動の設備配置・接続・候補生成	プラント概念設計を既存 Code Apps に追加するとき

SDK に触れる面を 1 ファイルに閉じる

@microsoft/power-apps は 2〜4 週ごとに更新され、マイナーバージョンでも破壊的変更が入る。 影響範囲を押さえるため、SDK を import してよいのは src/lib / src/services / src/providers の 3 階層だけとし、 ページ・コンポーネントからは直接呼ばない（validate_sample.py が検出する）。

SDK 1.4+ では elastic table の update／delete／file 操作と IOperationOptions に optional partitionId が追加された。standard table では省略し、elastic table では対象レコードと同じ partition ID を service 層から渡す。SDK 1.5+ のユーザー識別は下記の systemUserId 優先パターンを使う。

Dataverse CRUD ラッパーは templates/dataverse-client.ts を正とし、手書きせずコピーして使う。 検索ボックス・ドロップダウンは同ファイルの Search（Dataverse 検索）を使う（Dataverse 検索のドロップダウン）。

cp .github/skills/code-apps/templates/dataverse-client.ts src/lib/

SDK の破壊的変更への追従は、この 1 ファイルを直して python scripts/sync_dataverse_client.py で配布する。

[!NOTE] templates/generic-base にはこのファイルを同梱していない。 @/generated/services/MicrosoftDataverseService に依存しており、add-data-source 前の状態では tsc -b が通らないため。 Step 6 で接続を追加した後にコピーする。

samples/geek-asset / geek-hr / geek-expense / geek-sales / geek-fieldservice は、このラッパーではなく getClient() の *Async 系・テーブル別生成サービスを使う別パターンの参照実装。上記 3 階層の制約は同じく適用される。

3D モデル（GLB）を読む面も 1 ファイルに閉じる

GLB を読むときは templates/csp-safe-gltf.ts をコピーして createCspSafeGltfLoader() を使う（new GLTFLoader() を直接使わない）。 既定 CSP は blob: を img-src / connect-src で拒否するため、素の GLTFLoader では埋め込みテクスチャが黙って落ちる（troubleshooting #73）。 同じファイルを使う実装: samples/plant-design-maintenance/src/lib/csp-safe-gltf.ts。

cp .github/skills/code-apps/templates/csp-safe-gltf.ts src/lib/

構築手順の詳細

詳細な構築手順（初期化・Dataverse 接続・ビルド・デプロイ）は 構築リファレンス を参照。

TanStack React Query パターン

自前 MicrosoftDataverseService ラッパーを React Query で包むパターン（useRecords / useCreateRecord 等）は 構築リファレンス を参照。

プレデプロイレビュー（「デプロイして」「プッシュして」時の必須チェック）

「デプロイして」「プッシュして」が指示されたとき、ビルド前に必ずレビューを実行する。 dataSourcesInfo 整合性・インポート元・ルーター種別（createHashRouter 必須）・サイドバー fixed レイアウト等を確認。

→ 詳細: プレデプロイレビューリファレンス

ビルド・デプロイの注意事項

• noUnusedLocals: true のため未使用 import は即削除
• PowerShell で npm run build 2>&1 の後にテキストを付けない（Vite が入力パスと誤解）

→ 詳細: ビルドリファレンス

Power Automate フロー統合

フロー追加は npx pa app add flow --flow-id {id} を使う（add data-source --connector logicflows は旧方式）。 Copilot Studio 応答は JSON 配列文字列で返るため JSON.parse() → 配列の最初の要素を取得する。 502 タイムアウト対策としてローカル検索へのフォールバックを必ず実装する。

→ 詳細: フロー連携リファレンス

---

5. リファレンス

正常系の流れは本ファイル（§1〜§4）に集約し、異常系・詳細手順・トラブルシューティングは references/ に逃がしている。各トピックの詳細は以下を参照。

リファレンス	内容
デザインテンプレート集	設計時に選択する配色テンプレート 6 種（プレビュー HTML・CSS Variables 一式・light/dark 対応）
デザインシステム	Tailwind CSS v4 のコンポーネント選定・画面設計パターン
コンポーネントカタログ	全コンポーネントの詳細仕様・使用例
ステージ矢羽パターン	OptionSet（ステージ／ステータス）を Salesforce 風の矢羽で可視化・クリックで変更
使い方ガイドパターン	初回起動のカルーセル＋実操作ツアー（data-tour 属性・localStorage 初回判定・スポットライト・全アプリ標準）
月間カレンダーパターン	日付を持つレコードを月間グリッドで俯瞰（date-fns のみ・依存追加なし・イベントチップ・今日ハイライト）
ウィザードフォームパターン	入力項目の多いフォームを複数ステップに分割（ステップインジケーター・ステップ別バリデーション・確認画面）
CSV エクスポートパターン	フィルター適用後の一覧を UTF-8 BOM 付き CSV でダウンロード（Excel 日本語対応・OptionSet ラベル変換）
パレート図パターン	不良分析・ABC 分析などの分類別集計を降順棒 + 累積構成比折れ線 + 80% 基準線で可視化（重点対策対象の強調色）
チェックリスト採点パターン	点検・監査系業務の判定トグル・スコア自動計算（対象外を分母から除外）・テンプレート一括生成・親レコードへのスコア同期
クロス集計マトリクスパターン	2 軸の組み合わせ件数をヒート色付きピボット表で俯瞰（行列自動生成・合計行/列・追加依存なし）
縦タイムライン/ステッパーパターン	順序を持つ項目の進行状態を縦に可視化（done/current/problem/pending・行ごとに操作ボタン差込可・追加依存なし）
一覧ペイン（マスター詳細）パターン	詳細画面の左にレコード一覧を常駐させて遷移しないで切り替え（Dataverse 側検索・デバウンス・見切れ防止の落とし穴表）
AI 評価ルールのマスタ化パターン	LLM の判定基準をテーブルに出してアプリから編集・ジョブ行キューで過去データを再評価・根拠ハイライトと改善提案（OData キーの URL エンコード落とし穴）
構築リファレンス	ビルド・デプロイの詳細手順・vite.config.ts 必須設定・TypeScript エラー対処
npm CLI リファレンス	SDK 1.3.1 / CLI 1.0.1 検証済み・最新版への更新方針・push -s の GUID 要件・share の最小権限運用・create-connection / refresh-data-source / auth-switch
ソリューション ALM	接続参照バインド・almMode と初回 push・コンポーネント種別・共有時の権限モデル
データソースパターン	生成サービス・dataSourcesInfo・TanStack React Query（旧/native パターン含む）・外部システムの資産を Dataverse にミラーして読む
モックデータ開発パターン	開発限定の createMockDataExecutor 導入・本番バンドル混入防止・SDK 1.2.7 の取得専用制約
Lookup 名前解決	クライアントサイド名前解決・OData FormattedValue パターン・所有者（Owner）列の表示
日本語サニタイズ	旧ネイティブ add-data-source 方式の日本語 DisplayName 回避
CSP 構成	iframe 埋め込み・外部 API・WebSocket 接続・録音の再生時の CSP 設定・CSP 安全な SDK メソッド一覧
3D 資産の共通利用	3D モデル・素材ライブラリを複数アプリ / Blender と共通利用する際の CSP・色合わせ・ライセンス・検証（契約検証とヘッドレス描画）
Dataverse 検索のドロップダウン	工事・ユーザーなどの候補検索。関連性検索（GetRelevantRows）と部分一致の統合、簡易検索ビューを API で変えない理由、アクセシブルなコンボボックス
3D 施工進捗モデル	完成形を破線、施工中をクリッピングで立ち上げる進捗表示・部位と工程の対応・BIM/CIM の glTF・GLB の書き出し
デバイス・メディア	マイク・AudioContext・録音・PCM 変換の正常系、SDK にマイクを直接渡さない理由、CPU 負荷、前提欠落時の開始抑止、Console へのログ集約
ホスト再現テスト	別オリジン iframe + Code Apps 既定 CSP + 疑似マイクをローカルで再現し、ヘッドレス Edge の Console ログで判定する
テレメトリ / 可観測性パターン	initializeLogger / Metric 判別共用体・sessionLoadSummary SLI・PII サニタイズ規約・Application Insights 連携時の CSP
ユーザー識別	ログインユーザーの systemuserid 取得パターン（CSP 安全）
LIVE 共有パターン	1 人が操作し、特定の人に読み取り専用で同じ画面を見せる（Dataverse レコード 1 件の状態 + GrantAccess・1.2 秒配信 / 1.5 秒取得）
根拠と生成文の行を線で結ぶ	React Flow で検索結果（根拠）と生成文の各行を引用の関係で結ぶ（行ごとの接続点・左右配置・ホバー強調・E2E での着地確認）
ディープリンク	MDA / Power Automate から特定ページへパラメータ付き遷移
フロー連携	Power Automate フロー呼び出し・Copilot Studio 応答パース・エラーハンドリング
Copilot Studio コネクタ	Copilot Studio エージェント直接呼び出し・会話継続・レスポンス解析
Copilot Studio v2 iframe	v2 Web app チャネルを Code Apps に表示する標準パターン。URL、CSP、認証・受入境界
コネクタリファレンス	Code Apps で利用する主要コネクタの追加方法・使用例
メール・PDF 送信	HTML→PDF 変換・Power Automate 経由メール添付送信パターン
地図埋め込みパターン	Google Maps iframe 埋め込み（Code Apps は frame-src 追加が必須）
高度な実装パターン	マルチ環境・オフライン・i18n・パフォーマンス最適化パターン
プレデプロイレビュー	「デプロイして」「プッシュして」時の自動チェック手順
新規テーマ開始チェックリスト	前テーマの残骸がないクリーン開始の確認手順・scaffold 時に含めないファイル
トラブルシューティング	頻出エラーと対処法（GUID フィルタ・.toLowerCase() 統一・テンプレート削除時の use-theme 巻き添え 等）
サンプル作成ガイド	公開リポジトリ向けサンプルのセキュリティ要件・環境変数ルール・feature flag 命名規則

スクリプト

スクリプト	用途
check_code_apps_environment.py	Code Apps 許可の必須条件を確認し、マネージド環境の状態を参考表示（pa app init の前に実行）
configure_code_app_csp.py	Code Apps の CSP（frame-src 等）を確認・追加・検証。iframe を使うアプリはデプロイ前に --assert を通す
setup_connection_reference.py	接続参照をソリューションに用意する（既存流用ファースト→Web API で新規作成）。Step 1 で実行
add_data_source.py	データソースを非対話で追加する。コネクタの通称（sharepoint 等）を shared_xxx に解決し、接続・必須値を確定してから --non-interactive で CLI を起動する。Step 3 の標準
pre-deploy-check.mjs	.env / power.config.json / モック実行基盤の本番混入を検証（npm run predeploy）。プロジェクト直下の scripts/ にコピーして使う
detect-csp-hazards.mjs	既定 CSP で無言で失敗する書き方を検出（predeploy チェック 13 が呼ぶ。pre-deploy-check.mjs と同じ場所にコピーする）
templates/csp-safe-gltf.ts	既定 CSP の中で GLB を読む GLTFLoader（埋め込みテクスチャを createImageBitmap でデコード・外部参照は明示エラー・同梱 GLB の base64 デコード）
validate_3d_assets.py	素材ライブラリ manifest・テクスチャ・GLB の契約（サイズ・色の偏り・光沢フラグ・ライセンス・名前空間）を検証
capture_3d.mjs	ヘッドレス Edge（DevTools プロトコル、Playwright 不要）で 3D 画面を撮り、描画状態を window.__viewer などから取得する。--ready で描画完了を待ち、--fail-on-error でページのエラーを失敗にする
inspect_table_metadata.py	既存テーブルの EntitySetName / 主キー / 列 / 参照先 / 選択肢を調査（既存テーブル接続時は実装前に必須）
validate_cli_reference.py	テンプレート採用版の pa app share --help と CLI リファレンスの主要オプション・実行例が一致することを検証
validate_sample.py	samples/ 配下の完全性と generic-base のテレメトリ契約を検証（必須ファイル・import 先の実在・秘匿情報・SDK の使い方）
sync_dataverse_client.py	templates/dataverse-client.ts を samples/ 配下の全コピーへ反映（SDK の破壊的変更への追従はこの 1 ファイルを直して配布）
scaffold_from_cache.ps1	キャッシュからのテンプレート scaffold
toggle_table_lang.py	旧方式の pac code add-data-source 向けにテーブル表示名を一時的に英語化
serve_host_emulation.mjs	Power Apps ホスト（別オリジン iframe + allow 属性 + 既定 CSP）をローカルで再現してビルド成果物を配信する
run_headless_media_test.ps1	ヘッドレス Edge に疑似マイク（WAV）を流し、Console ログを抽出する。終了時に残存プロセスを 0 にする
capture_host_screens.ps1	ヘッドレス Edge の仮想時間でタイマー駆動のデモを早送りし、途中・最後の画面を撮る（統合ブラウザが使えない環境の画面確認）
capture_host_screens_realtime.mjs	実時間で待って撮る（DevTools プロトコル）。生成 API のストリームなど、仮想時間で進まない画面用

環境変数

スクリプトが参照するキーは references/.env.example を参照（実値はリポジトリルートの .env に置く）。