lockfile

Documentation

Overview

Package lockfile implements the unirtm.lock file format — a multi-platform snapshot of resolved tool versions, download URLs, and checksums.

The format is TOML-based and intentionally compatible with the mise.lock schema so that projects can reuse the same lockfile understanding across tools.

Example:

# @generated - this file is auto-generated by `unirtm lock`
[[tools.cli]]
version = "2.72.0"
backend = "github:cli/cli"

[tools.cli."platforms.linux-amd64"]
checksum = "sha256:abc123..."
size     = 12345678
url      = "https://github.com/cli/cli/releases/download/v2.72.0/gh_2.72.0_linux_amd64.tar.gz"
url_api  = "https://api.github.com/repos/cli/cli/releases/assets/123456"

Index

• Constants
• Variables
• func CurrentPlatformKey() string
• func IsValidPlatformKey(key string) bool
• func NormalizePlatformKey(raw string) (string, error)
• func ParsePlatformKey(key string) (goos, goarch string, musl bool, err error)
• func ParsePlatformKeys(input string) ([]string, error)
• func PlatformKey(goos, goarch string, musl bool) string
• func ToolKey(backendName, toolName string) string
• type LockFile
  • func Load(path string) (*LockFile, error)
  • func New(path string) *LockFile
  • func (lf *LockFile) CheckStrict(required []LockRequirement) error
  • func (lf *LockFile) GetEntry(key, version string) *ToolLockEntry
  • func (lf *LockFile) GetPlatform(key, version, platformKey string) *PlatformEntry
  • func (lf *LockFile) HasURL(key, version, platformKey string) bool
  • func (lf *LockFile) IsEmpty() bool
  • func (lf *LockFile) Path() string
  • func (lf *LockFile) RemoveEntry(key string)
  • func (lf *LockFile) Save() error
  • func (lf *LockFile) UpsertEntry(key string, entry *ToolLockEntry)
  • func (lf *LockFile) UpsertPlatform(key, version, platformKey string, pe *PlatformEntry)
  • func (lf *LockFile) Validate() error
• type LockRequirement
• type PlatformEntry
• type ToolLockEntry
• type ValidationError
  • func (e *ValidationError) Error() string

Constants

const Header = "# @generated - this file is auto-generated by `unirtm lock`\n" +
	"# Do not edit manually. See https://github.com/snowdreamtech/unirtm for details.\n"

Header is written at the top of every generated lockfile.

Variables

var StandardPlatforms = []string{
	"linux-amd64",
	"linux-amd64-musl",
	"linux-arm64",
	"linux-arm64-musl",
	"macos-amd64",
	"macos-arm64",
	"windows-amd64",
	"windows-arm64",
}

StandardPlatforms is the canonical list of platforms that `unirtm lock --all-platforms` will resolve. These mirror the platform keys used in mise.lock.

Functions

func CurrentPlatformKey

func CurrentPlatformKey() string

CurrentPlatformKey returns the platform key for the running OS/arch, e.g. "linux-amd64", "macos-arm64", "windows-amd64".

func IsValidPlatformKey

func IsValidPlatformKey(key string) bool

IsValidPlatformKey reports whether key is a recognised standard platform key.

func NormalizePlatformKey

func NormalizePlatformKey(raw string) (string, error)

NormalizePlatformKey lower-cases and validates a user-supplied platform key. It accepts both "linux-x64" (mise-style) and "linux-amd64" (unirtm-style) forms.

func ParsePlatformKey

func ParsePlatformKey(key string) (goos, goarch string, musl bool, err error)

ParsePlatformKey parses a canonical platform key back into (goos, goarch, musl). Returns an error for keys that do not follow the expected format.

func ParsePlatformKeys

func ParsePlatformKeys(input string) ([]string, error)

ParsePlatformKeys parses a comma-separated list of platform keys (user input), normalising each one and deduplicating.

func PlatformKey

func PlatformKey(goos, goarch string, musl bool) string

PlatformKey builds a canonical lockfile platform key from GOOS/GOARCH components.

PlatformKey("linux",   "amd64", false) → "linux-amd64"
PlatformKey("darwin",  "arm64", false) → "macos-arm64"
PlatformKey("windows", "amd64", false) → "windows-amd64"
PlatformKey("linux",   "amd64", true)  → "linux-amd64-musl"

func ToolKey

func ToolKey(backendName, toolName string) string

ToolKey builds the canonical lock key for a given backend+tool combination.

ToolKey("github", "cli/cli")   → "github:cli/cli"
ToolKey("npm",    "typescript") → "npm:typescript"

Types

type LockFile

type LockFile struct {
	// Tools maps a canonical key ("backend:tool") → list of entries.
	// In the common case there is exactly one entry per tool key.
	Tools map[string][]*ToolLockEntry `toml:"tools"`
	// contains filtered or unexported fields
}

LockFile is the in-memory representation of a unirtm.lock file. It maps a canonical tool key to one or more ToolLockEntry records. Multiple entries per tool are an edge case (e.g. different options sets), mirroring the [[tools.name]] array-of-tables TOML syntax from mise.

