Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Esquema del núcleo de Aggrega (Plugin)

Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.

ID del esquema: https://aggrega.ai/schemas/plugin-v1beta1.schema.json

Un plugin Wasm: un módulo WebAssembly publicado en un registro OCI e identificado por su metadata.pluginType — el socket que implementa — más su metadata.name simple, que declara la versión de ABI a la que se dirige, un puntero de firma opcional y un bloque runtime opcional. La entidad y su .wasm se publican como un único manifiesto OCI etiquetado con metadata.version — el YAML de la entidad como blob de configuración del manifiesto, el .wasm como capa inline, firmados una sola vez. La identidad es la coordenada metadata.pluginType/metadata.name más la metadata.version de la entidad; la ubicación del .wasm se deriva de esa coordenada más el registro configurado, y el digest del contenido resuelto reside en el archivo de bloqueo, no en la entidad. El archivo de bloqueo registra el digest, y la política de confianza de cada registro verifica la firma del artefacto en el pull. El compilador no interpreta el comportamiento del plugin — enruta la referencia; el runtime de WebAssembly ejecuta los bytes.

Consulta la referencia de autoría del Plugin para obtener orientación en prosa sobre cómo escribir entidades Plugin; esta página documenta el esquema estructural que describe esa referencia.

Tipo de nivel superior: object

Propiedades

PropiedadTipoObligatoriaDescripción
apiVersionconst “aggrega.ai/v1beta1”síConstante: "aggrega.ai/v1beta1"
kindconst “Plugin”síConstante: "Plugin"
metadataobjectsí
specobjectsíLa versión de ABI a la que se dirige el plugin, un puntero de firma opcional y un bloque runtime opcional. La ubicación del .wasm del plugin se deriva de la identidad del plugin — su metadata.pluginType (el socket) más su metadata.name simple — y del registro configurado; no se incluye en la spec.

No se permiten propiedades adicionales.

plugin.metadata

PropiedadTipoObligatoriaDescripción
namestringsíAl menos 1 carácter de longitud.
versionstringsíVersionado semántico estricto de la entidad Plugin (p. ej., 1.0.0). Patrón: ^(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)síEl tipo de socket que implementa este plugin. Un plugin implementa exactamente un tipo de socket, tomado de la taxonomía de tipos de plugin que reconoce el runtime: provider (renderiza nodos de la IR en artefactos nativos del proveedor), linter (inspecciona el contenido escrito por los autores y emite diagnósticos), pipeline-step (un paso del pipeline: de una FeatureRecipe o de una Recipe que aplica parches al conjunto de documentos renderizados), governance (atiende los roles de gobernanza del pipeline de compilación — transformar las etiquetas de los nodos durante la construcción de la topología, o emitir un veredicto de aceptación/rechazo sobre el grafo de la IR durante el análisis estático o sobre los artefactos renderizados durante el renderizado; es el rol al que está vinculado, no su tipo, lo que fija qué puede emitir), cli (aporta un subcomando de runtime aggrega <cmd> que un operador invoca en la línea de comandos — un socket de runtime, distinto de los sockets de renderizado y de pipeline en tiempo de compilación), parser (convierte un texto fuente externo en un árbol estructurado canónico para que un consumidor lea el árbol sin tener que incluir su propio parser del lenguaje, anunciando los formatos que maneja como capacidades parse:<format>), importer (convierte una fuente externa de infraestructura o de definición de agentes en borradores de archivos de autoría de Aggrega, anunciando los formatos que maneja como capacidades import:<format>). Valores permitidos: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer"
descriptionstringnoQué es esta entidad y para qué sirve, escrito para quien está decidiendo si usarla. Empieza con una frase que nombre la cosa y luego añade lo que un lector necesita para elegirla y usarla correctamente — qué espera de la compilación que la ejecuta, y cualquier cosa sorprendente sobre su comportamiento. Un párrafo corto es la extensión habitual.
maintainersobject[]noLista de mantenedores responsables de esta entidad.
licensestringnoIdentificador SPDX de la licencia del software que describe esta entidad, como MIT o AGPL-3.0. Registra las condiciones de ese software, no las de este archivo.
repositorystringnoLa URL del repositorio Git donde se encuentran los archivos fuente.
homestringnoLa URL de la página de inicio, la wiki o la documentación de esta entidad.
keywordsstring[]noUna lista de palabras clave descriptivas para facilitar el descubrimiento en la interfaz de usuario.

No se permiten propiedades adicionales.

plugin.metadata.maintainers[]
PropiedadTipoObligatoriaDescripción
namestringsí
emailstringno
urlstringno

No se permiten propiedades adicionales.

plugin.spec

La versión de ABI a la que se dirige el plugin, un puntero de firma opcional y un bloque runtime opcional. La ubicación del .wasm del plugin se deriva de la identidad del plugin — su metadata.pluginType (el socket) más su metadata.name simple — y del registro configurado; no se incluye en la spec.

