config

type AdminConfig struct {
	Enabled      bool   `env:"NSELF_ADMIN_ENABLED"`
	Version      string `env:"NSELF_ADMIN_VERSION"`  // latest
	Port         int    `env:"NSELF_ADMIN_PORT"`     // 3021
	Route        string `env:"NSELF_ADMIN_ROUTE"`    // admin.{BD}
	DevMode      bool   `env:"NSELF_ADMIN_DEV"`      // false
	DevPort      int    `env:"NSELF_ADMIN_DEV_PORT"` // 3000
	SecretKey    string `env:"ADMIN_SECRET_KEY"`
	PasswordHash string `env:"ADMIN_PASSWORD_HASH"`
}

type ApiDocsConfig struct {
	Enabled         bool     `env:"API_DOCS_ENABLED"`      // default: true
	Path            string   `env:"API_DOCS_PATH"`         // serve path, default: /docs
	Title           string   `env:"API_DOCS_TITLE"`        // defaults to "<ProjectName> API"
	Theme           string   `env:"API_DOCS_THEME"`        // default | moon | purple | solarized
	AuthEnvVar      string   `env:"API_DOCS_AUTH_ENV_VAR"` // env var with bearer token for try-out
	HideEndpoints   []string // paths to exclude from the spec
	GraphQLEnabled  bool     `env:"API_DOCS_GRAPHQL_ENABLED"`  // default: true
	GraphQLEndpoint string   `env:"API_DOCS_GRAPHQL_ENDPOINT"` // default: /v1/graphql
}

type AuthConfig struct {
	Version            string `env:"AUTH_VERSION"` // 0.36.0
	Port               int    `env:"AUTH_PORT"`    // 4000
	ClientURL          string `env:"AUTH_CLIENT_URL"`
	AccessTokenExpiry  int    `env:"AUTH_ACCESS_TOKEN_EXPIRES_IN"`  // seconds
	RefreshTokenExpiry int    `env:"AUTH_REFRESH_TOKEN_EXPIRES_IN"` // seconds
	Route              string `env:"AUTH_ROUTE"`
	SMTPHost           string `env:"AUTH_SMTP_HOST"`
	SMTPPort           int    `env:"AUTH_SMTP_PORT"`
	SMTPUser           string `env:"AUTH_SMTP_USER"`
	SMTPPass           string `env:"AUTH_SMTP_PASS"`
	SMTPSecure         bool   `env:"AUTH_SMTP_SECURE"`
	SMTPSender         string `env:"AUTH_SMTP_SENDER"`
	MemLimit           string `env:"AUTH_MEM_LIMIT"`           // 256m
	CPULimit           string `env:"AUTH_CPU_LIMIT"`           // 0.25
	ExtraRedirectURLs  string `env:"AUTH_EXTRA_REDIRECT_URLS"` // comma-separated extra redirect URLs
	WebAuthnEnabled    bool   `env:"AUTH_WEBAUTHN_ENABLED"`
	MFATOTPEnabled     bool   `env:"AUTH_MFA_TOTP_ENABLED"` // false
	LogLevel           string `env:"AUTH_LOG_LEVEL"`        // info
}

type BackupConfig struct {
	Dir           string `env:"BACKUP_DIR"` // ./backups — read by database/backup.go and restore.go
	Enabled       bool   `env:"BACKUP_ENABLED"`
	Schedule      string `env:"BACKUP_SCHEDULE"`       // legacy alias for BACKUP_SCHEDULE_FULL
	RetentionDays int    `env:"BACKUP_RETENTION_DAYS"` // legacy — use Daily/Weekly/Monthly instead
	CloudProvider string `env:"BACKUP_CLOUD_PROVIDER"` // legacy — use Remote instead

	// Cloud/remote storage
	Remote              string `env:"BACKUP_REMOTE"`                // rclone remote path, e.g. s3://bucket/path
	Encryption          bool   `env:"BACKUP_ENCRYPTION"`            // enable age encryption
	AgeRecipients       string `env:"BACKUP_AGE_RECIPIENTS"`        // age public key for encryption
	ScheduleFull        string `env:"BACKUP_SCHEDULE_FULL"`         // cron expr for full backups (default: 0 3 * * *)
	WALInterval         int    `env:"BACKUP_WAL_INTERVAL_SECONDS"`  // WAL archive interval (default: 60)
	RetentionDaily      int    `env:"BACKUP_RETENTION_DAILY"`       // keep last N daily backups (default: 7)
	RetentionWeekly     int    `env:"BACKUP_RETENTION_WEEKLY"`      // keep last N weekly backups (default: 4)
	RetentionMonthly    int    `env:"BACKUP_RETENTION_MONTHLY"`     // keep last N monthly backups (default: 12)
	RestoreTestSchedule string `env:"BACKUP_RESTORE_TEST_SCHEDULE"` // cron for restore tests (default: 0 5 * * 0)
	AlertOnFailure      bool   `env:"BACKUP_ALERT_ON_FAILURE"`      // send alert on backup failure
	S3AccessKeyID       string `env:"BACKUP_S3_ACCESS_KEY_ID"`
	S3SecretAccessKey   string `env:"BACKUP_S3_SECRET_ACCESS_KEY"`
	S3Region            string `env:"BACKUP_S3_REGION"`
	S3Endpoint          string `env:"BACKUP_S3_ENDPOINT"`

	// CriticalTables overrides database.DefaultCriticalTables for the backup
	// drill's smoke check (comma-separated table names, e.g.
	// "users,licenses,audit_logs,plugins"). Empty (the default) keeps the
	// np_-prefixed convention. Deployed schemas vary in whether they use
	// nSelf's np_ multi-app-isolation prefix, so the drill's critical-table
	// presence check must be project-configurable rather than hardcoded to
	// one convention — see .claude/qa/bugs/drill-critical-tables-naming.md.
	CriticalTables string `env:"BACKUP_CRITICAL_TABLES"`
}

