aggrega search
Pesquisar no índice local dos registries configurados
Sinopse
aggrega search [query] [flags]Descrição
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 | Padrão | Descrição |
|---|---|---|
--capability | [] | Capacidade de Plugin a corresponder. Repetível; um registro que declare qualquer uma delas é mantido. |
--include-retracted | false | Informa a versão publicada mais alta mesmo quando um marcador verificado a retira. Por padrão, a versão informada é aquela que uma resolução escolheria. |
--kind | [] | Tipo de entidade a corresponder (component|feature|recipe|featurerecipe|workload|plugin). Repetível; um registro que corresponda a qualquer um deles é mantido. Não diferencia maiúsculas de minúsculas. |
--limit | 0 | Limita o número de resultados (0 significa sem limite). |
--output, -o | table | Formato de saída: table|json|names. |
--plugin-type | — | Tipo de socket de Plugin a corresponder (por exemplo provider, governance, linter). |
--registry | — | Pesquisa apenas neste registry, indicado por host ou alias amigável. Por padrão, a pesquisa abrange todos os registries configurados. |
--selector, -l | — | Seletor de rótulos sobre os rótulos de catálogo da entidade, que incluem sua categoria (-l component.aggrega.ai/category=compute). |
Quando nenhum registry está configurado
Uma pesquisa lê o índice local dos registries que esta máquina está configurada para alcançar, portanto precisa de pelo menos um deles. Sem nenhum configurado, não há onde procurar, e aggrega search recusa em vez de responder: escreve o motivo na saída de erro padrão, termina com um código diferente de zero e deixa a saída padrão vazia — em todos os formatos de saída, --output json incluído.
A recusa é o que mantém separadas duas respostas diferentes. Uma pesquisa que foi executada e não encontrou nada termina com zero e informa (no matches) na saída padrão; uma pesquisa que nem pôde ser executada termina com um código diferente de zero e não informa nada ali. Um script que se ramifica pelo código de saída pode, portanto, distinguir “esta entidade não está publicada” de “esta máquina não tem nenhum registry a consultar”, algo que um aviso na saída padrão com um código zero não consegue expressar.
Execute aggrega config init para registrar um registry junto com sua política de confiança de assinaturas e, em seguida, aggrega registry update para construir o índice local que a pesquisa lê.
aggrega registry list e aggrega registry update respondem à mesma situação de forma diferente, e isso é proposital. Listar registries quando não há nenhum é uma listagem completa de um conjunto vazio, e a construção de um índice sem nada a percorrer não tem mais nada a fazer: ambas são operações concluídas, então ambas informam na saída padrão e terminam com zero. Somente a pesquisa está informando que não pôde fazer o que lhe foi pedido.
A versão que uma pesquisa informa
A coluna VERSION traz a versão que uma resolução escolheria. Uma versão que seu publicador retirou não é informada, desde que a retirada traga uma assinatura que a política de confiança deste workspace verifique — as mesmas duas condições que decidem se uma retirada afeta um pull, de modo que uma pesquisa e um pull concordam sobre qual versão é a resposta.
Uma retirada que não atende a qualquer uma das condições não muda nada no que é informado. Um marcador com severidade consultiva deixa sua versão selecionável, e um marcador cuja assinatura não é verificada não é uma afirmação com base na qual este workspace age. Nos dois casos, a versão publicada mais alta é informada exatamente como seria sem nenhum marcador.
Uma entidade com uma versão retirada continua sendo listada. Uma coluna NOTES nomeia as versões deixadas de fora e aparece apenas em um resultado que tem algo a informar. Uma entidade cujas versões publicadas estão todas retiradas é informada com (none) como versão e uma nota dizendo que não resta nenhuma versão, em vez de ser removida do resultado — uma entidade omitida seria indistinguível de uma que não existe.
Passe --include-retracted para informar a versão publicada mais alta independentemente do seu status de retirada, que é a resposta a “o que está publicado?” em vez de “o que devo usar?”. Isso muda apenas a versão informada; a coluna NOTES nomeia as versões retiradas de qualquer forma.
O que uma pesquisa lê é o índice local que aggrega registry update escreve, portanto ela informa o que cada registry declarava quando esse índice foi construído pela última vez. Uma versão retirada desde então ainda não está registrada, e a linha de atualização escrita na saída de erro padrão nomeia o momento em que cada índice foi construído.
O resultado legível por máquina
--output json traz o mesmo contrato em dois campos:
versioné a versão que uma resolução escolheria. É a string vazia quando todas as versões publicadas estão retiradas, o que vem acompanhado de uma listaretractedque nomeia todas elas.retractedlista as versões deixadas de fora dessa escolha, em ordem crescente de versão. Fica ausente quando nada foi deixado de fora.
Um consumidor que pergunta qual versão obteria lê version. Derivá-la do array deprecations significa reimplementar as condições de severidade e de assinatura, e uma segunda implementação dessas condições pode muito bem discordar daquela que o compilador aplica; retracted informa o resultado que essas condições já produziram.
Cada registro também traz published: todas as versões que o índice registrou, em ordem crescente de versão, cada uma com o manifestDigest para o qual sua tag se resolvia quando o índice foi construído e, quando a política de confiança deste workspace verificou a assinatura própria dessa versão, seu signer — dentre várias que são verificadas, aquela que o log de transparência registrou primeiro. Uma versão sem signer não traz nenhuma assinatura que essa política tenha verificado, e nada mais é dito sobre ela. Um consumidor que lê o conteúdo de uma versão o endereça por esse digest — por exemplo aggrega inspect oci://<host>/<repository>@<digest> —, de modo que o que ele lê são os bytes que o índice registrou, aconteça o que acontecer com a tag depois.
Quando algo registra quando uma versão foi publicada, sua entrada também traz publishedAt, um carimbo de data/hora RFC 3339 em UTC com precisão de segundos, e publishedAtSource, que diz de onde ele veio. transparency-log é o momento em que um log de transparência registrou a assinatura keyless da versão, que a política de confiança deste workspace verificou junto com a promessa assinada do log sobre esse momento — a assinatura do signer, a mais antiga das que são verificadas, de modo que assinar uma versão novamente não move nenhum dos dois. publisher é o momento que a publicação declarou ao lado do que publicou, segundo o relógio da própria máquina que publicou, que nada atesta. Os dois são mantidos separados para que um consumidor que ordena por data ainda possa distinguir um horário atestado de um declarado. Uma versão sem nenhum dos dois não traz data, e nada mais é dito sobre ela; consulte aggrega registry update para saber quando cada um é registrado.