box

Documentation

Overview

Package box is the charly plugin housing the build-mode `charly box …` verb HANDLERS that are NESTED under the core `box` command group (P15). It is a dual-placement COMMAND plugin (F8): the SAME NewProvider()/NewMeta()/CliMain compile INTO charly in-process when listed in compiled_plugins (the canonical placement, P15), or cmd/serve serves them OUT-OF-PROCESS when they are not.

It serves ELEVEN command capabilities, all NESTED under the `box` parent (CommandParent()=="box", so `charly box generate/validate/new/pkg/pull/build/inspect/list/labels/merge/reconcile` parse + dispatch here while the retained core BoxCmd verb — feature — and the authoring verbs stay in core):

• command:generate — `charly box generate`: builds a spec.BuildRequest and InvokeProvider's the peer COMPILED-IN build:generate word (candy/plugin-build), which renders the .build/ Containerfile tree host-side over HostBuild("build-prep", GenerateOnly). Zero core reentry.
• command:new — `charly box new candy/project/box`: calls kit.ScaffoldCandy / kit.ScaffoldProject / kit.AddBox directly (the scaffold ENGINE already lives in sdk/kit). Zero core reentry.
• command:validate — `charly box validate`: fetches the error-TOLERANT resolved-project envelope (HostBuild("validate-project") → spec.ValidateProjectReply) and runs the whole per-kind/op rule ENGINE + the deploykit resolution-graph checks IN-PLUGIN over that envelope, MERGING the host's CUE-conformance/tunable/base⊻from diagnostics for the verdict (validate.go / validate_rules.go / validate_graph.go / validate_check.go).
• command:pkg — `charly box pkg`: reaches the hidden core `__box-pkg` reentry over HostBuild("cli") (the localpkg build engine needs the host build context, pre-K1).
• command:pull — `charly box pull`: reaches the hidden core `__box-pull` reentry over HostBuild("cli") (FINAL/K5 unit 6a M4c, pull-first per the build/pull dispersal ruling — EnsureImagePresent's build-fallback needs the full box-build engine + charly.yml resolution, which is K1/K3-ENGINE family, not CLI-dispersal residue). The plugin owns ONLY the CLI grammar (pullGrammar, byte-identical to the former static BoxPullCmd Kong leaf) + reentry dispatch; BoxPullCmd's Run body is UNCHANGED, unmoved, still core-only.
• command:build — `charly box build`: reaches the hidden core `__box-build` reentry over HostBuild("cli") (FINAL/K5 unit 6a M4d, the CLI-only mirror of the pull move — BuildCmd.Run()'s engine, the bootstrap-builder subsystem, remote-ref resolve/download, and retention pruning are K1/K3-ENGINE family, tracked to move with those waves, not this dispersal). The plugin owns ONLY the CLI grammar (buildGrammar, byte-identical to the former static BuildCmd Kong leaf) + reentry dispatch; BuildCmd's Run body is UNCHANGED, unmoved, still core-only.
• command:inspect — `charly box inspect`: reads the generic spec.ResolvedProject envelope (HostBuild("resolved-project")) and prints the resolved box view — snake_case JSON by default, scalar/box-aggregate fields per --format. The deploy-overlay formats (tunnel/bind_mounts) reenter the hidden core `__box-inspect-overlay`. See inspect_list.go.
• command:list — `charly box list <sub>`: boxes/candies/targets/services/routes/volumes/aliases from the same envelope; `list tags` reenters the hidden core `__box-list-tags` (podman store).
• command:labels — `charly box labels <ref>`: resolves the local image + prints its OCI labels directly via sdk/kit (ResolveRuntime/ResolveLocalImageRef/InspectImageLabels) — pure container-storage probes with zero loader coupling, so this needs NO core reentry (K3 reentry-class dissolution; the former `__box-labels` HostBuild("cli") hop is gone).
• command:merge — `charly box merge`: reads Registry/Tag/Merge settings for one (or every merge.auto) box off the resolved-project envelope, then reaches verb:oci DIRECTLY via InvokeProvider (the SAME F10 peer-dispatch leg candy/plugin-build's own post-build inline merge already uses) — zero core reentry (P14: relocated from charly/merge.go).
• command:reconcile — `charly box reconcile`: aligns cross-repo `@github` git-tag pins to one target version per repo. Purely sdk/kit + sdk/deploykit + sdk/spec + stdlib YAML — zero HostBuild, zero InvokeProvider, zero core reentry (Cutover B unit 3+4: relocated from charly/reconcile.go, which had no core-only coupling at all — the cleanest of this wave's moves). See reconcile.go.

NOT command:feature: `charly box feature run <image>` was ATTEMPTED here (P12a follow-up) and REVERTED — nesting a second "feature" word under `box` panics RegisterBuiltinPluginUnit at process init, because the provider registry's uniqueness key is provKey(class, word) alone (provider_registry.go) with NO CommandParent component, and candy/plugin-feature already owns the TOP-LEVEL {command, feature} word (`charly feature list/pending/validate`). See charly/check_feature_run.go for the retained in-core BoxFeatureCmd/BoxFeatureRunCmd and the full finding (routed to P12b: either rename the nested word, breaking CLI parity, or make the registry key CommandParent-aware, a cross-cutting core change).

COMPILED-IN, it dispatches IN-PROC via Invoke(OpRun), so the handlers run in charly's OWN process and inherit charly's real stdio natively. It imports ONLY the sdk module, never charly core.

Index

• func CliMain(_ []string) int
• func NewMeta() pb.PluginMetaServer
• func NewProvider() pb.ProviderServer

Functions

func CliMain

func CliMain(_ []string) int

CliMain is the OUT-OF-PROCESS command entry — unreachable in the canonical compiled-in placement. The generate/validate/pkg handlers reach the host reverse channel (build:generate over InvokeProvider, validate-project + __box-pkg over HostBuild), which is unavailable out-of-process, so this errors (like candy/plugin-vm's / candy/plugin-alias's CliMain).

func NewMeta

func NewMeta() pb.PluginMetaServer

NewMeta advertises command:generate/validate/new/pkg via sdk.NewMeta → BuildCapabilities so the COMPILED-IN path registers each as a command provider (the host builds its dynamic Kong grammar + dispatches Invoke(OpRun)). A command's args are pass-through CLI tokens, not a structured plugin_input, so the capabilities carry no InputDef and the plugin ships no schema. The "list" word ALSO declares its own boxListSubcommands catalog (F-CLI-NEST); every other word declares none, keeping today's flat pass-through grammar unchanged for them.

func NewProvider

func NewProvider() pb.ProviderServer

NewProvider returns the box command provider for in-proc registration (compiled-in) or out-of-proc serving.