@voxgig/sdkgen 4.5.3 → 4.6.0

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

@@ -0,0 +1,238 @@
+// VENDORED: @voxgig/omni 0.1.2 (typescript/src/Util.ts)
+// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// Omni internal JSON utilities.
+//
+// This module is deliberately self-contained: the omni runner must be able
+// to test *any* library, including libraries that provide these same
+// operations, so it can never borrow them from the system under test.
+// Zero third-party dependencies, by design.
+
+// A JSON value: null, boolean, number, string, list or map.
+export type Json = any
+
+const NULLMARK = '__NULL__' // Value is JSON null.
+const UNDEFMARK = '__UNDEF__' // Value is not present (thus, undefined).
+const EXISTSMARK = '__EXISTS__' // Value exists (not undefined).
+
+// A map (JSON object)?
+function ismap(val: Json): boolean {
+  return null != val && 'object' === typeof val && !Array.isArray(val)
+}
+
+// A list (JSON array)?
+function islist(val: Json): boolean {
+  return Array.isArray(val)
+}
+
+// A container (map or list)?
+function isnode(val: Json): boolean {
+  return ismap(val) || islist(val)
+}
+
+// Deep copy a JSON value. Non-JSON values (functions, class instances) are
+// passed through by reference - the runner only ever clones test data.
+function clone(val: Json): Json {
+  if (islist(val)) {
+    return val.map((entry: Json) => clone(entry))
+  }
+
+  if (ismap(val)) {
+    const out: Record<string, Json> = {}
+    for (const key of Object.keys(val)) {
+      out[key] = clone(val[key])
+    }
+    return out
+  }
+
+  return val
+}
+
+// Read a value from a nested structure by path. The path is a list of
+// string keys (map) or integer-like keys (list). Returns undefined when
+// any step is missing.
+function getpath(val: Json, path: (string | number)[]): Json {
+  let current = val
+
+  for (const part of path) {
+    if (islist(current)) {
+      const index = 'number' === typeof part ? part : parseInt(String(part), 10)
+      if (isNaN(index) || index < 0 || index >= current.length) {
+        return undefined
+      }
+      current = current[index]
+    } else if (ismap(current)) {
+      const key = String(part)
+      if (!Object.prototype.hasOwnProperty.call(current, key)) {
+        return undefined
+      }
+      current = current[key]
+    } else {
+      return undefined
+    }
+  }
+
+  return current
+}
+
+// Depth-first walk, applying `apply` to every node and leaf, children
+// first, then the containing node. `apply` may replace the value.
+function walk(
+  val: Json,
+  apply: (key: string | number | undefined, val: Json, parent: Json, path: (string | number)[]) => Json,
+  key?: string | number,
+  parent?: Json,
+  path?: (string | number)[],
+): Json {
+  const curpath = path || []
+
+  if (isnode(val)) {
+    if (islist(val)) {
+      for (let index = 0; index < val.length; index++) {
+        val[index] = walk(val[index], apply, index, val, [...curpath, index])
+      }
+    } else {
+      for (const childkey of Object.keys(val)) {
+        val[childkey] = walk(val[childkey], apply, childkey, val, [...curpath, childkey])
+      }
+    }
+  }
+
+  return apply(key, val, parent, curpath)
+}
+
+// Deep structural equality. Numbers compare by value (1 and 1.0 are the
+// same), booleans never equal numbers, map key order is not significant.
+function deepequal(a: Json, b: Json): boolean {
+  if (a === b) {
+    return true
+  }
+
+  if (null == a || null == b) {
+    // undefined and null are distinct: only both-absent compares equal.
+    return (undefined === a && undefined === b) || (null === a && null === b)
+  }
+
+  const atype = typeof a
+  const btype = typeof b
+
+  if ('number' === atype && 'number' === btype) {
+    return a === b || (isNaN(a) && isNaN(b))
+  }
+
+  if (atype !== btype) {
+    return false
+  }
+
+  if (islist(a) && islist(b)) {
+    if (a.length !== b.length) {
+      return false
+    }
+    for (let index = 0; index < a.length; index++) {
+      if (!deepequal(a[index], b[index])) {
+        return false
+      }
+    }
+    return true
+  }
+
+  if (ismap(a) && ismap(b)) {
+    const akeys = Object.keys(a)
+    const bkeys = Object.keys(b)
+    if (akeys.length !== bkeys.length) {
+      return false
+    }
+    for (const key of akeys) {
+      if (!Object.prototype.hasOwnProperty.call(b, key)) {
+        return false
+      }
+      if (!deepequal(a[key], b[key])) {
+        return false
+      }
+    }
+    return true
+  }
+
+  return false
+}
+
+// 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 {
+  if (undefined === val) {
+    return 'undefined'
+  }
+
+  if (null === val) {
+    return 'null'
+  }
+
+  if ('string' === typeof val) {
+    return JSON.stringify(val)
+  }
+
+  if ('number' === typeof val) {
+    return Number.isFinite(val) ? String(val) : 'null'
+  }
+
+  if ('boolean' === typeof val) {
+    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 (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(',') + '}'
+  }
+
+  if ('function' === typeof val) {
+    return '[Function' + (val.name ? ' ' + val.name : '') + ']'
+  }
+
+  return JSON.stringify(String(val))
+}
+
+// Human readable form of a value: strings are shown verbatim (so that
+// error-message matching is exact), everything else as compact JSON.
+function stringify(val: Json): string {
+  return 'string' === typeof val ? val : jsonstr(val)
+}
+
+// Render a path as a dotted string.
+function pathify(path: (string | number)[]): string {
+  return (path || []).map((part) => String(part)).join('.')
+}
+
+export {
+  NULLMARK,
+  UNDEFMARK,
+  EXISTSMARK,
+  clone,
+  deepequal,
+  getpath,
+  islist,
+  ismap,
+  isnode,
+  jsonstr,
+  pathify,
+  stringify,
+  walk,
+}

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

