cluster

type ApplyOpts struct {
	// MainK is the path to deploy/kcl/<env>/main.k — the KCL entrypoint
	// that renders the cluster manifests. Required.
	MainK string

	// ImageTag is the value bound to KCL's `image_tag` -D variable.
	// Required (callers default to gitShortSHA at the call site).
	ImageTag string

	// ImageDigests is the per-image content-addressed digest map bound to
	// KCL's `image_digests` -D variable (image NAME → "sha256:..."). When
	// set, each rendered service's manifest image resolves to ITS image's
	// digest (`<image>@sha256:...`), not the env-wide ImageTag — the
	// structural fix for a multi-image env pinning every service to one
	// digest. May be nil/empty (the local-registry / no-digest path), in
	// which case every image stays on ImageTag, byte-identical to before.
	ImageDigests map[string]string

	// Namespace is the value bound to KCL's `namespace` -D variable and
	// passed to every kubectl invocation. Required.
	Namespace string

	// EnvConfigKV is the per-env config map projected as additional
	// `-D key=value` bindings to KCL. May be nil — the dev cluster
	// reload doesn't project per-env config (it would force a re-deploy
	// pipeline rebuild, defeating the inner-loop purpose).
	EnvConfigKV map[string]string

	// DryRun skips kubectl apply and prints the rendered manifests
	// instead. With DryRunFramed, the output is wrapped in
	// "--- Generated Manifests (dry-run) ---" / "--- End Manifests ---"
	// markers (the forge deploy convention). Without it, raw manifests
	// are printed (the forge cluster reload convention).
	DryRun       bool
	DryRunFramed bool

	// Prune deletes forge-managed Deployments in the namespace that the
	// just-applied KCL render no longer produces. Opt-in — pruning is
	// destructive (see deploy.go's pruneOrphanDeployments docstring).
	Prune bool

	// HostSkip is the set of Deployment names to skip in the rollout
	// wait — services declared `deploy: host` in KCL, which run as host
	// processes and don't have a Deployment in the cluster. Empty
	// disables the skip (every managed Deployment is awaited).
	HostSkip map[string]struct{}

	// OneShotJobs is an OPTIONAL caller-supplied list of Job names to
	// wait on. Apply UNIONs it with every `kind: Job` it finds in the
	// rendered manifest stream (see RenderedJobNames), so the wait set
	// is authoritative-by-manifest and a caller no longer has to derive
	// it correctly for the schedule=="" migrate-Job wait to fire — this
	// field is now belt-and-suspenders for a Job not present in the
	// stream. Each Job in the union is waited on with `kubectl wait
	// --for=condition=complete` so the caller gets a definitive
	// done/fail signal before Apply returns. Scheduled CronJobs render
	// as `kind: CronJob` (not `kind: Job`) and are NOT waited on — they
	// run on their own cadence and the deploy is done once applied.
	OneShotJobs []string

	// Quiet suppresses the section-header banners ("Applying
	// manifests...", "Waiting for rollouts...") and emits the matching
	// per-resource warnings in the bare format ("Warning: <msg>" with
	// no leading indent) — the shape `forge cluster reload` used
	// pre-extraction. Off by default; the deploy and up call sites
	// keep the framed banners.
	Quiet bool

	// Env is the environment name (e.g. "dev", "dev-host", "prod")
	// passed to KCL as `-D env=<env>`. User main.k files can read it via
	// `option("env")` to conditionally include manifests — typical use
	// is skipping in-cluster infra (NATS, Temporal, LiteLLM) on dev-host
	// envs where docker-compose provides the same services.
	Env string

	// Context, when non-empty, is the kubectl context every kubectl
	// invocation in the apply/wait path runs against — passed as
	// `--context <ctx>` per command rather than mutating the global
	// active context (`kubectl config use-context`). This is what makes
	// concurrent multi-cluster `forge deploy` safe: two deploys sharing
	// one kubeconfig but targeting different clusters no longer race on
	// the single global context. Empty = use kubectl's current/default
	// context (unchanged for single-cluster users).
	Context string

	// Targets, when non-empty, is the EXCLUSIVE set of KCL-declared service
	// GROUPs (`app.kubernetes.io/name` values) this apply keeps. The whole
	// env bundle is still rendered (KCL renders the env as a unit), but after
	// RenderManifests and before KubectlApply the multi-doc YAML is filtered
	// to EXACTLY the manifests whose group ∈ Targets — and EXACTLY the helm
	// charts whose Name ∈ Targets are rendered. The filter is purely
	// mechanical: it includes nothing implicitly. There is no shared-base
	// auto-keep, and no synthetic group: the env-shared manifests (Namespace,
	// ConfigMap, RuntimeClass, NetworkPolicy) and bundle-level
	// `additional_manifests` carry NO group, so they apply ONLY on a bare
	// deploy and are NEVER selected by a service Target. To make a manifest
	// ride a service's Target, declare it on that service's `manifests`.
	// Empty Targets means "apply EVERYTHING" — every manifest and every
	// declared platform dep (the full declarative reconcile). See
	// SelectManifestsByGroup and selectHelmChartsByGroup.
	Targets []string

	// HelmCharts are the env's declared platform dependencies, rendered
	// with helm-as-a-RENDERER (helm template --skip-crds) and folded into
	// THIS apply stream. Each is a renderable whose NAME is its GROUP — the
	// SAME exclusive Targets filter selects it: a chart is rendered + applied
	// iff (no Targets) OR (its Name ∈ Targets), the identical rule every other
	// manifest obeys (each chart's manifests are stamped
	// `app.kubernetes.io/name = Name`). There is NO chart opt-in special case
	// — a bare `forge deploy <env>` (no Targets) reconciles every declared
	// platform dep too. Apply renders each selected chart, stamps every
	// manifest with its group, and applies it in CRD-first order (the chart's
	// forge-supplied CRDs → wait Established → the chart's controllers) so the
	// apply leaves CRDs Established + controllers Deployed. Empty => no
	// platform deps. See helm.go.
	HelmCharts []HelmChartSpec

	// ClusterScope, when non-nil, scopes the rendered env bundle to ONE
	// deploy group's cluster before applying — declared-cluster-only
	// multi-cluster routing. KCL renders the whole env as a unit (every
	// service's manifests in one stream), but each manifest must land ONLY
	// on the cluster of its OWNING service (identified by its
	// `app.kubernetes.io/name` label), and no other cluster may receive it.
	// Without this, every group applied the entire bundle to its own
	// `--context`, so a two-cluster env cross-contaminated both clusters
	// (the secondary got the whole stack and hard-failed on missing CRDs).
	// ScopeManifestsToGroup does the per-doc partition by owner; nil leaves
	// the stream untouched (the single-cluster path, byte-identical to the
	// pre-scoping behaviour). See ScopeManifestsToGroup for the ownership
	// rule.
	ClusterScope *GroupScope
}

