releasepromote

type Config struct {
	// GitHub is required.
	GitHub GitHub
	// DryRun checks every repository and dispatches nothing.
	DryRun bool
	// Version is the candidate vX.Y.Z-rc.N to promote instead of the
	// latest; empty promotes the latest. [ValidVersion] checks its form.
	Version string
	// NotFoundHint is added to GitHub's 404 for a repository: what the
	// token reaches. Empty adds nothing.
	NotFoundHint string
	// Follow reads the run each dispatch started until it concludes, at
	// most FollowTimeout: a run that cuts no release, the stable gate's
	// refusal for one, is refused.
	Follow bool
	// FollowTimeout bounds following; zero means DefaultFollowTimeout.
	FollowTimeout time.Duration
	// Clock paces following; the zero value is the wall clock.
	Clock agentcli.Clock
	// Progress receives one line per repository; nil is silent.
	Progress *agentcli.Progress
}

type Document struct {
	agentcli.Envelope
	Result
}

type GitHub interface {
	DefaultBranch(ctx context.Context, owner, repo string) (string, error)
	ReadFile(ctx context.Context, owner, repo, path, ref string) ([]byte, bool, error)
	ListReleases(ctx context.Context, owner, repo string) ([]githubclient.Release, error)
	Reachable(ctx context.Context, owner, repo, ref, branch string) (bool, error)
	GetCombinedStatus(ctx context.Context, owner, repo, ref string) (githubclient.CombinedStatus, error)
	DispatchWorkflowRun(ctx context.Context, owner, repo, file, ref string, inputs map[string]any) (githubclient.DispatchedRun, error)
	GetWorkflowRun(ctx context.Context, owner, repo string, id int64) (githubclient.WorkflowRun, error)
	ListWorkflowRunJobs(ctx context.Context, owner, repo string, runID int64) ([]githubclient.WorkflowJob, error)
	CheckRunAnnotations(ctx context.Context, owner, repo string, id int64) ([]githubclient.Annotation, error)
	JobLog(ctx context.Context, owner, repo string, jobID int64) (io.ReadCloser, error)
}

type Identity struct {
	// Source is "keychain", the devctl GitHub App login, or "$NAME", the
	// environment variable that overrides it; empty until the token is
	// resolved.
	Source string `json:"source"`
	// Login is the account of the App login; empty for a token from the
	// environment, whose account devctl does not look up.
	Login string `json:"login"`
}

type Repository struct {
	// Repository is owner/repo.
	Repository string `json:"repository"`
	// Stable is the tag of the latest stable release; empty when there is
	// none.
	Stable string `json:"stable"`
	// Candidate is the tag of the candidate to promote; empty when there is
	// none.
	Candidate string `json:"candidate"`
	// NewestBuilt is, for not_built, the highest other candidate the
	// workflow would promote whose commit is built: promote it with
	// --version instead of waiting. Empty when there is none or for another
	// state.
	NewestBuilt string `json:"newestBuilt,omitempty"`
	// Later are, with --version, the release candidates on the default
	// branch cut after the promoted one, lowest first: the stable release
	// is the promoted candidate's commit, so they are not in it. Empty
	// without --version or when there is none.
	Later []string `json:"later,omitempty"`
	// StatusState is the combined commit status of the candidate: success,
	// pending, failure or error; empty until read.
	StatusState string `json:"statusState"`
	// State is one of the State constants.
	State string `json:"state"`
	// Message says what was done or why not.
	Message string `json:"message"`
	// Run is the run the dispatch started; nil before a dispatch or when
	// GitHub named no run.
	Run *Run `json:"run,omitempty"`
	// FailedJobs are, for refused, the run's failed jobs with the end of
	// their logs, where the stable gate's own output is.
	FailedJobs []prwait.FailedJob `json:"failedJobs,omitempty"`
	// Warnings name what the promotion went on despite: a failed commit
	// status of an advisory job (circleciclient.AdvisoryJobs), which the
	// release does not require. Empty when there is none.
	Warnings []string `json:"warnings,omitempty"`
}

type Result struct {
	// Team is the team whose repositories were promoted; empty for named
	// repositories.
	Team string `json:"team"`
	// DryRun is set with --dry-run: nothing was dispatched.
	DryRun bool `json:"dryRun"`
	// Identity is who dispatched the workflows, or would with --dry-run.
	Identity Identity `json:"identity"`
	// Repositories are the repositories in the order they were given or
	// the team file lists them.
	Repositories []Repository `json:"repositories"`
}

type Run struct {
	ID  int64  `json:"id"`
	URL string `json:"url"`
	// Status is queued, in_progress or completed; empty until read.
	Status string `json:"status"`
	// Conclusion is success, failure, cancelled, ... once completed.
	Conclusion string `json:"conclusion"`
}

type Sources struct {
	GitHub GitHub
	// Team lists the auto-release repositories of a team.
	Team func(ctx context.Context, team string) ([]string, error)
	// NotFoundHint is [Config]'s.
	NotFoundHint string
	// Identity is who the token acts as, for the document.
	Identity Identity
}