PropiedadTipoObligatoriaDescripción
abiVersionstring (enum)síLa versión de ABI host/guest a la que se dirige el plugin. v1beta1 es el único valor aceptado; un Plugin que declara una versión de ABI que este compilador ya no habla se rechaza, indicando la versión con la que recompilar el plugin. Valores permitidos: "v1beta1"
signatureobjectnoUn puntero descriptivo opcional a la firma adjunta del plugin. Este bloque es solo documentación — registra para los lectores del catálogo dónde está la firma y cómo se produjo; por sí mismo no filtra ni admite el plugin. La comprobación que lo hace cumplir es la política de confianza de cada registro aplicada en el pull: la firma se descarga como referrer OCI, se verifica frente a las identidades de confianza o la clave fijada del registro y se registra como un hecho verificado en el archivo de bloqueo. Un registro que exige firmas detiene el pull cuando falta una firma requerida, no es de confianza o no es válida.
runtimeobjectnoRestricciones de ejecución opcionales que el host aplica al cargar y ejecutar el plugin. El acceso saliente a la red no es un campo de autoría: un plugin nunca accede a la red en tiempo de compilación (el límite ahead-of-time), así que aquí no hay ningún campo de lista de hosts permitidos que escribir.
exportsobject[]noLas exportaciones que ofrece este plugin, cada una con su capacidad declarada. Una exportación es un punto de entrada con nombre al que el host despacha las llamadas (por ejemplo render_node, lint_naming, step); el bloque de capacidad por exportación es la declaración escrita por el autor de lo que hace esa exportación, que el host contrasta con el autoinforme del plugin al publicar y al cargar. Las entradas conservan el orden del autor. Si está ausente, no se declara ninguna superficie de exportación escrita por el autor.
commandsobject[]noGestionado por la máquina, no lo escribas a mano: lo registra aggrega plugin sync (o aggrega plugin gen-catalog) a partir del autoinforme del plugin. Los verbos de nivel superior aggrega <command> que aporta un plugin de CLI se leen del autoinforme del plugin y se registran aquí en el orden en que el autoinforme los declara, de modo que la superficie de comandos con la que se instala un plugin de CLI puede leerse desde la entidad sin cargar el plugin. Un plugin que no es de CLI no aporta comandos y registra una lista vacía. El host instala exactamente este conjunto; un conjunto registrado que difiere del autoinforme del plugin provoca una detención al cargar, y la publicación rechaza un conjunto no sincronizado con el binario e indica al autor que vuelva a registrarlo.
providerobjectnoEl bloque del socket de proveedor para un plugin pluginType: provider: las capacidades que atiende, cómo traduce el tipo Workload de aggrega.ai/v1beta1, qué anotaciones nativas de la plataforma lee y su contrato de comportamiento de renderizado. Presente solo en los plugins de renderizado de proveedor; ausente en cualquier otro tipo de plugin.
pipelineStepobjectnoEl bloque pipeline-step para un plugin pluginType: pipeline-step: las capacidades del proveedor con las que es compatible su paso. Presente solo en los plugins pipeline-step; ausente en cualquier otro tipo de plugin.
parserobjectnoEl bloque parser para un plugin pluginType: parser: los formatos de origen que convierte en un árbol estructurado canónico. Presente solo en los plugins parser; ausente en cualquier otro tipo de plugin.
importerobjectnoEl bloque importer para un plugin pluginType: importer: los formatos de origen externos que convierte en borradores de archivos de autoría de Aggrega, y las firmas por las que se reconoce una fuente de esos formatos. Presente solo en los plugins importer; ausente en cualquier otro tipo de plugin.

No se permiten propiedades adicionales.

plugin.spec.signature

Un puntero descriptivo opcional a la firma adjunta del plugin. Este bloque es solo documentación — registra para los lectores del catálogo dónde está la firma y cómo se produjo; por sí mismo no filtra ni admite el plugin. La comprobación que lo hace cumplir es la política de confianza de cada registro aplicada en el pull: la firma se descarga como referrer OCI, se verifica frente a las identidades de confianza o la clave fijada del registro y se registra como un hecho verificado en el archivo de bloqueo. Un registro que exige firmas detiene el pull cuando falta una firma requerida, no es de confianza o no es válida.

PropiedadTipoObligatoriaDescripción
typeconst “sigstore-cosign”síEl esquema de firma. sigstore-cosign es el esquema admitido. Constante: "sigstore-cosign"
signatureRefstringnoLa referencia de referrer OCI del bundle de firma adjunto, para documentación y descubrimiento. Ausente cuando la firma se descubre enumerando los referrers en el pull en lugar de fijarse aquí.
publicKeyRefstringnoUn puntero a la clave pública con la que se produjo la firma, para una firma con clave. Su ausencia indica una firma sin clave (basada en identidad OIDC), verificada frente a las identidades de confianza del registro.

No se permiten propiedades adicionales.

plugin.spec.runtime

Restricciones de ejecución opcionales que el host aplica al cargar y ejecutar el plugin. El acceso saliente a la red no es un campo de autoría: un plugin nunca accede a la red en tiempo de compilación (el límite ahead-of-time), así que aquí no hay ningún campo de lista de hosts permitidos que escribir.