type ConfigMapGetter interface {
	GetConfigMapKeys(ctx context.Context, kctx, namespace, name string) (keys map[string]struct{}, exists bool, err error)
}

type CredentialedImageArchChecker interface {
	WithDockerConfigDir(dir string) ImageArchChecker
}

type CredentialedImageChecker interface {
	// WithDockerConfigDir returns an ImageChecker that runs `docker` with
	// DOCKER_CONFIG=dir, so private-registry lookups authenticate with the
	// cluster's pull creds materialised there.
	WithDockerConfigDir(dir string) ImageChecker
}

type DockerImageArchChecker struct {
	// DockerConfigDir overrides DOCKER_CONFIG for the docker invocation. Empty
	// inherits the process environment.
	DockerConfigDir string
}

type DockerImageChecker struct {
	// DockerConfigDir overrides DOCKER_CONFIG for the docker invocation. Empty
	// means inherit the process environment (ambient docker login).
	DockerConfigDir string
}

type GroupScope struct {
	// Cluster is THIS group's cluster name (forge.K8sCluster.cluster). It
	// is the value a manifest's first-class `forge.dev/cluster` routing
	// label is matched against: a manifest carrying that label lands on
	// this group iff the label equals Cluster, and is dropped otherwise —
	// no app-label indirection. Empty disables the first-class match (the
	// stream is routed purely by OwnApps/OtherApps, the pre-existing
	// behaviour). See clusterRoutingLabel and ScopeManifestsToGroup.
	Cluster string

	// OwnApps is the set of `app.kubernetes.io/name` values belonging to
	// THIS group's services — their workloads (Deployment / Service /
	// per-service RBAC / HPA) AND the raw manifests those services own (a
	// CRD, env-level infra pinned to this cluster via an image-less infra
	// service). All carry the service's app label. These land on this
	// group's cluster.
	OwnApps map[string]struct{}

	// OtherApps is the set of app-name labels owned by OTHER k8s groups —
	// services that target a DIFFERENT cluster. These are dropped from this
	// group so a manifest never lands on a cluster its owner doesn't declare.
	OtherApps map[string]struct{}
}

