spec

type Autoscaling struct {
	Enabled     bool     `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	MinReplicas int      `json:"minReplicas,omitempty" yaml:"minReplicas,omitempty"`
	MaxReplicas int      `json:"maxReplicas,omitempty" yaml:"maxReplicas,omitempty"`
	Metrics     []Metric `json:"metrics,omitempty" yaml:"metrics,omitempty"`
}

type Component struct {
	// Role selects the default deployment strategy for the component.
	Role ComponentRole `json:"role,omitempty" yaml:"role,omitempty"`
	// EnvFile is the path to a component-specific dotenv file.
	EnvFile string `json:"envFile,omitempty" yaml:"envFile,omitempty"`
	// ConfigFile is the path to a component-specific config file.
	ConfigFile string `json:"configFile,omitempty" yaml:"configFile,omitempty"`
	// Environments limits the component to the named environments.
	Environments []string `json:"environments,omitempty" yaml:"environments,omitempty"`
	// Kind selects stateless or stateful deployment behavior.
	Kind ComponentKind `json:"kind,omitempty" yaml:"kind,omitempty"`
	// Image is the container image reference.
	Image string `json:"image" yaml:"image"`
	// Command overrides the container entrypoint.
	Command []string `json:"command,omitempty" yaml:"command,omitempty"`
	// Args overrides the container command arguments.
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`
	// Port is the primary container port for services.
	Port int `json:"port,omitempty" yaml:"port,omitempty"`
	// Autoscaling configures horizontal pod autoscaling.
	Autoscaling *Autoscaling `json:"autoscaling,omitempty" yaml:"autoscaling,omitempty"`
	// Resources sets explicit CPU, memory, and storage requests and limits.
	Resources Resources `json:"resources" yaml:"resources,omitempty"`
	// ResourcePreset selects a named resource profile when Resources is empty.
	ResourcePreset ResourcePreset `json:"resourcePreset,omitempty" yaml:"resourcePreset,omitempty"`
	// Expose exposes the component via an ingress rule resolved against the
	// platform domain configuration. Replaces the former ingress block.
	Expose *Expose `json:"expose,omitempty" yaml:"expose,omitempty"`
	// Profiles lists platform-defined deployment profile names. Multiple
	// profiles are merged left to right. Requires a profiles section in the
	// platform file.
	Profiles []string `json:"profiles,omitempty" yaml:"profiles,omitempty"`
	// Env sets static environment variables for the container.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
	// Health configures ready and alive checks for the component.
	Health *Health `json:"health,omitempty" yaml:"health,omitempty"`
}

type ComponentKind string

type ComponentRole string

type DefaultValues map[string]any

type EnvIdentity struct {
	// Original is the raw environment name as supplied by the caller.
	Original string
	// MapKey is the key used for map lookups: split on the first "/" and take
	// the prefix. For "review/pr-123" MapKey is "review". For "production" it
	// equals Original.
	MapKey string
	// K8sSafe is a Kubernetes-safe version of Original: "/" replaced with "-",
	// truncated to 53 characters. When truncation changes the string a 4-char
	// hex hash of Original is appended (after truncating to 49 chars) to keep
	// uniqueness. Safe for Helm release name suffixes and label values.
	K8sSafe string
}

type Environment struct {
	// EnvFile is the path to a dotenv file for this environment.
	EnvFile string `json:"envFile,omitempty" yaml:"envFile,omitempty"`
	// ConfigFile is the path to an environment-specific config file.
	ConfigFile string `json:"configFile,omitempty" yaml:"configFile,omitempty"`
	// Variables holds inline key-value overrides for this environment.
	Variables map[string]string `json:"variables,omitempty" yaml:"variables,omitempty"`
}

type Expose struct {
	// Domain is the domain key referencing an entry in the platform
	// environment's domains map. When empty, the environment's only domain
	// is used, or the one marked default in the platform file.
	Domain string `json:"domain,omitempty" yaml:"domain,omitempty"`
	// Subdomain is a DNS label prepended to the platform baseDomain to form
	// the FQDN. When nil the component name is used. Mutually exclusive
	// with Apex.
	Subdomain *string `json:"subdomain,omitempty" yaml:"subdomain,omitempty"`
	// Apex exposes the component at the baseDomain itself. Mutually
	// exclusive with Subdomain.
	Apex bool `json:"apex,omitempty" yaml:"apex,omitempty"`
	// contains filtered or unexported fields
}

type Health struct {
	// Ready controls the readiness check. Provide a path to upgrade from TCP
	// to HTTP. Set to false to disable readiness and startup checks entirely.
	Ready *HealthReady `json:"ready,omitempty" yaml:"ready,omitempty"`
	// Alive controls the alive check. Provide a path to upgrade from TCP to
	// HTTP. Set to false to disable the alive check entirely.
	Alive *HealthAlive `json:"alive,omitempty" yaml:"alive,omitempty"`
}

