aggrega search
Przeszukuje lokalny indeks skonfigurowanych rejestrów
Składnia
aggrega search [query] [flags]Opis
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.Flagi
| Flaga | Domyślnie | Opis |
|---|---|---|
--capability | [] | Zdolność (capability) Plugin do dopasowania. Można podać wielokrotnie; zachowywany jest rekord deklarujący dowolną z nich. |
--include-retracted | false | Zgłasza najwyższą opublikowaną wersję, nawet jeśli zweryfikowany znacznik ją wycofuje. Domyślnie zgłaszana jest wersja, którą wybrałoby rozwiązywanie zależności. |
--kind | [] | Dopasowywany rodzaj encji (component|feature|recipe|featurerecipe|workload|plugin). Można powtarzać; zachowywany jest rekord pasujący do dowolnego z nich. Wielkość liter nie ma znaczenia. |
--limit | 0 | Ogranicza liczbę wyników (0 oznacza brak limitu). |
--output, -o | table | Format wyjścia: table|json|names. |
--plugin-type | — | Typ gniazda Plugin do dopasowania (na przykład provider, governance, linter). |
--registry | — | Przeszukuje tylko ten rejestr, wskazany przez hosta lub przyjazny alias. Domyślnie przeszukiwane są wszystkie skonfigurowane rejestry. |
--selector, -l | — | Selektor etykiet działający na etykietach katalogowych encji, w tym na jej kategorii (-l component.aggrega.ai/category=compute). |
Gdy nie skonfigurowano żadnego rejestru
Wyszukiwanie odczytuje lokalny indeks rejestrów, do których ta maszyna jest skonfigurowana, więc
wymaga co najmniej jednego z nich. Gdy żaden nie jest skonfigurowany, nie ma gdzie szukać, a aggrega search
odmawia zamiast odpowiadać: zapisuje powód na standardowe wyjście błędów, kończy się kodem niezerowym i
pozostawia standardowe wyjście puste — w każdym formacie wyjścia, łącznie z --output json.
Odmowa pozwala odróżnić dwie różne odpowiedzi. Wyszukiwanie, które się wykonało i niczego nie znalazło,
kończy się kodem zero i zgłasza (no matches) na standardowym wyjściu; wyszukiwanie, którego w ogóle nie dało się wykonać,
kończy się kodem niezerowym i niczego tam nie zgłasza. Skrypt rozgałęziający się według kodu wyjścia może więc
odróżnić „ta encja nie jest opublikowana” od „ta maszyna nie ma rejestru, który mogłaby zapytać”, czego komunikat
na standardowym wyjściu i kod zero nie są w stanie wyrazić.
Należy uruchomić aggrega config init, aby zarejestrować rejestr wraz z jego polityką zaufania podpisów, a następnie
aggrega registry update, aby zbudować lokalny indeks odczytywany przez wyszukiwanie.
aggrega registry list i aggrega registry update reagują na tę samą sytuację inaczej, i
to celowo. Wylistowanie rejestrów, gdy nie ma żadnego, jest pełnym wylistowaniem zbioru pustego,
a budowa indeksu, gdy nie ma czego przeglądać, nie ma już nic do zrobienia: obie operacje są zakończone, więc
obie zgłaszają wynik na standardowym wyjściu i kończą się kodem zero. Tylko wyszukiwanie zgłasza, że nie mogło wykonać
tego, o co zostało poproszone.
Wersja zgłaszana przez wyszukiwanie
Kolumna VERSION zawiera wersję, którą wybrałoby rozwiązywanie zależności. Wersja wycofana przez
wydawcę nie jest zgłaszana, pod warunkiem że wycofanie ma podpis weryfikowany przez politykę zaufania
tego obszaru roboczego — to te same dwa warunki, które decydują, czy wycofanie wpływa na pobranie, więc
wyszukiwanie i pobranie zgadzają się co do tego, która wersja jest odpowiedzią.
Wycofanie niespełniające któregokolwiek z warunków nie zmienia niczego w zgłaszanym wyniku. Znacznik o poziomie doradczym pozostawia swoją wersję możliwą do wybrania, a znacznik, którego podpis nie przechodzi weryfikacji, nie jest deklaracją, na podstawie której działa ten obszar roboczy. W obu przypadkach najwyższa opublikowana wersja jest zgłaszana dokładnie tak, jak byłaby bez żadnego znacznika.
Encja z wycofaną wersją nadal jest wyświetlana. Kolumna NOTES wymienia pominięte
wersje i pojawia się tylko w wyniku, w którym jest coś do zgłoszenia. Encja, której każda
opublikowana wersja jest wycofana, jest zgłaszana z wartością (none) jako wersją i notatką, że nie
pozostała żadna wersja, zamiast zostać usunięta z wyniku — pominiętej encji nie dałoby się
odróżnić od takiej, która nie istnieje.
Przekazanie --include-retracted powoduje zgłoszenie najwyższej opublikowanej wersji bez względu na status
wycofania, co odpowiada na pytanie „co jest opublikowane?”, a nie „czego należy użyć?”.
Zmienia to tylko zgłaszaną wersję; kolumna NOTES wymienia wycofane wersje w obu
przypadkach.
Wyszukiwanie odczytuje lokalny indeks zapisywany przez aggrega registry update, więc zgłasza
to, co każdy rejestr deklarował w chwili ostatniej budowy indeksu. Wersja wycofana od tego czasu
nie jest jeszcze odnotowana, a wiersz aktualności zapisywany na standardowe wyjście błędów podaje moment
zbudowania każdego indeksu.
Wynik do odczytu maszynowego
--output json przenosi ten sam kontrakt w dwóch polach:
versionto wersja, którą wybrałoby rozwiązywanie zależności. Jest pustym ciągiem, gdy każda opublikowana wersja jest wycofana, czemu towarzyszy listaretractedwymieniająca je wszystkie.retractedwymienia wersje pominięte w tym wyborze, w rosnącej kolejności wersji. Pole jest nieobecne, gdy niczego nie pominięto.
Konsument pytający, którą wersję otrzyma, odczytuje version. Wyprowadzanie tego z
tablicy deprecations oznacza ponowną implementację warunków poziomu i podpisu, a
druga implementacja tych warunków może się nie zgadzać z tą, którą stosuje
kompilator; retracted zgłasza wynik, który te warunki już dały.
Każdy rekord zawiera też published: każdą wersję odnotowaną w indeksie, w rosnącej kolejności
wersji, każdą z manifestDigest, na który wskazywał jej tag w chwili budowy indeksu, oraz — jeśli
polityka zaufania tego obszaru roboczego zweryfikowała własny podpis tej wersji — jej signer: spośród kilku
weryfikowanych ten, który dziennik przejrzystości odnotował najwcześniej. Wersja bez signer nie ma
podpisu zweryfikowanego przez tę politykę i nic więcej się o niej nie mówi.
Konsument odczytujący zawartość jednej wersji adresuje ją tym skrótem — na przykład
aggrega inspect oci://<host>/<repository>@<digest> — więc odczytuje bajty odnotowane przez indeks,
bez względu na to, co później stanie się z tagiem.
Jeśli cokolwiek odnotowuje datę publikacji wersji, jej wpis zawiera też publishedAt,
znacznik czasu RFC 3339 w UTC z dokładnością do sekundy, oraz publishedAtSource, który wskazuje jego źródło.
transparency-log to czas, w którym dziennik przejrzystości odnotował bezkluczowy podpis wersji,
zweryfikowany przez politykę zaufania tego obszaru roboczego wraz z podpisaną przez dziennik obietnicą tego
czasu — podpis signer, najwcześniejszy z weryfikowanych, więc ponowne podpisanie wersji
nie zmienia żadnego z nich. publisher to czas podany przez publikację obok tego, co opublikowała, według
własnego zegara publikującej maszyny, którego nic nie poświadcza. Oba są trzymane osobno, aby konsument
sortujący według daty nadal mógł odróżnić czas poświadczony od deklarowanego. Wersja bez żadnego z nich
nie ma daty i nic więcej się o niej nie mówi; informacje o tym, kiedy każdy z nich jest odnotowywany, zawiera
aggrega registry update.