@voxgig/sdkgen 4.6.0 → 4.7.0

package/project/.sdk/tm/ts/test/vendor/omni/Runner.ts

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni 0.1.2 (typescript/src/Runner.ts)
-// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// Source: https://github.com/voxgig/omni @ 5956cc4e5ecdaeebd11eab8bb4b9462dfc76e018
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Omni: the shared multi-language test runner.
 //
@@ -352,20 +352,22 @@ function fixjsonval(val: Json, donull: boolean): Json {
 }
 
 // The JSON form of an error: always at least {name,message}.
-// PATCH (solardemo prototype, pending upstream fix), here and in
-// errmessage below: handle error-shaped MAPS. The shared corpus throws
-// plain objects in some ports (this SDK's makeError rethrows the
-// fixture's ctrl.err verbatim), and the struct repos' original runner
-// matched err.message regardless of the thrown value's class. Upstream
-// collapses any non-Error to String(err) — '[object Object]' — which
-// fails both the err check and every match.err.* leaf.
+//
+// A thrown value need not be an Error. Ports commonly rethrow an
+// error-SHAPED map ({name, message, ...}) - voxgig/sdkgen's generated
+// makeError rethrows the fixture's own error object verbatim - and
+// collapsing that to String(err) yields '[object Object]', which fails both
+// the `err` check and every `match.err.*` leaf. The struct repository's
+// original runner read `.message` regardless of the thrown value's class.
 function errify(err: any): Json {
   if (err instanceof Error) {
     return { ...err, name: err.name, message: err.message }
   }
+
   if (null != err && 'object' === typeof err) {
     return { name: 'Error', ...err }
   }
+
   return { name: 'Error', message: String(err) }
 }
 
