github

type APIError struct {
	Status  int
	Message string
	// RateLimited marks a throttle: GitHub's primary limit answers 403 and its
	// secondary limit 429, and neither says anything about the credential —
	// reporting a throttled 403 as "GitHub refused the App credential" sends
	// the operator to their key file over a wait. Detected from the message,
	// because the body is what this type carries; the message shapes are
	// GitHub's documented rate-limit responses.
	RateLimited bool
}

type App struct {
	ID            int64  `json:"id"`
	Slug          string `json:"slug"`
	NodeID        string `json:"node_id"`
	Name          string `json:"name"`
	HTMLURL       string `json:"html_url"`
	PEM           string `json:"pem"`
	WebhookSecret string `json:"webhook_secret"`
	ClientID      string `json:"client_id"`
	ClientSecret  string `json:"client_secret"`

	Owner struct {
		Login string `json:"login"`
	} `json:"owner"`
}

type HookAttributes struct {
	URL    string `json:"url,omitempty"`
	Active bool   `json:"active"`
}

type Installation struct {
	ID      int64 `json:"id"`
	Account struct {
		Login string `json:"login"`
		Type  string `json:"type"`
	} `json:"account"`
	Permissions  map[string]string `json:"permissions"`
	RepositoryCt int               `json:"-"`
	// SuspendedAt is non-nil when the installation is suspended — GitHub's way
	// of disabling an App without uninstalling it. A suspended installation
	// answers this endpoint with a matching id and matching permissions while
	// every installation-token request fails, so verification must refuse it.
	SuspendedAt *time.Time `json:"suspended_at"`
}

type Manifest struct {
	Name string `json:"name,omitempty"`
	// URL is required by GitHub even for an app that serves no web surface.
	URL            string            `json:"url"`
	HookAttributes *HookAttributes   `json:"hook_attributes,omitempty"`
	RedirectURL    string            `json:"redirect_url,omitempty"`
	SetupURL       string            `json:"setup_url,omitempty"`
	Description    string            `json:"description,omitempty"`
	Public         bool              `json:"public"`
	DefaultEvents  []string          `json:"default_events,omitempty"`
	Permissions    map[string]string `json:"default_permissions,omitempty"`
	// SetupOnUpdate keeps the installation callback firing when an operator
	// changes which repositories the app can see, so a re-scoped install still
	// lands back here.
	SetupOnUpdate bool `json:"setup_on_update,omitempty"`
}

type OnboardOptions struct {
	Org string
	// Name pre-fills the app name. GitHub app names are globally unique, so this
	// is a suggestion the operator edits on GitHub's own page.
	Name string
	// OpenBrowser is called with each URL the operator must visit. Returning an
	// error is not fatal: the URL is printed for manual use, which is what makes
	// the flow work over SSH.
	OpenBrowser func(context.Context, string) error
	// OnAppCreated is called the moment the app's credentials exist, BEFORE the
	// installation step. Required.
	//
	// The ordering is the point: GitHub registers the app during the browser redirect
	// and the private key is returned exactly once by the conversion, so persisting it
	// at the END would let any failure in the installation phase leave a real
	// registered app whose only key had been discarded. Returning an error here aborts,
	// because continuing produces that same orphan.
	OnAppCreated func(*App) error

	// Log receives human-facing progress. Required.
	Log func(format string, args ...any)
	// Client is optional; a sane default is used when nil.
	Client *http.Client
	// InstallPoll is how often to check whether the install finished, used when
	// the post-install redirect never arrives.
	InstallPoll time.Duration

	// Port fixes the loopback callback port. Zero picks a free one.
	//
	// It exists for the remote case: onboarding a CI host over SSH is the normal
	// way this runs, and there the callback listens on the SERVER's loopback
	// while the browser is on a laptop, where 127.0.0.1 means the laptop. That
	// needs `ssh -L`, and a forward needs a port known in advance.
	Port int
	// contains filtered or unexported fields
}

type Onboarding struct {
	App          *App
	Installation *Installation
}

type RunnerGroupPolicyClient interface {
	ValidateTrustedRunnerGroup(ctx context.Context, groupID int, wantWorkflows []string) error
	// ValidateRunnerGroupReach asks only whether a group can be assigned a job
	// at all. It is the half of the trusted validation that applies to EVERY
	// tier, including an untrusted one, which lives in the default group and was
	// asked nothing.
	ValidateRunnerGroupReach(ctx context.Context, groupID int) error
	InspectScaleSetRunner(ctx context.Context, runnerName string, runnerID int64) (RunnerRecovery, error)
	// FindRunnerGroupID resolves a name so a caller holding only the App
	// credentials can validate a group, which is what lets `billet check` reach
	// the same verdict the server does without an Actions-tenant client.
	FindRunnerGroupID(ctx context.Context, name string) (int, bool, error)
}

type RunnerRecovery struct {
	RunnerID int64
	Present  bool
	Busy     bool
}