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
	// 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)
	DispatchWorkflow(ctx context.Context, owner, repo, file, ref string, inputs map[string]any) 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"`
	// 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"`
	// 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 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
}