config

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package config handles staghorn configuration.

Package config handles staghorn configuration.

Package config handles staghorn configuration.

Package config handles staghorn configuration.

Package config handles staghorn configuration.

Index

Constants

View Source
const (
	DefaultVersion  = 1
	DefaultPath     = "CLAUDE.md"
	DefaultCacheTTL = "24h"
)

Default values.

View Source
const (
	DefaultFileMode = 0644
	DefaultDirMode  = 0755
)

File permission constants for consistent file creation.

Variables

View Source
var DefaultTrustedSources = []string{
	"HartBrook/staghorn-community",
}

DefaultTrustedSources contains sources that are trusted by default. These are official staghorn repositories maintained by HartBrook.

Functions

func Exists

func Exists() bool

Exists checks if a config file exists at the default location.

func IsSourceRepo added in v0.7.0

func IsSourceRepo(projectRoot string) bool

IsSourceRepo checks if the given directory is a staghorn source repo. A source repo has .staghorn/source.yaml with source_repo: true.

func IsTrusted added in v0.3.0

func IsTrusted(repo string, trusted []string) bool

IsTrusted checks if a repository is in the trusted list. The trusted list can contain:

  • Full repo references: "owner/repo"
  • Org-level trust: "owner" (trusts all repos from that owner)

func ParseRepo added in v0.3.0

func ParseRepo(repoStr string) (owner, repo string, err error)

ParseRepo extracts owner and repo name from a repository string. Accepts formats:

func ProjectClaudeCommandsDir added in v0.2.0

func ProjectClaudeCommandsDir(projectRoot string) string

ProjectClaudeCommandsDir returns the path for project-level Claude Code commands.

func ProjectClaudeRulesDir added in v0.8.0

func ProjectClaudeRulesDir(projectRoot string) string

ProjectClaudeRulesDir returns the path for project-level Claude Code rules.

func ProjectClaudeSkillsDir added in v0.8.0

func ProjectClaudeSkillsDir(projectRoot string) string

ProjectClaudeSkillsDir returns the path for project-level Claude Code skills.

func ProjectCommandsDir added in v0.2.0

func ProjectCommandsDir(projectRoot string) string

ProjectCommandsDir returns the path for project-specific commands. This is relative to the project root (.staghorn/commands/).

func ProjectEvalsDir added in v0.4.0

func ProjectEvalsDir(projectRoot string) string

ProjectEvalsDir returns the path for project-specific evals.

func ProjectRulesDir added in v0.8.0

func ProjectRulesDir(projectRoot string) string

ProjectRulesDir returns the path for project-specific rules.

func ProjectSkillsDir added in v0.8.0

func ProjectSkillsDir(projectRoot string) string

ProjectSkillsDir returns the path for project-specific skills.

func Save

func Save(cfg *Config) error

Save writes config to the default location.

func SaveTo

func SaveTo(cfg *Config, path string) error

SaveTo writes config to a specific path.

func TrustWarning added in v0.3.0

func TrustWarning(repo string) string

TrustWarning returns a warning message for untrusted sources.

func WriteSourceRepoConfig added in v0.7.0

func WriteSourceRepoConfig(projectRoot string) error

WriteSourceRepoConfig writes a source.yaml file to mark a repo as a source repo.

Types

type CacheConfig

type CacheConfig struct {
	TTL string `yaml:"ttl"` // e.g., "24h"
}

CacheConfig contains cache settings.

func (*CacheConfig) TTLDuration

func (c *CacheConfig) TTLDuration() time.Duration

TTLDuration returns the cache TTL as a time.Duration.

type Config

type Config struct {
	Version int `yaml:"version"`

	// Source defines where to fetch configs from.
	// Can be a simple string ("owner/repo") or a structured object for multi-source.
	Source Source `yaml:"source"`

	// Trusted is a list of repos/orgs that don't require confirmation.
	// Examples: "acme-corp" (trusts all repos from org), "user/repo" (specific repo)
	Trusted []string `yaml:"trusted,omitempty"`

	Cache     CacheConfig    `yaml:"cache"`
	Languages LanguageConfig `yaml:"languages,omitempty"`
	Optimize  OptimizeConfig `yaml:"optimize,omitempty"`
}

Config represents the staghorn configuration file.

func Load

func Load() (*Config, error)

Load reads and validates config from the default location.

func LoadFrom

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

LoadFrom reads and validates config from a specific path.

func NewSimpleConfig added in v0.3.0

func NewSimpleConfig(repo string) *Config

NewSimpleConfig creates a config with a single source.

func (*Config) DefaultOwnerRepo added in v0.3.0

func (c *Config) DefaultOwnerRepo() (owner, repo string, err error)

DefaultOwnerRepo returns the owner and repo for the default source. This is a convenience method for the common single-source case.

func (*Config) IsTrustedSource added in v0.3.0

