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 CDApplicationRefresher interface {
	EnsureFirstComparison(ctx context.Context, kubeconfig []byte, namespace, name string) error
}

type CIArtifactLinker interface {
	ArtifactWebURL(ref CIArtifactRef) string
}

type CIArtifactReader interface {
	// ReadArtifact 는 파일 내용을 돌려준다. 없으면 found=false 이고 오류가 아니다 —
	// 리포트가 없는 실행(스캐너에 닿지 못함, 보존 기간 만료)은 정상 경로다.
	ReadArtifact(ctx context.Context, ref CIArtifactRef) (data []byte, found bool, err error)
}

type CIArtifactRef struct {
	JobName string
	Branch  string
	Build   CIBuild
	Stage   CIStage
	// Name 은 산출물 묶음 이름, Path 는 그 안의 파일 경로다.
	Name string
	Path string
}

type CIBuild struct {
	// Number 는 화면에 보이는 실행 번호다(Jenkins 빌드 번호, GitLab iid, GitHub run_number).
	Number int
	// ID 는 CI API 가 실행을 가리키는 식별자다(GitLab pipeline id, GitHub run id).
	// 번호와 다를 수 있고, 산출물 조회는 이것으로 한다.
	ID string
	// Result 는 CI 가 보고한 결과다(SUCCESS/FAILURE/ABORTED/SKIPPED). 실행 중이면 빈 값이다.
	// SKIPPED(Jenkins 는 NOT_BUILT)는 실행이 아니다 — 아무 잡도 돌지 않은 빈 파이프라인이라
	// 동기화가 실행 기록으로 남기지 않는다.
	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) (runURL string, err 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 {
	// ID 는 CI 가 단계(잡)에 붙인 식별자다. 산출물을 잡 단위로 주는 CI(GitLab)에서
	// 리포트를 받을 때 쓴다. 단계에 따로 식별자가 없는 CI 는 비워 둔다.
	ID        string
	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
	// Executable 은 실행 권한이 있는 파일인지다(원본의 mvnw · entrypoint.sh 등). 잃으면 원본
	// Dockerfile 이 permission denied 로 죽는다. Gitea 의 contents API 는 파일 모드를 받지 않는다.
	Executable bool
}

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 DependencyScanResultRepository interface {
	// Upsert 는 같은 ID 면 덮어쓴다. 같은 실행을 여러 번 동기화해도 기록이 늘지 않아야 한다.
	Upsert(ctx context.Context, result *domain.DependencyScanResult) error
	// ListByPipelineID 는 최신 결과부터 돌려준다.
	ListByPipelineID(ctx context.Context, pipelineID string) ([]*domain.DependencyScanResult, error)
	// Delete 는 기록을 지운다. 없으면 오류가 아니다 — 동기화가 취소된 실행마다 부른다.
	Delete(ctx context.Context, id string) error
}

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
	// Delete 는 기록 하나를 지운다. 없으면 오류가 아니다. 동기화가 실행이 아닌 것(SKIPPED 파이프라인)을
	// 예전에 실패로 남긴 기록을 거둘 때 쓴다.
	Delete(ctx context.Context, id string) error
}

