@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -0,0 +1,195 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each,
+  File, Content, Fragment, Slot,
+} from '@voxgig/sdkgen'
+
+import type {
+  ModelEntity,
+} from '@voxgig/apidef'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Published aql/eng/go version. Tagged at aql-lang/aql under
+// eng/go/v<X.Y.Z>. Bump here when adopting a newer engine.
+const AQL_ENG_VERSION = 'v0.0.1'
+
+
+const Main = cmp(function Main(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const org = model.origin || 'voxgig-sdk'
+  const sdkModule = `github.com/${org}/${model.name}-sdk/go`
+  const cliModule = `github.com/${org}/${model.name}-sdk/go-cli`
+
+  const entityMap: any = getModelPath(model, `main.${KIT}.entity`)
+  const entityNames = Object.keys(entityMap).map(n => n.toLowerCase())
+
+  const FRAGMENT = Path.normalize(__dirname + '/../../../src/cmp/go-cli/fragment')
+
+  // .gitignore — the compiled binary lands at /<modulename>-cli; ignore it.
+  File({ name: '.gitignore' }, () => Content(`/${model.name}-cli
+`))
+
+  // README.md — usage guide for the AQL-driven CLI.
+  const entityList = entityNames.length > 0 ? entityNames.join(' ') : '(none)'
+
+  // 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            |',
+  }
+  const supportedOps = new Set<string>()
+  each(entityMap, (entity: any) => {
+    if (entity && entity.active === false) return
+    const ops = (entity && entity.op) || {}
+    for (const opname of Object.keys(ops)) {
+      if (ops[opname] && ops[opname].active !== false) supportedOps.add(opname)
+    }
+  })
+  const verbRows = ['list', 'load', 'update']
+    .filter(op => supportedOps.has(op))
+    .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)
+  const firstEntity = firstEntityObj
+    ? String(firstEntityObj.name).toLowerCase()
+    : (entityNames[0] || 'entity')
+  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}`)
+  }
+  if (firstHas('load')) {
+    runLines.push(`./${model.name}-cli load 1 ${firstEntity}`)
+    runLines.push(`./${model.name}-cli load '{id:1}' ${firstEntity}`)
+  }
+  if (firstHas('update')) {
+    runLines.push(`./${model.name}-cli update '{id:1}' ${firstEntity}`)
+  }
+
+  File({ name: 'README.md' }, () => Content(`# ${model.name}-cli
+
+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.
+
+Built on \`github.com/aql-lang/aql/eng/go\` and the sibling Go SDK at \`../go\`.
+
+## Build
+
+\`\`\`sh
+go build -o ${model.name}-cli ./...
+\`\`\`
+
+## Run
+
+\`\`\`sh
+${runLines.join('\n')}
+
+# REPL
+./${model.name}-cli
+\`\`\`
+
+## Words
+
+| Word     | Signatures                                   | Description                |
+|----------|----------------------------------------------|----------------------------|
+${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).
+
+## Entities
+
+${entityList}
+
+## REPL commands
+
+- \`:quit\` / \`:q\` / \`:exit\` — exit the REPL
+- \`:help\` / \`:h\` / \`:?\`     — show help
+
+## Generated by
+
+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/\`.
+`))
+
+  // go.mod — sibling SDK via relative replace; aql/eng/go from the
+  // public Go module proxy.
+  File({ name: 'go.mod' }, () => Content(`module ${cliModule}
+
+go 1.21
+
+require ${sdkModule} v0.0.0
+require github.com/aql-lang/aql/eng/go ${AQL_ENG_VERSION}
+
+replace ${sdkModule} => ../go
+`))
+
+  // main.go — produced from fragment/main.fragment.go with two Slots
+  // for the prompt label and the entity help line.
+  File({ name: 'main.go' }, () => {
+    Fragment(
+      {
+        from: Path.join(FRAGMENT, 'main.fragment.go'),
+        replace: {
+          ...props.ctx$.stdrep,
+          GOMODULE: sdkModule,
+        },
+      },
+      () => {
+        Slot({ name: 'promptName' }, () => Content(model.name))
+        Slot({ name: 'entityNamesSpaced' }, () => Content(entityNames.join(' ')))
+      },
+    )
+  })
+
+  // words.go — produced from fragment/words.fragment.go with a single
+  // Slot that emits one `case "<name>":` per entity.
+  File({ name: 'words.go' }, () => {
+    Fragment(
+      {
+        from: Path.join(FRAGMENT, 'words.fragment.go'),
+        replace: {
+          ...props.ctx$.stdrep,
+          GOMODULE: sdkModule,
+        },
+      },
+      () => {
+        Slot({ name: 'entityCases' }, () => {
+          each(entityMap, (entity: ModelEntity) => {
+            const lower = entity.name.toLowerCase()
+            const pascal = (entity as any).Name
+            Content(`\tcase "${lower}":
+\t\treturn client.${pascal}(nil), nil
+`)
+          })
+        })
+      },
+    )
+  })
+})
+
+
+export {
+  Main
+}

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

