config

Documentation

Overview

Package config provides shared config loading.

Config loading follows a 4-layer priority: 1) --config flag value 2) <CLI>_CONFIG env var 3) project-local config (mode B): <binary-dir>/config.yaml or <binary-dir>/../config.yaml 4) user dir config (mode A or fallback): ~/.config/<cli>/config.yaml (Unix) or %APPDATA%\<cli>\config.yaml (Windows)

The package never reads skillconfig.json (DECIDE-011).

Index

• Constants
• func ExtractEnvVars(s string) []string
• func HasEnvVars(s string) bool
• func Interpolate(s string, getenv func(string) string) (string, error)
• func InterpolateFromOS(s string) (string, error)
• func Resolve(cliName, binaryPath string) (mode string, candidates []string)
• type Config
• type FS
• type LoadResult
  • func LoadConfig(cliName string, args []string, env map[string]string, binaryPath string, fs FS) (*LoadResult, error)

Constants

const (
	// ModeGlobal means the binary is in a user bin directory (e.g., ~/go/bin).
	// Config is loaded from user directory (~/.config/<cli>/config.yaml).
	ModeGlobal = "global"

	// ModeProject means the binary is in a project directory.
	// Config is loaded from project-local first, then user directory as fallback.
	ModeProject = "project"
)

ResolvedMode indicates where the binary was installed.

const Version1 = 1

Version1 is the supported schema version.

Functions

func ExtractEnvVars

func ExtractEnvVars(s string) []string

ExtractEnvVars returns a list of env var names referenced in the string.

func HasEnvVars

func HasEnvVars(s string) bool

HasEnvVars checks if a string contains any ${ENV_VAR} patterns.

func Interpolate

func Interpolate(s string, getenv func(string) string) (string, error)

Interpolate replaces ${ENV_VAR} with the value from the provided getenv function. Only string fields should call this function. Returns error if any referenced env var is not set (empty string is treated as "not set").

Examples:

"${FB_PASSWORD}" with FB_PASSWORD=secret → "secret"
"${FB_PASSWORD}" without FB_PASSWORD set → error
"prefix_${X}_suffix" with X=hello → "prefix_hello_suffix"

func InterpolateFromOS

func InterpolateFromOS(s string) (string, error)

InterpolateFromOS uses os.LookupEnv to resolve environment variables. Empty values are treated as "not set".

func Resolve

func Resolve(cliName, binaryPath string) (mode string, candidates []string)

Resolve detects the install mode and returns candidate config paths.

binaryPath is typically from os.Executable(). The function resolves symlinks before checking against user bin paths.

Returns:

• mode: ModeGlobal or ModeProject
• candidates: ordered list of config file paths to try

Types

type Config

type Config struct {
	// Version is the YAML schema version. Must be 1.
	Version int `yaml:"version"`
}

Config is the base struct. Specific CLIs embed this and add their fields.

Example YAML:

version: 1
instance_url: "http://localhost:8080"
username: "admin"
password: "${FB_PASSWORD}"

type FS

type FS interface {
	ReadFile(path string) ([]byte, error)
	Stat(path string) (os.FileInfo, error)
}

FS is the minimal interface needed for testing file system operations.

type LoadResult

type LoadResult struct {
	// Config is the parsed configuration.
	Config *Config

	// Data is the interpolated YAML content that was parsed.
	Data []byte

	// SourcePath is the path to the config file that was loaded.
	SourcePath string

	// Mode is "explicit", "env", "global", or "project".
	Mode string
}

LoadResult contains the result of loading a config file.

func LoadConfig

func LoadConfig(cliName string, args []string, env map[string]string, binaryPath string, fs FS) (*LoadResult, error)

LoadConfig loads config for the given CLI with 4-layer priority: 1) --config flag value (if set in args) 2) <CLI>_CONFIG env var 3) project-local config (mode B): <binary-dir>/config.yaml or <binary-dir>/../config.yaml 4) user dir config (mode A or fallback): ~/.config/<cli>/config.yaml

The function NEVER reads skillconfig.json (DECIDE-011).

Parameters:

• cliName: CLI name (e.g., "filebrowser-cli")
• args: command line arguments (to extract --config flag)
• env: environment variables (map takes precedence over os env)
• binaryPath: path to the binary (from os.Executable())
• fs: file system interface (nil uses real fs)