gitwt

type CommitOptions struct {
	// AuthorName and AuthorEmail set the commit author. When empty, go-git
	// falls back to repository/user config.
	AuthorName  string
	AuthorEmail string

	// All stages modified and deleted tracked files before committing (it does
	// not stage new untracked files), mirroring `git commit -a`.
	All bool

	// AllowEmpty permits a commit with no tree changes.
	AllowEmpty bool
}

type Coordinator struct {
	// contains filtered or unexported fields
}

type CreateOptions struct {
	// Name is the worktree name; the created branch is named identically. It
	// must satisfy the ^[a-zA-Z0-9-]+$ charset (use SafeName to encode).
	Name string
	// Path is the working-tree directory for the new linked worktree.
	Path string
	// BaseBranch is the parent branch whose current tip becomes the recorded
	// base (fork point). One of BaseBranch / Base must be set; Base wins when
	// both are provided.
	BaseBranch string
	// Base is an explicit fork-point commit. Takes precedence over BaseBranch
	// when non-zero.
	Base plumbing.Hash
	// Purpose is the free-form registry note (the task/slice the worktree is
	// for).
	Purpose string
	// ParentPR is the pull-request number the work feeds into (0 when none).
	ParentPR int
	// AppType is the app_type the delegated task runs under; it is recorded on
	// the worktree metadata and is the routing key the resolved execution shape
	// below was loaded from. Empty when the caller supplies no app_type.
	AppType string
	// Profile is the free-form execution profile (e.g. "loop-worker") recorded
	// verbatim on the worktree metadata.
	Profile string
	// VerifierSequence / LensSet / LensConcurrency / GraphBackend are the
	// app_type-routed execution shape the caller already resolved from the
	// project's execution_profile.by_app_type[AppType]. They are recorded as-is
	// so the worktree self-describes its execution shape; all are empty when no
	// profile entry resolved.
	VerifierSequence []string
	LensSet          []string
	LensConcurrency  string
	GraphBackend     string
}

type CreateResult struct {
	// Metadata is the registry record stamped for the new worktree.
	Metadata Metadata
	// Base is the fork-point commit recorded as the worktree's base ref.
	Base plumbing.Hash
}

type Manager interface {
	// AddBranch creates a linked worktree at path checked out onto a NEW branch
	// named identically to name, rooted at base. The base hash is recorded so
	// later rebase/merge-back never re-derives it. Returns ErrWorktreeExists if
	// the worktree name is taken, ErrBranchExists if the branch already exists,
	// or ErrInvalidName if name is malformed.
	AddBranch(name, path string, base plumbing.Hash) error

	// AddDetached creates a linked worktree at path with a detached HEAD at
	// commit (swarm-cd style) — for read-only or ephemeral checkouts that need
	// no branch. The commit is also recorded as the base ref.
	AddDetached(name, path string, commit plumbing.Hash) error

	// Remove deletes the worktree's admin metadata (.git/worktrees/<name>) and
	// its working-tree directory at path. A zero-value path removes only the
	// metadata. Returns ErrWorktreeNotFound if the worktree is unknown.
	Remove(name, path string) error

	// List returns the names of all linked worktrees known to the repository
	// (enumerated natively from .git/worktrees, not from any external
	// registry).
	List() ([]string, error)

	// Prune removes admin metadata for linked worktrees whose working-tree
	// directory no longer exists on disk (the deterministic prune-if-gone
	// contract). It returns the names that were pruned.
	Prune() ([]string, error)

	// Open returns a Worktree handle for operating the linked worktree rooted
	// at path. The handle has its own index / HEAD / working tree, independent
	// of the main repository and of every other linked worktree.
	Open(path string) (Worktree, error)

	// RecordBaseRef stores base as the recorded base ref for the named
	// worktree, overwriting any prior value. Returns ErrWorktreeNotFound if the
	// worktree is unknown.
	RecordBaseRef(name string, base plumbing.Hash) error

	// BaseRef reads the recorded base ref for the named worktree. Returns
	// ErrBaseRefNotRecorded if none was recorded, or ErrWorktreeNotFound if the
	// worktree is unknown.
	BaseRef(name string) (plumbing.Hash, error)
}

