port

type ChartUpgradeExecutor interface {
	UpgradeChart(ctx context.Context, req ChartUpgradeRequest) (*ChartUpgradeResult, error)
	RollbackRelease(ctx context.Context, releaseName, namespace string, revision int) error
}

type ChartUpgradeRequest struct {
	ReleaseName string
	ChartName   string
	RepoURL     string
	Version     string
	Namespace   string
	Values      map[string]any
	DryRun      bool
}

type ChartUpgradeResult struct {
	Revision int
	Status   string
	Manifest string
}

type ClusterReader interface {
	GetClusterSummary(ctx context.Context, clusterID string) (*ClusterSummary, error)
}

type ClusterSummary struct {
	ID                string   `json:"id"`
	OrgID             string   `json:"org_id"`
	NodeArchitectures []string `json:"node_architectures"`
}

type CompatibilityRepository interface {
	GetAll(ctx context.Context) ([]*domain.CompatibilityMatrix, error)
	GetByID(ctx context.Context, id string) (*domain.CompatibilityMatrix, error)
	Validate(ctx context.Context, tools map[string]string) (*domain.CompatibilityMatrix, error)

	// Create persists a new matrix. Returns ErrCompatibilityMatrixExists
	// when the id collides with an existing row.
	Create(ctx context.Context, m *domain.CompatibilityMatrix) error
	// Update replaces every mutable field on the matrix identified by
	// m.ID. Returns ErrCompatibilityMatrixNotFound when the row is
	// missing; no-op partial-update semantics — callers send the full
	// desired state.
	Update(ctx context.Context, m *domain.CompatibilityMatrix) error
	// Delete removes the matrix. Idempotent — missing row returns nil so
	// the admin UI can re-issue delete on an already-deleted id without
	// error. Handlers map post-facto 404s via GetByID when strict
	// semantics are desired.
	Delete(ctx context.Context, id string) error
}

type CompletedStackLister interface {
	ListCompleted(ctx context.Context) ([]*domain.Stack, error)
}

type GatewayAddressReader interface {
	GatewayClusterIP(ctx context.Context, namespace string) (string, error)
}

type HelmInstallRequest struct {
	ReleaseName string         `json:"release_name"`
	ChartName   string         `json:"chart_name"`
	RepoURL     string         `json:"repo_url"`
	Version     string         `json:"version"`
	Namespace   string         `json:"namespace"`
	Values      map[string]any `json:"values"`
	Wait        *bool          `json:"wait,omitempty"`
}

type HelmInstallResult struct {
	ReleaseName string `json:"release_name"`
	Namespace   string `json:"namespace"`
	Status      string `json:"status"`
	Revision    int    `json:"revision"`
}

type HelmInstaller interface {
	Install(ctx context.Context, req HelmInstallRequest) (*HelmInstallResult, error)
	Uninstall(ctx context.Context, releaseName, namespace string) error
	Status(ctx context.Context, releaseName, namespace string) (*HelmInstallResult, error)
}

type HelmReleaseManager interface {
	ListReleases(ctx context.Context, namespace string) ([]ReleaseInfo, error)
	// GetValues 는 사용자가 지정한 values(= 설치 때 우리가 넘긴 값)를 돌려준다.
	// 차트 기본값까지 합친 전체가 아니라, 실제로 배포에 쓰인 우리 입력이다.
	GetValues(ctx context.Context, releaseName, namespace string) (map[string]any, error)
	Upgrade(ctx context.Context, req HelmUpgradeRequest) (*HelmUpgradeResult, error)
}

type HelmStepMetadataRepository interface {
	Create(ctx context.Context, item *domain.HelmStepMetadata) error
	Update(ctx context.Context, item *domain.HelmStepMetadata) error
	Delete(ctx context.Context, stepName string) error
	GetByStep(ctx context.Context, stepName string) (*domain.HelmStepMetadata, error)
	List(ctx context.Context) ([]*domain.HelmStepMetadata, error)
}

type HelmUpgradeRequest struct {
	ReleaseName string
	Namespace   string
	Values      map[string]any
	// DryRun 이면 클러스터를 건드리지 않고 렌더 결과만 돌려준다.
	DryRun bool
}

type HelmUpgradeResult struct {
	ReleaseName string
	Namespace   string
	Revision    int
	Status      string
	// Manifest 는 렌더된 매니페스트다. 드라이런에서 변경 내용을 보여주는 데 쓴다.
	Manifest string
}

