v1alpha1

type AgentTask struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   AgentTaskSpec   `json:"spec,omitempty"`
	Status AgentTaskStatus `json:"status,omitempty"`
}

type AgentTaskList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []AgentTask `json:"items"`
}

type AgentTaskPhase string

type AgentTaskRepository struct {
	// URL is the Git clone URL (e.g. https://github.com/org/repo or git@github.com:org/repo.git).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	URL string `json:"url"`

	// BaseBranch is the baseline branch to fork from and submit PR against (defaults to "main").
	// +kubebuilder:default="main"
	// +optional
	BaseBranch string `json:"baseBranch,omitempty"`

	// WorkingBranch is the branch where the agent commits its work.
	// Defaults to "agent/<task-name>".
	// +optional
	WorkingBranch string `json:"workingBranch,omitempty"`
}

type AgentTaskSandbox struct {
	// Provider defines the sandbox provider kind. Defaults to "agent-sandbox".
	// +kubebuilder:default="agent-sandbox"
	// +optional
	Provider string `json:"provider,omitempty"`

	// PoolRef references a pre-warmed SandboxWarmPool in the cluster.
	// +optional
	PoolRef string `json:"poolRef,omitempty"`

	// TemplateRef references a SandboxTemplate definition.
	// +optional
	TemplateRef string `json:"templateRef,omitempty"`

	// TimeoutSeconds is the execution TTL for the sandbox. Defaults to 3600 (1 hour).
	// +kubebuilder:default=3600
	// +optional
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`
}

type AgentTaskSpec struct {
	// Objective is the human-provided natural language task or specification.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Objective string `json:"objective"`

	// Repository specifies the target VCS repository.
	// +kubebuilder:validation:Required
	Repository AgentTaskRepository `json:"repository"`

	// Sandbox configures the isolated sandbox execution runtime.
	// +optional
	Sandbox AgentTaskSandbox `json:"sandbox,omitempty"`

	// BudgetUSD specifies the maximum token and compute spend limit (e.g. "5.00").
	// +optional
	BudgetUSD string `json:"budgetUSD,omitempty"`

	// BudgetTokens specifies the maximum token consumption limit (e.g. 500000).
	// +optional
	BudgetTokens int64 `json:"budgetTokens,omitempty"`

	// MaxIterations sets the maximum number of autonomous build-test-review loops.
	// Defaults to 5.
	// +kubebuilder:default=5
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxIterations int32 `json:"maxIterations,omitempty"`

	// Capabilities defines allowed model tiers (e.g. ["fast", "lite", "smart"]).
	// +optional
	Capabilities []string `json:"capabilities,omitempty"`

	// DraftPR specifies whether PRs created by the agent must be in Draft mode.
	// Defaults to true for safety.
	// +kubebuilder:default=true
	// +optional
	DraftPR bool `json:"draftPR,omitempty"`

	// Suspended pauses the agent execution and scales compute to zero.
	// +optional
	Suspended bool `json:"suspended,omitempty"`
}

type AgentTaskStatus struct {
	// Phase is the current lifecycle state.
	// +kubebuilder:default="Pending"
	Phase AgentTaskPhase `json:"phase,omitempty"`

	// SandboxClaimRef is the name of the SandboxClaim created for this task.
	// +optional
	SandboxClaimRef string `json:"sandboxClaimRef,omitempty"`

	// SandboxPodName is the pod executing the sandbox workspace.
	// +optional
	SandboxPodName string `json:"sandboxPodName,omitempty"`

	// SandboxIP is the IP address of the sandbox pod.
	// +optional
	SandboxIP string `json:"sandboxIP,omitempty"`

	// Iteration tracks the current autonomous loop cycle.
	// +optional
	Iteration int32 `json:"iteration,omitempty"`

	// PRURL is the URL of the created draft pull request once opened.
	// +optional
	PRURL string `json:"prURL,omitempty"`

	// CostUSD is the accumulated token/compute cost in USD.
	// +optional
	CostUSD string `json:"costUSD,omitempty"`

	// TokensConsumed is the accumulated count of prompt and candidate tokens consumed.
	// +optional
	TokensConsumed int64 `json:"tokensConsumed,omitempty"`

	// Message is human-readable status or diagnostic text.
	// +optional
	Message string `json:"message,omitempty"`

	// Conditions describe state transitions and status observations.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration is the most recent metadata generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type AsyncRouteSpec struct {
	// Protocol is the async protocol type.
	// +kubebuilder:validation:Enum=temporal;kafka;redis;valkey
	Protocol string `json:"protocol" yaml:"protocol"`

	// Target is the baseline resource name (e.g., task queue name or topic name).
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=249
	Target string `json:"target" yaml:"target"`

	// EnvVarMapping maps provisioned targets to environment variable names.
	// If empty, sensible defaults are used based on protocol:
	// - temporal: TEMPORAL_TASK_QUEUE
	// - kafka: KAFKA_CONSUMER_GROUP
	// - redis / valkey: DIVERGE_REDIS_PREFIX
	// +optional
	EnvVarMapping map[string]string `json:"envVarMapping,omitempty" yaml:"envVarMapping,omitempty"`
}

type AtlasPolicySpec struct {
	// Destructive controls how destructive schema changes are handled.
	// +kubebuilder:validation:Enum=error;warn;allow
	// +kubebuilder:default=error
	Destructive string `json:"destructive,omitempty"`
}

type AtlasSpec struct {
	// Mode selects the Atlas migration paradigm.
	// +kubebuilder:validation:Enum=versioned;declarative
	Mode string `json:"mode,omitempty"` // versioned (AtlasMigration) or declarative (AtlasSchema)
	// MigrationConfigMap references a ConfigMap containing versioned .sql migration files and atlas.sum.
	MigrationConfigMap string `json:"migrationConfigMap,omitempty"`
	// SchemaConfigMap references a ConfigMap containing the desired schema (SQL or HCL).
	SchemaConfigMap string `json:"schemaConfigMap,omitempty"`
	// Blocking controls whether the Environment waits for Atlas to report Ready.
	// +kubebuilder:default=true
	// +optional
	Blocking *bool `json:"blocking,omitempty"`
	// Policy configures Atlas safety policies.
	// +optional
	Policy *AtlasPolicySpec `json:"policy,omitempty"`
	// Engine selects the execution engine: "operator" (Atlas CRDs) or "job" (standalone K8s Job).
	// +kubebuilder:validation:Enum=operator;job
	// +kubebuilder:default=operator
	// +optional
	Engine string `json:"engine,omitempty"`
	// Image overrides the container image used for standalone Atlas jobs.
	// Defaults to "arigaio/atlas:latest".
	// +optional
	Image string `json:"image,omitempty"`
	// ExtraArgs specifies additional command-line arguments to pass to the Atlas CLI.
	// +optional
	ExtraArgs []string `json:"extraArgs,omitempty"`
}

type BannerSpec struct {
	// Enabled controls whether the preview banner is injected into HTTP responses.
	Enabled bool `json:"enabled,omitempty"`
	// Text specifies the text to display inside the preview banner.
	// +kubebuilder:default="Preview Environment"
	Text string `json:"text,omitempty"`
	// Position determines where the banner is displayed on the screen.
	// +kubebuilder:validation:Enum=top;bottom
	// +kubebuilder:default=top
	Position string `json:"position,omitempty"`
	// Color is the hex color code for the banner background.
	// +kubebuilder:validation:Pattern="^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
	// +kubebuilder:default="#FF6B00"
	Color string `json:"color,omitempty"`
}

type CookieSpec struct {
	Enabled bool `json:"enabled,omitempty"`
	// +kubebuilder:validation:Minimum=0
	MaxAge int `json:"maxAge,omitempty"` // seconds, default 86400 (24h)
	// +kubebuilder:validation:Enum=Lax;Strict;None
	SameSite string `json:"sameSite,omitempty"` // Lax, Strict, None
	Secure   bool   `json:"secure,omitempty"`
}

type DiscoveredIngressPath struct {
	// Entrypoint is the gateway service name where the path originates.
	Entrypoint string `json:"entrypoint"`

	// Target is the destination service name.
	Target string `json:"target"`

	// Hops is the ordered list of services along the path,
	// from entrypoint to target inclusive.
	Hops []string `json:"hops"`
}

type EnvVar struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type Environment struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   EnvironmentSpec   `json:"spec,omitempty"`
	Status EnvironmentStatus `json:"status,omitempty"`
}

type EnvironmentDatabase struct {
	// +kubebuilder:validation:Enum=shared;schema;snapshot;fresh
	Mode          string            `json:"mode,omitempty"` // shared, schema, snapshot, fresh
	ConnectionRef string            `json:"connectionRef,omitempty"`
	SeedSource    string            `json:"seedSource,omitempty"`
	MigrationJob  *MigrationJobSpec `json:"migrationJob,omitempty"`
	Atlas         *AtlasSpec        `json:"atlas,omitempty"`
}

type EnvironmentDeploy struct {
	// +kubebuilder:validation:Enum=delta;full
	Mode string `json:"mode,omitempty"` // delta or full
	// +kubebuilder:validation:Enum=same;create
	// +kubebuilder:default=same
	Namespace string `json:"namespace,omitempty"` // same = deploy in CR's namespace, create = new diverge-* namespace
	// +optional
	NamespaceLabels map[string]string `json:"namespaceLabels,omitempty"`
	ChangedServices []string          `json:"changedServices,omitempty"`
	BaselineRef     string            `json:"baselineRef,omitempty"`
	// Manifests specifies where pre-rendered manifests are stored.
	// Required when using the direct deployer.
	// +optional
	Manifests *ManifestSource `json:"manifests,omitempty"`
	// EnvFrom specifies environment variables to inject from Secrets.
	// +optional
	EnvFrom []SecretRef `json:"envFrom,omitempty"`
}

type EnvironmentLifecycle struct {
	TTL            *metav1.Duration `json:"ttl,omitempty"`
	CleanupOnMerge bool             `json:"cleanupOnMerge,omitempty"`
}

type EnvironmentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Environment `json:"items"`
}

type EnvironmentPhase string

type EnvironmentRouting struct {
	// +kubebuilder:validation:Enum=header;namespace;subdomain
	Mode string `json:"mode,omitempty"` // header, namespace, subdomain
	// +kubebuilder:validation:Enum=istio;gateway
	// +kubebuilder:default=gateway
	Provider    string `json:"provider,omitempty"`
	HeaderKey   string `json:"headerKey,omitempty"`
	HeaderValue string `json:"headerValue,omitempty"`
	ExternalURL string `json:"externalUrl,omitempty"`
	DevIP       string `json:"devIP,omitempty"`
	// BaseDomain is the base domain for subdomain routing (e.g., "preview.app.dev").
	// When mode is "subdomain", HTTPRoutes are created with hostname "<env-name>.<baseDomain>".
	// +optional
	BaseDomain string `json:"baseDomain,omitempty"`
	// AsyncRoutes defines async routing targets for event-driven backends.
	// +optional
	// +kubebuilder:validation:MaxItems=50
	AsyncRoutes []AsyncRouteSpec `json:"asyncRoutes,omitempty"`
	// Cookie enables sticky routing using cookies.
	// +optional
	Cookie *CookieSpec `json:"cookie,omitempty"`
	// Banner configures a preview indicator banner to inject into responses.
	// +optional
	Banner *BannerSpec `json:"banner,omitempty"`
}

type EnvironmentSource struct {
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=gitlab;github;local
	Provider string `json:"provider"` // e.g., gitlab, github, local
	// +optional
	Project string `json:"project,omitempty"`
	MR      int    `json:"mr,omitempty"`
	// +kubebuilder:validation:Required
	Branch    string `json:"branch"`
	CommitSHA string `json:"commitSHA,omitempty"`
}

type EnvironmentSpec struct {
	Source    EnvironmentSource    `json:"source,omitempty"`
	Deploy    EnvironmentDeploy    `json:"deploy,omitempty"`
	Routing   EnvironmentRouting   `json:"routing,omitempty"`
	Database  EnvironmentDatabase  `json:"database,omitempty"`
	Lifecycle EnvironmentLifecycle `json:"lifecycle,omitempty"`
	// Features configures feature flags and remote configuration.
	// +optional
	Features *FeatureSpec `json:"features,omitempty"`
	// Testing configures automated test integration.
	// +optional
	Testing *TestingSpec `json:"testing,omitempty"`
	// ServiceConfig holds preview configuration for multi-repo mode.
	// When set, the controller deploys a single preview pod based on
	// this config rather than using ManifestFetcher.
	// +optional
	ServiceConfig *ServicePreviewConfig `json:"serviceConfig,omitempty"`
	// EnvFrom specifies environment variables to inject from Secrets.
	// +optional
	EnvFrom []SecretRef `json:"envFrom,omitempty"`
}

type EnvironmentStatus struct {
	Phase          EnvironmentPhase `json:"phase,omitempty"`
	URL            string           `json:"url,omitempty"`
	Services       []string         `json:"services,omitempty"`
	DatabaseStatus string           `json:"databaseStatus,omitempty"`
	// DatabaseProvider records the resolved database provider name for consistent teardown.
	// +optional
	DatabaseProvider   string             `json:"databaseProvider,omitempty"`
	CreatedAt          *metav1.Time       `json:"createdAt,omitempty"`
	ExpiresAt          *metav1.Time       `json:"expiresAt,omitempty"`
	ObservedGeneration int64              `json:"observedGeneration,omitempty"`
	Conditions         []metav1.Condition `json:"conditions,omitempty"`
	CommitSHA          string             `json:"commitSHA,omitempty"`
	CommentID          int                `json:"commentID,omitempty"`
	CommitStatusURL    string             `json:"commitStatusURL,omitempty"`
	// TestStatus tracks the state of the test run for this environment.
	// +optional
	TestStatus *TestStatus `json:"testStatus,omitempty"`

	// AsyncEnvVars contains environment variables injected by async route provisioners.
	// +optional
	AsyncEnvVars map[string]string `json:"asyncEnvVars,omitempty"`

	// MigrationStatus tracks the state of the migration hook.
	// +optional
	MigrationStatus string `json:"migrationStatus,omitempty"` // Pending, Running, Succeeded, Failed
	// MigrationMessage provides details about the migration hook state.
	// +optional
	MigrationMessage string `json:"migrationMessage,omitempty"`
	// PostDeployStatus tracks the state of the post-deploy hook.
	// +optional
	PostDeployStatus string `json:"postDeployStatus,omitempty"`

	// FeatureConfigMap is the name of the ConfigMap provisioned for feature flags.
	// +optional
	FeatureConfigMap string `json:"featureConfigMap,omitempty"`
	// FeatureEnvVars contains environment variables injected by feature providers.
	// +optional
	FeatureEnvVars map[string]string `json:"featureEnvVars,omitempty"`
}

type FeatureSpec struct {
	// Provider selects the feature flag provider: "configmap", "flipt", "flagsmith", "unleash".
	// +kubebuilder:validation:Enum=configmap;flipt;flagsmith;unleash
	// +kubebuilder:default=configmap
	// +optional
	Provider string `json:"provider,omitempty"`
	// Overrides defines key-value flag overrides for this environment.
	// +optional
	Overrides map[string]string `json:"overrides,omitempty"`
	// ConnectionRef references a Secret containing provider credentials or endpoint details.
	// +optional
	ConnectionRef string `json:"connectionRef,omitempty"`
}

type KEDASpec struct {
	// Enabled enables KEDA autoscaling for this service.
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
	// MinReplicas is the minimum number of replicas. Set to 0 for scale-to-zero.
	// When nil, falls back to the controller CLI flag (--keda-min-replicas).
	// +kubebuilder:validation:Minimum=0
	// +optional
	MinReplicas *int32 `json:"minReplicas,omitempty"`
	// MaxReplicas is the maximum number of replicas.
	// When nil, falls back to the controller CLI flag (--keda-max-replicas).
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=100
	// +optional
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`
	// CooldownPeriod is the cooldown period in seconds before scaling down.
	// When nil, falls back to the controller CLI flag (--keda-cooldown).
	// +kubebuilder:validation:Minimum=0
	// +optional
	CooldownPeriod *int32 `json:"cooldownPeriod,omitempty"`
	// PollingInterval is the interval in seconds KEDA checks metrics. Default: 30.
	// +kubebuilder:validation:Minimum=1
	// +optional
	PollingInterval *int32 `json:"pollingInterval,omitempty"`
	// TargetQueueSize is the target backlog per replica for queue-based scaling. Default: 5.
	// +optional
	TargetQueueSize *int32 `json:"targetQueueSize,omitempty"`
}

