server

type App struct {

	// Approval is the optional approval-gate backend. nil disables gating
	// (gates recorded AWAITING are never satisfied — the check stays pending
	// with the awaiting-approval title). Set after
	// construction (e.g. by the serve command), so New's signature is unchanged.
	Approval approval.Backend
	// Objects is the optional object store for completed-log offload. nil keeps
	// logs in the local buffer only. Set after construction, like Approval.
	Objects ObjectStore
	// Executor is the optional CI backend serve drives when it triggers runs
	// itself (webhook → build). nil keeps serve reactive-only (runs start via
	// the CI system's own triggers, as before). Set after construction.
	Executor executor.Backend
	// PushVerifier verifies a Pub/Sub push OIDC bearer token, returning the
	// token's email claim. Set externally (like Approval/Objects); nil disables
	// the /pubsub/push endpoint (it returns 404).
	PushVerifier func(ctx context.Context, bearer string) (email string, err error)
	// APIVerifier verifies a Google-signed OIDC bearer token on /api/* routes,
	// returning the token's email claim (audience checking included). Set
	// externally, like PushVerifier; nil disables /api/* auth entirely
	// (local/dev). It is the only /api/* credential — the legacy shared-secret
	// HS256 path was removed once every caller migrated to OIDC.
	APIVerifier func(ctx context.Context, bearer string) (email string, err error)
	// contains filtered or unexported fields
}

type CheckRunUpdate struct {
	Title      string // check-run title (e.g. "Terraform plan" / "Terraform apply")
	Summary    string // GFM blast-radius headline + verdict chips + per-stack table (renders at the top)
	Text       string // the rendered plan report (renders below the summary)
	DetailsURL string // the live page for the full view
	Conclusion string // "" while running; otherwise success|failure|action_required|neutral
}

type Config struct {
	// PublicBaseURL is the public origin of THIS serve, used for the check-run
	// embedded DAG image URL (/img — public, GitHub's camo proxy fetches it).
	// Empty derives it from the inbound request.
	PublicBaseURL string
	// UIBaseURL is the central UI service's external base URL. Check-run
	// details and approval links point there; empty leaves them unset. The
	// UI's configured tier names must match serve environments (its routes
	// are /t/<tier>/e/<id> and /pr/<n>).
	UIBaseURL string
	// Environment is this serve's tier (e.g. "nonprod"). Run triggering scopes
	// its ChangeSets to it; empty disables webhook-driven run triggering.
	Environment string
	// LogsDir is where per-stack log buffers are written. Empty disables log
	// ingestion (the endpoints become no-ops).
	LogsDir string
	// GroupDepth controls the live DAG's grouping: stacks fold into groups by
	// their first GroupDepth path segments. 0 = unset → handlers default to 2.
	GroupDepth int
	// GroupPattern is a regexp whose first capture group is the group key;
	// overrides GroupDepth. Empty → fall back to GroupDepth grouping.
	GroupPattern string
	// PushServiceAccount is the allowed verified OIDC email for /pubsub/push.
	// Empty accepts any verified token.
	PushServiceAccount string
	// APIPrincipals maps a verified OIDC caller email (lowercase) to the API
	// scopes it holds (see the scope* constants). Only consulted when
	// App.APIVerifier is set.
	APIPrincipals map[string][]string
	// GitHubWebhookSecret is the HMAC-SHA256 secret GitHub sends on every webhook
	// delivery (X-Hub-Signature-256). Empty disables the /github/webhook endpoint.
	GitHubWebhookSecret string
	// Progress is the optional per-operation weighted phase set (from the policy
	// file's progress{} block) driving the full-progress bar. nil → built-in
	// fractions.
	Progress *config.ProgressConfig
	// BuildTriggerNames maps a Cloud Build trigger NAME to the run kind
	// ("plan"/"apply") it drives. Populated from the executor block; lets the
	// /pubsub/cloud-builds ingest recognize builds from serve's own triggers and
	// derive their kind. Empty disables inbound build reconciliation.
	BuildTriggerNames map[string]string
	// RequesterPool is the set of service-account identities configured for the applier pool.
	RequesterPool []string
}

type GitHub interface {
	// CreateCheckRun opens an in_progress check run with the given name whose
	// Details link is detailsURL; returns its id.
	CreateCheckRun(ctx context.Context, repo, sha, name, detailsURL string) (int64, error)
	// UpdateCheckRun patches an existing check run.
	UpdateCheckRun(ctx context.Context, repo string, checkRunID int64, u CheckRunUpdate) error
	// PostStatus sets a commit status (commit-status fallback).
	PostStatus(ctx context.Context, repo, sha, context_, state, description, targetURL string) error
	// PRHeadSHA returns the current head commit SHA of a pull request, so a
	// verdict is posted on the live head rather than a stale execution SHA.
	PRHeadSHA(ctx context.Context, repo string, pr int) (string, error)
	// PRAbandoned reports whether a pull request is closed WITHOUT having been
	// merged (i.e. abandoned). A merged PR returns false so its post-merge apply
	// keeps its grant. Returns (false, err) when the PR cannot be read.
	PRAbandoned(ctx context.Context, repo string, pr int) (bool, error)
	// MergeGroupPRs returns the PR numbers whose commits compose the merge group
	// at headSHA, via the commit→PRs association API.
	MergeGroupPRs(ctx context.Context, repo, headSHA string) ([]int, error)
	// ReRequestCheckRun re-requests a GitHub check-run.
	ReRequestCheckRun(ctx context.Context, repo string, checkRunID int64) error
	// MergeQueue returns the repository's merge-queue entries for the default
	// branch (GraphQL). A missing/invisible queue returns an empty result, not
	// an error, so the UI simply hides the hero.
	MergeQueue(ctx context.Context, repo string) (MergeQueueResult, error)
}

type MergeQueueEntry struct {
	Position int
	PR       int
	State    string // GitHub MergeQueueEntryState (QUEUED, MERGEABLE, AWAITING_CHECKS, LOCKED, UNMERGEABLE)
}

type MergeQueueResult struct {
	Branch  string
	Entries []MergeQueueEntry
}

type MockGitHub struct {
	CreateCheckRunFn    func(ctx context.Context, repo, sha, name, detailsURL string) (int64, error)
	UpdateCheckRunFn    func(ctx context.Context, repo string, checkRunID int64, u CheckRunUpdate) error
	PostStatusFn        func(ctx context.Context, repo, sha, context_, state, description, targetURL string) error
	PRHeadSHAFn         func(ctx context.Context, repo string, pr int) (string, error)
	PRAbandonedFn       func(ctx context.Context, repo string, pr int) (bool, error)
	MergeGroupPRsFn     func(ctx context.Context, repo, headSHA string) ([]int, error)
	ReRequestCheckRunFn func(ctx context.Context, repo string, checkRunID int64) error
	MergeQueueFn        func(ctx context.Context, repo string) (MergeQueueResult, error)
	// CreateCheckRunCalls counts CreateCheckRun invocations so tests can assert
	// the check run is created exactly once (idempotency).
	CreateCheckRunCalls int
}

type ObjectStore interface {
	Put(ctx context.Context, key string, r io.Reader) error
	Get(ctx context.Context, key string) (io.ReadCloser, error)
}

type PRMergeState struct {
	Environment     string
	RequiredCheck   string
	CheckConclusion string
	MergeBlocked    bool
	Blocker         string
}

type RealClient struct {
	// contains filtered or unexported fields
}

type Shell struct {
	// contains filtered or unexported fields
}