plugin-cache

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

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:

• cache — command class

What it does

The charly cache command — the git-ref cache operator surface, served as a charly COMMAND-class plugin (dual-placement: compiled-in + external). On charly cache status|clear|refresh|bypass, the plugin operates on the git-ref cache DIRECTLY through spec/refs (the same per-host charly.yml cache: section the core singleton uses — shared on-disk state). The bypass (charly cache bypass) is PERSISTED in the cache: git: section via refs.GitClient.SetBypass, so a fresh core process honors it at construction — the plugin owns the whole operator surface; core keeps only the mechanism (spec/refs) + the singleton. The command-class companion of the verb-class plugin-example-external; the command class is external-capable: charly prescans cache into the CLI grammar and dispatches it in-proc (compiled-in) or fork/execs this binary (external).

The OCI-transport surface (charly cache push <name> <ref> / pull) moves a named spec/cache.ArtifactStore (an OCI Image Layout) to and from a registry, reaching candy/plugin-oci’s verb:oci cache-push/cache-pull over the F10 peer-dispatch leg — the go-containerregistry transport stays single-homed in plugin-oci, never linked here. Needs the compiled-in placement (the reverse channel).

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

// plugin-cache's OWN self-contained CUE schema — the plugin's declaration
// surface, used two ways exactly like every other plugin's schema (there is
// no schema-less plugin):
//
//  1. SERVE over Describe — the host splices `base ++ plugin` at the load gate, so the
//     plugin's declarations travel WITH it and a self-contained schema that will not
//     splice is a LOUD load failure.
//  2. DOCUMENT the plugin's published surface — the reference site's per-plugin page is
//     rendered from its providers, this schema, and the candy description.
//
// command:cache's authored input is its pass-through CLI grammar (the OpRun `{args:
// [...]}` envelope), so this schema DOCUMENTS the command contract rather than a
// structured plugin_input. SELF-CONTAINED: it references no base def, so it compiles
// STANDALONE (the property that lets the SDK compile it serve-side).
#CachePlugin: {
  // The declared capability words (the plugin.providers surface), recorded here as
  // part of the plugin's published declaration surface.
  providers: [...string]

  // The command word the plugin serves.
  command: "cache"

  // The subcommands of the `charly cache` CLI tree — the git-ref cache operator
  // surface plus the OCI-transport push/pull leaves.
  subcommands: ["status", "clear", "refresh", "bypass", "push", "pull"]

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

  // The configuration surface: env var names the plugin reads, recorded here as part
  // of the plugin's published declaration surface.
  config?: [string]: string
}

---

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