type CSDependency struct {
	Name      string
	Condition string
}

type CascadeFile struct {
	// Name is the filename relative to the project directory, e.g. ".env.secrets".
	Name string
	// Path is Name joined with the project directory.
	Path string
	// Exists reports whether the file is present on disk.
	Exists bool
}

type Config struct {
	// Core
	ProjectName        string `env:"PROJECT_NAME"`
	BaseDomain         string `env:"BASE_DOMAIN"`
	Env                string `env:"ENV"` // dev, staging, prod
	ProjectDescription string `env:"PROJECT_DESCRIPTION"`
	AdminEmail         string `env:"ADMIN_EMAIL"`
	DBEnvSeeds         bool   `env:"DB_ENV_SEEDS"`
	// AppName is an OPTIONAL app-prefix used to namespace generated core
	// nginx subdomains (gap #5): when set, routes render as
	// "api.{AppName}.{BASE_DOMAIN}" / "auth.{AppName}.{BASE_DOMAIN}" instead
	// of the bare "api.{BASE_DOMAIN}" / "auth.{BASE_DOMAIN}" scheme. Deliberately
	// distinct from PROJECT_NAME (which is always set, for container/network
	// naming) so existing single-app deployments (ummat, unity) that only set
	// PROJECT_NAME are unaffected — AppName defaults to "" (bare scheme).
	AppName string `env:"APP_NAME"`

	// PostgreSQL
	Postgres PostgresConfig

	// Hasura
	Hasura HasuraConfig

	// Auth
	Auth AuthConfig

	// Nginx
	Nginx NginxConfig

	// SSL
	SSLMode           string `env:"SSL_MODE"`            // local, letsencrypt, custom, none
	SSLProvider       string `env:"SSL_PROVIDER"`        // cloudflare, route53, digitalocean, custom
	SSLWildcardDomain string `env:"SSL_WILDCARD_DOMAIN"` // *.example.com
	ExtraSSLDomains   string `env:"EXTRA_SSL_DOMAINS"`   // comma-separated
	CloudflareAPIKey  string `env:"CLOUDFLARE_API_KEY"`  // DNS-01 challenge

	// WAF
	WAFMode string `env:"WAF_MODE"` // off, detection, blocking

	// Optional Services
	Redis      RedisConfig
	Minio      MinioConfig
	Mailpit    MailpitConfig
	Functions  FunctionsConfig
	MLflow     MLflowConfig
	Admin      AdminConfig
	Monitoring MonitoringConfig

	// Search (provider-agnostic)
	Search SearchConfig

	// Email Provider
	Email EmailConfig

	// PgBouncer connection pooler
	PgBouncer PgBouncerConfig

	// Backup & Recovery
	Backup BackupConfig

	// Disaster Recovery
	DR DRConfig

	// Multi-Tenancy & Billing
	Tenant TenantConfig

	// License
	License LicenseConfig

	// Secrets Management
	Secrets SecretsConfig

	// Plugin Pro Configuration
	PluginConfig PluginProConfig

	// Plugin System
	PluginSystem PluginSystemConfig

	// API Docs (Scalar)
	ApiDocs ApiDocsConfig

	// Custom Services
	CustomServices []CustomService // CS_1..CS_10

	// Frontend Apps
	FrontendApps []FrontendApp // FRONTEND_APP_1..FRONTEND_APP_20

	// Remote Schemas
	RemoteSchemas []RemoteSchema

	// Internal Routes (up to 20)
	InternalRoutes []InternalRoute

	// Docker
	DockerNetwork      string `env:"DOCKER_NETWORK"`
	DockerLogMaxSize   string `env:"DOCKER_LOG_MAX_SIZE"`        // 10m
	DockerLogMaxFile   string `env:"DOCKER_LOG_MAX_FILE"`        // 3
	DockerStopGrace    string `env:"DOCKER_STOP_GRACE_PERIOD"`   // 30s
	DockerBuildTimeout int    `env:"NSELF_DOCKER_BUILD_TIMEOUT"` // 300

	// Start/Stop behavior
	StartMode           string `env:"NSELF_START_MODE"`           // smart, fresh, force
	HealthCheckTimeout  int    `env:"NSELF_HEALTH_CHECK_TIMEOUT"` // seconds
	HealthCheckInterval int    `env:"NSELF_HEALTH_CHECK_INTERVAL"`
	HealthCheckRequired int    `env:"NSELF_HEALTH_CHECK_REQUIRED"` // percentage
	CleanupOnStart      string `env:"NSELF_CLEANUP_ON_START"`      // auto/always/never
	AllowExposedPorts   bool   `env:"NSELF_ALLOW_EXPOSED_PORTS"`
	ParallelLimit       int    `env:"NSELF_PARALLEL_LIMIT"` // 5
	LogLevel            string `env:"NSELF_LOG_LEVEL"`      // info
	SkipHealthChecks    bool   `env:"NSELF_SKIP_HEALTH_CHECKS"`
	StopTimeout         int    `env:"NSELF_STOP_TIMEOUT"` // 30

	// Federation — GraphQL Federation via Apollo Router (G05).
	// When true, nself build injects Apollo Router (CS_7) and composes a
	// supergraph schema from installed plugin subgraphs. Default: false.
	FederationEnabled bool `env:"NSELF_FEDERATION"`

	// EmbeddedPG — when true, nself build omits the Docker postgres service
	// and instead relies on the pglite/wasmtime embedded runtime started by
	// `nself start --embedded-pg`. Hasura is wired via a Unix-domain socket
	// bridge. Default: false.
	EmbeddedPG bool `env:"NSELF_EMBEDDED_PG"`

	// Passthrough: arbitrary env vars matching patterns (AUTH_PROVIDER_*, REMOTE_SCHEMA_*, etc.)
	Passthrough map[string]string
}

