コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

aggrega plugin

CLI が解決できる Wasm プラグインを検査します

概要

aggrega plugin

説明

Work with the WebAssembly plugins this CLI can resolve.
All of Aggrega's provider-specific and policy-specific behaviour lives in Wasm
plugins rather than in the binary, so this is where you see which ones are
reachable, add or remove a workspace binding, and check a guest before you
publish it.
Plugins reach the CLI two ways. Some are compiled into the binary and resolve
with no filesystem, cache or network access. The rest are workspace bindings in
.aggrega-config.yaml, resolved through the plugin cascade. "aggrega plugin list"
shows both groups together.
The subcommands below cover the whole life of a binding: list what is reachable,
add and remove bindings, run a local guest export directly, sync the
machine-owned records in a Plugin entity with its .wasm, and generate Plugin
catalog entities from a guest's own metadata.

サブコマンド

コマンド説明
aggrega plugin addレジストリで指定した種類のプラグインを見つけて追加します
aggrega plugin gen-catalogゲストの describe() と作成済みのオーバーレイから Plugin カタログエンティティを生成します
aggrega plugin listCLI が解決できるプラグインを describe() メタデータとともに一覧表示します
aggrega plugin remove指定した種類の設定済みプラグインを削除します
aggrega plugin run-localローカルの .wasm ゲストを読み込み、そのエクスポートの 1 つを呼び出します
aggrega plugin syncエンティティファイル内のプラグインの機械所有レコード(ホスト関数、CLI コマンド)をその .wasm と同期します

aggrega plugin add の説明

Find a plugin of the named type in the configured registry and add it to your
configuration.
Examples:
aggrega plugin add cli moo # add the moo command
aggrega plugin add cli moo:0.2.4 # a specific version
aggrega plugin add governance rego --role render-verdict
Arguments:
<type> The plugin socket to add for. One of: provider, governance,
linter, importer, or cli. The governance type requires --role.
<query> The plugin's name, optionally followed by :<version> to add that
version rather than the latest published one. The name is looked
up directly first. Where no plugin of the chosen type has that name,
it is matched as a case-insensitive substring against the plugin
names of that type, which reads the registry's whole catalog and
must resolve to exactly one plugin — otherwise the command lists the
candidates so you can narrow it. A query naming a version is never
matched that way. The provider type takes no version.
What add writes depends on the type:
- A socket type (governance, linter, importer) pins the version the query
names, or else the latest published version, and adds the bare plugin
identity (<type>/<name>:<version>) to the plugins.<type> list. The latest
is never taken from pre-release versions, so a plugin that publishes only
those is added by naming one. A governance entry also records its --role,
one of annotation-transform, label-transform, ir-verdict, or render-verdict.
An importer the plugins.importer list already names keeps its one entry,
moved to the pinned version with its place and what it carries under with.
- The provider type adds a plugins.providers entry naming the plugin by its
bare identity (provider/<name>) with no version; --capability names the
capability the binding serves, preserving existing settings. The version is
the one the Recipe pins, or else the highest available, and the lockfile
records the one a pull chose.
- The cli type fetches the plugin from the registry, verifies it, and caches
its bytes, then pins it into the plugins.cli list as a top-level aggrega
command — no separate pull step. Its resolved reference and the content
digest of the verified bytes are recorded so the command runs those exact
bytes, resolving from the local cache on later runs with no further network
access. A cli plugin defaults to the global config, so its command is
available in every workspace; --workspace pins it to this project instead.
It needs no workspace: run outside one, its bytes are cached in the
machine-wide cache rather than in the folder you ran it in. Its declared
capabilities are confirmed before installing, and --accept-capabilities or
--yes skips that prompt for non-interactive use.
A provider or socket attachment is written to a workspace's own configuration
unless --global is passed, so outside a workspace it is refused before the
registry is reached; so is anything else that can be refused without it.
A provider or socket attachment is configuration you go on editing, so --dry-run
does everything the plain command does except write: it hands back the
configuration the write would have produced, creating and modifying nothing. The
answer names the file that content is for — which matters here, because a
--global attachment targets the config shared across every workspace. A caller
that keeps its own document model puts the content there, where it is visible
before it is saved and can be amended or undone. The registry is still searched,
and for a socket type the version still resolved, since the returned document
carries the identity a write would have written.
Under --dry-run standard output carries that content and nothing else, so it stays
parseable; a version substitution is announced on standard error instead. The cli
type does not accept --dry-run: what it records is the content digest of the bytes
it verified, which is a record the machine maintains rather than content you
edit.