type ManifestSource struct {
	// Type is the manifest source type: "configmap" or "url".
	// +kubebuilder:validation:Enum=configmap;url
	Type string `json:"type"`
	// URL for HTTP-based manifest fetching (when type=url).
	// +kubebuilder:validation:Pattern="^https?://.*"
	URL string `json:"url,omitempty"`
}

type MigrationJobSpec struct {
	// Image is the container image to use for the migration job.
	Image string `json:"image,omitempty"`
	// Args specifies the arguments to pass to the migration job container.
	Args []string `json:"args,omitempty"`
	// EnvFrom specifies environment variables to inject from Secrets.
	EnvFrom []SecretRef `json:"envFrom,omitempty"`
	// TimeoutSeconds is the maximum duration the migration job can run before being terminated.
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"` // Default 120
	// Blocking controls whether the Environment waits for the migration to complete.
	// +kubebuilder:default=true
	// +optional
	Blocking *bool `json:"blocking,omitempty"` // Default true
}

type PostDeploySpec struct {
	// Image is the container image to use for the post-deploy job.
	Image string `json:"image,omitempty"`
	// Args specifies the arguments to pass to the post-deploy container.
	Args []string `json:"args,omitempty"`
	// EnvFrom specifies environment variables to inject from Secrets.
	EnvFrom []SecretRef `json:"envFrom,omitempty"`
	// TimeoutSeconds is the maximum duration before the job is terminated.
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"` // Default 60
	// Blocking controls whether the Environment waits for the post-deploy job.
	// +kubebuilder:default=false
	// +optional
	Blocking *bool `json:"blocking,omitempty"` // Default false
}