type HelmChartSpec struct {
	// Name is the platform dep's NAME — the `--target` selector and the
	// `app.kubernetes.io/name` stamped on every rendered manifest.
	Name string
	// Chart is the chart name for a repo chart (e.g. "cert-manager").
	// Empty for an OCI chart (OCI carries the full ref).
	Chart string
	// Repo is the chart-repo URL (e.g. "https://charts.jetstack.io").
	// Mutually exclusive with OCI.
	Repo string
	// OCI is the OCI chart ref (e.g.
	// "oci://docker.io/envoyproxy/gateway-helm"). Mutually exclusive with Repo.
	OCI string
	// Version is the pinned chart version (e.g. "v1.20.1").
	Version string
	// Namespace is the namespace to render the chart into
	// (`helm template -n <namespace>`).
	Namespace string
	// Values is the helm values overlay (the `--values` file content),
	// passed through verbatim from the KCL `values` dict.
	Values map[string]any
	// CRDs is the forge-supplied CRD manifest YAML applied FIRST (before
	// the chart's controllers) and waited until Established. The caller
	// fetches it (pinned standard Gateway API CRDs / cert-manager CRDs at
	// the chart version). Empty when the chart needs no forge CRDs.
	CRDs string
	// Manifests is the consumer-declared raw manifest YAML (a `---`-joined
	// stream) that rides this chart's `--target`: the cluster-scoped
	// instances a chart's controller reconciles but the chart doesn't ship
	// (the `eg` GatewayClass, cert-manager ClusterIssuers). Applied AFTER
	// the chart's controllers (so the controller is up before its
	// instances), stamped with the chart's app-label like the chart's own
	// output, so they ride the chart's GROUP under the exclusive `--target`
	// filter (selected iff no targets, or the chart's Name ∈ targets — the
	// same rule as the chart itself). Empty when the chart carries none.
	Manifests string
}

type ImageArchChecker interface {
	ImageArchitectures(ctx context.Context, ref string) (archs []string, err error)
}

type ImageChecker interface {
	ImageExists(ctx context.Context, ref string) (exists bool, err error)
}

type KubectlConfigMapGetter struct{}

type KubectlPullCredsResolver struct{}

type KubectlSecretGetter struct{}

type KubectlSecretValueGetter struct{}

type KubectlServedKinds struct{}

type ManifestGVK struct {
	APIVersion string
	Kind       string
	// Name is metadata.name of the document (best-effort, "" when absent) —
	// used only to make the missing-CRD report actionable.
	Name string
}

