CUE Schema Patterns

Use this skill when:

• Working with CUE schema files (

  *.cue

  )
• Modifying parse functions in

  pkg/invowkfile/

  ,

  pkg/invowkmod/

  , or

  internal/config/

• Adding new CUE definitions or corresponding Go struct fields
• Debugging CUE validation errors

Schema Locations

• pkg/invowkfile/invowkfile_schema.cue

  defines invowkfile structure.

• pkg/invowkmod/invowkmod_schema.cue

  defines invowkmod structure.

• internal/config/config_schema.cue

  defines config.

Schema Compilation Pattern (3-Step Flow)

All CUE parsing in Invowk follows a consistent 3-step pattern:

// Step 1: Compile the schema (embedded via //go:embed)
ctx := cuecontext.New()
schemaValue := ctx.CompileString(embeddedSchema)
if schemaValue.Err() != nil {
    return nil, fmt.Errorf("internal error: failed to compile schema: %w", schemaValue.Err())
}

// Step 2: Compile user data and unify with schema
userValue := ctx.CompileBytes(data, cue.Filename(path))
if userValue.Err() != nil {
    return nil, formatCUEError(userValue.Err(), path)
}

schema := schemaValue.LookupPath(cue.ParsePath("#DefinitionName"))
unified := schema.Unify(userValue)
if err := unified.Validate(cue.Concrete(true)); err != nil {
    return nil, formatCUEError(err, path)
}

// Step 3: Decode to Go struct
var result GoStructType
if err := unified.Decode(&result); err != nil {
    return nil, formatCUEError(err, path)
}

Key Points:

• Schema is embedded via

  //go:embed

  for single-binary distribution
• Use

  LookupPath()

  to get the root definition (e.g.,

  #Invowkfile

  ,

  #Config

  )
• Use

  Validate(cue.Concrete(true))

  to ensure all values are concrete
• Use

  cue.Concrete(false)

  for config files where some fields may be optional
• Always use

  Decode()

  for type-safe extraction (see Decode Usage Rules below)

Reference Implementations:

• pkg/invowkfile/parse.go:ParseBytes()

  - Invowkfile parsing

• pkg/invowkmod/invowkmod.go:ParseInvowkmodBytes()

  - Invowkmod parsing

• internal/config/config.go:loadCUEIntoViper()

  - Config loading

Validation Responsibility Matrix

Validation is split between CUE and Go based on what each can handle:

CUE Handles (Declarative, Schema-Level)

name: string

=~

name: =~"^[a-zA-Z][a-zA-Z0-9_-]*$"

"native" | "virtual" | "container"

strings.MaxRunes()

& strings.MaxRunes(256)

>=0 & <=65535

?

name: string

?

description?: string

close({})

[_, ...]

Go Handles (Dynamic, Runtime-Level)

ValidateRegexPattern()

os.Stat()

filepath.Clean()

MaxNameLength

Justification Comments

All Go-only validations MUST include a

[GO-ONLY]

// ValidateRegexPattern validates a user-provided regex pattern for safety.
// [GO-ONLY] ReDoS (Regular Expression Denial of Service) prevention MUST be in Go.
// CUE cannot analyze regex complexity or detect catastrophic backtracking patterns.
func ValidateRegexPattern(pattern string) error { ... }

// validateEnvFilePath validates an env file path for security.
// [GO-ONLY] Path traversal prevention and cross-platform path handling require Go.
// CUE cannot perform filesystem operations or cross-platform path normalization.
func validateEnvFilePath(path string) error { ... }

Decode Usage Rules

ALWAYS use

value.Decode(&goStruct)

Correct Pattern

var invowkfile Invowkfile
if err := unified.Decode(&invowkfile); err != nil {
    return nil, formatCUEError(err, path)
}

Why Not Manual Extraction?

Manual extraction methods (

String()

Int64()

Bool()

• No compile-time type checking
• Requires manual error handling for each field
• Easy to forget optional field handling
• Doesn't leverage CUE's type system

Exception: Manual extraction is acceptable only for truly dynamic scenarios (e.g., extracting arbitrary user-defined keys). Document such cases.

Field Naming Convention

CUE uses

snake_case

PascalCase

// CUE Schema (snake_case)
#Config: close({
    container_engine: #ContainerEngine
    includes:         [...#IncludeEntry]
    default_runtime:  #RuntimeType
})

// Go Struct (PascalCase with JSON tags)
type Config struct {
    ContainerEngine ContainerEngine `json:"container_engine"`
    Includes        []IncludeEntry  `json:"includes"`
    DefaultRuntime  RuntimeMode     `json:"default_runtime"`
}

Rule: Every CUE field name MUST have a matching JSON tag in the corresponding Go struct.

