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 の機能です。複数回指定できます。いずれか 1 つを宣言しているレコードが残されます。 |
--include-retracted | false | 検証済みのマーカーが撤回している場合でも、公開されている最も高いバージョンを報告します。デフォルトでは、報告されるバージョンは解決で選ばれるバージョンです。 |
--kind | [] | 照合するエンティティの種類(component|feature|recipe|featurerecipe|workload|plugin)。繰り返し指定できます。いずれか 1 つに一致するレコードが残されます。大文字と小文字を区別しません。 |
--limit | 0 | 結果の件数の上限(0 は上限なしを意味します)。 |
--output, -o | table | 出力形式: table|json|names。 |
--plugin-type | — | 照合する Plugin のソケットタイプです(例: provider、governance、linter)。 |
--registry | — | ホストまたはフレンドリーエイリアスで指定したこのレジストリのみを検索します。デフォルトでは、設定済みのすべてのレジストリを検索します。 |
--selector, -l | — | エンティティのカタログラベルに対するラベルセレクタ。カタログラベルにはカテゴリが含まれます(-l component.aggrega.ai/category=compute)。 |
レジストリが設定されていない場合
検索は、このマシンが到達するよう設定されているレジストリのローカルインデックスを読み取るため、
少なくとも 1 つのレジストリが必要です。1 つも設定されていなければ検索先がないため、aggrega search
は応答せずに拒否します。理由を標準エラーに書き出し、0 以外のステータスで終了し、
標準出力を空のままにします。これは --output json を含むすべての出力形式で同じです。
この拒否によって、2 つの異なる応答が区別されます。実行されて何にも一致しなかった検索は
0 で終了し、標準出力に (no matches) を報告します。そもそも実行できなかった検索は
0 以外で終了し、標準出力には何も報告しません。そのため、終了ステータスで分岐するスクリプトは
「このエンティティは公開されていない」と「このマシンには問い合わせるレジストリがない」を区別できます。標準出力への通知と
0 のステータスでは、この区別は表現できません。
aggrega config init を実行してレジストリをその署名トラストポリシーとともに登録し、次に
aggrega registry update を実行して検索が読み取るローカルインデックスを構築します。
aggrega registry list と aggrega registry update は同じ状況に対して異なる応答をしますが、
これは意図的なものです。レジストリが 1 つもないときのレジストリ一覧は空集合の完全な一覧であり、
たどる対象のないインデックス構築にはやるべきことが残っていません。どちらも完了した操作なので、
どちらも標準出力に報告して 0 で終了します。求められたことを実行できなかったと報告するのは
検索だけです。
検索が報告するバージョン
VERSION 列には、解決で選ばれるバージョンが入ります。公開者が撤回したバージョンは、
その撤回がこのワークスペースのトラストポリシーで検証される署名を持つ場合、報告されません。これは撤回が
pull に影響するかどうかを決める 2 つの条件と同じであり、そのため検索と pull はどのバージョンが答えになるかについて一致します。
いずれかの条件を満たさない撤回は、報告内容を何も変えません。勧告レベルの重大度のマーカーは そのバージョンを選択可能なままにし、署名が検証されないマーカーは、このワークスペースが 従う主張ではありません。どちらの場合も、公開されている最も高いバージョンが、 マーカーがまったくない場合とまったく同じように報告されます。
撤回されたバージョンを持つエンティティも引き続き一覧に表示されます。NOTES 列が除外された
バージョンを示し、この列は報告すべき内容がある結果にのみ表示されます。公開されたすべての
バージョンが撤回されたエンティティは、結果から除外されるのではなく、バージョンとして (none) と、
残っているバージョンがないことを示す注記とともに報告されます。除外されたエンティティは、
存在しないエンティティと区別できなくなるためです。
--include-retracted を渡すと、撤回の状態にかかわらず公開されている最も高いバージョンが報告されます。
これは「何を使うべきか」ではなく「何が公開されているか」への答えです。
変わるのは報告されるバージョンだけで、NOTES 列はどちらの場合も撤回されたバージョンを
示します。
検索が読み取るのは aggrega registry update が書き出すローカルインデックスであるため、
そのインデックスが最後に構築された時点で各レジストリが示していた内容を報告します。それ以降に撤回されたバージョンは
まだ記録されておらず、標準エラーに書き出される鮮度の行が、各
インデックスが構築された時点を示します。
機械可読な結果
--output json は、同じ取り決めを 2 つのフィールドで伝えます。
versionは、解決で選ばれるバージョンです。公開されたすべてのバージョンが撤回されている場合は 空文字列になり、それらすべてを示すretractedリストと対になります。retractedは、その選択から除外されたバージョンをバージョンの昇順で列挙します。 何も除外されなかった場合は存在しません。
どのバージョンを取得するかを問うコンシューマは version を読み取ります。代わりに
deprecations 配列からそれを導き出すと、重大度と署名の条件を再実装することになり、
それらの条件の 2 つ目の実装はコンパイラが適用する実装と食い違う可能性があります。
retracted は、それらの条件がすでに生み出した結果を報告します。
各レコードには published も含まれます。これはインデックスが記録したすべてのバージョンをバージョンの昇順で
列挙したもので、それぞれに、インデックス構築時にそのタグが解決された manifestDigest と、
このワークスペースのトラストポリシーがそのバージョン自身の署名を検証した場合はその signer が含まれます。検証される署名が
複数ある場合は、透明性ログが最も早く記録したものです。signer のないバージョンには、
そのポリシーが検証した署名がなく、それ以上の情報はありません。
1 つのバージョンの内容を読み取るコンシューマは、そのダイジェストで指定します。例:
aggrega inspect oci://<host>/<repository>@<digest>。これにより、その後タグに何が起きても、
読み取るのはインデックスが記録したバイト列になります。
バージョンの公開日時を記録しているものがある場合、そのエントリには publishedAt(UTC で秒単位の
RFC 3339 タイムスタンプ)と、その出所を示す publishedAtSource も含まれます。
transparency-log は、透明性ログがそのバージョンのキーレス署名を記録した時刻であり、
このワークスペースのトラストポリシーが、その時刻に対するログの署名付きの約束とともに検証したものです。
対象は signer の署名、つまり検証される署名のうち最も早いものであるため、バージョンに再度署名しても
どちらも変わりません。publisher は、公開物が公開内容とともに示した時刻で、
公開したマシン自身の時計によるものであり、何も証明していません。日付で並べ替えるコンシューマが
証明された時刻と示されただけの時刻を区別できるよう、両者は分けて保持されます。どちらもないバージョンには
日付がなく、それ以上の情報はありません。それぞれがいつ記録されるかについては
aggrega registry update を
参照してください。