docs: more work, rename first-example to the-walkthrough

.hof/shadow/cli/cmd/hof/cmd/gen.go

@@ -83,7 +83,7 @@ var genLong = `hof unifies CUE with Go's text/template system and diff3
 
 # Compose code gen mappings into reusable modules with
   hof gen app.cue -G frontend -G backend -G migrations -T ...
-  https://docs.hofstadter.io/first-example/`
+  https://docs.hofstadter.io/the-walkthrough/`
 
 func init() {
 

README.md

@@ -14,7 +14,7 @@ __`hof` is a CLI tool you *add* to your workflow.__
 | Core Features | |
 |:---                    |:-- |
 | __code generation__    | Data + templates = _ (anything), technology agnostic |
-| __data model__         | Define and manage data models, life-cycle features |
+| __data modeling__      | Define, checkpoint, and diff data models |
 | __task engine__        | Extensible task and DAG workflow engine |
 | __CUE cmds__           | Core def, eval, export, and vet commands |
 | __creators__           | bootstraping and starter kits from any repo |
@@ -39,7 +39,7 @@ Learn more about CUE: [cuelang.org](https://cuelang.org) | [cuetorials.com](http
 Please see __[docs.hofstadter.io](https://docs.hofstadter.io)__ to learn more.
 
 The [getting-started](https://docs.hofstadter.io/getting-started/) section will take you on a tour of hof.
-The [first-example](https://docs.hofstadter.io/first-example/) section shows you how to build and use a generator.
+The [the-walkthrough](https://docs.hofstadter.io/the-walkthrough/) section shows you how to build and use a generator.
 
 Join us or ask questions on
 

cmd/hof/cmd/gen.go

@@ -84,7 +84,7 @@ var genLong = `hof unifies CUE with Go's text/template system and diff3
 
 # Compose code gen mappings into reusable modules with
   hof gen app.cue -G frontend -G backend -G migrations -T ...
-  https://docs.hofstadter.io/first-example/`
+  https://docs.hofstadter.io/the-walkthrough/`
 
 func init() {
 

design/cmds/gen.cue

@@ -195,5 +195,5 @@ GenLongHelp: """
 
 	# Compose code gen mappings into reusable modules with
 	  hof gen app.cue -G frontend -G backend -G migrations -T ...
-	  https://docs.hofstadter.io/first-example/
+	  https://docs.hofstadter.io/the-walkthrough/
 	"""

docs/ci/server.template

@@ -37,6 +37,10 @@ server {
     proxy_pass https://www.google-analytics.com;
   }
 
+  location /the-walkthrough {
+    rewrite ^ /the-walkthrough;
+  }
+
   location / {
     try_files $uri $uri/ =404;
     expires -1;

docs/code/Makefile

@@ -1,5 +1,5 @@
 gen:
-	make -C first-example gen
+	make -C the-walkthrough gen
 
 test:
-	make -C first-example test
+	make -C the-walkthrough test

docs/code/cmd-help/def

@@ -0,0 +1,32 @@
+print consolidated CUE definitions
+
+Usage:
+  hof def [flags]
+
+Flags:
+  -a, --attributes               diplay field attributes
+  -C, --comments                 include comments in output
+  -e, --expression stringArray   evaluate these expressions only
+  -h, --help                     help for def
+      --inline-imports           expand references to non-core imports
+      --list                     concatenate multiple objects into a list
+      --out string               output data format, when detection does not work
+  -o, --outfile string           filename or - for stdout with optional file prefix
+      --simplify                 simplify CUE statements where possible
+
+Global Flags:
+  -E, --all-errors               print all available errors
+  -i, --ignore-errors            turn off output and assume defaults at prompts
+  -D, --include-data             auto include all data files found with cue files
+  -V, --inject-env               inject all ENV VARs as default tag vars
+  -I, --input stringArray        extra data to unify into the root value
+  -p, --package string           the Cue package context to use during execution
+  -l, --path stringArray         CUE expression for single path component when placing data files
+  -q, --quiet                    turn off output and assume defaults at prompts
+  -d, --schema stringArray       expression to select schema to apply to data files
+      --stats                    print generator statistics
+  -0, --stdin-empty              A flag that ensure stdin is zero and does not block
+  -t, --tags stringArray         @tags() to be injected into CUE code
+  -U, --user-files stringArray   file globs to embed into the root value (<cue-path>=<file-glob>), use % as slash to trim before
+  -v, --verbosity int            set the verbosity of output
+      --with-context             add extra context for data files, usable in the -l/path flag

docs/code/cmd-help/dev

@@ -0,0 +1,7 @@
+unknown command "dev" for "hof"
+
+Did you mean this?
+	gen
+	def
+	vet
+

docs/code/cmd-help/eval

@@ -0,0 +1,41 @@
+evaluate and print CUE configuration
+
+Usage:
+  hof eval [flags]
+
+Flags:
+  -a, --all                      show optional and hidden fields
+  -A, --attributes               display field attributes
+  -C, --comments                 include comments in output
+  -c, --concrete                 require the evaluation to be concrete
+      --defaults                 use default values if not set
+  -S, --definitions              display defintions (default true)
+      --escape                   use HTLM escaping
+  -e, --expression stringArray   evaluate these expressions only
+      --final                    finalize the value (default true)
+  -h, --help                     help for eval
+  -H, --hidden                   display hidden fields
+      --inline-imports           expand references to non-core imports
+      --list                     concatenate multiple objects into a list
+  -O, --optional                 display optional fields
+      --out string               output data format, when detection does not work
+  -o, --outfile string           filename or - for stdout with optional file prefix
+      --resolve                  resolve references in value
+      --simplify                 simplify CUE statements where possible
+
+Global Flags:
+  -E, --all-errors               print all available errors
+  -i, --ignore-errors            turn off output and assume defaults at prompts
+  -D, --include-data             auto include all data files found with cue files
+  -V, --inject-env               inject all ENV VARs as default tag vars
+  -I, --input stringArray        extra data to unify into the root value
+  -p, --package string           the Cue package context to use during execution
+  -l, --path stringArray         CUE expression for single path component when placing data files
+  -q, --quiet                    turn off output and assume defaults at prompts
+  -d, --schema stringArray       expression to select schema to apply to data files
+      --stats                    print generator statistics
+  -0, --stdin-empty              A flag that ensure stdin is zero and does not block
+  -t, --tags stringArray         @tags() to be injected into CUE code
+  -U, --user-files stringArray   file globs to embed into the root value (<cue-path>=<file-glob>), use % as slash to trim before
+  -v, --verbosity int            set the verbosity of output
+      --with-context             add extra context for data files, usable in the -l/path flag

docs/code/cmd-help/export

@@ -0,0 +1,31 @@
+output data in a standard format
+
+Usage:
+  hof export [flags]
+
+Flags:
+  -C, --comments                 include comments in output
+      --escape                   use HTLM escaping
+  -e, --expression stringArray   evaluate these expressions only
+  -h, --help                     help for export
+      --list                     concatenate multiple objects into a list
+      --out string               output data format, when detection does not work
+  -o, --outfile string           filename or - for stdout with optional file prefix
+      --simplify                 simplify CUE statements where possible
+
+Global Flags:
+  -E, --all-errors               print all available errors
+  -i, --ignore-errors            turn off output and assume defaults at prompts
+  -D, --include-data             auto include all data files found with cue files
+  -V, --inject-env               inject all ENV VARs as default tag vars
+  -I, --input stringArray        extra data to unify into the root value
+  -p, --package string           the Cue package context to use during execution
+  -l, --path stringArray         CUE expression for single path component when placing data files
+  -q, --quiet                    turn off output and assume defaults at prompts
+  -d, --schema stringArray       expression to select schema to apply to data files
+      --stats                    print generator statistics
+  -0, --stdin-empty              A flag that ensure stdin is zero and does not block
+  -t, --tags stringArray         @tags() to be injected into CUE code
+  -U, --user-files stringArray   file globs to embed into the root value (<cue-path>=<file-glob>), use % as slash to trim before
+  -v, --verbosity int            set the verbosity of output
+      --with-context             add extra context for data files, usable in the -l/path flag

docs/code/cmd-help/gen

@@ -66,7 +66,7 @@ hof unifies CUE with Go's text/template system and diff3
 
 # Compose code gen mappings into reusable modules with
   hof gen app.cue -G frontend -G backend -G migrations -T ...
-  https://docs.hofstadter.io/first-example/
+  https://docs.hofstadter.io/the-walkthrough/
 
 Usage:
   hof gen [files...] [flags]

docs/code/cmd-help/vet

@@ -0,0 +1,35 @@
+validate data with CUE
+
+Usage:
+  hof vet [flags]
+
+Flags:
+  -A, --attributes               display field attributes
+  -C, --comments                 include comments in output
+  -c, --concrete                 require the evaluation to be concrete
+  -S, --definitions              display defintions (default true)
+  -e, --expression stringArray   evaluate these expressions only
+  -h, --help                     help for vet
+  -H, --hidden                   display hidden fields
+      --list                     concatenate multiple objects into a list
+  -O, --optional                 display optional fields
+      --out string               output data format, when detection does not work
+  -o, --outfile string           filename or - for stdout with optional file prefix
+      --simplify                 simplify CUE statements where possible
+
+Global Flags:
+  -E, --all-errors               print all available errors
+  -i, --ignore-errors            turn off output and assume defaults at prompts
+  -D, --include-data             auto include all data files found with cue files
+  -V, --inject-env               inject all ENV VARs as default tag vars
+  -I, --input stringArray        extra data to unify into the root value
+  -p, --package string           the Cue package context to use during execution
+  -l, --path stringArray         CUE expression for single path component when placing data files
+  -q, --quiet                    turn off output and assume defaults at prompts
+  -d, --schema stringArray       expression to select schema to apply to data files
+      --stats                    print generator statistics
+  -0, --stdin-empty              A flag that ensure stdin is zero and does not block
+  -t, --tags stringArray         @tags() to be injected into CUE code
+  -U, --user-files stringArray   file globs to embed into the root value (<cue-path>=<file-glob>), use % as slash to trim before
+  -v, --verbosity int            set the verbosity of output
+      --with-context             add extra context for data files, usable in the -l/path flag

docs/code/getting-started/code-generation/adhoc-mod-snippet.cue

@@ -4,15 +4,20 @@ import (
 	"github.com/hofstadter-io/hof/schema/gen"
 }
 
-foo: gen.#Generator: {
+foo: gen.Generator & {
 	@gen(foo)
 
 	// input data
 	In: _
 
-	Out: [
-		// list of files to generate
-	]
+	// normally when writing generators as code
+	// you add the CUE to turn In -> Out
+	//   - provide project specific config and flags
+	//   - dynamically decide what files to generate
+	//   - craft schemas and DSLs to create anything
 
-	// other fields filled by hof
+	// list of files to generate
+	Out: [...gen.File]
+
+	// other fields filled by hof when you turn adhoc -> reusable
 }

docs/code/getting-started/task-engine/server.cue

@@ -0,0 +1,66 @@
+package examples
+
+import "strings"
+
+server: {
+  @flow(server)
+
+  // task: get auth from external command
+  gcp: {
+    @task(os.Exec)
+    cmd: ["gcloud", "auth", "print-access-token"]
+    stdout: string
+    key:    strings.TrimSpace(stdout)
+  }
+
+  run: {
+    @task(api.Serve)
+
+    port: "8080"
+    routes: {
+
+      // simple hello route
+      "/hello": {
+        method: "GET"
+        resp: {
+          status: 200
+          body: "hallo chat!"
+        }
+      }
+
+      // echo request object back as json
+      "/jsonecho": {
+        method: ["GET", "POST"]
+        req: body: {}
+        resp: json: req
+      }
+
+      // our gemini call warpped in an API
+      "/chat": {
+        @flow()
+
+        method: "POST"
+
+        // input schema
+        req: {
+          body: {
+            msg: string
+          }
+        }
+
+        // task: api call via reusable task
+        call: _gemini & {
+          apikey: gcp.key
+          msg: req.body.msg
+        }
+
+        // the response to user
+        resp: {
+          status: 200
+          body: call.final.text
+        }
+      }
+
+    }
+  }
+}