port

type AccessTokenSpec struct {
	Name   string
	Scopes []string
	// ExpiresInDays 가 0 이면 구현체 기본값을 쓴다.
	ExpiresInDays int
}

type BuildDelegate interface {
	// DelegateBuild 는 러너의 실행을 시작시키고 그 실행의 주소를 돌려준다.
	DelegateBuild(ctx context.Context, opts DelegateBuildOpts) (runURL string, err error)
}

type CDApplicationDeleter interface {
	// DeleteApplication 은 애플리케이션이 이미 없으면 성공으로 본다 —
	// 삭제의 목표는 "없는 상태" 이고, 없음을 오류로 올리면 재시도가 끝나지 않는다.
	DeleteApplication(ctx context.Context, kubeconfig []byte, namespace, name string) error
}

type CIBuild struct {
	Number int
	// Result 는 CI 가 보고한 결과다(SUCCESS/FAILURE/ABORTED). 실행 중이면 빈 값이다.
	Result   string
	Building bool
	// StartedAt 은 빌드 시작 시각, Duration 은 실행 시간이다.
	// 실행 중인 빌드의 Duration 은 0 이다.
	StartedAt time.Time
	Duration  time.Duration
	// Stages 는 실행 안의 단계다. CI 가 단계 정보를 주지 않으면 비어 있다 —
	// 비어 있는 것과 "모두 성공" 은 다르다.
	Stages []CIStage
}

type CIBuildReader interface {
	ListBuilds(ctx context.Context, jobName, branch string, limit int) ([]CIBuild, error)
}

type CIBuildTrigger interface {
	TriggerBuild(ctx context.Context, jobName, branch string) error
}

type CICDGoldenPathRepository interface {
	GetByID(ctx context.Context, id string) (*domain.CICDGoldenPath, error)
	List(ctx context.Context) ([]*domain.CICDGoldenPath, error)
	Create(ctx context.Context, goldenPath *domain.CICDGoldenPath) error
	Update(ctx context.Context, goldenPath *domain.CICDGoldenPath) error
	Delete(ctx context.Context, id string) error
}

type CICredentialResolver interface {
	ResolveCICredential(ctx context.Context, spec SCMTokenSpec) (user, secret string, err error)
}

type CIJob struct {
	Name string
	URL  string
}

type CIJobProvisioner interface {
	// EnsureJob 은 job 을 만들거나 이미 있으면 그대로 둔다(멱등).
	EnsureJob(ctx context.Context, spec CIJobSpec) (*CIJob, error)
	// DeleteJob 은 job 을 지운다. 이미 없으면 성공으로 본다.
	DeleteJob(ctx context.Context, name string) error
}

type CIJobSpec struct {
	// Name 은 job 이름이다. 앱 이름과 같게 두어 화면에서 짝을 찾기 쉽게 한다.
	Name string
	// RepoCloneURL 은 CI 가 스캔할 저장소 주소다.
	RepoCloneURL string
	// RepoOwner / RepoName 은 organization 소스가 요구하는 분해된 형태다.
	RepoOwner string
	RepoName  string
	// ServerURL 은 SCM 서버의 루트 주소다. Gitea 소스는 리포 주소가 아니라
	// 서버 주소를 받아 API 로 브랜치를 훑는다.
	ServerURL string
	// CredentialID 는 CI 서버에 등록된 SCM 자격증명 식별자다.
	// 비어 있으면 익명으로 스캔한다 — private 리포에서는 실패한다.
	CredentialID string
	// PipelinePath 는 파이프라인 정의 파일의 리포 내 경로다.
	PipelinePath string
}

type CIPlatform string

type CIStage struct {
	Name      string
	Status    CIStageStatus
	StartedAt time.Time
	Duration  time.Duration
}

type CIStageStatus string

type ClusterTarget struct {
	Kubeconfig  []byte
	ClusterName string
}

type ClusterTargetProvider interface {
	GetTarget(ctx context.Context, clusterID string) (*ClusterTarget, error)
}

type CommitFile struct {
	Path    string
	Content string
}

type CommitSpec struct {
	Branch  string
	Message string
	Files   []CommitFile
}