func (c *Config) IsTrustedSource(repo string) bool

IsTrustedSource checks if a repo is trusted according to this config. It checks both the user's trusted list and the default trusted sources.

func (*Config) SourceRepo added in v0.3.0

func (c *Config) SourceRepo() string

SourceRepo returns the full repo string for display purposes.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks config for required fields and valid values.

type LanguageConfig

type LanguageConfig struct {
	AutoDetect bool     `yaml:"auto_detect"`
	Enabled    []string `yaml:"enabled,omitempty"`
	Disabled   []string `yaml:"disabled,omitempty"`
}

LanguageConfig contains language-specific settings.

type OptimizeConfig added in v0.6.0

type OptimizeConfig struct {
	WarnThreshold     int    `yaml:"warn_threshold,omitempty"`     // Token threshold for warning (default: 3000)
	TargetTokens      int    `yaml:"target_tokens,omitempty"`      // Default target token count
	Model             string `yaml:"model,omitempty"`              // Model for optimization
	DeterministicOnly bool   `yaml:"deterministic_only,omitempty"` // Skip LLM, only do deterministic cleanup
}

OptimizeConfig contains optimization settings.

type Paths

type Paths struct {
	ConfigDir         string // ~/.config/staghorn
	CacheDir          string // ~/.cache/staghorn
	ConfigFile        string // ~/.config/staghorn/config.yaml
	PersonalMD        string // ~/.config/staghorn/personal.md
	PersonalCommands  string // ~/.config/staghorn/commands
	PersonalLanguages string // ~/.config/staghorn/languages
	PersonalEvals     string // ~/.config/staghorn/evals
	PersonalRules     string // ~/.config/staghorn/rules
	PersonalSkills    string // ~/.config/staghorn/skills
}

Paths provides all staghorn-related filesystem paths.

func NewPaths

func NewPaths() *Paths

NewPaths creates Paths using ~/.config and ~/.cache directories. We use these paths explicitly for cross-platform consistency rather than platform-specific defaults (like ~/Library/Application Support on macOS).

func NewPathsWithOverrides

func NewPathsWithOverrides(configDir, cacheDir string) *Paths

NewPathsWithOverrides allows overriding directories for testing.

func (*Paths) CacheFile

func (p *Paths) CacheFile(owner, repo string) string

CacheFile returns the path for a cached team config.

func (*Paths) CacheMetadataFile

func (p *Paths) CacheMetadataFile(owner, repo string) string

CacheMetadataFile returns the path for cache metadata sidecar.

func (*Paths) ClaudeCommandsDir added in v0.2.0

func (p *Paths) ClaudeCommandsDir() string

ClaudeCommandsDir returns the path for Claude Code custom commands.

func (*Paths) ClaudeRulesDir added in v0.8.0

func (p *Paths) ClaudeRulesDir() string

ClaudeRulesDir returns the path for Claude Code user-level rules.

func (*Paths) ClaudeSkillsDir added in v0.8.0

func (p *Paths) ClaudeSkillsDir() string

ClaudeSkillsDir returns the path for Claude Code user-level skills.

func (*Paths) OptimizedDir added in v0.6.0

func (p *Paths) OptimizedDir() string

OptimizedDir returns the path for optimized config storage.

func (*Paths) OptimizedFile added in v0.6.0

func (p *Paths) OptimizedFile(owner, repo string) string

OptimizedFile returns the path for an optimized config file.

func (*Paths) OptimizedMetaFile added in v0.6.0

func (p *Paths) OptimizedMetaFile(owner, repo string) string

OptimizedMetaFile returns the path for optimization metadata sidecar.

func (*Paths) TeamCommandsDir added in v0.2.0

func (p *Paths) TeamCommandsDir(owner, repo string) string

TeamCommandsDir returns the path for cached team commands.

func (*Paths) TeamEvalsDir added in v0.4.0

func (p *Paths) TeamEvalsDir(owner, repo string) string

TeamEvalsDir returns the path for cached team evals.

func (*Paths) TeamLanguagesDir

func (p *Paths) TeamLanguagesDir(owner, repo string) string

TeamLanguagesDir returns the path for cached team language configs.

func (*Paths) TeamRulesDir added in v0.8.0

func (p *Paths) TeamRulesDir(owner, repo string) string

TeamRulesDir returns the path for cached team rules.

func (*Paths) TeamSkillsDir added in v0.8.0

func (p *Paths) TeamSkillsDir(owner, repo string) string

TeamSkillsDir returns the path for cached team skills.

func (*Paths) TeamTemplatesDir

func (p *Paths) TeamTemplatesDir(owner, repo string) string

TeamTemplatesDir returns the path for cached team project templates.

type ProjectPaths