type PreviewGroup struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PreviewGroupSpec   `json:"spec,omitempty"`
	Status PreviewGroupStatus `json:"status,omitempty"`
}

type PreviewGroupLifecycle struct {
	// TTL is the time-to-live for the preview group.
	// After this duration, the group is automatically deleted.
	// +optional
	TTL *metav1.Duration `json:"ttl,omitempty"`

	// CleanupOnMerge controls whether to automatically delete the preview group
	// when the source MR/PR is merged or closed.
	// +optional
	CleanupOnMerge bool `json:"cleanupOnMerge,omitempty"`
}

type PreviewGroupList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PreviewGroup `json:"items"`
}

type PreviewGroupPhase string

type PreviewGroupRouting struct {
	// Mode is the routing mode.
	// +kubebuilder:validation:Enum=header;subdomain
	// +kubebuilder:default=header
	// +optional
	Mode string `json:"mode,omitempty"`

	// HeaderKey is the HTTP header key used for routing.
	// Defaults to "x-preview-env".
	// +kubebuilder:default="x-preview-env"
	// +optional
	HeaderKey string `json:"headerKey,omitempty"`

	// HeaderValue is the value that identifies this preview group.
	// Typically set to the MR number (e.g. "42") or branch name.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	HeaderValue string `json:"headerValue"`

	// ExternalURL is an optional shareable URL for non-engineer access
	// (e.g. "https://mr-42.preview.dev.azra-ai.com").
	// +optional
	ExternalURL string `json:"externalUrl,omitempty"`

	// BaseDomain is the base domain for subdomain routing.
	// +optional
	BaseDomain string `json:"baseDomain,omitempty"`
}