@@ -0,0 +1,106 @@
+// Command ProjectName-cli is a CLI + REPL for the ProjectName SDK,
+// built on the AQL engine. Positional arguments are joined into a
+// single AQL expression and evaluated; with no arguments, falls into
+// a REPL. Generated by sdkgen go-cli target.
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	eng "github.com/aql-lang/aql/eng/go"
+	"github.com/aql-lang/aql/eng/go/parser"
+	sdk "GOMODULE"
+)
+
+// prompt is the REPL prompt prefix (matches the SDK slug).
+const prompt = "// <[SLOT:promptName]>"
+
+// 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))
+}
+
+func run(args []string, in io.Reader, out, errOut io.Writer) int {
+	client := sdk.NewProjectNameSDK(nil)
+
+	r, err := eng.NewRegistry()
+	if err != nil {
+		fmt.Fprintf(errOut, "registry: %v\n", err)
+		return 1
+	}
+	registerSDKWords(r, client)
+	if err := r.Err(); err != nil {
+		fmt.Fprintf(errOut, "word registration: %v\n", err)
+		return 1
+	}
+	r.SetParseFunc(parser.Parse)
+	r.InitRootContext()
+	r.MarkReady()
+
+	if len(args) > 0 {
+		return evalOnce(r, strings.Join(args, " "), out, errOut)
+	}
+	repl(r, in, out)
+	return 0
+}
+
+func evalOnce(r *eng.Registry, src string, out, errOut io.Writer) int {
+	values, err := parser.Parse(src)
+	if err != nil {
+		fmt.Fprintf(errOut, "parse: %v\n", err)
+		return 1
+	}
+	result, err := eng.NewTop(r).Run(values)
+	if err != nil {
+		fmt.Fprintf(errOut, "error: %v\n", err)
+		return 1
+	}
+	for _, v := range result {
+		fmt.Fprintln(out, v.String())
+	}
+	return 0
+}
+
+func repl(r *eng.Registry, in io.Reader, out io.Writer) {
+	scanner := bufio.NewScanner(in)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for {
+		fmt.Fprintf(out, "%s> ", prompt)
+		if !scanner.Scan() {
+			fmt.Fprintln(out)
+			return
+		}
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		switch line {
+		case ":quit", ":q", ":exit":
+			return
+		case ":help", ":h", ":?":
+			fmt.Fprintln(out, "commands: list / load / update <query?> <entity>")
+			fmt.Fprintln(out, "entities:", entitiesHelp)
+			fmt.Fprintln(out, "meta:     :quit :help")
+			continue
+		}
+		values, err := parser.Parse(line)
+		if err != nil {
+			fmt.Fprintf(out, "  parse error: %v\n", err)
+			continue
+		}
+		result, err := eng.NewTop(r).Run(values)
+		if err != nil {
+			fmt.Fprintf(out, "  error: %v\n", err)
+			continue
+		}
+		for _, v := range result {
+			fmt.Fprintln(out, v.String())
+		}
+	}
+}

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