type ProjectPaths struct {
	Root         string // Project root directory
	StaghornDir  string // .staghorn/
	SourceMD     string // .staghorn/project.md (source of truth)
	OutputMD     string // ./CLAUDE.md (generated output)
	CommandsDir  string // .staghorn/commands/
	LanguagesDir string // .staghorn/languages/
	EvalsDir     string // .staghorn/evals/
	RulesDir     string // .staghorn/rules/
	SkillsDir    string // .staghorn/skills/
	ConfigFile   string // .staghorn/config.yaml (optional project config)
}

ProjectPaths holds paths for project-level config management.

func NewProjectPaths

func NewProjectPaths(projectRoot string) *ProjectPaths

NewProjectPaths creates ProjectPaths for a given project root.

type Source added in v0.3.0

type Source struct {
	// Simple holds the repo string when source is a simple string.
	Simple string

	// Multi holds the structured config when source is an object.
	Multi *SourceConfig
}

Source wraps the flexible source configuration. It can be unmarshaled from either a string or an object.

func (*Source) AllRepos added in v0.3.0

func (s *Source) AllRepos() []string

AllRepos returns all unique repositories referenced by this source config. Useful for syncing all sources at once.

func (*Source) DefaultRepo added in v0.3.0

func (s *Source) DefaultRepo() string

DefaultRepo returns the default repository for this source configuration.

func (*Source) IsEmpty added in v0.3.0

func (s *Source) IsEmpty() bool

IsEmpty returns true if no source is configured.

func (*Source) IsMultiSource added in v0.3.0

func (s *Source) IsMultiSource() bool

IsMultiSource returns true if this is a multi-source configuration.

func (Source) MarshalYAML added in v0.3.0

func (s Source) MarshalYAML() (interface{}, error)

MarshalYAML implements custom marshaling to output the appropriate format.

func (*Source) RepoForBase added in v0.3.0

func (s *Source) RepoForBase() string

RepoForBase returns the repository to use for the base CLAUDE.md.

func (*Source) RepoForCommand added in v0.3.0

func (s *Source) RepoForCommand(cmd string) string

RepoForCommand returns the repository to use for a specific command.

func (*Source) RepoForLanguage added in v0.3.0

func (s *Source) RepoForLanguage(lang string) string

RepoForLanguage returns the repository to use for a specific language config.

func (*Source) RepoForSkill added in v0.8.0

func (s *Source) RepoForSkill(skill string) string

RepoForSkill returns the repository to use for a specific skill.

func (*Source) UnmarshalYAML added in v0.3.0

func (s *Source) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements custom unmarshaling to handle both string and object formats.

func (*Source) Validate added in v0.3.0

func (s *Source) Validate() error

Validate checks that the source configuration is valid. An empty source is valid (for local-only mode).

type SourceConfig added in v0.3.0

type SourceConfig struct {
	// Default is the fallback source for all items not explicitly configured.
	Default string `yaml:"default,omitempty"`

	// Base overrides the source for the main CLAUDE.md file.
	Base string `yaml:"base,omitempty"`

	// Languages maps language IDs to their source repos.
	// Example: { "python": "acme/python-standards" }
	Languages map[string]string `yaml:"languages,omitempty"`

	// Commands maps command names to their source repos.
	// Example: { "code-review": "acme/internal-commands" }
	Commands map[string]string `yaml:"commands,omitempty"`

	// Skills maps skill names to their source repos.
	// Example: { "react": "vercel-labs/agent-skills/skills/react" }
	Skills map[string]string `yaml:"skills,omitempty"`
}

SourceConfig supports both simple string and multi-source configurations. Simple: source: "owner/repo" Multi: source: { default: "owner/repo", base: "other/repo", languages: {...} }

type SourceRepoConfig added in v0.7.0

type SourceRepoConfig struct {
	SourceRepo bool `yaml:"source_repo"`
}

SourceRepoConfig represents a .staghorn/source.yaml file that marks a repository as a staghorn source repo (team/community standards).

func LoadSourceRepoConfig added in v0.7.0

func LoadSourceRepoConfig(projectRoot string) (*SourceRepoConfig, error)

LoadSourceRepoConfig loads .staghorn/source.yaml from the given project root. Returns nil and an error if the file doesn't exist or can't be parsed.

type SourceRepoPaths added in v0.7.0

type SourceRepoPaths struct {
	Root         string // Project root
	ConfigFile   string // .staghorn/source.yaml
	ClaudeMD     string // ./CLAUDE.md
	CommandsDir  string // ./commands/
	LanguagesDir string // ./languages/
	TemplatesDir string // ./templates/
	EvalsDir     string // ./evals/
}

SourceRepoPaths provides paths for source repo operations. These are the standard locations for team repo content.

func NewSourceRepoPaths added in v0.7.0

func NewSourceRepoPaths(projectRoot string) *SourceRepoPaths

NewSourceRepoPaths creates SourceRepoPaths for a given project root.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL