plugin-build

Placement	compiled-in (in-process)
Source	github.com/opencharly/charly/candy/plugin-build
Version	2026.206.1217
Candy	plugin-build

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:

• box — build class
• ensure — build class
• generate — build class

What it does

The BUILD-DRIVE plugin: it OWNS the podman build drive (the build-order loop, the per-image build lock, the push, and the merge gate) for build:box (the charly box build engine) and build:generate (the charly box generate engine), AND the ensure-image ORCHESTRATION for build:ensure (core-min wave 3, build-engine cluster relocation — the former core ensure-image + cross-engine-transfer helpers): pull an image, falling back to a local (or remote-cached) build reached via the SAME in-process build:box drive this candy already owns — no new build seam. The heavy loader/render RESOLVE runs PLUGIN-SIDE ITSELF (resolveBuildEngine, K3 U6 — the former host-side NewGenerator this candy used to call over HostBuild is DELETED, #55 step3 3-II), reaching the host only for what a sdk-only candy structurally cannot do (the bootstrap-delicate local scan, the git fetch, the build-time plugin connect, the host-fs prep) over a small buildengine-* HostBuild leg family; the layer MERGE crosses to verb:oci via InvokeProvider (no HostBuild(“merge”) seam). The candy then runs podman directly — building each image (Containerfile piped over stdin), gating the inline merge on the box’s MergeAuto, and pushing (podman) after merge; build:generate renders the .build/ Containerfile tree in its own code (via sdk/deploykit, #67) and returns the written paths (no podman, no merge); build:ensure resolves a project-authored image identifier against charly.yml PLUGIN-SIDE (loaderkit.LoadUnified via the K1 loader reverse legs — no “box-ref-resolve” HostBuild seam, shed #55 coneK1 #8) and a remote @github.com/… identifier via HostBuild(“remote-image-resolve”, …) (git clone/cache ONLY, then plugin-side resolve), then execs podman pull/podman tag directly (no seam needed for that — same host, same privilege as the build drive’s own podman exec). Only the wire envelopes cross the seam; the podman exec happens IN the candy. COMPILED-IN (in the embedded compiled_plugins:) — charly box build / charly box generate / every dispatchBuildEnsure caller dispatch it IN-PROCESS, the host threading the reverse channel onto the Invoke context so HostBuild is reachable without a go-plugin broker. Also serves out-of-process via cmd/serve for module-shape parity (one provider, two placements).

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/build.cue

// schema/build.cue — the SELF-CONTAINED CUE schema candy/plugin-build ships over Describe
// (schema_cue). References NO base def so it compiles standalone (BuildCapabilities compiles it
// alone, failing loudly if broken) AND splices onto the base (the base ++ plugin splice detects a
// def-name collision — hence a UNIQUE name, never a #Build* already in the base).
//
// UNLIKE most plugins, this schema does NOT validate a per-word plugin_input: the build words
// (build:box / build:generate) carry a HOST-constructed spec.BuildRequest (built by BuildCmd /
// candy/plugin-box's generate handler from CLI flags), never a user-authored plugin_input, so both capabilities declare
// InputDef:"" and there is nothing to validate against a served schema. This def exists ONLY to
// satisfy the non-empty-schema load gate and to DOCUMENT the seam — it is never used for
// validation. The build request/reply wire shapes are the authoritative Go types
// spec.BuildRequest / spec.BuildReply (CUE-sourced at sdk/schema/buildwire.cue); the fields below
// mirror them for documentation.
#BuildDispatch: {
  // The host-constructed build request forwarded verbatim to HostBuild (informational).
  boxes?: [...string]
  tag?:              string
  dir?:              string
  include_disabled?: bool
  dev_local_pkg?:    bool
  push?:             bool
  platform?:         string
  cache?:            string
  no_cache?:         bool
  jobs?:             int
  podman_jobs?:      int
}

---

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