@voxgig/sdkgen 1.2.0 → 1.3.1

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,40 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  // Model-driven op rows for the shared entity interface: emit a
+  // load/list/create/update/remove row only for operations at least one active
+  // entity actually exposes (a read-only entity has just list+load) — never
+  // document an operation no entity has.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `load` | `(reqmatch, ctrl) -> any, err` | Load a single entity by match criteria. |',
+    list: '| `list` | `(reqmatch, ctrl) -> any, err` | List entities matching the criteria. |',
+    create: '| `create` | `(reqdata, ctrl) -> any, err` | Create a new entity. |',
+    update: '| `update` | `(reqdata, ctrl) -> any, err` | Update an existing entity. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> any, err` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  // Model-driven Result-shape rows: only describe the operations that
+  // actually exist. Record-returning ops (load/create/update/remove) share
+  // one row; list has its own — never name a missing op.
+  const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
+    .map((o) => '`' + o + '`')
+  const resultRows: string[] = []
+  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity record (a `table`) |')
+  if (opUnion.has('list')) resultRows.push('| `list` | an array (`table`) of entity records |')
+  const resultShapeRows = resultRows.join('\n')
+
+  const exEnt: any = entityList[0] || {}
+  const eName = exEnt.Name || 'Entity'
+  const eLower = String(exEnt.name || 'entity').toLowerCase()
+  // Model-driven id key: null when the example entity has no id-like field, so
+  // the Result-shape load illustration takes no match argument.
+  const idF = entityIdField(exEnt)
+
   const apikeyOptionRow = isAuthActive(model)
     ? '| `apikey` | `string` | API key for authentication. |\n'
     : ''
