Update Cue tutorial to use testscript

PROBLEM:

The "Cue" tutorial has hardcoded code blocks and hasn't been
updated to use the automated testscript workflow.

NOTE: This is slightly more complex than normal because we need
to make sure Timoni is installed when we execute the testscripts
due to the fact that we need to execute `timoni mod vendor crds ...`
and capture the output.

SOLUTION:

* Add Timoni as one of the packages that are installed via `make go-deps`.
* Update the testing GH Action to install all go dependencies before executing the tests.
* Create a test for the Cue tutorial.
* Create a testscript for the Cue test.
* Update the Cue MDX file to load in data from the testscript directory.

OUTCOME:

The code content in the Cue tutorial now comes directly from the
testscript workflow.

Makefile

@@ -124,6 +124,7 @@ go-deps: ## tool versions pinned in tools.go
 	go install golang.org/x/tools/cmd/godoc
 	go install github.com/princjef/gomarkdoc/cmd/gomarkdoc
 	go install github.com/google/ko
+	go install github.com/stefanprodan/timoni/cmd/timoni@v0.23.0
 	# curl https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | bash
 
 .PHONY: frontend-deps

doc/md/tutorial/_cue/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_cue/examples/02-cue.txt

@@ -0,0 +1,166 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-cue-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail mkdir-and-init.sh'
+cd holos-cue-tutorial
+
+# Create the components directory, then combine and execute the multiline
+# podinfo component header/body/trailer files
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+exec cat $WORK/podinfo-component-header.sh $WORK/podinfo-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files.
+exec cat $WORK/register-components-header.sh $WORK/register-components-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render and capture output
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Git init and commit
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+
+# Combine and execute the mixin component header/body/trailer files
+exec cat $WORK/mixin-component-header.sh $WORK/mixin-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Import CRDs with Timoni
+exec bash -c 'bash -euo pipefail $WORK/import-crds.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/timoni-vendor.txt
+
+# Render platform
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+
+# Git diff and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-cue-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-cue-tutorial && cd holos-cue-tutorial
+holos init platform v1alpha5
+-- mkdir-components.sh --
+mkdir -p components/podinfo
+-- import-crds.sh --
+timoni mod vendor crds -f https://raw.githubusercontent.com/external-secrets/external-secrets/v0.10.5/deploy/crds/bundle.yaml
+-- podinfo-component-header.sh --
+cat <<EOF > components/podinfo/podinfo.cue
+-- podinfo-component-body.cue --
+package holos
+
+// export the component build plan to holos
+holos: Component.BuildPlan
+
+// Component is a Helm chart
+Component: #Helm & {
+	Name:      "podinfo"
+	Namespace: "default"
+	// Add metadata.namespace to all resources with kustomize.
+	KustomizeConfig: Kustomization: namespace: Namespace
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- register-components-header.sh --
+cat <<EOF > platform/podinfo.cue
+-- register-components-body.cue --
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+}
+-- render.sh --
+holos render platform
+-- git-init.sh --
+git init . && git add . && git commit -m initial
+-- mixin-component-header.sh --
+cat <<EOF > components/podinfo/mixins.cue
+-- mixin-component-body.cue --
+package holos
+
+// Component fields are unified with podinfo.cue
+Component: {
+	// Concrete values are defined in podinfo.cue
+	Name:      string
+	Namespace: string
+
+	// Resources represents mix-in resources organized as a struct.
+	Resources: ExternalSecret: (Name): {
+		// Name is consistent with the component name.
+		metadata: name: Name
+		// Namespace is consistent with the component namespace.
+		metadata: namespace: Namespace
+		spec: {
+			// Ensure the target secret name is consistent.
+			target: name: metadata.name
+			// Ensure the name in the SecretStore is consistent.
+			dataFrom: [{extract: {key: metadata.name}}]
+			refreshInterval: "30s"
+			secretStoreRef: kind: "SecretStore"
+			secretStoreRef: name: "default"
+		}
+	}
+}
+-- git-diff.sh --
+git diff deploy
+-- git.diff --
+diff --git a/deploy/components/podinfo/podinfo.gen.yaml b/deploy/components/podinfo/podinfo.gen.yaml
+index 6e4aec0..f79e9d0 100644
+--- a/deploy/components/podinfo/podinfo.gen.yaml
++++ b/deploy/components/podinfo/podinfo.gen.yaml
+@@ -112,3 +112,19 @@ spec:
+       volumes:
+       - emptyDir: {}
+         name: data
++---
++apiVersion: external-secrets.io/v1beta1
++kind: ExternalSecret
++metadata:
++  name: podinfo
++  namespace: default
++spec:
++  dataFrom:
++  - extract:
++      key: podinfo
++  refreshInterval: 30s
++  secretStoreRef:
++    kind: SecretStore
++    name: default
++  target:
++    name: podinfo

doc/md/tutorial/_cue/script-01-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/tutorial/_cue/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_cue/script-02-cue/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_cue/script-02-cue/git-diff.sh

@@ -0,0 +1 @@
+git diff deploy

doc/md/tutorial/_cue/script-02-cue/git-init.sh

@@ -0,0 +1 @@
+git init . && git add . && git commit -m initial

doc/md/tutorial/_cue/script-02-cue/git.diff

@@ -0,0 +1,24 @@
+diff --git a/deploy/components/podinfo/podinfo.gen.yaml b/deploy/components/podinfo/podinfo.gen.yaml
+index 6e4aec0..f79e9d0 100644
+--- a/deploy/components/podinfo/podinfo.gen.yaml
++++ b/deploy/components/podinfo/podinfo.gen.yaml
+@@ -112,3 +112,19 @@ spec:
+       volumes:
+       - emptyDir: {}
+         name: data
++---
++apiVersion: external-secrets.io/v1beta1
++kind: ExternalSecret
++metadata:
++  name: podinfo
++  namespace: default
++spec:
++  dataFrom:
++  - extract:
++      key: podinfo
++  refreshInterval: 30s
++  secretStoreRef:
++    kind: SecretStore
++    name: default
++  target:
++    name: podinfo

doc/md/tutorial/_cue/script-02-cue/import-crds.sh

@@ -0,0 +1 @@
+timoni mod vendor crds -f https://raw.githubusercontent.com/external-secrets/external-secrets/v0.10.5/deploy/crds/bundle.yaml

doc/md/tutorial/_cue/script-02-cue/mixin-component-body.cue

@@ -0,0 +1,25 @@
+package holos
+
+// Component fields are unified with podinfo.cue
+Component: {
+	// Concrete values are defined in podinfo.cue
+	Name:      string
+	Namespace: string
+
+	// Resources represents mix-in resources organized as a struct.
+	Resources: ExternalSecret: (Name): {
+		// Name is consistent with the component name.
+		metadata: name: Name
+		// Namespace is consistent with the component namespace.
+		metadata: namespace: Namespace
+		spec: {
+			// Ensure the target secret name is consistent.
+			target: name: metadata.name
+			// Ensure the name in the SecretStore is consistent.
+			dataFrom: [{extract: {key: metadata.name}}]
+			refreshInterval: "30s"
+			secretStoreRef: kind: "SecretStore"
+			secretStoreRef: name: "default"
+		}
+	}
+}

doc/md/tutorial/_cue/script-02-cue/mixin-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/mixins.cue

doc/md/tutorial/_cue/script-02-cue/mkdir-and-init.sh

@@ -0,0 +1,2 @@
+mkdir holos-cue-tutorial && cd holos-cue-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_cue/script-02-cue/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/podinfo

doc/md/tutorial/_cue/script-02-cue/podinfo-component-body.cue

@@ -0,0 +1,19 @@
+package holos
+
+// export the component build plan to holos
+holos: Component.BuildPlan
+
+// Component is a Helm chart
+Component: #Helm & {
+	Name:      "podinfo"
+	Namespace: "default"
+	// Add metadata.namespace to all resources with kustomize.
+	KustomizeConfig: Kustomization: namespace: Namespace
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+}

