cue

package
v0.39.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package cue provides CUE schema validation and Terraform bridge for StackKits.

Package cue provides CUE schema validation and Terraform bridge for StackKits.

CatalogEntry drives domain computation and dashboard generation. Data is extracted from module CUE contracts (#ServiceDefinition.subdomain + .dashboard). Services without module contracts (coolify, dockge) are included as fallbacks.

Package cue provides CUE schema validation for StackKits.

Index

Constants

View Source 
const (
	SupportSupported    = "supported"
	SupportScaffolding  = "scaffolding"
	SupportUnsupported  = "unsupported"
	SupportControlPlane = "control-plane"
)

Support levels of a mode-matrix cell (foundation/mode_matrix.cue #SupportLevel).

View Source 
const (
	ProductionGradeProduction      = "production"
	ProductionGradeLocalProduction = "local-production"
	ProductionGradeReference       = "reference"
	ProductionGradeExperimental    = "experimental"

	ProductionAuthPolicyLoginGateway = "login-gateway"
	ProductionAuthPolicySelfAuth     = "self-auth"
	ProductionAuthPolicyPublic       = "public"
	ProductionAuthPolicyInternal     = "internal"

	ProductionBackupRestoreNone = "not-applicable"
)

Variables

This section is empty.

Functions

func CanonicalJSON 

func CanonicalJSON(v interface{}) ([]byte, error)

CanonicalJSON returns a deterministic JSON encoding of v with sorted map keys, no indentation, and stable array ordering for primitive-only arrays. This is the canonical form used to compute module contract hashes.

func ContractHash 

func ContractHash(v interface{}) (string, error)

ContractHash computes the SHA256 of the canonical-JSON encoding of v. Return is the 64-character lowercase hex string stored in sk_module_version.contract_hash.

func GenerateAppsTF 

func GenerateAppsTF(spec *models.StackSpec, outputDir string) error

GenerateAppsTF writes PaaS handoff manifests for user applications declared in StackSpec.apps. StackKit produces the compose/manifest boundary; the selected PaaS owns user app deployment and lifecycle.

func KitDeclaresModeMatrix 

func KitDeclaresModeMatrix(kitDir string) bool

KitDeclaresModeMatrix reports whether <kitDir> ships a mode_matrix.cue file. It lets callers fail closed: a kit that DECLARES a matrix but whose matrix fails to load is a real error, whereas a legacy exported kit cache without the file legitimately skips enforcement.

func ModulesByName 

func ModulesByName(modules []ModuleContract) map[string]ModuleContract

ModulesByName returns a map of module name → ModuleContract for quick lookup.

Types

type AccessPolicyDef 

type AccessPolicyDef struct {
	OuterAuth string
	AppAuth   string
}

AccessPolicyDef mirrors #ServiceDefinition.accessPolicy. Traefik-routed services must declare an outer auth posture (Golden Rules §4.1/§4.8).

type CatalogEntry 

type CatalogEntry struct {
	// Key in Terraform local.domains map (e.g., "dashboard", "auth")
	Key string
	// Subdomain for own-domain mode: {Nested}.{domain}
	Nested string
	// Subdomain for flat/kombify.me mode: {prefix}-{Flat}.{domain}
	Flat string
	// Human-readable service name
	DisplayName string
	// Tool/service implementation name from CUE
	ToolName string
	// Module slug that owns this service
	ModuleSlug string
	// Short description for dashboard card
	Description string
	// HTML entity for dashboard icon (e.g., "&#128100;")
	Icon string
	// Layer badge label (e.g., "L1 · IdP")
	Badge string
	// Dashboard section: "Platform" or "Applications"
	Section string
	// Display order within section (lower = first)
	Order int
	// Terraform enable variable name. Empty = always shown.
	EnableVar string
	// Public Mintlify guide URL for this service.
	GuideURL string
}

CatalogEntry describes a service for domain computation and dashboard generation. Fields correspond to #ServiceDefinition.subdomain and #ServiceDefinition.dashboard in CUE.

func DomainEntriesFromModules 

func DomainEntriesFromModules(modulesDir string) ([]CatalogEntry, error)

DomainEntriesFromModules returns ALL services that need a local.domains entry, including services that don't appear in the dashboard (e.g., dashboard, dozzle).

func ServiceCatalogFromModules 

func ServiceCatalogFromModules(modulesDir string) ([]CatalogEntry, error)

ServiceCatalogFromModules reads all module contracts and builds the canonical service catalog.

type EndpointDef 

type EndpointDef struct {
	URL         string
	Internal    bool
	Description string
}

EndpointDef represents an endpoint provided by a module.

type Extractor 

type Extractor struct {
	// contains filtered or unexported fields
}

Extractor reads CUE service definitions and returns Go structs.

func NewExtractor 

func NewExtractor(stackkitDir string) *Extractor

NewExtractor creates a new CUE service extractor.

func (*Extractor) ExtractServicesFromModules 

func (e *Extractor) ExtractServicesFromModules(modulesDir string) ([]ServiceDef, error)

ExtractServicesFromModules scans the modules directory and extracts services from each module's Contract. This replaces the legacy variant-based extraction.

type Generator 

type Generator struct {
	// contains filtered or unexported fields
}

Generator produces per-module OpenTofu fragments from resolved module contracts.

func NewGenerator 

func NewGenerator(domain string) *Generator

NewGenerator creates a new OpenTofu generator.

func NewGeneratorWithVariables 

func NewGeneratorWithVariables(domain string, variables map[string]any) *Generator

NewGeneratorWithVariables creates a generator that also knows the tfvars keys available to generated fragments.

func (*Generator) GenerateAll 

func (g *Generator) GenerateAll(graph *ModuleGraph, outputDir string) error

GenerateAll produces OpenTofu files for all modules in the resolved graph. Output structure: 

outputDir/
  providers.tf      — shared provider config
  networks.tf       — shared Docker networks
  variables.tf      — all variable declarations
  terraform.tfvars.json — variable values
  traefik.tf        — per-module resource definitions
  tinyauth.tf
  ...

func (*Generator) WithDockerMemoryLimits 

func (g *Generator) WithDockerMemoryLimits(enabled bool) *Generator

WithDockerMemoryLimits controls whether generated docker_container resources include memory and memory_swap fields from module contracts.

type HealthCheckDef 

type HealthCheckDef struct {
	Test        []string
	Path        string
	Port        int
	Scheme      string
	Interval    string
	Timeout     string
	Retries     int
	StartPeriod string
}

HealthCheckDef represents a health check.

type InfraRequirements 

type InfraRequirements struct {
	Docker            bool
	Network           string
	DockerSocket      bool
	PersistentStorage bool
	MinMemory         string
	Arch              string
}

InfraRequirements declares infrastructure needs.

type KitModeMatrix 

type KitModeMatrix struct {
	Kit       string
	Placement map[string]string
	Install   map[string]string
	Context   map[string]string
	Paas      map[string]string
	Evidence  []string
}

KitModeMatrix is the Go projection of a kit's #KitModeSupport declaration.

func LoadKitModeMatrix 

func LoadKitModeMatrix(kitDir string) (*KitModeMatrix, error)

LoadKitModeMatrix loads <kitDir>'s CUE package and decodes its modeMatrix. Kits without a declaration (e.g. older exported kit caches) return an error; callers treat that as "matrix enforcement unavailable", not as a failure.

func (*KitModeMatrix) CellVerdict 

func (m *KitModeMatrix) CellVerdict(placementMode, installMode, nodeContext string) (level string, details []string)

CellVerdict grades the (placement, install, context) cell of this kit. Returned level is the worst across the three axes (unsupported > control-plane > scaffolding > supported); details name the axes that caused a non-supported verdict.

type MiddlewareDef 

type MiddlewareDef struct {
	Type        string
	Description string
}

MiddlewareDef represents a Traefik middleware provided by a module.

type ModuleContract 

type ModuleContract struct {
	Metadata     ModuleMetadata
	Delivery     *ModuleDelivery
	Requires     *RequiresSpec
	Provides     *ProvidesSpec
	Settings     *SettingsSpec
	Services     map[string]ServiceDef
	Provisioners map[string]ProvisionerDef
	Enabled      bool
	// Placement is the module's placement eligibility (#PlacementSupport).
	// nil means the module did not declare it; the CUE safe-open defaults
	// apply (eligible for local-only/standard, not managed-serverless).
	Placement *PlacementSupport
}

ModuleContract represents a full extracted #ModuleContract from a module's CUE definition.

func (*ModuleContract) EligibleForPlacement 

func (mc *ModuleContract) EligibleForPlacement(mode string) bool

EligibleForPlacement reports whether the module may be composed under the given placement mode. Modules without a declaration follow the CUE safe-open defaults: local-only/standard yes, managed-serverless no.

type ModuleDelivery 

type ModuleDelivery struct {
	Type      string
	ManagedBy string
}

ModuleDelivery declares how a module reaches the runtime.

type ModuleGraph 

type ModuleGraph struct {
	// Ordered is the topologically sorted list of enabled module names.
	Ordered []string
	// Modules maps module name to its contract.
	Modules map[string]ModuleContract
	// Layers groups module names by their layer for staged deployment.
	Layers map[string][]string
}

ModuleGraph holds resolved modules in dependency order with validation results.

func (*ModuleGraph) DependenciesOf 

func (g *ModuleGraph) DependenciesOf(moduleName string) []string

DependenciesOf returns the direct dependency names for a module (enabled, non-optional only).

type ModuleMetadata 

type ModuleMetadata struct {
	Name        string
	DisplayName string
	Version     string
	Layer       string
	Description string
	Core        bool
	// Maturity is the release classification: "default", "opt-in", or
	// "draft". Draft modules must not claim canonical test scenarios.
	Maturity      string
	TestScenarios []string
}

ModuleMetadata identifies a module.

type ModuleReader 

type ModuleReader struct {
	// contains filtered or unexported fields
}

ModuleReader reads and extracts ModuleContracts from CUE module definitions.

func NewModuleReader 

func NewModuleReader() *ModuleReader

NewModuleReader creates a new ModuleReader.

func (*ModuleReader) ReadAllModules 

func (r *ModuleReader) ReadAllModules(modulesDir string) ([]ModuleContract, error)

ReadAllModules scans the modules directory and extracts all ModuleContracts.

func (*ModuleReader) ReadModule 

func (r *ModuleReader) ReadModule(modulePath string) (ModuleContract, error)

ReadModule reads a single module from the given directory (must contain module.cue).

type PlacementSupport 

type PlacementSupport struct {
	LocalOnly         bool
	Standard          bool
	ManagedServerless bool
	MissingAdapters   []string
	RejectionReason   string
}

PlacementSupport mirrors foundation/placement.cue #PlacementSupport: publishable eligibility metadata, not realization.

type PortDef 

type PortDef struct {
	Host      int
	Container int
	Protocol  string
}

PortDef represents a port mapping.

type ProductionAuthPolicy 

type ProductionAuthPolicy struct {
	Policy          string
	Middleware      string
	ExceptionReason string
}

type ProductionBackupPolicy 

type ProductionBackupPolicy struct {
	Required bool
	Restore  string
	Volumes  []string
}

type ProductionFirstRunPolicy 

type ProductionFirstRunPolicy struct {
	Behavior string
	State    string
	Note     string
}

type ProductionHealthPolicy 

type ProductionHealthPolicy struct {
	Smoke string
	Path  string
	Port  int
}

type ProductionResourceBudget 

type ProductionResourceBudget struct {
	Profile string
	Memory  string
	CPUs    float64
}

type ProductionServicePolicy 

type ProductionServicePolicy struct {
	Grade     string
	Auth      ProductionAuthPolicy
	FirstRun  ProductionFirstRunPolicy
	Health    ProductionHealthPolicy
	Backup    ProductionBackupPolicy
	Resources ProductionResourceBudget
}

ProductionServicePolicy is the Go representation of foundation.#ProductionServicePolicy.

type ProvidesSpec 

type ProvidesSpec struct {
	Capabilities map[string]bool
	Middleware   map[string]MiddlewareDef
	Endpoints    map[string]EndpointDef
}

ProvidesSpec declares what a module offers.

type ProvisionerDef 

type ProvisionerDef struct {
	Image       string
	Command     string
	DependsOn   string
	Networks    []string
	Environment map[string]string
}

ProvisionerDef represents a one-shot provisioner container.

type RequiredService 

type RequiredService struct {
	MinVersion string
	Provides   []string
	Optional   bool
}

RequiredService is a dependency on another module.

type RequiresSpec 

type RequiresSpec struct {
	Services       map[string]RequiredService
	Infrastructure InfraRequirements
}

RequiresSpec declares what a module needs from other modules and infrastructure.

type ResolveError 

type ResolveError struct {
	Module  string
	Message string
}

ResolveError describes a dependency resolution failure.

func (*ResolveError) Error 

func (e *ResolveError) Error() string

type Resolver 

type Resolver struct{}

Resolver validates and orders modules based on their dependency declarations.

func NewResolver 

func NewResolver() *Resolver

NewResolver creates a new dependency resolver.

func (*Resolver) Resolve 

func (r *Resolver) Resolve(contracts []ModuleContract) (*ModuleGraph, error)

Resolve takes a set of module contracts and returns a validated, ordered ModuleGraph. Only enabled modules are included. Disabled modules that are required by enabled modules produce an error (unless the dependency is optional).

type ResourceDef 

type ResourceDef struct {
	Memory    string
	MemoryMax string
	CPUs      float64
}

ResourceDef represents resource limits.

type SecurityDef 

type SecurityDef struct {
	NoNewPrivileges bool
	CapDrop         []string
	ReadOnly        bool
	Tmpfs           []string
}

SecurityDef mirrors the module house-hardening `security` block. Every real module declares it (noNewPrivileges + capDrop ALL is the house default); `stackkit module lint` asserts its presence.

func (*SecurityDef) HasCapDropAll 

func (s *SecurityDef) HasCapDropAll() bool

HasCapDropAll reports whether the service drops all Linux capabilities.

type ServiceDef 

type ServiceDef struct {
	Name          string
	DisplayName   string
	Category      string
	Type          string
	Required      bool
	Enabled       bool
	Image         string
	Tag           string
	Upstream      *UpstreamDef
	Command       []string
	Description   string
	Needs         []string
	RestartPolicy string
	Ports         []PortDef
	Volumes       []VolumeDef
	Environment   map[string]string
	Labels        map[string]string
	HealthCheck   *HealthCheckDef
	Resources     *ResourceDef
	TraefikRule   string
	TraefikPort   int
	// TraefikEnabled is true when network.traefik.enabled is set, i.e. the
	// service is externally routed and therefore requires an accessPolicy.
	TraefikEnabled bool
	// Security mirrors the module house-hardening block (#ServiceDefinition
	// allows `security` as an open extension used by every real module).
	Security *SecurityDef
	// AccessPolicy mirrors #ServiceDefinition.accessPolicy: the outer/app auth
	// posture. Required for Traefik-routed services (Golden Rules §4.1/§4.8).
	AccessPolicy *AccessPolicyDef
	OutputURL    string
	OutputDesc   string

	// Subdomain routing (from CUE #ServiceDefinition.subdomain)
	SubdomainKey    string
	SubdomainNested string
	SubdomainFlat   string

	// Dashboard card (from CUE #ServiceDefinition.dashboard)
	DashboardIcon      string
	DashboardOrder     int
	DashboardSection   string
	DashboardBadge     string
	DashboardEnableVar string
	DashboardGuideURL  string
}

ServiceDef represents an extracted service definition from CUE.

type SettingsSpec 

type SettingsSpec struct {
	Perma    map[string]any
	Flexible map[string]any
}

SettingsSpec holds perma (immutable) and flexible (changeable) settings.

type TFVars 

type TFVars struct {
	InstallMode string `json:"installation_mode"`

	// Legacy variable name consumed by existing platform bootstrap scripts.
	BootstrapMode string `json:"bootstrap_mode"`

	PlacementMode         string                       `json:"placement_mode,omitempty"`
	PlacementExposure     string                       `json:"placement_exposure,omitempty"`
	PlacementCoupling     string                       `json:"placement_coupling,omitempty"`
	PlacementCapabilities map[string]map[string]string `json:"placement_capabilities,omitempty"`

	// Domain for Traefik routing (e.g. "stack.local")
	Domain string `json:"domain"`

	SubdomainPrefix string `json:"subdomain_prefix,omitempty"`

	// Docker network name
	NetworkName string `json:"network_name"`

	// Optional Docker network subnet. Empty lets Docker choose a non-overlapping subnet.
	NetworkSubnet string `json:"network_subnet"`
	ServerLANIP   string `json:"server_lan_ip,omitempty"`

	ComputeTier string `json:"compute_tier"`

	EnableKombifyPoint bool `json:"enable_kombify_point"`
	// Deprecated alias kept for older generated templates and external tests.
	EnableDNSMasq bool `json:"enable_dnsmasq"`

	// EnableMDNS is a deprecated compatibility field. The canonical local path
	// never advertises a parallel .local namespace.
	EnableMDNS bool `json:"enable_mdns"`

	EnableHTTPS   bool   `json:"enable_https"`
	TLSProvider   string `json:"tls_provider,omitempty"`
	StepCAEnabled bool   `json:"step_ca_enabled"`
	AcmeEmail     string `json:"acme_email,omitempty"`
	AcmeChallenge string `json:"acme_challenge,omitempty"`
	DNSProvider   string `json:"dns_provider,omitempty"`
	DNSAPIToken   string `json:"dns_api_token,omitempty"`
	DNSAPIEmail   string `json:"dns_api_email,omitempty"`

	Paas                   string `json:"paas"`
	ReverseProxyBackend    string `json:"reverse_proxy_backend"`
	EnablePlatformFallback bool   `json:"enable_platform_fallback"`
	PlatformFallbackMode   string `json:"platform_fallback_mode"`

	// Service enable flags
	EnableTraefik       bool   `json:"enable_traefik"`
	EnableTinyauth      bool   `json:"enable_tinyauth"`
	EnablePocketID      bool   `json:"enable_pocketid"`
	EnableDokploy       bool   `json:"enable_dokploy"`
	EnableDokployApps   bool   `json:"enable_dokploy_apps"`
	EnableDockge        bool   `json:"enable_dockge"`
	EnableCoolify       bool   `json:"enable_coolify"`
	EnableKomodo        bool   `json:"enable_komodo"`
	EnableDashboard     bool   `json:"enable_dashboard"`
	EnableHomepage      bool   `json:"enable_homepage"`
	EnableUptimeKuma    bool   `json:"enable_uptime_kuma"`
	EnableWhoami        bool   `json:"enable_whoami"`
	EnableVaultwarden   bool   `json:"enable_vaultwarden"`
	EnableJellyfin      bool   `json:"enable_jellyfin"`
	EnableImmich        bool   `json:"enable_immich"`
	EnableFiles         bool   `json:"enable_files"`
	FilesProvider       string `json:"files_provider"`
	EnableCloudreve     bool   `json:"enable_cloudreve"`
	EnableNextcloud     bool   `json:"enable_nextcloud"`
	EnableHomeAssistant bool   `json:"enable_home_assistant,omitempty"`

	MediaPath string `json:"media_path"`

	DemoDataEnabled               bool   `json:"demo_data_enabled"`
	SetupPolicyPlatform           string `json:"setup_policy_platform"`
	SetupPolicyApplicationDefault string `json:"setup_policy_application_default"`
	SetupPolicyKuma               string `json:"setup_policy_kuma"`
	SetupPolicyWhoami             string `json:"setup_policy_whoami"`
	SetupPolicyVaultwarden        string `json:"setup_policy_vaultwarden"`
	SetupPolicyImmich             string `json:"setup_policy_immich"`
	SetupPolicyFiles              string `json:"setup_policy_files"`

	// TinyAuth configuration
	AdminEmail             string `json:"admin_email"`
	AdminPasswordPlaintext string `json:"admin_password_plaintext"`
	TinyauthUsers          string `json:"tinyauth_users"`
	TinyauthAppURL         string `json:"tinyauth_app_url"`
	TinyauthSessionSecret  string `json:"tinyauth_session_secret,omitempty"`

	// TinyAuth OIDC (PocketID integration)
	TinyauthOIDCEnabled      bool   `json:"tinyauth_oidc_enabled,omitempty"`
	TinyauthOIDCIssuer       string `json:"tinyauth_oidc_issuer,omitempty"`
	TinyauthOIDCClientID     string `json:"tinyauth_oidc_client_id,omitempty"`
	TinyauthOIDCClientSecret string `json:"tinyauth_oidc_client_secret,omitempty"`

	// PocketID configuration
	PocketIDAppURL        string `json:"pocketid_app_url,omitempty"`
	PocketIDEncryptionKey string `json:"pocketid_encryption_key,omitempty"`

	// Branding
	BrandColor     string `json:"brand_color"`
	DashboardTitle string `json:"dashboard_title"`

	// Runtime system app images
	StackKitServerImage string `json:"stackkit_server_image,omitempty"`
	Timezone            string `json:"timezone,omitempty"`

	NetworkMode           string `json:"network_mode"`
	DNSFixed              bool   `json:"dns_fixed"`
	DNSFixMethod          string `json:"dns_fix_method"`
	StorageDriverDegraded bool   `json:"storage_driver_degraded"`
	StorageDriver         string `json:"storage_driver"`

	// Docker host (for remote daemon)
	DockerHost string `json:"docker_host,omitempty"`
}

TFVars represents the complete structure of terraform.tfvars.json, matching all variables declared in basement-kit/templates/simple/main.tf.

type TerraformBridge 

type TerraformBridge struct{}

TerraformBridge projects admitted StackSpecs into Terraform variables.

func NewTerraformBridge 

func NewTerraformBridge() *TerraformBridge

NewTerraformBridge creates the canonical StackSpec-to-Terraform bridge.

func (*TerraformBridge) GenerateTFVarsBytesFromSpec 

func (b *TerraformBridge) GenerateTFVarsBytesFromSpec(spec *models.StackSpec) ([]byte, error)

GenerateTFVarsBytesFromSpec generates terraform.tfvars.json content from a StackSpec.

func (*TerraformBridge) GenerateTFVarsFromSpec 

func (b *TerraformBridge) GenerateTFVarsFromSpec(spec *models.StackSpec, outputDir string) error

GenerateTFVarsFromSpec generates terraform.tfvars.json from a StackSpec. This is the canonical generation path used by the CLI.

type UpstreamDef 

type UpstreamDef struct {
	GitHubRepo    string
	RegistryImage string
	Track         string
	PinLine       string
	OSVEcosystem  string
	OSVName       string
}

UpstreamDef mirrors #ServiceDefinition.upstream (ADR-0028): watch coordinates consumed by the Admin tool_release_watch job. Watch metadata only — deliberately excluded from the module contract hash.

type Validator 

type Validator struct {
	// contains filtered or unexported fields
}

Validator handles CUE schema validation

func NewValidator 

func NewValidator(baseDir string) *Validator

NewValidator creates a new CUE validator

func (*Validator) GetSchemaDir 

func (v *Validator) GetSchemaDir() string

GetSchemaDir returns the CUE schema directory

func (*Validator) ValidateCUEFile 

func (v *Validator) ValidateCUEFile(path string) (*models.ValidationResult, error)

ValidateCUEFile validates a single CUE file

func (*Validator) ValidateSpec 

func (v *Validator) ValidateSpec(spec *models.StackSpec) (*models.ValidationResult, error)

ValidateSpec validates a stack-spec against CUE schema

func (*Validator) ValidateStackKit 

func (v *Validator) ValidateStackKit(stackkitDir string) (*models.ValidationResult, error)

ValidateStackKit validates a StackKit against CUE schemas

type VolumeDef 

type VolumeDef struct {
	Source   string
	Target   string
	Type     string // "bind" or "volume"
	ReadOnly bool
}

VolumeDef represents a volume mount.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.