@@ -54,7 +88,8 @@ Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -65,11 +100,7 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`(reqmatch, ctrl) -> any, err\` | Load a single entity by match criteria. |
-| \`list\` | \`(reqmatch, ctrl) -> any, err\` | List entities matching the criteria. |
-| \`create\` | \`(reqdata, ctrl) -> any, err\` | Create a new entity. |
-| \`update\` | \`(reqdata, ctrl) -> any, err\` | Update an existing entity. |
-| \`remove\` | \`(reqmatch, ctrl) -> any, err\` | Remove an entity. |
+${opRows}
 | \`data_get\` | \`() -> table\` | Get entity data. |
 | \`data_set\` | \`(data)\` | Set entity data. |
 | \`match_get\` | \`() -> table\` | Get entity match criteria. |
@@ -79,17 +110,21 @@ All entities share the same interface.
 
 ### Result shape
 
-Entity operations return \`(any, err)\`. The first value is a
-\`table\` with these keys:
+Entity operations return \`(value, err)\`. The \`value\` is the operation's
+data **directly** — there is no wrapper:
 
-| Key | Type | Description |
-| --- | --- | --- |
-| \`ok\` | \`boolean\` | \`true\` if the HTTP status is 2xx. |
-| \`status\` | \`number\` | HTTP status code. |
-| \`headers\` | \`table\` | Response headers. |
-| \`data\` | \`any\` | Parsed JSON response body. |
+| Operation | \`value\` |
+| --- | --- |
+${resultShapeRows}
+
+Check \`err\` first (it is non-\`nil\` on failure), then use \`value\`:
+
+    local ${eLower}, err = client:${eName}():load(${idF ? `{ ${idF} = "example_id" }` : ''})
+    if err then error(err) end
+    -- ${eLower} is the loaded record
 
-On error, \`ok\` is \`false\` and \`err\` contains the error value.
+Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
+\`status\`, \`headers\`, and \`data\` keys.
 
 `)
 

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

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ local client = sdk.new({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`  ${option.name} = os.getenv("${model.NAME}_APIKEY"),
+      Content(`  ${option.name} = os.getenv("${envName(model)}_APIKEY"),
 `)
     }
     else {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,36 +18,62 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     e.active !== false && e.ancestors && e.ancestors.length > 0
   ) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey = os.getenv("${model.NAME}_APIKEY"),\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `sdk.new({\n  apikey = os.getenv("${envName(model)}_APIKEY"),\n})`
+    : `sdk.new()`
 
   Content(`### 1. Create a client
 
 \`\`\`lua
 local sdk = require("${model.name}_sdk")
 
-local client = sdk.new({${apikeyArg}})
+local client = ${ctor}
 \`\`\`
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? "an" : "a"
     const opnames = Object.keys(exampleEntity.op || {})
+    // 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
+    // on an id it does not carry as data, so a record id read (`item["id"]`,
+    // `created["id"]`) must be guarded on this, not the match key.
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
+
+    // MODEL-DRIVEN display field: the list example must reference a field
+    // the entity actually has, not a hardcoded "name". Pick the entity's
+    // first non-id string field (falling back to the first non-id field of
+    // any type). The id key stays `id` — the SDK renames every id param to
+    // `id`, matching the load example and the seeded test fixture.
+    const idNames = new Set<string>(['id',
+      (exampleEntity.id && exampleEntity.id.field) || 'id'])
+    const fields: any[] = Array.isArray(exampleEntity.fields) ? exampleEntity.fields : []
+    const isStringField = (f: any) =>
+      f && typeof f.type === 'string' && /STRING/i.test(f.type)
+    const displayFieldObj =
+      fields.find((f: any) => f && !idNames.has(f.name) && isStringField(f)) ||
+      fields.find((f: any) => f && !idNames.has(f.name))
+    const displayField = displayFieldObj ? displayFieldObj.name : null
+    const idCol = dataIdF ? `item["${dataIdF}"]` : null
+    const dispCol = displayField ? `item["${displayField}"]` : null
+    const printCols = [idCol, dispCol].filter(Boolean).join(', ')
+    const printLine = printCols ? `  print(${printCols})` : `  print(item)`
 
     if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
+      Content(`### 2. List ${eName.toLowerCase()} records
+
+Entity operations return \`(value, err)\`. For \`list\`, \`value\` is the
+array of records itself — iterate it directly (there is no wrapper).
 
 \`\`\`lua
-local result, err = client:${eName}(nil):list(nil, nil)
+local ${eName.toLowerCase()}s, err = client:${eName}():list()
 if err then error(err) end
 
-if type(result) == "table" then
-  for _, item in ipairs(result) do
-    local d = item:data_get()
-    print(d["id"], d["name"])
-  end
+for _, item in ipairs(${eName.toLowerCase()}s) do
+${printLine}
 end
 \`\`\`
 
@@ -55,17 +81,50 @@ end
     }
 
     if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`\`\`lua
-local result, err = client:${eName}(nil):load({ id = "example_id" }, nil)
+local ${eName.toLowerCase()}, err = client:${eName}():load(${idF ? `{ ${idF} = "example_id" }` : ''})
 if err then error(err) end
-print(result)
+print(${eName.toLowerCase()})
 \`\`\`
 
 `)
     }
 
+    // Model-driven example fields: derive the create/update body from the op
+    // shape (opRequestShape) so the docs reference REAL writable fields, not a
+    // hardcoded "name" the entity may not have. Literals are Lua-typed by the
+    // field's canonical type; non-identifier keys use bracket syntax.
+    const luaLit = (type: any): string => {
+      const k = canonKey(type)
+      if ('INTEGER' === k || 'NUMBER' === k) return '1'
+      if ('BOOLEAN' === k) return 'true'
+      if ('ARRAY' === k || 'OBJECT' === k) return '{}'
+      return '"example"'
+    }
+    const luaKey = (name: string): string =>
+      /^[A-Za-z_]\w*$/.test(name) ? name : `["${name}"]`
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => !idNames.has(it.name))
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : items.slice(0, 2)
+      return chosen.map((it: any) => `${luaKey(it.name)} = ${luaLit(it.type)}`)
+    }
+
+    // The id VALUE for an update/remove match: off the returned `created` record
+    // only when its data type carries the id AND a create ran, else a literal.
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `created["${dataIdF}"]`
+      : luaLit(idParamType(opname))
+
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
@@ -73,19 +132,21 @@ print(result)
 `)
       if (opnames.includes('create')) {
         Content(`-- Create
