Die owlat-plugins-CLI

@owlat/plugin-cli (Binary owlat-plugins) ist das Lifecycle-Werkzeug für den gebündelten Plugin-Satz. Es arbeitet auf dem eingecheckten Kompositionspunkt plugins.config.ts und delegiert jede Kompositionsentscheidung an @owlat/plugin-codegen — es implementiert Komposition niemals selbst nach.

Führen Sie es von einer beliebigen Stelle innerhalb des Owlat-Workspace aus. Aus einem Source-Checkout:

bun run plugins:prepare                        # build the plugin-kit contracts once
bun packages/plugin-cli/src/index.ts --help

owlat plugins — manage bundled Owlat plugins

Usage: owlat plugins <command> [options]

Commands:
  create <plugin-id> [--name <package>] [--dir <path>] [--template <name>]
         [--dry-run]
      Scaffold a new plugin package (never installs or executes code).
      --template minimal (default) emits an empty manifest; --template
      send-provider emits a complete send-transport bundle: send module,
      feedback webhook, sending-domain identity, capabilities and test stubs.
  add <package> [--dry-run]
      Add a bundled plugin package to plugins.config.ts and preview its
      capability diff. --dry-run previews without writing.
  remove <package> [--dry-run]
      Remove a bundled plugin package from plugins.config.ts.
  codegen [--check] [--boundaries-only]
      Regenerate (or check) the bundled composition via @owlat/plugin-codegen.
  dev
      Regenerate the composition and re-run on every plugins.config.ts change.

Run from anywhere inside the Owlat workspace.

Sicherheitseigenschaften

Diese gelten für jeden Befehl, und sie sind der Grund, warum die CLI gefahrlos gegen einen Produktions-Checkout laufen kann:

• Sie wertet plugins.config.ts niemals als Code aus. Die Konfiguration wird als statische Daten geparst.
• Sie importiert niemals einen beliebigen Pfad. Das einzige Laden von Modulen, das sie durchführt, wird an den verifizierten Loader der Codegen delegiert, der ausschließlich den lockfile-gepinnten, provenance-geprüften Manifest-Eintrag jedes gebündelten Packages importiert — niemals ein Contribution- oder Komponentenmodul.
• Validierung geht der Mutation voraus. Der vorgeschlagene Package-Satz wird vollständig geladen und validiert, bevor irgendeine Datei geschrieben wird; ein fehlendes, falsch gepinntes oder ungültiges Package schlägt mit einem umsetzbaren Fehler und unveränderter Konfiguration fehl.
• Änderungen sind deterministisch und idempotent. Ein erneuter Lauf erzeugt byte-identische Ausgabe; ein bereits gelistetes add (oder ein nicht vorhandenes remove) ist eine gemeldete No-op, die nichts schreibt.
• Fehlschläge werden zurückgerollt. create entfernt jede angelegte Datei und jedes angelegte Verzeichnis, wenn ein Schreibvorgang fehlschlägt; ein fehlgeschlagenes Schreiben der Konfiguration lässt die Konfiguration unverändert.

create

owlat-plugins create hello-owlat [--name @acme/owlat-hello] [--dir plugins/hello] [--dry-run]

Scaffoldet ein Plugin-Package: package.json, tsconfig.json, vitest.config.ts, README.md, src/manifest.ts, src/index.ts sowie einen Manifest-Test. Der Inhalt ist eine reine Funktion aus Id, Package-Name und der Position des Verzeichnisses im Workspace — keine Zeitstempel, keine Zufälligkeit.

Defaults: --name @owlat/plugin-<id>, --dir examples/plugins/<id>. Ein erneuter Lauf auf einem unveränderten Scaffold ist eine No-op; eine Datei, die mit anderem Inhalt existiert, bricht den Lauf ab, statt sie zu überschreiben.

add / remove

owlat-plugins add @vendor/owlat-plugin-example --dry-run
owlat-plugins add @vendor/owlat-plugin-example
owlat-plugins remove @vendor/owlat-plugin-example

Beide geben vor dem Schreiben ein Capability-Diff aus: die hinzugefügten oder entfernten Plugins sowie die Capabilities, die die Komposition als Vereinigung über den gebündelten Satz hinweg gewinnt oder verliert. Lesen Sie dieses Diff — für ein gebündeltes Plugin ist es die vollständige Liste der Host-Operationen, die das Package jemals anfordern kann.

--dry-run gibt das Diff sowie die exakte vorgeschlagene plugins.config.ts aus und schreibt nichts.

Wenn der aktuelle Satz nicht geladen werden kann — zum Beispiel weil das Package, das Sie entfernen, selbst defekt ist —, wird der vorgeschlagene Satz dennoch validiert und die Mutation dennoch ausgeführt; das Diff meldet den Vorher-Zustand als nicht verfügbar, statt stillschweigend irreführende Arithmetik anzuzeigen.

codegen

owlat-plugins codegen                  # regenerate the composition files
owlat-plugins codegen --check          # fail if output is missing or stale (CI)
owlat-plugins codegen --boundaries-only  # only enforce the import boundary

Generiert die eingecheckten Convex- und Nuxt-Kompositionsmodule, den Convex-Component-Installer sowie jedes Contribution-Katalog/Registry-Paar neu. --boundaries-only erzwingt die Regel, dass Core-Quellcode ein konfiguriertes Plugin-Package außerhalb dieser generierten Dateien nicht importieren darf — auch nicht über Node-/Bun-Loader oder Repository-Aliase —, und zwar ohne selbst Plugin-Code zu importieren.

Äquivalente Workspace-Skripte, die CI und der Build-Graph ausführen:

bun run plugins:codegen        # regenerate
bun run plugins:check          # --check
bun run lint:plugin-imports    # --boundaries-only

bun run plugins:check ist Teil von ci:lint, ci:verify sowie der Turbo-Tasks build und deploy, sodass eine veraltete oder ungültige Komposition den Build fail-closed abbrechen lässt.

dev

owlat-plugins dev

Generiert die Komposition neu und führt sie bei jeder Änderung an plugins.config.ts erneut aus. Nützlich beim Iterieren am gebündelten Satz; es ersetzt nicht das Committen der generierten Ausgabe.

Commit-Disziplin

Generierte Kompositionsdateien sind eingecheckt. Committen Sie die Konfigurationsänderung und die neu generierte Ausgabe immer zusammen — ein generiertes Artefakt gehört in denselben Commit wie die Eingabe, die es erzeugt hat, und andernfalls lässt plugins:check die CI fehlschlagen.