plugin-refs

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

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:

• refs — refs class

What it does

The remote-repo FETCH BACKEND, relocated out of charly core into a compiled-in plugin candy (P7) — the swappable download seam every @github remote-candy fetch reaches. A compiled-in plugin candy is a SEPARATE Go module importing only sdk (never charly core), so it composes the shared sdk/kit git primitives (GitResolveRef/GitClone/DownloadRepo) rather than core code. It serves the cache-miss DOWNLOAD via kit.RefsDownloader: the host dispatches every remote-repo fetch through the registered refs provider, so an alternative refs plugin can serve a different backend (OCI/S3-hosted candies) by registering a different RefsDownloader — the DEFAULT (this candy) fetches via git. The host keeps the fetch ORCHESTRATION (local-override resolution, cache-hit short-circuit, the post-fetch schema auto-migration via command:migrate); this plugin owns only the pluggable backend that turns a (repoPath, version) into a populated local cache tree. The fetch runs deep in config loading, where the compiled-in command:migrate already invokes with no bootstrap cycle, so registering this at init() before the first load is likewise cycle-free. COMPILED-IN (in the embedded compiled_plugins:); unlocks alternative ref backends.

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

// plugin-refs's OWN self-contained CUE schema — the SINGLE SOURCE for this plugin's
// declaration surface, served over the Describe channel (there is no schema-less
// plugin). SELF-CONTAINED: it references no base def, so it compiles STANDALONE (the
// property the SDK's serve-side compile and `cue exp gengotypes` both need).
//
// `refs:refs` is the swappable remote-repo fetch backend. The host keeps the fetch
// ORCHESTRATION (local-override resolution, cache-hit short-circuit) and only a genuine
// cache miss reaches this backend, which turns the wire input below into a populated
// local cache tree.
#RefsPlugin: {
  // The capability class:word the plugin serves.
  refs: "refs"

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

  // The wire input each cache-miss download carries (mirrors spec.RefsDownloadInput).
  input?: {
    repo_path!: string & !=""
    version!:   string & !=""
  }
}

---

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