@voxgig/sdkgen 4.2.4 → 4.2.6

package/model/sdkgen.aon

@@ -270,6 +270,15 @@ main: kit: target: &: {
   output: {
     path: *'' | string
 
+    # Whether generation may create a destination folder that does not yet
+    # exist. true preserves the ordinary behaviour: jostraca creates it and
+    # any missing parents. false keeps the target active but skips its
+    # out-of-tree generation pass until the destination folder exists — for
+    # example when a separate provider fleet is only checked out on some
+    # machines. An existing destination still goes through every ownership
+    # and overwrite-safety check below.
+    create: *true | boolean
+
     # Write into a destination that already holds content this generator did
     # not write.
     #
@@ -411,6 +420,16 @@ main: kit: feature: &: {
   # TODO: version '0.0.1' | semver # where semver is a string format type as per semver.org
   version: *'0.0.1' | string
 
+  # Transport role (station design §8.4): how the feature relates to the
+  # transport slot. 'base' REPLACES ctx.utility.fetcher outright (only the
+  # `test` feature); 'wrap' wraps it in init() (netsim, retry, cache,
+  # ratelimit, timeout, proxy - and station's own feature); 'none' is
+  # hook-only. Carried into the embedded config by configDefinition so
+  # station can validate the resolved feature order. Declared, never
+  # inferred: the obvious signal, an empty `hook: {}`, is wrong for a
+  # feature that both wraps AND dispatches hooks (station does).
+  transport: *'none' | 'base' | 'wrap'
+
   hook: &: {
    active: *false | boolean
    await: *false | boolean
@@ -480,6 +499,7 @@ main: kit: docs: &: {
   output: {
     path: *'' | string
     repo: *'' | string
+    create: *true | boolean
     adopt: *false | boolean
     sdkrel: *'' | string
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "4.2.4",
+  "version": "4.2.6",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {

package/project/.sdk/model/feature/audit.aon

@@ -6,6 +6,7 @@ main: kit: feature: audit: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/cache.aon

@@ -6,6 +6,7 @@ main: kit: feature: cache: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     options: {

package/project/.sdk/model/feature/clienttrack.aon

@@ -6,6 +6,7 @@ main: kit: feature: clienttrack: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/debug.aon

@@ -6,6 +6,7 @@ main: kit: feature: debug: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/idempotency.aon

@@ -6,6 +6,7 @@ main: kit: feature: idempotency: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/log.aon

@@ -6,6 +6,7 @@ main: kit: feature: log: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
 
   config: {

package/project/.sdk/model/feature/metrics.aon

@@ -6,6 +6,7 @@ main: kit: feature: metrics: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/netsim.aon

@@ -6,6 +6,7 @@ main: kit: feature: netsim: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     # Test-support feature: enable per test via

package/project/.sdk/model/feature/paging.aon

@@ -6,6 +6,7 @@ main: kit: feature: paging: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/proxy.aon

@@ -6,6 +6,7 @@ main: kit: feature: proxy: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     options: {

package/project/.sdk/model/feature/ratelimit.aon

@@ -6,6 +6,7 @@ main: kit: feature: ratelimit: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     options: {

package/project/.sdk/model/feature/rbac.aon

@@ -6,6 +6,7 @@ main: kit: feature: rbac: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/retry.aon

@@ -6,6 +6,7 @@ main: kit: feature: retry: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     # Opt-in: enable per SDK via options.feature.retry.active = true

package/project/.sdk/model/feature/streaming.aon

@@ -6,6 +6,7 @@ main: kit: feature: streaming: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/telemetry.aon

@@ -6,6 +6,7 @@ main: kit: feature: telemetry: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'none'
 
   config: {
     options: {

package/project/.sdk/model/feature/test.aon

@@ -6,6 +6,7 @@ main: kit: feature: test: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'base'
 
   config: {
     # Test mode is not active by default, unlike most features

package/project/.sdk/model/feature/timeout.aon

@@ -6,6 +6,7 @@ main: kit: feature: timeout: {
   version: '0.0.1'
   active: true
   base: 'BASE'
+  transport: 'wrap'
 
   config: {
     options: {

package/project/.sdk/src/cmp/c/Config_c.ts

@@ -46,9 +46,21 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
+  // The same config as an OBJECT, built by the shared helper so this target's
+  // literal and the data that replaces it above the threshold are the same
+  // config by construction. The JSON is what the threshold is measured on -
+  // emitted source size varies by language, the model does not. Passing
+  // target.name opts this target into the main slug/version/target identity
+  // fields (read by station's descriptor - see configDefinition).
+  const { def: configDef, json: configJson } = configDefinition(model, target.name)
+  const asData = isConfigData(configJson, configReprSetting(model))
+
+  // The feature block comes from configDefinition's def, not from f.config,
+  // so the literal carries each feature's `transport` role (station design
+  // §8.4) beside its options and cannot drift from the data rep.
   const featureConfig: any = {}
   each(feature, (f: any) => {
-    featureConfig[f.name] = f.config || {}
+    featureConfig[f.name] = configDef.feature[f.name] || {}
   })
 
   const entityOptions: any = {}
@@ -73,15 +85,6 @@ const Config = cmp(async function Config(props: any) {
       relations: n.relations,
     }, true), a), {})
 
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not. Passing
-  // target.name opts this target into the main slug/version/target identity
-  // fields (read by station's descriptor - see configDefinition).
-  const { def: configDef, json: configJson } = configDefinition(model, target.name)
-  const asData = isConfigData(configJson, configReprSetting(model))
-
   const config = {
     // main from configDefinition's def, not re-derived here, so the literal
     // rep and the data rep cannot disagree on identity (the Config_ts

package/project/.sdk/src/cmp/clojure/Config_clojure.ts

@@ -32,6 +32,7 @@ import {
 // N-feature-safe: an empty feature/entity map renders as (vs/jm).
 const Config = cmp(async function Config(props: any) {
   const ctx$ = props.ctx$
+  const target = props.target
 
   const model: Model = ctx$.model
 
@@ -39,7 +40,9 @@ const Config = cmp(async function Config(props: any) {
   // representations render from the same `def`, so they cannot describe
   // different configs - and this target picks up `options.server` (the OpenAPI
   // server-variable defaults), which the hand-rolled build here omitted.
-  const { def: config, json: configJson } = configDefinition(model)
+  // Passing target.name opts this target into the main slug/version/target
+  // identity fields (read by station's descriptor - see configDefinition).
+  const { def: config, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'config.clj' }, () => {

package/project/.sdk/src/cmp/dart/Config_dart.ts

@@ -143,8 +143,11 @@ const Config = cmp(async function Config(props: any) {
           Line(`  '${f.name}': () => ${nom(f, 'Name')}Feature(),`)
         }),
 
+        // Rendered from configDefinition's def, not from f.config, so the
+        // literal carries the feature's `transport` role (station design
+        // §8.4) beside its options and cannot drift from the data rep.
         '// #FeatureConfigs': () => each(feature, (f: any) => {
-          Line(`    '${f.name}': ${dartValue(f.config, 2)},`)
+          Line(`    '${f.name}': ${dartValue(configDef.feature[f.name], 2)},`)
         }),
 
 

package/project/.sdk/src/cmp/elixir/Config_elixir.ts

@@ -174,7 +174,10 @@ defmodule ${Name}.Config do
 `)
 
       each(feature, (f: any) => {
-        Content(`        ${elixirString(f.name)} => ${formatElixir(f.config || {}, 4)},
+        // From configDefinition's def, not f.config, so the literal carries
+        // the feature's `transport` role (station design §8.4) beside its
+        // options and cannot drift from the data rep.
+        Content(`        ${elixirString(f.name)} => ${formatElixir(configDef.feature[f.name] || {}, 4)},
 `)
       })
 

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -48,15 +48,34 @@ const Main = cmp(async function Main(props: any) {
   // Generate the documented typespec module (lib/<app>_types.ex).
   EntityTypes({ target })
 
-  // Copy tm/elixir verbatim (with ProjectName/projectname substitution).
+  // Copy tm/elixir (with ProjectName/projectname substitution).
+  //
+  // THE RUNTIME DIRECTORY HAS TO CARRY THE APP NAME. Copy substitutes file
+  // CONTENTS, never path components, so a blanket copy shipped the runtime as
+  // lib/projectname/ in every generated SDK. Nothing broke — Elixir resolves
+  // modules by their `defmodule`, not by path, and those were substituted
+  // correctly — so it compiled, tested green, and published looking wrong.
+  //
+  // Copy's `to` prop names the destination, so lib/projectname is copied
+  // explicitly under the app's own name and excluded from the blanket copy.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, /lib\/projectname\//],
     replace: {
       ...stdrep,
     }
   })
 
+  Folder({ name: 'lib' }, () => {
+    Copy({
+      from: 'tm/' + target.name + '/lib/projectname',
+      to: model.const.name,
+      replace: {
+        ...stdrep,
+      }
+    })
+  })
+
   Folder({ name: 'lib' }, () => {
 
     // Main SDK module (entity factory fns injected at the slot).

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

@@ -173,7 +173,10 @@ func MakeConfig() map[string]any {
 `)
 
     each(feature, (f: any) => {
-      const fconfig = f.config || {}
+      // From configDefinition's def, not f.config, so the literal carries
+      // the feature's `transport` role (station design §8.4) beside its
+      // options and cannot drift from the data rep.
+      const fconfig = configDef.feature[f.name] || {}
       Content(`			"${f.name}": ${formatGoMap(fconfig, 3)},
 `)
     })

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

@@ -7,6 +7,7 @@ import {
   canonKey,
   canonScalarKey,
   each,
+  opParams,
   exampleVarName,
   names,
 } from '@voxgig/sdkgen'
@@ -36,13 +37,25 @@ function projectPath(suffix?: string): string {
 // has no params and the request shape mirrors the entity fields). Returns
 // undefined when neither is present.
 function paramCanonType(entity: any, op: any, paramName: string): unknown {
-  const points = op && op.points ? each(op.points) : []
-  for (const pt of points as any[]) {
-    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
-    const found = (params as any[]).find((p: any) => p && p.name === paramName)
-    if (found) {
-      return found.type
-    }
+  // opParams, NOT a raw walk of op.points.
+  //
+  // opParams drops points flagged with select['$action'] and merges what is
+  // left; the typed-model generator reaches the op's params through it, so
+  // anything else is a DIFFERENT set of params wearing the same name.
+  //
+  // A raw walk returned the first match on ANY point, action points included.
+  // github's `action` entity has a field `owner` (`$OBJECT`, "A GitHub user")
+  // and seven create points whose path carries `{owner}` (a string) — so the
+  // type said Record<string, any> and the doc example said 'example_owner',
+  // and ts/README.md stopped compiling. Same for workflow_id: `number` in the
+  // type, quoted string in the example.
+  //
+  // Deriving from opParams is what actually makes good on the promise below —
+  // that the docs and the generated types cannot disagree.
+  const params = op ? each(opParams(op)) : []
+  const found = (params as any[]).find((p: any) => p && p.name === paramName)
+  if (found) {
+    return found.type
   }
   const field = (entity && entity.fields ? each(entity.fields) : [])
     .find((f: any) => f && f.name === paramName) as any

package/project/.sdk/src/cmp/java/Config_java.ts

@@ -48,10 +48,19 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Assemble the config shape (mirrors Config_go's emitted map).
+  // Identity comes from configDefinition's def, not re-derived here, so
+  // this target cannot disagree with the shared emitter on main.slug /
+  // main.version / main.target (the three station descriptor fields,
+  // station design §4) — passing target.name is what opts this target in.
+  const { def: configDef } = configDefinition(model, target.name)
+
+  // Assemble the config shape (mirrors Config_go's emitted map). The
+  // feature block comes from configDefinition's def, not from f.config,
+  // so it carries each feature's `transport` role (station design §8.4)
+  // beside its options and cannot drift from the shared emitter.
   const featureConfig: Record<string, any> = {}
   each(feature, (f: any) => {
-    featureConfig[f.name] = cleanModel(f.config || {})
+    featureConfig[f.name] = cleanModel(configDef.feature[f.name] || {})
   })
 
   const optionsEntity: Record<string, any> = {}
@@ -76,12 +85,6 @@ const Config = cmp(async function Config(props: any) {
       relations: n.relations,
     }, true), a), {})
 
-  // Identity comes from configDefinition's def, not re-derived here, so
-  // this target cannot disagree with the shared emitter on main.slug /
-  // main.version / main.target (the three station descriptor fields,
-  // station design §4) — passing target.name is what opts this target in.
-  const { def: configDef } = configDefinition(model, target.name)
-
   const config = {
     main: configDef.main,
     feature: featureConfig,

package/project/.sdk/src/cmp/js/Config_js.ts

@@ -142,8 +142,11 @@ const Config = cmp(async function Config(props: any) {
           Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
         }),
 
+        // Rendered from configDefinition's def, not from f.config, so the
+        // literal carries the feature's `transport` role (station design
+        // §8.4) beside its options and cannot drift from the data rep.
         '// #FeatureConfigs': () => each(feature, (f: any) => {
-          Line(` ${f.name}: ${formatJson(f.config, { margin: 4 })},`)
+          Line(` ${f.name}: ${formatJson(configDef.feature[f.name], { margin: 4 })},`)
         }),
 
 

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection, srcFeatureExcludes,
+  entityClassName, entityCollection, srcFeatureExcludes, stationLibrary,
 } from '@voxgig/sdkgen'
 
 
@@ -102,6 +102,25 @@ if (fres instanceof Promise) { await fres }
             MainEntity(entprops)
           })
         })
+
+      // Station self-registration (station design §6.2 path 1;
+      // station-declarative-config §11 item 2): emitted ONLY when the model
+      // carries an ACTIVE station feature (installed via
+      // `package add @voxgig/sdkgen-station`). The library package name
+      // comes from the feature model's own `deps.js` block — the same entry
+      // collectDeps flows into package.json — so the manifest dependency
+      // and the emitted require cannot disagree.
+      const stationPkg = stationLibrary(model, target.name)
+      if (null != stationPkg) {
+        Fragment({
+          from: Path.normalize(
+            __dirname + '/../../../src/cmp/js/fragment/MainStation.fragment.js'),
+          replace: {
+            ...props.ctx$.stdrep,
+            "'STATIONPKG'": JSON.stringify(stationPkg),
+          }
+        })
+      }
     })
 
     Config({ target })

package/project/.sdk/src/cmp/js/fragment/MainStation.fragment.js

@@ -0,0 +1,36 @@
+
+
+// Station self-registration (voxgig/station design §6.2, path 1): linking
+// this package is the whole bootstrap. When the station library is
+// installed beside this SDK, the {construct, config} factory pair is
+// registered under the api slug (config.main.slug, the descriptor slug) at
+// module init, so `station.sdk('<name>')` needs no imports in application
+// code. Registration is SOFT — the station library is a peer dependency of
+// the station feature, and a project without it skips registration and
+// gets exactly the SDK it always had. Only a genuine module-not-found is
+// swallowed: a station that RESOLVES but throws while loading must
+// propagate (a silently empty factory table has no visible cause), and so
+// must station_factory_conflict — two different builds of one SDK in one
+// process is not a thing to pick between quietly.
+let stationInstalled = true
+try { require.resolve('STATIONPKG') }
+catch (err) {
+  // MODULE_NOT_FOUND is the absent case. Anything else - an invalid
+  // package config, a root entry the package does not export - is a
+  // real failure to load a station that IS installed, and swallowing
+  // it would leave an empty factory table with no visible cause.
+  if ('MODULE_NOT_FOUND' !== (err && err.code)) { throw err }
+  stationInstalled = false
+}
+
+if (stationInstalled) {
+  const { provide } = require('STATIONPKG')
+  // A station library predating the factory table has no provide() —
+  // there is nothing to register with, which is not this SDK's error.
+  if ('function' === typeof provide) {
+    provide(config.main.slug, {
+      construct: (options) => new ProjectNameSDK(options),
+      config,
+    })
+  }
+}

package/project/.sdk/src/cmp/js/utility_js.ts

@@ -6,6 +6,7 @@ import {
   canonKey,
   canonScalarKey,
   each,
+  opParams,
 } from '@voxgig/sdkgen'
 
 import {
@@ -28,13 +29,25 @@ import {
 // does. Falls back to the entity field of the same name (used when the op
 // has no params). Returns undefined when neither is present.
 function paramCanonType(entity: any, op: any, paramName: string): unknown {
-  const points = op && op.points ? each(op.points) : []
-  for (const pt of points as any[]) {
-    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
-    const found = (params as any[]).find((p: any) => p && p.name === paramName)
-    if (found) {
-      return found.type
-    }
+  // opParams, NOT a raw walk of op.points.
+  //
+  // opParams drops points flagged with select['$action'] and merges what is
+  // left; the typed-model generator reaches the op's params through it, so
+  // anything else is a DIFFERENT set of params wearing the same name.
+  //
+  // A raw walk returned the first match on ANY point, action points included.
+  // github's `action` entity has a field `owner` (`$OBJECT`, "A GitHub user")
+  // and seven create points whose path carries `{owner}` (a string) — so the
+  // type said Record<string, any> and the doc example said 'example_owner',
+  // and ts/README.md stopped compiling. Same for workflow_id: `number` in the
+  // type, quoted string in the example.
+  //
+  // Deriving from opParams is what actually makes good on the promise below —
+  // that the docs and the generated types cannot disagree.
+  const params = op ? each(opParams(op)) : []
+  const found = (params as any[]).find((p: any) => p && p.name === paramName)
+  if (found) {
+    return found.type
   }
   const field = (entity && entity.fields ? each(entity.fields) : [])
     .find((f: any) => f && f.name === paramName) as any

package/project/.sdk/src/cmp/kotlin/Config_kotlin.ts

@@ -46,9 +46,19 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
+  // Identity comes from configDefinition's def, not re-derived here, so
+  // this target cannot disagree with the shared emitter on main.slug /
+  // main.version / main.target (the three station descriptor fields,
+  // station design §4) — passing target.name is what opts this target in.
+  const { def: configDef } = configDefinition(model, target.name)
+
+  // The feature block comes from configDefinition's def, not from
+  // f.config, so it carries each feature's `transport` role (station
+  // design §8.4) beside its options and cannot drift from the shared
+  // emitter.
   const featureConfig: Record<string, any> = {}
   each(feature, (f: any) => {
-    featureConfig[f.name] = cleanModel(f.config || {})
+    featureConfig[f.name] = cleanModel(configDef.feature[f.name] || {})
   })
 
   const optionsEntity: Record<string, any> = {}
@@ -73,12 +83,6 @@ const Config = cmp(async function Config(props: any) {
       relations: n.relations,
     }, true), a), {})
 
-  // Identity comes from configDefinition's def, not re-derived here, so
-  // this target cannot disagree with the shared emitter on main.slug /
-  // main.version / main.target (the three station descriptor fields,
-  // station design §4) — passing target.name is what opts this target in.
-  const { def: configDef } = configDefinition(model, target.name)
-
   const config = {
     main: configDef.main,
     feature: featureConfig,

package/project/.sdk/src/cmp/lua/Config_lua.ts

@@ -133,7 +133,10 @@ local function make_config()
 `)
 
     each(feature, (f: any) => {
-      const fconfig = f.config || {}
+      // From configDefinition's def, not f.config, so the literal carries
+      // the feature's `transport` role (station design §8.4) beside its
+      // options and cannot drift from the data rep.
+      const fconfig = configDef.feature[f.name] || {}
       Content(`      ["${f.name}"] = ${formatLuaTable(fconfig, 3)},
 `)
     })

package/project/.sdk/src/cmp/ocaml/Config_ocaml.ts

@@ -40,7 +40,9 @@ const Config = cmp(async function Config(props: any) {
   // representations render from the same `def`, so they cannot describe
   // different configs - and this target picks up `options.server` (the OpenAPI
   // server-variable defaults), which the hand-rolled build here omitted.
-  const { def: config, json: configJson } = configDefinition(model)
+  // Passing target.name opts this target into the main slug/version/target
+  // identity fields (read by station's descriptor - see configDefinition).
+  const { def: config, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'sdk_config.' + target.ext }, () => {

package/project/.sdk/src/cmp/php/Config_php.ts

@@ -197,7 +197,10 @@ class ${model.const.Name}Config
 `)
 
     each(feature, (f: any) => {
-      const fconfig = f.config || {}
+      // From configDefinition's def, not f.config, so the literal carries
+      // the feature's `transport` role (station design §8.4) beside its
+      // options and cannot drift from the data rep.
+      const fconfig = configDef.feature[f.name] || {}
       Content(`                "${f.name}" => ${formatPhpArray(fconfig, 4)},
 `)
     })