Modèles

AppKit s'appuie sur un système de modèles basé sur la commande databricks apps init de la Databricks CLI. Les modèles définissent la structure du projet, et les fichiers .tmpl sont traités par le moteur text/template de Go afin de générer une sortie personnalisée.

Fonctionnement des fichiers .tmpl

Tout fichier se terminant par .tmpl est traité par la CLI lors de l'exécution de databricks apps init :

1. Le suffixe .tmpl est supprimé (par ex. .env.tmpl → .env)
2. Les expressions de modèle Go sont évaluées et remplacées
3. Le fichier généré est écrit dans le répertoire de sortie

Les fichiers dont le nom commence par _ sont renommés avec un préfixe . (par ex. _gitignore → .gitignore).

Variables de modèle

Contenu conditionnel

Utilisez les conditions des modèles Go pour inclure ou exclure du code selon les plugins sélectionnés :

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

appkit.plugins.json

Le manifeste de plugins pilote le comportement de la CLI pendant databricks apps init :

• UI de sélection des plugins — les plugins sélectionnables affichés dans le prompt interactif
• Invites de ressources — les ressources requises/optionnelles invitent l'utilisateur à saisir des valeurs (par ex. l'ID du SQL Warehouse)
• Remplissage de .dotEnv — les champs de ressource dotés d'une propriété env sont écrits dans .env
• Génération de app.yaml — les champs de ressource produisent des entrées env + valueFrom
• Génération de databricks.yml — les champs de ressource produisent des variables de bundle et des entrées de ressource d'app

Le manifeste synchronisé est généré par appkit plugin sync --write à partir du manifest.json de chaque plugin (voir Manifeste de plugin pour le contrat de rédaction). La forme sur disque comporte un champ version que la CLI utilise pour négocier les fonctionnalités :

• "1.0" / "1.1" — formes antérieures ; toujours lisibles.
• "2.0" — forme actuelle. Ajoute scaffolding (requis par la CLI lorsque version vaut "2.0" ; imposé au moment de l'analyse, et non via le JSON Schema publié) ainsi que le champ origin sur chaque entrée de champ de ressource. JSON Schema publié à l'adresse https://databricks.github.io/appkit/schemas/template-plugins.schema.json.

Propriétés des champs de ressource

Chaque champ de ressource du manifeste synchronisé peut posséder les propriétés suivantes :

origin (v2.0)

origin est calculé lors de la synchronisation à partir des autres propriétés du champ — les auteurs de plugins ne le renseignent pas. Il indique aux agents de génération d'ossature comment chaque valeur parvient à l'application en cours d'exécution :

La priorité suit l'ordre ci-dessus (localOnly l'emporte sur value, qui l'emporte sur resolve). La transformation écrase tout origin modifié à la main lors de la synchronisation suivante : par construction, aucun écart n'est possible entre la valeur sur disque et la forme réelle du champ.

Resolvers

Les champs dotés d'une propriété resolve sont renseignés automatiquement par la CLI à partir d'appels d'API, et non via des saisies de l'utilisateur. Le format est <type>:<field>.

Actuellement, seul le type de ressource postgres dispose d'un resolver. À partir des noms de ressources branch et database fournis par l'utilisateur, il déduit :

Exemple de définition de champ :

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

Après la synchronisation, le champ porte "origin": "platform" (car localOnly prime sur resolve pour les champs exclusivement locaux injectés lors du déploiement).

Propagation de scaffolding.rules

Le bloc scaffolding.rules de chaque plugin (voir Manifeste de plugin — Règles d'ossature) est propagé tel quel dans son entrée de appkit.plugins.json. La CLI transmet aux agents de génération d’ossature qui pilotent databricks apps init les règles fusionnées au niveau des plugins, ainsi que le scaffolding.rules de niveau supérieur défini par le modèle.

Modèle de fusion :

1. Rassembler les règles de chaque plugin sélectionné et de chaque plugin ayant requiredByTemplate: true.
2. Appliquer par-dessus le scaffolding.rules du modèle.
3. Les règles de niveau plugin remplacent les valeurs par défaut intégrées aux compétences ou définies au niveau du modèle pour une même directive.
4. Un must de plugin en conflit avec un never de modèle (ou l'inverse) interrompt le flux d'initialisation — voir les règles de validation ci-dessous.

Descripteur scaffolding (v2.0)

Le bloc scaffolding, placé au niveau racine de appkit.plugins.json, décrit la commande de génération d'ossature, ses options et les règles transversales que tout agent de génération d'ossature doit respecter. La CLI l'exige lorsque version vaut "2.0". Cette contrainte est vérifiée au moment de l'analyse : le JSON Schema publié ne déclare que version et plugins comme champs obligatoires de premier niveau, car il ne permet pas d'exprimer d'exigences conditionnelles.

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

L'exemple ci-dessus présente trois options. Le jeu d'options canonique livré avec chaque manifeste de modèle synchronisé est le suivant :

Le schéma limite chaque règle à 120 caractères. Un texte trop long échoue à la validation — découpez-le en directives distinctes et actionnables.

Le descripteur fait autorité : AppKit en détient les valeurs et les livre avec chaque manifeste de modèle synchronisé. Les auteurs d'agents consommateurs (générateurs d'ossature pilotés par LLM, exécuteurs CLI personnalisés) doivent traiter les listes de règles comme des contrats à respecter, et non comme de simples suggestions.

Filtre de substituabilité (règles de modèle)

Les règles au niveau du modèle sont soumises au même filtre de substituabilité que les règles au niveau du plugin : chaque entrée doit décrire une décision transverse de l'agent que le schéma ne peut pas déjà encoder. Des règles comme « ne modifier que les fichiers situés dans le répertoire du modèle » ou « lister les volumes après avoir demandé le catalogue/schéma » sont volontairement absentes — la première n'a plus lieu d'être dès lors que l'on considère le manifeste comme la source de vérité, et la seconde est désormais encodée structurellement sous la forme parents: ["catalog", "schema"] sur le type de découverte volume (voir Manifeste de plugin — Prompts transitoires).

Voir aussi

• Manifeste du plugin — la partie rédaction (manifest.json).
• Gestion des plugins — appkit plugin sync, appkit plugin create.
• Configuration — variables d'environnement.