pubgh

type ArtifactDigest string

type ArtifactID int64

type ArtifactMeta interface {
	// Get returns metadata for id in repository.
	//
	// Callers must not assume Get downloads the archive or recomputes
	// its digest.
	Get(ctx context.Context, repository Repository, id ArtifactID) (ArtifactMetadata, error)
}

type ArtifactMetadata struct {
	// ID is the observed artifact identifier.
	ID ArtifactID
	// Name is the observed artifact name.
	Name string
	// Digest is the GitHub-reported digest. The zero value means GitHub
	// reported no digest.
	Digest ArtifactDigest
	// SizeBytes is the reported archive size.
	SizeBytes int64
	// HasRun reports whether workflow-run metadata was present.
	HasRun bool
	// Run is the workflow run that produced the artifact. It is only
	// valid when HasRun is true.
	Run RunID
	// ExpiresAt is the reported expiry instant. The zero value means
	// GitHub reported no expiry.
	ExpiresAt time.Time
	// Expired reports GitHub's expired flag.
	Expired bool
}

type Asset struct {
	// Name is the asset file name on the release.
	Name string
	// Digest is the GitHub-reported digest, "sha256:<64 hex>". It is empty
	// until GitHub finishes processing the upload.
	Digest string
	// State is the GitHub-reported asset state. It is "uploaded" when the
	// asset is ready.
	State string
}

type AssetPath string

type AssetReplacer interface {
	// Replace uploads expected onto the release identified by tag.
	Replace(ctx context.Context, repository Repository, tag rel.Tag, expected []AssetPath) error
}

type AssetsView struct {
	// Assets are the GitHub-reported release assets, in API order.
	Assets []Asset
}

type BlobVerification struct {
	// Payload is the name inside the distribution directory, for example
	// checksums.txt.
	Payload string
	// Bundle is the name inside the distribution directory, for example
	// checksums.txt.sigstore.json.
	Bundle string
	// Identity is the exact certificate identity URL.
	Identity string
	// Issuer is the OIDC issuer URL.
	Issuer string
}

type BlobVerifier interface {
	// Verify checks request.Payload against request.Bundle using the
	// exact identity and issuer. Implementations must not mutate the
	// distribution directory.
	Verify(ctx context.Context, request BlobVerification) error
}

type Bundle struct {
	// Payloads are the checksummed release payloads, in checksums.txt order.
	Payloads []BundleEntry
	// Controls are exactly checksums.txt then checksums.txt.sigstore.json.
	Controls []BundleEntry
}

type BundleEntry struct {
	// Name is the flat file name inside the distribution directory.
	Name string
	// Digest is the lowercase SHA-256 hex digest with no prefix.
	Digest stage.Digest
}

type CommitSHA string

type Handoff struct {
	// Repository is the repository that owns the artifact.
	Repository Repository
	// Run is the workflow run that must own the artifact.
	Run RunID
	// Artifact is the expected artifact identifier.
	Artifact ArtifactID
	// Digest is the expected GitHub-reported artifact digest.
	Digest ArtifactDigest
}

type PollPolicy struct {
	// Attempts is the maximum number of lookups, including the first.
	Attempts int
	// Wait is the pause after each failed lookup, including the last.
	Wait time.Duration
}

type PublishInput struct {
	// Repository is the GitHub owner/name that owns the release.
	Repository Repository
	// Tag is the git tag bound to the draft release.
	Tag rel.Tag
	// Commit is the workflow's github.sha. The tag must resolve to it.
	Commit CommitSHA
	// Expected is the closed bundle rebuilt from the distribution
	// directory. Payload and control names carry their hex digests.
	Expected Bundle
	// Assets are the local paths to upload, in [Bundle] order.
	Assets []AssetPath
	// Undraft is false for --no-undraft: converge and stop while still
	// a draft.
	Undraft bool
	// Draft is the draft-discovery budget. The zero value selects
	// [DefaultDraftPolicy].
	Draft PollPolicy
	// Asset is the asset-convergence budget. The zero value selects
	// [DefaultAssetPolicy].
	Asset PollPolicy
	// Sleep waits between retryable GitHub calls and between poll
	// attempts. Nil selects a context-aware timer.
	Sleep SleepFunc
}

type PublishResult struct {
	// ReleaseID is the GitHub Release identifier.
	ReleaseID int64 `json:"release_id"`
	// Tag is the git tag bound to the release.
	Tag string `json:"tag"`
	// URL is the GitHub html_url of the release.
	URL string `json:"url"`
	// Draft reports the release draft state after the run.
	Draft bool `json:"draft"`
	// Assets are the converged asset names, sorted.
	Assets []string `json:"assets"`
}

type Publisher interface {
	// Publish marks the release public. It must not re-draft a public
	// release and must not create a release.
	Publish(ctx context.Context, repository Repository, release ReleaseID) error
}

type RefResolver interface {
	// Resolve returns the commit object ID named by tag.
	Resolve(ctx context.Context, tag rel.Tag) (CommitSHA, error)
}

type Release struct {
	// ID is the GitHub Release identifier.
	ID ReleaseID
	// Tag is the git tag bound to the release.
	Tag rel.Tag
	// Draft reports whether the release is still a draft.
	Draft bool
	// URL is the GitHub html_url of the release.
	URL string
}

type ReleaseID int64

type ReleaseReader interface {
	// FindDraft returns the unique release whose tag_name equals tag.
	//
	// The adapter lists once. Zero matches is [ErrNoDraft] immediately.
	// More than one match is [ErrAmbiguousRelease]. Otherwise it returns
	// the release with its real Draft flag; it does not wait for a draft
	// and does not refuse a public release. [Publish] retries [ErrNoDraft]
	// under [PublishInput.Draft].
	FindDraft(ctx context.Context, repository Repository, tag rel.Tag) (Release, error)
	// WaitAssets returns the current assets on release after one list pass.
	//
	// The adapter does not judge readiness, count, or digests. [Publish]
	// re-reads under [PublishInput.Asset] until the expected set matches.
	// Implementations must not mutate the release.
	WaitAssets(ctx context.Context, repository Repository, release ReleaseID) (AssetsView, error)
	// Get returns the current release metadata for id.
	Get(ctx context.Context, repository Repository, release ReleaseID) (Release, error)
}

type Repository struct {
	// Owner is the account or organization that owns the repository.
	Owner string
	// Name is the repository name.
	Name string
}

type RunID int64

type SleepFunc func(ctx context.Context, d time.Duration) error

type TrustPolicy struct {
	// Identity is the exact certificate identity URL. It is required.
	Identity string
	// Issuer is the OIDC issuer. An empty value defaults to
	// https://token.actions.githubusercontent.com.
	Issuer string
}