@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/ts/ReadmeRef_ts.ts

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
@@ -70,8 +72,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`object\` | 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\` | \`object\` | Custom headers for all requests. |
@@ -180,6 +181,11 @@ Alias for \`${model.Name}SDK.test()\`.
     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)
+      // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+      const eVar = safeVarName(ent.name, target.name)
 
       Content(`
 ---
@@ -195,7 +201,7 @@ Alias for \`${model.Name}SDK.test()\`.
       }
 
       Content(`\`\`\`ts
-const ${ent.name} = client.${ent.Name}()
+const ${eVar} = client.${ent.Name}()
 \`\`\`
 
 `)
@@ -211,7 +217,7 @@ const ${ent.name} = client.${ent.Name}()
         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} |
 `)
         })
 
@@ -221,15 +227,18 @@ const ${ent.name} = client.${ent.Name}()
         // 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 '-'
@@ -263,8 +272,20 @@ ${info.desc}
 
           // Show example
           if ('load' === opname || 'remove' === opname) {
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape that generates <Name><Op>Match,
+            // so the example always type-checks.
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `{ ${matchItems.map((it: any) =>
+                `${it.name}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().${opname}({ id: '${ent.name}_id' })
+const result = await client.${ent.Name}().${opname}(${arg})
 \`\`\`
 
 `)
@@ -277,14 +298,19 @@ const results = await client.${ent.Name}().${opname}()
 `)
           }
           else if ('create' === opname) {
+            // Members come from the SAME shape that generates
+            // <Name>CreateData: every required member must appear (the
+            // /* type */ placeholders also mark the block as an illustration
+            // for the doc gates); an all-optional create renders an empty —
+            // still assignable — literal.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`  ${field.name}: /* ${field.type || 'value'} */,
+            createItems.map((it: any) => {
+              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-              }
             })
             Content(`})
 \`\`\`
@@ -292,10 +318,18 @@ const result = await client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
+            // The id key plus every REQUIRED data member — the same shape
+            // that generates <Name>UpdateData — then the patch-fields note.
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `  ${it.name}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({
-  id: '${ent.name}_id',
-  // Fields to update
+${updateLines}  // Fields to update
 })
 \`\`\`
 

package/project/.sdk/src/cmp/ts/ReadmeTopHowto_ts.ts

@@ -12,6 +12,9 @@ const result = await client.direct({
   method: 'GET',
   params: { id: 'example' },
 })
+if (result instanceof Error) {
+  throw result
+}
 console.log(result.data)
 \`\`\`
 

package/project/.sdk/src/cmp/ts/ReadmeTopQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -14,45 +16,82 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`\`\`\`ts
-import { ${model.const.Name}SDK } from '${target.module.name}'
+import { ${model.const.Name}SDK } from '${packageName(model, target.name)}'
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
+    const eVar = safeVarName(eName.toLowerCase(), 'ts')
+    const opnames = entityOps(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-const ${eName.toLowerCase()}s = await client.${eName}().list()
+      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}[])
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 `)
+      hasCall = true
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: one with a parent
+    // chain, an active load op of its OWN, and a required non-id load param
+    // to demonstrate (the parent key, e.g. page_id).
     const nestedEntity = Object.values(entity).find((e: any) =>
-      e.active !== false && e.ancestors && e.ancestors.length > 0
+      e.active !== false &&
+      e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+      entityOps(e).includes('load') &&
+      opRequestShape(e, 'load').items.some((it: any) =>
+        !it.optional && it.name !== entityIdField(e))
     ) as any
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+      const neVar = safeVarName(neName.toLowerCase(), 'ts')
+      const loadOp = nestedEntity.op && nestedEntity.op.load
+
+      // Every REQUIRED load-match key (parent keys first, own id last) — the
+      // same shape that generates <Name>LoadMatch, so the example
+      // type-checks.
+      const neIdF = entityIdField(nestedEntity)
+      const neMatchLines = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === neIdF)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `  ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
-// Load a specific ${neName.toLowerCase()}
-const ${neName.toLowerCase()} = await client.${neName}().load({
-  ${parentParam}: 'example',
-  id: 'example_id',
+// Load a specific ${neName.toLowerCase()} (returns a ${neName})
+const ${neVar} = await client.${neName}().load({
+${neMatchLines.join('\n')}
 })
+console.log(${neVar})
+`)
+      hasCall = true
+    }
+
+    // Fallback: APIs with only `load` (no list, no nested) — most public
+    // read-only services. Still show one concrete call. `load()` with no
+    // match is always valid (the match arg is optional).
+    if (!hasCall && opnames.includes('load')) {
+      Content(`// Load ${eName.toLowerCase()} data (returns a ${eName})
+const ${eVar} = await client.${eName}().load()
+console.log(${eVar})
 `)
+      hasCall = true
     }
   }
 