type ManifestRefs struct {
	// Secrets maps a Secret name to the set of keys referenced from it. A
	// key of "" (present in the set) means a whole-Secret reference
	// (envFrom secretRef, a volume mount, an imagePullSecret) — verify
	// existence only.
	Secrets map[string]map[string]struct{}
	// ConfigMaps maps a ConfigMap name to the set of keys referenced from
	// it. A key of "" means a whole-ConfigMap reference (envFrom
	// configMapRef or a whole-ConfigMap volume mount) — verify existence
	// only. A missing ConfigMap key fails a pod identically to a missing
	// Secret key (CreateContainerConfigError).
	ConfigMaps map[string]map[string]struct{}
	// Images is the set of distinct container image refs in the bundle.
	Images map[string]struct{}
	// ImagePullSecrets is the set of distinct Secret names referenced via a
	// pod spec's imagePullSecrets[].name. These are the credentials the
	// CLUSTER uses to pull private images — the image-verification path
	// resolves their .dockerconfigjson from the target cluster and uses it to
	// authenticate an otherwise auth-denied registry lookup, so a present
	// private image isn't false-flagged just because the LOCAL docker daemon
	// lacks creds for that registry. A subset of the names in Secrets (which
	// records every Secret reference shape); kept distinct here because only
	// imagePullSecrets carry registry credentials.
	ImagePullSecrets map[string]struct{}
}

type PreflightOpts struct {
	// Manifests is the rendered `---`-separated YAML stream about to be
	// applied. Refs are collected from it.
	Manifests string

	// Context is the DECLARED kubectl context (forge.K8sCluster.cluster)
	// the Secret checks run against — the SAME context the apply targets,
	// never the ambient one. Empty disables the Secret check (host-only /
	// compose env with nothing to verify against a cluster).
	Context string

	// Namespace is the namespace the referenced Secrets are expected to
	// live in (the deploy's target namespace).
	Namespace string

	// Secrets resolves Secret keys against the target cluster.
	Secrets SecretGetter

	// ConfigMaps resolves ConfigMap keys against the target cluster. Like
	// Secrets, the check runs only when this and Context are both set.
	ConfigMaps ConfigMapGetter

	// ServedKinds resolves which resource types the target cluster serves, so
	// the CRD preflight can BLOCK a deploy that renders a kind (e.g. GRPCRoute)
	// whose CRD / Gateway API channel isn't installed — before the partial
	// apply that otherwise errors `no matches for kind` mid-rollout. The check
	// runs only when this and Context are both set, and only gates NON-CORE
	// kinds (core kinds like Deployment/Service are served by every cluster, so
	// gating them would false-positive on a discovery blind spot). Nil disables
	// the CRD gate (local dev / nothing to verify).
	ServedKinds ServedKindChecker

	// Images checks image existence against the registry.
	Images ImageChecker

	// ImageArch reports an image's advertised architecture(s) for the arch
	// gate. Nil disables the gate entirely (the existence check still runs).
	ImageArch ImageArchChecker

	// PullCreds resolves the CLUSTER's registry pull credentials (the
	// .dockerconfigjson of the bundle's imagePullSecrets) from the target
	// cluster. When set AND the image checker implements
	// CredentialedImageChecker AND the bundle declares imagePullSecrets, an
	// AUTH-DENIED registry lookup from the LOCAL docker daemon is RETRIED with
	// those creds, so a present private image the cluster can pull yields a TRUE
	// verdict instead of a false BLOCK. Nil (or no imagePullSecrets, or creds
	// not resolvable) leaves the existing local-daemon behaviour unchanged — the
	// auth-denied lookup still BLOCKS (fail-safe, no regression). Resolution
	// runs against opts.Context / opts.Namespace, the same target the apply
	// uses.
	PullCreds PullCredsResolver

	// TargetArch is the DECLARED node architecture of the target cluster
	// (GOARCH form: "amd64" / "arm64"), resolved from the env's KCL
	// `deploy.Cluster.platform`. When set AND ImageArch is configured, each
	// checked image's architectures are compared to it and a mismatch BLOCKS
	// the deploy (the exec-format-error gate). EMPTY means the env hasn't
	// declared a platform yet — the gate is INERT (WARN-don't-block) so envs
	// that predate the platform field (incl. the local e2e path) are never
	// false-failed.
	TargetArch string

	// SkipImageRef, when non-nil, returns true for image refs that should
	// NOT be checked (e.g. local k3d / registry.localhost refs in a dev
	// loop). A nil func checks every image (both existence AND arch).
	SkipImageRef func(ref string) bool

	// RequiredSecrets are the env's DECLARED external Secret prerequisites
	// (forge.ExternalSecret) — out-of-band Secrets the deploy depends on but
	// forge does NOT create. UNLIKE the secretKeyRef check above (which is
	// driven by what the rendered manifests reference, all in opts.Namespace),
	// a declared prereq carries its OWN namespace (cert-manager's
	// `cloudflare-api-token` lives in the `cert-manager` namespace, not the
	// deploy namespace), so each is checked in its declared namespace. A
	// declared-required-but-absent Secret/key BLOCKS — this is the whole
	// point: it converts "render green, then ACME hangs silently" into a
	// fail-fast pre-apply block. Verified only when opts.Secrets is configured
	// (a SecretGetter against the live target). Empty => no declared prereqs.
	RequiredSecrets []RequiredSecret

	// SecretValues, when set, resolves a Secret's full .data value bytes
	// (base64-decoded) for the cross-secret BYTE-MATCH check: ExternalSecrets
	// sharing a `value_group` must carry IDENTICAL bytes under their keys. A
	// drifted copy (same group, different bytes — a half-rotated credential)
	// is caught here before it ships. Nil => the byte-match compare is skipped
	// (the KCL schema still enforces that a group's members declare the same
	// KEY SET; only the live byte equality needs cluster reads).
	SecretValues SecretValueGetter

	// SecretSupply is the env's bundle-internal Secret SUPPLY for the
	// RENDER-TIME back-propagation gate (CheckSecretSupply): the Secrets the
	// bundle PROVIDES via a forge.KubeconfigSecret mint, a forge.ExternalSecret
	// out-of-band promise, or any other generated/known Secret forge produces.
	// Rendered-stream Secrets (kind: Secret) are collected from Manifests
	// directly, so this need only carry the entity-derived supply. The gate is
	// pure (NO cluster) and ALWAYS runs — it converts a workload mounting a
	// Secret nothing declares (the silent FailedMount / 15-min ContainerCreating
	// rot) into a fail-fast render-time BLOCK. Empty => only rendered-stream
	// Secrets count as supply. See SecretSupply / CheckSecretSupply.
	SecretSupply []SecretSupply
}

