config

type APIConfigSection struct {
	// Address to bind the API server (e.g., "0.0.0.0:8090")
	// Maps to CLI flag --addr
	Addr *string `json:"addr,omitempty" toml:"addr,omitempty" yaml:"addr,omitempty"`

	// Nested timeout configuration for API operations
	Timeout *APITimeoutConfigSection `json:"timeout,omitempty" toml:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Nested CORS configuration for cross-origin requests
	CORS *CORSConfigSection `json:"cors,omitempty" toml:"cors,omitempty" yaml:"cors,omitempty"`
}

type APITimeoutConfigSection struct {
	// Shutdown timeout for graceful API server shutdown
	// Maps to CLI flag --timeout-api-shutdown
	Shutdown *Duration `json:"shutdown,omitempty" toml:"shutdown,omitempty" yaml:"shutdown,omitempty"`
}

type CORSConfigSection struct {
	// Enable CORS support
	// Maps to CLI flag --cors-enable
	Enable *bool `json:"enable,omitempty" toml:"enable,omitempty" yaml:"enable,omitempty"`

	// Allowed origins for CORS requests
	// Maps to CLI flag --cors-origins
	Origins []string `json:"allowOrigins,omitempty" toml:"allow_origins,omitempty" yaml:"allow_origins,omitempty"`

	// Allowed HTTP methods for CORS requests
	// Maps to CLI flag --cors-methods
	Methods []string `json:"allowMethods,omitempty" toml:"allow_methods,omitempty" yaml:"allow_methods,omitempty"`

	// Allowed headers for CORS requests
	// Maps to CLI flag --cors-headers
	Headers []string `json:"allowHeaders,omitempty" toml:"allow_headers,omitempty" yaml:"allow_headers,omitempty"`

	// Headers exposed to the client
	// Maps to CLI flag --cors-expose-headers
	ExposeHeaders []string `json:"exposeHeaders,omitempty" toml:"expose_headers,omitempty" yaml:"expose_headers,omitempty"`

	// Allow credentials in CORS requests
	// Maps to CLI flag --cors-credentials
	Credentials *bool `json:"allowCredentials,omitempty" toml:"allow_credentials,omitempty" yaml:"allow_credentials,omitempty"`

	// Maximum age for CORS preflight cache
	// Maps to CLI flag --cors-max-age
	MaxAge *Duration `json:"maxAge,omitempty" toml:"max_age,omitempty" yaml:"max_age,omitempty"`
}

type Categories []Category

type Category string

type Config struct {
	Servers []ServerEntry `toml:"servers"`
	Daemon  *DaemonConfig `toml:"daemon,omitempty"`
	Plugins *PluginConfig `toml:"plugins,omitempty"`
	// contains filtered or unexported fields
}

type DaemonConfig struct {
	// API configuration (includes address and nested timeout/cors)
	API *APIConfigSection `json:"api,omitempty" toml:"api,omitempty" yaml:"api,omitempty"`

	// MCP configuration (includes nested timeout and interval settings)
	MCP *MCPConfigSection `json:"mcp,omitempty" toml:"mcp,omitempty" yaml:"mcp,omitempty"`
}

type DefaultLoader struct{}

type Duration time.Duration

type Flow string

type Getter interface {
	// Get retrieves a configuration value using path segments, or all configured values when no key specified.
	// Single argument gets a specific key, multiple arguments traverse nested structure.
	// Returns the value or any error encountered during retrieval.
	// NOTE: When used without any keys, no errors are returned for missing configuration.
	Get(keys ...string) (any, error)
}

type Initializer interface {
	Init(path string) error
}

type Loader interface {
	Load(path string) (Modifier, error)
}

type MCPConfigSection struct {
	// Nested timeout configuration for MCP operations
	Timeout *MCPTimeoutConfigSection `json:"timeout,omitempty" toml:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Nested interval configuration for MCP periodic operations
	Interval *MCPIntervalConfigSection `json:"interval,omitempty" toml:"interval,omitempty" yaml:"interval,omitempty"`
}

type MCPIntervalConfigSection struct {
	// Health check interval for MCP servers
	// Maps to CLI flag --interval-mcp-health
	Health *Duration `json:"health,omitempty" toml:"health,omitempty" yaml:"health,omitempty"`
}

type MCPTimeoutConfigSection struct {
	// Shutdown timeout for graceful MCP server shutdown
	// Maps to CLI flag --timeout-mcp-shutdown
	Shutdown *Duration `json:"shutdown,omitempty" toml:"shutdown,omitempty" yaml:"shutdown,omitempty"`

	// Initialization timeout for MCP server startup
	// Maps to CLI flag --timeout-mcp-init
	Init *Duration `json:"init,omitempty" toml:"init,omitempty" yaml:"init,omitempty"`

	// Health check timeout for MCP servers
	// Maps to CLI flag --timeout-mcp-health
	Health *Duration `json:"health,omitempty" toml:"health,omitempty" yaml:"health,omitempty"`
}

type Modifier interface {
	AddServer(entry ServerEntry) error
	RemoveServer(name string) error
	ListServers() []ServerEntry
	SaveConfig() error
}

type MoveOption func(*moveOptions) error