@@ -481,11 +483,11 @@ function handleerror(flags: Flags, index: number, entry: Json, err: any) {
 
 // Check that every leaf of `check` is present, and matches, in `base`.
 function match(flags: Flags, index: number, entry: Json, check: Json, base: Json) {
-  // PATCH (solardemo prototype, pending upstream fix): read the base
-  // directly instead of cloning it. The clone gained nothing (the walk
-  // below only READS via getpath) and blew the stack on cyclic bases —
-  // which every corpus ctx entry produces, because a live Context reaches
-  // its client and the client's root context reaches the client again.
+  // Read the base DIRECTLY. The clone bought nothing - the walk below only
+  // reads, via getpath - and it blows the stack on a cyclic base. A port
+  // that drives entries with live objects rather than pure JSON produces
+  // those routinely: voxgig/sdkgen's corpus matches against a live client
+  // context whose root context reaches the client again.
   const cbase = base
 
   const at = (path: Json[]) => (0 === path.length ? '<root>' : pathify(path))

package/project/.sdk/tm/ts/test/vendor/omni/Util.ts

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni 0.1.2 (typescript/src/Util.ts)
-// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// Source: https://github.com/voxgig/omni @ 5956cc4e5ecdaeebd11eab8bb4b9462dfc76e018
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Omni internal JSON utilities.
 //
@@ -158,12 +158,17 @@ function deepequal(a: Json, b: Json): boolean {
 
 // Compact JSON text with map keys sorted, so that messages are identical
 // in every port regardless of local map ordering.
-// PATCH (solardemo prototype, pending upstream fix): cycle guard. The
-// corpus drives LIVE Context objects through entries (entry.ctx, and the
-// entry bookkeeping fail() prints with jsonstr), and a live ctx is cyclic
-// (sdk._rootctx.client === sdk). Upstream jsonstr recursed forever; the
-// struct repos' original runner emitted '[Circular]', restored here.
-function jsonstr(val: Json, seen?: WeakSet<object>): string {
+//
+// CYCLE SAFE. Building a FAILURE MESSAGE must never be the thing that
+// crashes: a port driving entries with live objects rather than pure JSON
+// can carry a cyclic value in the entry bookkeeping fail() prints, and this
+// recursed until the stack gave out. A cycle renders as "[Circular]", as
+// the struct repository's original runner did.
+//
+// `seen` tracks the ANCESTORS of the current value, not every value
+// visited: it is removed again on the way out, so the same object appearing
+// twice as siblings - a DAG, not a cycle - still renders in full.
+function jsonstr(val: Json, seen?: Set<any>): string {
   if (undefined === val) {
     return 'undefined'
   }
@@ -184,23 +189,24 @@ function jsonstr(val: Json, seen?: WeakSet<object>): string {
     return val ? 'true' : 'false'
   }
 
-  if (islist(val)) {
-    seen = seen || new WeakSet()
-    if (seen.has(val)) {
-      return '"[Circular]"'
-    }
-    seen.add(val)
-    return '[' + val.map((entry: Json) => jsonstr(entry, seen)).join(',') + ']'
-  }
+  if (islist(val) || ismap(val)) {
+    seen = seen || new Set()
 
-  if (ismap(val)) {
-    seen = seen || new WeakSet()
     if (seen.has(val)) {
       return '"[Circular]"'
     }
+
     seen.add(val)
-    const keys = Object.keys(val).sort()
-    return '{' + keys.map((key) => JSON.stringify(key) + ':' + jsonstr(val[key], seen)).join(',') + '}'
+
+    const out = islist(val)
+      ? '[' + val.map((entry: Json) => jsonstr(entry, seen)).join(',') + ']'
+      : '{' + Object.keys(val).sort()
+        .map((key) => JSON.stringify(key) + ':' + jsonstr((val as any)[key], seen))
+        .join(',') + '}'
+
+    seen.delete(val)
+
+    return out
   }
 
   if ('function' === typeof val) {

package/project/.sdk/tm/ts/test/vendor/omni/compat.ts

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni 0.1.2 (typescript/compat/struct.ts), import path adapted ('../src' -> './index').
-// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// Source: https://github.com/voxgig/omni @ 5956cc4e5ecdaeebd11eab8bb4b9462dfc76e018
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Drop-in replacement for the in-situ test runner in the voxgig/struct
 // repository (`typescript/test/runner.ts`).

package/project/.sdk/tm/ts/test/vendor/omni/index.ts

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni 0.1.2 (typescript/src/index.ts)
-// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// Source: https://github.com/voxgig/omni @ 5956cc4e5ecdaeebd11eab8bb4b9462dfc76e018
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // @voxgig/omni - shared multi-language test runner.
 

package/project/.sdk/tm/zig/core/utility.zig

@@ -372,7 +372,7 @@ pub fn make_options_util(ctx: *Context) Value {
         .{ "base", h.vstr("http://localhost:8000") },
         .{ "prefix", h.vstr("") },
         .{ "suffix", h.vstr("") },
-        .{ "auth", h.jo(&.{.{ "prefix", h.vstr("") }}) },
+        .{ "auth", h.jo(&.{ .{ "prefix", h.vstr("") }, .{ "basic", h.vbool(false) } }) },
         .{ "headers", h.jo(&.{.{ "`$CHILD`", h.vstr("`$STRING`") }}) },
         .{ "allow", h.jo(&.{
             .{ "method", h.vstr("GET,PUT,POST,PATCH,DELETE,OPTIONS") },

package/project/sdkgen-package.json

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

package/src/cmp/Feature.ts

@@ -3,6 +3,7 @@ import { cmp, Copy, Folder } from 'jostraca'
 
 import { ensureStdrep } from '../helpers/stdrep'
 import { featureApplies, featureTags } from '../helpers/applicability'
+import { pluginExcludesFor } from '../helpers/featureSource'
 
 const Feature = cmp(function Feature(props: any) {
   const { target, feature, ctx$ } = props
@@ -31,6 +32,10 @@ const Feature = cmp(function Feature(props: any) {
       // TODO: Copy should just warn if from not found
       Copy({
         from: 'tm/' + target.name + '/src/feature/' + feature.name,
+        // An ACTIVE feature's INACTIVE plugins do not come with it. This
+        // is the copy that decides it: Main's exclude never sees these
+        // files, because this Copy has already written them.
+        exclude: pluginExcludesFor(ctx$.model, feature.name),
         replace: {
           // Feature templates reference the SDK class by placeholder — e.g.
           // tm/ts/.../TestFeature.ts imports `ProjectNameSDK`. Without the

package/src/cmp/TestControl.ts

@@ -0,0 +1,64 @@
+import Path from 'node:path'
+
+import {
+  cmp,
+  File,
+  Fragment,
+} from 'jostraca'
+
+
+const TEST_CONTROL_FILE = 'sdk-test-control.json'
+
+
+// Keep the blanket per-target `Copy({ from: 'tm/<lang>' })` from restoring the
+// template default over a project's edited control file. One regex for every
+// target: the file sits under `test/`, `t/`, `tests/` or `sdktest/` depending
+// on the language, and the name is what identifies it either way.
+const TEST_CONTROL_EXCLUDE = new RegExp('(^|/)' + TEST_CONTROL_FILE + '$')
+
+
+// `sdk-test-control.json` is the ONE generated file a project is meant to edit
+// by hand: it names the tests to skip, the live pacing, and the extra client
+// options a live run needs (`test.client.options`).
+//
+// It shipped as part of each target's blanket `Copy({ from: 'tm/<lang>' })`,
+// and a Copy has no per-file "leave it alone if it already exists" — so every
+// `npm run generate` overwrote whatever the project had put there. The
+// documented workaround, editing the template master under `.sdk/tm/`, is
+// worse: `doctor` reports it as drift and the next `target add <lang>` reverts
+// it.
+//
+// So it is emitted HERE instead, write-once: `File({ exclude: true })` returns
+// early when the file already exists (FileOp), which is exactly the semantics
+// the file is documented to have. A project without one yet gets the
+// template's default; a project that has edited one keeps its edits across
+// both `generate` and `target add`.
+//
+// The content still comes from the target's own template, so there remains
+// exactly one copy of the default on disk.
+//
+// The template is addressed the SAME way the Copy this replaces addressed it:
+// `tm/<lang>/...` relative to the working directory, which is the project's
+// `.sdk`. Resolved to absolute here because Fragment resolves a RELATIVE
+// `from` against the OUTPUT folder instead — a different base, and the one
+// place these two could silently disagree.
+const TestControl = cmp(function TestControl(props: {
+  target: { name: string }
+  dir: string
+  ctx$?: any
+}) {
+  const { target, dir } = props
+
+  File({ name: TEST_CONTROL_FILE, exclude: true }, () => {
+    Fragment({
+      from: Path.resolve('tm', target.name, dir, TEST_CONTROL_FILE)
+    })
+  })
+})
+
+
+export {
+  TestControl,
+  TEST_CONTROL_FILE,
+  TEST_CONTROL_EXCLUDE,
+}

package/src/helpers/featureSource.ts

@@ -260,6 +260,134 @@ function srcFeatureExcludes(model: any): RegExp[] {
 }
 
 
+// The same rule as srcFeatureExcludes, ONE LEVEL DEEPER: a feature's
+// declared-but-inactive PLUGINS.
+//
+// A plugin is a feature's optional part — the `secrets` feature over
+// sekreto has one per provider kind, and each carries its own platform
+// cost (node:crypto for AWS request signing, fetch for seven HTTP vault
+// clients). A project whose chain is `[dotenv, env]` should carry neither,
+// and before the plugin trim it carried both, because every kind was
+// reachable from a single import.
+//
+// Layout is `src/feature/<feature>/plugin/<plugin>/`, so a plugin's tree
+// is excluded exactly as a feature's is. Only declared-but-inactive
+// plugins are excluded: a directory the model never mentions is left
+// alone, matching srcFeatureExcludes' treatment of `base`.
+//
+// Note this trims a plugin belonging to an ACTIVE feature. An inactive
+// feature's whole tree — plugins included — is already gone via
+// srcFeatureExcludes, so walking its plugins here would be redundant, and
+// asking the model for them would fail on the `only_active` filter anyway.
+// One feature's inactive-plugin patterns.
+//
+// Separate from pluginExcludes(model) because the two COPIES that need it
+// see different things: Main copies the whole target tree and has the
+// model, while the Feature component copies one feature's tree and has
+// only that feature. Feature's copy is the one that actually matters —
+// it runs for every ACTIVE feature, so without this an active feature's
+// plugins were all copied regardless, and Main's exclude never saw them.
+function pluginExcludesFor(model: any, fname: string): RegExp[] {
+  if (null == model || null == fname) {
+    return []
+  }
+
+  // `only_active: false`, and this is the whole subtlety. The feature
+  // object a component is handed has ALREADY been filtered, so its
+  // `plugin` map contains only the ACTIVE plugins — and a function looking
+  // there for something inactive finds nothing and excludes nothing. That
+  // is exactly the trap srcFeatureExcludes documents, hit again one level
+  // down: the first cut of this read the filtered feature and silently
+  // trimmed nothing while every test passed.
+  const plugins = getModelPath(model,
+    `main.${KIT}.feature.${fname}.plugin`,
+    { required: false, only_active: false }) || {}
+
+  const out: RegExp[] = []
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  for (const pname of Object.keys(plugins).sort()) {
+    const plugin = plugins[pname]
+    if (false !== plugin?.active) continue
+
+    const declared = plugin.path || []
+
+    if (0 < declared.length) {
+      for (const one of declared) {
+        // FEATURE-RELATIVE, because jostraca tests a Copy's candidates
+        // against the path RELATIVE TO THAT COPY'S ROOT — `sekreto/
+        // provider/aws.ts`, not `src/feature/secrets/sekreto/provider/
+        // aws.ts`. The Feature component's Copy is rooted at
+        // `tm/<target>/src/feature/<feature>`, so a full declared path
+        // never matches and the trim silently does nothing.
+        //
+        // Worth stating because it is invisible: an exclude that matches
+        // nothing is indistinguishable from no exclude at all, and both
+        // the patterns and the model were correct while nothing was
+        // trimmed. Main's copy IS rooted at the target root, which is why
+        // pluginExcludes below keeps the full path.
+        const rel = String(one).replace(
+          new RegExp('^src/feature/' + esc(fname) + '/'), '')
+        const pat = esc(rel)
+        out.push(new RegExp('(^|/)' + pat.replace(/\\\/$/, '') +
+          (/\/$/.test(rel) ? '/' : '$')))
+      }
+      continue
+    }
+
+    out.push(new RegExp('(^|/)plugin/' + esc(pname) + '/'))
+  }
+
+  return out
+}
+
+
+function pluginExcludes(model: any): RegExp[] {
+  const active = getModelPath(model, `main.${KIT}.feature`,
+    { required: false }) || {}
+
+  const out: RegExp[] = []
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  for (const fname of Object.keys(active)) {
+    const all = getModelPath(model,
+      `main.${KIT}.feature.${fname}.plugin`,
+      { required: false, only_active: false }) || {}
+    const on = getModelPath(model,
+      `main.${KIT}.feature.${fname}.plugin`,
+      { required: false }) || {}
+
+    for (const pname of Object.keys(all)) {
+      if (null != on[pname]) continue
+
+      // DECLARED paths first. A plugin's files are often not free to
+      // move — sekreto's provider modules are vendored, and both the
+      // vendoring guard and their own relative imports pin them at
+      // upstream's directory depth — so a plugin says which paths it
+      // owns rather than being assumed to own a directory.
+      const declared = all[pname].path || []
+
+      if (0 < declared.length) {
+        for (const one of declared) {
+          const pat = esc(String(one))
+          // A trailing slash means a folder and everything under it;
+          // anything else matches that path exactly, as featureExcludes
+          // does for a file source.
+          out.push(new RegExp('(^|/)' + pat.replace(/\\\/$/, '') +
+            (/\/$/.test(String(one)) ? '/' : '$')))
+        }
+        continue
+      }
+
+      out.push(new RegExp(
+        '(^|/)src/feature/' + esc(fname) + '/plugin/' + esc(pname) + '/'))
+    }
+  }
+
+  return out
+}
+
+
 export type {
   FeatureSource,
   FeatureEntry,
@@ -275,4 +403,6 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
 }

package/src/sdkgen.ts

@@ -40,6 +40,7 @@ import { License } from './cmp/License'
 import { Security } from './cmp/Security'
 import { Changelog } from './cmp/Changelog'
 import { Test } from './cmp/Test'
+import { TestControl, TEST_CONTROL_EXCLUDE } from './cmp/TestControl'
 import { ReadmeInstall } from './cmp/ReadmeInstall'
 import { ReadmeQuick } from './cmp/ReadmeQuick'
 import { ReadmeErrors } from './cmp/ReadmeErrors'
@@ -73,6 +74,8 @@ import {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
 } from './helpers/featureSource'
 import type { FeatureSource } from './helpers/featureSource'
 import { stationLibrary } from './helpers/station'
@@ -1072,6 +1075,8 @@ export {
   Entity,
   Feature,
   Test,
+  TestControl,
+  TEST_CONTROL_EXCLUDE,
   Readme,
   ReadmeTop,
   AgentGuideTop,
@@ -1167,6 +1172,8 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
   stationLibrary,
 
   featureApplies,

package/src/utility.ts

@@ -82,6 +82,34 @@ function isHttpBasicAuth(model: any): boolean {
 }
 
 
+// The API's ACCESS-TOKEN EXCHANGE, as apidef recorded it from the spec
+// (main.kit.info.security.exchange): where the token endpoint lives, and the
+// field names it sends and answers with. Null when the spec describes none,
+// which is the common case.
+//
+// These are FACTS ABOUT THE API, so they belong in the generated config
+// rather than in a project's hand-written model: an SDK whose spec says the
+// exchange is at `auth/token` should not need to be told so again. A feature
+// opts in to receiving them with `spec: { authexchange: '<options-key>' }`;
+// configDefinition does the overlay.
+//
+// Deliberately NOT included: `active`. Whether a client performs the
+// exchange is the project's decision (some resolve a static credential
+// through the same feature on an API that also has a token endpoint), so
+// apidef records only what the exchange IS, never that it should run.
+function resolveAuthExchange(model: any): Record<string, any> | null {
+  const security = getModelPath(model, `main.${KIT}.info.security`,
+    { only_active: false, required: false })
+
+  const exchange = security?.exchange
+  if (null == exchange || 'object' !== typeof exchange) {
+    return null
+  }
+
+  return exchange
+}
+
+
 function requirePath(ctx$: any, path: string, flags?: { ignore?: boolean }): any {
   const fullpath = resolvePath(ctx$, path)
   const ignore = null == flags?.ignore ? false : flags.ignore
@@ -118,6 +146,7 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  resolveAuthExchange,
   isHttpBasicAuth,
   SdkGenError,
   CONFIG_DATA_THRESHOLD,
@@ -301,6 +330,15 @@ function rawStringLiteral(s: string): string {
 }
 
 
+// The closed vocabulary of spec-derived facts a feature may ask for by
+// declaring `spec: { <fact>: <options-key> }`. Closed, and resolved through
+// one function each, so a feature cannot reach arbitrarily into the model
+// and a fact's shape is defined in exactly one place.
+const SPEC_FACTS: Record<string, (model: any) => any> = {
+  authexchange: resolveAuthExchange,
+}
+
+
 // THE CANONICAL CONFIG OBJECT, and the JSON the threshold is measured on.
 //
 // Every target builds its config from this one function, so the literal a
@@ -361,6 +399,29 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
     if (null != f.transport && '' !== f.transport) {
       fdef.transport = String(f.transport)
     }
+
+    // SPEC-DERIVED OPTIONS. A feature declares `spec: { <fact>: <options
+    // key> }` to receive facts apidef recorded from the OpenAPI spec — the
+    // same declare-never-infer rule `needs` and `transport` follow, and for
+    // the same reason: the alternative is this function knowing feature
+    // names, which is exactly the coupling the generic feature loop exists
+    // to avoid.
+    //
+    // The fact overlays the feature's DECLARED DEFAULTS, and rightly: a
+    // default like `path: 'auth/token'` is a generic guess, while the spec
+    // states where this API's endpoint actually is. A project that needs
+    // something else still overrides at runtime through `options.feature`,
+    // which beats the embedded config either way.
+    for (const factname of Object.keys(f.spec || {}).sort()) {
+      const optkey = f.spec[factname]
+      const fact = SPEC_FACTS[factname]?.(model)
+      if (null == fact || null == optkey || '' === optkey) {
+        continue
+      }
+      fdef.options = { ...(fdef.options || {}) }
+      fdef.options[optkey] = { ...(fdef.options[optkey] || {}), ...fact }
+    }
+
     featureDefs[f.name] = fdef
   })