type GatewayLocator interface {
	// LocateGateway 는 namespace 의 게이트웨이 가운데 앱이 붙을 것을 고른다. preferred 가 있으면 그것을,
	// 없으면 하나뿐인 것(또는 Nullus 가 만든 것 하나)을 돌려준다. 고를 수 없으면 빈 문자열이다.
	LocateGateway(ctx context.Context, kubeconfig []byte, namespace, preferred string) (string, 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 ImageScanResultRepository interface {
	// Upsert 는 같은 ID 면 덮어쓴다. 같은 실행을 여러 번 동기화해도 기록이
	// 늘지 않아야 한다.
	Upsert(ctx context.Context, result *domain.ImageScanResult) error
	// ListByPipelineID 는 최신 결과부터 돌려준다.
	ListByPipelineID(ctx context.Context, pipelineID string) ([]*domain.ImageScanResult, error)
	// GetByID 는 결과 하나다. 없으면 nil, nil 이다.
	GetByID(ctx context.Context, id string) (*domain.ImageScanResult, error)
	// Delete 는 기록을 지운다. 없으면 오류가 아니다 — 동기화가 반복해서 부른다.
	Delete(ctx context.Context, id string) 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 ManagedSecretDeleter interface {
	DeleteManagedSecret(ctx context.Context, kubeconfig []byte, namespace, name string) 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 PipelineCredentialObject struct {
	Namespace       string
	Name            string
	RemoteKeyPrefix string
}

type PipelineCredentialObjectDeleter interface {
	DeleteCredentialObject(ctx context.Context, kubeconfig []byte, obj PipelineCredentialObject) error
}

type PipelineCredentialPlane interface {
	Provision(ctx context.Context, app string, vars []PipelineVariable) (manifest string, err error)
	// CredentialObject 는 Provision 이 만든 클러스터 객체의 자리다. 파이프라인을 지울 때
	// 클러스터에서 그것을 찾아 지운다. 이름이 경로로 쓸 수 없으면 오류다.
	CredentialObject(app string) (PipelineCredentialObject, error)
	// Revoke 는 Provision 이 금고에 쓴 값을 지운다. 이미 없으면 성공이다.
	Revoke(ctx context.Context, app string) error
}

type PipelineNameLookup interface {
	OtherPipelinesNamed(ctx context.Context, stackID, name, excludeID string) ([]string, 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 PipelineSecurityReader interface {
	// ListPipelineSecurity 는 조직의 파이프라인을 최근 만든 것부터 최대 limit 개 돌려준다. 결과가 없는
	// 칸은 nil 이다. RunVersions 는 채우지 않는다(실행 ID 규칙은 동기화 유스케이스가 안다).
	ListPipelineSecurity(ctx context.Context, orgID string, limit int) ([]*domain.PipelineSecuritySnapshot, 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 PipelineVariableWriter interface {
	SetPipelineVariable(ctx context.Context, projectID, key, value string) error
}

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 RepositoryLocation struct {
	Platform SCMPlatform `json:"platform"`
	// GroupPath 는 저장소가 들어갈 그룹(GitLab · Gitea) 또는 조직(GitHub)이다.
	GroupPath string `json:"group_path"`
	// WebBaseURL 은 브라우저가 여는 SCM 주소다. 접근 도메인이 없어 모르면 비어 있다.
	WebBaseURL string `json:"web_base_url"`
}

type RepositoryLocator interface {
	RepositoryLocation(ctx context.Context, stackID string) (*RepositoryLocation, error)
}

type SASTResultRepository interface {
	// Upsert 는 같은 ID 면 덮어쓴다. 같은 실행을 여러 번 동기화해도 기록이 늘지 않아야 한다.
	Upsert(ctx context.Context, result *domain.SASTResult) error
	// ListByPipelineID 는 최신 결과부터 돌려준다.
	ListByPipelineID(ctx context.Context, pipelineID string) ([]*domain.SASTResult, error)
}

type SASTTokenResolver interface {
	AnalysisToken(ctx context.Context) (string, error)
}

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
	// CIArtifacts 는 실행이 남긴 산출물(스캔 리포트)을 읽는다. 지원하지 않으면 nil —
	// 스캔 판정은 단계 결과만으로 남고 건수는 비어 있다.
	CIArtifacts CIArtifactReader
	// ScanPolicy 는 스캔 정책을 파이프라인이 읽는 자리에 싣는다. 정책을 실을
	// 경로가 배선되지 않은 스택에서는 nil 이다.
	ScanPolicy ScanPolicyPublisher
	// 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
	// CDRefresher 는 방금 만든 애플리케이션의 첫 비교를 확인한다. 지원하지 않으면 nil.
	CDRefresher CDApplicationRefresher
	// CDWebhooks / CDWebhookURL 은 저장소가 새 커밋을 CD 도구에 바로 알리게 하는
	// 수단과 주소다. 비어 있으면 CD 도구는 정기 확인(Argo CD 기본 3분)으로만 새
	// 커밋을 안다 — CI 가 배포 태그를 되커밋해도 그만큼 늦게 배포된다.
	CDWebhooks   SCMWebhookProvisioner
	CDWebhookURL string

	// 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
	// ImageScannerEndpoint 는 스택 Trivy 서버의 클러스터 내 주소다.
	// 스캐너를 고르지 않은 스택에서는 비어 있고, 그때는 스캐폴딩이
	// 이미지 스캔 단계를 만들지 않는다.
	ImageScannerEndpoint string
	// ImageScannerJavaDBRepository 는 에어갭 설치에서 CI 잡의 trivy client 가 Java DB 를
	// 받을 내부 미러다. 클러스터 안 CI(GitLab 러너·Jenkins 에이전트) 번들에만 싣는다.
	ImageScannerJavaDBRepository string
	// DependencyScanEndpoint 는 의존성 스캔(SCA)이 붙을 스택 Trivy 서버 주소다. 비면 단계를 만들지 않는다.
	DependencyScanEndpoint string
	// SASTServerEndpoint 는 스택 SonarQube 의 클러스터 내 주소다. SonarQube 를 고르지 않은
	// 스택에서는 비어 있고, 그때는 스캐폴딩이 소스 정적 분석 단계를 만들지 않는다.
	SASTServerEndpoint string
	// SASTWebURL 은 사람이 여는 SonarQube 주소다(https://sonarqube.<접근 도메인>). 분석 결과의
	// 링크를 만든다. SonarQube 가 없거나 접근 도메인이 없으면 비어 있다.
	SASTWebURL string
	// SASTToken 은 CI 가 분석에 쓸 토큰을 푼다. 스택 설치가 OpenBao 에 둔 값이다.
	// SonarQube 가 없거나 시크릿 백엔드가 배선되지 않았으면 nil 이다.
	SASTToken   SASTTokenResolver
	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 ScanPolicyPublisher interface {
	PublishScanPolicy(ctx context.Context, apps []string, vars []ProjectVariable) map[string]error
}

type ScanPolicyRepository interface {
	// Get 은 저장된 정책이다. 저장한 적 없으면 found=false 다 — 기본값을 지어
	// 돌려주면 호출부가 운영자가 고른 값인지 구분할 수 없다.
	Get(ctx context.Context, stackID string) (policy domain.ScanPolicy, found bool, err error)
	// Upsert 는 스택의 정책을 저장하거나 덮어쓴다.
	Upsert(ctx context.Context, stackID string, policy domain.ScanPolicy, updatedBy string) error
}

type ScanSource string

type SecretScanResultRepository interface {
	// Upsert 는 같은 ID 면 덮어쓴다.
	Upsert(ctx context.Context, result *domain.SecretScanResult) error
	// ListByPipelineID 는 최신 결과부터 돌려준다.
	ListByPipelineID(ctx context.Context, pipelineID string) ([]*domain.SecretScanResult, error)
	// Delete 는 기록을 지운다. 없으면 오류가 아니다.
	Delete(ctx context.Context, id string) error
}

type SourceArchive interface {
	// Fetch 는 repoURL 저장소의 commit 시점 파일을 돌려준다. 경로는 저장소 루트 기준이다.
	Fetch(ctx context.Context, repoURL, commit string) ([]CommitFile, error)
	// Supports 는 그 주소를 가져올 수 있는 모양인지 본다(네트워크를 쓰지 않는다). 템플릿을 저장할 때
	// 부른다 — 저장은 되는데 파이프라인을 만들 때마다 실패하는 템플릿이 생기지 않게.
	Supports(repoURL 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"`

	// ImageScannerEndpoint 는 스택 Trivy 서버의 클러스터 내 주소다
	// (http://host:port). 스캐너를 고르지 않은 스택에서는 비어 있다.
	//
	// OTLPEndpoint 와 같은 이유로 조립된 결과만 받는다 — 릴리스명·포트로
	// 주소를 만드는 규칙은 shared 가 소유하고, 여기서 흉내 내면 차트가 바뀔 때
	// 조용히 어긋난다.
	ImageScannerEndpoint string `json:"image_scanner_endpoint"`

	// SASTServerEndpoint 는 스택 SonarQube 의 클러스터 내 주소다(http://host:port).
	// SonarQube 를 고르지 않았거나 외부 SonarQube 를 쓰는 스택에서는 비어 있다.
	SASTServerEndpoint string `json:"sast_server_endpoint"`

	// DependencyScanEndpoint 는 의존성 스캔(SCA)이 붙을 스택 Trivy 서버 주소다(nullus-plan#79).
	// 의존성 스캔을 고르지 않은 스택에서는 비어 있다 — 이미지 스캐너와 같은 서버라 값이 같을 수 있지만,
	// 둘은 따로 고르는 단계라 칸도 따로 둔다.
	DependencyScanEndpoint string `json:"dependency_scan_endpoint"`
}

type SyncablePipelineLister interface {
	ListWithStack(ctx context.Context) ([]*domain.Pipeline, error)
}

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