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
- Variables
- func Exists() bool
- func IsSourceRepo(projectRoot string) bool
- func IsTrusted(repo string, trusted []string) bool
- func ParseRepo(repoStr string) (owner, repo string, err error)
- func ProjectClaudeCommandsDir(projectRoot string) string
- func ProjectClaudeRulesDir(projectRoot string) string
- func ProjectClaudeSkillsDir(projectRoot string) string
- func ProjectCommandsDir(projectRoot string) string
- func ProjectEvalsDir(projectRoot string) string
- func ProjectRulesDir(projectRoot string) string
- func ProjectSkillsDir(projectRoot string) string
- func Save(cfg *Config) error
- func SaveTo(cfg *Config, path string) error
- func TrustWarning(repo string) string
- func WriteSourceRepoConfig(projectRoot string) error
- type CacheConfig
- type Config
- type LanguageConfig
- type OptimizeConfig
- type Paths
- func (p *Paths) CacheFile(owner, repo string) string
- func (p *Paths) CacheMetadataFile(owner, repo string) string
- func (p *Paths) ClaudeCommandsDir() string
- func (p *Paths) ClaudeRulesDir() string
- func (p *Paths) ClaudeSkillsDir() string
- func (p *Paths) OptimizedDir() string
- func (p *Paths) OptimizedFile(owner, repo string) string
- func (p *Paths) OptimizedMetaFile(owner, repo string) string
- func (p *Paths) TeamCommandsDir(owner, repo string) string
- func (p *Paths) TeamEvalsDir(owner, repo string) string
- func (p *Paths) TeamLanguagesDir(owner, repo string) string
- func (p *Paths) TeamRulesDir(owner, repo string) string
- func (p *Paths) TeamSkillsDir(owner, repo string) string
- func (p *Paths) TeamTemplatesDir(owner, repo string) string
- type ProjectPaths
- type Source
- func (s *Source) AllRepos() []string
- func (s *Source) DefaultRepo() string
- func (s *Source) IsEmpty() bool
- func (s *Source) IsMultiSource() bool
- func (s Source) MarshalYAML() (interface{}, error)
- func (s *Source) RepoForBase() string
- func (s *Source) RepoForCommand(cmd string) string
- func (s *Source) RepoForLanguage(lang string) string
- func (s *Source) RepoForSkill(skill string) string
- func (s *Source) UnmarshalYAML(node *yaml.Node) error
- func (s *Source) Validate() error
- type SourceConfig
- type SourceRepoConfig
- type SourceRepoPaths
Constants ¶
const ( DefaultVersion = 1 DefaultPath = "CLAUDE.md" DefaultCacheTTL = "24h" )
Default values.
const ( DefaultFileMode = 0644 DefaultDirMode = 0755 )
File permission constants for consistent file creation.
Variables ¶
var DefaultTrustedSources = []string{
"HartBrook/staghorn-community",
}
DefaultTrustedSources contains sources that are trusted by default. These are official staghorn repositories maintained by HartBrook.
Functions ¶
func IsSourceRepo ¶ added in v0.7.0
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
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
ParseRepo extracts owner and repo name from a repository string. Accepts formats:
- "https://github.com/owner/repo"
- "https://github.com/owner/repo.git"
- "https://github.com/owner/repo/tree/main"
- "https://github.com/owner/repo/blob/main/file.md"
- "github.com/owner/repo"
- "owner/repo"
func ProjectClaudeCommandsDir ¶ added in v0.2.0
ProjectClaudeCommandsDir returns the path for project-level Claude Code commands.
func ProjectClaudeRulesDir ¶ added in v0.8.0
ProjectClaudeRulesDir returns the path for project-level Claude Code rules.
func ProjectClaudeSkillsDir ¶ added in v0.8.0
ProjectClaudeSkillsDir returns the path for project-level Claude Code skills.
func ProjectCommandsDir ¶ added in v0.2.0
ProjectCommandsDir returns the path for project-specific commands. This is relative to the project root (.staghorn/commands/).
func ProjectEvalsDir ¶ added in v0.4.0
ProjectEvalsDir returns the path for project-specific evals.
func ProjectRulesDir ¶ added in v0.8.0
ProjectRulesDir returns the path for project-specific rules.
func ProjectSkillsDir ¶ added in v0.8.0
ProjectSkillsDir returns the path for project-specific skills.
func TrustWarning ¶ added in v0.3.0
TrustWarning returns a warning message for untrusted sources.
func WriteSourceRepoConfig ¶ added in v0.7.0
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 NewSimpleConfig ¶ added in v0.3.0
NewSimpleConfig creates a config with a single source.
func (*Config) DefaultOwnerRepo ¶ added in v0.3.0
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
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
SourceRepo returns the full repo string for display purposes.
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 ¶
NewPathsWithOverrides allows overriding directories for testing.
func (*Paths) CacheMetadataFile ¶
CacheMetadataFile returns the path for cache metadata sidecar.
func (*Paths) ClaudeCommandsDir ¶ added in v0.2.0
ClaudeCommandsDir returns the path for Claude Code custom commands.
func (*Paths) ClaudeRulesDir ¶ added in v0.8.0
ClaudeRulesDir returns the path for Claude Code user-level rules.
func (*Paths) ClaudeSkillsDir ¶ added in v0.8.0
ClaudeSkillsDir returns the path for Claude Code user-level skills.
func (*Paths) OptimizedDir ¶ added in v0.6.0
OptimizedDir returns the path for optimized config storage.
func (*Paths) OptimizedFile ¶ added in v0.6.0
OptimizedFile returns the path for an optimized config file.
func (*Paths) OptimizedMetaFile ¶ added in v0.6.0
OptimizedMetaFile returns the path for optimization metadata sidecar.
func (*Paths) TeamCommandsDir ¶ added in v0.2.0
TeamCommandsDir returns the path for cached team commands.
func (*Paths) TeamEvalsDir ¶ added in v0.4.0
TeamEvalsDir returns the path for cached team evals.
func (*Paths) TeamLanguagesDir ¶
TeamLanguagesDir returns the path for cached team language configs.
func (*Paths) TeamRulesDir ¶ added in v0.8.0
TeamRulesDir returns the path for cached team rules.
func (*Paths) TeamSkillsDir ¶ added in v0.8.0
TeamSkillsDir returns the path for cached team skills.
func (*Paths) TeamTemplatesDir ¶
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
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
DefaultRepo returns the default repository for this source configuration.
func (*Source) IsMultiSource ¶ added in v0.3.0
IsMultiSource returns true if this is a multi-source configuration.
func (Source) MarshalYAML ¶ added in v0.3.0
MarshalYAML implements custom marshaling to output the appropriate format.
func (*Source) RepoForBase ¶ added in v0.3.0
RepoForBase returns the repository to use for the base CLAUDE.md.
func (*Source) RepoForCommand ¶ added in v0.3.0
RepoForCommand returns the repository to use for a specific command.
func (*Source) RepoForLanguage ¶ added in v0.3.0
RepoForLanguage returns the repository to use for a specific language config.
func (*Source) RepoForSkill ¶ added in v0.8.0
RepoForSkill returns the repository to use for a specific skill.
func (*Source) UnmarshalYAML ¶ added in v0.3.0
UnmarshalYAML implements custom unmarshaling to handle both string and object formats.
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.