type MergeBackOptions struct {
	// Name is the sub-branch / worktree to merge back.
	Name string
	// ParentBranch is the branch the sub-branch is integrated into. Its current
	// tip MUST still equal the recorded base, or MergeBack fails with
	// ErrStaleBase — the parent is not allowed to have moved since creation.
	ParentBranch string
}

type MergeBackResult struct {
	// Base is the recorded fork point read back from the base ref (NOT derived).
	Base plumbing.Hash
	// SubHead is the sub-branch tip that was integrated.
	SubHead plumbing.Hash
	// ParentBranch is the branch that was fast-forwarded.
	ParentBranch string
	// ParentTip is the parent branch tip after integration (equals SubHead).
	ParentTip plumbing.Hash
}

type Metadata struct {
	// Name is the worktree name; it is the registry key and is always set to
	// the lookup name on write, so a mutator can never repoint it.
	Name string `yaml:"name"`
	// Purpose is a free-form human note (e.g. the task or delegation slice the
	// worktree was created for).
	Purpose string `yaml:"purpose"`
	// ParentPR is the pull-request number the worktree's work feeds into, or 0
	// when none is associated yet.
	ParentPR int `yaml:"parent_pr"`
	// CreatedAt is stamped once at Create and never rewritten afterwards.
	CreatedAt time.Time `yaml:"created_at"`
	// LastUsed drives the auto-prune-if-unchanged idle check; Touch re-stamps
	// it whenever the worktree is worked in.
	LastUsed time.Time `yaml:"last_used"`
	// AppType is the app_type this worktree's delegated task runs under, as
	// requested at create time. It is the routing key the resolved execution
	// shape below was loaded from (empty when the worktree carries no app_type).
	AppType string `yaml:"app_type,omitempty"`
	// Profile is the free-form execution profile the task runs under (e.g.
	// "loop-worker"), recorded verbatim from create.
	Profile string `yaml:"profile,omitempty"`
	// VerifierSequence is the app_type-routed ordered verifier-profile ids
	// resolved from the project's execution_profile.by_app_type[AppType]
	// topology. Empty when no profile entry resolved.
	VerifierSequence []string `yaml:"verifier_sequence,omitempty"`
	// LensSet is the resolved review-lens set for the app_type (from the
	// profile's lenses facet). Empty when unresolved.
	LensSet []string `yaml:"lens_set,omitempty"`
	// LensConcurrency is how the lens set runs ("parallel"/"gated"/"tiered"),
	// resolved from the profile's lenses facet. Empty when unresolved.
	LensConcurrency string `yaml:"lens_concurrency,omitempty"`
	// GraphBackend is the graph-backend adapter-ref the app_type profile
	// selects. Empty when unresolved.
	GraphBackend string `yaml:"graph_backend,omitempty"`
}

type PruneScan struct {
	// Eligible worktrees have no commits past their recorded base AND are idle
	// past the TTL — safe to auto-prune.
	Eligible []string
	// Abandoned worktrees have commits past their recorded base and are idle:
	// that is unmerged work, never auto-pruned — surfaced for a human to judge.
	Abandoned []string
	// Kept worktrees are held for any other reason: recently used (fresh), or
	// with an indeterminate base/tip or missing metadata.
	Kept []string
}

type ReconcileResult struct {
	// Tracked names are recorded AND still returned by List().
	Tracked []string
	// Orphaned names are recorded but no longer returned by List() (their admin
	// dir was removed out-of-band). Reconcile drops them from the roster so
	// they are not silently kept.
	Orphaned []string
	// Untracked names are returned by List() but have no metadata record.
	Untracked []string
}

type Registry struct {
	// contains filtered or unexported fields
}

type Worktree interface {
	// Stage adds the working-tree path (file or directory, relative to the
	// worktree root) to this worktree's index. Staging here can never touch
	// another worktree's index.
	Stage(path string) error

	// Status returns the porcelain status of this worktree.
	Status() (git.Status, error)

	// Commit records the current index of this worktree as a new commit on its
	// current branch and returns the new commit hash. opts may be nil.
	Commit(message string, opts *CommitOptions) (plumbing.Hash, error)

	// Head returns the worktree's current HEAD reference.
	Head() (*plumbing.Reference, error)

	// Branch returns the short name of the branch HEAD points to, or "" if HEAD
	// is detached.
	Branch() (string, error)
}