doc/md/tutorial/_cue/script-02-cue/podinfo-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/podinfo.cue

doc/md/tutorial/_cue/script-02-cue/register-components-body.cue

@@ -0,0 +1,6 @@
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+}

doc/md/tutorial/_cue/script-02-cue/register-components-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/podinfo.cue

doc/md/tutorial/_cue/script-02-cue/register-components-output.txt

@@ -0,0 +1,3 @@
+cached podinfo 6.6.2
+rendered podinfo in 1.938665041s
+rendered platform in 1.938759417s

doc/md/tutorial/_cue/script-02-cue/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_cue/script-02-cue/timoni-vendor.txt

@@ -0,0 +1,17 @@
+3:20PM INF schemas vendored: external-secrets.io/clusterexternalsecret/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/clustersecretstore/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/clustersecretstore/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/externalsecret/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/externalsecret/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/pushsecret/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/secretstore/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/secretstore/v1beta1
+3:20PM INF schemas vendored: generators.external-secrets.io/acraccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/ecrauthorizationtoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/fake/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/gcraccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/githubaccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/password/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/uuid/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/vaultdynamicsecret/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/webhook/v1alpha1

doc/md/tutorial/_cue/script-02-cue/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_hello-holos/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_hello-holos/examples/02-hello-holos.txt

@@ -0,0 +1,126 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail $WORK/mkdir-and-init.sh'
+cd holos-tutorial
+
+# Create the components directory
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+
+# Combine and execute the multiline podinfo component header/body/trailer files
+exec cat $WORK/podinfo-component-header.sh ../podinfo-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files
+exec cat $WORK/register-podinfo-header.sh ../register-podinfo-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Generate and update the tree of the tutorial directory (omitting the cue.mod directory)
+exec bash -c 'bash -euo pipefail $WORK/tree.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/tree.txt
+
+# Split the rendered manifest into two separate files to display separately
+exec bash -c 'bash -euo pipefail $WORK/split-rendered-manifest.sh $WORK/holos-tutorial/deploy/components/podinfo/podinfo.gen.yaml $WORK'
+
+# Grep for the Hello Holos message and write the output file
+exec bash -c 'bash -euo pipefail $WORK/grep-for-message.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/grepped-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-tutorial && cd holos-tutorial
+holos init platform v1alpha5
+-- tree.sh --
+tree -L 3 -I cue.mod .
+-- mkdir-components.sh --
+mkdir -p components/podinfo
+-- podinfo-component-header.sh --
+cat <<EOF > components/podinfo/podinfo.cue
+-- podinfo-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: HelmChart.BuildPlan
+
+HelmChart: #Helm & {
+	Name: "podinfo"
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	// Holos marshals Values into values.yaml for Helm.
+	Values: {
+		// message is a string with a default value.  @tag indicates a value may
+		// be injected from the platform spec component parameters.
+		ui: {
+			message: string | *"Hello World" @tag(greeting, type=string)
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- register-podinfo-header.sh --
+cat <<EOF > platform/podinfo.cue
+-- register-podinfo-body.cue --
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+	// Inject a value into the component.
+	parameters: greeting: "Hello Holos!"
+}
+-- render.sh --
+holos render platform
+-- register-components-output.txt --
+cached podinfo 6.6.2
+rendered podinfo in 1.938665041s
+rendered platform in 1.938759417s
+-- podinfo-rendered-path.sh --
+deploy/components/podinfo/podinfo.gen.yaml
+-- split-rendered-manifest.sh --
+awk 'BEGIN {RS="---"} NR==1 {print > "service.yaml"} NR==2 {print > "deployment.yaml"}' $1
+mv service.yaml $2/rendered-service.yaml
+mv deployment.yaml $2/rendered-deployment.yaml
+-- grep-for-message.sh --
+grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml
+-- grepped-output.txt --
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!

doc/md/tutorial/_hello-holos/script-01-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/tutorial/_hello-holos/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_hello-holos/script-02-hello-holos/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_hello-holos/script-02-hello-holos/grep-for-message.sh

@@ -0,0 +1 @@
+grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/grepped-output.txt

@@ -0,0 +1,3 @@
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!

doc/md/tutorial/_hello-holos/script-02-hello-holos/mkdir-and-init.sh

@@ -0,0 +1,2 @@
+mkdir holos-tutorial && cd holos-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_hello-holos/script-02-hello-holos/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/podinfo

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-component-body.cue

@@ -0,0 +1,23 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: HelmChart.BuildPlan
+
+HelmChart: #Helm & {
+	Name: "podinfo"
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	// Holos marshals Values into values.yaml for Helm.
+	Values: {
+		// message is a string with a default value.  @tag indicates a value may
+		// be injected from the platform spec component parameters.
+		ui: {
+			message: string | *"Hello World" @tag(greeting, type=string)
+		}
+	}
+}

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/podinfo.cue

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-rendered-path.sh

@@ -0,0 +1 @@
+deploy/components/podinfo/podinfo.gen.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-components-output.txt

@@ -0,0 +1,2 @@
+rendered podinfo in 544.501875ms
+rendered platform in 544.608125ms

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-podinfo-body.cue

@@ -0,0 +1,8 @@
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+	// Inject a value into the component.
+	parameters: greeting: "Hello Holos!"
+}

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-podinfo-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/podinfo.cue

doc/md/tutorial/_hello-holos/script-02-hello-holos/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_hello-holos/script-02-hello-holos/rendered-deployment.yaml

@@ -0,0 +1,93 @@
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: Helm
+    app.kubernetes.io/name: podinfo
+    app.kubernetes.io/version: 6.6.2
+    helm.sh/chart: podinfo-6.6.2
+  name: podinfo
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: podinfo
+  strategy:
+    rollingUpdate:
+      maxUnavailable: 1
+    type: RollingUpdate
+  template:
+    metadata:
+      annotations:
+        prometheus.io/port: "9898"
+        prometheus.io/scrape: "true"
+      labels:
+        app.kubernetes.io/name: podinfo
+    spec:
+      containers:
+      - command:
+        - ./podinfo
+        - --port=9898
+        - --cert-path=/data/cert
+        - --port-metrics=9797
+        - --grpc-port=9999
+        - --grpc-service-name=podinfo
+        - --level=info
+        - --random-delay=false
+        - --random-error=false
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!
+        - name: PODINFO_UI_COLOR
+          value: '#34577c'
+        image: ghcr.io/stefanprodan/podinfo:6.6.2
+        imagePullPolicy: IfNotPresent
+        livenessProbe:
+          exec:
+            command:
+            - podcli
+            - check
+            - http
+            - localhost:9898/healthz
+          failureThreshold: 3
+          initialDelaySeconds: 1
+          periodSeconds: 10
+          successThreshold: 1
+          timeoutSeconds: 5
+        name: podinfo
+        ports:
+        - containerPort: 9898
+          name: http
+          protocol: TCP
+        - containerPort: 9797
+          name: http-metrics
+          protocol: TCP
+        - containerPort: 9999
+          name: grpc
+          protocol: TCP
+        readinessProbe:
+          exec:
+            command:
+            - podcli
+            - check
+            - http
+            - localhost:9898/readyz
+          failureThreshold: 3
+          initialDelaySeconds: 1
+          periodSeconds: 10
+          successThreshold: 1
+          timeoutSeconds: 5
+        resources:
+          limits: null
+          requests:
+            cpu: 1m
+            memory: 16Mi
+        volumeMounts:
+        - mountPath: /data
+          name: data
+      terminationGracePeriodSeconds: 30
+      volumes:
+      - emptyDir: {}
+        name: data
+

doc/md/tutorial/_hello-holos/script-02-hello-holos/rendered-service.yaml