@@ -0,0 +1,188 @@
+// VENDORED: @voxgig/omni 0.1.2 (typescript/compat/struct.ts), import path adapted ('../src' -> './index').
+// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// 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`).
+//
+// struct's own runner and omni's runner implement the same spec format;
+// this module exposes omni behind struct's exact runner API, so a struct
+// port switches over by changing one import:
+//
+//   -import { makeRunner, nullModifier, NULLMARK } from './runner'
+//   +import { makeRunner, nullModifier, NULLMARK } from './omni'
+//
+// where `./omni` is a small resolver in the port's test directory that
+// locates a local omni checkout. Everything else - the corpus, the SDK,
+// the test file - is unchanged. This is the TypeScript peer of
+// javascript/compat/struct.js and python/voxgig_omni/compat/struct.py.
+
+import { dirname, isAbsolute, join, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { EXISTSMARK, NULLMARK, UNDEFMARK, makeRunner as omnimakerunner, nullmodifier } from './index'
+
+import type { Json, Provider, Subject } from './index'
+
+// struct's data model is JSON-shaped `any` at its boundaries, and so is
+// its SDK; these aliases say that on purpose rather than by omission.
+export type StructSDK = any
+export type StructUtility = any
+
+// struct's runner API, name for name.
+export type StructSubject = (...args: any[]) => any
+
+export type StructRunSet = (testspec: any, testsubject?: StructSubject) => Promise<void>
+
+export type StructRunSetFlags = (
+  testspec: any,
+  flags: Record<string, any>,
+  testsubject?: StructSubject,
+) => Promise<void>
+
+export type StructRunPack = {
+  spec: any
+  runset: StructRunSet
+  runsetflags: StructRunSetFlags
+  subject?: StructSubject
+  client: StructProvider
+}
+
+export type StructRunner = (name: string, store?: any) => Promise<StructRunPack>
+
+// An omni provider that is also a struct client: test code reaches through
+// the runpack's `client` as an SDK (`client.utility().struct`), so the
+// wrapper forwards `utility()` and `tester()` alongside the four hooks.
+export type StructProvider = Provider & {
+  utility: () => StructUtility
+  tester: (options?: any) => any
+  sdk: StructSDK
+}
+
+// The directory this shim was loaded from: dist/compat when built, compat
+// when run from source. Its parent is the port root, so every frame from
+// inside omni is skipped when locating the caller.
+//
+// It is derived from __dirname rather than matched against a known path,
+// so it holds wherever the package sits - a checkout, or
+// node_modules/@voxgig/omni. The trailing separator matters: without it a
+// sibling whose name merely EXTENDS this one (`omni-js-extra` beside
+// `omni-js`) would read as inside.
+const OMNIDIR = dirname(__dirname)
+
+// A relative test-file path is resolved against the first stack frame
+// outside omni - the caller.
+//
+// PREFER AN ABSOLUTE PATH. This heuristic guesses at what "relative to"
+// means, and the guess is wrong whenever a consumer's test FILES sit at a
+// different depth from the module that loads the runner. struct's TypeScript
+// port is exactly that shape: its loader compiles to `dist-test/` and its
+// test files to `dist-test/utility/`, so the same relative string resolved
+// one directory too deep and read `typescript/build/test/test.json`. That
+// port now resolves the path itself, in `test/omni.ts`, and never reaches
+// this. (An earlier version of this comment asserted it already did - it did
+// not; this shim shipped before any consumer had proved it.)
+// A stack frame's file, as a filesystem path.
+//
+// An ESM caller's frame reports a file:// URL rather than a path, and
+// `dirname('file:///a/b.mjs')` yields 'file:/a', so a relative spec path
+// resolved against it died on `ENOENT ... 'file:/.../fib.json'`. Frames
+// that name no path at all - node: internals, data: URLs, eval - are
+// skipped rather than mistaken for the caller.
+function framepath(frame: any): string | null {
+  const file = 'function' === typeof frame.getFileName ? frame.getFileName() : null
+  if (null == file) {
+    return null
+  }
+  if (file.startsWith('file://')) {
+    try {
+      return fileURLToPath(file)
+    } catch {
+      return null
+    }
+  }
+  return isAbsolute(file) ? file : null
+}
+
+function callerdir(): string {
+  const original = Error.prepareStackTrace
+  Error.prepareStackTrace = (_err, stack) => stack
+  const holder: any = {}
+  Error.captureStackTrace(holder, callerdir)
+  const stack: any = holder.stack
+  Error.prepareStackTrace = original
+
+  for (const frame of stack) {
+    const file = framepath(frame)
+    if (file && !file.startsWith(OMNIDIR + sep)) {
+      return dirname(file)
+    }
+  }
+
+  return process.cwd()
+}
+
+// Wrap a struct SDK client as an omni provider.
+function structprovider(sdk: StructSDK): StructProvider {
+  return {
+    // struct resolves a subject from the utility, or from utility.struct.
+    subject: (name: string): Subject | undefined => {
+      const utility = sdk.utility()
+      return utility[name] || (utility.struct && utility.struct[name])
+    },
+
+    // A DEF.client entry becomes another SDK instance.
+    client: async (options: Json) => structprovider(await sdk.tester(options)),
+
+    // struct's SDK supplies its own context wrapper.
+    contextify: (val: Json): Json => {
+      const utility = sdk.utility()
+      const hook =
+        'function' === typeof utility.contextify
+          ? utility.contextify
+          : 'function' === typeof utility.makeContext
+            ? utility.makeContext
+            : null
+      const ctx = null == hook ? val : hook.call(utility, val)
+      if (null != ctx && 'object' === typeof ctx) {
+        ;(ctx as any).utility = utility
+      }
+      return ctx
+    },
+
+    // Client options may reference the runner store.
+    inject: (options: Json, store: Json): Json => {
+      const structutils = sdk.utility().struct
+      if (structutils && 'function' === typeof structutils.inject) {
+        return structutils.inject(options, store)
+      }
+      return options
+    },
+
+    utility: () => sdk.utility(),
+    tester: (options?: any) => sdk.tester(options),
+    sdk,
+  }
+}
+
+// struct's makeRunner(testfile, client) signature, backed by omni.
+async function makeRunner(testfile: string, client: StructSDK): Promise<StructRunner> {
+  const specpath = isAbsolute(testfile) ? testfile : join(callerdir(), testfile)
+  const provider = structprovider(client)
+  const runner = await omnimakerunner(specpath, provider)
+
+  return async function structrunner(name: string, store?: any): Promise<StructRunPack> {
+    const runpack = await runner(name, store)
+
+    return {
+      spec: runpack.spec,
+      runset: runpack.runset,
+      runsetflags: runpack.runsetflags,
+      subject: runpack.subject,
+      client: provider,
+    }
+  }
+}
+
+const nullModifier = nullmodifier
+
+export { EXISTSMARK, NULLMARK, UNDEFMARK, makeRunner, nullModifier, structprovider }

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

@@ -0,0 +1,38 @@
+// VENDORED: @voxgig/omni 0.1.2 (typescript/src/index.ts)
+// Source: https://github.com/voxgig/omni @ bc9535d655564c0833f6eff003b0b13dad8b350f
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// @voxgig/omni - shared multi-language test runner.
+
+export {
+  CAPABILITIES,
+  EXISTSMARK,
+  NULLMARK,
+  OmniError,
+  SPECVERSION,
+  UNDEFMARK,
+  errify,
+  fixjson,
+  loadspec,
+  makeRunner,
+  match,
+  matchval,
+  nullmodifier,
+  resolvespec,
+} from './Runner'
+
+export type { Flags, Provider, RunPack, RunSet, RunSetFlags, Runner, Subject } from './Runner'
+
+export {
+  clone,
+  deepequal,
+  getpath,
+  islist,
+  ismap,
+  isnode,
+  jsonstr,
+  pathify,
+  stringify,
+  walk,
+} from './Util'
+
+export type { Json } from './Util'

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

@@ -318,8 +318,26 @@ pub fn make_options_util(ctx: *Context) Value {
         }
     }
 