type CustomService struct {
	Index int    // 1-10
	Name  string // parsed from CS_N, then overwritten with SanitizeName(Name) for
	// Docker service/container naming (hyphens only, no underscores).
	// RawName preserves the pre-sanitization value.
	//
	// Purpose: a user's CS_N name (e.g. "ping_api") may contain underscores,
	// which are valid in a directory name but not in a Docker compose
	// service/container name. parseCustomServices sanitizes Name for that
	// reason, but internal/compose.defaultCustomServiceBuildContext needs
	// the original spelling to find the on-disk `services/<name>` directory
	// the user actually created — using the sanitized Name there produced a
	// build context ("./services/ping-api") that never matched an existing
	// directory ("./services/ping_api"), so the image build failed for any
	// name containing an underscore (see the F13/G-013-adjacent bug this
	// field fixes). Empty when a CustomService is constructed by hand
	// (tests, scaffolding) rather than through parseCustomServices.
	RawName     string
	Template    string // express-ts, fastapi, etc.
	Port        int
	Route       string // empty = internal only
	Public      bool
	Memory      string
	CPU         string
	TablePrefix string // CS_N_TABLE_PREFIX
	ExtraEnv    string // CS_N_ENV (raw key=val pairs, comma-separated)
	BuildPath   string // CS_N_PATH: overrides default ./services/{name} build context

	// HealthCheck is CS_N_HEALTHCHECK: a path (e.g. "/auth/health"), a full
	// "CMD ..." / "CMD-SHELL ..." override, or "disabled"/"none"/"false" to
	// omit the healthcheck entirely. Empty keeps the default GET /health.
	HealthCheck string

	// EnvPassthrough is CS_N_ENV_PASSTHROUGH: a comma-separated allowlist of
	// project .env var names to forward into this container in addition to
	// the fixed core set from coreEnvVars. CS_N_ENV still wins on conflict.
	EnvPassthrough string

	// Image is CS_N_IMAGE: a pre-built image reference (optionally digest-pinned,
	// e.g. "minio/minio:RELEASE.2024-01-16T16-07-38Z@sha256:...") to run instead
	// of building from a Dockerfile. When set, the compose generator emits
	// `image:` and omits `build:` entirely — mutually exclusive with
	// CS_N_PATH (G-013: closes the gap where a pinned third-party image had
	// no CS_N representation and had to be hand-authored into
	// docker-compose.override.yml).
	Image string

	// EnvFile is CS_N_ENV_FILE: a project-relative path to a dotenv-format
	// file whose KEY=VALUE lines are injected into this container. Unlike
	// CS_N_ENV (a single comma-joined line), a file has no comma/newline
	// escaping problem, so it is the right vehicle for many vars or values
	// that themselves contain commas (e.g. SMTP credentials). Precedence:
	// applied after CS_N_ENV_PASSTHROUGH, before CS_N_ENV (CS_N_ENV always
	// wins on conflict, per the existing coreEnvVars contract). Same
	// relative-path rules as BuildPath (no absolute paths, no "..").
	EnvFile string

	// Volumes is CS_N_VOLUMES: a comma-separated list of extra Docker volume
	// mounts in "host:container[:mode]" form (e.g.
	// "./email-templates:/app/templates:ro"), appended to the service's
	// generated volume list. Closes the gap where a required bind mount
	// (e.g. a template directory) had no CS_N representation.
	Volumes string

	// EnvFiles is CS_N_ENV_FILE split on commas, in load order (later wins).
	// EnvFile stays the first entry for callers that read it.
	EnvFiles []string

	// DependsOn is CS_N_DEPENDS_ON: extra compose depends_on entries. Names
	// are syntax-checked here and resolved against the whole project in build
	// post-validation (after the plugin step).
	DependsOn []CSDependency

	// Networks is CS_N_NETWORKS: extra project networks, each
	// <PROJECT_NAME>_*, emitted as external networks (checked at compose time).
	Networks []string

	// Dockerfile is CS_N_DOCKERFILE: path relative to the build context.
	Dockerfile string

	// BuildTarget is CS_N_BUILD_TARGET: the multi-stage build target.
	BuildTarget string

	// Command is CS_N_COMMAND: exec-form command (whitespace-split, no shell).
	Command []string
}