type DelegateBuildOpts struct {
	StackID string
	// JobName 은 CI 서버의 job 이름이다. 프로비저닝이 앱 이름으로 만든다.
	JobName string
	// Branch 는 실행할 브랜치다. multibranch job 은 브랜치가 하위 job 이라
	// 이것이 없으면 무엇을 실행할지 정해지지 않는다.
	Branch string
	// DeploymentID 는 진행 상황을 기록할 배포 기록이다.
	DeploymentID string
	// StepIndex 는 이 작업이 기록될 단계 번호다.
	StepIndex int
}

type DeploymentRepository interface {
	Create(ctx context.Context, deployment *domain.Deployment) error
	GetByID(ctx context.Context, id string) (*domain.Deployment, error)
	ListByPipelineID(ctx context.Context, pipelineID string) ([]*domain.Deployment, error)
	Update(ctx context.Context, deployment *domain.Deployment) error
}

type GroupSpec struct {
	Name        string
	Path        string
	Description string
}

type ImagePreparer interface {
	PrepareImage(ctx context.Context, opts PrepareImageOpts) (imageRef string, err error)
}

type ImageRegistryResolver interface {
	Resolve(ctx context.Context, spec ImageTargetSpec) (*ImageTarget, error)
}

type ImageRepositoryDeleter interface {
	DeleteImageRepository(ctx context.Context, target *ImageTarget) error
}

type ImageTarget struct {
	Kind RegistryKind
	// Host 는 레지스트리 호스트다 (예: "registry.nullus.local").
	Host string
	// Repository 는 태그를 뺀 완전한 이미지 경로다
	// (예: "registry.nullus.local/acme/myapp").
	Repository string
	// UsernameVar / PasswordVar 는 CI 가 로그인에 쓸 변수 이름이다.
	// GitLab 프로젝트 레지스트리는 내장 변수를, 외부 레지스트리는
	// 파이프라인에 등록된 변수를 가리킨다.
	UsernameVar string
	PasswordVar string
	// RequiredVariables 는 파이프라인에 미리 등록돼야 하는 변수들이다.
	// 내장 변수만 쓰는 구성에서는 비어 있다.
	RequiredVariables []string
}

type ImageTargetSpec struct {
	// AppName 은 애플리케이션 이름이다.
	AppName string
	// SCMProjectPath 는 앱의 SCM 프로젝트 전체 경로다 (예: "acme/myapp").
	// SCM 프로젝트 레지스트리를 쓰는 구성에서만 의미가 있다.
	SCMProjectPath string
	// SCMRegistryURL 은 SCM 이 알려준 프로젝트 레지스트리 경로다.
	SCMRegistryURL string
	// OrgPath 는 조직 그룹 경로다. Harbor 프로젝트 이름 등에 쓴다.
	OrgPath string
}

type KubeconfigProvider interface {
	GetKubeconfig(ctx context.Context, clusterID string) ([]byte, error)
}

type ManifestApplier interface {
	Apply(ctx context.Context, kubeconfig []byte, manifests []string) error
	ApplyWithTracking(ctx context.Context, kubeconfig []byte, manifests []string, deploymentID string, stepOffset ...int) error
}

type OrgMemberProvisioner interface {
	// EnsureOrgMember 는 이메일로 찾은 사용자를 조직에 넣는다(멱등).
	EnsureOrgMember(ctx context.Context, org, email string) error
}

type PipelineConfigurator interface {
	// SetProjectVariable 은 변수를 등록하거나 이미 있으면 갱신한다.
	SetProjectVariable(ctx context.Context, projectID string, v ProjectVariable) error
	// CreateProjectAccessToken 은 프로젝트 범위 토큰을 발급한다.
	// 값은 발급 시점에만 읽을 수 있다.
	CreateProjectAccessToken(ctx context.Context, projectID string, spec AccessTokenSpec) (string, error)
}

type PipelineCredentialPlane interface {
	Provision(ctx context.Context, app string, vars []PipelineVariable) (manifest string, err error)
}

type PipelineRepository interface {
	Create(ctx context.Context, pipeline *domain.Pipeline) error
	GetByID(ctx context.Context, id string) (*domain.Pipeline, error)
	List(ctx context.Context, orgID string) ([]*domain.Pipeline, error)
	ListByStackID(ctx context.Context, stackID string) ([]*domain.Pipeline, error)
	Update(ctx context.Context, pipeline *domain.Pipeline) error
	Delete(ctx context.Context, id string) error
}