+    // `auth: null` is the documented way to suppress auth outright, and
+    // prepare_auth honours it before it ever reads the apikey. It cannot
+    // survive validate: a stored null reads as "no value", so the optspec
+    // `auth` default fires and the suppression becomes "use the default auth"
+    // - transmitting the credential the caller withheld. Withhold the key for
+    // validate, then put the null back. Same fix as ts/js/go make_options.
+    //
+    // Value has no separate undefined variant (is_noval IS `== .null`), so
+    // getp cannot tell an absent key from a stored null. The raw MapRef.get
+    // optional can: a null OPTIONAL is absent, a `.null` payload is a stored
+    // JSON null.
+    const auth_suppressed = switch (options) {
+        .object => |m| if (m.get("auth")) |a| a == .null else false,
+        else => false,
+    };
+
     var opts = h.clone(options);
 
+    if (auth_suppressed) h.del_prop(opts, h.vstr("auth"));
+
     // Feature add-order. options.feature may be an ordered list of
     // { name, active, ...opts } entries (the list position IS the order in
     // which features are added), or a { name: {opts} } map. Normalize a list
@@ -396,6 +414,11 @@ pub fn make_options_util(ctx: *Context) Value {
         if (vr.err == null and vr.out == .object) opts = vr.out;
     }
 