type HealthAlive struct {
	// Disabled is true when the developer set alive: false.
	Disabled bool `json:"-" yaml:"-"`
	// Path is the HTTP endpoint that must return 2xx for the pod to be
	// considered alive. Must start with /. Check only internal process
	// state here, not external dependencies.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`
	// Interval is how often to check the endpoint (e.g. "10s", "1m").
	// Defaults to "10s" when omitted.
	Interval string `json:"interval,omitempty" yaml:"interval,omitempty"`
	// RestartAfter is how long the endpoint must fail continuously before
	// the pod is restarted (e.g. "60s", "2m"). Defaults to "60s" when
	// omitted. The effective window rounds up to the nearest multiple of
	// Interval.
	RestartAfter string `json:"restartAfter,omitempty" yaml:"restartAfter,omitempty"`
}

type HealthReady struct {
	// Disabled is true when the developer set ready: false.
	Disabled bool `json:"-" yaml:"-"`
	// Path is the HTTP endpoint that must return 2xx for the component to
	// receive traffic. Must start with /.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`
}

type Metric struct {
	Type   MetricType `json:"type" yaml:"type"`
	Target int        `json:"target" yaml:"target"`
}

type MetricType string

type PlatformConfig struct {
	// APIVersion is the platform schema version, e.g. "platform/v1-alpha.1".
	APIVersion string `json:"apiVersion" yaml:"apiVersion"`
	// Profiles maps logical profile names to deployment policy. Profiles are
	// org-wide (root-level), not per-environment. A profile named "default" is
	// prepended automatically when a component omits profiles.
	Profiles map[string]PlatformProfile `json:"profiles,omitempty" yaml:"profiles,omitempty"`
	// Environments is a map of environment names to their platform
	// configuration. Wildcard matching (prefix-split on "/") is applied by
	// [matchEnvKey].
	Environments map[string]PlatformEnvironment `json:"environments" yaml:"environments"`
}

type PlatformDomain struct {
	// BaseDomain is the DNS apex for this domain, e.g. "example.com".
	BaseDomain string `json:"baseDomain" yaml:"baseDomain"`
	// Default marks this domain as the one used when a component's expose
	// block names no domain. At most one per environment.
	Default bool `json:"default,omitempty" yaml:"default,omitempty"`
	// TLS holds the TLS mode and associated parameters.
	TLS *PlatformTLS `json:"tls,omitempty" yaml:"tls,omitempty"`
}

type PlatformEnvironment struct {
	// Context is the Kubernetes context to use for this environment.
	Context string `json:"context,omitempty" yaml:"context,omitempty"`
	// Domains is a map of logical domain names to their configuration.
	// Developers reference domain keys in expose.domain.
	Domains map[string]PlatformDomain `json:"domains,omitempty" yaml:"domains,omitempty"`
	// StorageClasses maps logical names to Kubernetes storage classes.
	StorageClasses map[string]PlatformStorageClass `json:"storageClasses,omitempty" yaml:"storageClasses,omitempty"`
	// AllowStaticSubdomain suppresses the wildcard static-subdomain warning
	// for this environment key when set to true.
	AllowStaticSubdomain bool `json:"allowStaticSubdomain,omitempty" yaml:"allowStaticSubdomain,omitempty"`
}

type PlatformProfile struct {
	// NodeSelector is Kubernetes nodeSelector labels for pod placement.
	NodeSelector map[string]string `json:"nodeSelector,omitempty" yaml:"nodeSelector,omitempty"`
	// Tolerations are Kubernetes tolerations for pod scheduling.
	Tolerations []corev1.Toleration `json:"tolerations,omitempty" yaml:"tolerations,omitempty"`
	// PodLabels are additional labels applied to pods.
	PodLabels map[string]string `json:"podLabels,omitempty" yaml:"podLabels,omitempty"`
	// PodAnnotations are additional annotations applied to pods.
	PodAnnotations map[string]string `json:"podAnnotations,omitempty" yaml:"podAnnotations,omitempty"`
	// SecurityContext is a Kubernetes PodSecurityContext (pod-level).
	SecurityContext *corev1.PodSecurityContext `json:"securityContext,omitempty" yaml:"securityContext,omitempty"`
	// ContainerSecurityContext is a Kubernetes SecurityContext applied to
	// all containers.
	ContainerSecurityContext *corev1.SecurityContext `json:"containerSecurityContext,omitempty" yaml:"containerSecurityContext,omitempty"`
	// StorageClass is a logical storage class key from the target
	// environment's storageClasses map.
	StorageClass string `json:"storageClass,omitempty" yaml:"storageClass,omitempty"`
	// AllowedDomains restricts which domain keys a component may expose on.
	// nil means no constraint. A non-nil empty list means deny-all (no domain
	// is allowed). Multiple profiles intersect. Neither JSON nor YAML uses
	// omitempty, so deny-all serializes as [] rather than becoming nil.
	AllowedDomains []string `json:"allowedDomains" yaml:"allowedDomains"`
	// MaxResources is a ceiling on component resource requests.
	MaxResources *ProfileMaxResources `json:"maxResources,omitempty" yaml:"maxResources,omitempty"`
}