Verification: Schema sync tests (in

*_sync_test.go

Error Formatting Requirements

All CUE errors MUST include JSON path prefixes for clear error messages:

Error Format

<file-path>: <json-path>: <message>

Examples:

invowkfile.cue: cmds[0].implementations[2].script: value exceeds maximum length
config.cue: container.auto_provision.enabled: expected bool, got string

Implementation Pattern

Use the

formatCUEError()

import "cuelang.org/go/cue/errors"

func formatCUEError(err error, filePath string) error {
    if err == nil {
        return nil
    }

    cueErrors := errors.Errors(err)
    if len(cueErrors) == 0 {
        return fmt.Errorf("%s: %w", filePath, err)
    }

    var lines []string
    for _, e := range cueErrors {
        path := errors.Path(e)
        pathStr := formatPath(path)  // Convert ["cmds", "0", "script"] to "cmds[0].script"
        msg := e.Error()

        if pathStr != "" {
            lines = append(lines, fmt.Sprintf("%s: %s", pathStr, msg))
        } else {
            lines = append(lines, msg)
        }
    }

    if len(lines) == 1 {
        return fmt.Errorf("%s: %s", filePath, lines[0])
    }
    return fmt.Errorf("%s: validation failed:\n  %s", filePath, strings.Join(lines, "\n  "))
}

Important: Import

cuelang.org/go/cue/errors

errors

Errors()

Path()

CUE Library Version Pinning

Current Version

CUE is pinned in

go.mod

cuelang.org/go v0.15.4

Upgrade Process

When upgrading the CUE library version:

1. Review Changelog: Check for breaking changes in the CUE release notes
2. Run Full Test Suite:

   make test

   including all schema sync tests
3. Check API Deprecations: Search for deprecated function usage
4. Verify Error Formats: Manually test that error messages still include paths
5. Update Documentation: If CUE behavior changes, update this rules file
6. Test Cross-Platform: Run CI on all platforms (Linux, macOS, Windows)

Known CUE Limitations

• No Encode API: CUE can decode Go structs but has no production-ready encoder
• No Code Generation:

  gengotypes

  is experimental; we use sync tests instead
• Context is Stateful: Create a new

  cuecontext.New()

  for each parse operation

Rules

• All CUE structs must be closed (use

  close({ ... })

  ) so unknown fields cause validation errors.
• When adding new CUE struct fields or definitions, always include appropriate validation constraints (e.g.,

  strings.MaxRunes()

  , regex patterns with

  =~

  , range constraints like

  >=0 & <=255

  ) - not just type declarations. This ensures defense-in-depth validation.
• Schema sync tests MUST exist for every Go struct that corresponds to a CUE definition.
• Go-only validations MUST have

  [GO-ONLY]

  comments explaining why CUE cannot handle them.

Schema Sync Tests

Sync tests verify Go struct JSON tags match CUE schema field names at CI time. They catch misalignments before they cause silent parsing failures.

Test Files:

• pkg/invowkfile/sync_test.go

  - Invowkfile, Command, Implementation, etc.

• pkg/invowkmod/sync_test.go

  - Invowkmod, ModuleRequirement

• internal/config/sync_test.go

  - Config, VirtualShellConfig, UIConfig, etc.

Pattern:

func TestStructNameSchemaSync(t *testing.T) {
    schema, _ := getCUESchema(t)
    cueFields := extractCUEFields(t, lookupDefinition(t, schema, "#DefinitionName"))
    goFields := extractGoJSONTags(t, reflect.TypeFor[GoStructType]())

    assertFieldsSync(t, "StructName", cueFields, goFields)
}

When to Add Sync Tests:

• Adding a new CUE definition with a corresponding Go struct
• Adding new fields to existing CUE/Go types
• Renaming fields (test will fail until both are updated)

Common Pitfalls

Unclosed CUE Structs

Problem: Open structs allow arbitrary unknown fields, bypassing validation.

// WRONG: Open struct - unknown fields silently accepted
#Config: {
    name: string
}

// CORRECT: Closed struct - unknown fields rejected
#Config: close({
    name: string
})

Redundant Validation

Problem: Same validation in both CUE and Go creates maintenance burden.

Rule: Validation lives in ONE place. CUE handles format/type validation. Go handles security/filesystem/cross-field logic.

Anti-Pattern:

// WRONG: Duplicates CUE regex validation
if !regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`).MatchString(name) {
    return fmt.Errorf("invalid name format")
}

Correct Pattern:

// CORRECT: CUE handles format; Go handles length (defense-in-depth)
// [GO-ONLY] Length limit not in CUE for simplicity; checked here for defense-in-depth.
if len(name) > MaxNameLength {
    return fmt.Errorf("name too long (%d chars, max %d)", len(name), MaxNameLength)
}

Missing JSON Tags

Problem: Go struct field without JSON tag won't be populated by

Decode()

Symptom: Field is always zero value despite being in CUE file.

Fix: Add JSON tag matching the CUE field name:

type Config struct {
    Includes  []IncludeEntry `json:"includes"`  // Matches CUE field
    CachePath string         // No JSON tag - will be empty!
}

Wrong Error Import

Problem: Using standard library

errors

// WRONG: Standard library - no Path() function
import "errors"

// CORRECT: CUE error package with path extraction
import "cuelang.org/go/cue/errors"

Stale Schema Sync Tests

Problem: Sync test exclusions become outdated after refactoring.

Fix: After any CUE/Go struct changes, run

make test