@voxgig/sdkgen 1.2.0 → 1.3.1

package/model/sdkgen.aontu

@@ -0,0 +1,137 @@
+
+
+main: def: {
+  desc: *'' | string
+}
+
+
+# Canonical order for language targets in generated documentation
+# (top-level README, per-language docs links). Targets present in the
+# SDK but not listed here are appended afterwards in spec-defined
+# order. Override per-SDK by setting
+# `main.kit.config.docs_order: ['py','ts',...]` in
+# `<sdk>/.sdk/model/config.jsonic`.
+main: kit: config: docs_order: *['ts','py','php','go','rb','lua'] | [&: string]
+
+main: kit: target: &: {
+  name: key()
+  active: *true | boolean
+  ext: string
+  comment: line: string
+  module: {
+    name: string
+  }
+  deps: &: {
+    active: *false | boolean
+    version: *'*' | string
+  }
+
+  # Publication: how (and whether) this port is released. Credentials are
+  # always injected by the aql key vault (never on disk or argv).
+  #
+  # Every port gets a git release tag `<prefix>/vX.Y.Z` (prefix defaults
+  # to the target name). Ports with a `registry` entry also publish a
+  # package to that registry — but only when the registry is active
+  # (`registry.state === 'active'`): registries are activated one at a
+  # time as each ecosystem is ready. Until then a port is 'pending'
+  # (declared + git-tag-published, but not yet uploaded to the registry).
+  # Tag-only ports (the go family: the Go proxy resolves from GitHub
+  # tags) simply leave `registry` unset — they are implicitly pending
+  # until their `<target>/vX.Y.Z` tag exists.
+  publish: {
+    # Git release tag (all ports).
+    tag: {
+      active: *true | boolean
+      prefix: *'' | string       # '' -> target name
+      # Who implements the tag publish: 'port' delegates to the port's
+      # own Makefile publish recipe (which may do more, e.g. go proxy
+      # priming); 'root' uses the generated root tag-push recipe (for
+      # ports without a Makefile, e.g. go-cli / go-mcp).
+      via: *'port' | string
+      vault: {
+        recipe: *'github' | string   # aql `vault exec --for=<recipe>=<alias>`
+        alias: *'github' | string    # default vault alias for the token
+      }
+    }
+
+    # Package registry (omit for tag-only ports).
+    registry: {
+      # Publication state (tri-state):
+      #   'pending'  — declared + git-tag-published, NOT yet on the
+      #                registry (the default: READMEs point at the git
+      #                tag, deploy publishes the tag only).
+      #   'active'   — package is uploaded to the registry; READMEs show
+      #                the real `npm install`/`pip install`/... command.
+      #   'inactive' — registry deliberately disabled (also tag-only).
+      # Kept as a plain string (default 'pending') rather than a literal
+      # disjunction to sidestep aontu's literal-disjunction fragility;
+      # code (packageMeta.registryState / Deploy) enforces the tri-state.
+      state: *'pending' | string
+      # Back-compat alias: `active: true` still means state === 'active'.
+      active: *false | boolean   # real publishes refuse when not active
+      name: *'' | string         # npm | pypi | packagist | rubygems | luarocks
+      url: *'' | string
+      package: *'' | string      # registry package name ('' -> derived)
+      vault: {
+        recipe: *'' | string     # aql --for preset (npm, pypi, gem, ...)
+        alias: *'' | string      # vault alias ('' -> registry name)
+        env: *'' | string        # raw env var to inject when no preset exists
+      }
+    }
+  }
+}
+
+
+main: kit: entity: &: {
+  name: key()
+  active: *true | boolean
+
+  alias: {}
+}
+
+
+main: kit: feature: &: {
+  name: key()
+  active: *false | boolean
+  title: string
+
+  # TODO: version '0.0.1' | semver # where semver is a string format type as per semver.org
+  version: *'0.0.1' | string
+
+  hook: &: {
+   active: *false | boolean
+   await: *false | boolean
+  }
+
+  hook: {
+    PostConstruct: {}
+    PostConstructEntity: {}
+    SetData: {}
+    GetData: {}
+    GetMatch: {}
+        
+    PreTarget: {}
+    PreSpec: {}
+    PreRequest: {}
+    PreResponse: {}
+    PreResult: {}
+    PostOperation: {}
+  }
+
+  # Target specific structures 
+  target: &: deps: &: {
+    active: *false | boolean
+    version: *'*' | string 
+  }
+}
+
+
+main: kit: option: &: {
+  name: key()
+  active: *true | boolean
+}
+
+
+
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "types": "dist/sdkgen.d.ts",
@@ -23,12 +23,18 @@
     "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test dist-test/**/*.test.js",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test",