@@ -0,0 +1,23 @@
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: Helm
+    app.kubernetes.io/name: podinfo
+    app.kubernetes.io/version: 6.6.2
+    helm.sh/chart: podinfo-6.6.2
+  name: podinfo
+spec:
+  ports:
+  - name: http
+    port: 9898
+    protocol: TCP
+    targetPort: http
+  - name: grpc
+    port: 9999
+    protocol: TCP
+    targetPort: grpc
+  selector:
+    app.kubernetes.io/name: podinfo
+  type: ClusterIP
+

doc/md/tutorial/_hello-holos/script-02-hello-holos/split-rendered-manifest.sh

@@ -0,0 +1,3 @@
+awk 'BEGIN {RS="---"} NR==1 {print > "service.yaml"} NR==2 {print > "deployment.yaml"}' $1
+mv service.yaml $2/rendered-service.yaml
+mv deployment.yaml $2/rendered-deployment.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/tree.sh

@@ -0,0 +1 @@
+tree -L 3 -I cue.mod .

doc/md/tutorial/_hello-holos/script-02-hello-holos/tree.txt

@@ -0,0 +1,17 @@
+.
+|-- components
+|   `-- podinfo
+|       |-- podinfo.cue
+|       `-- vendor
+|-- deploy
+|   `-- components
+|       `-- podinfo
+|-- platform
+|   |-- platform.gen.cue
+|   `-- podinfo.cue
+|-- platform.metadata.json
+|-- resources.cue
+|-- schema.cue
+`-- tags.cue
+
+8 directories, 7 files

doc/md/tutorial/_hello-holos/script-02-hello-holos/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_kustomize/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_kustomize/examples/02-kustomize.txt