type PreflightResult struct {
	// MissingSecretKeys maps "<namespace>/<secret>" to the sorted list of
	// referenced keys that are absent (or the whole Secret, rendered as a
	// single marker when the Secret doesn't exist).
	MissingSecretKeys map[string][]string
	// MissingConfigMapKeys maps "<namespace>/<configmap>" to the sorted
	// list of referenced keys that are absent (or the whole-ConfigMap
	// marker when the ConfigMap doesn't exist).
	MissingConfigMapKeys map[string][]string
	// MissingImages is the sorted list of image refs CONFIRMED absent.
	MissingImages []string
	// UnverifiableImages is the sorted list of "<ref>: <reason>" entries for
	// images whose registry lookup was AUTH-DENIED (denied / unauthorized /
	// 403). Their presence is unknown and a deploy gate must not silently
	// pass an image it cannot confirm — these BLOCK, with a message naming
	// both possible causes (image not pushed, OR the deploy host lacks pull
	// creds for the registry).
	UnverifiableImages []string
	// ImageWarnings is the sorted list of "could not verify" notes for
	// images whose existence check was inconclusive — a TRANSPORT failure
	// (DNS, connection refused, i/o timeout, docker daemon down) that says
	// nothing about the image. These do NOT block the deploy — they are
	// printed so the user knows the gate couldn't vouch for those images.
	ImageWarnings []string
	// ArchMismatchImages is the sorted list of "<ref>: image is <archs>,
	// cluster nodes are <target>" entries for images whose advertised
	// architecture does NOT include the target cluster's declared arch. These
	// BLOCK — running an arm64 image on amd64 nodes is the exec-format-error
	// crash, caught here before a single pod schedules. Only populated when a
	// target arch is DECLARED (an undeclared target arch can't assert a
	// mismatch).
	ArchMismatchImages []string
	// ArchWarnings is the sorted list of advisory notes for images whose arch
	// could not be read (transport failure / inconclusive). These do NOT
	// block — a mismatch can only be asserted on a known arch.
	ArchWarnings []string
	// MissingCRDs is the sorted list of "<Kind> (<apiVersion>) — required by
	// <manifest-name>" entries for NON-CORE kinds the bundle renders that the
	// target cluster's API server does NOT serve (no installed CRD / Gateway
	// API channel). These BLOCK — applying such a manifest fails `no matches
	// for kind` mid-rollout, AFTER other resources already applied. Only
	// populated when a ServedKindChecker is configured (an undeclared discovery
	// surface can't assert a kind is missing).
	MissingCRDs []string
	// MissingRequiredSecretKeys maps "<namespace>/<secret>" to the sorted list
	// of declared-required keys absent on the live target (or the whole-Secret
	// marker when the Secret itself is absent), for the DECLARED external
	// Secret prerequisites (forge.ExternalSecret). These BLOCK — the deploy
	// renders a consumer (e.g. cert-manager's DNS-01 ClusterIssuer) that reads
	// the Secret out-of-band, so its absence hangs ACME/DNS silently after a
	// green apply. Only populated when a SecretGetter is configured.
	MissingRequiredSecretKeys map[string][]string
	// ByteMatchMismatches is the sorted list of advisory notes for
	// cross-secret byte-match groups whose live Secret values are NOT
	// identical across the group (a half-rotated / drifted shared credential).
	// These BLOCK — a value_group declares that the same logical secret is
	// projected to N refs, so a divergence means one consumer has the stale
	// value. Only populated when a SecretValueGetter is configured AND every
	// member Secret exists (a missing member is reported by the existence
	// check, not here).
	ByteMatchMismatches []string
	// UndeclaredSecretMounts is the RENDER-TIME back-propagation result: every
	// Secret a workload mounts/references that NOTHING in the rendered bundle
	// provides (no rendered Secret, no KubeconfigSecret, no ExternalSecret, no
	// generated/known Secret). These BLOCK — the pod would stick on
	// MountVolume.SetUp failed / CreateContainerConfigError forever, with zero
	// error at deploy time. Unlike every other field here this is a PURE,
	// no-cluster check that ALWAYS runs (incl. dry-run / local clusters) — it's
	// the complement to the live Secret preflight. See CheckSecretSupply.
	UndeclaredSecretMounts []UndeclaredSecretMount
}

