@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -35,21 +35,6 @@ import {
 } from './utility_lua'
 
 
-// PLUGIN DEFINITION REQUIRES AND THE FEATURE PLUGINS TABLE (the lua peer
-// of cmp/py/Config_py.ts's pluginImports/pluginDefs).
-//
-// Upstream sekreto replaced its self-registration registry with
-// voxgig/plugin definitions: a provider kind the caller did not pass in via
-// `plugins = { ... }` is unknown to that Sekreto. So the generated
-// config_plugins module requires each active plugin's module and names the
-// FIELD it exports (the model's `def.lua` map - `hashicorp` on
-// plugins/hashicorp.lua, `awssecrets` AND `awsparams` on plugins/aws.lua),
-// handing the list to the feature.
-//
-// A def value is the module's path under tm/lua, this target's root; the
-// require is that path with `.lua` stripped and slashes turned to dots,
-// resolved by the plain `?.lua` searcher every generated lua SDK relies on.
-// One `local` per module, so a two-definition module is required once.
 function pluginRequires(feature: any): { locals: string[], defs: Record<string, string[]> } {
   const bypath: Record<string, { local: string, syms: string[] }> = {}
   const defs: Record<string, string[]> = {}
@@ -94,36 +79,22 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
   const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see make_options).
   const svars = serverVariables(model)
   const serverBlock = 0 === svars.length ? '' :
     '      server = {\n' +
     svars.map((v: any) => `        [${JSON.stringify(v.name)}] = ${JSON.stringify(v.dflt)},\n`).join('') +
     '      },\n'
 
