Documentation
¶
Index ¶
- Constants
- func CalculatePort(expression string, instance int) (int, error)
- func CalculateRelativePath(worktreeDepth int) string
- func ExtractBasePort(expr string) (int, error)
- func ReadEnvFile(featureDir string) (map[string]string, error)
- func RemoveInstanceMarker(featureDir string) error
- func ReplaceInstancePlaceholder(command string, instance int) string
- func UpdateInstanceYoloMode(featureDir string, yoloMode bool) error
- func WriteEnvFile(featureDir string, computedVars map[string]string) error
- func WriteInstanceMarker(featureDir string, feature string, instance int, projectRoot string, ...) error
- type AgentContext
- type AgentStep
- type AgentTask
- type Config
- type EnvVarConfig
- type FileLink
- type GSDConfig
- type GeneratedFile
- type GitConfig
- type InstanceContext
- type Notification
- type NotifyConfig
- type PresetConfig
- type ProjectConfig
- type PushConfig
- type RollbackConfig
- type SafetyConfig
- type SafetyGate
- type ScheduledAgents
- type WorktreeConfig
- func (c *WorktreeConfig) ExportEnvVars(instance int) map[string]string
- func (c *WorktreeConfig) GenerateFiles(projectName, featureDir string, envVars map[string]string) error
- func (c *WorktreeConfig) GetClaudeWorkingProject() string
- func (c *WorktreeConfig) GetComposeProjectTemplate() string
- func (c *WorktreeConfig) GetComputedVars(envVars map[string]string) map[string]string
- func (c *WorktreeConfig) GetDisplayableServices(ports map[string]int) map[string]string
- func (c *WorktreeConfig) GetFirstProjectDir() string
- func (c *WorktreeConfig) GetInstancePortName() (string, error)
- func (c *WorktreeConfig) GetPortServiceNames() []string
- func (c *WorktreeConfig) GetPreset(name string) (*PresetConfig, error)
- func (c *WorktreeConfig) GetProjectsForPreset(presetName string) ([]ProjectConfig, error)
- func (c *WorktreeConfig) GetServiceURL(portEnvName string, ports map[string]int) string
- func (c *WorktreeConfig) ReplaceComposeProjectPlaceholders(template, featureName, serviceName string) string
- func (c *WorktreeConfig) ResolveValueVars(instance int, envVars map[string]string)
- func (c *WorktreeConfig) Validate() error
Constants ¶
const ( // WorktreeDir is the directory where worktrees are created WorktreeDir = "worktrees" // ConfigFileName is the name of the worktree configuration file ConfigFileName = ".worktree.yml" )
Variables ¶
This section is empty.
Functions ¶
func CalculatePort ¶
CalculatePort evaluates a port expression like "3000 + {instance}" or "4510 + {instance} * 50"
func CalculateRelativePath ¶
CalculateRelativePath calculates relative path from worktree to project root Example: worktrees/feature-name -> ../..
func ExtractBasePort ¶
ExtractBasePort extracts base port from expressions like "3000 + {instance}"
func ReadEnvFile ¶ added in v0.0.10
ReadEnvFile reads .worktree-env.json from featureDir and returns all key-value pairs.
func RemoveInstanceMarker ¶
RemoveInstanceMarker deletes the .worktree-instance file from the feature directory
func ReplaceInstancePlaceholder ¶
ReplaceInstancePlaceholder replaces {instance} placeholder in command
func UpdateInstanceYoloMode ¶
UpdateInstanceYoloMode updates the yolo_mode field in the .worktree-instance file
func WriteEnvFile ¶ added in v0.0.10
WriteEnvFile writes all computed vars to .worktree-env.json in the feature directory.
Types ¶
type AgentContext ¶
type AgentContext struct {
Preset string `yaml:"preset"` // Which preset to use (frontend, backend, fullstack)
Branch string `yaml:"branch"` // Base branch to work from
Instance int `yaml:"instance"` // Instance number for port allocation
Yolo bool `yaml:"yolo"` // Enable YOLO mode for autonomous execution
}
AgentContext defines the execution environment for an agent task
type AgentStep ¶
type AgentStep struct {
Name string `yaml:"name"`
Type string `yaml:"type"` // "shell" or "skill"
Command string `yaml:"command,omitempty"` // For shell steps
Skill string `yaml:"skill,omitempty"` // For skill steps
Args string `yaml:"args,omitempty"` // Arguments for skill steps
WorkingDir string `yaml:"working_dir,omitempty"` // Working directory for execution
}
AgentStep represents a single step in an agent task
type AgentTask ¶
type AgentTask struct {
Name string `yaml:"name"`
Description string `yaml:"description"`
Schedule string `yaml:"schedule"`
Context AgentContext `yaml:"context"`
Steps []AgentStep `yaml:"steps,omitempty"`
Safety SafetyConfig `yaml:"safety"`
Notifications NotifyConfig `yaml:"notifications"`
GSD *GSDConfig `yaml:"gsd,omitempty"` // GSD framework integration
}
AgentTask represents a scheduled agent maintenance task
type Config ¶
Config holds the application configuration
func (*Config) WorktreeExists ¶
WorktreeExists checks if a worktree exists for a feature
func (*Config) WorktreeFeaturePath ¶
WorktreeFeaturePath returns the path to the worktree directory for a feature
type EnvVarConfig ¶
type EnvVarConfig struct {
Name string `yaml:"name"`
URL string `yaml:"url"`
Port string `yaml:"port"` // Expression like "3000 + {instance}" or null for non-port configs
Value string `yaml:"value"` // String template for non-port configs like COMPOSE_PROJECT_NAME
Env string `yaml:"env"` // Environment variable name to export
Range *[2]int `yaml:"range"` // Optional explicit range [min, max] for port allocation
}
EnvVarConfig represents an environment variable configuration entry (port, string template, or display-only)
func (*EnvVarConfig) GetPortRange ¶
func (pc *EnvVarConfig) GetPortRange() *[2]int
GetPortRange extracts port range from either explicit Range field or Port expression
func (*EnvVarConfig) GetURL ¶
func (pc *EnvVarConfig) GetURL(hostname string, port int) string
GetPortURL generates the URL for a port configuration
type FileLink ¶
type FileLink struct {
Source string `yaml:"source"` // Path relative to project root
Target string `yaml:"target"` // Path relative to worktree root
}
FileLink represents a file or directory to symlink or copy
type GSDConfig ¶
type GSDConfig struct {
Enabled bool `yaml:"enabled"` // Enable GSD workflow
Milestone string `yaml:"milestone"` // GSD milestone name
ReadTaskFile bool `yaml:"read_task_file,omitempty"` // Read .task.md from worktree
AutoExecute bool `yaml:"auto_execute,omitempty"` // Auto-execute after planning
}
GSDConfig defines GSD framework integration settings
type GeneratedFile ¶
type GeneratedFile struct {
Path string `yaml:"path"` // File path relative to project directory
Template string `yaml:"template"` // Template content with {PLACEHOLDER} substitution
}
GeneratedFile represents a file to be auto-generated in a worktree
type GitConfig ¶
type GitConfig struct {
Branch string `yaml:"branch"`
CommitMessage string `yaml:"commit_message"`
Push PushConfig `yaml:"push"`
}
GitConfig defines Git operations for agent tasks
type InstanceContext ¶
type InstanceContext struct {
Feature string `json:"feature"`
Instance int `json:"instance"`
ProjectRoot string `json:"project_root"`
WorktreeRoot string `json:"worktree_root"`
Projects []string `json:"projects"`
Ports map[string]int `json:"ports"`
YoloMode bool `json:"yolo_mode"`
CreatedAt string `json:"created_at"`
}
InstanceContext represents the worktree instance metadata
func DetectInstance ¶
func DetectInstance() (*InstanceContext, error)
DetectInstance walks up from the current working directory to find .worktree-instance Returns the instance context if found, or an error if not in a worktree
type Notification ¶
type Notification struct {
Type string `yaml:"type"` // "slack", "email", "gitlab_issue"
Project string `yaml:"project,omitempty"` // GitLab project (for gitlab_issue)
Title string `yaml:"title,omitempty"` // Slack channel or email subject
Body string `yaml:"body,omitempty"` // Message body
Labels []string `yaml:"labels,omitempty"` // Labels (for gitlab_issue)
Recipients []string `yaml:"recipients,omitempty"` // Webhook URL (for slack) or email addresses
}
Notification represents a single notification channel
type NotifyConfig ¶
type NotifyConfig struct {
OnSuccess []Notification `yaml:"on_success,omitempty"`
OnFailure []Notification `yaml:"on_failure,omitempty"`
}
NotifyConfig defines notification channels for agent tasks
type PresetConfig ¶
type PresetConfig struct {
Projects []string `yaml:"projects"`
Description string `yaml:"description"`
}
PresetConfig represents a preset configuration
type ProjectConfig ¶
type ProjectConfig struct {
Executor string `yaml:"executor"` // "docker" (default) or "process"
Dir string `yaml:"dir"`
MainBranch string `yaml:"main_branch"`
StartPreCommand string `yaml:"start_pre_command"` // Runs before start_command
StartCommand string `yaml:"start_command"`
StartPostCommand string `yaml:"start_post_command"` // Runs after start_command (fixtures, seed, etc.)
StopPreCommand string `yaml:"stop_pre_command"` // Runs before stopping services
StopPostCommand string `yaml:"stop_post_command"` // Runs after stopping services
RestartPreCommand string `yaml:"restart_pre_command"` // Runs before the full restart cycle
RestartPostCommand string `yaml:"restart_post_command"` // Runs after the full restart cycle
ClaudeWorkingDir bool `yaml:"claude_working_dir"`
Symlinks []FileLink `yaml:"symlinks"` // Symlinks created inside this project's worktree dir
Copies []FileLink `yaml:"copies"` // Files copied into this project's worktree dir
}
ProjectConfig represents a single project configuration
func (*ProjectConfig) GetExecutor ¶
func (p *ProjectConfig) GetExecutor() string
GetExecutor returns the executor type, defaulting to "docker" if not set.
type PushConfig ¶
type PushConfig struct {
Enabled bool `yaml:"enabled"`
CreatePR bool `yaml:"create_pr"`
PRTitle string `yaml:"pr_title"`
PRBody string `yaml:"pr_body"`
AutoMerge bool `yaml:"auto_merge"`
}
PushConfig defines push and PR creation settings
type RollbackConfig ¶
type RollbackConfig struct {
Enabled bool `yaml:"enabled"`
Strategy string `yaml:"strategy"` // "cleanup-worktree"
}
RollbackConfig defines rollback behavior on failure
type SafetyConfig ¶
type SafetyConfig struct {
Gates []SafetyGate `yaml:"gates"`
Git GitConfig `yaml:"git"`
Rollback RollbackConfig `yaml:"rollback"`
}
SafetyConfig defines safety mechanisms for agent tasks
type SafetyGate ¶
type SafetyGate struct {
Name string `yaml:"name"`
Command string `yaml:"command"`
Required bool `yaml:"required"`
}
SafetyGate represents a quality gate that must pass before committing
type ScheduledAgents ¶
ScheduledAgents is a map of agent task names to their configurations
type WorktreeConfig ¶
type WorktreeConfig struct {
ProjectName string `yaml:"project_name"`
Hostname string `yaml:"hostname"`
Projects map[string]ProjectConfig `yaml:"projects"`
Presets map[string]PresetConfig `yaml:"presets"`
DefaultPreset string `yaml:"default_preset"`
MaxInstances int `yaml:"max_instances"`
AutoFixtures bool `yaml:"auto_fixtures"`
Symlinks []FileLink `yaml:"symlinks"`
Copies []FileLink `yaml:"copies"`
EnvVariables map[string]EnvVarConfig `yaml:"env_variables"`
GeneratedFiles map[string][]GeneratedFile `yaml:"generated_files"`
ScheduledAgents ScheduledAgents `yaml:"scheduled_agents"` // NEW: Scheduled agent tasks
}
WorktreeConfig represents the .worktree.yml configuration
func LoadWorktreeConfig ¶
func LoadWorktreeConfig(projectRoot string) (*WorktreeConfig, error)
LoadWorktreeConfig loads the .worktree.yml configuration file
func (*WorktreeConfig) ExportEnvVars ¶
func (c *WorktreeConfig) ExportEnvVars(instance int) map[string]string
ExportEnvVars exports all configured environment variables for the given instance
func (*WorktreeConfig) GenerateFiles ¶
func (c *WorktreeConfig) GenerateFiles(projectName, featureDir string, envVars map[string]string) error
GenerateFiles creates configured files for a project with templated content Uses the same placeholder substitution as environment variables
func (*WorktreeConfig) GetClaudeWorkingProject ¶
func (c *WorktreeConfig) GetClaudeWorkingProject() string
GetClaudeWorkingProject returns the project configured as Claude's working directory
func (*WorktreeConfig) GetComposeProjectTemplate ¶
func (c *WorktreeConfig) GetComposeProjectTemplate() string
GetComposeProjectTemplate returns the template for compose project names Returns "{project}-{feature}" as default if not configured
func (*WorktreeConfig) GetComputedVars ¶
func (c *WorktreeConfig) GetComputedVars(envVars map[string]string) map[string]string
GetComputedVars returns all env vars that are fully resolved in the provided envVars map. Entries with unresolved {placeholder} tokens (e.g. COMPOSE_PROJECT_NAME={project}-{feature}-{service}) are excluded — they are substituted separately and cannot be stored as-is.
func (*WorktreeConfig) GetDisplayableServices ¶
func (c *WorktreeConfig) GetDisplayableServices(ports map[string]int) map[string]string
GetDisplayableServices returns a list of services that should be displayed Returns map of service name -> URL
func (*WorktreeConfig) GetFirstProjectDir ¶
func (c *WorktreeConfig) GetFirstProjectDir() string
GetFirstProjectDir returns the Dir field of the first configured project (alphabetically). Used as a representative git directory for health checks.
func (*WorktreeConfig) GetInstancePortName ¶
func (c *WorktreeConfig) GetInstancePortName() (string, error)
GetInstancePortName returns the name of the env variable used for instance number calculation. It finds the first env variable (alphabetically) that has both a range and a port expression. All ranged ports with base+{instance} expressions yield the same instance number, so any one works.
func (*WorktreeConfig) GetPortServiceNames ¶
func (c *WorktreeConfig) GetPortServiceNames() []string
GetPortServiceNames returns list of all service names that need port allocation Services must have both 'env' and 'range' fields to be included This excludes template-only services like COMPOSE_PROJECT_NAME
func (*WorktreeConfig) GetPreset ¶
func (c *WorktreeConfig) GetPreset(name string) (*PresetConfig, error)
GetPreset returns a preset by name, or the default preset
func (*WorktreeConfig) GetProjectsForPreset ¶
func (c *WorktreeConfig) GetProjectsForPreset(presetName string) ([]ProjectConfig, error)
GetProjectsForPreset returns the list of projects for a preset
func (*WorktreeConfig) GetServiceURL ¶
func (c *WorktreeConfig) GetServiceURL(portEnvName string, ports map[string]int) string
GetServiceURL returns the formatted URL for a service by port env name Returns empty string if port not found or URL not configured
func (*WorktreeConfig) ReplaceComposeProjectPlaceholders ¶
func (c *WorktreeConfig) ReplaceComposeProjectPlaceholders(template, featureName, serviceName string) string
ReplaceComposeProjectPlaceholders replaces placeholders in a compose project name template Supported placeholders: {project}, {feature}, {service}
func (*WorktreeConfig) ResolveValueVars ¶
func (c *WorktreeConfig) ResolveValueVars(instance int, envVars map[string]string)
ResolveValueVars recomputes value-template env vars (e.g., GOOGLE_OAUTH_REDIRECT_URI) using the provided envVars map. Call this AFTER overriding ports from the registry so that placeholder substitution uses the actual allocated port values, not base values.
func (*WorktreeConfig) Validate ¶
func (c *WorktreeConfig) Validate() error
Validate validates the configuration