Plantillas

AppKit utiliza un sistema de plantillas basado en el comando databricks apps init de la Databricks CLI. Las plantillas definen la estructura del project y los archivos .tmpl se procesan con el motor text/template de Go para generar un output personalizado.

Cómo funcionan los archivos .tmpl

La CLI procesa cualquier archivo que termine en .tmpl durante databricks apps init:

1. Se elimina el sufijo .tmpl (por ejemplo, .env.tmpl → .env)
2. Se evalúan y sustituyen las expresiones de template de Go
3. El archivo renderizado se escribe en el directorio de salida

Los archivos cuyo nombre empieza por _ se renombran con el prefijo . (por ejemplo, _gitignore → .gitignore).

Variables de template

Contenido condicional

Usa los condicionales de los templates de Go para incluir o excluir código según los plugins seleccionados:

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

appkit.plugins.json

El manifiesto de plugins determina el comportamiento de la CLI durante databricks apps init:

• UI de selección de plugins — plugins seleccionables que se muestran en el prompt interactivo
• Prompts de recursos — los recursos obligatorios/opcionales piden valores al usuario (p. ej., el ID del SQL Warehouse)
• Relleno de .dotEnv — los campos de recursos con una propiedad env se escriben en .env
• Generación de app.yaml — los campos de recursos generan entradas env + valueFrom
• Generación de databricks.yml — los campos de recursos generan variables de bundle y entradas de recursos de la app

El manifiesto sincronizado lo genera appkit plugin sync --write a partir del manifest.json de cada plugin (consulta Manifiesto del plugin para conocer el contrato de autoría). La estructura en disco incluye un campo version que la CLI utiliza para negociar funcionalidades:

• "1.0" / "1.1" — estructuras anteriores; siguen siendo legibles.
• "2.0" — estructura actual. Añade scaffolding (obligatorio para la CLI cuando version es "2.0"; se valida al analizar el archivo, no mediante el JSON Schema publicado) y el campo origin en cada entrada de campo de recurso. JSON Schema publicado en https://databricks.github.io/appkit/schemas/template-plugins.schema.json.

Propiedades de los campos de recurso

Cada campo de recurso del manifiesto sincronizado puede tener estas propiedades:

origin (v2.0)

origin se calcula durante la sincronización a partir de las demás propiedades del campo; los autores de plugins no lo escriben. Indica a los agentes de scaffolding cómo llega cada valor a la aplicación en ejecución:

La precedencia sigue el orden anterior (localOnly prevalece sobre value, que a su vez prevalece sobre resolve). La transformación sobrescribe cualquier origin editado a mano en la siguiente sincronización: por construcción, no puede haber divergencia entre el valor almacenado en disco y la forma real del campo.

Resolvers

Los campos con una propiedad resolve los completa automáticamente la CLI a partir de llamadas a la API, en lugar de solicitarlos al usuario. El formato es <type>:<field>.

Actualmente, solo el tipo de recurso postgres cuenta con un resolver. A partir de los nombres de recurso branch y database proporcionados por el usuario, deriva lo siguiente:

Ejemplo de definición de campo:

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

Tras la sincronización, el campo incluye "origin": "platform" (porque localOnly tiene prioridad sobre resolve en los campos exclusivamente locales que se inyectan durante el deploy).

Propagación de scaffolding.rules

El bloque scaffolding.rules de cada plugin (consulta Manifiesto del plugin — Reglas de scaffolding) se propaga sin cambios a su entrada en appkit.plugins.json. La CLI entrega las reglas combinadas a nivel de plugin —junto con el scaffolding.rules de nivel superior del template— a los agentes de scaffolding que ejecutan databricks apps init.

Modelo de combinación:

1. Recopila las reglas de cada plugin seleccionado y de cada plugin con requiredByTemplate: true.
2. Aplica por encima el scaffolding.rules a nivel de template.
3. Las reglas a nivel de plugin prevalecen sobre los valores predeterminados integrados en la skill o definidos a nivel de template en el mismo punto de la directiva.
4. Un must de un plugin que entra en conflicto con un never del template (o viceversa) detiene el flujo de inicialización; consulta las reglas de validación a continuación.

Descriptor scaffolding (v2.0)

El bloque scaffolding del nivel superior de appkit.plugins.json describe el comando de scaffolding, sus flags y las reglas transversales que todo agente de scaffolding debe respetar. La CLI lo exige cuando version es "2.0". Este requisito se valida durante el análisis: el JSON Schema publicado marca únicamente version y plugins como campos obligatorios de nivel superior, ya que no puede expresar requisitos condicionales.

{
  "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"
      ]
    }
  }
}

El ejemplo anterior muestra tres flags. El conjunto canónico de flags que se incluye con cada manifiesto de template sincronizado es:

El esquema limita cada elemento de regla a 120 caracteres. Los textos largos no superan la validación: divídelos en directivas concretas y accionables.

El descriptor es canónico: AppKit es el propietario de los valores y los incluye con cada manifiesto de template sincronizado. Los autores de agentes consumidores (scaffolders dirigidos por LLM, ejecutores de CLI personalizados) deben tratar las listas de reglas como contratos de obligado cumplimiento, no como sugerencias.

Filtro de sustituibilidad (reglas de template)

Las reglas a nivel de template superan el mismo filtro de sustituibilidad que rige las reglas a nivel de plugin: cada entrada debe describir una decisión transversal del agente que el esquema no pueda codificar por sí solo. Reglas como «modificar únicamente los archivos dentro del directorio del template» o «listar los volúmenes tras solicitar catálogo/esquema» se omiten a propósito: la primera es inalcanzable en cuanto se lee el manifiesto como fuente de verdad, y la segunda ya se codifica estructuralmente como parents: ["catalog", "schema"] en el tipo de descubrimiento volume (consulta Manifiesto del plugin — Prompts transitorios).

Véase también

• Manifiesto del plugin: la parte de la creación (manifest.json).
• Gestión de plugins: appkit plugin sync, appkit plugin create.
• Configuración: variables de entorno.