-  // WHERE the credential goes and UNDER WHAT NAME. apidef resolved both
-  // from the spec's securityScheme all along and generation dropped them,
-  // so an apiKey-in-query API got an authorization header it does not read.
-  // Emitted only when they differ from the defaults, so a
-  // header/Authorization SDK is byte-identical to what it generated before.
-  //
-  // `in` is a RESERVED WORD in lua, so the key is bracketed - a bare
-  // `in = "query"` does not parse.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   const authBlock = authActive
@@ -134,13 +105,6 @@ const Config = cmp(async function Config(props: any) {
       },\n`
     : ''
 
-  // 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 the
-  // target name opts this target into the main slug/version/target identity
-  // fields (station descriptor v1 reads all three) - the literal branch
-  // below emits them too, so the two representations cannot diverge.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -150,18 +114,6 @@ const Config = cmp(async function Config(props: any) {
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // A table constructor makes the Lua parser emit a SETTABLE per entry and
-    // the VM run them all on every load; a long-bracket string is one token,
-    // and dkjson's decoder builds the table from it.
-    //
-    // dkjson is already a runtime dependency - `utility/fetcher.lua` decodes
-    // every HTTP response with it - so this adds nothing to the SDK.
-    //
-    // Null handling agrees between the branches by construction: dkjson maps
-    // JSON null to nil, and assigning nil to a table key removes it, which is
-    // exactly what the literal branch does when `formatLuaTable` emits `nil`.
     if (asData) {
       Content(`local json = require("dkjson")
 
@@ -253,14 +205,6 @@ return make_config
 `)
   })
 
-  // The plugin definitions the model selected per feature, as a module of
-  // the config family. ALWAYS emitted, even with nothing declared: the
-  // secrets feature requires it (a missing module and a broken one must
-  // read differently there), and a feature source arrives in the tree by
-  // Main's blanket copy whether or not the model declares the feature.
-  //
-  // A sibling module rather than a member of `config`, for the reason
-  // config_shared is: `config` returns a bare function.
   const plugins = pluginRequires(feature)
 
   File({ name: 'config_plugins.' + target.ext }, () => {

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

@@ -1,20 +1,5 @@
 
 
-// Typed-model generator (Lua target).
-//
-// Lua is dynamically typed, so the "types" are LuaLS annotations
-// (---@class / ---@field) for editor/tooling DX only — no runtime effect.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, <sdk>_types.lua,
-// with a `---@class <Name>` per active entity plus a request/match ---@class
-// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned
-// into LuaLS types by the shared sdkgen helper `canonToType` ('lua' column).
-//
-// Keeps the SAME type-name scheme as the TS reference (<Name>,
-// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
-// <Name>RemoveMatch). The op fragments reference these class names via
-// ---@param / ---@return.
 
 import {
   cmp, each, names,
@@ -32,8 +17,6 @@ import {
 const LANG = 'lua'
 
 
-// A bare LuaLS field key, or a bracketed string literal for anything that is
-// not a plain Lua identifier.
 function propKey(name: string): string {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : '[' + JSON.stringify(name) + ']'
 }
@@ -43,10 +26,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const { target } = props
   const { model, log } = props.ctx$
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // collection, so inactive entities still get generated entity code that
-  // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
   // Emit for EVERY entity that gets generated entity code: the consumer
   // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
@@ -58,9 +37,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   File({ name: model.name + '_types.' + (target.ext || LANG) }, () => {
@@ -80,7 +56,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.active !== false)
 
-      // Entity data model: one ---@field per field, `req:false` -> optional (?).
       Content(`---@class ${Name}
 `)
       fields.forEach((f: any) => {
@@ -91,9 +66,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       Content(`
 `)
 
-      // Per active op: a request/match class. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as LuaLS ---@field lines.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
@@ -115,8 +87,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       })
     })
 
-    // Make the file a require-able (empty) module. The blank line above keeps
-    // LuaLS from binding the last ---@class to this local.
     Content(`local M = {}
 
 return M

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

@@ -35,7 +35,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/lua/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -58,14 +57,8 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.lua so the class can be renamed independently.
           EntyClass: cls,
 
-          // Feature-hook wiring: the built-in `#Name-Hook` tag replacement
-          // is hardwired to `//` line comments, so Lua's `-- #PrePoint-Hook`
-          // markers were never matched and no pipeline hooks fired in
-          // generated code. Match the Lua-comment hook tags explicitly.
           '/(?<indent>[ \\t]*)-- #(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
             ({ name, indent }: any) =>
               `${indent}utility.feature_hook(ctx, "${name}")\n`,

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

@@ -22,21 +22,13 @@ import {
 
 import { Package } from './Package_lua'
 import { Config } from './Config_lua'
+import { Schema } from './Schema_lua'
 import { PrepareAuth } from './PrepareAuth_lua'
 import { Gitignore } from './Gitignore_lua'
 import { MainEntity } from './MainEntity_lua'
 import { EntityTypes } from './EntityTypes_lua'
 
 
-// Features whose source is a CONTAINER under the top-level feature/ dir,
-// beside the flat `<name>_feature.lua` every other lua feature is. Today
-// that is `secrets`: its folder holds a vendored @voxgig/sekreto port, the
-// voxgig/plugin runtime and the C transport helper - some forty files of
-// key-store, request-signing and child-process code that an SDK which never
-// asked for secrets must not ship. Anything named here is EXCLUDED from the
-// verbatim copy unless the model SELECTS the feature (see the Copy below);
-// its shipped test suite under test/feature/<name>/ goes with it. The
-// clojure target gates its container the same way (Main_clojure.ts).
 const CONTAINED = ['secrets']
 
 
@@ -55,12 +47,6 @@ const Main = cmp(async function Main(props: any) {
 
   Gitignore({})
 
-  // THE feature/<name>/ CONTAINER IS GATED HERE, at generate time - the
-  // top-level-container peer of the `srcFeatureExcludes` gate ts and js
-  // apply to src/feature/<name>/. `target add` keeps an unselected
-  // feature out of a project's tm/ in the first place; this covers a
-  // feature switched off after it was added, and the generator suite,
-  // which copies the whole scaffold tree.
   const containerExcludes = CONTAINED
     .filter((name: string) => null == feature[name])
     .flatMap((name: string) => [
@@ -69,13 +55,6 @@ const Main = cmp(async function Main(props: any) {
       new RegExp('(^|/)test/feature/' + name + '/'),
     ])
 
-  // Copy tm/lua files with replacements.
-  //
-  // pluginExcludes: the generate-time plugin trim (an ACTIVE feature's
-  // INACTIVE plugin group's declared files stay out of the tree). The
-  // model's lua `path` entries are target-root-relative, which is this
-  // Copy's root - helpers/featureSource documents that getting the root
-  // wrong makes the trim a silent no-op.
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, TEST_CONTROL_EXCLUDE,
@@ -85,64 +64,75 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // THE NATIVE BUILD SEAM. sekreto's lua PLUGIN kinds (hashicorp, aws, ...)
-  // run a small compiled transport helper, because Lua 5.4 has no sockets
-  // and no TLS; the four built-in kinds never reach it. The helper's
-  // source is vendored with the feature (feature/secrets/native/
-  // sekretonet.c) and the template Makefile `-include`s this fragment, so
-  // it is compiled - and OpenSSL linked - ONLY when the model activates a
-  // plugin group that lua has definitions for. An SDK without secrets, or
-  // with the built-in chain alone, gets no fragment, no compiler run and
-  // no OpenSSL dependency.
-  //
-  // The vendored file opens with the vendoring tool's three-line `--`
-  // provenance header (every file under tm/lua is stamped in lua's comment
-  // syntax; the guard holds that), which the C compiler cannot read - so
-  // the rule feeds the compiler from line four. Line numbers in a compiler
-  // diagnostic are therefore three lower than in the file.
   const nativeGroups: string[] = []
+  let wantsVault = false
   each(feature, (f: any) => {
     each(f.plugin, (plugin: any) => {
       if (false === plugin.active || null == plugin.active) return
       if (0 < Object.keys(plugin.def?.lua || {}).length) {
         nativeGroups.push(f.name + '.' + plugin.name)
+        if ('minivault' === plugin.name) {
+          wantsVault = true
+        }
       }
     })
   })
 
+  // The transport helper serves every kind that reaches the network or a
+  // child process. The vault reaches neither, so a vault-only chain needs
+  // the module and not the program.
+  const wantsNet = nativeGroups.some((one) => !/\.minivault$/.test(one))
+
   if (0 < nativeGroups.length) {
     Folder({ name: 'feature' }, () => {
       Folder({ name: 'secrets' }, () => {
         File({ name: 'native.mk' }, () => {
-          Content(`# ${model.const.Name} SDK: the sekreto transport helper build.
+          Content(`# ${model.const.Name} SDK: the sekreto native helper build.
 #
 # GENERATED because a secrets plugin group is active
-# (${nativeGroups.sort().join(', ')}): the plugin provider kinds run this
-# helper for every socket and child process, since Lua 5.4 has none. An
-# SDK without an active plugin group has no such file, and its Makefile's
-# optional include of it is a no-op - nothing is compiled and OpenSSL is
-# not linked.
+# (${nativeGroups.sort().join(', ')}). Lua 5.4 has no sockets, no TLS and no
+# cryptography, so the kinds that need any of the three reach a small
+# compiled helper - and this file builds only the ones this SDK's chain
+# actually uses. An SDK without an active plugin group has no such file,
+# and its Makefile's optional include of it is a no-op: nothing is
+# compiled and nothing is linked.
 #
 # The source carries the vendoring tool's three-line provenance header in
 # lua comment syntax, which the compiler cannot read: it is fed the file
 # from line four. Compiler line numbers are therefore three lower than the
 # file's.
-NATIVE := feature/secrets/native/sekreto-net
+NATIVE := ${[
+            wantsNet ? 'feature/secrets/native/sekreto-net' : '',
+            wantsVault ? 'feature/secrets/native/sekretovault.so' : '',
+          ].filter((one) => '' !== one).join(' ')}
 
 CC ?= cc
 CFLAGS ?= -std=c11 -O2 -Wall -Wextra
 LDLIBS ?= -lssl -lcrypto
-
+${wantsNet ? `
 feature/secrets/native/sekreto-net: feature/secrets/native/sekretonet.c
 	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the sekreto transport helper that this SDK's plugin provider kinds run - install one, or use only the built-in provider kinds" >&2; exit 1; }
 	tail -n +4 $< | $(CC) $(CFLAGS) -x c - -o $@ $(LDLIBS)
-`)
+` : ''}${wantsVault ? `
+# The mini vault's crypto is a LOADABLE MODULE, not a program: minivault.lua
+# opens it with package.loadlib and calls luaopen_sekretovault, so it is
+# compiled -shared -fPIC and keeps the .so name that call expects. It links
+# libcrypto alone - the vault reads a file and never opens a socket, so it
+# needs no TLS.
+#
+# LUA_CFLAGS is where a consumer points the compiler at lua.h when it is not
+# on the default include path (Homebrew, a pkg-config build, a vendored Lua).
+LUA_CFLAGS ?= $(shell pkg-config --cflags lua5.4 2>/dev/null || pkg-config --cflags lua 2>/dev/null)
+
+feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.c
+	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the mini vault's crypto module - install one, or use only the built-in provider kinds" >&2; exit 1; }
+	tail -n +4 $< | $(CC) $(CFLAGS) $(LUA_CFLAGS) -fPIC -shared -x c - -o $@ -lcrypto
+` : ''}`)
         })
       })
     })
   }
 
-  // Generate main SDK file
   File({ name: model.name + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -154,15 +144,12 @@ feature/secrets/native/sekreto-net: feature/secrets/native/sekretonet.c
           // Load the LuaLS typed-model annotations module so it is part of
           // the loaded program (module body is empty — no runtime effect) and
           // does not depend on workspace-wide language-server scanning.
-          // NOTE: plain marker keys must EMBED the lua comment prefix
           // (`-- #X`) — jostraca's bare `#X` form only matches `//`-style
           // comment lines (cf. the `'-- #LoadOp'` keys in Entity_lua.ts).
           '-- #TypesRequire': ({ indent }: any) => Content({ indent },
             `-- Typed-model annotations (LuaLS ---@class); empty at runtime.\n` +
             `require("${model.name}_types")`),
 
-          // Same embedded `-- ` prefix requirement as above (the bare
-          // '#BuildFeatures' key never matched the lua comment line).
           '-- #BuildFeatures': ({ indent }: any) => {
             each(feature, (feat: any) => {
               const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
@@ -178,7 +165,6 @@ self._utility.feature_hook(self._rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -188,25 +174,19 @@ self._utility.feature_hook(self._rootctx, "${name}")
       })
   })
 
-  // Generate typed-model annotations (LuaLS ---@class / ---@field)
   EntityTypes({ target })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the
   // API - header, query or cookie, under the name the spec gives - and tm/
-  // can only hold one answer. See PrepareAuth_lua.
-  //
   // Called at the TARGET ROOT, like Config above (that Folder({name:'.'})
   // is the root itself), because the lua tree has no src/ wrapper: the
-  // component opens the one `utility` folder that
-  // require("utility.prepare_auth") needs.
   PrepareAuth({ target })
 
-  // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`-- ${model.const.Name} SDK feature factory
 
@@ -248,7 +228,6 @@ return features
   })
 
   // Generate _make_feature function referenced by Main.fragment.lua
-  // This is part of the main SDK class, inserted via the slot
 
 })
 

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

@@ -33,9 +33,6 @@ const SECRETS_CORE_MODULES = [
   'feature/secrets/sekreto/err',
   'feature/secrets/sekreto/name',
   'feature/secrets/sekreto/providers',
-  // The shared plugin helpers, in no group: httpjson (eight kinds), net
-  // (httpjson, boru, secretspec), json and support (every kind), crypto
-  // (aws AND gcpsecrets - two groups, so neither may own it).
   'feature/secrets/sekreto/plugins/crypto',
   'feature/secrets/sekreto/plugins/httpjson',
   'feature/secrets/sekreto/plugins/json',
@@ -110,23 +107,6 @@ dependencies = {
 `)
     }
 
-    // Feature modules must be listed too, or an install-from-rock ships a
-    // features.lua whose requires cannot resolve. Emitted from the model
-    // (each = sorted order, byte-stable), plus the base feature every
-    // factory falls back to. The station feature additionally carries the
-    // VENDORED voxgig_station library beside its adapter (no voxgig-station
-    // rock exists to depend on - station design 9.2's registry-less tier).
-    // Gated: a feature that does not apply to lua must not be listed
-    // as a rockspec module — the require would not resolve.
-    //
-    // The secrets feature carries the VENDORED sekreto core, the
-    // voxgig/plugin runtime and the shared plugin helpers (no sekreto or
-    // plugin rock exists to depend on); the plugin KINDS themselves are
-    // listed from the model's active `def.lua` entries, so a trimmed
-    // group's modules are not claimed. The compiled transport helper the
-    // plugin kinds run is NOT a rock module: `build.type = "builtin"`
-    // cannot produce an executable, so an install-from-rock carries the
-    // helper's source and `make build` compiles it where the SDK runs.
     const feature = targetFeatures(model, target)
     let featureModules = `    ["feature.base_feature"] = "feature/base_feature.lua",\n`
     each(feature, (f: any) => {
@@ -159,6 +139,7 @@ build = {
     ["config"] = "config.lua",
     ["config_shared"] = "config_shared.lua",
     ["config_plugins"] = "config_plugins.lua",
+    ["schema"] = "schema.lua",
     ["features"] = "features.lua",
 ${featureModules}  }
 }

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

@@ -12,64 +12,18 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The lua peer of PrepareAuth_ts.
-//
-// This was a static file at tm/lua/utility/prepare_auth.lua that hardcoded
-// a lower-case "authorization" HEADER. apidef has always resolved the
-// scheme's "in" and "name" into main.kit.info.security - joplin's says
-// in: "query", name: "token" - and generation dropped both. The result was
-// an SDK that sent a header the API does not read and never sent the query
-// parameter it does, so it could not authenticate at all. Four repos in
-// the cedar fleet shipped that way: joplin (token), pipedrive (api_token),
-// trello (key), lm-umbrella (apiKey).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else - no dead query code in a
-// bearer-token SDK, and no runtime branch on a value that is fixed at
-// generation time.
-//
-// The header placement renders BYTE-FOR-BYTE what the template rendered,
-// so every header-based lua SDK regenerates with a zero diff.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  // `!isAuthSuppressed`, NOT `isAuthActive`. The latter is also false when
-  // the SPEC merely declares no security scheme (`main.kit.info.auth:
-  // false`), and those SDKs still carry a credential: optspec always
-  // declares `apikey` and makeOptions fills `options.auth` from its
-  // defaults, so the runtime guard never fired and they have always sent
-  // it. Only an explicit `main.kit.config.auth.active: false` means "no
-  // credential, ever", which is what isAuthSuppressed reads.
   const active = !isAuthSuppressed(model)
   const where = resolveAuthIn(model)
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // A HEADER NAME IS LOWER-CASED HERE; A QUERY OR COOKIE NAME IS NOT.
-  // Every header key the lua SDK writes is lower case (make_spec's
-  // "content-type", the secrets feature's "authorization", fetcher's
-  // lower-casing of the response headers), and HTTP header names are
-  // case-insensitive on the wire - so "Authorization" must arrive here as
-  // the "authorization" the rest of the SDK looks up. A query parameter
-  // and a cookie name are case-SENSITIVE: lm-umbrella's "apiKey" is not
-  // "apikey", and lower-casing it would break exactly the APIs this
-  // change exists to fix.
   const cred = resolveAuthName(model)
   const name = 'header' === where ? cred.toLowerCase() : cred
 
-  // FOLDER NESTING. Main_lua opens NO folder around this call: its
-  // Folder({name:'.'}) around Config is the target root itself, and the
-  // lua tree has no src/ wrapper (tm/lua/src holds only feature
-  // placeholders and Main's Copy excludes it). The template lived at
-  // tm/lua/utility/prepare_auth.lua, which the blanket Copy lands at
-  // <root>/utility/prepare_auth.lua - the one path
-  // require("utility.prepare_auth") in utility/register.lua resolves. So
-  // this component opens the single "utility" folder that path needs.
-  // Opening a second one would write <root>/utility/utility/, where
-  // nothing requires it.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({
@@ -91,8 +45,6 @@ function render(spec: {
 }): string {
   const head = `-- ${spec.project} SDK utility: prepare_auth\n`
 
-  // NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
-  // about it rather than one that deletes a header nobody set.
   if (!spec.active) {
     return head + `
 -- This API declares no authentication, so there is no credential to place.
@@ -166,8 +118,6 @@ return prepare_auth_util
 }
 
 
-// The constant the credential name is bound to, named for where it goes -
-// a reader of the generated file should not have to ask.
 function credConst(where: string): string {
   return 'query' === where ? 'QUERY_AUTH' :
     'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
@@ -200,9 +150,6 @@ function clear(where: string, indent: number): string {
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. "?token=Bearer%20abc" is not a thing any
-    // API reads; the prefix is a header-value convention and is dropped
-    // here deliberately rather than silently concatenated.
     return `    -- NO PREFIX IN A QUERY STRING: "?token=Bearer%20abc" is not a thing
     -- any API reads, so the auth.prefix a header placement space-joins is
     -- dropped here deliberately rather than concatenated.
@@ -223,8 +170,6 @@ function place(where: string): string {
     cookie_set(headers, apikey_val)`
   }
 
-  // BYTE-FOR-BYTE the template's body, so a header-based SDK regenerates
-  // unchanged.
   return `    local auth_prefix = ""
     local ap = vs.getpath(options, "auth.prefix")
     if type(ap) == "string" then
@@ -243,8 +188,6 @@ function place(where: string): string {
 }
 
 
-// True HTTP Basic Auth: two credentials, base64-joined. Emitted only for a
-// header placement (see render).
 const BASIC = `
   -- True HTTP Basic Auth needs TWO credentials, base64-joined - a single
   -- token in the header (the branch below) can never authenticate against
@@ -322,10 +265,6 @@ end
 `
 
 
-// A cookie header is SHARED: any other cookie the caller set rides in the
-// same string, so the credential pair is rewritten in place and everything
-// else is kept. A plain assignment would throw the caller's cookies away.
-// A nil value removes just our pair.
 const COOKIE_SET = `
 local function cookie_set(headers, value)
   local kept = {}

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

@@ -19,12 +19,8 @@ function luaLit(type: any, placeholder: string = 'example'): string {
   return `"${placeholder}"`
 }
 
-// Non-identifier table keys use bracket syntax.
 
 
-// Operation method spelling differs between Go and other languages — Go
-// uses PascalCase methods with explicit ctrl arg, others use lowercase
-// methods with optional ctrl. The op descriptions are language-agnostic.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
@@ -56,7 +52,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
-    // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
@@ -113,9 +108,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
-      // The id key plus every REQUIRED match key (parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

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

@@ -6,30 +6,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits lua/test/readme_examples_test.lua — a busted spec that is a
-// COMPLETENESS GATE over every ```lua block in ALL THREE docs that ship
-// lua examples:
-//   - the root README.md (top-level, multi-language quick start)
-//   - the per-language lua/README.md
-//   - the per-language lua/REFERENCE.md
-//
-// For every ```lua block, tagged by (source doc, index):
-//   1. Syntax: it must compile with Lua's load() — catches malformed
-//      example code (missing end, bad token, ...).
-//   2. Offline run: every RUNNABLE block (one that builds a client via
-//      sdk.new/sdk.test or references `client`) is EXECUTED with the mock
-//      transport (no network). Each client constructor is rewritten to the
-//      seeded test-mode form, and fragments that only use `client` get a
-//      seeded test client injected. A call to a method that does not exist
-//      — e.g. a lowercase entity accessor after the API capitalised it to
-//      client:Entity() — raises "call a nil value" and FAILS the test.
-//      Entity operations return a (value, err) tuple, so a seeded-fixture
-//      miss surfaces as a tolerated (nil, err) not-found domain error.
-//   3. Completeness: every block is partitioned into {executed, illustration}
-//      and total == executed + illustration is asserted per doc. A block that
-//      is neither runnable nor a NARROW explicit illustration (a comment-only
-//      / --[[ ]] placeholder) is a silently-untested example and FAILS the
-//      gate — "illustration" is never a catch-all.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props
 

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

@@ -20,6 +20,7 @@ Use \`helpers.to_map()\` to safely validate that a value is a table.
 lua/
 ├── ${model.name}_sdk.lua    -- Main SDK module
 ├── config.lua               -- Configuration
+├── schema.lua               -- Generated option + entity specs
 ├── features.lua             -- Feature factory
 ├── core/                    -- Core types and context
 ├── entity/                  -- Entity implementations