aggrega plugin add のフラグ

フラグデフォルト説明
--accept-capabilitiesfalse対話式プロンプトなしで cli プラグインが宣言したケイパビリティを受け入れます(cli タイプのみ)
--capability—provider バインディングが提供するケイパビリティ(provider タイプでは必須で、provider タイプでのみ有効)
--dry-runfalse書き込み以外のすべてを行います。結果の設定を対象ファイル名とともにコンテンツとして返し、何も作成・変更しません。指定しない場合、アタッチメントは解決された設定ファイルに書き込まれます。cli タイプでは使用できません。
--globalfalseすべてのワークスペースで共有されるグローバル設定にアタッチメントを書き込みます。
--role—governance アタッチメントのロール:annotation-transform、label-transform、ir-verdict、または render-verdict(governance タイプでは必須で、governance タイプでのみ有効)
--workspacefalseこのプロジェクトのワークスペース設定にアタッチメントを書き込みます。provider または socket のアタッチメントはデフォルトでここに書き込まれ、cli プラグインはデフォルトでグローバル設定に書き込まれます。
--yesfalse非対話的な使用のために cli のケイパビリティ確認プロンプトをスキップします(cli タイプのみ)

aggrega plugin gen-catalog の説明

Generate one Plugin entity per selected Wasm guest.
Each entity's contract fields — pluginType, abiVersion, capabilities, exports,
and contract — are derived from the guest's describe() self-report, so the
entity can never promise a capability the binary does not provide. The entity's
identity (metadata.name), runtime limits, and provider block come from an authored
per-plugin overlay; the entity version is the guest's describe() self-report
version. The plugin-level description, when the guest reports one, is emitted as
metadata.description and omitted cleanly when it does not.
Two selection modes:
--from-embedded generate an entity for every guest embedded in this binary.
The overlay path is a directory; each overlay is matched to
a guest by its metadata.name identity, and, where overlays
in several socket directories (<socket>/<name>.yaml)
declare one name, by the directory naming the guest's
socket.
--plugin <f.wasm> generate a single entity for one non-embedded guest. The
overlay path is a single overlay file.
The output is written under <output-dir>/<pluginType>/<name>/<version>/plugin.yaml
and carries a generated-output banner. The leading pluginType segment keeps two
same-named plugins in different sockets apart, since a bare plugin name is unique
only within its own socket. Regenerating over unchanged inputs yields
byte-identical files.
A generated entity is a catalog document you own and go on editing, so --dry-run
does everything gen-catalog does except write: it hands the content back, creating
and modifying nothing, and the answer names the file each document is for. A
caller that keeps its own document model — an editor, for instance — puts the
content there, where it is visible before it is saved and can be amended or
undone. Every other behaviour is the write's — the same guests are read and the
same overlays matched — so a selection gen-catalog would refuse is refused under
--dry-run too. Without the flag the entities are written, because a caller at a
terminal has nowhere better to put them.

aggrega plugin gen-catalog のフラグ

フラグデフォルト説明
--dry-runfalse書き込み以外のすべてを行います。生成したエンティティをそれぞれの対象ファイル名とともにコンテンツとして返し、何も作成・変更しません。その他の動作はすべて書き込み時と同じであるため、書き込みで拒否される選択はここでも拒否されます。指定しない場合、エンティティは —output-dir 配下に書き込まれます。
--from-embeddedfalseこのバイナリに埋め込まれたすべてのゲストについてエンティティを生成します
--output-dir—生成したエンティティを書き込むディレクトリ(必須)
--overlay—作成済みのオーバーレイのディレクトリ(—from-embedded)またはファイル(—plugin)(必須)
--plugin—このパスにある .wasm ゲストについて単一のエンティティを生成します

aggrega plugin list の説明

