.nest.yaml Config Schema

ELI5

.nest.yaml is the recipe card of a workspace: top-level pantry settings (log level, root), a list of dishes (services) with where to source the ingredients (git repos), and house rules for syncing changes back and forth.

Technical Deep Dive

Defined by Go structs in engine/internal/config/config.go and a fully-worked example at engine/examples/configs/example.nest.yaml.

Schema

classDiagram
    class Config {
        string workspaceRoot
        string logLevel
        map services
        SyncConfig sync
        AssemblyConfig assembly
    }
    class ServiceConfig {
        string name
        string repository
        string ref
        string path
        []string dependencies
    }
    class SyncConfig {
        bool dryRun
    }
    class AssemblyConfig {
        bool enabled
    }
    Config "1" --> "*" ServiceConfig
    Config --> SyncConfig
    Config --> AssemblyConfig

Example Layout (extended in example.nest.yaml)

workspace_root: ./workspace
temp_dir: /tmp/nestr
log_level: info

assembly:
  manifest_file: manifest.json
  parallel_clones: 4
  clone_timeout: 5m
  git:
    default_branch: main
    ssh_key_path: ~/.ssh/id_ed25519
    depth: 1
  strategy:
    mode: smart            # smart | full | partial
    use_cache: true
    cache_dir: ./.pellets/cache
    validation: strict     # strict | lenient | none

sync:
  patterns: ["src/**", "package.json"]
  exclude: ["node_modules/**", "coverage/**"]
  direction: bidirectional # bidirectional | source-to-target | target-to-source
  conflict_resolution: prompt # prompt | source | target | merge | skip
  dry_run: false

services:
  api:
    repository: git@github.com:org/api.git
    ref: main
    path: services/api
    dependencies: [shield]

monitoring:
  enabled: true
  port: 9090
  path: /metrics
  prometheus:
    push_gateway: http://pushgw:9091
    job_name: nestr-engine
    instance: ${HOSTNAME}

Surface vs Example Drift

The Go struct in this revision encodes a minimal subset (workspaceRoot, logLevel, services, sync.dryRun, assembly.enabled); the example YAML showcases a richer schema (assembly strategies, sync conflict resolution, monitoring). Treat the example as the target schema and the struct as the currently-bound subset.

Key Terms

• conflict_resolution → behaviour when sync sees diverged content: prompt (interactive), source/target (overwrite one side), merge (3-way), skip (leave both).
• assembly.strategy.mode → smart (cache-aware), full (fresh clone), partial (only changed services).
• dependencies → list of other service names this service must be cloned/built after; consumed by the dependency graph (see nestr-013).

Q&A

Q: What happens if a service references a missing dependency name? A: BuildDependencyGraph will produce an edge to a non-existent node; TopologicalOrder then either skips or errors depending on revision. Always validate names against the services map keys.

Q: Is direction: bidirectional symmetric on conflict? A: No — conflict_resolution is the tiebreaker. bidirectional only describes which side initiates change detection.

Q: Does the engine rebuild on ref change? A: The struct captures ref; whether a downstream operation rebuilds is decided by the operation handler (assemble does, sync may not unless the ref affects matched patterns).

Examples

Minimum viable workspace: workspace_root: ., log_level: info, two services with repository/ref/path and one dependencies: [other] edge — enough to drive assemble, produce a topological order, and hand off to the dependency-graph card.