PropiedadTipoObligatoriaDescripción
maxMemoryPagesintegernoLimita la memoria lineal del plugin en páginas Wasm (64 KiB por página). Cero o la ausencia aplican el tope predeterminado de la plataforma, de modo que una carga nunca es ilimitada; una vinculación que necesita más aumenta este valor. Mínimo: 0.
timeoutMsintegernoLimita cuánto tiempo puede ejecutarse el código propio del plugin durante una llamada, en milisegundos, sin contar el tiempo pasado dentro de las funciones del host a las que llama. En Linux la medida es el tiempo de procesador, por lo que el tiempo de espera de un procesador en una máquina ocupada no cuenta; en otros sistemas es el tiempo transcurrido. La primera llamada a un plugin recién cargado también cuenta el arranque propio del plugin. Cero o la ausencia aplican el tope predeterminado de la plataforma, de modo que una llamada nunca es imposible de cancelar; una vinculación que se ejecuta durante más tiempo aumenta este valor. Mínimo: 0.
hostFunctionsstring[]noGestionado por la máquina, no lo escribas a mano: las funciones del host que importa el plugin, leídas de la sección de importaciones del .wasm por aggrega plugin sync (o aggrega plugin gen-catalog) y registradas aquí en forma canónica (ordenada, sin duplicados). La publicación las vuelve a derivar del binario y rechaza una entidad cuyo registro difiere; el pull las vuelve a derivar y las verifica de nuevo. El host registra exactamente este conjunto derivado y valida cada entrada frente a la lista de permitidos curada.
configKVmapa de stringnoConfiguración específica del Plugin que el runtime entrega al plugin al iniciarse, como pares clave/valor de cadena a cadena. Las entradas conservan el orden del autor para que el registro emitido sea idéntico byte a byte entre ejecuciones. Su ausencia deja en vigor la configuración vacía predeterminada del runtime.

No se permiten propiedades adicionales.

plugin.spec.exports[]
PropiedadTipoObligatoriaDescripción
namestringsíEl nombre ABI de la exportación — el nombre al que el host despacha (por ejemplo render_node, lint_naming, step). Al menos 1 carácter.
operatesstring (enum)noLa operación de pipeline que realiza esta exportación: patch (modificar un documento renderizado existente) o emit (añadir un documento nuevo). Si está ausente, no declara ninguna operación. Valores permitidos: "patch", "emit"
scopestring (enum)noLa raíz de documentos sobre la que opera esta exportación: own (los documentos renderizados propios del nodo) o host (los documentos del componente al que está vinculada una FeatureRecipe con ámbito de componente). Si está ausente, no declara ningún ámbito. Valores permitidos: "own", "host"
selectorstringnoUna descripción libre y legible por personas de aquello sobre lo que actúa la exportación (por ejemplo workloads carrying a pod template). Documentación para los lectores del catálogo; el compilador no la interpreta.

No se permiten propiedades adicionales.

plugin.spec.commands[]
PropiedadTipoObligatoriaDescripción
namestringsíEl verbo de comando que registra el host — el token aggrega <name> que invoca un operador, y el discriminador que el host entrega al plugin en la invocación para que un único plugin que respalda varios comandos enrute según el comando que se llamó. Al menos 1 carácter.
descriptionstringnoEl texto de ayuda breve de una línea del comando, que se muestra en el listado de comandos y en la salida de ayuda. Solo documentación; el host no actúa en función de él.
flagsobject[]noLos flags del comando, en el orden declarado. Cada entrada aporta un flag que el host registra en el comando para que aggrega help lo muestre como el flag de un comando integrado. Un comando sin flags deja la lista vacía. Dentro de un comando, cada nombre de flag y cada forma abreviada aparece una sola vez, y ninguno reutiliza un flag que ya tiene todo comando de aggrega — --help, -h y los flags globales; el host lo comprueba cuando añade los comandos del plugin, y un plugin cuyas declaraciones no superan la comprobación no se añade, con una advertencia.

No se permiten propiedades adicionales.

plugin.spec.commands[].flags[]
PropiedadTipoObligatoriaDescripción
namestringsíEl nombre largo del flag — el token —name que un operador pasa en la línea de comandos. Todo flag declarado debe indicarlo. Al menos 1 carácter.
shorthandstringnoEl alias corto opcional del flag — la forma -x que un operador puede pasar en lugar del nombre largo — como una sola letra o un solo dígito ASCII. Su ausencia significa que el flag no tiene alias corto. Patrón: ^[A-Za-z0-9]$.
descriptionstringnoEl texto de ayuda de una línea del flag, mostrado en la salida de ayuda del comando. Es documentación opcional; el host no lo valida ni actúa en función de él.
typestring (enum)noEl tipo de valor del flag — string, bool o int — y la clase de flag como la que la ayuda lo muestra. Si está ausente, se muestra como un flag de cadena. Valores permitidos: "string", "bool", "int"
defaultstringnoEl valor predeterminado del flag cuando el operador no lo pasa, expresado como cadena. Para un flag bool o int es un valor de ese tipo. Si falta, el flag no declara ningún valor predeterminado.

No se permiten propiedades adicionales.

plugin.spec.provider

El bloque del socket de proveedor para un plugin pluginType: provider: las capacidades que atiende, cómo traduce el tipo Workload de aggrega.ai/v1beta1, qué anotaciones nativas de la plataforma lee y su contrato de comportamiento de renderizado. Presente solo en los plugins de renderizado de proveedor; ausente en cualquier otro tipo de plugin.

