Modelos

O AppKit usa um sistema de modelos baseado no comando databricks apps init da Databricks CLI. Os modelos definem a estrutura do projeto, e os arquivos .tmpl são processados pelo mecanismo text/template do Go para gerar uma saída personalizada.

Como funcionam os arquivos .tmpl

Qualquer arquivo terminado em .tmpl é processado pela CLI durante o databricks apps init:

1. O sufixo .tmpl é removido (ex.: .env.tmpl → .env)
2. As expressões de modelo do Go são avaliadas e substituídas
3. O arquivo renderizado é gravado no diretório de saída

Arquivos com o prefixo _ são renomeados para o prefixo . (ex.: _gitignore → .gitignore).

Variáveis de modelo

Conteúdo condicional

Use condicionais de modelo do Go para incluir/excluir código com base nos plugins selecionados:

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

appkit.plugins.json

O manifesto de plugins determina o comportamento da CLI durante o databricks apps init:

• UI de seleção de plugins — plugins selecionáveis exibidos no prompt interativo
• Prompts de recursos — recursos obrigatórios/opcionais solicitam valores ao usuário (por exemplo, o SQL Warehouse ID)
• Preenchimento do .dotEnv — campos de recurso com a propriedade env são gravados no .env
• Geração do app.yaml — campos de recurso geram entradas env + valueFrom
• Geração do databricks.yml — campos de recurso geram variáveis de bundle e entradas de recurso do app

O manifesto sincronizado é gerado pelo appkit plugin sync --write a partir do manifest.json de cada plugin (consulte Manifesto de plugin para conhecer o contrato de autoria). O formato em disco traz um campo version que a CLI usa para negociar funcionalidades:

• "1.0" / "1.1" — formatos anteriores; ainda legíveis.
• "2.0" — formato atual. Adiciona scaffolding (exigido pela CLI quando version é "2.0"; validado no momento do parse, e não pelo JSON Schema publicado) e o campo origin em cada entrada de campo de recurso. JSON Schema publicado em https://databricks.github.io/appkit/schemas/template-plugins.schema.json.

Propriedades dos campos de recurso

Cada campo de recurso no manifesto sincronizado pode ter estas propriedades:

origin (v2.0)

origin é calculado no momento da sincronização a partir das demais propriedades do campo — autores de plugins não o escrevem. Ele informa aos agentes de scaffolding como cada valor chega ao app em execução:

A precedência segue a ordem acima (localOnly prevalece sobre value, que prevalece sobre resolve). A transformação sobrescreve qualquer origin editado manualmente na sincronização seguinte — por construção, não há como ocorrer divergência entre o valor em disco e o formato real do campo.

Resolvers

Campos com a propriedade resolve são preenchidos automaticamente pela CLI a partir de chamadas de API, em vez de prompts ao usuário. O formato é <type>:<field>.

Atualmente, apenas o tipo de recurso postgres possui um resolver. Com base nos nomes de recurso branch e database informados pelo usuário, ele deriva:

Exemplo de definição de campo:

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

Após a sincronização, o campo passa a ter "origin": "platform" (porque localOnly tem precedência sobre resolve para campos exclusivamente locais injetados no momento do deploy).

Propagação de scaffolding.rules

O bloco scaffolding.rules de cada plugin (consulte Manifesto do plugin — Regras de scaffolding) é propagado sem alterações para a respectiva entrada em appkit.plugins.json. A CLI entrega as regras mescladas em nível de plugin — junto com o scaffolding.rules de nível superior do modelo — aos agentes de scaffolding que conduzem o databricks apps init.

Modelo de mesclagem:

1. Reunir as regras de cada plugin selecionado e de cada plugin com requiredByTemplate: true.
2. Aplicar o scaffolding.rules de nível de modelo por cima.
3. As regras em nível de plugin sobrescrevem os padrões embutidos na skill ou definidos em nível de modelo no mesmo ponto de diretiva.
4. Um must de plugin que entre em conflito com um never de modelo (ou vice-versa) interrompe o fluxo de init — consulte as regras de validação abaixo.

Descritor scaffolding (v2.0)

O bloco scaffolding no nível superior do appkit.plugins.json descreve o comando de scaffolding, suas flags e as regras transversais que todo agente de scaffolding deve respeitar. Ele é obrigatório para a CLI quando version é "2.0". Essa obrigatoriedade é verificada no momento do parse — o JSON Schema publicado marca apenas version e plugins como campos obrigatórios de nível superior, já que não é capaz de expressar requisitos condicionais.

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

O exemplo acima mostra três flags. O conjunto canônico de flags distribuído com cada manifesto de modelo sincronizado é:

Cada item de regra é limitado a 120 caracteres pelo schema. Textos longos não passam na validação — divida-os em diretivas acionáveis e independentes.

O descritor é canônico: o AppKit detém os valores e os distribui com cada manifesto de modelo sincronizado. Autores de agentes consumidores (scaffolders conduzidos por LLM, executores de CLI personalizados) devem tratar as listas de regras como contratos de cumprimento obrigatório, e não como sugestões.

Barreira de substituibilidade (regras de modelo)

As regras em nível de modelo passam pela mesma barreira de substituibilidade que rege as regras em nível de plugin: cada entrada deve descrever uma decisão transversal do agente que o schema ainda não seja capaz de codificar. Regras como "modificar apenas arquivos dentro do diretório do modelo" ou "listar volumes após solicitar catálogo/schema" foram omitidas de propósito — a primeira se torna irrelevante quando se lê o manifesto como fonte da verdade, e a segunda agora está codificada estruturalmente como parents: ["catalog", "schema"] no tipo de descoberta volume (consulte Manifesto do plugin — Prompts transitórios).

Veja também

• Manifesto do plugin — o lado da autoria (manifest.json).
• Gerenciamento de plugins — appkit plugin sync, appkit plugin create.
• Configuração — variáveis de ambiente.