@voxgig/sdkgen 1.3.4 → 1.3.5

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

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

@@ -9,7 +9,7 @@ local entityCreateOp = {}
 ---@param ctrl? table
 ---@return EntityName
 ---@return string? err
-function EntityNameEntity:create(reqdata, ctrl)
+function EntyClass:create(reqdata, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({
     opname = "create",

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

@@ -6,7 +6,7 @@ local entityListOp = {}
 ---@param ctrl? table
 ---@return EntityName[]
 ---@return string? err
-function EntityNameEntity:list(reqmatch, ctrl)
+function EntyClass:list(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({
     opname = "list",

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

@@ -9,7 +9,7 @@ local entityLoadOp = {}
 ---@param ctrl? table
 ---@return EntityName
 ---@return string? err
-function EntityNameEntity:load(reqmatch, ctrl)
+function EntyClass:load(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({
     opname = "load",

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

@@ -9,7 +9,7 @@ local entityRemoveOp = {}
 ---@param ctrl? table
 ---@return EntityName
 ---@return string? err
-function EntityNameEntity:remove(reqmatch, ctrl)
+function EntyClass:remove(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({
     opname = "remove",

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

@@ -9,7 +9,7 @@ local entityUpdateOp = {}
 ---@param ctrl? table
 ---@return EntityName
 ---@return string? err
-function EntityNameEntity:update(reqdata, ctrl)
+function EntyClass:update(reqdata, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({
     opname = "update",

package/project/.sdk/src/cmp/php/Entity_php.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_php'
 
 
@@ -13,6 +19,12 @@ 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 snake-cased source-file name is unaffected.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -44,6 +56,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.php 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/php/MainEntity_php.ts

@@ -1,6 +1,11 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
 
 
 // Reserved PHP method names on the SDK class that an entity accessor must
@@ -13,6 +18,10 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
 
+  // Collision-free entity CLASS name (entityClassName); the accessor METHOD name
+  // (below) is unchanged so callers still write $client->${entity.Name}().
+  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
+
   // Canonical facade method name is the PascalCase entity Name
   // (`$client->${entity.Name}()`). PHP method names are case-insensitive, so
   // the lowercase spelling `$client->${entity.name}()` still resolves here as
@@ -34,11 +43,11 @@ const MainEntity = cmp(async function MainEntity(props: any) {
         require_once __DIR__ . '/entity/${entity.name}_entity.php';
         if ($data === null) {
             if ($this->_${entity.name} === null) {
-                $this->_${entity.name} = new ${entity.Name}Entity($this, null);
+                $this->_${entity.name} = new ${cls}($this, null);
             }
             return $this->_${entity.name};
         }
-        return new ${entity.Name}Entity($this, $data);
+        return new ${cls}($this, $data);
     }
 
 `)

package/project/.sdk/src/cmp/php/ReadmeHowto_php.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, getModelPath, nom } from '@voxgig/apidef'
 
@@ -18,13 +18,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 && 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
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
@@ -43,6 +43,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testCallArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(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
+    ? `// Entity ops return the bare mock record (throws on error).
+$${eName.toLowerCase()} = $client->${eName}()->${primaryOp}(${testCallArg});
+print_r($${eName.toLowerCase()});`
+    : `$result = $client->direct(["path" => "/api/resource", "method" => "GET"]);
+print_r($result);`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -93,9 +102,7 @@ Create a mock client for unit testing — no server required${seedSentence}:
 \`\`\`php
 $client = ${testCtor};
 
-// Entity ops return the bare mock record (throws on error).
-$${eName.toLowerCase()} = $client->${eName}()->${primaryOp}(${testCallArg});
-print_r($${eName.toLowerCase()});
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function