worktree

type Entry struct {
	// Path is the absolute path of the worktree directory, whether or not it
	// still exists.
	Path string
	// Branch is the branch checked out there, without the refs/heads/ prefix.
	// Empty when git no longer registers the worktree and no single
	// cloop/task-<id>-* branch could be matched to it — see List for why an
	// ambiguous match is deliberately left empty rather than guessed.
	Branch string
	// TaskID is the cloop task this worktree was created for, parsed from the
	// directory name or, failing that, from the branch. Zero means the entry
	// could not be attributed to a task, which makes it invisible to
	// PruneOptions.Active and therefore protected only by MinAge.
	TaskID int
	// DirExists reports whether the directory is on disk.
	DirExists bool
	// Registered reports whether `git worktree list` still knows about it.
	Registered bool
	// Locked reports that the worktree carries git's own lock marker
	// (`git worktree lock`), which is an operator saying "do not collect this".
	// Prune honours it unconditionally.
	Locked bool
	// LockReason is the message passed to `git worktree lock`, if any.
	LockReason string
	// ModTime is the most recent modification observed for this worktree. It is
	// a heuristic, not a liveness signal: see entryModTime.
	ModTime time.Time
}

type KeepCode string

type KeptEntry struct {
	Entry
	Code   KeepCode
	Reason string
}

type PruneError struct {
	Path   string
	TaskID int
	Err    error
}

type PruneOptions struct {
	// DryRun computes and reports the whole plan without changing anything.
	// The merged-branch check still runs, because it is read-only, so a dry run
	// reports the branch deletions a real run would attempt. It cannot report
	// the outcome of git's own second gate — `git branch -d` applies a stricter
	// merged test of its own, against HEAD rather than against BaseBranch — so
	// a real run can keep a branch a dry run listed for deletion. It can never
	// go the other way and delete one a dry run did not list.
	DryRun bool

	// MinAge is the single most important safety property in this package.
	//
	// A live parallel run's worktrees are in this directory *right now*, and
	// pruning one destroys in-flight, uncommitted work that no git operation
	// can bring back. Nothing younger than MinAge is touched under any
	// circumstance.
	//
	// Zero means DefaultMinAge — the zero value of this struct must be safe,
	// because it is what a caller writes when they have not thought about it.
	// A *negative* value disables the guard entirely, which is deliberately
	// something a caller has to type on purpose; it is meant for tests and for
	// an operator who has already established that nothing is running.
	MinAge time.Duration

	// Active names the task IDs that are executing right now. This is the
	// authoritative liveness signal and MinAge is only the backstop for tasks
	// the caller has lost track of: a caller that has a task table should pass
	// it, because mtime cannot distinguish "finished an hour ago" from "still
	// running and quiet for an hour".
	Active map[int]bool

	// KeepTaskIDs is the same instruction in slice form, for callers that have
	// a list rather than a set. The two are unioned; neither overrides the
	// other.
	KeepTaskIDs []int

	// DeleteBranches also removes each collected worktree's cloop/task-N-*
	// branch — but only when that branch's commits are already contained in
	// BaseBranch. An unmerged branch is the only copy of its task's work, so it
	// is kept and the reason recorded. Off by default.
	DeleteBranches bool

	// BaseBranch is the branch a task branch must be merged into before
	// DeleteBranches will remove it. Empty means the current branch of repoDir,
	// which is the branch a task worktree was created from and merged back to.
	BaseBranch string
}

type PruneResult struct {
	// DryRun echoes the option, so a caller holding only the result can tell
	// whether Removed describes the past or a plan.
	DryRun bool
	// Removed lists the worktrees collected, or that would be.
	Removed []PrunedEntry
	// Kept lists the worktrees spared, each with the reason.
	Kept []KeptEntry
	// Errors lists per-entry failures. A non-empty Errors does not mean the
	// sweep failed; it means these entries were skipped and the rest were done.
	Errors []*PruneError
}

type PrunedEntry struct {
	Entry
	// BranchDeleted reports whether the task branch was deleted too.
	BranchDeleted bool
	// BranchKept explains why it was not, and is empty when it was deleted or
	// when DeleteBranches was off. The common value is "not merged", which is
	// the API refusing to destroy the only copy of a task's work.
	BranchKept string
}

type Worktree struct {
	// Path is the absolute path to the worktree directory.
	Path string
	// Branch is the branch checked out in the worktree.
	Branch string
	// BaseBranch is the branch the worktree was created from (the merge target).
	BaseBranch string
	// TaskID is the cloop task ID this worktree was created for.
	TaskID int
}