@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/js/Config_js.ts

@@ -42,9 +42,6 @@ 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 ff = Path.normalize(__dirname + '/../../../src/cmp/js/fragment/')
@@ -52,7 +49,6 @@ const Config = cmp(async function Config(props: any) {
   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)
   // `in` and `name` travel with the prefix now. They were resolved by
   // apidef all along and dropped here, so an apiKey-in-query API got an
@@ -71,30 +67,17 @@ const Config = cmp(async function Config(props: any) {
     `
     : ''
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see makeOptions).
   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\n    '
 
-  // Read the base URL here rather than leaving it to a `$$...$$` stdrep
-  // placeholder in the fragment. stdrep can only substitute a path the model
-  // actually has: a model with no `info.servers` left the placeholder itself in
-  // the generated source, so `options.base` came out as the literal string
-  // '$main.kit.info.servers.0.url$'. Reading it explicitly yields '' in that
-  // case, which is what every other target already emits, and is identical to
-  // the old output whenever the model does define a server.
   let baseUrl = ''
   try {
     baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`)
   } catch (_e) { }
 
-  // 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.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -122,9 +105,6 @@ const Config = cmp(async function Config(props: any) {
 
           '// #FeaturePlugins': () => pluginDefs(feature),
 
-          // A JS string literal, so the JSON survives verbatim. JSON.stringify
-          // escapes the quotes and backslashes the model contains (values like
-          // `$STRING` carry backticks, which a template literal could not).
           "'CONFIGJSON'": JSON.stringify(configJson),
         }
       })
@@ -162,8 +142,6 @@ const Config = cmp(async function Config(props: any) {
 
         '// #FeatureClasses': () => {
           each(feature, (f: any) => {
-            // Trailing comma: the map has one entry per feature, so entries
-            // must be comma-separated (a single feature hid this until now).
             Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
           })
         },
@@ -189,12 +167,6 @@ const Config = cmp(async function Config(props: any) {
           })
         },
 
-        // configDefinition's `def.entity` verbatim, NOT rebuilt here. This
-        // reduce was a second copy of that function's entityDefs loop, and
-        // when configDefinition started reconstructing a point's `parts`
-        // from apidef's segment vector (its ADR-003), only the data
-        // representation got it — the literal one emitted empty paths. The
-        // config-repr equivalence test caught it, which is what it is for.
         "'ENTITYMAP'": formatJson(configDef.entity, { margin: 2 }).trim(),
       }
     })
@@ -202,24 +174,8 @@ const Config = cmp(async function Config(props: any) {
 })
 
 
