Manifesto do plugin — referência

A referência completa do PluginManifest — cada campo que um plugin pode declarar e o que o runtime faz com ele. Para a introdução conceitual, veja Manifesto do plugin.

O tipo canônico vive em @fayz-ai/core (PluginManifest). Um plugin — oficial ou app-local — é sempre uma factory que devolve este objeto.

Campos de identidade

Campo	Tipo	Obrigatório	Descrição
`id`	`string`	sim	Identificador único do plugin.
`name`	`string`	sim	Nome exibido.
`icon`	`string`	sim	Nome do ícone.
`version`	`string`	sim	Versão do plugin (semver).
`apiVersion`	`number`	não	Versão do contrato de plugin. O runtime recusa um plugin construído para um contrato mais novo do que suporta. Omitir = legado/compatível.
`description`	`string`	não	Descrição curta.
`scope`	`PluginScope`	não	`core` · `vertical` · `universal` · `addon` · `tenant`.
`verticalId`	`VerticalId`	não	`beauty` · `food` · `health` · `services` · `retail` · `education` · (custom).
`scaffolds`	`ScaffoldType[]`	não	Scaffolds que o plugin suporta. Omitir = universal.
`defaultEnabled`	`boolean`	não	Se já vem ligado.
`dependencies`	`string[]`	não	Ids de outros plugins de que depende.
`tenantId`	`string`	não	Vincula o plugin a um tenant específico (instâncias por tenant).
`schema`	`string`	não	Schema de banco em que as tabelas do plugin vivem.

UI e navegação

Campo	Tipo	Obrigatório	Descrição
`navigation`	`PluginNavigationEntry[]`	sim	Itens de menu. Cada um: `section` (`main`/`secondary`/`settings`), `position`, `label`, `route`, `icon?`, `badge?`, `permission?`.
`routes`	`PluginRouteDefinition[]`	sim	Rotas. Cada uma: `path`, `component` ou `componentId`, `guard?` (`authenticated`/`role`/`public`/`share-token`), `roles?`, `permission?`, `fullBleed?`.
`settings`	`PluginSettingsTab[]`	não	Abas na tela de configurações. `id`, `label`, `component`/`componentId`, `order?`, `permission?`.
`widgets`	`PluginWidgetDefinition[]`	não	Componentes injetados em zonas do shell. `id`, `zone` (`WidgetZone`), `component`/`componentId`, `order?`, `visibility?`.
`dashboardWidgets`	`DashboardWidgetDef[]`	não	KPIs/gráficos/tabelas contribuídos ao dashboard. `id`, `title`, `kind` (`kpi`/`chart`/`table`/`onboarding`/`custom`), `span?`, `surfaces?`.
`onboarding`	`PluginOnboarding`	não	Fluxo de primeiro uso. `component`/`componentId`, `title?`, `description?`.

Componente por valor ou por id: em toda parte (rotas, abas, widgets), você fornece ou component (o componente React direto) ou componentId (um id resolvido pelo registry) — exatamente um.

Comportamento e integração

Campo	Tipo	Descrição
`events`	`PluginEventDefinition[]`	Eventos que o plugin emite no bus. `name` namespaced (`agenda.booking.confirmed`), `description?`, `payloadSchema?`.
`capabilities`	`PluginCapability[]`	Capacidades declaradas. `id`, `label`, `kind?` (`page`/`widget`/`data`/`integration`).
`aiTools`	`PluginAITool[]`	Ferramentas para um agente de IA. `id`, `name`, `description`, `mode` (`read`/`persist`), `parameters?`, `permission?`, `suggestions?`.
`connectors`	`ConnectorDefinition[]`	Conectores para provedores externos (o plugin como addon de um host). Veja o catálogo de Integrações.
`registries`	`PluginRegistryDef[]`	Entidades registradas com `seedData`/`mockData` e display (`table`/`cards`/`tree`).

Dados, permissões e diagnóstico

Campo	Tipo	Descrição
`entities`	`string[]`	Entidades de dados que o plugin registra.
`permissions`	`string[]`	Permissões que o plugin usa.
`declaredFeatures`	`FeatureDeclaration[]`	Features declaradas para o controle de acesso.
`migrations`	`PluginMigration[]`	O SQL das tabelas do plugin. Cada uma: `id`, `version`, `sql`, `description?`.
`diagnostics`	`PluginDiagnostic[]`	Pré-requisitos de backend verificados pelo `fayz doctor`. `requires` (`rpcs`/`views`/`tables`/`migrations`/`env`), `level?` (`error`/`warn`/`info`).
`locales`	`Record<string, Record<string, string>>`	Traduções por idioma.

Exemplo mínimo

O plugin gerado pelo incubator — o menor manifesto válido e útil:

import type { PluginManifest } from '@fayz-ai/core'

export function createFidelidadePlugin(): PluginManifest {
  const Page = () => /* ... */ null
  return {
    id: 'fidelidade',
    name: 'Fidelidade',
    icon: 'Puzzle',
    version: '0.1.0',
    navigation: [
      { section: 'main', position: 50, label: 'Fidelidade', route: '/fidelidade', icon: 'Puzzle' },
    ],
    routes: [{ path: '/fidelidade', component: Page }],
  }
}

Exemplo com seams

O mesmo plugin declarando dados, permissões e um diagnóstico:

return {
  id: 'fidelidade',
  name: 'Fidelidade',
  icon: 'Puzzle',
  version: '0.1.0',
  apiVersion: 1,
  navigation: [{ section: 'main', position: 50, label: 'Fidelidade', route: '/fidelidade', icon: 'Award' }],
  routes: [{ path: '/fidelidade', component: Page }],
  permissions: ['fidelidade:read', 'fidelidade:write'],
  migrations: [{ id: 'fidelidade-0001', version: '0.1.0', sql: 'create table fid_points (...)' }],
  diagnostics: [
    { id: 'fid-tables', requires: { tables: ['fid_points'] }, level: 'warn' },
  ],
  locales: {
    'pt-BR': { 'fidelidade.title': 'Fidelidade' },
    en: { 'fidelidade.title': 'Loyalty' },
  },
}

Próximo: a ferramenta que valida tudo isso em CLI.