@voxgig/create-sdkgen 0.16.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/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.16.0",
+  "version": "0.16.1",
   "main": "dist/create-sdkgen.js",
   "type": "commonjs",
   "types": "dist/create-sdkgen.d.ts",
@@ -24,8 +24,8 @@
     "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)')\"",

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

@@ -79,6 +79,11 @@ jobs:
           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
 

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.jsonic → sdk.fragment.aontu}

@@ -11,25 +11,25 @@ def: 'DEF'
 
 
 # API Information
-@"api/api-info.jsonic"
+@"api/api-info.aontu"
 
 
 # SDK Configuration.
-@"config.jsonic"
+@"config.aontu"
 
 
 # SDK Entities
-@"entity/entity-index.jsonic"
+@"entity/entity-index.aontu"
 
 
 # SDK Features.
-@"feature/feature-index.jsonic"
+@"feature/feature-index.aontu"
  
 
 # SDK Targets.
-@"target/target-index.jsonic"
+@"target/target-index.aontu"
 
 
 # Operation workflows.
-@"flow/flow-index.jsonic"
+@"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/Root.ts

@@ -83,7 +83,7 @@ const Root = cmp(function Root(props: any) {
 
       Folder({ name: target.name }, () => {
 
-        // Per-generation-phase activation. A target's jsonic carries
+        // Per-generation-phase activation. A target's aontu model carries
         // a `phase` map mirroring the feature pattern:
         //
         //   phase: {

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

@@ -4,12 +4,22 @@ 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.

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/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/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/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"