plugin-box

Placement	compiled-in (in-process)
Source	github.com/opencharly/plugin-box/candy/plugin-box
Version	2026.194.0000
Candy	plugin-box

This plugin is listed in charly/charly.yml’s compiled_plugins:, so its providers are compiled into the charly binary and register in-process.

Providers

The reserved words this plugin serves:

• build:box — command class
• feature:box — command class
• generate:box — command class
• inspect:box — command class
• labels:box — command class
• list:box — command class
• load:box — command class
• merge:box — command class
• new:box — command class
• pull:box — command class
• reconcile:box — command class
• validate:box — command class

What it does

The build-mode charly box … verb HANDLERS relocated into a COMPILED-IN command plugin candy (P15, K5). charly box is a SHARED command group whose subcommands have different owners: the core BoxCmd keeps only the grammar spine (a bare kong.Plugins holder, no retained verb) and candy/plugin-authoring contributes the authoring words, while THIS candy contributes twelve NESTED command providers under the box parent (each command: with CommandParent()==“box”): generate, validate, new, pull, build, inspect, list, labels, load, merge, reconcile, feature. COMPILED-IN, each dispatches IN-PROC via Invoke(OpRun) (kong-parse its sub-grammar), so the handlers own charly’s real stdio. generate renders the .build/ tree by InvokeProvider’ing the peer build:generate word (candy/plugin-build), which drives HostBuild(“build-resolve”, GenerateOnly); new (candy/project/box) calls the sdk/kit scaffold engine directly (kit.ScaffoldCandy/ScaffoldProject/AddBox), no core reentry; validate fetches the error-TOLERANT resolved-project envelope (HostBuild(“validate-project”)) and runs the whole per-kind/op rule engine + the deploykit resolution-graph checks IN-PLUGIN over it, merging the host’s CUE-conformance / tunable / base⊻from diagnostics for the verdict; load streams a host image into a RUNNING pod venue’s nested podman store over deploykit.TransferImageToVenue — the container twin of charly vm cp-box, needing no host reentry at all; inspect and list read the generic spec.ResolvedProject envelope (InvokeProvider(“build”,“project”)) — inspect’s default JSON is snake_case canonical — with the deploy-overlay formats (inspect tunnel/bind_mounts) + store-live list tags reaching the hidden core __box-inspect-overlay / __box-list-tags reentries. Their data still needs the fully-resolved project / deploy overlay / podman store the plugin cannot compute pre-K1. It imports only the sdk module, never charly core. Placement-invisible (F8): the SAME provider compiles into charly or serves out-of-process.

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/box.cue

// plugin-box's OWN self-contained CUE schema — the SINGLE SOURCE for this plugin's
// served declaration surface (there is no schema-less plugin: every plugin ships a
// non-empty schema over Describe).
//
// SELF-CONTAINED and PACKAGE-LESS: it references no base def and carries no package
// clause, so it compiles STANDALONE — the property the SDK's serve-side compile needs
// and the property that lets the host splice `base ++ plugin` at the load gate
// (registerPluginUnitSchema); a self-contained schema that will not splice is a LOUD
// load failure.
//
// NO GO CONSUMER: the plugin declares no typed `plugin_input` (its authored input is
// its pass-through CLI grammar), so this schema generates NO `params` package and has
// NO `cue exp gengotypes` artifact — it is the SERVED documentation/config surface,
// not a code-generation source.
//
// It DOCUMENTS the `command:<word>:box` surface: the `box` parent, its twelve words, and `list`'s own subcommand catalog.
#BoxPlugin: {
  // The command group every word below NESTS under — part of each capability's
  // declared IDENTITY (`command:<word>:box`), keyed by charly's provider registry.
  parent: "box"

  // The command words this plugin serves, all nested under `parent`. A command's
  // args are pass-through CLI tokens (there is no typed plugin_input), so these
  // words ARE this plugin's authored declaration surface.
  commands: ["generate", "validate", "new", "pull", "build", "inspect", "list", "labels", "load", "merge", "reconcile", "feature"]

  // The `list` word's own subcommand catalog (F-CLI-NEST), declared so the host
  // builds a real nested Kong grammar + the `box.list.*` MCP tools.
  listSubcommands: ["boxes", "candies", "targets", "services", "routes", "volumes", "aliases", "tags"]

  // What the plugin does, in one line (the public-docs surface).
  contract: string & !=""
}

---

See also the candy reference for this candy’s install surface.