PropiedadTipoObligatoriaDescripción
capabilitiesstring[]noSe registra a partir del autoinforme del .wasm del plugin mediante aggrega plugin gen-catalog, de modo que el plugin es la fuente de esta lista. Un autor puede acotarla antes de publicar, quitando una entrada que esta entidad no deba ofrecer, y no puede añadir ninguna que el autoinforme no nombre: la publicación, y aggrega validate al que se le da el .wasm del plugin con --plugin, rechazan una lista que nombre una capacidad que el autoinforme no nombra. La publicación envía la entidad tal como está escrita, sin reescribir nunca esta lista, y señala cada capacidad que nombra el autoinforme y que la lista deja fuera. Las capacidades que atiende este proveedor — nombres de capacidad como helm o compose — cuya forma de salida renderiza. Un proveedor es genérico entre artefactos que comparten la forma de salida de una capacidad, no entre todas las capacidades, por lo que la lista es una declaración explícita de compatibilidad probada y no una aspiración. Las entradas conservan el orden del autor. El destino de proveedor que solicita una Recipe se resuelve en el plugin de proveedor cuya lista contiene ese destino; un destino que aparece en la lista de más de un plugin de proveedor detiene la compilación por ambiguo, salvo que la selección plugins.providers de la configuración del espacio de trabajo indique qué plugin usar. Una lista vacía o ausente no declara ninguna capacidad, por lo que el plugin no atiende ningún destino.
workloadSchemastringnoJSON Schema 2020-12 que documenta cómo este proveedor traduce el tipo Workload de aggrega.ai/v1beta1 a manifiestos nativos del proveedor. Cuando está presente, el proveedor admite Recipes que declaran un bloque workload: (modo sintetizado) — el proveedor traduce el Workload a manifiestos nativos del proveedor, guiado por este esquema como documentación/contrato. Si una Recipe con workload: es compatible lo determina la capacidad de síntesis del proveedor vinculado, no la presencia de este campo: una Recipe en modo sintetizado vinculada a un proveedor que no puede sintetizar se detiene de forma bien visible en tiempo de renderizado. El catálogo de la biblioteca estándar declara workloadSchema en los proveedores que sintetizan como contrato documentado, mantenido en sincronía con esa capacidad. El campo es el contrato documentado: el cuerpo se compila a JSON Schema 2020-12 al cargar para comprobar que está bien formado, y nada más lo lee.
wellKnownAnnotationsobject[]noLa declaración de compatibilidad del proveedor: las claves de anotación bien conocidas nativas de la plataforma (el namespace aggrega.ai/) que lee este proveedor, cada una con el ámbito en el que se lee y el comportamiento que se aplica cuando está ausente. Declara una clave solo donde el proveedor la lee — la matriz de compatibilidad publicada se renderiza a partir de estas declaraciones, por lo que una clave listada aquí es una clave que un autor puede esperar que cambie la salida renderizada en el ámbito que nombra. El compilador lee la declaración de dos maneras: un scope que nombra un tipo de entrada que el propio contract.inputKinds del proveedor no reclama contradice una declaración adyacente en la misma entidad, y la compilación se detiene nombrando la clave y la contradicción; y una compilación advierte sobre una anotación aggrega.ai/ que llega a un renderizado a través de este proveedor cuando ninguna entrada la cubre en ninguno de los tipos de entrada que declara ese renderizado. Es distinta de la regla que rige el enlace de un valor bajo el prefijo reservado aggrega.ai/. Si está ausente, no declara ninguna compatibilidad, y no se emite ninguna advertencia de este tipo para este proveedor; un proveedor que no lee ninguna de estas claves declara readsNoWellKnownAnnotations en lugar de esta lista. Las entradas son una lista ordenada y conservan el orden del autor.
readsNoWellKnownAnnotationsconst truenoDeclara que este proveedor no lee ninguna de las claves de anotación nativas de la plataforma del namespace aggrega.ai/, las claves que wellKnownAnnotations listaría en otro caso: una declaración de compatibilidad que no cubre ninguna clave, lo cual es una afirmación, mientras que omitir tanto este campo como wellKnownAnnotations es silencio. Una compilación advierte entonces sobre cada anotación aggrega.ai/ que llega a un renderizado a través de este proveedor, nombrando la clave, el proveedor y los tipos de entrada que declara ese renderizado; el valor pasa igualmente sin cambios y la compilación no se detiene. Solo puede escribirse true, de modo que omitir el campo sigue siendo la única manera de no decir nada. No puede escribirse junto con wellKnownAnnotations: un proveedor que lee algunas de las claves las lista allí en su lugar. Constante: true
contractobjectnoEl contrato de comportamiento de renderizado autodeclarado del proveedor: los tipos de entrada que renderiza, cómo ensambla la salida por nodo de un grupo de despacho y bajo qué directorios queda esa salida, el par de delimitadores de plantilla que aplica a los archivos de artefactos importados, si una única instancia cargada puede atender cada cruce, si cablea aristas entre límites, si respeta las entradas de exclusión, si acepta los archivos que una Recipe aporta a la salida compartida de su límite, y qué archivos su ecosistema nunca distribuye junto a una fuente. Es el registro, en el momento de la publicación, del autoinforme del plugin de proveedor, que el host contrasta con ese mismo autoinforme al publicar y al cargar. Si está ausente, no declara ningún contrato de comportamiento de renderizado, y la comprobación cruzada compara solo las declaraciones por exportación.

