manager

package
v1.223.0-rc.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package manager implements the Atmos Version Tracker: externally managed versions declared in atmos.yaml, resolved into a lock file, and consumed at runtime via the !version YAML function and the .version template context.

Index

Constants

View Source 
const (
	// DefaultTrack is the implicit track name used when none is configured.
	DefaultTrack = "default"
	// DefaultLockFile is the default managed versions lock file name.
	DefaultLockFile = "versions.lock.yaml"
)
View Source 
const (
	ShowDesired = "desired"
	ShowLocked  = "locked"
)

Show selectors for TrackVersionMatrix: which version value populates each matrix cell.

View Source 
const (
	// StrategyMajor allows any version advance (the default).
	StrategyMajor = "major"
	// StrategyMinor allows advances within the locked major version.
	StrategyMinor = "minor"
	// StrategyPatch allows advances within the locked major.minor version.
	StrategyPatch = "patch"
	// StrategyPin never advances the version; pinned digests still refresh.
	StrategyPin = "pin"
	// StrategyDigest is an alias for StrategyPin used by digest-only entries.
	StrategyDigest = "digest"
)

Update strategy values.

View Source 
const (
	// PinNone emits plain version references.
	PinNone = "none"
	// PinDigest emits the immutable identifier (git commit SHA or OCI digest).
	PinDigest = "digest"
)

Pin policy values (after normalization).

View Source 
const (
	// StatusUnlocked means the entry has no lock file record.
	StatusUnlocked = "unlocked"
	// StatusLocked means the entry is locked but its target could not be resolved.
	StatusLocked = "locked"
	// StatusCurrent means the locked version matches the resolved target.
	StatusCurrent = "current"
	// StatusUpdateAvailable means a policy-eligible update differs from the locked version.
	StatusUpdateAvailable = "update-available"
	// StatusBlocked means a newer version exists but the update policy
	// (strategy or cooldown) holds it back; Message carries the reason.
	StatusBlocked = "newer-available (blocked)"
)

Status values reported for managed dependency entries.

Variables

View Source 
var (
	// ErrEntryExists is returned when adding an entry that is already configured.
	ErrEntryExists = errUtils.ErrVersionEntryExists
	// ErrEntryNotFound is returned when editing an entry that is not configured.
	ErrEntryNotFound = errUtils.ErrVersionEntryNotFound
)
View Source 
var (
	ErrTrackNotFound          = errUtils.ErrVersionTrackNotFound
	ErrVersionNotFound        = errUtils.ErrVersionNotFound
	ErrVersionNotLocked       = errUtils.ErrVersionNotLocked
	ErrTrackNotVerified       = errUtils.ErrVersionTrackNotVerified
	ErrDesiredVersionRequired = errUtils.ErrDesiredVersionRequired
)
View Source 
var (
	ErrResolverUnsupported = resolver.ErrResolverUnsupported
	ErrNoVersionMatch      = resolver.ErrNoVersionMatch
)

Errors surfaced from the resolver registry, aliased so existing callers and errors.Is checks against the manager package keep working.

View Source 
var ErrInvalidCooldown = errUtils.ErrInvalidVersionCooldown

ErrInvalidCooldown is returned for unparseable cooldown values.

View Source 
var ErrUnsupportedEntryField = errUtils.ErrUnsupportedVersionField

ErrUnsupportedEntryField is returned when Field is called with an unknown field name.

View Source 
var ErrUnsupportedVersionShow = errUtils.ErrUnsupportedVersionShow

ErrUnsupportedVersionShow is returned when TrackVersionMatrix is called with an unrecognized show value.

Functions

func AddEntry 

func AddEntry(atmosConfig *schema.AtmosConfiguration, track, name string, entry *schema.VersionEntry) (string, error)

AddEntry writes a new dependency entry into the editable atmos.yaml, preserving comments and formatting, and returns the file modified. It fails with ErrEntryExists when the entry is already configured.

func AddTemplateContext 

func AddTemplateContext(
	atmosConfig *schema.AtmosConfiguration,
	yamlContent string,
	context map[string]any,
	track string,
) (map[string]any, error)

AddTemplateContext lazily injects the .version template context when the YAML content references it. The version map is loaded from the lock file for the given track. An existing "version" key in the context is left untouched.

It never turns an empty context into a non-empty one: a non-empty context is what gates whole-file template processing in the stack processor, and enabling that early would evaluate templates (e.g. `{{ .vars.* }}` inside generate sections) that are meant for later processing stages. The .version context therefore piggybacks only on template processing that is already going to happen.

