@voxgig/create-sdkgen 0.20.1 → 0.20.2

package/README.md

@@ -6,6 +6,8 @@ Ruby, Lua, plus a CLI and MCP server).
 
 ## Quickstart
 
+From a spec to a tested SDK, in four steps:
+
 ```sh
 # 1. Scaffold a project from your OpenAPI 3 spec
 create-sdkgen my-api -d ./openapi.yaml -o ./my-api-sdk
@@ -32,20 +34,39 @@ generated output and is overwritten on each regenerate.
 | --- | --- |
 | `<name>` | SDK name (kebab-case), the package base name |
 | `-d, --def <spec>` | OpenAPI 3 spec file (`.yaml`/`.json`) |
-| `-o, --folder <dir>` | output directory |
+| `-o, --folder <dir>` | output directory (default `<name>-sdk`) |
 | `-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?
+## After the scaffold
+
+The loop from here is:
+
+```
+edit .sdk/model/entity/*.aontu  →  (cd .sdk && npm run generate)  →  re-run the target tests
+```
+
+Commit before regenerating, since generation overwrites the target
+directories. Every generated target carries a `readme_examples` test that
+extracts each code block from that language's `README.md` and `REFERENCE.md`,
+compiles it, and runs the runnable ones in offline test mode, so a documented
+example that does not work fails that target's build. When the tests are
+green, publish each language package the way its ecosystem expects (npm, PyPI,
+Packagist, RubyGems, LuaRocks, or a Go module tag).
 
