forge

type APIError struct {
	Method     string
	URL        string
	StatusCode int
	Body       string
}

type Asset struct {
	Name     string // display name
	FilePath string // local file to upload
	MIMEType string // e.g., "application/json"
}

type AzureDevOpsForge struct {
	// BaseURL is the organization collection URL, e.g. "https://dev.azure.com/myorg"
	// (Azure DevOps Services) or "https://server/tfs/DefaultCollection" (Server).
	BaseURL string
	Project string
	Repo    string
	Token   string // Personal Access Token (HTTP Basic, empty username)
}

type BasicFactory struct {
	ProviderName string // "gitlab", "github", "gitea"
	BaseURL      string // e.g., "https://gitlab.prplanit.com"
	CredPrefix   string // credential env var prefix
}

type CommitFileOptions struct {
	Branch  string
	Path    string // file path in repo
	Content []byte
	Message string
}

type CommitFilesOptions struct {
	Branch      string
	Message     string
	Files       []FileAction
	ExpectedSHA string // optional: fail if branch head != this SHA
}

type CommitResult struct {
	SHA string
}

type Factory interface {
	ForRepo(ctx context.Context, repo string) (Forge, error)
}

type FileAction struct {
	Path    string
	Content []byte // nil for deletes
	Delete  bool   // true = delete this file
}

type Forge interface {
	// Provider returns which platform this forge represents.
	Provider() Provider

	// CreateRelease creates a release/tag on the forge.
	CreateRelease(ctx context.Context, opts ReleaseOptions) (*Release, error)

	// UploadAsset attaches a file to an existing release.
	UploadAsset(ctx context.Context, releaseID string, asset Asset) error

	// AddReleaseLink adds a URL link to a release (e.g., registry image links).
	AddReleaseLink(ctx context.Context, releaseID string, link ReleaseLink) error

	// CommitFile creates or updates a file in the repo via the forge API.
	// Used for badge SVG updates without a local clone.
	CommitFile(ctx context.Context, opts CommitFileOptions) error

	// CommitFiles creates or updates multiple files in a single atomic commit
	// via the forge API. Used by the commit subsystem for CI push.
	CommitFiles(ctx context.Context, opts CommitFilesOptions) (*CommitResult, error)

	// BranchHeadSHA returns the current HEAD SHA of a branch via the forge API.
	BranchHeadSHA(ctx context.Context, branch string) (string, error)

	// CreateMR opens a merge/pull request.
	CreateMR(ctx context.Context, opts MROptions) (*MR, error)

	// CancelPipeline cancels the currently running pipeline (best-effort cleanup
	// after deps pushes a repaired commit). Returns nil if the provider doesn't
	// support pipeline cancellation.
	CancelPipeline(ctx context.Context, pipelineID string) error

	// ListReleases returns all releases, newest first.
	ListReleases(ctx context.Context) ([]ReleaseInfo, error)

	// DeleteRelease removes a release by its tag name.
	DeleteRelease(ctx context.Context, tagName string) error

	// CreateTag creates a lightweight git tag pointing at a ref.
	// Used for rolling tag aliases (e.g., "latest") that are not releases.
	CreateTag(ctx context.Context, tagName, ref string) error

	// DeleteTag deletes a git tag.
	DeleteTag(ctx context.Context, tagName string) error

	// DownloadJobArtifact fetches a single file from the latest successful job's
	// artifacts for the given ref. Returns the raw file bytes.
	// Returns os.ErrNotExist (or equivalent) if no artifacts found.
	// Implementations may return ErrNotSupported if the forge doesn't support this.
	DownloadJobArtifact(ctx context.Context, ref, jobName, artifactPath string) ([]byte, error)

	// GetFileContent reads a file from the repo at the given ref.
	// Returns the raw file content. Returns os.ErrNotExist if file is not found.
	// Used by governance drift detection, asset sync, and repo inspection.
	GetFileContent(ctx context.Context, path, ref string) ([]byte, error)

	// DefaultBranch returns the default branch name for the repo.
	DefaultBranch(ctx context.Context) (string, error)
}

type ForgejoForge struct {
	*GiteaForge
}

type GitHubForge struct {
	BaseURL string // "https://api.github.com" or "https://ghes.example.com/api/v3"
	Token   string
	Owner   string
	Repo    string
}

type GitLabForge struct {
	BaseURL   string // e.g., "https://gitlab.prplanit.com"
	Token     string // private token or job token
	ProjectID string // numeric ID or "group/project" URL-encoded path
	// contains filtered or unexported fields
}

type GiteaForge struct {
	BaseURL string // e.g., "https://codeberg.org"
	Token   string
	Owner   string
	Repo    string
}

type MR struct {
	ID  string
	URL string
}

type MROptions struct {
	Title        string
	Description  string
	SourceBranch string
	TargetBranch string
	Draft        bool
}

type Provider string

type Release struct {
	ID  string // platform-specific ID
	URL string // web URL to the release page
}

type ReleaseInfo struct {
	ID          string // platform-specific ID (numeric for GitHub/Gitea, tag_name for GitLab)
	TagName     string
	Name        string // release title
	Description string // release body (markdown)
	Draft       bool
	Prerelease  bool
	CreatedAt   time.Time
}

type ReleaseLink struct {
	Name     string // display name (e.g., "Docker Hub 1.3.0")
	URL      string // target URL
	LinkType string // "image", "package", "other"
}

type ReleaseOptions struct {
	TagName     string
	Ref         string // commit SHA, branch, or tag to create the release from (required by GitLab when tag doesn't exist)
	Name        string
	Description string // markdown body (release notes)
	Draft       bool
	Prerelease  bool
}