func EffectiveEntries 

func EffectiveEntries(atmosConfig *schema.AtmosConfiguration, track string) (map[string]EffectiveEntry, error)

EffectiveEntries returns all versions for a track with defaults and groups applied.

func EffectiveTrack 

func EffectiveTrack(atmosConfig *schema.AtmosConfiguration, requested string) string

EffectiveTrack returns the requested track, the config default, or "default".

func EffectiveTrackFromStack 

func EffectiveTrackFromStack(atmosConfig *schema.AtmosConfiguration, stackInfo *schema.ConfigAndStacksInfo) string

EffectiveTrackFromStack returns the stack-asserted track when present.

func InferEcosystem 

func InferEcosystem(pkg string) string

InferEcosystem guesses the ecosystem for a package coordinate when it is not set explicitly: GitHub Actions for actions/*, OCI for registry-hosted images (first segment carries a dot), toolchain for bare tool names, and github for everything else in owner/repo form.

func LockFilePath 

func LockFilePath(atmosConfig *schema.AtmosConfiguration) string

LockFilePath returns the absolute lock file path.

func RemoveEntry 

func RemoveEntry(atmosConfig *schema.AtmosConfiguration, track, name string) (string, error)

RemoveEntry deletes a dependency entry and returns the file modified.

func RenderFile 

func RenderFile(atmosConfig *schema.AtmosConfiguration, track, file string, render RenderFunc) (string, error)

RenderFile renders a template file with the .version context for a track. It returns the rendered content; writing (or check-mode comparison) is the caller's concern.

func ResolveEntry 

func ResolveEntry(atmosConfig *schema.AtmosConfiguration, entry *EffectiveEntry, pin bool) (resolver.Candidate, error)

ResolveEntry resolves an entry to its full candidate (version plus digest and release timestamp when the datasource provides them). When pin is true and the resolved candidate has no digest yet, the datasource's Pin resolution runs; a datasource without a digest concept fails loudly so a misconfigured `pin: digest` is never silently ignored.

func ResolveEntryWithContext 

func ResolveEntryWithContext(ctx context.Context, atmosConfig *schema.AtmosConfiguration, entry *EffectiveEntry, pin bool) (resolver.Candidate, error)

ResolveEntryWithContext resolves an entry to its full candidate while honoring the caller's cancellation and deadline.

func ResolveLocked 

func ResolveLocked(atmosConfig *schema.AtmosConfiguration, track, name string) (string, error)

ResolveLocked resolves a version name from the lock file.

func ResolveTarget 

func ResolveTarget(atmosConfig *schema.AtmosConfiguration, entry *EffectiveEntry) (string, error)

ResolveTarget returns the desired concrete version for an entry. Concrete desired versions pass through unchanged; "latest" and SemVer constraints are resolved against the entry's datasource via the resolver registry, honoring the entry's include, exclude, and prerelease rules.

func ResolveTargetWithContext 

func ResolveTargetWithContext(ctx context.Context, atmosConfig *schema.AtmosConfiguration, entry *EffectiveEntry) (string, error)

ResolveTargetWithContext returns the desired concrete version for an entry, honoring the caller's cancellation and deadline.

func ResolveYAMLFunc 

func ResolveYAMLFunc(atmosConfig *schema.AtmosConfiguration, name string, stackInfo *schema.ConfigAndStacksInfo) (string, error)

ResolveYAMLFunc resolves a `!version name` YAML function argument against the lock file, using the stack-asserted track when present.

func SaveLock 

func SaveLock(atmosConfig *schema.AtmosConfiguration, lock *LockFile) error

SaveLock writes the lock file.

func SetEntryFields 

func SetEntryFields(atmosConfig *schema.AtmosConfiguration, track, name string, fields map[string]any) (string, error)

SetEntryFields updates fields of an existing dependency entry (dot-relative paths such as "desired" or "update.pin") and returns the file modified.

func TrackNames 

func TrackNames(atmosConfig *schema.AtmosConfiguration) []string

TrackNames returns sorted configured track names. It also includes the implicit default track (the one EffectiveTrack resolves to) when it has no entry in version.tracks but is usable via the base dependency catalog, so callers see the same set of usable tracks that EffectiveEntries does.

func TrackVersionMatrix 

func TrackVersionMatrix(atmosConfig *schema.AtmosConfiguration, show string) (map[string]map[string]string, error)

TrackVersionMatrix returns configured version tracks as a matrix keyed by track name, then dependency name, with the requested show value as each cell's value: ShowDesired reads the configured version straight from EffectiveEntries (no lock file access); ShowLocked reads the resolved version from versions.lock.yaml, leaving the cell empty when a dependency is not yet locked for that track.

func VersionMap 

func VersionMap(atmosConfig *schema.AtmosConfiguration, track string) (map[string]VersionRef, error)

VersionMap returns a map usable as template context at .version. Each value is a VersionRef whose String() form honors the entry's pin policy, so `{{ .version.name }}` renders the digest for pinned entries while `.Version` and `.Digest` stay individually addressable.

func VersionRefs 

func VersionRefs(entries map[string]EffectiveEntry, lock map[string]LockEntry) map[string]VersionRef

VersionRefs joins effective entries with their lock records into the template-context/file-manager reference form.

Types

type EffectiveEntry 

type EffectiveEntry struct {
	Name       string                     `yaml:"name" json:"name"`
	Ecosystem  string                     `yaml:"ecosystem,omitempty" json:"ecosystem,omitempty"`
	Datasource string                     `yaml:"datasource,omitempty" json:"datasource,omitempty"`
	Provider   string                     `yaml:"provider,omitempty" json:"provider,omitempty"`
	Package    string                     `yaml:"package,omitempty" json:"package,omitempty"`
	Desired    string                     `yaml:"desired,omitempty" json:"desired,omitempty"`
	Group      string                     `yaml:"group,omitempty" json:"group,omitempty"`
	Update     schema.VersionUpdatePolicy `yaml:"update,omitempty" json:"update,omitempty"`
	Include    []string                   `yaml:"include,omitempty" json:"include,omitempty"`
	Exclude    []string                   `yaml:"exclude,omitempty" json:"exclude,omitempty"`
	Prerelease bool                       `yaml:"prerelease,omitempty" json:"prerelease,omitempty"`
	Labels     []string                   `yaml:"labels,omitempty" json:"labels,omitempty"`
	Locked     string                     `yaml:"locked,omitempty" json:"locked,omitempty"`
}

EffectiveEntry is a version entry after defaults and groups are applied.

func (*EffectiveEntry) Field 

func (e *EffectiveEntry) Field(name string) (any, error)

Field returns the value of a single field on the entry, keyed by the same names used in its yaml/json tags. Used by `version track get --show` to print one value instead of the full entry.

type LockEntry 

type LockEntry struct {
	Version    string `yaml:"version" json:"version"`
	Ecosystem  string `yaml:"ecosystem,omitempty" json:"ecosystem,omitempty"`
	Datasource string `yaml:"datasource,omitempty" json:"datasource,omitempty"`
	Provider   string `yaml:"provider,omitempty" json:"provider,omitempty"`
	Package    string `yaml:"package,omitempty" json:"package,omitempty"`
	Digest     string `yaml:"digest,omitempty" json:"digest,omitempty"`
	ResolvedAt string `yaml:"resolved_at,omitempty" json:"resolved_at,omitempty"`
	// ReleasedAt is the upstream release timestamp when the datasource
	// provides one; used by update cooldown checks.
	ReleasedAt string `yaml:"released_at,omitempty" json:"released_at,omitempty"`
}

LockEntry is one resolved version in the lock file.

type LockFile 

type LockFile struct {
	Version int                             `yaml:"version" json:"version"`
	Tracks  map[string]map[string]LockEntry `yaml:"tracks" json:"tracks"`
}

LockFile is the on-disk versions.lock.yaml format.

func LoadLock 

func LoadLock(atmosConfig *schema.AtmosConfiguration) (*LockFile, error)

LoadLock reads the lock file. A missing lock file returns an empty lock.

func LockTrack 

func LockTrack(atmosConfig *schema.AtmosConfiguration, track, group string) (*LockFile, error)

LockTrack resolves and writes all entries in a track.

type RenderFunc 

type RenderFunc func(atmosConfig *schema.AtmosConfiguration, name, content string, data map[string]any) (string, error)

RenderFunc renders template content with the given data. The command layer injects the Atmos template engine so this package never depends on internal/exec.

type StatusEntry 

type StatusEntry struct {
	Name       string `yaml:"name" json:"name"`
	Ecosystem  string `yaml:"ecosystem,omitempty" json:"ecosystem,omitempty"`
	Datasource string `yaml:"datasource,omitempty" json:"datasource,omitempty"`
	Provider   string `yaml:"provider,omitempty" json:"provider,omitempty"`
	Package    string `yaml:"package,omitempty" json:"package,omitempty"`
	Desired    string `yaml:"desired,omitempty" json:"desired,omitempty"`
	Locked     string `yaml:"locked,omitempty" json:"locked,omitempty"`
	Resolved   string `yaml:"resolved,omitempty" json:"resolved,omitempty"`
	Group      string `yaml:"group,omitempty" json:"group,omitempty"`
	Status     string `yaml:"status" json:"status"`
	Message    string `yaml:"message,omitempty" json:"message,omitempty"`
}

StatusEntry reports the lock/update status for one managed version.

type TrackStatus 

type TrackStatus struct {
	Track   string        `yaml:"track" json:"track"`
	Entries []StatusEntry `yaml:"entries" json:"entries"`
}

TrackStatus is the status payload for a track.

func StatusTrack 

func StatusTrack(atmosConfig *schema.AtmosConfiguration, track, group string) (*TrackStatus, error)

StatusTrack returns status for all entries in a track.

func StatusTrackWithContext 

func StatusTrackWithContext(ctx context.Context, atmosConfig *schema.AtmosConfiguration, track, group string) (*TrackStatus, error)

StatusTrackWithContext returns status for all entries in a track while honoring caller cancellation and deadlines for resolver calls.

func VerifyTrack 

func VerifyTrack(atmosConfig *schema.AtmosConfiguration, track string) (*TrackStatus, error)

VerifyTrack checks that all configured entries are locked and satisfy resolvable policy.

func VerifyTrackWithContext 

func VerifyTrackWithContext(ctx context.Context, atmosConfig *schema.AtmosConfiguration, track string) (*TrackStatus, error)

VerifyTrackWithContext checks that all configured entries are locked and satisfy resolvable policy while honoring caller cancellation and deadlines.

type TrackUpdate 

type TrackUpdate struct {
	Track   string         `yaml:"track" json:"track"`
	Results []UpdateResult `yaml:"results" json:"results"`
}

TrackUpdate is the payload of a policy-driven track update.

func UpdateTrack 

func UpdateTrack(atmosConfig *schema.AtmosConfiguration, track, group string, only []string) (*TrackUpdate, error)

UpdateTrack advances locked versions within each entry's effective update policy (strategy caps relative to the locked version, cooldown against the upstream release timestamp, include/exclude/prerelease rules) and writes the lock file. Unlike LockTrack, which resolves the desired expression as-is, UpdateTrack starts from the locked state and records a structured reason whenever a newer candidate is held back. The only filter limits the update to the named entries.

func UpdateTrackWithContext 

func UpdateTrackWithContext(ctx context.Context, atmosConfig *schema.AtmosConfiguration, track, group string, only []string) (*TrackUpdate, error)

UpdateTrackWithContext advances locked versions while honoring caller cancellation and deadlines for resolver calls.

type UpdateResult 

type UpdateResult struct {
	Name       string `yaml:"name" json:"name"`
	From       string `yaml:"from,omitempty" json:"from,omitempty"`
	To         string `yaml:"to,omitempty" json:"to,omitempty"`
	FromDigest string `yaml:"from_digest,omitempty" json:"from_digest,omitempty"`
	ToDigest   string `yaml:"to_digest,omitempty" json:"to_digest,omitempty"`
	Updated    bool   `yaml:"updated" json:"updated"`
	// Reason explains a held-back or unchanged outcome (e.g. a newer version
	// blocked by strategy or cooldown).
	Reason string `yaml:"reason,omitempty" json:"reason,omitempty"`
}

UpdateResult reports the outcome of one entry's policy-driven update.

type VersionRef 

type VersionRef struct {
	Version string `yaml:"version" json:"version"`
	Digest  string `yaml:"digest,omitempty" json:"digest,omitempty"`
	Pin     string `yaml:"pin,omitempty" json:"pin,omitempty"`
}

VersionRef is the template-context value for one managed version, exposing both the human-readable version and the locked immutable digest.

func (VersionRef) String 

func (r VersionRef) String() string

String returns the reference form to embed in rendered output: the digest when pinning is enabled and a digest is locked, otherwise the version. Go templates call this automatically, so `{{ .version.name }}` yields the pinned form for pinned entries.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.