List every Wasm plugin the CLI can see and, for each, its self-reported
describe() metadata.
Two groups are printed. Embedded built-ins are the provider and linter guests
compiled into the binary; they resolve with no filesystem, cache, or network
access. Configured plugins are the workspace bindings — the provider and linter
bindings and the CLI-extension commands — resolved through the plugin cascade.
Each plugin's type appears in the TYPE column, so a CLI-extension command
(type cli) is legible alongside the socket plugins; a CLI plugin also carries a
status of its own — ready, unresolved, describe-failed, or digest-drift when
its bytes changed since it was pinned at install.
The default output is a scannable table with one row per plugin, showing its
type, name, served capabilities, and version. The output is read-only and
deterministic. A plugin that fails to resolve or describe is listed with its
failure status rather than halting the whole listing.
With -o json, the output is a structured object carrying the full per-plugin
detail — type, name, version, commit, capabilities, input kinds, boundary
assembly, exports, origin, readiness, and any resolve or describe error —
grouped as embedded and configured. It is suitable for programmatic
consumption and documentation generation.

aggrega plugin list のフラグ

フラグデフォルト説明
--output, -otable出力形式:table|json。

aggrega plugin remove の説明

Remove a configured plugin of the named type from a config file so it no longer
participates.
The type is one of provider, governance, linter, importer, or cli — the same
set 'plugin add' accepts. The query identifies the entry to remove: the plugin's
short name (matched against 'add's short name so remove is symmetric with add),
its full pinned reference, or, for the provider type, the capability the binding
serves. A query that matches nothing halts and leaves the config untouched, so a
typo never silently removes the wrong plugin.
A provider or socket attachment defaults to this project's workspace config; a cli
command defaults to the global config shared across every workspace. --global and
--workspace force the file the removal targets, overriding the default.

aggrega plugin remove のフラグ

フラグデフォルト説明
--globalfalseすべてのワークスペースで共有されるグローバル設定から削除します。
--workspacefalseこのプロジェクトのワークスペース設定から削除します。provider または socket のアタッチメントはデフォルトでここが対象となり、cli コマンドはデフォルトでグローバル設定が対象となります。

aggrega plugin run-local の説明

Load a .wasm guest from a filesystem path, call one of its declared
exports with an optional payload, and write the guest's answer to stdout.
The guest is addressed directly by --plugin path; it is not resolved through
the workspace plugin cascade. The export named by --export must be one the
guest advertises in its describe() self-report, or the call is rejected before
the guest runs.
The command has two forms. The artifact form takes no positional argument and
loads the guest bare. The entity form takes a Plugin entity file as its one
positional argument: the entity is schema-validated, and its declared
metadata.pluginType and export contract are cross-checked against the guest's
describe() before the guest runs. In both forms the guest bytes come from
--plugin; the entity carries no artifact path.
The payload is supplied with --with, and it is always written as JSON. A value
beginning with @ reads the payload bytes from a file (--with @input.json); any
other value is taken as a literal inline JSON payload (--with '{"k":1}'). When
--with is omitted, the export receives the minimal empty JSON object {}. The
resolved payload is validated as JSON before the guest runs, so malformed input
is reported up front.
An export a socket calls with a payload reads it in a binary encoding rather
than as JSON; a CLI plugin's cli_run export is the exception, and reads JSON.
Which encoding an export reads is fixed by the socket that export serves, so no
flag selects it: the resolved payload is converted into the encoding the named
export reads before the guest is called. The conversion reads the payload's
shape from the export's name, so it covers each export a socket calls by
default; an entry function an attachment or a pipeline step names under a name
of its own receives the payload as written. The authored payload stays JSON
either way.
The answer is converted the same way in reverse. An export a socket calls
answers in that binary encoding, so its answer is read as the export's output
shape and written to stdout as indented JSON; an answer that is not that shape
is reported as an error naming the export rather than printed. A cli_run
export's answer, and an entry function under a name of its own, are written to
stdout exactly as the guest wrote them. When the guest exits non-zero, what it
wrote is passed through unchanged.
In the artifact form, --type optionally names a plugin type the guest's
describe() self-report must agree with, or the load is rejected before the
guest runs; when omitted, no type expectation is imposed. In the entity form
--type is rejected, because the entity's metadata.pluginType supplies the type.
The guest's clean exit code becomes this command's exit status, so a failure
inside the plugin is distinguishable from a failure of aggrega itself.

