diff --git a/tech_docs/template_kindom.md b/tech_docs/template_kindom.md index c7427b0..80880a2 100644 --- a/tech_docs/template_kindom.md +++ b/tech_docs/template_kindom.md @@ -350,4 +350,158 @@ render: > In this kingdom the **template is the constitution**, > the seed is the crown jewel, -> and every `.yaml` is a citizen whose fate is **deterministically serendipitous**. \ No newline at end of file +> and every `.yaml` is a citizen whose fate is **deterministically serendipitous**. + +--- + +──────────────────────────────────────── +THE ONE-TOOL MOUSETRAP +“CUE is the linter, the schema, *and* the template.” +──────────────────────────────────────── + +0. Thesis +Traditional pipelines +``` +YAML → Jinja2 → JSON → Validator → (retry) +``` +Anti-pattern: **type errors are discovered *after* rendering**. + +CUE collapses the stack +``` +CUE spec + data → `cue export` → Valid YAML/JSON/Dockerfile/INI +``` +One binary, zero runtime surprises. + +──────────────────────────────────────── +1. Single Source of Truth (`spec.cue`) + +```cue +package kingdom + +// Universal schema: any object must satisfy this +#Object: { + id: string & =~"^[a-z0-9-]+$" + kind: string + meta?: {...} +} + +// Domain specialisations +#Dockerfile: #Object & { + kind: "Dockerfile" + stages: [string]: { + from: string + run: [...string] + } +} + +#CiscoCfg: #Object & { + kind: "Cisco" + lines: [...string] +} + +#FastAPISite: #Object & { + kind: "FastAPI" + routes: [...{path: string, method: "GET"|"POST"}] +} + +#EmailTpl: #Object & { + kind: "Email" + subject: string + body_html: string +} + +// Definition of the entire universe +objects: [...#Object] +``` + +──────────────────────────────────────── +2. Concrete Data (`objects/anything.yaml`) + +```yaml +objects: + - id: web + kind: Dockerfile + stages: + base: + from: "python:3.11-slim" + run: ["pip install fastapi uvicorn"] + - id: api + kind: FastAPI + routes: + - path: /health + method: GET + - id: alert + kind: Email + subject: "Build {{ .build_id }} succeeded" + body_html: "
Timestamp: {{ .timestamp }}
+ + + """ +} +``` + +Inject data: + +```bash +cue export --with-context build_id=12345 --with-context timestamp=2024-06-13T12:34:56Z +``` + +──────────────────────────────────────── +5. Multi-Format Output + +```bash +# Dockerfile +cue export objects/anything.yaml spec.cue -e 'objects[0]' --out dockerfile > Dockerfile + +# Cisco IOS +cue export objects/anything.yaml spec.cue -e 'objects[1]' --out text > router.cfg + +# GitHub Actions +cue export objects/anything.yaml spec.cue -e 'objects[2]' --out yaml > .github/workflows/deploy.yml +``` + +──────────────────────────────────────── +6. CI Guardrails (single 15-line job) + +```yaml +- name: One tool to rule them all + uses: cue-lang/setup-cue@main + with: + version: 'v0.8.0' + run: | + cue vet objects/ spec.cue + cue export objects/ spec.cue --out yaml > rendered.yml + sha256sum rendered.yml > checksum.sha256 +``` + +──────────────────────────────────────── +7. The Mousetrap in One Sentence + +> With **CUE**, the schema *is* the linter, the template, and the runtime contract—every artifact (Dockerfile, Cisco config, FastAPI schema, email, GitHub Action) is **guaranteed correct at render time**, not discovered later. \ No newline at end of file