-    "clean": "rm -rf node_modules yarn.lock package-lock.json",
+    "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
     "reset": "npm run clean && npm i && npm run build && npm test",
     "embed-version": "node build/version.js",
+    "repo-bump": "npm version patch --no-git-tag-version && node -e \"console.log('bumped to v' + require('./package.json').version + ' (package.json only - commit via repo-tag / repo-release)')\"",
     "repo-tag": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo TAG: v$REPO_VERSION && git commit -a -m v$REPO_VERSION && git push && git tag v$REPO_VERSION && git push --tags;",
+    "repo-tag-dry": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo \"[dry-run] TAG: v$REPO_VERSION\" && if git rev-parse -q --verify refs/tags/v$REPO_VERSION >/dev/null; then echo \"[dry-run] WARNING: tag v$REPO_VERSION already exists - bump the version first\"; else echo \"[dry-run] would commit -a, push, tag v$REPO_VERSION and push --tags; nothing done\"; fi && git status --short",
     "repo-publish": "npm run clean && npm i && npm run repo-publish-quick",
-    "repo-publish-quick": "npm run embed-version && npm run build && npm run test && npm run repo-tag && npm publish --registry https://registry.npmjs.org --access=public"
+    "repo-publish-dry": "npm run clean && npm i && npm run repo-publish-quick-dry",
+    "repo-publish-quick": "npm run embed-version && npm run build && npm run test && npm run repo-tag && npm publish --registry https://registry.npmjs.org --access=public",
+    "repo-publish-quick-dry": "npm run build && npm run test && ( npm publish --dry-run --registry https://registry.npmjs.org --access=public || echo \"[dry-run] npm publish refused (see npm error above) - usually the version is already published; bump package.json before a real release\" )",
+    "repo-release": "npm run repo-publish && npm run repo-tag",
+    "repo-release-dry": "npm run repo-publish-quick-dry && npm run repo-tag-dry"
   },
   "license": "MIT",
   "files": [
@@ -41,9 +47,9 @@
   ],
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
-    "@types/node": "25.8.0",
+    "@types/node": "26.1.0",
     "json-schema-to-ts": "3.1.1",
-    "memfs": "4.57.2",
+    "memfs": "4.62.0",
     "typescript": "6.0.3"
   },
   "peerDependencies": {
@@ -51,6 +57,7 @@
     "@voxgig/struct": ">=0",
     "@voxgig/util": ">=0",
     "aontu": ">=0",
-    "jostraca": ">=0"
+    "jostraca": ">=0",
+    "shape": ">=10.1"
   }
 }

package/project/.sdk/model/target/go-cli.jsonic

@@ -0,0 +1,47 @@
+
+// Go CLI target — a Go program that *consumes* the sibling Go SDK
+// (generated by the `go` target into the same SDK repo). It is not a
+// language SDK in its own right, so the standard per-entity /
+// per-feature / readme / test generation phases are switched off via
+// the `phase` map below.
+
+main: kit: target: 'go-cli': {
+
+  title: 'Go CLI'
+  ext: go
+  comment: line: "//"
+  module: name: '$$name$$'
+
+  // Per-generation-phase activation. Mirrors the feature pattern
+  // (`main.kit.feature.<name>: { active: true }`). Root.ts inspects
+  // `target.phase.<name>.active` — defaults to true (active) when
+  // the entry is missing, so existing standard targets need no
+  // changes. A CLI-style target switches the standard phases off
+  // and runs only Main.
+  phase: {
+    entity:  { active: false }
+    feature: { active: false }
+    readme:  { active: false }
+    test:    { active: false }
+  }
+
+  // No external module deps declared here; the generated go.mod uses
+  // a relative replace to the sibling SDK at ../go and (until
+  // aql/eng is published with a subdir tag) a local replace for the
+  // AQL engine. See Main_go-cli.ts.
+  deps: {}
+}
+
+
+// Feature-deps map slot — every target carries this so the same
+// feature can specify per-target dep variants.
+main: kit: feature: &: target: 'go-cli': deps: &: {
+  kind: *'prod' | string
+}
+
+
+# Publication: tag-only — the Go module proxy resolves versions from the
+# go-cli/vX.Y.Z GitHub tag; there is no package registry to upload to.
+main: kit: target: 'go-cli': publish: {
+  tag: { active: true, via: 'root' }
+}

package/project/.sdk/model/target/go-mcp.jsonic