+    // Restore the suppression the optspec default would otherwise erase. setp
+    // does a direct map put, so the explicit null is STORED, not treated as a
+    // delete.
+    if (auth_suppressed) h.setp(opts, "auth", h.vnull());
+
     // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
     // Every placeholder must resolve to a non-empty value: from options.server
     // (user), else the Config default. A placeholder that resolves to "" is a

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.5.3",
+  "version": "4.6.0",
   "provides": {
     "target": [
       "c",
@@ -48,6 +48,7 @@
       "ratelimit",
       "rbac",
       "retry",
+      "secrets",
       "streaming",
       "telemetry",
       "test",

package/src/action/check.ts

@@ -32,6 +32,7 @@
 // is the first finding and the rest of the battery still runs, because an
 // author who has not written it yet is precisely who needs the rest.
 
+import { unknownTags, TAGS } from '../helpers/applicability'
 import Path from 'node:path'
 
 import { KIT } from '../types'
@@ -326,6 +327,23 @@ function checkDefinition(
       err + '  (unified with the base schema — this is what a consumer compiles)'))
   }
 
+  // 5b. APPLICABILITY TAGS come from a CLOSED vocabulary (see
+  //     helpers/applicability). `provides: &: boolean` accepts any key, so
+  //     without this a typo — `sekrreto` for `sekreto` — compiles cleanly
+  //     and silently makes the feature apply to NO target at all. That is
+  //     the worst shape a mistake can take here: the feature simply
+  //     vanishes from every generated SDK with no diagnostic anywhere.
+  const tagkey = 'feature' === kind ? 'needs' : 'provides'
+  const unknown = null == declared ? [] : unknownTags((declared as any)[tagkey])
+
+  if (0 < unknown.length) {
+    found.push(at('error', 'model-tag-unknown',
+      'declares unknown applicability tag(s) in `' + tagkey + '`: ' +
+      unknown.join(', ') + ' — the vocabulary is CLOSED (' + TAGS.join(', ') +
+      '), so an unrecognised tag makes this ' + kind +
+      ' match nothing rather than failing loudly'))
+  }
+
   if ('target' === kind) {
     found.push(...checkTargetModel(src, name, file, at))
   }

package/src/cmp/AgentGuide.ts