type PipelineTemplateRepository interface {
	GetByID(ctx context.Context, id string) (*domain.PipelineTemplate, error)
	List(ctx context.Context) ([]*domain.PipelineTemplate, error)
	Create(ctx context.Context, tmpl *domain.PipelineTemplate) error
	Update(ctx context.Context, tmpl *domain.PipelineTemplate) error
	Delete(ctx context.Context, id string) error
}

type PipelineVariable struct {
	Key   string
	Value string
}

type PrepareImageOpts struct {
	GitRepoURL       string
	DockerfilePath   string
	DockerContext    string
	ImageName        string
	ClusterName      string
	DeploymentID     string
	RegistryURL      string
	RegistryUsername string
	RegistryPassword string
}

type ProjectSpec struct {
	Name string
	Path string
	// GroupID 는 생성 시 네임스페이스 지정에 쓴다(숫자 ID).
	GroupID string
	// GroupPath 는 조회 시 경로 조합에 쓴다("{GroupPath}/{Path}").
	// 비면 개인 네임스페이스로 간주해 Path 만으로 조회한다.
	GroupPath   string
	Description string
	// Visibility 는 private | internal | public. 비면 private.
	Visibility string
	// InitReadme 가 true 면 기본 브랜치가 즉시 생성된다.
	// 브랜치가 없으면 파일 커밋이 실패하므로 첫 커밋 전에는 켜야 한다.
	InitReadme bool
}

type ProjectVariable struct {
	Key   string
	Value string
	// Masked 는 job 로그에서 값을 가린다. 자격증명에는 반드시 켠다.
	Masked bool
	// Protected 를 켜면 보호 브랜치에서만 노출된다.
	Protected bool
}

type RegistryCredentialResolver interface {
	Resolve(ctx context.Context, variables []string) (map[string]string, error)
}

type RegistryKind string