No se permiten propiedades adicionales.

plugin.spec.provider.wellKnownAnnotations[]
PropiedadTipoObligatoriaDescripción
keystringsíLa clave de anotación bien conocida nativa de la plataforma que lee el proveedor (p. ej., aggrega.ai/namespace). Se sitúa bajo el namespace de anotaciones aggrega.ai/ reservado a la plataforma — las directivas de plataforma que lee el proveedor. Patrón: ^aggrega\.ai/.+.
purposestringsíLo que controla la anotación — el comportamiento de renderizado en el que influye cuando está presente.
defaultBehaviorstringnoEl comportamiento que aplica el proveedor cuando esta anotación está ausente.
scopestring (enum)[]noDónde lee la clave este proveedor. Los tres primeros valores son los tipos de entrada de la Recipe y nombran la ruta de renderizado en la que se lee la clave — sourced un conjunto de archivos vendorizados, synthesized un Workload que el proveedor materializa, artifactsStandalone un nodo cuya salida completa son documentos de artefactos importados. Cada uno de ellos debe ser un tipo de entrada que reclame el contract.inputKinds de este proveedor; nombrar uno que no reclama detiene la compilación. boundary es para una clave que se resuelve una vez por límite en lugar de por nodo — el nombre de un artefacto ensamblado, o el contexto de ubicación a partir del cual se forma una referencia entre límites —, donde el tipo de entrada no es un eje significativo, por lo que no se compara con contract.inputKinds. Una clave que se lee en más de una ruta las lista todas. Si está ausente, no hace ninguna declaración por ruta: no se comprueba nada, y la clave solo indica que el proveedor la lee en algún lugar. Al menos 1 entrada. Ninguna entrada puede aparecer dos veces. Valores permitidos para cada entrada: "sourced", "synthesized", "artifactsStandalone", "boundary".

No se permiten propiedades adicionales.

plugin.spec.provider.contract

El contrato de comportamiento de renderizado autodeclarado del proveedor: los tipos de entrada que renderiza, cómo ensambla la salida por nodo de un grupo de despacho y bajo qué directorios queda esa salida, el par de delimitadores de plantilla que aplica a los archivos de artefactos importados, si una única instancia cargada puede atender cada cruce, si cablea aristas entre límites, si respeta las entradas de exclusión, si acepta los archivos que una Recipe aporta a la salida compartida de su límite, y qué archivos su ecosistema nunca distribuye junto a una fuente. Es el registro, en el momento de la publicación, del autoinforme del plugin de proveedor, que el host contrasta con ese mismo autoinforme al publicar y al cargar. Si está ausente, no declara ningún contrato de comportamiento de renderizado, y la comprobación cruzada compara solo las declaraciones por exportación.

