forge

type Check struct {
	Name       string
	Status     string // queued | in_progress | completed
	Conclusion string // success, failure, skipped, neutral, cancelled, timed_out, action_required, …
}

type CheckVisibility interface {
	// ChecksLimited reports whether ListChecks for repo had reduced visibility.
	ChecksLimited(repo string) bool
}

type Forge interface {
	GetRepo(ctx context.Context, full string) (Repo, error)
	CreatePrivateRepo(ctx context.Context, full string) (Repo, error)
	SetDefaultBranch(ctx context.Context, full, branch string) error
	FindOpenPR(ctx context.Context, full, head, base string) (*PR, error)
	CreatePR(ctx context.Context, full string, pr NewPR) (PR, error)
	GetPR(ctx context.Context, full string, number int) (PR, error)
	ListChecks(ctx context.Context, full, sha string) ([]Check, error)
	CurrentUser(ctx context.Context) (User, error)
	// SecretNames lists the Actions secret names visible to full: its own
	// and the org secrets shared with it. Values are never read.
	SecretNames(ctx context.Context, full string) ([]string, error)
	// PushRuns lists Actions runs for sha triggered by event "push" (any status).
	PushRuns(ctx context.Context, full, sha string) ([]Run, error)
	// CancelRun asks to cancel a queued or in-progress run. The host only
	// accepts the request: the run may keep going. A run the host won't
	// cancel in its current state, finished or not, is ErrConflict.
	CancelRun(ctx context.Context, full string, id int64) error
	// ForceCancelRun force-cancels a run that ignored CancelRun. Like
	// CancelRun, the host only accepts the request (a 202): the run may
	// still keep going. A 409 is ErrConflict, a plain permission refusal
	// ErrForbidden.
	ForceCancelRun(ctx context.Context, full string, id int64) error
	// ClosePullRequest closes PR number in full. A PR that is already
	// closed is not an error; a missing one is ErrNotFound, and a plain
	// permission refusal ErrForbidden.
	ClosePullRequest(ctx context.Context, full string, number int) error
	// EditPR changes PR number's title and body in full. A nil field is
	// left as it is. A missing PR is ErrNotFound, and a plain permission
	// refusal ErrForbidden.
	EditPR(ctx context.Context, full string, number int, title, body *string) error
}

type HostError struct {
	Message string
	Err     error
}

type Installation struct {
	ID          int64
	Account     string // login of the user or org it is installed on
	AccountType string // "User" | "Organization"
	Selection   string // "all" | "selected"
}

type Installer interface {
	// UserInstallations: GET /user/installations, every page.
	UserInstallations(ctx context.Context) ([]Installation, error)
	// InstallationRepos: GET /user/installations/{id}/repositories, every
	// page; owner/name of the repos the install covers that the user can
	// also access.
	InstallationRepos(ctx context.Context, id int64) ([]string, error)
}

type NewPR struct {
	Title string
	Body  string
	Head  string
	Base  string
	Draft bool
}

type PR struct {
	Number int
	Head   string
	Base   string
	State  string
	Draft  bool
	URL    string
	// Merged is true when the PR was merged; State is then closed.
	Merged bool
}

type PermissionError struct {
	// Permission is what the token lacks, as GitHub's settings page names
	// it: "Workflows: write", or a set joined with " and ". For a classic
	// or OAuth token, "OAuth scope: repo".
	Permission string
	// Repo is the owner/name the refused call was about; "" for none.
	Repo string
}

type PermissionProber interface {
	// ProbePermissions makes only GET requests (and the push probe, which
	// pushes nothing) against full. A refusal is an answer, not an error;
	// a network failure on the first request is an error wrapping
	// ErrTransient, and a later one leaves that permission unknown.
	ProbePermissions(ctx context.Context, full string) (RepoPermissions, error)
	// OAuthScopes is the token's classic OAuth scopes, from GET /user's
	// X-OAuth-Scopes header. ok is false when GitHub sent no such header
	// (fine-grained and App tokens).
	OAuthScopes(ctx context.Context) (scopes []string, ok bool, err error)
}

type PushAccess struct {
	Can        string `json:"can"`
	HTTPStatus int    `json:"http_status"`
}

type PushProber interface {
	PushAccess(ctx context.Context, full string) PushAccess
}

type Repo struct {
	FullName      string
	Private       bool
	Fork          bool
	DefaultBranch string
	CloneURL      string
	// OwnerType is GitHub's type of the repo's owner: OwnerOrganization or
	// OwnerUser ("" when unknown).
	OwnerType string
}

type RepoPermissions struct {
	Have     map[string]string
	Accepted map[string]string
}

type Run struct {
	ID         int64
	Workflow   string
	Status     string // queued | in_progress | waiting | requested | pending | completed
	Conclusion string // set once Status is completed: success | failure | cancelled | …
	URL        string
}

type Stack struct {
	Number int
	PRs    []int
}

type Stacker interface {
	// CreateStack makes a stack of prs, bottom first. Each PR's base must be
	// the head of the PR below it.
	CreateStack(ctx context.Context, repo string, prs []int) (Stack, error)
	// AddToStack appends prs, bottom first, on top of stack number stack. A
	// 409 (another change to the stack is in progress) is ErrConflict.
	AddToStack(ctx context.Context, repo string, stack int, prs []int) (Stack, error)
	// StackOf is the stack PR pr is in, or nil when it isn't stacked, which
	// is every PR on a host without native stacks.
	StackOf(ctx context.Context, repo string, pr int) (*Stack, error)
}

type User struct {
	Login string
	ID    int64
}