lockfile

Documentation

Overview

Package lockfile loads and saves the gskill.lock file as deterministic, sorted-key JSON capturing resolved install reality.

Index

• Constants
• Variables
• func CheckConsistency(m *manifest.Manifest, lf *Lockfile) error
• func Marshal(lf *Lockfile) ([]byte, error)
• func Save(path string, lf *Lockfile) error
• type Installation
• type LockedSkill
• type Lockfile
  • func Load(path string) (*Lockfile, error)
  • func New() *Lockfile
  • func Unmarshal(data []byte) (*Lockfile, error)
• type Metadata
• type Provenance
• type Requested
• type Requires
• type Resolved
• type Source

Constants

const SchemaVersion = 1

SchemaVersion is the lockfile schema this build understands (FR-006).

Variables

var ErrUnsupportedSchema = errors.New("unsupported lockfile schema version")

ErrUnsupportedSchema is returned for a lockfile_version newer than this build.

Functions

func CheckConsistency

func CheckConsistency(m *manifest.Manifest, lf *Lockfile) error

CheckConsistency reports whether the manifest and lockfile agree closely enough that a frozen restore would not need to change the lock. A disagreement (a skill present in only one, or a changed source/requested version) maps to the lockfile-mismatch exit code 4 (FR-037, SC-002).

func Marshal

func Marshal(lf *Lockfile) ([]byte, error)

Marshal serializes lf deterministically: sorted map keys, 2-space indent, a trailing newline, and no HTML escaping (FR-004).

func Save

func Save(path string, lf *Lockfile) error

Save writes lf to path atomically.

Types

type Installation

type Installation struct {
	Scope      string            `json:"scope"`
	Mode       string            `json:"mode"`
	Agents     []string          `json:"agents"`
	ActivePath string            `json:"active_path,omitempty"`
	Targets    map[string]string `json:"targets"`
	Modes      map[string]string `json:"modes,omitempty"`
}

Installation is the placement record (FR-019, FR-020, FR-027, FR-028). Mode is the representative install mode; Modes records the actual mode per agent for the case where they differ (e.g. a symlink falls back to a copy). ActivePath is the project-relative active-layer entry (.agents/skills/<name>) that every agent target derives from; it is absent on legacy (pre-active-layer) entries, which signals a migration on the next reconcile/repair.

type LockedSkill

type LockedSkill struct {
	Source       Source       `json:"source"`
	Requested    Requested    `json:"requested"`
	Resolved     Resolved     `json:"resolved"`
	Metadata     Metadata     `json:"metadata"`
	Requires     Requires     `json:"requires"`
	Installation Installation `json:"installation"`
	Provenance   Provenance   `json:"provenance"`
}

LockedSkill is the full reproduction record for one skill.

type Lockfile

type Lockfile struct {
	LockfileVersion int                    `json:"lockfile_version"`
	Skills          map[string]LockedSkill `json:"skills"`
}

Lockfile is the machine-generated record of resolved reality (FR-003).

func Load

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

Load reads and parses the lockfile at path.

func New

func New() *Lockfile

New returns an empty lockfile at the current schema version.

func Unmarshal

func Unmarshal(data []byte) (*Lockfile, error)

Unmarshal parses lockfile bytes and refuses a newer schema version (FR-006).

type Metadata

type Metadata struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Version     string `json:"version,omitempty"`
	License     string `json:"license,omitempty"`
}

Metadata is the captured SKILL.md frontmatter.

type Provenance

type Provenance struct {
	FetchedAt string `json:"fetched_at,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
	Trust     string `json:"trust"`
}

Provenance is best-effort trust info. Timestamps are excluded from reproducible determinism (FR-004).

type Requested

type Requested struct {
	Version string `json:"version,omitempty"`
	Ref     string `json:"ref,omitempty"`
	Commit  string `json:"commit,omitempty"`
}

Requested echoes the human's intent (FR-010).

type Requires

type Requires struct {
	Skills      []string `json:"skills"`
	Commands    []string `json:"commands"`
	Environment []string `json:"environment"`
	MCP         []string `json:"mcp"`
}

Requires records declared needs, surfaced but never resolved (FR-032).

type Resolved

type Resolved struct {
	Version       string `json:"version,omitempty"`
	RefKind       string `json:"ref_kind"`
	Tag           string `json:"tag,omitempty"`
	Branch        string `json:"branch,omitempty"`
	Commit        string `json:"commit,omitempty"`
	TreeHash      string `json:"tree_hash,omitempty"`
	ContentHash   string `json:"content_hash"`
	SkillFileHash string `json:"skill_file_hash,omitempty"`
	MutableRef    bool   `json:"mutable_ref"`
	LocalPathHash string `json:"local_path_hash,omitempty"`
}

Resolved is the immutable identity gskill pinned to (FR-009, FR-010).

type Source

type Source struct {
	Type     string `json:"type"`
	Original string `json:"original"`
	URL      string `json:"url,omitempty"`
	Owner    string `json:"owner,omitempty"`
	Repo     string `json:"repo,omitempty"`
	Path     string `json:"path,omitempty"`
}

Source is the normalized origin of a skill.