@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/go-cli/Main_go-cli.ts

@@ -2,7 +2,7 @@
 import * as Path from 'node:path'
 
 import {
-  cmp, each,
+  cmp, each, deriveEntityNames,
   File, Content, Fragment, Slot,
 } from '@voxgig/sdkgen'
 
@@ -40,6 +40,14 @@ const Main = cmp(function Main(props: any) {
   const cliModule = `github.com/${org}/${model.name}-sdk/go-cli`
 
   const entityMap: any = getModelPath(model, `main.${KIT}.entity`)
+  // Derive each entity's PascalCase `Name` here rather than relying on another
+  // TARGET having run first. This target sets `phase.entity: { active: false }`
+  // (see model/target/go-{cli,mcp}.aontu), so create-sdkgen's Root.ts never
+  // calls names() for it — the accessor emitted below used to read `Name` off
+  // objects the `go` target happened to have named as a side effect, which
+  // yields `client.undefined(nil)` whenever this target is generated without
+  // `go`, or before it in target order.
+  deriveEntityNames(entityMap)
   const entityNames = Object.keys(entityMap).map(n => n.toLowerCase())
 
   const FRAGMENT = Path.normalize(__dirname + '/../../../src/cmp/go-cli/fragment')
@@ -50,18 +58,27 @@ const Main = cmp(function Main(props: any) {
 /go-cli
 `))
 
-  // README.md — usage guide for the AQL-driven CLI.
+  // ==========================================================================
+  // README.md — Diátaxis-structured, examples-first usage guide.
+  //
+  // EVERYTHING here is MODEL-DRIVEN: verbs, examples and how-to sections are
+  // gated on whether an active entity actually exposes that op
+  // (op.<name>.active !== false) — never document an operation no entity
+  // supports. The CLI implements three AQL words (list / load / update; see
+  // words.fragment.go + runOp).
+  // ==========================================================================
+  const bin = `${model.name}-cli`
   const entityList = entityNames.length > 0 ? entityNames.join(' ') : '(none)'
+  const entityCount = entityNames.length
+
+  const projUpper = String(model.name).toUpperCase().replace(/[^A-Z0-9]/g, '_')
+  const apiKeyEnv = projUpper + '_APIKEY'
+  const baseEnv = projUpper + '_BASE'
 
-  // MODEL-DRIVEN verbs. The CLI implements three AQL words (list / load /
-  // update; see words.fragment.go + runOp). Each README verb row is
-  // advertised ONLY when at least one active entity actually exposes that
-  // op (op.<name>.active !== false) — never document an operation no entity
-  // supports.
   const CLI_VERB_ROWS: Record<string, string> = {
-    list:   '| `list`   | `[entity]` · `[query entity]`                | List records               |',
-    load:   '| `load`   | `[entity]` · `[query entity]`                | Load a single record       |',
-    update: '| `update` | `[entity]` · `[query entity]`                | Update a record            |',
+    list:   '| `list`   | `list <entity>` · `list <query> <entity>`     | First page of records          |',
+    load:   '| `load`   | `load <entity>` · `load <query> <entity>`     | A single record                |',
+    update: '| `update` | `update <query> <entity>`                     | Update a record, return it     |',
   }
   const supportedOps = new Set<string>()
   each(entityMap, (entity: any) => {
@@ -76,72 +93,260 @@ const Main = cmp(function Main(props: any) {
     .map(op => CLI_VERB_ROWS[op])
     .join('\n')
 
-  // MODEL-DRIVEN run examples, gated on the first entity's own ops so the
-  // Run section never demonstrates a verb the example entity lacks.
-  const firstEntityObj: any =
-    Object.values(entityMap).find((e: any) => e && e.active !== false)
+  // First / second active entity for concrete, truthful examples, gated on
+  // the FIRST entity's own ops so an example never shows a verb it lacks.
+  const activeEntityObjs: any[] =
+    Object.values(entityMap).filter((e: any) => e && e.active !== false)
+  const firstEntityObj: any = activeEntityObjs[0]
   const firstEntity = firstEntityObj
     ? String(firstEntityObj.name).toLowerCase()
     : (entityNames[0] || 'entity')
+  const secondEntity = activeEntityObjs.length > 1
+    ? String(activeEntityObjs[1].name).toLowerCase()
+    : firstEntity
   const firstOps: any = (firstEntityObj && firstEntityObj.op) || {}
   const firstHas = (op: string) => !!(firstOps[op] && firstOps[op].active !== false)
-  const runLines: string[] = ['# One-shot: arguments form a single AQL expression']
-  if (firstHas('list')) {
-    runLines.push(`./${model.name}-cli list ${firstEntity}`)
-  }
+  const entityNoun = entityCount === 1 ? 'entity' : 'entities'
+  // The best single example expression this SDK can actually run, for the
+  // tutorial/REPL walkthroughs (never demonstrates an unsupported op).
+  const exampleOp =
+    firstHas('list') ? `list ${firstEntity}` :
+    firstHas('load') ? `load 1 ${firstEntity}` :
+    firstHas('update') ? `update '{id:1}' ${firstEntity}` : ''
+  // Fallback differs by context: a COMMAND-LINE arg uses the `--help` flag;
+  // the `/`-prefixed meta-command is only valid INSIDE the REPL.
+  const cliExampleExpr = exampleOp || '--help'
+  const replExampleExpr = exampleOp || '/help'
+
+  // ---- Examples block (up front) -------------------------------------------
+  const ex: string[] = []
+  ex.push(`# 1. Build a native binary (-> dist/<os>-<arch>/${bin})`)
+  ex.push('make build')
+  ex.push('')
+  ex.push('# 2. See usage (words, entities, env vars)')
+  ex.push(`./${bin} --help`)
+  ex.push('')
+  ex.push('# 3. Provide credentials once, via the environment')
+  ex.push(`export ${apiKeyEnv}=sk_live_xxx`)
+  ex.push('')
+  ex.push('# 4. Each command line is ONE AQL expression, run against the API:')
+  if (firstHas('list')) ex.push(`./${bin} list ${firstEntity}`)
   if (firstHas('load')) {
-    runLines.push(`./${model.name}-cli load 1 ${firstEntity}`)
-    runLines.push(`./${model.name}-cli load '{id:1}' ${firstEntity}`)
+    ex.push(`./${bin} load 1 ${firstEntity}            # {id:1} shorthand`)
+    ex.push(`./${bin} load '{id:1}' ${firstEntity}       # explicit match map`)
   }
-  if (firstHas('update')) {
-    runLines.push(`./${model.name}-cli update '{id:1}' ${firstEntity}`)
+  if (firstHas('update')) ex.push(`./${bin} update '{name:"x"}' ${firstEntity}`)
+  if (firstHas('list') && secondEntity !== firstEntity) {
+    ex.push(`./${bin} list ${secondEntity}`)
   }
+  ex.push('')
+  ex.push('# 5. Override the API base URL for a single call')
+  ex.push(`${baseEnv}=https://api.example.com ./${bin} ${cliExampleExpr}`)
+  ex.push('')
+  ex.push('# 6. No arguments -> interactive REPL')
+  ex.push(`./${bin}`)
+  ex.push(`${model.name}> ${replExampleExpr}`)
+  ex.push(`${model.name}> /quit`)
+  const exampleBlock = ex.join('\n')
+
+  // ---- How-to guides (gated) -----------------------------------------------
+  const howtos: string[] = []
+  if (firstHas('list')) howtos.push(`### List the records of an entity
 
-  File({ name: 'README.md' }, () => Content(`# ${model.name}-cli
+\`\`\`sh
+./${bin} list ${firstEntity}
+\`\`\`
+
+\`list <entity>\` returns the first page of records. \`<entity>\` is a bareword —
+it is auto-quoted as an AQL atom, so no quotes are needed.`)
+
+  if (firstHas('load')) howtos.push(`### Load a single record
+
+\`\`\`sh
+./${bin} load 1 ${firstEntity}          # scalar shorthand for {id:1}
+./${bin} load '{id:1}' ${firstEntity}     # explicit match map
+\`\`\`
+
+The query is either a **scalar** (\`1\`, treated as \`{id:1}\`) or a **match map**
+(\`{id:1}\`, \`{slug:"acme"}\`). Quote the map so your shell passes it through intact.`)
+
+  if (firstHas('update')) howtos.push(`### Update a record
+
+\`\`\`sh
+./${bin} update '{id:1,name:"new"}' ${firstEntity}
+\`\`\`
 
-AQL-driven CLI and REPL for the ${model.Name} SDK. Positional arguments are
-joined into a single AQL expression and evaluated; with no arguments,
-falls into an interactive REPL.
+The match map carries both the selector and the new field values; the updated
+record is printed back.`)
 
-Built on \`github.com/aql-lang/aql/eng/go\` and the sibling Go SDK at \`../go\`.
+  howtos.push(`### Authenticate and choose an environment
 
-## Build
+Configuration is read from the environment — nothing is written to disk:
 
 \`\`\`sh
-go build -o ${model.name}-cli ./...
+export ${apiKeyEnv}=sk_live_xxx            # API key
+export ${baseEnv}=https://api.example.com  # optional: override the API base URL
+./${bin} ${cliExampleExpr}
 \`\`\`
 
-## Run
+Both are injectable by a secrets vault, so the key never has to be typed inline.`)
+
+  howtos.push(`### Explore interactively with the REPL
+
+Run with no arguments to open a REPL (prompt \`${model.name}>\`). Each line is
+evaluated as its own AQL expression:
+
+\`\`\`text
+$ ./${bin}
+${exampleOp ? `${model.name}> ${exampleOp}\n` : ''}${model.name}> /help
+${model.name}> /quit
+\`\`\``)
+
+  howtos.push(`### Cross-compile release binaries
 
 \`\`\`sh
-${runLines.join('\n')}
+make build       # native binary for this machine
+make build-all   # linux/darwin/windows x amd64/arm64, under dist/<os>-<arch>/
+\`\`\``)
 
-# REPL
-./${model.name}-cli
+  howtos.push(`### Discover the available entities
+
+\`/help\` in the REPL prints the full entity list, or see [Entities](#entities)
+below — this SDK exposes ${entityCount} ${entityNoun}.`)
+
+  const howtoBlock = howtos.join('\n\n')
+
+  File({ name: 'README.md' }, () => Content(`# ${model.name}-cli
+
+AQL-driven command-line client **and** interactive REPL for the ${model.Name}
+SDK. Each command line is parsed as a single [AQL](https://github.com/aql-lang/aql)
+expression and evaluated against the live API; run it with no arguments to drop
+into a REPL. Built on \`github.com/aql-lang/aql/eng/go\` and the sibling Go SDK
+at \`../go\`.
+
+## Examples
+
+\`\`\`sh
+${exampleBlock}
 \`\`\`
 
-## Words
+> The rest of this guide follows the [Diátaxis](https://diataxis.fr) framework:
+> a hands-on **Tutorial**, task-focused **How-to guides**, a factual
+> **Reference**, and background **Explanation**.
+
+## Tutorial: your first query in under a minute
+
+1. **Build the binary.** From this \`go-cli/\` directory:
+
+   \`\`\`sh
+   make build          # -> dist/<os>-<arch>/${bin}
+   \`\`\`
 
-| Word     | Signatures                                   | Description                |
-|----------|----------------------------------------------|----------------------------|
+2. **Set your API key** (read from the environment):
+
+   \`\`\`sh
+   export ${apiKeyEnv}=sk_live_xxx
+   \`\`\`
+
+3. **Run a query.** Evaluate an AQL expression against the API (or run with no
+   arguments to open the REPL):
+
+   \`\`\`sh
+   ./dist/*/${bin} ${cliExampleExpr}
+   \`\`\`
+
+4. **Go interactive.** Run the binary with no arguments to open the REPL, then
+   type \`/help\` for the word and entity lists and \`/quit\` to leave.
+
+That is the whole loop: *build → set key → evaluate AQL expressions*.
+
+## How-to guides
+
+${howtoBlock}
+
+## Reference
+
+### Words
+
+The CLI registers these AQL words, each bound to the SDK:
+
+| Word     | Signatures                                    | Returns                        |
+|----------|-----------------------------------------------|--------------------------------|
 ${verbRows}
 
-\`query\` is either a Map (\`{id:1}\`) or a Scalar (\`1\`, treated as \`{id:1}\`).
-\`entity\` is one of the SDK's entity names (auto-quoted as an atom).
+- \`<entity>\` is a bareword, auto-quoted as an AQL atom (e.g. \`${firstEntity}\`).
+- \`<query>\` is either a **Map** (\`{id:1}\`) or a **Scalar** (\`1\`, treated as
+  \`{id:1}\`). A scalar is always wrapped as \`{id:<value>}\`.
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| \`${apiKeyEnv}\` | API key sent with every request. |
+| \`${baseEnv}\` | Optional override of the API base URL. |
+
+Unset variables fall back to the SDK's built-in defaults.
+
+### CLI flags
 
-## Entities
+- \`--help\` / \`-h\` — print usage (words, entities, env vars) and exit.
+
+### REPL commands
+
+Meta-commands use the \`/\` prefix (everything else on a line is evaluated as AQL):
+
+- \`/quit\` / \`/q\` / \`/exit\` — exit the REPL
+- \`/help\` / \`/h\` / \`/?\`     — show the word list, entity list and meta commands
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| \`0\` | Success (also the normal REPL exit). |
+| \`1\` | Parse error, word-registration error, or an API/evaluation error. |
+
+### Build targets
+
+| Target | Result |
+|--------|--------|
+| \`make build\` | Native binary at \`dist/<os>-<arch>/${bin}\`. |
+| \`make build-all\` | linux/darwin/windows x amd64/arm64, each under its own \`dist/<os>-<arch>/\`. |
+| \`make clean\` | Remove \`dist/\` and any stray binaries. |
+
+### Entities
+
+The ${entityCount} ${entityNoun} this SDK exposes (any is valid as \`<entity>\`):
 
 ${entityList}
 
-## REPL commands
+## Explanation
+
+### Why AQL?
+
+The whole command line is one [AQL](https://github.com/aql-lang/aql) expression,
+not a fixed \`verb --flag\` grammar. That means the same binary works one-shot
+(\`./${bin} <expr>\`) and interactively (the REPL), and expressions compose the
+same way in both. \`list\` / \`load\` / \`update\` are ordinary AQL *words* bound to
+the SDK — adding SDK operations is adding words, not re-parsing flags.
+
+### How it is wired
+
+\`main.go\` builds the SDK client (configured from the environment), creates an
+AQL registry, and \`words.go\` registers \`list\` / \`load\` / \`update\` as native
+words that dispatch on the entity atom and call the sibling Go SDK at \`../go\`.
+Results are unwrapped from their \`Entity\` wrappers to plain data before being
+printed.
+
+### Output format
 
-- \`:quit\` / \`:q\` / \`:exit\` — exit the REPL
-- \`:help\` / \`:h\` / \`:?\`     — show help
+Each result value is printed as its AQL string form (a JSON-like rendering of
+the record or list of records). One-shot mode prints to stdout; errors go to
+stderr with a non-zero exit code.
 
 ## Generated by
 
-sdkgen \`go-cli\` target. See the target source under
-\`.sdk/src/cmp/go-cli/\` in this repo, or upstream at
+sdkgen \`go-cli\` target. See the target source under \`.sdk/src/cmp/go-cli/\` in
+this repo, or upstream at
 \`github.com/voxgig/sdkgen/project/.sdk/src/cmp/go-cli/\`.
 `))
 

package/project/.sdk/src/cmp/go-cli/fragment/main.fragment.go

@@ -19,14 +19,36 @@ import (
 // prompt is the REPL prompt prefix (matches the SDK slug).
 const prompt = "// <[SLOT:promptName]>"
 
-// entitiesHelp is the space-separated entity list shown by :help.
+// entitiesHelp is the space-separated entity list shown by /help.
 const entitiesHelp = "// <[SLOT:entityNamesSpaced]>"
 
 func main() {
 	os.Exit(run(os.Args[1:], os.Stdin, os.Stdout, os.Stderr))
 }
 
+// usage prints the CLI help (for --help / -h). No client or network setup.
+func usage(out io.Writer) {
+	fmt.Fprintf(out, "%s-cli — AQL-driven CLI + REPL for the %s SDK\n\n", prompt, prompt)
+	fmt.Fprintln(out, "Usage:")
+	fmt.Fprintf(out, "  %s-cli [--help] [<AQL expression>]\n\n", prompt)
+	fmt.Fprintln(out, "With arguments, they are joined into a single AQL expression and")
+	fmt.Fprintln(out, "evaluated against the API. With no arguments, starts an interactive REPL.")
+	fmt.Fprintln(out)
+	fmt.Fprintln(out, "Words:    list / load / update <query?> <entity>")
+	fmt.Fprintln(out, "Entities:", entitiesHelp)
+	fmt.Fprintln(out, "Env:      APIKEYENVVAR (api key), BASEENVVAR (base url override)")
+	fmt.Fprintln(out, "REPL:     /help  /quit")
+}
+
 func run(args []string, in io.Reader, out, errOut io.Writer) int {
+	// --help / -h: print usage and exit before any config or network setup.
+	for _, a := range args {
+		if a == "--help" || a == "-h" {
+			usage(out)
+			return 0
+		}
+	}
+
 	// Configure from the environment: APIKEYENVVAR carries the API key and
 	// BASEENVVAR optionally overrides the API base URL (e.g. production).
 	// Both injectable by a secrets vault. Unset -> nil config defaults.
@@ -94,12 +116,12 @@ func repl(r *eng.Registry, in io.Reader, out io.Writer) {
 			continue
 		}
 		switch line {
-		case ":quit", ":q", ":exit":
+		case "/quit", "/q", "/exit":
 			return
-		case ":help", ":h", ":?":
-			fmt.Fprintln(out, "commands: list / load / update <query?> <entity>")
+		case "/help", "/h", "/?":
+			fmt.Fprintln(out, "words:    list / load / update <query?> <entity>")
 			fmt.Fprintln(out, "entities:", entitiesHelp)
-			fmt.Fprintln(out, "meta:     :quit :help")
+			fmt.Fprintln(out, "meta:     /help  /quit")
 			continue
 		}
 		values, err := parser.Parse(line)