@voxgig/sdkgen 1.2.1 → 1.3.1

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,26 @@ 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
+    const eVar = safeVarName(eName.toLowerCase(), 'ts')
+    // 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 primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
+    const idF = entityIdField(exampleEntity)
+    let arg = ''
+    if ('load' === primaryOp || 'remove' === primaryOp) {
+      arg = idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, 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) =>
+        `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
+    }
+    Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
+// ${eVar} is 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

package/project/.sdk/tm/go/core/context.go

@@ -217,7 +217,17 @@ func NewContext(ctxmap map[string]any, basectx *Context) *Context {
 }
 
 func (ctx *Context) resolveOp(opname string) *Operation {
-	if op, ok := ctx.Opmap[opname]; ok && op != nil {
+	// Cache key is `<entity>:<opname>` so two entities with the same op
+	// (e.g. both have a "list") get distinct cached Operations. Keying on
+	// opname alone caused the first-resolved entity's points to be served
+	// to every subsequent entity's call.
+	entname := ""
+	if ctx.Entity != nil {
+		entname = ctx.Entity.GetName()
+	}
+	cacheKey := entname + ":" + opname
+
+	if op, ok := ctx.Opmap[cacheKey]; ok && op != nil {
 		return op
 	}
 
@@ -225,11 +235,6 @@ func (ctx *Context) resolveOp(opname string) *Operation {
 		return NewOperation(map[string]any{})
 	}
 
-	entname := ""
-	if ctx.Entity != nil {
-		entname = ctx.Entity.GetName()
-	}
-
 	opcfg := vs.GetPath([]any{"entity", entname, "op", opname}, ctx.Config)
 
 	input := "match"
@@ -258,7 +263,7 @@ func (ctx *Context) resolveOp(opname string) *Operation {
 		"points": targets,
 	})
 
-	ctx.Opmap[opname] = op
+	ctx.Opmap[cacheKey] = op
 	return op
 }
 

package/project/.sdk/tm/go-cli/src/feature/README.md

@@ -0,0 +1,6 @@
+# go-cli features
+
+The go-cli target does not generate per-feature source. Features are
+applied to the sibling Go SDK by the `go` target; the CLI consumes
+that SDK as a single dependency. This file exists only to satisfy
+the standard tm/<target>/src/feature/ folder convention.

package/project/.sdk/tm/go-mcp/src/feature/README.md

@@ -0,0 +1,6 @@
+# go-cli features
+
+The go-cli target does not generate per-feature source. Features are
+applied to the sibling Go SDK by the `go` target; the CLI consumes
+that SDK as a single dependency. This file exists only to satisfy
+the standard tm/<target>/src/feature/ folder convention.

package/project/.sdk/tm/js/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/js/Makefile

@@ -0,0 +1,41 @@
+.PHONY: test build clean publish
+
+test:
+	npm test
+
+build:
+	@echo "No build step for JavaScript"
+
+clean:
+	rm -rf node_modules
+
+# --- Release: publish to npm ----------------------------------------------
+# Publish this package to npm, then tag js/vX.Y.Z. Run headless under the aql
+# key vault, which injects the npm auth token + the GitHub token (never on disk
+# or argv):
+#   aql vault exec --for=npm=<alias> --for=github=<alias> -- make publish
+# aql `--dry-run` injects a filler token we detect to rehearse (no publish/tag).
+# set -e + tag-last: a failed publish never leaves a tag behind.
+SHELL := /bin/bash
+VERSION := $(shell node -p "require('./package.json').version")
+TAG := js/v$(VERSION)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish: test
+	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
+	  echo "tag $(TAG) already exists — bump package.json 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 publish to npm and tag $(TAG); nothing pushed."; \
+	  exit 0; \
+	fi; \
+	npm publish --access public --registry https://registry.npmjs.org; \
+	git tag -a "$(TAG)" -m "js 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 "Published to npm + tag $(TAG)."

package/project/.sdk/tm/lua/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/lua/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test build clean
+.PHONY: test build clean publish
 
 test:
 	busted -p _test test/
@@ -8,3 +8,42 @@ build:
 
 clean:
 	@echo "No clean step for Lua"
+
+# --- Release: publish to LuaRocks -----------------------------------------
+# Upload the rockspec to LuaRocks, then tag lua/vX.Y.Z. LuaRocks has no aql
+# recipe, so inject its API key + the GitHub token as custom env vars
+# (all-positional — aql cannot mix --for recipes with positional env):
+#   aql vault exec '<alias>=LUAROCKS_API_KEY,<gh-alias>=GITHUB_TOKEN' -- make publish
+# --skip-pack uploads only the rockspec (its git+https source is fetched at the
+# lua/vX.Y.Z tag on install; that tag is pushed in the LAST step, so we must not
+# pack here). LuaRocks requires the rockspec filename to be
+# <package>-<version>.rockspec, so we upload a canonically-named copy. aql
+# `--dry-run` rehearses (no upload/tag). set -e + tag-last: a failed upload
+# never leaves a tag behind.
+VERSION := $(shell sed -nE 's/^version *= *"([0-9.]+).*/\1/p' *.rockspec | head -1)
+TAG := lua/v$(VERSION)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish: test
+	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
+	  echo "tag $(TAG) already exists — bump the rockspec version first"; exit 1; fi
+	@set -e; \
+	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
+	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ] || [ "$$LUAROCKS_API_KEY" = "$(AQL_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] aql filler token detected: would upload to LuaRocks and tag $(TAG); nothing pushed."; \
+	  exit 0; \
+	fi; \
+	rock=$$(ls *.rockspec | head -1); \
+	pkg=$$(sed -nE 's/^package *= *"([^"]+)".*/\1/p' "$$rock" | head -1); \
+	rev=$$(sed -nE 's/^version *= *"([^"]+)".*/\1/p' "$$rock" | head -1); \
+	cp "$$rock" "$$pkg-$$rev.rockspec"; \
+	luarocks upload --skip-pack "$$pkg-$$rev.rockspec" --temp-key="$$LUAROCKS_API_KEY"; \
+	rm -f "$$pkg-$$rev.rockspec"; \
+	git tag -a "$(TAG)" -m "lua 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 "Published to LuaRocks + tag $(TAG)."

package/project/.sdk/tm/lua/core/context.lua

@@ -160,17 +160,22 @@ end
 
 
 function Context:resolve_op(opname)
-  if self.opmap[opname] ~= nil then
-    return self.opmap[opname]
+  -- Cache key is `<entity>:<opname>` so two entities with the same op
+  -- (e.g. both have a "list") get distinct cached Operations. Keying
+  -- on opname alone caused the first-resolved entity's points to be
+  -- served to every subsequent entity's call.
+  local entname = "_"
+  if self.entity ~= nil and type(self.entity.get_name) == "function" then
+    entname = self.entity:get_name()
   end
+  local cache_key = entname .. ":" .. opname
 
-  if opname == "" then
-    return Operation.new({})
+  if self.opmap[cache_key] ~= nil then
+    return self.opmap[cache_key]
   end
 
-  local entname = "_"
-  if self.entity ~= nil and type(self.entity.get_name) == "function" then
-    entname = self.entity:get_name()
+  if opname == "" then
+    return Operation.new({})
   end
 
   local opcfg = vs.getpath(self.config, "entity." .. entname .. ".op." .. opname)
@@ -195,7 +200,7 @@ function Context:resolve_op(opname)
     points = points,
   })
 
-  self.opmap[opname] = op
+  self.opmap[cache_key] = op
   return op
 end
 

package/project/.sdk/tm/php/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/php/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test build clean
+.PHONY: test build clean publish
 
 test:
 	./vendor/bin/phpunit test
@@ -8,3 +8,33 @@ build:
 
 clean:
 	@echo "No clean step for PHP"
+
+# --- Release: tag for Packagist -------------------------------------------
+# Packagist has no upload — it tracks the repo and indexes each git tag
+# php/vX.Y.Z (a configured GitHub webhook, or the Packagist "Update" API,
+# refreshes the package). So publishing a version means pushing the tag. Run
+# headless under the aql key vault, which injects the GitHub token:
+#   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.
+VERSION := $(shell cat VERSION)
+TAG := php/v$(VERSION)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish: test
+	@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 Packagist; nothing pushed."; \
+	  exit 0; \
+	fi; \
+	git tag -a "$(TAG)" -m "php 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 Packagist."

package/project/.sdk/tm/php/VERSION

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