type DRConfig struct {
	SecondaryRegion string `env:"DR_SECONDARY_REGION"` // Hetzner region for standby
	StandbyHost     string `env:"DR_STANDBY_HOST"`     // IP/hostname of warm standby
	DrillSchedule   string `env:"DR_DRILL_SCHEDULE"`   // cron for DR drills (default: off)
}

type ElasticsearchConfig struct {
	Version  string `env:"ELASTICSEARCH_VERSION"` // 8.11.3
	Port     int    `env:"ELASTICSEARCH_PORT"`    // 9200
	Password string `env:"ELASTICSEARCH_PASSWORD"`
	Memory   string `env:"ELASTICSEARCH_MEMORY"` // 1Gi
}

type EmailConfig struct {
	Provider            string `env:"EMAIL_PROVIDER"` // mailpit/elasticemail/sendgrid/postmark/mailgun/ses/smtp
	From                string `env:"EMAIL_FROM"`
	ElasticEmailAPIKey  string `env:"ELASTIC_EMAIL_API_KEY"`
	ElasticEmailAccount string `env:"ELASTIC_EMAIL_ACCOUNT_EMAIL"`
	SendGridAPIKey      string `env:"SENDGRID_API_KEY"`
	PostmarkAPIKey      string `env:"POSTMARK_API_KEY"`
	MailgunAPIKey       string `env:"MAILGUN_API_KEY"`
	MailgunDomain       string `env:"MAILGUN_DOMAIN"`
	AWSAccessKeyID      string `env:"AWS_ACCESS_KEY_ID"`
	AWSSecretAccessKey  string `env:"AWS_SECRET_ACCESS_KEY"`
	AWSRegion           string `env:"AWS_REGION"`
	SMTPHost            string `env:"SMTP_HOST"`
	SMTPPort            int    `env:"SMTP_PORT"`
	SMTPUser            string `env:"SMTP_USER"`
	SMTPPass            string `env:"SMTP_PASS"`
	SMTPSecure          bool   `env:"SMTP_SECURE"`
}

type Explanation struct {
	// Key is the variable name asked about.
	Key string
	// Known reports whether the key is in KnownEnvVars().
	Known bool
	// Default is DefaultFor(Key); empty when the key has no static default.
	Default string
	// Env is the active environment name the cascade was built for.
	Env string
	// EnvSource is where Env came from (ResolveEnv: "process environment",
	// ".env" or "default"); empty when the caller passed Env directly.
	EnvSource string
	// Legacy reports that NSELF_LEGACY_ENV_ORDER selected the legacy order.
	Legacy bool
	// Cascade is every file the loader consults, lowest precedence first.
	Cascade []CascadeFile
	// Setters are the existing cascade files that set the key, in cascade order.
	Setters []Setter
	// ProcessSet and ProcessValue describe the process environment.
	ProcessSet   bool
	ProcessValue string
}

type FrontendApp struct {
	Index       int
	DisplayName string
	SystemName  string
	Port        int
	Route       string
	Framework   string
	TablePrefix string
	Image       string // FRONTEND_APP_N_IMAGE (optional docker image reference)
}

type FunctionsConfig struct {
	Enabled bool   `env:"FUNCTIONS_ENABLED"`
	Version string `env:"FUNCTIONS_VERSION"` // latest
	Port    int    `env:"FUNCTIONS_PORT"`    // 3008
	Route   string `env:"FUNCTIONS_ROUTE"`   // functions.{BD}

	// Runtime selects the container image: node (default), deno, python.
	Runtime string `env:"FUNCTIONS_RUNTIME"` // node|deno|python

	// Resource limits for the functions container.
	Memory  string `env:"FUNCTIONS_MEMORY"`  // 256M
	CPU     string `env:"FUNCTIONS_CPU"`     // 0.5
	Timeout string `env:"FUNCTIONS_TIMEOUT"` // 30s
}

type HasuraConfig struct {
	Version     string `env:"HASURA_VERSION"`
	AdminSecret string `env:"HASURA_GRAPHQL_ADMIN_SECRET"`
	JWTKey      string `env:"HASURA_JWT_KEY"`
	JWTType     string `env:"HASURA_JWT_TYPE"` // HS256
	Console     bool   `env:"HASURA_GRAPHQL_ENABLE_CONSOLE"`
	DevMode     bool   `env:"HASURA_GRAPHQL_DEV_MODE"`
	CORSDomain  string `env:"HASURA_GRAPHQL_CORS_DOMAIN"`
	Route       string `env:"HASURA_ROUTE"` // api.{BASE_DOMAIN}
	Port        int    `env:"HASURA_PORT"`  // 8080
	MemLimit    string `env:"HASURA_MEM_LIMIT"`
	CPULimit    string `env:"HASURA_CPU_LIMIT"`
	LogLevel    string `env:"HASURA_GRAPHQL_LOG_LEVEL"` // warn
}

