worktreeend

type Capture interface {
	// DirtyPaths lists uncommitted paths, tracked and untracked.
	DirtyPaths(ctx context.Context, worktree string) ([]string, error)
	// Preserve captures the uncommitted work and returns a reference the
	// operator can recover it from. It must not depend on the worktree
	// surviving: the whole point is that removal follows.
	Preserve(ctx context.Context, worktree, message string) (ref string, err error)
}

type Claims interface {
	Release(projectsRoot, task string) string
}

type Engine struct {
	ProjectsRoot string
	Inventory    Inventory
	Links        LinkGuard
	Capture      Capture
	Notes        Notes
	Retirer      Retirer
	Claims       Claims
	Now          func() time.Time
}

type Inventory interface {
	Worktrees(ctx context.Context, projectsRoot, task, repository string) ([]Worktree, error)
}

type LinkGuard interface {
	// LiveLinks returns a human-readable reason per live link, and the
	// command that clears each. An empty result means the worktree is free
	// to be retired.
	LiveLinks(worktree string) (reasons []string, sanctioned []string, err error)
}

type MemberResult struct {
	Repository string `json:"repository"`
	Worktree   string `json:"worktree"`
	// Dirty lists the uncommitted paths found before anything was removed.
	Dirty []string `json:"dirty,omitempty"`
	// CaptureRef is where the uncommitted work was preserved. It is printed
	// so the operator can recover it; a capture nobody can find is not a
	// capture.
	CaptureRef string `json:"capture_ref,omitempty"`
	NotePath   string `json:"note_path,omitempty"`
	Removed    bool   `json:"removed"`
	Action     string `json:"action"`
	Detail     string `json:"detail,omitempty"`
}

type Notes interface {
	Seal(worktree, note string) (path string, err error)
}

type Options struct {
	Task string
	// Repository narrows a coordinated task to one owner/repository.
	Repository string
	// Note is recorded in the Work Log as the task's closing statement.
	Note string
	// Apply performs the retirement. Without it nothing is changed and the
	// report says exactly what would happen — including which worktrees carry
	// uncommitted work that would be captured.
	Apply bool
	// KeepCapture stops the capture from being taken. It is not a bypass of
	// anything: it is for a caller that has already preserved the work and
	// does not want a second copy.
	KeepCapture bool
}

type Refusal struct {
	Code       string
	Message    string
	Sanctioned []string
}

type Result struct {
	Task         string         `json:"task"`
	Applied      bool           `json:"applied"`
	Members      []MemberResult `json:"members"`
	ClaimOutcome string         `json:"claim_outcome,omitempty"`
	Errors       []string       `json:"errors,omitempty"`
}

type Retirer interface {
	Retire(ctx context.Context, projectsRoot, task, repository, worktree string) error
}

type Worktree struct {
	Repository string
	Path       string
	Branch     string
}