@@ -0,0 +1,41 @@
+
+// Go MCP server target — a Go program that *consumes* the sibling Go
+// SDK and exposes it as MCP tools. Like go-cli, it is not a language
+// SDK in its own right, so the standard per-entity / per-feature /
+// readme / test generation phases are switched off via the `phase`
+// map below.
+
+main: kit: target: 'go-mcp': {
+
+  title: 'Go MCP server'
+  ext: go
+  comment: line: "//"
+  module: name: '$$name$$'
+
+  // Per-generation-phase activation. Mirrors go-cli — only Main runs.
+  phase: {
+    entity:  { active: false }
+    feature: { active: false }
+    readme:  { active: false }
+    test:    { active: false }
+  }
+
+  // No external module deps declared here. The generated go.mod uses
+  // a relative replace to the sibling SDK at ../go and declares the
+  // MCP Go SDK as a direct dep. See Main_go-mcp.ts.
+  deps: {}
+}
+
+
+// Feature-deps map slot — every target carries this so the same
+// feature can specify per-target dep variants.
+main: kit: feature: &: target: 'go-mcp': deps: &: {
+  kind: *'prod' | string
+}
+
+
+# Publication: tag-only — the Go module proxy resolves versions from the
+# go-mcp/vX.Y.Z GitHub tag; there is no package registry to upload to.
+main: kit: target: 'go-mcp': publish: {
+  tag: { active: true, via: 'root' }
+}

package/project/.sdk/model/target/go.jsonic

@@ -11,12 +11,18 @@ main: kit: target: go: {
     kind: *'prod' | string
   }
 
-  deps: {
-    'github.com/voxgig/struct': { active: true, version: 'v0.0.0', replace: './utility/struct' }
-  }
+  // struct is inlined under <gomodule>/utility/struct — no external dep.
+  deps: {}
 }
 
 
 main: kit: feature: &: target: go: deps: &: {
   kind: *'prod' | string
 }
+
+
+# Publication: tag-only — the Go module proxy resolves versions from the
+# go/vX.Y.Z GitHub tag; there is no package registry to upload to.
+main: kit: target: go: publish: {
+  tag: { active: true }
+}

package/project/.sdk/model/target/js.jsonic

@@ -21,3 +21,16 @@ main: kit: feature: &: target: js: deps: &: {
   # TODO: fix aontu disjunctions!
   kind: *'prod' | string # 'peer' |'dev'
 }
+
+
+# Publication: npm registry (declared, publish pending — git-tag only).
+main: kit: target: js: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'npm'
+    url: 'https://registry.npmjs.org'
+    vault: { recipe: 'npm', alias: 'npm' }
+  }
+}

package/project/.sdk/model/target/lua.jsonic

@@ -21,3 +21,16 @@ main: kit: target: lua: {
 main: kit: feature: &: target: lua: deps: &: {
   kind: *'prod' | string
 }
+
+
+# Publication: luarocks registry (declared, publish pending — git-tag only).
+main: kit: target: lua: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'luarocks'
+    url: 'https://luarocks.org'
+    vault: { alias: 'luarocks', env: 'LUAROCKS_API_KEY' }
+  }
+}

package/project/.sdk/model/target/php.jsonic

@@ -19,3 +19,16 @@ main: kit: target: php: {
 main: kit: feature: &: target: php: deps: &: {
   kind: *'prod' | string
 }
+
+
+# Publication: packagist registry (declared, publish pending — git-tag only).
+main: kit: target: php: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'packagist'
+    url: 'https://packagist.org'
+    vault: { alias: 'packagist', env: 'PACKAGIST_API_TOKEN' }
+  }
+}

package/project/.sdk/model/target/py.jsonic

@@ -21,3 +21,16 @@ main: kit: target: py: {
 main: kit: feature: &: target: py: deps: &: {
   kind: *'prod' | string
 }
+
+
+# Publication: pypi registry (declared, publish pending — git-tag only).
+main: kit: target: py: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'pypi'
+    url: 'https://pypi.org'
+    vault: { recipe: 'pypi', alias: 'pypi' }
+  }
+}

package/project/.sdk/model/target/rb.jsonic

@@ -21,3 +21,16 @@ main: kit: target: rb: {
 main: kit: feature: &: target: rb: deps: &: {
   kind: *'prod' | string
 }
+
+
+# Publication: rubygems registry (declared, publish pending — git-tag only).
+main: kit: target: rb: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'rubygems'
+    url: 'https://rubygems.org'
+    vault: { recipe: 'gem', alias: 'gem' }
+  }
+}

package/project/.sdk/model/target/ts.jsonic

@@ -24,3 +24,16 @@ main: kit: feature: &: target: ts: deps: &: {
   # TODO: fix aontu disjunctions!
   kind: *'prod' | string # 'peer' |'dev'
 }
+
+
+# Publication: npm registry (declared, publish pending — git-tag only).
+main: kit: target: ts: publish: {
+  tag: { active: true }
+  registry: {
+    state: 'pending'
+    active: false
+    name: 'npm'
+    url: 'https://registry.npmjs.org'
+    vault: { recipe: 'npm', alias: 'npm' }
+  }
+}

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

@@ -30,6 +30,7 @@ const EntityOperation = cmp(function Operation(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/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)
 }