PropiedadTipoObligatoriaDescripción
inputKindsobjectnoCuáles de los tres tipos de entrada de Recipe renderiza este plugin: un conjunto de archivos con fuente, una carga de trabajo sintetizada y un nodo autónomo solo de artefactos. Cada campo es una declaración independiente.
boundaryAssemblystring (enum)noCómo combina el plugin la salida de renderizado por nodo de un grupo de despacho: none escribe la salida de cada nodo directamente en la ruta de despacho; merge fusiona los fragmentos por nodo en un único documento; nest coloca la salida de cada nodo en su propia posición dentro de una estructura paraguas. Si está ausente, no lleva ninguna declaración de ensamblado. Valores permitidos: "none", "merge", "nest"
artifactDelimitersobjectnoEl par de delimitadores de plantillas Go que el plugin aplica a los archivos de artefactos importados. Si está ausente, se usa el par predeterminado {{/}}; un plugin cuya sintaxis de destino colisiona con ese par declara aquí un par alternativo.
assemblyNameAnnotationobjectnoLa anotación de límite cuyo valor resuelto nombra el artefacto que el plugin ensambla a partir de un grupo de despacho. Un plugin que reúne los límites que contribuyen a un grupo en un único ensamblado con nombre declara la clave de anotación que lee y si cada límite que contribuye debe coincidir en el valor resuelto de esa anotación. Si está ausente, el plugin nombra su ensamblado solo a partir de la ruta de despacho.
reusableInstancebooleanonoSi una única instancia cargada del plugin puede atender cada cruce de renderizado, ensamblado y validación de una compilación en lugar de una instancia nueva por cruce. Se declara true solo cuando el plugin no conserva estado de un cruce a otro — una función pura de su entrada por cruce —, de modo que una única instancia produce una salida idéntica byte a byte, tanto si se reutiliza como si se carga de nuevo. Si está ausente (false), se carga una instancia nueva por cruce, lo que aísla por construcción un plugin que lleva estado.
crossBoundaryLinkingbooleanonoSi el plugin cablea una arista uses entre límites — una arista uses cuyos extremos consumidor y consumido se ensamblan en grupos de despacho distintos — emitiendo un cableado de referencias cruzadas nativo del proveedor mediante un contrato de exportación emparejado link_publish/link_resolve. Se declara true solo cuando el plugin exporta ambos; una declaración que no coincide con el par de exportaciones provoca una detención al cargar. Si está ausente (false), no declara ningún enlace entre límites, por lo que el host no enruta ningún cruce de enlace al plugin.
omitsbooleanonoSi el proveedor respeta las entradas de exclusión — entradas que nombran unidades renderizadas que se excluyen de la salida de un nodo: excluye de lo que renderiza cada unidad con la que coincide una entrada, e informa de con cuántas unidades coincidió cada entrada. Es el registro, en el momento de la publicación, de la declaración omits que hace el autoinforme del proveedor, y un valor que difiere de ese autoinforme provoca una detención al cargar. Si está ausente (false), no declara tal compatibilidad.
boundaryArtifactsbooleanonoSi el proveedor acepta los archivos que una Recipe aporta a la salida compartida del límite en el que se renderiza, bajo el spec.boundary.artifacts de la Recipe: el compilador escribe cada uno de esos archivos una sola vez, en el directorio que contiene la salida ensamblada del límite, y el destino del proveedor lo trata como parte de esa salida. Es el registro, en el momento de la publicación, de la declaración boundary_artifacts que hace el autoinforme del proveedor, y un valor que difiere de ese autoinforme provoca una detención al cargar. Si está ausente (false), no declara tal compatibilidad, y una Recipe que declara el bloque para este proveedor se rechaza antes de que se renderice nada.
nestSegmentstringnoEl directorio bajo el que el destino de este proveedor coloca el subdirectorio propio de cada contribuyente, para un proveedor cuyo boundaryAssembly es nest — charts para un chart paraguas, modules para un módulo raíz. El compilador une este directorio, el nombre del contribuyente y la ruta propia de cada archivo. Solo se lee para un proveedor que anida. Si está ausente, el subdirectorio de cada contribuyente se coloca directamente en el directorio propio del límite. El valor nombra un único directorio y nunca una ruta.
sourceIgnoreobjectnoLos archivos que el ecosistema de este proveedor nunca distribuye junto a una fuente que renderiza, como reglas ignore en sintaxis gitignore — el registro, en el momento de la publicación, de las reglas source_ignore que declara su autoinforme. Cuando un autor fija una Recipe o una FeatureRecipe cuya capacidad este proveedor atiende para él, estas reglas se componen con el .aggregaignore propio del autor y se registran en el entity.lock junto a la entidad, además del nombre de este plugin, y cada publicación, comparación y renderizado posterior de la fuente local de la entidad aplica las reglas registradas. Cuando está presente, debe ser igual a lo que declara el autoinforme, y la carga rechaza un plugin cuyo autoinforme difiere; si está ausente, no declara nada y no se compara.

No se permiten propiedades adicionales.

plugin.spec.provider.contract.inputKinds

Cuáles de los tres tipos de entrada de Recipe renderiza este plugin: un conjunto de archivos con fuente, una carga de trabajo sintetizada y un nodo autónomo solo de artefactos. Cada campo es una declaración independiente.

PropiedadTipoObligatoriaDescripción
sourcedbooleanonoRenderiza un conjunto de archivos con fuente (un chart, un módulo, un archivo compose).
synthesizedbooleanonoRenderiza una carga de trabajo sintetizada en artefactos nativos del proveedor.
artifactsStandalonebooleanonoRenderiza un nodo autónomo solo de artefactos — uno que lleva documentos de artefactos importados y ni fuente ni carga de trabajo.

No se permiten propiedades adicionales.

plugin.spec.provider.contract.artifactDelimiters

El par de delimitadores de plantillas Go que el plugin aplica a los archivos de artefactos importados. Si está ausente, se usa el par predeterminado {{/}}; un plugin cuya sintaxis de destino colisiona con ese par declara aquí un par alternativo.

PropiedadTipoObligatoriaDescripción
leftstringsíEl delimitador de apertura.
rightstringsíEl delimitador de cierre.

No se permiten propiedades adicionales.

plugin.spec.provider.contract.assemblyNameAnnotation

La anotación de límite cuyo valor resuelto nombra el artefacto que el plugin ensambla a partir de un grupo de despacho. Un plugin que reúne los límites que contribuyen a un grupo en un único ensamblado con nombre declara la clave de anotación que lee y si cada límite que contribuye debe coincidir en el valor resuelto de esa anotación. Si está ausente, el plugin nombra su ensamblado solo a partir de la ruta de despacho.

PropiedadTipoObligatoriaDescripción
annotationstringsíLa clave de la anotación de límite de la que el plugin lee el nombre del artefacto ensamblado.
requireUniquebooleanonoSi cada límite que contribuye a un mismo grupo de despacho debe coincidir en el valor resuelto de la anotación. Cuando es true, un grupo cuyos límites contribuyentes resuelven la anotación en valores distintos detiene la compilación; cuando es false, el plugin acepta el primer valor resuelto.

No se permiten propiedades adicionales.

plugin.spec.provider.contract.sourceIgnore