aggrega plugin run-local のフラグ

フラグデフォルト説明
--export—呼び出す宣言済みのエクスポート
--plugin—.wasm アーティファクトへのファイルシステムパス
--type—ゲストの describe() の自己申告が一致すべきプラグインの種類
--with—エクスポートへのペイロード:インライン JSON、またはファイルから読み込む場合は @。省略時のデフォルトは {}

aggrega plugin sync の説明

Sync a plugin's machine-owned records in a Plugin entity file with its .wasm.
Two records are not authored by hand: the set of host functions a plugin may
call, derived from the plugin's .wasm import section, and the top-level commands a
CLI plugin contributes, read from the plugin's describe() self-report. Both are
ground truth in the binary. This command reads the .wasm, derives the
host-function set in canonical form and the command mirror in describe()-declared
order, and aligns the entity's spec.runtime.hostFunctions and spec.commands with
them — creating the runtime block when the file has none. Only those blocks
change; every comment, blank line, and other field is preserved byte-for-byte. A
plugin that imports no host functions or contributes no commands records an
explicit empty list, so each field is always present and reviewable.
The write is idempotent: re-running when the records already match the .wasm
leaves the file untouched. Commit the result; publish (aggrega push) then only
verifies the committed records against the .wasm and refuses to publish a file
whose records are out of sync with its binary.

aggrega plugin sync のフラグ

フラグデフォルト説明
--plugin—プラグインの .wasm アーティファクトへのパス。そのインポートと describe() によって、記録されるホスト関数とコマンドが決まります

importer エントリの役割

aggrega plugin add importer は、プラグインの識別子と、そのプラグインについて公開されている最新バージョン、または <name>:<version> として指定したバージョン(importer/<name>:<version>)を plugins.importer リストに書き込みます。このエントリは、指定したインポーターをアタッチします。そのインポーターが提示するフォーマットを求めるインポートは、カタログ内の他のインポーターが同じフォーマットを提示している場合でも、そのバージョンのそのインポーターを実行します。また、エントリが with の下に持つ内容を受け取るのは、そのインポーターだけです。エントリの詳細はソースをドラフトに変換するインポーターで説明しています。

インポーターは 1 つのエントリによってアタッチされるため、書き込み対象のファイルの plugins.importer リストがすでに指定しているインポーターを追加しても(どのバージョンであっても、範囲指定であっても)、2 つ目のエントリは追加されません。代わりに、コマンドはそのエントリを解決したバージョンに移します。エントリはリスト内の位置と、with の下に持つすべての内容を保持します。エントリがすでに指定しているバージョンでインポーターを追加した場合、エントリはそのまま変更されません。

CLI プラグインのコマンドとそのフラグ

aggrega は起動するたびに、設定された cli プラグインが提供するコマンドごとに 1 つのコマンドを追加します。コマンドとそのフラグは、プラグインの describe() の自己報告から読み取ります。describe キャッシュがプラグインの固定されたダイジェストを保持している場合はキャッシュから、そうでない場合はプラグインを describe して読み取ります。宣言された各フラグはそのコマンド上で宣言されるため、aggrega help <command> は組み込みコマンドのフラグと同じようにそれを一覧表示します。ただし、プラグインは引数を解析されないまま受け取り、自身のフラグを自分で読み取ります。

固定されたダイジェストは、設定の plugins.cli リストでプラグインの参照の隣に置かれ、sha256: の後に 64 桁の小文字の 16 進数が続く形で書かれます。これは aggrega plugin add cli が記録する表記です。sha256: 接頭辞のない 16 進数のみなど、それ以外の表記のダイジェストは、設定ファイルの読み込み時にファイルとエントリを示して拒否されます。修正されるまで、設定されたどのプラグインのコマンドも追加されず、標準エラーへの警告がその拒否を伝えます。

