userconfig

Documentation

Overview

Package userconfig manages user-level epack configuration and utilities. User configuration is stored in ~/.epack/ and is separate from project-level configuration (epack.yaml/epack.lock.yaml).

Directory structure:

~/.epack/
  utilities.lock       # Pinned utility versions and digests
  bin/                 # Installed utility binaries
    {name}/
      {version}/
        {os}-{arch}/
          epack-util-{name}

Index

• Constants
• func BinPath() (string, error)
• func ConfigPath() (string, error)
• func Dir() (string, error)
• func EnsureBinDir() error
• func EnsureDir() error
• func GetConfigValue(key string) (string, error)
• func SaveConfig(cfg *Config) error
• func SetConfigValue(key string, value string) error
• func UtilitiesLockPath() (string, error)
• func UtilityBinaryPath(name string) (string, error)
• func UtilityInstallPath(name, version string) (string, error)
• type ComponentConfig
• type Config
  • func LoadConfig() (*Config, error)
• type InstallOpts
• type InstallResult
• type SecureInstallOptions
• type UnsafeInstallOverrides
• type UtilitiesLock
  • func LoadUtilitiesLock() (*UtilitiesLock, error)
  • func LoadUtilitiesLockFromPath(path string) (*UtilitiesLock, error)
  • func NewUtilitiesLock() *UtilitiesLock
  • func ParseUtilitiesLock(data []byte) (*UtilitiesLock, error)
  • func (lf *UtilitiesLock) GetUtility(name string) (componenttypes.LockedUtility, bool)
  • func (lf *UtilitiesLock) ListUtilities() []string
  • func (lf *UtilitiesLock) RemoveUtility(name string)
  • func (lf *UtilitiesLock) Save() error
  • func (lf *UtilitiesLock) SaveToPath(path string) error
  • func (lf *UtilitiesLock) SetUtility(name string, utility componenttypes.LockedUtility)
  • func (lf *UtilitiesLock) UtilityDigest(name string) (string, error)
• type UtilitySyncer
  • func NewUtilitySyncer() *UtilitySyncer
  • func (s *UtilitySyncer) Install(ctx context.Context, name, source string, opts InstallOpts) (*InstallResult, error)
  • func (s *UtilitySyncer) Remove(name string) error
  • func (s *UtilitySyncer) Verify(name string) error

Constants

const BinDir = "bin"

BinDir is the subdirectory for installed utility binaries.

const ConfigFile = "config.yaml"

ConfigFile is the filename for user configuration.

const DirName = ".epack"

DirName is the user config directory name.

const UtilitiesLockFile = "utilities.lock"

UtilitiesLockFile is the filename for the utilities lockfile.

Functions

func BinPath

func BinPath() (string, error)

BinPath returns the path to the utilities bin directory.

func ConfigPath

func ConfigPath() (string, error)

ConfigPath returns the path to the user config file.

func Dir

func Dir() (string, error)

Dir returns the user config directory path (~/.epack).

func EnsureBinDir

func EnsureBinDir() error

EnsureBinDir creates the bin directory if it doesn't exist.

func EnsureDir

func EnsureDir() error

EnsureDir creates the user config directory if it doesn't exist.

func GetConfigValue

func GetConfigValue(key string) (string, error)

GetConfigValue gets a configuration value by dot-separated key path.

func SaveConfig

func SaveConfig(cfg *Config) error

SaveConfig saves the user configuration to ~/.epack/config.yaml.

func SetConfigValue

func SetConfigValue(key string, value string) error

SetConfigValue sets a configuration value by dot-separated key path. Currently supported: component.trust_local

func UtilitiesLockPath

func UtilitiesLockPath() (string, error)

UtilitiesLockPath returns the path to the utilities lockfile.

func UtilityBinaryPath

func UtilityBinaryPath(name string) (string, error)

UtilityBinaryPath returns the path to an installed utility for the current platform. Returns the path if the utility is installed, or an error if not found.

func UtilityInstallPath

func UtilityInstallPath(name, version string) (string, error)

UtilityInstallPath returns the full path where a utility binary will be installed. Format: ~/.epack/bin/{name}/{version}/{os}-{arch}/epack-util-{name}

Types

type ComponentConfig

type ComponentConfig struct {
	// TrustLocal skips confirmation prompts when running local binaries
	// with 'epack component run'.
	TrustLocal bool `yaml:"trust_local,omitempty"`
}

