docs/tutorial: make custom modules registry tutorial runnable

cue mod registry allows us to use cmd/cue to run an in-memory
OCI-compatible server. This is sufficient for the tutorial on
custom module registries.

We can therefore make the entire tutorial runnable by removing the
special #norun directives.

This process caught a couple of bugs which are fixed as part of this
change.

It also allows a couple of file content assertions to be replaced with
calls to cat which render the actual contents of the files. Because the
rendered result is also committed to VCS, we therefore capture the
intended result.

Preview-Path: /docs/tutorial/working-with-a-custom-module-registry/
Signed-off-by: Paul Jolly <[email protected]>
Change-Id: I82b4c21426d6bf6fc45e0105ebbba0a0dffb1d56
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1176732
Reviewed-by: Roger Peppe <[email protected]>
Reviewed-by: Jonathan Matthews <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

content/docs/tutorial/working-with-a-custom-module-registry/en.md

@@ -9,6 +9,13 @@ tags:
 toc_hide: true
 ---
 
+{{{with _script "en" "cue mod registry"}}}
+# TODO: this is inherently racey. But not a problem in practice...
+# for now. When it does become a problem we can solve this properly
+# using a nc-based wait loop or similar.
+nohup cue mod registry localhost:5000 > /tmp/cue_mod_registry 2>&1 &
+{{{end}}}
+
 ## Introduction
 
 In this tutorial you will learn how to create and work with CUE modules,
@@ -54,8 +61,6 @@ We would like to be able to share the schema between several consumers.
 
 Create a directory to hold the schema code:
 {{{with script "en" "create-frostyconfig"}}}
-#norun
-
 mkdir frostyconfig
 cd frostyconfig
 {{{end}}}
@@ -68,8 +73,6 @@ you will create as they are needed.
 
 Initialize the directory as a module:
 {{{with script "en" "initialize-frostyconfig-module"}}}
-#norun
-
 cue mod init glacial-tech.example/frostyconfig@v0
 {{{end}}}
 
@@ -164,8 +167,6 @@ tutorial.
 
 Set up some required envirionment variables:
 {{{with script "en" "init-environ"}}}
-#norun
-
 export CUE_EXPERIMENT=modules
 export CUE_REGISTRY=localhost:5000/cuemodules
 {{{end}}}
@@ -176,7 +177,7 @@ support is currently in its experimental phase.
 The `CUE_REGISTRY` variable tells the `cue` command which
 registry to use when fetching and pushing modules.
 In our example the modules will be stored in the registry under the prefix `cuemodules`.
-In practice you would want this prefix to be some place of your choice - 
+In practice you would want this prefix to be some place of your choice -
 or you could leave the prefix empty if you plan to dedicate the registry
 to holding CUE modules.
 {{{end}}}
@@ -185,8 +186,6 @@ to holding CUE modules.
 
 Ensure the `module.cue` file is tidy:
 {{{with script "en" "frostyconfig-v0.0.1-tidy"}}}
-#norun
-
 cue mod tidy
 {{{end}}}
 This command checks that modules for all imported packages
@@ -200,8 +199,6 @@ have any dependencies, we will run `cue mod tidy` anyway.
 
 Publish the first version of this module:
 {{{with script "en" "frostyconfig-v0.0.1-publish"}}}
-#norun
-
 cue mod publish v0.0.1
 {{{end}}}
 
@@ -232,8 +229,6 @@ published.
 
 Create a directory for the new module and initalize it:
 {{{with script "en" "init-frostyapp"}}}
-#norun
-
 mkdir ../frostyapp
 cd    ../frostyapp
 cue mod init glacial-tech.example/frostyapp@v0
@@ -266,23 +261,14 @@ constrained by the `frostyconfig.#Config` schema.
 
 Ensure the module is tidy, pulling all dependencies:
 {{{with script "en" "frostyapp-tidy-1"}}}
-#norun
-
 cue mod tidy
 {{{end}}}
 
 We can see that the dependencies have now been added to the
 `cue.mod/module.cue` file:
 
-<!-- TODO: show actual file content -->
-{{{with upload "en" "frostyapp-tidy-result-1"}}}
--- frostyapp/cue.mod/module.cue --
-module: "glacial-tech.example/frostyapp@v0"
-deps: {
-	"glacial-tech.example/frostyconfig@v0": {
-		v: "v0.0.1"
-	}
-}
+{{{with script "en" "show frostyapp-tidy-result-1"}}}
+cat cue.mod/module.cue
 {{{end}}}
 
 Our dependencies currently look like this:
@@ -298,22 +284,11 @@ flowchart TD
 
 Export the configuration as YAML:
 {{{with script "en" "frostyapp-export-1"}}}