type PreviewGroupServiceSpec struct {
	// Name of the Kubernetes Service to preview. Must match an existing Service.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Image is the container image to deploy for mode=image.
	// Required when mode is "image", ignored for "local" and "baseline".
	// +optional
	Image string `json:"image,omitempty"`

	// Mode defines how this service participates in the preview group.
	// +kubebuilder:validation:Enum=image;local;baseline
	// +kubebuilder:default=image
	// +optional
	Mode ServiceMode `json:"mode,omitempty"`

	// Endpoint is the external endpoint for mode=local
	// (e.g. "100.64.23.42:8080" for a developer's Tailscale IP).
	// Required when mode is "local", ignored otherwise.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// Namespace is the Kubernetes namespace where the service will be deployed. Required. If omitted, falls back to the controller's default namespace.
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// Port is the container port. Auto-discovered from existing Service if 0.
	// +optional
	Port int32 `json:"port,omitempty"`

	// ParentRef is the Gateway API parentRef name (e.g. the Istio waypoint proxy
	// or a gateway). Auto-discovered if empty.
	// +optional
	ParentRef string `json:"parentRef,omitempty"`

	// PathPrefix scopes HTTPRoute matching to a specific path prefix
	// (e.g. "/api/payments") to avoid shadowing the baseline service.
	// Auto-discovered if empty.
	// +kubebuilder:validation:Pattern=`^/.*$`
	// +optional
	PathPrefix string `json:"pathPrefix,omitempty"`

	// Protocol determines whether to generate an HTTPRoute or GRPCRoute.
	// +kubebuilder:validation:Enum=http;grpc
	// +kubebuilder:default=http
	// +optional
	Protocol ServiceProtocol `json:"protocol,omitempty"`

	// AsyncRoutes defines async routing targets to provision for this service.
	// +optional
	AsyncRoutes []AsyncRouteSpec `json:"asyncRoutes,omitempty"`

	// ImagePullPolicy overrides the container image pull policy.
	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
	// +optional
	ImagePullPolicy string `json:"imagePullPolicy,omitempty"`

	// Env specifies additional environment variables for the preview pod.
	// +optional
	Env []EnvVar `json:"env,omitempty"`

	// Resources overrides the baseline resource requests/limits for preview pods.
	// If unset, the controller defaults to conservative values (100m CPU, 256Mi RAM).
	// +optional
	Resources *ResourceOverride `json:"resources,omitempty"`

	// Database overrides the group-level database configuration for this service.
	// +optional
	Database *EnvironmentDatabase `json:"database,omitempty"`

	// PostDeploy configures a generic post-deployment Job hook for this service.
	// +optional
	PostDeploy *PostDeploySpec `json:"postDeploy,omitempty"`

	// KEDA configures per-service autoscaling and scale-to-zero settings.
	// Overrides controller-level CLI flags when set.
	// +optional
	KEDA *KEDASpec `json:"keda,omitempty"`
}