type SCMBundle struct {
	Provisioner SCMProvisioner
	Pipeline    PipelineConfigurator
	Registry    ImageRegistryResolver
	// Images 는 이미지 저장소를 지울 수단이다. 지원하지 않는 레지스트리에서는
	// nil 이며, 호출부는 이를 ErrImageDeletionUnsupported 와 같게 다뤄야 한다
	// — 조용히 건너뛰면 사용자는 이미지가 지워진 줄 안다.
	Images ImageRepositoryDeleter

	// CIJobs 는 CI 서버에 job 을 만드는 수단이다.
	//
	// GitLab CI·GitHub Actions 는 파이프라인 정의를 푸시하면 자동 감지하므로
	// nil 이다. Jenkins 는 job 이 먼저 존재해야 하므로 이 자리가 채워진다.
	// 호출부는 nil 이면 건너뛴다 — 기존 경로 무영향.
	CIJobs CIJobProvisioner
	// Webhooks 는 저장소에 push webhook 을 거는 수단이다.
	// Jenkins multibranch 가 새 커밋을 알려면 필요하다. 지원하지 않으면 nil.
	Webhooks SCMWebhookProvisioner
	// CITrigger 는 CI 서버의 job 을 지금 실행시킨다. 지원하지 않으면 nil.
	//
	// 스택에 묶인 파이프라인의 "배포 실행" 이 이 자리로 온다 — 플랫폼이
	// 빌드하지 않고 러너에게 넘긴다.
	CITrigger CIBuildTrigger
	// CIBuilds 는 CI 서버의 빌드 이력을 읽는다. 지원하지 않으면 nil.
	CIBuilds CIBuildReader
	// CIBaseURL 은 CI 서버의 주소다. webhook 대상 주소를 만드는 데 쓴다.
	CIBaseURL string
	// SCMInClusterURL 은 클러스터 안에서 SCM 에 닿는 주소다.
	//
	// Provisioner 의 base URL 과 구분한다 — 그쪽은 API 서버가 쓰는 주소라
	// 로컬 실행에서 우회 주소(localhost 포트포워드 등)일 수 있다. 반면 이 값은
	// Jenkins·Argo CD 처럼 클러스터 안에서 도는 소비자가 쓰므로 항상 서비스
	// DNS 여야 한다. 둘을 같은 값으로 두면 job 이
	// "Unknown server: http://localhost:3000" 으로 죽는다.
	SCMInClusterURL string
	// Credentials 는 CI 변수 저장소가 없는 SCM(Gitea)에서 파이프라인 자격증명을
	// OpenBao → ESO → K8s Secret 평면으로 나른다. 지원하지 않으면 nil.
	Credentials PipelineCredentialPlane

	// CDApplications 는 CD 도구가 배포한 애플리케이션을 지우는 수단이다.
	// 지원하지 않는 도구에서는 nil 이며, 호출부는 그것을 밝히고 넘어간다.
	CDApplications CDApplicationDeleter

	// OrgMembers 는 사람을 조직에 넣는 수단이다. 지원하지 않으면 nil.
	//
	// 플랫폼이 만든 저장소는 자동화 계정 소유의 private 조직 안에 있어서,
	// 그대로 두면 정작 소스를 밀어야 할 사람이 보지도 못한다.
	OrgMembers OrgMemberProvisioner

	// RegistryCredentials 는 스택이 설치한 레지스트리(Harbor·Nexus)의 자격증명을
	// 푼다. 그 값은 스택 설치가 OpenBao 에 만들어 두므로 사용자에게 다시 받을
	// 이유가 없다. 플랫폼이 소유하지 않는 레지스트리에서는 아무것도 돌려주지 않는다.
	RegistryCredentials RegistryCredentialResolver

	// Platform 은 이 묶음이 향하는 SCM 플랫폼이다.
	// 파이프라인 파일 형식이 여기서 갈리므로 렌더러까지 전달돼야 한다.
	Platform SCMPlatform
	// RepoAccessToken 은 플랫폼이 리포 범위 토큰 발급을 지원하지 않을 때
	// Argo CD·이미지 pull 인증에 재사용할 토큰이다.
	//
	// GitLab 에서는 비어 있다 — 프로젝트마다 최소 권한 토큰을 따로 발급한다.
	// GitHub 에는 리포 단위 토큰 API 가 없어 조직 PAT 를 그대로 쓴다.
	RepoAccessToken string

	// GroupPath 는 프로젝트가 만들어질 네임스페이스다.
	// GitLab 은 그룹 경로, GitHub 은 organization/사용자 이름이다.
	GroupPath string
	// CDNamespace 는 CD 도구가 설치된 네임스페이스다.
	//
	// 애플리케이션 리소스는 **여기**에 산다. 배포 대상 네임스페이스(앱이 서는
	// 곳)와 다르다 — 둘을 혼동하면 삭제가 없는 곳을 뒤지고 성공으로 끝난다.
	CDNamespace string
	// ClusterID 는 Application 을 적용할 클러스터다.
	ClusterID string
	// AccessDomain / GatewayName 은 배포된 앱을 외부에 노출할 때 쓴다.
	// 비어 있으면 앱은 클러스터 내부에서만 접근 가능하다.
	AccessDomain string
	GatewayName  string
}

type SCMBundleFactory interface {
	For(ctx context.Context, stackID string) (*SCMBundle, error)
}

type SCMConnection struct {
	Platform SCMPlatform
	// Owner 는 리포지토리가 만들어질 GitHub Organization 또는 사용자 계정이다.
	Owner string
	// APIBaseURL 은 GitHub Enterprise Server 의 API 주소다.
	// 비면 어댑터가 github.com 을 쓴다.
	APIBaseURL string
}

type SCMConnectionReader interface {
	// GetConnection 은 설정을 읽는다. 등록된 것이 없으면 nil, nil 을 돌려준다.
	GetConnection(ctx context.Context, orgID string, platform SCMPlatform) (*SCMConnection, error)
}

type SCMGroup struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	FullPath string `json:"full_path"`
	WebURL   string `json:"web_url"`
}

type SCMPlatform string

type SCMProject struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	FullPath      string `json:"full_path"`
	WebURL        string `json:"web_url"`
	HTTPCloneURL  string `json:"http_clone_url"`
	RegistryURL   string `json:"registry_url"`
	DefaultBranch string `json:"default_branch"`
	// Created 는 이번 호출이 저장소를 새로 만들었는지다.
	//
	// 스캐폴딩을 덮어쓸지 판단하는 데 쓴다. CommitFiles 는 upsert 라 이미 쓰이던
	// 저장소에 다시 커밋하면 CI 가 갱신해 둔 이미지 태그가 초기값으로 되돌아가고,
	// 사용자가 고친 Dockerfile·워크플로·매니페스트도 함께 사라진다.
	Created bool `json:"created"`
}