-local created, _ = client:${eName}(nil):create({ name = "Example" }, nil)
+local created, err = client:${eName}():create({ ${examplePairs('create').join(', ')} })
+if err then error(err) end
 
 `)
       }
       if (opnames.includes('update')) {
+        const updatePairs = (idF ? [`${idF} = ${idValueFor('update')}`] : []).concat(examplePairs('update'))
         Content(`-- Update
-client:${eName}(nil):update({ id = created["id"], name = "Example-Renamed" }, nil)
+client:${eName}():update({ ${updatePairs.join(', ')} })
 
 `)
       }
       if (opnames.includes('remove')) {
         Content(`-- Remove
-client:${eName}(nil):remove({ id = created["id"] }, nil)
+client:${eName}():remove(${idF ? `{ ${idF} = ${idValueFor('remove')} }` : ''})
 `)
       }
       Content(`\`\`\`

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -71,8 +71,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`table\` | SDK configuration options. |
-| \`options.apikey\` | \`string\` | API key for authentication. |
-| \`options.base\` | \`string\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`options.apikey\` | \`string\` | API key for authentication. |\n' : ''}| \`options.base\` | \`string\` | Base URL for API requests. |
 | \`options.prefix\` | \`string\` | URL prefix appended after base. |
 | \`options.suffix\` | \`string\` | URL suffix appended after path. |
 | \`options.headers\` | \`table\` | Custom headers for all requests. |
@@ -87,12 +86,12 @@ Create a new SDK client instance.
 
 `)
 
-    Content(`#### \`sdk.test(testopts, sdkopts)\`
+    Content(`#### \`sdk.test(testopts?, sdkopts?)\`
 
-Create a test client with mock features active. Both arguments may be \`nil\`.
+Create a test client with mock features active. Both arguments are optional.
 
 \`\`\`lua
-local client = sdk.test(nil, nil)
+local client = sdk.test()
 \`\`\`
 
 `)
@@ -154,6 +153,9 @@ same parameters as \`direct()\`.
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = 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)
 
       Content(`
 ---