@@ -0,0 +1,226 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-kustomize-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail $WORK/mkdir-and-init.sh'
+cd holos-kustomize-tutorial
+
+# Initialize git
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+
+# Create the component directory
+exec bash -c 'bash -euo pipefail $WORK/mkdir-component.sh'
+
+# Combine and execute the multiline httpbin component header/body/trailer files
+exec cat $WORK/httpbin-component-header.sh $WORK/httpbin-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline httpbin yaml header/body/trailer files
+exec cat $WORK/httpbin-yaml-header.sh $WORK/httpbin-yaml-body.yaml $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline registration header/body/trailer files
+exec cat $WORK/register-component-header.sh $WORK/register-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-component-output.txt
+
+# Git commit and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-commit-component.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git-commit-component-output.txt
+
+# Export Build Plan and capture output
+exec bash -c 'bash -euo pipefail $WORK/cue-export.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/buildplan-output.cue
+
+# Combine and execute the multiline kustomize patch header/body/trailer files
+exec cat $WORK/httpbin-patch-header.sh $WORK/httpbin-patch-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform and capture output
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/kustomize-patch-render-output.txt
+
+# Git diff and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Git commit and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-commit-final.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git-commit-final-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-kustomize-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-kustomize-tutorial
+cd holos-kustomize-tutorial
+holos init platform v1alpha5
+-- git-init.sh --
+git init . && git add . && git commit -m initial
+-- mkdir-component.sh --
+mkdir -p components/httpbin
+-- httpbin-component-header.sh --
+cat <<EOF > components/httpbin/httpbin.cue
+-- httpbin-component-body.cue --
+package holos
+
+// Produce a Kustomize BuildPlan for Holos
+holos: Kustomize.BuildPlan
+
+// https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/README.md
+Kustomize: #Kustomize & {
+	KustomizeConfig: {
+		// Files tells Holos to copy the file from the component path to the
+		// temporary directory Holos uses for BuildPlan execution.
+		Files: {
+			"httpbin.yaml": _
+		}
+		CommonLabels: {
+			"app.kubernetes.io/name": "httpbin"
+		}
+		// Kustomization represents a kustomization.yaml file in CUE.  Holos
+		// marshals this field into a `kustomization.yaml` while processing a
+		// BuildPlan.  See
+		// https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
+		Kustomization: {
+			images: [{name: "mccutchen/go-httpbin"}]
+			// Use a hidden field to compose patches easily with a struct.  Hidden
+			// fields are not included in exported structures.
+			_patches: {}
+			// Convert the hidden struct to a list.
+			patches: [for x in _patches {x}]
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- httpbin-yaml-header.sh --
+cat <<EOF > components/httpbin/httpbin.yaml
+-- httpbin-yaml-body.yaml --
+# https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/resources.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: httpbin
+spec:
+  template:
+    spec:
+      containers:
+        - name: httpbin
+          image: mccutchen/go-httpbin
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          readinessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          resources: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin
+spec:
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+      appProtocol: http
+-- register-component-header.sh --
+cat <<EOF > platform/httpbin.cue
+-- register-component-body.cue --
+package holos
+
+Platform: Components: {
+	httpbin: {
+		name: "httpbin"
+		path: "components/httpbin"
+	}
+}
+-- git-commit-component.sh --
+git add . && git commit -m 'add httpbin'
+-- cue-export.sh --
+holos cue export --expression holos --out=yaml ./components/httpbin
+-- httpbin-patch-header.sh --
+cat <<EOF > components/httpbin/patches.cue
+-- httpbin-patch-body.cue --
+package holos
+
+import "encoding/yaml"
+
+// Mix in a Kustomize patch to the configuration.
+Kustomize: KustomizeConfig: Kustomization: _patches: {
+	probe: {
+		target: kind: "Service"
+		target: name: "httpbin"
+		patch: yaml.Marshal([{
+			op:    "add"
+			path:  "/metadata/annotations/prometheus.io~1probe"
+			value: "true"
+		}])
+	}
+}
+-- httpbin-component-output.txt --
+rendered httpbin in 197.030208ms
+rendered platform in 197.416416ms
+-- render.sh --
+holos render platform
+-- git-diff.sh --
+git diff
+-- git.diff --
+diff --git a/deploy/components/httpbin/httpbin.gen.yaml b/deploy/components/httpbin/httpbin.gen.yaml
+index 298b9a8..a16bd1a 100644
+--- a/deploy/components/httpbin/httpbin.gen.yaml
++++ b/deploy/components/httpbin/httpbin.gen.yaml
+@@ -1,6 +1,8 @@
+ apiVersion: v1
+ kind: Service
+ metadata:
++  annotations:
++    prometheus.io/probe: "true"
+   labels:
+     app.kubernetes.io/name: httpbin
+   name: httpbin
+-- git-commit-final.sh --
+git add . && git commit -m 'annotate httpbin for prometheus probes'

doc/md/tutorial/_kustomize/script-01-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/tutorial/_kustomize/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_kustomize/script-02-kustomize/buildplan-output.cue

@@ -0,0 +1,36 @@
+kind: BuildPlan
+apiVersion: v1alpha5
+metadata:
+  name: no-name
+spec:
+  artifacts:
+    - artifact: components/no-name/no-name.gen.yaml
+      generators:
+        - kind: Resources
+          output: resources.gen.yaml
+          resources: {}
+        - kind: File
+          output: httpbin.yaml
+          file:
+            source: httpbin.yaml
+      validators: []
+      transformers:
+        - kind: Kustomize
+          inputs:
+            - resources.gen.yaml
+            - httpbin.yaml
+          output: components/no-name/no-name.gen.yaml
+          kustomize:
+            kustomization:
+              labels:
+                - includeSelectors: false
+                  pairs:
+                    app.kubernetes.io/name: httpbin
+              patches: []
+              images:
+                - name: mccutchen/go-httpbin
+              resources:
+                - resources.gen.yaml
+                - httpbin.yaml
+              kind: Kustomization
+              apiVersion: kustomize.config.k8s.io/v1beta1

doc/md/tutorial/_kustomize/script-02-kustomize/cue-export.sh

@@ -0,0 +1 @@
+holos cue export --expression holos --out=yaml ./components/httpbin

doc/md/tutorial/_kustomize/script-02-kustomize/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-component-output.txt

@@ -0,0 +1,6 @@
+[main f0dd632] add httpbin
+ 4 files changed, 113 insertions(+)
+ create mode 100644 components/httpbin/httpbin.cue
+ create mode 100644 components/httpbin/httpbin.yaml
+ create mode 100644 deploy/components/httpbin/httpbin.gen.yaml
+ create mode 100644 platform/httpbin.cue

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-component.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add httpbin'

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-final-output.txt

@@ -0,0 +1,3 @@
+[main b120712] annotate httpbin for prometheus probes
+ 2 files changed, 18 insertions(+)
+ create mode 100644 components/httpbin/patches.cue

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-final.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'annotate httpbin for prometheus probes'

doc/md/tutorial/_kustomize/script-02-kustomize/git-diff.sh

@@ -0,0 +1 @@
+git diff

doc/md/tutorial/_kustomize/script-02-kustomize/git-init.sh

@@ -0,0 +1 @@
+git init . && git add . && git commit -m initial

doc/md/tutorial/_kustomize/script-02-kustomize/git.diff

@@ -0,0 +1,13 @@
+diff --git a/deploy/components/httpbin/httpbin.gen.yaml b/deploy/components/httpbin/httpbin.gen.yaml
+index 298b9a8..a16bd1a 100644
+--- a/deploy/components/httpbin/httpbin.gen.yaml
++++ b/deploy/components/httpbin/httpbin.gen.yaml
+@@ -1,6 +1,8 @@
+ apiVersion: v1
+ kind: Service
+ metadata:
++  annotations:
++    prometheus.io/probe: "true"
+   labels:
+     app.kubernetes.io/name: httpbin
+   name: httpbin

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-component-body.cue

@@ -0,0 +1,30 @@
+package holos
+
+// Produce a Kustomize BuildPlan for Holos
+holos: Kustomize.BuildPlan
+
+// https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/README.md
+Kustomize: #Kustomize & {
+	KustomizeConfig: {
+		// Files tells Holos to copy the file from the component path to the
+		// temporary directory Holos uses for BuildPlan execution.
+		Files: {
+			"httpbin.yaml": _
+		}
+		CommonLabels: {
+			"app.kubernetes.io/name": "httpbin"
+		}
+		// Kustomization represents a kustomization.yaml file in CUE.  Holos
+		// marshals this field into a `kustomization.yaml` while processing a
+		// BuildPlan.  See
+		// https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
+		Kustomization: {
+			images: [{name: "mccutchen/go-httpbin"}]
+			// Use a hidden field to compose patches easily with a struct.  Hidden
+			// fields are not included in exported structures.
+			_patches: {}
+			// Convert the hidden struct to a list.
+			patches: [for x in _patches {x}]
+		}
+	}
+}

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/httpbin/httpbin.cue

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-component-output.txt

@@ -0,0 +1,2 @@
+rendered httpbin in 197.030208ms
+rendered platform in 197.416416ms

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-patch-body.cue

@@ -0,0 +1,16 @@
+package holos
+
+import "encoding/yaml"
+
+// Mix in a Kustomize patch to the configuration.
+Kustomize: KustomizeConfig: Kustomization: _patches: {
+	probe: {
+		target: kind: "Service"
+		target: name: "httpbin"
+		patch: yaml.Marshal([{
+			op:    "add"
+			path:  "/metadata/annotations/prometheus.io~1probe"
+			value: "true"
+		}])
+	}
+}

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-patch-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/httpbin/patches.cue

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-yaml-body.yaml

@@ -0,0 +1,36 @@
+# https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/resources.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: httpbin
+spec:
+  template:
+    spec:
+      containers:
+        - name: httpbin
+          image: mccutchen/go-httpbin
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          readinessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          resources: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin
+spec:
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+      appProtocol: http

doc/md/tutorial/_kustomize/script-02-kustomize/httpbin-yaml-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/httpbin/httpbin.yaml

doc/md/tutorial/_kustomize/script-02-kustomize/kustomize-patch-render-output.txt

@@ -0,0 +1,2 @@
+rendered httpbin in 132.00525ms
+rendered platform in 132.124042ms

doc/md/tutorial/_kustomize/script-02-kustomize/mkdir-and-init.sh

@@ -0,0 +1,3 @@
+mkdir holos-kustomize-tutorial
+cd holos-kustomize-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_kustomize/script-02-kustomize/mkdir-component.sh

@@ -0,0 +1 @@
+mkdir -p components/httpbin

doc/md/tutorial/_kustomize/script-02-kustomize/register-component-body.cue

@@ -0,0 +1,8 @@
+package holos
+
+Platform: Components: {
+	httpbin: {
+		name: "httpbin"
+		path: "components/httpbin"
+	}
+}

doc/md/tutorial/_kustomize/script-02-kustomize/register-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/httpbin.cue

doc/md/tutorial/_kustomize/script-02-kustomize/register-component-output.txt

@@ -0,0 +1,2 @@
+rendered httpbin in 175.057083ms
+rendered platform in 175.145292ms

doc/md/tutorial/_kustomize/script-02-kustomize/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_kustomize/script-02-kustomize/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/cue.mdx

@@ -7,6 +7,7 @@ sidebar_position: 50
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
 
 # CUE
 
@@ -25,92 +26,69 @@ Key concepts:
 
 ## The Code
 
+### Holos Version
+
+Ensure you have a current version of `holos` installed.  This document was
+tested with the following version.
+
+import HolosVersionCommand from '!!raw-loader!./_cue/script-01-holos-version/command.sh';
+import HolosVersionOutput from '!!raw-loader!./_cue/script-01-holos-version/output.txt';
+
+<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
+<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
+
 ### Generating the Structure
 
 Use `holos` to generate a minimal platform directory structure. First, create
 and navigate into a blank directory. Then, use the `holos generate platform`
 command to generate a minimal platform.
 
-```shell
-mkdir holos-cue-tutorial && cd holos-cue-tutorial
-holos init platform v1alpha5
-```
+import MkdirAndInit from '!!raw-loader!./_cue/script-02-cue/mkdir-and-init.sh';
+
+<CodeBlock language="bash">{MkdirAndInit}</CodeBlock>
 
 ### Creating the Component
 
 Create the directory for the `podinfo` component. Create an empty file, then add
 the following CUE configuration to it.
 
-```bash
-mkdir -p components/podinfo
-```
-```bash
-cat <<EOF > components/podinfo/podinfo.cue
-```
-```cue showLineNumbers
-package holos
+import MkdirComponents from '!!raw-loader!./_cue/script-02-cue/mkdir-components.sh';
+import PodinfoHeader from '!!raw-loader!./_cue/script-02-cue/podinfo-component-header.sh';
+import PodinfoBody from '!!raw-loader!./_cue/script-02-cue/podinfo-component-body.cue';
+import EofTrailer from '!!raw-loader!./_cue/script-02-cue/eof-trailer.sh';
 
-// export the component build plan to holos
-holos: Component.BuildPlan
-
-// Component is a Helm chart
-Component: #Helm & {
-	Name:      "podinfo"
-	Namespace: "default"
-	// Add metadata.namespace to all resources with kustomize.
-	KustomizeConfig: Kustomization: namespace: Namespace
-	Chart: {
-		version: "6.6.2"
-		repository: {
-			name: "podinfo"
-			url:  "https://stefanprodan.github.io/podinfo"
-		}
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{PodinfoHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{PodinfoBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 Register the component with the platform.
 
-```bash
-cat <<EOF > platform/podinfo.cue
-```
-```cue showLineNumbers
-package holos
+import RegisterHeader from '!!raw-loader!./_cue/script-02-cue/register-components-header.sh';
+import RegisterBody from '!!raw-loader!./_cue/script-02-cue/register-components-body.cue';
 
-Platform: Components: podinfo: {
-	name: "podinfo"
-	path: "components/podinfo"
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{RegisterHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{RegisterBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 Render the platform.
 
+import RenderCommand from '!!raw-loader!./_cue/script-02-cue/render.sh';
+import RegisterOutput from '!!raw-loader!./_cue/script-02-cue/register-components-output.txt';
+
 <Tabs groupId="tutorial-hello-render-manifests">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```
-cached podinfo 6.6.2
-rendered podinfo in 1.938665041s
-rendered platform in 1.938759417s
-```
+    <CodeBlock language="txt">{RegisterOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Add and commit the initial configuration.
 
-```bash
-git init . && git add . && git commit -m initial
-```
+import GitInit from '!!raw-loader!./_cue/script-02-cue/git-init.sh';
+
+<CodeBlock language="bash">{GitInit}</CodeBlock>
 
 ### Mixing in Resources
 
@@ -120,39 +98,12 @@ component kind.  This field is a convenient wrapper around the core [BuildPlan]
 
 Create the mixins.cue file.
 
-```bash
-cat <<EOF > components/podinfo/mixins.cue
-```
-```cue showLineNumbers
-package holos
+import MixinHeader from '!!raw-loader!./_cue/script-02-cue/mixin-component-header.sh';
+import MixinBody from '!!raw-loader!./_cue/script-02-cue/mixin-component-body.cue';
 
-// Component fields are unified with podinfo.cue
-Component: {
-	// Concrete values are defined in podinfo.cue
-	Name:      string
-	Namespace: string
-
-	// Resources represents mix-in resources organized as a struct.
-	Resources: ExternalSecret: (Name): {
-		// Name is consistent with the component name.
-		metadata: name: Name
-		// Namespace is consistent with the component namespace.
-		metadata: namespace: Namespace
-		spec: {
-			// Ensure the target secret name is consistent.
-			target: name: metadata.name
-			// Ensure the name in the SecretStore is consistent.
-			dataFrom: [{extract: {key: metadata.name}}]
-			refreshInterval: "30s"
-			secretStoreRef: kind: "SecretStore"
-			secretStoreRef: name: "default"
-		}
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{MixinHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{MixinBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 :::important
 Holos uses CUE to validate mixed in resources against a schema.  The `Resources`
@@ -169,32 +120,15 @@ tutorial.
 To import your own custom resource definitions, use [Timoni]. We imported the
 ExternalSecret CRDs embedded in `holos` using the following command.
 
+import ImportCRDs from '!!raw-loader!./_cue/script-02-cue/import-crds.sh';
+import ImportOutput from '!!raw-loader!./_cue/script-02-cue/timoni-vendor.txt';
+
 <Tabs groupId="35B1A1A1-D7DF-4D27-A575-28556E182096">
   <TabItem value="command" label="Command">
-```bash
-timoni mod vendor crds -f https://raw.githubusercontent.com/external-secrets/external-secrets/v0.10.5/deploy/crds/bundle.yaml
-```
+    <CodeBlock language="bash">{ImportCRDs}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-2:22PM INF schemas vendored: external-secrets.io/clusterexternalsecret/v1beta1
-2:22PM INF schemas vendored: external-secrets.io/clustersecretstore/v1alpha1
-2:22PM INF schemas vendored: external-secrets.io/clustersecretstore/v1beta1
-2:22PM INF schemas vendored: external-secrets.io/externalsecret/v1alpha1
-2:22PM INF schemas vendored: external-secrets.io/externalsecret/v1beta1
-2:22PM INF schemas vendored: external-secrets.io/pushsecret/v1alpha1
-2:22PM INF schemas vendored: external-secrets.io/secretstore/v1alpha1
-2:22PM INF schemas vendored: external-secrets.io/secretstore/v1beta1
-2:22PM INF schemas vendored: generators.external-secrets.io/acraccesstoken/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/ecrauthorizationtoken/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/fake/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/gcraccesstoken/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/githubaccesstoken/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/password/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/uuid/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/vaultdynamicsecret/v1alpha1
-2:22PM INF schemas vendored: generators.external-secrets.io/webhook/v1alpha1
-```
+    <CodeBlock language="txt">{ImportOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -212,42 +146,15 @@ existing [resources.cue] file.
 
 Render the platform with the `ExternalSecret` mixed into the podinfo component.
 
-```shell
-holos render platform
-```
+<CodeBlock language="bash">{RenderCommand}</CodeBlock>
 
 Take a look at the diff to see the mixed in `ExternalSecret`.
 
-```shell
-git diff deploy
-```
+import GitDiff from '!!raw-loader!./_cue/script-02-cue/git-diff.sh';
+import DiffOutput from '!!raw-loader!./_cue/script-02-cue/git.diff';
 
-```diff
-diff --git a/deploy/components/podinfo/podinfo.gen.yaml b/deploy/components/podinfo/podinfo.gen.yaml
-index 6e4aec0..f79e9d0 100644
---- a/deploy/components/podinfo/podinfo.gen.yaml
-+++ b/deploy/components/podinfo/podinfo.gen.yaml
-@@ -112,3 +112,19 @@ spec:
-       volumes:
-       - emptyDir: {}
-         name: data
-+---
-+apiVersion: external-secrets.io/v1beta1
-+kind: ExternalSecret
-+metadata:
-+  name: podinfo
-+  namespace: default
-+spec:
-+  dataFrom:
-+  - extract:
-+      key: podinfo
-+  refreshInterval: 30s
-+  secretStoreRef:
-+    kind: SecretStore
-+    name: default
-+  target:
-+    name: podinfo
-```
+<CodeBlock language="bash">{GitDiff}</CodeBlock>
+<CodeBlock language="diff">{DiffOutput}</CodeBlock>
 
 We saw how to mix in resources using the `Resources` field of the
 [ComponentConfig]. This approach works for every kind of component in Holos,

doc/md/tutorial/cue_test.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// Run these with go test -v to see the verbose names
+func TestCue(t *testing.T) {
+	t.Run("TestCue", func(t *testing.T) {
+		// Get an ordered list of test script files.
+		dir := "_cue"
+		for _, file := range sortedTestScripts(t, filepath.Join(dir, "examples")) {
+			t.Run("examples", func(t *testing.T) {
+				runOneScript(t, dir, file)
+			})
+		}
+	})
+}

doc/md/tutorial/hello-holos.mdx

@@ -10,6 +10,7 @@ import TabItem from '@theme/TabItem';
 import RenderingOverview from '@site/src/diagrams/rendering-overview.mdx';
 import PlatformSequence from '@site/src/diagrams/render-platform-sequence.mdx';
 import ComponentSequence from '@site/src/diagrams/render-component-sequence.mdx';
+import CodeBlock from '@theme/CodeBlock';
 
 # Hello Holos
 
@@ -21,49 +22,37 @@ This introduces the core concept of wrapping Helm charts as Holos Components.
 
 ## Implementation
 
+### Holos Version
+
+Ensure you have a current version of `holos` installed.  This document was
+tested with the following version.
+
+import HolosVersionCommand from '!!raw-loader!./_hello-holos/script-01-holos-version/command.sh';
+import HolosVersionOutput from '!!raw-loader!./_hello-holos/script-01-holos-version/output.txt';
+
+<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
+<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
+
 ### Initialize Platform Structure
 
 Create and initialize a minimal platform:
 
-```shell
-mkdir holos-tutorial && cd holos-tutorial
-holos init platform v1alpha5
-```
+import MkdirAndInit from '!!raw-loader!./_hello-holos/script-02-hello-holos/mkdir-and-init.sh';
+import TreeOutput from '!!raw-loader!./_hello-holos/script-02-hello-holos/tree.txt';
 
-The resulting directory structure:
+<CodeBlock language="bash">{MkdirAndInit}</CodeBlock>
+
+For reference, the directory structure you will attain by the end of this tutorial
+is listed below (NOTE: we have omitted the `cue.mod` directory for brevity):
 
 <Tabs groupId="80D04C6A-BC83-44D0-95CC-CE01B439B159">
 <TabItem value="tree" label="Tree">
-```text showLineNumbers
-holos-tutorial/
-├── components/
-│   └── podinfo/
-│       └── podinfo.cue
-├── cue.mod/
-├── platform/
-│   ├── platform.gen.cue
-│   └── podinfo.cue
-├── resources.cue
-├── schema.cue
-└── tags.cue
-```
+<CodeBlock language="txt" showLineNumbers>{TreeOutput}</CodeBlock>
 </TabItem>
 <TabItem value="details" label="Details">
 <div style={{display: "flex"}}>
 <div>
-```text showLineNumbers
-holos-tutorial/
-├── components/
-│   └── podinfo/
-│       └── podinfo.cue
-├── cue.mod/
-├── platform/
-│   ├── platform.gen.cue
-│   └── podinfo.cue
-├── resources.cue
-├── schema.cue
-└── tags.cue
-```
+<CodeBlock language="txt" showLineNumbers>{TreeOutput}</CodeBlock>
 </div>
 <div>
 - **Line 1** The platform root is the `holos-tutorial` directory we created.
@@ -72,22 +61,24 @@ anywhere.
 - **Line 3** A component is a collection of `*.cue` files at a path.
 - **Line 4** We'll create this file and configure the podinfo helm chart in the
 next section.
-- **Line 5** The CUE module directory.  Schema definitions for Kubernetes and
-Holos resources reside within the `cue.mod` directory.
-- **Line 6** The platform directory is the **main entrypoint** for the `holos
+- **Line 5** The `vendor` directory contains a cached copy of the Helm chart that
+was fetched for the component.
+- **Line 6**  Rendered manifests are placed within the `deploy` directory following
+the structure of the `components/` directory.
+- **Line 9** The platform directory is the **main entrypoint** for the `holos
 render platform` command.
-- **Line 7** `platform.gen.cue` is initialized by `holos init platform` and
+- **Line 10** `platform.gen.cue` is initialized by `holos init platform` and
 contains the Platform spec.
-- **Line 8** `podinfo.cue` integrates podinfo with the platform by adding the
+- **Line 11** `podinfo.cue` integrates podinfo with the platform by adding the
 component to the platform spec.  We'll add ths file after the next section.
-- **Line 9** `resources.cue` Defines the Kubernetes resources available to
+- **Line 13** `resources.cue` Defines the Kubernetes resources available to
 manage in CUE.
-- **Line 10** `schema.cue` Defines the configuration common to all component
+- **Line 14** `schema.cue` Defines the configuration common to all component
 kinds.
-- **Line 11** `tags.cue` Defines where component parameter values are injected
+- **Line 15** `tags.cue` Defines where component parameter values are injected
 into the overall platform configuration.  We don't need to be concerned with
 this file until we cover component parameters.
-- **Lines 9-11** Initialized by `holos init platform`, user editable after
+- **Lines 9-15** Initialized by `holos init platform`, user editable after
 initialization.
 </div>
 </div>
@@ -98,40 +89,15 @@ initialization.
 
 Configure the `podinfo` component:
 
-```bash
-mkdir -p components/podinfo
-```
-```bash
-cat <<EOF > components/podinfo/podinfo.cue
-```
-```cue showLineNumbers
-package holos
+import MkdirComponents from '!!raw-loader!./_hello-holos/script-02-hello-holos/mkdir-components.sh';
+import PodinfoHeader from '!!raw-loader!./_hello-holos/script-02-hello-holos/podinfo-component-header.sh';
+import PodinfoBody from '!!raw-loader!./_hello-holos/script-02-hello-holos/podinfo-component-body.cue';
+import EofTrailer from '!!raw-loader!./_hello-holos/script-02-hello-holos/eof-trailer.sh';
 
-// Produce a helm chart build plan.
-holos: HelmChart.BuildPlan
-
-HelmChart: #Helm & {
-	Name: "podinfo"
-	Chart: {
-		version: "6.6.2"
-		repository: {
-			name: "podinfo"
-			url:  "https://stefanprodan.github.io/podinfo"
-		}
-	}
-	// Holos marshals Values into values.yaml for Helm.
-	Values: {
-		// message is a string with a default value.  @tag indicates a value may
-		// be injected from the platform spec component parameters.
-		ui: {
-			message: string | *"Hello World" @tag(greeting, type=string)
-		}
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{MkdirComponents}</CodeBlock>
+<CodeBlock language="bash">{PodinfoHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{PodinfoBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 :::important
 Like Go packages, CUE loads all `*.cue` files in the component directory to
@@ -148,22 +114,12 @@ root-level `schema.cue`.
 
 Register the `podinfo` component in `platform/podinfo.cue`:
 
-```bash
-cat <<EOF > platform/podinfo.cue
-```
-```cue showLineNumbers
-package holos
+import RegisterPodinfoHeader from '!!raw-loader!./_hello-holos/script-02-hello-holos/register-podinfo-header.sh';
+import RegisterPodinfoBody from '!!raw-loader!./_hello-holos/script-02-hello-holos/register-podinfo-body.cue';
 
-Platform: Components: podinfo: {
-	name: "podinfo"
-	path: "components/podinfo"
-	// Inject a value into the component.
-	parameters: greeting: "Hello Holos!"
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{RegisterPodinfoHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{RegisterPodinfoBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 :::tip
 Parameter names are unrestricted, except for the reserved `holos_` prefix.
@@ -173,161 +129,42 @@ Parameter names are unrestricted, except for the reserved `holos_` prefix.
 
 Render the `podinfo` configuration:
 
+import RenderCommand from '!!raw-loader!./_hello-holos/script-02-hello-holos/render.sh';
+import RegisterComponentsOutput from '!!raw-loader!./_hello-holos/script-02-hello-holos/register-components-output.txt';
+
 <Tabs groupId="E150C802-7162-4FBF-82A7-77D9ADAEE847">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```
-cached podinfo 6.6.2
-rendered podinfo in 1.938665041s
-rendered platform in 1.938759417s
-```
+    <CodeBlock language="txt">{RegisterComponentsOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Holos executes `helm template` with locally cached charts to generate:
 
-```txt
-deploy/components/podinfo/podinfo.gen.yaml
-```
+import PodinfoRenderedPath from '!!raw-loader!./_hello-holos/script-02-hello-holos/podinfo-rendered-path.sh';
+import RenderedService from '!!raw-loader!./_hello-holos/script-02-hello-holos/rendered-service.yaml';
+import RenderedDeployment from '!!raw-loader!./_hello-holos/script-02-hello-holos/rendered-deployment.yaml';
+
+<CodeBlock language="txt">{PodinfoRenderedPath}</CodeBlock>
 
 <Tabs groupId="0E9C231D-D0E8-410A-A4A0-601842A086A6">
   <TabItem value="service" label="Service">
-```yaml showLineNumbers
-apiVersion: v1
-kind: Service
-metadata:
-  labels:
-    app.kubernetes.io/managed-by: Helm
-    app.kubernetes.io/name: podinfo
-    app.kubernetes.io/version: 6.6.2
-    helm.sh/chart: podinfo-6.6.2
-  name: podinfo
-spec:
-  ports:
-  - name: http
-    port: 9898
-    protocol: TCP
-    targetPort: http
-  - name: grpc
-    port: 9999
-    protocol: TCP
-    targetPort: grpc
-  selector:
-    app.kubernetes.io/name: podinfo
-  type: ClusterIP
-```
+    <CodeBlock language="yaml" showLineNumbers>{RenderedService}</CodeBlock>
   </TabItem>
   <TabItem value="deployment" label="Deployment">
-```yaml showLineNumbers
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  labels:
-    app.kubernetes.io/managed-by: Helm
-    app.kubernetes.io/name: podinfo
-    app.kubernetes.io/version: 6.6.2
-    helm.sh/chart: podinfo-6.6.2
-  name: podinfo
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: podinfo
-  strategy:
-    rollingUpdate:
-      maxUnavailable: 1
-    type: RollingUpdate
-  template:
-    metadata:
-      annotations:
-        prometheus.io/port: "9898"
-        prometheus.io/scrape: "true"
-      labels:
-        app.kubernetes.io/name: podinfo
-    spec:
-      containers:
-      - command:
-        - ./podinfo
-        - --port=9898
-        - --cert-path=/data/cert
-        - --port-metrics=9797
-        - --grpc-port=9999
-        - --grpc-service-name=podinfo
-        - --level=info
-        - --random-delay=false
-        - --random-error=false
-        env:
-        - name: PODINFO_UI_MESSAGE
-          value: Hello Holos!
-        - name: PODINFO_UI_COLOR
-          value: '#34577c'
-        image: ghcr.io/stefanprodan/podinfo:6.6.2
-        imagePullPolicy: IfNotPresent
-        livenessProbe:
-          exec:
-            command:
-            - podcli
-            - check
-            - http
-            - localhost:9898/healthz
-          failureThreshold: 3
-          initialDelaySeconds: 1
-          periodSeconds: 10
-          successThreshold: 1
-          timeoutSeconds: 5
-        name: podinfo
-        ports:
-        - containerPort: 9898
-          name: http
-          protocol: TCP
-        - containerPort: 9797
-          name: http-metrics
-          protocol: TCP
-        - containerPort: 9999
-          name: grpc
-          protocol: TCP
-        readinessProbe:
-          exec:
-            command:
-            - podcli
-            - check
-            - http
-            - localhost:9898/readyz
-          failureThreshold: 3
-          initialDelaySeconds: 1
-          periodSeconds: 10
-          successThreshold: 1
-          timeoutSeconds: 5
-        resources:
-          limits: null
-          requests:
-            cpu: 1m
-            memory: 16Mi
-        volumeMounts:
-        - mountPath: /data
-          name: data
-      terminationGracePeriodSeconds: 30
-      volumes:
-      - emptyDir: {}
-        name: data
-```
+    <CodeBlock language="yaml" showLineNumbers>{RenderedDeployment}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Holos renders the component with the greeting injected from the platform spec.
 
-```shell
-grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml
-```
-```yaml
-        env:
-        - name: PODINFO_UI_MESSAGE
-          value: Hello Holos!
-```
+import GrepForMessage from '!!raw-loader!./_hello-holos/script-02-hello-holos/grep-for-message.sh';
+import GreppedOutput from '!!raw-loader!./_hello-holos/script-02-hello-holos/grepped-output.txt';
+
+<CodeBlock language="bash">{GrepForMessage}</CodeBlock>
+<CodeBlock language="yaml">{GreppedOutput}</CodeBlock>
 
 ## Breaking it down
 

doc/md/tutorial/hello-holos_test.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// Run these with go test -v to see the verbose names
+func TestHelloHolos(t *testing.T) {
+	t.Run("TestHelloHolos", func(t *testing.T) {
+		// Get an ordered list of test script files.
+		dir := "_hello-holos"
+		for _, file := range sortedTestScripts(t, filepath.Join(dir, "examples")) {
+			t.Run("examples", func(t *testing.T) {
+				runOneScript(t, dir, file)
+			})
+		}
+	})
+}

doc/md/tutorial/kustomize.mdx

@@ -7,6 +7,7 @@ sidebar_position: 45
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
 
 # Kustomize
 
@@ -24,6 +25,17 @@ covered in the [Helm Values] tutorial.
 
 ## The Code
 
+### Holos Version
+
+Ensure you have a current version of `holos` installed.  This document was
+tested with the following version.
+
+import HolosVersionCommand from '!!raw-loader!./_kustomize/script-01-holos-version/command.sh';
+import HolosVersionOutput from '!!raw-loader!./_kustomize/script-01-holos-version/output.txt';
+
+<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
+<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
+
 ### Generating the structure
 
 <Tabs>
@@ -39,18 +51,14 @@ Use `holos` to generate a minimal platform directory structure. First, create
 and navigate into a blank directory. Then, run the `holos init platform`
 command.
 
-```shell
-mkdir holos-kustomize-tutorial
-cd holos-kustomize-tutorial
-holos init platform v1alpha5
-```
+import MkdirAndInit from '!!raw-loader!./_kustomize/script-02-kustomize/mkdir-and-init.sh';
+import GitInit from '!!raw-loader!./_kustomize/script-02-kustomize/git-init.sh';
+
+<CodeBlock language="bash">{MkdirAndInit}</CodeBlock>
 
 Make a commit to track changes.
 
-```bash
-git init . && git add . && git commit -m initial
-```
-
+<CodeBlock language="bash">{GitInit}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -59,97 +67,26 @@ git init . && git add . && git commit -m initial
 Create the `httpbin` component directory, and add the `httpbin.cue` and
 `httpbin.yaml` files to it for configuration and setup.
 
+import MkdirComponent from '!!raw-loader!./_kustomize/script-02-kustomize/mkdir-component.sh';
+import HttpbinComponentHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-component-header.sh';
+import HttpbinComponentBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-component-body.cue';
+import EofTrailer from '!!raw-loader!./_kustomize/script-02-kustomize/eof-trailer.sh';
+import HttpbinYamlHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-yaml-header.sh';
+import HttpbinYamlBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-yaml-body.yaml';
+
 <Tabs groupId="800C3AE7-E7F8-4AFC-ABF1-6AFECD945958">
   <TabItem value="setup" label="Setup">
-```bash
-mkdir -p components/httpbin
-```
+    <CodeBlock language="bash">{MkdirComponent}</CodeBlock>
   </TabItem>
   <TabItem value="components/httpbin/httpbin.cue" label="httpbin.cue">
-```bash
-cat <<EOF > components/httpbin/httpbin.cue
-```
-```cue showLineNumbers
-package holos
-
-// Produce a Kustomize BuildPlan for Holos
-holos: Kustomize.BuildPlan
-
-// https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/README.md
-Kustomize: #Kustomize & {
-	KustomizeConfig: {
-		// Files tells Holos to copy the file from the component path to the
-		// temporary directory Holos uses for BuildPlan execution.
-		Files: {
-			"httpbin.yaml": _
-		}
-		CommonLabels: {
-			"app.kubernetes.io/name": "httpbin"
-		}
-		// Kustomization represents a kustomization.yaml file in CUE.  Holos
-		// marshals this field into a `kustomization.yaml` while processing a
-		// BuildPlan.  See
-		// https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
-		Kustomization: {
-			images: [{name: "mccutchen/go-httpbin"}]
-			// Use a hidden field to compose patches easily with a struct.  Hidden
-			// fields are not included in exported structures.
-			_patches: {}
-			// Convert the hidden struct to a list.
-			patches: [for x in _patches {x}]
-		}
-	}
-}
-```
-```bash
-EOF
-```
+    <CodeBlock language="bash">{HttpbinComponentHeader}</CodeBlock>
+    <CodeBlock language="cue" showLineNumbers>{HttpbinComponentBody}</CodeBlock>
+    <CodeBlock language="bash">{EofTrailer}</CodeBlock>
   </TabItem>
   <TabItem value="components/httpbin/httpbin.yaml" label="httpbin.yaml">
-```bash
-cat <<EOF > components/httpbin/httpbin.yaml
-```
-```yaml showLineNumbers
-# https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/resources.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: httpbin
-spec:
-  template:
-    spec:
-      containers:
-        - name: httpbin
-          image: mccutchen/go-httpbin
-          ports:
-            - name: http
-              containerPort: 8080
-              protocol: TCP
-          livenessProbe:
-            httpGet:
-              path: /status/200
-              port: http
-          readinessProbe:
-            httpGet:
-              path: /status/200
-              port: http
-          resources: {}
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: httpbin
-spec:
-  ports:
-    - port: 80
-      targetPort: http
-      protocol: TCP
-      name: http
-      appProtocol: http
-```
-```bash
-EOF
-```
+    <CodeBlock language="bash">{HttpbinYamlHeader}</CodeBlock>
+    <CodeBlock language="yaml" showLineNumbers>{HttpbinYamlBody}</CodeBlock>
+    <CodeBlock language="bash">{EofTrailer}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -161,56 +98,38 @@ Holos knows the `httpbin.yaml` file is part of the BuildPlan because of the
 Register `httpbin` with the platform by adding the following file to the
 platform directory.
 
-```bash
-cat <<EOF > platform/httpbin.cue
-```
-```cue showLineNumbers
-package holos
+import RegisterComponentHeader from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-header.sh';
+import RegisterComponentBody from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-body.cue';
 
-Platform: Components: {
-	httpbin: {
-		name: "httpbin"
-		path: "components/httpbin"
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{RegisterComponentHeader}</CodeBlock>
+<CodeBlock language="cue">{RegisterComponentBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 Render the platform.
 
+import RenderCommand from '!!raw-loader!./_kustomize/script-02-kustomize/render.sh';
+import RegisterComponentOutput from '!!raw-loader!./_kustomize/script-02-kustomize/register-component-output.txt';
+
 <Tabs groupId="B120D5D1-0EAB-41E0-AD21-15526EBDD53D">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-rendered httpbin in 707.554666ms
-rendered platform in 707.9845ms
-```
+    <CodeBlock language="txt">{RegisterComponentOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Commit the results.
 
+import GitCommitComponent from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-component.sh';
+import GitCommitComponentOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-component-output.txt';
+
 <Tabs groupId="446CC550-A634-45C0-BEC7-992E5C56D4FA">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'add httpbin'
-```
+    <CodeBlock language="bash">{GitCommitComponent}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main c05f9ef] add httpbin
- 4 files changed, 118 insertions(+)
- create mode 100644 components/httpbin/httpbin.cue
- create mode 100644 components/httpbin/httpbin.yaml
- create mode 100644 deploy/components/httpbin/httpbin.gen.yaml
- create mode 100644 platform/httpbin.cue
-```
+    <CodeBlock language="txt">{GitCommitComponentOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -220,55 +139,15 @@ We can see the [BuildPlan] exported to `holos` by the `holos:
 Kustomize.BuildPlan` line in `httpbin.cue`. Holos processes this build plan to
 produce the fully rendered manifests.
 
+import CueExport from '!!raw-loader!./_kustomize/script-02-kustomize/cue-export.sh';
+import BuildplanOutput from '!!raw-loader!./_kustomize/script-02-kustomize/buildplan-output.cue';
+
 <Tabs groupId="DD697D65-5BEC-4B92-BB33-59BE4FEC112F">
   <TabItem value="command" label="Command">
-```bash
-holos cue export --expression holos --out=yaml ./components/httpbin
-```
+    <CodeBlock language="bash">{CueExport}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```yaml showLineNumbers
-kind: BuildPlan
-apiVersion: v1alpha5
-metadata:
-  name: no-name
-spec:
-  artifacts:
-    - artifact: components/no-name/no-name.gen.yaml
-      generators:
-        - kind: Resources
-          output: resources.gen.yaml
-          resources: {}
-        - kind: File
-          output: httpbin.yaml
-          file:
-            source: httpbin.yaml
-      transformers:
-        - kind: Kustomize
-          inputs:
-            - resources.gen.yaml
-            - httpbin.yaml
-          output: components/no-name/no-name.gen.yaml
-          kustomize:
-            kustomization:
-              labels:
-                - includeSelectors: false
-                  pairs:
-                    app.kubernetes.io/name: httpbin
-              patches: []
-              images:
-                - name: mccutchen/go-httpbin
-              resources:
-                - resources.gen.yaml
-                - httpbin.yaml
-              kind: Kustomization
-              apiVersion: kustomize.config.k8s.io/v1beta1
-source:
-  component:
-    name: no-name
-    path: no-path
-    parameters: {}
-```
+    <CodeBlock language="yaml">{BuildplanOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -291,30 +170,12 @@ need to edit any YAML files manually.
 Add a new `patches.cue` file to the `httpbin` component with the following
 content.
 
-```bash
-cat <<EOF > components/httpbin/patches.cue
-```
-```cue showLineNumbers
-package holos
+import HttpbinPatchHeader from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-patch-header.sh';
+import HttpbinPatchBody from '!!raw-loader!./_kustomize/script-02-kustomize/httpbin-patch-body.cue';
 
-import "encoding/yaml"
-
-// Mix in a Kustomize patch to the configuration.
-Kustomize: KustomizeConfig: Kustomization: _patches: {
-	probe: {
-		target: kind: "Service"
-		target: name: "httpbin"
-		patch: yaml.Marshal([{
-			op:    "add"
-			path:  "/metadata/annotations/prometheus.io~1probe"
-			value: "true"
-		}])
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{HttpbinPatchHeader}</CodeBlock>
+<CodeBlock language="bash" showLineNumbers>{HttpbinPatchBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 :::note
 We use a hidden `_patches` field to easily unify data into a struct, then
@@ -325,62 +186,43 @@ convert the struct into a list for export.
 
 Render the platform to see the result of the kustomization patch.
 
+import KustomizePatchRenderOutput from '!!raw-loader!./_kustomize/script-02-kustomize/kustomize-patch-render-output.txt';
+
 <Tabs groupId="5D1812DD-8E7B-4F97-B349-275214F38B6E">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-rendered httpbin in 197.030208ms
-rendered platform in 197.416416ms
-```
+    <CodeBlock language="txt">{KustomizePatchRenderOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Holos is configuring Kustomize to patch the plain `httpbin.yaml` file with the
 annotation.
 
+import GitDiff from '!!raw-loader!./_kustomize/script-02-kustomize/git-diff.sh';
+import GitDiffOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git.diff';
+
 <Tabs groupId="3D80279E-8EDE-4B3E-9269-50F5D1C1CA42">
   <TabItem value="command" label="Command">
-```bash
-git diff
-```
+    <CodeBlock language="bash">{GitDiff}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```diff
-diff --git a/deploy/components/httpbin/httpbin.gen.yaml b/deploy/components/httpbin/httpbin.gen.yaml
-index 298b9a8..a16bd1a 100644
---- a/deploy/components/httpbin/httpbin.gen.yaml
-+++ b/deploy/components/httpbin/httpbin.gen.yaml
-@@ -1,6 +1,8 @@
- apiVersion: v1
- kind: Service
- metadata:
-+  annotations:
-+    prometheus.io/probe: "true"
-   labels:
-     app.kubernetes.io/name: httpbin
-   name: httpbin
-
-```
+    <CodeBlock language="diff">{GitDiffOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Add and commit the final changes.
 
+import GitCommitFinal from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-final.sh';
+import GitCommitFinalOutput from '!!raw-loader!./_kustomize/script-02-kustomize/git-commit-final-output.txt';
+
 <Tabs groupId="54C335C8-B382-4277-AE87-0D6556921955">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'annotate httpbin for prometheus probes'
-```
+    <CodeBlock language="bash">{GitCommitFinal}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main 6eeeadb] annotate httpbin for prometheus probes
- 2 files changed, 3 insertions(+), 1 deletion(-)
-```
+    <CodeBlock language="txt">{GitCommitFinalOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 

doc/md/tutorial/kustomize_test.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// Run these with go test -v to see the verbose names
+func TestKustomize(t *testing.T) {
+	t.Run("TestKustomize", func(t *testing.T) {
+		// Get an ordered list of test script files.
+		dir := "_kustomize"
+		for _, file := range sortedTestScripts(t, filepath.Join(dir, "examples")) {
+			t.Run("examples", func(t *testing.T) {
+				runOneScript(t, dir, file)
+			})
+		}
+	})
+}

scripts/test

@@ -1,3 +1,7 @@
 #! /bin/bash
 set -xeuo pipefail
+
+# Necessary to install timoni for testscript execution
+make go-deps
+
 go test -coverprofile=coverage.out ./...

tools/tools.go

@@ -16,4 +16,5 @@ import (
 	_ "golang.org/x/tools/cmd/godoc"
 	_ "google.golang.org/protobuf/cmd/protoc-gen-go"
 	_ "honnef.co/go/tools/cmd/staticcheck"
+	- "github.com/stefanprodan/timoni/cmd/timoni"
 )