Documentation
¶
Index ¶
- Constants
- Variables
- func ForgeFailureCause(err error) string
- func GenerateName(taken func(string) bool) string
- func NewForgeFailure(kind error, cause string, err error) error
- func ParseUntrackedStatusV2(output []byte) ([]string, error)
- func ReclamationEligible(branch, recordedNamespace string, createdBranch bool) bool
- func RunBranchName(namespace, taskSlug, runID string) string
- func RunWorktreeName(taskSlug, runID string) string
- func SanitizeName(value string) string
- type AgentActivity
- type CapabilityDiagnostic
- type CapabilityGate
- type CatalogEvent
- type CatalogEventKind
- type CreateOptions
- type DerivedNames
- type DetailedListing
- type DiscoveredWorktree
- type EventSink
- type ExitAction
- type ExitActionPlan
- type ExitActionRequest
- type ExitActionResult
- type ExitCTA
- type ExitCleanupEvidence
- type ExitCommitScope
- type ExitEventPayload
- type ExitOperation
- type ExitPRPrefill
- type ExitPhase
- type ExitPlan
- type ExitStepResult
- type ExitTerminalEventSink
- type ForgeCapabilities
- type ForgeFailure
- type ForgePRRequest
- type ForgePRResult
- type ForgeProvider
- type ForgeStatus
- type ForgeStatusRequest
- type GitOutput
- type GitOutputHandler
- type GitOutputStream
- type GitRunner
- type GitStatus
- type GitWorktree
- type HookDispatcher
- type HookPreRemovePayload
- type HookRequest
- type HookVerdict
- type HookWorktree
- type Inspection
- type LifecycleEvent
- type Listing
- type Numstat
- type Option
- func WithCapabilityGate(gate *CapabilityGate) Option
- func WithClock(now func() time.Time) Option
- func WithConfig(value config.WorktreesConfig, resolvedRoot string) Option
- func WithEvents(sink EventSink) Option
- func WithForge(provider ForgeProvider) Option
- func WithHooks(dispatcher HookDispatcher) Option
- func WithIDGenerator(generator func(string) (string, error)) Option
- func WithLogger(logger *slog.Logger) Option
- func WithRepositoryLocks(locks *RepositoryLocks) Option
- func WithSessionGuard(guard SessionGuard) Option
- func WithWorkspaceResolver(resolver WorkspaceResolver) Option
- type Origin
- type ParseError
- type PendingPhase
- type PendingUpdate
- type RealGitRunner
- type ReclaimOutcome
- type RefusalError
- type RemovalRefusal
- type RemovalRisk
- type RepoState
- type RepositoryLocks
- type RunWorktreeRequest
- type Service
- func (s *Service) Adopt(ctx context.Context, workspaceID, candidatePath string) (*Worktree, error)
- func (s *Service) CancelCreate(ctx context.Context, workspaceID, ref string) error
- func (s *Service) CancelExitAction(ctx context.Context, workspaceID, ref, opID string) error
- func (s *Service) Capability(ctx context.Context) (CapabilityDiagnostic, error)
- func (s *Service) Create(ctx context.Context, workspaceID string, options CreateOptions) (*Worktree, error)
- func (s *Service) CreateAccepted(ctx context.Context, workspaceID string, options CreateOptions) (*Worktree, error)
- func (s *Service) CreateReady(ctx context.Context, workspaceID string, options CreateOptions) (*Worktree, error)
- func (s *Service) Dismiss(ctx context.Context, workspaceID, id string) error
- func (s *Service) ExitPlan(ctx context.Context, workspaceID, id string) (*ExitPlan, error)
- func (s *Service) Get(ctx context.Context, workspaceID, ref string) (*Worktree, error)
- func (s *Service) Inspect(ctx context.Context, workspaceID, ref string) (*Inspection, error)
- func (s *Service) List(ctx context.Context, workspaceID string, refresh bool) (*Listing, error)
- func (s *Service) ListDetails(ctx context.Context, workspaceID string, refresh bool) (*DetailedListing, error)
- func (s *Service) MaterializeForRun(ctx context.Context, workspaceID string, request RunWorktreeRequest) (*Worktree, error)
- func (s *Service) Reconfigure(value config.WorktreesConfig, resolvedRoot string)
- func (s *Service) RecoverCreations(ctx context.Context) error
- func (s *Service) Remove(ctx context.Context, workspaceID string, id string, force bool) (*RemovalRefusal, error)
- func (s *Service) Resolve(ctx context.Context, workspaceID, ref string) (*Worktree, error)
- func (s *Service) RollbackRunMaterialization(ctx context.Context, workspaceID string, worktreeID string, runID string) error
- func (s *Service) RunExitAction(ctx context.Context, workspaceID string, id string, request ExitActionRequest) (string, error)
- func (s *Service) Status(ctx context.Context, workspaceID, id string, refresh bool) (*Status, error)
- func (s *Service) StatusDetails(ctx context.Context, workspaceID string, id string, refresh bool, ...) (*StatusDetails, error)
- func (s *Service) SubscribeWorktreeCatalogEvents(ctx context.Context) (<-chan CatalogEvent, func(), error)
- type SessionGuard
- type SetupState
- type State
- type Status
- type StatusDetails
- type Store
- type StreamingGitRunner
- type Workspace
- type WorkspaceResolver
- type Worktree
Constants ¶
const ( EventPreCreate = "worktree.pre_create" EventPreRemove = "worktree.pre_remove" EventCreated = "worktree.created" EventAdopted = "worktree.adopted" EventRemoved = "worktree.removed" EventMissing = "worktree.missing" EventDismissed = "worktree.dismissed" EventCreationCanceled = "worktree.creation_canceled" EventSetupFailed = "worktree.setup_failed" EventStatusRefreshed = "worktree.status_refreshed" EventBranchReclaimed = "worktree.branch_reclaimed" EventExitActionStarted = "worktree.exit_action_started" EventExitActionStep = "worktree.exit_action_step" EventExitHookOutput = "worktree.exit_hook_output" EventExitActionCompleted = "worktree.exit_action_completed" EventExitActionFailed = "worktree.exit_action_failed" EventExitActionCanceled = "worktree.exit_action_canceled" )
Variables ¶
var ( ErrGitVersionUnsupported = errors.New("worktree_git_version_unsupported") ErrWorkspaceNotGitBacked = errors.New("workspace_not_git_backed") ErrNameTaken = errors.New("worktree_name_taken") ErrPathExists = errors.New("worktree_path_exists") ErrBranchHeld = errors.New("branch_held_by_worktree") ErrBranchCheckedOutAtRoot = errors.New("branch_checked_out_at_root") ErrBaseRefNotFound = errors.New("base_ref_not_found") ErrRepoHasNoCommits = errors.New("repo_has_no_commits") ErrNotFound = errors.New("worktree_not_found") ErrNotReady = errors.New("worktree_not_ready") ErrPending = errors.New("worktree_pending") ErrMissing = errors.New("worktree_missing") ErrRefInvalid = errors.New("worktree_ref_invalid") ErrAdoptionMainCheckout = errors.New("adoption_main_checkout") ErrAdoptionForeignRepo = errors.New("adoption_foreign_repository") ErrAdoptionUnreadable = errors.New("adoption_unreadable") ErrOperationInProgress = errors.New("worktree_operation_in_progress") ErrSessionActive = errors.New("worktree_session_active") ErrStatusUnreadable = errors.New("worktree_status_unreadable") ErrDirtyRequiresForce = errors.New("worktree_dirty_requires_force") ErrUnpushedRequiresForce = errors.New("worktree_unpushed_requires_force") ErrSafetyCheckFailed = errors.New("worktree_safety_check_failed") ErrRemovalFailed = errors.New("worktree_removal_failed") ErrPerRunMaterialization = errors.New("per_run_materialization_failed") ErrConfigInvalid = errors.New("worktree_config_invalid") ErrDeniedByHook = errors.New("worktree_denied_by_hook") ErrNotPending = errors.New("worktree_not_pending") ErrForge = errors.New("forge_error") ErrExitActionInvalid = errors.New("worktree_exit_action_invalid") )
Functions ¶
func ForgeFailureCause ¶
func GenerateName ¶
func ParseUntrackedStatusV2 ¶
ParseUntrackedStatusV2 returns the exact untracked additions from a porcelain-v2 snapshot. Ignored records are deliberately absent from the result.
func ReclamationEligible ¶
func RunBranchName ¶
func RunWorktreeName ¶
RunWorktreeName returns the readable per-run name without its branch namespace.
func SanitizeName ¶
Types ¶
type AgentActivity ¶
type AgentActivity string
const ( AgentActivityIdle AgentActivity = "idle" AgentActivityRunning AgentActivity = "running" )
type CapabilityDiagnostic ¶
type CapabilityGate ¶
type CapabilityGate struct {
// contains filtered or unexported fields
}
func NewCapabilityGate ¶
func NewCapabilityGate(runner GitRunner) *CapabilityGate
func NewCapabilityGateWithLookPath ¶
func NewCapabilityGateWithLookPath(runner GitRunner, lookPath func(string) (string, error)) *CapabilityGate
func (*CapabilityGate) Check ¶
func (g *CapabilityGate) Check(ctx context.Context) (CapabilityDiagnostic, error)
type CatalogEvent ¶
type CatalogEvent struct {
Kind CatalogEventKind
WorkspaceID string
WorktreeID string
Error string
}
type CatalogEventKind ¶
type CatalogEventKind string
const ( CatalogEventUpserted CatalogEventKind = "upserted" CatalogEventDeleted CatalogEventKind = "deleted" CatalogEventFailed CatalogEventKind = "failed" )
type CreateOptions ¶
type DerivedNames ¶
func DeriveNames ¶
func DeriveNames(value string) DerivedNames
type DetailedListing ¶
type DetailedListing struct {
Worktrees []Inspection
Discovered []DiscoveredWorktree
Repo RepoState
}
type DiscoveredWorktree ¶
type EventSink ¶
type EventSink interface {
PublishWorktreeEvent(context.Context, LifecycleEvent) error
}
type ExitAction ¶
type ExitAction string
const ( ExitActionCommit ExitAction = "commit" ExitActionCommitPush ExitAction = "commit_push" ExitActionPush ExitAction = "push" ExitActionOpenPR ExitAction = "open_pr" ExitActionViewPR ExitAction = "view_pr" )
type ExitActionPlan ¶
type ExitActionRequest ¶
type ExitActionResult ¶
type ExitActionResult struct {
OperationID string `json:"op_id"`
Action ExitAction `json:"action"`
Steps []ExitStepResult `json:"steps"`
CTA *ExitCTA `json:"cta,omitempty"`
}
type ExitCTA ¶
type ExitCTA struct {
Action ExitAction `json:"action"`
Label string `json:"label"`
URL string `json:"url,omitempty"`
}
type ExitCleanupEvidence ¶
type ExitCleanupEvidence struct {
ForgeState string `json:"forge_state,omitempty"`
Stale bool `json:"stale,omitempty"`
Safe bool `json:"safe"`
Source string `json:"source,omitempty"`
Summary string `json:"summary,omitempty"`
Blocker string `json:"blocker,omitempty"`
Downgraded bool `json:"downgraded,omitempty"`
}
type ExitCommitScope ¶
type ExitEventPayload ¶
type ExitEventPayload struct {
OperationID string `json:"op_id"`
Action ExitAction `json:"action"`
Phases []ExitPhase `json:"phases,omitempty"`
Phase ExitPhase `json:"phase,omitempty"`
State string `json:"state,omitempty"`
Result *ExitActionResult `json:"result,omitempty"`
Message string `json:"message,omitempty"`
Cause string `json:"cause,omitempty"`
Stream string `json:"stream,omitempty"`
Chunk string `json:"chunk,omitempty"`
}
type ExitOperation ¶
type ExitPRPrefill ¶
type ExitPlan ¶
type ExitPlan struct {
WorktreeID string `json:"worktree_id"`
Primary ExitAction `json:"primary,omitempty"`
Actions []ExitActionPlan `json:"actions"`
GlobalPauseCause string `json:"global_pause_cause,omitempty"`
CommitScope ExitCommitScope `json:"commit_scope"`
BrowserURL string `json:"browser_url,omitempty"`
Forge *ForgeCapabilities `json:"forge,omitempty"`
ForgeStatus *ForgeStatus `json:"forge_status,omitempty"`
PRPrefill *ExitPRPrefill `json:"pr_prefill,omitempty"`
Cleanup ExitCleanupEvidence `json:"cleanup"`
Base string `json:"base,omitempty"`
RemoteURLs []string `json:"remote_urls,omitempty"`
}
type ExitStepResult ¶
type ExitStepResult struct {
Phase ExitPhase `json:"phase"`
State string `json:"state"`
Reason string `json:"reason,omitempty"`
Output string `json:"output,omitempty"`
SHA string `json:"sha,omitempty"`
Upstream string `json:"upstream,omitempty"`
PRStatus string `json:"pr_status,omitempty"`
PRNumber int `json:"pr_number,omitempty"`
URL string `json:"url,omitempty"`
}
type ExitTerminalEventSink ¶
type ExitTerminalEventSink interface {
FinishExitOperationWithEvent(
context.Context,
string,
string,
string,
string,
time.Time,
LifecycleEvent,
) (bool, error)
}
ExitTerminalEventSink commits an exit operation's terminal state and replay event together. The production store implements this boundary transactionally.
type ForgeCapabilities ¶
type ForgeFailure ¶
type ForgeFailure struct {
// contains filtered or unexported fields
}
func (*ForgeFailure) Error ¶
func (e *ForgeFailure) Error() string
func (*ForgeFailure) Unwrap ¶
func (e *ForgeFailure) Unwrap() []error
type ForgePRRequest ¶
type ForgePRResult ¶
type ForgeProvider ¶
type ForgeProvider interface {
Capabilities(context.Context, []string) (*ForgeCapabilities, error)
Status(context.Context, ForgeStatusRequest) (*ForgeStatus, error)
CreatePR(context.Context, ForgePRRequest) (*ForgePRResult, error)
}
type ForgeStatus ¶
type ForgeStatusRequest ¶
type GitOutput ¶
type GitOutput struct {
Stream GitOutputStream
Chunk []byte
}
type GitOutputHandler ¶
type GitOutputHandler func(GitOutput)
type GitOutputStream ¶
type GitOutputStream string
const ( GitOutputStdout GitOutputStream = "stdout" GitOutputStderr GitOutputStream = "stderr" )
type GitStatus ¶
type GitStatus struct {
Branch string
Upstream string
HeadSHA string
Detached bool
DirtyFiles int
HasUpstream bool
Ahead *int
Behind *int
}
func ParseStatusV2 ¶
type GitWorktree ¶
type GitWorktree struct {
Path string
HeadSHA string
Branch string
Main bool
Detached bool
Bare bool
Locked bool
LockReason string
Prunable bool
PrunableReason string
}
func ParseWorktreeList ¶
func ParseWorktreeList(output []byte) ([]GitWorktree, error)
type HookDispatcher ¶
type HookDispatcher interface {
DispatchWorktreeHook(context.Context, HookRequest) (HookVerdict, error)
}
type HookPreRemovePayload ¶
type HookPreRemovePayload struct {
Worktree HookWorktree `json:"worktree"`
Force bool `json:"force"`
Risk RemovalRisk `json:"risk"`
}
type HookRequest ¶
type HookVerdict ¶
type HookWorktree ¶
type HookWorktree struct {
WorktreeID string `json:"worktree_id"`
WorkspaceID string `json:"workspace_id"`
WorkspaceRoot string `json:"workspace_root,omitempty"`
Name string `json:"name"`
Branch string `json:"branch"`
Path string `json:"path"`
Origin Origin `json:"origin"`
RunID string `json:"run_id,omitempty"`
}
type Inspection ¶
type Inspection struct {
Worktree Worktree
Status *Status
ForgeStatus *ForgeStatus
Repo RepoState
AgentActivity AgentActivity
}
type LifecycleEvent ¶
type Listing ¶
type Listing struct {
Worktrees []Worktree
Discovered []DiscoveredWorktree
Repo RepoState
}
type Option ¶
type Option func(*Service)
func WithCapabilityGate ¶
func WithCapabilityGate(gate *CapabilityGate) Option
func WithConfig ¶
func WithConfig(value config.WorktreesConfig, resolvedRoot string) Option
func WithEvents ¶
func WithForge ¶
func WithForge(provider ForgeProvider) Option
func WithHooks ¶
func WithHooks(dispatcher HookDispatcher) Option
func WithLogger ¶
func WithRepositoryLocks ¶
func WithRepositoryLocks(locks *RepositoryLocks) Option
func WithSessionGuard ¶
func WithSessionGuard(guard SessionGuard) Option
func WithWorkspaceResolver ¶
func WithWorkspaceResolver(resolver WorkspaceResolver) Option
type ParseError ¶
func (*ParseError) Error ¶
func (e *ParseError) Error() string
type PendingPhase ¶
type PendingPhase string
const ( PhaseNone PendingPhase = "" PhaseBranch PendingPhase = "branch" PhaseCheckout PendingPhase = "checkout" PhaseCopy PendingPhase = "copy" PhaseSetup PendingPhase = "setup" )
type PendingUpdate ¶
type RealGitRunner ¶
type RealGitRunner struct {
// contains filtered or unexported fields
}
func NewRealGitRunner ¶
func NewRealGitRunner(timeout time.Duration) (*RealGitRunner, error)
func (*RealGitRunner) RunStreaming ¶
func (r *RealGitRunner) RunStreaming( ctx context.Context, dir string, onOutput GitOutputHandler, args ...string, ) ([]byte, []byte, error)
type ReclaimOutcome ¶
type RefusalError ¶
func (*RefusalError) Error ¶
func (e *RefusalError) Error() string
func (*RefusalError) Unwrap ¶
func (e *RefusalError) Unwrap() error
type RemovalRefusal ¶
type RemovalRefusal struct {
Code string
Risk RemovalRisk
Downgrade bool
}
type RemovalRisk ¶
type RepositoryLocks ¶
type RepositoryLocks struct {
// contains filtered or unexported fields
}
func NewRepositoryLocks ¶
func NewRepositoryLocks(maxWaiters int) *RepositoryLocks
type RunWorktreeRequest ¶
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func (*Service) CancelCreate ¶
func (*Service) CancelExitAction ¶
func (*Service) Capability ¶
func (s *Service) Capability(ctx context.Context) (CapabilityDiagnostic, error)
Capability reports whether the Git dependency required by worktree mutations is ready.
func (*Service) CreateAccepted ¶
func (s *Service) CreateAccepted( ctx context.Context, workspaceID string, options CreateOptions, ) (*Worktree, error)
CreateAccepted durably inserts a pending worktree and continues materialization after the request ends. Callers observe phases through the catalog stream and canonical lifecycle events.
func (*Service) CreateReady ¶
func (s *Service) CreateReady( ctx context.Context, workspaceID string, options CreateOptions, ) (*Worktree, error)
CreateReady inserts a visible pending worktree, waits for materialization, and returns only after the worktree is ready for session binding.
func (*Service) Inspect ¶
Inspect returns durable registry and cached derived state. It probes only repository capability; status, discovery, and forge reads remain cached.
func (*Service) ListDetails ¶
func (s *Service) ListDetails( ctx context.Context, workspaceID string, refresh bool, ) (*DetailedListing, error)
ListDetails returns the registry/discovery merge plus cached status, forge, and live activity. Git status is refreshed only when refresh is explicit.
func (*Service) MaterializeForRun ¶
func (*Service) Reconfigure ¶
func (s *Service) Reconfigure(value config.WorktreesConfig, resolvedRoot string)
Reconfigure applies global worktree settings to future operations. Existing registry rows retain their persisted paths and lifecycle state.
func (*Service) Resolve ¶
Resolve returns the canonical registry record for an ID-or-name reference without probing repository capability or derived status caches.
func (*Service) RollbackRunMaterialization ¶
func (s *Service) RollbackRunMaterialization( ctx context.Context, workspaceID string, worktreeID string, runID string, ) error
RollbackRunMaterialization removes the exact per-run worktree produced for a session that could not be bound under its active task-run lease.
func (*Service) RunExitAction ¶
func (*Service) StatusDetails ¶
func (*Service) SubscribeWorktreeCatalogEvents ¶
func (s *Service) SubscribeWorktreeCatalogEvents( ctx context.Context, ) (<-chan CatalogEvent, func(), error)
type SessionGuard ¶
type SetupState ¶
type SetupState string
const ( SetupNone SetupState = "none" SetupOK SetupState = "ok" SetupFailed SetupState = "failed" )
type Status ¶
type StatusDetails ¶
type StatusDetails struct {
WorktreeID string
Status *Status
ForgeStatus *ForgeStatus
}
type Store ¶
type Store interface {
Insert(context.Context, Worktree) error
Get(context.Context, string, string) (*Worktree, error)
GetByPath(context.Context, string, string) (*Worktree, error)
List(context.Context, string) ([]Worktree, error)
ListRecoverable(context.Context) ([]Worktree, error)
DeletePending(context.Context, string, string) error
DeleteRunMaterialization(context.Context, string, string, string) error
UpdatePending(context.Context, string, string, PendingUpdate) error
CompleteCreate(context.Context, string, string, SetupState, string, time.Time) error
CompareAndSwapState(context.Context, string, string, State, State, time.Time) (bool, error)
SetState(context.Context, string, string, State, time.Time) error
SaveStatus(context.Context, string, string, Status) error
GetStatus(context.Context, string, string) (*Status, error)
SaveForgeStatus(context.Context, string, string, ForgeStatus) error
GetForgeStatus(context.Context, string, string) (*ForgeStatus, error)
InsertExitOperation(context.Context, ExitOperation) error
FinishExitOperation(context.Context, string, string, string, string, time.Time) (bool, error)
ListRunningExitOperations(context.Context) ([]ExitOperation, error)
FailRunningExitOperations(context.Context, time.Time) error
}
Store owns workspace-predicated persistence for the worktree domain.
type StreamingGitRunner ¶
type WorkspaceResolver ¶
type Worktree ¶
type Worktree struct {
ID string
WorkspaceID string
Name string
Branch string
Path string
GitDir string
State State
PendingPhase PendingPhase
Origin Origin
SetupState SetupState
SetupError string
BaseRef string
CreatedBranch bool
RunNamespace string
CreatedHead string
RunID string
CreatedAt time.Time
UpdatedAt time.Time
}
Source Files
¶
- adopt.go
- bootstrap.go
- capability.go
- catalog_stream.go
- create.go
- create_async.go
- create_branch.go
- discovery.go
- dismiss.go
- events.go
- exit_action_commit.go
- exit_actions.go
- exit_browser.go
- exit_cleanup.go
- exit_contracts.go
- exit_plan.go
- exit_refresh.go
- exit_terminal.go
- forge.go
- git_metadata.go
- git_porcelain.go
- git_runner.go
- inspection.go
- lock.go
- naming.go
- pr_template.go
- reclaim.go
- reconcile.go
- remove.go
- resolve.go
- run_materialization.go
- service.go
- status.go
- status_details.go
- value_helpers.go
- worktree.go