augmented

nickel-augmented

A reusable Nickel contract library that enforces Rhodium Standard Repository (RSR) policies at configuration time. Part of the nickel-augmentation monorepo.

1. What This Does

Nickel-augmented provides typed, validated configuration contracts for RSR-compliant projects. Import the library into your .ncl files to get compile-time enforcement of:

• Language policy — only RSR-allowed languages pass validation

• License policy — SPDX identifiers restricted to approved set

• Security policy — HTTPS-only URLs, SHA-256+ hashes, SHA-pinned actions

• Infrastructure contracts — services, databases, containers, environments

• CI/CD contracts — job definitions, matrix builds, workflow steps

2. Quick Start

# Import the full library
let aug = import "./lib/prelude.ncl" in

{
  project = {
    name | aug.rsr.NonEmptyString = "my-project",
    version | aug.rsr.SemVer = "1.0.0",
    license | aug.rsr.SpdxLicense = "MPL-2.0",
  },

  api | aug.infra.Service = {
    name = "api-gateway",
    port = 8080,
    health_check = "/health",
    environment = "production",
    replicas = 3,
  },
}

Or import individual modules:

let rsr = import "./lib/rsr.ncl" in
let security = import "./lib/security.ncl" in

{
  target | rsr.BuildTarget = {
    name = "backend",
    language = "gleam",      # ← passes AllowedLanguage contract
    entry_point = "src/app.gleam",
  },

  db_password | security.SecretRef = {
    type = 'vault,
    key = "secret/prod/db-password",
  },
}

3. Library Modules

Module	Contracts	Purpose
lib/rsr.ncl	NonEmptyString, SemVer, AllowedLanguage, BannedLanguage, SpdxLicense, RsrTier, RepoMetadata, BuildTarget, CheckpointFile	Core RSR policy enforcement
lib/security.ncl	HttpsUrl, SecureHash, Sha256, ShaPinnedAction, SecretRef, SecretProvider, TlsVersion, SslMode	Security policy contracts
lib/ci.ncl	Step, Job, Matrix, CiPlatform, checkout_step, cache_step, base_job, security_job, rsr_validate_job, required_workflows	CI/CD workflow contracts and templates
lib/infra.ncl	Environment, Port, Service, DatabaseConfig, ContainerImage, BaseImage, ContainerRuntime, base_env_config	Infrastructure and deployment contracts
lib/prelude.ncl	Re-exports rsr, security, ci, infra	Convenience import for all modules

4. The Augmentation Boundary

Nickel augments RSR templates — it does not replace other tools:

Nickel handles	Stays in	Reason
Build config, CI pipelines, infra	—	Contracts validate at build-time
—	STATE.scm, META.scm	Guile Scheme governs project state
—	guix.scm, flake.nix	Native package managers
—	Runtime config	Environment variables / JSON at runtime
—	Application logic	ReScript / Rust / Gleam

Rule: Nickel generates, Scheme governs. Contracts, not code.

5. Examples

See examples/nickel/ for working examples:

• contracts.ncl — Shared contracts (standalone version of the library)

• build.ncl — Build targets with language policy enforcement

• ci.ncl — CI/CD pipeline with merge semantics

• infra.ncl — Infrastructure config with secret references

6. Validation

# Typecheck all library modules
nickel typecheck lib/rsr.ncl
nickel typecheck lib/security.ncl
nickel typecheck lib/ci.ncl
nickel typecheck lib/infra.ncl

# Typecheck examples
nickel typecheck examples/nickel/build.ncl

# Export a config to JSON
nickel export examples/nickel/build.ncl

7. License

MPL-2.0