-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 step-by-step tutorial, the model reference, and the generator's CLI flags
+are in the [sdkgen documentation](https://github.com/voxgig/sdkgen/tree/main/docs).
 
 ## 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.
+
+## Contributing
+
+How to validate a change, and why a pull request from a fork gets no CI, are
+in [`CONTRIBUTING.md`](./CONTRIBUTING.md). The documentation follows
+[the style guide](./STYLE-GUIDE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/create-sdkgen",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "main": "dist/create-sdkgen.js",
   "type": "commonjs",
   "types": "dist/create-sdkgen.d.ts",
@@ -26,6 +26,7 @@
     "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",
+    "scan-prose": "python3 tools/check_prose.py",
     "test-model": "voxgig-model project/.sdk/test/test.aon",
     "test-model-watch": "voxgig-model -w project/.sdk/test/test.aon",
     "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",

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

@@ -84,7 +84,7 @@ jobs:
       - if: hashFiles('go-mcp/go.mod') != ''
         uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
-          go-version: '1.24'
+          go-version: '1.25'
       - if: hashFiles('go-mcp/go.mod') != ''
         run: |
           cd go-mcp
@@ -369,7 +369,10 @@ jobs:
         with:
           ocaml-compiler: '5.2'
       - if: hashFiles('ocaml/Makefile') != ''
-        run: make -C ocaml test
+        # setup-ocaml installs the compiler into an opam switch; without
+        # `opam exec` the switch is not on PATH and make dies with
+        # `ocamlc: No such file or directory` (exit 127).
+        run: opam exec -- make -C ocaml test
 
   haskell:
     runs-on: ubuntu-latest

package/project/standard/.sdk/test/struct/nullsem.aon

@@ -0,0 +1,172 @@
+
+# STORED-NULL SEMANTICS.
+#
+# One question, asked of every reader: when a key is PRESENT and holds a JSON
+# null, is that "no value" (the same as an absent key) or is it a value?
+#
+# Nothing in the corpus asked it before. `minor.getprop` and `minor.haskey`
+# have ~50 cases each and not one stores a null: every entry is an absent key
+# or a non-null value. So the ports diverged silently, and they HAVE:
+#
+#   port   getprop({x:null},'x','ALT')   haskey({x:null},'x')
+#   ────   ───────────────────────────   ────────────────────
+#   go     'ALT'                         false
+#   py     'ALT'                         false
+#   perl   'ALT'                         false
+#   rb      null                         true
+#   php     null                         true
+#   js      null                         true
+#
+# That is not academic. It is the direct cause of the `auth: null` bug family:
+# `auth: null` is the documented way to suppress auth outright, and where a
+# stored null reads as "no value" the optspec `auth` default fires, the
+# suppression becomes "use the default auth", and the credential the caller
+# withheld goes out on the wire.
+#
+# 0.3.2 answers "no value" — the top three rows. This section pins that.
+#
+#
+# THIS SECTION IS OPT-IN, AND DELIBERATELY SO.
+#
+# Half the tree still vendors a struct that answers the other way. Putting
+# these cases in `minor` would red those targets today and gate the whole
+# corpus on finishing the struct migration everywhere first. Instead a target
+# wires this section up as it migrates:
+#
+#   runsetflags(nullsemSpec["getprop"], {"null": False}, getprop_wrapper)
+#
+# so the section becomes that target's null-semantics gate, and a target that
+# has not migrated simply does not reference it yet.
+#
+#
+# `null: false` IS NOT OPTIONAL HERE.
+#
+# The runner's default fixJSON rewrites every JSON null - on BOTH the `in` and
+# `out` sides - to the string '__NULL__' before the subject ever sees it. Run
+# without the flag, every case below would pass the STRING '__NULL__' as the
+# stored value, which is not a null and is not the question. The section would
+# then pass on every port while asserting nothing about null at all - the
+# exact "green while checking nothing" failure the corpus guards exist to
+# prevent. `minor.getelem` and `minor.clone` already run with the flag for the
+# same reason.
+#
+# With the flag, an entry with NO `out` expects a null result, and `out:` with
+# a value expects that value.
+#
+#
+# VERIFIED AGAINST THE REFERENCE, NOT GUESSED.
+#
+# All 33 cases below were run against upstream @voxgig/struct 0.3.2
+# (typescript/src/StructUtility.ts, the canonical port) and all 33 pass. They
+# are what the reference DOES, not what it was assumed to do.
+#
+# That mattered on the first run: `getprop([null], 0, 'ALT')` was assumed to
+# be a formality and turned out to be a live defect in the py port's vendored
+# copy. Canonical getprop tests `isnode(val)` - map AND list - and then
+# applies the null rule once to whatever it read. The py copy branches on
+# ismap/islist and its list branch does `return val[key]`, an early return
+# that skips the null check entirely, so it hands back the stored null where
+# every other reader would substitute the alt. Its map path is correct, which
+# is why nothing noticed.
+#
+# So py cannot opt in to this section until its vendored struct is resynced.
+# That is the section working as intended: it says "not yet" in a test result
+# instead of in a comment.
+
+
+# Does the ALT fire for a stored null, as it does for an absent key?
+getprop: {
+  set: [
+    # THE CASE. Absent and stored-null must answer alike.
+    { in: { val: {x:null}, key: x, alt: 'ALT' }, out: 'ALT' }
+    { in: { val: {},       key: x, alt: 'ALT' }, out: 'ALT' }
+
+    # No alt: a stored null reads back as null either way, so this pins that
+    # the rule does not turn a null into something else.
+    { in: { val: {x:null}, key: x } }
+
+    # A stored null must not leak past its own key.
+    { in: { val: {x:null, y:1}, key: y, alt: 'ALT' }, out: 1 }
+    { in: { val: {x:1, y:null}, key: x, alt: 'ALT' }, out: 1 }
+
+    # false, 0 and '' are VALUES, not absence. A port that collapses "nullish"
+    # to "falsy" passes every case above and fails these.
+    { in: { val: {x:false}, key: x, alt: 'ALT' }, out: false }
+    { in: { val: {x:0},     key: x, alt: 'ALT' }, out: 0 }
+    { in: { val: {x:''},    key: x, alt: 'ALT' }, out: '' }
+
+    # Lists too: index 0 holding a null is the list-shaped form of the same
+    # question, and a port can easily fix one and not the other.
+    { in: { val: [null], key: 0, alt: 'ALT' }, out: 'ALT' }
+    { in: { val: [null, 1], key: 1, alt: 'ALT' }, out: 1 }
+  ]
+}
+
+
+# getelem is the list-index reader. Same rule, different entry point - and it
+# is a separate function in every port, so it needs its own cases.
+getelem: {
+  set: [
+    { in: { val: [null], key: 0, alt: 'ALT' }, out: 'ALT' }
+    { in: { val: [10, null, 30], key: 1, alt: 'ALT' }, out: 'ALT' }
+    { in: { val: [10, null, 30], key: 2, alt: 'ALT' }, out: 30 }
+
+    # Negative indices are getelem's whole reason for existing; a stored null
+    # at a negative index is the case a port is most likely to miss.
+    { in: { val: [10, null], key: -1, alt: 'ALT' }, out: 'ALT' }
+    { in: { val: [null, 20], key: -1, alt: 'ALT' }, out: 20 }
+
+    { in: { val: [false], key: 0, alt: 'ALT' }, out: false }
+  ]
+}
+
+
+# A path that lands on a stored null, and - the case that actually bites - a
+# path that must TRAVERSE one. Traversal through a null is not the same
+# question as reading one, and a port can get the leaf right and still walk
+# into a null parent.
+getpath: {
+  set: [
+    { in: { path: 'a', store: {a:null} } }
+    { in: { path: 'a.b', store: {a:null} } }
+    { in: { path: 'a.b.c', store: {a:{b:null}} } }
+    { in: { path: 'a.b', store: {a:{b:null}} } }
+    { in: { path: 'a.b', store: {a:{b:1}} }, out: 1 }
+    { in: { path: 'a.b', store: {a:{b:false}} }, out: false }
+  ]
+}
+
+
+# Presence, asked directly. This is the reader the auth-null fix needs in
+# every port, and the one whose answer splits the tree.
+haskey: {
+  set: [
+    { in: { src: {x:null}, key: x }, out: false }
+    { in: { src: {},       key: x }, out: false }
+    { in: { src: {x:1},    key: x }, out: true }
+
+    # Again: falsy is not absent.
+    { in: { src: {x:false}, key: x }, out: true }
+    { in: { src: {x:0},     key: x }, out: true }
+    { in: { src: {x:''},    key: x }, out: true }
+
+    { in: { src: [null], key: 0 }, out: false }
+    { in: { src: [1],    key: 0 }, out: true }
+  ]
+}
+
+
+# The other direction, and the reason `auth: null` is expressible at all:
+# presence is STRUCTURAL. keysof lists a null-valued key, because the key IS
+# there - it is only the READERS above that treat its value as no value.
+#
+# A port that made haskey false by DELETING the key would pass every case
+# above and fail here, and it would also make the suppression unwritable:
+# there would be nothing left for makeOptions to detect.
+keysof: {
+  set: [
+    { in: {a:null}, out: [a] }
+    { in: {a:null, b:1}, out: [a, b] }
+    { in: {a:1, b:null}, out: [a, b] }
+  ]
+}

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

@@ -12,6 +12,7 @@ struct: transform: @"transform.aon"
 struct: walk: @"walk.aon"
 struct: validate: @"validate.aon"
 struct: select: @"select.aon"
+struct: nullsem: @"nullsem.aon"
 
 primary: check: {
   DEF: {

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

@@ -1543,7 +1543,11 @@
       "DEF": {
         "setup": {
           "a": {
-            "apikey": "APIKEY01"
+            "apikey": "APIKEY01",
+            "auth": {
+              "basic": false,
+              "prefix": ""
+            }
           }
         }
       },
@@ -10276,6 +10280,351 @@
         ]
       }
     },
+    "nullsem": {
+      "getelem": {
+        "set": [
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 0,
+              "val": [
+                null
+              ]
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 1,
+              "val": [
+                10,
+                null,
+                30
+              ]
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 2,
+              "val": [
+                10,
+                null,
+                30
+              ]
+            },
+            "out": 30
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": -1,
+              "val": [
+                10,
+                null
+              ]
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": -1,
+              "val": [
+                null,
+                20
+              ]
+            },
+            "out": 20
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 0,
+              "val": [
+                false
+              ]
+            },
+            "out": false
+          }
+        ]
+      },
+      "getpath": {
+        "set": [
+          {
+            "in": {
+              "path": "a",
+              "store": {
+                "a": null
+              }
+            }
+          },
+          {
+            "in": {
+              "path": "a.b",
+              "store": {
+                "a": null
+              }
+            }
+          },
+          {
+            "in": {
+              "path": "a.b.c",
+              "store": {
+                "a": {
+                  "b": null
+                }
+              }
+            }
+          },
+          {
+            "in": {
+              "path": "a.b",
+              "store": {
+                "a": {
+                  "b": null
+                }
+              }
+            }
+          },
+          {
+            "in": {
+              "path": "a.b",
+              "store": {
+                "a": {
+                  "b": 1
+                }
+              }
+            },
+            "out": 1
+          },
+          {
+            "in": {
+              "path": "a.b",
+              "store": {
+                "a": {
+                  "b": false
+                }
+              }
+            },
+            "out": false
+          }
+        ]
+      },
+      "getprop": {
+        "set": [
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {
+                "x": null
+              }
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {}
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "key": "x",
+              "val": {
+                "x": null
+              }
+            }
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "y",
+              "val": {
+                "x": null,
+                "y": 1
+              }
+            },
+            "out": 1
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {
+                "x": 1,
+                "y": null
+              }
+            },
+            "out": 1
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {
+                "x": false
+              }
+            },
+            "out": false
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {
+                "x": 0
+              }
+            },
+            "out": 0
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": "x",
+              "val": {
+                "x": ""
+              }
+            },
+            "out": ""
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 0,
+              "val": [
+                null
+              ]
+            },
+            "out": "ALT"
+          },
+          {
+            "in": {
+              "alt": "ALT",
+              "key": 1,
+              "val": [
+                null,
+                1
+              ]
+            },
+            "out": 1
+          }
+        ]
+      },
+      "haskey": {
+        "set": [
+          {
+            "in": {
+              "key": "x",
+              "src": {
+                "x": null
+              }
+            },
+            "out": false
+          },
+          {
+            "in": {
+              "key": "x",
+              "src": {}
+            },
+            "out": false
+          },
+          {
+            "in": {
+              "key": "x",
+              "src": {
+                "x": 1
+              }
+            },
+            "out": true
+          },
+          {
+            "in": {
+              "key": "x",
+              "src": {
+                "x": false
+              }
+            },
+            "out": true
+          },
+          {
+            "in": {
+              "key": "x",
+              "src": {
+                "x": 0
+              }
+            },
+            "out": true
+          },
+          {
+            "in": {
+              "key": "x",
+              "src": {
+                "x": ""
+              }
+            },
+            "out": true
+          },
+          {
+            "in": {
+              "key": 0,
+              "src": [
+                null
+              ]
+            },
+            "out": false
+          },
+          {
+            "in": {
+              "key": 0,
+              "src": [
+                1
+              ]
+            },
+            "out": true
+          }
+        ]
+      },
+      "keysof": {
+        "set": [
+          {
+            "in": {
+              "a": null
+            },
+            "out": [
+              "a"
+            ]
+          },
+          {
+            "in": {
+              "a": null,
+              "b": 1
+            },
+            "out": [
+              "a",
+              "b"
+            ]
+          },
+          {
+            "in": {
+              "a": 1,
+              "b": null
+            },
+            "out": [
+              "a",
+              "b"
+            ]
+          }
+        ]
+      },
+      "name": "nullsem",
+      "set": []
+    },
     "select": {
       "alts": {
         "data": {