type PreviewGroupServiceStatus struct {
	// Name is the service name.
	Name string `json:"name"`

	// EnvironmentName is the name of the child Environment CR created for this service.
	EnvironmentName string `json:"environmentName,omitempty"`

	// Namespace is where the preview pod is deployed.
	Namespace string `json:"namespace,omitempty"`

	// Phase is the current lifecycle phase of this service's preview.
	Phase EnvironmentPhase `json:"phase,omitempty"`

	// URL is the reachable URL for this service's preview.
	URL string `json:"url,omitempty"`

	// Message is a human-readable status message.
	Message string `json:"message,omitempty"`

	// Reason is a machine-readable failure reason
	// (e.g. "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled").
	Reason string `json:"reason,omitempty"`

	// LastLogSnippet contains the last few lines from the preview pod's
	// container logs, enabling quick debugging from the MR comment.
	LastLogSnippet string `json:"lastLogSnippet,omitempty"`

	// ChangedServices lists the services that were modified in this preview,
	// sourced from the child Environment's spec.deploy.changedServices.
	ChangedServices []string `json:"changedServices,omitempty"`
}

type PreviewGroupSpec struct {
	// Source identifies the SCM context (GitLab MR, GitHub PR, etc.)
	// +kubebuilder:validation:Required
	Source EnvironmentSource `json:"source"`

	// Routing configures header-based traffic routing shared by all services.
	// +kubebuilder:validation:Required
	Routing PreviewGroupRouting `json:"routing"`

	// Services defines the services included in this preview group.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Services []PreviewGroupServiceSpec `json:"services"`

	// Database provides group-level database configuration.
	// Individual services can override this in their own database field.
	// +optional
	Database *EnvironmentDatabase `json:"database,omitempty"`

	// Lifecycle configures TTL and automatic cleanup.
	// +optional
	Lifecycle *PreviewGroupLifecycle `json:"lifecycle,omitempty"`

	// Owner is the username of the developer who created this PreviewGroup.
	// Used for collision detection and audit.
	Owner string `json:"owner,omitempty"`

	// TopologyOverrides provides inline service dependency edges for environments
	// created via CI/CD or webhooks where .diverge.yaml is not accessible.
	// These override auto-discovered edges from Gateway API and Prometheus.
	// +optional
	TopologyOverrides []TopologyEdge `json:"topologyOverrides,omitempty"`
}

