@voxgig/sdkgen 1.3.4 → 1.3.5

package/project/.sdk/src/cmp/php/ReadmeTopTest_php.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,
@@ -23,16 +23,15 @@ 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)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
     const ename = eName.toLowerCase()
     // Model-driven id key: null when the entity has no id-like field.
     const idF = entityIdField(exampleEntity)
-    // 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'
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     const recBody = idF ? `["${idF}" => "test01"]` : '[]'
     let callArg = ''

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

@@ -8,7 +8,7 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 use Voxgig\Struct\Struct;
 
-class EntityNameEntity
+class EntyClass
 {
     private string $_name;
     private $_client;
@@ -52,7 +52,7 @@ class EntityNameEntity
     public function make(): self
     {
         $opts = $this->_entopts;
-        return new EntityNameEntity($this->_client, $opts);
+        return new EntyClass($this->_client, $opts);
     }
 
     /**

package/project/.sdk/src/cmp/py/Entity_py.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_py'
 
 
@@ -19,6 +25,13 @@ 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 DATA type stays `<Name>`. The snake-cased source-file
+  // name is unaffected; only the class identifier changes.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -66,6 +79,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.py so the class can be renamed independently.
+          EntyClass: cls,
+
           // Literal-marker slot (jostraca's `#Name` tag pattern is hardcoded to
           // `//` comments, so Python uses a `# #`-prefixed literal like the op
           // frag slots) — fills in the typed-model import for this entity.

package/project/.sdk/src/cmp/py/MainEntity_py.ts

@@ -1,17 +1,27 @@
 
 
-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>(). The
+  // source module is snake-cased, so only the imported class identifier changes.
+  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
+
   Content(`
-    def ${entity.Name}(self, data=None) -> "${entity.Name}Entity":
+    def ${entity.Name}(self, data=None) -> "${cls}":
         """Entity factory: client.${entity.Name}().list() / client.${entity.Name}().load({"id": ...})."""
-        from entity.${entity.name}_entity import ${entity.Name}Entity
-        return ${entity.Name}Entity(self, data)
+        from entity.${entity.name}_entity import ${cls}
+        return ${cls}(self, data)
 
 `)
 

package/project/.sdk/src/cmp/py/Main_py.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'
 
 
@@ -93,7 +94,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
 `)
       each(entity, (ent: any) => {
-        Content(`    from entity.${ent.name}_entity import ${ent.Name}Entity
+        Content(`    from entity.${ent.name}_entity import ${entityClassName(ent, entity)}
 `)
       })
     }

package/project/.sdk/src/cmp/py/ReadmeEntity_py.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,
@@ -58,6 +58,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
+    // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(entity.name, 'py')
 
     Content(`
 ### ${entity.Name}
@@ -70,7 +73,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`${eVar} = client.${entity.Name}()\`
 
 `)
 
@@ -125,7 +128,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`python
-${entity.name} = client.${entity.Name}().load(${loadArg})
+${eVar} = client.${entity.Name}().load(${loadArg})
 \`\`\`
 
 `)
@@ -135,7 +138,7 @@ ${entity.name} = client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`python
-${entity.name}s = client.${entity.Name}().list()
+${eVar}s = client.${entity.Name}().list()
 \`\`\`
 
 `)
@@ -152,7 +155,7 @@ ${entity.name}s = client.${entity.Name}().list()
       Content(`#### Example: Create
 
 \`\`\`python
-${entity.name} = client.${entity.Name}().create({
+${eVar} = client.${entity.Name}().create({
 `)
       createItems.map((it: any) => {
         Content(`    "${it.name}": ${pyLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/py/ReadmeHowto_py.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, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -23,14 +23,17 @@ 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'
+  // Sanitise the local variable name — an entity whose lowercased name is a
+  // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
+  const eVar = safeVarName(eName.toLowerCase(), 'py')
   // Model-driven id key: null when the entity has no id-like field, so a
   // match op takes no argument.
   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 testArg = ''
   if (exampleEntity && isMatchOp) {
@@ -43,6 +46,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testArg = `{${chosen.map((it: any) => `"${it.name}": ${pyLit(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 record and raise on error.
+${eVar} = client.${eName}().${primaryOp}(${testArg})
+# ${eVar} contains the mock response record`
+    : `result = client.direct({"path": "/api/resource", "method": "GET"})
+print(result)`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -90,9 +102,7 @@ Create a mock client for unit testing — no server required:
 \`\`\`python
 client = ${model.const.Name}SDK.test()
 
-# Entity ops return the bare record and raise on error.
-${eName.toLowerCase()} = client.${eName}().${primaryOp}(${testArg})
-# ${eName.toLowerCase()} contains the mock response record
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

package/project/.sdk/src/cmp/py/ReadmeQuick_py.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,
@@ -45,6 +45,9 @@ 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
+    // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(eName.toLowerCase(), 'py')
     const opnames = entityOps(exampleEntity)
     // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
     // null when it has none (a response-wrapped spec). `dataIdF` is the id on
@@ -75,9 +78,9 @@ error — iterate it directly.
 
 \`\`\`python
 try:
-    ${eName.toLowerCase()}s = client.${eName}().list()
-    for ${eName.toLowerCase()} in ${eName.toLowerCase()}s:
-        print(${eName.toLowerCase()})
+    ${eVar}s = client.${eName}().list()
+    for ${eVar} in ${eVar}s:
+        print(${eVar})
 except Exception as err:
     print(f"list failed: {err}")
 \`\`\`
@@ -88,7 +91,7 @@ except Exception as err:
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
-      const neVar = neName.toLowerCase()
+      const neVar = safeVarName(neName.toLowerCase(), 'py')
 
       // Model-driven match: every REQUIRED load-match key — the same shape
       // the runtime resolves path params from, so the example always works.
@@ -140,8 +143,8 @@ except Exception as err:
 
 \`\`\`python
 try:
-    ${eName.toLowerCase()} = client.${eName}().load(${loadArg})
-    print(${eName.toLowerCase()})
+    ${eVar} = client.${eName}().load(${loadArg})
+    print(${eVar})
 except Exception as err:
     print(f"load failed: {err}")
 \`\`\`

package/project/.sdk/src/cmp/py/ReadmeRef_py.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,
@@ -166,6 +166,9 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
       // 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 Python keyword (e.g. `class`) would otherwise emit uncompilable code.
+      const eVar = safeVarName(ent.name, 'py')
 
       Content(`
 ---
@@ -181,7 +184,7 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
       }
 
       Content(`\`\`\`python
-${ent.name} = client.${ent.Name}()
+${eVar} = client.${ent.Name}()
 \`\`\`
 
 `)
@@ -274,8 +277,8 @@ result = client.${ent.Name}().${opname}(${arg})
           else if ('list' === opname) {
             Content(`\`\`\`python
 results = client.${ent.Name}().list()
-for ${ent.name} in results:
-    print(${ent.name})
+for ${eVar} in results:
+    print(${eVar})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/py/ReadmeTopQuick_py.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,
@@ -44,6 +44,9 @@ client = ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    // Sanitise the local variable name — an entity whose lowercased name is a
+    // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(eName.toLowerCase(), 'py')
     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.
@@ -53,9 +56,9 @@ client = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`# List all ${eName.toLowerCase()}s (returns a list, raises on error)
-${eName.toLowerCase()}s = client.${eName}().list()
-for ${eName.toLowerCase()} in ${eName.toLowerCase()}s:
-    print(${eName.toLowerCase()})
+${eVar}s = client.${eName}().list()
+for ${eVar} in ${eVar}s:
+    print(${eVar})
 `)
       hasCall = true
     }
@@ -75,8 +78,8 @@ for ${eName.toLowerCase()} in ${eName.toLowerCase()}s:
         : ''
       Content(`
 # Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
-${eName.toLowerCase()} = client.${eName}().load(${loadArg})
-print(${eName.toLowerCase()})
+${eVar} = client.${eName}().load(${loadArg})
+print(${eVar})
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/py/ReadmeTopTest_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -24,18 +24,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(`\`\`\`python
 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 idF = entityIdField(exampleEntity)
-    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = ''
     if (isMatchOp) {
@@ -59,7 +58,7 @@ client = ${model.const.Name}SDK.test()
     // A list() result is a list — name the variable accordingly (the root
     // README doc gate concatenates blocks, so reusing the singular name for
     // a different type is a mypy assignment error).
-    const eVar = eName.toLowerCase() + ('list' === primaryOp ? 's' : '')
+    const eVar = safeVarName(eName.toLowerCase(), 'py') + ('list' === primaryOp ? 's' : '')
     Content(`${eVar} = client.${eName}().${primaryOp}(${arg})
 print(${eVar})
 `)

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

@@ -7,7 +7,7 @@ from core import helpers
 # #TypeImports
 
 
-class EntityNameEntity:
+class EntyClass:
 
     def __init__(self, client, entopts=None):
         if entopts is None:
@@ -40,7 +40,7 @@ class EntityNameEntity:
         opts = {}
         for k, v in self._entopts.items():
             opts[k] = v
-        return EntityNameEntity(self._client, opts)
+        return EntyClass(self._client, opts)
 
     def data_set(self, args=None):
         if args is not None:

package/project/.sdk/src/cmp/rb/Entity_rb.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_rb'
 
 
@@ -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.rb so the class can be renamed independently.
+          EntyClass: cls,
+
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `utility.feature_hook.call(ctx, "${name}")`),
 

package/project/.sdk/src/cmp/rb/MainEntity_rb.ts

@@ -1,17 +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(`
   # Canonical facade: client.${entity.Name}.list / client.${entity.Name}.load({ "id" => ... })
   def ${entity.Name}(data = nil)
     require_relative 'entity/${entity.name}_entity'
-    ${entity.Name}Entity.new(self, data)
+    ${cls}.new(self, data)
   end
 
 `)

package/project/.sdk/src/cmp/rb/ReadmeEntity_rb.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,
@@ -56,6 +56,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
+    // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(entity.name, 'rb')
 
     Content(`
 ### ${entity.Name}
@@ -68,7 +71,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`${entity.name} = client.${entity.Name}\`
+    Content(`Create an instance: \`${eVar} = client.${entity.Name}\`
 
 `)
 
@@ -124,7 +127,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
 \`\`\`ruby
 # load returns the bare ${entity.Name} record (raises on error).
-${entity.name} = client.${entity.Name}.load(${loadArg})
+${eVar} = client.${entity.Name}.load(${loadArg})
 \`\`\`
 
 `)
@@ -135,7 +138,7 @@ ${entity.name} = client.${entity.Name}.load(${loadArg})
 
 \`\`\`ruby
 # list returns an Array of ${entity.Name} records (raises on error).
-${entity.name}s = client.${entity.Name}.list
+${eVar}s = client.${entity.Name}.list
 \`\`\`
 
 `)
@@ -152,7 +155,7 @@ ${entity.name}s = client.${entity.Name}.list
       Content(`#### Example: Create
 
 \`\`\`ruby
-${entity.name} = client.${entity.Name}.create({
+${eVar} = client.${entity.Name}.create({
 `)
       createItems.map((it: any) => {
         Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/rb/ReadmeHowto_rb.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, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -23,15 +23,20 @@ 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'
+  // Sanitise the local variable name — an entity whose lowercased name is a
+  // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code. The
+  // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
+  // entity's registered name for the mock lookup to resolve.
+  const eVar = safeVarName(eName.toLowerCase(), 'rb')
   // Model-driven id key: null when the entity has no id-like field (a
   // response-wrapped spec). When null the fixture seeds no id and a match op
   // takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
-  // Drive the test-mode example 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 isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
@@ -52,6 +57,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testCallArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(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 (raises on error).
+${eVar} = client.${eName}.${primaryOp}(${testCallArg})
+puts ${eVar}`
+    : `result = client.direct({ "path" => "/api/resource", "method" => "GET" })
+puts result`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -101,9 +115,7 @@ Create a mock client for unit testing — no server required${seedSentence}:
 \`\`\`ruby
 client = ${testCtor}
 
-# Entity ops return the bare mock record (raises on error).
-${eName.toLowerCase()} = client.${eName}.${primaryOp}(${testCallArg})
-puts ${eName.toLowerCase()}
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

package/project/.sdk/src/cmp/rb/ReadmeQuick_rb.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 @@ 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
+    // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(eName.toLowerCase(), 'rb')
     const opnames = entityOps(exampleEntity)
     // Model-driven id keys: `idF` is the load-MATCH key (null when the entity
     // has no id-like field — a response-wrapped spec); when null, load/remove
@@ -84,8 +87,8 @@ client = ${ctor}
 \`\`\`ruby
 begin
   # list returns an Array of ${eName} records — iterate directly.
-  ${eName.toLowerCase()}s = client.${eName}.list
-  ${eName.toLowerCase()}s.each do |item|
+  ${eVar}s = client.${eName}.list
+  ${eVar}s.each do |item|
     puts "${itemPrint}"
   end
 rescue => err
@@ -99,7 +102,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(), 'rb')
 
       // Model-driven match: every REQUIRED load-match key — the same shape
       // the runtime resolves path params from, so the example always works.
@@ -151,8 +154,8 @@ end
 \`\`\`ruby
 begin
   # load returns the bare ${eName} record (raises on error).
-  ${eName.toLowerCase()} = client.${eName}.load(${loadArg})
-  puts ${eName.toLowerCase()}
+  ${eVar} = client.${eName}.load(${loadArg})
+  puts ${eVar}
 rescue => err
   warn "load failed: #{err}"
 end