config

Documentation

Overview

Package config provides JSON config management for opencode: path resolution, loading, atomic saving, and field access via map[string]interface{}.

The map-based JSON strategy preserves ALL unknown/future fields automatically, which is critical for MCP API keys, permissions, and any fields the tool does not explicitly model.

Index

• Variables
• func CleanOldBackups(configPath string, keep int) error
• func CreateBackup(configPath string) (string, error)
• func GetConfigPath(override string) (string, error)
• func IsSystemAgent(name string) bool
• func ValidateModel(modelID string, available []opencode.Model) bool
• type Config
  • func LoadConfig(path string) (*Config, error)
  • func (c *Config) Data() map[string]interface{}
  • func (c *Config) GetAgentField(agentName, fieldName string) (interface{}, bool)
  • func (c *Config) GetAgentMode(agentName string) string
  • func (c *Config) GetAgents() (primary, subagents, disabled []string)
  • func (c *Config) GetGlobalModel() (string, bool)
  • func (c *Config) IsAgentDisabled(agentName string) bool
  • func (c *Config) IsAgentHidden(agentName string) bool
  • func (c *Config) Path() string
  • func (c *Config) Save() error
  • func (c *Config) SetAgentField(agentName, fieldName string, value interface{}) error
  • func (c *Config) SetGlobalModel(model string)

Variables

var (
	// ErrConfigNotFound is returned when the config file does not exist at the
	// resolved path.
	ErrConfigNotFound = errors.New("config file not found")

	// ErrBackupFailed is returned when a backup copy of the config cannot be
	// created before a write operation.
	ErrBackupFailed = errors.New("failed to create backup")

	// ErrWriteFailed is returned when the atomic write to the config file fails
	// (temp write or rename).
	ErrWriteFailed = errors.New("failed to write config file")
)

Sentinel errors for programmatic error classification via errors.Is. Error messages MUST reference paths only, never config values (REQ-CFG-013).

Functions

func CleanOldBackups

func CleanOldBackups(configPath string, keep int) error

CleanOldBackups removes backup files beyond the retention count. Backups are matched via "opencode.json.backup.*" in the same directory as configPath, sorted lexicographically (timestamps sort correctly), and the N most recent are kept while the rest are deleted (REQ-CFG-010).

A retention value of 0 means skip: no backups are deleted. If fewer backups exist than the retention count, or no backups exist at all, CleanOldBackups returns nil without modifying anything.

func CreateBackup

func CreateBackup(configPath string) (string, error)

CreateBackup creates a timestamped backup of the config file in the same directory as configPath. The backup is named "opencode.json.backup.{YYYYMMDD-HHMMSS}" and is a byte-for-byte copy of the source written with 0o600 permissions on Unix (REQ-CFG-009).

Returns the path of the created backup file, or an error wrapping ErrBackupFailed on read or write failure.

func GetConfigPath

func GetConfigPath(override string) (string, error)

GetConfigPath resolves the config file path.

If override is non-empty it is returned verbatim (flag or env override). Otherwise the default path is constructed as filepath.Join(os.UserHomeDir(), ".config", "opencode", "opencode.json").

os.UserHomeDir() is used — NOT os.UserConfigDir() — because opencode uses an XDG-style ".config/opencode/" path on ALL platforms, while os.UserConfigDir() returns %AppData% on Windows (wrong for opencode).

func IsSystemAgent

func IsSystemAgent(name string) bool

IsSystemAgent returns true if the agent name is a system agent ("compactación", "title", or "summary"). The match is case-sensitive.

func ValidateModel

func ValidateModel(modelID string, available []opencode.Model) bool

ValidateModel checks if a model ID exists in the available models list.

Uses exact, case-sensitive match on the FullName field of each Model. Returns true only if modelID exactly equals the FullName of some entry in available; returns false for partial matches, case-insensitive matches, empty inputs, or an empty available list (REQ-CFG-012).

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config wraps the parsed config data and the filesystem path it was loaded from (or will be saved to).

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads the JSON config file at the given path and unmarshals it into a Config wrapping map[string]interface{}.

Returns ErrConfigNotFound (wrapping the path) when the file does not exist. Returns a JSON parse error when the file exists but contains invalid JSON. Error messages reference the path only, never config values (REQ-CFG-013).

func (*Config) Data

func (c *Config) Data() map[string]interface{}

Data returns the raw parsed config map. Callers MUST NOT mutate the returned map without understanding that changes are reflected in the Config.

func (*Config) GetAgentField

func (c *Config) GetAgentField(agentName, fieldName string) (interface{}, bool)

GetAgentField returns the value of a field for an agent. Returns (nil, false) if the agent or the field does not exist (REQ-CFG-003).

func (*Config) GetAgentMode

func (c *Config) GetAgentMode(agentName string) string

GetAgentMode returns the mode string for an agent ("primary", "subagent", or "all"). Returns "all" when the agent has no mode field (REQ-CFG-003).

func (*Config) GetAgents

func (c *Config) GetAgents() (primary, subagents, disabled []string)

GetAgents returns all agent names grouped by mode: primary, subagents, and disabled. System agents are excluded from every slice. An agent with disable:true appears in the disabled slice AND in its mode slice (primary or subagent), so callers can filter disabled agents out of either group (REQ-CFG-008).

func (*Config) GetGlobalModel

func (c *Config) GetGlobalModel() (string, bool)

GetGlobalModel returns the top-level "model" key value. Returns ("", false) if the key is absent or not a string (REQ-CFG-004).

func (*Config) IsAgentDisabled

func (c *Config) IsAgentDisabled(agentName string) bool

IsAgentDisabled returns true if the agent has disable: true (REQ-CFG-006).

func (*Config) IsAgentHidden

func (c *Config) IsAgentHidden(agentName string) bool

IsAgentHidden returns true if the agent has hidden: true (REQ-CFG-007).

func (*Config) Path

func (c *Config) Path() string

Path returns the filesystem path associated with this Config.

func (*Config) Save

func (c *Config) Save() error

Save writes the config data atomically to the configured path.

The write is atomic: data is marshalled with 2-space indentation, written to a temporary file (path + ".tmp") with 0o600 permissions, then os.Rename replaces the target. If the rename fails the temp file is cleaned up and the original file remains untouched.

Returns ErrWriteFailed (wrapping the path) on any write or rename failure.

func (*Config) SetAgentField

func (c *Config) SetAgentField(agentName, fieldName string, value interface{}) error

SetAgentField sets a field value for an agent. If the agent does not exist it is created automatically. Returns an error if the agent is disabled (disable: true), since disabled agents must not be mutated (REQ-CFG-005).

func (*Config) SetGlobalModel

func (c *Config) SetGlobalModel(model string)

SetGlobalModel sets the top-level "model" key (REQ-CFG-004).