create

type Deps struct {
	Engine Engine
	actions.MutationDeps
	Log output.Logger
	// Verify runs git commit hooks when set (the inverse of --no-verify).
	Verify bool
	// Worktrees backs --worktree; it may be nil when --worktree is not used.
	Worktrees Worktrees
}

type Engine interface {
	validation.BranchValidationEngine
	actions.OwnershipEngine
	CurrentBranch(ctx context.Context) *engine.Branch
	Trunk() engine.Branch
	IsTrunk(branch engine.Branch) bool
	AllBranches() engine.Branches
	BranchNames() *engine.BranchSet
	Graph(ctx context.Context, strategy engine.SortStrategy) *engine.StackGraph
	SortBranchesTopologically(ctx context.Context, branches engine.Branches) engine.Branches
	GetScope(branch engine.Branch) engine.Scope
	SetScope(ctx context.Context, branch engine.Branch, scope engine.Scope) error
	GetUserName(ctx context.Context) (string, error)
	GetWorkingTreeStatus(ctx context.Context) (git.WorktreeStatus, error)
	GetCommitTemplate(ctx context.Context) (string, error)
	StageChanges(ctx context.Context, opts git.StagingOptions) error
	StageAll(ctx context.Context) error
	Commit(ctx context.Context, opts git.CommitOptions) error
	CreateBranch(ctx context.Context, branchName string, startPoint string) error
	CreateAndCheckoutBranch(ctx context.Context, branch engine.Branch) error
	CheckoutBranch(ctx context.Context, branch engine.Branch) error
	DeleteBranch(ctx context.Context, branch engine.Branch) error
	TrackBranch(ctx context.Context, branchName string, parentBranchName string) error
	ReparentBranchesToParents(ctx context.Context, moves []engine.BranchParentMove, opts engine.ReparentOpts) error
	RestackBranches(ctx context.Context, branches engine.Branches, opts engine.RestackOpts) (engine.RestackBatchResult, error)
	ConfigureRemoteMetadataSync(ctx context.Context) error
}

type Handler interface {
	// Start is called at the beginning of create
	Start(parentBranch string)

	// OnStep is called for each step in the create process
	OnStep(step Step, status handler.StepStatus, message string)

	// Complete is called when create finishes
	Complete(result Result)

	// Cleanup restores terminal state (may be no-op)
	Cleanup()

	// IsInteractive returns true if the handler supports interactive prompts
	IsInteractive() bool

	// PromptStageChanges prompts user to stage unstaged changes
	PromptStageChanges() (bool, error)

	// PromptScope prompts user for a scope value when pattern contains {scope}
	// The patternHint shows the current branch pattern to the user
	PromptScope(patternHint string) (string, error)

	// PromptChildToMove asks which of the current branch's children should be
	// moved onto a newly inserted branch. Returns "all" to move every child, or
	// a specific child name. Only called when IsInteractive() is true.
	PromptChildToMove(children []string) (string, error)
}

type NullHandler struct {
	handler.NullBase
	handler.NullProgress[Step]
}

type Options struct {
	BranchName    string
	Message       string
	Scope         string
	All           bool
	Insert        bool
	Patch         bool
	Update        bool
	Verbose       int
	BranchPattern config.BranchPattern
	// SelectedChildren is used to specify which children to move during insert
	// in non-interactive mode (mostly for tests)
	SelectedChildren []string
	// Onto creates the branch as a tracked child of this branch instead of the
	// current branch, without checking it out. Mutually exclusive with
	// Worktree and Insert.
	Onto string
	// Worktree creates a dedicated worktree for this stack (only valid from trunk)
	Worktree bool
	// AllowEmpty permits creating a branch with no commit when the working tree
	// has unstaged/untracked changes in non-interactive mode (otherwise that is
	// treated as a "forgot to stage" mistake and rejected).
	AllowEmpty bool
}

type Result struct {
	BranchName   string
	ParentBranch string
	HasCommit    bool
	WorktreePath engine.WorktreePath
}

type Step string

type Worktrees interface {
	// CreateAnchored creates a managed worktree anchored on branchName and
	// returns its path.
	CreateAnchored(ctx context.Context, branchName, name, scope string) (engine.WorktreePath, error)
	// RunPostCreateHooks runs the configured post-create hooks in path.
	RunPostCreateHooks(ctx context.Context, path engine.WorktreePath) error
}