type PreviewGroupStatus struct {
	// Phase is the aggregated phase across all services.
	// +kubebuilder:validation:Enum=Pending;Deploying;Running;Degraded;Failed;Terminating;Abandoned
	Phase PreviewGroupPhase `json:"phase,omitempty"`

	// ServiceCount is the total number of services in the group.
	ServiceCount int32 `json:"serviceCount,omitempty"`

	// Services contains per-service status.
	// +optional
	Services []PreviewGroupServiceStatus `json:"services,omitempty"`

	// ObservedGeneration is the last observed generation of the spec.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// CreatedAt is when the preview group was first created.
	CreatedAt *metav1.Time `json:"createdAt,omitempty"`

	// ExpiresAt is when the preview group will expire (from TTL).
	ExpiresAt *metav1.Time `json:"expiresAt,omitempty"`

	// Conditions represent the latest available observations of the
	// PreviewGroup's state. Includes "Ready" and "Degraded" conditions.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// CommentID is the ID of the comment tracking the preview group status.
	// +optional
	CommentID int64 `json:"commentID,omitempty"`

	// LeaseRenewedAt is the last time the owning CLI heartbeat renewed the lease.
	LeaseRenewedAt *metav1.Time `json:"leaseRenewedAt,omitempty"`

	// DiscoveredIngressPaths contains the resolved ingress routing paths
	// from gateway entrypoints to the changed services in this group.
	// Populated by the topology discovery engine during environment creation.
	// +optional
	DiscoveredIngressPaths []DiscoveredIngressPath `json:"discoveredIngressPaths,omitempty"`

	// GraphSource describes where the topology graph was discovered from
	// (e.g. "gateway-api+prometheus+static").
	// +optional
	GraphSource string `json:"graphSource,omitempty"`
}