type PluginConfig struct {
	// Dir specifies the directory containing plugin binaries.
	Dir string `json:"dir,omitempty" toml:"dir,omitempty" yaml:"dir,omitempty"`

	// Authentication plugins execute first, validating identity.
	Authentication []PluginEntry `json:"authentication,omitempty" toml:"authentication,omitempty" yaml:"authentication,omitempty"`

	// Authorization plugins verify permissions after authentication.
	Authorization []PluginEntry `json:"authorization,omitempty" toml:"authorization,omitempty" yaml:"authorization,omitempty"`

	// RateLimiting plugins enforce request rate limits.
	RateLimiting []PluginEntry `json:"rateLimiting,omitempty" toml:"rate_limiting,omitempty" yaml:"rate_limiting,omitempty"`

	// Validation plugins check request/response structure and content.
	Validation []PluginEntry `json:"validation,omitempty" toml:"validation,omitempty" yaml:"validation,omitempty"`

	// Content plugins transform request/response payloads.
	Content []PluginEntry `json:"content,omitempty" toml:"content,omitempty" yaml:"content,omitempty"`

	// Observability plugins collect metrics and traces (non-blocking).
	Observability []PluginEntry `json:"observability,omitempty" toml:"observability,omitempty" yaml:"observability,omitempty"`

	// Audit plugins log compliance and security events (typically required).
	Audit []PluginEntry `json:"audit,omitempty" toml:"audit,omitempty" yaml:"audit,omitempty"`
}

type PluginEntry struct {
	// Name of the plugin binary in the plugins directory.
	Name string `json:"name" toml:"name" yaml:"name"`

	// CommitHash for validating plugin version against metadata.
	CommitHash *string `json:"commitHash,omitempty" toml:"commit_hash,omitempty" yaml:"commit_hash,omitempty"`

	// Required indicates if plugin failure should block the request.
	Required *bool `json:"required,omitempty" toml:"required,omitempty" yaml:"required,omitempty"`

	// Flows specifies when the plugin executes (request, response, or both).
	// Treated as a set - duplicates are rejected during validation.
	Flows []Flow `json:"flows" toml:"flows" yaml:"flows"`
}

type PluginModifier interface {
	// Plugin retrieves a plugin by category and name.
	Plugin(category Category, name string) (PluginEntry, bool)

	// UpsertPlugin creates or updates a plugin entry.
	UpsertPlugin(category Category, entry PluginEntry) (context.UpsertResult, error)

	// DeletePlugin removes a plugin entry.
	DeletePlugin(category Category, name string) (context.UpsertResult, error)

	// ListPlugins returns all plugins in a category.
	ListPlugins(category Category) []PluginEntry
}

type Provider interface {
	Initializer
	Loader
}

type SchemaKey struct {
	// Path is the configuration key path (e.g., "addr", "enable", "shutdown").
	Path string
	// Type describes the expected value type (e.g., "string", "bool", "duration", "[]string").
	Type string
	// Description provides a human-readable explanation of the configuration key.
	Description string
}

type SchemaProvider interface {
	// AvailableKeys returns all configuration keys available at this level.
	// Keys are returned without prefixes - parent sections add prefixes when recursing.
	AvailableKeys() []SchemaKey
}

type ServerEntry struct {
	// Name is the unique name/ID from the registry, referenced by the user.
	// e.g. 'github-server'
	Name string `json:"name" toml:"name" yaml:"name"`

	// Package contains the identifier including runtime and version.
	// e.g. 'uvx::modelcontextprotocol/[email protected]'
	Package string `json:"package" toml:"package" yaml:"package"`

	// Tools lists the names of the tools which should be allowed on this server.
	// e.g. 'create_repository'
	Tools []string `json:"tools" toml:"tools" yaml:"tools"`

	// RequiredEnvVars captures any environment variables required to run the server.
	RequiredEnvVars []string `json:"requiredEnv,omitempty" toml:"required_env,omitempty" yaml:"required_env,omitempty"`

	// RequiredPositionalArgs captures any command line args that must be positional, and which are required to run the server.
	// The arguments must be ordered by their position (ascending).
	RequiredPositionalArgs []string `json:"requiredPositionalArgs,omitempty" toml:"required_args_positional,omitempty"`

	// RequiredValueArgs captures any command line args that need values, which are required to run the server.
	RequiredValueArgs []string `json:"requiredArgs,omitempty" toml:"required_args,omitempty" yaml:"required_args,omitempty"`

	// RequiredBoolArgs captures any command line args that are boolean flags when present, which are required to run the server.
	RequiredBoolArgs []string `json:"requiredArgsBool,omitempty" toml:"required_args_bool,omitempty" yaml:"required_args_bool,omitempty"`

	// Volumes maps volume names to their Docker volume configuration.
	Volumes VolumesEntry `json:"volumes,omitempty" toml:"volumes,omitempty" yaml:"volumes,omitempty"`
}

type Setter interface {
	// Set applies a configuration value using dot-separated path notation.
	// An empty value removes/clears the configuration at the given path.
	// Returns the operation performed (Created, Updated, Deleted, Noop) and any validation error.
	Set(path string, value string) (context.UpsertResult, error)
}

type ValidatingLoader struct {
	Loader
	// contains filtered or unexported fields
}

type ValidationPredicate func(*Config) error

type Validator interface {
	// Validate checks the configuration for errors and returns combined validation errors.
	// Uses errors.Join to combine multiple validation errors from child sections.
	Validate() error
}

type VolumeEntry struct {
	// Path is the container mount path.
	// e.g., "/workspace", "/home/nonroot/.kube/config".
	Path string `toml:"path"`

	// Required indicates whether the volume must be configured by the user.
	Required bool `toml:"required"`
}

type VolumesEntry map[string]VolumeEntry