Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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

PropriedadeTipoObrigatóriaDescrição
apiVersionconst “aggrega.ai/v1beta1”simConstante: "aggrega.ai/v1beta1"
kindconst “Plugin”simConstante: "Plugin"
metadataobjectsim
specobjectsimA 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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 caractere.
versionstringsimVersionamento 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-]+)*))?$.
pluginTypestring (enum)simO 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"
descriptionstringnãoO 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.
maintainersobject[]nãoLista de mantenedores responsáveis por esta entidade.
licensestringnãoIdentificador 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.
repositorystringnãoA URL do repositório Git onde ficam os arquivos-fonte.
homestringnãoA URL da página inicial, do wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do usuário.

Não são permitidas propriedades adicionais.

plugin.metadata.maintainers[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnã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.

PropriedadeTipoObrigatóriaDescrição
abiVersionstring (enum)simA 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"
signatureobjectnãoUm 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.
runtimeobjectnãoRestriçõ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.
exportsobject[]nãoAs 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.
commandsobject[]nãoGerenciado 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.
providerobjectnãoO 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.
pipelineStepobjectnãoO 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.
parserobjectnãoO 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.
importerobjectnãoO 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.

PropriedadeTipoObrigatóriaDescrição
typeconst “sigstore-cosign”simO esquema de assinatura. sigstore-cosign é o esquema suportado. Constante: "sigstore-cosign"
signatureRefstringnãoA 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.
publicKeyRefstringnãoUm 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.

PropriedadeTipoObrigatóriaDescrição
maxMemoryPagesintegernãoLimita 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.
timeoutMsintegernãoLimita 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.
hostFunctionsstring[]nãoGerenciado 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.
configKVmapa de stringnãoConfiguraçã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[]
PropriedadeTipoObrigatóriaDescrição
namestringsimO nome ABI da exportação — o nome para o qual o host despacha (por exemplo, render_node, lint_naming, step). Pelo menos 1 caractere.
operatesstring (enum)nãoA 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"
scopestring (enum)nãoA 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"
selectorstringnãoUma 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[]
PropriedadeTipoObrigatóriaDescrição
namestringsimO 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.
descriptionstringnãoO 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.
flagsobject[]nãoOs flags do comando, na ordem declarada. Cada entrada contribui com um flag que o host registra no comando para que aggrega help o exiba como o flag de um comando integrado. Um comando sem flags deixa a lista vazia. Dentro de um comando, cada nome de flag e cada forma abreviada aparece uma vez, e nenhum reutiliza um flag que todo comando aggrega já tem — --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[]
PropriedadeTipoObrigatóriaDescrição
namestringsimO 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.
shorthandstringnãoO 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]$.
descriptionstringnãoO 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.
typestring (enum)nãoO 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"
defaultstringnãoO 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.

PropriedadeTipoObrigatóriaDescrição
capabilitiesstring[]nãoRegistrada 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.
workloadSchemastringnãoJSON 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ê.
wellKnownAnnotationsobject[]nãoA 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.
readsNoWellKnownAnnotationsconst truenãoDeclara 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
contractobjectnãoO 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[]
PropriedadeTipoObrigatóriaDescrição
keystringsimA 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/.+.
purposestringsimO que a anotação controla — o comportamento de renderização que ela influencia quando presente.
defaultBehaviorstringnãoO comportamento que o provedor aplica quando esta anotação está ausente.
scopestring (enum)[]nãoOnde 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.

PropriedadeTipoObrigatóriaDescrição
inputKindsobjectnãoQuais 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.
boundaryAssemblystring (enum)nãoComo 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"
artifactDelimitersobjectnãoO 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.
assemblyNameAnnotationobjectnãoA 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.
reusableInstancebooleanonãoSe 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.
crossBoundaryLinkingbooleanonãoSe 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.
omitsbooleanonãoSe 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.
boundaryArtifactsbooleanonãoSe 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.
nestSegmentstringnãoO 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.
sourceIgnoreobjectnãoOs 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.

PropriedadeTipoObrigatóriaDescrição
sourcedbooleanonãoRenderiza um conjunto de arquivos com fonte (um chart, um módulo, um arquivo compose).
synthesizedbooleanonãoRenderiza uma carga de trabalho sintetizada em artefatos nativos do provedor.
artifactsStandalonebooleanonãoRenderiza 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.

PropriedadeTipoObrigatóriaDescrição
leftstringsimO delimitador de abertura.
rightstringsimO 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.

PropriedadeTipoObrigatóriaDescrição
annotationstringsimA chave da anotação de fronteira da qual o plugin lê o nome do artefato montado.
requireUniquebooleanonãoSe 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.

PropriedadeTipoObrigatóriaDescrição
patternsstring[]nãoOs 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.
filesstring[]nãoOs 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.

PropriedadeTipoObrigatóriaDescrição
capabilitiesstring[]nãoRegistrada 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.

PropriedadeTipoObrigatóriaDescrição
capabilitiesstring[]nãoRegistrada 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.

PropriedadeTipoObrigatóriaDescrição
capabilitiesstring[]nãoRegistrada 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.
detectobject[]nãoGerenciado 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[]
PropriedadeTipoObrigatóriaDescrição
syntaxstringsimO 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.
filesstring[]nãoOs 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.
matchobject[]nãoOs 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[]
PropriedadeTipoObrigatóriaDescrição
pathstringsimOnde 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.
isstring (enum)simO 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"
equalsstringnãoUma 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.
prefixstringnãoUma 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.