Documentation
¶
Overview ¶
Package refs is the spec fabric slice for the remote-repo GIT primitives — pure git-exec + string parsing + cache-path computation, host primitives a plugin composes but the kernel itself needs (reconcile's --remote tag query, the collection walk). RELOCATED from sdk/kit (#55 fabric-primitive extraction), so charly core reaches them via spec/refs directly and the remaining sdk/candy callers keep a thin kit re-export. The FETCH ORCHESTRATION (override → cache → clone → migrate) still lives in the refs plugin (candy/plugin-refs); these are the reusable mechanisms it composes. The only non-stdlib dependency is the advisory file lock (spec/lock) DownloadRepo serializes concurrent cache refresh with.
Index ¶
- func CompareSemver(a, b string) int
- func DownloadRepo(repoPath string, version string) (string, error)
- func GitClone(repoURL string, ref string, commit string, targetDir string) error
- func GitDefaultBranch(repoURL string) (string, error)
- func GitLatestTag(repoURL string) (string, error)
- func GitResolveRef(repoURL string, ref string) (string, error)
- func IsMutableRef(version string) bool
- func IsRepoCached(repoPath, version string) (bool, error)
- func RepoCacheDir() (string, error)
- func RepoCachePath(repoPath, version string) (string, error)
- func RepoGitURL(repoPath string) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareSemver ¶
CompareSemver compares two semver-like version strings (e.g. "v1.2.3"). Returns -1 if a < b, 0 if equal, 1 if a > b. Handles v-prefixed versions and falls back to string comparison for non-numeric parts.
func DownloadRepo ¶
DownloadRepo downloads a remote repo to the cache. Returns the cache path where the repo was stored.
Freshness contract: the cache is reused ONLY when its recorded provenance (the commit the export was cloned from) equals the ref's CURRENTLY resolved commit — so a branch that advanced upstream (main) is re-downloaded instead of silently serving stale content. The check costs the one ls-remote GitResolveRef already performs; for immutable tags the provenance always matches, so their cache-hit behavior is unchanged. A cache written before this contract has no provenance and is re-downloaded once, then self-heals.
func GitClone ¶
GitClone clones a git repository at a specific ref into the target directory. Uses shallow clone for efficiency.
func GitDefaultBranch ¶
GitDefaultBranch detects the default branch of a remote repository. Uses git ls-remote --symref to find what HEAD points to. Returns the branch name (e.g., "main", "master").
func GitLatestTag ¶
GitLatestTag queries a remote repo for tags and returns the highest semver tag. Looks for tags matching v* pattern, sorts by semver, returns the highest. Returns an error if no version tags are found.
func GitResolveRef ¶
GitResolveRef resolves a git reference (tag, branch, or commit) to a full commit hash. Uses git ls-remote for tags/branches; for commit hashes, validates length and returns as-is.
func IsMutableRef ¶
IsMutableRef reports whether a repo ref version can ADVANCE upstream (a branch name such as main, or an empty version that resolves to the default branch). Immutable coordinates — CalVer/semver tags (v…) and full commit SHAs — never change what they point at; the project's tags are add-only. Mutable refs must re-resolve on every access: a cache hit on a branch otherwise freezes it at first-download content forever (the pre-#146 @main protocol skew — a stale main export served protocol-v1 plugin sources indefinitely).
func IsRepoCached ¶
IsRepoCached reports whether a repo version is already in the cache AS A USABLE EXPORT — the directory exists AND every submodule it declares has content.
The completeness half is load-bearing for IMMUTABLE refs. EnsureRepoDownloaded short-circuits on `cached && !IsMutableRef(version)`, returning RepoCachePath directly and never entering DownloadRepo — so the repoCacheFresh completeness check cannot see a tag's cache at all. Directory-exists alone therefore pinned every incomplete TAG export permanently: a tag never moves, so nothing would ever re-fetch it. On the machine this was found, `charly@v2026.183.1359` held 0 of its 9 declared submodules and `charly@v2026.201.0706` held 1 of 10, both unrepairable for the life of the cache. Checking content here routes an incomplete export down the download branch instead, so tag and branch caches self-heal by the SAME predicate rather than one growing its own copy.
func RepoCacheDir ¶
RepoCacheDir returns the cache directory for remote repos. Uses $CHARLY_REPO_CACHE env var if set, otherwise ~/.cache/charly/repos/.
func RepoCachePath ¶
RepoCachePath returns the cache path for a specific repo version. e.g. ~/.cache/charly/repos/github.com/org/repo@v1.0.0/
func RepoGitURL ¶
RepoGitURL converts a repo path to a git clone URL. e.g. "github.com/opencharly/ml-layers" -> "https://github.com/opencharly/ml-layers.git"
Types ¶
This section is empty.
Source Files