func Load

func Load(path string) (*LockFile, error)

Load reads and parses path as a unirtm.lock TOML file. Returns a new empty LockFile (not an error) when path does not exist, which allows callers to handle the "first run" case uniformly.

func New

func New(path string) *LockFile

New returns an empty LockFile bound to path.

func (*LockFile) CheckStrict

func (lf *LockFile) CheckStrict(required []LockRequirement) error

CheckStrict verifies that the lockfile contains a valid entry for each tool/platform pair in the required set. For URL-based backends, it ensures a URL is present. Used to enforce UNIRTM_LOCKED=1 / settings.locked=true.

required is a slice of (toolKey, version, platformKey) tuples.

func (*LockFile) GetEntry

func (lf *LockFile) GetEntry(key, version string) *ToolLockEntry

GetEntry returns the first ToolLockEntry for key that matches the given version. GetEntry returns the ToolLockEntry for a given key and version. If version is empty, any version matches. Returns nil when not found.

func (*LockFile) GetPlatform

func (lf *LockFile) GetPlatform(key, version, platformKey string) *PlatformEntry

GetPlatform returns the PlatformEntry for (key, version, platformKey). Returns nil when not found.

func (*LockFile) HasURL

func (lf *LockFile) HasURL(key, version, platformKey string) bool

HasURL reports whether the lockfile contains a download URL for the given (key, version, platformKey) combination. Used by strict-mode enforcement.

func (*LockFile) IsEmpty

func (lf *LockFile) IsEmpty() bool

IsEmpty returns true when no tools are recorded in the lockfile.

func (*LockFile) Path

func (lf *LockFile) Path() string

Path returns the filesystem path this LockFile is bound to.

func (*LockFile) RemoveEntry

func (lf *LockFile) RemoveEntry(key string)

RemoveEntry removes all entries for key (tool eviction, e.g. after uninstall).

func (*LockFile) Save

func (lf *LockFile) Save() error

Save serialises the LockFile to its bound path atomically (write-temp + rename).

func (*LockFile) UpsertEntry

func (lf *LockFile) UpsertEntry(key string, entry *ToolLockEntry)

UpsertEntry creates or updates the ToolLockEntry for key+version. If an entry for key+version already exists it is updated in place; otherwise a new entry is appended to lf.Tools[key].

func (*LockFile) UpsertPlatform

func (lf *LockFile) UpsertPlatform(key, version, platformKey string, pe *PlatformEntry)

UpsertPlatform creates or updates a single PlatformEntry inside an existing (or newly created) ToolLockEntry.

func (*LockFile) Validate

func (lf *LockFile) Validate() error

Validate checks the LockFile for structural and semantic correctness. It returns *ValidationError (with all discovered issues) or nil.

type LockRequirement

type LockRequirement struct {
	ToolKey     string // e.g. "github:cli/cli"
	Version     string // e.g. "2.72.0"
	PlatformKey string // e.g. "linux-amd64"
}

LockRequirement describes a (tool, version, platform) combination that must be present in the lockfile under strict mode.

type PlatformEntry

type PlatformEntry struct {
	// Checksum is the hex digest with algorithm prefix: "sha256:<hex>" or "blake3:<hex>".
	// Empty when the backend does not provide checksums.
	Checksum string `toml:"checksum,omitempty"`

	// Size is the artifact size in bytes (0 = unknown).
	Size int64 `toml:"size,omitempty"`

	// URL is the direct download URL.
	URL string `toml:"url,omitempty"`

	// URLAPI is the backend API URL for the asset (GitHub Releases asset API, etc.).
	// Stored for cache-bypass installs that need the canonical API reference.
	URLAPI string `toml:"url_api,omitempty"`

	// GPGKey is the hex fingerprint of the trusted GPG key for this artifact.
	GPGKey string `toml:"gpg_key,omitempty"`
}

PlatformEntry holds the resolved artifact metadata for a single platform.

type ToolLockEntry

type ToolLockEntry struct {
	// Version is the resolved, exact version string (e.g. "2.72.0").
	Version string `toml:"version"`

	// Backend is the backend name used to install this tool (e.g. "github", "ubi").
	Backend string `toml:"backend"`

	// Options holds backend-specific options that affect artifact selection,
	// e.g. {"exe": "rg", "matching": "musl"} for ubi.
	// omitempty so that empty maps are not serialised.
	Options map[string]string `toml:"options,omitempty"`

	// Platforms maps a platform key (e.g. "linux-amd64") to its artifact entry.
	// We use toml:"-" here because the mise format stores these as top-level
	// keys in the tool table with a "platforms." prefix, e.g. ["platforms.linux-amd64"].
	Platforms map[string]*PlatformEntry `toml:"-"`
}

ToolLockEntry corresponds to one [[tools."<key>"]] TOML table.

type ValidationError

type ValidationError struct {
	Errors []string
}

ValidationError accumulates multiple lockfile validation issues.

func (*ValidationError) Error

func (e *ValidationError) Error() string