-#norun
-
 cue export --out yaml
 {{{end}}}
 
 We can use this new module code just like any other CUE code.
 
-<!-- TODO: show actual file content -->
-Here is the output:
-```
-config:
-  appName: alpha
-  port: 80
-  features:
-    logging: true
-```
 {{{end}}}
 
 ## Publish a `frostytemplate` module
@@ -329,8 +304,6 @@ other source of truth.
 
 Create a directory for the new module and initalize it:
 {{{with script "en" "init-frostytemplate"}}}
-#norun
-
 mkdir ../frostytemplate
 cd    ../frostytemplate
 cue mod init glacial-tech.example/frostytemplate@v0
@@ -370,8 +343,6 @@ We import the schema to constrain the default values, just as we did with the
 
 Publish the `frostytemplate` module:
 {{{with script "en" "frostytemplate-v0.0.1-publish"}}}
-#norun
-
 cue mod tidy
 cue mod publish v0.0.1
 {{{end}}}
@@ -383,6 +354,11 @@ cue mod publish v0.0.1
 
 Update the `frostyapp` module to make use of this new template
 module:
+
+{{{with script "en" "back to frostyapp to use template"}}}
+cd ../frostyapp
+{{{end}}}
+
 {{{with upload "en" "update-frostyapp"}}}
 -- frostyapp/config.cue --
 package frostyapp
@@ -403,8 +379,6 @@ requirements of the configuration.
 
 Resolve dependencies in `frostyapp`:
 {{{with script "en" "frostyapp-tidy-2"}}}
-#norun
-
 cue mod tidy
 {{{end}}}
 
@@ -413,18 +387,8 @@ use `frostytemplate` as well as `frostyconfig`.
 
 Here is what the `cue.mod/module.cue` file now looks like:
 
-<!-- TODO: show actual file content -->
-{{{with upload "en" "frostyapp-tidy-result-2"}}}
--- frostyapp/cue.mod/module.cue --
-module: "glacial-tech.example/frostyapp@v0"
-deps: {
-	"glacial-tech.example/frostyconfig@v0": {
-		v: "v0.0.1"
-	}
-	"glacial-tech.example/frostytemplate@v0": {
-		v: "v0.0.1"
-	}
-}
+{{{with script "en" "show frostyapp-tidy-result-2"}}}
+cat cue.mod/module.cue
 {{{end}}}
 
 {{< mermaid caption="Current dependencies" >}}
@@ -438,23 +402,11 @@ flowchart TD
 
 Re-render the configuration as YAML:
 {{{with script "en" "rerender-config"}}}
-#norun
-
 cue export --out yaml
 {{{end}}}
 
-We can see that the values in the configuration reflect the new default values:
+We can see that the values in the configuration reflect the new default values.
 
-<!-- TODO: show actual file content -->
-```
-config:
-  appName: alpha
-  port: 80
-  debug: false
-  features:
-    logging: true
-    analytics: true
-```
 {{{end}}}
 
 ## Add a new field to the schema
@@ -466,6 +418,10 @@ We will add that field to the schema and update the app to use it.
 {{{with step}}}
 
 Update the schema to add a new `maxConcurrency` field:
+{{{with script "en" "return to schema to add maxConcurrency field"}}}
+cd ../frostyconfig
+{{{end}}}
+
 {{{with upload "en" "schema-v0.1.0"}}}
 -- frostyconfig/config.cue --
 package frostyconfig
@@ -498,9 +454,6 @@ The schema is unchanged except for the new `maxConcurrency` field.
 
 Upload a new version of the `frostyconfig` schema:
 {{{with script "en" "upload-schema2"}}}
-#norun
-
-cd ../frostyconfig
 cue mod tidy
 cue mod publish v0.1.0
 {{{end}}}
@@ -514,6 +467,11 @@ compatible feature has been added.
 {{{with step}}}
 
 Edit the `cue.mod/module.cue` file to use the new version:
+
+{{{with script "en" "return to app to use updated schema"}}}
+cd ../frostyapp
+{{{end}}}
+
 {{{with upload "en" "edit-dependency-version"}}}
 -- frostyapp/cue.mod/module.cue --
 module: "glacial-tech.example/frostyapp@v0"
@@ -549,13 +507,11 @@ future the `cue` command will be able to perform this kind of update.
 
 Check that everything still works and that your configuration is still valid:
 {{{with script "en" "check-update-ok"}}}
-#norun
-
 cue mod tidy
 cue export --out yaml
 {{{end}}}
 
-So exactly has happened above?
+So exactly what happened above?
 
 Recall that the `glacial-tech.example/frostytemplate` module remains unchanged:
 its module still depends on the original `v0.0.1` version of the schema. By