// Package repos owns shared service-level lifecycle contracts and helpers for resource-backed AGS repositories. It is distinct from internal/store/resource/repos persistence, domain resource services, source-control repository models, and API DTOs.
package repos

import "context"

// RepositoryIdentity identifies an AGS repository used by a MeshX resource.
type RepositoryIdentity struct {
	Owner         string
	Name          string
	FullName      string
	ID            string
	DefaultBranch string
	Archived      bool
}

// RepositorySnapshotResolver is the narrow source-control snapshot lookup port used by resource services.
type RepositorySnapshotResolver interface {
	ResolveRepositorySnapshot(context.Context, RepositoryIdentity) (string, error)
}

// RepositoryExistenceChecker is the narrow AGS existence port for a lifecycle RepositoryIdentity.
type RepositoryExistenceChecker interface {
	RepositoryExists(context.Context, RepositoryIdentity) (bool, error)
}

// ResourceRepositoryActor identifies the AgentTeam user that should receive access
// to an AGS repository created on their behalf.
type ResourceRepositoryActor struct {
	Provider string
	Subject  string
	Login    string
	Name     string
	Email    string
	Groups   []string
}

// ResourceRepositoryCollaboratorGrant requests direct collaborator access to a
// specific AGS resource repository.
type ResourceRepositoryCollaboratorGrant struct {
	Repository RepositoryIdentity
	Actor      ResourceRepositoryActor
	Permission string
	// AllowExistingDirectUpdate is set only when MeshX already owns a
	// materialized direct collaborator row for this repository/actor.
	AllowExistingDirectUpdate bool
}

// ResourceRepositoryCollaboratorGrantResult reports whether the grantor had
// to create or update direct AGS collaborator state owned by MeshX.
type ResourceRepositoryCollaboratorGrantResult struct {
	Materialized bool
}

// ResourceRepositoryGrantor applies resource-repository access after provisioning.
type ResourceRepositoryGrantor interface {
	GrantRepositoryCollaborator(context.Context, ResourceRepositoryCollaboratorGrant) (ResourceRepositoryCollaboratorGrantResult, error)
}

// ResourceRepositoryCollaboratorRevoke requests removal of a direct
// collaborator grant from a specific AGS resource repository.
type ResourceRepositoryCollaboratorRevoke struct {
	Repository RepositoryIdentity
	Actor      ResourceRepositoryActor
}

// ResourceRepositoryRevoker removes resource-repository access after MeshX has
// determined no remaining MeshX-owned intent needs that collaborator.
type ResourceRepositoryRevoker interface {
	RevokeRepositoryCollaborator(context.Context, ResourceRepositoryCollaboratorRevoke) error
}

// RepositoryDeleter is the narrow AGS deletion port used after resource-owned intent has been removed.
type RepositoryDeleter interface {
	DeleteRepository(context.Context, RepositoryIdentity) error
}

// AGSRepositoryFeatures selects AGS repository capabilities during lifecycle provisioning; it is not a persisted feature model or API DTO.
type AGSRepositoryFeatures struct {
	Issues      bool
	Wiki        bool
	Projects    bool
	Downloads   bool
	Discussions bool
}

// AGSRepositoryEnsureRequest is the service-level provisioning contract for one resource-backed AGS repository, not a store row or public request DTO.
type AGSRepositoryEnsureRequest struct {
	WorkspaceID       string
	ResourceType      string
	ResourceID        string
	RepoRole          string
	Owner             string
	Name              string
	Description       string
	Kind              string
	SourceType        string
	Visibility        string
	UserVisible       bool
	AutoInit          bool
	RejectExisting    bool
	NameConflictField string
	SuggestedRepoName string
	DefaultBranch     string
	Features          AGSRepositoryFeatures
	Actor             ResourceRepositoryActor
}

// RepositoryEnsurer is the narrow AGS provisioning port consumed by resource domain services.
type RepositoryEnsurer interface {
	EnsureRepository(context.Context, AGSRepositoryEnsureRequest) (RepositoryIdentity, error)
}