type PlatformStorageClass struct {
	// ClassName is the actual Kubernetes storage class name.
	ClassName string `json:"className" yaml:"className"`
}

type PlatformTLS struct {
	// Mode is the TLS provisioning strategy.
	Mode TLSMode `json:"mode" yaml:"mode"`
	// Issuer is the cert-manager ClusterIssuer or Issuer name.
	// Required when Mode is [TLSModeCertManager].
	Issuer string `json:"issuer,omitempty" yaml:"issuer,omitempty"`
	// SecretName is the pre-existing Kubernetes TLS secret name.
	// Required when Mode is [TLSModeSecretName].
	SecretName string `json:"secretName,omitempty" yaml:"secretName,omitempty"`
}

type ProfileMaxResources struct {
	// CPU is the maximum CPU request (Kubernetes quantity).
	CPU *resource.Quantity `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	// Memory is the maximum memory request (Kubernetes quantity).
	Memory *resource.Quantity `json:"memory,omitempty" yaml:"memory,omitempty"`
}

type ResolutionError struct {
	Code    string
	Message string
}

type ResolutionReport struct {
	// Env is the environment identity used for this resolution.
	Env EnvIdentity
	// Fields is the ordered list of resolved field provenance entries.
	Fields []ResolvedField
	// Warnings is the list of non-fatal warnings emitted during resolution.
	Warnings []string
	// ErrorCode is set when resolution produced a hard error.
	ErrorCode string
	// ErrorMessage is the human-readable error message when ErrorCode is set.
	ErrorMessage string
}

type ResolvedComponent struct {
	// FQDN is the fully qualified domain name resolved for this component.
	// Empty when the component has no expose block.
	FQDN string
	// TLSMode is the TLS provisioning strategy resolved from the platform.
	// Empty when the component has no TLS configuration.
	TLSMode TLSMode
	// TLSIssuer is the cert-manager issuer name (certManager mode only).
	TLSIssuer string
	// TLSSecretName is the pre-existing TLS secret name (secretName mode only).
	TLSSecretName string
	// TLSCertPEM and TLSKeyPEM hold a materialized self-signed certificate
	// (selfSigned mode only), filled in by
	// [k8s.MaterializeSelfSignedTLS] before rendering. Never written into
	// the deployah.resolved chart values block: only fqdn/tlsMode are.
	TLSCertPEM []byte
	TLSKeyPEM  []byte
	// StorageClass is the Kubernetes storage class name resolved from the
	// platform profile's storageClass reference. Empty when no profile sets
	// a storage class.
	StorageClass string
	// Profiles is the ordered list of profile names applied after default
	// prepend. Empty when no profiles apply.
	Profiles []string
	// MergedProfile is the left-to-right merge of Profiles. Nil when no
	// profiles apply.
	MergedProfile *PlatformProfile
	// DomainKey is the logical domain key used for expose resolution.
	// Empty when the component has no expose block.
	DomainKey string
}

type ResolvedField struct {
	// Component is the component name this field belongs to, or empty for
	// top-level fields.
	Component string
	// Path is the spec path, e.g. "expose.host".
	Path string
	// Value is the resolved value as a string.
	Value string
	// Source is a human-readable description of where the value came from,
	// e.g. "platform environments.production.domains.public.baseDomain".
	Source string
}

type ResolvedSpec struct {
	// Spec is the application manifest with defaults applied.
	Spec *Spec
	// Env is the canonical environment identity used for this resolution.
	Env EnvIdentity
	// KubeContext is the Kubernetes context resolved from the platform file.
	// Empty when no platform file was loaded.
	KubeContext string
	// Components holds the per-component resolved data.
	Components map[string]ResolvedComponent
	// Warnings is the list of non-fatal resolution warnings.
	Warnings []string
}

type ResourcePreset string

type Resources struct {
	CPU              *resource.Quantity `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory           *resource.Quantity `json:"memory,omitempty" yaml:"memory,omitempty"`
	EphemeralStorage *resource.Quantity `json:"ephemeralStorage,omitempty" yaml:"ephemeralStorage,omitempty"`
}

type Spec struct {
	// APIVersion is the schema version of the spec (e.g., "v1-alpha.2").
	APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"`
	// Project is the project name.
	Project string `json:"project" yaml:"project"`
	// Environments is a map of environment names to their definitions.
	// The map key is the environment name (e.g. "production", "staging").
	// Context is platform-owned and lives in deployah.platform.yaml.
	Environments map[string]Environment `json:"environments,omitempty" yaml:"environments,omitempty"`
	// Components is a map of component names to their configuration.
	Components map[string]Component `json:"components" yaml:"components"`
}

type SubstitutionReport struct {
	// DynamicSubdomains maps component names to true when the component's
	// expose.subdomain field contained a ${VAR} token before substitution.
	DynamicSubdomains map[string]bool
}

type TLSMode string