Update tech_docs/template_kindom.md

2025-08-06 06:04:58 -05:00
parent a9024e59f2
commit 97cc8cffa2
1 changed files with 155 additions and 1 deletions
--- 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**.
+> 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.