type HistoryRepository interface {
	SaveVersion(ctx context.Context, version *domain.StackVersion) error
	ListVersions(ctx context.Context, stackID string) ([]*domain.StackVersion, error)
	GetVersion(ctx context.Context, stackID, versionID string) (*domain.StackVersion, error)
	GetDiff(ctx context.Context, stackID, versionID string) ([]domain.ConfigDiff, error)
}

type InstalledImageScanner interface {
	// shared 는 스택 네임스페이스 밖에서 함께 스캔할 공용 구성요소다. 읽지 못한 것은 건너뛴다.
	ScanInstalledImages(ctx context.Context, kubeconfig []byte, namespace string, shared []domain.SharedComponent) ([]domain.StackImageScan, error)
}

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

type LogEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Level     string    `json:"level"` // info, warn, error
	Step      string    `json:"step"`  // e.g. "installing_minio", "configuring_argocd"
	Message   string    `json:"message"`
	Phase     string    `json:"phase"` // A, B, C
}

type LogStreamer interface {
	// Stream publishes a log entry for the given deploymentID.
	Stream(ctx context.Context, deploymentID string, entry LogEntry)
	// Subscribe returns a channel that receives log entries for the given deploymentID.
	Subscribe(deploymentID string) <-chan LogEntry
	// Unsubscribe removes the given channel from the subscriber list for deploymentID.
	Unsubscribe(deploymentID string, ch <-chan LogEntry)
	// Tail 은 최근 n 줄을 기록 순서(오름차순)로 돌려준다 — WS 재생과 같은 순서다.
	// 연결을 붙들 수 없는 자동화 클라이언트(CLI·MCP)가 한 번의 요청으로 읽는 경로.
	Tail(ctx context.Context, deploymentID string, n int) ([]LogEntry, error)
}

type ReleaseInfo struct {
	ReleaseName string `json:"release_name"`
	// StepName 은 이 릴리스를 만든 설치 단계다. YAML 오버라이드를 어느 키로
	// 저장할지 결정하므로 비어 있으면 편집 결과가 재배포 때 유실된다.
	StepName     string `json:"step_name,omitempty"`
	ChartName    string `json:"chart_name,omitempty"`
	ChartVersion string `json:"chart_version,omitempty"`
	AppVersion   string `json:"app_version,omitempty"`
	Namespace    string `json:"namespace"`
	Revision     int    `json:"revision"`
	Status       string `json:"status"`
}

type ReleaseVulnerabilityLookup interface {
	VulnerabilityIDsByRelease(ctx context.Context, stackID, release string) (ids map[string]bool, scanned bool, err error)
}

type ResourceDefaultRepository interface {
	List(ctx context.Context) ([]*domain.ResourceDefault, error)
	Upsert(ctx context.Context, resource *domain.ResourceDefault) error
}

type SSOClientSpec struct {
	// StepName 은 대상 도구를 식별한다 (예: installing_grafana).
	StepName string
	// ClientSecret 은 Nullus 가 생성해 OpenBao 에 기록한 값이다.
	ClientSecret string
}

type SSOProvisioner interface {
	// ClientIDFor 는 스택 네임스페이스가 적용된 client ID 를 돌려준다.
	ClientIDFor(stepName string) (string, bool)
	// ToolSteps 는 SSO 대상 스텝 목록이다.
	ToolSteps() []string
	// Provision 은 클라이언트를 등록하거나 갱신한다.
	Provision(ctx context.Context, spec SSOClientSpec) error
	// Deprovision 은 등록했던 클라이언트를 지운다.
	//
	// 스택을 지워도 이걸 부르지 않으면 realm 에 존재하지 않는 도구를 가리키는
	// redirect URI 가 계속 남는다. 구현은 진작 있었는데 이 인터페이스에 없어서
	// stack 모듈이 부를 방법이 없었다.
	Deprovision(ctx context.Context, stepName string) error
	// UsesClientSecret 은 도구가 client secret 으로 IdP 와 통신하는지 알려 준다.
	//
	// SAML 로 로그인하는 도구(SonarQube Community)는 client secret 이 없다. 이걸
	// 모르면 시크릿 평면이 아무도 읽지 않는 값을 만들고, 프로비저닝이 OpenBao 에서
	// 그 값을 찾다가 멈춘다.
	UsesClientSecret(stepName string) bool
	// SAMLSigningCertificate 는 IdP 가 SAML 응답에 서명하는 인증서다(머리말 없는
	// base64 DER). SAML 도구는 디스커버리 문서 대신 이 인증서를 직접 받아 서명을
	// 검증한다.
	SAMLSigningCertificate(ctx context.Context) (string, error)
}

