providers

type Constructor func(atmosConfig *schema.AtmosConfiguration, name string, sectionProviders map[string]any) (Provider, error)

type Coordinate struct {
	Stack     string
	Component string
	Key       string
	// Scope is the addressing level (instance, stack, or global). Providers interpret it in
	// their own terms. Empty is treated as ScopeInstance. For ScopeStack, Component is empty;
	// for ScopeGlobal, both Stack and Component are empty.
	Scope Scope
}

type FilePathProvider interface {
	// FilePath returns the backing file path the coordinate resolves to.
	FilePath(coord Coordinate) (string, error)
}

type FileResettable interface {
	// Reset overwrites the provider's backing file with an empty document for the coordinate's scope.
	Reset(coord Coordinate) error
}

type KeyGenerator interface {
	// HasKey reports whether the vault already has resolvable key material (so callers can decide
	// whether to generate).
	HasKey() bool
	// GenerateKey produces new key material and records it in the vault's configured sinks. basePath
	// roots any relative output. Implementations append/merge and never clobber other vaults'
	// material. The KeygenResult describes what was produced for user-facing output.
	GenerateKey(basePath string) (*KeygenResult, error)
}

type KeygenOutput struct {
	// Label names the artifact (e.g. "private identity", "public recipient", "certificate").
	Label string
	// Location is where it was written (a file path or a store reference).
	Location string
	// Sensitive marks private material that must be kept out of version control.
	Sensitive bool
}

type KeygenResult struct {
	// Vault is the named secrets vault (`secrets.providers.<name>`) the material belongs to.
	Vault string
	// Kind is the provider kind that generated it (e.g. "sops/age", "ssl/x509").
	Kind string
	// Summary is a one-line human description (e.g. "Generated an age key pair.").
	Summary string
	// Outputs are the artifacts written, with where each landed.
	Outputs []KeygenOutput
	// Public is optional public material safe to print/share (an age recipient, a certificate, a
	// public key). Empty when there is none.
	Public string
}

type LocalStatus interface {
	// LocalStatusCheck reports whether Status() is credential-free for this provider instance.
	LocalStatusCheck() bool
}

type Provider interface {
	// Set stores a value at the coordinate.
	Set(coord Coordinate, value any) error
	// Get retrieves a value at the coordinate.
	Get(coord Coordinate) (any, error)
	// Delete removes a value at the coordinate.
	Delete(coord Coordinate) error
	// Status reports whether a value exists at the coordinate.
	Status(coord Coordinate) (bool, error)
	// Kind returns the provider kind (e.g. aws/ssm, sops/age) for display/observability.
	Kind() string
	// SupportsScope reports whether the provider can represent the given scope. A declared
	// secret whose resolved scope is unsupported is rejected with ErrScopeUnsupported before any
	// write. An empty scope (ScopeInstance) must always be supported.
	SupportsScope(scope Scope) bool
}

type Scope string