@@ -185,7 +187,7 @@ local ${ent.name} = client:${ent.Name}(nil)
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -195,15 +197,18 @@ local ${ent.name} = client:${ent.Name}(nil)
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
+          // Only emit columns for operations this entity actually exposes —
+          // never advertise a create/update/remove column the entity lacks.
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -238,39 +243,39 @@ ${info.desc}
           // Show example
           if ('load' === opname || 'remove' === opname) {
             Content(`\`\`\`lua
-local result, err = client:${ent.Name}(nil):${opname}({ id = "${ent.name}_id" }, nil)
+local result, err = client:${ent.Name}():${opname}(${idF ? `{ ${idF} = "${ent.name}_id" }` : ''})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`lua
-local results, err = client:${ent.Name}(nil):list(nil, nil)
+local results, err = client:${ent.Name}():list()
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
             Content(`\`\`\`lua
-local result, err = client:${ent.Name}(nil):create({
+local result, err = client:${ent.Name}():create({
 `)
             each(fields, (field: any) => {
               if ('id' !== field.name && field.req) {
-                Content(`  ${field.name} = --[[ ${field.type || 'value'} ]],
+                Content(`  ${field.name} = --[[ ${canonToType(field.type, target.name)} ]],
 `)
               }
             })
-            Content(`}, nil)
+            Content(`})
 \`\`\`
 
 `)
           }
           else if ('update' === opname) {
+            const updateIdLine = idF ? `  ${idF} = "${ent.name}_id",\n` : ''
             Content(`\`\`\`lua
-local result, err = client:${ent.Name}(nil):update({
-  id = "${ent.name}_id",
-  -- Fields to update
-}, nil)
+local result, err = client:${ent.Name}():update({
+${updateIdLine}  -- Fields to update
+})
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -15,34 +15,42 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey = os.getenv("${model.NAME}_APIKEY"),\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `sdk.new({\n  apikey = os.getenv("${envName(model)}_APIKEY"),\n})`
+    : `sdk.new()`
 
   Content(`\`\`\`lua
 local sdk = require("${model.name}_sdk")
 
-local client = sdk.new({${apikeyArg}})
+local client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
       Content(`-- List all ${eName.toLowerCase()}s
-local ${eName.toLowerCase()}s, err = client:${eName}(nil):list(nil, nil)
+local ${eName.toLowerCase()}s, err = client:${eName}():list()
+print(${eName.toLowerCase()}s)
 `)
+      hasCall = true
     }
 
     if (opnames.includes('load')) {
       Content(`
 -- Load a specific ${eName.toLowerCase()}
-local ${eName.toLowerCase()}, err = client:${eName}(nil):load(
-  { id = "example_id" }, nil
-)
+local ${eName.toLowerCase()}, err = client:${eName}():load(${idF ? `{ ${idF} = "example_id" }` : ''})
+print(${eName.toLowerCase()})
 `)
+      hasCall = true
     }
   }
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,20 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Lua literal for a field's canonical type.
+function luaLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '{}'
+  return '"example"'
+}
+
+function luaKey(name: string): string {
+  return /^[A-Za-z_]\w*$/.test(name) ? name : `["${name}"]`
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -16,14 +30,27 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   Content(`\`\`\`lua
-local client = sdk.test(nil, nil)
+local client = sdk.test()
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`local result, err = client:${eName}(nil):load(
-  { id = "test01" }, nil
-)
+    // 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) {
+      arg = idF ? `{ ${idF} = "test01" }` : ''
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = `{ ${chosen.map((it: any) => `${luaKey(it.name)} = ${luaLit(it.type)}`).join(', ')} }`
+    }
+    Content(`local result, err = client:${eName}():${primaryOp}(${arg})
 `)
   }
 

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

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_lua'
 import { TestDirect } from './TestDirect_lua'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_lua'
 
 
 const Test = cmp(function Test(props: any) {
@@ -40,6 +41,9 @@ end)
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // README ```lua example snippets: syntax-check + offline run.
+    ReadmeExamplesTest({ target })
   })
 })
 

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

@@ -5,6 +5,10 @@ local entityCreateOp = {}
 
 -- EJECT-START
 
+---@param reqdata EntityNameCreateData
+---@param ctrl? table
+---@return EntityName
+---@return string? err
 function EntityNameEntity:create(reqdata, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({

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

@@ -2,6 +2,10 @@ local entityListOp = {}
 
 -- EJECT-START
 
+---@param reqmatch EntityNameListMatch
+---@param ctrl? table
+---@return EntityName[]
+---@return string? err
 function EntityNameEntity:list(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({

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

@@ -5,6 +5,10 @@ local entityLoadOp = {}
 
 -- EJECT-START
 
+---@param reqmatch EntityNameLoadMatch
+---@param ctrl? table
+---@return EntityName
+---@return string? err
 function EntityNameEntity:load(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({

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

@@ -5,6 +5,10 @@ local entityRemoveOp = {}
 
 -- EJECT-START
 
+---@param reqmatch EntityNameRemoveMatch
+---@param ctrl? table
+---@return EntityName
+---@return string? err
 function EntityNameEntity:remove(reqmatch, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({

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

@@ -5,6 +5,10 @@ local entityUpdateOp = {}
 
 -- EJECT-START
 
+---@param reqdata EntityNameUpdateData
+---@param ctrl? table
+---@return EntityName
+---@return string? err
 function EntityNameEntity:update(reqdata, ctrl)
   local utility = self._utility
   local ctx = utility.make_context({