build-actions-generator

ODC ビルドアクションジェネレーター

MABS 12+ を介して Android および iOS を対象とする ODC モバイルライブラリ（Capacitor および Cordova プラグイン）と ODC アプリ用の buildAction.json を生成します。

使用する場合

✅ このスキルを使用する場合:

• ODC モバイルライブラリ（Capacitor または Cordova プラグイン）用の buildAction.json ファイルを生成するとき。
• ネイティブビルド構成を必要とする ODC アプリ用の buildAction.json ファイルを生成するとき。
• ODC（Capacitor ベース）デプロイ用に適応させている Cordova プラグインのビルドアクションを生成するとき。
• Android 用の AndroidManifest.xml、Gradle ファイル、または XML リソースを構成するとき。
• iOS 用の Info.plist、エンタイトルメント、または表示名を構成するとき。
• 入力変数（文字列、数値、ブール値）と条件付きロジックを定義するとき。
• プラグインのネイティブ要件から両プラットフォーム用のビルドアクションをスキャフォールディングするとき。
• プラグインパスの引数を指定して、または Capacitor もしくは Cordova プラグインディレクトリ内から呼び出されたとき。

❌ このスキルを使用しない場合:

• ODC Studio/Portal で JSON をアップロードまたは参照する場合（ステップ 2〜3 — 手動のガイダンスを参照してください）。
• Cordova 拡張性構成または O11 拡張性 JSON。
• Cordova アプリのビルド、O11 ビルド、または MABS 12 より前のバージョン — ビルドアクションは ODC（MABS 12+）の Capacitor アプリにのみ適用されます。
• ビルドアクション JSON の外部にあるアプリレベルのビルド構成。
• プラグインの公開またはテスト（ステップ 4 — 開発者の責任）。

---

エンドツーエンドのプロセス

このスキルはステップ 1 のみを処理します。ステップ 2〜4 は手動での操作が必要です。

ステップ	担当	内容
1. JSON の生成	このスキル	必要なすべてのプラットフォームアクションを含む buildAction.json を作成します
2. JSON のアップロード	開発者	ODC Studio → リソースでファイルをプラグイン/ライブラリに追加し、その後拡張性タブで参照して、変数があれば拡張性設定を作成します。
3. Portal でのリンク	開発者	ビルドアクションにパラメーターがある場合は、ODC Portal → モバイル配布タブ → 拡張性設定で値を指定します
4. 公開とテスト	開発者	MABS 12（Capacitor）以降を使用してモバイルビルドをテストします

---

JSON ファイル構造

出力場所: 2 つのファイルがプラグインルートの build-actions/ フォルダーに 書き込まれます:

• build-actions/buildAction.json — ビルドアクション構成
• build-actions/README.md — 人間が読めるドキュメント（生成ガイドラインのステップ 5 を参照）

常に、指定されたディレクトリの最上位（またはパス引数が指定されていない場合は 現在の作業ディレクトリ）に build-actions/ を作成してください。 plugin/、 android/、ios/ などのサブディレクトリ内には決して作成しないでください。 それらのサブディレクトリにあるソースファイルをスキャンする場合でも同様です。 プラグインリポジトリがネストされた構造（例: plugin/android/、plugin/ios/）を 持っている場合でも、出力はリポジトリルートに置きます: build-actions/buildAction.json。

{
  "variables": { },       // optional — input parameters for the build action
  "platforms": {
    "android": { },       // optional — Android-specific actions
    "ios": { }            // optional — iOS-specific actions
  }
}

ファイル命名: スペースなしの camelCase を使用してください。

✅ buildAction.json、pushNotifications.json、cameraPlugin.json ❌ build action.json、Build_Action.json

platforms の下に android または ios の少なくとも一方が存在する必要があります。

---

変数と条件

ビルドアクションで変数や条件を使用する場合は、完全な構文と例について references/variables-and-conditions.md を参照してください。

