aggrega search
Шукати в локальному індексі налаштованих реєстрів
Синтаксис
aggrega search [query] [flags]Опис
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.Прапорці
| Прапорець | За замовчуванням | Опис |
|---|---|---|
--capability | [] | Можливість сутності Plugin, з якою слід шукати збіг. Можна повторювати; запис, що оголошує будь-яку з них, залишається. |
--include-retracted | false | Повідомляти найвищу опубліковану версію, навіть якщо перевірений маркер її відкликає. За замовчуванням повідомляється версія, яку обрало б розв’язання. |
--kind | [] | Тип сутності, за яким шукати (component|feature|recipe|featurerecipe|workload|plugin). Можна повторювати; запис, що відповідає будь-якому з них, зберігається. Без урахування регістру. |
--limit | 0 | Обмежити кількість результатів (0 означає без обмеження). |
--output, -o | table | Формат виводу: table|json|names. |
--plugin-type | — | Тип сокета сутності Plugin, з яким слід шукати збіг (наприклад, provider, governance, linter). |
--registry | — | Шукати лише в цьому реєстрі, указаному за хостом або зручним псевдонімом. За замовчуванням пошук виконується в усіх налаштованих реєстрах. |
--selector, -l | — | Селектор міток за мітками каталогу сутності, серед яких є її категорія (-l component.aggrega.ai/category=compute). |
Коли жоден реєстр не налаштовано
Пошук читає локальний індекс реєстрів, до яких налаштовано доступ на цій машині, тож
потрібен принаймні один із них. Якщо жоден не налаштовано, шукати ніде, і aggrega search
відмовляє замість відповіді: записує причину до стандартного потоку помилок, завершується з ненульовим кодом і
залишає стандартний вивід порожнім — у кожному форматі виводу, зокрема --output json.
Саме відмова розрізняє дві різні відповіді. Пошук, який виконався й нічого не знайшов,
завершується з кодом нуль і повідомляє (no matches) у стандартний вивід; пошук, який узагалі не зміг виконатися,
завершується з ненульовим кодом і нічого туди не повідомляє. Тому скрипт, що розгалужується за кодом завершення, може
відрізнити «цю сутність не опубліковано» від «на цій машині немає реєстру, до якого звернутися», чого повідомлення
у стандартному виводі з нульовим кодом виразити не може.
Виконайте aggrega config init, щоб зареєструвати реєстр разом із його політикою довіри до підписів, а потім
aggrega registry update, щоб побудувати локальний індекс, який читає пошук.
aggrega registry list і aggrega registry update реагують на ту саму ситуацію інакше, і
це навмисно. Перелік реєстрів, коли їх немає, — це повний перелік порожньої множини,
а побудові індексу, якій нічого обходити, нічого й не лишається робити: обидві операції завершені, тож
обидві звітують у стандартний вивід і завершуються з кодом нуль. Лише пошук повідомляє, що не зміг виконати
те, про що його просили.
Версія, яку повідомляє пошук
Стовпець VERSION містить версію, яку обрало б розв’язання. Версія, яку її видавець
відкликав, не повідомляється за умови, що відкликання має підпис, який перевіряє політика довіри цього робочого простору, — ті самі дві умови, що визначають, чи впливає відкликання на завантаження, тож
пошук і завантаження погоджуються щодо того, яка версія є відповіддю.
Відкликання, що не задовольняє будь-яку з умов, нічого не змінює в повідомленому. Маркер рекомендаційного рівня серйозності залишає свою версію доступною для вибору, а маркер, підпис якого не перевіряється, не є твердженням, на яке зважає цей робочий простір. В обох випадках найвища опублікована версія повідомляється точно так, як і без жодного маркера.
Сутність із відкликаною версією все одно показується. Стовпець NOTES називає пропущені
версії й з’являється лише в результаті, де є що повідомити. Сутність, у якої кожну
опубліковану версію відкликано, показується з (none) як версією та приміткою, що жодної
версії не лишилося, замість вилучення з результату — пропущену сутність було б
неможливо відрізнити від тієї, якої не існує.
Передайте --include-retracted, щоб повідомляти найвищу опубліковану версію незалежно від статусу
відкликання, — це відповідь на «що опубліковано?», а не на «що мені використовувати?». Це
змінює лише повідомлену версію; стовпець NOTES називає відкликані версії в обох
випадках.
Пошук читає локальний індекс, який записує aggrega registry update, тож повідомляє
те, що заявляв кожен реєстр на момент останньої побудови цього індексу. Версію, відкликану відтоді,
ще не записано, а рядок актуальності, що записується до стандартного потоку помилок, називає момент побудови кожного
індексу.
Машиночитаний результат
--output json передає той самий контракт у двох полях:
version— версія, яку обрало б розв’язання. Це порожній рядок, коли кожну опубліковану версію відкликано, і тоді поруч є списокretracted, що називає їх усі.retractedперелічує версії, пропущені під час цього вибору, у порядку зростання версій. Він відсутній, коли нічого не пропущено.
Споживач, який хоче знати, яку версію отримає, читає version. Виводити її натомість із
масиву deprecations означає заново реалізувати умови щодо серйозності та підпису, а
друга реалізація цих умов цілком може розійтися з тією, яку застосовує компілятор;
retracted повідомляє результат, який ці умови вже дали.
Кожен запис також містить published: кожну версію, яку записав індекс, у порядку зростання
версій, кожну з manifestDigest, на який розв’язувався її тег під час побудови індексу, і, якщо
політика довіри цього робочого простору перевірила власний підпис цієї версії, її signer — з кількох
перевірених той, який журнал прозорості записав найраніше. Версія без signer не має
підпису, перевіреного цією політикою, і більше про неї нічого не повідомляється.
Споживач, що читає вміст однієї версії, адресує його за цим дайджестом — наприклад,
aggrega inspect oci://<host>/<repository>@<digest> — тож читає саме ті байти, які записав індекс,
хоч би що потім сталося з тегом.
Якщо щось записує час публікації версії, її запис також містить publishedAt —
позначку часу RFC 3339 в UTC з точністю до секунди, і publishedAtSource, що вказує, звідки вона походить.
transparency-log — час, коли журнал прозорості записав безключовий підпис версії,
який політика довіри цього робочого простору перевірила разом із підписаною журналом обіцянкою щодо цього
часу, — підпис signer, найраніший із перевірених, тож повторне підписання версії
не змінює жодного з них. publisher — час, який публікація вказала поряд із опублікованим, за
власним годинником машини-видавця, що ніщо не засвідчує. Їх тримають окремо, щоб споживач,
який сортує за датою, усе одно міг відрізнити засвідчений час від заявленого. Версія без жодного з них
не має дати, і більше про неї нічого не повідомляється; див.
aggrega registry update, щоб дізнатися,
коли записується кожен із них.