git

type BranchReader interface {
	GetCurrentBranch() (string, error)
	GetAllBranchNames(ctx context.Context) ([]string, error)
	GetCurrentBranchOrSHA(ctx context.Context) (string, error)
}

type BranchType string

type BranchWriter interface {
	CheckoutBranch(ctx context.Context, branchName string) error
	CheckoutBranchForce(ctx context.Context, branchName string) error
	CheckoutDetached(ctx context.Context, revision string) error
	CreateAndCheckoutBranch(ctx context.Context, branchName string) error
	CreateBranch(ctx context.Context, branchName, startPoint string) error
	CreateBranchForce(ctx context.Context, branchName, revision string) error
	DeleteBranch(ctx context.Context, branchName string) error
	RenameBranch(ctx context.Context, oldName, newName string) error
	UpdateBranchRef(ctx context.Context, branchName, revision string) error
}

type CherryPickOperations interface {
	CherryPick(ctx context.Context, commitSHA, onto string) (string, error)
	CherryPickSimple(ctx context.Context, commitSHA string) error
	CherryPickAbort(ctx context.Context) error
}

type CommandError struct {
	Command string
	Args    []string
	Stdout  string
	Stderr  string
	Err     error
}

type CommitOptions struct {
	Message     string
	Amend       bool
	NoEdit      bool
	Edit        bool
	Verbose     int
	ResetAuthor bool
	NoVerify    bool
}

type CommitReader interface {
	GetRevision(branchName string) (string, error)
	GetCurrentRevision(ctx context.Context) (string, error)
	BatchGetRevisions(branchNames []string) (map[string]string, []error)
	GetCommitDate(branchName string) (time.Time, error)
	GetCommitAuthor(branchName string) (string, error)
	GetCommitRange(ctx context.Context, base, head, format string) ([]string, error)
	GetCommitRangeSHAs(ctx context.Context, rr RevRange) ([]string, error)
	GetCommitHistorySHAs(ctx context.Context, branchName string) ([]string, error)
	GetCommitSHA(branchName string, offset int) (string, error)
	GetCommitLog(sha, format string) (string, error)
	GetRecentCommits(ctx context.Context, branchName string, count int) ([]RecentCommit, error)
	GetRecentCommitsInRange(ctx context.Context, revRange string) ([]RecentCommit, error)
	GetCommitTemplate(ctx context.Context) (string, error)
	GetParentCommitSHA(commitSHA string) (string, error)
}

type CommitWriter interface {
	Commit(message string, verbose int, noVerify bool) error
	CommitWithOptions(opts CommitOptions) error
	CommitAmendNoEdit(ctx context.Context) error
}

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

type DebugLogger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
}

type DiffOperations interface {
	GetMergeBase(ctx context.Context, rev1, rev2 string) (string, error)
	GetMergeBaseByRef(ctx context.Context, ref1, ref2 string) (string, error)
	IsAncestor(ctx context.Context, ancestor, descendant string) (bool, error)
	IsMerged(ctx context.Context, branchName, target string) (bool, error)
	IsSquashMerged(ctx context.Context, branchName, target string, cache *SquashMergeCache) (bool, error)
	GetMergedBranches(ctx context.Context, target string) (map[string]bool, error)
	IsDiffEmpty(ctx context.Context, branchName, base string) (bool, error)
	GetChangedFiles(ctx context.Context, rr RevRange) ([]string, error)
	ShowDiff(ctx context.Context, left, right string, stat bool) (string, error)
	ShowCommits(ctx context.Context, rr RevRange, patch, stat bool) (string, error)
	GetDiffNumstat(rr RevRange) (string, error)
	GetStagedDiff(ctx context.Context, files ...string) (string, error)
	GetUnstagedDiff(ctx context.Context, files ...string) (string, error)
	// GetUnstagedDiffBinary is like GetUnstagedDiff but includes full binary
	// content (`git diff --binary`) so the result can be reapplied with
	// `git apply`.
	GetUnstagedDiffBinary(ctx context.Context, files ...string) (string, error)
	// GetDiffBetween returns the raw diff between two refs, without color codes.
	// This is suitable for parsing into hunks.
	GetDiffBetween(ctx context.Context, rr RevRange, files ...string) (string, error)
}