type InternalRoute struct {
	Index     int
	Name      string // INTERNAL_ROUTE_N_NAME
	Subdomain string // INTERNAL_ROUTE_N_SUBDOMAIN
	Target    string // INTERNAL_ROUTE_N_TARGET (e.g., hasura:8080)
	RateZone  string // INTERNAL_ROUTE_N_RATE_ZONE (default: general)
	WebSocket bool   // INTERNAL_ROUTE_N_WEBSOCKET
}

type LicenseConfig struct {
	PingURL           string    `env:"LICENSE_PING_URL"`            // https://ping.nself.org
	CachePath         string    `env:"LICENSE_CACHE_PATH"`          // ~/.cache/nself/license.json
	CheckInterval     string    `env:"LICENSE_CHECK_INTERVAL"`      // 6h
	OfflineMode       bool      `env:"LICENSE_OFFLINE_MODE"`        // false
	PublicKeyOverride string    `env:"LICENSE_PUBLIC_KEY_OVERRIDE"` // hex-encoded Ed25519 pubkey for testing
	SunsetAt          time.Time `env:"LICENSE_SUNSET_AT"`           // optional hard cutoff; zero = no sunset
}

type LoadOptions struct {
	// RemoteDeploy drops .env.local from the cascade: the build is for a
	// remote host, and a developer's personal override must not reach it (the
	// env file pushed to the host omits it too).
	RemoteDeploy bool
	// EnvOverlay replaces cascade files by name (".env", ".env.secrets", ...)
	// with the given bytes for this load only: the disk copy of an overlaid
	// name is not read and need not exist. A plan uses it to load the cascade
	// a pending `config set` will leave before the line is written
	// (P7-LIVE-05, env_overlay.go). Nil reads every file from disk.
	EnvOverlay map[string][]byte
}

type Loader interface {
	Load(dir string) (*Config, error)
}

type MLflowConfig struct {
	Enabled         bool   `env:"MLFLOW_ENABLED"`
	Route           string `env:"MLFLOW_ROUTE"`            // mlflow.{BD} — read by ssl/domains.go, urls.go, doctor.go
	Version         string `env:"MLFLOW_VERSION"`          // plugin-managed: populated by nself plugin install mlflow
	Port            int    `env:"MLFLOW_PORT"`             // read by doctor.go for port-conflict checks; plugin-managed: populated by nself plugin install mlflow
	DBName          string `env:"MLFLOW_DB_NAME"`          // plugin-managed: populated by nself plugin install mlflow
	ArtifactsBucket string `env:"MLFLOW_ARTIFACTS_BUCKET"` // plugin-managed: populated by nself plugin install mlflow
	AuthEnabled     bool   `env:"MLFLOW_AUTH_ENABLED"`     // plugin-managed: populated by nself plugin install mlflow
	AuthUsername    string `env:"MLFLOW_AUTH_USERNAME"`    // plugin-managed: populated by nself plugin install mlflow
	AuthPassword    string `env:"MLFLOW_AUTH_PASSWORD"`    // plugin-managed: populated by nself plugin install mlflow
}

type MailpitConfig struct {
	Enabled     bool   `env:"MAILPIT_ENABLED"`
	Version     string `env:"MAILPIT_VERSION"`      // latest
	SMTPPort    int    `env:"MAILPIT_SMTP_PORT"`    // 1025
	UIPort      int    `env:"MAILPIT_UI_PORT"`      // 8025
	MaxMessages int    `env:"MAILPIT_MAX_MESSAGES"` // 500
	Route       string `env:"MAILPIT_ROUTE"`        // mail.{BD}
	UIUser      string `env:"MAILPIT_UI_USER"`      // admin (default)
	UIPassword  string `env:"MAILPIT_UI_PASSWORD"`
}

type MeiliSearchConfig struct {
	Version   string `env:"MEILISEARCH_VERSION"` // v1.6
	MasterKey string `env:"MEILISEARCH_MASTER_KEY"`
	Env       string `env:"MEILISEARCH_ENV"` // development
}

type MinioConfig struct {
	Enabled        bool   `env:"MINIO_ENABLED"`
	Version        string `env:"MINIO_VERSION"`         // latest
	Port           int    `env:"MINIO_PORT"`            // 9000
	ConsolePort    int    `env:"MINIO_CONSOLE_PORT"`    // 9001
	RootUser       string `env:"MINIO_ROOT_USER"`       // minioadmin
	RootPassword   string `env:"MINIO_ROOT_PASSWORD"`   // minioadmin
	DefaultBuckets string `env:"MINIO_DEFAULT_BUCKETS"` // uploads,public,private,temp
	Region         string `env:"MINIO_REGION"`          // us-east-1
	S3AccessKey    string `env:"S3_ACCESS_KEY"`
	S3SecretKey    string `env:"S3_SECRET_KEY"`
	S3Bucket       string `env:"S3_BUCKET"`             // nself
	StorageVersion string `env:"STORAGE_VERSION"`       // 0.6.1
	StorageRoute   string `env:"STORAGE_ROUTE"`         // storage.{BD}
	ConsoleRoute   string `env:"STORAGE_CONSOLE_ROUTE"` // storage-console.{BD}
	MemLimit       string `env:"MINIO_MEMORY"`          // 1G
	CPULimit       string `env:"MINIO_CPU"`             // 0.5
}