aggrega は、プラグインのコマンドを追加する前に、各コマンドが宣言するすべてのフラグを検査します。宣言が検査に失敗したプラグインはスキップされます。そのコマンドはどれも追加されず、標準エラーへの 1 つの警告がプラグイン、コマンド、フラグ、およびその問題点を示し、組み込みか別のプラグインからかを問わず、他のすべてのコマンドは通常どおり実行されます。

warning: CLI plugin "oci://hub.aggrega.ai/plugin/cli/greet:1.2.0" was not added as a command: its command "greet" declares the flag "--verbose" with the shorthand "vv"; a shorthand is a single ASCII letter or digit

フラグの宣言は、次の場合に検査を通過します。

  • フラグに名前があり、同じコマンドの他のどのフラグもその名前を持たない。
  • 短縮形がある場合、それが 1 文字の ASCII 英字または数字であり、同じコマンドの他のどのフラグも使用していない。
  • 名前も短縮形も、すべての aggrega コマンドが既に持つフラグ(--help、-h、およびグローバルフラグ)を再利用していない。
  • 型を宣言する場合、それが string、bool、int のいずれかである。型のないフラグは文字列フラグになる。
  • デフォルト値を宣言する場合、それがその型の値である。

このスキップは、宣言が検査を通過するバージョンのプラグインを設定が固定するまで、呼び出しのたびに警告とともに繰り返されます。フラグの宣言が持つフィールドについては、Plugin エンティティのページの spec.commands で説明しています。

エンティティの生成とレコードの同期:2 つの異なる種類の操作

これらのサブコマンドのうち 2 つはファイルを生成しますが、生成するものの種類は同じではありません。

plugin gen-catalog — 生成されたエンティティは利用者が編集するものです

aggrega plugin gen-catalog は Plugin のカタログエンティティを生成します。エンティティはカタログのドキュメントです。ファイルとして保存し、レビューし、カタログの他の部分とともに編集を続けます。利用者が所有するコンテンツであるため、コマンドはそれをディスクに書き込む代わりに利用者へ渡すことができます。

--dry-run は、書き込み以外のすべてを gen-catalog と同じように行います。生成されたエンティティをコンテンツとして返し(ファイルもディレクトリも作成されません)、応答内の各ドキュメントは対象となるファイルを示すため、呼び出し側はそれぞれの配置先を把握できます。エディタのように独自のドキュメントモデルを持つ呼び出し側は、コンテンツをそこに配置します。そこでは保存前に内容を確認し、修正や取り消しができます。このフラグがない場合、エンティティは --output-dir の下に書き込まれます。ターミナルの呼び出し側には、それ以上に適した置き場所がないためです。

返される内容と書き込まれるバイト列は同じ内容です。--dry-run は書き込みが生成したはずのものを返すのであり、別途組み立てられたプレビューを返すのではありません。その他のすべての動作も書き込み時と同じです。同じゲストが読み込まれ、同じオーバーレイが照合されます。また、どちらの場合も --output-dir が必須です。返される各ドキュメントは、それが対象とするファイルを依然として指定しており、そのパスはこのフラグから組み立てられるためです。

すべてのエンティティは、いずれかが渡される前に組み立てと検証が行われるため、1 回の実行ではセット全体が生成されるか、何も生成されないかのどちらかです。生成を停止させるオーバーレイ(存在しないもの、またはマージ対象のゲストと ID が一致しないもの)があっても、後片付けが必要な中途半端な出力は残りません。

plugin sync — マシン所有のレコードはコンパイラのものです

aggrega plugin sync は、プラグインのマシン所有のレコードをそのモジュールと一致させます。対象は、モジュールのインポートセクションから導出されるホスト関数セットと、プラグイン自身のセルフレポートから読み取られるコマンドミラーです。どちらも誰かが選ぶ値ではなく、バイナリ内にある実際の事実です。

このコマンドは常に書き込みを行い、--dry-run は提供しません。利用者が作成したエンティティファイルに書き込む場合でも同様です。境界はファイルではなくコンテンツで引かれています。コンパイラが自身について管理するレコードは利用者が編集するものではないため、反映前にレビューすべきものはありません。周囲のドキュメントはバイト単位でそのまま保たれ、変更されるのはそれらのブロックだけです。