@voxgig/sdkgen 4.21.0 → 4.22.0

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

@@ -29,15 +29,6 @@ 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']
 
 
@@ -56,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) => [
@@ -70,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,
@@ -86,29 +64,6 @@ 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.
-  //
-  // TWO HELPERS, NOT ONE, AND THEY ARE BUILT DIFFERENTLY. The transport
-  // helper is a PROGRAM the plugins run; the mini vault's crypto is a
-  // LOADABLE MODULE the interpreter opens with package.loadlib, so it is
-  // compiled -shared -fPIC and keeps its `.so` name. Each is emitted only
-  // for the groups that actually use it: a chain of `[hashicorp]` builds
-  // no vault, and a chain of `[minivault]` opens no socket and links no
-  // TLS.
   const nativeGroups: string[] = []
   let wantsVault = false
   each(feature, (f: any) => {
@@ -178,7 +133,6 @@ feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.c
     })
   }
 
-  // Generate main SDK file
   File({ name: model.name + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -190,15 +144,12 @@ feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.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)
@@ -214,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}`)
@@ -224,10 +174,8 @@ 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 })
@@ -235,15 +183,10 @@ self._utility.feature_hook(self._rootctx, "${name}")
 
   // 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
 
@@ -285,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) => {

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/ReadmeModel_lua.ts

@@ -13,10 +13,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
-  // Model-driven op rows for the shared entity interface: emit a
-  // load/list/create/update/remove row only for operations at least one active
-  // entity actually exposes (a read-only entity has just list+load) — never
-  // document an operation no entity has.
   const opUnion = new Set<string>()
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
@@ -30,9 +26,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  // Model-driven Result-shape rows: only describe the operations that
-  // actually exist. Record-returning ops (load/create/update/remove) share
-  // one row; list has its own — never name a missing op.
   const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const resultRows: string[] = []
@@ -50,8 +43,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const eName = exEnt.Name || 'Entity'
   const eLower = String(exEnt.name || 'entity').toLowerCase()
   const hasLoad = null != (exEnt.op || {}).load
-  // Model-driven id key: null when the example entity has no id-like field, so
-  // the Result-shape load illustration takes no match argument.
   const idF = entityIdField(exEnt)
 
   const apikeyOptionRow = isAuthActive(model)
@@ -136,7 +127,6 @@ Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 
 `)
 
-  // Entities summary
   Content(`### Entities
 
 `)

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

@@ -15,9 +15,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -108,9 +105,6 @@ end
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
       const neVar = exampleVarName(neName.toLowerCase(), 'lua')
 
-      // Model-driven match: every REQUIRED load-match key — the same shape
-      // the runtime resolves path params from, so the example always works.
-      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
         .filter((it: any) => !it.optional)
@@ -136,9 +130,6 @@ print(${neVar})
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -160,20 +151,12 @@ print(${eVar})
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Lua-typed by the
-    // field's canonical type; non-identifier keys use bracket syntax. ids are
-    // rendered separately as the match key for update/remove; a REQUIRED
-    // create id stays (the call is invalid without it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => !idNames.has(it.name) ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
@@ -181,8 +164,6 @@ print(${eVar})
         `${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}`)
     }
 
-    // The id VALUE for an update/remove match: off the returned `created` record
-    // only when its data type carries the id AND a create ran, else a literal.
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -211,8 +192,6 @@ client:${eName}():update({ ${updatePairs.join(', ')} })
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -57,7 +57,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -119,7 +119,6 @@ local client = sdk.test()
 `)
 
 
-    // Entity factory methods
     publishedEntities.map((ent: any) => {
       Content(`#### \`${ent.Name}(data)\`
 
@@ -165,7 +164,6 @@ same parameters as \`direct()\`.
 `)
 
 
-    // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
@@ -196,7 +194,6 @@ local ${eVar} = client:${ent.Name}(nil)
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -243,7 +240,6 @@ local ${eVar} = client:${ent.Name}(nil)
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -259,7 +255,6 @@ ${info.desc}
 
 `)
 
-          // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -328,7 +323,6 @@ ${updateLines}  -- Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get() -> table\`
@@ -360,7 +354,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -396,9 +389,6 @@ local client = sdk.new({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

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

@@ -19,7 +19,6 @@ function luaLit(type: any, placeholder: string = 'example'): string {
   return `"${placeholder}"`
 }
 
-// Non-identifier table keys use bracket syntax.
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -47,8 +46,6 @@ local client = ${ctor}
     // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'lua')
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes no match argument.
     const idF = entityIdField(exampleEntity)
 
     let hasCall = false

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

@@ -17,22 +17,6 @@ import {
 } from './utility_lua'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The lua peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source —
-// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
-// ENTITYSPEC from the entity field sentinels — built by the shared helpers,
-// so what lua validates against and what ts validates against cannot drift.
-//
-// EMBEDDED AS JSON IN A LONG BRACKET, PARSED AT LOAD: the mechanism
-// config.lua already uses for the model above the size threshold.
-// `luaLongString` picks a bracket level no `]]` in the content can close, so
-// the sentinels' backticks and the JSON's own quoting survive verbatim with
-// no escaping at all.
-//
-// The round-trip is exact because the spec holds only strings and booleans —
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target

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

@@ -251,8 +251,6 @@ ${listSkipBlock}    local client = setup.client
     }
 
     if (hasLoad && loadPoint) {
-      // Skip live direct-load only when we can't fill path params:
-      // no spec examples and no list-bootstrap. Spec examples win first.
       const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
         ? `    if setup.live then
       pending("live direct-load needs real ID — set *_ENTID env var with real IDs to run")

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

@@ -66,28 +66,6 @@ function formatLuaValue(val: any, indent: number = 0): string {
 }
 
 
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
 // Keys whose value IS the default the runtime already assumes when the key is
@@ -128,14 +106,6 @@ function clean(o: any, dropDefaults?: boolean): any {
 
 
 
-// A Lua LONG-BRACKET string holding `s` verbatim.
-//
-// Lua's quoted strings process escapes, so the JSON's own `\n` and `\uXXXX`
-// would be consumed by the Lua lexer before the JSON decoder ever saw them -
-// turning an escaped newline into a real one inside a JSON string (invalid
-// JSON), and failing outright on `\uXXXX`, which Lua 5.1/5.2 do not accept at
-// all. A long bracket processes nothing, so the JSON text survives byte for
-// byte. The level is raised until its terminator does not occur in the text.
 function luaLongString(s: string): string {
   let level = 0
   while (s.includes(']' + '='.repeat(level) + ']')) {