type MonitoringConfig struct {
	Enabled              bool   `env:"MONITORING_ENABLED"`
	GrafanaEnabled       bool   `env:"GRAFANA_ENABLED"`
	GrafanaRoute         string `env:"GRAFANA_ROUTE"`             // read by ssl/domains.go, urls.go, doctor.go
	GrafanaAdminPassword string `env:"GRAFANA_ADMIN_PASSWORD"`    // read by config/validator.go
	PrometheusEnabled    bool   `env:"PROMETHEUS_ENABLED"`        // plugin-managed: populated by nself plugin install monitoring
	PrometheusPort       int    `env:"PROMETHEUS_PORT"`           // plugin-managed: populated by nself plugin install monitoring
	GrafanaPort          int    `env:"GRAFANA_PORT"`              // read by urls.go and doctor.go for port display; plugin-managed: populated by nself plugin install monitoring
	GrafanaAdminUser     string `env:"GRAFANA_ADMIN_USER"`        // plugin-managed: populated by nself plugin install monitoring
	LokiEnabled          bool   `env:"LOKI_ENABLED"`              // plugin-managed: populated by nself plugin install monitoring
	LokiPort             int    `env:"LOKI_PORT"`                 // plugin-managed: populated by nself plugin install monitoring
	PromtailEnabled      bool   `env:"PROMTAIL_ENABLED"`          // plugin-managed: populated by nself plugin install monitoring
	TempoEnabled         bool   `env:"TEMPO_ENABLED"`             // plugin-managed: populated by nself plugin install monitoring
	TempoPort            int    `env:"TEMPO_PORT"`                // plugin-managed: populated by nself plugin install monitoring
	AlertmanagerEnabled  bool   `env:"ALERTMANAGER_ENABLED"`      // plugin-managed: populated by nself plugin install monitoring
	AlertmanagerPort     int    `env:"ALERTMANAGER_PORT"`         // plugin-managed: populated by nself plugin install monitoring
	CadvisorEnabled      bool   `env:"CADVISOR_ENABLED"`          // plugin-managed: populated by nself plugin install monitoring
	CadvisorPort         int    `env:"CADVISOR_PORT"`             // plugin-managed: populated by nself plugin install monitoring
	NodeExporterEnabled  bool   `env:"NODE_EXPORTER_ENABLED"`     // plugin-managed: populated by nself plugin install monitoring
	NodeExporterPort     int    `env:"NODE_EXPORTER_PORT"`        // plugin-managed: populated by nself plugin install monitoring
	PGExporterEnabled    bool   `env:"POSTGRES_EXPORTER_ENABLED"` // plugin-managed: populated by nself plugin install monitoring
	PGExporterPort       int    `env:"POSTGRES_EXPORTER_PORT"`    // plugin-managed: populated by nself plugin install monitoring
	RedisExporterEnabled bool   `env:"REDIS_EXPORTER_ENABLED"`    // plugin-managed: populated by nself plugin install monitoring
	RedisExporterPort    int    `env:"REDIS_EXPORTER_PORT"`       // plugin-managed: populated by nself plugin install monitoring

	// S34 additions
	PrometheusRetention      string `env:"PROMETHEUS_RETENTION"`       // e.g. "30d"
	LokiHotDays              int    `env:"LOKI_HOT_DAYS"`              // default 30
	LokiColdDays             int    `env:"LOKI_COLD_DAYS"`             // default 365
	AlertmanagerPagerdutyKey string `env:"ALERTMANAGER_PAGERDUTY_KEY"` // PagerDuty integration key

	// Watchdog
	WatchdogEnabled                bool   `env:"WATCHDOG_ENABLED"`
	WatchdogCircuitBreakerAttempts int    `env:"WATCHDOG_CIRCUIT_BREAKER_ATTEMPTS"` // default 3
	WatchdogCircuitBreakerWindow   string `env:"WATCHDOG_CIRCUIT_BREAKER_WINDOW"`   // default 10m
	WatchdogEscalationWebhook      string `env:"WATCHDOG_ESCALATION_WEBHOOK"`

	// Queue/Jobs
	QueueWorkersPerQueue   int `env:"QUEUE_WORKERS_PER_QUEUE"`   // default 2
	QueueDLQAlertThreshold int `env:"QUEUE_DLQ_ALERT_THRESHOLD"` // default 100

	// Promotion
	PromoteRequiresTwoApprovers bool `env:"PROMOTE_REQUIRES_TWO_APPROVERS"`
}

