Esquema do núcleo do Aggrega (Plugin)
Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/plugin-v1beta1.schema.json
Um plugin Wasm: um módulo WebAssembly publicado em um registro OCI e identificado pelo seu metadata.pluginType — o socket que ele implementa — mais o seu metadata.name simples, que declara a versão de ABI a que se destina, um ponteiro de assinatura opcional e um bloco de runtime opcional. A entidade e o seu .wasm são publicados como um único manifesto OCI com a tag metadata.version — o YAML da entidade como blob de configuração do manifesto, o .wasm como uma camada inline, assinados uma única vez. A identidade é a coordenada metadata.pluginType/metadata.name mais a metadata.version da entidade; a localização do .wasm é derivada dessa coordenada mais o registro configurado, e o digest do conteúdo resolvido fica no arquivo de bloqueio, não na entidade. O arquivo de bloqueio registra o digest, e a política de confiança por registro verifica a assinatura do artefato no pull. O compilador não interpreta o comportamento do plugin — ele roteia a referência; o runtime WebAssembly executa os bytes.
Consulte a referência de autoria do Plugin para orientações em prosa sobre como escrever entidades Plugin; esta página documenta o esquema estrutural que essa referência descreve.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sim | Constante: "aggrega.ai/v1beta1" |
kind | const “Plugin” | sim | Constante: "Plugin" |
metadata | object | sim | |
spec | object | sim | A versão de ABI a que o plugin se destina, um ponteiro de assinatura opcional e um bloco de runtime opcional. A localização do .wasm do plugin é derivada da identidade do plugin — o seu metadata.pluginType (o socket) mais o seu metadata.name simples — e do registro configurado; ela não é incluída na spec. |
Não são permitidas propriedades adicionais.
plugin.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 caractere. |
version | string | sim | Versionamento semântico estrito da entidade Plugin (por exemplo, 1.0.0). Padrão: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
pluginType | string (enum) | sim | O tipo de socket que este plugin implementa. Um plugin implementa exatamente um tipo de socket, extraído da taxonomia de tipos de plugin que o runtime reconhece: provider (renderiza nós da IR em artefatos nativos do provedor), linter (inspeciona o conteúdo escrito pelos autores e emite diagnósticos), pipeline-step (uma etapa do pipeline: de uma FeatureRecipe ou de uma Recipe que aplica patches ao conjunto de documentos renderizados), governance (atende aos papéis de governança do pipeline de build — transformando os rótulos dos nós na construção da topologia, ou emitindo um veredito de aceitação/rejeição sobre o grafo da IR na análise estática ou sobre os artefatos renderizados na renderização; é o papel ao qual ele está vinculado, e não o seu tipo, que define o que ele pode emitir), cli (contribui com um subcomando de runtime aggrega <cmd> que um operador invoca na linha de comando — um socket de runtime, distinto dos sockets de renderização e de pipeline em tempo de compilação), parser (transforma um texto de origem externo em uma árvore estruturada canônica para que um consumidor leia a árvore sem precisar carregar o seu próprio parser da linguagem, anunciando os formatos que trata como capacidades parse:<format>), importer (transforma uma fonte externa de infraestrutura ou de definição de agentes em rascunhos de arquivos de autoria do Aggrega, anunciando os formatos que trata como capacidades import:<format>). Valores permitidos: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer" |
description | string | não | O que esta entidade é e para que serve, escrito para quem está decidindo se vai usá-la. Comece com uma frase que nomeie a coisa e depois acrescente o que um leitor precisa para escolhê-la e usá-la corretamente — o que ela espera do build que a executa, e qualquer coisa surpreendente sobre como ela se comporta. Um parágrafo curto é o tamanho habitual. |
maintainers | object[] | não | Lista de mantenedores responsáveis por esta entidade. |
license | string | não | Identificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Ele registra os termos desse software, não os termos deste arquivo. |
repository | string | não | A URL do repositório Git onde ficam os arquivos-fonte. |
home | string | não | A URL da página inicial, do wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do usuário. |
Não são permitidas propriedades adicionais.
plugin.metadata.maintainers[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | |
email | string | não | |
url | string | não |
Não são permitidas propriedades adicionais.
plugin.spec
A versão de ABI a que o plugin se destina, um ponteiro de assinatura opcional e um bloco de runtime opcional. A localização do .wasm do plugin é derivada da identidade do plugin — o seu metadata.pluginType (o socket) mais o seu metadata.name simples — e do registro configurado; ela não é incluída na spec.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
abiVersion | string (enum) | sim | A versão de ABI host/guest a que o plugin se destina. v1beta1 é o único valor aceito; um Plugin que declara uma versão de ABI que este compilador não fala mais é recusado, com o nome da versão para a qual recompilar o plugin. Valores permitidos: "v1beta1" |
signature | object | não | Um ponteiro descritivo opcional para a assinatura anexada do plugin. Este bloco é apenas documentação — registra, para os leitores do catálogo, onde a assinatura está e como foi produzida; ele mesmo não bloqueia nem admite o plugin. A verificação que efetivamente se aplica é a política de confiança por registro aplicada no pull: uma assinatura é baixada como referrer OCI, verificada em relação às identidades confiáveis ou à chave fixada do registro e registrada como um fato verificado no arquivo de bloqueio. Um registro que exige assinaturas interrompe o pull quando uma assinatura exigida está ausente, não é confiável ou é inválida. |
runtime | object | não | Restrições de execução opcionais que o host aplica ao carregar e executar o plugin. O acesso de saída à rede não é um campo de autoria: um plugin nunca acessa a rede em tempo de build (o limite ahead-of-time), então não há aqui nenhum campo de lista de hosts permitidos a escrever. |
exports | object[] | não | As exportações que este plugin oferece, cada uma com a sua capacidade declarada. Uma exportação é um ponto de entrada nomeado para o qual o host despacha as chamadas (por exemplo, render_node, lint_naming, step); o bloco de capacidade por exportação é a declaração do autor sobre o que essa exportação faz, que o host confere com a autodeclaração do plugin na publicação e no carregamento. As entradas preservam a ordem do autor. A ausência não declara nenhuma superfície de exportação escrita pelo autor. |
commands | object[] | não | Gerenciado pela máquina, não escreva à mão: registrado por aggrega plugin sync (ou aggrega plugin gen-catalog) a partir da autodeclaração do plugin. Os verbos de nível superior aggrega <command> com que um plugin de CLI contribui são lidos da autodeclaração do plugin e registrados aqui na ordem em que a autodeclaração os declara, de modo que a superfície de comandos com que um plugin de CLI se instala pode ser lida a partir da entidade sem carregar o plugin. Um plugin que não é de CLI não contribui com comandos e registra uma lista vazia. O host instala exatamente esse conjunto; um conjunto registrado que diverge da autodeclaração do plugin interrompe o carregamento, e a publicação recusa um conjunto fora de sincronia com o binário e orienta o autor a registrá-lo novamente. |
provider | object | não | O bloco do socket de provedor para um plugin pluginType: provider: as capacidades que ele atende, como ele traduz o tipo Workload de aggrega.ai/v1beta1, quais anotações nativas da plataforma ele lê e o seu contrato de comportamento de renderização. Presente apenas em plugins de renderização de provedor; ausente em qualquer outro tipo de plugin. |
pipelineStep | object | não | O bloco pipeline-step para um plugin pluginType: pipeline-step: as capacidades do provedor com as quais a sua etapa é compatível. Presente apenas em plugins pipeline-step; ausente em qualquer outro tipo de plugin. |
parser | object | não | O bloco parser para um plugin pluginType: parser: os formatos de origem que ele transforma em uma árvore estruturada canônica. Presente apenas em plugins parser; ausente em qualquer outro tipo de plugin. |
importer | object | não | O bloco importer para um plugin pluginType: importer: os formatos de origem externos que ele transforma em rascunhos de arquivos de autoria do Aggrega, e as assinaturas pelas quais se reconhece uma fonte nesses formatos. Presente apenas em plugins importer; ausente em qualquer outro tipo de plugin. |
Não são permitidas propriedades adicionais.
plugin.spec.signature
Um ponteiro descritivo opcional para a assinatura anexada do plugin. Este bloco é apenas documentação — registra, para os leitores do catálogo, onde a assinatura está e como foi produzida; ele mesmo não bloqueia nem admite o plugin. A verificação que efetivamente se aplica é a política de confiança por registro aplicada no pull: uma assinatura é baixada como referrer OCI, verificada em relação às identidades confiáveis ou à chave fixada do registro e registrada como um fato verificado no arquivo de bloqueio. Um registro que exige assinaturas interrompe o pull quando uma assinatura exigida está ausente, não é confiável ou é inválida.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | const “sigstore-cosign” | sim | O esquema de assinatura. sigstore-cosign é o esquema suportado. Constante: "sigstore-cosign" |
signatureRef | string | não | A referência de referrer OCI do bundle de assinatura anexado, para documentação e descoberta. Ausente quando a assinatura é descoberta pela enumeração de referrers no pull, em vez de ser fixada aqui. |
publicKeyRef | string | não | Um ponteiro para a chave pública com a qual a assinatura foi produzida, para uma assinatura com chave. A ausência indica uma assinatura sem chave (identidade OIDC), verificada em relação às identidades confiáveis do registro. |
Não são permitidas propriedades adicionais.
plugin.spec.runtime
Restrições de execução opcionais que o host aplica ao carregar e executar o plugin. O acesso de saída à rede não é um campo de autoria: um plugin nunca acessa a rede em tempo de build (o limite ahead-of-time), então não há aqui nenhum campo de lista de hosts permitidos a escrever.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
maxMemoryPages | integer | não | Limita a memória linear do plugin em páginas Wasm (64 KiB por página). Zero ou a ausência aplica o teto padrão da plataforma, de modo que um carregamento nunca é ilimitado; uma vinculação que precisa de mais aumenta esse valor. Mínimo: 0. |
timeoutMs | integer | não | Limita por quanto tempo o próprio código do plugin pode ser executado durante uma chamada, em milissegundos, sem contar o tempo gasto dentro das funções do host que ele chama. No Linux a medida é o tempo de processador, então o tempo gasto esperando por um processador em uma máquina ocupada não conta; em outros sistemas é o tempo decorrido. A primeira chamada a um plugin recém-carregado também conta a própria inicialização do plugin. Zero ou a ausência aplica o teto padrão da plataforma, de modo que uma chamada nunca é impossível de cancelar; uma vinculação que é executada por mais tempo aumenta esse valor. Mínimo: 0. |
hostFunctions | string[] | não | Gerenciado pela máquina, não escreva à mão: as funções do host que o plugin importa, lidas da seção de importação do .wasm por aggrega plugin sync (ou aggrega plugin gen-catalog) e registradas aqui em forma canônica (ordenada, sem duplicatas). A publicação as deriva novamente do binário e recusa uma entidade cujo registro difere; o pull as deriva novamente e as verifica outra vez. O host registra exatamente esse conjunto derivado e valida cada entrada em relação à allowlist curada. |
configKV | mapa de string | não | Configuração específica do Plugin que o runtime entrega ao plugin na inicialização, como pares chave/valor de string para string. As entradas preservam a ordem do autor para que o registro emitido seja idêntico byte a byte entre execuções. A ausência mantém em vigor a configuração vazia padrão do runtime. |
Não são permitidas propriedades adicionais.
plugin.spec.exports[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome ABI da exportação — o nome para o qual o host despacha (por exemplo, render_node, lint_naming, step). Pelo menos 1 caractere. |
operates | string (enum) | não | A operação de pipeline que esta exportação realiza: patch (modificar um documento renderizado existente) ou emit (adicionar um novo documento). A ausência não traz nenhuma declaração de operação. Valores permitidos: "patch", "emit" |
scope | string (enum) | não | A raiz de documentos sobre a qual esta exportação opera: own (os documentos renderizados próprios do nó) ou host (os documentos do componente ao qual está vinculada uma FeatureRecipe com escopo de componente). A ausência não traz nenhuma declaração de escopo. Valores permitidos: "own", "host" |
selector | string | não | Uma descrição livre e legível por pessoas daquilo sobre o que a exportação atua (por exemplo, workloads carrying a pod template). Documentação para os leitores do catálogo; o compilador não a interpreta. |
Não são permitidas propriedades adicionais.
plugin.spec.commands[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O verbo de comando que o host registra — o token aggrega <name> que um operador invoca, e o discriminador que o host entrega ao plugin na invocação para que um único plugin que atende a vários comandos faça o roteamento conforme o comando chamado. Pelo menos 1 caractere. |
description | string | não | O texto de ajuda curto, de uma linha, do comando, exibido na listagem de comandos e na saída de ajuda. Apenas documentação; o host não age com base nele. |
flags | object[] | não | Os flags do comando, na ordem declarada. Cada entrada contribui com um flag que o host registra no comando para que aggrega help --help, -h e os flags globais; o host verifica isso quando adiciona os comandos do plugin, e um plugin cujas declarações falham não é adicionado, com um aviso. |
Não são permitidas propriedades adicionais.
plugin.spec.commands[].flags[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome longo do flag — o token —name que um operador passa na linha de comando. Todo flag declarado deve indicá-lo. Pelo menos 1 caractere. |
shorthand | string | não | O alias curto opcional do flag — a forma -x que um operador pode passar em vez do nome longo — como uma única letra ou um único dígito ASCII. A ausência significa que o flag não tem alias curto. Padrão: ^[A-Za-z0-9]$. |
description | string | não | O texto de ajuda de uma linha do flag, exibido na saída de ajuda do comando. É documentação opcional; o host não o valida nem age com base nele. |
type | string (enum) | não | O tipo de valor do flag — string, bool ou int — e o tipo de flag como o qual a ajuda o exibe. A ausência o exibe como um flag de string. Valores permitidos: "string", "bool", "int" |
default | string | não | O valor padrão da flag quando o operador não a passa, expresso como string. Para uma flag bool ou int, é um valor desse tipo. Se ausente, a flag não declara valor padrão. |
Não são permitidas propriedades adicionais.
plugin.spec.provider
O bloco do socket de provedor para um plugin pluginType: provider: as capacidades que ele atende, como ele traduz o tipo Workload de aggrega.ai/v1beta1, quais anotações nativas da plataforma ele lê e o seu contrato de comportamento de renderização. Presente apenas em plugins de renderização de provedor; ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registrada a partir da autodeclaração do .wasm do plugin por aggrega plugin gen-catalog, de modo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deve oferecer, e não pode adicionar nenhuma que a autodeclaração não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que a autodeclaração não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e aponta cada capacidade que a autodeclaração nomeia e que a lista deixa de fora. As capacidades que este provedor atende — nomes de capacidade como helm ou compose — cuja forma de saída ele renderiza. Um provedor é genérico entre artefatos que compartilham a forma de saída de uma capacidade, não entre todas as capacidades, então a lista é uma declaração explícita de compatibilidade testada, e não uma aspiração. As entradas preservam a ordem do autor. O destino de provedor solicitado por uma Recipe é resolvido para o plugin de provedor cuja lista contém esse destino; um destino listado por mais de um plugin de provedor interrompe como ambíguo, a menos que a seleção plugins.providers da configuração do workspace indique qual plugin usar. Uma lista vazia ou ausente não declara nenhuma capacidade, então o plugin não atende nenhum destino. |
workloadSchema | string | não | JSON Schema 2020-12 que documenta como este provedor traduz o tipo Workload de aggrega.ai/v1beta1 em manifestos nativos do provedor. Quando presente, o provedor suporta Recipes que declaram um bloco workload: (modo sintetizado) — o provedor traduz o Workload em manifestos nativos do provedor, orientado por este esquema como documentação/contrato. Se uma Recipe com workload: é suportada é determinado pela capacidade de síntese do provedor vinculado, não pela presença deste campo: uma Recipe em modo sintetizado vinculada a um provedor que não consegue sintetizar é interrompida de forma bem visível no momento da renderização. O catálogo da biblioteca padrão declara workloadSchema nos provedores que sintetizam como o contrato documentado, mantido em sincronia com essa capacidade. O campo é o contrato documentado: o corpo é compilado para JSON Schema 2020-12 no carregamento para verificar se está bem formado, e nada mais o lê. |
wellKnownAnnotations | object[] | não | A declaração de suporte do provedor: as chaves de anotação bem conhecidas nativas da plataforma (o namespace aggrega.ai/) que este provedor lê, cada uma com o escopo em que é lida e o comportamento aplicado quando está ausente. Declare uma chave apenas onde o provedor a lê — a matriz de suporte publicada é renderizada a partir dessas declarações, então uma chave listada aqui é uma chave que um autor pode esperar que altere a saída renderizada no escopo que ela nomeia. O compilador lê a declaração de duas maneiras: um scope que nomeia um tipo de entrada que o próprio contract.inputKinds do provedor não declara contradiz uma declaração adjacente na mesma entidade, e o build é interrompido nomeando a chave e a contradição; e um build emite um aviso sobre uma anotação aggrega.ai/ que chega a uma renderização por meio deste provedor quando nenhuma entrada a cobre em nenhum tipo de entrada que essa renderização declara. Ela é distinta da regra que rege a associação de um valor sob o prefixo reservado aggrega.ai/. A ausência não declara nenhum suporte, e nenhum aviso desse tipo é emitido para este provedor; um provedor que não lê nenhuma dessas chaves declara readsNoWellKnownAnnotations em vez desta lista. As entradas são uma lista ordenada e preservam a ordem do autor. |
readsNoWellKnownAnnotations | const true | não | Declara que este provedor não lê nenhuma das chaves de anotação nativas da plataforma no namespace aggrega.ai/, as chaves que wellKnownAnnotations listaria de outra forma: uma declaração de suporte que não cobre nenhuma chave, o que é uma afirmação, enquanto omitir tanto este campo quanto wellKnownAnnotations é silêncio. Um build então emite um aviso sobre cada anotação aggrega.ai/ que chega a uma renderização por meio deste provedor, nomeando a chave, o provedor e os tipos de entrada que essa renderização declara; o valor ainda passa intacto e o build não é interrompido. Somente true pode ser escrito, de modo que omitir o campo continua sendo a única maneira de não dizer nada. Não pode ser escrito junto com wellKnownAnnotations: um provedor que lê algumas das chaves as lista ali em vez disso. Constante: true |
contract | object | não | O contrato de comportamento de renderização autodeclarado do provedor: os tipos de entrada que ele renderiza, como ele monta a saída por nó de um grupo de despacho e sob quais diretórios essa saída fica, o par de delimitadores de template que ele aplica aos arquivos de artefatos importados, se uma única instância carregada pode atender a cada travessia, se ele conecta arestas entre fronteiras, se ele respeita as entradas de omissão, se ele aceita os arquivos com que uma Recipe contribui para a saída compartilhada da sua fronteira, e quais arquivos o seu ecossistema nunca entrega ao lado de uma fonte. É o registro, no momento da publicação, da autodeclaração do plugin de provedor, que o host confere com essa mesma autodeclaração na publicação e no carregamento. A ausência não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as declarações por exportação. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.wellKnownAnnotations[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
key | string | sim | A chave de anotação bem conhecida nativa da plataforma que o provedor lê (por exemplo, aggrega.ai/namespace). Fica sob o namespace de anotações aggrega.ai/ reservado à plataforma — as diretivas de plataforma lidas pelo provedor. Padrão: ^aggrega\.ai/.+. |
purpose | string | sim | O que a anotação controla — o comportamento de renderização que ela influencia quando presente. |
defaultBehavior | string | não | O comportamento que o provedor aplica quando esta anotação está ausente. |
scope | string (enum)[] | não | Onde este provedor lê a chave. Os três primeiros valores são os tipos de entrada da Recipe e nomeiam o caminho de renderização em que a chave é lida — sourced um conjunto de arquivos vendorizados, synthesized um Workload que o provedor materializa, artifactsStandalone um nó cuja saída inteira são documentos de artefatos importados. Cada um deles deve ser um tipo de entrada que o contract.inputKinds deste provedor declara; nomear um que ele não declara interrompe o build. boundary é para uma chave resolvida uma vez por fronteira em vez de por nó — o nome de um artefato montado, ou o contexto de posicionamento a partir do qual uma referência entre fronteiras é formada —, onde o tipo de entrada não é um eixo significativo, então ela não é comparada com contract.inputKinds. Uma chave lida em mais de um caminho lista todos eles. A ausência não faz nenhuma declaração por caminho: nada é verificado, e a chave afirma apenas que o provedor a lê em algum lugar. Pelo menos 1 entrada. Nenhuma entrada pode aparecer duas vezes. Valores permitidos para cada entrada: "sourced", "synthesized", "artifactsStandalone", "boundary". |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract
O contrato de comportamento de renderização autodeclarado do provedor: os tipos de entrada que ele renderiza, como ele monta a saída por nó de um grupo de despacho e sob quais diretórios essa saída fica, o par de delimitadores de template que ele aplica aos arquivos de artefatos importados, se uma única instância carregada pode atender a cada travessia, se ele conecta arestas entre fronteiras, se ele respeita as entradas de omissão, se ele aceita os arquivos com que uma Recipe contribui para a saída compartilhada da sua fronteira, e quais arquivos o seu ecossistema nunca entrega ao lado de uma fonte. É o registro, no momento da publicação, da autodeclaração do plugin de provedor, que o host confere com essa mesma autodeclaração na publicação e no carregamento. A ausência não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as declarações por exportação.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
inputKinds | object | não | Quais dos três tipos de entrada de Recipe este plugin renderiza: um conjunto de arquivos com fonte, uma carga de trabalho sintetizada e um nó autônomo só de artefatos. Cada campo é uma declaração independente. |
boundaryAssembly | string (enum) | não | Como o plugin combina a saída de renderização por nó de um grupo de despacho: none escreve a saída de cada nó diretamente no caminho de despacho; merge funde os fragmentos por nó em um único documento; nest coloca a saída de cada nó em sua própria posição dentro de uma estrutura guarda-chuva. Se ausente, não traz nenhuma declaração de montagem. Valores permitidos: "none", "merge", "nest" |
artifactDelimiters | object | não | O par de delimitadores de template Go que o plugin aplica aos arquivos de artefatos importados. Se ausente, vale o par padrão {{/}}; um plugin cuja sintaxe de destino colide com esse par declara aqui um par alternativo. |
assemblyNameAnnotation | object | não | A anotação de fronteira cujo valor resolvido nomeia o artefato que o plugin monta a partir de um grupo de despacho. Um plugin que reúne as fronteiras contribuintes de um grupo em uma única montagem nomeada declara a chave de anotação que lê e se cada fronteira contribuinte deve concordar quanto ao valor resolvido dessa anotação. Se ausente, o plugin nomeia sua montagem apenas a partir do caminho de despacho. |
reusableInstance | booleano | não | Se uma única instância carregada do plugin pode atender a cada travessia de renderização, montagem e validação de um build, em vez de uma instância nova por travessia. Declarado true apenas quando o plugin não mantém estado entre travessias — uma função pura de sua entrada por travessia —, de modo que uma única instância produz uma saída idêntica byte a byte, seja reutilizada ou carregada de novo. Se ausente (false), uma instância nova é carregada por travessia, isolando por construção um plugin que carrega estado. |
crossBoundaryLinking | booleano | não | Se o plugin conecta uma aresta uses entre fronteiras — uma aresta uses cujas extremidades consumidora e consumida são montadas em grupos de despacho diferentes — emitindo uma conexão de referências cruzadas nativa do provedor por meio de um contrato de exportação pareado link_publish/link_resolve. Declarado true apenas quando o plugin exporta ambos; uma declaração que não corresponde ao par de exportações interrompe o carregamento. Se ausente (false), não declara nenhuma ligação entre fronteiras, então o host não encaminha nenhuma travessia de ligação para o plugin. |
omits | booleano | não | Se o provedor respeita as entradas de omissão — entradas que nomeiam unidades renderizadas a deixar de fora da saída de um nó: deixa de fora do que renderiza cada unidade a que uma entrada corresponde, e relata a quantas unidades cada entrada correspondeu. É o registro, no momento da publicação, da declaração omits que a autodeclaração do provedor faz, e um valor que difere dessa autodeclaração interrompe o carregamento. Se ausente (false), não declara tal suporte. |
boundaryArtifacts | booleano | não | Se o provedor aceita os arquivos com que uma Recipe contribui para a saída compartilhada da fronteira em que é renderizada, sob o spec.boundary.artifacts da Recipe: o compilador escreve cada um desses arquivos uma única vez, no diretório que contém a saída montada da fronteira, e o destino do provedor o trata como parte dessa saída. É o registro, no momento da publicação, da declaração boundary_artifacts que a autodeclaração do provedor faz, e um valor que difere dessa autodeclaração interrompe o carregamento. Se ausente (false), não declara tal suporte, e uma Recipe que declara o bloco para este provedor é recusada antes que qualquer coisa seja renderizada. |
nestSegment | string | não | O diretório sob o qual o destino deste provedor coloca o subdiretório próprio de cada contribuidor, para um provedor cujo boundaryAssembly é nest — charts para um chart guarda-chuva, modules para um módulo raiz. O compilador junta este diretório, o nome do contribuidor e o caminho próprio de cada arquivo. Lido apenas para um provedor que aninha. Se ausente, o subdiretório de cada contribuidor é colocado diretamente no diretório próprio da fronteira. O valor nomeia um único diretório e nunca um caminho. |
sourceIgnore | object | não | Os arquivos que o ecossistema deste provedor nunca entrega ao lado de uma fonte que renderiza, como regras ignore em sintaxe gitignore — o registro, no momento da publicação, das regras source_ignore que a sua autodeclaração declara. Quando um autor fixa uma Recipe ou uma FeatureRecipe cuja capacidade este provedor atende para ele, essas regras são compostas com o .aggregaignore próprio do autor e registradas no entity.lock ao lado da entidade, junto com o nome deste plugin, e cada publicação, comparação e renderização posterior da fonte local da entidade aplica as regras registradas. Quando presente, deve ser igual ao que a autodeclaração declara, e o carregamento recusa um plugin cuja autodeclaração difere; se ausente, não declara nada e não é comparado. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.inputKinds
Quais dos três tipos de entrada de Recipe este plugin renderiza: um conjunto de arquivos com fonte, uma carga de trabalho sintetizada e um nó autônomo só de artefatos. Cada campo é uma declaração independente.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
sourced | booleano | não | Renderiza um conjunto de arquivos com fonte (um chart, um módulo, um arquivo compose). |
synthesized | booleano | não | Renderiza uma carga de trabalho sintetizada em artefatos nativos do provedor. |
artifactsStandalone | booleano | não | Renderiza um nó autônomo só de artefatos — um que carrega documentos de artefatos importados e nenhuma fonte nem carga de trabalho. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.artifactDelimiters
O par de delimitadores de template Go que o plugin aplica aos arquivos de artefatos importados. Se ausente, vale o par padrão {{/}}; um plugin cuja sintaxe de destino colide com esse par declara aqui um par alternativo.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
left | string | sim | O delimitador de abertura. |
right | string | sim | O delimitador de fechamento. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.assemblyNameAnnotation
A anotação de fronteira cujo valor resolvido nomeia o artefato que o plugin monta a partir de um grupo de despacho. Um plugin que reúne as fronteiras contribuintes de um grupo em uma única montagem nomeada declara a chave de anotação que lê e se cada fronteira contribuinte deve concordar quanto ao valor resolvido dessa anotação. Se ausente, o plugin nomeia sua montagem apenas a partir do caminho de despacho.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
annotation | string | sim | A chave da anotação de fronteira da qual o plugin lê o nome do artefato montado. |
requireUnique | booleano | não | Se cada fronteira que contribui para um mesmo grupo de despacho deve concordar quanto ao valor resolvido da anotação. Quando true, um grupo cujas fronteiras contribuintes resolvem a anotação para valores diferentes interrompe o build; quando false, o plugin aceita o primeiro valor resolvido. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.sourceIgnore
Os arquivos que o ecossistema deste provedor nunca entrega ao lado de uma fonte que renderiza, como regras ignore em sintaxe gitignore — o registro, no momento da publicação, das regras source_ignore que a sua autodeclaração declara. Quando um autor fixa uma Recipe ou uma FeatureRecipe cuja capacidade este provedor atende para ele, essas regras são compostas com o .aggregaignore próprio do autor e registradas no entity.lock ao lado da entidade, junto com o nome deste plugin, e cada publicação, comparação e renderização posterior da fonte local da entidade aplica as regras registradas. Quando presente, deve ser igual ao que a autodeclaração declara, e o carregamento recusa um plugin cuja autodeclaração difere; se ausente, não declara nada e não é comparado.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
patterns | string[] | não | Os padrões ignore próprios do ecossistema, cada um com escopo na raiz do diretório da fonte local, na ordem em que se aplicam. |
files | string[] | não | Os nomes dos arquivos ignore que o ecossistema respeita dentro de uma fonte — .helmignore para um chart. As linhas de cada um desses arquivos são padrões adicionais, com escopo no diretório que o contém. |
Não são permitidas propriedades adicionais.
plugin.spec.pipelineStep
O bloco pipeline-step para um plugin pluginType: pipeline-step: as capacidades do provedor com as quais a sua etapa é compatível. Presente apenas em plugins pipeline-step; ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registrada a partir da autodeclaração do .wasm do plugin por aggrega plugin gen-catalog, de modo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deve oferecer, e não pode adicionar nenhuma que a autodeclaração não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que a autodeclaração não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e aponta cada capacidade que a autodeclaração nomeia e que a lista deixa de fora. As capacidades de provedor com as quais a etapa de pipeline deste plugin é compatível — os nomes de capacidades de provedor, como helm ou compose, cuja saída renderizada a etapa sabe transformar. Uma etapa é escrita para a forma de saída de um único provedor por vez, então a lista é uma declaração explícita de compatibilidade testada, e não uma aspiração. As entradas preservam a ordem do autor. É o registro legível pelo catálogo dessa declaração; o build lê a mesma declaração a partir do plugin quando uma etapa toca um escopo e é interrompido quando o provedor que renderiza os documentos desse escopo não está entre elas. Uma lista vazia ou ausente não declara nenhuma compatibilidade, então nenhum escopo admite a etapa. |
Não são permitidas propriedades adicionais.
plugin.spec.parser
O bloco parser para um plugin pluginType: parser: os formatos de origem que ele transforma em uma árvore estruturada canônica. Presente apenas em plugins parser; ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registrada a partir da autodeclaração do .wasm do plugin por aggrega plugin gen-catalog, de modo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deve oferecer, e não pode adicionar nenhuma que a autodeclaração não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que a autodeclaração não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e aponta cada capacidade que a autodeclaração nomeia e que a lista deixa de fora. Os formatos de fonte que este parser transforma em uma árvore estruturada canônica, cada um escrito como parse:<format> — por exemplo parse:yaml. O prefixo faz parte da entrada, então um plugin que anuncia vários formatos lista uma entrada por formato. As entradas preservam a ordem do autor. Um formato solicitado é resolvido para o parser cuja lista contém a entrada correspondente; um formato que nenhum parser anuncia interrompe o build, e um formato anunciado por mais de um plugin parser interrompe como ambíguo. Uma lista vazia ou ausente não declara nenhum formato, então o plugin não analisa nada. |
Não são permitidas propriedades adicionais.
plugin.spec.importer
O bloco importer para um plugin pluginType: importer: os formatos de origem externos que ele transforma em rascunhos de arquivos de autoria do Aggrega, e as assinaturas pelas quais se reconhece uma fonte nesses formatos. Presente apenas em plugins importer; ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registrada a partir da autodeclaração do .wasm do plugin por aggrega plugin gen-catalog, de modo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deve oferecer, e não pode adicionar nenhuma que a autodeclaração não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que a autodeclaração não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e aponta cada capacidade que a autodeclaração nomeia e que a lista deixa de fora. Os formatos de fonte externos que este importador transforma em arquivos de autoria do Aggrega em rascunho, cada um escrito como import:<format> — por exemplo import:terraform. O prefixo faz parte da entrada, então um plugin que anuncia vários formatos lista uma entrada por formato. As entradas preservam a ordem do autor. Um formato de importação solicitado é resolvido para o importador cuja lista contém a entrada correspondente; um formato que nenhum importador anuncia interrompe a importação, e um formato anunciado por mais de um plugin importador interrompe como ambíguo, a menos que uma entrada plugins.importer na configuração do workspace vincule um deles, que então é executado. Uma lista vazia ou ausente não declara nenhum formato, então o plugin não importa nada. |
detect | object[] | não | Gerenciado pela máquina, não deve ser escrito à mão: derivado da autodeclaração do .wasm do plugin quando a entidade é gerada a partir dele, e registrado aqui na ordem em que a autodeclaração as declara. As assinaturas pelas quais uma fonte dos formatos deste importador é reconhecida quando uma importação não nomeia nenhum formato. aggrega import lê as assinaturas de cada importador que o catálogo do workspace contém, todas as versões incluídas, e dos importadores do núcleo do compilador, compara-as com a fonte sem saber o que é qualquer formato, e lê a fonte como o formato do único importador cuja assinatura corresponde; uma fonte à qual nenhuma assinatura corresponde é recusada com um pedido do formato, e uma fonte à qual correspondem assinaturas de mais de um formato é recusada com a nomeação desses formatos. Um importador que reconhece uma fonte a reconhece como cada formato que anuncia, então, para um importador que anuncia mais de um formato, toda correspondência é recusada como ambígua. Quando presente, a lista deve ser igual ao que a autodeclaração do plugin declara, entrada por entrada e na mesma ordem, e o carregamento e a publicação recusam um plugin cuja autodeclaração difere, nomeando este campo. Se ausente, não declara nada e não é comparada, e os formatos do importador então só são alcançados quando nomeados. |
Não são permitidas propriedades adicionais.
plugin.spec.importer.detect[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
syntax | string | sim | O formato sintático como o qual a fonte é analisada — json ou yaml, por exemplo —, que é o formato que um plugin parser anuncia como parse:<syntax>. A fonte é analisada pelo parser que o catálogo do workspace oferece para essa sintaxe ou, para uma sintaxe para a qual o catálogo não oferece nenhum, por aquele que o compilador traz consigo, no máximo uma vez, qualquer que seja o número de assinaturas que nomeiam a sintaxe, e uma fonte que não pode ser analisada nela não corresponde a nenhuma assinatura que a nomeie. Uma sintaxe para a qual nenhum dos dois oferece um parser interrompe o reconhecimento, nomeando a ausência desse parser. Pelo menos 1 caractere. |
files | string[] | não | Os padrões de nome de arquivo aos quais a assinatura se aplica, comparados com o final do nome da fonte com os seus separadores lidos como barras: um padrão de um único segmento com o nome próprio do arquivo, e um padrão de vários segmentos separados por barras com o mesmo número de segmentos finais do seu caminho, de modo que .vscode/mcp.json corresponde a um arquivo chamado mcp.json em um diretório chamado .vscode. Dentro de um segmento, * corresponde a qualquer sequência de caracteres, ? a um caractere e [...] a um caractere de uma classe. A assinatura se aplica quando qualquer padrão corresponde. Se ausente ou vazio, a assinatura se aplica a uma fonte que é um único arquivo, seja qual for o seu nome, e a nenhum arquivo de um diretório. Os padrões das assinaturas de um importador também são o que decide quais arquivos de um diretório aggrega import lhe passa. |
match | object[] | não | Os predicados que a árvore analisada deve satisfazer, todos eles, na ordem declarada. Se ausente ou vazio, não exige nada da árvore além de ser analisável na sintaxe. |
Não são permitidas propriedades adicionais.
plugin.spec.importer.detect[].match[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
path | string | sim | Onde na árvore o predicado procura, escrito como chaves unidas por pontos a partir do topo da árvore: data.nodes nomeia o membro nodes do objeto data de nível superior. Um segmento escrito como número inteiro, 0 ou maior, seleciona essa posição de um array contando a partir de zero, de modo que nodes.0.type nomeia o tipo do primeiro nó; qualquer outro segmento seleciona um membro de um objeto. Pelo menos 1 caractere. |
is | string (enum) | sim | O que o caminho deve alcançar: present é satisfeito quando alcança um valor de qualquer tipo, null incluído; absent é satisfeito quando não alcança nada; object, array, string, number e boolean são satisfeitos, cada um, quando alcança um valor desse tipo. Valores permitidos: "present", "absent", "object", "array", "string", "number", "boolean" |
equals | string | não | Uma string à qual o valor alcançado pelo caminho deve ser exatamente igual; um valor que não é uma string nunca é igual a ela. No máximo um entre equals e prefix é declarado em um predicado. Pelo menos 1 caractere. |
prefix | string | não | Uma string com a qual o valor alcançado pelo caminho deve começar; um valor que não é uma string nunca começa com ela. No máximo um entre equals e prefix é declarado em um predicado. Pelo menos 1 caractere. |
Não são permitidas propriedades adicionais.