package/project/.sdk/src/cmp/ts/ReadmeTopTest_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
@@ -20,8 +22,38 @@ const client = ${model.const.Name}SDK.test()
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`const result = await client.${eName}().load({ id: 'test01' })
-// result.ok === true, result.data contains mock data
+    // 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(), 'ts') +
+      ('list' === primaryOp ? 's' : '')
+    const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
+    const idF = entityIdField(exampleEntity)
+    let arg = ''
+    if ('load' === primaryOp || 'remove' === primaryOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's Match type, so the block type-checks.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+    } 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) =>
+        `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
+    }
+    Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
+// ${eVar} is ${'list' === primaryOp ? `an array of bare ${eName} records` : `a bare ${eName}`} populated with mock data
+console.log(${eVar})
 `)
   }
 

package/project/.sdk/src/cmp/ts/TestEntity_ts.ts

@@ -398,7 +398,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
       const fieldvalue = spec.def.mark
       Content(`
     const ${markdefvar} = { name: '${fieldname}', value: '${fieldvalue}_' + setup.now }
-    ${datavar} [${markdefvar}.name] = ${markdefvar}.value
+    ;(${datavar} as any)[${markdefvar}.name] = ${markdefvar}.value
 `)
     }
   }
@@ -419,7 +419,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
     const spec = step.spec[sI]
     if ('TextFieldMark' === spec.apply && null != step.input.textfield) {
       Content(`