type Hunk struct {
	File          string // File path
	OldStart      int    // Line number in old file (1-indexed)
	OldCount      int    // Number of lines in old file
	NewStart      int    // Line number in new file (1-indexed)
	NewCount      int    // Number of lines in new file
	Content       string // The actual diff content (including header)
	IndexLine     string // The index line from the diff (e.g., "index abc123..def456 100644") for --3way merging
	Binary        bool   // True if this represents a binary file change
	IsNewFile     bool   // True if this hunk is for a newly created file
	IsDeletedFile bool   // True if this hunk is for a deleted file
	FileMode      string // File mode (e.g., "100644", "100755") for new/deleted files
}

type HunkTarget struct {
	Hunk        Hunk
	CommitSHA   string
	CommitIndex int // Index in the commit list (0 = newest)
}

type Hunks []Hunk

type LocalMeta struct {
	Frozen              bool   `json:"frozen,omitempty"`
	NeedsPRBodyUpdate   bool   `json:"needsPRBodyUpdate,omitempty"`
	NavigationCommentID *int64 `json:"navigationCommentId,omitempty"`
}

type LocalMetaMap map[string]*LocalMeta

type LockReason string

type MergeOperations interface {
	Merge(ctx context.Context, branchName string, opts MergeOptions) error
	MergeMultiple(ctx context.Context, branches []string, opts MergeOptions) error
	IsMergeInProgress(ctx context.Context) bool
	MergeAbort(ctx context.Context) error
	GetUnmergedFiles(ctx context.Context) ([]string, error)
}

type MergeOptions struct {
	FFOnly  bool
	NoEdit  bool
	NoFF    bool
	Message string
}

type MergedParent struct {
	BranchName string   `json:"branchName"`
	PRNumber   *int     `json:"prNumber,omitempty"`
	PRState    *PRState `json:"prState,omitempty"` // MERGED or CLOSED
}

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

type MetaFields struct {
	ParentBranchName     *string
	ParentBranchRevision *string
	PrInfo               *PrInfoPersistence
	Scope                *string
	LockReason           LockReason
	BranchType           BranchType
	LastModifiedBy       *ModifiedBy
	LastModifiedAt       *time.Time
	LocalOnlyHash        *string
	MergedDownstack      []MergedParent
	StackID              *string
}

type MetadataCacheSummary struct {
	Hits   uint64
	Misses uint64
}

type MetadataOperations interface {
	ReadMetadata(branchName string) (*Meta, error)
	BatchReadMetadata(branchNames []string) (map[string]*Meta, map[string]error)
	WriteMetadata(branchName string, meta *Meta) error
	DeleteMetadata(ctx context.Context, branchName string) error
	RenameMetadata(oldName, newName string) error
	ListMetadata() (map[string]string, error)
	ReadLocalMetadata(branchName string) (*LocalMeta, error)
	BatchReadLocalMetadata(branchNames []string) LocalMetaMap
	WriteLocalMetadata(branchName string, meta *LocalMeta) error

	// Transaction support methods. The batch forms marshal each entry and
	// forward to CreateBlobsBatch — call them with len(metas) >= 1 from
	// engine_writer.go and transaction.go's commit path. ctx is honored for
	// the underlying git hash-object invocation.
	WriteMetadataBlobsBatch(ctx context.Context, metas []*Meta) ([]string, error)
	WriteLocalMetadataBlobsBatch(ctx context.Context, metas []*LocalMeta) ([]string, error)
	GetMetadataRefSHA(branchName string) string
	GetLocalMetadataRefSHA(branchName string) string

	// Cache management
	ClearMetadataCache()

	// MetadataCacheStats returns cumulative cache hit/miss counts since process start.
	// Used by tests and instrumentation to verify lazy-load behavior.
	MetadataCacheStats() MetadataCacheSummary
}

type ModifiedBy struct {
	GitName        string  `json:"gitName"`
	GitEmail       string  `json:"gitEmail"`
	GitHubUsername *string `json:"githubUsername,omitempty"`
}

