medusa/the_information_nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update tech_docs/template_kindom.md

Browse Source
This commit is contained in:
medusa
2025-08-06 06:04:58 -05:00
parent a9024e59f2
commit 97cc8cffa2
1 changed files with 155 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
tech_docs/template_kindom.md
View File

@@ -351,3 +351,157 @@ render:
> In this kingdom the **template is the constitution**, > In this kingdom the **template is the constitution**,
> the seed is the crown jewel, > the seed is the crown jewel,
> and every `.yaml` is a citizen whose fate is **deterministically serendipitous**. > 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: "<h1>🎉</h1>"
```
────────────────────────────────────────
3. One Command to Rule Them All
```bash
# Validate + render + lint in one shot
cue export objects/anything.yaml spec.cue --out yaml
```
- **Validation**: fails before render if any field is wrong.
- **Rendering**: substitutes `{{ }}` using native CUE interpolation.
- **Linting**: built-in `cue vet` ensures every object is well-formed.
────────────────────────────────────────
4. Template Engine Inside the Schema (no Jinja2)
CUE supports string interpolation directly:
```cue
#EmailTpl: {
subject: string
body_html: """
<html>
<body>
<h1>Build {{ .build_id }} succeeded</h1>
<p>Timestamp: {{ .timestamp }}</p>
</body>
</html>
"""
}
```
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.