Los archivos que el ecosistema de este proveedor nunca distribuye junto a una fuente que renderiza, como reglas ignore en sintaxis gitignore — el registro, en el momento de la publicación, de las reglas source_ignore que declara su autoinforme. Cuando un autor fija una Recipe o una FeatureRecipe cuya capacidad este proveedor atiende para él, estas reglas se componen con el .aggregaignore propio del autor y se registran en el entity.lock junto a la entidad, además del nombre de este plugin, y cada publicación, comparación y renderizado posterior de la fuente local de la entidad aplica las reglas registradas. Cuando está presente, debe ser igual a lo que declara el autoinforme, y la carga rechaza un plugin cuyo autoinforme difiere; si está ausente, no declara nada y no se compara.

PropiedadTipoObligatoriaDescripción
patternsstring[]noLos patrones ignore propios del ecosistema, cada uno con ámbito en la raíz del directorio de la fuente local, en el orden en que se aplican.
filesstring[]noLos nombres de los archivos ignore que el ecosistema respeta dentro de una fuente — .helmignore para un chart. Las líneas de cada uno de esos archivos son patrones adicionales, con ámbito en el directorio que lo contiene.

No se permiten propiedades adicionales.

plugin.spec.pipelineStep

El bloque pipeline-step para un plugin pluginType: pipeline-step: las capacidades del proveedor con las que es compatible su paso. Presente solo en los plugins pipeline-step; ausente en cualquier otro tipo de plugin.

PropiedadTipoObligatoriaDescripción
capabilitiesstring[]noSe registra a partir del autoinforme del .wasm del plugin mediante aggrega plugin gen-catalog, de modo que el plugin es la fuente de esta lista. Un autor puede acotarla antes de publicar, quitando una entrada que esta entidad no deba ofrecer, y no puede añadir ninguna que el autoinforme no nombre: la publicación, y aggrega validate al que se le da el .wasm del plugin con --plugin, rechazan una lista que nombre una capacidad que el autoinforme no nombra. La publicación envía la entidad tal como está escrita, sin reescribir nunca esta lista, y señala cada capacidad que nombra el autoinforme y que la lista deja fuera. Las capacidades de proveedor con las que es compatible el paso de pipeline de este plugin — los nombres de capacidades de proveedor, como helm o compose, cuya salida renderizada el paso sabe transformar. Un paso se escribe para la forma de salida de un solo proveedor a la vez, por lo que la lista es una declaración explícita de compatibilidad probada y no una aspiración. Las entradas conservan el orden del autor. Es el registro legible por el catálogo de esa declaración; la compilación lee la misma declaración del plugin cuando un paso toca un ámbito y se detiene cuando el proveedor que renderiza los documentos de ese ámbito no está entre ellas. Una lista vacía o ausente no declara ninguna compatibilidad, por lo que ningún ámbito admite el paso.

No se permiten propiedades adicionales.

plugin.spec.parser

El bloque parser para un plugin pluginType: parser: los formatos de origen que convierte en un árbol estructurado canónico. Presente solo en los plugins parser; ausente en cualquier otro tipo de plugin.

PropiedadTipoObligatoriaDescripción
capabilitiesstring[]noSe registra a partir del autoinforme del .wasm del plugin mediante aggrega plugin gen-catalog, de modo que el plugin es la fuente de esta lista. Un autor puede acotarla antes de publicar, quitando una entrada que esta entidad no deba ofrecer, y no puede añadir ninguna que el autoinforme no nombre: la publicación, y aggrega validate al que se le da el .wasm del plugin con --plugin, rechazan una lista que nombre una capacidad que el autoinforme no nombra. La publicación envía la entidad tal como está escrita, sin reescribir nunca esta lista, y señala cada capacidad que nombra el autoinforme y que la lista deja fuera. Los formatos de fuente que este parser convierte en un árbol estructurado canónico, cada uno escrito como parse:<format> — por ejemplo parse:yaml. El prefijo forma parte de la entrada, por lo que un plugin que anuncia varios formatos lista una entrada por formato. Las entradas conservan el orden del autor. Un formato solicitado se resuelve en el parser cuya lista contiene la entrada correspondiente; un formato que ningún parser anuncia detiene la compilación, y un formato anunciado por más de un plugin parser detiene la compilación por ambiguo. Una lista vacía o ausente no declara ningún formato, por lo que el plugin no analiza nada.

No se permiten propiedades adicionales.

plugin.spec.importer

El bloque importer para un plugin pluginType: importer: los formatos de origen externos que convierte en borradores de archivos de autoría de Aggrega, y las firmas por las que se reconoce una fuente de esos formatos. Presente solo en los plugins importer; ausente en cualquier otro tipo de plugin.