type ObjectOperations interface {
	CreateBlob(content string) (string, error)
	// CreateBlobsBatch writes N blobs in a single `git hash-object` invocation.
	// Returns SHAs in input order. For small N (<3) callers should still use
	// CreateBlob — the temp-file staging required by the batch path only pays
	// off once per-blob subprocess overhead would dominate. ctx is honored for
	// the underlying git invocation so long-running batches can be canceled.
	CreateBlobsBatch(ctx context.Context, contents []string) ([]string, error)
	ReadBlob(sha string) (string, error)
	CatFile(sha string) (string, error)
}

type PRState string

type PatchOperations interface {
	ApplyPatch(ctx context.Context, patchFile string, threeWay bool) error
	// ApplyPatchToWorktree applies a patch (read from stdin) to the working
	// tree only, never the index. It applies atomically or fails leaving the
	// working tree untouched, so it can never write conflict markers.
	ApplyPatchToWorktree(ctx context.Context, patch string) error
	CheckCommutation(hunk Hunk, commitSHA, parentSHA string) (bool, error)
}

type PathOperations interface {
	CheckoutPaths(ctx context.Context, branch string, paths []string) error
	RemovePaths(ctx context.Context, paths []string) error
}

type PrInfoPersistence struct {
	Number      *int        `json:"number,omitempty"`
	Base        *string     `json:"base,omitempty"`
	BaseSHA     *string     `json:"baseSHA,omitempty"`
	URL         *string     `json:"url,omitempty"`
	Title       *string     `json:"title,omitempty"`
	Body        *string     `json:"body,omitempty"`
	State       *PRState    `json:"state,omitempty"`
	IsDraft     *bool       `json:"isDraft,omitempty"`
	LockReason  *LockReason `json:"lockReason,omitempty"`
	MergeBranch *string     `json:"mergeBranch,omitempty"`
}

type PullResult int

type PushOptions struct {
	Force                     bool
	ForceWithLease            bool
	ForceWithLeaseExpectedSHA string
	NoVerify                  bool
}

type PushSpec struct {
	BranchName string
	// ExpectedRemoteSHA is the SHA the remote ref is expected to be at, used for
	// force-with-lease. An empty value means the branch is not expected to exist
	// on the remote yet (a create); the lease then asserts the ref is absent.
	ExpectedRemoteSHA string
}

type RebaseOperations interface {
	Rebase(ctx context.Context, branchName, upstream, oldUpstream string) (RebaseOutcome, error)
	RebaseContinue(ctx context.Context) (RebaseOutcome, error)
	RebaseContinueNoEdit(ctx context.Context) (RebaseOutcome, error)
	RebaseAbort(ctx context.Context) error
	InteractiveRebase(ctx context.Context, onto string) error
	IsRebaseInProgress(ctx context.Context) bool
	GetRebaseHead() (string, error)
	CheckRebaseInProgress(ctx context.Context) error
}

type RebaseOutcome struct {
	Result              RebaseResult
	RerereResolvedCount int
}

type RebaseResult int

type RecentCommit struct {
	SHA            string
	Subject        string
	Author         string
	Date           time.Time
	PRNumber       int              // parsed from subject suffix "(#123)" if present
	Kind           RecentCommitKind // derived from trailer metadata
	StackSize      int              // from Stackit-Stack-Size trailer (0 if absent)
	StackPRNumbers []int            // from Stackit-PRs trailer
	StackScope     string           // from Stackit-Scope trailer (empty if absent)
}

type RecentCommitKind string

type RecentCommits []RecentCommit

type RefDecoration struct {
	Name  string // short ref name, e.g. "main" or "v1.4.0"
	IsTag bool   // true for refs/tags/*, false for refs/heads/*
}

type RefOperations interface {
	GetRef(name string) (string, error)
	UpdateRef(name, sha string) error
	UpdateRefWithLog(ctx context.Context, refName, sha, message string) error
	UpdateRefsBatch(ctx context.Context, updates []RefUpdate) error
	UpdateRefsBatchWithLog(ctx context.Context, updates []RefUpdate, reflogMessage string) error
	DeleteRefsBatch(ctx context.Context, refNames []string) error
	VerifyRef(ctx context.Context, refName string) error
	DeleteRef(ctx context.Context, name string) error
	ListRefs(prefix string) (map[string]string, error)
	// RefDecorations returns local branch and tag refs grouped by the commit SHA
	// they point at, dereferencing annotated tags to the wrapped commit.
	RefDecorations() (map[string][]RefDecoration, error)
}