type NginxConfig struct {
	Version       string `env:"NGINX_VERSION"`              // alpine
	HTTPPort      int    `env:"NGINX_HTTP_PORT"`            // 80
	SSLPort       int    `env:"NGINX_HTTPS_PORT"`           // 443
	MaxBody       string `env:"NGINX_CLIENT_MAX_BODY_SIZE"` // 100M
	BindIP        string `env:"NGINX_BIND_IP"`              // computed: 127.0.0.1 (dev) or 0.0.0.0 (prod) — overridable
	AuthRateLimit string `env:"AUTH_RATE_LIMIT"`            // 30r/m
	RateLimitAPI  string `env:"RATE_LIMIT_API_RPS"`         // 30
	RateLimitAuth string `env:"RATE_LIMIT_AUTH_RPS"`        // 5
	RateLimitAI   string `env:"RATE_LIMIT_AI_RPS"`          // 10

	// FrontedBy names the stack whose nginx fronts this project's domains
	// (e.g. "nself-web"), when this project has no ingress nginx of its own.
	// Empty (the default) means this stack runs its own nginx, unchanged
	// from every prior release.
	//
	// When set, `nself build` omits the nginx service from
	// docker-compose.yml entirely and excludes it from the service counts
	// `nself status`/`nself start` expect. Without this, a stack meant to
	// sit behind another stack's nginx still generates and tries to start
	// its own nginx container, which fails to bind 80/443 (already held by
	// the fronting stack's nginx via docker-proxy) and then sits forever as
	// one unhealthy service nself status can never clear ("6/7" on ntask's
	// staging deploy, 2026-09-03, fronted by nself-web).
	//
	// This flag only removes the container that can never run. It does NOT
	// wire this project's containers onto the fronting stack's Docker
	// network — the fronting nginx's `resolver 127.0.0.11` can only reach
	// container names on a network it is attached to, so making
	// auth.task.staging.nself.org resolve ntask_auth still requires the
	// operator to attach the two projects' networks (or declare one as
	// external in both compose files) by hand. That is a bigger, riskier
	// change — automatically rewriting a Docker network topology from a
	// per-project flag — and belongs in a follow-up once the desired shape
	// of that wiring is decided.
	FrontedBy string `env:"NGINX_FRONTED_BY"`
}

type PgBouncerConfig struct {
	Enabled           bool   `env:"PGBOUNCER_ENABLED"`
	Port              int    `env:"PGBOUNCER_PORT"`                // 6432
	PoolMode          string `env:"PGBOUNCER_POOL_MODE"`           // session, transaction, statement
	MaxClientConn     int    `env:"PGBOUNCER_MAX_CLIENT_CONN"`     // 100
	DefaultPoolSize   int    `env:"PGBOUNCER_DEFAULT_POOL_SIZE"`   // 25
	MinPoolSize       int    `env:"PGBOUNCER_MIN_POOL_SIZE"`       // 5
	ReservePoolSize   int    `env:"PGBOUNCER_RESERVE_POOL_SIZE"`   // 5
	ServerIdleTimeout int    `env:"PGBOUNCER_SERVER_IDLE_TIMEOUT"` // 600
	LogConnections    bool   `env:"PGBOUNCER_LOG_CONNECTIONS"`     // false
	LogDisconnections bool   `env:"PGBOUNCER_LOG_DISCONNECTIONS"`  // false
	AdminUsers        string `env:"PGBOUNCER_ADMIN_USERS"`         // postgres
	StatsUsers        string `env:"PGBOUNCER_STATS_USERS"`         // postgres
}

type PluginProConfig struct {
	NotifySecret    string `env:"NOTIFY_INTERNAL_SECRET"`
	NotifyPort      int    `env:"NOTIFY_PORT"` // 3712
	NotifyVAPIDPub  string `env:"NOTIFY_VAPID_PUBLIC_KEY"`
	NotifyVAPIDPriv string `env:"NOTIFY_VAPID_PRIVATE_KEY"`
	NotifyRoute     string `env:"NOTIFY_ROUTE"`
	CronSecret      string `env:"CRON_INTERNAL_SECRET"`
	CronPort        int    `env:"CRON_PORT"`                   // 3713
	CronRetention   int    `env:"CRON_RETENTION_DAYS"`         // 90
	AIMemLimit      string `env:"PLUGIN_AI_MEMORY_LIMIT"`      // 1g
	AICPULimit      string `env:"PLUGIN_AI_CPU_LIMIT"`         // 1.0
	MuxMemLimit     string `env:"PLUGIN_MUX_MEMORY_LIMIT"`     // 512m
	MuxCPULimit     string `env:"PLUGIN_MUX_CPU_LIMIT"`        // 0.5
	ClawMemLimit    string `env:"PLUGIN_CLAW_MEMORY_LIMIT"`    // 512m
	ClawCPULimit    string `env:"PLUGIN_CLAW_CPU_LIMIT"`       // 0.5
	DefaultMemLimit string `env:"PLUGIN_DEFAULT_MEMORY_LIMIT"` // 512m
	DefaultCPULimit string `env:"PLUGIN_DEFAULT_CPU_LIMIT"`    // 0.5
}

type PluginSystemConfig struct {
	Dir            string `env:"NSELF_PLUGIN_DIR"`         // ~/.nself/plugins
	Cache          string `env:"NSELF_PLUGIN_CACHE"`       // ~/.nself/cache/plugins
	Registry       string `env:"NSELF_PLUGIN_REGISTRY"`    // https://plugins.nself.org
	CacheTTL       int    `env:"NSELF_REGISTRY_CACHE_TTL"` // 300
	LicenseKey     string `env:"NSELF_PLUGIN_LICENSE_KEY"`
	SkipVerify     bool   `env:"NSELF_LICENSE_SKIP_VERIFY"`
	PingURL        string `env:"NSELF_PING_API_URL"` // https://ping.nself.org
	PricingURL     string `env:"NSELF_PRICING_URL"`  // https://nself.org/pricing
	InternalSecret string `env:"PLUGIN_INTERNAL_SECRET"`
}