• 変数（"variables" キー） — プラグイン開発者が宣言する型付き入力（string、number、boolean）です。利用側アプリは拡張機能構成の parameters ブロックを介して値を提供します。値が本当に必須でない限り、常に default を含めてください。含めない場合、未設定のままだとビルドが失敗します。
• プラットフォーム固有のバリアント — 同じ論理値（例: アプリ ID、API キー）が Android と iOS の両方で使用されるものの、通常はプラットフォームごとに異なる場合は、_ANDROID と _IOS のサフィックスを付けた 別々の変数 として公開してください（例: ADMOB_APP_ID_ANDROID、ADMOB_APP_ID_IOS）。これらを単一の共有変数に統合しないでください。開発者は各プラットフォームを個別に構成できる必要があります。
• 条件 — 任意のアクションエントリに condition フィールドを追加すると、条件付きでスキップできます（displayName、productName、appName を除く）。構文と演算子については、リファレンスファイルを参照してください。

変数が定義されている場合は、拡張機能構成の parameters が buildAction.json で宣言された変数にどのように値を提供するかについて、references/extensibility-configuration.md を参照してください。ライブラリとその利用側アプリの両方でビルドアクションが定義されている場合、ライブラリのものが先に実行されます。

---

Android アクション

Android を対象とする場合は、完全なアクションスキーマと例について references/android-build-actions.md を参照してください。

利用可能なアクション:

• appName — Android アプリ名を設定します（文字列、条件はサポートされません）
• manifest — AndroidManifest.xml を変更します（属性の設定、XML のマージまたは注入）
• gradle — Gradle ビルドファイルにパッチを適用します（ターゲット DSL パスへの挿入または置換）
• res — res/ フォルダーの下にリソースファイルを作成します
• json — JSON ファイルを変更します（set または merge）
• xml — 任意の XML リソースファイルを変更します
• copy — ファイル、ディレクトリ、または URL をプロジェクトにコピーします
• code — ネイティブ Android（Java/Kotlin）ソースファイルを追加またはパッチ適用します（source+targetDir、file+target+replace、または file+patchFile）
• tar — プロジェクトファイルに対して tar 操作を適用します

---

iOS アクション

iOS を対象とする場合は、完全なアクションスキーマと例について references/ios-build-actions.md を参照してください。

利用可能なアクション:

• displayName — ホーム画面に表示されるアプリの表示名を設定します（条件はサポートされません）
• productName — App Store に表示される製品名を設定します（条件はサポートされません）
• buildSettings — Xcode ビルド設定をキーと値のペアとして設定します
• buildPhases — カスタムシェルスクリプトのビルドフェーズを追加または置換します
• plist — Info.plist またはその他の plist ファイルを変更します（エントリの置換またはマージ）
• xcprivacy — PrivacyInfo.xcprivacy を更新します
• entitlements — entitlement を追加または変更します（オブジェクトであり、配列ではありません）
• frameworks — Xcode プロジェクトにシステムまたはカスタムのフレームワークを追加します
• json — JSON ファイルを変更します（set または merge）
• xml — 任意の XML ファイルを変更します
• copy — ファイル、ディレクトリ、または URL をプロジェクトにコピーします
• strings — .strings ローカリゼーションファイルを更新します
• xcconfig — .xcconfig ビルド構成ファイルを更新します
• code — ネイティブ iOS（Swift/Objective-C）ソースファイルを追加またはパッチ適用します（source+compilerFlags、file+target+replace、または file+patchFile）
• tar — プロジェクトファイルに対して tar 操作を適用します

---

生成ガイドライン

1. プラグインの入力シグナルを読み取る

プラグインルートは、引数が指定されていればそのパス、そうでなければカレントディレクトリです。開発者に質問をする前に、プラグイン内に既存のシグナルがないか確認してください。

• プラグインルートに input-contract.yaml が存在する場合は、完全な capacitor-plugin-generator/references/input-contract.md スキーマに照らして読み取り、 以下の関連セクションを抽出します。
  • migration.hooks（tier_1 / tier_2 / tier_3）— ビルドアクション導出のための フック分類。
  • dependencies.android.gradle および dependencies.ios.{cocoapods,spm,system_frameworks} — 依存関係に基づく アクション（Gradle パッチ、フレームワークエントリ）。
  • permissions.android および permissions.ios — パーミッションアクション （マニフェストの <uses-permission>、plist の使用目的の説明）。
  • plugin.name — README のタイトル用。
  • その他すべてのフィールド（api.methods、api.types、api.events など）は 無関係です — 黙って無視してください。