type SCMProvisioner interface {
	EnsureGroup(ctx context.Context, spec GroupSpec) (*SCMGroup, error)
	EnsureProject(ctx context.Context, spec ProjectSpec) (*SCMProject, error)
	// CommitFiles 는 파일이 이미 있으면 갱신한다(upsert).
	CommitFiles(ctx context.Context, projectID string, spec CommitSpec) error
	// DeleteProject 는 저장소를 지운다. 이미 없으면 성공으로 본다.
	//
	// 되돌릴 수 없다. 사용자가 명시적으로 요청했을 때만 호출해야 하며,
	// 파이프라인 삭제의 기본 동작이어서는 안 된다 — 소스 코드는 사용자 자산이다.
	DeleteProject(ctx context.Context, projectID string) error
}

type SCMTokenIssuer interface {
	EnsureToken(ctx context.Context, spec SCMTokenSpec) (string, error)
}

type SCMTokenSpec struct {
	// StackID 는 시크릿 저장소를 고르는 키다.
	//
	// OpenBao 는 스택마다 배포되므로 전역 주소가 하나일 수 없다.
	// 스택 범위로 접근해야 해당 스택의 OpenBao 에 저장된다.
	StackID string
	// ClusterID 는 kubeconfig 를 찾는 키다.
	ClusterID string
	// Namespace 는 SCM(GitLab)이 설치된 네임스페이스다.
	Namespace string
	// OrgID / Env 는 시크릿 저장 경로를 구성한다.
	OrgID string
	Env   string
	// Force 가 true 면 저장된 토큰을 무시하고 새로 발급한다.
	// 토큰이 만료되거나 폐기돼 401 을 받은 호출자가 쓴다.
	Force bool
}

type SCMWebhookProvisioner interface {
	EnsureWebhook(ctx context.Context, projectID, targetURL, secret string) error
}

type StackReader interface {
	// GetStackSummary retrieves minimal stack information by ID.
	// Returns nil and no error if the stack does not exist.
	GetStackSummary(ctx context.Context, stackID string) (*StackSummary, error)
}

type StackSummary struct {
	ID        string `json:"id"`
	OrgID     string `json:"org_id"`
	ClusterID string `json:"cluster_id"`
	State     string `json:"state"` // "completed", "failed", etc.

	// Name 은 스택 이름이다. 스택이 만든 게이트웨이 이름이 여기서 나온다
	// (`<이름>-gateway`). 도메인에서 유추하면 존재하지 않는 이름이 만들어진다.
	Name string `json:"name"`

	// Namespace 는 스택이 설치된 네임스페이스다. GitLab/Argo CD 의 클러스터 내
	// 주소를 만들 때 쓴다.
	Namespace string `json:"namespace"`
	// SourceRepository / ContainerRegistry 는 스택이 고른 도구 이름이다
	// (예: "GitLab CE", "GitLab Registry", "Harbor").
	// 이미지 저장 위치를 결정하는 근거가 된다.
	SourceRepository  string `json:"source_repository"`
	ContainerRegistry string `json:"container_registry"`
	// AccessDomain 은 스택의 외부 접근 도메인이다. 비어 있을 수 있다.
	AccessDomain string `json:"access_domain"`
	// OTLPEndpoint 는 스택 OpenTelemetry Collector 의 클러스터 내 주소다
	// (host:port). 수집기를 고르지 않은 스택에서는 비어 있다.
	//
	// 배포되는 앱에 넣어 줄 값이라 CI/CD 가 알아야 하는데, 릴리스명·차트명으로
	// 주소를 조립하는 규칙은 Stack 컨텍스트의 것이다. 그래서 조립된 결과만
	// 받아 온다 — 여기서 규칙을 흉내 내면 차트가 바뀔 때 조용히 어긋난다.
	OTLPEndpoint string `json:"otlp_endpoint"`
}

type WorkloadDeleter interface {
	DeleteByLabel(ctx context.Context, kubeconfig []byte, namespace, selector string) error
}