Gestión de plugins

AppKit incluye una CLI para gestionar plugins. Todos los comandos están disponibles en npx @databricks/appkit plugin.

Convención de manifiestos: manifest.json es el formato predeterminado y recomendado para los comandos de la CLI (sync, list, validate). Por seguridad de confianza cero, los manifiestos JS (manifest.js/manifest.cjs) se ignoran a menos que pases --allow-js-manifest, que ejecuta código del plugin y solo debería usarse con fuentes de confianza. El comando add-resource solo modifica manifest.json directamente en el archivo.

Crear un plugin

Genera la estructura de un nuevo plugin de forma interactiva o mediante flags:

# Modo interactivo (pregunta por todas las opciones)
npx @databricks/appkit plugin create

# Modo no interactivo (se proporcionan todos los flags obligatorios)
npx @databricks/appkit plugin create \
  --placement in-repo \
  --path plugins/my-plugin \
  --name my-plugin \
  --description "My custom plugin" \
  --resources sql_warehouse \
  --force

En modo interactivo, el asistente te guía por:

Ubicación: En tu repositorio (por ejemplo, plugins/my-plugin) o como paquete independiente
Metadatos: Nombre, nombre visible, descripción
Recursos: Qué recursos de Databricks necesita el plugin (SQL Warehouse, Secret, etc.) y si cada uno es obligatorio u opcional

En modo no interactivo, son obligatorios --placement, --path, --name y --description. Los recursos se pueden especificar como una lista separada por comas (--resources sql_warehouse,volume) o como JSON para tener control total (--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]'). Para ver todas las opciones disponibles, ejecuta npx @databricks/appkit plugin create --help.

El comando genera una estructura completa de plugin con manifest.json y una clase de plugin en TypeScript que importa el manifiesto directamente, lista para registrarse en tu aplicación.

Sincronizar los manifiestos de plugins

Analiza tu proyecto en busca de plugins y genera appkit.plugins.json:

npx @databricks/appkit plugin sync --write

Esto detecta los manifiestos de plugins en los paquetes instalados y las importaciones locales, y luego escribe un manifiesto consolidado que utilizan las herramientas de deployment. Los plugins referenciados en la llamada a createApp({ plugins: [...] }) se marcan automáticamente como obligatorios.

Los paquetes de Databricks instalados y de confianza (por ejemplo, @databricks/appkit) pueden cargar manifiestos JS empaquetados durante plugin sync. Para otros orígenes, si dependes intencionadamente de manifiestos JS, habilítalo de forma explícita:

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

Usa la opción --silent en los hooks de compilación para suprimir la salida:

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

Validar manifiestos

Valida los manifiestos de plugins frente al esquema JSON:

# Validar manifest.json en el directorio actual
npx @databricks/appkit plugin validate

# Validar archivos o directorios específicos
npx @databricks/appkit plugin validate plugins/my-plugin appkit.plugins.json

El validador detecta automáticamente si un archivo es un manifiesto de plugin o un manifiesto de template (a partir de $schema) e informa los errores con rutas legibles y los valores esperados.

Para incluir manifiestos JS en la validación, usa --allow-js-manifest.

Listar plugins

Consulta los plugins registrados en appkit.plugins.json o escanea un directorio:

# Desde appkit.plugins.json (predeterminado)
npx @databricks/appkit plugin list

# Analizar un directorio en busca de carpetas de plugins
npx @databricks/appkit plugin list --dir plugins/

# Analizar un directorio e incluir manifiestos JS (solo código de confianza)
npx @databricks/appkit plugin list --dir plugins/ --allow-js-manifest

# Salida JSON para scripting
npx @databricks/appkit plugin list --json

Agregar un recurso a un plugin

Agrega un nuevo requisito de recurso al manifiesto de un plugin existente. Requiere manifest.json en el directorio del plugin (el comando lo edita directamente; no modifica manifest.js):

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

# Modo no interactivo (--type activa el modo basado en 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

En modo no interactivo, solo --type es obligatorio: todos los demás campos (permiso, clave del recurso, variables de entorno de los campos) toman valores predeterminados razonables definidos en el esquema. Usa --dry-run para previsualizar el manifiesto actualizado sin escribirlo. Para ver todas las opciones disponibles, ejecuta npx @databricks/appkit plugin add-resource --help.