type ResourceOverride struct {
	// CPURequest is the CPU request for the preview pod (e.g. "100m").
	// +optional
	CPURequest string `json:"cpuRequest,omitempty"`
	// MemoryRequest is the memory request for the preview pod (e.g. "256Mi").
	// +optional
	MemoryRequest string `json:"memoryRequest,omitempty"`
	// CPULimit is the CPU limit for the preview pod.
	// +optional
	CPULimit string `json:"cpuLimit,omitempty"`
	// MemoryLimit is the memory limit for the preview pod.
	// +optional
	MemoryLimit string `json:"memoryLimit,omitempty"`
}

type SecretRef struct {
	// Namespace is the namespace of the Secret.
	Namespace string `json:"namespace,omitempty"`
	// Name is the name of the Secret.
	Name string `json:"name,omitempty"`
	// Key is the specific key in the Secret to reference.
	Key string `json:"key,omitempty"`
}

type ServiceMode string

type ServicePreviewConfig struct {
	// ServiceName is the Kubernetes Service name to shadow.
	ServiceName string `json:"serviceName"`
	// Namespace is the namespace where the baseline service runs.
	Namespace string `json:"namespace,omitempty"`
	// Port is the container port the service listens on.
	Port int32 `json:"port"`
	// Image is the container image for the preview pod (set by CI).
	Image string `json:"image"`
	// ImagePullPolicy overrides the container image pull policy.
	// Valid values: Always, Never, IfNotPresent. Defaults to IfNotPresent.
	ImagePullPolicy string `json:"imagePullPolicy,omitempty"`
	// DatabaseEnvKey is the environment variable name for the database connection URL.
	// Defaults to DATABASE_URL.
	DatabaseEnvKey string `json:"databaseEnvKey,omitempty"`
	// ParentRef is the Gateway API parentRef name (e.g., Istio Waypoint proxy).
	// If empty, defaults to "diverge-gateway".
	ParentRef string `json:"parentRef,omitempty"`
	// HeaderKey overrides the routing header key.
	HeaderKey string `json:"headerKey,omitempty"`
	// PathPrefix scopes HTTPRoute matching to a specific path prefix (e.g., "/api/payments") to avoid shadowing the baseline.
	// +kubebuilder:validation:Pattern=`^/.*$`
	// +optional
	PathPrefix string `json:"pathPrefix,omitempty"`
	// Env is additional environment variables for the preview container.
	Env []EnvVar `json:"env,omitempty"`
	// Protocol specifies the service protocol for routing (http or grpc).
	// When set to "grpc", the router generates a GRPCRoute instead of HTTPRoute.
	// +kubebuilder:validation:Enum=http;grpc
	// +kubebuilder:default=http
	// +optional
	Protocol string `json:"protocol,omitempty"`
	// Endpoint is the external endpoint for mode=local (e.g. Tailscale IP:port).
	// +optional
	Endpoint string `json:"endpoint,omitempty"`
	// Resources overrides the resource requests/limits for the preview pod.
	// +optional
	Resources *ResourceOverride `json:"resources,omitempty"`
	// KEDA configures per-service autoscaling. Overrides controller CLI flags.
	// +optional
	KEDA *KEDASpec `json:"keda,omitempty"`
	// WebSocket configures WebSocket proxy support.
	// +optional
	WebSocket *WebSocketSpec `json:"websocket,omitempty"`
}

