git

type Backend interface {
	// Clone clones the repository to the specified directory.
	// If the directory already exists and contains a valid clone, this is a no-op.
	Clone(ctx context.Context, repoURL string, directory string) error

	// Pull fetches and merges the latest changes from the remote repository.
	Pull(ctx context.Context, directory string) error

	// GetRevision returns the current git revision (commit SHA) of the repository.
	GetRevision(ctx context.Context, directory string) (string, error)

	// GetStatus returns the current git status of the repository.
	// Returns information about uncommitted changes, branch, etc.
	GetStatus(ctx context.Context, directory string) (*Status, error)

	// EnsureCloned ensures the repository is cloned based on the clone strategy.
	// For "always": always clones (or re-clones if exists)
	// For "on-demand": only clones if directory doesn't exist
	// TODO: move cloneStrategy up to the caller and remove from here
	EnsureCloned(ctx context.Context, repoURL string, directory string, cloneStrategy string) error

	// IsGitRepository checks if the directory is a valid git repository.
	IsGitRepository(ctx context.Context, directory string) (bool, error)

	// GetCurrentBranch returns the current branch name or empty string if detached.
	GetCurrentBranch(ctx context.Context, directory string) (string, error)

	// IsDetached checks if HEAD is detached (not on any branch).
	IsDetached(ctx context.Context, directory string) (bool, error)

	// GetTrackingBranch returns the upstream tracking branch (e.g., "origin/main").
	// Returns empty string if no tracking branch is set.
	GetTrackingBranch(ctx context.Context, directory string) (string, error)

	// GetDefaultBranch detects the default branch from remote or origin/HEAD.
	// First tries to read from the cloned repository's origin/HEAD, then falls back to querying the remote.
	GetDefaultBranch(ctx context.Context, directory string, repoURL string) (string, error)

	// GetCommitCounts returns (behind, ahead) counts vs tracking branch.
	// Returns (0, 0) if no tracking branch exists.
	GetCommitCounts(ctx context.Context, directory string) (behind, ahead int, err error)

	// DetectState detects the complete state of a repository.
	// This function is fail-safe: it continues collecting state even if some checks fail.
	DetectState(ctx context.Context, directory string, configuredURL string) (*RepositoryState, error)

	// PullFFOnly pulls with fast-forward only to avoid creating merge commits.
	PullFFOnly(ctx context.Context, directory string) error

	// Fetch fetches from origin without merging.
	Fetch(ctx context.Context, directory string) error

	// StashPush stashes uncommitted changes with an optional message.
	StashPush(ctx context.Context, directory string, message string) error
}

type Client struct {
}

type RepositoryState struct {
	Exists         bool
	IsGitRepo      bool
	CurrentBranch  string // Empty if detached
	IsDetached     bool
	HasUncommitted bool
	HasUnpushed    bool
	TrackingBranch string // e.g., "origin/main"
	DefaultBranch  string // e.g., "main"
	CommitsBehind  int
	CommitsAhead   int
	RemoteURL      string
	RemoteMatches  bool
	LastError      error
}

type Status struct {
	// Branch is the current branch name.
	Branch string

	// Revision is the current commit SHA.
	Revision string

	// HasUncommittedChanges indicates if there are uncommitted changes.
	HasUncommittedChanges bool

	// RemoteURL is the remote repository URL.
	RemoteURL string
}