İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

aggrega plugin

CLI’ın çözümleyebildiği Wasm eklentilerini inceler

Kullanım

aggrega plugin

Açıklama

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.

Alt komutlar

KomutAçıklama
aggrega plugin addKayıt defterinde adı verilen türde bir eklenti bulur ve onu ekler
aggrega plugin gen-catalogKonuk describe() çıktısından ve yazılmış bir katmandan Plugin katalog varlıkları üretir
aggrega plugin listCLI’ın çözümleyebildiği eklentileri describe() meta verileriyle listeler
aggrega plugin removeAdı verilen türde yapılandırılmış bir eklentiyi kaldırır
aggrega plugin run-localYerel bir .wasm konuğunu yükler ve dışa aktarımlarından birini çağırır
aggrega plugin syncBir eklentinin varlık dosyasındaki makineye ait kayıtları (ana makine işlevleri, CLI komutları) .wasm dosyasıyla eşitler

aggrega plugin add açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--accept-capabilitiesfalseBir cli eklentisinin bildirdiği yetenekleri etkileşimli istem olmadan kabul eder (yalnızca cli türü)
--capability—Sağlayıcı bağlamasının sunduğu yetenek (provider türü için zorunludur ve yalnızca onunla geçerlidir)
--dry-runfalseYazma dışında her şeyi yapar: ortaya çıkan yapılandırmayı, ait olduğu dosyayı belirterek içerik olarak döndürür ve hiçbir şey oluşturmaz ya da değiştirmez. Bu bayrak olmadan ek, çözümlenen yapılandırma dosyasına yazılır. cli türüyle kabul edilmez.
--globalfalseEki, tüm çalışma alanlarınca paylaşılan genel yapılandırmaya yazar.
--role—Yönetişim eki rolü: annotation-transform, label-transform, ir-verdict veya render-verdict (governance türü için zorunludur ve yalnızca onunla geçerlidir)
--workspacefalseEki bu projenin çalışma alanı yapılandırmasına yazar. Bir provider veya socket eki varsayılan olarak buraya yazılır; bir cli eklentisi varsayılan olarak genel yapılandırmaya yazılır.
--yesfalseEtkileşimsiz kullanım için cli yetenek onayı istemini atlar (yalnızca cli türü)

aggrega plugin gen-catalog açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--dry-runfalseYazma dışında her şeyi yapar: üretilen varlıkları, her birinin ait olduğu dosyayı belirterek içerik olarak döndürür ve hiçbir şey oluşturmaz ya da değiştirmez. Diğer tüm davranışlar yazmayla aynıdır; bu nedenle yazmanın reddedeceği bir seçim burada da reddedilir. Bu bayrak olmadan varlıklar —output-dir altına yazılır.
--from-embeddedfalsebu ikili dosyaya gömülü her konuk için bir varlık üretir
--output-dir—üretilen varlıkların altına yazıldığı dizin (zorunlu)
--overlay—yazılmış katman dizini (—from-embedded) veya dosyası (—plugin) (zorunlu)
--plugin—bu yoldaki .wasm konuğu için tek bir varlık üretir

aggrega plugin list açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--output, -otableÇıktı biçimi: table|json.

aggrega plugin remove açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--globalfalseTüm çalışma alanlarınca paylaşılan genel yapılandırmadan kaldırır.
--workspacefalseBu projenin çalışma alanı yapılandırmasından kaldırır. Bir provider veya socket eki varsayılan olarak buradan kaldırılır; bir cli komutu varsayılan olarak genel yapılandırmadan kaldırılır.

aggrega plugin run-local açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--export—çağrılacak bildirilmiş dışa aktarım
--plugin—.wasm yapıtının dosya sistemi yolu
--type—konuğun describe() öz bildiriminin eşleşmesi gereken eklenti türü
--with—dışa aktarım için yük: satır içi JSON veya bir dosyadan okumak için @; belirtilmezse varsayılan değer {}

aggrega plugin sync açıklaması

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 bayrakları

BayrakVarsayılanAçıklama
--plugin—İçe aktarımları ve describe() çıktısı kaydedilen ana makine işlevlerini ve komutları belirleyen, eklentinin .wasm yapıtının yolu

Bir içe aktarıcı girdisinin yaptığı iş

aggrega plugin add importer, eklentinin kimliğini ve onun için yayımlanmış en son sürümü ya da <name>:<version> olarak belirttiğiniz sürümü — importer/<name>:<version> — plugins.importer listesine yazar. Bu girdi, adını verdiği içe aktarıcıyı bağlar: içe aktarıcının duyurduğu bir biçimi isteyen bir içe aktarma, kataloğunuzdaki başka içe aktarıcılar da o biçimi duyursa bile o içe aktarıcıyı o sürümde çalıştırır ve girdinin with altında taşıdıkları yalnızca o içe aktarıcıya verilir. Bir kaynağı hangi içe aktarıcının taslaklara dönüştürdüğü girdiyi ayrıntılı olarak açıklar.

Bir içe aktarıcı tek bir girdiyle bağlanır; bu nedenle yazılan dosyanın plugins.importer listesinin zaten adını verdiği — herhangi bir sürümde ya da bir aralıkla — bir içe aktarıcıyı eklemek ikinci bir girdi eklemez. Komut bunun yerine o girdiyi çözümlediği sürüme taşır: girdi listedeki yerini ve with altında taşıdığı her şeyi korur. Bir içe aktarıcıyı girdisinin zaten adını verdiği sürümde eklemek girdiyi olduğu gibi bırakır.

Bir CLI eklentisinin komutları ve bayrakları