PropiedadTipoObligatoriaDescripción
capabilitiesstring[]noSe registra a partir del autoinforme del .wasm del plugin mediante aggrega plugin gen-catalog, de modo que el plugin es la fuente de esta lista. Un autor puede acotarla antes de publicar, quitando una entrada que esta entidad no deba ofrecer, y no puede añadir ninguna que el autoinforme no nombre: la publicación, y aggrega validate al que se le da el .wasm del plugin con --plugin, rechazan una lista que nombre una capacidad que el autoinforme no nombra. La publicación envía la entidad tal como está escrita, sin reescribir nunca esta lista, y señala cada capacidad que nombra el autoinforme y que la lista deja fuera. Los formatos de fuente externos que este importador convierte en archivos de autoría de Aggrega en borrador, cada uno escrito como import:<format> — por ejemplo import:terraform. El prefijo forma parte de la entrada, por lo que un plugin que anuncia varios formatos lista una entrada por formato. Las entradas conservan el orden del autor. Un formato de importación solicitado se resuelve en el importador cuya lista contiene la entrada correspondiente; un formato que ningún importador anuncia detiene la importación, y un formato anunciado por más de un plugin importador detiene la importación por ambiguo, salvo que una entrada plugins.importer en la configuración del espacio de trabajo vincule uno de ellos, que entonces se ejecuta. Una lista vacía o ausente no declara ningún formato, por lo que el plugin no importa nada.
detectobject[]noGestionado por la máquina, no se escribe a mano: derivado del autoinforme del .wasm del plugin cuando la entidad se genera a partir de él, y registrado aquí en el orden en que el autoinforme las declara. Las firmas por las que se reconoce una fuente de los formatos de este importador cuando una importación no nombra ningún formato. aggrega import lee las firmas de cada importador que contiene el catálogo del espacio de trabajo, incluidas todas sus versiones, y de los importadores del núcleo del compilador, las compara con la fuente sin saber qué es ningún formato, y lee la fuente como el formato del único importador cuya firma coincide; una fuente con la que no coincide ninguna firma se rechaza pidiendo el formato, y una fuente con la que coinciden firmas de más de un formato se rechaza nombrándolos. Un importador que reconoce una fuente la reconoce como cada formato que anuncia, por lo que, en un importador que anuncia más de un formato, cada coincidencia se rechaza por ambigua. Cuando está presente, la lista debe ser igual a lo que declara el autoinforme del plugin, entrada por entrada y en orden, y la carga y la publicación rechazan un plugin cuyo autoinforme difiere, nombrando este campo. Si está ausente, no declara nada y no se compara, y entonces solo se llega a los formatos del importador nombrándolos.

No se permiten propiedades adicionales.

plugin.spec.importer.detect[]
PropiedadTipoObligatoriaDescripción
syntaxstringsíEl formato sintáctico como el que se analiza la fuente — json o yaml, por ejemplo —, que es el formato que un plugin parser anuncia como parse:<syntax>. La fuente se analiza mediante el parser que el catálogo del espacio de trabajo ofrece para esa sintaxis o, para una sintaxis para la que el catálogo no ofrece ninguno, mediante el que lleva el compilador, como máximo una vez sea cual sea el número de firmas que nombran la sintaxis, y una fuente que no se puede analizar en ella no coincide con ninguna firma que la nombre. Una sintaxis para la que ninguno de los dos ofrece un parser detiene el reconocimiento nombrando la ausencia de ese parser. Al menos 1 carácter de longitud.
filesstring[]noLos patrones de nombre de archivo a los que se aplica la firma, comparados con el final del nombre de la fuente con sus separadores leídos como barras: un patrón de un solo segmento con el nombre propio del archivo, y un patrón de varios segmentos separados por barras con otros tantos segmentos finales de su ruta, de modo que .vscode/mcp.json coincide con un archivo llamado mcp.json en un directorio llamado .vscode. Dentro de un segmento, * coincide con cualquier secuencia de caracteres, ? con un carácter y [...] con un carácter de una clase. La firma se aplica cuando coincide cualquier patrón. Si está ausente o vacío, la firma se aplica a una fuente que es un solo archivo, se llame como se llame, y a ningún archivo de un directorio. Los patrones de las firmas de un importador también son lo que decide qué archivos de un directorio le pasa aggrega import.
matchobject[]noLos predicados que el árbol analizado debe cumplir, todos ellos, en el orden declarado. Si está ausente o vacío, no exige nada al árbol más allá de poder analizarse en la sintaxis.

No se permiten propiedades adicionales.

plugin.spec.importer.detect[].match[]
PropiedadTipoObligatoriaDescripción
pathstringsíEl lugar del árbol en el que mira el predicado, escrito como claves unidas por puntos desde la parte superior del árbol: data.nodes nombra el miembro nodes del objeto data de nivel superior. Un segmento escrito como número entero, 0 o mayor, selecciona esa posición de un array contando desde cero, de modo que nodes.0.type nombra el tipo del primer nodo; cualquier otro segmento selecciona un miembro de un objeto. Al menos 1 carácter de longitud.
isstring (enum)síLo que debe alcanzar la ruta: present se cumple cuando alcanza un valor de cualquier tipo, null incluido; absent se cumple cuando no alcanza nada; object, array, string, number y boolean se cumplen cada uno cuando alcanza un valor de ese tipo. Valores permitidos: "present", "absent", "object", "array", "string", "number", "boolean"
equalsstringnoUna cadena a la que debe ser exactamente igual el valor que alcanza la ruta; un valor que no es una cadena nunca es igual a ella. En un predicado se declara como máximo uno de equals y prefix. Al menos 1 carácter de longitud.
prefixstringnoUna cadena por la que debe empezar el valor que alcanza la ruta; un valor que no es una cadena nunca empieza por ella. En un predicado se declara como máximo uno de equals y prefix. Al menos 1 carácter de longitud.

No se permiten propiedades adicionales.