get

type Deps struct {
	Engine Engine
	Out    output.Output
	// GitHub returns the client, or nil when GitHub is unavailable. It is a
	// function so the client is only built when get actually needs it.
	GitHub func() github.Client
	// GitHubError explains why GitHub returned nil, when known. May be nil.
	GitHubError func() error
	// Restack is what the restack phase runs actions.RunRestack with.
	Restack actions.RestackDeps
}

type Engine interface {
	engine.BranchReader
	BranchNames() *engine.BranchSet
	GetRemote(ctx context.Context) string
	FetchRemote(ctx context.Context, req engine.RemoteFetchRequest) error
	MissingRemoteBranches(ctx context.Context, branchNames []string) ([]string, error)
	LoadRemoteMetadataCache(ctx context.Context) error
	RemoteMetadataCache() engine.RemoteMetadataView
	ApplyRemoteMetadataForBranches(ctx context.Context, branchNames []string) error
	ListWorktrees(ctx context.Context) (git.WorktreeList, error)
	CreateBranch(ctx context.Context, branchName string, startPoint string) error
	TrackBranch(ctx context.Context, branchName string, parentBranchName string) error
	TrackBranchPastLandedParent(ctx context.Context, branchName string, parentBranchName string, prior engine.PriorParent) error
	ReparentBranch(ctx context.Context, branch engine.Branch, newParent engine.Branch) error
	CheckoutBranch(ctx context.Context, branch engine.Branch) error
	ResetHard(ctx context.Context, revision string) error
	Merge(ctx context.Context, revision string, opts engine.MergeOptions) error
	SetFrozen(ctx context.Context, branches engine.Branches, state engine.FreezeState) (engine.BatchFreezeResult, error)
	BatchUpsertPrInfo(ctx context.Context, updates map[string]*engine.PrInfo) error
}

type Event struct {
	Phase       Phase         // Current phase
	Type        EventType     // Event type
	Branch      string        // Branch name (if applicable)
	PRNumber    *git.PRNumber // PR number (if applicable)
	Message     string        // Human-readable description
	NewRevision string        // For position changes
	IsNew       bool          // Is this a new branch?
	Error       error         // If non-nil, this step had an error
}

type EventType string

type Handler interface {
	// Start is called at the beginning of get with target info
	Start(targetBranch string, prNumber *git.PRNumber)

	// EmitEvent is called for each progress update
	EmitEvent(event Event)

	// ReportLandedAncestors explains that branches were re-anchored past an
	// ancestor that landed and left the remote, and asks whether to unfreeze
	// the ones get can safely rebase (report.Unfreezable) so this run rebases
	// them onto their new parent.
	ReportLandedAncestors(report LandedAncestorReport) (LandedAncestorDecision, error)

	// Complete is called when get finishes with the summary
	Complete(summary Summary)

	// RestackHandler methods are available for restack phase output
	// This ensures consistent restack output between get, sync, and restack commands
	actions.RestackHandler
}

type LandedAncestorDecision int

type LandedAncestorReport struct {
	// Reanchored lists the substitutions get made, trunk-first.
	Reanchored []Reanchored
	// Stale lists every branch left carrying the landed commits — the
	// re-anchored branches plus their descendants in this run — trunk-first.
	Stale []StaleBranch
	// CanRestack is false when restacking is disabled for this run, leaving
	// nothing to offer.
	CanRestack bool
}

type NullHandler struct {
	actions.NullRestackHandler
}

type Options struct {
	Downstack bool // Don't sync upstack branches if branch exists locally
	Force     bool // Overwrite all fetched branches with remote source of truth
	Restack   bool // Restack after syncing (default true)
	Unfrozen  bool // Checkout new branches as unfrozen
}

type Phase string

type Reanchored struct {
	// Branch is the branch that was tracked against a substitute parent.
	Branch string
	// LandedParent is the parent recorded on the remote, now gone from it.
	LandedParent string
	// LandedPR is the landed parent's PR number, when metadata recorded one.
	LandedPR *git.PRNumber
	// NewParent is the nearest surviving ancestor, often trunk.
	NewParent string
	// Anchor is the landed parent's tip at the time this branch was pushed, as
	// recorded in the branch's own remote metadata. It is what lets a later
	// restack replay only the branch's own commits. Empty when nothing on the
	// remote recorded it, which makes the branch unsafe to rebase — see
	// LandedAncestorReport.Unanchored.
	Anchor string
}

type StaleBranch struct {
	// Name is the branch.
	Name string
	// Frozen reports whether this run leaves the branch frozen. A frozen branch
	// mirrors the remote and restack resets rather than rebases it, so it stays
	// stale until something unfreezes it.
	Frozen bool
	// Anchored reports whether the re-anchored branch at the root of this
	// branch's subtree recorded a divergence anchor. Without one, rebasing
	// replays the landed commits instead of dropping them.
	Anchored bool
}

type Summary struct {
	TargetBranch    string // The branch that was retrieved
	BranchesCreated int    // Number of branches created
	BranchesUpdated int    // Number of branches updated
	Restacked       int    // Number of branches restacked
	IsFrozen        bool   // Was the target branch frozen?
	UpToDate        bool   // Everything was already current
}