type RefUpdate struct {
	RefName  string
	NewSHA   string
	OldSHA   string // Optional: for optimistic locking verification
	IsDelete bool   // If true, this is a deletion instead of an update
}

type RemoteOperations interface {
	FetchRemoteShas(ctx context.Context, remote string) (map[string]string, error)
	GetRemoteSha(remote, branchName string) (string, error)
	GetRemoteRevision(branchName string) (string, error)
	FindRemoteBranch(ctx context.Context, remote string) (string, error)
	PushBranch(ctx context.Context, branchName, remote string, opts PushOptions) error
	PushBranches(ctx context.Context, remote string, specs []PushSpec, opts PushOptions) map[string]error
	PullBranch(ctx context.Context, remote, branchName string) (PullResult, error)
	UpdateBranchFromRemote(ctx context.Context, remote, branchName string) (PullResult, error)
	Fetch(ctx context.Context, remote, branch string) error
	FetchRefSpecs(ctx context.Context, remote string, refspecs []string) error
	PushMetadataRefs(ctx context.Context, branches []string) error
	FetchMetadataRefs(ctx context.Context) error
	DeleteRemoteMetadataRef(ctx context.Context, branch string) error
	BatchDeleteRemoteMetadataRefs(ctx context.Context, branches []string) error
	TestRemoteRefCompatibility(ctx context.Context) error
	PushStackMetaRefs(ctx context.Context, stackIDs []string) error
	FetchStackMetaRefs(ctx context.Context) error
	DeleteRemoteStackMetaRefs(ctx context.Context, stackIDs []string) error
}

type RepositoryReader interface {
	GetRemote() string
	GetConfig(key string) (string, error)
	GetConfigAll(key string) ([]string, error)
	GetRepoRoot() string
	DiscoverRepoRoot() (string, error)
	// GetGitCommonDir returns the path to the shared .git directory.
	// For regular repos this is the same as .git, but for worktrees it returns
	// the main repository's .git directory (where config is stored).
	GetGitCommonDir() (string, error)
	IsInsideRepo() bool
	GetUserName(ctx context.Context) (string, error)
	GetRepoInfo(ctx context.Context) (string, string, error)
}

type RepositoryWriter interface {
	InitDefaultRepo() error
	SetConfig(key, value string) error
	AddConfigValue(key, value string) error
	EnsureMetadataRefspecConfigured() error
	EnsureStackMetaRefspecConfigured() error
}

type ResetOperations interface {
	HardReset(ctx context.Context, revision string) error
	ResetMerge(ctx context.Context, revision string) error
	SoftReset(ctx context.Context, revision string) error
	MixedReset(ctx context.Context, revision string) error
}

type RevRange struct {
	Base string
	Head string
}

type Runner interface {
	// Repository access and configuration
	RepositoryReader
	RepositoryWriter

	// Remote operations
	RemoteOperations

	// Branch operations
	BranchReader
	BranchWriter

	// Commit and revision access
	CommitReader

	// Diff and comparison
	DiffOperations

	// Staging area
	StagingOperations

	// Commit creation
	CommitWriter

	// Advanced git operations
	RebaseOperations
	MergeOperations
	CherryPickOperations
	StashOperations
	ResetOperations
	PathOperations
	PatchOperations

	// Worktree management
	WorktreeOperations
	WorktreeRegistryOperations

	// Repository status
	StatusOperations

	// Low-level operations
	RefOperations
	ObjectOperations
	MetadataOperations
	StackMetadataOperations

	// Raw command execution
	RunGitCommandWithContext(ctx context.Context, args ...string) (string, error)
	RunGitCommandRawWithContext(ctx context.Context, args ...string) (string, error)
	RunGitCommandWithEnv(ctx context.Context, env []string, args ...string) (string, error)
	RunGitCommandInteractive(args ...string) error
	RunGHCommandWithContext(ctx context.Context, args ...string) (string, error)

	// Logging
	SetLogger(logger DebugLogger)
}

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