@@ -0,0 +1,132 @@
+// Generated by sdkgen go-cli target.
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	eng "github.com/aql-lang/aql/eng/go"
+	sdk "GOMODULE"
+)
+
+// registerSDKWords installs three native AQL words bound to the SDK:
+// list / load / update. Each is declared with two overloads matching
+// the signature  [query?:(Node or Scalar) entity:atom]:
+//
+//   [entity:Atom]            — no query (e.g. `list book`)
+//   [query:Any entity:Atom]  — query is any Node or Scalar (e.g.
+//                              `load {id:1} book`, `load 1 book`)
+//
+// The entity slot is /q-quoted so a bareword `book` parses as the
+// Atom "book" rather than dispatching as an undefined word.
+func registerSDKWords(r *eng.Registry, client *sdk.ProjectNameSDK) {
+	for _, op := range []string{"list", "load", "update"} {
+		op := op
+		single := eng.NativeSig{
+			Args:      []*eng.Type{eng.TAtom},
+			QuoteArgs: map[int]bool{0: true},
+			Handler: func(args []eng.Value, _ map[string]eng.Value, _ []eng.Value, _ *eng.Registry) ([]eng.Value, error) {
+				return runOp(client, op, nil, args[0])
+			},
+			Returns: []*eng.Type{eng.TAny},
+		}
+		dual := eng.NativeSig{
+			Args:      []*eng.Type{eng.TAny, eng.TAtom},
+			QuoteArgs: map[int]bool{1: true},
+			Handler: func(args []eng.Value, _ map[string]eng.Value, _ []eng.Value, _ *eng.Registry) ([]eng.Value, error) {
+				q := args[0]
+				return runOp(client, op, &q, args[1])
+			},
+			Returns: []*eng.Type{eng.TAny},
+		}
+		r.RegisterNativeFunc(eng.NativeFunc{
+			Name:        op,
+			ForwardArgs: true,
+			Signatures:  []eng.NativeSig{single, dual},
+		})
+	}
+}
+
+func runOp(client *sdk.ProjectNameSDK, op string, query *eng.Value, entityAtom eng.Value) ([]eng.Value, error) {
+	entityName, err := eng.AsAtom(entityAtom)
+	if err != nil {
+		return nil, fmt.Errorf("%s: entity argument is not an atom: %w", op, err)
+	}
+	ent, err := entityFor(client, entityName)
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", op, err)
+	}
+
+	var arg map[string]any
+	if query != nil {
+		arg, err = queryToMap(*query)
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", op, err)
+		}
+	}
+
+	var result any
+	switch op {
+	case "list":
+		result, err = ent.List(arg, nil)
+	case "load":
+		result, err = ent.Load(arg, nil)
+	case "update":
+		result, err = ent.Update(arg, nil)
+	default:
+		return nil, fmt.Errorf("unknown op %q", op)
+	}
+	if err != nil {
+		return nil, err
+	}
+	return []eng.Value{eng.FromNative(extractData(result))}, nil
+}
+
+// entityFor dispatches on the lowercase entity name. The generator
+// emits one `case "<name>":` per entity defined in the SDK model.
+func entityFor(client *sdk.ProjectNameSDK, name string) (sdk.ProjectNameEntity, error) {
+	switch strings.ToLower(name) {
+	// <[SLOT:entityCases]>
+	}
+	return nil, fmt.Errorf("unknown entity %q", name)
+}
+
+// queryToMap converts an AQL Value (Map or Scalar) into the
+// `map[string]any` shape the SDK expects. Maps are unwrapped via
+// eng.ToNative. Scalars are wrapped as {"id": <value>} so the
+// shorthand `load 1 book` becomes `load {id:1} book`.
+func queryToMap(v eng.Value) (map[string]any, error) {
+	if v.VType.Matches(eng.TMap) {
+		m, ok := eng.ToNative(v).(map[string]any)
+		if !ok {
+			return nil, fmt.Errorf("query map could not be unwrapped")
+		}
+		return m, nil
+	}
+	if v.VType.Matches(eng.TScalar) {
+		return map[string]any{"id": eng.ToNative(v)}, nil
+	}
+	return nil, fmt.Errorf("query must be a Map or Scalar, got %s", v.VType)
+}
+
+// extractData walks an SDK result and replaces any sdk.Entity wrapper
+// with the underlying record via .Data().
+func extractData(x any) any {
+	switch v := x.(type) {
+	case sdk.Entity:
+		return extractData(v.Data())
+	case []any:
+		out := make([]any, len(v))
+		for i, e := range v {
+			out[i] = extractData(e)
+		}
+		return out
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for k, vv := range v {
+			out[k] = extractData(vv)
+		}
+		return out
+	}
+	return x
+}

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