@@ -31,7 +31,7 @@ const AgentGuide = cmp(function AgentGuide(props: any) {
   const title = target.title || lang
   const surface = langCmd(lang).note
 
-  const features = activeFeatures(model)
+  const features = activeFeatures(model, target)
   // go-cli/go-mcp disable the feature phase; ts/js lay features out as
   // per-feature directories, the other SDK targets as flat files.
   const featuresOn = featuresEnabled(target)

package/src/cmp/AgentGuideContent.ts

@@ -9,6 +9,8 @@
 // `.sdk/model/...`) — NOT the `project/.sdk/...` form used by the sdkgen repo's
 // own developer docs.
 
+import { featureApplies } from '../helpers/applicability'
+
 import { each } from 'jostraca'
 
 import {
@@ -114,9 +116,14 @@ function activeTargets(model: any): any[] {
   return each(target).filter((t: any) => t && t.active !== false)
 }
 
-function activeFeatures(model: any): any[] {
+// With a target, also drops features that do not APPLY to it — a guide
+// must not document a feature the target has no implementation for.
+// Without one (the repo-level guide) every active feature is listed.
+function activeFeatures(model: any, target?: any): any[] {
   const feature = getModelPath(model, `main.${KIT}.feature`) || {}
-  return each(feature).filter((f: any) => f && f.active !== false)
+  return each(feature)
+    .filter((f: any) => f && f.active !== false)
+    .filter((f: any) => null == target || featureApplies(f, target))
 }
 
 function activeEntities(model: any): any[] {

package/src/cmp/Feature.ts

@@ -2,11 +2,30 @@
 import { cmp, Copy, Folder } from 'jostraca'
 
 import { ensureStdrep } from '../helpers/stdrep'
+import { featureApplies, featureTags } from '../helpers/applicability'
 
 const Feature = cmp(function Feature(props: any) {
   const { target, feature, ctx$ } = props
   const { log } = ctx$
 
+  // A feature the target cannot take generates NOTHING for it — not the
+  // source, and (via targetFeatures in the Config/Main components) not the
+  // import or registry entry either. Copy would otherwise stat-fail on the
+  // missing template folder and abort the whole run, taking every other
+  // target with it. See helpers/applicability and docs/design/feature-tags.
+  if (!featureApplies(feature, target)) {
+    const provided = featureTags(target.provides)
+    const unmet = featureTags(feature.needs).filter((n) => !provided.includes(n))
+
+    log.info({
+      point: 'feature-not-applicable', target: target.name, feature: feature.name,
+      needs: feature.needs, provides: target.provides, unmet,
+      note: feature.name + ': target ' + target.name +
+        ' does not provide ' + unmet.join(', ')
+    })
+    return
+  }
+
   if (false !== target.srcfeature) {
     Folder({ name: 'src/feature/' + feature.name }, () => {
       // TODO: Copy should just warn if from not found

package/src/cmp/FeatureDocs.ts

@@ -1,3 +1,5 @@
+import { featureApplies } from '../helpers/applicability'
+
 import { each } from 'jostraca'
 
 import { KIT, getModelPath } from '../types'
@@ -46,11 +48,15 @@ function renderValue(v: any): string {
 
 // Every feature the model declares active, in a stable order, with its
 // options and their defaults.
-function featureDocs(model: any): FeatureDoc[] {
+// With a target, also drops features that do not APPLY to it: a target
+// README must not document a feature that target has no implementation
+// for. Without one (the repo-level README) every active feature is listed.
+function featureDocs(model: any, target?: any): FeatureDoc[] {
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
   return each(feature)
     .filter((f: any) => false !== f.active && 'base' !== f.name)
+    .filter((f: any) => null == target || featureApplies(f, target))
     .map((f: any) => {
       const opts = (f.config && f.config.options) || {}
       const options = Object.keys(opts).sort().map((k) => ({

package/src/cmp/ReadmeExplanation.ts

@@ -1,4 +1,6 @@
 
+import { targetFeatures } from '../helpers/applicability'
+
 import { cmp, each, names, Content } from 'jostraca'
 
 import {
@@ -222,7 +224,8 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated: this section describes a TARGET's features.
+  const feature = targetFeatures(model, target)
   const lang = LANGS[target.name] || DEFAULT_LANG
 
   // Pick a real example entity WITH a real op (prefer a read op) so the

package/src/cmp/ReadmeFeatures.ts

@@ -27,7 +27,7 @@ const ReadmeFeatures = cmp(function ReadmeFeatures(props: any) {
     return
   }
 
-  const features: FeatureDoc[] = featureDocs(model)
+  const features: FeatureDoc[] = featureDocs(model, target)
 
   if (0 === features.length) {
     return

package/src/cmp/ReadmeRefFeatures.ts

@@ -19,7 +19,7 @@ const ReadmeRefFeatures = cmp(function ReadmeRefFeatures(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  const features: FeatureDoc[] = featureDocs(model)
+  const features: FeatureDoc[] = featureDocs(model, target)
 
   if (0 === features.length) {
     return