@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/go/EntityTypes_go.ts

@@ -0,0 +1,197 @@
+
+
+// Typed-model generator (Go target).
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, entity/types.go, in
+// the `entity` package, with a Go `type <Name> struct { ... }` per entity plus
+// a request/match struct per active op. Field/param sentinels ($STRING,
+// $INTEGER, ...) are turned into real Go types by the shared sdkgen helper
+// `canonToType` (source of truth: @voxgig/apidef VALID_CANON).
+//
+// PORT NOTES (Go specifics vs the TS reference):
+//   * Types live in the SAME package as the entity methods (`entity`), so the
+//     generated typed accessors reference them without an import (task step B).
+//   * Go has no method overloading and go-cli / go-mcp dispatch entities
+//     dynamically through the untyped `core.ProjectNameEntity` interface
+//     (Load/List/... (map[string]any) (any, error)). That interface — and the
+//     untyped concrete methods that satisfy it — are therefore KEPT unchanged.
+//     Typed access is delivered ADDITIVELY: the op fragments emit `LoadTyped`
+//     / `ListTyped` / ... alongside the untyped methods, and Entity.fragment.go
+//     emits `DataTyped` / `MatchTyped`. All are thin typed wrappers over the
+//     untyped runtime (identical behaviour), converting at the typed boundary
+//     via the JSON-round-trip helpers emitted at the bottom of this file.
+//   * `list` typed op returns []<Name>; other typed ops return <Name>.
+//   * op WITH params -> a struct of those params (reqd:false -> pointer +
+//     ,omitempty). op WITHOUT params -> a struct mirroring the entity fields
+//     with every field optional (Go's analog of TS `Partial<Name>`).
+
+import {
+  cmp, each,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'go'
+
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+
+// A model field/param name -> an exported Go field identifier:
+//   advice -> Advice, some_field -> SomeField, id -> Id.
+function goField(name: string): string {
+  const out = String(name)
+    .replace(/[^A-Za-z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('')
+  // Go identifiers can't start with a digit.
+  return /^[A-Za-z_]/.test(out) ? out : 'F' + out
+}
+
+
+// One Go struct field line. `optional` -> pointer + ,omitempty (Go's closest
+// analog to an optional/absent field).
+function fieldLine(name: string, sentinel: any, optional: boolean): string {
+  const gt = canonToType(sentinel, LANG)
+  const typ = optional ? ('*' + gt) : gt
+  const tag = optional ? `\`json:"${name},omitempty"\`` : `\`json:"${name}"\``
+  return `\t${goField(name)} ${typ} ${tag}\n`
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Emit for every entity that gets an entity file. Main_go.ts iterates
+  // entities WITHOUT an `active` filter, so a struct is required for each so
+  // the typed accessors in every *_entity.go resolve at compile time.
+  const entityList = each(entity).filter((e: any) => e && null != e.Name)
+
+  Folder({ name: 'entity' }, () => {
+
+    File({ name: 'types.' + target.ext }, () => {
+
+      Content(`// Typed models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+// @voxgig/apidef VALID_CANON). Do not edit by hand.
+package entity
+
+import "encoding/json"
+
+`)
+
+      entityList.forEach((ent: any) => {
+        const Name = ent.Name
+        const fields = (ent.fields ? each(ent.fields) : [])
+          .filter((f: any) => f.active !== false)
+
+        // Entity data model: one field per model field. req:false -> pointer.
+        Content(`// ${Name} is the typed data model for the ${ent.name} entity.
+type ${Name} struct {
+`)
+        fields.forEach((f: any) => {
+          Content(fieldLine(f.name, f.type, false === f.req))
+        })
+        Content(`}
+
+`)
+
+        // Per active op: a request/match struct (same package as the entity
+        // methods, so no import is needed there). Members and their optionality
+        // come from the shared partiality policy (opRequestShape); this file
+        // only renders them as a Go struct (optional -> pointer + ,omitempty).
+        const ops = ent.op || {}
+        ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+          if (null == ops[opname]) {
+            return
+          }
+
+          const typeName = opTypeName(Name, opname)
+          const { items } = opRequestShape(ent, opname)
+
+          Content(`// ${typeName} is the typed request payload for ${Name}.${cap(opname)}Typed.
+type ${typeName} struct {
+`)
+          items.forEach((it: any) => {
+            Content(fieldLine(it.name, it.type, it.optional))
+          })
+          Content(`}
+
+`)
+        })
+      })
+
+      // Conversion helpers shared by the generated typed accessors/methods.
+      // Kept unexported and package-local so the typed boundary stays a pure
+      // wrapper over the untyped runtime.
+      Content(`// asMap turns a typed request/data struct into the map[string]any the
+// runtime op pipeline consumes, honouring the json tags above.
+func asMap(v any) map[string]any {
+	out := map[string]any{}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return out
+	}
+	_ = json.Unmarshal(b, &out)
+	return out
+}
+
+// typedFrom decodes a runtime value (a map[string]any produced by the op
+// pipeline) into a typed model T via a JSON round-trip. On any error it
+// returns the zero value of T; the op's own (value, error) tuple carries the
+// real error.
+func typedFrom[T any](v any) T {
+	var out T
+	if v == nil {
+		return out
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return out
+	}
+	_ = json.Unmarshal(b, &out)
+	return out
+}
+
+// typedSliceFrom decodes a runtime list value ([]any of maps) into a typed
+// slice []T via a JSON round-trip, for list ops.
+func typedSliceFrom[T any](v any) []T {
+	var out []T
+	if v == nil {
+		return out
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return out
+	}
+	_ = json.Unmarshal(b, &out)
+	return out
+}
+`)
+
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/go/Entity_go.ts

@@ -15,7 +15,7 @@ const Entity = cmp(function Entity(props: any) {
 
   // Module name: concatenated lowercase
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   const entrep = {
     ...stdrep,
@@ -57,6 +57,7 @@ const Entity = cmp(function Entity(props: any) {
         replace: {
           ...entrep,
           'GOMODULE': gomodule,
+          '"github.com/voxgig/struct"': `"${gomodule}/utility/struct"`,
           ProjectName: model.const.Name,
           EntityName: entity.Name,
           entityname: entity.name,

package/project/.sdk/src/cmp/go/MainEntity_go.ts

@@ -7,7 +7,13 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity, gomodule } = props
   const { model } = props.ctx$
 
+  // Go keeps the PascalCase accessor: exported identifiers must be PascalCase,
+  // so a lowercase facade is not idiomatic (nor exportable) in Go.
+  // Idiomatic usage: client.${entity.Name}(nil).List(nil, nil) / .Load(...).
   Content(`
+// ${entity.Name} returns a ${entity.Name} entity bound to this client.
+// Idiomatic usage: client.${entity.Name}(nil).List(nil, nil) or
+// client.${entity.Name}(nil).Load(map[string]any{"id": ...}, nil).
 func (sdk *${model.const.Name}SDK) ${entity.Name}(data map[string]any) ${model.const.Name}Entity {
 	return New${entity.Name}EntityFunc(sdk, data)
 }

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

@@ -22,6 +22,7 @@ import { Package } from './Package_go'
 import { Config } from './Config_go'
 import { Gitignore } from './Gitignore_go'
 import { MainEntity } from './MainEntity_go'
+import { EntityTypes } from './EntityTypes_go'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -34,7 +35,7 @@ const Main = cmp(async function Main(props: any) {
 
   // Go module path == the repo path on GitHub (org from model.origin),
   // e.g. github.com/voxgig-sdk/<slug>-sdk. Used in go.mod and every import.
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
   // The root package name must be a plain Go identifier (can't be a path),
   // so it stays as the concatenated-lowercase form (e.g. voxgigdogsdk).
   const gopackage = (model.origin || 'voxgig-sdk').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '') +
@@ -44,16 +45,27 @@ const Main = cmp(async function Main(props: any) {
 
   Gitignore({})
 
-  // Copy tm/go files with replacements
+  // Copy tm/go files with replacements.
+  //
+  // Rewrite the placeholder `github.com/voxgig/struct` import (used in the
+  // template since it's a self-contained module there) to its in-SDK path.
+  // The struct package is inlined under `<gomodule>/utility/struct` so the
+  // module is fully self-contained — no external go.mod required by
+  // downstream consumers.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, /utility\/struct\/go\.mod$/],
     replace: {
       ...props.ctx$.stdrep,
       GOMODULE: gomodule,
+      '"github.com/voxgig/struct"': `"${gomodule}/utility/struct"`,
     }
   })
 
+  // Typed models: entity/types.go (package entity), emitted alongside the
+  // generated *_entity.go files so the typed accessors resolve without imports.
+  EntityTypes({ target })
+
   // Generate main SDK file in core/ folder
   Folder({ name: 'core' }, () => {
 
@@ -65,6 +77,7 @@ const Main = cmp(async function Main(props: any) {
           replace: {
             ...props.ctx$.stdrep,
             'ProjectNameModule': gomodule,
+            '"github.com/voxgig/struct"': `"${gomodule}/utility/struct"`,
 
             '#BuildFeatures': ({ indent }: any) => {
               each(feature, (feat: any) => {
@@ -190,6 +203,13 @@ var NewResult = core.NewResult
 var NewResponse = core.NewResponse
 var NewOperation = core.NewOperation
 var MakeConfig = core.MakeConfig
+
+// No-arg convenience constructors. Go has no default-argument syntax,
+// so these aliases let callers write \`sdk.New()\` / \`sdk.Test()\`
+// instead of \`sdk.New${model.const.Name}SDK(nil)\` / \`sdk.TestSDK(nil, nil)\`
+// for the common no-options case.
+func New() *${model.const.Name}SDK  { return New${model.const.Name}SDK(nil) }
+func Test() *${model.const.Name}SDK { return TestSDK(nil, nil) }
 `)
 
     // Feature constructor re-exports - base is always present

package/project/.sdk/src/cmp/go/Package_go.ts

@@ -20,7 +20,7 @@ const Package = cmp(async function Package(props: any) {
 
   // Module name: concatenated lowercase (e.g., voxgigsolardemosdk)
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   File({ name: 'go.mod' }, () => {
     Content(`module ${gomodule}

package/project/.sdk/src/cmp/go/ReadmeEntity_go.ts

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
@@ -39,8 +41,15 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
   publishedEntities.map((entity: any) => {
-    const opnames = Object.keys(entity.op || {})
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would not compile.
+    const opnames = entityOps(entity)
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // camelCase Go identifier (a `status_embed_config` entity must not bind a
+    // snake_case Go variable, and a `type`/`range` entity not a Go keyword).
+    const eVar = goVarName(entity.name)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +62,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`${entity.name} := client.${entity.Name}(nil)\`
+    Content(`Create an instance: \`${eVar} := client.${entity.Name}(nil)\`
 
 `)
 
@@ -84,7 +93,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +102,26 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape that generates the op's request match, so
+      // the example always carries the keys the route needs.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `map[string]any{${loadItems.map((it: any) =>
+          `"${it.name}": ${exampleValue(entity, entity.op && entity.op.load, it.name,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}}`
+        : 'nil'
       Content(`#### Example: Load
 
 \`\`\`go
-result, err := client.${entity.Name}(nil).Load(map[string]any{"id": "${entity.name}_id"}, nil)
+${eVar}, err := client.${entity.Name}(nil).Load(${loadArg}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eVar}) // the loaded record
 \`\`\`
 
 `)
@@ -106,25 +131,38 @@ result, err := client.${entity.Name}(nil).Load(map[string]any{"id": "${entity.na
       Content(`#### Example: List
 
 \`\`\`go
-results, err := client.${entity.Name}(nil).List(nil, nil)
+${eVar}s, err := client.${entity.Name}(nil).List(nil, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eVar}s) // the array of records
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape that generates the op's request
+      // data: every required member must appear — including a required id
+      // (the /* type */ placeholders also mark the block as an illustration
+      // for the doc gates); an all-optional create renders an empty — still
+      // valid — literal, and the compiled example is self-consuming.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`go
 result, err := client.${entity.Name}(nil).Create(map[string]any{
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`    "${field.name}": /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`    "${it.name}": /* ${canonToType(it.type, target.name)} */,
 `)
-        }
       })
       Content(`}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)