type PullCredsResolver interface {
	ResolveDockerConfig(ctx context.Context, kctx, namespace string, secretNames []string) (dockerConfigJSON []byte, err error)
}

type RequiredSecret struct {
	// Name / Namespace identify the out-of-band Secret. Namespace is the
	// declared namespace (often NOT the deploy namespace).
	Name      string
	Namespace string
	// Keys are the data keys the consumer reads; each must exist.
	Keys []string
	// ValueGroup ties this Secret to others that must carry identical bytes
	// (the cross-secret byte-match group). Empty => standalone.
	ValueGroup string
}

type SecretGetter interface {
	GetSecretKeys(ctx context.Context, kctx, namespace, name string) (keys map[string]struct{}, exists bool, err error)
}

type SecretSupply struct {
	// Name is the k8s Secret name this source provides. The match key.
	Name string
	// Namespace is the source's declared namespace (may differ from the deploy
	// namespace; empty means "the deploy namespace"). Recorded for the report
	// only — the match is name-based to avoid false positives.
	Namespace string
	// Kind labels the source for the report.
	Kind SecretSupplyKind
}

type SecretSupplyKind string

type SecretValueGetter interface {
	GetSecretValues(ctx context.Context, kctx, namespace, name string) (values map[string][]byte, exists bool, err error)
}

type ServedKindChecker interface {
	// ServedKinds returns the set of resource types the cluster serves, keyed
	// by servedKindKey(group, kind).
	ServedKinds(ctx context.Context, kctx string) (served map[string]struct{}, err error)
}

type UndeclaredSecretMount struct {
	// Secret is the demanded Secret name nothing supplies.
	Secret string
	// Workloads are the names of the manifests that mount/reference it,
	// deduped + sorted. Best-effort: a workload whose metadata.name couldn't be
	// read contributes nothing.
	Workloads []string
}