config

type EnvField[C any] struct {
	Suffix string
	Set    func(c *C, v string)
	Get    func(c C) string // optional: read the current value (needed for vault resolution)
}

type EnvLookup func(key string) (string, bool)

type InstanceSpec[C any, I any] struct {
	// Section is the YAML key in .humanconfig (e.g. "githubs", "jiras").
	Section string

	// EnvPrefix is the prefix for environment variables (e.g. "GITHUB_", "JIRA_").
	EnvPrefix string

	// EnvFields maps config struct fields to env var suffixes.
	EnvFields []EnvField[C]

	// DefaultURL is set on configs with an empty URL before env overrides.
	// Leave empty if no default (e.g. Jira requires explicit URL).
	DefaultURL string

	// Lookup overrides how environment variables are resolved.
	// When nil, os.LookupEnv is used. Set this to a per-project scoped
	// lookup function to support multi-project token isolation.
	Lookup EnvLookup

	// GetName returns the instance name from a config entry.
	GetName func(C) string

	// SetURL sets the URL on the config. Nil if the config has no URL field.
	SetURL func(*C, string)

	// GetURL returns the URL from a config entry. Nil if the config has no URL field.
	GetURL func(C) string

	// Build creates an instance from a config entry. Return (zero, false) to skip
	// the entry (e.g. missing required credentials).
	Build func(C) (I, bool)

	// SecretResolver resolves vault references in config field values.
	// When nil, no vault resolution is performed and values are used as-is.
	// Set this to vault.Resolver.Resolve to enable 1pw:// references.
	SecretResolver SecretResolveFunc
}

type SecretResolveFunc func(ref string) (string, error)