type SSOProvisionerFactory func(accessDomain, stackSlug string) SSOProvisioner

type StackImageScanRepository interface {
	// ReplaceForStack 은 스택의 결과를 이번 스캔으로 통째로 바꾼다 — 더는 돌지 않는
	// 이미지의 결과가 남아 현재 상태처럼 보이지 않게 한다.
	ReplaceForStack(ctx context.Context, stackID string, scans []domain.StackImageScan) error
	ListByStack(ctx context.Context, stackID string) ([]domain.StackImageScan, error)
	// ListVulnerabilities 는 이미지 하나의 저장된 취약점 목록이다.
	ListVulnerabilities(ctx context.Context, stackID, digest string) (domain.StackImageVulnerabilities, error)
	// NotifiedCVEIDs 는 스택에 이미 알린 CVE 다. 새 CVE 고지는 저장된 스캔 결과가 아니라 이것으로
	// 새것을 가린다 — 이미지 하나의 스캔이 실패하면 그 이미지의 취약점 행이 사라진다.
	NotifiedCVEIDs(ctx context.Context, stackID string) (map[string]bool, error)
	// ClaimCVENotices 는 ids 중 아직 남지 않은 것을 알린 것으로 남기고, 이번에 남긴 것만 돌려준다 —
	// API 레플리카 둘이 같은 스캔 결과를 보고도 한 번만 알린다. 이미 남은 것의 시각은 바꾸지 않는다.
	ClaimCVENotices(ctx context.Context, stackID string, ids []string, at time.Time) ([]string, error)
	// ReleaseCVENotices 는 보내지 못한 선점을 되돌린다.
	ReleaseCVENotices(ctx context.Context, stackID string, ids []string) error
}

type StackRepository interface {
	Create(ctx context.Context, stack *domain.Stack) error
	GetByID(ctx context.Context, id string) (*domain.Stack, error)
	FindByID(ctx context.Context, id string) (*domain.Stack, error)
	List(ctx context.Context, orgID string, includeDeleted bool) ([]*domain.Stack, error)
	// ListInFlight 는 설치가 진행 중인 상태로 남아 있는 스택을 조직과 무관하게
	// 돌려준다. 끊긴 설치를 찾아내는 데 쓴다 — 그것은 조직 경계와 무관한 일이다.
	ListInFlight(ctx context.Context) ([]*domain.Stack, error)
	// ListByCluster 는 한 클러스터의 지우지 않은 스택을 조직과 무관하게 돌려준다.
	// 스택 삭제가 그 클러스터의 마지막 스택인지 볼 때 쓴다 — 클러스터 공용 자원은
	// 마지막 스택을 지울 때만 회수한다.
	ListByCluster(ctx context.Context, clusterID string) ([]*domain.Stack, error)
	Update(ctx context.Context, stack *domain.Stack) error
	// TouchUpdatedAt 은 갱신 시각만 찍는다.
	//
	// 설치가 도는 동안 살아 있음을 알리는 데 쓴다. Update 를 쓰지 않는 이유는
	// 그쪽이 메모리에 든 스택 전체를 다시 쓰기 때문이다 — 오래된 사본으로
	// 하트비트를 찍으면 그 사이 다른 경로가 바꾼 값을 되돌린다.
	TouchUpdatedAt(ctx context.Context, stackID string) error
	UpdateTools(ctx context.Context, stack *domain.Stack) error
	Delete(ctx context.Context, id string) error
}

type StepExecutor interface {
	ExecuteStep(ctx context.Context, stackID, step, phase string) error
}

type TemplateRepository interface {
	Create(ctx context.Context, template *domain.Template) error
	Update(ctx context.Context, template *domain.Template) error
	Delete(ctx context.Context, id string) error
	GetByID(ctx context.Context, id string) (*domain.Template, error)
	List(ctx context.Context) ([]*domain.Template, error)
}

