git

type AuthConfig struct {
	Type          AuthType
	SSHKeyPath    string // Path to SSH private key
	SSHPassword   string // SSH key passphrase
	HTTPSUsername string // HTTPS username
	HTTPSPassword string // HTTPS password/token
}

type AuthType int

type CheckoutOptions struct {
	CreateBranch string // Create new branch at ref (empty = no creation)
	Force        bool   // Discard local changes
	Detach       bool   // Detach HEAD (create detached HEAD state)
}

type CloneOptions struct {
	Branch         string                 // Specific branch to clone (empty = default branch)
	Depth          *int                   // Shallow clone depth (nil = full clone)
	SingleBranch   bool                   // Clone only the specified branch
	Bare           bool                   // Create a bare repository
	SparseCheckout *SparseCheckoutOptions // Sparse checkout config (nil = full checkout)
}

type Commit struct {
	Hash      string    `json:"hash"`
	Author    string    `json:"author"`
	Date      time.Time `json:"date"`
	Message   string    `json:"message"`
	ShortHash string    `json:"shortHash"`
}

type Config struct {
	// DefaultAuthor is used when no Git user is configured.
	DefaultAuthor string

	// DefaultEmail is used when no Git email is configured.
	DefaultEmail string

	// Auth configures authentication for remote operations.
	Auth *AuthConfig
}

type FetchOptions struct {
	Remote string // Remote name (default: "origin")
	Branch string // Specific branch to fetch (empty = all branches)
	Prune  bool   // Remove remote-tracking references that no longer exist
	Tags   bool   // Fetch tags
}

type FileInfo struct {
	Path  string
	IsDir bool
	Size  int64
}

type GitError struct {
	Op     string // Operation that failed (e.g., "clone", "push")
	Path   string // Repository path
	Err    error  // Underlying error
	Stderr string // Git command stderr output (if applicable)
}

type InitOptions struct {
	Bare          bool   // Create bare repository
	DefaultBranch string // Name of default branch (empty = "main")
}

type PullOptions struct {
	Remote      string // Remote name (default: "origin")
	Branch      string // Remote branch (empty = tracking branch)
	FastForward bool   // Only allow fast-forward merges
	Rebase      bool   // Rebase instead of merge
}

type PullResult struct {
	Updated       bool     // Whether local branch was updated
	OldCommit     string   // Commit hash before pull
	NewCommit     string   // Commit hash after pull
	ConflictFiles []string // Files with conflicts (if any)
}

type PushOptions struct {
	Remote      string // Remote name (default: "origin")
	Branch      string // Local branch to push (empty = current branch)
	Force       bool   // Force push (overwrite remote)
	SetUpstream bool   // Set upstream tracking branch
}

type PushResult struct {
	Pushed        bool // Whether any commits were pushed
	Rejected      bool // Whether push was rejected
	CommitsPushed int  // Number of commits pushed
}

type Remote struct {
	Name     string
	FetchURL string
	PushURL  string
}

type Repository interface {
	// GetStatus returns the current Git status of a node directory.
	GetStatus(ctx context.Context, nodePath string) (*Status, error)

	// GetDiff returns the diff of uncommitted changes.
	GetDiff(ctx context.Context, nodePath string, staged bool) (string, error)

	// GetHistory returns the commit history for a node.
	GetHistory(ctx context.Context, nodePath string, limit int) ([]Commit, error)

	// CreateCommit creates a new commit with the given message.
	CreateCommit(ctx context.Context, nodePath, message string) error

	// StageFiles stages the specified files for commit.
	StageFiles(ctx context.Context, nodePath string, files []string) error

	// UnstageFiles unstages the specified files.
	UnstageFiles(ctx context.Context, nodePath string, files []string) error

	// Clone creates a local copy of a remote repository.
	Clone(ctx context.Context, url string, localPath string, options CloneOptions) error

	// Fetch downloads objects and refs from remote repository.
	Fetch(ctx context.Context, nodePath string, options FetchOptions) error

	// Pull fetches from remote and integrates into current branch.
	Pull(ctx context.Context, nodePath string, options PullOptions) (*PullResult, error)

	// Push uploads local commits to remote repository.
	Push(ctx context.Context, nodePath string, options PushOptions) (*PushResult, error)

	// IsAncestor determines if one commit is an ancestor of another.
	IsAncestor(ctx context.Context, nodePath string, ancestor string, descendant string) (bool, error)

	// GetRemoteHead retrieves the commit hash of a remote branch.
	GetRemoteHead(ctx context.Context, nodePath string, remote string, branch string) (string, error)

	// GetCurrentCommit returns the commit hash of the current HEAD.
	GetCurrentCommit(ctx context.Context, nodePath string) (string, error)

	// Checkout switches to a different branch or commit.
	Checkout(ctx context.Context, nodePath string, ref string, options CheckoutOptions) error

	// InitRepository creates a new git repository.
	InitRepository(ctx context.Context, path string, options InitOptions) error

	// AddRemote adds a remote repository reference.
	AddRemote(ctx context.Context, nodePath string, name string, url string) error

	// ListRemotes returns all configured remotes.
	ListRemotes(ctx context.Context, nodePath string) ([]Remote, error)

	// GetFileAtCommit retrieves file content from a specific commit.
	GetFileAtCommit(ctx context.Context, nodePath string, commit string, filePath string) ([]byte, error)

	// ListFilesAtCommit lists all files in a directory at a specific commit.
	ListFilesAtCommit(ctx context.Context, nodePath string, commit string, dirPath string) ([]FileInfo, error)

	// IsRepoBare checks if a repository is bare (no working directory).
	IsRepoBare(ctx context.Context, repoPath string) (bool, error)

	// GetCurrentBranch returns the name of the current branch.
	// Returns error if repository is in detached HEAD state.
	GetCurrentBranch(ctx context.Context, repoPath string) (string, error)

	// ConfigureUser sets the user.name and user.email for a repository.
	// This is required before creating commits.
	ConfigureUser(ctx context.Context, repoPath string, name string, email string) error

	// UpdateRemoteURL updates the URL of an existing remote.
	UpdateRemoteURL(ctx context.Context, repoPath string, remoteName string, newURL string) error
}

type SparseCheckoutOptions struct {
	// Cone enables cone mode sparse checkout (recommended).
	// When true, Paths are treated as directory paths.
	// When false, sparse checkout is disabled.
	Cone bool

	// Paths specifies the directories to checkout in cone mode.
	// Example: []string{".c2/recipes", "docs"}
	// Empty slice disables sparse checkout.
	Paths []string
}

type Status struct {
	Branch    string       `json:"branch"`
	Clean     bool         `json:"clean"`
	Files     []StatusFile `json:"files"`
	Ahead     int          `json:"ahead"`
	Behind    int          `json:"behind"`
	HasRemote bool         `json:"hasRemote"`
}

type StatusFile struct {
	Path   string `json:"path"`
	Status string `json:"status"` // "M", "A", "D", "?", etc.
}