CLI-Provider

CLI-Provider

Ein Plugin klinkt sich in den Build-Lifecycle ein - Config, Nav, Seiten-Markdown/HTML, Post-Build. Ein CLI-Provider ist der Schwester-Erweiterungspunkt für den Command-Lifecycle: Er erlaubt es einem installierten, aktivierten BoxLang-Modul, eigene bxSites <verb>- Befehle zu registrieren, ohne bx-sites selbst anzufassen.

Dasselbe Aktivierungsmodell wie ein Plugin - ein Modul meldet sich über bxsites.yamls eigenes plugins-Array namentlich an:

plugins: [ myBxSitesAddon ]

Ein Modul kann models/BxSitesPlugin.bx, models/BxSitesCliProvider.bx, beides oder keines von beidem implementieren - ein Modul zu installieren/ aktivieren ist ein Schritt; welche Contracts es implementiert, entscheidet, was es tatsächlich erweitert.

Einen CLI-Provider schreiben

Ein CLI-Provider braucht genau eine Sache zusätzlich zu den üblichen box.json/ModuleConfig.bx: eine Klasse models/BxSitesCliProvider.bx, die eine einzelne Methode verbs() bereitstellt, die einen Struct Verbname → Dispatch-Info zurückgibt:

// models/BxSitesCliProvider.bx
class {

	struct function verbs() {
		return {
			"cloud:publish" : {
				class       : "models.cli.cloud.Publish@myBxSitesAddon",
				description : "Build (if needed) and publish via the configured deploy target"
			},
			"cloud:status" : {
				class       : "models.cli.cloud.Status@myBxSitesAddon",
				description : "Show license/entitlement and last deploy status"
			}
		}
	}

}

Jede Dispatch-Klasse folgt genau derselben Form wie eine Core-Verb-Klasse unter bx-sitess eigenem models/cli/ - eine struct function run( struct options ), die { exitCode, message } zurückgibt:

class {
	struct function run( struct options ) {
		// arguments.options carries the same parsed-flags-plus-projectRoot
		// shape every core verb receives - see the CLI reference's
		// "How dispatch works" section.
		return { exitCode : 0, message : "Published #arguments.options.projectRoot#" }
	}
}

Das Suffix @myBxSitesAddon ist erforderlich

Ein reiner Punktpfad wie "models.cli.cloud.Publish" löst sich nur relativ zu bx-sitess eigenem Modul-Root auf - so verweisen Core-Verben auf models/cli/Build.bx und ähnliche, aber er kann nicht in ein anderes Modul hineinreichen. Die eigenen Verb-Klassen eines Providers müssen daher immer selbst das Suffix @<mapping> ihres eigenen Moduls mitliefern, genau wie oben gezeigt. Das ist auch der Grund, warum sich kein Provider in bx-sitess eigene, wörtliche Verb-Tabelle einschmuggeln kann - der Klassenpfad muss sein eigenes Modul explizit benennen.

Verb-Namen: Ein-Token und Zwei-Token ("compound")

Ein Verb-Name wird als eine einzige, durch Doppelpunkt verbundene Zeichenkette registriert - dieselbe Konvention, die Core bereits für post:new/i18n:status/page:rename verwendet. bxSites akzeptiert außerdem die äquivalenten zwei durch Leerzeichen getrennten Argv-Tokens als Zucker über dieselbe Registrierung - bxSites cloud publish und bxSites cloud:publish dispatchen identisch, sobald "cloud:publish" ein registrierter Verb-Name ist. Es gibt keinen separaten Zweiwort-Registrierungsmechanismus zu lernen; registrieren Sie "cloud:publish", und beide Schreibweisen funktionieren automatisch.

Vorrang und Fehlerfälle

• Core gewinnt immer. Registriert ein Provider einen Verb-Namen, der mit einem der eingebauten Verben von bx-sites kollidiert, wird das Core-Verb dispatcht und der Eintrag des Providers wird stillschweigend ignoriert - ein Provider kann neue Befehle hinzufügen, aber nie einen bestehenden überschatten.
• Bei einer Kollision zwischen zwei Providern gewinnt der erste. Wenn zwei verschiedene aktivierte Module denselben Verb-Namen registrieren, gewinnt derjenige, der in bxsites.yamls plugins-Array zuerst aufgeführt ist.
• Discovery bricht nie den Core-Dispatch. Eine fehlende/fehlerhafte bxsites.yaml, ein Projekt, das noch nicht existiert (z. B. --help außerhalb eines Projekts auszuführen), ein in plugins aufgeführtes Modul ohne eigenes BxSitesCliProvider.bx, oder ein Provider, dessen verbs() einen Fehler wirft - keiner dieser Fälle ist ein Fehler. Sie werden alle genauso behandelt wie ein nicht aktiviertes Plugin: Die Core-Verb-Tabelle bleibt einfach unangetastet, und jeder eingebaute bxSites-Befehl funktioniert weiterhin von selbst.

Ein minimales Beispiel

myBxSitesAddon/
├── box.json                          # boxlang.moduleName is what bxsites.yaml's [plugins] references
├── ModuleConfig.bx                    # a normal BoxLang module descriptor
└── models/
    ├── BxSitesPlugin.bx               # optional - build-lifecycle hooks, see plugins.md
    ├── BxSitesCliProvider.bx          # verbs()
    └── cli/
        └── cloud/
            ├── Publish.bx             # run( options )
            └── Status.bx              # run( options )

Siehe Plugins für die Build-Lifecycle-Seite desselben Moduls, und die CLI-Referenz für jedes Verb, das Core selbst mitbringt.