ComponentConfig holds component authoring settings.

type Config

type Config struct {
	Component ComponentConfig `yaml:"component,omitempty"`
}

Config represents user configuration from ~/.epack/config.yaml

func LoadConfig

func LoadConfig() (*Config, error)

LoadConfig loads the user configuration from ~/.epack/config.yaml. Returns an empty config if the file doesn't exist.

type InstallOpts

type InstallOpts struct {
	Secure SecureInstallOptions
	Unsafe UnsafeInstallOverrides
}

InstallOpts controls utility installation behavior.

type InstallResult

type InstallResult struct {
	Name      string
	Version   string
	Platform  string
	Installed bool
	Verified  bool
	Path      string
}

InstallResult contains the result of installing a utility.

type SecureInstallOptions

type SecureInstallOptions struct{}

type UnsafeInstallOverrides

type UnsafeInstallOverrides struct {
	SkipVerify   bool // Skip Sigstore verification (NOT RECOMMENDED)
	TrustOnFirst bool // Trust digest without Sigstore (NOT RECOMMENDED)
}

type UtilitiesLock

type UtilitiesLock struct {
	SchemaVersion int                                     `yaml:"schema_version"`
	Utilities     map[string]componenttypes.LockedUtility `yaml:"utilities,omitempty"`
}

UtilitiesLock is the lockfile format for user-installed utilities. It mirrors the structure of the project lockfile but only contains utilities.

func LoadUtilitiesLock

func LoadUtilitiesLock() (*UtilitiesLock, error)

LoadUtilitiesLock loads the utilities lockfile from the user config directory. Returns an empty lockfile if the file doesn't exist.

func LoadUtilitiesLockFromPath

func LoadUtilitiesLockFromPath(path string) (*UtilitiesLock, error)

LoadUtilitiesLockFromPath loads a utilities lockfile from a specific path.

func NewUtilitiesLock

func NewUtilitiesLock() *UtilitiesLock

NewUtilitiesLock creates an empty utilities lockfile.

func ParseUtilitiesLock

func ParseUtilitiesLock(data []byte) (*UtilitiesLock, error)

ParseUtilitiesLock parses utilities lockfile data.

func (*UtilitiesLock) GetUtility

func (lf *UtilitiesLock) GetUtility(name string) (componenttypes.LockedUtility, bool)

GetUtility returns a utility entry by name. Returns a defensive copy to prevent callers from mutating internal state.

func (*UtilitiesLock) ListUtilities

func (lf *UtilitiesLock) ListUtilities() []string

ListUtilities returns a sorted list of installed utility names.

func (*UtilitiesLock) RemoveUtility

func (lf *UtilitiesLock) RemoveUtility(name string)

RemoveUtility removes a utility entry.

func (*UtilitiesLock) Save

func (lf *UtilitiesLock) Save() error

Save writes the utilities lockfile to the user config directory.

func (*UtilitiesLock) SaveToPath

func (lf *UtilitiesLock) SaveToPath(path string) error

SaveToPath writes the utilities lockfile to a specific path. SECURITY: Uses symlink-safe operations and atomic write via fd-pinned temp+rename.

func (*UtilitiesLock) SetUtility

func (lf *UtilitiesLock) SetUtility(name string, utility componenttypes.LockedUtility)

SetUtility sets a utility entry.

func (*UtilitiesLock) UtilityDigest

func (lf *UtilitiesLock) UtilityDigest(name string) (string, error)

UtilityDigest returns the expected digest for a utility on the current platform. The digest is used for TOCTOU-safe binary verification during dispatch.

type UtilitySyncer

type UtilitySyncer struct {
	Registry sync.RegistryClient
}

UtilitySyncer handles downloading and verifying utilities.

func NewUtilitySyncer

func NewUtilitySyncer() *UtilitySyncer

NewUtilitySyncer creates a syncer with the default GitHub registry.

func (*UtilitySyncer) Install

func (s *UtilitySyncer) Install(ctx context.Context, name, source string, opts InstallOpts) (*InstallResult, error)

Install downloads and installs a utility from a source. Source format: owner/repo@version (e.g., "locktivity/epack-tools-viewer@v1.0.0")

func (*UtilitySyncer) Remove

func (s *UtilitySyncer) Remove(name string) error

Remove uninstalls a utility.

func (*UtilitySyncer) Verify

func (s *UtilitySyncer) Verify(name string) error

Verify checks that an installed utility matches its lockfile digest.