type TokenSourceInput struct {
	OrgID         string
	Module        string
	Provider      string
	Path          string
	TokenType     string
	Status        string
	SecretManager string
	TokenValue    string
	// StackID 가 있으면 그 스택의 시크릿 저장소에 기록한다.
	//
	// OpenBao 는 스택마다 배포되므로 전역 저장소에 써 두면 스택 범위로 읽는
	// 쪽(cicd 모듈)이 값을 찾지 못한다. 비면 예전처럼 전역 저장소를 쓴다.
	StackID string
	// Metadata 는 토큰과 함께 보관할 접속 정보다 (예: GitHub organization).
	// 토큰만으로는 어디에 붙어야 할지 알 수 없는 외부 SaaS 에 필요하다.
	Metadata map[string]string
	// ClusterID / Namespace 는 회전 후 반영(rolling restart) 대상을 찾는 데 쓴다.
	ClusterID string
	Namespace string
}

type TokenSourceRegistry interface {
	Upsert(ctx context.Context, input TokenSourceInput) error
}

type UpgradeBackupLookup interface {
	LatestRestorableBackup(ctx context.Context, stackID string) (finishedAt time.Time, found bool, err error)
}

type UpgradeBundleStore interface {
	ListBundles(ctx context.Context) ([]domain.UpgradeBundle, error)
	// GetBundle 은 없으면 domain.ErrUpgradeBundleUnknown.
	GetBundle(ctx context.Context, id string) (*domain.UpgradeBundle, error)
	// CreateBundle 은 같은 ID 나 같은 경로(도구 · 출발 · 대상)가 있으면 domain.ErrUpgradeBundleExists.
	CreateBundle(ctx context.Context, bundle *domain.UpgradeBundle) error
	// UpdateBundleStatus 는 없으면 domain.ErrUpgradeBundleUnknown.
	UpdateBundleStatus(ctx context.Context, id, status string) error
}

type UpgradeHealthVerifier interface {
	Verify(ctx context.Context, kubeconfig []byte, namespace string, bundle domain.UpgradeBundle) error
}

type UpgradeRepository interface {
	UpgradeBundleStore
	ListVerifiedBundles(ctx context.Context, tool, sourceChartVersion string) ([]domain.UpgradeBundle, error)
	// GetVerifiedBundle 은 verified 번들만 돌려준다. 없으면 domain.ErrUpgradeBundleNotFound.
	GetVerifiedBundle(ctx context.Context, id string) (*domain.UpgradeBundle, error)
	// ListRuns 는 스택의 실행을 최근 것부터 limit 개 돌려준다. 막힌 시도도 들어간다 — 감사 기록이다.
	ListRuns(ctx context.Context, stackID string, limit int) ([]domain.UpgradeRun, error)
	// CreateRun 은 진행 중 실행이 이미 있으면 domain.ErrUpgradeInProgress, 같은 키의 실행이
	// 있으면 ErrUpgradeIdempotencyConflict 를 돌려준다. 동시에 들어온 요청은 DB 가 가린다.
	CreateRun(ctx context.Context, run *domain.UpgradeRun) error
	// UpdateRun 과 Heartbeat 는 실행이 아직 진행 중일 때만 쓴다. 이미 끝났으면(중단 처리가 닫음)
	// domain.ErrUpgradeRunClosed — 백그라운드 작업은 거기서 멈춘다. 없으면 domain.ErrUpgradeRunNotFound.
	UpdateRun(ctx context.Context, run *domain.UpgradeRun) error
	Heartbeat(ctx context.Context, runID string, at time.Time) error
	// CloseStaleRun 은 진행 중이고 박동이 staleBefore 보다 오래된 실행만 run 의 상태로 닫는다.
	// 그 사이 박동이 들어왔으면 닫지 않고 false 다.
	CloseStaleRun(ctx context.Context, run *domain.UpgradeRun, staleBefore time.Time) (bool, error)
	// GetRun 은 없으면 domain.ErrUpgradeRunNotFound.
	GetRun(ctx context.Context, stackID, runID string) (*domain.UpgradeRun, error)
	// FindRunByIdempotencyKey 와 아래 조회는 없으면 (nil, nil) 이다.
	FindRunByIdempotencyKey(ctx context.Context, stackID, key string) (*domain.UpgradeRun, error)
	ActiveRun(ctx context.Context, stackID string) (*domain.UpgradeRun, error)
	// LatestRun 은 실제로 실행된(사전 점검에서 막히지 않은) 실행 중 가장 최근 것이다. 막힌 시도는
	// 요청한 자리에서 이유를 돌려주므로, 화면의 "마지막 실행" 을 가리지 않게 뺀다.
	LatestRun(ctx context.Context, stackID, tool string) (*domain.UpgradeRun, error)
}