Templates

AppKit は、Databricks CLI の databricks apps init コマンドを基盤とするテンプレートシステムを使用します。Templates がプロジェクト構造を定義し、.tmpl ファイルは Go の text/template エンジンで処理されて、カスタマイズされた output を生成します。

.tmpl ファイルの仕組み

.tmpl で終わるファイルは、databricks apps init の実行時に CLI によって処理されます。

1. .tmpl の接尾辞が削除されます (例: .env.tmpl → .env)
2. Go テンプレート式が評価され、置換されます
3. レンダリング結果のファイルが出力ディレクトリに書き出されます

先頭が _ のファイル名は、先頭が . の名前にリネームされます (例: _gitignore → .gitignore) 。

テンプレート変数

条件付きコンテンツ

Go テンプレートの条件分岐を使うと、選択された プラグイン に応じてコードを含めたり除外したりできます。

{{- if .plugins.analytics}}
import { analytics } from '@databricks/appkit';
{{- end}}

appkit.plugins.json

プラグインマニフェストは、databricks apps init 実行時の CLI の挙動を制御します。

• プラグイン選択 UI — 対話型プロンプトに表示される選択可能なプラグイン
• リソースのプロンプト — 必須/任意のリソースについて、ユーザーに値の入力を求めます(例: SQL Warehouse ID)
• .dotEnv への書き込み — env プロパティを持つリソースフィールドが .env に書き込まれます
• app.yaml の生成 — リソースフィールドから env と valueFrom のエントリが生成されます
• databricks.yml の生成 — リソースフィールドからバンドル変数とアプリリソースのエントリが生成されます

同期済みのマニフェストは、各プラグインの manifest.json を基に appkit plugin sync --write で生成されます(記述時の規約については プラグインマニフェスト を参照してください)。ディスク上の形式には、CLI が機能をネゴシエートするために使用する version フィールドが含まれます。

• "1.0" / "1.1" — 旧形式。引き続き読み取り可能です。
• "2.0" — 現行の形式。scaffolding(version が "2.0" の場合は CLI が必須とします。公開されている JSON Schema ではなく、パース時にチェックされます)と、すべてのリソースフィールドエントリへの origin フィールドが追加されています。JSON Schema は https://databricks.github.io/appkit/schemas/template-plugins.schema.json で公開されています。

リソースフィールドのプロパティ

同期済みマニフェスト内の各リソースフィールドには、次のプロパティを指定できます。

origin (v2.0)

origin は同期時にフィールドの他のプロパティから算出される値で、プラグイン作成者が記述するものではありません。各値がどのような経路で実行中のアプリに渡されるかを、スキャフォールディングエージェントに伝えます。

優先順位は上記の順序どおりです (localOnly が value より優先され、value が resolve より優先されます) 。手動で編集した origin は、次回の同期時に変換処理によって上書きされます。ディスク上の値とフィールドの実際の形状が食い違うことは、仕組み上あり得ません。

Resolvers

resolve プロパティを持つフィールドは、ユーザーへの入力プロンプトではなく API 呼び出しの結果から CLI が自動的に設定します。形式は <type>:<field> です。

現時点でリゾルバーを持つリソースタイプは postgres のみです。ユーザーが指定した branch および database のリソース名から、次の値を導出します。

フィールド定義の例:

{
  "host": {
    "env": "PGHOST",
    "localOnly": true,
    "resolve": "postgres:host",
    "description": "Postgres host for local development."
  }
}

同期後、このフィールドには "origin": "platform" が付与されます (deploy 時に注入されるローカル専用フィールドでは、localOnly が resolve より優先されるため) 。

scaffolding.rules の伝播

各プラグインの scaffolding.rules ブロック (プラグインマニフェスト — Scaffolding rules を参照) は、そのまま appkit.plugins.json 内の該当エントリに引き継がれます。CLI は、マージ済みのプラグインレベルのルールを、トップレベルのテンプレートの scaffolding.rules とあわせて、databricks apps init を実行するスキャフォールディングエージェントに渡します。

マージモデル:

1. 選択されたすべてのプラグイン、および requiredByTemplate: true を持つすべてのプラグインからルールを収集します。
2. その上にテンプレートレベルの scaffolding.rules を適用します。
3. プラグインレベルのルールは、同一のディレクティブ箇所において、スキルに組み込まれた既定値やテンプレートレベルの既定値を上書きします。
4. プラグインの must がテンプレートの never (またはその逆) と競合する場合、init フローは停止します。詳細は以下のバリデーションルールを参照してください。

scaffolding ディスクリプタ (v2.0)

appkit.plugins.json のトップレベルにある scaffolding ブロックは、スキャフォールディングコマンドとそのフラグ、およびすべてのスキャフォールディングエージェントが従うべき横断的なルールを定義します。version が "2.0" の場合、CLI はこのブロックを必須とします。この要件はパース時にチェックされます。公開されている JSON Schema は条件付きの必須要件を表現できないため、トップレベルの必須フィールドとしては version と plugins のみを指定しています。

{
  "scaffolding": {
    "command": "databricks apps init",
    "flags": {
      "--name": {
        "description": "Project name — sets {{.projectName}} in package.json, databricks.yml, and .env. Required for non-interactive scaffolding.",
        "required": true,
        "pattern": "^[a-z][a-z0-9-]*$"
      },
      "--features": {
        "description": "Plugins to enable (comma-separated, no spaces; must match keys in this manifest's plugins map)",
        "required": false,
        "pattern": "^[a-zA-Z0-9_-]+(,[a-zA-Z0-9_-]+)*$"
      },
      "--profile": {
        "description": "Databricks CLI profile to use for authentication (global flag)",
        "required": false
      }
    },
    "rules": {
      "must": [
        "Keep all secrets and credentials only in app.yaml, databricks.yml, and/or .env"
      ],
      "should": [
        "ask user when in doubt of resource to use for plugin"
      ],
      "never": [
        "guess resources when multiple or no options are available",
        "embed secrets in files that will go to the client-bundle"
      ]
    }
  }
}

上記の例では 3 つのフラグを示しています。同期されるすべてのテンプレートマニフェストに同梱される標準のフラグセットは次のとおりです。

各ルール項目はスキーマにより 120 文字 に制限されています。長い文章は validation に失敗するため、実行可能な個別の指示に分割してください。

このディスクリプタは標準仕様です。値は AppKit が管理し、同期されるすべてのテンプレートマニフェストに同梱されます。これを利用するエージェント(LLM 主導のスキャフォールダーやカスタム CLI ランナーなど)の作成者は、ルールの一覧を提案ではなく遵守すべき契約として扱ってください。

代替可能性ゲート (テンプレートのルール)

テンプレートレベルのルールも、プラグイン レベルのルールと同じ代替可能性ゲートを通過する必要があります。つまり、各エントリはスキーマでは表現できない横断的なエージェントの判断を記述していなければなりません。「テンプレートディレクトリ内のファイルのみを変更する」や「catalog/schema を prompt した後に volume を一覧する」といったルールが含まれていないのは意図的です。前者はマニフェストを信頼できる唯一の情報源として読む限り起こり得ない状況であり、後者は現在 volume discovery kind の parents: ["catalog", "schema"] として構造的に表現されています (Plugin manifest — Transient prompts を参照) 。

関連項目

• プラグイン manifest — 作成側 (manifest.json) について。
• プラグイン management — appkit plugin sync、appkit plugin create。
• Configuration — 環境変数について。