type ServiceProtocol string

type TestState string

type TestStatus struct {
	State       TestState    `json:"state,omitempty"`
	Summary     string       `json:"summary,omitempty"`
	URL         string       `json:"url,omitempty"`
	RunID       string       `json:"runID,omitempty"`
	StartedAt   *metav1.Time `json:"startedAt,omitempty"`
	CompletedAt *metav1.Time `json:"completedAt,omitempty"`
}

type TestTriggerSpec struct {
	// +kubebuilder:validation:Enum=gitlab-pipeline;github-dispatch;webhook
	Type TestTriggerType `json:"type"`
	// Project is the CI project to trigger (e.g., "team/e2e-tests").
	// Used by gitlab-pipeline and github-dispatch triggers.
	Project string `json:"project,omitempty"`
	// Ref is the git ref to trigger tests against (e.g., "main").
	Ref string `json:"ref,omitempty"`
	// EventType is the GitHub repository dispatch event type.
	// Used by github-dispatch trigger only.
	EventType string `json:"eventType,omitempty"`
	// Workflow is the GitHub Actions workflow file name to filter by.
	Workflow string `json:"workflow,omitempty"`
	// WebhookURL is the URL to POST to for webhook triggers.
	WebhookURL string `json:"webhookURL,omitempty"`
	// SecretRef references a Kubernetes Secret containing the trigger token.
	SecretRef string `json:"secretRef,omitempty"`
}

type TestTriggerType string

type TestingSpec struct {
	// Enabled controls whether tests are triggered for this environment.
	Enabled bool `json:"enabled,omitempty"`
	// Trigger defines how tests are triggered.
	Trigger TestTriggerSpec `json:"trigger"`
	// Timeout is how long to wait for test results before timing out.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`
	// Required controls whether test results block the diverge/tests commit status.
	Required bool `json:"required,omitempty"`
}

type TopologyEdge struct {
	// From is the source service name (the caller).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	From string `json:"from"`

	// To is the target service name (the callee).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	To string `json:"to"`

	// Protocol is the communication protocol (http, grpc, async).
	// +kubebuilder:validation:Enum=http;grpc;async
	// +kubebuilder:default=http
	Protocol string `json:"protocol,omitempty"`

	// Suppress removes this edge from the auto-discovered graph (tombstone).
	// Use to correct false-positive edges from Prometheus metrics.
	// +optional
	Suppress bool `json:"suppress,omitempty"`
}

type WebSocketSpec struct {
	// Enabled turns on WebSocket proxy support for the service route.
	Enabled bool `json:"enabled,omitempty"`
	// Path is the URL path prefix to match for WebSocket connections (e.g., "/ws").
	// +kubebuilder:validation:Pattern=`^/.*$`
	Path string `json:"path,omitempty"`
	// Timeout sets the maximum duration for the WebSocket connection.
	// Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$`
	Timeout string `json:"timeout,omitempty"`
}