forge

type Forge interface {
	Reader
	Writer
}

type ProjectToken struct {
	ID        int
	Name      string
	ExpiresAt time.Time
	Active    bool
	Revoked   bool
}

type ProjectTokenRequest struct {
	Name      string
	Scopes    []string
	Role      config.AccessLevel
	ExpiresAt time.Time
}

type Protection struct {
	// Exists is false when the branch carries no protection at all.
	Exists bool
	// AllowForcePush is GitHub's absent non_fast_forward rule, and GitLab's
	// allow_force_push flag.
	AllowForcePush bool
	// AllowDelete is GitHub's absent deletion rule. On GitLab it is ALWAYS
	// false: deleting a protected branch is denied with no toggle (R9), so a
	// configured allow_delete: false is satisfied by protection existing at
	// all and must never be reported as drift.
	AllowDelete bool
	// PushAccessLevel is GitLab only. It carries the zero value on GitHub,
	// which models no equivalent, and is therefore never compared there
	// (FR-026).
	PushAccessLevel config.AccessLevel
}

type Reader interface {
	// DefaultBranch reports the branch the platform serves as default (FR-023).
	DefaultBranch(ctx context.Context) (string, error)
	// BranchExists reports whether the named branch is on the platform. It is
	// what lets the protection check skip with a reason rather than fail when
	// the target branch is not there yet (FR-024).
	BranchExists(ctx context.Context, name string) (bool, error)
	// Protection reads the protection in force on a branch (FR-024).
	Protection(ctx context.Context, branch string) (Protection, error)
	// TagProtection lists the tag patterns the platform protects (FR-025).
	TagProtection(ctx context.Context) ([]string, error)
	// Variable reads what the platform reports about a CI variable (FR-026).
	Variable(ctx context.Context, name string, secret bool) (VariableState, error)
}

type Target struct {
	Instance config.Instance
	Owner    string
	Repo     string

	// Credential is the token read from the environment variable the instance
	// names. It is never logged and never rendered (FR-054, CLI-004).
	Credential string
}

type TokenIssuer interface {
	// ProjectTokens lists the active tokens carrying the given name (FR-028).
	ProjectTokens(ctx context.Context, name string) ([]ProjectToken, error)
	// CreateProjectToken creates a token and returns it with its value, which
	// the platform discloses exactly once (R8).
	//
	// The second return is that value. It goes straight into SetVariable and is
	// never stored anywhere else (FR-050).
	CreateProjectToken(ctx context.Context, req ProjectTokenRequest) (ProjectToken, string, error)
	// RevokeProjectToken revokes one token by id (FR-048).
	RevokeProjectToken(ctx context.Context, id int) error
}

type Transport struct {
	// Base is the round tripper actually performing the request. A nil Base
	// uses http.DefaultTransport.
	Base http.RoundTripper
	// MaxAttempts overrides the default when set, so a test need not wait.
	MaxAttempts int
	// BaseBackoff overrides the default when set.
	BaseBackoff time.Duration
	// Sleep is the pause function, replaced in tests. A nil Sleep uses time.Sleep.
	Sleep func(time.Duration)
}

type VariableState struct {
	Exists bool
	// Masked is GitLab only.
	Masked bool
	// Protected is GitLab only.
	Protected bool
	// Value is GitLab only, and always empty on GitHub, whose Actions
	// credentials are write-only.
	Value string
	// ValueReadable is false wherever the platform cannot disclose a value.
	//
	// It is an explicit field rather than an inference from the platform, so
	// the comparison in internal/compliance reads as a fact about the value
	// rather than a special case about one platform (FR-027).
	ValueReadable bool
}

type VariableWrite struct {
	Name  string
	Value string

	// Secret selects the Actions credential store over the Actions variable
	// store on GitHub. It has no effect on GitLab, where every variable is a
	// CI variable (FR-026).
	Secret bool
	// Masked and Protected are GitLab attributes with no GitHub equivalent.
	Masked    bool
	Protected bool
}

type Writer interface {
	// SetDefaultBranch makes name the platform default (FR-037, FR-038).
	SetDefaultBranch(ctx context.Context, name string) error
	// SetProtection puts the wanted protection in force on a branch (FR-037).
	SetProtection(ctx context.Context, branch string, want Protection) error
	// ProtectTag protects one tag pattern (FR-025).
	ProtectTag(ctx context.Context, pattern string) error
	// SetVariable creates or updates a CI variable (FR-042).
	//
	// This is the only method that receives a value. It writes it to the
	// platform and nowhere else: the value is never logged, never wrapped into
	// an error, and never returned (FR-050, FR-054).
	SetVariable(ctx context.Context, write VariableWrite) error
}