@@ -0,0 +1,184 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each,
+  File, Content, Fragment, Slot,
+} from '@voxgig/sdkgen'
+
+import type {
+  ModelEntity,
+} from '@voxgig/apidef'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const MCP_GO_SDK_VERSION = 'v1.6.0'
+
+
+const Main = cmp(function Main(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const org = model.origin || 'voxgig-sdk'
+  const sdkModule = `github.com/${org}/${model.name}-sdk/go`
+  const mcpModule = `github.com/${org}/${model.name}-sdk/go-mcp`
+
+  const entityMap: any = getModelPath(model, `main.${KIT}.entity`)
+  const entityNames = Object.keys(entityMap).map(n => n.toLowerCase())
+  const entityHelp = entityNames.length > 0 ? entityNames.join(' | ') : '(none)'
+
+  // Slug-based tool name prefix. Goes into `<slug>_list` / `<slug>_load`
+  // tool names so an MCP host with multiple installed SDK servers
+  // sees unambiguous tool ids.
+  const slugLower = model.name.toLowerCase()
+
+  const FRAGMENT = Path.normalize(__dirname + '/../../../src/cmp/go-mcp/fragment')
+
+  // .gitignore — the compiled binary lands at /<modulename>-mcp; ignore it.
+  File({ name: '.gitignore' }, () => Content(`/${model.name}-mcp
+`))
+
+  // README.md — usage guide for the MCP server.
+  const firstEntity = entityNames[0] || 'entity'
+  File({ name: 'README.md' }, () => Content(`# ${model.name}-mcp
+
+MCP server exposing the ${model.Name} SDK as tools, built on the
+[official Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk)
+and the sibling Go SDK at \`../go\`.
+
+## Tools
+
+| Tool | Args | Returns |
+|------|------|---------|
+| \`${slugLower}_list\` | \`entity\`, optional \`query\` map | First page of records as JSON |
+| \`${slugLower}_load\` | \`entity\`, \`query\` (e.g. \`{id:N}\`) | Single record as JSON |
+
+JSON schemas for both tools are emitted by the SDK from the \`Args\`
+struct's \`json\` / \`jsonschema\` tags — no schema is hand-written.
+
+## Entities
+
+${entityHelp}
+
+## Build
+
+\`\`\`sh
+go build -o ${model.name}-mcp ./...
+\`\`\`
+
+## Run
+
+\`\`\`sh
+# stdio transport — for spawnable agent installs (default).
+./${model.name}-mcp
+
+# streamable HTTP transport — share one running server between agents.
+./${model.name}-mcp -transport http -addr :8080
+\`\`\`
+
+## Install for Claude Code
+
+\`\`\`sh
+claude mcp add --scope user ${slugLower} \\
+  -- /absolute/path/to/${model.name}-mcp -transport stdio
+\`\`\`
+
+After install, restart Claude Code; the \`${slugLower}_list\` and
+\`${slugLower}_load\` tools become available in new sessions.
+
+## Smoke test via HTTP
+
+\`\`\`sh
+./${model.name}-mcp -transport http -addr :18080 &
+
+# initialize, grab the session id
+curl -sN -X POST http://localhost:18080 \\
+  -H 'Content-Type: application/json' \\
+  -H 'Accept: application/json, text/event-stream' \\
+  -D headers \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
+
+SESSION=$(awk '/Mcp-Session-Id/ {print $2}' headers | tr -d '\\r')
+
+curl -sN -X POST http://localhost:18080 \\
+  -H 'Content-Type: application/json' \\
+  -H 'Accept: application/json, text/event-stream' \\
+  -H "Mcp-Session-Id: $SESSION" \\
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"${slugLower}_load","arguments":{"entity":"${firstEntity}","query":{"id":1}}}}'
+\`\`\`
+
+## Generated by
+
+sdkgen \`go-mcp\` target. See the target source under
+\`.sdk/src/cmp/go-mcp/\` in this repo, or upstream at
+\`github.com/voxgig/sdkgen/project/.sdk/src/cmp/go-mcp/\`.
+`))
+
+  // go.mod — sibling SDK via relative replace; MCP Go SDK pulled from
+  // the public proxy.
+  File({ name: 'go.mod' }, () => Content(`module ${mcpModule}
+
+go 1.21
+
+require ${sdkModule} v0.0.0
+require github.com/modelcontextprotocol/go-sdk ${MCP_GO_SDK_VERSION}
+
+replace ${sdkModule} => ../go
+`))
+
+  // main.go — produced from fragment/main.fragment.go with one Slot
+  // for the MCP server's announced name.
+  File({ name: 'main.go' }, () => {
+    Fragment(
+      {
+        from: Path.join(FRAGMENT, 'main.fragment.go'),
+        replace: {
+          ...props.ctx$.stdrep,
+          GOMODULE: sdkModule,
+        },
+      },
+      () => {
+        Slot({ name: 'serverName' }, () => Content(slugLower))
+      },
+    )
+  })
+
+  // tools.go — produced from fragment/tools.fragment.go with Slots
+  // for: the entity help string in the input-schema description,
+  // the two tool name prefixes (`<slug>_list` / `<slug>_load`), and
+  // a per-entity `case` block in the entity dispatch switch.
+  File({ name: 'tools.go' }, () => {
+    Fragment(
+      {
+        from: Path.join(FRAGMENT, 'tools.fragment.go'),
+        replace: {
+          ...props.ctx$.stdrep,
+          GOMODULE: sdkModule,
+        },
+      },
+      () => {
+        Slot({ name: 'entityHelp' }, () => Content(entityHelp))
+        Slot({ name: 'toolPrefixList' }, () => Content(`${slugLower}_list`))
+        Slot({ name: 'toolPrefixLoad' }, () => Content(`${slugLower}_load`))
+        Slot({ name: 'entityCases' }, () => {
+          each(entityMap, (entity: ModelEntity) => {
+            const lower = entity.name.toLowerCase()
+            const pascal = (entity as any).Name
+            Content(`\tcase "${lower}":
+\t\treturn client.${pascal}(nil), nil
+`)
+          })
+        })
+      },
+    )
+  })
+})
+
+
+export {
+  Main
+}

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