-// PLUGIN DEFINITION REQUIRES AND THE FEATURE_PLUGINS MAP.
-//
-// 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 Config no longer
-// requires provider modules for their side effects — it requires each
-// active plugin's exported Definition BY NAME (the model's `def` map)
-// and hands the list to the feature through FEATURE_PLUGINS.
-//
-// Emitted here because Config already requires every active feature from
-// the model, and this is the same list one level down. The `def` map is
-// declared in the model rather than derived from filenames because one
-// file may export several definitions (sekreto's aws.js exports
-// awssecrets AND awsparams).
 function pluginImports(feature: any) {
   each(feature, (f: any) => {
-    // path -> [symbol, ...], so one require line serves a two-definition
-    // module.
     const bypath: Record<string, string[]> = {}
 
     each(f.plugin, (plugin: any) => {
@@ -243,8 +199,6 @@ function pluginImports(feature: any) {
   })
 }
 
-// The FEATURE_PLUGINS entries: one line per feature that has any active
-// plugin definitions, listing the required symbols.
 function pluginDefs(feature: any) {
   each(feature, (f: any) => {
     const syms: string[] = []

package/project/.sdk/src/cmp/js/EntityTypes_js.ts

@@ -1,25 +1,5 @@
 
 
-// Typed-model generator (JavaScript target).
-//
-// JavaScript is dynamically typed, so the "types" are JSDoc typedefs
-// (@typedef / @property) 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, src/<Sdk>Types.js,
-// with a `@typedef {Object} <Name>` per active entity plus a request/match
-// typedef per active op. Field/param sentinels ($STRING, $INTEGER, ...) are
-// turned into JSDoc types by the shared sdkgen helper `canonToType`
-// ('js' column: Object / Array / * for open shapes).
-//
-// The typedefs are emitted at file (script) scope so they are GLOBAL across
-// the SDK's JS program — the op fragments reference them by bare name
-// (@param {AdviceLoadMatch} / @returns {Promise<Advice>}). The program itself
-// is established by the tm/js/jsconfig.json template shipped at the SDK root
-// (one project spanning src/ + test/), so resolution does not depend on
-// editor workspace inference. Keeps the SAME type-name scheme as the TS
-// reference (<Name>, <Name>LoadMatch, <Name>ListMatch, <Name>CreateData,
-// <Name>UpdateData, <Name>RemoveMatch).
 
 import {
   cmp, each, names,
@@ -37,8 +17,6 @@ import {
 const LANG = 'js'
 
 
-// A bare JSDoc property key, or a quoted string literal for anything that is
-// not a plain identifier.
 function propKey(name: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
 }
@@ -47,10 +25,6 @@ function propKey(name: string): string {
 const EntityTypes = cmp(function EntityTypes(props: any) {
   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
@@ -62,17 +36,14 @@ 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.const.Name + 'Types.' + LANG }, () => {
 
     Content(`// Typed models for the ${model.const.Name} SDK (JSDoc typedefs).
 //
-// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
-// params (op.<name>.points[].args.params[]). Field/param types come from the
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields{} and per-op
+// params (op.<name>.points[].g.params[]). Field/param types come from the
 // canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
 // @voxgig/apidef VALID_CANON). Annotations only — no runtime effect. Do not
 // edit by hand.
@@ -82,24 +53,20 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
     entityList.forEach((ent: any) => {
       const Name = ent.Name
       const fields = (ent.fields ? each(ent.fields) : [])
-        .filter((f: any) => f.active !== false)
+        .filter((f: any) => f.a !== false)
 
-      // Entity data model: one @property per field, `req:false` -> optional [].
       Content(`/**
  * @typedef {Object} ${Name}
 `)
       fields.forEach((f: any) => {
-        const key = false === f.req ? '[' + propKey(f.name) + ']' : propKey(f.name)
-        Content(` * @property {${canonToType(f.type, LANG)}} ${key}
+        const key = false === f.r ? '[' + propKey(f.n) + ']' : propKey(f.n)
+        Content(` * @property {${canonToType(f.t, LANG)}} ${key}
 `)
       })
       Content(` */
 
 `)
 
-      // Per active op: a request/match typedef. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as JSDoc @property lines (optional -> [bracketed] key).
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -55,15 +55,6 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
-    // Root copies src/feature/<name>/ per ACTIVE feature; keep this blanket
-    // copy from restoring one that was switched off after `target add`.
-    // A feature's inactive plugins go too - same rule, one level
-    // deeper. See helpers/featureSource.pluginExcludes.
-    //
-    // pluginExcludes is REQUIRED, not cosmetic: Feature() renders before
-    // Main(), so its per-feature Copy applies pluginExcludesFor and then
-    // this blanket copy runs — and without the same patterns here it puts
-    // every trimmed plugin straight back.
     exclude: [
       ...srcFeatureExcludes(model),
       ...pluginExcludes(model),
@@ -93,14 +84,6 @@ const Main = cmp(async function Main(props: any) {
           replace: {
             ...props.ctx$.stdrep,
 
-            // SECRETS. All five slots are emitted only when the secrets
-            // feature applies to this target AND the model activates it.
-            // An unconditional edit here would land in every generated SDK
-            // and break the inactive-output gate: a model without the
-            // feature must generate byte-identically to pre-migration.
-            //
-            // `feature` is already gated by targetFeatures, so a target
-            // that does not provide 'sekreto' never reaches these.
             '// #SecretsImport': () => secrets ?
               Line(`const sekreto = require('./feature/secrets/sekreto')`) : undefined,
 
@@ -117,15 +100,6 @@ secrets() {
 }
 `) : undefined,
 
-            // prepare() bypasses the feature hook pipeline, so the PreSpec
-            // hook that resolves the secret for entity ops never runs on
-            // this path and the resolve has to be explicit. This is also
-            // what defends direct() and graphql(), which run no feature
-            // hooks at all and reach the wire through prepare().
-            //
-            // It RETURNS the Error rather than rejecting: _rawRequest
-            // awaits prepare() outside its try, and direct()/graphql() are
-            // documented to return a value or an Error, never reject.
             '// #SecretsResolve': ({ indent }: any) => secrets ?
               Content({ indent }, `
 if (null != this._secrets) {
@@ -174,13 +148,6 @@ if (fres instanceof Promise) { await fres }
           })
         })
 
-      // Station self-registration (station design §6.2 path 1;
-      // station-declarative-config §11 item 2): emitted ONLY when the model
-      // carries an ACTIVE station feature (installed via
-      // `package add @voxgig/sdkgen-station`). The library package name
-      // comes from the feature model's own `deps.js` block — the same entry
-      // collectDeps flows into package.json — so the manifest dependency
-      // and the emitted require cannot disagree.
       const stationPkg = stationLibrary(model, target.name)
       if (null != stationPkg) {
         Fragment({

package/project/.sdk/src/cmp/js/Package_js.ts

@@ -14,6 +14,7 @@ import {
   packageVersion,
   authorInfo,
   targetFeatures, envName,
+  hasLiveScenarios,
 } from '@voxgig/sdkgen'
 
 
@@ -44,14 +45,11 @@ const Package = cmp(async function Package(props: any) {
   const only = (kind: string, deps: any) =>
     omap(deps, ([k, v]: any) => [v.active && kind === v.kind ? k : undefined, v.version])
 
-  // merge target and feature deps, by kind
   const deps =
     each(feature, (feature: any) =>
       omap(feature.deps?.[target.name], ([k, v]: any) =>
         [v.active ? k : undefined, v]))
 
-      // TODO: sort by version; rules for version choice?
-      // TODO: non-node dep kinds
       .reduce((a: any, deps: any) => (each(deps, (dep: any) =>
         a[dep.kind][dep.key$] = dep.version), a),
         {
@@ -64,8 +62,6 @@ const Package = cmp(async function Package(props: any) {
   const { repoUrl, issuesUrl } = repoInfo(model)
 
   const pkg = {
-    // The ts target publishes the canonical scoped npm name; the js target
-    // appends `-js` so the two never collide on npm.
     name: packageName(model, target.name),
     version: packageVersion(model, target.name),
     description: pkgDescription(model, target.name),
@@ -81,7 +77,7 @@ const Package = cmp(async function Package(props: any) {
     // directly (no build step), so that is the whole package.
     files: ['src'],
     scripts: {
-      ...(Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? {
+      ...(hasLiveScenarios(model) ? {
         'test:live': `${envName(model)}_TEST_LIVE=TRUE node --test test/live.test.js`,
       } : {}),
 
@@ -95,7 +91,6 @@ const Package = cmp(async function Package(props: any) {
     },
     author,
 
-    // TODO: needs to be config
     license: 'MIT',
 
     dependencies: deps.prod,

package/project/.sdk/src/cmp/js/PrepareAuth_js.ts

@@ -17,53 +17,17 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// This was a static file at `tm/js/src/utility/PrepareAuthUtility.js` that
-// hardcoded `authorization` and a 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 `if` on a value that is fixed at
-// generation time.
-//
-// Ported from PrepareAuth_ts, which is the proven shape. The differences
-// are the language's, not the design's: no type import, `module.exports`
-// instead of `export {}`, and the prefix read inline off `options.auth`
-// exactly as the js template read it, rather than hoisted into a local
-// that the query and cookie bodies would leave unused.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
   const active = isAuthActive_js(model)
   const where = resolveAuthIn(model)
-  // LOWERCASED FOR A HEADER, VERBATIM OTHERWISE. The js runtime keys its
-  // header map in lower case — the old template hardcoded 'authorization',
-  // the shared corpus asserts ctx:spec:headers:authorization, and every
-  // generatedcompile probe reads the lower-case key. apidef writes
-  // name: "Authorization", so emitting it verbatim hides the credential
-  // under a key nothing reads. Query parameters and cookies ARE
-  // case-sensitive and keep the spec's spelling.
   const resolvedName = resolveAuthName(model)
   const name = 'header' === where ? resolvedName.toLowerCase() : resolvedName
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // No `src` folder here: Main_js already opened it, and Config, Schema,
-  // SdkError, EntityBase and EntityTypes all write straight into it. The
-  // template this replaces lived at `tm/js/src/utility/`, so relative to
-  // that open folder the file needs `utility` and nothing more. Opening a
-  // second `src` would put it at src/src/utility/ — where nothing imports
-  // it, and the stale copy at src/utility/ keeps being used.
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuthUtility.' + target.ext }, () => {
       Content(render({ active, where, name, prefix, basic }))
@@ -76,8 +40,6 @@ function render(spec: {
   active: boolean, where: string, name: string, prefix: string, basic: boolean
 }): string {
 
-  // NO AUTH AT ALL. A public API's SDK gets a prepareAuth that is honest
-  // about it rather than one that deletes a header nobody set.
   if (!spec.active) {
     return `
 // This API declares no authentication, so there is no credential to
@@ -193,16 +155,10 @@ function clear(where: string): 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 convention and is dropped here
-    // deliberately rather than silently concatenated.
     return `    setprop(query, CRED_name, apikey)`
   }
 
   if ('cookie' === where) {
-    // APPEND, never clobber: the request may already carry a session
-    // cookie set from options.headers, and a cookie header holds a
-    // '; '-joined list of pairs.
     return `    const existing = getprop(headers, 'cookie', '')
     const pair = CRED_name + '=' + apikey
     setprop(headers, 'cookie', existing ? existing + '; ' + pair : pair)`
@@ -224,19 +180,6 @@ export {
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is
-// also false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`) — a statement about the DEFINITION, not a
-// ban on ever sending a credential. `optspec` still declares `apikey` and
-// makeOptions fills `options.auth` from its defaults, so the runtime
-// `options.auth == null` guard never fired and those SDKs have always sent
-// the credential. Gating the body on `isAuthActive` does not trim dead
-// code, it removes working authentication — which
-// `js: auth null suppresses the credential` catches, and which takes the
-// secrets feature down with it.
-//
-// `main.kit.config.auth.active: false` is the project saying "no credential,
-// ever", and it is the only signal that can be honoured before runtime.
 function isAuthActive_js(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -9,14 +9,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-// 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.
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -53,10 +45,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.fields || []
+    const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
-    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
     const eVar = exampleVarName(entity.name, 'js')
 
     Content(`
@@ -100,8 +91,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -32,8 +32,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
-      // Every REQUIRED match key (id first), not just idF — a composite-match
-      // entity (database_id + id) needs them all. Mirrors ReadmeTopTest.
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))

package/project/.sdk/src/cmp/js/ReadmeModel_js.ts

@@ -153,13 +153,13 @@ The \`prepare()\` method returns:
 `)
 
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -167,7 +167,7 @@ The \`prepare()\` method returns:
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`${field.name}\` | ${field.short || ''} |
+      Content(`| \`${field.n}\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/js/ReadmeQuick_js.ts

@@ -10,11 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -26,7 +21,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
-  // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   const ctor = isAuthActive(model)
@@ -47,8 +41,6 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    // ACTIVE ops only — an inactive op generates no method, so an example
-    // calling it would be wrong.
     const opnames = entityOps(exampleEntity)
 
     // Model-driven example fields, in parity with the ts target: derive the
@@ -57,20 +49,13 @@ const client = ${ctor}
     // `idF` is the entity's id-like field name, or null when it has none —
     // then load/remove match on no argument and update omits the id.
     const idF = entityIdField(exampleEntity)
-    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
     const eVar = exampleVarName(exampleEntity.name, 'js')
     const exampleFields = (opname: string): string[] => {
-      // ids are rendered separately as the match key for update/remove; a
-      // REQUIRED id stays for create (dropping it makes the payload
-      // incomplete).
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('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 for parity with the typed ts target;
-      // 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))

package/project/.sdk/src/cmp/js/ReadmeRef_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -44,7 +44,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)
 
@@ -181,11 +181,10 @@ Alias for \`${model.Name}SDK.test()\`.
     // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
-      const fields = ent.fields || []
+      const fields = Object.values(ent.fields || {})
       // Model-driven id key: null when this entity has no id-like field, in
       // which case load/remove match on no argument and update omits the id.
       const idF = entityIdField(ent)
-      // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
       const eVar = exampleVarName(ent.name, 'js')
 
       Content(`
@@ -208,7 +207,6 @@ const ${eVar} = client.${ent.Name}()
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -216,9 +214,9 @@ const ${eVar} = client.${ent.Name}()
 | --- | --- | --- | --- |
 `)
         each(fields, (field: any) => {
-          const req = field.req ? 'Yes' : 'No'
-          const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+          const req = field.r ? 'Yes' : 'No'
+          const desc = field.sh || ''
+          Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -245,7 +243,7 @@ const ${eVar} = client.${ent.Name}()
               if (fop.active === false) return '-'
               return 'Yes'
             })
-            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+            Content(`| \`${field.n}\` | ${cols.join(' | ')} |
 `)
           })
 
@@ -406,9 +404,6 @@ const client = new ${model.Name}SDK({
 \`\`\`
 
 `)
-      // 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/js/ReadmeTopQuick_js.ts

@@ -10,11 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -41,8 +36,6 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const eVar = exampleVarName(eName.toLowerCase(), 'js')
-    // ACTIVE ops only — an inactive op generates no method, so an example
-    // calling it would be wrong.
     const opnames = entityOps(exampleEntity)
 
     if (opnames.includes('list')) {

package/project/.sdk/src/cmp/js/Schema_js.ts

@@ -12,27 +12,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// Two exports, both struct.validate specs:
-//
-//   OPTSPEC     what makeOptions validates the caller's options against —
-//               the standard options from `main.kit.optspec` plus one entry
-//               per feature this target carries, built by helpers/optspec.
-//
-//   ENTITYSPEC  per entity, `{ data, op: { <opname> } }` — the record shape
-//               and each operation's request shape, mapped from the field
-//               type sentinels the model already carries (helpers/canonSpec).
-//               Emitted as an EMPTY MAP unless the `validate` feature is
-//               active, because nothing else reads it and every byte here is
-//               a byte in the consumer's package.
-//
-// A JSON OBJECT LITERAL, not a parsed string: JSON is a subset of the
-// language's own literal syntax, so the values land as data with no parse
-// step, and the backticks the sentinels carry (`\`$STRING\``) survive because
-// JSON.stringify quotes and escapes them. The config emitter has to choose
-// between a literal and a parsed blob because the config can be megabytes;
-// the spec is bounded by the model's field count, so it does not.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -46,7 +25,7 @@ const Schema = cmp(async function Schema(props: any) {
     Content(`// ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
 //
 // Generated from the model: \`main.kit.optspec\` and each feature's
-// \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+// \`config.options\` for OPTSPEC; entity \`fields{}.type\` for ENTITYSPEC.
 
 const OPTSPEC = ${JSON.stringify(optspec, null, 2)}