Gerenciamento de plugins

O AppKit inclui uma CLI para gerenciar plugins. Todos os comandos estão disponíveis em npx @databricks/appkit plugin.

Convenção de manifesto: manifest.json é o formato padrão e recomendado para os comandos da CLI (sync, list, validate). Por questões de segurança de confiança zero, manifestos JS (manifest.js/manifest.cjs) são ignorados, a menos que você use a flag --allow-js-manifest, que executa o código do plugin e só deve ser usada com fontes confiáveis. O comando add-resource edita apenas o próprio manifest.json.

Criar um plugin

Faça o scaffold de um novo plugin de forma interativa ou via flags:

# Modo interativo (pergunta todas as opções)
npx @databricks/appkit plugin create

# Modo não interativo (todas as flags obrigatórias fornecidas)
npx @databricks/appkit plugin create \
  --placement in-repo \
  --path plugins/my-plugin \
  --name my-plugin \
  --description "My custom plugin" \
  --resources sql_warehouse \
  --force

No modo interativo, o assistente guia você pelas seguintes etapas:

Posicionamento: No seu repositório (por exemplo, plugins/my-plugin) ou como um pacote independente
Metadados: Nome, nome de exibição, descrição
Recursos: De quais recursos do Databricks o plugin precisa (SQL Warehouse, Secret, etc.) e se cada um é obrigatório ou opcional

No modo não interativo, --placement, --path, --name e --description são obrigatórios. Os recursos podem ser especificados como uma lista separada por vírgulas (--resources sql_warehouse,volume) ou como JSON, para controle total (--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]'). Para ver todas as opções disponíveis, execute npx @databricks/appkit plugin create --help.

O comando gera um scaffold completo de plugin, com manifest.json e uma classe TypeScript de plugin que importa o manifesto diretamente — pronta para ser registrada no seu app.

Sincronizar manifestos de plugins

Examine seu projeto em busca de plugins e gere o appkit.plugins.json:

npx @databricks/appkit plugin sync --write

Isso descobre os manifestos de plugins nos pacotes instalados e nas importações locais e, em seguida, grava um manifesto consolidado usado pelas ferramentas de deployment. Os plugins referenciados na chamada createApp({ plugins: [...] }) são marcados automaticamente como obrigatórios.

Pacotes Databricks instalados e confiáveis (por exemplo, @databricks/appkit) podem carregar manifestos JS empacotados durante o plugin sync. Para outras origens, caso você dependa intencionalmente de manifestos JS, ative essa opção explicitamente:

npx @databricks/appkit plugin sync --write --allow-js-manifest

Use a flag --silent nos hooks de build para suprimir a saída:

{
  "scripts": {
    "sync": "appkit plugin sync --write --silent",
    "predev": "npm run sync",
    "prebuild": "npm run sync"
  }
}

Validar manifestos

Valide os manifestos de plugin com base no JSON schema:

# Valida o manifest.json no diretório atual
npx @databricks/appkit plugin validate

# Valida arquivos ou diretórios específicos
npx @databricks/appkit plugin validate plugins/my-plugin appkit.plugins.json

O validador detecta automaticamente se um arquivo é um manifesto de plugin ou de template (a partir do $schema) e informa os erros com caminhos legíveis e os valores esperados.

Para incluir manifestos JS na validação, use --allow-js-manifest.

Listar plugins

Visualize os plugins registrados no appkit.plugins.json ou faça a varredura de um diretório:

# A partir do appkit.plugins.json (padrão)
npx @databricks/appkit plugin list

# Verifica um diretório em busca de pastas de plugins
npx @databricks/appkit plugin list --dir plugins/

# Verifica um diretório e inclui manifestos JS (apenas código confiável)
npx @databricks/appkit plugin list --dir plugins/ --allow-js-manifest

# Saída em JSON para uso em scripts
npx @databricks/appkit plugin list --json

Adicionar um recurso a um plugin

Adicione um novo requisito de recurso a um manifesto de plugin existente. Requer o manifest.json no diretório do plugin (o comando o edita no próprio arquivo; não modifica o manifest.js):

# Modo interativo
npx @databricks/appkit plugin add-resource
npx @databricks/appkit plugin add-resource --path plugins/my-plugin

# Modo não interativo (--type ativa o modo baseado em flags)
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run

No modo não interativo, apenas --type é obrigatório — todos os outros campos (permissão, chave do recurso, variáveis de ambiente dos campos) assumem valores padrão adequados, obtidos do schema. Use --dry-run para visualizar o manifesto atualizado sem gravá-lo. Para ver todas as opções disponíveis, execute npx @databricks/appkit plugin add-resource --help.