@@ -0,0 +1,68 @@
+// Command ProjectName-mcp is an MCP server exposing the ProjectName
+// SDK as MCP tools.
+//
+// Two tools are registered:
+//
+//	ProjectName_list  — list records of an entity
+//	ProjectName_load  — load a single record of an entity
+//
+// Each accepts an `entity` argument and an optional `query` object
+// (mapped 1:1 onto the SDK's reqmatch parameter).
+//
+// Transports:
+//
+//	-transport stdio   (default) — JSON-RPC over stdin/stdout, the
+//	                   standard for spawnable agent-installed servers.
+//	-transport http    — streamable HTTP on -addr (default :8080),
+//	                   useful when sharing one running server between
+//	                   multiple agents.
+//
+// Generated by sdkgen go-mcp target.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	sdk "GOMODULE"
+)
+
+func main() {
+	transport := flag.String("transport", "stdio", "transport: stdio | http")
+	addr := flag.String("addr", ":8080", "listen address for http transport")
+	flag.Parse()
+
+	client := sdk.NewProjectNameSDK(nil)
+	server := mcp.NewServer(
+		&mcp.Implementation{
+			Name:    "// <[SLOT:serverName]>",
+			Version: "0.0.0",
+		},
+		nil,
+	)
+	registerTools(server, client)
+
+	switch *transport {
+	case "stdio":
+		if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
+			log.Fatalf("stdio server: %v", err)
+		}
+	case "http":
+		handler := mcp.NewStreamableHTTPHandler(
+			func(r *http.Request) *mcp.Server { return server },
+			nil,
+		)
+		log.Printf("MCP streamable HTTP server listening on %s", *addr)
+		if err := http.ListenAndServe(*addr, handler); err != nil {
+			log.Fatalf("http server: %v", err)
+		}
+	default:
+		fmt.Fprintf(os.Stderr, "unknown transport %q (want stdio | http)\n", *transport)
+		os.Exit(2)
+	}
+}