@voxgig/create-sdkgen 0.15.0 → 0.16.1

package/README.md

@@ -1,4 +1,51 @@
 # create-sdkgen
-Create a Voxgig SDK Generator project
 
+Scaffold a new **Voxgig SDK Generator** project — turn an OpenAPI spec into
+idiomatic, tested, multi-language client SDKs (TypeScript, Python, Go, PHP,
+Ruby, Lua, plus a CLI and MCP server).
 
+## Quickstart
+
+```sh
+# 1. Scaffold a project from your OpenAPI 3 spec
+create-sdkgen my-api -d ./openapi.yaml -o ./my-api-sdk
+
+# 2. Add the languages you want + offline test mode
+cd my-api-sdk/.sdk
+npx voxgig-sdkgen target add ts py go
+npx voxgig-sdkgen feature add test
+
+# 3. Generate the SDKs (builds the .sdk sources, then runs the generator)
+npm run generate
+
+# 4. Verify
+cd ../ts && npm install && npm run build && npm test
+```
+
+You shape the SDK by editing the **model** in `.sdk/model/` (entities, ops,
+fields); everything under the language directories (`ts/`, `py/`, …) is
+generated output and is overwritten on each regenerate.
+
+## Options
+
+| Flag | Meaning |
+| --- | --- |
+| `<name>` | SDK name (kebab-case), the package base name |
+| `-d, --def <spec>` | OpenAPI 3 spec file (`.yaml`/`.json`) |
+| `-o, --folder <dir>` | output directory |
+| `-t, --target <langs>` | targets to add during scaffold (e.g. `ts,py,go`) |
+| `-f, --feature <feats>` | features to add (e.g. `test`) |
+| `--no-install` | skip `npm install` |
+| `-h`, `-v` | help, version |
+
+## Building an SDK with an AI agent?
+
+Point your agent at **[`AGENTS.md`](./AGENTS.md)** — the full end-to-end guide
+(spec → scaffold → generate → test → publish), what to edit vs. what is
+generated, the doc-example test guarantee, and the real-world shape gotchas.
+
+## The toolchain
+
+- **create-sdkgen** (this package) — scaffolds the project.
+- **[@voxgig/apidef](https://github.com/voxgig/apidef)** — parses your OpenAPI spec into the model.
+- **[@voxgig/sdkgen](https://github.com/voxgig/sdkgen)** — generates the SDKs from the model.

package/bin/create-sdkgen

@@ -249,6 +249,10 @@ Usage: npm create @voxgig/sdkgen@latest <name> <args>
     --folder     Target output folder. Default: ./<name>-sdk.
     -o
 
+    --target     Language targets to add (e.g. ts, py, go, rb). Can be
+    -t           specified multiple times; extra positional arguments
+                 after <name> are also treated as targets.
+
     --feature    Features to add. Can be specified multiple times.
     -f
 

package/dist/project/standard/CreateRoot.js

@@ -77,7 +77,6 @@ const CreateRoot = (0, jostraca_1.cmp)(function CreateRoot(props) {
                     (0, jostraca_1.Copy)({ from: origdef, to: projdef });
                 }
                 else {
-                    console.log('DEF NOT FOUND: ', origdef);
                     (0, jostraca_1.File)({ name: projdef }, () => {
                         (0, jostraca_1.Content)('# OpenAPI Definition');
                     });

package/dist/project/standard/CreateRoot.js.map

@@ -1 +1 @@
-{"version":3,"file":"CreateRoot.js","sourceRoot":"","sources":["../../../src/project/standard/CreateRoot.ts"],"names":[],"mappings":";;;;;;AAEA,0DAA4B;AAC5B,gCAAgC;AAEhC,uCAUiB;AAGjB,yCAAqC;AAGrC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;CAiBrB,CAAA;AAGD,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;CAkBrB,CAAA;AAGD,0BAA0B;AAC1B,MAAM,UAAU,GAAG,IAAA,cAAG,EAAC,SAAS,UAAU,CAAC,KAAU;IACnD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;IACrD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,CAAA;IAEpB,2CAA2C;IAC3C,KAAK,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IAClC,IAAA,gBAAK,EAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC9B,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAE3C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IAElB,IAAA,kBAAO,EAAC,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE;QACvB,MAAM,IAAI,GACR,mBAAI,CAAC,OAAO,CAAC,mBAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;QAEpF,4BAA4B;QAE5B,IAAA,eAAI,EAAC;YACH,IAAI;YACJ,OAAO,EAAE,CAAC,cAAc,CAAC;SAC1B,CAAC,CAAA;QAEF,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE;YAChC,IAAA,kBAAO,EAAC,aAAa,CAAC,CAAA;QACxB,CAAC,CAAC,CAAA;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAA;QACxB,MAAM,OAAO,GAAG,mBAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACtC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAA;QAElB,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE;YACrC,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE;gBAChC,IAAA,kBAAO,EAAC,aAAa,CAAC,CAAA;YACxB,CAAC,CAAC,CAAA;YAEF,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE;gBAC3B,qDAAqD;gBACrD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3B,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;gBACtC,CAAC;qBACI,CAAC;oBACJ,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAA;oBAEvC,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE;wBAC3B,IAAA,kBAAO,EAAC,sBAAsB,CAAC,CAAA;oBACjC,CAAC,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC,CAAC,CAAA;YAEF,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE;gBAC7B,IAAA,mBAAQ,EAAC,EAAE,IAAI,EAAE,CAAC,CAAA;YACpB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IAEJ,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAIA,gCAAU"}
+{"version":3,"file":"CreateRoot.js","sourceRoot":"","sources":["../../../src/project/standard/CreateRoot.ts"],"names":[],"mappings":";;;;;;AAEA,0DAA4B;AAC5B,gCAAgC;AAEhC,uCAUiB;AAGjB,yCAAqC;AAGrC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;CAiBrB,CAAA;AAGD,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;CAkBrB,CAAA;AAGD,0BAA0B;AAC1B,MAAM,UAAU,GAAG,IAAA,cAAG,EAAC,SAAS,UAAU,CAAC,KAAU;IACnD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;IACrD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,CAAA;IAEpB,2CAA2C;IAC3C,KAAK,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IAClC,IAAA,gBAAK,EAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC9B,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAE3C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IAElB,IAAA,kBAAO,EAAC,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE;QACvB,MAAM,IAAI,GACR,mBAAI,CAAC,OAAO,CAAC,mBAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;QAEpF,4BAA4B;QAE5B,IAAA,eAAI,EAAC;YACH,IAAI;YACJ,OAAO,EAAE,CAAC,cAAc,CAAC;SAC1B,CAAC,CAAA;QAEF,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE;YAChC,IAAA,kBAAO,EAAC,aAAa,CAAC,CAAA;QACxB,CAAC,CAAC,CAAA;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAA;QACxB,MAAM,OAAO,GAAG,mBAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACtC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAA;QAElB,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE;YACrC,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE;gBAChC,IAAA,kBAAO,EAAC,aAAa,CAAC,CAAA;YACxB,CAAC,CAAC,CAAA;YAEF,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE;gBAC3B,qDAAqD;gBACrD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3B,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;gBACtC,CAAC;qBACI,CAAC;oBACJ,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE;wBAC3B,IAAA,kBAAO,EAAC,sBAAsB,CAAC,CAAA;oBACjC,CAAC,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC,CAAC,CAAA;YAEF,IAAA,iBAAM,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE;gBAC7B,IAAA,mBAAQ,EAAC,EAAE,IAAI,EAAE,CAAC,CAAA;YACpB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IAEJ,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAIA,gCAAU"}

package/dist/project/standard/ModelSdk.js

@@ -9,9 +9,9 @@ const jostraca_1 = require("jostraca");
 const ModelSdk = (0, jostraca_1.cmp)(function ModelSdk(props) {
     const { spec } = props;
     const from = node_path_1.default.resolve(node_path_1.default.join(__dirname + '..', '..', '..', '..', 'project', 'standard'));
-    (0, jostraca_1.File)({ name: 'sdk.jsonic' }, () => {
+    (0, jostraca_1.File)({ name: 'sdk.aontu' }, () => {
         (0, jostraca_1.Fragment)({
-            from: node_path_1.default.join(from, spec.sdk_folder, 'model', 'sdk.fragment.jsonic'),
+            from: node_path_1.default.join(from, spec.sdk_folder, 'model', 'sdk.fragment.aontu'),
             replace: {
                 ProjectName: spec.name,
                 NAME: spec.name,

package/dist/project/standard/ModelSdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"ModelSdk.js","sourceRoot":"","sources":["../../../src/project/standard/ModelSdk.ts"],"names":[],"mappings":";;;;;;AACA,0DAA4B;AAG5B,uCAKiB;AAIjB,MAAM,QAAQ,GAAG,IAAA,cAAG,EAAC,SAAS,QAAQ,CAAC,KAAU;IAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IAEtB,MAAM,IAAI,GACR,mBAAI,CAAC,OAAO,CAAC,mBAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;IAEpF,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE;QAChC,IAAA,mBAAQ,EAAC;YACP,IAAI,EAAE,mBAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,qBAAqB,CAAC;YACtE,OAAO,EAAE;gBACP,WAAW,EAAE,IAAI,CAAC,IAAI;gBACtB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,EAAE,IAAI,CAAC,GAAG;aACd;SACF,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AAEJ,CAAC,CAAC,CAAA;AAIA,4BAAQ"}
+{"version":3,"file":"ModelSdk.js","sourceRoot":"","sources":["../../../src/project/standard/ModelSdk.ts"],"names":[],"mappings":";;;;;;AACA,0DAA4B;AAG5B,uCAKiB;AAIjB,MAAM,QAAQ,GAAG,IAAA,cAAG,EAAC,SAAS,QAAQ,CAAC,KAAU;IAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IAEtB,MAAM,IAAI,GACR,mBAAI,CAAC,OAAO,CAAC,mBAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;IAEpF,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE;QAC/B,IAAA,mBAAQ,EAAC;YACP,IAAI,EAAE,mBAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,oBAAoB,CAAC;YACrE,OAAO,EAAE;gBACP,WAAW,EAAE,IAAI,CAAC,IAAI;gBACtB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,EAAE,IAAI,CAAC,GAAG;aACd;SACF,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AAEJ,CAAC,CAAC,CAAA;AAIA,4BAAQ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/create-sdkgen",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "main": "dist/create-sdkgen.js",
   "type": "commonjs",
   "types": "dist/create-sdkgen.d.ts",
@@ -24,13 +24,19 @@
     "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test dist-test/**/*.test.js",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test",
-    "test-model": "voxgig-model project/.sdk/test/test.jsonic",
-    "test-model-watch": "voxgig-model -w project/.sdk/test/test.jsonic",
+    "test-model": "voxgig-model project/.sdk/test/test.aontu",
+    "test-model-watch": "voxgig-model -w project/.sdk/test/test.aontu",
     "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
     "reset": "npm run clean && npm i && npm run build && npm test",
+    "repo-bump": "npm version patch --no-git-tag-version && node -e \"console.log('bumped to v' + require('./package.json').version + ' (package.json only - commit via repo-tag / repo-release)')\"",
     "repo-tag": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo TAG: v$REPO_VERSION && git commit -a -m v$REPO_VERSION && git push && git tag v$REPO_VERSION && git push --tags;",
+    "repo-tag-dry": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo \"[dry-run] TAG: v$REPO_VERSION\" && if git rev-parse -q --verify refs/tags/v$REPO_VERSION >/dev/null; then echo \"[dry-run] WARNING: tag v$REPO_VERSION already exists - bump the version first\"; else echo \"[dry-run] would commit -a, push, tag v$REPO_VERSION and push --tags; nothing done\"; fi && git status --short",
     "repo-publish": "npm run clean && npm i && npm run repo-publish-quick",
-    "repo-publish-quick": "npm run build && npm run test && npm run repo-tag && npm publish --registry https://registry.npmjs.org --access=public"
+    "repo-publish-dry": "npm run clean && npm i && npm run repo-publish-quick-dry",
+    "repo-publish-quick": "npm run build && npm run test && npm publish --registry https://registry.npmjs.org --access=public",
+    "repo-publish-quick-dry": "npm run build && npm run test && ( npm publish --dry-run --registry https://registry.npmjs.org --access=public || echo \"[dry-run] npm publish refused (see npm error above) - usually the version is already published; bump package.json before a real release\" )",
+    "repo-release": "npm run repo-publish && npm run repo-tag",
+    "repo-release-dry": "npm run repo-publish-quick-dry && npm run repo-tag-dry"
   },
   "license": "MIT",
   "files": [
@@ -41,15 +47,15 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/node": "25.8.0",
-    "memfs": "4.57.2",
+    "@types/node": "26.1.0",
+    "memfs": "4.62.0",
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@voxgig/util": "0.4.0",
-    "aontu": "0.44.0",
+    "@voxgig/util": "0.5.1",
+    "aontu": "0.48.1",
     "chokidar": "5.0.0",
-    "jostraca": "0.30.1",
+    "jostraca": "0.31.0",
     "shape": "10.1.0"
   }
 }

package/project/standard/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+name: ci
+
+# Unit tests only — strictly offline. No live API calls.
+# Each per-language job runs the mocked unit-test suite for that target.
+# Each step after checkout is gated by hashFiles() so a job auto-skips
+# all its work when the target directory is absent.
+#
+# Live API verification is NOT run here. It happens in the central
+# rebuild pipeline under controlled conditions, with per-API auth and
+# rate-limit handling.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('go/go.mod') != ''
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - if: hashFiles('go/go.mod') != ''
+        run: make -C go test
+
+  go-cli:
+    runs-on: ubuntu-latest
+    # aql/eng/go is served via proxy.golang.org but its source repo
+    # (aql-lang/aql) is currently private, so sum.golang.org can't
+    # checksum-verify it. GOSUMDB=off lets `go mod tidy` use the
+    # committed go.sum without re-checking the public sum DB. Once
+    # aql-lang/aql goes public this env can be removed.
+    env:
+      GOSUMDB: 'off'
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('go-cli/go.mod') != ''
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - if: hashFiles('go-cli/go.mod') != ''
+        run: |
+          cd go-cli
+          go mod tidy
+          go vet ./...
+          go build ./...
+          go test ./...
+
+  go-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('go-mcp/go.mod') != ''
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - if: hashFiles('go-mcp/go.mod') != ''
+        run: |
+          cd go-mcp
+          go mod tidy
+          go vet ./...
+          go build ./...
+          go test ./...
+
+  ts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('ts/package.json') != ''
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - if: hashFiles('ts/package.json') != ''
+        run: cd ts && npm install --no-audit --no-fund
+      # npm test runs the compiled dist-test/ suite, which is gitignored —
+      # without a build first, node --test matches zero files and exits 0,
+      # leaving CI green while testing nothing.
+      - if: hashFiles('ts/package.json') != ''
+        run: cd ts && npm run build
+      - if: hashFiles('ts/package.json') != ''
+        run: cd ts && npm test
+
+  py:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('py/Makefile') != ''
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - if: hashFiles('py/Makefile') != ''
+        run: pip install pytest
+      - if: hashFiles('py/Makefile') != ''
+        run: make -C py test
+
+  rb:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('rb/Makefile') != ''
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - if: hashFiles('rb/Makefile') != ''
+        run: make -C rb test
+
+  php:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('php/composer.json') != ''
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+      - if: hashFiles('php/composer.json') != ''
+        run: cd php && composer install --no-interaction --no-progress
+      - if: hashFiles('php/composer.json') != ''
+        run: make -C php test
+
+  lua:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - if: hashFiles('lua/Makefile') != ''
+        uses: leafo/gh-actions-lua@v10
+        with:
+          luaVersion: '5.4'
+      - if: hashFiles('lua/Makefile') != ''
+        uses: leafo/gh-actions-luarocks@v4
+      - if: hashFiles('lua/Makefile') != ''
+        run: luarocks install busted
+      - if: hashFiles('lua/Makefile') != ''
+        run: make -C lua test

package/project/standard/.sdk/model/.model-config/{model-config.jsonic → model-config.aontu}

@@ -1,6 +1,6 @@
 
 
-@'@voxgig/model/model/.model-config/model-config.jsonic'
+@'@voxgig/model/model/.model-config/model-config.aontu'
 
 sys: model: action: {
   apidef: load: 'build/apidef.js'

package/project/standard/.sdk/model/config.aontu

@@ -0,0 +1,16 @@
+# SDK Configuration
+
+main: kit: config: {
+
+  # The Authorization credential prefix is derived from the OpenAPI
+  # security scheme (see api/api-info.aontu: main.kit.info.security,
+  # set by apidef) and defaults to 'Bearer' when the spec gives no
+  # signal. Uncomment to override per-SDK:
+  # auth: prefix: 'Bearer'
+
+
+  headers: {
+    'content-type': 'application/json'
+  }
+
+}

package/project/standard/.sdk/model/guide/guide.aontu

@@ -0,0 +1,8 @@
+# Guide
+
+@"@voxgig/apidef/model/guide.aontu"
+
+@"base-guide.aontu"
+
+
+

package/project/standard/.sdk/model/sdk.fragment.aontu

@@ -0,0 +1,35 @@
+
+# Model definitions.
+@"@voxgig/apidef/model/apidef.aontu"
+@"@voxgig/sdkgen/model/sdkgen.aontu"
+
+
+# SDK Details.
+name: 'NAME'
+origin: 'voxgig-sdk'
+def: 'DEF'
+
+
+# API Information
+@"api/api-info.aontu"
+
+
+# SDK Configuration.
+@"config.aontu"
+
+
+# SDK Entities
+@"entity/entity-index.aontu"
+
+
+# SDK Features.
+@"feature/feature-index.aontu"
+ 
+
+# SDK Targets.
+@"target/target-index.aontu"
+
+
+# Operation workflows.
+@"flow/flow-index.aontu"
+

package/project/standard/.sdk/package.json

@@ -3,12 +3,12 @@
   "version": "0.0.1",
   "description": "$$const.Name$$ SDK Project",
   "scripts": {
-    "generate": "voxgig-model model/sdk.jsonic",
-    "watch-generate": "voxgig-model -w model/sdk.jsonic",
-    "dry-generate": "voxgig-model -y model/sdk.jsonic",
-    "watch-dry-generate": "voxgig-model -w -y model/sdk.jsonic",
-    "test-model": "voxgig-model test/test.jsonic",
-    "watch-test-model": "voxgig-model -w test/test.jsonic",
+    "generate": "tsc --build src && voxgig-model model/sdk.aontu",
+    "watch-generate": "voxgig-model -w model/sdk.aontu",
+    "dry-generate": "tsc --build src && voxgig-model -y model/sdk.aontu",
+    "watch-dry-generate": "voxgig-model -w -y model/sdk.aontu",
+    "test-model": "voxgig-model test/test.aontu",
+    "watch-test-model": "voxgig-model -w test/test.aontu",
     "watch": "tsc --build src -w",
     "build": "tsc --build src",
     "test": "echo no-test",

package/project/standard/.sdk/src/BuildSDK.ts

@@ -77,6 +77,14 @@ function makeEntityTestData(_model: Model, entity: ModelEntity) {
   const pathParams = collectEntityPathParams(entity)
 
   const hasEntId = null != (entity as any).id
+  // Some entities don't declare a top-level `id` field but still need an
+  // `id` value in their fixture: any entity that has a non-list op (remove,
+  // update, load) will hit `data["id"]` in the generated test code. The
+  // test mock is lenient about extra/missing path params, so synthesising
+  // an `id` here keeps tests green for entities like
+  //   `/{namespace}/{key}` (no `id` in URL) or `/{resource}/{id}`
+  // alongside the simple `{id}`-only case.
+  const needsFixtureId = hasEntId || entityHasMutatingOp(entity)
 
   let i = 1
 
@@ -91,10 +99,11 @@ function makeEntityTestData(_model: Model, entity: ModelEntity) {
         ent[paramName] = paramValue
       }
     }
-    // Only inject a fixture id when the spec actually models one for this
-    // entity. Public APIs (e.g. read-only feeds) without ids leave fixtures
-    // bare so test generators don't synthesise bogus id assertions.
-    if (hasEntId) {
+    // Inject a fixture id when the spec models one for this entity (either
+    // as a top-level field or as a path param). Read-only feeds with no id
+    // at all leave fixtures bare so test generators don't synthesise bogus
+    // id assertions.
+    if (needsFixtureId) {
       ent.id = id
     }
   })
@@ -108,6 +117,21 @@ function makeEntityTestData(_model: Model, entity: ModelEntity) {
 }
 
 
+// Detect whether the entity has any op other than `list` (which doesn't
+// take a per-item id). Used to decide whether the fixture needs a
+// synthesised `id` — the test code for load/update/remove ops references
+// `data["id"]` unconditionally in Python (and similarly in other strict
+// languages), so the fixture must provide one even when the URL path
+// params are named differently (e.g. `/{namespace}/{key}`).
+function entityHasMutatingOp(entity: any): boolean {
+  const ops = entity?.op || {}
+  for (const opname of Object.keys(ops)) {
+    if (opname !== 'list') return true
+  }
+  return false
+}
+
+
 // Walk every op point on the entity, collect the names of path params, and
 // pair each with its canonical idmap value. The canonical value mirrors the
 // flow generator's path-param defaulting in apidef:

package/project/standard/.sdk/src/Root.ts

@@ -83,21 +83,48 @@ const Root = cmp(function Root(props: any) {
 
       Folder({ name: target.name }, () => {
 
-        each(entity, (entity: any) => {
-          names(entity, entity.name)
-          Entity({ target, entity })
-        })
-
-        each(feature).filter((feature: any) => feature.active).map((feature: any) => {
-          names(feature, feature.name)
-          Feature({ target, feature })
-        })
+        // Per-generation-phase activation. A target's aontu model carries
+        // a `phase` map mirroring the feature pattern:
+        //
+        //   phase: {
+        //     entity:  { active: false }
+        //     feature: { active: false }
+        //     readme:  { active: false }
+        //     test:    { active: false }
+        //   }
+        //
+        // Defaults are inclusive — when a phase entry is absent (or
+        // active is not explicitly false), the phase runs. Existing
+        // standard targets don't declare `phase` and keep current
+        // behaviour. A CLI-style target switches all four off and
+        // only emits Main.
+        const phase = target.phase || {}
+        const phaseActive = (name: string): boolean =>
+          false !== (phase[name] && phase[name].active)
+
+        if (phaseActive('entity')) {
+          each(entity, (entity: any) => {
+            names(entity, entity.name)
+            Entity({ target, entity })
+          })
+        }
+
+        if (phaseActive('feature')) {
+          each(feature).filter((feature: any) => feature.active).map((feature: any) => {
+            names(feature, feature.name)
+            Feature({ target, feature })
+          })
+        }
 
         Main({ target })
 
-        Readme({ target })
+        if (phaseActive('readme')) {
+          Readme({ target })
+        }
 
-        Test({ target })
+        if (phaseActive('test')) {
+          Test({ target })
+        }
       })
     })
 

package/project/standard/.sdk/src/Top.ts

@@ -2,12 +2,28 @@
 
 import {
   cmp,
+  Deploy,
   ReadmeTop,
+  License,
+  Security,
+  Changelog,
 } from '@voxgig/sdkgen'
 
 
 const Top = cmp(function Top(props: any) {
   ReadmeTop({})
+
+  // Root governance files for a publishable, unofficial generated SDK:
+  // an MIT LICENSE (held by Voxgig), a SECURITY.md disclosure policy, and a
+  // seed CHANGELOG. Emitted at repo root, before the per-target folders.
+  License({})
+  Security({})
+  Changelog({})
+
+  // Root deployment Makefile: per-target `make deploy-<t>` (publish with
+  // credentials injected by the aql key vault) plus an all-targets
+  // `make deploy-dry` rehearsal.
+  Deploy({})
 })
 
 

package/project/standard/.sdk/src/tsconfig.json

@@ -10,6 +10,13 @@
     "strict": true,
     "target": "es2021",
     "types": ["node"],
+
+    // A generated project must not fail on a *dependency's* own .d.ts: e.g.
+    // thread-stream (via @voxgig/apidef -> pino) references
+    // worker_threads.TransferListItem, dropped in @types/node >=26. Only src
+    // is our code, so skip lib checking of node_modules type declarations.
+    "skipLibCheck": true,
+
     "declaration": true,
     "declarationDir": "../dist"
   },

package/project/standard/.sdk/test/.model-config/model-config.aontu

@@ -0,0 +1,4 @@
+
+@"@voxgig/model/model/.model-config/model-config.aontu"
+
+sys: model: builders: {}

package/project/standard/.sdk/test/primary/primary-test-index.aontu

@@ -0,0 +1,30 @@
+primary: clean: @"clean.aontu"
+primary: done: @"done.aontu"
+primary: featureAdd: @"featureAdd.aontu"
+primary: featureHook: @"featureHook.aontu"
+primary: featureInit: @"featureInit.aontu"
+primary: fetcher: @"fetcher.aontu"
+primary: makeContext: @"makeContext.aontu"
+primary: makeError: @"makeError.aontu"
+primary: makeFetchDef: @"makeFetchDef.aontu"
+primary: makeOptions: @"makeOptions.aontu"
+primary: makeRequest: @"makeRequest.aontu"
+primary: makeResponse: @"makeResponse.aontu"
+primary: makeResult: @"makeResult.aontu"
+primary: makeSpec: @"makeSpec.aontu"
+primary: makePoint: @"makePoint.aontu"
+primary: makeUrl: @"makeUrl.aontu"
+primary: operator: @"operator.aontu"
+primary: param: @"param.aontu"
+primary: prepareAuth: @"prepareAuth.aontu"
+primary: prepareBody: @"prepareBody.aontu"
+primary: prepareHeaders: @"prepareHeaders.aontu"
+primary: prepareMethod: @"prepareMethod.aontu"
+primary: prepareParams: @"prepareParams.aontu"
+primary: preparePath: @"preparePath.aontu"
+primary: prepareQuery: @"prepareQuery.aontu"
+primary: resultBasic: @"resultBasic.aontu"
+primary: resultBody: @"resultBody.aontu"
+primary: resultHeaders: @"resultHeaders.aontu"
+primary: transformRequest: @"transformRequest.aontu"
+primary: transformResponse: @"transformResponse.aontu"

package/project/standard/.sdk/test/struct/test.aontu

@@ -0,0 +1,25 @@
+
+struct: &: {
+  name: .$KEY
+  set: []
+}
+
+struct: minor: @"minor.aontu"
+struct: getpath: @"getpath.aontu"
+struct: inject: @"inject.aontu"
+struct: merge: @"merge.aontu"
+struct: transform: @"transform.aontu"
+struct: walk: @"walk.aontu"
+struct: validate: @"validate.aontu"
+struct: select: @"select.aontu"
+
+primary: check: {
+  DEF: {
+    client:a:test:options:foo:1
+  }
+  basic: set: [
+    { ctx:meta:bar:BAR0, out:zed:ZED_BAR0 }
+    { ctx:meta:bar:BAR1, client:a, out:zed:ZED1_BAR1 }
+  ]
+}
+

package/project/standard/.sdk/test/test.aontu

@@ -0,0 +1,3 @@
+
+@"struct/test.aontu"
+@"primary/primary-test-index.aontu"

package/src/project/standard/CreateRoot.ts

@@ -102,8 +102,6 @@ const CreateRoot = cmp(function CreateRoot(props: any) {
           Copy({ from: origdef, to: projdef })
         }
         else {
-          console.log('DEF NOT FOUND: ', origdef)
-
           File({ name: projdef }, () => {
             Content('# OpenAPI Definition')
           })

package/src/project/standard/ModelSdk.ts

@@ -17,9 +17,9 @@ const ModelSdk = cmp(function ModelSdk(props: any) {
   const from =
     Path.resolve(Path.join(__dirname + '..', '..', '..', '..', 'project', 'standard'))
 
-  File({ name: 'sdk.jsonic' }, () => {
+  File({ name: 'sdk.aontu' }, () => {
     Fragment({
-      from: Path.join(from, spec.sdk_folder, 'model', 'sdk.fragment.jsonic'),
+      from: Path.join(from, spec.sdk_folder, 'model', 'sdk.fragment.aontu'),
       replace: {
         ProjectName: spec.name,
         NAME: spec.name,

package/src/tsconfig.json

@@ -9,6 +9,12 @@
     "sourceMap": true,
     "strict": true,
     "target": "es2021",
+
+    // @types/node >=26 dropped worker_threads.TransferListItem, which a
+    // dependency's own .d.ts (thread-stream via pino) still references. Only
+    // src is our code, so skip lib checking of node_modules type declarations.
+    "skipLibCheck": true,
+
     "declaration": true,
     "declarationDir": "../dist"
   }

package/bin/create-sdkgen~

@@ -1,261 +0,0 @@
-#!/usr/bin/env node
-
-const Path = require('node:path')
-const { statSync } = require('node:fs')
-const { parseArgs } = require('node:util')
-
-const { Gubu, Fault, One } = require('gubu')
-
-const Pkg = require('../package.json')
-
-const { CreateSdkGen } = require('../dist/create-sdkgen.js') 
-
-const rootpath = require.resolve('../dist/standard/Root')
-
-let KONSOLE = global['con'+'sole']
-
-
-run()
-
-
-async function run() {
-  try {
-    let options = resolveOptions()
-
-    if(options.debug) {
-      DEBUG = true
-    }
-
-    if(options.version) {
-      version()
-    }
-
-    if(options.help) {
-      help()
-    }
-
-    if(options.version || options.help) {
-      exit()
-    }
-
-    options = validateOptions(options)
-
-    generate(options)
-  }
-  catch(err) {
-    handleError(err)
-  }
-}
-
-
-function exit(err) {
-  let code = 0
-  if(err) {
-    code = 1
-  }
-  process.exit(code)
-}
-
-
-function generate(options) {
-  const createSdkGen = CreateSdkGen({
-    debug: options.debug
-  })
-
-
-  const spec = {
-    root: 'Root',
-
-    name: options.name,
-    def: options.def,
-    dryrun: options.dryrun,
-    project: options.project,
-    install: options.install,
-    target: options.target,
-    feature: options.feature,
-  }
-  
-  createSdkGen.generate(spec)
-}
-
-
-
-function resolveOptions() {
-
-  let args
-
-  try {
-    args = parseArgs({
-      allowPositionals: true,
-      allowNegative: true,
-      options: {
-        def: {
-          type: 'string',
-          short: 'd',
-          default: ''
-        },
-
-        project: {
-          type: 'string',
-          short: 'p',
-          default: 'standard'
-        },
-
-        dryrun: {
-          type: 'boolean',
-          short: 'y',
-        },
-
-        install: {
-          type: 'boolean',
-          short: 'y',
-          default: true,
-        },
-
-        target: {
-          type: 'string',
-          short: 't',
-          multiple: true
-        },
-
-        feature: {
-          type: 'string',
-          short: 'f',
-          multiple: true
-        },
-
-        debug: {
-          type: 'string',
-          short: 'g',
-          default: 'info'
-        },
-        
-        help: {
-          type: 'boolean',
-          short: 'h',
-        },
-        
-        version: {
-          type: 'boolean',
-          short: 'v',
-        },
-        
-      }
-    })
-  }
-  catch(err) {
-    if('ERR_PARSE_ARGS_UNKNOWN_OPTION' === err.code) {
-      handleError(err.message.replace(/\. .+$/,'.'))
-    }
-    throw err
-  }
-
-  // Set fake name if -v or -h used.
-  let name = args.positionals[0]
-  name = null == name ? '' : name
-  name = '' === name && (args.values.help || args.values.version) ? '__none__' : name
-
-  targets = args.values.target || []
-  if( 1 < args.positionals.length ) {
-    targets.push(args.positionals.slice(1))
-  }
-
-  features = args.values.feature || []
-  
-  const options = {
-    name,
-    def: args.values.def,
-    project: args.values.project,
-    dryrun: !!args.values.dryrun,
-    install: !!args.values.install,
-    target: targets,
-    feature: features,
-    debug: args.values.debug,
-    help: !!args.values.help,
-    version: !!args.values.version,
-  }
-
-  // console.log('ARGS', args, options)
-  
-  return options
-}
-
-
-function validateOptions(rawOptions) {
-  const optShape = Gubu({
-    name: Fault('The first argument must be the project name.', String),
-    def: '',
-    project: String,
-    dryrun: Boolean,
-    install: Boolean,
-    target: [String],
-    feature: [String],
-    debug: String,
-    help: Boolean,
-    version: Boolean,
-  })
-
-  const err = []
-  const options = optShape(rawOptions,{err})
-
-  if(err[0]) {
-    handleError(err[0].text)
-  }
-
-  return options
-}
-
-
-function handleError(err) {
-  KONSOLE.log('Voxgig Create SDK Error: '+err)
-  exit(err)
-}
-
-
-function version() {
-  KONSOLE.log(Pkg.version)
-}
-
-
-function help() {
-  let s = `
-Create a Voxgig SDK Generator project.
-
-Usage: npm create @voxgig/sdkgen@latest <name> <args> 
-
-  <name> is the name of the SDK project. This is also used to
-    create a project folder. If run against an existing folder
-    generated files will be overwritten.
-
-  <args> are the command arguments:
-
-    --def        Path to the OpenAPI definition file (optional).
-    -d            
-
-    --project    Project template (folder or package reference). Default: standard.
-    -p            
-
-    --dryrun     Perform a dry run, where no files are modified.
-    -y
-
-    --debug      Set log level (default: info): trace, error, debug, info, warn, fatal.
-    -g             
-
-    --help       Print this help message.
-    -h
-
-    --version    Print version number.
-    -v
-
-
-Examples:
-
-# Basic usage
-> npm create @voxgig/sdkgen@latest foo
-# Creates the SDK Project in the folder ./foo
-
-See also: https://voxgig.com/sdkgen
-`
-
-  KONSOLE.log(s)
-}

package/project/standard/.env.local

@@ -1 +0,0 @@
-PROJECTNAME_APIKEY=<apikey>

package/project/standard/.sdk/model/config.jsonic

@@ -1,15 +0,0 @@
-# SDK Configuration
-
-main: kit: config: {
-
-  ## TODO: crate in apidef and put servers here
-  
-  # Authorization header token value prefix
-  auth: prefix: 'Bearer'
-
-
-  headers: {
-    'content-type': 'application/json'
-  }
-
-}

package/project/standard/.sdk/model/guide/guide.jsonic

@@ -1,8 +0,0 @@
-# Guide
-
-@"@voxgig/apidef/model/guide.jsonic"
-
-@"base-guide.jsonic"
-
-
-

package/project/standard/.sdk/model/sdk.fragment.jsonic

@@ -1,35 +0,0 @@
-
-# Model definitions.
-@"@voxgig/apidef/model/apidef.jsonic"
-@"@voxgig/sdkgen/model/sdkgen.jsonic"
-
-
-# SDK Details.
-name: 'NAME'
-origin: 'voxgig-sdk'
-def: 'DEF'
-
-
-# API Information
-@"api/api-info.jsonic"
-
-
-# SDK Configuration.
-@"config.jsonic"
-
-
-# SDK Entities
-@"entity/entity-index.jsonic"
-
-
-# SDK Features.
-@"feature/feature-index.jsonic"
- 
-
-# SDK Targets.
-@"target/target-index.jsonic"
-
-
-# Operation workflows.
-@"flow/flow-index.jsonic"
-

package/project/standard/.sdk/test/.model-config/model-config.jsonic

@@ -1,4 +0,0 @@
-
-@"@voxgig/model/model/.model-config/model-config.jsonic"
-
-sys: model: builders: {}

package/project/standard/.sdk/test/primary/primary-test-index.jsonic

@@ -1,30 +0,0 @@
-primary: clean: @"clean.jsonic"
-primary: done: @"done.jsonic"
-primary: featureAdd: @"featureAdd.jsonic"
-primary: featureHook: @"featureHook.jsonic"
-primary: featureInit: @"featureInit.jsonic"
-primary: fetcher: @"fetcher.jsonic"
-primary: makeContext: @"makeContext.jsonic"
-primary: makeError: @"makeError.jsonic"
-primary: makeFetchDef: @"makeFetchDef.jsonic"
-primary: makeOptions: @"makeOptions.jsonic"
-primary: makeRequest: @"makeRequest.jsonic"
-primary: makeResponse: @"makeResponse.jsonic"
-primary: makeResult: @"makeResult.jsonic"
-primary: makeSpec: @"makeSpec.jsonic"
-primary: makePoint: @"makePoint.jsonic"
-primary: makeUrl: @"makeUrl.jsonic"
-primary: operator: @"operator.jsonic"
-primary: param: @"param.jsonic"
-primary: prepareAuth: @"prepareAuth.jsonic"
-primary: prepareBody: @"prepareBody.jsonic"
-primary: prepareHeaders: @"prepareHeaders.jsonic"
-primary: prepareMethod: @"prepareMethod.jsonic"
-primary: prepareParams: @"prepareParams.jsonic"
-primary: preparePath: @"preparePath.jsonic"
-primary: prepareQuery: @"prepareQuery.jsonic"
-primary: resultBasic: @"resultBasic.jsonic"
-primary: resultBody: @"resultBody.jsonic"
-primary: resultHeaders: @"resultHeaders.jsonic"
-primary: transformRequest: @"transformRequest.jsonic"
-primary: transformResponse: @"transformResponse.jsonic"

package/project/standard/.sdk/test/struct/test.jsonic

@@ -1,25 +0,0 @@
-
-struct: &: {
-  name: .$KEY
-  set: []
-}
-
-struct: minor: @"minor.jsonic"
-struct: getpath: @"getpath.jsonic"
-struct: inject: @"inject.jsonic"
-struct: merge: @"merge.jsonic"
-struct: transform: @"transform.jsonic"
-struct: walk: @"walk.jsonic"
-struct: validate: @"validate.jsonic"
-struct: select: @"select.jsonic"
-
-primary: check: {
-  DEF: {
-    client:a:test:options:foo:1
-  }
-  basic: set: [
-    { ctx:meta:bar:BAR0, out:zed:ZED_BAR0 }
-    { ctx:meta:bar:BAR1, client:a, out:zed:ZED1_BAR1 }
-  ]
-}
-

package/project/standard/.sdk/test/test.jsonic

@@ -1,3 +0,0 @@
-
-@"struct/test.jsonic"
-@"primary/primary-test-index.jsonic"