@voxgig/sdkgen 1.2.0 → 1.3.1

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)
+	}
+}

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

@@ -0,0 +1,114 @@
+// Generated by sdkgen go-mcp target.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	sdk "GOMODULE"
+)
+
+// Args is the common argument shape for both tools. `entity` selects
+// the SDK entity to operate on; `query` is the optional reqmatch /
+// reqdata map passed through to the SDK. For load, `query` should be
+// `{"id": <value>}`. For list, omit `query` or pass an empty map.
+type Args struct {
+	Entity string         `json:"entity" jsonschema:"// <[SLOT:entityHelp]>"`
+	Query  map[string]any `json:"query,omitempty" jsonschema:"optional match map e.g. {\"id\":1} for load, omit for list"`
+}
+
+func registerTools(server *mcp.Server, client *sdk.ProjectNameSDK) {
+	mcp.AddTool(server, &mcp.Tool{
+		Name: "// <[SLOT:toolPrefixList]>",
+		Description: "List records from ProjectName. " +
+			"Args: entity (one of the supported SDK entities), query (optional filter map). " +
+			"Returns the first page of records as JSON.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args Args) (*mcp.CallToolResult, any, error) {
+		return runOp(client, "list", args)
+	})
+
+	mcp.AddTool(server, &mcp.Tool{
+		Name: "// <[SLOT:toolPrefixLoad]>",
+		Description: "Load a single record from ProjectName. " +
+			"Args: entity, query ({\"id\":N} required). Returns the record as JSON.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args Args) (*mcp.CallToolResult, any, error) {
+		return runOp(client, "load", args)
+	})
+}
+
+func runOp(client *sdk.ProjectNameSDK, op string, args Args) (*mcp.CallToolResult, any, error) {
+	ent, err := entityFor(client, args.Entity)
+	if err != nil {
+		return toolError(err.Error())
+	}
+
+	var result any
+	switch op {
+	case "list":
+		result, err = ent.List(args.Query, nil)
+	case "load":
+		result, err = ent.Load(args.Query, nil)
+	default:
+		return toolError(fmt.Sprintf("unknown op %q", op))
+	}
+	if err != nil {
+		return toolError(err.Error())
+	}
+
+	// SDK returns *Entity wrappers; unwrap each via .Data() to get a
+	// plain map[string]any (or []any of maps for list) suitable for
+	// JSON marshalling.
+	data := extractData(result)
+	body, err := json.MarshalIndent(data, "", "  ")
+	if err != nil {
+		return toolError(fmt.Sprintf("marshal: %v", err))
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: string(body)},
+		},
+	}, data, 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)
+}
+
+// extractData walks an SDK result and replaces any sdk.Entity wrapper
+// with its 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
+}
+
+func toolError(msg string) (*mcp.CallToolResult, any, error) {
+	return &mcp.CallToolResult{
+		IsError: true,
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: msg},
+		},
+	}, nil, nil
+}