aggrega search
Cerca nell’indice locale dei registry configurati
Sinossi
aggrega search [query] [flags]Descrizione
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.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--capability | [] | Capability del Plugin da confrontare. Ripetibile; viene mantenuto un record che ne dichiara una qualsiasi. |
--include-retracted | false | Riporta la versione pubblicata più alta anche dove un marcatore verificato la ritira. Per impostazione predefinita, la versione riportata è quella che una risoluzione sceglierebbe. |
--kind | [] | Tipo di entità da confrontare (component|feature|recipe|featurerecipe|workload|plugin). Ripetibile; viene mantenuto un record che corrisponde a uno qualsiasi. Senza distinzione tra maiuscole e minuscole. |
--limit | 0 | Limita il numero di risultati (0 significa nessun limite). |
--output, -o | table | Formato di output: table|json|names. |
--plugin-type | — | Tipo di socket del Plugin da confrontare (ad esempio provider, governance, linter). |
--registry | — | Cerca solo in questo registry, indicato tramite host o alias descrittivo. Per impostazione predefinita la ricerca avviene in ogni registry configurato. |
--selector, -l | — | Selettore di etichette sulle etichette di catalogo dell’entità, che includono la sua categoria (-l component.aggrega.ai/category=compute). |
Quando nessun registry è configurato
Una ricerca legge l’indice locale dei registry che questa macchina è configurata per raggiungere, quindi ne richiede almeno uno. Se non ne è configurato nessuno non c’è dove cercare, e aggrega search rifiuta invece di rispondere: scrive il motivo sullo standard error, termina con un codice diverso da zero e lascia vuoto lo standard output — in ogni formato di output, --output json compreso.
Il rifiuto è ciò che tiene distinte due risposte diverse. Una ricerca che è stata eseguita e non ha trovato nulla termina con zero e riporta (no matches) sullo standard output; una ricerca che non è potuta essere eseguita affatto termina con un codice diverso da zero e lì non riporta nulla. Uno script che si dirama in base allo stato di uscita può quindi distinguere «questa entità non è pubblicata» da «questa macchina non ha alcun registry da interrogare», cosa che un avviso sullo standard output e uno stato zero non possono esprimere.
Esegui aggrega config init per registrare un registry insieme alla sua policy di attendibilità delle firme, quindi aggrega registry update per costruire l’indice locale letto dalla ricerca.
aggrega registry list e aggrega registry update rispondono alla stessa situazione in modo diverso, e deliberatamente. Elencare i registry quando non ce n’è nessuno è un elenco completo di un insieme vuoto, e la costruzione di un indice senza nulla da percorrere non ha altro da fare: entrambe sono operazioni concluse, quindi entrambe riportano sullo standard output e terminano con zero. Solo la ricerca sta segnalando di non aver potuto fare ciò che le era stato chiesto.
La versione riportata da una ricerca
La colonna VERSION contiene la versione che una risoluzione sceglierebbe. Una versione ritirata dal suo publisher non viene riportata, a condizione che il ritiro abbia una firma verificata dalla policy di attendibilità di questo workspace — le stesse due condizioni che decidono se un ritiro influisce su un pull, così una ricerca e un pull concordano su quale versione sia la risposta.
Un ritiro che non soddisfa una delle due condizioni non cambia nulla di ciò che viene riportato. Un marcatore con severità consultiva lascia selezionabile la sua versione, e un marcatore la cui firma non viene verificata non è un’affermazione in base alla quale questo workspace agisce. In entrambi i casi la versione pubblicata più alta viene riportata esattamente come lo sarebbe senza alcun marcatore.
Un’entità con una versione ritirata viene comunque elencata. Una colonna NOTES nomina le versioni escluse e compare solo in un risultato che ha qualcosa da segnalare. Un’entità di cui ogni versione pubblicata è ritirata viene riportata con (none) come versione e una nota che dice che non resta alcuna versione, invece di essere eliminata dal risultato — un’entità omessa sarebbe indistinguibile da una che non esiste.
Passa --include-retracted per riportare la versione pubblicata più alta qualunque sia il suo stato di ritiro, che è la risposta a «che cosa è pubblicato?» anziché a «che cosa dovrei usare?». Cambia solo la versione riportata; la colonna NOTES nomina le versioni ritirate in entrambi i casi.
Ciò che una ricerca legge è l’indice locale scritto da aggrega registry update, quindi riporta ciò che ciascun registry dichiarava quando quell’indice è stato costruito l’ultima volta. Una versione ritirata da allora non è ancora registrata, e la riga sull’aggiornamento dei dati scritta sullo standard error indica il momento in cui ciascun indice è stato costruito.
Il risultato leggibile da una macchina
--output json riporta lo stesso contratto in due campi:
versionè la versione che una risoluzione sceglierebbe. È la stringa vuota quando ogni versione pubblicata è ritirata, e in tal caso si accompagna a un elencoretractedche le nomina tutte.retractedelenca le versioni escluse da quella scelta, in ordine di versione crescente. È assente quando non è stato escluso nulla.
Un consumer che vuole sapere quale versione otterrebbe legge version. Ricavarla invece dall’array deprecations significa reimplementare le condizioni di severità e di firma, e una seconda implementazione di quelle condizioni è libera di non concordare con quella applicata dal compilatore; retracted riporta l’esito che quelle condizioni hanno già prodotto.
Ogni record contiene anche published: ogni versione registrata dall’indice, in ordine di versione crescente, ciascuna con il manifestDigest a cui il suo tag si risolveva quando l’indice è stato costruito e, dove la policy di attendibilità di questo workspace ha verificato la firma propria di quella versione, il suo signer — tra più firme che si verificano, quella che il transparency log ha registrato per prima. Una versione senza signer non ha alcuna firma verificata da quella policy, e non se ne dice altro. Un consumer che legge il contenuto di una versione lo indirizza tramite quel digest — ad esempio aggrega inspect oci://<host>/<repository>@<digest> — così ciò che legge sono i byte registrati dall’indice, qualunque cosa accada al tag in seguito.
Dove qualcosa registra quando una versione è stata pubblicata, la sua voce contiene anche publishedAt, un timestamp RFC 3339 in UTC al secondo, e publishedAtSource, che indica da dove proviene. transparency-log è il momento in cui un transparency log ha registrato la firma keyless della versione, che la policy di attendibilità di questo workspace ha verificato insieme alla promessa firmata del log su quel momento — la firma del signer, la prima tra quelle che si verificano, così firmare di nuovo una versione non sposta né l’una né l’altro. publisher è il momento che la pubblicazione ha dichiarato accanto a ciò che ha pubblicato, secondo l’orologio della macchina che ha pubblicato, che nulla attesta. I due sono tenuti separati affinché un consumer che ordina per data possa ancora distinguere un momento attestato da uno dichiarato. Una versione priva di entrambi non ha data, e non se ne dice altro; vedi aggrega registry update per sapere quando viene registrato ciascuno.