@voxgig/sdkgen 3.6.0 → 3.7.0

package/project/.sdk/tm/ts/src/utility/MakeOptionsUtility.ts

@@ -71,6 +71,12 @@ function makeOptions(ctx: Context) {
       }
     },
     utility: {},
+    // Feature INSTANCES supplied at construction (the station adopt
+    // path): consumed by the constructor's featureAdd loop, so they are
+    // class instances, not data - `$ANY` accepts them verbatim. Without
+    // this entry the seam is dead: the constructor reads
+    // options.extend, but validate rejected the key.
+    extend: '`$ANY`' as any,
     system: {
       fetch: undefined as any
     },
@@ -134,10 +140,22 @@ function makeOptions(ctx: Context) {
   // otherwise order the map test-first, then the remaining names sorted, so
   // the outcome is deterministic and `test` is always the base transport.
   if (0 === featureorder.length) {
-    const names = Object.keys(opts.feature || {}).sort()
-    featureorder = names.indexOf('test') < 0
+    let names = Object.keys(opts.feature || {}).sort()
+    names = names.indexOf('test') < 0
       ? names
       : ['test'].concat(names.filter((n: string) => 'test' !== n))
+    // Station special case, mirroring test's: its transport wrap must
+    // sit immediately outside the base transport (inside retry/cache/
+    // netsim), so map-form activation hoists it to just after test -
+    // or first, when no test entry exists. Without this the sorted
+    // default would init station last and wrap OUTSIDE the recording
+    // features, turning its wire-truth events into fiction.
+    const si = names.indexOf('station')
+    if (0 <= si) {
+      names.splice(si, 1)
+      names.splice(names.indexOf('test') + 1, 0, 'station')
+    }
+    featureorder = names
   }
 
   opts.__derived__ = {

package/project/.sdk/tm/ts/test/utility/Corpus.test.ts

@@ -0,0 +1,85 @@
+import { test, describe } from 'node:test'
+import { ok, equal } from 'node:assert'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { TEST_JSON_FILE } from './index'
+
+
+// Guards the shared corpus AS A WHOLE, which the per-section guard in the
+// language runners cannot do.
+//
+// That guard only fires for a section some test actually runs. Seven sections
+// — fetcher, makeFetchDef, makePoint, makeResult, featureAdd, featureHook and
+// featureInit — had no test calling them at all, so they sat at `set: []`
+// through two reviews reporting nothing. A fixture nobody runs is
+// indistinguishable from a fixture that passes.
+//
+// Deferral is therefore DATA (`basic.pending`), not a comment: comments do not
+// survive compilation to test.json, so a marker written only in the .aontu
+// source cannot be checked by the thing that consumes it. Being data, these
+// invariants hold for every port, not just this one.
+describe('Corpus', () => {
+
+  // Resolved the same way runner.ts resolves it — from dist-test/, one level
+  // up from this file's dist-test/utility/.
+  const corpus = JSON.parse(
+    readFileSync(join(__dirname, '..', TEST_JSON_FILE), 'utf8'))
+
+  const primary: Record<string, any> = corpus.primary || {}
+  const names = Object.keys(primary).sort()
+
+
+  test('the corpus is not empty', () => {
+    ok(0 < names.length, 'no primary sections found — check TEST_JSON_FILE')
+  })
+
+
+  // A section that compiles to zero cases must say why, in the fixture.
+  test('every empty section declares why it is deferred', () => {
+    const undeclared = names.filter((n) => {
+      const basic = primary[n]?.basic
+      return Array.isArray(basic?.set) && 0 === basic.set.length &&
+        'string' !== typeof basic?.pending
+    })
+    equal(undeclared.join(','), '',
+      'these sections compile to ZERO cases and carry no `basic: pending` ' +
+      'reason — add cases, or state the blocker in .sdk/test/primary/<name>.aontu')
+  })
+
+
+  // "PENDING" with no reason is just a way to keep a hole open.
+  test('every deferral gives a real reason', () => {
+    for (const n of names) {
+      const pending = primary[n]?.basic?.pending
+      if (null == pending) continue
+      ok(20 < String(pending).length,
+        `${n}: 'pending' needs a reason, not just a marker`)
+    }
+  })
+
+
+  // The other direction: a section that has gained cases must drop its
+  // deferral, or the marker rots into a lie and the runners keep excusing it.
+  test('a deferred section that gained cases is promoted', () => {
+    const stale = names.filter((n) => {
+      const basic = primary[n]?.basic
+      return null != basic?.pending && Array.isArray(basic?.set) &&
+        0 < basic.set.length
+    })
+    equal(stale.join(','), '',
+      'these sections now have cases — remove `basic: pending` from the ' +
+      'fixture and from the PENDING list in the language runners')
+  })
+
+
+  // Every section must actually be a section: `basic.set` is what the runners
+  // iterate, and a fixture that failed to compile silently loses it.
+  test('every section has a basic.set list', () => {
+    for (const n of names) {
+      ok(Array.isArray(primary[n]?.basic?.set),
+        `${n}: no basic.set list — the fixture did not compile as expected`)
+    }
+  })
+
+})

package/project/.sdk/tm/ts/test/utility/PrimaryUtility.test.ts

@@ -35,7 +35,7 @@ describe('PrimaryUtility', async () => {
   // (.sdk/test/primary/<name>.aontu carries a PENDING header). Everything
   // else MUST contribute cases.
   const PENDING = new Set([
-    'fetcher', 'makeFetchDef', 'makePoint', 'makeResult',
+    'fetcher', 'makeFetchDef', 'makeResult',
     'featureAdd', 'featureHook', 'featureInit',
   ])
 
@@ -279,22 +279,15 @@ describe('PrimaryUtility', async () => {
   })
 
 
-  test('makePoint-single', () => {
-    const ctx = makeCtx()
-    const point = {
-      parts: ['items', '{id}'],
-      args: { params: [] },
-      params: [],
-      alias: {},
-      select: {},
-      active: true,
-      transform: { req: undefined, res: undefined },
-    }
-    ctx.op.points = [point]
-
-    const result = utility.makePoint(ctx)
-    ok(!(result instanceof Error))
-    equal(ctx.point, point)
+  // Was one hand-written case (the single-point path) covering one of this
+  // utility's seven branches, which is how the corpus fixture came to be
+  // marked deferred as "needs a real client". It does not: Context rebuilds
+  // `op` from opname + entity + config, and `options` can be supplied
+  // literally, so allow.op, the empty-points error, exist-selection,
+  // $action selection and the invalid-$action error are all expressible.
+  // Driven from the corpus now, so every port asserts the same branches.
+  test('makePoint-basic', async () => {
+    await runsection('makePoint', utility.makePoint)
   })
 
 

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "provides": {
     "target": [
       "c",

package/src/cmp/AgentGuideTop.ts

@@ -80,6 +80,24 @@ package (other languages). Each target's guide documents its features.
       Content(`**Entities** (${entities.length}): `)
       Content(entities.map((e: any) => `\`${e.Name || e.name}\``).join(', ') + `.
 
+`)
+    }
+
+    // Station paragraph (station design §9.4), only when the model
+    // carries the feature: an agent working on this repo should know
+    // the runtime story without leaving AGENTS.md.
+    if (features.some((f: any) => 'station' === f.name)) {
+      Content(`**Station**: this SDK is a
+[voxgig/station](https://github.com/voxgig/station) plugin (the
+\`station\` feature, off by default). Bound to an open \`Station\`,
+the credential is resolved by sekreto under the plugin's secret name
+and injected at the transport seam — \`options()\` and
+\`prepare()\` output hold only a placeholder, so both are safe to
+inspect and log. \`station.tap(...)\`/\`station.events()\` show live
+traffic; \`station.plugins()\` lists descriptors. See the "Use with
+Station" README section and \`src/feature/station/\` (or the
+target's feature container) for the generated adapter.
+
 `)
     }
 

package/src/cmp/Readme.ts

@@ -6,6 +6,7 @@ import { ReadmeIntro } from './ReadmeIntro'
 import { ReadmeInstall } from './ReadmeInstall'
 import { ReadmeQuick } from './ReadmeQuick'
 import { ReadmeErrors } from './ReadmeErrors'
+import { ReadmeStation } from './ReadmeStation'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
@@ -24,6 +25,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeIntro({ target })
     ReadmeInstall({ target })
     ReadmeQuick({ target })
+    ReadmeStation({ target })
     ReadmeErrors({ target })
     ReadmeHowto({ target })
     ReadmeModel({ target })

package/src/cmp/ReadmeStation.ts

@@ -0,0 +1,69 @@
+
+import { cmp, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { envName } from '../helpers/packageMeta'
+
+
+// The "Use with Station" README section (station design §9.4): rendered
+// ONLY when the project's model carries the station feature (installed
+// via `package add @voxgig/sdkgen-station`) — a project without it sees
+// nothing. Documents the binding forms and the secret name; store
+// configuration is sekreto's documentation, deliberately not restated
+// here (one canonical source).
+
+// Targets where station.connect(SDK) is the idiomatic binding; everything
+// else uses inverted binding through the SDK's own constructor.
+const CONNECT_TARGETS = ['ts', 'js', 'py', 'rb', 'php', 'lua', 'perl']
+
+const ReadmeStation = cmp(function ReadmeStation(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const features = getModelPath(model, `main.${KIT}.feature`,
+    { only_active: false, required: false }) || {}
+  const station = Object.values(features)
+    .find((f: any) => 'station' === f?.name)
+  if (null == station) { return }
+
+  const env = envName(model)
+  const secretname = env.toLowerCase() + '.apikey'
+  const connect = CONNECT_TARGETS.includes(target.name)
+
+  Content(`
+## Use with Station
+
+This SDK ships as a [voxgig/station](https://github.com/voxgig/station)
+plugin: bind it to a local \`Station\` and outbound configuration,
+credentials, and observability move to one place. The feature is
+present but **off by default** — nothing changes until you bind.
+
+${connect
+  ? `Bind by passing the SDK class to the station:
+
+1. \`station = Station.open()\` — profile, env, and proxy all defaulted.
+2. \`client = station.connect(${model.const.Name}SDK)\` — replaces direct
+   construction.`
+  : `Bind through the constructor this SDK already has (inverted
+binding): open a station, then construct with station-built options —
+\`station.options()\` merges the handle, the activation entry, and the
+correct feature order into the plain options the constructor accepts.`}
+
+The credential comes from [sekreto](https://github.com/voxgig/sekreto)
+under the name \`${secretname}\` — by default the \`${env}_APIKEY\`
+environment variable this README already documents, unchanged. Point a
+profile in \`station.json\` at a vault later and application code does
+not change; sekreto's own documentation covers the stores. The key
+stays out of \`options()\` and \`prepare()\` output; \`station.tap(...)\`
+shows live traffic.
+`)
+})
+
+
+export {
+  ReadmeStation
+}

package/src/helpers/naming.ts

@@ -216,6 +216,8 @@ const SWIFT_SDK_TYPES = new Set<string>([
   'OrderedDictionary', 'Sentinel', 'Value', 'VList', 'VMap', 'WalkApply',
   // function/callback aliases
   'FetcherFunc', 'Formatter', 'NativeCall0', 'NativeRef', 'SystemFetch',
+  // transport plumbing
+  'ManualRedirectDelegate',
   // features
   'AuditFeature', 'BaseFeature', 'CacheFeature', 'ClienttrackFeature',
   'DebugFeature', 'IdempotencyFeature', 'LogFeature', 'MetricsBucket',
@@ -245,8 +247,8 @@ function swiftSafeTypeName(Name: string): string {
 }
 
 
-// PHP RESERVED WORDS THAT CANNOT BE A CLASS NAME — a fourth hazard, and the
-// only one of the four where the check must be CASE-INSENSITIVE.
+// PHP RESERVED WORDS THAT CANNOT BE A CLASS NAME — a fifth hazard, and the
+// only one of the five where the check must be CASE-INSENSITIVE.
 //
 // PHP's grammar refuses a reserved word where a class name is expected, so a
 // spec with a `Namespace` entity emitted a file that does not parse at all:
@@ -316,6 +318,45 @@ function phpSafeTypeName(Name: string): string {
 }
 
 
+// TypeScript GLOBAL TYPE NAMES — a fourth hazard, same shape as the Ruby and
+// Swift ones above but for TS/JS builtins, which are in scope everywhere
+// with no import. An entity named `Record` emitted `export interface Record
+// {...}` and canonToType's own generic-object mapping (`Record<string,
+// any>`) then resolved to that flat interface INSIDE THE SAME FILE instead
+// of the builtin: `error TS2315: Type 'Record' is not generic` — on a
+// field of the `Record` entity itself.
+//
+// Utility types (`Record`, `Partial`, ...) and common global constructors
+// (`Array`, `Map`, `Promise`, ...) that a REST entity name plausibly lands
+// on. Mirrors RB_CORE_CONSTANTS / SWIFT_SDK_TYPES: only real builtins are
+// listed, so a non-colliding SDK stays byte-identical to before.
+const TS_RESERVED_TYPES = new Set<string>([
+  // utility types
+  'Record', 'Partial', 'Required', 'Readonly', 'Pick', 'Omit', 'Exclude',
+  'Extract', 'NonNullable', 'Parameters', 'ReturnType', 'InstanceType',
+  'Awaited', 'ConstructorParameters',
+  // global constructors / builtins
+  'Array', 'Object', 'Map', 'Set', 'WeakMap', 'WeakSet', 'Date', 'Error',
+  'Function', 'Promise', 'RegExp', 'String', 'Number', 'Boolean', 'Symbol',
+  'ArrayBuffer', 'Proxy', 'Reflect', 'JSON', 'Math',
+])
+
+
+// Does `Name` collide with a TS/JS global type?
+function isTsReservedType(Name: string): boolean {
+  return TS_RESERVED_TYPES.has(Name)
+}
+
+
+// A collision-free TS type name for a generated type: unchanged, unless it
+// shadows a TS/JS global, in which case `Type` is appended (`Record` ->
+// `RecordType`). Mirrors rbSafeTypeName / swiftSafeTypeName. Applied ONLY
+// to the bare entity data type, for the same reason as both of those.
+function tsSafeTypeName(Name: string): string {
+  return isTsReservedType(Name) ? Name + 'Type' : Name
+}
+
+
 // Is `name` a reserved word (an illegal identifier) in the target language?
 function isReservedName(name: string, lang: string): boolean {
   const set = RESERVED[lang]
@@ -455,6 +496,8 @@ export {
   swiftSafeTypeName,
   isPhpReservedType,
   phpSafeTypeName,
+  isTsReservedType,
+  tsSafeTypeName,
   jsProp,
   jsOptProp,
   jsKey,

package/src/sdkgen.ts

@@ -59,7 +59,7 @@ import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonToDtype, canonKey } from './helpers/canonType'
 import { OP_SUFFIX, opTypeName, opParams, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
-import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, phpSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
+import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
 import { serverVariables, hasServerVariables } from './helpers/serverVars'
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
@@ -1089,6 +1089,8 @@ export {
   swiftSafeTypeName,
   isPhpReservedType,
   phpSafeTypeName,
+  isTsReservedType,
+  tsSafeTypeName,
   serverVariables,
   hasServerVariables,
   liveStrict,

package/src/utility.ts

@@ -6,6 +6,7 @@ import { JostracaResult, each } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
 import { serverVariables } from './helpers/serverVars'
+import { packageVersion } from './helpers/packageMeta'
 
 
 // Where a per-target component is loaded from: `<project>/.sdk/dist/<path>`.
@@ -290,7 +291,7 @@ function rawStringLiteral(s: string): string {
 //
 // Key order is `each`'s order, which is sorted, so the JSON is byte-stable
 // across runs exactly like the literal it replaces.
-function configDefinition(model: any): { def: any, json: string } {
+function configDefinition(model: any, targetname?: string): { def: any, json: string } {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
@@ -330,8 +331,22 @@ function configDefinition(model: any): { def: any, json: string } {
   options.headers = headers
   options.entity = entityStubs
 
+  // Identity beyond the camel Name: the hyphenated slug is CARRIED, never
+  // derived from the camel form downstream (deriving swallows hyphens - the
+  // packageMeta envToken defect), and version/target let a running SDK say
+  // what it is. Station's descriptor (voxgig/station) reads all three.
+  // Gated on targetname so a target that does not pass its name emits the
+  // exact config it always has - each target opts in when its literal
+  // emitter learns the fields too, keeping data and literal reps in step.
+  const main: any = { name: model.const.Name }
+  if (null != targetname) {
+    main.slug = model.name
+    main.version = packageVersion(model, targetname)
+    main.target = targetname
+  }
+
   const def = {
-    main: { name: model.const.Name },
+    main,
     feature: featureDefs,
     options,
     entity: entityDefs,