type PostgresConfig struct {
	Version string `env:"POSTGRES_VERSION"` // 16-alpine
	// Image, when set, is the exact postgres image nself build emits and wins
	// over every other resolution (see compose.ResolvePostgresImage). Set this
	// to pin a running image (e.g. pgvector/pgvector:pg16) across regens
	// without relying on POSTGRES_EXTENSIONS inference (cli#384).
	Image      string   `env:"POSTGRES_IMAGE"`
	Host       string   `env:"POSTGRES_HOST"` // postgres (container name)
	Port       int      `env:"POSTGRES_PORT"` // 5432
	DB         string   `env:"POSTGRES_DB"`   // nself
	User       string   `env:"POSTGRES_USER"` // postgres
	Password   string   `env:"POSTGRES_PASSWORD"`
	Extensions []string `env:"POSTGRES_EXTENSIONS"`  // comma-separated list
	ExposePort string   `env:"POSTGRES_EXPOSE_PORT"` // auto, true, false
	MemLimit   string   `env:"POSTGRES_MEM_LIMIT"`   // 2g
	CPULimit   string   `env:"POSTGRES_CPU_LIMIT"`   // 2.0
	// MaxConnections overrides Postgres max_connections. The stock default of
	// 100 exhausts under a multi-service stack (PERF-POOL-01); nself raises it.
	MaxConnections int `env:"POSTGRES_MAX_CONNECTIONS"` // default 200
}

type RedisConfig struct {
	Enabled  bool   `env:"REDIS_ENABLED"`
	Version  string `env:"REDIS_VERSION"`   // 7-alpine
	Port     int    `env:"REDIS_PORT"`      // 6379
	Password string `env:"REDIS_PASSWORD"`  // empty = no auth
	Memory   string `env:"REDIS_MEMORY"`    // 512M
	CPU      string `env:"REDIS_CPU"`       // 0.5
	PoolSize int    `env:"REDIS_POOL_SIZE"` // 50 (prod default); use 20 for dev
	// Engine is REDIS_ENGINE: "valkey" or "redis" (lower case), or "" when not
	// set. Empty is resolved at generation (internal/compose cacheEngine): the
	// engine of the project lock's redis pin, else the mode default.
	Engine string `env:"REDIS_ENGINE"`
}

type RemoteSchema struct {
	Index   int
	Name    string
	URL     string
	Headers string // key:val,key:val
}

type SearchConfig struct {
	Enabled     bool   `env:"SEARCH_ENABLED"`
	Engine      string `env:"SEARCH_ENGINE"`  // meilisearch, typesense, etc.
	Port        int    `env:"SEARCH_PORT"`    // auto from provider
	APIKey      string `env:"SEARCH_API_KEY"` // auto-generated if unset
	Route       string `env:"SEARCH_ROUTE"`   // search.{BD}
	IndexPrefix string `env:"SEARCH_INDEX_PREFIX"`
	AutoIndex   bool   `env:"SEARCH_AUTO_INDEX"` // true
	Language    string `env:"SEARCH_LANGUAGE"`   // en

	// Provider-specific (only populated for active provider)
	MeiliSearch   MeiliSearchConfig
	Typesense     TypesenseConfig
	Elasticsearch ElasticsearchConfig
}

type SecretsConfig struct {
	AgeKeyPath   string `env:"SECRETS_AGE_KEY_PATH"` // ~/.config/nself/age-key.txt
	DeployAgeKey string `env:"DEPLOY_AGE_KEY"`       // raw age private key for CI/CD
}

type Setter struct {
	// File is the cascade file name relative to the project directory.
	File string
	// Value is the value the file sets, in clear.
	Value string
}

type TelemetryPreference struct {
	// Enabled is the stored preference from config.toml.
	// This value is overridden to false when NSELF_TELEMETRY_OPT_OUT=1 is set.
	Enabled bool

	// Source describes where the value came from: "env", "config", or "default".
	Source string
}

type TenantConfig struct {
	DefaultPlan             string `env:"TENANT_DEFAULT_PLAN"`               // basic
	DestroyBackupRetainDays int    `env:"TENANT_DESTROY_BACKUP_RETAIN_DAYS"` // 90
	StripeSecretKey         string `env:"STRIPE_SECRET_KEY"`
	StripeWebhookSecret     string `env:"STRIPE_WEBHOOK_SECRET"`
	StripeAPIVersion        string `env:"STRIPE_API_VERSION"` // 2024-04-10
}

type TypesenseConfig struct {
	Version           string `env:"TYPESENSE_VERSION"` // 27.1
	APIKey            string `env:"TYPESENSE_API_KEY"`
	EnableCORS        bool   `env:"TYPESENSE_ENABLE_CORS"`
	LogLevel          string `env:"TYPESENSE_LOG_LEVEL"`
	NumMemoryShards   int    `env:"TYPESENSE_NUM_MEMORY_SHARDS"`
	SnapshotIntervalS int    `env:"TYPESENSE_SNAPSHOT_INTERVAL_SECONDS"`
}

type ValidatorFunc struct {
	Name string
	Fn   func(*Config) error
}

type ValidatorResult struct {
	Name string
	Err  error
}