type StackDescription struct {
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
}

type StackMeta struct {
	ID          string    `json:"id"`                    // Matches ref name (timestamp-sanitized-root)
	Title       string    `json:"title,omitempty"`       // Stack title
	Description string    `json:"description,omitempty"` // Stack description
	CreatedAt   time.Time `json:"createdAt"`             // When stack was created
	CreatedBy   string    `json:"createdBy,omitempty"`   // Who created the stack (git user)
}

type StackMetadataOperations interface {
	ReadStackMeta(stackID string) (*StackMeta, error)
	WriteStackMeta(stackID string, meta *StackMeta) error
	DeleteStackMeta(ctx context.Context, stackID string) error
	ListStackMetas() (map[string]string, error)

	// Transaction support methods
	WriteStackMetaBlob(meta *StackMeta) (string, error)
	GetStackMetaRefSHA(stackID string) string
}

type StagingOperations interface {
	StageAll(ctx context.Context) error
	StagePatch(ctx context.Context) error
	StageTracked(ctx context.Context) error
	AddAll(ctx context.Context) error
	StageChanges(ctx context.Context, opts StagingOptions) error
	HasStagedChanges(ctx context.Context) (bool, error)
	HasUnstagedChanges(ctx context.Context) (bool, error)
	HasUntrackedFiles(ctx context.Context) (bool, error)
	GetUntrackedFiles(ctx context.Context) ([]string, error)
	ParseStagedHunks(ctx context.Context) ([]Hunk, error)
	StageHunks(ctx context.Context, hunks []Hunk) error
	UnstageAll(ctx context.Context) error
}

type StagingOptions struct {
	All    bool
	Update bool
	Patch  bool
}

type StashOperations interface {
	StashPush(ctx context.Context, message string) (string, error)
	StashPushStaged(ctx context.Context, message string) (string, error)
	StashDrop(ctx context.Context, ref string) error
	StashPop(ctx context.Context) error
	StashPopRef(ctx context.Context, ref string) error
	ListStash(ctx context.Context) (string, error)
}

type StatusOperations interface {
	GetStatusPorcelain(ctx context.Context) (string, error)
	GetReflog(ctx context.Context, count int, format string) (string, error)
	HasUncommittedChanges(ctx context.Context) bool
}

type Worktree struct {
	Path   string
	Branch string // empty when the worktree is at detached HEAD
}

type WorktreeDetachMode int

type WorktreeList []Worktree

type WorktreeMeta struct {
	Name         string    `json:"name,omitempty"` // User-provided name for display (new worktrees only)
	Path         string    `json:"path"`           // Absolute path to worktree
	AnchorBranch string    `json:"stackRoot"`      // Anchor branch for worktree (JSON: stackRoot for backwards compat)
	CreatedAt    time.Time `json:"createdAt"`      // When worktree was created
	MainRepoDir  string    `json:"mainRepoDir"`    // Path to main repo (for detection)
}

type WorktreeOperations interface {
	AddWorktree(ctx context.Context, path string, branch string, detach WorktreeDetachMode) error
	AddWorktreeWithOptions(ctx context.Context, path string, branch string, detach WorktreeDetachMode, noCheckout bool) error
	RemoveWorktree(ctx context.Context, path string) error
	ForceRemoveWorktree(ctx context.Context, path string) error
	ListWorktrees(ctx context.Context) (WorktreeList, error)
	PruneWorktrees(ctx context.Context) error
	GetWorktreePathForBranch(ctx context.Context, branchName string) (string, error)
	GetWorktreeCurrentBranch(ctx context.Context, worktreePath string) (string, error)
	ResetWorktreeWorkingDir(ctx context.Context, worktreePath string) error
	WorktreeHasUncommittedChanges(ctx context.Context, worktreePath string) (bool, error)
}

type WorktreeRegistryOperations interface {
	ReadWorktreeMeta(stackRoot string) (*WorktreeMeta, error)
	WriteWorktreeMeta(stackRoot string, meta *WorktreeMeta) error
	DeleteWorktreeMeta(ctx context.Context, stackRoot string) error
	ListWorktreeMetas() (map[string]*WorktreeMeta, error)
}