Proveedores de CLI

Proveedores de CLI

Un plugin se conecta al ciclo de vida del build - configuración, nav, markdown/HTML de página, post-build. Un proveedor de CLI es el punto de extensión hermano para el ciclo de vida de comandos: permite que un módulo de BoxLang instalado y activado registre sus propios comandos bxSites <verbo>, sin tocar bx-sites mismo.

Mismo modelo de activación que un plugin - un módulo se apunta por nombre, mediante el propio array plugins de bxsites.yaml:

plugins: [ myBxSitesAddon ]

Un módulo puede implementar models/BxSitesPlugin.bx, models/BxSitesCliProvider.bx, ambos, o ninguno - instalar/activar un módulo es un paso; qué contratos implementa decide qué es lo que realmente extiende.

Escribir un proveedor de CLI

Un proveedor de CLI necesita exactamente una cosa además de los habituales box.json/ModuleConfig.bx: una clase models/BxSitesCliProvider.bx que exponga un único método verbs(), que devuelve un struct de nombre de verbo → información de dispatch:

// 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"
			}
		}
	}

}

Cada clase de dispatch sigue exactamente la misma forma que una clase de verbo del core bajo el propio models/cli/ de bx-sites - una struct function run( struct options ) que devuelve { exitCode, message }:

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#" }
	}
}

El sufijo @myBxSitesAddon es obligatorio

Una ruta con puntos simple como "models.cli.cloud.Publish" solo se resuelve en relación con el propio raíz de módulo de bx-sites - así es como los verbos del core hacen referencia a models/cli/Build.bx y similares, pero no puede alcanzar un módulo distinto. Las propias clases de verbo de un proveedor deben suministrar siempre su propio sufijo @<mapping> de módulo, exactamente como se muestra arriba. Esta es también la razón por la que registrarse en la propia tabla literal de verbos de bx-sites no es algo en lo que un proveedor pueda colarse - la ruta de clase tiene que nombrar explícitamente su propio módulo.

Nombres de verbo: de un token y de dos tokens ("compuesto")

Un nombre de verbo se registra como una única cadena unida por dos puntos, la misma convención que el core ya usa para post:new/i18n:status/page:rename. bxSites también acepta el equivalente de dos tokens de argv separados por espacio como azúcar sintáctico sobre ese mismo registro - bxSites cloud publish y bxSites cloud:publish despachan de forma idéntica, en cuanto "cloud:publish" es un nombre de verbo registrado. No hay un mecanismo de registro de dos palabras separado que aprender; registra "cloud:publish", y ambas grafías funcionan gratis.

Precedencia y modos de fallo

• El core siempre gana. Si un proveedor registra un nombre de verbo que choca con uno de los verbos incorporados de bx-sites, se despacha el verbo del core y la entrada del proveedor se ignora silenciosamente
  • un proveedor puede añadir comandos nuevos, nunca eclipsar uno existente.
• Ante una colisión entre dos proveedores, gana el primero. Si dos módulos activados distintos registran el mismo nombre de verbo, gana el que aparezca antes en el array plugins de bxsites.yaml.
• El descubrimiento nunca rompe el dispatch del core. Un bxsites.yaml ausente o mal formado, un proyecto que todavía no existe (p. ej. ejecutar --help fuera de cualquier proyecto), un módulo listado en plugins sin su propio BxSitesCliProvider.bx, o un proveedor cuyo verbs() lanza un error - ninguno de estos casos es un error. Todos se tratan igual que un plugin no activado: la tabla de verbos del core simplemente queda intacta, y todos los comandos incorporados de bxSites siguen funcionando por su cuenta.

Un ejemplo mínimo

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 )

Consulta Plugins para el lado del ciclo de vida del build del mismo módulo, y la referencia de la CLI para cada verbo que trae el core mismo.