-    assert(${resdatavar}[${markdefvar}.name] === ${markdefvar}.value)
+    assert((${resdatavar} as any)[${markdefvar}.name] === ${markdefvar}.value)
 `)
     }
   }

package/project/.sdk/src/cmp/ts/Test_ts.ts

@@ -15,6 +15,8 @@ import { cmp, each, Folder } from '@voxgig/sdkgen'
 // import { TestMain } from './TestMain_ts'
 import { TestDirect } from './TestDirect_ts'
 import { TestEntity } from './TestEntity_ts'
+import { ReadmeExampleTest } from './ReadmeExampleTest_ts'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_ts'
 
 
 const Test = cmp(function Test(props: any) {
@@ -25,6 +27,9 @@ const Test = cmp(function Test(props: any) {
     // Quick({ target })
     // TestMain({ target })
 
+    ReadmeExampleTest({ target })
+    ReadmeExamplesTest({ target })
+
     Folder({ name: 'entity' }, () => {
       each(model.main[KIT].entity, (entity: ModelEntity) => {
         TestEntity({ target, entity })

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

@@ -14,9 +14,11 @@ import type {
   Control,
 } from '../types'
 
+// #TypeImports
+
 
 // TODO: needs Entity superclass
-class EntityNameEntity extends ProjectNameEntityBase {
+class EntityNameEntity extends ProjectNameEntityBase<EntityName> {
 
   constructor(client: ProjectNameSDK, entopts: any) {
     super(client, entopts)

package/project/.sdk/src/cmp/ts/fragment/EntityBase.fragment.ts

@@ -15,7 +15,9 @@ import type {
 
 
 // TODO: needs Entity superclass
-class ProjectNameEntityBase {
+// `D` is the entity's typed data model (e.g. Advice); subclasses bind it via
+// `class AdviceEntity extends ProjectNameEntityBase<Advice>`.
+class ProjectNameEntityBase<D = any> {
   name = ''
   name_ = ''
   Name = ''
@@ -23,8 +25,11 @@ class ProjectNameEntityBase {
   _client: ProjectNameSDK
   _utility: Utility
   _entopts: any
-  _data: any
-  _match: any
+  // `_data`/`_match` hold accreted partial state (they start `{}` and fill in
+  // as ops resolve), so they are `Partial<D>` — the full `D` is only asserted
+  // at the `data()` return boundary.
+  _data: Partial<D>
+  _match: Partial<D>
   _entctx: Context
 
 
@@ -58,7 +63,7 @@ class ProjectNameEntityBase {
   }
 
 
-  data(this: any, data?: any) {
+  data(this: any, data?: Partial<D>): D {
     const struct = this._utility.struct
     const featureHook = this._utility.featureHook
 
@@ -74,7 +79,7 @@ class ProjectNameEntityBase {
   }
 
 
-  match(match?: any) {
+  match(this: any, match?: Partial<D>): Partial<D> {
     const struct = this._utility.struct
     const featureHook = this._utility.featureHook
 

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

@@ -10,7 +10,7 @@ class EntityOperation {
 
   // EJECT-START
 
-  async create(this: any, reqdata?: any, ctrl?: Control) {
+  async create(this: any, reqdata?: EntityNameCreateData, ctrl?: Control): Promise<EntityName> {
 
     const utility = this._utility
     const {
@@ -95,7 +95,9 @@ class EntityOperation {
         throw err
       }
       else {
-        return undefined
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntityName> return stays clean under strict null checks.
+        return undefined as any
       }
     }
   }

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

@@ -10,7 +10,7 @@ class EntityOperation {
 
   // EJECT-START
 
-  async list(this: any, reqmatch?: any, ctrl?: Control) {
+  async list(this: any, reqmatch?: EntityNameListMatch, ctrl?: Control): Promise<EntityName[]> {
 
     const utility = this._utility
 
@@ -96,7 +96,9 @@ class EntityOperation {
         throw err
       }
       else {
-        return undefined
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntityName[]> return stays clean under strict null checks.
+        return undefined as any
       }
     }
   }

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

@@ -10,7 +10,7 @@ class EntityOperation {
 
   // EJECT-START
 
-  async load(this: any, reqmatch?: any, ctrl?: Control) {
+  async load(this: any, reqmatch?: EntityNameLoadMatch, ctrl?: Control): Promise<EntityName> {
 
     const utility = this._utility
 
@@ -100,7 +100,9 @@ class EntityOperation {
         throw err
       }
       else {
-        return undefined
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntityName> return stays clean under strict null checks.
+        return undefined as any
       }
     }
   }

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

@@ -10,7 +10,7 @@ class EntityOperation {
 
   // EJECT-START
 
-  async remove(this: any, reqmatch?: any, ctrl?: Control) {
+  async remove(this: any, reqmatch?: EntityNameRemoveMatch, ctrl?: Control): Promise<EntityName> {
 
     const utility = this._utility
 
@@ -101,7 +101,9 @@ class EntityOperation {
         throw err
       }
       else {
-        return undefined
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntityName> return stays clean under strict null checks.
+        return undefined as any
       }
     }
   }

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

@@ -10,7 +10,7 @@ class EntityOperation {
 
   // EJECT-START
 
-  async update(this: any, reqdata?: any, ctrl?: Control) {
+  async update(this: any, reqdata?: EntityNameUpdateData, ctrl?: Control): Promise<EntityName> {
 
     const utility = this._utility
 
@@ -101,7 +101,9 @@ class EntityOperation {
         throw err
       }
       else {
-        return undefined
+        // Off-happy-path (throw disabled): typed as any so the method's
+        // Promise<EntityName> return stays clean under strict null checks.
+        return undefined as any
       }
     }
   }

package/project/.sdk/src/cmp/ts/utility_ts.ts

@@ -2,12 +2,70 @@
 import * as Path from 'node:path'
 
 
+import {
+  canonKey,
+  each,
+} from '@voxgig/sdkgen'
+
 import {
   clone,
   walk,
 } from '@voxgig/struct'
 
 
+// --- Model-driven example literals -----------------------------------------
+// Doc snippets must use example values whose TYPE matches the generated
+// TypeScript types, or the snippet does not compile. The id/match params of
+// load/remove/update are the common trap: their generated
+// `<Name><Op>Match` / `<Name><Op>Data` type is built from the op's params
+// (see EntityTypes_ts.ts), so a `number` id shown as a quoted string is a
+// TS2322 error. These helpers derive the example literal from the SAME model
+// source, so the docs and the generated types can never disagree.
+
+// The declared canon-type sentinel of a named parameter of an op — looked up
+// in the op's `points[].args.params[]` exactly as the typed-model generator
+// does. Falls back to the entity field of the same name (used when the op
+// has no params and the generated match type is `Partial<Entity>`). Returns
+// undefined when neither is present.
+function paramCanonType(entity: any, op: any, paramName: string): unknown {
+  const points = op && op.points ? each(op.points) : []
+  for (const pt of points as any[]) {
+    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const found = (params as any[]).find((p: any) => p && p.name === paramName)
+    if (found) {
+      return found.type
+    }
+  }
+  const field = (entity && entity.fields ? each(entity.fields) : [])
+    .find((f: any) => f && f.name === paramName) as any
+  return field && field.type
+}
+
+
+// A type-correct example literal for a named match/data parameter of an op,
+// derived entirely from the model. INTEGER/NUMBER render as the bare number
+// `1` (a quoted string on a `number` field is a compile error), BOOLEAN as
+// `true`, ARRAY as the empty `[]` and OBJECT as the empty `{}` (a quoted
+// string is not assignable to `any[]` / `Record<string, any>`), everything
+// else (STRING, unknown, missing) as the quoted `placeholder`.
+function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
+  const key = canonKey(paramCanonType(entity, op, paramName))
+  if ('INTEGER' === key || 'NUMBER' === key) {
+    return '1'
+  }
+  if ('BOOLEAN' === key) {
+    return 'true'
+  }
+  if ('ARRAY' === key) {
+    return '[]'
+  }
+  if ('OBJECT' === key) {
+    return '{}'
+  }
+  return `'${placeholder}'`
+}
+
+
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
 }
@@ -61,4 +119,5 @@ export {
   formatJSONSrc,
   formatJson,
   projectPath,
+  exampleValue,
 }

package/project/.sdk/tm/go/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) $$const.year$$ $$const.Name$$
+Copyright (c) $$const.year$$ Voxgig
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/project/.sdk/tm/go/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test build clean
+.PHONY: test build clean publish
 
 test:
 	go test ./... -v
@@ -8,3 +8,38 @@ build:
 
 clean:
 	go clean ./...
+
+# --- Release: tag for the Go module proxy (pkg.go.dev) --------------------
+# Go modules have no registry upload — publishing a version means pushing the
+# tag go/vX.Y.Z (this module is the go/ subdir, and Go's submodule-tag
+# convention is <subdir>/vX.Y.Z), which the module proxy + pkg.go.dev pick up on
+# first fetch. Run headless under the aql key vault, which injects the GitHub
+# token so nothing lands on disk or argv:
+#   aql vault exec --for=github=<alias> -- make publish
+# aql `--dry-run` injects a filler token we detect to rehearse (no tag/push).
+# set -e + tag-last: a failed push never leaves a tag behind.
+#
+# NOTE: publishing the git tag is deliberately NOT gated on `go test` (every
+# other target's deploy just pushes its tag; a generated-test quirk must not
+# block the module tag). Run `make test` separately in CI to gate quality.
+VERSION := $(shell cat VERSION)
+TAG := go/v$(VERSION)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish:
+	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
+	  echo "tag $(TAG) already exists — bump VERSION first"; exit 1; fi
+	@set -e; \
+	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
+	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] aql filler token detected: would tag $(TAG) for pkg.go.dev; nothing pushed."; \
+	  exit 0; \
+	fi; \
+	git tag -a "$(TAG)" -m "go v$(VERSION)"; \
+	url=$$(git remote get-url origin | sed -E 's#^git@github.com:#https://github.com/#'); \
+	if [ -n "$$token" ] && printf '%s' "$$url" | grep -q '^https://github.com/'; then \
+	  hdr="AUTHORIZATION: basic $$(printf 'x-access-token:%s' "$$token" | base64 | tr -d '\n')"; \
+	  git -c http.extraheader="$$hdr" push "$$url" "$(TAG)"; \
+	else \
+	  git push origin "$(TAG)"; \
+	fi; \
+	echo "Tagged $(TAG) for pkg.go.dev."

package/project/.sdk/tm/go/VERSION

@@ -0,0 +1 @@
+0.0.1