• コントラクトが存在する場合でも、常にプラグインソースを直接スキャンしてください。コントラクトは出発点にすぎません。ソースをスキャンすることで、コントラクトが捉えきれない、あるいは古くなっている可能性のあるシグナルを検出できます。
  • Cordova プラグイン: plugin.xml を解析してください — 要素からアクションへの完全なマッピングとフック分類ガイドについては、references/cordova-plugin-scanning.md をお読みください。
  • Capacitor プラグイン: プラグインのドキュメント、package.json、ネイティブソースファイル（Java/Kotlin および Swift/Objective-C）をスキャンしてください — 完全なスキャンガイドについては、references/capacitor-plugin-scanning.md をお読みください。
• cordova-plugin-migrator ODC フローの一部として（フェーズ 11a）呼び出された場合、 出力（build-actions/）は Cordova ソースツリーではなく、Capacitor プラグイン ディレクトリに書き込まれます。cordova-plugin-migrator は、作業ディレクトリ または引数として Capacitor プラグインのパスを提供します。

2. 要件を収集する

開発者に質問してください（またはコンテキストから推測してください）。

• プラグインに必要なネイティブ機能は何ですか？（カメラ、位置情報、プッシュ、Bluetooth など）
• 対象とするプラットフォームはどれですか。Android のみ、iOS のみ、それとも両方ですか？
• 開発者が制御すべき実行時構成値はありますか？（→ 変数）
• それらの値に依存して条件付きになるアクションはありますか？

3. 要件をアクションにマッピングする

ネイティブ要件	Android アクション	iOS アクション
実行時パーミッション	manifest で <uses-permission> を注入	plist の使用目的の説明キー
カスタム URL スキーム	manifest で intent-filter をマージ	plist の CFBundleURLTypes
カスタムアプリ属性	manifest の属性	—
ネイティブ依存関係	gradle を置換	—
プッシュ通知	manifest をマージ + gradle	entitlements の aps-environment
アプリグループ	—	entitlements の com.apple.security.application-groups
カスタム表示名	—	displayName
カスタムネイティブコード	code を注入/置換	code を注入/置換

フックまたは要素が上記のどのアクションにも明確にマッピングされない場合は、マッピングできないように見えても正しいビルドアクションの等価物が存在するパターンについて、references/common-scenarios.md をお読みください。

4. JSON を生成する

• ファイル名: camelCase、スペースなし（例: buildAction.json）
• 実際にアクションがあるプラットフォームのみを含める
• 開発者が制御する値には $VAR_NAME 置換を使用する
• 値が本当に必須でない限り、変数には default を含める — これがないと、プラグインライブラリも利用側アプリも拡張性構成の parameters で変数値を指定しない場合にビルドが失敗します
• condition は、アクションを条件付きでスキップすべき場合にのみ追加する
• manifest では重複エントリを避けるため、inject より merge を優先する
• 有効で整形された JSON を出力する
• code アクションにはプラットフォーム固有のファイルパスの慣例があります — iOS は Swift/Objective-C ファイル（例: App/AppDelegate.swift）を対象とし、Android は Java/Kotlin ファイル（例: app/src/main/java/com/example/App.java）を対象とします。 プラットフォーム間で慣例を混在させないでください。
• code より構成レベルのアクションを優先する — manifest、gradle、plist、 xml、entitlements は、ソースファイルに触れることなくほとんどのネイティブ要件を カバーします。構成レベルの代替手段が存在しない場合にのみ code アクションを生成して ください。生成する場合は、file+target+replace を使用してください。patchFile は 決して使用しないでください — ODC ビルドでは信頼性が低いです。変更を単純な文字列置換 として表現できない場合は、そのアプローチは ODC では信頼性が低いことをユーザーに簡潔に 伝え、代替として Capacitor フックを提案してください（このスキルの範囲外です）。 ODC の内部仕様は説明しないでください。
• ソースファイルが実行時にユーザー提供される場合は tar と copy を避ける — これらのアクションは、プラグインバンドル内のハードコードされたパスまたは外部 URL でのみ 信頼性があります。ユースケースでユーザー提供のファイルが必要な場合は、代わりに Capacitor フックを検討するようユーザーに簡潔に伝えてください。ODC の内部仕様は 説明しないでください。

JSON ファイルを書き終えたら、先に進む前にその構文を検証してください:

