aggrega search
Buscar en el índice local de los registries configurados
Sinopsis
aggrega search [query] [flags]Descripción
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach entity's name and description. The facet filters narrow the result further,combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe, workload, plugin); repeatable, case-insensitive --capability a plugin capability; repeatable --plugin-type a plugin socket type (for example provider, governance) -l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalogcategory is the label component.aggrega.ai/category, so'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere to look, so the command refuses: the reason goes to standard error,standard output carries nothing, and the exit status is non-zero. That is whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--capability | [] | Capacidad de Plugin que debe coincidir. Repetible; se conserva un registro que declare cualquiera de ellas. |
--include-retracted | false | Informa de la versión publicada más alta incluso cuando un marcador verificado la retira. De forma predeterminada, la versión informada es la que tomaría una resolución. |
--kind | [] | Tipo de entidad que debe coincidir (component|feature|recipe|featurerecipe|workload|plugin). Repetible; se conserva un registro que coincida con cualquiera de ellos. No distingue mayúsculas de minúsculas. |
--limit | 0 | Limita el número de resultados (0 significa sin límite). |
--output, -o | table | Formato de salida: table|json|names. |
--plugin-type | — | Tipo de socket de Plugin que debe coincidir (por ejemplo provider, governance, linter). |
--registry | — | Busca solo en este registro, indicado por host o alias descriptivo. De forma predeterminada se busca en todos los registros configurados. |
--selector, -l | — | Selector de etiquetas sobre las etiquetas de catálogo de la entidad, que incluyen su categoría (-l component.aggrega.ai/category=compute). |
Cuando no hay ningún registro configurado
Una búsqueda lee el índice local de los registros a los que esta máquina está configurada para llegar, así que necesita al menos uno de ellos. Si no hay ninguno configurado, no hay dónde buscar, y aggrega search se niega en lugar de responder: escribe el motivo en la salida de error estándar, termina con un código distinto de cero y deja vacía la salida estándar — en todos los formatos de salida, incluido --output json.
El rechazo es lo que mantiene separadas dos respuestas distintas. Una búsqueda que se ejecutó y no encontró nada termina con cero e informa de (no matches) en la salida estándar; una búsqueda que no pudo ejecutarse en absoluto termina con un código distinto de cero y no informa de nada allí. Por lo tanto, un script que se ramifica según el código de salida puede distinguir «esta entidad no está publicada» de «esta máquina no tiene ningún registro al que preguntar», algo que un aviso en la salida estándar y un código cero no pueden expresar.
Ejecuta aggrega config init para dar de alta un registro junto con su política de confianza de firmas y, después, aggrega registry update para construir el índice local que lee la búsqueda.
aggrega registry list y aggrega registry update responden de forma distinta a la misma situación, y de manera deliberada. Listar los registros cuando no hay ninguno es un listado completo de un conjunto vacío, y la construcción de un índice sin nada que recorrer no tiene nada más que hacer: ambas son operaciones terminadas, así que ambas informan en la salida estándar y terminan con cero. Solo la búsqueda está informando de que no pudo hacer lo que se le pidió.
La versión que informa una búsqueda
La columna VERSION contiene la versión que tomaría una resolución. No se informa de una versión que su publicador haya retirado, siempre que la retirada lleve una firma que verifique la política de confianza de este espacio de trabajo — las mismas dos condiciones que deciden si una retirada afecta a un pull, de modo que una búsqueda y un pull coinciden en qué versión es la respuesta.
Una retirada que no cumple alguna de las dos condiciones no cambia nada de lo que se informa. Un marcador con severidad informativa deja su versión seleccionable, y un marcador cuya firma no se verifica no es una afirmación según la cual actúe este espacio de trabajo. En ambos casos, se informa de la versión publicada más alta exactamente como se haría sin ningún marcador.
Una entidad con una versión retirada se sigue listando. Una columna NOTES nombra las versiones excluidas y solo aparece en un resultado que tiene algo que informar. Una entidad cuyas versiones publicadas están todas retiradas se informa con (none) como versión y una nota que indica que no queda ninguna versión, en lugar de eliminarse del resultado — una entidad omitida sería indistinguible de una que no existe.
Pasa --include-retracted para informar de la versión publicada más alta sea cual sea su estado de retirada, que es la respuesta a «¿qué está publicado?» en lugar de a «¿qué debería usar?». Solo cambia la versión informada; la columna NOTES nombra las versiones retiradas en ambos casos.
Lo que lee una búsqueda es el índice local que escribe aggrega registry update, así que informa de lo que cada registro indicaba cuando ese índice se construyó por última vez. Una versión retirada desde entonces todavía no está registrada, y la línea de actualidad que se escribe en la salida de error estándar indica el momento en que se construyó cada índice.
El resultado legible por máquina
--output json lleva el mismo contrato en dos campos:
versiones la versión que tomaría una resolución. Es la cadena vacía cuando todas las versiones publicadas están retiradas, lo que va acompañado de una listaretractedque las nombra todas.retractedlista las versiones excluidas de esa elección, en orden ascendente de versión. Está ausente cuando no se excluyó nada.
Un consumidor que pregunta qué versión obtendría lee version. Deducirla en cambio del array deprecations supone reimplementar las condiciones de severidad y de firma, y una segunda implementación de esas condiciones puede perfectamente discrepar de la que aplica el compilador; retracted informa del resultado que esas condiciones ya produjeron.
Cada registro lleva también published: todas las versiones que registró el índice, en orden ascendente de versión, cada una con el manifestDigest al que se resolvía su tag cuando se construyó el índice y, cuando la política de confianza de este espacio de trabajo verificó la firma propia de esa versión, su signer — de entre varias que se verifican, la que el registro de transparencia registró primero. Una versión sin signer no lleva ninguna firma que esa política haya verificado, y no se dice nada más de ella. Un consumidor que lee el contenido de una versión lo direcciona mediante ese digest — por ejemplo aggrega inspect oci://<host>/<repository>@<digest> — de modo que lo que lee son los bytes que registró el índice, pase lo que pase después con el tag.
Cuando algo registra cuándo se publicó una versión, su entrada lleva también publishedAt, una marca de tiempo RFC 3339 en UTC con precisión de segundos, y publishedAtSource, que indica de dónde procede. transparency-log es el momento en que un registro de transparencia registró la firma keyless de la versión, que la política de confianza de este espacio de trabajo verificó junto con la promesa firmada del registro sobre ese momento — la firma del signer, la más antigua de las que se verifican, de modo que volver a firmar una versión no mueve ninguno de los dos. publisher es el momento que la publicación declaró junto a lo que publicó, según el reloj propio de la máquina que publicó, que nada certifica. Ambos se mantienen separados para que un consumidor que ordena por fecha pueda seguir distinguiendo una hora certificada de una declarada. Una versión sin ninguno de los dos no lleva fecha, y no se dice nada más de ella; consulta aggrega registry update para saber cuándo se registra cada uno.