aggrega her başladığında, yapılandırılmış bir cli eklentisinin sağladığı her komut için bir komut ekler; komutları ve bayraklarını eklentinin describe() öz raporundan okur: describe önbelleği eklentinin sabitlenmiş özetini tutuyorsa oradan, aksi halde eklentiyi tanımlatarak. Bildirilen her bayrak kendi komutunda bildirilir; böylece aggrega help <command> onu yerleşik bir komutun bayraklarını listelediği gibi listeler. Eklenti yine de argümanlarını ayrıştırılmamış olarak alır ve kendi bayraklarını kendisi okur.

Sabitlenmiş özet, yapılandırmanın plugins.cli listesinde eklentinin referansının yanında yer alır ve sha256: ardından 64 küçük harfli onaltılık basamak olarak yazılır; bu, aggrega plugin add cli komutunun kaydettiği yazımdır. Başka bir biçimde yazılmış bir özet, örneğin sha256: öneki olmayan yalın onaltılık değer, yapılandırma dosyası yüklenirken dosya ve girdi belirtilerek reddedilir; düzeltilene kadar yapılandırılmış hiçbir eklentinin komutu eklenmez ve ret, standart hataya yazılan bir uyarıyla bildirilir.

aggrega, bir eklentinin komutlarından herhangi birini eklemeden önce her birinin bildirdiği her bayrağı denetler. Bildirimleri başarısız olan bir eklenti atlanır: komutlarından hiçbiri eklenmez, standart hataya eklentiyi, komutu, bayrağı ve bayraktaki sorunu belirten tek bir uyarı yazılır ve diğer tüm komutlar, yerleşik olsun ya da başka bir eklentiden gelsin, her zamanki gibi çalışır:

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

Bir bayrak bildirimi şu durumlarda geçer:

  • bayrağın bir adı vardır ve aynı komutun başka hiçbir bayrağı bu ada sahip değildir;
  • kısaltması, varsa, aynı komutun başka hiçbir bayrağının kullanmadığı tek bir ASCII harf ya da rakamdır;
  • ne adı ne de kısaltması, her aggrega komutunda zaten bulunan bir bayrağı (--help, -h ve genel bayraklar) yeniden kullanır;
  • türü, bildiriyorsa, string, bool ya da int olur; türü olmayan bir bayrak string bayrağıdır;
  • varsayılan değeri, bildiriyorsa, kendi türünde bir değerdir.

Atlama, uyarısıyla birlikte, yapılandırma eklentinin bildirimleri geçen bir sürümünü sabitleyene kadar her çağrıda yinelenir. Bir bayrak bildiriminin taşıdığı alanlar Plugin varlık sayfasında spec.commands altında açıklanır.

Varlık üretmek ve kayıt eşitlemek: iki farklı türde eylem

Bu alt komutlardan ikisi bir dosya üretir ve ürettikleri şey aynı türden değildir.

plugin gen-catalog — üretilen varlıkları siz düzenlersiniz

aggrega plugin gen-catalog, Plugin katalog varlıkları üretir. Bir varlık bir katalog belgesidir: onu dosyalar, gözden geçirir ve kataloğunuzun geri kalanıyla birlikte düzenlemeye devam edersiniz. Sahibi olduğunuz içerik olduğundan komut, onu diske yazmak yerine size teslim edebilir.

--dry-run, yazma dışında gen-catalog’un yaptığı her şeyi yapar. Üretilen varlıkları içerik olarak döndürür — hiçbir dosya oluşturulmaz, hiçbir dizin açılmaz — ve yanıttaki her belge hangi dosya için olduğunu belirtir; böylece çağıran taraf her birinin nereye ait olduğunu bilir. Bir düzenleyici gibi kendi belge modelini tutan bir çağıran, içeriği oraya koyar; orada onu kaydedilmeden önce görür, değiştirebilir veya geri alabilirsiniz. Bayrak olmadan varlıklar --output-dir altına yazılır, çünkü terminaldeki bir çağıranın onları koyabileceği daha iyi bir yer yoktur.

Döndürülen içerik ile yazılan baytlar aynı içeriktir: --dry-run, ayrıca derlenmiş bir önizleme değil, yazmanın üreteceği şeyi döndürür. Diğer her davranış da yazmanınkiyle aynıdır — aynı konuklar okunur, aynı katmanlar eşleştirilir ve --output-dir her iki durumda da gereklidir, çünkü döndürülen her belge yine hangi dosya için olduğunu belirtir ve bu yol ondan oluşturulur.

Herhangi biri teslim edilmeden önce her varlık oluşturulur ve doğrulanır; dolayısıyla bir çalıştırma ya kümenin tamamını üretir ya da hiçbir şey üretmez. Üretimi durduran bir katman — eksik olan ya da kimliği birleştirildiği konukla eşleşmeyen bir katman — arkasında temizlenecek kısmen yazılmış bir çıktı bırakmaz.

plugin sync — makineye ait kayıtlar derleyicinindir

aggrega plugin sync, bir plugin’in makineye ait kayıtlarını modülüyle uyumlu hâle getirir: modülün içe aktarma bölümünden türetilen ana makine işlevi kümesi ve plugin’in kendi öz raporundan okunan komut yansıması. Her ikisi de birinin seçtiği değerler değil, ikili dosyadaki temel gerçeklerdir.

Her zaman yazar ve --dry-run sunmaz. Bu, sizin yazdığınız bir varlık dosyasının içine yazmasına rağmen geçerlidir — sınır dosyaya göre değil, içeriğe göre çizilir. Derleyicinin kendisi hakkında tuttuğu kayıtları siz düzenlemezsiniz; bu nedenle yerleşmeden önce gözden geçirilecek bir şey yoktur. Çevreleyen belge bayt bayt dokunulmadan kalır ve yalnızca bu bloklar değişir.