1. ユーザーに伝えます: 「JSON 構文を検証しています...」
2. python3 -m json.tool build-actions/buildAction.json > /dev/null を試します — python3 が利用可能な場合はこれを使用します。
3. python3 が利用できない場合は、jq empty build-actions/buildAction.json を試します。
4. どちらのツールも利用できない場合は、ファイルを注意深く自己検査します: 波括弧と 角括弧の対応、末尾のカンマがないこと、文字列値内のエスケープが正しいこと （特に manifest/plist エントリ内の XML コンテンツでは、引用符を \" として エスケープする必要があることに注意してください）を確認します。
5. エラーが見つかった場合（ツールまたは自己検査による）、ファイルを修正し、JSON が 有効になるまで手順 2 から繰り返します。
6. 検証に合格した後にのみ、生成ガイドライン 5（README）に進みます。

5. README を生成して締めくくる

JSON と並べて build-actions/README.md を生成します。これはプラグインのソース管理用ドキュメントとして、また ODC をセットアップする開発者にとっての主要なリファレンスとして機能します。必要な構造については references/readme-template.md を読み、その後、以下の作成ルールに従ってください。

README 作成ルール:

• そのプラットフォームにアクションがない場合は、### Android または ### iOS セクションを省略します。
• すべての入力シグナルがビルドアクションにマッピングされた場合は、## What requires additional setup を完全に省略します。マッピングできなかったフックや要素が見つかった場合にのみ含めます。
• 変数がない場合は、## Variables セクションを完全に省略します。
• プラグインに変数がない場合（その場合 parameters キーが存在せず、手順に文脈がありません）は、拡張性設定の手順（## ODC Setup のステップ 2 の JSON ブロックの下の段落）を省略します。
• ## Variables テーブルでは、デフォルトがない場合は Required を yes に、デフォルトが存在する場合は no に設定します。Required が yes の場合は Default を — のままにします。
• ## ODC Setup の拡張性 JSON は、プレースホルダーの VAR_NAME ではなく、生成された JSON の実際の変数名を反映する必要があります。
• ## What requires additional setup では、Recommended approach を次のように設定します:
  • スクリプトタイプのフックには Capacitor hook — フックが何をしなければならないかを具体的に記述します
  • ユーザーが提供するファイルには ODC resource — 開発者に、ODC Studio でそのファイルを ODC リソースとして追加するよう伝えます（Deploy Action: Deploy to Target Directory）
  • ブロッカーには Not supported in ODC — ODC 開発者はネイティブプロジェクトにアクセスできないため、手動のフォールバックはありません。作り直しが必要になる理由を簡潔に述べます
• 拡張性設定のパーミッションの代替案: pluginConfigurations.permissions を README に記載するのは、(a) 開発者が拡張性設定について明示的に質問した場合、または (b) 生成されたすべてのビルドアクションが排他的に manifest の <uses-permission> エントリおよび/または plist の iOS 使用目的の説明エントリである場合 — つまり buildAction.json 全体をライブラリの拡張性設定の permissions ブロックで置き換えられる場合のみです。それ以外のすべてのケースでは省略します。リファレンスは references/extensibility-configuration.md にあります。

両方のファイルを生成した後のターミナル出力:

• buildAction.json の内容を出力しないでください — ファイル書き込みで既に表示されています。
• ターミナルに分析テーブル、スキャンの判断、要素ごとの推論を表示しないでください。内部の推論は内部にとどめます。きれいにマッピングされなかった注目すべき判断は、ターミナルではなく README に記載します。
• 短いメモを 1 つ出力します: 「ビルドアクションを build-actions/ に書き込みました。これは候補です — 使用前に build-actions/buildAction.json を確認し、その後 MABS 12+ のビルドと実際のモバイルアプリに対する機能テストで検証してください。この設定が何を行うかの概要と ODC セットアップ手順については build-actions/README.md を参照してください。」
• ## What requires additional setup を README に書き込んだ場合は、さらに 1 行追加します: 「一部のフックまたは要素をビルドアクションにマッピングできませんでした — 詳細は build-actions/README.md を参照してください。」
• 開発者がターゲットプラットフォームとして ODC を明示的に言及しなかった場合は、ビルドアクションは ODC ビルドでのみ有効であり、スタンドアロンの Capacitor アプリでは有効でないことを述べる文を 1 つ追加します。
• ターミナルで ODC セットアップ手順を繰り返さないでください。