git

type ApplyPatchesRequest struct {
	URL     string
	Auth    Auth
	Branch  string   // branch name to force-push the result to
	BaseRef string   // commit hash to start from
	Patches []string // ordered raw diff content, applied in order

	// ExpectedTip, when non-empty, is the branch's remote tip as last
	// observed by the caller (e.g. a prior Read). The push is performed as
	// a compare-and-swap: it only succeeds if the branch's current remote
	// tip still equals ExpectedTip, and returns a *ConflictError otherwise.
	// An empty ExpectedTip means push unconditionally, as before this field
	// existed (used for Create, and for Update when on_conflict is
	// "force").
	ExpectedTip string
}

type ApplyPatchesResult struct {
	ResolvedSHA string // HEAD after applying all patches, i.e. what was pushed
}

type Auth struct {
	Token string // empty means unauthenticated
	Host  string // host type, e.g. "github" or "gitlab"; "" for unknown/generic
}

type Client interface {
	// LsRemote lists refs on the given remote URL, verifying it is reachable
	// and that auth (if any) is valid.
	LsRemote(ctx context.Context, url string, auth Auth) ([]Ref, error)

	// ApplyPatches applies req.Patches in order as commits on top of
	// req.BaseRef, then force-pushes the result to req.Branch on req.URL.
	ApplyPatches(ctx context.Context, req ApplyPatchesRequest) (ApplyPatchesResult, error)

	// IsAncestor reports whether ancestor is an ancestor of (or equal to)
	// descendant in url's history. A false, nil result means "no" — either
	// genuinely not an ancestor, or ancestor could no longer be found in
	// url's history even after a full fetch (rewritten away / garbage
	// collected), which for this provider's purposes is the same
	// conclusion: the ref did not move forward from ancestor. A non-nil
	// error means the check itself could not be completed (network, auth,
	// transport) and should be surfaced like any other backend failure.
	IsAncestor(ctx context.Context, url string, auth Auth, ancestor, descendant string) (bool, error)
}

type ConflictError struct {
	Branch      string
	ExpectedTip string
	Err         error // underlying backend error, for detail/logging
}

type Ref struct {
	Name string // e.g. "HEAD", "refs/heads/main"
	Hash string // full object hash
}