@voxgig/sdkgen 1.3.4 → 1.3.6

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

@@ -1,16 +1,26 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
 
 
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
+  const { model } = props.ctx$
+
+  // Return the collision-free class (entityClassName); the accessor METHOD name
+  // (entity.Name) is unchanged so callers still write client.<Name>().
+  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
 
   Content(`
   // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
   ${entity.Name}(data) {
     const self = this
-    return new ${entity.Name}Entity(self,data)
+    return new ${cls}(self,data)
   }
 
 `)

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

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
 
@@ -55,8 +56,10 @@ const Main = cmp(async function Main(props: any) {
 
       Line(`// ${model.const.Name} ${target.Name} SDK\n`)
 
-      List({ item: entity }, ({ item }: any) =>
-        Line(`const { ${item.Name}Entity } = require('./entity/${item.Name}Entity')`))
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entity)
+        return Line(`const { ${cls} } = require('./entity/${cls}')`)
+      })
 
       Fragment(
         {

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

@@ -132,10 +132,10 @@ const ${eVar}s = await client.${entity.Name}().list()
 
     if (opnames.includes('create')) {
       // Members come from the SAME shape the runtime validates
-      // (opRequestShape): every required member must appear — including a
-      // required id and parent keys like page_id (the /* type */
-      // placeholders mark the block as an illustration); an all-optional
-      // create renders an empty — still valid — literal.
+      // (opRequestShape): every required member appears — including a
+      // required id and parent keys like page_id — each with a type-correct
+      // example VALUE via exampleValue — a `name: /* type */` comment is not
+      // a value and yields invalid code.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -144,7 +144,7 @@ const ${eVar}s = await client.${entity.Name}().list()
 const ${eVar} = await client.${entity.Name}().create({
 `)
       createItems.map((it: any) => {
-        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+        Content(`  ${it.name}: ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
 `)
       })
       Content(`})

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,14 +14,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
+  // only when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   const eVar = safeVarName(eName.toLowerCase(), 'js')
 
-  // Drive the test-mode / stateful examples off the entity's PRIMARY op — an op
-  // it actually exposes — never a hardcoded `load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
-  const primaryOpDef = exampleEntity && exampleEntity.op && exampleEntity.op[primaryOp]
+  const primaryOpDef = exampleEntity && primaryOp && exampleEntity.op && exampleEntity.op[primaryOp]
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   // idF is the MATCH key; dataIdF is the id on the RETURNED record's data type
   // (guard `.id` reads off a returned record on this, not the match key).
@@ -29,7 +29,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const dataIdF = exampleEntity ? entityDataIdField(exampleEntity) : null
 
   const primaryArg = (idPlaceholder: string): string => {
-    if (!exampleEntity) return ''
+    if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
       return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
@@ -48,6 +48,34 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     ? `console.log(data.${dataIdF})`
     : `console.log(data)`
 
+  // The op-driven example lines, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() test call instead
+  // and omits the stateful section (there is no op to retain state across).
+  const testModeExample = primaryOp
+    ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
+// ${eVar} is a bare entity populated with mock response data
+console.log(${eVar})`
+    : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
+console.log(result)`
+  const stateSection = primaryOp
+    ? `### Retain entity state across calls
+
+Entity instances remember their last match and data:
+
+\`\`\`js
+const entity = client.${eName}()
+
+// First call runs the operation and stores its result
+await entity.${primaryOp}(${stateCallArg})
+
+// Subsequent calls reuse the stored state
+const data = entity.data()
+${stateDataLine}
+\`\`\`
+
+`
+    : ''
+
   const authActive = isAuthActive(model)
   const apikeyTesterCtor = authActive
     ? `new ${model.const.Name}SDK({ apikey: '...' })`
@@ -97,9 +125,7 @@ Create a mock client for unit testing — no server required:
 \`\`\`js
 const client = ${model.const.Name}SDK.test()
 
-const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is a bare entity populated with mock response data
-console.log(${eVar})
+${testModeExample}
 \`\`\`
 
 You can also use the instance method:
@@ -109,22 +135,7 @@ const client = ${apikeyTesterCtor}
 const testClient = client.tester()
 \`\`\`
 
-### Retain entity state across calls
-
-Entity instances remember their last match and data:
-
-\`\`\`js
-const entity = client.${eName}()
-
-// First call runs the operation and stores its result
-await entity.${primaryOp}(${stateCallArg})
-
-// Subsequent calls reuse the stored state
-const data = entity.data()
-${stateDataLine}
-\`\`\`
-
-### Add custom middleware
+${stateSection}### Add custom middleware
 
 Pass features via the \`extend\` option:
 

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

@@ -299,17 +299,17 @@ const results = await client.${ent.Name}().${opname}()
           }
           else if ('create' === opname) {
             // Members come from the SAME shape the runtime validates
-            // (opRequestShape): every required member must appear — including
-            // a required id and parent keys like page_id (the /* type */
-            // placeholders mark the block as an illustration); an
-            // all-optional create renders an empty — still valid — literal.
+            // (opRequestShape): every required member appears — including
+            // a required id and parent keys like page_id — each with a
+            // type-correct example VALUE via exampleValue — a
+            // `name: /* type */` comment is not a value and yields invalid code.
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
             createItems.map((it: any) => {
-              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+              Content(`  ${it.name}: ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
 `)
             })
             Content(`})

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,17 +14,16 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
   Content(`\`\`\`js
 const client = ${model.const.Name}SDK.test()
 `)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
-    // Drive the test-mode example off the entity's PRIMARY op (never a
-    // hardcoded `load` a create-only entity lacks).
-    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
     // A list() result is an array — name the variable accordingly.
     const eVar = safeVarName(eName.toLowerCase(), 'js') +
       ('list' === primaryOp ? 's' : '')

package/project/.sdk/src/cmp/js/fragment/Entity.fragment.js

@@ -5,7 +5,7 @@ const { ProjectNameEntityBase } = require('../ProjectNameEntityBase')
 
 
 // TODO: needs Entity superclass
-class EntityNameEntity extends ProjectNameEntityBase {
+class EntyClass extends ProjectNameEntityBase {
 
   constructor(client, entopts) {
     super(client, entopts)
@@ -16,7 +16,7 @@ class EntityNameEntity extends ProjectNameEntityBase {
 
 
   make() {
-    return new EntityNameEntity(this._client, this.entopts())
+    return new EntyClass(this._client, this.entopts())
   }
 
 
@@ -34,5 +34,5 @@ class EntityNameEntity extends ProjectNameEntityBase {
 
 
 module.exports = {
-  EntityNameEntity
+  EntyClass
 }

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

@@ -7,7 +7,7 @@ import {
 
 const EntityOperation = cmp(function Operation(props: any) {
   const { model } = props.ctx$
-  const { ff, opname, entity, entrep } = props
+  const { ff, opname, entity, entrep, cls } = props
 
   let { indent } = props
 
@@ -29,6 +29,11 @@ const EntityOperation = cmp(function Operation(props: any) {
       ProjectName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+
+      // Class receiver token decoupled from the EntityName data-type token in
+      // the Entity<Op>Op.fragment.lua files (receiver -> cls).
+      EntyClass: cls,
+
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `
 u.feature_hook(ctx, "${name}")

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

@@ -3,9 +3,15 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, camelify, names,
-  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
 import { EntityOperation } from './EntityOperation_lua'
 
 
@@ -13,6 +19,14 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
+  // Collision-free entity CLASS name (see entityClassName): normally
+  // `<Name>Entity`, disambiguated when it would clash with another entity's
+  // data-type name. The class is a module-local table (snake-cased file name),
+  // so this is used only for the local identifier — kept uniform with the other
+  // languages.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -33,7 +47,7 @@ const Entity = cmp(function Entity(props: any) {
           .reduce((a: any, opname: string) =>
           (a['-- #' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ? '' : ({ indent }: any) => {
-              EntityOperation({ ff, opname, indent, entity, entrep })
+              EntityOperation({ ff, opname, indent, entity, entrep, cls })
             }, a), {}))
 
       Fragment({
@@ -44,6 +58,10 @@ 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,
+
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `utility.feature_hook(ctx, "${name}")`),
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -61,6 +61,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     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.
+    const eVar = safeVarName(entity.name, 'lua')
 
     Content(`
 ### ${entity.Name}
@@ -73,7 +76,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`local ${entity.name} = client:${entity.Name}(nil)\`
+    Content(`Create an instance: \`local ${eVar} = client:${entity.Name}(nil)\`
 
 `)
 
@@ -128,7 +131,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`lua
-local ${entity.name}, err = client:${entity.Name}():load(${loadArg})
+local ${eVar}, err = client:${entity.Name}():load(${loadArg})
 \`\`\`
 
 `)
@@ -138,7 +141,7 @@ local ${entity.name}, err = client:${entity.Name}():load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`lua
-local ${entity.name}s, err = client:${entity.Name}():list()
+local ${eVar}s, err = client:${entity.Name}():list()
 \`\`\`
 
 `)
@@ -155,7 +158,7 @@ local ${entity.name}s, err = client:${entity.Name}():list()
       Content(`#### Example: Create
 
 \`\`\`lua
-local ${entity.name}, err = client:${entity.Name}():create({
+local ${eVar}, err = client:${entity.Name}():create({
 `)
       createItems.map((it: any) => {
         Content(`  ${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}, -- ${canonToType(it.type, target.name)}

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -26,13 +26,13 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
+  // only when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Model-driven id key: null when the entity has no id-like field.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
-  // Drive the test-mode example off the entity's PRIMARY op — never a hardcoded
-  // `load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testCallArg = ''
   if (exampleEntity && isMatchOp) {
@@ -45,6 +45,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testCallArg = `{ ${chosen.map((it: any) => `${luaKey(it.name)} = ${luaLit(it.type)}`).join(', ')} }`
   }
 
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `local result, err = client:${eName}():${primaryOp}(${testCallArg})
+-- result is the returned data; err is set on failure`
+    : `local result, err = client:direct({ path = "/api/resource", method = "GET" })
+-- result is the returned data; err is set on failure`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -89,8 +97,7 @@ Create a mock client for unit testing — no server required:
 \`\`\`lua
 local client = sdk.test()
 
-local result, err = client:${eName}():${primaryOp}(${testCallArg})
--- result is the returned data; err is set on failure
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -43,6 +43,9 @@ local client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? "an" : "a"
+    // Sanitise the local variable name — an entity whose lowercased name is a
+    // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(eName.toLowerCase(), 'lua')
     const opnames = entityOps(exampleEntity)
     // Model-driven id key: `idF` is the MATCH key (null when none). `dataIdF`
     // is the id on the RETURNED record's data type — an entity can key its match
@@ -91,10 +94,10 @@ Entity operations return \`(value, err)\`. For \`list\`, \`value\` is the
 array of records itself — iterate it directly (there is no wrapper).
 
 \`\`\`lua
-local ${eName.toLowerCase()}s, err = client:${eName}():list()
+local ${eVar}s, err = client:${eName}():list()
 if err then error(err) end
 
-for _, item in ipairs(${eName.toLowerCase()}s) do
+for _, item in ipairs(${eVar}s) do
 ${printLine}
 end
 \`\`\`
@@ -105,7 +108,7 @@ end
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
-      const neVar = neName.toLowerCase()
+      const neVar = safeVarName(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.
@@ -151,9 +154,9 @@ print(${neVar})
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`\`\`lua
-local ${eName.toLowerCase()}, err = client:${eName}():load(${loadArg})
+local ${eVar}, err = client:${eName}():load(${loadArg})
 if err then error(err) end
-print(${eName.toLowerCase()})
+print(${eVar})
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -174,6 +174,9 @@ same parameters as \`direct()\`.
       // 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)
+      // Sanitise the local variable name — an entity whose lowercased name is
+      // a Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
+      const eVar = safeVarName(ent.name, 'lua')
 
       Content(`
 ---
@@ -189,7 +192,7 @@ same parameters as \`direct()\`.
       }
 
       Content(`\`\`\`lua
-local ${ent.name} = client:${ent.Name}(nil)
+local ${eVar} = client:${ent.Name}(nil)
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -46,6 +46,9 @@ local client = ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    // Sanitise the local variable name — an entity whose lowercased name is a
+    // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(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.
@@ -55,8 +58,8 @@ local client = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`-- List all ${eName.toLowerCase()}s
-local ${eName.toLowerCase()}s, err = client:${eName}():list()
-print(${eName.toLowerCase()}s)
+local ${eVar}s, err = client:${eName}():list()
+print(${eVar}s)
 `)
       hasCall = true
     }
@@ -76,8 +79,8 @@ print(${eName.toLowerCase()}s)
         : ''
       Content(`
 -- Load a specific ${eName.toLowerCase()}
-local ${eName.toLowerCase()}, err = client:${eName}():load(${loadArg})
-print(${eName.toLowerCase()})
+local ${eVar}, err = client:${eName}():load(${loadArg})
+print(${eVar})
 `)
       hasCall = true
     }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -27,18 +27,17 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
   Content(`\`\`\`lua
 local client = sdk.test()
 `)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
-    // Drive the test-mode example off the entity's PRIMARY op (never a hardcoded
-    // `load` a create-only entity lacks).
     const idF = entityIdField(exampleEntity)
-    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
     if (isMatchOp) {

package/project/.sdk/src/cmp/lua/fragment/Entity.fragment.lua

@@ -3,11 +3,11 @@
 local vs = require("utility.struct.struct")
 local helpers = require("core.helpers")
 
-local EntityNameEntity = {}
-EntityNameEntity.__index = EntityNameEntity
+local EntyClass = {}
+EntyClass.__index = EntyClass
 
 
-function EntityNameEntity.new(client, entopts)
+function EntyClass.new(client, entopts)
   entopts = entopts or {}
   if entopts["active"] == nil then
     entopts["active"] = true
@@ -17,7 +17,7 @@ function EntityNameEntity.new(client, entopts)
     entopts["active"] = true
   end
 
-  local self = setmetatable({}, EntityNameEntity)
+  local self = setmetatable({}, EntyClass)
   self._name = "entityname"
   self._client = client
   self._utility = client:get_utility()
@@ -36,21 +36,21 @@ function EntityNameEntity.new(client, entopts)
 end
 
 
-function EntityNameEntity:get_name()
+function EntyClass:get_name()
   return self._name
 end
 
 
-function EntityNameEntity:make()
+function EntyClass:make()
   local opts = {}
   for k, v in pairs(self._entopts) do
     opts[k] = v
   end
-  return EntityNameEntity.new(self._client, opts)
+  return EntyClass.new(self._client, opts)
 end
 
 
-function EntityNameEntity:data_set(args)
+function EntyClass:data_set(args)
   if args ~= nil then
     self._data = helpers.to_map(vs.clone(args)) or {}
     self._utility.feature_hook(self._entctx, "SetData")
@@ -58,13 +58,13 @@ function EntityNameEntity:data_set(args)
 end
 
 
-function EntityNameEntity:data_get()
+function EntyClass:data_get()
   self._utility.feature_hook(self._entctx, "GetData")
   return vs.clone(self._data)
 end
 
 
-function EntityNameEntity:match_set(args)
+function EntyClass:match_set(args)
   if args ~= nil then
     self._match = helpers.to_map(vs.clone(args)) or {}
     self._utility.feature_hook(self._entctx, "SetMatch")
@@ -72,7 +72,7 @@ function EntityNameEntity:match_set(args)
 end
 
 
-function EntityNameEntity:match_get()
+function EntyClass:match_get()
   self._utility.feature_hook(self._entctx, "GetMatch")
   return vs.clone(self._match)
 end
@@ -89,7 +89,7 @@ end
 -- #RemoveOp
 
 
-function EntityNameEntity:_run_op(ctx, post_done)
+function EntyClass:_run_op(ctx, post_done)
   local utility = self._utility
 
   -- #PrePoint-Hook
@@ -144,4 +144,4 @@ function EntityNameEntity:_run_op(ctx, post_done)
 end
 
 
-return EntityNameEntity
+return EntyClass